From b9cde963555b6519c5dbd34a39dee3418f593437 Mon Sep 17 00:00:00 2001 From: Jacob McDonnell Date: Sat, 25 Apr 2026 16:08:12 -0400 Subject: feat: Added FreeBSD man pages --- build | 2 +- static/freebsd/Makefile | 4 + static/freebsd/man1/Makefile | 3 + static/freebsd/man1/builtin.1 | 239 + static/freebsd/man1/intro.1 | 105 + static/freebsd/man3/ATOMIC_VAR_INIT.3 | 299 ++ static/freebsd/man3/CMSG_DATA.3 | 212 + static/freebsd/man3/Makefile | 3 + static/freebsd/man3/Q_FRAWMASK.3 | 123 + static/freebsd/man3/Q_IFRAWMASK.3 | 160 + static/freebsd/man3/Q_INI.3 | 259 + static/freebsd/man3/Q_IRAWMASK.3 | 123 + static/freebsd/man3/Q_QABS.3 | 99 + static/freebsd/man3/Q_QADDI.3 | 132 + static/freebsd/man3/Q_QADDQ.3 | 173 + static/freebsd/man3/Q_SIGNED.3 | 208 + static/freebsd/man3/Q_SIGNSHFT.3 | 145 + static/freebsd/man3/alloca.3 | 101 + static/freebsd/man3/arb.3 | 511 ++ static/freebsd/man3/assert.3 | 136 + static/freebsd/man3/bitstring.3 | 470 ++ static/freebsd/man3/end.3 | 76 + static/freebsd/man3/fpgetround.3 | 173 + static/freebsd/man3/intro.3 | 384 ++ static/freebsd/man3/makedev.3 | 100 + static/freebsd/man3/offsetof.3 | 45 + static/freebsd/man3/pthread.3 | 552 +++ static/freebsd/man3/pthread_affinity_np.3 | 162 + static/freebsd/man3/pthread_atfork.3 | 114 + static/freebsd/man3/pthread_attr.3 | 236 + static/freebsd/man3/pthread_attr_affinity_np.3 | 161 + static/freebsd/man3/pthread_attr_get_np.3 | 128 + .../man3/pthread_attr_setcreatesuspend_np.3 | 71 + static/freebsd/man3/pthread_barrier_destroy.3 | 154 + static/freebsd/man3/pthread_barrierattr.3 | 137 + static/freebsd/man3/pthread_cancel.3 | 80 + static/freebsd/man3/pthread_cleanup_pop.3 | 72 + static/freebsd/man3/pthread_cleanup_push.3 | 74 + static/freebsd/man3/pthread_cond_broadcast.3 | 70 + static/freebsd/man3/pthread_cond_destroy.3 | 77 + static/freebsd/man3/pthread_cond_init.3 | 81 + static/freebsd/man3/pthread_cond_signal.3 | 70 + static/freebsd/man3/pthread_cond_timedwait.3 | 99 + static/freebsd/man3/pthread_cond_wait.3 | 99 + static/freebsd/man3/pthread_condattr.3 | 170 + static/freebsd/man3/pthread_create.3 | 147 + static/freebsd/man3/pthread_detach.3 | 89 + static/freebsd/man3/pthread_equal.3 | 67 + static/freebsd/man3/pthread_exit.3 | 105 + static/freebsd/man3/pthread_getconcurrency.3 | 113 + static/freebsd/man3/pthread_getcpuclockid.3 | 84 + static/freebsd/man3/pthread_getspecific.3 | 88 + static/freebsd/man3/pthread_getthreadid_np.3 | 55 + static/freebsd/man3/pthread_join.3 | 194 + static/freebsd/man3/pthread_key_create.3 | 107 + static/freebsd/man3/pthread_key_delete.3 | 98 + static/freebsd/man3/pthread_kill.3 | 75 + static/freebsd/man3/pthread_main_np.3 | 59 + static/freebsd/man3/pthread_multi_np.3 | 65 + static/freebsd/man3/pthread_mutex_consistent.3 | 91 + static/freebsd/man3/pthread_mutex_destroy.3 | 72 + static/freebsd/man3/pthread_mutex_init.3 | 76 + static/freebsd/man3/pthread_mutex_lock.3 | 86 + static/freebsd/man3/pthread_mutex_timedlock.3 | 113 + static/freebsd/man3/pthread_mutex_trylock.3 | 87 + static/freebsd/man3/pthread_mutex_unlock.3 | 85 + static/freebsd/man3/pthread_mutexattr.3 | 368 ++ static/freebsd/man3/pthread_mutexattr_getkind_np.3 | 80 + static/freebsd/man3/pthread_np.3 | 226 + static/freebsd/man3/pthread_once.3 | 105 + static/freebsd/man3/pthread_resume_all_np.3 | 50 + static/freebsd/man3/pthread_resume_np.3 | 71 + static/freebsd/man3/pthread_rwlock_destroy.3 | 81 + static/freebsd/man3/pthread_rwlock_init.3 | 98 + static/freebsd/man3/pthread_rwlock_rdlock.3 | 125 + static/freebsd/man3/pthread_rwlock_timedrdlock.3 | 116 + static/freebsd/man3/pthread_rwlock_timedwrlock.3 | 106 + static/freebsd/man3/pthread_rwlock_unlock.3 | 80 + static/freebsd/man3/pthread_rwlock_wrlock.3 | 104 + static/freebsd/man3/pthread_rwlockattr_destroy.3 | 70 + .../freebsd/man3/pthread_rwlockattr_getpshared.3 | 86 + static/freebsd/man3/pthread_rwlockattr_init.3 | 69 + .../freebsd/man3/pthread_rwlockattr_setpshared.3 | 90 + static/freebsd/man3/pthread_schedparam.3 | 100 + static/freebsd/man3/pthread_self.3 | 61 + static/freebsd/man3/pthread_set_name_np.3 | 107 + static/freebsd/man3/pthread_setspecific.3 | 99 + static/freebsd/man3/pthread_sigmask.3 | 97 + static/freebsd/man3/pthread_signals_block_np.3 | 81 + static/freebsd/man3/pthread_sigqueue.3 | 102 + static/freebsd/man3/pthread_spin_init.3 | 123 + static/freebsd/man3/pthread_spin_lock.3 | 136 + static/freebsd/man3/pthread_suspend_all_np.3 | 59 + static/freebsd/man3/pthread_suspend_np.3 | 76 + static/freebsd/man3/pthread_testcancel.3 | 263 + static/freebsd/man3/pthread_yield.3 | 28 + static/freebsd/man3/qmath.3 | 387 ++ static/freebsd/man3/queue.3 | 1487 ++++++ static/freebsd/man3/sigevent.3 | 129 + static/freebsd/man3/siginfo.3 | 348 ++ static/freebsd/man3/snl.3 | 309 ++ static/freebsd/man3/stats.3 | 966 ++++ static/freebsd/man3/stdarg.3 | 243 + static/freebsd/man3/stdbit.3 | 120 + static/freebsd/man3/stdckdint.3 | 106 + static/freebsd/man3/sysexits.3 | 135 + static/freebsd/man3/tgmath.3 | 160 + static/freebsd/man3/timeradd.3 | 164 + static/freebsd/man3/tree.3 | 816 +++ static/freebsd/man3lua/Makefile | 3 + static/freebsd/man3lua/intro.3lua | 63 + static/freebsd/man4/Makefile | 8 + static/freebsd/man4/aac.4 | 300 ++ static/freebsd/man4/aacraid.4 | 136 + static/freebsd/man4/acpi.4 | 646 +++ static/freebsd/man4/acpi_asus.4 | 185 + static/freebsd/man4/acpi_asus_wmi.4 | 96 + static/freebsd/man4/acpi_battery.4 | 378 ++ static/freebsd/man4/acpi_dock.4 | 60 + static/freebsd/man4/acpi_fujitsu.4 | 173 + static/freebsd/man4/acpi_ged.4 | 62 + static/freebsd/man4/acpi_hp.4 | 286 ++ static/freebsd/man4/acpi_ibm.4 | 504 ++ static/freebsd/man4/acpi_panasonic.4 | 176 + static/freebsd/man4/acpi_rapidstart.4 | 82 + static/freebsd/man4/acpi_sony.4 | 80 + static/freebsd/man4/acpi_thermal.4 | 150 + static/freebsd/man4/acpi_toshiba.4 | 126 + static/freebsd/man4/acpi_video.4 | 96 + static/freebsd/man4/acpi_wmi.4 | 132 + static/freebsd/man4/ada.4 | 166 + static/freebsd/man4/adm6996fc.4 | 66 + static/freebsd/man4/ads111x.4 | 239 + static/freebsd/man4/ae.4 | 149 + static/freebsd/man4/aesni.4 | 110 + static/freebsd/man4/age.4 | 184 + static/freebsd/man4/agp.4 | 180 + static/freebsd/man4/ahc.4 | 413 ++ static/freebsd/man4/ahci.4 | 209 + static/freebsd/man4/ahd.4 | 190 + static/freebsd/man4/aibs.4 | 206 + static/freebsd/man4/aio.4 | 237 + static/freebsd/man4/alc.4 | 183 + static/freebsd/man4/ale.4 | 159 + static/freebsd/man4/alpm.4 | 60 + static/freebsd/man4/altq.4 | 200 + static/freebsd/man4/amdpm.4 | 71 + static/freebsd/man4/amdsbwd.4 | 87 + static/freebsd/man4/amdsmb.4 | 55 + static/freebsd/man4/amdsmn.4 | 62 + static/freebsd/man4/amdtemp.4 | 110 + static/freebsd/man4/aout.4 | 144 + static/freebsd/man4/apic.4 | 76 + static/freebsd/man4/appleir.4 | 93 + static/freebsd/man4/aq.4 | 56 + static/freebsd/man4/arcmsr.4 | 179 + static/freebsd/man4/arswitch.4 | 92 + static/freebsd/man4/asmc.4 | 198 + static/freebsd/man4/at45d.4 | 182 + static/freebsd/man4/ata.4 | 253 + static/freebsd/man4/ath.4 | 283 ++ static/freebsd/man4/ath10k.4 | 103 + static/freebsd/man4/ath_hal.4 | 135 + static/freebsd/man4/atkbd.4 | 231 + static/freebsd/man4/atkbdc.4 | 126 + static/freebsd/man4/atopcase.4 | 134 + static/freebsd/man4/atp.4 | 157 + static/freebsd/man4/atrtc.4 | 61 + static/freebsd/man4/attimer.4 | 85 + static/freebsd/man4/audit.4 | 158 + static/freebsd/man4/auditpipe.4 | 255 + static/freebsd/man4/aue.4 | 208 + static/freebsd/man4/autofs.4 | 135 + static/freebsd/man4/aw_gpio.4 | 102 + static/freebsd/man4/aw_mmc.4 | 75 + static/freebsd/man4/aw_rtc.4 | 68 + static/freebsd/man4/aw_sid.4 | 79 + static/freebsd/man4/aw_spi.4 | 55 + static/freebsd/man4/aw_syscon.4 | 67 + static/freebsd/man4/axe.4 | 257 + static/freebsd/man4/axge.4 | 166 + static/freebsd/man4/axp.4 | 196 + static/freebsd/man4/bce.4 | 430 ++ static/freebsd/man4/bcm5974.4 | 83 + static/freebsd/man4/bcma.4 | 77 + static/freebsd/man4/bfe.4 | 114 + static/freebsd/man4/bge.4 | 286 ++ static/freebsd/man4/bhnd.4 | 81 + static/freebsd/man4/bhnd_chipc.4 | 78 + static/freebsd/man4/bhnd_pmu.4 | 71 + static/freebsd/man4/bhndb.4 | 78 + static/freebsd/man4/bhndb_pci.4 | 73 + static/freebsd/man4/bhyve.4 | 66 + static/freebsd/man4/blackhole.4 | 104 + static/freebsd/man4/bnxt.4 | 271 + static/freebsd/man4/bnxt_re.4 | 91 + static/freebsd/man4/boottrace.4 | 222 + static/freebsd/man4/bpf.4 | 1217 +++++ static/freebsd/man4/bridge.4 | 743 +++ static/freebsd/man4/bwi.4 | 149 + static/freebsd/man4/bwn.4 | 169 + static/freebsd/man4/bxe.4 | 342 ++ static/freebsd/man4/bytgpio.4 | 53 + static/freebsd/man4/capsicum.4 | 199 + static/freebsd/man4/cardbus.4 | 55 + static/freebsd/man4/carp.4 | 351 ++ static/freebsd/man4/cas.4 | 131 + static/freebsd/man4/cc_cdg.4 | 154 + static/freebsd/man4/cc_chd.4 | 127 + static/freebsd/man4/cc_cubic.4 | 120 + static/freebsd/man4/cc_dctcp.4 | 150 + static/freebsd/man4/cc_hd.4 | 119 + static/freebsd/man4/cc_htcp.4 | 136 + static/freebsd/man4/cc_newreno.4 | 174 + static/freebsd/man4/cc_vegas.4 | 135 + static/freebsd/man4/ccd.4 | 284 ++ static/freebsd/man4/ccr.4 | 118 + static/freebsd/man4/cd.4 | 361 ++ static/freebsd/man4/cd9660.4 | 84 + static/freebsd/man4/cdce.4 | 195 + static/freebsd/man4/cdceem.4 | 120 + static/freebsd/man4/cfi.4 | 91 + static/freebsd/man4/cfiscsi.4 | 109 + static/freebsd/man4/cfumass.4 | 141 + static/freebsd/man4/cgem.4 | 300 ++ static/freebsd/man4/ch.4 | 351 ++ static/freebsd/man4/chromebook_platform.4 | 66 + static/freebsd/man4/chvgpio.4 | 63 + static/freebsd/man4/ciss.4 | 236 + static/freebsd/man4/coretemp.4 | 73 + static/freebsd/man4/cp2112.4 | 85 + static/freebsd/man4/cpuctl.4 | 196 + static/freebsd/man4/cpufreq.4 | 327 ++ static/freebsd/man4/crypto.4 | 376 ++ static/freebsd/man4/ctl.4 | 221 + static/freebsd/man4/cue.4 | 113 + static/freebsd/man4/cxgb.4 | 132 + static/freebsd/man4/cxgbe.4 | 465 ++ static/freebsd/man4/cxgbev.4 | 310 ++ static/freebsd/man4/cyapa.4 | 228 + static/freebsd/man4/da.4 | 255 + static/freebsd/man4/dc.4 | 422 ++ static/freebsd/man4/dcons.4 | 123 + static/freebsd/man4/dcons_crom.4 | 59 + static/freebsd/man4/ddb.4 | 1713 +++++++ static/freebsd/man4/devctl.4 | 142 + static/freebsd/man4/devfs.4 | 147 + static/freebsd/man4/disc.4 | 73 + static/freebsd/man4/disk.4 | 206 + static/freebsd/man4/divert.4 | 200 + static/freebsd/man4/dpms.4 | 55 + static/freebsd/man4/ds1307.4 | 129 + static/freebsd/man4/ds3231.4 | 146 + static/freebsd/man4/dtrace_audit.4 | 174 + static/freebsd/man4/dtrace_callout_execute.4 | 68 + static/freebsd/man4/dtrace_cam.4 | 42 + static/freebsd/man4/dtrace_dtrace.4 | 191 + static/freebsd/man4/dtrace_fbt.4 | 332 ++ static/freebsd/man4/dtrace_io.4 | 121 + static/freebsd/man4/dtrace_ip.4 | 283 ++ static/freebsd/man4/dtrace_kinst.4 | 95 + static/freebsd/man4/dtrace_lockstat.4 | 292 ++ static/freebsd/man4/dtrace_pid.4 | 99 + static/freebsd/man4/dtrace_priv.4 | 59 + static/freebsd/man4/dtrace_proc.4 | 262 + static/freebsd/man4/dtrace_profile.4 | 129 + static/freebsd/man4/dtrace_sched.4 | 225 + static/freebsd/man4/dtrace_sctp.4 | 226 + static/freebsd/man4/dtrace_tcp.4 | 526 ++ static/freebsd/man4/dtrace_udp.4 | 203 + static/freebsd/man4/dtrace_udplite.4 | 202 + static/freebsd/man4/dtrace_vfs.4 | 97 + static/freebsd/man4/dummymbuf.4 | 211 + static/freebsd/man4/dummynet.4 | 80 + static/freebsd/man4/e6000sw.4 | 48 + static/freebsd/man4/e6060sw.4 | 81 + static/freebsd/man4/edsc.4 | 104 + static/freebsd/man4/efidev.4 | 162 + static/freebsd/man4/ehci.4 | 111 + static/freebsd/man4/em.4 | 348 ++ static/freebsd/man4/ena.4 | 536 ++ static/freebsd/man4/enc.4 | 142 + static/freebsd/man4/enic.4 | 88 + static/freebsd/man4/epair.4 | 171 + static/freebsd/man4/est.4 | 118 + static/freebsd/man4/et.4 | 184 + static/freebsd/man4/etherswitch.4 | 65 + static/freebsd/man4/eventtimers.4 | 151 + static/freebsd/man4/exca.4 | 36 + static/freebsd/man4/ext2fs.4 | 104 + static/freebsd/man4/fd.4 | 98 + static/freebsd/man4/fdc.4 | 396 ++ static/freebsd/man4/fdescfs.4 | 218 + static/freebsd/man4/fdt.4 | 203 + static/freebsd/man4/fdt_pinctrl.4 | 124 + static/freebsd/man4/fdtbus.4 | 87 + static/freebsd/man4/ffclock.4 | 127 + static/freebsd/man4/ffs.4 | 333 ++ static/freebsd/man4/filemon.4 | 252 + static/freebsd/man4/firewire.4 | 130 + static/freebsd/man4/ftgpio.4 | 54 + static/freebsd/man4/ftwd.4 | 64 + static/freebsd/man4/full.4 | 45 + static/freebsd/man4/fusefs.4 | 136 + static/freebsd/man4/fwe.4 | 94 + static/freebsd/man4/fwip.4 | 93 + static/freebsd/man4/fwohci.4 | 154 + static/freebsd/man4/fxp.4 | 212 + static/freebsd/man4/gdb.4 | 601 +++ static/freebsd/man4/gem.4 | 112 + static/freebsd/man4/genet.4 | 184 + static/freebsd/man4/genetlink.4 | 146 + static/freebsd/man4/geneve.4 | 384 ++ static/freebsd/man4/geom.4 | 505 ++ static/freebsd/man4/geom_linux_lvm.4 | 86 + static/freebsd/man4/geom_uzip.4 | 182 + static/freebsd/man4/geom_zero.4 | 174 + static/freebsd/man4/gif.4 | 378 ++ static/freebsd/man4/gpio.4 | 191 + static/freebsd/man4/gpioiic.4 | 156 + static/freebsd/man4/gpiokeys.4 | 150 + static/freebsd/man4/gpioled.4 | 173 + static/freebsd/man4/gpioths.4 | 150 + static/freebsd/man4/gre.4 | 275 + static/freebsd/man4/gve.4 | 310 ++ static/freebsd/man4/h_ertt.4 | 140 + static/freebsd/man4/hconf.4 | 88 + static/freebsd/man4/hcons.4 | 96 + static/freebsd/man4/hgame.4 | 130 + static/freebsd/man4/hidbus.4 | 100 + static/freebsd/man4/hidquirk.4 | 143 + static/freebsd/man4/hidraw.4 | 314 ++ static/freebsd/man4/hkbd.4 | 205 + static/freebsd/man4/hms.4 | 113 + static/freebsd/man4/hmt.4 | 77 + static/freebsd/man4/hpen.4 | 110 + static/freebsd/man4/hpet.4 | 110 + static/freebsd/man4/hpt27xx.4 | 99 + static/freebsd/man4/hptiop.4 | 137 + static/freebsd/man4/hptmv.4 | 99 + static/freebsd/man4/hptnr.4 | 90 + static/freebsd/man4/hptrr.4 | 140 + static/freebsd/man4/hsctrl.4 | 96 + static/freebsd/man4/htu21.4 | 132 + static/freebsd/man4/hv_kvp.4 | 95 + static/freebsd/man4/hv_netvsc.4 | 84 + static/freebsd/man4/hv_storvsc.4 | 88 + static/freebsd/man4/hv_utils.4 | 84 + static/freebsd/man4/hv_vmbus.4 | 92 + static/freebsd/man4/hv_vss.4 | 373 ++ static/freebsd/man4/hwpmc.4 | 967 ++++ static/freebsd/man4/hwpstate_intel.4 | 95 + static/freebsd/man4/hwt.4 | 144 + static/freebsd/man4/i2ctinyusb.4 | 85 + static/freebsd/man4/iavf.4 | 353 ++ static/freebsd/man4/ice.4 | 1171 +++++ static/freebsd/man4/ichsmb.4 | 59 + static/freebsd/man4/ichwd.4 | 98 + static/freebsd/man4/icmp.4 | 276 ++ static/freebsd/man4/icmp6.4 | 281 ++ static/freebsd/man4/ida.4 | 79 + static/freebsd/man4/ietp.4 | 79 + static/freebsd/man4/if_ipsec.4 | 139 + static/freebsd/man4/if_ntb.4 | 87 + static/freebsd/man4/iflib.4 | 241 + static/freebsd/man4/ifmib.4 | 184 + static/freebsd/man4/ig4.4 | 82 + static/freebsd/man4/igc.4 | 161 + static/freebsd/man4/igmp.4 | 136 + static/freebsd/man4/iic.4 | 257 + static/freebsd/man4/iic_gpiomux.4 | 85 + static/freebsd/man4/iicbb.4 | 56 + static/freebsd/man4/iicbus.4 | 163 + static/freebsd/man4/iichid.4 | 94 + static/freebsd/man4/iicmux.4 | 146 + static/freebsd/man4/iicsmb.4 | 56 + static/freebsd/man4/imcsmb.4 | 130 + static/freebsd/man4/inet.4 | 366 ++ static/freebsd/man4/inet6.4 | 493 ++ static/freebsd/man4/intpm.4 | 84 + static/freebsd/man4/intro.4 | 216 + static/freebsd/man4/io.4 | 128 + static/freebsd/man4/ioat.4 | 332 ++ static/freebsd/man4/ip.4 | 952 ++++ static/freebsd/man4/ip17x.4 | 42 + static/freebsd/man4/ip6.4 | 731 +++ static/freebsd/man4/ipfirewall.4 | 160 + static/freebsd/man4/ipheth.4 | 185 + static/freebsd/man4/ipmi.4 | 212 + static/freebsd/man4/ips.4 | 202 + static/freebsd/man4/ipsec.4 | 448 ++ static/freebsd/man4/ipw.4 | 158 + static/freebsd/man4/ipwfw.4 | 73 + static/freebsd/man4/irdma.4 | 243 + static/freebsd/man4/isci.4 | 113 + static/freebsd/man4/iscsi.4 | 117 + static/freebsd/man4/iser.4 | 92 + static/freebsd/man4/isl.4 | 130 + static/freebsd/man4/ismt.4 | 58 + static/freebsd/man4/isp.4 | 250 + static/freebsd/man4/ispfw.4 | 60 + static/freebsd/man4/itwd.4 | 73 + static/freebsd/man4/iwi.4 | 171 + static/freebsd/man4/iwifw.4 | 73 + static/freebsd/man4/iwlwifi.4 | 341 ++ static/freebsd/man4/iwlwififw.4 | 1583 ++++++ static/freebsd/man4/iwm.4 | 192 + static/freebsd/man4/iwmfw.4 | 75 + static/freebsd/man4/iwn.4 | 230 + static/freebsd/man4/iwnfw.4 | 84 + static/freebsd/man4/iwx.4 | 160 + static/freebsd/man4/ix.4 | 242 + static/freebsd/man4/ixl.4 | 308 ++ static/freebsd/man4/jedec_dimm.4 | 251 + static/freebsd/man4/jme.4 | 194 + static/freebsd/man4/kbdmux.4 | 56 + static/freebsd/man4/kcov.4 | 204 + static/freebsd/man4/keyboard.4 | 168 + static/freebsd/man4/kld.4 | 171 + static/freebsd/man4/ksyms.4 | 133 + static/freebsd/man4/ksz8995ma.4 | 67 + static/freebsd/man4/ktls.4 | 257 + static/freebsd/man4/ktr.4 | 208 + static/freebsd/man4/kue.4 | 142 + static/freebsd/man4/kvmclock.4 | 96 + static/freebsd/man4/lagg.4 | 251 + static/freebsd/man4/led.4 | 188 + static/freebsd/man4/lge.4 | 155 + static/freebsd/man4/lindebugfs.4 | 95 + static/freebsd/man4/linprocfs.4 | 167 + static/freebsd/man4/linsysfs.4 | 98 + static/freebsd/man4/linux.4 | 198 + static/freebsd/man4/linuxkpi.4 | 42 + static/freebsd/man4/linuxkpi_wlan.4 | 141 + static/freebsd/man4/liquidio.4 | 132 + static/freebsd/man4/lm75.4 | 186 + static/freebsd/man4/lo.4 | 87 + static/freebsd/man4/lp.4 | 240 + static/freebsd/man4/lpbb.4 | 77 + static/freebsd/man4/lpt.4 | 96 + static/freebsd/man4/ltc430x.4 | 143 + static/freebsd/man4/mac.4 | 258 + static/freebsd/man4/mac_biba.4 | 234 + static/freebsd/man4/mac_bsdextended.4 | 147 + static/freebsd/man4/mac_ddb.4 | 108 + static/freebsd/man4/mac_do.4 | 454 ++ static/freebsd/man4/mac_ifoff.4 | 123 + static/freebsd/man4/mac_ipacl.4 | 164 + static/freebsd/man4/mac_lomac.4 | 220 + static/freebsd/man4/mac_mls.4 | 242 + static/freebsd/man4/mac_none.4 | 104 + static/freebsd/man4/mac_ntpd.4 | 111 + static/freebsd/man4/mac_partition.4 | 124 + static/freebsd/man4/mac_portacl.4 | 216 + static/freebsd/man4/mac_priority.4 | 128 + static/freebsd/man4/mac_seeotheruids.4 | 122 + static/freebsd/man4/mac_stub.4 | 107 + static/freebsd/man4/mac_test.4 | 108 + static/freebsd/man4/malo.4 | 116 + static/freebsd/man4/man4.aarch64/Makefile | 3 + static/freebsd/man4/man4.aarch64/armv8crypto.4 | 81 + static/freebsd/man4/man4.aarch64/enetc.4 | 69 + static/freebsd/man4/man4.aarch64/felix.4 | 83 + static/freebsd/man4/man4.aarch64/rk_gpio.4 | 60 + static/freebsd/man4/man4.aarch64/rk_grf.4 | 57 + static/freebsd/man4/man4.aarch64/rk_grf_gpio.4 | 42 + static/freebsd/man4/man4.aarch64/rk_i2c.4 | 62 + static/freebsd/man4/man4.aarch64/rk_pinctrl.4 | 59 + static/freebsd/man4/man4.arm/Makefile | 3 + static/freebsd/man4/man4.arm/am335x_dmtpps.4 | 161 + static/freebsd/man4/man4.arm/ar40xx.4 | 35 + static/freebsd/man4/man4.arm/bcm283x_pwm.4 | 108 + static/freebsd/man4/man4.arm/devcfg.4 | 93 + static/freebsd/man4/man4.arm/dwcotg.4 | 29 + static/freebsd/man4/man4.arm/imx6_ahci.4 | 63 + static/freebsd/man4/man4.arm/imx6_snvs.4 | 76 + static/freebsd/man4/man4.arm/imx_spi.4 | 88 + static/freebsd/man4/man4.arm/imx_wdog.4 | 110 + static/freebsd/man4/man4.arm/mge.4 | 158 + static/freebsd/man4/man4.arm/ti_adc.4 | 126 + static/freebsd/man4/man4.i386/CPU_ELAN.4 | 157 + static/freebsd/man4/man4.i386/Makefile | 3 + static/freebsd/man4/man4.i386/apm.4 | 159 + static/freebsd/man4/man4.i386/glxiic.4 | 105 + static/freebsd/man4/man4.i386/glxsb.4 | 96 + static/freebsd/man4/man4.i386/longrun.4 | 65 + static/freebsd/man4/man4.i386/npx.4 | 110 + static/freebsd/man4/man4.i386/pae.4 | 125 + static/freebsd/man4/man4.i386/pbio.4 | 185 + static/freebsd/man4/man4.i386/pnp.4 | 83 + static/freebsd/man4/man4.i386/pnpbios.4 | 83 + static/freebsd/man4/man4.i386/sbni.4 | 130 + static/freebsd/man4/man4.i386/smapi.4 | 151 + static/freebsd/man4/man4.i386/vpd.4 | 88 + static/freebsd/man4/man4.powerpc/Makefile | 3 + static/freebsd/man4/man4.powerpc/abtn.4 | 113 + static/freebsd/man4/man4.powerpc/adb.4 | 67 + static/freebsd/man4/man4.powerpc/akbd.4 | 102 + static/freebsd/man4/man4.powerpc/ams.4 | 84 + static/freebsd/man4/man4.powerpc/cuda.4 | 77 + static/freebsd/man4/man4.powerpc/dtsec.4 | 117 + static/freebsd/man4/man4.powerpc/llan.4 | 59 + static/freebsd/man4/man4.powerpc/ofw_console.4 | 110 + static/freebsd/man4/man4.powerpc/pmu.4 | 114 + static/freebsd/man4/man4.powerpc/powermac_nvram.4 | 65 + static/freebsd/man4/man4.powerpc/smu.4 | 124 + static/freebsd/man4/man4.powerpc/snd_ai2s.4 | 86 + static/freebsd/man4/man4.powerpc/snd_davbus.4 | 78 + static/freebsd/man4/man4.powerpc/tsec.4 | 157 + static/freebsd/man4/max44009.4 | 90 + static/freebsd/man4/mca.4 | 277 ++ static/freebsd/man4/md.4 | 168 + static/freebsd/man4/mdio.4 | 52 + static/freebsd/man4/me.4 | 82 + static/freebsd/man4/mem.4 | 314 ++ static/freebsd/man4/mfi.4 | 155 + static/freebsd/man4/mgb.4 | 84 + static/freebsd/man4/miibus.4 | 177 + static/freebsd/man4/mld.4 | 100 + static/freebsd/man4/mlx.4 | 244 + static/freebsd/man4/mlx4en.4 | 93 + static/freebsd/man4/mlx4ib.4 | 93 + static/freebsd/man4/mlx5en.4 | 132 + static/freebsd/man4/mlx5ib.4 | 122 + static/freebsd/man4/mlx5io.4 | 189 + static/freebsd/man4/mmc.4 | 56 + static/freebsd/man4/mmcsd.4 | 51 + static/freebsd/man4/mod_cc.4 | 207 + static/freebsd/man4/mos.4 | 96 + static/freebsd/man4/mouse.4 | 376 ++ static/freebsd/man4/mpi3mr.4 | 81 + static/freebsd/man4/mpr.4 | 415 ++ static/freebsd/man4/mps.4 | 385 ++ static/freebsd/man4/mpt.4 | 193 + static/freebsd/man4/mqueuefs.4 | 122 + static/freebsd/man4/mrsas.4 | 389 ++ static/freebsd/man4/msdosfs.4 | 75 + static/freebsd/man4/msk.4 | 253 + static/freebsd/man4/mt7915.4 | 111 + static/freebsd/man4/mt7921.4 | 111 + static/freebsd/man4/mtio.4 | 411 ++ static/freebsd/man4/mtkswitch.4 | 45 + static/freebsd/man4/mtw.4 | 118 + static/freebsd/man4/muge.4 | 66 + static/freebsd/man4/multicast.4 | 1027 ++++ static/freebsd/man4/mvs.4 | 169 + static/freebsd/man4/mwl.4 | 191 + static/freebsd/man4/mwlfw.4 | 50 + static/freebsd/man4/mx25l.4 | 199 + static/freebsd/man4/mxge.4 | 183 + static/freebsd/man4/my.4 | 87 + static/freebsd/man4/nctgpio.4 | 54 + static/freebsd/man4/ncthwm.4 | 52 + static/freebsd/man4/nda.4 | 215 + static/freebsd/man4/net80211.4 | 1326 +++++ static/freebsd/man4/netdump.4 | 165 + static/freebsd/man4/netfpga10g_nf10bmac.4 | 68 + static/freebsd/man4/netgdb.4 | 148 + static/freebsd/man4/netgraph.4 | 1475 ++++++ static/freebsd/man4/netintro.4 | 442 ++ static/freebsd/man4/netlink.4 | 358 ++ static/freebsd/man4/netmap.4 | 1200 +++++ static/freebsd/man4/nfe.4 | 198 + static/freebsd/man4/nfslockd.4 | 45 + static/freebsd/man4/nfsmb.4 | 52 + static/freebsd/man4/ng_UI.4 | 91 + static/freebsd/man4/ng_async.4 | 170 + static/freebsd/man4/ng_bluetooth.4 | 111 + static/freebsd/man4/ng_bpf.4 | 230 + static/freebsd/man4/ng_bridge.4 | 290 ++ static/freebsd/man4/ng_btsocket.4 | 353 ++ static/freebsd/man4/ng_car.4 | 216 + static/freebsd/man4/ng_checksum.4 | 145 + static/freebsd/man4/ng_cisco.4 | 182 + static/freebsd/man4/ng_deflate.4 | 157 + static/freebsd/man4/ng_device.4 | 102 + static/freebsd/man4/ng_echo.4 | 71 + static/freebsd/man4/ng_eiface.4 | 120 + static/freebsd/man4/ng_etf.4 | 152 + static/freebsd/man4/ng_ether.4 | 239 + static/freebsd/man4/ng_ether_echo.4 | 75 + static/freebsd/man4/ng_frame_relay.4 | 97 + static/freebsd/man4/ng_gif.4 | 124 + static/freebsd/man4/ng_gif_demux.4 | 105 + static/freebsd/man4/ng_hci.4 | 386 ++ static/freebsd/man4/ng_hole.4 | 89 + static/freebsd/man4/ng_hub.4 | 73 + static/freebsd/man4/ng_iface.4 | 164 + static/freebsd/man4/ng_ip_input.4 | 100 + static/freebsd/man4/ng_ipfw.4 | 115 + static/freebsd/man4/ng_ksocket.4 | 247 + static/freebsd/man4/ng_l2cap.4 | 421 ++ static/freebsd/man4/ng_l2tp.4 | 327 ++ static/freebsd/man4/ng_lmi.4 | 136 + static/freebsd/man4/ng_macfilter.4 | 220 + static/freebsd/man4/ng_mppc.4 | 185 + static/freebsd/man4/ng_nat.4 | 408 ++ static/freebsd/man4/ng_netflow.4 | 356 ++ static/freebsd/man4/ng_one2many.4 | 275 + static/freebsd/man4/ng_patch.4 | 271 + static/freebsd/man4/ng_pipe.4 | 213 + static/freebsd/man4/ng_ppp.4 | 458 ++ static/freebsd/man4/ng_pppoe.4 | 587 +++ static/freebsd/man4/ng_pptpgre.4 | 198 + static/freebsd/man4/ng_pred1.4 | 144 + static/freebsd/man4/ng_rfc1490.4 | 139 + static/freebsd/man4/ng_socket.4 | 188 + static/freebsd/man4/ng_source.4 | 355 ++ static/freebsd/man4/ng_split.4 | 86 + static/freebsd/man4/ng_tag.4 | 328 ++ static/freebsd/man4/ng_tcpmss.4 | 123 + static/freebsd/man4/ng_tee.4 | 132 + static/freebsd/man4/ng_tty.4 | 127 + static/freebsd/man4/ng_ubt.4 | 124 + static/freebsd/man4/ng_vjc.4 | 236 + static/freebsd/man4/ng_vlan.4 | 143 + static/freebsd/man4/ng_vlan_rotate.4 | 250 + static/freebsd/man4/nge.4 | 223 + static/freebsd/man4/nlsysevent.4 | 132 + static/freebsd/man4/nmdm.4 | 96 + static/freebsd/man4/ntb.4 | 90 + static/freebsd/man4/ntb_hw_amd.4 | 92 + static/freebsd/man4/ntb_hw_intel.4 | 98 + static/freebsd/man4/ntb_hw_plx.4 | 121 + static/freebsd/man4/ntb_transport.4 | 112 + static/freebsd/man4/null.4 | 54 + static/freebsd/man4/nullfs.4 | 80 + static/freebsd/man4/numa.4 | 150 + static/freebsd/man4/nvd.4 | 110 + static/freebsd/man4/nvdimm.4 | 132 + static/freebsd/man4/nvme.4 | 294 ++ static/freebsd/man4/nvmf.4 | 106 + static/freebsd/man4/nvmf_che.4 | 80 + static/freebsd/man4/nvmf_tcp.4 | 64 + static/freebsd/man4/nvmft.4 | 85 + static/freebsd/man4/nvram.4 | 91 + static/freebsd/man4/oce.4 | 133 + static/freebsd/man4/ocs_fc.4 | 194 + static/freebsd/man4/ohci.4 | 86 + static/freebsd/man4/openfirm.4 | 292 ++ static/freebsd/man4/orm.4 | 45 + static/freebsd/man4/ossl.4 | 115 + static/freebsd/man4/otus.4 | 188 + static/freebsd/man4/otusfw.4 | 44 + static/freebsd/man4/ovpn.4 | 54 + static/freebsd/man4/ow.4 | 57 + static/freebsd/man4/ow_temp.4 | 149 + static/freebsd/man4/owc.4 | 110 + static/freebsd/man4/p9fs.4 | 127 + static/freebsd/man4/padlock.4 | 96 + static/freebsd/man4/pass.4 | 240 + static/freebsd/man4/pca954x.4 | 117 + static/freebsd/man4/pccbb.4 | 179 + static/freebsd/man4/pcf.4 | 70 + static/freebsd/man4/pcf8574.4 | 96 + static/freebsd/man4/pcf8591.4 | 120 + static/freebsd/man4/pchtherm.4 | 114 + static/freebsd/man4/pci.4 | 764 +++ static/freebsd/man4/pcib.4 | 46 + static/freebsd/man4/pcm.4 | 682 +++ static/freebsd/man4/pf.4 | 1279 +++++ static/freebsd/man4/pflog.4 | 115 + static/freebsd/man4/pflow.4 | 123 + static/freebsd/man4/pfsync.4 | 296 ++ static/freebsd/man4/pim.4 | 199 + static/freebsd/man4/pms.4 | 124 + static/freebsd/man4/polling.4 | 218 + static/freebsd/man4/ppbus.4 | 346 ++ static/freebsd/man4/ppc.4 | 134 + static/freebsd/man4/ppi.4 | 105 + static/freebsd/man4/procdesc.4 | 83 + static/freebsd/man4/procfs.4 | 308 ++ static/freebsd/man4/proto.4 | 473 ++ static/freebsd/man4/ps4dshock.4 | 110 + static/freebsd/man4/psm.4 | 873 ++++ static/freebsd/man4/pst.4 | 73 + static/freebsd/man4/pt.4 | 89 + static/freebsd/man4/ptnet.4 | 138 + static/freebsd/man4/pts.4 | 158 + static/freebsd/man4/pty.4 | 98 + static/freebsd/man4/puc.4 | 291 ++ static/freebsd/man4/pvscsi.4 | 72 + static/freebsd/man4/pwmc.4 | 209 + static/freebsd/man4/qat.4 | 189 + static/freebsd/man4/qat_c2xxx.4 | 100 + static/freebsd/man4/qlnxe.4 | 90 + static/freebsd/man4/qlxgb.4 | 91 + static/freebsd/man4/qlxgbe.4 | 90 + static/freebsd/man4/qlxge.4 | 89 + static/freebsd/man4/ral.4 | 301 ++ static/freebsd/man4/random.4 | 303 ++ static/freebsd/man4/rccgpio.4 | 61 + static/freebsd/man4/rctl.4 | 71 + static/freebsd/man4/re.4 | 293 ++ static/freebsd/man4/rge.4 | 195 + static/freebsd/man4/rgephy.4 | 93 + static/freebsd/man4/rights.4 | 751 +++ static/freebsd/man4/rl.4 | 310 ++ static/freebsd/man4/rndtest.4 | 68 + static/freebsd/man4/route.4 | 326 ++ static/freebsd/man4/rsu.4 | 215 + static/freebsd/man4/rsufw.4 | 45 + static/freebsd/man4/rtnetlink.4 | 542 ++ static/freebsd/man4/rtsx.4 | 141 + static/freebsd/man4/rtw88.4 | 110 + static/freebsd/man4/rtw89.4 | 112 + static/freebsd/man4/rtwn.4 | 268 + static/freebsd/man4/rtwn_pci.4 | 73 + static/freebsd/man4/rtwn_usb.4 | 134 + static/freebsd/man4/rtwnfw.4 | 92 + static/freebsd/man4/rue.4 | 153 + static/freebsd/man4/rum.4 | 185 + static/freebsd/man4/run.4 | 319 ++ static/freebsd/man4/runfw.4 | 48 + static/freebsd/man4/sa.4 | 500 ++ static/freebsd/man4/safe.4 | 146 + static/freebsd/man4/safexcel.4 | 90 + static/freebsd/man4/sbp.4 | 106 + static/freebsd/man4/sbp_targ.4 | 96 + static/freebsd/man4/scc.4 | 75 + static/freebsd/man4/sched_4bsd.4 | 72 + static/freebsd/man4/sched_ule.4 | 73 + static/freebsd/man4/screen.4 | 239 + static/freebsd/man4/scsi.4 | 562 +++ static/freebsd/man4/sctp.4 | 624 +++ static/freebsd/man4/sdhci.4 | 90 + static/freebsd/man4/sem.4 | 79 + static/freebsd/man4/send.4 | 212 + static/freebsd/man4/ses.4 | 151 + static/freebsd/man4/sfxge.4 | 187 + static/freebsd/man4/sg.4 | 63 + static/freebsd/man4/sge.4 | 117 + static/freebsd/man4/siba.4 | 91 + static/freebsd/man4/siftr.4 | 744 +++ static/freebsd/man4/siis.4 | 133 + static/freebsd/man4/simplebus.4 | 81 + static/freebsd/man4/sis.4 | 223 + static/freebsd/man4/sk.4 | 239 + static/freebsd/man4/smartpqi.4 | 175 + static/freebsd/man4/smb.4 | 201 + static/freebsd/man4/smbfs.4 | 99 + static/freebsd/man4/smbios.4 | 63 + static/freebsd/man4/smbus.4 | 77 + static/freebsd/man4/smp.4 | 188 + static/freebsd/man4/smsc.4 | 90 + static/freebsd/man4/snd_als4000.4 | 68 + static/freebsd/man4/snd_atiixp.4 | 98 + static/freebsd/man4/snd_cmi.4 | 74 + static/freebsd/man4/snd_cs4281.4 | 68 + static/freebsd/man4/snd_csa.4 | 96 + static/freebsd/man4/snd_dummy.4 | 80 + static/freebsd/man4/snd_emu10k1.4 | 80 + static/freebsd/man4/snd_emu10kx.4 | 294 ++ static/freebsd/man4/snd_envy24.4 | 82 + static/freebsd/man4/snd_envy24ht.4 | 107 + static/freebsd/man4/snd_es137x.4 | 115 + static/freebsd/man4/snd_fm801.4 | 76 + static/freebsd/man4/snd_hda.4 | 641 +++ static/freebsd/man4/snd_hdsp.4 | 176 + static/freebsd/man4/snd_hdspe.4 | 178 + static/freebsd/man4/snd_ich.4 | 109 + static/freebsd/man4/snd_maestro3.4 | 92 + static/freebsd/man4/snd_neomagic.4 | 72 + static/freebsd/man4/snd_solo.4 | 59 + static/freebsd/man4/snd_spicds.4 | 87 + static/freebsd/man4/snd_t4dwave.4 | 75 + static/freebsd/man4/snd_uaudio.4 | 170 + static/freebsd/man4/snd_via8233.4 | 103 + static/freebsd/man4/snd_via82c686.4 | 69 + static/freebsd/man4/snd_vibes.4 | 69 + static/freebsd/man4/sndstat.4 | 400 ++ static/freebsd/man4/snp.4 | 87 + static/freebsd/man4/spigen.4 | 205 + static/freebsd/man4/spkr.4 | 247 + static/freebsd/man4/splash.4 | 329 ++ static/freebsd/man4/ste.4 | 201 + static/freebsd/man4/stf.4 | 339 ++ static/freebsd/man4/stge.4 | 198 + static/freebsd/man4/sume.4 | 96 + static/freebsd/man4/superio.4 | 149 + static/freebsd/man4/sym.4 | 325 ++ static/freebsd/man4/syncache.4 | 263 + static/freebsd/man4/syncer.4 | 90 + static/freebsd/man4/syscons.4 | 647 +++ static/freebsd/man4/sysmouse.4 | 463 ++ static/freebsd/man4/tap.4 | 333 ++ static/freebsd/man4/tarfs.4 | 126 + static/freebsd/man4/targ.4 | 150 + static/freebsd/man4/tcp.4 | 1160 +++++ static/freebsd/man4/tcp_bbr.4 | 161 + static/freebsd/man4/tcp_rack.4 | 162 + static/freebsd/man4/tdfx.4 | 96 + static/freebsd/man4/termios.4 | 1610 ++++++ static/freebsd/man4/textdump.4 | 194 + static/freebsd/man4/thunderbolt.4 | 22 + static/freebsd/man4/ti.4 | 423 ++ static/freebsd/man4/timecounters.4 | 111 + static/freebsd/man4/tmpfs.4 | 229 + static/freebsd/man4/tpm.4 | 122 + static/freebsd/man4/tslog.4 | 137 + static/freebsd/man4/tty.4 | 395 ++ static/freebsd/man4/tun.4 | 358 ++ static/freebsd/man4/tws.4 | 116 + static/freebsd/man4/u2f.4 | 96 + static/freebsd/man4/u3g.4 | 175 + static/freebsd/man4/uark.4 | 96 + static/freebsd/man4/uart.4 | 403 ++ static/freebsd/man4/uath.4 | 184 + static/freebsd/man4/ubsa.4 | 121 + static/freebsd/man4/ubser.4 | 78 + static/freebsd/man4/ubtbcmfw.4 | 107 + static/freebsd/man4/uchcom.4 | 127 + static/freebsd/man4/ucom.4 | 166 + static/freebsd/man4/ucycom.4 | 101 + static/freebsd/man4/udav.4 | 100 + static/freebsd/man4/udbc.4 | 132 + static/freebsd/man4/udbp.4 | 163 + static/freebsd/man4/udl.4 | 95 + static/freebsd/man4/udp.4 | 186 + static/freebsd/man4/udplite.4 | 94 + static/freebsd/man4/uep.4 | 97 + static/freebsd/man4/ufintek.4 | 118 + static/freebsd/man4/ufoma.4 | 139 + static/freebsd/man4/ufshci.4 | 213 + static/freebsd/man4/uftdi.4 | 279 ++ static/freebsd/man4/ugen.4 | 326 ++ static/freebsd/man4/ugold.4 | 59 + static/freebsd/man4/uhci.4 | 78 + static/freebsd/man4/uhid.4 | 181 + static/freebsd/man4/uhso.4 | 140 + static/freebsd/man4/uipaq.4 | 119 + static/freebsd/man4/ukbd.4 | 207 + static/freebsd/man4/uled.4 | 93 + static/freebsd/man4/ulpt.4 | 108 + static/freebsd/man4/umass.4 | 147 + static/freebsd/man4/umb.4 | 118 + static/freebsd/man4/umcs.4 | 112 + static/freebsd/man4/umct.4 | 113 + static/freebsd/man4/umodem.4 | 128 + static/freebsd/man4/umoscom.4 | 81 + static/freebsd/man4/ums.4 | 124 + static/freebsd/man4/unionfs.4 | 89 + static/freebsd/man4/unix.4 | 473 ++ static/freebsd/man4/upgt.4 | 228 + static/freebsd/man4/uplcom.4 | 227 + static/freebsd/man4/ural.4 | 163 + static/freebsd/man4/ure.4 | 138 + static/freebsd/man4/urio.4 | 128 + static/freebsd/man4/urndis.4 | 106 + static/freebsd/man4/urtw.4 | 125 + static/freebsd/man4/usb.4 | 178 + static/freebsd/man4/usb_quirk.4 | 267 + static/freebsd/man4/usb_template.4 | 134 + static/freebsd/man4/usbhid.4 | 94 + static/freebsd/man4/usfs.4 | 74 + static/freebsd/man4/uslcom.4 | 229 + static/freebsd/man4/uvisor.4 | 154 + static/freebsd/man4/uvscom.4 | 107 + static/freebsd/man4/vale.4 | 120 + static/freebsd/man4/veriexec.4 | 96 + static/freebsd/man4/vga.4 | 183 + static/freebsd/man4/vge.4 | 223 + static/freebsd/man4/viapm.4 | 70 + static/freebsd/man4/viawd.4 | 77 + static/freebsd/man4/virtio.4 | 134 + static/freebsd/man4/virtio_balloon.4 | 62 + static/freebsd/man4/virtio_blk.4 | 90 + static/freebsd/man4/virtio_console.4 | 65 + static/freebsd/man4/virtio_gpu.4 | 54 + static/freebsd/man4/virtio_random.4 | 59 + static/freebsd/man4/virtio_scsi.4 | 91 + static/freebsd/man4/vkbd.4 | 153 + static/freebsd/man4/vlan.4 | 197 + static/freebsd/man4/vmci.4 | 70 + static/freebsd/man4/vmd.4 | 83 + static/freebsd/man4/vmgenc.4 | 62 + static/freebsd/man4/vmm.4 | 196 + static/freebsd/man4/vmx.4 | 155 + static/freebsd/man4/vr.4 | 215 + static/freebsd/man4/vt.4 | 456 ++ static/freebsd/man4/vte.4 | 149 + static/freebsd/man4/vtnet.4 | 298 ++ static/freebsd/man4/vxlan.4 | 292 ++ static/freebsd/man4/watchdog.4 | 218 + static/freebsd/man4/wbwd.4 | 142 + static/freebsd/man4/wdatwd.4 | 91 + static/freebsd/man4/wg.4 | 238 + static/freebsd/man4/witness.4 | 229 + static/freebsd/man4/wlan.4 | 221 + static/freebsd/man4/wlan_acl.4 | 55 + static/freebsd/man4/wlan_amrr.4 | 57 + static/freebsd/man4/wlan_ccmp.4 | 65 + static/freebsd/man4/wlan_gcmp.4 | 72 + static/freebsd/man4/wlan_tkip.4 | 65 + static/freebsd/man4/wlan_wep.4 | 62 + static/freebsd/man4/wlan_xauth.4 | 59 + static/freebsd/man4/wmt.4 | 79 + static/freebsd/man4/wpi.4 | 216 + static/freebsd/man4/wsp.4 | 219 + static/freebsd/man4/xb360gp.4 | 99 + static/freebsd/man4/xdma.4 | 75 + static/freebsd/man4/xen.4 | 138 + static/freebsd/man4/xhci.4 | 103 + static/freebsd/man4/xl.4 | 267 + static/freebsd/man4/xnb.4 | 139 + static/freebsd/man4/xpt.4 | 106 + static/freebsd/man4/zero.4 | 57 + static/freebsd/man4/zyd.4 | 231 + static/freebsd/man5/Makefile | 3 + static/freebsd/man5/a.out.5 | 453 ++ static/freebsd/man5/acct.5 | 124 + static/freebsd/man5/ar.5 | 325 ++ static/freebsd/man5/bluetooth.device.conf.5 | 182 + static/freebsd/man5/bluetooth.hosts.5 | 62 + static/freebsd/man5/bluetooth.protocols.5 | 61 + static/freebsd/man5/boot.config.5 | 104 + static/freebsd/man5/core.5 | 190 + static/freebsd/man5/devfs.conf.5 | 127 + static/freebsd/man5/devfs.rules.5 | 133 + static/freebsd/man5/device.hints.5 | 166 + static/freebsd/man5/dir.5 | 164 + static/freebsd/man5/disktab.5 | 136 + static/freebsd/man5/elf.5 | 1469 ++++++ static/freebsd/man5/ethers.5 | 100 + static/freebsd/man5/eui64.5 | 108 + static/freebsd/man5/fbtab.5 | 45 + static/freebsd/man5/forward.5 | 94 + static/freebsd/man5/freebsd-update.conf.5 | 289 ++ static/freebsd/man5/fs.5 | 428 ++ static/freebsd/man5/fstab.5 | 467 ++ static/freebsd/man5/group.5 | 164 + static/freebsd/man5/hesiod.conf.5 | 78 + static/freebsd/man5/hosts.5 | 91 + static/freebsd/man5/hosts.equiv.5 | 139 + static/freebsd/man5/hosts.lpd.5 | 56 + static/freebsd/man5/intro.5 | 68 + static/freebsd/man5/libmap.conf.5 | 179 + static/freebsd/man5/link.5 | 588 +++ static/freebsd/man5/mailer.conf.5 | 171 + static/freebsd/man5/make.conf.5 | 688 +++ static/freebsd/man5/moduli.5 | 123 + static/freebsd/man5/motd.5 | 63 + static/freebsd/man5/mount.conf.5 | 249 + static/freebsd/man5/networks.5 | 82 + static/freebsd/man5/nsmb.conf.5 | 166 + static/freebsd/man5/nsswitch.conf.5 | 386 ++ static/freebsd/man5/os-release.5 | 131 + static/freebsd/man5/passwd.5 | 460 ++ static/freebsd/man5/pbm.5 | 86 + static/freebsd/man5/periodic.conf.5 | 1095 ++++ static/freebsd/man5/pf.conf.5 | 3894 +++++++++++++++ static/freebsd/man5/pf.os.5 | 221 + static/freebsd/man5/phones.5 | 75 + static/freebsd/man5/portindex.5 | 98 + static/freebsd/man5/protocols.5 | 84 + static/freebsd/man5/quota.user.5 | 128 + static/freebsd/man5/rc.conf.5 | 5239 ++++++++++++++++++++ static/freebsd/man5/rctl.conf.5 | 72 + static/freebsd/man5/regdomain.5 | 46 + static/freebsd/man5/remote.5 | 207 + static/freebsd/man5/resolver.5 | 292 ++ static/freebsd/man5/services.5 | 103 + static/freebsd/man5/shells.5 | 59 + static/freebsd/man5/src.conf.5 | 2056 ++++++++ static/freebsd/man5/stab.5 | 214 + static/freebsd/man5/style.Makefile.5 | 288 ++ static/freebsd/man5/style.mdoc.5 | 229 + static/freebsd/man5/sysctl.conf.5 | 106 + static/freebsd/man6/Makefile | 3 + static/freebsd/man6/intro.6 | 66 + static/freebsd/man7/Makefile | 3 + static/freebsd/man7/arch.7 | 563 +++ static/freebsd/man7/ascii.7 | 195 + static/freebsd/man7/bsd.snmpmod.mk.7 | 115 + static/freebsd/man7/build.7 | 1196 +++++ static/freebsd/man7/c.7 | 532 ++ static/freebsd/man7/clocks.7 | 171 + static/freebsd/man7/crypto.7 | 179 + static/freebsd/man7/d.7 | 413 ++ static/freebsd/man7/development.7 | 188 + static/freebsd/man7/environ.7 | 333 ++ static/freebsd/man7/firewall.7 | 440 ++ static/freebsd/man7/freebsd-base.7 | 264 + static/freebsd/man7/growfs.7 | 140 + static/freebsd/man7/hier.7 | 996 ++++ static/freebsd/man7/hostname.7 | 85 + static/freebsd/man7/intro.7 | 106 + static/freebsd/man7/maclabel.7 | 96 + static/freebsd/man7/mitigations.7 | 509 ++ static/freebsd/man7/named_attribute.7 | 320 ++ static/freebsd/man7/networking.7 | 93 + static/freebsd/man7/operator.7 | 61 + static/freebsd/man7/orders.7 | 115 + static/freebsd/man7/ports.7 | 788 +++ static/freebsd/man7/release.7 | 806 +++ static/freebsd/man7/sdoc.7 | 242 + static/freebsd/man7/security.7 | 1127 +++++ static/freebsd/man7/simd.7 | 246 + static/freebsd/man7/sizeof.7 | 308 ++ static/freebsd/man7/sprog.7 | 178 + static/freebsd/man7/stats.7 | 123 + static/freebsd/man7/stdint.7 | 134 + static/freebsd/man7/sticky.7 | 75 + static/freebsd/man7/tests.7 | 322 ++ static/freebsd/man7/tracing.7 | 100 + static/freebsd/man7/tuning.7 | 749 +++ static/freebsd/man8/Makefile | 3 + static/freebsd/man8/beinstall.8 | 128 + static/freebsd/man8/crash.8 | 210 + static/freebsd/man8/debug.sh.8 | 191 + static/freebsd/man8/diskless.8 | 486 ++ static/freebsd/man8/intro.8 | 86 + static/freebsd/man8/nanobsd.8 | 366 ++ static/freebsd/man8/rc.8 | 587 +++ static/freebsd/man8/rc.subr.8 | 1186 +++++ static/freebsd/man8/rescue.8 | 178 + static/freebsd/man8/uefi.8 | 134 + static/freebsd/man8/yp.8 | 588 +++ static/freebsd/man9/BUF_ISLOCKED.9 | 66 + static/freebsd/man9/BUF_LOCK.9 | 73 + static/freebsd/man9/BUF_LOCKFREE.9 | 61 + static/freebsd/man9/BUF_LOCKINIT.9 | 60 + static/freebsd/man9/BUF_RECURSED.9 | 63 + static/freebsd/man9/BUF_TIMELOCK.9 | 81 + static/freebsd/man9/BUF_UNLOCK.9 | 62 + static/freebsd/man9/BUS_ADD_CHILD.9 | 83 + static/freebsd/man9/BUS_BIND_INTR.9 | 96 + static/freebsd/man9/BUS_CHILD_DELETED.9 | 53 + static/freebsd/man9/BUS_CHILD_DETACHED.9 | 53 + static/freebsd/man9/BUS_CHILD_LOCATION.9 | 59 + static/freebsd/man9/BUS_CHILD_PNPINFO.9 | 63 + static/freebsd/man9/BUS_CONFIG_INTR.9 | 113 + static/freebsd/man9/BUS_DESCRIBE_INTR.9 | 102 + static/freebsd/man9/BUS_GET_CPUS.9 | 98 + static/freebsd/man9/BUS_GET_PROPERTY.9 | 74 + static/freebsd/man9/BUS_HINTED_CHILD.9 | 37 + static/freebsd/man9/BUS_NEW_PASS.9 | 54 + static/freebsd/man9/BUS_PRINT_CHILD.9 | 62 + static/freebsd/man9/BUS_READ_IVAR.9 | 61 + static/freebsd/man9/BUS_RESCAN.9 | 48 + static/freebsd/man9/BUS_SETUP_INTR.9 | 212 + static/freebsd/man9/CTASSERT.9 | 68 + static/freebsd/man9/DB_COMMAND.9 | 180 + static/freebsd/man9/DECLARE_GEOM_CLASS.9 | 177 + static/freebsd/man9/DECLARE_MODULE.9 | 127 + static/freebsd/man9/DEFINE_IFUNC.9 | 140 + static/freebsd/man9/DELAY.9 | 47 + static/freebsd/man9/DEVICE_ATTACH.9 | 70 + static/freebsd/man9/DEVICE_DETACH.9 | 60 + static/freebsd/man9/DEVICE_IDENTIFY.9 | 91 + static/freebsd/man9/DEVICE_PROBE.9 | 138 + static/freebsd/man9/DEVICE_SHUTDOWN.9 | 55 + static/freebsd/man9/DEV_MODULE.9 | 103 + static/freebsd/man9/DRIVER_MODULE.9 | 151 + static/freebsd/man9/EVENTHANDLER.9 | 288 ++ static/freebsd/man9/KASSERT.9 | 201 + static/freebsd/man9/LOCK_PROFILING.9 | 185 + static/freebsd/man9/MODULE_DEPEND.9 | 78 + static/freebsd/man9/MODULE_PNP_INFO.9 | 218 + static/freebsd/man9/MODULE_VERSION.9 | 57 + static/freebsd/man9/Makefile | 3 + static/freebsd/man9/OF_child.9 | 73 + static/freebsd/man9/OF_device_from_xref.9 | 100 + static/freebsd/man9/OF_finddevice.9 | 71 + static/freebsd/man9/OF_getprop.9 | 354 ++ static/freebsd/man9/OF_node_from_xref.9 | 99 + static/freebsd/man9/OF_package_to_path.9 | 51 + static/freebsd/man9/PCI_IOV_ADD_VF.9 | 110 + static/freebsd/man9/PCI_IOV_INIT.9 | 83 + static/freebsd/man9/PCI_IOV_UNINIT.9 | 61 + static/freebsd/man9/PHOLD.9 | 65 + static/freebsd/man9/SDT.9 | 344 ++ static/freebsd/man9/SYSCALL_MODULE.9 | 97 + static/freebsd/man9/SYSINIT.9 | 162 + static/freebsd/man9/VFS.9 | 59 + static/freebsd/man9/VFS_CHECKEXP.9 | 96 + static/freebsd/man9/VFS_FHTOVP.9 | 89 + static/freebsd/man9/VFS_MOUNT.9 | 82 + static/freebsd/man9/VFS_QUOTACTL.9 | 77 + static/freebsd/man9/VFS_ROOT.9 | 65 + static/freebsd/man9/VFS_SET.9 | 110 + static/freebsd/man9/VFS_STATFS.9 | 114 + static/freebsd/man9/VFS_SYNC.9 | 79 + static/freebsd/man9/VFS_UNMOUNT.9 | 66 + static/freebsd/man9/VFS_VGET.9 | 81 + static/freebsd/man9/VNET.9 | 471 ++ static/freebsd/man9/VOP_ACCESS.9 | 101 + static/freebsd/man9/VOP_ACLCHECK.9 | 100 + static/freebsd/man9/VOP_ADVISE.9 | 89 + static/freebsd/man9/VOP_ADVLOCK.9 | 84 + static/freebsd/man9/VOP_ALLOCATE.9 | 92 + static/freebsd/man9/VOP_ATTRIB.9 | 149 + static/freebsd/man9/VOP_BMAP.9 | 84 + static/freebsd/man9/VOP_BWRITE.9 | 54 + static/freebsd/man9/VOP_COPY_FILE_RANGE.9 | 142 + static/freebsd/man9/VOP_CREATE.9 | 98 + static/freebsd/man9/VOP_DEALLOCATE.9 | 109 + static/freebsd/man9/VOP_FSYNC.9 | 106 + static/freebsd/man9/VOP_GETACL.9 | 94 + static/freebsd/man9/VOP_GETEXTATTR.9 | 131 + static/freebsd/man9/VOP_GETPAGES.9 | 205 + static/freebsd/man9/VOP_INACTIVE.9 | 79 + static/freebsd/man9/VOP_INOTIFY.9 | 60 + static/freebsd/man9/VOP_IOCTL.9 | 72 + static/freebsd/man9/VOP_LINK.9 | 81 + static/freebsd/man9/VOP_LISTEXTATTR.9 | 134 + static/freebsd/man9/VOP_LOCK.9 | 123 + static/freebsd/man9/VOP_LOOKUP.9 | 180 + static/freebsd/man9/VOP_OPENCLOSE.9 | 113 + static/freebsd/man9/VOP_PATHCONF.9 | 88 + static/freebsd/man9/VOP_PRINT.9 | 52 + static/freebsd/man9/VOP_RDWR.9 | 103 + static/freebsd/man9/VOP_READDIR.9 | 108 + static/freebsd/man9/VOP_READLINK.9 | 67 + static/freebsd/man9/VOP_READ_PGCACHE.9 | 131 + static/freebsd/man9/VOP_REALLOCBLKS.9 | 57 + static/freebsd/man9/VOP_REMOVE.9 | 75 + static/freebsd/man9/VOP_RENAME.9 | 94 + static/freebsd/man9/VOP_REVOKE.9 | 68 + static/freebsd/man9/VOP_SETACL.9 | 103 + static/freebsd/man9/VOP_SETEXTATTR.9 | 117 + static/freebsd/man9/VOP_SETLABEL.9 | 125 + static/freebsd/man9/VOP_STRATEGY.9 | 71 + static/freebsd/man9/VOP_VPTOCNP.9 | 94 + static/freebsd/man9/VOP_VPTOFH.9 | 58 + static/freebsd/man9/accept_filter.9 | 150 + static/freebsd/man9/accf_data.9 | 79 + static/freebsd/man9/accf_dns.9 | 80 + static/freebsd/man9/accf_http.9 | 99 + static/freebsd/man9/accf_tls.9 | 98 + static/freebsd/man9/acl.9 | 223 + static/freebsd/man9/alq.9 | 439 ++ static/freebsd/man9/altq.9 | 600 +++ static/freebsd/man9/atomic.9 | 654 +++ static/freebsd/man9/backlight.9 | 78 + static/freebsd/man9/bhnd.9 | 2664 ++++++++++ static/freebsd/man9/bhnd_erom.9 | 483 ++ static/freebsd/man9/bios.9 | 179 + static/freebsd/man9/bitset.9 | 658 +++ static/freebsd/man9/bpf.9 | 299 ++ static/freebsd/man9/buf.9 | 189 + static/freebsd/man9/buf_ring.9 | 131 + static/freebsd/man9/bus_activate_resource.9 | 126 + static/freebsd/man9/bus_adjust_resource.9 | 95 + static/freebsd/man9/bus_alloc_resource.9 | 187 + static/freebsd/man9/bus_attach_children.9 | 152 + static/freebsd/man9/bus_child_present.9 | 81 + static/freebsd/man9/bus_dma.9 | 1333 +++++ static/freebsd/man9/bus_generic_detach.9 | 67 + static/freebsd/man9/bus_generic_new_pass.9 | 55 + static/freebsd/man9/bus_generic_print_child.9 | 114 + static/freebsd/man9/bus_generic_read_ivar.9 | 55 + static/freebsd/man9/bus_generic_shutdown.9 | 57 + static/freebsd/man9/bus_get_resource.9 | 93 + static/freebsd/man9/bus_map_resource.9 | 153 + static/freebsd/man9/bus_release_resource.9 | 88 + static/freebsd/man9/bus_set_pass.9 | 52 + static/freebsd/man9/bus_set_resource.9 | 90 + static/freebsd/man9/bus_space.9 | 1866 +++++++ static/freebsd/man9/byteorder.9 | 167 + static/freebsd/man9/callout.9 | 886 ++++ static/freebsd/man9/casuword.9 | 112 + static/freebsd/man9/cd.9 | 121 + static/freebsd/man9/cdefs.9 | 487 ++ static/freebsd/man9/cnv.9 | 218 + static/freebsd/man9/condvar.9 | 259 + static/freebsd/man9/config_intrhook.9 | 137 + static/freebsd/man9/contigmalloc.9 | 149 + static/freebsd/man9/copy.9 | 164 + static/freebsd/man9/coredumper_register.9 | 168 + static/freebsd/man9/counter.9 | 298 ++ static/freebsd/man9/cpu_machdep.9 | 425 ++ static/freebsd/man9/cpuset.9 | 388 ++ static/freebsd/man9/cr_bsd_visible.9 | 117 + static/freebsd/man9/cr_cansee.9 | 83 + static/freebsd/man9/cr_canseejailproc.9 | 81 + static/freebsd/man9/cr_canseeothergids.9 | 83 + static/freebsd/man9/cr_canseeotheruids.9 | 79 + static/freebsd/man9/critical_enter.9 | 101 + static/freebsd/man9/crypto.9 | 148 + static/freebsd/man9/crypto_buffer.9 | 348 ++ static/freebsd/man9/crypto_driver.9 | 337 ++ static/freebsd/man9/crypto_request.9 | 527 ++ static/freebsd/man9/crypto_session.9 | 269 + static/freebsd/man9/deadfs.9 | 36 + static/freebsd/man9/dev_clone.9 | 76 + static/freebsd/man9/dev_refthread.9 | 151 + static/freebsd/man9/devclass.9 | 68 + static/freebsd/man9/devclass_find.9 | 54 + static/freebsd/man9/devclass_get_count.9 | 45 + static/freebsd/man9/devclass_get_device.9 | 50 + static/freebsd/man9/devclass_get_devices.9 | 58 + static/freebsd/man9/devclass_get_drivers.9 | 58 + static/freebsd/man9/devclass_get_maxunit.9 | 64 + static/freebsd/man9/devclass_get_name.9 | 47 + static/freebsd/man9/devclass_get_softc.9 | 50 + static/freebsd/man9/devctl_notify.9 | 74 + static/freebsd/man9/devctl_process_running.9 | 56 + static/freebsd/man9/devctl_safe_quote_sb.9 | 53 + static/freebsd/man9/devfs_set_cdevpriv.9 | 159 + static/freebsd/man9/device.9 | 102 + static/freebsd/man9/device_add_child.9 | 132 + static/freebsd/man9/device_delete_child.9 | 67 + static/freebsd/man9/device_delete_children.9 | 56 + static/freebsd/man9/device_enable.9 | 61 + static/freebsd/man9/device_find_child.9 | 60 + static/freebsd/man9/device_get_children.9 | 91 + static/freebsd/man9/device_get_devclass.9 | 50 + static/freebsd/man9/device_get_driver.9 | 50 + static/freebsd/man9/device_get_ivars.9 | 62 + static/freebsd/man9/device_get_name.9 | 50 + static/freebsd/man9/device_get_parent.9 | 44 + static/freebsd/man9/device_get_property.9 | 90 + static/freebsd/man9/device_get_softc.9 | 67 + static/freebsd/man9/device_get_state.9 | 97 + static/freebsd/man9/device_get_sysctl.9 | 52 + static/freebsd/man9/device_get_unit.9 | 46 + static/freebsd/man9/device_printf.9 | 55 + static/freebsd/man9/device_probe_and_attach.9 | 165 + static/freebsd/man9/device_quiet.9 | 66 + static/freebsd/man9/device_set_desc.9 | 67 + static/freebsd/man9/device_set_driver.9 | 47 + static/freebsd/man9/device_set_flags.9 | 54 + static/freebsd/man9/devstat.9 | 548 ++ static/freebsd/man9/devtoname.9 | 46 + static/freebsd/man9/disk.9 | 259 + static/freebsd/man9/dnv.9 | 120 + static/freebsd/man9/domain.9 | 227 + static/freebsd/man9/domainset.9 | 179 + static/freebsd/man9/dpcpu.9 | 163 + static/freebsd/man9/drbr.9 | 138 + static/freebsd/man9/driver.9 | 117 + static/freebsd/man9/ecn.9 | 184 + static/freebsd/man9/efirt.9 | 261 + static/freebsd/man9/epoch.9 | 290 ++ static/freebsd/man9/ether_gen_addr.9 | 78 + static/freebsd/man9/eventtimers.9 | 251 + static/freebsd/man9/extattr.9 | 99 + static/freebsd/man9/exterror.9 | 230 + static/freebsd/man9/fail.9 | 283 ++ static/freebsd/man9/fdt_pinctrl.9 | 189 + static/freebsd/man9/fetch.9 | 140 + static/freebsd/man9/firmware.9 | 385 ++ static/freebsd/man9/fpu_kern.9 | 216 + static/freebsd/man9/g_access.9 | 163 + static/freebsd/man9/g_attach.9 | 141 + static/freebsd/man9/g_bio.9 | 327 ++ static/freebsd/man9/g_consumer.9 | 135 + static/freebsd/man9/g_data.9 | 122 + static/freebsd/man9/g_event.9 | 217 + static/freebsd/man9/g_geom.9 | 217 + static/freebsd/man9/g_provider.9 | 143 + static/freebsd/man9/g_provider_by_name.9 | 75 + static/freebsd/man9/g_wither_geom.9 | 84 + static/freebsd/man9/get_cyclecount.9 | 87 + static/freebsd/man9/getenv.9 | 264 + static/freebsd/man9/getnewvnode.9 | 66 + static/freebsd/man9/gone_in.9 | 92 + static/freebsd/man9/groupmember.9 | 79 + static/freebsd/man9/hardclock.9 | 116 + static/freebsd/man9/hash.9 | 226 + static/freebsd/man9/hashalloc.9 | 314 ++ static/freebsd/man9/hashinit.9 | 197 + static/freebsd/man9/hexdump.9 | 92 + static/freebsd/man9/hhook.9 | 379 ++ static/freebsd/man9/hz.9 | 159 + static/freebsd/man9/ieee80211.9 | 714 +++ static/freebsd/man9/ieee80211_amrr.9 | 192 + static/freebsd/man9/ieee80211_beacon.9 | 113 + static/freebsd/man9/ieee80211_bmiss.9 | 89 + static/freebsd/man9/ieee80211_crypto.9 | 258 + static/freebsd/man9/ieee80211_ddb.9 | 69 + static/freebsd/man9/ieee80211_input.9 | 114 + static/freebsd/man9/ieee80211_node.9 | 242 + static/freebsd/man9/ieee80211_output.9 | 192 + static/freebsd/man9/ieee80211_proto.9 | 239 + static/freebsd/man9/ieee80211_radiotap.9 | 298 ++ static/freebsd/man9/ieee80211_regdomain.9 | 141 + static/freebsd/man9/ieee80211_scan.9 | 348 ++ static/freebsd/man9/ieee80211_vap.9 | 152 + static/freebsd/man9/iflib.9 | 42 + static/freebsd/man9/iflibdd.9 | 318 ++ static/freebsd/man9/iflibdi.9 | 236 + static/freebsd/man9/iflibtxrx.9 | 239 + static/freebsd/man9/ifnet.9 | 1692 +++++++ static/freebsd/man9/inittodr.9 | 121 + static/freebsd/man9/insmntque.9 | 97 + static/freebsd/man9/intr_event.9 | 481 ++ static/freebsd/man9/intro.9 | 517 ++ static/freebsd/man9/kasan.9 | 185 + static/freebsd/man9/kern_reboot.9 | 293 ++ static/freebsd/man9/kern_testfrwk.9 | 193 + static/freebsd/man9/kern_yield.9 | 134 + static/freebsd/man9/kernacc.9 | 81 + static/freebsd/man9/kernel_mount.9 | 186 + static/freebsd/man9/khelp.9 | 435 ++ static/freebsd/man9/kmsan.9 | 357 ++ static/freebsd/man9/kobj.9 | 154 + static/freebsd/man9/kproc.9 | 393 ++ static/freebsd/man9/kqueue.9 | 438 ++ static/freebsd/man9/kstack_contains.9 | 60 + static/freebsd/man9/kthread.9 | 347 ++ static/freebsd/man9/ktr.9 | 170 + static/freebsd/man9/lock.9 | 473 ++ static/freebsd/man9/locking.9 | 437 ++ static/freebsd/man9/mac.9 | 222 + static/freebsd/man9/make_dev.9 | 499 ++ static/freebsd/man9/malloc.9 | 406 ++ static/freebsd/man9/mbchain.9 | 220 + static/freebsd/man9/mbuf.9 | 1317 +++++ static/freebsd/man9/mbuf_tags.9 | 284 ++ static/freebsd/man9/mdchain.9 | 209 + static/freebsd/man9/memcchr.9 | 57 + static/freebsd/man9/memguard.9 | 204 + static/freebsd/man9/mi_switch.9 | 174 + static/freebsd/man9/microseq.9 | 491 ++ static/freebsd/man9/microtime.9 | 119 + static/freebsd/man9/microuptime.9 | 122 + static/freebsd/man9/mod_cc.9 | 421 ++ static/freebsd/man9/module.9 | 123 + static/freebsd/man9/mtx_pool.9 | 182 + static/freebsd/man9/mutex.9 | 559 +++ static/freebsd/man9/namei.9 | 551 ++ static/freebsd/man9/netisr.9 | 226 + static/freebsd/man9/nv.9 | 1099 ++++ static/freebsd/man9/nvmem.9 | 154 + static/freebsd/man9/ofw_bus_is_compatible.9 | 144 + static/freebsd/man9/ofw_bus_status_okay.9 | 74 + static/freebsd/man9/ofw_graph.9 | 104 + static/freebsd/man9/osd.9 | 448 ++ static/freebsd/man9/owll.9 | 90 + static/freebsd/man9/own.9 | 227 + static/freebsd/man9/p_candebug.9 | 145 + static/freebsd/man9/p_cansee.9 | 79 + static/freebsd/man9/panic.9 | 157 + static/freebsd/man9/pci.9 | 1159 +++++ static/freebsd/man9/pci_iov_schema.9 | 263 + static/freebsd/man9/pfil.9 | 162 + static/freebsd/man9/pfind.9 | 91 + static/freebsd/man9/pget.9 | 105 + static/freebsd/man9/pgfind.9 | 63 + static/freebsd/man9/physio.9 | 129 + static/freebsd/man9/pmap.9 | 125 + static/freebsd/man9/pmap_activate.9 | 49 + static/freebsd/man9/pmap_clear_modify.9 | 50 + static/freebsd/man9/pmap_copy.9 | 82 + static/freebsd/man9/pmap_enter.9 | 170 + static/freebsd/man9/pmap_extract.9 | 95 + static/freebsd/man9/pmap_growkernel.9 | 49 + static/freebsd/man9/pmap_init.9 | 53 + static/freebsd/man9/pmap_is_modified.9 | 68 + static/freebsd/man9/pmap_is_prefaultable.9 | 55 + static/freebsd/man9/pmap_kextract.9 | 77 + static/freebsd/man9/pmap_map.9 | 78 + static/freebsd/man9/pmap_mincore.9 | 72 + static/freebsd/man9/pmap_object_init_pt.9 | 71 + static/freebsd/man9/pmap_page_exists_quick.9 | 64 + static/freebsd/man9/pmap_page_init.9 | 49 + static/freebsd/man9/pmap_pinit.9 | 60 + static/freebsd/man9/pmap_protect.9 | 55 + static/freebsd/man9/pmap_qenter.9 | 79 + static/freebsd/man9/pmap_quick_enter_page.9 | 101 + static/freebsd/man9/pmap_release.9 | 56 + static/freebsd/man9/pmap_remove.9 | 82 + static/freebsd/man9/pmap_resident_count.9 | 72 + static/freebsd/man9/pmap_unwire.9 | 63 + static/freebsd/man9/pmap_zero_page.9 | 58 + static/freebsd/man9/printf.9 | 197 + static/freebsd/man9/prison_check.9 | 59 + static/freebsd/man9/priv.9 | 118 + static/freebsd/man9/prng.9 | 96 + static/freebsd/man9/proc_rwmem.9 | 102 + static/freebsd/man9/pseudofs.9 | 68 + static/freebsd/man9/psignal.9 | 143 + static/freebsd/man9/pwmbus.9 | 111 + static/freebsd/man9/random.9 | 203 + static/freebsd/man9/random_harvest.9 | 130 + static/freebsd/man9/ratecheck.9 | 91 + static/freebsd/man9/redzone.9 | 123 + static/freebsd/man9/refcount.9 | 194 + static/freebsd/man9/regulator.9 | 147 + static/freebsd/man9/resettodr.9 | 60 + static/freebsd/man9/resource_int_value.9 | 73 + static/freebsd/man9/rijndael.9 | 133 + static/freebsd/man9/rman.9 | 471 ++ static/freebsd/man9/rmlock.9 | 382 ++ static/freebsd/man9/rtentry.9 | 249 + static/freebsd/man9/runqueue.9 | 134 + static/freebsd/man9/rwlock.9 | 335 ++ static/freebsd/man9/sbuf.9 | 769 +++ static/freebsd/man9/scheduler.9 | 273 + static/freebsd/man9/securelevel_gt.9 | 70 + static/freebsd/man9/selrecord.9 | 124 + static/freebsd/man9/sema.9 | 130 + static/freebsd/man9/seqc.9 | 137 + static/freebsd/man9/sf_buf.9 | 140 + static/freebsd/man9/sglist.9 | 612 +++ static/freebsd/man9/shm_map.9 | 184 + static/freebsd/man9/signal.9 | 435 ++ static/freebsd/man9/sleep.9 | 421 ++ static/freebsd/man9/sleepqueue.9 | 388 ++ static/freebsd/man9/smr.9 | 294 ++ static/freebsd/man9/socket.9 | 643 +++ static/freebsd/man9/stack.9 | 184 + static/freebsd/man9/store.9 | 92 + static/freebsd/man9/style.9 | 1119 +++++ static/freebsd/man9/style.lua.9 | 124 + static/freebsd/man9/superio.9 | 187 + static/freebsd/man9/swi.9 | 231 + static/freebsd/man9/sx.9 | 336 ++ static/freebsd/man9/syscall_helper_register.9 | 137 + static/freebsd/man9/sysctl.9 | 1119 +++++ static/freebsd/man9/sysctl_add_oid.9 | 201 + static/freebsd/man9/sysctl_ctx_init.9 | 245 + static/freebsd/man9/taskqueue.9 | 542 ++ static/freebsd/man9/tcp_functions.9 | 392 ++ static/freebsd/man9/thread_exit.9 | 61 + static/freebsd/man9/time.9 | 125 + static/freebsd/man9/tvtohz.9 | 56 + static/freebsd/man9/ucred.9 | 224 + static/freebsd/man9/uidinfo.9 | 107 + static/freebsd/man9/uio.9 | 239 + static/freebsd/man9/unr.9 | 191 + static/freebsd/man9/usbdi.9 | 630 +++ static/freebsd/man9/vaccess.9 | 115 + static/freebsd/man9/vaccess_acl_nfs4.9 | 127 + static/freebsd/man9/vaccess_acl_posix1e.9 | 126 + static/freebsd/man9/vflush.9 | 79 + static/freebsd/man9/vfs_busy.9 | 89 + static/freebsd/man9/vfs_getnewfsid.9 | 75 + static/freebsd/man9/vfs_getopt.9 | 243 + static/freebsd/man9/vfs_getvfs.9 | 75 + static/freebsd/man9/vfs_mountedfrom.9 | 53 + static/freebsd/man9/vfs_rootmountalloc.9 | 64 + static/freebsd/man9/vfs_suser.9 | 70 + static/freebsd/man9/vfs_timestamp.9 | 61 + static/freebsd/man9/vfs_unbusy.9 | 56 + static/freebsd/man9/vfs_unmountall.9 | 45 + static/freebsd/man9/vfsconf.9 | 149 + static/freebsd/man9/vget.9 | 69 + static/freebsd/man9/vgone.9 | 61 + static/freebsd/man9/vhold.9 | 81 + static/freebsd/man9/vinvalbuf.9 | 115 + static/freebsd/man9/vm_fault_prefault.9 | 70 + static/freebsd/man9/vm_map.9 | 332 ++ static/freebsd/man9/vm_map_check_protection.9 | 68 + static/freebsd/man9/vm_map_delete.9 | 66 + static/freebsd/man9/vm_map_entry_resize_free.9 | 241 + static/freebsd/man9/vm_map_find.9 | 159 + static/freebsd/man9/vm_map_findspace.9 | 76 + static/freebsd/man9/vm_map_inherit.9 | 83 + static/freebsd/man9/vm_map_init.9 | 57 + static/freebsd/man9/vm_map_insert.9 | 91 + static/freebsd/man9/vm_map_lock.9 | 111 + static/freebsd/man9/vm_map_lookup.9 | 86 + static/freebsd/man9/vm_map_madvise.9 | 75 + static/freebsd/man9/vm_map_max.9 | 64 + static/freebsd/man9/vm_map_protect.9 | 137 + static/freebsd/man9/vm_map_remove.9 | 67 + static/freebsd/man9/vm_map_stack.9 | 130 + static/freebsd/man9/vm_map_submap.9 | 93 + static/freebsd/man9/vm_map_sync.9 | 79 + static/freebsd/man9/vm_map_wire.9 | 112 + static/freebsd/man9/vm_page_aflag.9 | 98 + static/freebsd/man9/vm_page_alloc.9 | 338 ++ static/freebsd/man9/vm_page_bits.9 | 165 + static/freebsd/man9/vm_page_busy.9 | 198 + static/freebsd/man9/vm_page_deactivate.9 | 48 + static/freebsd/man9/vm_page_dontneed.9 | 57 + static/freebsd/man9/vm_page_free.9 | 96 + static/freebsd/man9/vm_page_grab.9 | 82 + static/freebsd/man9/vm_page_insert.9 | 94 + static/freebsd/man9/vm_page_lookup.9 | 61 + static/freebsd/man9/vm_page_rename.9 | 70 + static/freebsd/man9/vm_page_wire.9 | 81 + static/freebsd/man9/vm_set_page_size.9 | 60 + static/freebsd/man9/vmem.9 | 316 ++ static/freebsd/man9/vn_deallocate.9 | 113 + static/freebsd/man9/vn_fullpath.9 | 196 + static/freebsd/man9/vn_isdisk.9 | 75 + static/freebsd/man9/vnode.9 | 219 + static/freebsd/man9/vnode_pager_purge_range.9 | 85 + static/freebsd/man9/vnode_pager_setsize.9 | 79 + static/freebsd/man9/vref.9 | 75 + static/freebsd/man9/vrefcnt.9 | 51 + static/freebsd/man9/vrele.9 | 101 + static/freebsd/man9/vslock.9 | 86 + static/freebsd/man9/watchdog.9 | 79 + static/freebsd/man9/zero_region.9 | 84 + static/freebsd/man9/zone.9 | 639 +++ 1490 files changed, 291009 insertions(+), 1 deletion(-) create mode 100644 static/freebsd/Makefile create mode 100644 static/freebsd/man1/Makefile create mode 100644 static/freebsd/man1/builtin.1 create mode 100644 static/freebsd/man1/intro.1 create mode 100644 static/freebsd/man3/ATOMIC_VAR_INIT.3 create mode 100644 static/freebsd/man3/CMSG_DATA.3 create mode 100644 static/freebsd/man3/Makefile create mode 100644 static/freebsd/man3/Q_FRAWMASK.3 create mode 100644 static/freebsd/man3/Q_IFRAWMASK.3 create mode 100644 static/freebsd/man3/Q_INI.3 create mode 100644 static/freebsd/man3/Q_IRAWMASK.3 create mode 100644 static/freebsd/man3/Q_QABS.3 create mode 100644 static/freebsd/man3/Q_QADDI.3 create mode 100644 static/freebsd/man3/Q_QADDQ.3 create mode 100644 static/freebsd/man3/Q_SIGNED.3 create mode 100644 static/freebsd/man3/Q_SIGNSHFT.3 create mode 100644 static/freebsd/man3/alloca.3 create mode 100644 static/freebsd/man3/arb.3 create mode 100644 static/freebsd/man3/assert.3 create mode 100644 static/freebsd/man3/bitstring.3 create mode 100644 static/freebsd/man3/end.3 create mode 100644 static/freebsd/man3/fpgetround.3 create mode 100644 static/freebsd/man3/intro.3 create mode 100644 static/freebsd/man3/makedev.3 create mode 100644 static/freebsd/man3/offsetof.3 create mode 100644 static/freebsd/man3/pthread.3 create mode 100644 static/freebsd/man3/pthread_affinity_np.3 create mode 100644 static/freebsd/man3/pthread_atfork.3 create mode 100644 static/freebsd/man3/pthread_attr.3 create mode 100644 static/freebsd/man3/pthread_attr_affinity_np.3 create mode 100644 static/freebsd/man3/pthread_attr_get_np.3 create mode 100644 static/freebsd/man3/pthread_attr_setcreatesuspend_np.3 create mode 100644 static/freebsd/man3/pthread_barrier_destroy.3 create mode 100644 static/freebsd/man3/pthread_barrierattr.3 create mode 100644 static/freebsd/man3/pthread_cancel.3 create mode 100644 static/freebsd/man3/pthread_cleanup_pop.3 create mode 100644 static/freebsd/man3/pthread_cleanup_push.3 create mode 100644 static/freebsd/man3/pthread_cond_broadcast.3 create mode 100644 static/freebsd/man3/pthread_cond_destroy.3 create mode 100644 static/freebsd/man3/pthread_cond_init.3 create mode 100644 static/freebsd/man3/pthread_cond_signal.3 create mode 100644 static/freebsd/man3/pthread_cond_timedwait.3 create mode 100644 static/freebsd/man3/pthread_cond_wait.3 create mode 100644 static/freebsd/man3/pthread_condattr.3 create mode 100644 static/freebsd/man3/pthread_create.3 create mode 100644 static/freebsd/man3/pthread_detach.3 create mode 100644 static/freebsd/man3/pthread_equal.3 create mode 100644 static/freebsd/man3/pthread_exit.3 create mode 100644 static/freebsd/man3/pthread_getconcurrency.3 create mode 100644 static/freebsd/man3/pthread_getcpuclockid.3 create mode 100644 static/freebsd/man3/pthread_getspecific.3 create mode 100644 static/freebsd/man3/pthread_getthreadid_np.3 create mode 100644 static/freebsd/man3/pthread_join.3 create mode 100644 static/freebsd/man3/pthread_key_create.3 create mode 100644 static/freebsd/man3/pthread_key_delete.3 create mode 100644 static/freebsd/man3/pthread_kill.3 create mode 100644 static/freebsd/man3/pthread_main_np.3 create mode 100644 static/freebsd/man3/pthread_multi_np.3 create mode 100644 static/freebsd/man3/pthread_mutex_consistent.3 create mode 100644 static/freebsd/man3/pthread_mutex_destroy.3 create mode 100644 static/freebsd/man3/pthread_mutex_init.3 create mode 100644 static/freebsd/man3/pthread_mutex_lock.3 create mode 100644 static/freebsd/man3/pthread_mutex_timedlock.3 create mode 100644 static/freebsd/man3/pthread_mutex_trylock.3 create mode 100644 static/freebsd/man3/pthread_mutex_unlock.3 create mode 100644 static/freebsd/man3/pthread_mutexattr.3 create mode 100644 static/freebsd/man3/pthread_mutexattr_getkind_np.3 create mode 100644 static/freebsd/man3/pthread_np.3 create mode 100644 static/freebsd/man3/pthread_once.3 create mode 100644 static/freebsd/man3/pthread_resume_all_np.3 create mode 100644 static/freebsd/man3/pthread_resume_np.3 create mode 100644 static/freebsd/man3/pthread_rwlock_destroy.3 create mode 100644 static/freebsd/man3/pthread_rwlock_init.3 create mode 100644 static/freebsd/man3/pthread_rwlock_rdlock.3 create mode 100644 static/freebsd/man3/pthread_rwlock_timedrdlock.3 create mode 100644 static/freebsd/man3/pthread_rwlock_timedwrlock.3 create mode 100644 static/freebsd/man3/pthread_rwlock_unlock.3 create mode 100644 static/freebsd/man3/pthread_rwlock_wrlock.3 create mode 100644 static/freebsd/man3/pthread_rwlockattr_destroy.3 create mode 100644 static/freebsd/man3/pthread_rwlockattr_getpshared.3 create mode 100644 static/freebsd/man3/pthread_rwlockattr_init.3 create mode 100644 static/freebsd/man3/pthread_rwlockattr_setpshared.3 create mode 100644 static/freebsd/man3/pthread_schedparam.3 create mode 100644 static/freebsd/man3/pthread_self.3 create mode 100644 static/freebsd/man3/pthread_set_name_np.3 create mode 100644 static/freebsd/man3/pthread_setspecific.3 create mode 100644 static/freebsd/man3/pthread_sigmask.3 create mode 100644 static/freebsd/man3/pthread_signals_block_np.3 create mode 100644 static/freebsd/man3/pthread_sigqueue.3 create mode 100644 static/freebsd/man3/pthread_spin_init.3 create mode 100644 static/freebsd/man3/pthread_spin_lock.3 create mode 100644 static/freebsd/man3/pthread_suspend_all_np.3 create mode 100644 static/freebsd/man3/pthread_suspend_np.3 create mode 100644 static/freebsd/man3/pthread_testcancel.3 create mode 100644 static/freebsd/man3/pthread_yield.3 create mode 100644 static/freebsd/man3/qmath.3 create mode 100644 static/freebsd/man3/queue.3 create mode 100644 static/freebsd/man3/sigevent.3 create mode 100644 static/freebsd/man3/siginfo.3 create mode 100644 static/freebsd/man3/snl.3 create mode 100644 static/freebsd/man3/stats.3 create mode 100644 static/freebsd/man3/stdarg.3 create mode 100644 static/freebsd/man3/stdbit.3 create mode 100644 static/freebsd/man3/stdckdint.3 create mode 100644 static/freebsd/man3/sysexits.3 create mode 100644 static/freebsd/man3/tgmath.3 create mode 100644 static/freebsd/man3/timeradd.3 create mode 100644 static/freebsd/man3/tree.3 create mode 100644 static/freebsd/man3lua/Makefile create mode 100644 static/freebsd/man3lua/intro.3lua create mode 100644 static/freebsd/man4/Makefile create mode 100644 static/freebsd/man4/aac.4 create mode 100644 static/freebsd/man4/aacraid.4 create mode 100644 static/freebsd/man4/acpi.4 create mode 100644 static/freebsd/man4/acpi_asus.4 create mode 100644 static/freebsd/man4/acpi_asus_wmi.4 create mode 100644 static/freebsd/man4/acpi_battery.4 create mode 100644 static/freebsd/man4/acpi_dock.4 create mode 100644 static/freebsd/man4/acpi_fujitsu.4 create mode 100644 static/freebsd/man4/acpi_ged.4 create mode 100644 static/freebsd/man4/acpi_hp.4 create mode 100644 static/freebsd/man4/acpi_ibm.4 create mode 100644 static/freebsd/man4/acpi_panasonic.4 create mode 100644 static/freebsd/man4/acpi_rapidstart.4 create mode 100644 static/freebsd/man4/acpi_sony.4 create mode 100644 static/freebsd/man4/acpi_thermal.4 create mode 100644 static/freebsd/man4/acpi_toshiba.4 create mode 100644 static/freebsd/man4/acpi_video.4 create mode 100644 static/freebsd/man4/acpi_wmi.4 create mode 100644 static/freebsd/man4/ada.4 create mode 100644 static/freebsd/man4/adm6996fc.4 create mode 100644 static/freebsd/man4/ads111x.4 create mode 100644 static/freebsd/man4/ae.4 create mode 100644 static/freebsd/man4/aesni.4 create mode 100644 static/freebsd/man4/age.4 create mode 100644 static/freebsd/man4/agp.4 create mode 100644 static/freebsd/man4/ahc.4 create mode 100644 static/freebsd/man4/ahci.4 create mode 100644 static/freebsd/man4/ahd.4 create mode 100644 static/freebsd/man4/aibs.4 create mode 100644 static/freebsd/man4/aio.4 create mode 100644 static/freebsd/man4/alc.4 create mode 100644 static/freebsd/man4/ale.4 create mode 100644 static/freebsd/man4/alpm.4 create mode 100644 static/freebsd/man4/altq.4 create mode 100644 static/freebsd/man4/amdpm.4 create mode 100644 static/freebsd/man4/amdsbwd.4 create mode 100644 static/freebsd/man4/amdsmb.4 create mode 100644 static/freebsd/man4/amdsmn.4 create mode 100644 static/freebsd/man4/amdtemp.4 create mode 100644 static/freebsd/man4/aout.4 create mode 100644 static/freebsd/man4/apic.4 create mode 100644 static/freebsd/man4/appleir.4 create mode 100644 static/freebsd/man4/aq.4 create mode 100644 static/freebsd/man4/arcmsr.4 create mode 100644 static/freebsd/man4/arswitch.4 create mode 100644 static/freebsd/man4/asmc.4 create mode 100644 static/freebsd/man4/at45d.4 create mode 100644 static/freebsd/man4/ata.4 create mode 100644 static/freebsd/man4/ath.4 create mode 100644 static/freebsd/man4/ath10k.4 create mode 100644 static/freebsd/man4/ath_hal.4 create mode 100644 static/freebsd/man4/atkbd.4 create mode 100644 static/freebsd/man4/atkbdc.4 create mode 100644 static/freebsd/man4/atopcase.4 create mode 100644 static/freebsd/man4/atp.4 create mode 100644 static/freebsd/man4/atrtc.4 create mode 100644 static/freebsd/man4/attimer.4 create mode 100644 static/freebsd/man4/audit.4 create mode 100644 static/freebsd/man4/auditpipe.4 create mode 100644 static/freebsd/man4/aue.4 create mode 100644 static/freebsd/man4/autofs.4 create mode 100644 static/freebsd/man4/aw_gpio.4 create mode 100644 static/freebsd/man4/aw_mmc.4 create mode 100644 static/freebsd/man4/aw_rtc.4 create mode 100644 static/freebsd/man4/aw_sid.4 create mode 100644 static/freebsd/man4/aw_spi.4 create mode 100644 static/freebsd/man4/aw_syscon.4 create mode 100644 static/freebsd/man4/axe.4 create mode 100644 static/freebsd/man4/axge.4 create mode 100644 static/freebsd/man4/axp.4 create mode 100644 static/freebsd/man4/bce.4 create mode 100644 static/freebsd/man4/bcm5974.4 create mode 100644 static/freebsd/man4/bcma.4 create mode 100644 static/freebsd/man4/bfe.4 create mode 100644 static/freebsd/man4/bge.4 create mode 100644 static/freebsd/man4/bhnd.4 create mode 100644 static/freebsd/man4/bhnd_chipc.4 create mode 100644 static/freebsd/man4/bhnd_pmu.4 create mode 100644 static/freebsd/man4/bhndb.4 create mode 100644 static/freebsd/man4/bhndb_pci.4 create mode 100644 static/freebsd/man4/bhyve.4 create mode 100644 static/freebsd/man4/blackhole.4 create mode 100644 static/freebsd/man4/bnxt.4 create mode 100644 static/freebsd/man4/bnxt_re.4 create mode 100644 static/freebsd/man4/boottrace.4 create mode 100644 static/freebsd/man4/bpf.4 create mode 100644 static/freebsd/man4/bridge.4 create mode 100644 static/freebsd/man4/bwi.4 create mode 100644 static/freebsd/man4/bwn.4 create mode 100644 static/freebsd/man4/bxe.4 create mode 100644 static/freebsd/man4/bytgpio.4 create mode 100644 static/freebsd/man4/capsicum.4 create mode 100644 static/freebsd/man4/cardbus.4 create mode 100644 static/freebsd/man4/carp.4 create mode 100644 static/freebsd/man4/cas.4 create mode 100644 static/freebsd/man4/cc_cdg.4 create mode 100644 static/freebsd/man4/cc_chd.4 create mode 100644 static/freebsd/man4/cc_cubic.4 create mode 100644 static/freebsd/man4/cc_dctcp.4 create mode 100644 static/freebsd/man4/cc_hd.4 create mode 100644 static/freebsd/man4/cc_htcp.4 create mode 100644 static/freebsd/man4/cc_newreno.4 create mode 100644 static/freebsd/man4/cc_vegas.4 create mode 100644 static/freebsd/man4/ccd.4 create mode 100644 static/freebsd/man4/ccr.4 create mode 100644 static/freebsd/man4/cd.4 create mode 100644 static/freebsd/man4/cd9660.4 create mode 100644 static/freebsd/man4/cdce.4 create mode 100644 static/freebsd/man4/cdceem.4 create mode 100644 static/freebsd/man4/cfi.4 create mode 100644 static/freebsd/man4/cfiscsi.4 create mode 100644 static/freebsd/man4/cfumass.4 create mode 100644 static/freebsd/man4/cgem.4 create mode 100644 static/freebsd/man4/ch.4 create mode 100644 static/freebsd/man4/chromebook_platform.4 create mode 100644 static/freebsd/man4/chvgpio.4 create mode 100644 static/freebsd/man4/ciss.4 create mode 100644 static/freebsd/man4/coretemp.4 create mode 100644 static/freebsd/man4/cp2112.4 create mode 100644 static/freebsd/man4/cpuctl.4 create mode 100644 static/freebsd/man4/cpufreq.4 create mode 100644 static/freebsd/man4/crypto.4 create mode 100644 static/freebsd/man4/ctl.4 create mode 100644 static/freebsd/man4/cue.4 create mode 100644 static/freebsd/man4/cxgb.4 create mode 100644 static/freebsd/man4/cxgbe.4 create mode 100644 static/freebsd/man4/cxgbev.4 create mode 100644 static/freebsd/man4/cyapa.4 create mode 100644 static/freebsd/man4/da.4 create mode 100644 static/freebsd/man4/dc.4 create mode 100644 static/freebsd/man4/dcons.4 create mode 100644 static/freebsd/man4/dcons_crom.4 create mode 100644 static/freebsd/man4/ddb.4 create mode 100644 static/freebsd/man4/devctl.4 create mode 100644 static/freebsd/man4/devfs.4 create mode 100644 static/freebsd/man4/disc.4 create mode 100644 static/freebsd/man4/disk.4 create mode 100644 static/freebsd/man4/divert.4 create mode 100644 static/freebsd/man4/dpms.4 create mode 100644 static/freebsd/man4/ds1307.4 create mode 100644 static/freebsd/man4/ds3231.4 create mode 100644 static/freebsd/man4/dtrace_audit.4 create mode 100644 static/freebsd/man4/dtrace_callout_execute.4 create mode 100644 static/freebsd/man4/dtrace_cam.4 create mode 100644 static/freebsd/man4/dtrace_dtrace.4 create mode 100644 static/freebsd/man4/dtrace_fbt.4 create mode 100644 static/freebsd/man4/dtrace_io.4 create mode 100644 static/freebsd/man4/dtrace_ip.4 create mode 100644 static/freebsd/man4/dtrace_kinst.4 create mode 100644 static/freebsd/man4/dtrace_lockstat.4 create mode 100644 static/freebsd/man4/dtrace_pid.4 create mode 100644 static/freebsd/man4/dtrace_priv.4 create mode 100644 static/freebsd/man4/dtrace_proc.4 create mode 100644 static/freebsd/man4/dtrace_profile.4 create mode 100644 static/freebsd/man4/dtrace_sched.4 create mode 100644 static/freebsd/man4/dtrace_sctp.4 create mode 100644 static/freebsd/man4/dtrace_tcp.4 create mode 100644 static/freebsd/man4/dtrace_udp.4 create mode 100644 static/freebsd/man4/dtrace_udplite.4 create mode 100644 static/freebsd/man4/dtrace_vfs.4 create mode 100644 static/freebsd/man4/dummymbuf.4 create mode 100644 static/freebsd/man4/dummynet.4 create mode 100644 static/freebsd/man4/e6000sw.4 create mode 100644 static/freebsd/man4/e6060sw.4 create mode 100644 static/freebsd/man4/edsc.4 create mode 100644 static/freebsd/man4/efidev.4 create mode 100644 static/freebsd/man4/ehci.4 create mode 100644 static/freebsd/man4/em.4 create mode 100644 static/freebsd/man4/ena.4 create mode 100644 static/freebsd/man4/enc.4 create mode 100644 static/freebsd/man4/enic.4 create mode 100644 static/freebsd/man4/epair.4 create mode 100644 static/freebsd/man4/est.4 create mode 100644 static/freebsd/man4/et.4 create mode 100644 static/freebsd/man4/etherswitch.4 create mode 100644 static/freebsd/man4/eventtimers.4 create mode 100644 static/freebsd/man4/exca.4 create mode 100644 static/freebsd/man4/ext2fs.4 create mode 100644 static/freebsd/man4/fd.4 create mode 100644 static/freebsd/man4/fdc.4 create mode 100644 static/freebsd/man4/fdescfs.4 create mode 100644 static/freebsd/man4/fdt.4 create mode 100644 static/freebsd/man4/fdt_pinctrl.4 create mode 100644 static/freebsd/man4/fdtbus.4 create mode 100644 static/freebsd/man4/ffclock.4 create mode 100644 static/freebsd/man4/ffs.4 create mode 100644 static/freebsd/man4/filemon.4 create mode 100644 static/freebsd/man4/firewire.4 create mode 100644 static/freebsd/man4/ftgpio.4 create mode 100644 static/freebsd/man4/ftwd.4 create mode 100644 static/freebsd/man4/full.4 create mode 100644 static/freebsd/man4/fusefs.4 create mode 100644 static/freebsd/man4/fwe.4 create mode 100644 static/freebsd/man4/fwip.4 create mode 100644 static/freebsd/man4/fwohci.4 create mode 100644 static/freebsd/man4/fxp.4 create mode 100644 static/freebsd/man4/gdb.4 create mode 100644 static/freebsd/man4/gem.4 create mode 100644 static/freebsd/man4/genet.4 create mode 100644 static/freebsd/man4/genetlink.4 create mode 100644 static/freebsd/man4/geneve.4 create mode 100644 static/freebsd/man4/geom.4 create mode 100644 static/freebsd/man4/geom_linux_lvm.4 create mode 100644 static/freebsd/man4/geom_uzip.4 create mode 100644 static/freebsd/man4/geom_zero.4 create mode 100644 static/freebsd/man4/gif.4 create mode 100644 static/freebsd/man4/gpio.4 create mode 100644 static/freebsd/man4/gpioiic.4 create mode 100644 static/freebsd/man4/gpiokeys.4 create mode 100644 static/freebsd/man4/gpioled.4 create mode 100644 static/freebsd/man4/gpioths.4 create mode 100644 static/freebsd/man4/gre.4 create mode 100644 static/freebsd/man4/gve.4 create mode 100644 static/freebsd/man4/h_ertt.4 create mode 100644 static/freebsd/man4/hconf.4 create mode 100644 static/freebsd/man4/hcons.4 create mode 100644 static/freebsd/man4/hgame.4 create mode 100644 static/freebsd/man4/hidbus.4 create mode 100644 static/freebsd/man4/hidquirk.4 create mode 100644 static/freebsd/man4/hidraw.4 create mode 100644 static/freebsd/man4/hkbd.4 create mode 100644 static/freebsd/man4/hms.4 create mode 100644 static/freebsd/man4/hmt.4 create mode 100644 static/freebsd/man4/hpen.4 create mode 100644 static/freebsd/man4/hpet.4 create mode 100644 static/freebsd/man4/hpt27xx.4 create mode 100644 static/freebsd/man4/hptiop.4 create mode 100644 static/freebsd/man4/hptmv.4 create mode 100644 static/freebsd/man4/hptnr.4 create mode 100644 static/freebsd/man4/hptrr.4 create mode 100644 static/freebsd/man4/hsctrl.4 create mode 100644 static/freebsd/man4/htu21.4 create mode 100644 static/freebsd/man4/hv_kvp.4 create mode 100644 static/freebsd/man4/hv_netvsc.4 create mode 100644 static/freebsd/man4/hv_storvsc.4 create mode 100644 static/freebsd/man4/hv_utils.4 create mode 100644 static/freebsd/man4/hv_vmbus.4 create mode 100644 static/freebsd/man4/hv_vss.4 create mode 100644 static/freebsd/man4/hwpmc.4 create mode 100644 static/freebsd/man4/hwpstate_intel.4 create mode 100644 static/freebsd/man4/hwt.4 create mode 100644 static/freebsd/man4/i2ctinyusb.4 create mode 100644 static/freebsd/man4/iavf.4 create mode 100644 static/freebsd/man4/ice.4 create mode 100644 static/freebsd/man4/ichsmb.4 create mode 100644 static/freebsd/man4/ichwd.4 create mode 100644 static/freebsd/man4/icmp.4 create mode 100644 static/freebsd/man4/icmp6.4 create mode 100644 static/freebsd/man4/ida.4 create mode 100644 static/freebsd/man4/ietp.4 create mode 100644 static/freebsd/man4/if_ipsec.4 create mode 100644 static/freebsd/man4/if_ntb.4 create mode 100644 static/freebsd/man4/iflib.4 create mode 100644 static/freebsd/man4/ifmib.4 create mode 100644 static/freebsd/man4/ig4.4 create mode 100644 static/freebsd/man4/igc.4 create mode 100644 static/freebsd/man4/igmp.4 create mode 100644 static/freebsd/man4/iic.4 create mode 100644 static/freebsd/man4/iic_gpiomux.4 create mode 100644 static/freebsd/man4/iicbb.4 create mode 100644 static/freebsd/man4/iicbus.4 create mode 100644 static/freebsd/man4/iichid.4 create mode 100644 static/freebsd/man4/iicmux.4 create mode 100644 static/freebsd/man4/iicsmb.4 create mode 100644 static/freebsd/man4/imcsmb.4 create mode 100644 static/freebsd/man4/inet.4 create mode 100644 static/freebsd/man4/inet6.4 create mode 100644 static/freebsd/man4/intpm.4 create mode 100644 static/freebsd/man4/intro.4 create mode 100644 static/freebsd/man4/io.4 create mode 100644 static/freebsd/man4/ioat.4 create mode 100644 static/freebsd/man4/ip.4 create mode 100644 static/freebsd/man4/ip17x.4 create mode 100644 static/freebsd/man4/ip6.4 create mode 100644 static/freebsd/man4/ipfirewall.4 create mode 100644 static/freebsd/man4/ipheth.4 create mode 100644 static/freebsd/man4/ipmi.4 create mode 100644 static/freebsd/man4/ips.4 create mode 100644 static/freebsd/man4/ipsec.4 create mode 100644 static/freebsd/man4/ipw.4 create mode 100644 static/freebsd/man4/ipwfw.4 create mode 100644 static/freebsd/man4/irdma.4 create mode 100644 static/freebsd/man4/isci.4 create mode 100644 static/freebsd/man4/iscsi.4 create mode 100644 static/freebsd/man4/iser.4 create mode 100644 static/freebsd/man4/isl.4 create mode 100644 static/freebsd/man4/ismt.4 create mode 100644 static/freebsd/man4/isp.4 create mode 100644 static/freebsd/man4/ispfw.4 create mode 100644 static/freebsd/man4/itwd.4 create mode 100644 static/freebsd/man4/iwi.4 create mode 100644 static/freebsd/man4/iwifw.4 create mode 100644 static/freebsd/man4/iwlwifi.4 create mode 100644 static/freebsd/man4/iwlwififw.4 create mode 100644 static/freebsd/man4/iwm.4 create mode 100644 static/freebsd/man4/iwmfw.4 create mode 100644 static/freebsd/man4/iwn.4 create mode 100644 static/freebsd/man4/iwnfw.4 create mode 100644 static/freebsd/man4/iwx.4 create mode 100644 static/freebsd/man4/ix.4 create mode 100644 static/freebsd/man4/ixl.4 create mode 100644 static/freebsd/man4/jedec_dimm.4 create mode 100644 static/freebsd/man4/jme.4 create mode 100644 static/freebsd/man4/kbdmux.4 create mode 100644 static/freebsd/man4/kcov.4 create mode 100644 static/freebsd/man4/keyboard.4 create mode 100644 static/freebsd/man4/kld.4 create mode 100644 static/freebsd/man4/ksyms.4 create mode 100644 static/freebsd/man4/ksz8995ma.4 create mode 100644 static/freebsd/man4/ktls.4 create mode 100644 static/freebsd/man4/ktr.4 create mode 100644 static/freebsd/man4/kue.4 create mode 100644 static/freebsd/man4/kvmclock.4 create mode 100644 static/freebsd/man4/lagg.4 create mode 100644 static/freebsd/man4/led.4 create mode 100644 static/freebsd/man4/lge.4 create mode 100644 static/freebsd/man4/lindebugfs.4 create mode 100644 static/freebsd/man4/linprocfs.4 create mode 100644 static/freebsd/man4/linsysfs.4 create mode 100644 static/freebsd/man4/linux.4 create mode 100644 static/freebsd/man4/linuxkpi.4 create mode 100644 static/freebsd/man4/linuxkpi_wlan.4 create mode 100644 static/freebsd/man4/liquidio.4 create mode 100644 static/freebsd/man4/lm75.4 create mode 100644 static/freebsd/man4/lo.4 create mode 100644 static/freebsd/man4/lp.4 create mode 100644 static/freebsd/man4/lpbb.4 create mode 100644 static/freebsd/man4/lpt.4 create mode 100644 static/freebsd/man4/ltc430x.4 create mode 100644 static/freebsd/man4/mac.4 create mode 100644 static/freebsd/man4/mac_biba.4 create mode 100644 static/freebsd/man4/mac_bsdextended.4 create mode 100644 static/freebsd/man4/mac_ddb.4 create mode 100644 static/freebsd/man4/mac_do.4 create mode 100644 static/freebsd/man4/mac_ifoff.4 create mode 100644 static/freebsd/man4/mac_ipacl.4 create mode 100644 static/freebsd/man4/mac_lomac.4 create mode 100644 static/freebsd/man4/mac_mls.4 create mode 100644 static/freebsd/man4/mac_none.4 create mode 100644 static/freebsd/man4/mac_ntpd.4 create mode 100644 static/freebsd/man4/mac_partition.4 create mode 100644 static/freebsd/man4/mac_portacl.4 create mode 100644 static/freebsd/man4/mac_priority.4 create mode 100644 static/freebsd/man4/mac_seeotheruids.4 create mode 100644 static/freebsd/man4/mac_stub.4 create mode 100644 static/freebsd/man4/mac_test.4 create mode 100644 static/freebsd/man4/malo.4 create mode 100644 static/freebsd/man4/man4.aarch64/Makefile create mode 100644 static/freebsd/man4/man4.aarch64/armv8crypto.4 create mode 100644 static/freebsd/man4/man4.aarch64/enetc.4 create mode 100644 static/freebsd/man4/man4.aarch64/felix.4 create mode 100644 static/freebsd/man4/man4.aarch64/rk_gpio.4 create mode 100644 static/freebsd/man4/man4.aarch64/rk_grf.4 create mode 100644 static/freebsd/man4/man4.aarch64/rk_grf_gpio.4 create mode 100644 static/freebsd/man4/man4.aarch64/rk_i2c.4 create mode 100644 static/freebsd/man4/man4.aarch64/rk_pinctrl.4 create mode 100644 static/freebsd/man4/man4.arm/Makefile create mode 100644 static/freebsd/man4/man4.arm/am335x_dmtpps.4 create mode 100644 static/freebsd/man4/man4.arm/ar40xx.4 create mode 100644 static/freebsd/man4/man4.arm/bcm283x_pwm.4 create mode 100644 static/freebsd/man4/man4.arm/devcfg.4 create mode 100644 static/freebsd/man4/man4.arm/dwcotg.4 create mode 100644 static/freebsd/man4/man4.arm/imx6_ahci.4 create mode 100644 static/freebsd/man4/man4.arm/imx6_snvs.4 create mode 100644 static/freebsd/man4/man4.arm/imx_spi.4 create mode 100644 static/freebsd/man4/man4.arm/imx_wdog.4 create mode 100644 static/freebsd/man4/man4.arm/mge.4 create mode 100644 static/freebsd/man4/man4.arm/ti_adc.4 create mode 100644 static/freebsd/man4/man4.i386/CPU_ELAN.4 create mode 100644 static/freebsd/man4/man4.i386/Makefile create mode 100644 static/freebsd/man4/man4.i386/apm.4 create mode 100644 static/freebsd/man4/man4.i386/glxiic.4 create mode 100644 static/freebsd/man4/man4.i386/glxsb.4 create mode 100644 static/freebsd/man4/man4.i386/longrun.4 create mode 100644 static/freebsd/man4/man4.i386/npx.4 create mode 100644 static/freebsd/man4/man4.i386/pae.4 create mode 100644 static/freebsd/man4/man4.i386/pbio.4 create mode 100644 static/freebsd/man4/man4.i386/pnp.4 create mode 100644 static/freebsd/man4/man4.i386/pnpbios.4 create mode 100644 static/freebsd/man4/man4.i386/sbni.4 create mode 100644 static/freebsd/man4/man4.i386/smapi.4 create mode 100644 static/freebsd/man4/man4.i386/vpd.4 create mode 100644 static/freebsd/man4/man4.powerpc/Makefile create mode 100644 static/freebsd/man4/man4.powerpc/abtn.4 create mode 100644 static/freebsd/man4/man4.powerpc/adb.4 create mode 100644 static/freebsd/man4/man4.powerpc/akbd.4 create mode 100644 static/freebsd/man4/man4.powerpc/ams.4 create mode 100644 static/freebsd/man4/man4.powerpc/cuda.4 create mode 100644 static/freebsd/man4/man4.powerpc/dtsec.4 create mode 100644 static/freebsd/man4/man4.powerpc/llan.4 create mode 100644 static/freebsd/man4/man4.powerpc/ofw_console.4 create mode 100644 static/freebsd/man4/man4.powerpc/pmu.4 create mode 100644 static/freebsd/man4/man4.powerpc/powermac_nvram.4 create mode 100644 static/freebsd/man4/man4.powerpc/smu.4 create mode 100644 static/freebsd/man4/man4.powerpc/snd_ai2s.4 create mode 100644 static/freebsd/man4/man4.powerpc/snd_davbus.4 create mode 100644 static/freebsd/man4/man4.powerpc/tsec.4 create mode 100644 static/freebsd/man4/max44009.4 create mode 100644 static/freebsd/man4/mca.4 create mode 100644 static/freebsd/man4/md.4 create mode 100644 static/freebsd/man4/mdio.4 create mode 100644 static/freebsd/man4/me.4 create mode 100644 static/freebsd/man4/mem.4 create mode 100644 static/freebsd/man4/mfi.4 create mode 100644 static/freebsd/man4/mgb.4 create mode 100644 static/freebsd/man4/miibus.4 create mode 100644 static/freebsd/man4/mld.4 create mode 100644 static/freebsd/man4/mlx.4 create mode 100644 static/freebsd/man4/mlx4en.4 create mode 100644 static/freebsd/man4/mlx4ib.4 create mode 100644 static/freebsd/man4/mlx5en.4 create mode 100644 static/freebsd/man4/mlx5ib.4 create mode 100644 static/freebsd/man4/mlx5io.4 create mode 100644 static/freebsd/man4/mmc.4 create mode 100644 static/freebsd/man4/mmcsd.4 create mode 100644 static/freebsd/man4/mod_cc.4 create mode 100644 static/freebsd/man4/mos.4 create mode 100644 static/freebsd/man4/mouse.4 create mode 100644 static/freebsd/man4/mpi3mr.4 create mode 100644 static/freebsd/man4/mpr.4 create mode 100644 static/freebsd/man4/mps.4 create mode 100644 static/freebsd/man4/mpt.4 create mode 100644 static/freebsd/man4/mqueuefs.4 create mode 100644 static/freebsd/man4/mrsas.4 create mode 100644 static/freebsd/man4/msdosfs.4 create mode 100644 static/freebsd/man4/msk.4 create mode 100644 static/freebsd/man4/mt7915.4 create mode 100644 static/freebsd/man4/mt7921.4 create mode 100644 static/freebsd/man4/mtio.4 create mode 100644 static/freebsd/man4/mtkswitch.4 create mode 100644 static/freebsd/man4/mtw.4 create mode 100644 static/freebsd/man4/muge.4 create mode 100644 static/freebsd/man4/multicast.4 create mode 100644 static/freebsd/man4/mvs.4 create mode 100644 static/freebsd/man4/mwl.4 create mode 100644 static/freebsd/man4/mwlfw.4 create mode 100644 static/freebsd/man4/mx25l.4 create mode 100644 static/freebsd/man4/mxge.4 create mode 100644 static/freebsd/man4/my.4 create mode 100644 static/freebsd/man4/nctgpio.4 create mode 100644 static/freebsd/man4/ncthwm.4 create mode 100644 static/freebsd/man4/nda.4 create mode 100644 static/freebsd/man4/net80211.4 create mode 100644 static/freebsd/man4/netdump.4 create mode 100644 static/freebsd/man4/netfpga10g_nf10bmac.4 create mode 100644 static/freebsd/man4/netgdb.4 create mode 100644 static/freebsd/man4/netgraph.4 create mode 100644 static/freebsd/man4/netintro.4 create mode 100644 static/freebsd/man4/netlink.4 create mode 100644 static/freebsd/man4/netmap.4 create mode 100644 static/freebsd/man4/nfe.4 create mode 100644 static/freebsd/man4/nfslockd.4 create mode 100644 static/freebsd/man4/nfsmb.4 create mode 100644 static/freebsd/man4/ng_UI.4 create mode 100644 static/freebsd/man4/ng_async.4 create mode 100644 static/freebsd/man4/ng_bluetooth.4 create mode 100644 static/freebsd/man4/ng_bpf.4 create mode 100644 static/freebsd/man4/ng_bridge.4 create mode 100644 static/freebsd/man4/ng_btsocket.4 create mode 100644 static/freebsd/man4/ng_car.4 create mode 100644 static/freebsd/man4/ng_checksum.4 create mode 100644 static/freebsd/man4/ng_cisco.4 create mode 100644 static/freebsd/man4/ng_deflate.4 create mode 100644 static/freebsd/man4/ng_device.4 create mode 100644 static/freebsd/man4/ng_echo.4 create mode 100644 static/freebsd/man4/ng_eiface.4 create mode 100644 static/freebsd/man4/ng_etf.4 create mode 100644 static/freebsd/man4/ng_ether.4 create mode 100644 static/freebsd/man4/ng_ether_echo.4 create mode 100644 static/freebsd/man4/ng_frame_relay.4 create mode 100644 static/freebsd/man4/ng_gif.4 create mode 100644 static/freebsd/man4/ng_gif_demux.4 create mode 100644 static/freebsd/man4/ng_hci.4 create mode 100644 static/freebsd/man4/ng_hole.4 create mode 100644 static/freebsd/man4/ng_hub.4 create mode 100644 static/freebsd/man4/ng_iface.4 create mode 100644 static/freebsd/man4/ng_ip_input.4 create mode 100644 static/freebsd/man4/ng_ipfw.4 create mode 100644 static/freebsd/man4/ng_ksocket.4 create mode 100644 static/freebsd/man4/ng_l2cap.4 create mode 100644 static/freebsd/man4/ng_l2tp.4 create mode 100644 static/freebsd/man4/ng_lmi.4 create mode 100644 static/freebsd/man4/ng_macfilter.4 create mode 100644 static/freebsd/man4/ng_mppc.4 create mode 100644 static/freebsd/man4/ng_nat.4 create mode 100644 static/freebsd/man4/ng_netflow.4 create mode 100644 static/freebsd/man4/ng_one2many.4 create mode 100644 static/freebsd/man4/ng_patch.4 create mode 100644 static/freebsd/man4/ng_pipe.4 create mode 100644 static/freebsd/man4/ng_ppp.4 create mode 100644 static/freebsd/man4/ng_pppoe.4 create mode 100644 static/freebsd/man4/ng_pptpgre.4 create mode 100644 static/freebsd/man4/ng_pred1.4 create mode 100644 static/freebsd/man4/ng_rfc1490.4 create mode 100644 static/freebsd/man4/ng_socket.4 create mode 100644 static/freebsd/man4/ng_source.4 create mode 100644 static/freebsd/man4/ng_split.4 create mode 100644 static/freebsd/man4/ng_tag.4 create mode 100644 static/freebsd/man4/ng_tcpmss.4 create mode 100644 static/freebsd/man4/ng_tee.4 create mode 100644 static/freebsd/man4/ng_tty.4 create mode 100644 static/freebsd/man4/ng_ubt.4 create mode 100644 static/freebsd/man4/ng_vjc.4 create mode 100644 static/freebsd/man4/ng_vlan.4 create mode 100644 static/freebsd/man4/ng_vlan_rotate.4 create mode 100644 static/freebsd/man4/nge.4 create mode 100644 static/freebsd/man4/nlsysevent.4 create mode 100644 static/freebsd/man4/nmdm.4 create mode 100644 static/freebsd/man4/ntb.4 create mode 100644 static/freebsd/man4/ntb_hw_amd.4 create mode 100644 static/freebsd/man4/ntb_hw_intel.4 create mode 100644 static/freebsd/man4/ntb_hw_plx.4 create mode 100644 static/freebsd/man4/ntb_transport.4 create mode 100644 static/freebsd/man4/null.4 create mode 100644 static/freebsd/man4/nullfs.4 create mode 100644 static/freebsd/man4/numa.4 create mode 100644 static/freebsd/man4/nvd.4 create mode 100644 static/freebsd/man4/nvdimm.4 create mode 100644 static/freebsd/man4/nvme.4 create mode 100644 static/freebsd/man4/nvmf.4 create mode 100644 static/freebsd/man4/nvmf_che.4 create mode 100644 static/freebsd/man4/nvmf_tcp.4 create mode 100644 static/freebsd/man4/nvmft.4 create mode 100644 static/freebsd/man4/nvram.4 create mode 100644 static/freebsd/man4/oce.4 create mode 100644 static/freebsd/man4/ocs_fc.4 create mode 100644 static/freebsd/man4/ohci.4 create mode 100644 static/freebsd/man4/openfirm.4 create mode 100644 static/freebsd/man4/orm.4 create mode 100644 static/freebsd/man4/ossl.4 create mode 100644 static/freebsd/man4/otus.4 create mode 100644 static/freebsd/man4/otusfw.4 create mode 100644 static/freebsd/man4/ovpn.4 create mode 100644 static/freebsd/man4/ow.4 create mode 100644 static/freebsd/man4/ow_temp.4 create mode 100644 static/freebsd/man4/owc.4 create mode 100644 static/freebsd/man4/p9fs.4 create mode 100644 static/freebsd/man4/padlock.4 create mode 100644 static/freebsd/man4/pass.4 create mode 100644 static/freebsd/man4/pca954x.4 create mode 100644 static/freebsd/man4/pccbb.4 create mode 100644 static/freebsd/man4/pcf.4 create mode 100644 static/freebsd/man4/pcf8574.4 create mode 100644 static/freebsd/man4/pcf8591.4 create mode 100644 static/freebsd/man4/pchtherm.4 create mode 100644 static/freebsd/man4/pci.4 create mode 100644 static/freebsd/man4/pcib.4 create mode 100644 static/freebsd/man4/pcm.4 create mode 100644 static/freebsd/man4/pf.4 create mode 100644 static/freebsd/man4/pflog.4 create mode 100644 static/freebsd/man4/pflow.4 create mode 100644 static/freebsd/man4/pfsync.4 create mode 100644 static/freebsd/man4/pim.4 create mode 100644 static/freebsd/man4/pms.4 create mode 100644 static/freebsd/man4/polling.4 create mode 100644 static/freebsd/man4/ppbus.4 create mode 100644 static/freebsd/man4/ppc.4 create mode 100644 static/freebsd/man4/ppi.4 create mode 100644 static/freebsd/man4/procdesc.4 create mode 100644 static/freebsd/man4/procfs.4 create mode 100644 static/freebsd/man4/proto.4 create mode 100644 static/freebsd/man4/ps4dshock.4 create mode 100644 static/freebsd/man4/psm.4 create mode 100644 static/freebsd/man4/pst.4 create mode 100644 static/freebsd/man4/pt.4 create mode 100644 static/freebsd/man4/ptnet.4 create mode 100644 static/freebsd/man4/pts.4 create mode 100644 static/freebsd/man4/pty.4 create mode 100644 static/freebsd/man4/puc.4 create mode 100644 static/freebsd/man4/pvscsi.4 create mode 100644 static/freebsd/man4/pwmc.4 create mode 100644 static/freebsd/man4/qat.4 create mode 100644 static/freebsd/man4/qat_c2xxx.4 create mode 100644 static/freebsd/man4/qlnxe.4 create mode 100644 static/freebsd/man4/qlxgb.4 create mode 100644 static/freebsd/man4/qlxgbe.4 create mode 100644 static/freebsd/man4/qlxge.4 create mode 100644 static/freebsd/man4/ral.4 create mode 100644 static/freebsd/man4/random.4 create mode 100644 static/freebsd/man4/rccgpio.4 create mode 100644 static/freebsd/man4/rctl.4 create mode 100644 static/freebsd/man4/re.4 create mode 100644 static/freebsd/man4/rge.4 create mode 100644 static/freebsd/man4/rgephy.4 create mode 100644 static/freebsd/man4/rights.4 create mode 100644 static/freebsd/man4/rl.4 create mode 100644 static/freebsd/man4/rndtest.4 create mode 100644 static/freebsd/man4/route.4 create mode 100644 static/freebsd/man4/rsu.4 create mode 100644 static/freebsd/man4/rsufw.4 create mode 100644 static/freebsd/man4/rtnetlink.4 create mode 100644 static/freebsd/man4/rtsx.4 create mode 100644 static/freebsd/man4/rtw88.4 create mode 100644 static/freebsd/man4/rtw89.4 create mode 100644 static/freebsd/man4/rtwn.4 create mode 100644 static/freebsd/man4/rtwn_pci.4 create mode 100644 static/freebsd/man4/rtwn_usb.4 create mode 100644 static/freebsd/man4/rtwnfw.4 create mode 100644 static/freebsd/man4/rue.4 create mode 100644 static/freebsd/man4/rum.4 create mode 100644 static/freebsd/man4/run.4 create mode 100644 static/freebsd/man4/runfw.4 create mode 100644 static/freebsd/man4/sa.4 create mode 100644 static/freebsd/man4/safe.4 create mode 100644 static/freebsd/man4/safexcel.4 create mode 100644 static/freebsd/man4/sbp.4 create mode 100644 static/freebsd/man4/sbp_targ.4 create mode 100644 static/freebsd/man4/scc.4 create mode 100644 static/freebsd/man4/sched_4bsd.4 create mode 100644 static/freebsd/man4/sched_ule.4 create mode 100644 static/freebsd/man4/screen.4 create mode 100644 static/freebsd/man4/scsi.4 create mode 100644 static/freebsd/man4/sctp.4 create mode 100644 static/freebsd/man4/sdhci.4 create mode 100644 static/freebsd/man4/sem.4 create mode 100644 static/freebsd/man4/send.4 create mode 100644 static/freebsd/man4/ses.4 create mode 100644 static/freebsd/man4/sfxge.4 create mode 100644 static/freebsd/man4/sg.4 create mode 100644 static/freebsd/man4/sge.4 create mode 100644 static/freebsd/man4/siba.4 create mode 100644 static/freebsd/man4/siftr.4 create mode 100644 static/freebsd/man4/siis.4 create mode 100644 static/freebsd/man4/simplebus.4 create mode 100644 static/freebsd/man4/sis.4 create mode 100644 static/freebsd/man4/sk.4 create mode 100644 static/freebsd/man4/smartpqi.4 create mode 100644 static/freebsd/man4/smb.4 create mode 100644 static/freebsd/man4/smbfs.4 create mode 100644 static/freebsd/man4/smbios.4 create mode 100644 static/freebsd/man4/smbus.4 create mode 100644 static/freebsd/man4/smp.4 create mode 100644 static/freebsd/man4/smsc.4 create mode 100644 static/freebsd/man4/snd_als4000.4 create mode 100644 static/freebsd/man4/snd_atiixp.4 create mode 100644 static/freebsd/man4/snd_cmi.4 create mode 100644 static/freebsd/man4/snd_cs4281.4 create mode 100644 static/freebsd/man4/snd_csa.4 create mode 100644 static/freebsd/man4/snd_dummy.4 create mode 100644 static/freebsd/man4/snd_emu10k1.4 create mode 100644 static/freebsd/man4/snd_emu10kx.4 create mode 100644 static/freebsd/man4/snd_envy24.4 create mode 100644 static/freebsd/man4/snd_envy24ht.4 create mode 100644 static/freebsd/man4/snd_es137x.4 create mode 100644 static/freebsd/man4/snd_fm801.4 create mode 100644 static/freebsd/man4/snd_hda.4 create mode 100644 static/freebsd/man4/snd_hdsp.4 create mode 100644 static/freebsd/man4/snd_hdspe.4 create mode 100644 static/freebsd/man4/snd_ich.4 create mode 100644 static/freebsd/man4/snd_maestro3.4 create mode 100644 static/freebsd/man4/snd_neomagic.4 create mode 100644 static/freebsd/man4/snd_solo.4 create mode 100644 static/freebsd/man4/snd_spicds.4 create mode 100644 static/freebsd/man4/snd_t4dwave.4 create mode 100644 static/freebsd/man4/snd_uaudio.4 create mode 100644 static/freebsd/man4/snd_via8233.4 create mode 100644 static/freebsd/man4/snd_via82c686.4 create mode 100644 static/freebsd/man4/snd_vibes.4 create mode 100644 static/freebsd/man4/sndstat.4 create mode 100644 static/freebsd/man4/snp.4 create mode 100644 static/freebsd/man4/spigen.4 create mode 100644 static/freebsd/man4/spkr.4 create mode 100644 static/freebsd/man4/splash.4 create mode 100644 static/freebsd/man4/ste.4 create mode 100644 static/freebsd/man4/stf.4 create mode 100644 static/freebsd/man4/stge.4 create mode 100644 static/freebsd/man4/sume.4 create mode 100644 static/freebsd/man4/superio.4 create mode 100644 static/freebsd/man4/sym.4 create mode 100644 static/freebsd/man4/syncache.4 create mode 100644 static/freebsd/man4/syncer.4 create mode 100644 static/freebsd/man4/syscons.4 create mode 100644 static/freebsd/man4/sysmouse.4 create mode 100644 static/freebsd/man4/tap.4 create mode 100644 static/freebsd/man4/tarfs.4 create mode 100644 static/freebsd/man4/targ.4 create mode 100644 static/freebsd/man4/tcp.4 create mode 100644 static/freebsd/man4/tcp_bbr.4 create mode 100644 static/freebsd/man4/tcp_rack.4 create mode 100644 static/freebsd/man4/tdfx.4 create mode 100644 static/freebsd/man4/termios.4 create mode 100644 static/freebsd/man4/textdump.4 create mode 100644 static/freebsd/man4/thunderbolt.4 create mode 100644 static/freebsd/man4/ti.4 create mode 100644 static/freebsd/man4/timecounters.4 create mode 100644 static/freebsd/man4/tmpfs.4 create mode 100644 static/freebsd/man4/tpm.4 create mode 100644 static/freebsd/man4/tslog.4 create mode 100644 static/freebsd/man4/tty.4 create mode 100644 static/freebsd/man4/tun.4 create mode 100644 static/freebsd/man4/tws.4 create mode 100644 static/freebsd/man4/u2f.4 create mode 100644 static/freebsd/man4/u3g.4 create mode 100644 static/freebsd/man4/uark.4 create mode 100644 static/freebsd/man4/uart.4 create mode 100644 static/freebsd/man4/uath.4 create mode 100644 static/freebsd/man4/ubsa.4 create mode 100644 static/freebsd/man4/ubser.4 create mode 100644 static/freebsd/man4/ubtbcmfw.4 create mode 100644 static/freebsd/man4/uchcom.4 create mode 100644 static/freebsd/man4/ucom.4 create mode 100644 static/freebsd/man4/ucycom.4 create mode 100644 static/freebsd/man4/udav.4 create mode 100644 static/freebsd/man4/udbc.4 create mode 100644 static/freebsd/man4/udbp.4 create mode 100644 static/freebsd/man4/udl.4 create mode 100644 static/freebsd/man4/udp.4 create mode 100644 static/freebsd/man4/udplite.4 create mode 100644 static/freebsd/man4/uep.4 create mode 100644 static/freebsd/man4/ufintek.4 create mode 100644 static/freebsd/man4/ufoma.4 create mode 100644 static/freebsd/man4/ufshci.4 create mode 100644 static/freebsd/man4/uftdi.4 create mode 100644 static/freebsd/man4/ugen.4 create mode 100644 static/freebsd/man4/ugold.4 create mode 100644 static/freebsd/man4/uhci.4 create mode 100644 static/freebsd/man4/uhid.4 create mode 100644 static/freebsd/man4/uhso.4 create mode 100644 static/freebsd/man4/uipaq.4 create mode 100644 static/freebsd/man4/ukbd.4 create mode 100644 static/freebsd/man4/uled.4 create mode 100644 static/freebsd/man4/ulpt.4 create mode 100644 static/freebsd/man4/umass.4 create mode 100644 static/freebsd/man4/umb.4 create mode 100644 static/freebsd/man4/umcs.4 create mode 100644 static/freebsd/man4/umct.4 create mode 100644 static/freebsd/man4/umodem.4 create mode 100644 static/freebsd/man4/umoscom.4 create mode 100644 static/freebsd/man4/ums.4 create mode 100644 static/freebsd/man4/unionfs.4 create mode 100644 static/freebsd/man4/unix.4 create mode 100644 static/freebsd/man4/upgt.4 create mode 100644 static/freebsd/man4/uplcom.4 create mode 100644 static/freebsd/man4/ural.4 create mode 100644 static/freebsd/man4/ure.4 create mode 100644 static/freebsd/man4/urio.4 create mode 100644 static/freebsd/man4/urndis.4 create mode 100644 static/freebsd/man4/urtw.4 create mode 100644 static/freebsd/man4/usb.4 create mode 100644 static/freebsd/man4/usb_quirk.4 create mode 100644 static/freebsd/man4/usb_template.4 create mode 100644 static/freebsd/man4/usbhid.4 create mode 100644 static/freebsd/man4/usfs.4 create mode 100644 static/freebsd/man4/uslcom.4 create mode 100644 static/freebsd/man4/uvisor.4 create mode 100644 static/freebsd/man4/uvscom.4 create mode 100644 static/freebsd/man4/vale.4 create mode 100644 static/freebsd/man4/veriexec.4 create mode 100644 static/freebsd/man4/vga.4 create mode 100644 static/freebsd/man4/vge.4 create mode 100644 static/freebsd/man4/viapm.4 create mode 100644 static/freebsd/man4/viawd.4 create mode 100644 static/freebsd/man4/virtio.4 create mode 100644 static/freebsd/man4/virtio_balloon.4 create mode 100644 static/freebsd/man4/virtio_blk.4 create mode 100644 static/freebsd/man4/virtio_console.4 create mode 100644 static/freebsd/man4/virtio_gpu.4 create mode 100644 static/freebsd/man4/virtio_random.4 create mode 100644 static/freebsd/man4/virtio_scsi.4 create mode 100644 static/freebsd/man4/vkbd.4 create mode 100644 static/freebsd/man4/vlan.4 create mode 100644 static/freebsd/man4/vmci.4 create mode 100644 static/freebsd/man4/vmd.4 create mode 100644 static/freebsd/man4/vmgenc.4 create mode 100644 static/freebsd/man4/vmm.4 create mode 100644 static/freebsd/man4/vmx.4 create mode 100644 static/freebsd/man4/vr.4 create mode 100644 static/freebsd/man4/vt.4 create mode 100644 static/freebsd/man4/vte.4 create mode 100644 static/freebsd/man4/vtnet.4 create mode 100644 static/freebsd/man4/vxlan.4 create mode 100644 static/freebsd/man4/watchdog.4 create mode 100644 static/freebsd/man4/wbwd.4 create mode 100644 static/freebsd/man4/wdatwd.4 create mode 100644 static/freebsd/man4/wg.4 create mode 100644 static/freebsd/man4/witness.4 create mode 100644 static/freebsd/man4/wlan.4 create mode 100644 static/freebsd/man4/wlan_acl.4 create mode 100644 static/freebsd/man4/wlan_amrr.4 create mode 100644 static/freebsd/man4/wlan_ccmp.4 create mode 100644 static/freebsd/man4/wlan_gcmp.4 create mode 100644 static/freebsd/man4/wlan_tkip.4 create mode 100644 static/freebsd/man4/wlan_wep.4 create mode 100644 static/freebsd/man4/wlan_xauth.4 create mode 100644 static/freebsd/man4/wmt.4 create mode 100644 static/freebsd/man4/wpi.4 create mode 100644 static/freebsd/man4/wsp.4 create mode 100644 static/freebsd/man4/xb360gp.4 create mode 100644 static/freebsd/man4/xdma.4 create mode 100644 static/freebsd/man4/xen.4 create mode 100644 static/freebsd/man4/xhci.4 create mode 100644 static/freebsd/man4/xl.4 create mode 100644 static/freebsd/man4/xnb.4 create mode 100644 static/freebsd/man4/xpt.4 create mode 100644 static/freebsd/man4/zero.4 create mode 100644 static/freebsd/man4/zyd.4 create mode 100644 static/freebsd/man5/Makefile create mode 100644 static/freebsd/man5/a.out.5 create mode 100644 static/freebsd/man5/acct.5 create mode 100644 static/freebsd/man5/ar.5 create mode 100644 static/freebsd/man5/bluetooth.device.conf.5 create mode 100644 static/freebsd/man5/bluetooth.hosts.5 create mode 100644 static/freebsd/man5/bluetooth.protocols.5 create mode 100644 static/freebsd/man5/boot.config.5 create mode 100644 static/freebsd/man5/core.5 create mode 100644 static/freebsd/man5/devfs.conf.5 create mode 100644 static/freebsd/man5/devfs.rules.5 create mode 100644 static/freebsd/man5/device.hints.5 create mode 100644 static/freebsd/man5/dir.5 create mode 100644 static/freebsd/man5/disktab.5 create mode 100644 static/freebsd/man5/elf.5 create mode 100644 static/freebsd/man5/ethers.5 create mode 100644 static/freebsd/man5/eui64.5 create mode 100644 static/freebsd/man5/fbtab.5 create mode 100644 static/freebsd/man5/forward.5 create mode 100644 static/freebsd/man5/freebsd-update.conf.5 create mode 100644 static/freebsd/man5/fs.5 create mode 100644 static/freebsd/man5/fstab.5 create mode 100644 static/freebsd/man5/group.5 create mode 100644 static/freebsd/man5/hesiod.conf.5 create mode 100644 static/freebsd/man5/hosts.5 create mode 100644 static/freebsd/man5/hosts.equiv.5 create mode 100644 static/freebsd/man5/hosts.lpd.5 create mode 100644 static/freebsd/man5/intro.5 create mode 100644 static/freebsd/man5/libmap.conf.5 create mode 100644 static/freebsd/man5/link.5 create mode 100644 static/freebsd/man5/mailer.conf.5 create mode 100644 static/freebsd/man5/make.conf.5 create mode 100644 static/freebsd/man5/moduli.5 create mode 100644 static/freebsd/man5/motd.5 create mode 100644 static/freebsd/man5/mount.conf.5 create mode 100644 static/freebsd/man5/networks.5 create mode 100644 static/freebsd/man5/nsmb.conf.5 create mode 100644 static/freebsd/man5/nsswitch.conf.5 create mode 100644 static/freebsd/man5/os-release.5 create mode 100644 static/freebsd/man5/passwd.5 create mode 100644 static/freebsd/man5/pbm.5 create mode 100644 static/freebsd/man5/periodic.conf.5 create mode 100644 static/freebsd/man5/pf.conf.5 create mode 100644 static/freebsd/man5/pf.os.5 create mode 100644 static/freebsd/man5/phones.5 create mode 100644 static/freebsd/man5/portindex.5 create mode 100644 static/freebsd/man5/protocols.5 create mode 100644 static/freebsd/man5/quota.user.5 create mode 100644 static/freebsd/man5/rc.conf.5 create mode 100644 static/freebsd/man5/rctl.conf.5 create mode 100644 static/freebsd/man5/regdomain.5 create mode 100644 static/freebsd/man5/remote.5 create mode 100644 static/freebsd/man5/resolver.5 create mode 100644 static/freebsd/man5/services.5 create mode 100644 static/freebsd/man5/shells.5 create mode 100644 static/freebsd/man5/src.conf.5 create mode 100644 static/freebsd/man5/stab.5 create mode 100644 static/freebsd/man5/style.Makefile.5 create mode 100644 static/freebsd/man5/style.mdoc.5 create mode 100644 static/freebsd/man5/sysctl.conf.5 create mode 100644 static/freebsd/man6/Makefile create mode 100644 static/freebsd/man6/intro.6 create mode 100644 static/freebsd/man7/Makefile create mode 100644 static/freebsd/man7/arch.7 create mode 100644 static/freebsd/man7/ascii.7 create mode 100644 static/freebsd/man7/bsd.snmpmod.mk.7 create mode 100644 static/freebsd/man7/build.7 create mode 100644 static/freebsd/man7/c.7 create mode 100644 static/freebsd/man7/clocks.7 create mode 100644 static/freebsd/man7/crypto.7 create mode 100644 static/freebsd/man7/d.7 create mode 100644 static/freebsd/man7/development.7 create mode 100644 static/freebsd/man7/environ.7 create mode 100644 static/freebsd/man7/firewall.7 create mode 100644 static/freebsd/man7/freebsd-base.7 create mode 100644 static/freebsd/man7/growfs.7 create mode 100644 static/freebsd/man7/hier.7 create mode 100644 static/freebsd/man7/hostname.7 create mode 100644 static/freebsd/man7/intro.7 create mode 100644 static/freebsd/man7/maclabel.7 create mode 100644 static/freebsd/man7/mitigations.7 create mode 100644 static/freebsd/man7/named_attribute.7 create mode 100644 static/freebsd/man7/networking.7 create mode 100644 static/freebsd/man7/operator.7 create mode 100644 static/freebsd/man7/orders.7 create mode 100644 static/freebsd/man7/ports.7 create mode 100644 static/freebsd/man7/release.7 create mode 100644 static/freebsd/man7/sdoc.7 create mode 100644 static/freebsd/man7/security.7 create mode 100644 static/freebsd/man7/simd.7 create mode 100644 static/freebsd/man7/sizeof.7 create mode 100644 static/freebsd/man7/sprog.7 create mode 100644 static/freebsd/man7/stats.7 create mode 100644 static/freebsd/man7/stdint.7 create mode 100644 static/freebsd/man7/sticky.7 create mode 100644 static/freebsd/man7/tests.7 create mode 100644 static/freebsd/man7/tracing.7 create mode 100644 static/freebsd/man7/tuning.7 create mode 100644 static/freebsd/man8/Makefile create mode 100644 static/freebsd/man8/beinstall.8 create mode 100644 static/freebsd/man8/crash.8 create mode 100644 static/freebsd/man8/debug.sh.8 create mode 100644 static/freebsd/man8/diskless.8 create mode 100644 static/freebsd/man8/intro.8 create mode 100644 static/freebsd/man8/nanobsd.8 create mode 100644 static/freebsd/man8/rc.8 create mode 100644 static/freebsd/man8/rc.subr.8 create mode 100644 static/freebsd/man8/rescue.8 create mode 100644 static/freebsd/man8/uefi.8 create mode 100644 static/freebsd/man8/yp.8 create mode 100644 static/freebsd/man9/BUF_ISLOCKED.9 create mode 100644 static/freebsd/man9/BUF_LOCK.9 create mode 100644 static/freebsd/man9/BUF_LOCKFREE.9 create mode 100644 static/freebsd/man9/BUF_LOCKINIT.9 create mode 100644 static/freebsd/man9/BUF_RECURSED.9 create mode 100644 static/freebsd/man9/BUF_TIMELOCK.9 create mode 100644 static/freebsd/man9/BUF_UNLOCK.9 create mode 100644 static/freebsd/man9/BUS_ADD_CHILD.9 create mode 100644 static/freebsd/man9/BUS_BIND_INTR.9 create mode 100644 static/freebsd/man9/BUS_CHILD_DELETED.9 create mode 100644 static/freebsd/man9/BUS_CHILD_DETACHED.9 create mode 100644 static/freebsd/man9/BUS_CHILD_LOCATION.9 create mode 100644 static/freebsd/man9/BUS_CHILD_PNPINFO.9 create mode 100644 static/freebsd/man9/BUS_CONFIG_INTR.9 create mode 100644 static/freebsd/man9/BUS_DESCRIBE_INTR.9 create mode 100644 static/freebsd/man9/BUS_GET_CPUS.9 create mode 100644 static/freebsd/man9/BUS_GET_PROPERTY.9 create mode 100644 static/freebsd/man9/BUS_HINTED_CHILD.9 create mode 100644 static/freebsd/man9/BUS_NEW_PASS.9 create mode 100644 static/freebsd/man9/BUS_PRINT_CHILD.9 create mode 100644 static/freebsd/man9/BUS_READ_IVAR.9 create mode 100644 static/freebsd/man9/BUS_RESCAN.9 create mode 100644 static/freebsd/man9/BUS_SETUP_INTR.9 create mode 100644 static/freebsd/man9/CTASSERT.9 create mode 100644 static/freebsd/man9/DB_COMMAND.9 create mode 100644 static/freebsd/man9/DECLARE_GEOM_CLASS.9 create mode 100644 static/freebsd/man9/DECLARE_MODULE.9 create mode 100644 static/freebsd/man9/DEFINE_IFUNC.9 create mode 100644 static/freebsd/man9/DELAY.9 create mode 100644 static/freebsd/man9/DEVICE_ATTACH.9 create mode 100644 static/freebsd/man9/DEVICE_DETACH.9 create mode 100644 static/freebsd/man9/DEVICE_IDENTIFY.9 create mode 100644 static/freebsd/man9/DEVICE_PROBE.9 create mode 100644 static/freebsd/man9/DEVICE_SHUTDOWN.9 create mode 100644 static/freebsd/man9/DEV_MODULE.9 create mode 100644 static/freebsd/man9/DRIVER_MODULE.9 create mode 100644 static/freebsd/man9/EVENTHANDLER.9 create mode 100644 static/freebsd/man9/KASSERT.9 create mode 100644 static/freebsd/man9/LOCK_PROFILING.9 create mode 100644 static/freebsd/man9/MODULE_DEPEND.9 create mode 100644 static/freebsd/man9/MODULE_PNP_INFO.9 create mode 100644 static/freebsd/man9/MODULE_VERSION.9 create mode 100644 static/freebsd/man9/Makefile create mode 100644 static/freebsd/man9/OF_child.9 create mode 100644 static/freebsd/man9/OF_device_from_xref.9 create mode 100644 static/freebsd/man9/OF_finddevice.9 create mode 100644 static/freebsd/man9/OF_getprop.9 create mode 100644 static/freebsd/man9/OF_node_from_xref.9 create mode 100644 static/freebsd/man9/OF_package_to_path.9 create mode 100644 static/freebsd/man9/PCI_IOV_ADD_VF.9 create mode 100644 static/freebsd/man9/PCI_IOV_INIT.9 create mode 100644 static/freebsd/man9/PCI_IOV_UNINIT.9 create mode 100644 static/freebsd/man9/PHOLD.9 create mode 100644 static/freebsd/man9/SDT.9 create mode 100644 static/freebsd/man9/SYSCALL_MODULE.9 create mode 100644 static/freebsd/man9/SYSINIT.9 create mode 100644 static/freebsd/man9/VFS.9 create mode 100644 static/freebsd/man9/VFS_CHECKEXP.9 create mode 100644 static/freebsd/man9/VFS_FHTOVP.9 create mode 100644 static/freebsd/man9/VFS_MOUNT.9 create mode 100644 static/freebsd/man9/VFS_QUOTACTL.9 create mode 100644 static/freebsd/man9/VFS_ROOT.9 create mode 100644 static/freebsd/man9/VFS_SET.9 create mode 100644 static/freebsd/man9/VFS_STATFS.9 create mode 100644 static/freebsd/man9/VFS_SYNC.9 create mode 100644 static/freebsd/man9/VFS_UNMOUNT.9 create mode 100644 static/freebsd/man9/VFS_VGET.9 create mode 100644 static/freebsd/man9/VNET.9 create mode 100644 static/freebsd/man9/VOP_ACCESS.9 create mode 100644 static/freebsd/man9/VOP_ACLCHECK.9 create mode 100644 static/freebsd/man9/VOP_ADVISE.9 create mode 100644 static/freebsd/man9/VOP_ADVLOCK.9 create mode 100644 static/freebsd/man9/VOP_ALLOCATE.9 create mode 100644 static/freebsd/man9/VOP_ATTRIB.9 create mode 100644 static/freebsd/man9/VOP_BMAP.9 create mode 100644 static/freebsd/man9/VOP_BWRITE.9 create mode 100644 static/freebsd/man9/VOP_COPY_FILE_RANGE.9 create mode 100644 static/freebsd/man9/VOP_CREATE.9 create mode 100644 static/freebsd/man9/VOP_DEALLOCATE.9 create mode 100644 static/freebsd/man9/VOP_FSYNC.9 create mode 100644 static/freebsd/man9/VOP_GETACL.9 create mode 100644 static/freebsd/man9/VOP_GETEXTATTR.9 create mode 100644 static/freebsd/man9/VOP_GETPAGES.9 create mode 100644 static/freebsd/man9/VOP_INACTIVE.9 create mode 100644 static/freebsd/man9/VOP_INOTIFY.9 create mode 100644 static/freebsd/man9/VOP_IOCTL.9 create mode 100644 static/freebsd/man9/VOP_LINK.9 create mode 100644 static/freebsd/man9/VOP_LISTEXTATTR.9 create mode 100644 static/freebsd/man9/VOP_LOCK.9 create mode 100644 static/freebsd/man9/VOP_LOOKUP.9 create mode 100644 static/freebsd/man9/VOP_OPENCLOSE.9 create mode 100644 static/freebsd/man9/VOP_PATHCONF.9 create mode 100644 static/freebsd/man9/VOP_PRINT.9 create mode 100644 static/freebsd/man9/VOP_RDWR.9 create mode 100644 static/freebsd/man9/VOP_READDIR.9 create mode 100644 static/freebsd/man9/VOP_READLINK.9 create mode 100644 static/freebsd/man9/VOP_READ_PGCACHE.9 create mode 100644 static/freebsd/man9/VOP_REALLOCBLKS.9 create mode 100644 static/freebsd/man9/VOP_REMOVE.9 create mode 100644 static/freebsd/man9/VOP_RENAME.9 create mode 100644 static/freebsd/man9/VOP_REVOKE.9 create mode 100644 static/freebsd/man9/VOP_SETACL.9 create mode 100644 static/freebsd/man9/VOP_SETEXTATTR.9 create mode 100644 static/freebsd/man9/VOP_SETLABEL.9 create mode 100644 static/freebsd/man9/VOP_STRATEGY.9 create mode 100644 static/freebsd/man9/VOP_VPTOCNP.9 create mode 100644 static/freebsd/man9/VOP_VPTOFH.9 create mode 100644 static/freebsd/man9/accept_filter.9 create mode 100644 static/freebsd/man9/accf_data.9 create mode 100644 static/freebsd/man9/accf_dns.9 create mode 100644 static/freebsd/man9/accf_http.9 create mode 100644 static/freebsd/man9/accf_tls.9 create mode 100644 static/freebsd/man9/acl.9 create mode 100644 static/freebsd/man9/alq.9 create mode 100644 static/freebsd/man9/altq.9 create mode 100644 static/freebsd/man9/atomic.9 create mode 100644 static/freebsd/man9/backlight.9 create mode 100644 static/freebsd/man9/bhnd.9 create mode 100644 static/freebsd/man9/bhnd_erom.9 create mode 100644 static/freebsd/man9/bios.9 create mode 100644 static/freebsd/man9/bitset.9 create mode 100644 static/freebsd/man9/bpf.9 create mode 100644 static/freebsd/man9/buf.9 create mode 100644 static/freebsd/man9/buf_ring.9 create mode 100644 static/freebsd/man9/bus_activate_resource.9 create mode 100644 static/freebsd/man9/bus_adjust_resource.9 create mode 100644 static/freebsd/man9/bus_alloc_resource.9 create mode 100644 static/freebsd/man9/bus_attach_children.9 create mode 100644 static/freebsd/man9/bus_child_present.9 create mode 100644 static/freebsd/man9/bus_dma.9 create mode 100644 static/freebsd/man9/bus_generic_detach.9 create mode 100644 static/freebsd/man9/bus_generic_new_pass.9 create mode 100644 static/freebsd/man9/bus_generic_print_child.9 create mode 100644 static/freebsd/man9/bus_generic_read_ivar.9 create mode 100644 static/freebsd/man9/bus_generic_shutdown.9 create mode 100644 static/freebsd/man9/bus_get_resource.9 create mode 100644 static/freebsd/man9/bus_map_resource.9 create mode 100644 static/freebsd/man9/bus_release_resource.9 create mode 100644 static/freebsd/man9/bus_set_pass.9 create mode 100644 static/freebsd/man9/bus_set_resource.9 create mode 100644 static/freebsd/man9/bus_space.9 create mode 100644 static/freebsd/man9/byteorder.9 create mode 100644 static/freebsd/man9/callout.9 create mode 100644 static/freebsd/man9/casuword.9 create mode 100644 static/freebsd/man9/cd.9 create mode 100644 static/freebsd/man9/cdefs.9 create mode 100644 static/freebsd/man9/cnv.9 create mode 100644 static/freebsd/man9/condvar.9 create mode 100644 static/freebsd/man9/config_intrhook.9 create mode 100644 static/freebsd/man9/contigmalloc.9 create mode 100644 static/freebsd/man9/copy.9 create mode 100644 static/freebsd/man9/coredumper_register.9 create mode 100644 static/freebsd/man9/counter.9 create mode 100644 static/freebsd/man9/cpu_machdep.9 create mode 100644 static/freebsd/man9/cpuset.9 create mode 100644 static/freebsd/man9/cr_bsd_visible.9 create mode 100644 static/freebsd/man9/cr_cansee.9 create mode 100644 static/freebsd/man9/cr_canseejailproc.9 create mode 100644 static/freebsd/man9/cr_canseeothergids.9 create mode 100644 static/freebsd/man9/cr_canseeotheruids.9 create mode 100644 static/freebsd/man9/critical_enter.9 create mode 100644 static/freebsd/man9/crypto.9 create mode 100644 static/freebsd/man9/crypto_buffer.9 create mode 100644 static/freebsd/man9/crypto_driver.9 create mode 100644 static/freebsd/man9/crypto_request.9 create mode 100644 static/freebsd/man9/crypto_session.9 create mode 100644 static/freebsd/man9/deadfs.9 create mode 100644 static/freebsd/man9/dev_clone.9 create mode 100644 static/freebsd/man9/dev_refthread.9 create mode 100644 static/freebsd/man9/devclass.9 create mode 100644 static/freebsd/man9/devclass_find.9 create mode 100644 static/freebsd/man9/devclass_get_count.9 create mode 100644 static/freebsd/man9/devclass_get_device.9 create mode 100644 static/freebsd/man9/devclass_get_devices.9 create mode 100644 static/freebsd/man9/devclass_get_drivers.9 create mode 100644 static/freebsd/man9/devclass_get_maxunit.9 create mode 100644 static/freebsd/man9/devclass_get_name.9 create mode 100644 static/freebsd/man9/devclass_get_softc.9 create mode 100644 static/freebsd/man9/devctl_notify.9 create mode 100644 static/freebsd/man9/devctl_process_running.9 create mode 100644 static/freebsd/man9/devctl_safe_quote_sb.9 create mode 100644 static/freebsd/man9/devfs_set_cdevpriv.9 create mode 100644 static/freebsd/man9/device.9 create mode 100644 static/freebsd/man9/device_add_child.9 create mode 100644 static/freebsd/man9/device_delete_child.9 create mode 100644 static/freebsd/man9/device_delete_children.9 create mode 100644 static/freebsd/man9/device_enable.9 create mode 100644 static/freebsd/man9/device_find_child.9 create mode 100644 static/freebsd/man9/device_get_children.9 create mode 100644 static/freebsd/man9/device_get_devclass.9 create mode 100644 static/freebsd/man9/device_get_driver.9 create mode 100644 static/freebsd/man9/device_get_ivars.9 create mode 100644 static/freebsd/man9/device_get_name.9 create mode 100644 static/freebsd/man9/device_get_parent.9 create mode 100644 static/freebsd/man9/device_get_property.9 create mode 100644 static/freebsd/man9/device_get_softc.9 create mode 100644 static/freebsd/man9/device_get_state.9 create mode 100644 static/freebsd/man9/device_get_sysctl.9 create mode 100644 static/freebsd/man9/device_get_unit.9 create mode 100644 static/freebsd/man9/device_printf.9 create mode 100644 static/freebsd/man9/device_probe_and_attach.9 create mode 100644 static/freebsd/man9/device_quiet.9 create mode 100644 static/freebsd/man9/device_set_desc.9 create mode 100644 static/freebsd/man9/device_set_driver.9 create mode 100644 static/freebsd/man9/device_set_flags.9 create mode 100644 static/freebsd/man9/devstat.9 create mode 100644 static/freebsd/man9/devtoname.9 create mode 100644 static/freebsd/man9/disk.9 create mode 100644 static/freebsd/man9/dnv.9 create mode 100644 static/freebsd/man9/domain.9 create mode 100644 static/freebsd/man9/domainset.9 create mode 100644 static/freebsd/man9/dpcpu.9 create mode 100644 static/freebsd/man9/drbr.9 create mode 100644 static/freebsd/man9/driver.9 create mode 100644 static/freebsd/man9/ecn.9 create mode 100644 static/freebsd/man9/efirt.9 create mode 100644 static/freebsd/man9/epoch.9 create mode 100644 static/freebsd/man9/ether_gen_addr.9 create mode 100644 static/freebsd/man9/eventtimers.9 create mode 100644 static/freebsd/man9/extattr.9 create mode 100644 static/freebsd/man9/exterror.9 create mode 100644 static/freebsd/man9/fail.9 create mode 100644 static/freebsd/man9/fdt_pinctrl.9 create mode 100644 static/freebsd/man9/fetch.9 create mode 100644 static/freebsd/man9/firmware.9 create mode 100644 static/freebsd/man9/fpu_kern.9 create mode 100644 static/freebsd/man9/g_access.9 create mode 100644 static/freebsd/man9/g_attach.9 create mode 100644 static/freebsd/man9/g_bio.9 create mode 100644 static/freebsd/man9/g_consumer.9 create mode 100644 static/freebsd/man9/g_data.9 create mode 100644 static/freebsd/man9/g_event.9 create mode 100644 static/freebsd/man9/g_geom.9 create mode 100644 static/freebsd/man9/g_provider.9 create mode 100644 static/freebsd/man9/g_provider_by_name.9 create mode 100644 static/freebsd/man9/g_wither_geom.9 create mode 100644 static/freebsd/man9/get_cyclecount.9 create mode 100644 static/freebsd/man9/getenv.9 create mode 100644 static/freebsd/man9/getnewvnode.9 create mode 100644 static/freebsd/man9/gone_in.9 create mode 100644 static/freebsd/man9/groupmember.9 create mode 100644 static/freebsd/man9/hardclock.9 create mode 100644 static/freebsd/man9/hash.9 create mode 100644 static/freebsd/man9/hashalloc.9 create mode 100644 static/freebsd/man9/hashinit.9 create mode 100644 static/freebsd/man9/hexdump.9 create mode 100644 static/freebsd/man9/hhook.9 create mode 100644 static/freebsd/man9/hz.9 create mode 100644 static/freebsd/man9/ieee80211.9 create mode 100644 static/freebsd/man9/ieee80211_amrr.9 create mode 100644 static/freebsd/man9/ieee80211_beacon.9 create mode 100644 static/freebsd/man9/ieee80211_bmiss.9 create mode 100644 static/freebsd/man9/ieee80211_crypto.9 create mode 100644 static/freebsd/man9/ieee80211_ddb.9 create mode 100644 static/freebsd/man9/ieee80211_input.9 create mode 100644 static/freebsd/man9/ieee80211_node.9 create mode 100644 static/freebsd/man9/ieee80211_output.9 create mode 100644 static/freebsd/man9/ieee80211_proto.9 create mode 100644 static/freebsd/man9/ieee80211_radiotap.9 create mode 100644 static/freebsd/man9/ieee80211_regdomain.9 create mode 100644 static/freebsd/man9/ieee80211_scan.9 create mode 100644 static/freebsd/man9/ieee80211_vap.9 create mode 100644 static/freebsd/man9/iflib.9 create mode 100644 static/freebsd/man9/iflibdd.9 create mode 100644 static/freebsd/man9/iflibdi.9 create mode 100644 static/freebsd/man9/iflibtxrx.9 create mode 100644 static/freebsd/man9/ifnet.9 create mode 100644 static/freebsd/man9/inittodr.9 create mode 100644 static/freebsd/man9/insmntque.9 create mode 100644 static/freebsd/man9/intr_event.9 create mode 100644 static/freebsd/man9/intro.9 create mode 100644 static/freebsd/man9/kasan.9 create mode 100644 static/freebsd/man9/kern_reboot.9 create mode 100644 static/freebsd/man9/kern_testfrwk.9 create mode 100644 static/freebsd/man9/kern_yield.9 create mode 100644 static/freebsd/man9/kernacc.9 create mode 100644 static/freebsd/man9/kernel_mount.9 create mode 100644 static/freebsd/man9/khelp.9 create mode 100644 static/freebsd/man9/kmsan.9 create mode 100644 static/freebsd/man9/kobj.9 create mode 100644 static/freebsd/man9/kproc.9 create mode 100644 static/freebsd/man9/kqueue.9 create mode 100644 static/freebsd/man9/kstack_contains.9 create mode 100644 static/freebsd/man9/kthread.9 create mode 100644 static/freebsd/man9/ktr.9 create mode 100644 static/freebsd/man9/lock.9 create mode 100644 static/freebsd/man9/locking.9 create mode 100644 static/freebsd/man9/mac.9 create mode 100644 static/freebsd/man9/make_dev.9 create mode 100644 static/freebsd/man9/malloc.9 create mode 100644 static/freebsd/man9/mbchain.9 create mode 100644 static/freebsd/man9/mbuf.9 create mode 100644 static/freebsd/man9/mbuf_tags.9 create mode 100644 static/freebsd/man9/mdchain.9 create mode 100644 static/freebsd/man9/memcchr.9 create mode 100644 static/freebsd/man9/memguard.9 create mode 100644 static/freebsd/man9/mi_switch.9 create mode 100644 static/freebsd/man9/microseq.9 create mode 100644 static/freebsd/man9/microtime.9 create mode 100644 static/freebsd/man9/microuptime.9 create mode 100644 static/freebsd/man9/mod_cc.9 create mode 100644 static/freebsd/man9/module.9 create mode 100644 static/freebsd/man9/mtx_pool.9 create mode 100644 static/freebsd/man9/mutex.9 create mode 100644 static/freebsd/man9/namei.9 create mode 100644 static/freebsd/man9/netisr.9 create mode 100644 static/freebsd/man9/nv.9 create mode 100644 static/freebsd/man9/nvmem.9 create mode 100644 static/freebsd/man9/ofw_bus_is_compatible.9 create mode 100644 static/freebsd/man9/ofw_bus_status_okay.9 create mode 100644 static/freebsd/man9/ofw_graph.9 create mode 100644 static/freebsd/man9/osd.9 create mode 100644 static/freebsd/man9/owll.9 create mode 100644 static/freebsd/man9/own.9 create mode 100644 static/freebsd/man9/p_candebug.9 create mode 100644 static/freebsd/man9/p_cansee.9 create mode 100644 static/freebsd/man9/panic.9 create mode 100644 static/freebsd/man9/pci.9 create mode 100644 static/freebsd/man9/pci_iov_schema.9 create mode 100644 static/freebsd/man9/pfil.9 create mode 100644 static/freebsd/man9/pfind.9 create mode 100644 static/freebsd/man9/pget.9 create mode 100644 static/freebsd/man9/pgfind.9 create mode 100644 static/freebsd/man9/physio.9 create mode 100644 static/freebsd/man9/pmap.9 create mode 100644 static/freebsd/man9/pmap_activate.9 create mode 100644 static/freebsd/man9/pmap_clear_modify.9 create mode 100644 static/freebsd/man9/pmap_copy.9 create mode 100644 static/freebsd/man9/pmap_enter.9 create mode 100644 static/freebsd/man9/pmap_extract.9 create mode 100644 static/freebsd/man9/pmap_growkernel.9 create mode 100644 static/freebsd/man9/pmap_init.9 create mode 100644 static/freebsd/man9/pmap_is_modified.9 create mode 100644 static/freebsd/man9/pmap_is_prefaultable.9 create mode 100644 static/freebsd/man9/pmap_kextract.9 create mode 100644 static/freebsd/man9/pmap_map.9 create mode 100644 static/freebsd/man9/pmap_mincore.9 create mode 100644 static/freebsd/man9/pmap_object_init_pt.9 create mode 100644 static/freebsd/man9/pmap_page_exists_quick.9 create mode 100644 static/freebsd/man9/pmap_page_init.9 create mode 100644 static/freebsd/man9/pmap_pinit.9 create mode 100644 static/freebsd/man9/pmap_protect.9 create mode 100644 static/freebsd/man9/pmap_qenter.9 create mode 100644 static/freebsd/man9/pmap_quick_enter_page.9 create mode 100644 static/freebsd/man9/pmap_release.9 create mode 100644 static/freebsd/man9/pmap_remove.9 create mode 100644 static/freebsd/man9/pmap_resident_count.9 create mode 100644 static/freebsd/man9/pmap_unwire.9 create mode 100644 static/freebsd/man9/pmap_zero_page.9 create mode 100644 static/freebsd/man9/printf.9 create mode 100644 static/freebsd/man9/prison_check.9 create mode 100644 static/freebsd/man9/priv.9 create mode 100644 static/freebsd/man9/prng.9 create mode 100644 static/freebsd/man9/proc_rwmem.9 create mode 100644 static/freebsd/man9/pseudofs.9 create mode 100644 static/freebsd/man9/psignal.9 create mode 100644 static/freebsd/man9/pwmbus.9 create mode 100644 static/freebsd/man9/random.9 create mode 100644 static/freebsd/man9/random_harvest.9 create mode 100644 static/freebsd/man9/ratecheck.9 create mode 100644 static/freebsd/man9/redzone.9 create mode 100644 static/freebsd/man9/refcount.9 create mode 100644 static/freebsd/man9/regulator.9 create mode 100644 static/freebsd/man9/resettodr.9 create mode 100644 static/freebsd/man9/resource_int_value.9 create mode 100644 static/freebsd/man9/rijndael.9 create mode 100644 static/freebsd/man9/rman.9 create mode 100644 static/freebsd/man9/rmlock.9 create mode 100644 static/freebsd/man9/rtentry.9 create mode 100644 static/freebsd/man9/runqueue.9 create mode 100644 static/freebsd/man9/rwlock.9 create mode 100644 static/freebsd/man9/sbuf.9 create mode 100644 static/freebsd/man9/scheduler.9 create mode 100644 static/freebsd/man9/securelevel_gt.9 create mode 100644 static/freebsd/man9/selrecord.9 create mode 100644 static/freebsd/man9/sema.9 create mode 100644 static/freebsd/man9/seqc.9 create mode 100644 static/freebsd/man9/sf_buf.9 create mode 100644 static/freebsd/man9/sglist.9 create mode 100644 static/freebsd/man9/shm_map.9 create mode 100644 static/freebsd/man9/signal.9 create mode 100644 static/freebsd/man9/sleep.9 create mode 100644 static/freebsd/man9/sleepqueue.9 create mode 100644 static/freebsd/man9/smr.9 create mode 100644 static/freebsd/man9/socket.9 create mode 100644 static/freebsd/man9/stack.9 create mode 100644 static/freebsd/man9/store.9 create mode 100644 static/freebsd/man9/style.9 create mode 100644 static/freebsd/man9/style.lua.9 create mode 100644 static/freebsd/man9/superio.9 create mode 100644 static/freebsd/man9/swi.9 create mode 100644 static/freebsd/man9/sx.9 create mode 100644 static/freebsd/man9/syscall_helper_register.9 create mode 100644 static/freebsd/man9/sysctl.9 create mode 100644 static/freebsd/man9/sysctl_add_oid.9 create mode 100644 static/freebsd/man9/sysctl_ctx_init.9 create mode 100644 static/freebsd/man9/taskqueue.9 create mode 100644 static/freebsd/man9/tcp_functions.9 create mode 100644 static/freebsd/man9/thread_exit.9 create mode 100644 static/freebsd/man9/time.9 create mode 100644 static/freebsd/man9/tvtohz.9 create mode 100644 static/freebsd/man9/ucred.9 create mode 100644 static/freebsd/man9/uidinfo.9 create mode 100644 static/freebsd/man9/uio.9 create mode 100644 static/freebsd/man9/unr.9 create mode 100644 static/freebsd/man9/usbdi.9 create mode 100644 static/freebsd/man9/vaccess.9 create mode 100644 static/freebsd/man9/vaccess_acl_nfs4.9 create mode 100644 static/freebsd/man9/vaccess_acl_posix1e.9 create mode 100644 static/freebsd/man9/vflush.9 create mode 100644 static/freebsd/man9/vfs_busy.9 create mode 100644 static/freebsd/man9/vfs_getnewfsid.9 create mode 100644 static/freebsd/man9/vfs_getopt.9 create mode 100644 static/freebsd/man9/vfs_getvfs.9 create mode 100644 static/freebsd/man9/vfs_mountedfrom.9 create mode 100644 static/freebsd/man9/vfs_rootmountalloc.9 create mode 100644 static/freebsd/man9/vfs_suser.9 create mode 100644 static/freebsd/man9/vfs_timestamp.9 create mode 100644 static/freebsd/man9/vfs_unbusy.9 create mode 100644 static/freebsd/man9/vfs_unmountall.9 create mode 100644 static/freebsd/man9/vfsconf.9 create mode 100644 static/freebsd/man9/vget.9 create mode 100644 static/freebsd/man9/vgone.9 create mode 100644 static/freebsd/man9/vhold.9 create mode 100644 static/freebsd/man9/vinvalbuf.9 create mode 100644 static/freebsd/man9/vm_fault_prefault.9 create mode 100644 static/freebsd/man9/vm_map.9 create mode 100644 static/freebsd/man9/vm_map_check_protection.9 create mode 100644 static/freebsd/man9/vm_map_delete.9 create mode 100644 static/freebsd/man9/vm_map_entry_resize_free.9 create mode 100644 static/freebsd/man9/vm_map_find.9 create mode 100644 static/freebsd/man9/vm_map_findspace.9 create mode 100644 static/freebsd/man9/vm_map_inherit.9 create mode 100644 static/freebsd/man9/vm_map_init.9 create mode 100644 static/freebsd/man9/vm_map_insert.9 create mode 100644 static/freebsd/man9/vm_map_lock.9 create mode 100644 static/freebsd/man9/vm_map_lookup.9 create mode 100644 static/freebsd/man9/vm_map_madvise.9 create mode 100644 static/freebsd/man9/vm_map_max.9 create mode 100644 static/freebsd/man9/vm_map_protect.9 create mode 100644 static/freebsd/man9/vm_map_remove.9 create mode 100644 static/freebsd/man9/vm_map_stack.9 create mode 100644 static/freebsd/man9/vm_map_submap.9 create mode 100644 static/freebsd/man9/vm_map_sync.9 create mode 100644 static/freebsd/man9/vm_map_wire.9 create mode 100644 static/freebsd/man9/vm_page_aflag.9 create mode 100644 static/freebsd/man9/vm_page_alloc.9 create mode 100644 static/freebsd/man9/vm_page_bits.9 create mode 100644 static/freebsd/man9/vm_page_busy.9 create mode 100644 static/freebsd/man9/vm_page_deactivate.9 create mode 100644 static/freebsd/man9/vm_page_dontneed.9 create mode 100644 static/freebsd/man9/vm_page_free.9 create mode 100644 static/freebsd/man9/vm_page_grab.9 create mode 100644 static/freebsd/man9/vm_page_insert.9 create mode 100644 static/freebsd/man9/vm_page_lookup.9 create mode 100644 static/freebsd/man9/vm_page_rename.9 create mode 100644 static/freebsd/man9/vm_page_wire.9 create mode 100644 static/freebsd/man9/vm_set_page_size.9 create mode 100644 static/freebsd/man9/vmem.9 create mode 100644 static/freebsd/man9/vn_deallocate.9 create mode 100644 static/freebsd/man9/vn_fullpath.9 create mode 100644 static/freebsd/man9/vn_isdisk.9 create mode 100644 static/freebsd/man9/vnode.9 create mode 100644 static/freebsd/man9/vnode_pager_purge_range.9 create mode 100644 static/freebsd/man9/vnode_pager_setsize.9 create mode 100644 static/freebsd/man9/vref.9 create mode 100644 static/freebsd/man9/vrefcnt.9 create mode 100644 static/freebsd/man9/vrele.9 create mode 100644 static/freebsd/man9/vslock.9 create mode 100644 static/freebsd/man9/watchdog.9 create mode 100644 static/freebsd/man9/zero_region.9 create mode 100644 static/freebsd/man9/zone.9 diff --git a/build b/build index 0af838ad..2c405ca6 100755 --- a/build +++ b/build @@ -1,6 +1,6 @@ #!/usr/bin/env bash -SUBDIRS=(static/openbsd static/netbsd) +SUBDIRS=(static/openbsd static/netbsd static/freebsd) create() { sqlite3 man.db <0 indicates an error. +Some commands attempt to describe the nature of the failure by using +exit codes as defined in +.Xr sysexits 3 , +while others simply set the status to an arbitrary value >0 +.Pq typically 1 . +.Sh FILES +.Bl -tag -width "/usr/local/bin/tab" -compact +.It Pa /bin/ +Commands fundamental to single- and multi-user modes. +.It Pa /usr/bin/ +General commands included with the base system. +.It Pa /usr/local/bin/ +Locally installed commands from +.Xr pkg 8 or +.Xr ports 7 . +.El +.Sh SEE ALSO +.Xr apropos 1 , +.Xr man 1 , +.Xr which 1 , +.Xr intro 2 , +.Xr intro 3 , +.Xr sysexits 3 , +.Xr intro 4 , +.Xr intro 5 , +.Xr intro 6 , +.Xr intro 7 , +.Xr ports 7 , +.Xr security 7 , +.Xr intro 8 , +.Xr pkg 8 , +.Xr intro 9 +.Pp +Tutorials in the +.%T "UNIX User's Manual Supplementary Documents" . +.Sh HISTORY +The +.Nm Ns Pq 1 +manual page first appeared in +.At v6 . diff --git a/static/freebsd/man3/ATOMIC_VAR_INIT.3 b/static/freebsd/man3/ATOMIC_VAR_INIT.3 new file mode 100644 index 00000000..b3dd2423 --- /dev/null +++ b/static/freebsd/man3/ATOMIC_VAR_INIT.3 @@ -0,0 +1,299 @@ +.\" Copyright (c) 2011 Ed Schouten +.\" 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 December 27, 2011 +.Dt ATOMIC_VAR_INIT 3 +.Os +.Sh NAME +.Nm ATOMIC_VAR_INIT , +.Nm atomic_init , +.Nm atomic_load , +.Nm atomic_store , +.Nm atomic_exchange , +.Nm atomic_compare_exchange_strong , +.Nm atomic_compare_exchange_weak , +.Nm atomic_fetch_add , +.Nm atomic_fetch_and , +.Nm atomic_fetch_or , +.Nm atomic_fetch_sub , +.Nm atomic_fetch_xor , +.Nm atomic_is_lock_free +.Nd type-generic atomic operations +.Sh SYNOPSIS +.In stdatomic.h +.Pp +_Atomic(T) +.Fa v += ATOMIC_VAR_INIT(c); +.Ft void +.Fn atomic_init "_Atomic(T) *object" "T value" +.Ft T +.Fn atomic_load "_Atomic(T) *object" +.Ft T +.Fn atomic_load_explicit "_Atomic(T) *object" "memory_order order" +.Ft void +.Fn atomic_store "_Atomic(T) *object" "T desired" +.Ft void +.Fn atomic_store_explicit "_Atomic(T) *object" "T desired" "memory_order order" +.Ft T +.Fn atomic_exchange "_Atomic(T) *object" "T desired" +.Ft T +.Fn atomic_exchange_explicit "_Atomic(T) *object" "T desired" "memory_order order" +.Ft _Bool +.Fn atomic_compare_exchange_strong "_Atomic(T) *object" "T *expected" "T desired" +.Ft _Bool +.Fn atomic_compare_exchange_strong_explicit "_Atomic(T) *object" "T *expected" "T desired" "memory_order success" "memory_order failure" +.Ft _Bool +.Fn atomic_compare_exchange_weak "_Atomic(T) *object" "T *expected" "T desired" +.Ft _Bool +.Fn atomic_compare_exchange_weak_explicit "_Atomic(T) *object" "T *expected" "T desired" "memory_order success" "memory_order failure" +.Ft T +.Fn atomic_fetch_add "_Atomic(T) *object" "T operand" +.Ft T +.Fn atomic_fetch_add_explicit "_Atomic(T) *object" "T operand" "memory_order order" +.Ft T +.Fn atomic_fetch_and "_Atomic(T) *object" "T operand" +.Ft T +.Fn atomic_fetch_and_explicit "_Atomic(T) *object" "T operand" "memory_order order" +.Ft T +.Fn atomic_fetch_or "_Atomic(T) *object" "T operand" +.Ft T +.Fn atomic_fetch_or_explicit "_Atomic(T) *object" "T operand" "memory_order order" +.Ft T +.Fn atomic_fetch_sub "_Atomic(T) *object" "T operand" +.Ft T +.Fn atomic_fetch_sub_explicit "_Atomic(T) *object" "T operand" "memory_order order" +.Ft T +.Fn atomic_fetch_xor "_Atomic(T) *object" "T operand" +.Ft T +.Fn atomic_fetch_xor_explicit "_Atomic(T) *object" "T operand" "memory_order order" +.Ft _Bool +.Fn atomic_is_lock_free "const _Atomic(T) *object" +.Sh DESCRIPTION +The header +.In stdatomic.h +provides type-generic macros for atomic operations. +Atomic operations can be used by multithreaded programs to provide +shared variables between threads that in most cases may be modified +without acquiring locks. +.Pp +Atomic variables are declared using the +.Fn _Atomic +type specifier. +These variables are not type-compatible with their non-atomic +counterparts. +Depending on the compiler used, atomic variables may be opaque and can +therefore only be influenced using the macros described. +.Pp +The +.Fn atomic_init +macro initializes the atomic variable +.Fa object +with a +.Fa value . +Atomic variables can be initialized while being declared using +.Fn ATOMIC_VAR_INIT . +.Pp +The +.Fn atomic_load +macro returns the value of atomic variable +.Fa object . +The +.Fn atomic_store +macro sets the atomic variable +.Fa object +to its +.Fa desired +value. +.Pp +The +.Fn atomic_exchange +macro combines the behaviour of +.Fn atomic_load +and +.Fn atomic_store . +It sets the atomic variable +.Fa object +to its desired +.Fa value +and returns the original contents of the atomic variable. +.Pp +The +.Fn atomic_compare_exchange_strong +macro stores a +.Fa desired +value into atomic variable +.Fa object , +only if the atomic variable is equal to its +.Fa expected +value. +Upon success, the macro returns +.Dv true . +Upon failure, the +.Fa desired +value is overwritten with the value of the atomic variable and +.Dv false +is returned. +The +.Fn atomic_compare_exchange_weak +macro is identical to +.Fn atomic_compare_exchange_strong , +but is allowed to fail even if atomic variable +.Fa object +is equal to its +.Fa expected +value. +.Pp +The +.Fn atomic_fetch_add +macro adds the value +.Fa operand +to atomic variable +.Fa object +and returns the original contents of the atomic variable. +.Pp +The +.Fn atomic_fetch_and +macro applies the +.Em and +operator to atomic variable +.Fa object +and +.Fa operand +and stores the value into +.Fa object , +while returning the original contents of the atomic variable. +.Pp +The +.Fn atomic_fetch_or +macro applies the +.Em or +operator to atomic variable +.Fa object +and +.Fa operand +and stores the value into +.Fa object , +while returning the original contents of the atomic variable. +.Pp +The +.Fn atomic_fetch_sub +macro subtracts the value +.Fa operand +from atomic variable +.Fa object +and returns the original contents of the atomic variable. +.Pp +The +.Fn atomic_fetch_xor +macro applies the +.Em xor +operator to atomic variable +.Fa object +and +.Fa operand +and stores the value into +.Fa object , +while returning the original contents of the atomic variable. +.Pp +The +.Fn atomic_is_lock_free +macro returns whether atomic variable +.Fa object +uses locks when using atomic operations. +.Sh BARRIERS +The atomic operations described previously are implemented in such a way +that they disallow both the compiler and the executing processor to +re-order any nearby memory operations across the atomic operation. +In certain cases this behaviour may cause suboptimal performance. +To mitigate this, every atomic operation has an +.Fn _explicit +version that allows the re-ordering to be configured. +.Pp +The +.Fa order +parameter of these +.Fn _explicit +macros can have one of the following values. +.Bl -tag -width memory_order_relaxed +.It Dv memory_order_relaxed +No operation orders memory. +.It Dv memory_order_consume +Perform consume operation. +.It Dv memory_order_acquire +Acquire fence. +.It Dv memory_order_release +Release fence. +.It Dv memory_order_acq_rel +Acquire and release fence. +.It Dv memory_order_seq_cst +Sequentially consistent acquire and release fence. +.El +.Pp +The previously described macros are identical to the +.Fn _explicit +macros, when +.Fa order +is +.Dv memory_order_seq_cst . +.Sh COMPILER SUPPORT +These atomic operations are typically implemented by the compiler, as +they must be implemented type-generically and must often use special +hardware instructions. +As this interface has not been adopted by most compilers yet, the +.In stdatomic.h +header implements these macros on top of existing compiler intrinsics to +provide forward compatibility. +.Pp +This means that certain aspects of the interface, such as support for +different barrier types may simply be ignored. +When using GCC, all atomic operations are executed as if they are using +.Dv memory_order_seq_cst . +.Pp +Instead of using the atomic operations provided by this interface, +.St -isoC-2011 +allows the atomic variables to be modified directly using built-in +language operators. +This behaviour cannot be emulated for older compilers. +To prevent unintended non-atomic access to these variables, this header +file places the atomic variable in a structure when using an older +compiler. +.Pp +When using GCC on architectures on which it lacks support for built-in +atomic intrinsics, these macros may emit function calls to fallback +routines. +These fallback routines are only implemented for 32-bits and 64-bits +datatypes, if supported by the CPU. +.Sh SEE ALSO +.Xr pthread 3 , +.Xr atomic 9 +.Sh STANDARDS +These macros attempt to conform to +.St -isoC-2011 . +.Sh HISTORY +These macros appeared in +.Fx 10.0 . +.Sh AUTHORS +.An \&Ed Schouten Aq Mt ed@FreeBSD.org +.An David Chisnall Aq Mt theraven@FreeBSD.org diff --git a/static/freebsd/man3/CMSG_DATA.3 b/static/freebsd/man3/CMSG_DATA.3 new file mode 100644 index 00000000..27e15613 --- /dev/null +++ b/static/freebsd/man3/CMSG_DATA.3 @@ -0,0 +1,212 @@ +.\" Written by Jared Yanovich +.\" Public domain, July 3, 2005 +.Dd March 13, 2020 +.Dt CMSG_DATA 3 +.Os +.Sh NAME +.Nm CMSG_DATA , +.Nm CMSG_FIRSTHDR , +.Nm CMSG_LEN , +.Nm CMSG_NXTHDR , +.Nm CMSG_SPACE +.Nd socket control message routines for ancillary data access +.Sh SYNOPSIS +.In sys/socket.h +.Ft unsigned char * +.Fn CMSG_DATA "struct cmsghdr *" +.Ft struct cmsghdr * +.Fn CMSG_FIRSTHDR "struct msghdr *" +.Ft size_t +.Fn CMSG_LEN "size_t" +.Ft struct cmsghdr * +.Fn CMSG_NXTHDR "struct msghdr *" "struct cmsghdr *" +.Ft size_t +.Fn CMSG_SPACE "size_t" +.Sh DESCRIPTION +The control message API is used to construct ancillary data objects for +use in control messages sent and received across sockets. +.Pp +Control messages are passed around by the +.Xr recvmsg 2 +and +.Xr sendmsg 2 +system calls. +The +.Vt cmsghdr +structure, described in +.Xr recvmsg 2 , +is used to specify a chain of control messages. +.Pp +These routines should be used instead of directly accessing the control +message header members and data buffers as they ensure that necessary +alignment constraints are met. +.Pp +The following routines are provided: +.Bl -tag -width Ds +.It Fn CMSG_DATA cmsg +This routine accesses the data portion of the control message header +.Fa cmsg . +It ensures proper alignment constraints on the beginning of ancillary +data are met. +.It Fn CMSG_FIRSTHDR msghdr +This routine accesses the first control message attached to the +message +.Fa msghdr . +If no control messages are attached to the message, this routine +returns +.Dv NULL . +.It Fn CMSG_LEN len +This routine determines the size in bytes of a control message, +which includes the control message header. +.Fa len +specifies the length of the data held by the control message. +This value is what is normally stored in the +.Fa cmsg_len +of each control message. +This routine accounts for any alignment constraints on the beginning of +ancillary data. +.It Fn CMSG_NXTHDR msghdr cmsg +This routine returns the location of the control message following +.Fa cmsg +in the message +.Fa msghdr . +If +.Fa cmsg +is the last control message in the chain, this routine returns +.Dv NULL . +.It Fn CMSG_SPACE len +This routine determines the size in bytes needed to hold a control +message and its contents of length +.Fa len , +which includes the control message header. +This value is what is normally stored in +.Fa msg_msgcontrollen . +This routine accounts for any alignment constraints on the beginning of +ancillary data as well as any needed to pad the next control message. +.El +.Sh EXAMPLES +The following example constructs a control message containing a file descriptor +in the parent process and passes it over a pre-shared socket over the child +process. +Then the child process sends a "hello" string to the parent process using the +received file descriptor. +.Bd -literal +#include + +#include +#include +#include +#include +#include + +#define HELLOLEN sizeof("hello") + +int +main() +{ + struct msghdr msg; + union { + struct cmsghdr hdr; + unsigned char buf[CMSG_SPACE(sizeof(int))]; + } cmsgbuf; + char buf[HELLOLEN]; + int hellofd[2]; + int presharedfd[2]; + struct cmsghdr *cmsg; + + if (socketpair(PF_LOCAL, SOCK_STREAM, 0, presharedfd) == -1) + err(EX_OSERR, "failed to create a pre-shared socket pair"); + + memset(&msg, 0, sizeof(msg)); + msg.msg_control = &cmsgbuf.buf; + msg.msg_controllen = sizeof(cmsgbuf.buf); + msg.msg_iov = NULL; + msg.msg_iovlen = 0; + + switch (fork()) { + case -1: + err(EX_OSERR, "fork"); + case 0: + close(presharedfd[0]); + strlcpy(buf, "hello", HELLOLEN); + + if (recvmsg(presharedfd[1], &msg, 0) == -1) + err(EX_IOERR, "failed to receive a message"); + if (msg.msg_flags & (MSG_CTRUNC | MSG_TRUNC)) + errx(EX_IOERR, "control message truncated"); + for (cmsg = CMSG_FIRSTHDR(&msg); cmsg != NULL; + cmsg = CMSG_NXTHDR(&msg, cmsg)) { + if (cmsg->cmsg_len == CMSG_LEN(sizeof(int)) && + cmsg->cmsg_level == SOL_SOCKET && + cmsg->cmsg_type == SCM_RIGHTS) { + hellofd[1] = *(int *)CMSG_DATA(cmsg); + printf("child: sending '%s'\\n", buf); + if (write(hellofd[1], buf, HELLOLEN) == -1) + err(EX_IOERR, "failed to send 'hello'"); + } + } + break; + default: + close(presharedfd[1]); + + if (socketpair(PF_LOCAL, SOCK_STREAM, 0, hellofd) == -1) + err(EX_OSERR, "failed to create a 'hello' socket pair"); + + cmsg = CMSG_FIRSTHDR(&msg); + cmsg->cmsg_len = CMSG_LEN(sizeof(int)); + cmsg->cmsg_level = SOL_SOCKET; + cmsg->cmsg_type = SCM_RIGHTS; + *(int *)CMSG_DATA(cmsg) = hellofd[1]; + + if (sendmsg(presharedfd[0], &msg, 0) == -1) + err(EX_IOERR, "sendmsg"); + close(hellofd[1]); + + if (read(hellofd[0], buf, HELLOLEN) == -1) + err(EX_IOERR, "failed to receive 'hello'"); + printf("parent: received '%s'\\n", buf); + break; + } + + return (0); +} +.Ed +.Sh SEE ALSO +.Xr recvmsg 2 , +.Xr sendmsg 2 , +.Xr socket 2 , +.Xr ip 4 , +.Xr ip6 4 , +.Xr unix 4 +.Sh STANDARDS +.Bl -item +.It +.Rs +.%A W. Stevens +.%A M. Thomas +.%T "Advanced Sockets API for IPv6" +.%R RFC 2292 +.%D February 1998 +.Re +.It +.Rs +.%A W. Stevens +.%A M. Thomas +.%A E. Nordmark +.%A T. Jinmei +.%T "Advanced Sockets Application Program Interface (API) for IPv6" +.%R RFC 3542 +.%D May 2003 +.Re +.El +.Sh HISTORY +The control message API first appeared in +.Bx 4.2 . +This manual page was originally written by +.An Jared Yanovich Aq Mt jaredy@OpenBSD.org +for +.Ox 3.8 +and eventually brought to +.Fx 12.0 +by +.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . diff --git a/static/freebsd/man3/Makefile b/static/freebsd/man3/Makefile new file mode 100644 index 00000000..c070e829 --- /dev/null +++ b/static/freebsd/man3/Makefile @@ -0,0 +1,3 @@ +MAN = $(wildcard *.3) + +include ../../mandoc.mk diff --git a/static/freebsd/man3/Q_FRAWMASK.3 b/static/freebsd/man3/Q_FRAWMASK.3 new file mode 100644 index 00000000..4d03b259 --- /dev/null +++ b/static/freebsd/man3/Q_FRAWMASK.3 @@ -0,0 +1,123 @@ +.\" +.\" Copyright (c) 2018 Netflix, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions, and the following disclaimer, +.\" without modification, immediately at the beginning of the file. +.\" 2. 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 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 8, 2018 +.Dt Q_FRAWMASK 3 +.Os +.Sh NAME +.Nm Q_FRAWMASK , +.Nm Q_GFRAW , +.Nm Q_GFABSVAL , +.Nm Q_GFVAL , +.Nm Q_SFVAL +.Nd fixed-point math functions which manipulate the fractional data bits +.Sh SYNOPSIS +.In sys/qmath.h +.Ft ITYPE +.Fn Q_FRAWMASK "QTYPE q" +.Ft ITYPE +.Fn Q_GFRAW "QTYPE q" +.Ft ITYPE +.Fn Q_GFABSVAL "QTYPE q" +.Ft ITYPE +.Fn Q_GFVAL "QTYPE q" +.Ft QTYPE +.Fn Q_SFVAL "QTYPE q" "ITYPE fv" +.Sh DESCRIPTION +.Fn Q_FRAWMASK +returns a +.Fa q Ns -specific +bit mask for +.Fa q Ap s +fractional data bits. +.Pp +.Fn Q_GFRAW +returns +.Fa q Ap s +raw masked fractional data bits. +.Pp +.Fn Q_GFABSVAL +and +.Fn Q_GFVAL +return the absolute and real values of +.Fa q Ap s +fractional data bits respectively. +.Pp +.Fn Q_SFVAL +sets +.Fa q Ap s +fractional data bits to the value +.Fa fv . +.Pp +All of those functions operate on +the following data types: +.Vt s8q_t , +.Vt u8q_t , +.Vt s16q_t , +.Vt u16q_t , +.Vt s32q_t , +.Vt u32q_t , +.Vt s64q_t , +and +.Vt u64q_t , +which are referred to generically as +.Fa QTYPE . +The +.Fa ITYPE +refers to the +.Xr stdint 7 +integer types. +.Pp +For more details, see +.Xr qmath 3 . +.Sh RETURN VALUES +.Fn Q_FRAWMASK , +.Fn Q_GFRAW , +.Fn Q_GFABSVAL +and +.Fn Q_GFVAL +return their respective values as integers of the same underlying ITYPE as +.Fa q . +.Pp +.Fn Q_SFVAL +returns the value of +.Fa q +post set. +.Sh SEE ALSO +.Xr errno 2 , +.Xr qmath 3 , +.Xr stdint 7 +.Sh HISTORY +The +.Xr qmath 3 +functions first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Xr qmath 3 +functions and this manual page were written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org +and sponsored by Netflix, Inc. diff --git a/static/freebsd/man3/Q_IFRAWMASK.3 b/static/freebsd/man3/Q_IFRAWMASK.3 new file mode 100644 index 00000000..b6885084 --- /dev/null +++ b/static/freebsd/man3/Q_IFRAWMASK.3 @@ -0,0 +1,160 @@ +.\" +.\" Copyright (c) 2018 Netflix, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions, and the following disclaimer, +.\" without modification, immediately at the beginning of the file. +.\" 2. 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 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 8, 2018 +.Dt Q_IFRAWMASK 3 +.Os +.Sh NAME +.Nm Q_IFRAWMASK , +.Nm Q_IFVALIMASK , +.Nm Q_IFVALFMASK , +.Nm Q_GIFRAW , +.Nm Q_GIFABSVAL , +.Nm Q_GIFVAL , +.Nm Q_SIFVAL , +.Nm Q_SIFVALS +.Nd fixed-point math functions which manipulate the combined integer/fractional +data bits +.Sh SYNOPSIS +.In sys/qmath.h +.Ft ITYPE +.Fn Q_IFRAWMASK "QTYPE q" +.Ft ITYPE +.Fn Q_IFVALIMASK "QTYPE q" +.Ft ITYPE +.Fn Q_IFVALFMASK "QTYPE q" +.Ft ITYPE +.Fn Q_GIFRAW "QTYPE q" +.Ft ITYPE +.Fn Q_GIFABSVAL "QTYPE q" +.Ft ITYPE +.Fn Q_GIFVAL "QTYPE q" +.Ft QTYPE +.Fn Q_SIFVAL "QTYPE q" "ITYPE ifv" +.Ft QTYPE +.Fn Q_SIFVALS "QTYPE q" "ITYPE iv" "ITYPE fv" +.Sh DESCRIPTION +.Fn Q_IFRAWMASK +returns a +.Fa q Ns -specific +bit mask for +.Fa q Ap s +combined integer and fractional data bits. +.Pp +.Fn Q_IFVALIMASK +and +.Fn Q_IFVALFMASK +return +.Fa q Ns -specific +bit masks for the integer and fractional bits of +.Fa q Ap s +combined integer and fractional data bits value, i.e., are applicable to the +values returned by +.Fn Q_GIFABSVAL +and +.Fn Q_GIFVAL . +.Pp +.Fn Q_GIFRAW +returns +.Fa q Ap s +raw masked integer/fractional data bits. +.Pp +.Fn Q_GIFABSVAL +and +.Fn Q_GIFVAL +return the absolute and real values of +.Fa q Ap s +integer/fractional data bits respectively. +.Pp +.Fn Q_SIFVAL +sets +.Fa q Ap s +combined integer/fractional data bits to the value +.Fa ifv , +whereas +.Fn Q_SIFVALS +independently sets +.Fa q Ap s +integer and fractional data bits to the separate values +.Fa iv +and +.Fa fv . +.Pp +All of those functions operate on +the following data types: +.Vt s8q_t , +.Vt u8q_t , +.Vt s16q_t , +.Vt u16q_t , +.Vt s32q_t , +.Vt u32q_t , +.Vt s64q_t , +and +.Vt u64q_t , +which are referred to generically as +.Fa QTYPE . +The +.Fa ITYPE +refers to the +.Xr stdint 7 +integer types. +.Pp +For more details, see +.Xr qmath 3 . +.Sh RETURN VALUES +.Fn Q_IFRAWMASK , +.Fn Q_IFVALIMASK , +.Fn Q_IFVALFMASK , +.Fn Q_GIFABSVAL , +.Fn Q_GIFVAL , +.Fn Q_GIFRAW , +.Fn Q_GIFABSVAL +and +.Fn Q_GIFVAL +return their respective values as integers of the same underlying ITYPE as +.Fa q . +.Pp +.Fn Q_SIFVAL +and +.Fn Q_SIFVALS +return the value of +.Fa q +post change. +.Sh SEE ALSO +.Xr errno 2 , +.Xr qmath 3 , +.Xr stdint 7 +.Sh HISTORY +The +.Xr qmath 3 +functions first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Xr qmath 3 +functions and this manual page were written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org +and sponsored by Netflix, Inc. diff --git a/static/freebsd/man3/Q_INI.3 b/static/freebsd/man3/Q_INI.3 new file mode 100644 index 00000000..b7794d72 --- /dev/null +++ b/static/freebsd/man3/Q_INI.3 @@ -0,0 +1,259 @@ +.\" +.\" Copyright (c) 2018 Netflix, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions, and the following disclaimer, +.\" without modification, immediately at the beginning of the file. +.\" 2. 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 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 8, 2018 +.Dt Q_INI 3 +.Os +.Sh NAME +.Nm Q_INI , +.Nm Q_NCBITS , +.Nm Q_BT , +.Nm Q_TC , +.Nm Q_NTBITS , +.Nm Q_NFCBITS , +.Nm Q_MAXNFBITS , +.Nm Q_NFBITS , +.Nm Q_NIBITS , +.Nm Q_RPSHFT , +.Nm Q_ABS , +.Nm Q_MAXSTRLEN , +.Nm Q_TOSTR , +.Nm Q_SHL , +.Nm Q_SHR , +.Nm Q_DEBUG +.Nd fixed-point math miscellaneous functions/variables +.Sh SYNOPSIS +.In sys/qmath.h +.Ft QTYPE +.Fn Q_INI "QTYPE *q" "ITYPE iv" "ITYPE dfv" "int rpshft" +.Fd Q_NCBITS +.Ft __typeof(q) +.Fn Q_BT "QTYPE q" +.Ft ITYPE +.Fn Q_TC "QTYPE q" "ITYPE v" +.Ft uint32_t +.Fn Q_NTBITS "QTYPE q" +.Ft uint32_t +.Fn Q_NFCBITS "QTYPE q" +.Ft uint32_t +.Fn Q_MAXNFBITS "QTYPE q" +.Ft uint32_t +.Fn Q_NFBITS "QTYPE q" +.Ft uint32_t +.Fn Q_NIBITS "QTYPE q" +.Ft uint32_t +.Fn Q_RPSHFT "QTYPE q" +.Ft NTYPE +.Fn Q_ABS "NTYPE n" +.Ft uint32_t +.Fn Q_MAXSTRLEN "QTYPE q" "int base" +.Ft char * +.Fn Q_TOSTR "QTYPE q" "int prec" "int base" "char *s" "int slen" +.Ft ITYPE +.Fn Q_SHL "QTYPE q" "ITYPE iv" +.Ft ITYPE +.Fn Q_SHR "QTYPE q" "ITYPE iv" +.Ft char *, ... +.Fn Q_DEBUG "QTYPE q" "char *prefmt" "char *postfmt" "incfmt" +.Ft ITYPE +.Fn Q_DFV2BFV "ITYPE dfv" "int nfbits" +.Sh DESCRIPTION +.Fn Q_INI +initialises a Q number with the supplied integral value +.Fa iv +and decimal fractional value +.Fa dfv , +with appropriate control bits based on the requested radix shift point +.Fa rpshft . +.Fa dfv +must be passed as a preprocessor literal to preserve leading zeroes. +.Pp +The +.Dv Q_NCBITS +defined constant specifies the number of reserved control bits, currently 3. +.Pp +.Fn Q_NTBITS , +.Fn Q_NFCBITS , +.Fn Q_MAXNFBITS , +.Fn Q_NFBITS +and +.Fn Q_NIBITS +return the +.Fa q Ns -specific +count of total, control-encoded fractional, maximum fractional, effective +fractional, and integer bits applicable to +.Fa q +respectively. +.Pp +.Fn Q_BT +returns the C data type of +.Fa q , +while +.Fn Q_TC +returns +.Fa v +type casted to the C data type of +.Fa q . +.Pp +.Fn Q_RPSHFT +returns the bit position of +.Fa q Ap s +binary radix point relative to bit zero. +.Pp +.Fn Q_ABS +returns the absolute value of any standard numeric type +.Pq that uses the MSB as a sign bit, but not Q numbers +passed in as +.Fa n . +The function is signed/unsigned type safe. +.Pp +.Fn Q_SHL +and +.Fn Q_SHR +return the integral value +.Fa v +left or right shifted by the appropriate amount for +.Fa q . +.Pp +.Fn Q_MAXSTRLEN +calculates the maximum number of characters that may be required to render the +C-string representation of +.Fa q +with numeric base +.Fa base . +.Pp +.Fn Q_TOSTR +renders the C-string representation of +.Fa q +with numeric base +.Fa base +and fractional precision +.Fa prec +into +.Fa s +which has an available capacity of +.Fa slen +characters. +.Fa base +must be in range +.Bq 2,16 . +Specifying +.Fa prec +as -1 renders the number's fractional component with maximum precision. +If +.Fa slen +is greater than zero but insufficient to hold the complete C-string, the '\\0' +C-string terminator will be written to +.Fa *s , +thereby returning a zero length C-string. +.Pp +.Fn Q_DEBUG +returns a format string and associated data suitable for printf-like rendering +of debugging information pertaining to +.Fa q . +If either +.Fa prefmt +and/or +.Fa postfmt +are specified, they are prepended and appended to the resulting format string +respectively. +The +.Fa incfmt +boolean specifies whether to include +.Pq Vt true +or exclude +.Pq Vt false +the raw format string itself in the debugging output. +.Pp +.Fn Q_DFV2BFV +converts decimal fractional value +.Fa dfv +to its binary-encoded representation with +.Fa nfbits +of binary precision. +.Fa dfv +must be passed as a preprocessor literal to preserve leading zeroes. +The returned value can be used to set a Q number's fractional bits, for example +using +.Fn Q_SFVAL . +.Pp +All of those functions operate on +the following data types: +.Vt s8q_t , +.Vt u8q_t , +.Vt s16q_t , +.Vt u16q_t , +.Vt s32q_t , +.Vt u32q_t , +.Vt s64q_t , +and +.Vt u64q_t , +which are referred to generically as +.Fa QTYPE . +The +.Fa ITYPE +refers to the +.Xr stdint 7 +integer types. +.Fa NTYPE +is used to refer to any numeric type and is therefore a superset of +.Fa QTYPE +and +.Fa ITYPE . +.Pp +For more details, see +.Xr qmath 3 . +.Sh RETURN VALUES +.Fn Q_INI +returns the initialised Q number which can be used to chain initialise +additional Q numbers. +.Pp +.Fn Q_TOSTR +returns a pointer to the '\\0' C-string terminator appended to +.Fa s +after the rendered numeric data, or NULL on buffer overflow. +.Pp +.Fn Q_DFV2BFV +returns the binary-encoded representation of decimal fractional value +.Fa dfv +with +.Fa nfbits +of binary precision. +.Sh SEE ALSO +.Xr errno 2 , +.Xr qmath 3 , +.Xr stdint 7 +.Sh HISTORY +The +.Xr qmath 3 +functions first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Xr qmath 3 +functions and this manual page were written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org +and sponsored by Netflix, Inc. diff --git a/static/freebsd/man3/Q_IRAWMASK.3 b/static/freebsd/man3/Q_IRAWMASK.3 new file mode 100644 index 00000000..a15b885c --- /dev/null +++ b/static/freebsd/man3/Q_IRAWMASK.3 @@ -0,0 +1,123 @@ +.\" +.\" Copyright (c) 2018 Netflix, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions, and the following disclaimer, +.\" without modification, immediately at the beginning of the file. +.\" 2. 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 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 8, 2018 +.Dt Q_IRAWMASK 3 +.Os +.Sh NAME +.Nm Q_IRAWMASK , +.Nm Q_GIRAW , +.Nm Q_GIABSVAL , +.Nm Q_GIVAL , +.Nm Q_SIVAL +.Nd fixed-point math functions which manipulate the integer data bits +.Sh SYNOPSIS +.In sys/qmath.h +.Ft ITYPE +.Fn Q_IRAWMASK "QTYPE q" +.Ft ITYPE +.Fn Q_GIRAW "QTYPE q" +.Ft ITYPE +.Fn Q_GIABSVAL "QTYPE q" +.Ft ITYPE +.Fn Q_GIVAL "QTYPE q" +.Ft QTYPE +.Fn Q_SIVAL "QTYPE q" "ITYPE iv" +.Sh DESCRIPTION +.Fn Q_IRAWMASK +returns a +.Fa q Ns -specific +bit mask for +.Fa q Ap s +integer data bits. +.Pp +.Fn Q_GIRAW +returns +.Fa q Ap s +raw masked integer data bits. +.Pp +.Fn Q_GIABSVAL +and +.Fn Q_GIVAL +return the absolute and real values of +.Fa q Ap s +integer data bits respectively. +.Pp +.Fn Q_SIVAL +sets +.Fa q Ap s +integer data bits to the value +.Fa iv . +.Pp +All of those functions operate on +the following data types: +.Vt s8q_t , +.Vt u8q_t , +.Vt s16q_t , +.Vt u16q_t , +.Vt s32q_t , +.Vt u32q_t , +.Vt s64q_t , +and +.Vt u64q_t , +which are referred to generically as +.Fa QTYPE . +The +.Fa ITYPE +refers to the +.Xr stdint 7 +integer types. +.Pp +For more details, see +.Xr qmath 3 . +.Sh RETURN VALUES +.Fn Q_IRAWMASK , +.Fn Q_GIRAW , +.Fn Q_GIABSVAL +and +.Fn Q_GIVAL +return their respective values as integers of the same underlying ITYPE as +.Fa q . +.Pp +.Fn Q_SIVAL +returns the value of +.Fa q +post change. +.Sh SEE ALSO +.Xr errno 2 , +.Xr qmath 3 , +.Xr stdint 7 +.Sh HISTORY +The +.Xr qmath 3 +functions first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Xr qmath 3 +functions and this manual page were written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org +and sponsored by Netflix, Inc. diff --git a/static/freebsd/man3/Q_QABS.3 b/static/freebsd/man3/Q_QABS.3 new file mode 100644 index 00000000..31219e1f --- /dev/null +++ b/static/freebsd/man3/Q_QABS.3 @@ -0,0 +1,99 @@ +.\" +.\" Copyright (c) 2018 Netflix, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions, and the following disclaimer, +.\" without modification, immediately at the beginning of the file. +.\" 2. 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 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 8, 2018 +.Dt Q_QABS 3 +.Os +.Sh NAME +.Nm Q_QABS , +.Nm Q_Q2S , +.Nm Q_Q2F +.Nd fixed-point math functions which operate on a single Q number +.Sh SYNOPSIS +.In sys/qmath.h +.Ft QTYPE +.Fn Q_QABS "QTYPE q" +.Ft double +.Fn Q_Q2D "QTYPE q" +.Ft float +.Fn Q_Q2F "QTYPE q" +.Sh DESCRIPTION +The +.Fn Q_QABS +function returns an absolute value representation of +.Fa q . +.Pp +The +.Fn Q_Q2D +and +.Fn Q_Q2F +functions return the double and float representations of +.Fa q +respectively. +.Pp +All of those functions operate on +the following data types: +.Vt s8q_t , +.Vt u8q_t , +.Vt s16q_t , +.Vt u16q_t , +.Vt s32q_t , +.Vt u32q_t , +.Vt s64q_t , +and +.Vt u64q_t , +which are referred to generically as +.Fa QTYPE . +.Pp +For more details, see +.Xr qmath 3 . +.Sh RETURN VALUES +.Fn Q_QABS +function returns a QTYPE that is identical to that of +.Fa q . +.Pp +The +.Fn Q_Q2D +and +.Fn Q_Q2F +functions return the double and float representations of +.Fa q +respectively. +.Sh SEE ALSO +.Xr errno 2 , +.Xr qmath 3 , +.Xr stdint 7 +.Sh HISTORY +The +.Xr qmath 3 +functions first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Xr qmath 3 +functions and this manual page were written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org +and sponsored by Netflix, Inc. diff --git a/static/freebsd/man3/Q_QADDI.3 b/static/freebsd/man3/Q_QADDI.3 new file mode 100644 index 00000000..5b1bc8c2 --- /dev/null +++ b/static/freebsd/man3/Q_QADDI.3 @@ -0,0 +1,132 @@ +.\" +.\" Copyright (c) 2018 Netflix, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions, and the following disclaimer, +.\" without modification, immediately at the beginning of the file. +.\" 2. 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 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 8, 2018 +.Dt Q_QADDI 3 +.Os +.Sh NAME +.Nm Q_QADDI , +.Nm Q_QDIVI , +.Nm Q_QMULI , +.Nm Q_QSUBI , +.Nm Q_QFRACI , +.Nm Q_QCPYVALI +.Nd fixed-point math functions which apply integers to a Q number +.Sh SYNOPSIS +.In sys/qmath.h +.Ft int +.Fn Q_QADDI "QTYPE *a" "ITYPE b" +.Ft int +.Fn Q_QDIVI "QTYPE *a" "ITYPE b" +.Ft int +.Fn Q_QMULI "QTYPE *a" "ITYPE b" +.Ft int +.Fn Q_QSUBI "QTYPE *a" "ITYPE b" +.Ft int +.Fn Q_QFRACI "QTYPE *q" "ITYPE n" "ITYPE d" +.Ft int +.Fn Q_QCPYVALI "QTYPE *q" "ITYPE i" +.Sh DESCRIPTION +The +.Fn Q_QADDI , +.Fn Q_QDIVI , +.Fn Q_QMULI +and +.Fn Q_QSUBI +functions add, divide, multiply or subtract +.Fa b +to/by/from +.Fa a +respectively, storing the result in +.Fa a . +.Pp +The +.Fn Q_QFRACI +function computes the fraction +.Fa n +divided by +.Fa d +and stores the fixed-point result in +.Fa q . +.Pp +The +.Fn Q_QCPYVALI +function overwrites +.Fa q Ap s +integer and fractional bits with the Q representation of integer value +.Fa i . +.Pp +All of those functions operate on +the following data types: +.Vt s8q_t , +.Vt u8q_t , +.Vt s16q_t , +.Vt u16q_t , +.Vt s32q_t , +.Vt u32q_t , +.Vt s64q_t , +and +.Vt u64q_t , +which are referred to generically as +.Fa QTYPE . +The +.Fa ITYPE +refers to the +.Xr stdint 7 +integer types. +.Pp +For more details, see +.Xr qmath 3 . +.Sh RETURN VALUES +.Fn Q_QADDI , +.Fn Q_QDIVI , +.Fn Q_QMULI , +.Fn Q_QSUBI , +.Fn Q_QFRACI +and +.Fn Q_QCPYVALI +functions return 0 on success, or an errno on failure. +.Er EINVAL +is returned for divide-by-zero. +.Er EOVERFLOW +and +.Er ERANGE +are returned for overflow and underflow respectively. +.Sh SEE ALSO +.Xr errno 2 , +.Xr qmath 3 , +.Xr stdint 7 +.Sh HISTORY +The +.Xr qmath 3 +functions first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Xr qmath 3 +functions and this manual page were written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org +and sponsored by Netflix, Inc. diff --git a/static/freebsd/man3/Q_QADDQ.3 b/static/freebsd/man3/Q_QADDQ.3 new file mode 100644 index 00000000..d6a7df7f --- /dev/null +++ b/static/freebsd/man3/Q_QADDQ.3 @@ -0,0 +1,173 @@ +.\" +.\" Copyright (c) 2018 Netflix, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions, and the following disclaimer, +.\" without modification, immediately at the beginning of the file. +.\" 2. 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 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 8, 2018 +.Dt Q_QADDQ 3 +.Os +.Sh NAME +.Nm Q_QADDQ , +.Nm Q_QDIVQ , +.Nm Q_QMULQ , +.Nm Q_QSUBQ , +.Nm Q_NORMPREC , +.Nm Q_QMAXQ , +.Nm Q_QMINQ , +.Nm Q_QCLONEQ , +.Nm Q_CPYVALQ +.Nd fixed-point math functions which operate on two Q numbers +.Sh SYNOPSIS +.In sys/qmath.h +.Ft int +.Fn Q_QADDQ "QTYPE *a" "QTYPE b" +.Ft int +.Fn Q_QDIVQ "QTYPE *a" "QTYPE b" +.Ft int +.Fn Q_QMULQ "QTYPE *a" "QTYPE b" +.Ft int +.Fn Q_QSUBQ "QTYPE *a" "QTYPE b" +.Ft int +.Fn Q_NORMPREC "QTYPE *a" "QTYPE *b" +.Ft QTYPE +.Fn Q_QMAXQ "QTYPE a" "QTYPE b" +.Ft QTYPE +.Fn Q_QMINQ "QTYPE a" "QTYPE b" +.Ft int +.Fn Q_QCLONEQ "QTYPE *l" "QTYPE r" +.Ft int +.Fn Q_QCPYVALQ "QTYPE *l" "QTYPE r" +.Sh DESCRIPTION +The +.Fn Q_QADDQ , +.Fn Q_QDIVQ , +.Fn Q_QMULQ , +and +.Fn Q_QSUBQ +functions add, divide, multiply or subtract +.Fa b +to/by/from +.Fa a +respectively, storing the result in +.Fa a . +Both arguments must be initialized with the same fractional radix point. +.Pp +The +.Fn Q_NORMPREC +function attempts to normalise the precision of +.Fa a +and +.Fa b +if they differ. +The greater of the two precisions is preferred if possible, unless that would +truncate integer component data for the other operand, in which case the highest +precision that preserves the integer component of both +.Fa a +and +.Fa b +is selected. +.Pp +The +.Fn Q_QMAXQ +and +.Fn Q_QMINQ +functions return the larger or smaller of +.Fa a +and +.Fa b +respectively. +.Pp +The +.Fn Q_QCLONEQ +and +.Fn Q_QCPYVALQ +functions attempt to store identical or representational copies of +.Fa r , +in +.Fa l +respectively. +An identical Q number produced by cloning copies the control bits as well as the +verbatim integer/fractional bits. +A representational copy only copies the values of +.Fa r Ap s +integer and fractional bits, representing them in the bits available per +.Fa l Ap s +Q format. +.Pp +All of those functions operate on the following data types: +.Vt s8q_t , +.Vt u8q_t , +.Vt s16q_t , +.Vt u16q_t , +.Vt s32q_t , +.Vt u32q_t , +.Vt s64q_t , +and +.Vt u64q_t , +which are referred to generically as +.Fa QTYPE . +.Pp +For more details, see +.Xr qmath 3 . +.Sh RETURN VALUES +The +.Fn Q_QADDQ , +.Fn Q_QDIVQ , +.Fn Q_QMULQ , +.Fn Q_QSUBQ +.Fn Q_NORMPREC , +.Fn Q_QCLONEQ +and +.Fn Q_QCPYVALQ +functions return 0 on success, or an errno on failure. +.Er EINVAL +is returned for divide-by-zero. +.Er EOVERFLOW +and +.Er ERANGE +are returned for overflow and underflow respectively. +.Er ERANGE is also returned when the precision of arguments +does not match. +.Pp +The +.Fn Q_QMAXQ +and +.Fn Q_QMINQ +functions return the numerically larger or smaller of their two inputs +respectively. +.Sh SEE ALSO +.Xr errno 2 , +.Xr qmath 3 , +.Xr stdint 7 +.Sh HISTORY +The +.Xr qmath 3 +functions first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Xr qmath 3 +functions and this manual page were written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org +and sponsored by Netflix, Inc. diff --git a/static/freebsd/man3/Q_SIGNED.3 b/static/freebsd/man3/Q_SIGNED.3 new file mode 100644 index 00000000..528757dc --- /dev/null +++ b/static/freebsd/man3/Q_SIGNED.3 @@ -0,0 +1,208 @@ +.\" +.\" Copyright (c) 2018 Netflix, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions, and the following disclaimer, +.\" without modification, immediately at the beginning of the file. +.\" 2. 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 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 8, 2018 +.Dt Q_SIGNED 3 +.Os +.Sh NAME +.Nm Q_SIGNED , +.Nm Q_LTZ , +.Nm Q_PRECEQ , +.Nm Q_QLTQ , +.Nm Q_QLEQ , +.Nm Q_QGTQ , +.Nm Q_QGEQ , +.Nm Q_QEQ , +.Nm Q_QNEQ , +.Nm Q_OFLOW , +.Nm Q_RELPREC +.Nd fixed-point math comparison and logic functions +.Sh SYNOPSIS +.In sys/qmath.h +.Ft bool +.Fn Q_SIGNED "NTYPE n" +.Ft bool +.Fn Q_LTZ "NTYPE n" +.Ft bool +.Fn Q_PRECEQ "QTYPE a" "QTYPE b" +.Ft bool +.Fn Q_QLTQ "QTYPE a" "QTYPE b" +.Ft bool +.Fn Q_QLEQ "QTYPE a" "QTYPE b" +.Ft bool +.Fn Q_QGTQ "QTYPE a" "QTYPE b" +.Ft bool +.Fn Q_QGEQ "QTYPE a" "QTYPE b" +.Ft bool +.Fn Q_QEQ "QTYPE a" "QTYPE b" +.Ft bool +.Fn Q_QNEQ "QTYPE a" "QTYPE b" +.Ft bool +.Fn Q_OFLOW "QTYPE q" "ITYPE iv" +.Ft int +.Fn Q_RELPREC "QTYPE a" "QTYPE b" +.Sh DESCRIPTION +.Fn Q_SIGNED +returns +.Ft true +if the numeric data type passed in as +.Fa n +is signed, or +.Ft false +otherwise. +.Pp +.Fn Q_LTZ +returns +.Ft true +if the numeric value +passed in as +.Fa n +is negative +.Pq requires types which use the MSB as the sign bit , +or +.Ft false +otherwise. +.Pp +.Fn Q_PRECEQ +returns +.Ft true +if the number of +.Fa a +and +.Fa b +fractional bits is the same, +.Ft false +otherwise. +.Pp +The +.Fn Q_QLTQ , +.Fn Q_QLEQ , +.Fn Q_QGTQ , +.Fn Q_QGEQ , +.Fn Q_QEQ +and +.Fn Q_QNEQ +functions compare two Q numbers, returning +.Ft true +if +.Fa a +is less than, less than or equal to, greater than, greater than or equal to, +equal to, or not equal to +.Fa b +respectively, or +.Ft false +otherwise. +The integral and fractional values are used to perform the comparison, without +explicit concern for the underlying number of integer versus fractional bits. +.Pp +.Fn Q_OFLOW +returns +.Ft true +if integer value +.Fa iv +cannot be stored in +.Fa q +without truncation, or false otherwise. +.Pp +.Fn Q_RELPREC +returns the relative precision of +.Fa a +versus +.Fa b . +In terms of +.Em Qm.n +notation, this function returns the difference between the +.Em n +values of +.Fa a +and +.Fa b . +For example, a return value of +4 means that +.Fa a +has an additional 4 bits of fractional precision compared to +.Fa b . +.Pp +All of those functions operate on +the following data types: +.Vt s8q_t , +.Vt u8q_t , +.Vt s16q_t , +.Vt u16q_t , +.Vt s32q_t , +.Vt u32q_t , +.Vt s64q_t , +and +.Vt u64q_t , +which are referred to generically as +.Fa QTYPE . +The +.Fa ITYPE +refers to the +.Xr stdint 7 +integer types. +.Fa NTYPE +is used to refer to any numeric type and is therefore a superset of +.Fa QTYPE +and +.Fa ITYPE . +.Pp +For more details, see +.Xr qmath 3 . +.Sh RETURN VALUES +The +.Fn Q_SIGNED , +.Fn Q_LTZ , +.Fn Q_PRECEQ , +.Fn Q_QLTQ , +.Fn Q_QLEQ , +.Fn Q_QGTQ , +.Fn Q_QGEQ , +.Fn Q_QEQ , +.Fn Q_QNEQ +and +.Fn Q_OFLOW +functions return expressions that evaluate to boolean +.Vt true +or +.Vt false . +.Pp +.Fn Q_RELPREC +returns the relative precision difference as a signed integer. +.Sh SEE ALSO +.Xr errno 2 , +.Xr qmath 3 , +.Xr stdint 7 +.Sh HISTORY +The +.Xr qmath 3 +functions first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Xr qmath 3 +functions and this manual page were written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org +and sponsored by Netflix, Inc. diff --git a/static/freebsd/man3/Q_SIGNSHFT.3 b/static/freebsd/man3/Q_SIGNSHFT.3 new file mode 100644 index 00000000..ce355560 --- /dev/null +++ b/static/freebsd/man3/Q_SIGNSHFT.3 @@ -0,0 +1,145 @@ +.\" +.\" Copyright (c) 2018 Netflix, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions, and the following disclaimer, +.\" without modification, immediately at the beginning of the file. +.\" 2. 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 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 8, 2018 +.Dt Q_SIGNSHFT 3 +.Os +.Sh NAME +.Nm Q_SIGNSHFT , +.Nm Q_SSIGN , +.Nm Q_CRAWMASK , +.Nm Q_SRAWMASK , +.Nm Q_GCRAW , +.Nm Q_GCVAL , +.Nm Q_SCVAL +.Nd fixed-point math functions which manipulate the control/sign data bits +.Sh SYNOPSIS +.In sys/qmath.h +.Ft uint32_t +.Fn Q_SIGNSHFT "QTYPE q" +.Ft QTYPE +.Fn Q_SSIGN "QTYPE q" "bool isneg" +.Ft ITYPE +.Fn Q_CRAWMASK "QTYPE q" +.Ft ITYPE +.Fn Q_SRAWMASK "QTYPE q" +.Ft ITYPE +.Fn Q_GCRAW "QTYPE q" +.Ft ITYPE +.Fn Q_GCVAL "QTYPE q" +.Ft QTYPE +.Fn Q_SCVAL "QTYPE q" "ITYPE cv" +.Sh DESCRIPTION +.Fn Q_SIGNSHFT +gets the bit position of +.Fa q Ap s +sign bit relative to bit zero. +.Pp +.Fn Q_SSIGN +sets the sign bit of +.Fa q +based on the boolean +.Fa isneg . +.Pp +.Fn Q_CRAWMASK +and +.Fn Q_SRAWMASK +return +.Fa q Ns -specific +bit masks for +.Fa q Ap s +control bits and sign bit respectively. +.Pp +.Fn Q_GCRAW +and +.Fn Q_GCVAL +get the raw masked control bits and value of +.Fa q Ap s +control bits respectively. +.Pp +.Fn Q_SCVAL +sets +.Fa q Ap s +control bits to the value +.Fa cv . +.Pp +All of those functions operate on +the following data types: +.Vt s8q_t , +.Vt u8q_t , +.Vt s16q_t , +.Vt u16q_t , +.Vt s32q_t , +.Vt u32q_t , +.Vt s64q_t , +and +.Vt u64q_t , +which are referred to generically as +.Fa QTYPE . +The +.Fa ITYPE +refers to the +.Xr stdint 7 +integer types. +.Pp +For more details, see +.Xr qmath 3 . +.Sh RETURN VALUES +.Fn Q_SIGNSHFT +returns the sign bit's position as an integer. +.Pp +.Fn Q_SSIGN +returns the value of +.Fa q +post change. +.Pp +.Fn Q_CRAWMASK , +.Fn Q_SRAWMASK , +.Fn Q_GCRAW +and +.Fn Q_GCVAL +return their respective values as integers of the same underlying ITYPE as +.Fa q . +.Pp +.Fn Q_SCVAL +returns the value of +.Fa q +post change. +.Sh SEE ALSO +.Xr errno 2 , +.Xr qmath 3 , +.Xr stdint 7 +.Sh HISTORY +The +.Xr qmath 3 +functions first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Xr qmath 3 +functions and this manual page were written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org +and sponsored by Netflix, Inc. diff --git a/static/freebsd/man3/alloca.3 b/static/freebsd/man3/alloca.3 new file mode 100644 index 00000000..9e905d44 --- /dev/null +++ b/static/freebsd/man3/alloca.3 @@ -0,0 +1,101 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" Copyright (c) 2026 Aymeric Wibo +.\" +.\" 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 February 19, 2026 +.Dt ALLOCA 3 +.Os +.Sh NAME +.Nm alloca +.Nd memory allocator +.Sh SYNOPSIS +.In stdlib.h +.Ft void * +.Fn alloca "size_t size" +.Sh DESCRIPTION +The +.Fn alloca +function or macro allocates +.Fa size +bytes of space in the stack frame of the caller. +This temporary space is automatically freed on +return. +.Sh RETURN VALUES +.Fn alloca +returns a pointer to the beginning of the allocated space. +.Sh SEE ALSO +.Xr brk 2 , +.Xr calloc 3 , +.Xr getpagesize 3 , +.Xr malloc 3 , +.Xr realloc 3 +.Sh HISTORY +.Fn alloca +appeared in +.At 32v . +.\" .Bx ?? . +.\" The function appeared in 32v, pwb and pwb.2 and in 3bsd 4bsd +.\" The first man page (or link to a man page that I can find at the +.\" moment is 4.3... +.Sh BUGS +.Fn alloca +is machine and compiler dependent; +its use is discouraged. +.Pp +.Fn alloca +is slightly unsafe because it cannot ensure that the pointer +returned points to a valid and usable block of memory. +The allocation made may exceed the bounds of the stack, or even go +further into other objects in memory, and +.Fn alloca +cannot determine such an error. +Avoid +.Fn alloca +with large unbounded allocations. +.Pp +The use of C99 variable-length arrays and +.Fn alloca +in the same function will cause the lifetime of +.Fn alloca Ns 's +storage to be limited to the block containing the +.Fn alloca . +For example, in the following snippet, +.Va p Ns 's +lifetime does not extend outside of the block, whereas it would've if +.Va vla +hadn't been defined or had been defined as a fixed-length array: +.Bd -literal -offset indent +char *p; +{ + const int n = 100; + int vla[n]; + p = alloca(32); + strcpy(p, "Hello, world!"); + printf("Inside: %s\\n", p); /* Valid. */ +} +printf("Outside: %s\\n", p); /* Undefined. */ +.Ed diff --git a/static/freebsd/man3/arb.3 b/static/freebsd/man3/arb.3 new file mode 100644 index 00000000..e33ef3a3 --- /dev/null +++ b/static/freebsd/man3/arb.3 @@ -0,0 +1,511 @@ +.\" $OpenBSD: tree.3,v 1.7 2002/06/12 01:09:20 provos Exp $ +.\" +.\" Copyright 2002 Niels Provos +.\" Copyright 2018-2019 Netflix, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by Niels Provos. +.\" 4. 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 October 14, 2019 +.Dt ARB 3 +.Os +.Sh NAME +.Nm ARB_PROTOTYPE , +.Nm ARB_PROTOTYPE_STATIC , +.Nm ARB_PROTOTYPE_INSERT , +.Nm ARB_PROTOTYPE_INSERT_COLOR , +.Nm ARB_PROTOTYPE_REMOVE , +.Nm ARB_PROTOTYPE_REMOVE_COLOR , +.Nm ARB_PROTOTYPE_FIND , +.Nm ARB_PROTOTYPE_NFIND , +.Nm ARB_PROTOTYPE_NEXT , +.Nm ARB_PROTOTYPE_PREV , +.Nm ARB_PROTOTYPE_MINMAX , +.Nm ARB_PROTOTYPE_REINSERT , +.Nm ARB_GENERATE , +.Nm ARB_GENERATE_STATIC , +.Nm ARB_GENERATE_INSERT , +.Nm ARB_GENERATE_INSERT_COLOR , +.Nm ARB_GENERATE_REMOVE , +.Nm ARB_GENERATE_REMOVE_COLOR , +.Nm ARB_GENERATE_FIND , +.Nm ARB_GENERATE_NFIND , +.Nm ARB_GENERATE_NEXT , +.Nm ARB_GENERATE_PREV , +.Nm ARB_GENERATE_MINMAX , +.Nm ARB_GENERATE_REINSERT , +.Nm ARB8_ENTRY , +.Nm ARB16_ENTRY , +.Nm ARB32_ENTRY , +.Nm ARB8_HEAD , +.Nm ARB16_HEAD , +.Nm ARB32_HEAD , +.Nm ARB_ALLOCSIZE , +.Nm ARB_INITIALIZER , +.Nm ARB_ROOT , +.Nm ARB_EMPTY , +.Nm ARB_FULL , +.Nm ARB_CURNODES , +.Nm ARB_MAXNODES , +.Nm ARB_NEXT , +.Nm ARB_PREV , +.Nm ARB_MIN , +.Nm ARB_MAX , +.Nm ARB_FIND , +.Nm ARB_NFIND , +.Nm ARB_LEFT , +.Nm ARB_LEFTIDX , +.Nm ARB_RIGHT , +.Nm ARB_RIGHTIDX , +.Nm ARB_PARENT , +.Nm ARB_PARENTIDX , +.Nm ARB_GETFREE , +.Nm ARB_FREEIDX , +.Nm ARB_FOREACH , +.Nm ARB_FOREACH_FROM , +.Nm ARB_FOREACH_SAFE , +.Nm ARB_FOREACH_REVERSE , +.Nm ARB_FOREACH_REVERSE_FROM , +.Nm ARB_FOREACH_REVERSE_SAFE , +.Nm ARB_INIT , +.Nm ARB_INSERT , +.Nm ARB_REMOVE , +.Nm ARB_REINSERT , +.Nm ARB_RESET_TREE +.Nd "array-based red-black trees" +.Sh SYNOPSIS +.In sys/arb.h +.Fn ARB_PROTOTYPE NAME TYPE FIELD CMP +.Fn ARB_PROTOTYPE_STATIC NAME TYPE FIELD CMP +.Fn ARB_PROTOTYPE_INSERT NAME TYPE ATTR +.Fn ARB_PROTOTYPE_INSERT_COLOR NAME TYPE ATTR +.Fn ARB_PROTOTYPE_REMOVE NAME TYPE ATTR +.Fn ARB_PROTOTYPE_REMOVE_COLOR NAME TYPE ATTR +.Fn ARB_PROTOTYPE_FIND NAME TYPE ATTR +.Fn ARB_PROTOTYPE_NFIND NAME TYPE ATTR +.Fn ARB_PROTOTYPE_NEXT NAME TYPE ATTR +.Fn ARB_PROTOTYPE_PREV NAME TYPE ATTR +.Fn ARB_PROTOTYPE_MINMAX NAME TYPE ATTR +.Fn ARB_PROTOTYPE_REINSERT NAME TYPE ATTR +.Fn ARB_GENERATE NAME TYPE FIELD CMP +.Fn ARB_GENERATE_STATIC NAME TYPE FIELD CMP +.Fn ARB_GENERATE_INSERT NAME TYPE FIELD CMP ATTR +.Fn ARB_GENERATE_INSERT_COLOR NAME TYPE FIELD ATTR +.Fn ARB_GENERATE_REMOVE NAME TYPE FIELD ATTR +.Fn ARB_GENERATE_REMOVE_COLOR NAME TYPE FIELD ATTR +.Fn ARB_GENERATE_FIND NAME TYPE FIELD CMP ATTR +.Fn ARB_GENERATE_NFIND NAME TYPE FIELD CMP ATTR +.Fn ARB_GENERATE_NEXT NAME TYPE FIELD ATTR +.Fn ARB_GENERATE_PREV NAME TYPE FIELD ATTR +.Fn ARB_GENERATE_MINMAX NAME TYPE FIELD ATTR +.Fn ARB_GENERATE_REINSERT NAME TYPE FIELD CMP ATTR +.Fn ARB<8|16|32>_ENTRY +.Fn ARB<8|16|32>_HEAD HEADNAME TYPE +.Ft "size_t" +.Fn ARB_ALLOCSIZE "ARB_HEAD *head" "int<8|16|32>_t maxnodes" "struct TYPE *elm" +.Fn ARB_INITIALIZER "ARB_HEAD *head" "int<8|16|32>_t maxnodes" +.Ft "struct TYPE *" +.Fn ARB_ROOT "ARB_HEAD *head" +.Ft "bool" +.Fn ARB_EMPTY "ARB_HEAD *head" +.Ft "bool" +.Fn ARB_FULL "ARB_HEAD *head" +.Ft "int<8|16|32>_t" +.Fn ARB_CURNODES "ARB_HEAD *head" +.Ft "int<8|16|32>_t" +.Fn ARB_MAXNODES "ARB_HEAD *head" +.Ft "struct TYPE *" +.Fn ARB_NEXT NAME "ARB_HEAD *head" "struct TYPE *elm" +.Ft "struct TYPE *" +.Fn ARB_PREV NAME "ARB_HEAD *head" "struct TYPE *elm" +.Ft "struct TYPE *" +.Fn ARB_MIN NAME "ARB_HEAD *head" +.Ft "struct TYPE *" +.Fn ARB_MAX NAME "ARB_HEAD *head" +.Ft "struct TYPE *" +.Fn ARB_FIND NAME "ARB_HEAD *head" "struct TYPE *elm" +.Ft "struct TYPE *" +.Fn ARB_NFIND NAME "ARB_HEAD *head" "struct TYPE *elm" +.Ft "struct TYPE *" +.Fn ARB_LEFT "struct TYPE *elm" "ARB_ENTRY NAME" +.Ft "int<8|16|32>_t" +.Fn ARB_LEFTIDX "struct TYPE *elm" "ARB_ENTRY NAME" +.Ft "struct TYPE *" +.Fn ARB_RIGHT "struct TYPE *elm" "ARB_ENTRY NAME" +.Ft "int<8|16|32>_t" +.Fn ARB_RIGHTIDX "struct TYPE *elm" "ARB_ENTRY NAME" +.Ft "struct TYPE *" +.Fn ARB_PARENT "struct TYPE *elm" "ARB_ENTRY NAME" +.Ft "int<8|16|32>_t" +.Fn ARB_PARENTIDX "struct TYPE *elm" "ARB_ENTRY NAME" +.Ft "struct TYPE *" +.Fn ARB_GETFREE "ARB_HEAD *head" "FIELD" +.Ft "int<8|16|32>_t" +.Fn ARB_FREEIDX "ARB_HEAD *head" +.Fn ARB_FOREACH VARNAME NAME "ARB_HEAD *head" +.Fn ARB_FOREACH_FROM "VARNAME" "NAME" "POS_VARNAME" +.Fn ARB_FOREACH_SAFE "VARNAME" "NAME" "ARB_HEAD *head" "TEMP_VARNAME" +.Fn ARB_FOREACH_REVERSE VARNAME NAME "ARB_HEAD *head" +.Fn ARB_FOREACH_REVERSE_FROM "VARNAME" "NAME" "POS_VARNAME" +.Fn ARB_FOREACH_REVERSE_SAFE "VARNAME" "NAME" "ARB_HEAD *head" "TEMP_VARNAME" +.Ft void +.Fn ARB_INIT "struct TYPE *elm" "FIELD" "ARB_HEAD *head" "int<8|16|32>_t maxnodes" +.Ft "struct TYPE *" +.Fn ARB_INSERT NAME "ARB_HEAD *head" "struct TYPE *elm" +.Ft "struct TYPE *" +.Fn ARB_REMOVE NAME "ARB_HEAD *head" "struct TYPE *elm" +.Ft "struct TYPE *" +.Fn ARB_REINSERT NAME "ARB_HEAD *head" "struct TYPE *elm" +.Ft void +.Fn ARB_RESET_TREE "ARB_HEAD *head" NAME "int<8|16|32>_t maxnodes" +.Sh DESCRIPTION +These macros define data structures for and array-based red-black trees. +They use a single, continuous chunk of memory, and are useful +e.g., when the tree needs to be transferred between userspace and kernel. +.Pp +In the macro definitions, +.Fa TYPE +is the name tag of a user defined structure that must contain a field of type +.Vt ARB_ENTRY , +named +.Fa ENTRYNAME . +The argument +.Fa HEADNAME +is the name tag of a user defined structure that must be declared +using the +.Fn ARB_HEAD +macro. +The argument +.Fa NAME +has to be a unique name prefix for every tree that is defined. +.Pp +The function prototypes are declared with +.Fn ARB_PROTOTYPE , +or +.Fn ARB_PROTOTYPE_STATIC . +The function bodies are generated with +.Fn ARB_GENERATE , +or +.Fn ARB_GENERATE_STATIC . +See the examples below for further explanation of how these macros are used. +.Pp +A red-black tree is a binary search tree with the node color as an +extra attribute. +It fulfills a set of conditions: +.Bl -enum -offset indent +.It +Every search path from the root to a leaf consists of the same number of +black nodes. +.It +Each red node (except for the root) has a black parent. +.It +Each leaf node is black. +.El +.Pp +Every operation on a red-black tree is bounded as +.Fn O "lg n" . +The maximum height of a red-black tree is +.Fn 2lg "n + 1" . +.Pp +.Fn ARB_* +trees require entries to be allocated as an array, and uses array +indices to link entries together. +The maximum number of +.Fn ARB_* +tree entries is therefore constrained by the minimum of array size and choice of +signed integer data type used to store array indices. +Use +.Fn ARB_ALLOCSIZE +to compute the size of memory chunk to allocate. +.Pp +A red-black tree is headed by a structure defined by the +.Fn ARB_HEAD +macro. +A +structure is declared with either of the following: +.Bd -ragged -offset indent +.Fn ARB<8|16|32>_HEAD HEADNAME TYPE +.Va head ; +.Ed +.Pp +where +.Fa HEADNAME +is the name of the structure to be defined, and struct +.Fa TYPE +is the type of the elements to be inserted into the tree. +.Pp +The +.Fn ARB_HEAD +variant includes a suffix denoting the signed integer data type size +.Pq in bits +used to store array indices. +For example, +.Fn ARB_HEAD8 +creates a red-black tree head structure with 8-bit signed array indices capable +of indexing up to 128 entries. +.Pp +The +.Fn ARB_ENTRY +macro declares a structure that allows elements to be connected in the tree. +Similarly to the +.Fn ARB<8|16|32>_HEAD +macro, the +.Fn ARB_ENTRY +variant includes a suffix denoting the signed integer data type size +.Pq in bits +used to store array indices. +Entries should use the same number of bits as the tree head structure they will +be linked into. +.Pp +In order to use the functions that manipulate the tree structure, +their prototypes need to be declared with the +.Fn ARB_PROTOTYPE +or +.Fn ARB_PROTOTYPE_STATIC +macro, +where +.Fa NAME +is a unique identifier for this particular tree. +The +.Fa TYPE +argument is the type of the structure that is being managed +by the tree. +The +.Fa FIELD +argument is the name of the element defined by +.Fn ARB_ENTRY . +Individual prototypes can be declared with +.Fn ARB_PROTOTYPE_INSERT , +.Fn ARB_PROTOTYPE_INSERT_COLOR , +.Fn ARB_PROTOTYPE_REMOVE , +.Fn ARB_PROTOTYPE_REMOVE_COLOR , +.Fn ARB_PROTOTYPE_FIND , +.Fn ARB_PROTOTYPE_NFIND , +.Fn ARB_PROTOTYPE_NEXT , +.Fn ARB_PROTOTYPE_PREV , +.Fn ARB_PROTOTYPE_MINMAX , +and +.Fn ARB_PROTOTYPE_REINSERT +in case not all functions are required. +The individual prototype macros expect +.Fa NAME , +.Fa TYPE , +and +.Fa ATTR +arguments. +The +.Fa ATTR +argument must be empty for global functions or +.Fa static +for static functions. +.Pp +The function bodies are generated with the +.Fn ARB_GENERATE +or +.Fn ARB_GENERATE_STATIC +macro. +These macros take the same arguments as the +.Fn ARB_PROTOTYPE +and +.Fn ARB_PROTOTYPE_STATIC +macros, but should be used only once. +As an alternative individual function bodies are generated with the +.Fn ARB_GENERATE_INSERT , +.Fn ARB_GENERATE_INSERT_COLOR , +.Fn ARB_GENERATE_REMOVE , +.Fn ARB_GENERATE_REMOVE_COLOR , +.Fn ARB_GENERATE_FIND , +.Fn ARB_GENERATE_NFIND , +.Fn ARB_GENERATE_NEXT , +.Fn ARB_GENERATE_PREV , +.Fn ARB_GENERATE_MINMAX , +and +.Fn ARB_GENERATE_REINSERT +macros. +.Pp +Finally, +the +.Fa CMP +argument is the name of a function used to compare tree nodes +with each other. +The function takes two arguments of type +.Vt "struct TYPE *" . +If the first argument is smaller than the second, the function returns a +value smaller than zero. +If they are equal, the function returns zero. +Otherwise, it should return a value greater than zero. +The compare +function defines the order of the tree elements. +.Pp +The +.Fn ARB_INIT +macro initializes the tree referenced by +.Fa head , +with the array length of +.Fa maxnodes . +.Pp +The red-black tree can also be initialized statically by using the +.Fn ARB_INITIALIZER +macro: +.Bd -ragged -offset indent +.Fn ARB<8|16|32>_HEAD HEADNAME TYPE +.Va head += +.Fn ARB_INITIALIZER &head maxnodes ; +.Ed +.Pp +The +.Fn ARB_INSERT +macro inserts the new element +.Fa elm +into the tree. +.Pp +The +.Fn ARB_REMOVE +macro removes the element +.Fa elm +from the tree pointed by +.Fa head . +.Pp +The +.Fn ARB_FIND +and +.Fn ARB_NFIND +macros can be used to find a particular element in the tree. +.Bd -literal -offset indent +struct TYPE find, *res; +find.key = 30; +res = ARB_FIND(NAME, head, &find); +.Ed +.Pp +The +.Fn ARB_ROOT , +.Fn ARB_MIN , +.Fn ARB_MAX , +.Fn ARB_NEXT , +and +.Fn ARB_PREV +macros can be used to traverse the tree: +.Pp +.Dl "for (np = ARB_MIN(NAME, &head); np != NULL; np = ARB_NEXT(NAME, &head, np))" +.Pp +Or, for simplicity, one can use the +.Fn ARB_FOREACH +or +.Fn ARB_FOREACH_REVERSE +macro: +.Bd -ragged -offset indent +.Fn ARB_FOREACH np NAME head +.Ed +.Pp +The macros +.Fn ARB_FOREACH_SAFE +and +.Fn ARB_FOREACH_REVERSE_SAFE +traverse the tree referenced by head +in a forward or reverse direction respectively, +assigning each element in turn to np. +However, unlike their unsafe counterparts, +they permit both the removal of np +as well as freeing it from within the loop safely +without interfering with the traversal. +.Pp +Both +.Fn ARB_FOREACH_FROM +and +.Fn ARB_FOREACH_REVERSE_FROM +may be used to continue an interrupted traversal +in a forward or reverse direction respectively. +The head pointer is not required. +The pointer to the node from where to resume the traversal +should be passed as their last argument, +and will be overwritten to provide safe traversal. +.Pp +The +.Fn ARB_EMPTY +macro should be used to check whether a red-black tree is empty. +.Pp +Given that ARB trees have an intrinsic upper bound on the number of entries, +some ARB-specific additional macros are defined. +The +.Fn ARB_FULL +macro returns a boolean indicating whether the current number of tree entries +equals the tree's maximum. +The +.Fn ARB_CURNODES +and +.Fn ARB_MAXNODES +macros return the current and maximum number of entries respectively. +The +.Fn ARB_GETFREE +macro returns a pointer to the next free entry in the array of entries, ready to +be linked into the tree. +The +.Fn ARB_INSERT +returns +.Dv NULL +if the element was inserted in the tree successfully, otherwise they +return a pointer to the element with the colliding key. +.Pp +Accordingly, +.Fn ARB_REMOVE +returns the pointer to the removed element otherwise they return +.Dv NULL +to indicate an error. +.Pp +The +.Fn ARB_REINSERT +macro updates the position of the element +.Fa elm +in the tree. +This must be called if a member of a +.Nm tree +is modified in a way that affects comparison, such as by modifying +a node's key. +This is a lower overhead alternative to removing the element +and reinserting it again. +.Pp +The +.Fn ARB_RESET_TREE +macro discards the tree topology. +It does not modify embedded object values or the free list. +.Sh SEE ALSO +.Xr queue 3 , +.Xr tree 3 +.Sh HISTORY +The +.Nm ARB +macros first appeared in +.Fx 13.0 . +.Sh AUTHORS +The +.Nm ARB +macros were implemented by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org , +based on +.Xr tree 3 +macros written by +.An Niels Provos . diff --git a/static/freebsd/man3/assert.3 b/static/freebsd/man3/assert.3 new file mode 100644 index 00000000..f219aa1d --- /dev/null +++ b/static/freebsd/man3/assert.3 @@ -0,0 +1,136 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 20, 2021 +.Dt ASSERT 3 +.Os +.Sh NAME +.Nm assert , +.Nm static_assert +.Nd expression verification macro +.Sh SYNOPSIS +.In assert.h +.Fn assert expression +.Fn static_assert expression +.Fn static_assert expression message +.Sh DESCRIPTION +The +.Fn assert +macro tests the given +.Ar expression +and if it is false, +the calling process is terminated. +A diagnostic message is written to +.Dv stderr +and the function +.Xr abort 3 +is called, effectively terminating the program. +.Pp +If +.Ar expression +is true, +the +.Fn assert +macro does nothing. +.Pp +The +.Fn assert +macro +may be removed at compile time by defining +.Dv NDEBUG +as a macro +(e.g., by using the +.Xr cc 1 +option +.Fl D Ns Dv NDEBUG ) . +Unlike most other include files, +.In assert.h +may be included multiple times. +Each time whether or not +.Dv NDEBUG +is defined determines the behavior of assert from that point forward +until the end of the unit or another include of +.In assert.h . +.Pp +The +.Fn assert +macro should only be used for ensuring the developer's expectations +hold true. +It is not appropriate for regular run-time error detection. +.Pp +The +.Fn static_assert +macro expands to +.Fn _Static_assert , +and, contrarily to +.Fn assert , +makes assertions at compile-time. +Once the constraint is violated, the compiler produces a diagnostic +message including the string literal message, if provided. +The initial form of the +.Fn _Static_assert +containing a string literal message was introduced in C11 standard, and +the other form with no string literal is to be implemented by C2x and +some compilers may lack its adoption at present. +.Sh EXAMPLES +The assertion: +.Dl "assert(1 == 0);" +generates a diagnostic message similar to the following: +.Dl "Assertion failed: (1 == 0), function main, file main.c, line 100." +.Pp +The following assert tries to assert there was no partial read: +.Dl "assert(read(fd, buf, nbytes) == nbytes);" +However, there are two problems. +First, it checks for normal conditions, rather than conditions that +indicate a bug. +Second, the code will disappear if +.Dv NDEBUG +is defined, changing the semantics of the program. +.Pp +The following asserts that the size of the S structure is 16. +Otherwise, it produces a diagnostic message which points at the +constraint and includes the provided string literal: +.Dl "static_assert(sizeof(struct S) == 16, ""size mismatch"");" +If none is provided, it only points at the constraint. +.Sh SEE ALSO +.Xr abort2 2 , +.Xr abort 3 +.Sh STANDARDS +The +.Fn assert +macro conforms to +.St -isoC-99 . +.Pp +The +.Fn static_assert +macro conforms to +.St -isoC-2011 . +.Sh HISTORY +An +.Nm +macro appeared in +.At v7 . diff --git a/static/freebsd/man3/bitstring.3 b/static/freebsd/man3/bitstring.3 new file mode 100644 index 00000000..87ba9a24 --- /dev/null +++ b/static/freebsd/man3/bitstring.3 @@ -0,0 +1,470 @@ +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Paul Vixie. +.\" 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" +.\" Copyright (c) 2014,2016 Spectra Logic Corporation +.\" 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, +.\" without modification. +.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer +.\" substantially similar to the "NO WARRANTY" disclaimer below +.\" ("Disclaimer") and any redistribution must be conditioned upon +.\" including a substantially similar Disclaimer requirement for further +.\" binary redistribution. +.\" +.\" NO WARRANTY +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR 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 DAMAGES. +.\" +.Dd November 21, 2023 +.Dt BITSTRING 3 +.Os +.Sh NAME +.Nm bit_alloc , +.Nm bit_clear , +.Nm bit_count , +.Nm bit_decl , +.Nm bit_ffc , +.Nm bit_ffs , +.Nm bit_ff_at , +.Nm bit_ffc_at , +.Nm bit_ffs_at , +.Nm bit_ffc_area , +.Nm bit_ffs_area , +.Nm bit_ff_area_at , +.Nm bit_ffc_area_at , +.Nm bit_ffs_area_at , +.Nm bit_nclear , +.Nm bit_nset , +.Nm bit_ntest , +.Nm bit_set , +.Nm bit_test , +.Nm bitstr_size +.Nd bit-string manipulation functions and macros +.Sh SYNOPSIS +.In bitstring.h +.Ft bitstr_t * +.Fn bit_alloc "size_t nbits" +.Ft void +.Fn bit_decl "bitstr_t *name" "size_t nbits" +.Ft void +.Fn bit_clear "bitstr_t *name" "size_t bit" +.Ft void +.Fn bit_count "bitstr_t *name" "size_t count" "size_t nbits" "ssize_t *value" +.Ft void +.Fn bit_ffc "bitstr_t *name" "size_t nbits" "ssize_t *value" +.Ft void +.Fn bit_ffs "bitstr_t *name" "size_t nbits" "ssize_t *value" +.Ft void +.Fn bit_ffc_at "bitstr_t *name" "size_t start" "size_t nbits" "ssize_t *value" +.Ft void +.Fn bit_ffs_at "bitstr_t *name" "size_t start" "size_t nbits" "ssize_t *value" +.Ft void +.Fn bit_ff_at "bitstr_t *name" "size_t start" "size_t nbits" "int match" "ssize_t *value" +.Ft void +.Fn bit_ffc_area "bitstr_t *name" "size_t nbits" "size_t size" "ssize_t *value" +.Ft void +.Fn bit_ffs_area "bitstr_t *name" "size_t nbits" "size_t size" "ssize_t *value" +.Ft void +.Fn bit_ffc_area_at "bitstr_t *name" "size_t start" "size_t nbits" "size_t size" "ssize_t *value" +.Ft void +.Fn bit_ffs_area_at "bitstr_t *name" "size_t start" "size_t nbits" "size_t size" "ssize_t *value" +.Ft void +.Fn bit_ff_area_at "bitstr_t *name" "size_t start" "size_t nbits" "size_t size" "int match" "ssize_t *value" +.Fn bit_foreach "bitstr_t *name" "size_t nbits" "size_t var" +.Fn bit_foreach_at "bitstr_t *name" "size_t start" "size_t nbits" "size_t var" +.Fn bit_foreach_unset "bitstr_t *name" "size_t nbits" "size_t var" +.Fn bit_foreach_unset_at "bitstr_t *name" "size_t start" "size_t nbits" "size_t var" +.Ft void +.Fn bit_nclear "bitstr_t *name" "size_t start" "size_t stop" +.Ft void +.Fn bit_nset "bitstr_t *name" "size_t start" "size_t stop" +.Ft int +.Fn bit_ntest "bitstr_t *name" "size_t start" "size_t stop" "int match" +.Ft void +.Fn bit_set "bitstr_t *name" "size_t bit" +.Ft int +.Fn bitstr_size "size_t nbits" +.Ft int +.Fn bit_test "bitstr_t *name" "size_t bit" +.Sh DESCRIPTION +These macros operate on strings of bits. +.Pp +The function +.Fn bit_alloc +returns a pointer of type +.Dq Fa "bitstr_t *" +to sufficient space to store +.Fa nbits +bits, or +.Dv NULL +if no space is available. +If successful, the returned bit string is initialized with all bits cleared. +.Pp +The macro +.Fn bit_decl +declares a bit string with sufficient space to store +.Fa nbits +bits. +.Fn bit_decl +may be used to include statically sized bit strings in structure +definitions or to create bit strings on the stack. +Users of this macro are responsible for initialization of the bit string, +typically via a global initialization of the containing struct or use of the +.Fn bit_nset +or +.Fn bin_nclear +functions. +.Pp +The macro +.Fn bitstr_size +returns the number of bytes necessary to store +.Fa nbits +bits. +This is useful for copying bit strings. +.Pp +The functions +.Fn bit_clear +and +.Fn bit_set +clear or set the zero-based numbered bit +.Fa bit , +in the bit string +.Ar name . +.Pp +The +.Fn bit_nset +and +.Fn bit_nclear +functions +set or clear the zero-based numbered bits from +.Fa start +through +.Fa stop +in the bit string +.Ar name . +.Pp +The +.Fn bit_test +function +evaluates to non-zero if the zero-based numbered bit +.Fa bit +of bit string +.Fa name +is set, and zero otherwise. +.Pp +The +.Fn bit_ntest +function +evaluates to non-zero if the zero-based numbered bits from +.Fa start +through +.Fa stop +in the bit string +.Ar name +all have the value +.Ar match . +.Pp +The function +.Fn bit_ffc +stores in the location referenced by +.Fa value +the zero-based number of the first bit not set in the array of +.Fa nbits +bits referenced by +.Fa name . +If all bits are set, the location referenced by +.Fa value +is set to \-1. +.Pp +The +.Fn bit_ffs +function +stores in the location referenced by +.Fa value +the zero-based number of the first bit set in the array of +.Fa nbits +bits referenced by +.Fa name . +If no bits are set, the location referenced by +.Fa value +is set to \-1. +.Pp +The function +.Fn bit_ffc_at +stores in the location referenced by +.Fa value +the zero-based number of the first bit not set in the array of +.Fa nbits +bits referenced by +.Fa name , +at or after the zero-based bit index +.Fa start . +If all bits at or after +.Fa start +are set, the location referenced by +.Fa value +is set to \-1. +.Pp +The +.Fn bit_ffs_at +function +stores in the location referenced by +.Fa value +the zero-based number of the first bit set in the array of +.Fa nbits +bits referenced by +.Fa name , +at or after the zero-based bit index +.Fa start . +If no bits are set after +.Fa start , +the location referenced by +.Fa value +is set to \-1. +.Pp +The +.Fn bit_ff_at +function +stores in the location referenced by +.Fa value +the zero-based number of the first bit in the array of +.Fa nbits +bits referenced by +.Fa name , +at or after the zero-based bit index +.Fa start +that has value +.Fa match . +If no bits after +.Fa start +match that value, the location referenced by +.Fa value +is set to \-1. +.Pp +The +.Fn bit_ffc_area +function stores in the location referenced by +.Fa value +the zero-based number of the first bit beginning a sequence of unset bits of +at least +.Fa size +unset bits in the array of +.Fa nbits +bits referenced by +.Fa name . +If no sequence of contiguous unset bits of the specified +.Fa size +can be found, the location referenced by +.Fa value +is set to \-1. +.Pp +The +.Fn bit_ffs_area +function stores in the location referenced by +.Fa value +the zero-based number of the first bit beginning a sequence of set bits of +at least +.Fa size +set bits in the array of +.Fa nbits +bits referenced by +.Fa name . +If no sequence of contiguous set bits of the specified +.Fa size +can be found, the location referenced by +.Fa value +is set to \-1. +.Pp +The +.Fn bit_ffc_area_at +function stores in the location referenced by +.Fa value +the zero-based number of the first bit beginning a sequence of unset bits of +at least +.Fa size +unset bits in the array of +.Fa nbits +bits referenced by +.Fa name , +at or after the zero-based bit index +.Fa start . +If no sequence of contiguous unset bits of the specified +.Fa size +can be found at or after +.Fa start , +the location referenced by +.Fa value +is set to \-1. +.Pp +The +.Fn bit_ffs_area_at +function stores in the location referenced by +.Fa value +the zero-based number of the first bit beginning a sequence of set bits of +at least +.Fa size +set bits in the array of +.Fa nbits +bits referenced by +.Fa name , +at or after the zero-based bit index +.Fa start . +If no sequence of contiguous set bits of the specified +.Fa size +can be found at or after +.Fa start , +the location referenced by +.Fa value +is set to \-1. +.Pp +The +.Fn bit_ff_area_at +function stores in the location referenced by +.Fa value +the zero-based number of the first bit beginning a sequence of bits of +at least +.Fa size +bits in the array of +.Fa nbits +bits referenced by +.Fa name , +at or after the zero-based bit index +.Fa start +in which all bits have the value +.Fa match . +If no sequence of contiguous such bits of the specified +.Fa size +can be found at or after +.Fa start , +the location referenced by +.Fa value +is set to \-1. +.Pp +The +.Fn bit_count +function stores in the location referenced by +.Fa value +the number of bits set in the array of +.Fa nbits +bits referenced by +.Fa name , +at or after the zero-based bit index +.Fa start . +.Pp +The macro +.Fn bit_foreach +traverses all set bits in the array of +.Fa nbits +referenced by +.Fa name +in the forward direction, assigning each location in turn to +.Fa var . +.Pp +The macro +.Fn bit_foreach_at +traverses all set bits in the array of +.Fa nbits +referenced by +.Fa name +in the forward direction at or after the zero-based bit index +.Fa start , +assigning each location in turn to +.Fa var . +.Pp +The macro +.Fn bit_foreach_unset +traverses all unset bits in the array of +.Fa nbits +referenced by +.Fa name +in the forward direction, assigning each location in turn to +.Fa var . +.Pp +The macro +.Fn bit_foreach_unset_at +traverses all unset bits in the array of +.Fa nbits +referenced by +.Fa name +in the forward direction at or after the zero-based bit index +.Fa start , +assigning each location in turn to +.Fa var . +.Pp +The arguments in bit string macros are evaluated only once and may safely +have side effects. +.Sh EXAMPLES +.Bd -literal -offset indent +#include +#include + +\&... +#define LPR_BUSY_BIT 0 +#define LPR_FORMAT_BIT 1 +#define LPR_DOWNLOAD_BIT 2 +\&... +#define LPR_AVAILABLE_BIT 9 +#define LPR_MAX_BITS 10 + +make_lpr_available() +{ + bitstr_t bit_decl(bitlist, LPR_MAX_BITS); + ... + bit_nclear(bitlist, 0, LPR_MAX_BITS - 1); + ... + if (!bit_test(bitlist, LPR_BUSY_BIT)) { + bit_clear(bitlist, LPR_FORMAT_BIT); + bit_clear(bitlist, LPR_DOWNLOAD_BIT); + bit_set(bitlist, LPR_AVAILABLE_BIT); + } +} +.Ed +.Sh SEE ALSO +.Xr malloc 3 , +.Xr stdbit 3 , +.Xr bitset 9 +.Sh HISTORY +The +.Nm bitstring +functions first appeared in +.Bx 4.4 . diff --git a/static/freebsd/man3/end.3 b/static/freebsd/man3/end.3 new file mode 100644 index 00000000..53800342 --- /dev/null +++ b/static/freebsd/man3/end.3 @@ -0,0 +1,76 @@ +.\" Copyright (c) 1986 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 August 28, 2000 +.Dt END 3 +.Os +.Sh NAME +.Nm end , +.Nm etext , +.Nm edata +.Nd end boundaries of image segments +.Sh SYNOPSIS +.Vt extern end ; +.Vt extern etext ; +.Vt extern edata ; +.Sh DESCRIPTION +The globals +.Va end , etext +and +.Va edata +are program segment end addresses. +.Pp +.Va etext +is the first address after the end of the text segment. +.Pp +.Va edata +is the first address after the end of the initialized data segment. +.Pp +.Va end +is the first address after the end of the data segment +.Pq Tn BSS +when the program is loaded. +Use the +.Xr sbrk 2 +.\".Fn sbrk 0 +system call with zero as its argument to find the current end of the +data segment. +.Sh SEE ALSO +.Xr sbrk 2 , +.Xr malloc 3 , +.Xr a.out 5 +.Sh HISTORY +An +.Nm +manual page appeared in +.At v6 . +.Sh BUGS +Traditionally, no variable existed that pointed to the start of the +text segment because the text segment always started at address zero. +Although it is no longer valid to make this assumption, no +variable similar to the ones documented above exists to point to the +start of the text segment. diff --git a/static/freebsd/man3/fpgetround.3 b/static/freebsd/man3/fpgetround.3 new file mode 100644 index 00000000..c827122e --- /dev/null +++ b/static/freebsd/man3/fpgetround.3 @@ -0,0 +1,173 @@ +.\" Copyright (c) 1993 Andrew Moore, Talke Studio +.\" 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 December 3, 2010 +.Dt FPGETROUND 3 +.Os +.Sh NAME +.Nm fpgetround , +.Nm fpsetround , +.Nm fpsetprec , +.Nm fpgetprec , +.Nm fpgetmask , +.Nm fpsetmask , +.Nm fpgetsticky , +.Nm fpresetsticky +.Nd IEEE floating point interface +.Sh SYNOPSIS +.In ieeefp.h +.Bd -literal +typedef enum { + FP_RN, /* round to nearest */ + FP_RM, /* round down to minus infinity */ + FP_RP, /* round up to plus infinity */ + FP_RZ /* truncate */ +} fp_rnd_t; +.Ed +.Ft fp_rnd_t +.Fn fpgetround void +.Ft fp_rnd_t +.Fn fpsetround "fp_rnd_t direction" +.Bd -literal +typedef enum { + FP_PS, /* 24 bit (single-precision) */ + FP_PRS, /* reserved */ + FP_PD, /* 53 bit (double-precision) */ + FP_PE /* 64 bit (extended-precision) */ +} fp_prec_t; +.Ed +.Ft fp_prec_t +.Fn fpgetprec void +.Ft fp_prec_t +.Fn fpsetprec "fp_prec_t precision" +.Bd -literal +#define fp_except_t int +#define FP_X_INV 0x01 /* invalid operation */ +#define FP_X_DNML 0x02 /* denormal */ +#define FP_X_DZ 0x04 /* zero divide */ +#define FP_X_OFL 0x08 /* overflow */ +#define FP_X_UFL 0x10 /* underflow */ +#define FP_X_IMP 0x20 /* (im)precision */ +#define FP_X_STK 0x40 /* stack fault */ +.Ed +.Ft fp_except_t +.Fn fpgetmask void +.Ft fp_except_t +.Fn fpsetmask "fp_except_t mask" +.Ft fp_except_t +.Fn fpgetsticky void +.Ft fp_except_t +.Fn fpresetsticky "fp_except_t sticky" +.Sh DESCRIPTION +The routines described herein are deprecated. +New code should use the functionality provided by +.Xr fenv 3 . +.Pp +When a floating point exception is detected, the exception sticky flag is +set and the exception mask is tested. +If the mask is set, then a trap +occurs. +These routines allow both setting the floating point exception +masks, and resetting the exception sticky flags after an exception is +detected. +In addition, they allow setting the floating point rounding mode +and precision. +.Pp +The +.Fn fpgetround +function +returns the current floating point rounding mode. +.Pp +The +.Fn fpsetround +function +sets the floating point rounding mode and returns +the previous mode. +.Pp +The +.Fn fpgetprec +function +returns the current floating point precision. +.Pp +The +.Fn fpsetprec +function +sets the floating point precision and returns +the previous precision. +.Pp +The +.Fn fpgetmask +function +returns the current floating point exception masks. +.Pp +The +.Fn fpsetmask +function +sets the floating point exception masks and returns the +previous masks. +.Pp +The +.Fn fpgetsticky +function +returns the current floating point sticky flags. +.Pp +The +.Fn fpresetsticky +function +clears the floating point sticky flags and returns +the previous flags. +.Pp +Sample code which prevents a trap on divide-by-zero: +.Bd -literal -offset indent +fpsetmask(~FP_X_DZ); +a = 1.0; +b = 0; +c = a / b; +fpresetsticky(FP_X_DZ); +fpsetmask(FP_X_DZ); +.Ed +.Sh IMPLEMENTATION NOTES +The +.Fn fpgetprec +and +.Fn fpsetprec +functions provide functionality unavailable on many platforms. +At present, they are implemented only on the i386 and amd64 platforms. +Changing precision is not a supported feature: +it may be ineffective when code is compiled to take advantage of SSE, +and many library functions and compiler optimizations depend upon the +default precision for correct behavior. +.Sh SEE ALSO +.Xr fenv 3 , +.Xr isnan 3 +.Sh HISTORY +These routines are based on SysV/386 routines of the same name. +.Sh CAVEATS +After a floating point exception and before a mask is set, the sticky +flags must be reset. +If another exception occurs before the sticky +flags are reset, then a wrong exception type may be signaled. diff --git a/static/freebsd/man3/intro.3 b/static/freebsd/man3/intro.3 new file mode 100644 index 00000000..952183d7 --- /dev/null +++ b/static/freebsd/man3/intro.3 @@ -0,0 +1,384 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 November 10, 2025 +.Dt INTRO 3 +.Os +.Sh NAME +.Nm intro +.Nd introduction to the C libraries +.Sh SYNOPSIS +.Nm cc +.Op Ar flags +.Ar +.Op Fl llibrary +.Sh DESCRIPTION +This section provides an overview of the C +library functions, their error returns and other +common definitions and concepts. +Most of these functions are available from the C library, +.Em libc . +Other libraries, such as the math library, +.Em libm , +must be indicated at compile time with the +.Fl l +option of the compiler. +.Pp +The various libraries (followed by the loader flag): +.Bl -tag -width "libbluetooth" +.It Em libbluetooth +.Pq Fl l Ns Ar bluetooth +The bluetooth library. +See +.Xr bluetooth 3 . +.It Em libc +.Pq Fl l Ns Ar c +Standard C library functions. +When using the C compiler +.Xr cc 1 , +it is not necessary +to supply the loader flag +.Fl l Ns Ar c +for these functions. +There are several `libraries' or groups of functions included inside of +.Em libc : +.Bl -tag -width "XXXXXX" +.It standard I/O routines +see +.Xr stdio 3 +.It database routines +see +.Xr db 3 +.It bit string operators +see +.Xr bitstring 3 +.It bit and byte utilities +see +.Xr stdbit 3 +.It string operators +see +.Xr string 3 +and +.Xr bstring 3 +.It character tests and character operators +see +.Xr ctype 3 +.It storage allocation +see +.Xr mpool 3 +.It regular-expressions +see +.Xr regex 3 +.It remote procedure calls (RPC) +see +.Xr rpc 3 +.It time functions +see +.Xr time 3 +.It signal handling +see +.Xr signal 3 +.El +.It Em libcalendar +.Pq Fl l Ns Ar calendar +The calendar arithmetic library. +See +.Xr calendar 3 . +.It Em libcam +.Pq Fl l Ns Ar cam +The common access method user library. +See +.Xr cam 3 . +.It Em libcrypt +.Pq Fl l Ns Ar crypt +The crypt library. +See +.Xr crypt 3 . +.It Em libcurses +.Pq Fl l Ns Ar curses Fl l Ns Ar termcap +Terminal independent screen management routines +for two dimensional non-bitmap display terminals. +See +.Xr ncurses 3 . +.It Em libcuse +.Pq Fl l Ns Ar cuse +The userland character device library. +See +.Xr cuse 3 . +.It Em libcompat +.Pq Fl l Ns Ar compat +Functions which are obsolete but are available for compatibility with +.Bx 4.3 . +In particular, +a number of system call interfaces provided in previous releases of +.Bx +have been included for source code compatibility. +Use of these routines should, for the most part, be avoided. +The manual page entry for each compatibility routine +indicates the proper interface to use. +.It Em libdevinfo +.Pq Fl l Ns Ar devinfo +The Device and Resource Information Utility library. +See +.Xr devinfo 3 . +.It Em libdevstat +.Pq Fl l Ns Ar devstat +The Device Statistics library. +See +.Xr devstat 3 . +.It Em libdwarf +.Pq Fl l Ns Ar dwarf +The DWARF access library. +See +.Xr dwarf 3 . +.It Em libelf +.Pq Fl l Ns Ar elf +The ELF access library. +See +.Xr elf 3 . +.It Em libfetch +.Pq Fl l Ns Ar fetch +The file transfer library. +See +.Xr fetch 3 . +.It Em libfigpar +.Pq Fl l Ns Ar figpar +The configuration file parsing library. +See +.Xr figpar 3 . +.It Em libgpio +.Pq Fl l Ns Ar gpio +The general-purpose input output library (GPIO). +See +.Xr gpio 3 . +.It Em libgssapi +.Pq Fl l Ns Ar gssapi +The generic security service application programming +interface. +See +.Xr gssapi 3 . +.It Em libjail +.Pq Fl l Ns Ar jail +The jail library. +See +.Xr jail 3 . +.It Em libkvm +.Pq Fl l Ns Ar kvm +Functions used to access kernel memory are in this library. +They can be used +against both a running system and a crash dump. +See +.Xr kvm 3 . +.It Em libl +.Pq Fl l Ns Ar l +The library for +.Xr lex 1 . +.It Em libm +.Pq Fl l Ns Ar m +The math library. +See +.Xr math 3 . +.It Em libmd +.Pq Fl l Ns Ar md +The message digest library. +See +.Xr md4 3 , +.Xr md5 3 , +.Xr sha 3 , +.Xr sha256 3 , +.Xr sha512 3 , +.Xr ripemd 3 , +.Xr skein 3 . +.It Em libmp +.Pq Fl l Ns Ar mp +.It Em libpam +.Pq Fl l Ns Ar pam +The pluggable authentication module library. +See +.Xr pam 3 . +.It Em libpcap +.Pq Fl l Ns Ar pcap +The packet capture library. +See +.Xr pcap 3 . +.It Em libpmc +.Pq Fl l Ns Ar pmc +The performance counters library. +See +.Xr pmc 3 . +.It Em libpthread +.Pq Fl l Ns Ar pthread +The POSIX threads library. +See +.Xr pthread 3 . +.It Em libstdthreads +.Pq Fl l Ns Ar stdthreads +The ISO C11 standard +.In threads.h +library. +See +.Xr thrd_create 3 . +.It Em libsysdecode +.Pq Fl l Ns Ar sysdecode +The system argument decoding library. +See +.Xr sysdecode 3 . +.It Em libtermcap +.Pq Fl l Ns Ar termcap +The terminal independent operation library package. +See +.Xr termcap 3 . +.It Em libusb +.Pq Fl l Ns Ar usb +The USB access library. +See +.Xr usb 3 . +.It Em libvgl +.Pq Fl l Ns Ar vgl +The video graphics library. +See +.Xr vgl 3 . +.It Em liby +.Pq Fl l Ns Ar y +The library for +.Xr yacc 1 . +.It Em libz +.Pq Fl l Ns Ar z +The general-purpose data compression library. +See +.Xr zlib 3 . +.El +.Sh FILES +.Bl -tag -width /usr/lib/libm_p.a -compact +.It Pa /usr/lib/libc.a +the C library +.It Pa /usr/lib/libm.a +the math library +.El +.Sh LIBRARY TYPES +The system libraries are located in +.Pa /lib +and +.Pa /usr/lib . +A library has the following naming convention: +.Bd -unfilled -offset indent +libc.so.7 +.Ed +.Pp +Libraries with an +.Sq .a +suffix are static. +When a program is linked against a static library, all necessary library code +will be included in the binary. +This means the binary can be run even when the libraries are unavailable. +However, it can be inefficient with both disk space and memory usage +during execution. +The C compiler, +.Xr cc 1 , +can be instructed to link statically by specifying the +.Fl static +flag. +.Pp +Libraries with a +.Sq .so.X +suffix are dynamic libraries. +When code is linked dynamically, the library code that the application needs +is not included in the binary. +Instead, data structures are added containing information about which dynamic +libraries to link with. +When the binary is executed, the run-time linker +.Xr ld.so 1 +reads these data structures and loads them into the +process virtual address space. +.Xr rtld 1 +loads the shared libraries when the program is executed. +.Pp +.Sq X +represents the library version number of the library. +In the example above, a binary linked with +.Pa libc.so.8 +would not be usable on a system where only +.Pa libc.so.7 +is available. +.Pp +The advantages of dynamic libraries are that multiple instances of the same +library can share address space, and the physical size of the binary is +smaller. +A namespace per shared library is available via hidden visibility, +allowing multiple compilation units in a library to share things without +making them available to other libraries. +It is possible to load libraries dynamically via +.Xr dlopen 3 . +The disadvantage is the added complexity that comes with loading the +libraries dynamically, and the extra time taken to load the libraries. +Of course, if the libraries are not available, the binary will be unable +to execute. +Calls across shared libraries are also slightly slower and cannot be +inlined, not even with link time optimization. +The C compiler, +.Xr cc 1 , +can be instructed to link dynamically by specifying the +.Fl shared +flag. +.Pp +Shared libraries, as well as static libraries on architectures which produce +position-independent executables +.Pq PIEs +by default, contain position-independent code +.Pq PIC . +Normally, compilers produce relocatable code. +Relocatable code needs to be modified at run-time, depending on where in +memory it is to be run. +The C compiler, +.Xr cc 1 , +can be instructed to generate PIC code by specifying the +.Fl fPIC +flag. +.Pp +Static libraries are generated using the +.Xr ar 1 +utility. +The libraries contain an index to the contents of the library, +stored within the library itself. +The index lists each symbol defined by a member of a library that is a +relocatable object file. +This speeds up linking to the library, and allows routines in the library +to call each other regardless of their placement within the library. +.Sh SEE ALSO +.Xr ar 1 , +.Xr cc 1 , +.Xr ld 1 , +.Xr nm 1 , +.Xr intro 2 , +.Xr math 3 , +.Xr stdio 3 , +.Xr make.conf 5 , +.Xr src.conf 5 +.Sh HISTORY +An +.Nm +manual appeared in +.At v7 . diff --git a/static/freebsd/man3/makedev.3 b/static/freebsd/man3/makedev.3 new file mode 100644 index 00000000..3c0e176a --- /dev/null +++ b/static/freebsd/man3/makedev.3 @@ -0,0 +1,100 @@ +.\" Copyright (c) 2008 Ed Schouten +.\" 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 August 3, 2017 +.Dt MAKEDEV 3 +.Os +.Sh NAME +.Nm makedev , +.Nm major , +.Nm minor +.Nd device number conversion +.Sh SYNOPSIS +.In sys/types.h +.Ft dev_t +.Fn makedev "int major" "int minor" +.Ft int +.Fn major "dev_t dev" +.Ft int +.Fn minor "dev_t dev" +.Sh DESCRIPTION +The +.Fn makedev +macro returns a device number created from the provided +.Fa major +and +.Fa minor +number. +The +.Fn major +and +.Fn minor +macros return the original numbers from the device number +.Fa dev . +In other words, for a value +.Va dev +of the type +.Vt dev_t , +and values +.Va ma , mi +of the type +.Vt int , +the assertions +.Dl dev == makedev(major(dev), minor(dev)) +.Dl ma == major(makedev(ma, mi)) +.Dl mi == minor(makedev(ma, mi)) +are valid. +.Pp +In previous implementations of +.Fx +all block and character devices were uniquely identified by a pair of +stable major and minor numbers. +The major number referred to a certain device class (e.g. disks, TTYs) +while the minor number identified an instance within the device class. +Later versions of +.Fx +automatically generate a unique device number for each character device +visible in +.Pa /dev/ . +These numbers are not divided in device classes and are not guaranteed +to be stable upon reboot or driver reload. +.Pp +On +.Fx +these macros are only used by utilities that need to exchange numbers +with other operating systems that may use different encodings for +.Vt dev_t , +but also applications that present these numbers to the user in a more +conventional way. +.Sh RETURN VALUES +The +.Fn major +and +.Fn minor +macros return numbers whose value can span the complete range of an +.Vt int . +.Sh SEE ALSO +.Xr mknod 2 , +.Xr devname 3 , +.Xr devfs 4 diff --git a/static/freebsd/man3/offsetof.3 b/static/freebsd/man3/offsetof.3 new file mode 100644 index 00000000..f757d58a --- /dev/null +++ b/static/freebsd/man3/offsetof.3 @@ -0,0 +1,45 @@ +.\" $OpenBSD: offsetof.3,v 1.2 2010/02/18 18:30:19 jmc Exp $ +.\" +.\" Copyright (c) 2010 Thomas Pfaff +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd February 18, 2010 +.Dt OFFSETOF 3 +.Os +.Sh NAME +.Nm offsetof +.Nd offset of a structure member +.Sh SYNOPSIS +.In stddef.h +.Ft size_t +.Fn offsetof "type" "member" +.Sh DESCRIPTION +The +.Fn offsetof +macro expands to an integer constant expression of type +.Ft size_t +and yields the offset, +in bytes, of the field +.Ar member +from the start of the structure +.Ar type . +.Pp +A compiler error will result if +.Ar member +is not aligned to a byte boundary (i.e. it is a bit-field). +.Sh STANDARDS +The +.Fn offsetof +macro conforms to +.St -ansiC . diff --git a/static/freebsd/man3/pthread.3 b/static/freebsd/man3/pthread.3 new file mode 100644 index 00000000..1cb13981 --- /dev/null +++ b/static/freebsd/man3/pthread.3 @@ -0,0 +1,552 @@ +.\" Copyright (c) 1996 John Birrell . +.\" 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 John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 REGENTS 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 October 12, 2021 +.Dt PTHREAD 3 +.Os +.Sh NAME +.Nm pthread +.Nd POSIX thread functions +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Sh DESCRIPTION +POSIX threads are a set of functions that support applications with +requirements for multiple flows of control, called +.Em threads , +within a process. +Multithreading is used to improve the performance of a +program. +.Pp +The POSIX thread functions are summarized in this section in the following +groups: +.Pp +.Bl -bullet -offset indent -compact +.It +Thread Routines +.It +Attribute Object Routines +.It +Mutex Routines +.It +Condition Variable Routines +.It +Read/Write Lock Routines +.It +Per-Thread Context Routines +.It +Cleanup Routines +.El +.Pp +.Fx +extensions to the POSIX thread functions are summarized in +.Xr pthread_np 3 . +.Ss Thread Routines +.Bl -tag -width indent +.It Xo +.Ft int +.Fo pthread_create +.Fa "pthread_t *thread" "const pthread_attr_t *attr" +.Fa "void *\*[lp]*start_routine\*[rp]\*[lp]void *\*[rp]" "void *arg" +.Fc +.Xc +Creates a new thread of execution. +.It Xo +.Ft int +.Fn pthread_cancel "pthread_t thread" +.Xc +Cancels execution of a thread. +.It Xo +.Ft int +.Fn pthread_detach "pthread_t thread" +.Xc +Marks a thread for deletion. +.It Xo +.Ft int +.Fn pthread_equal "pthread_t t1" "pthread_t t2" +.Xc +Compares two thread IDs. +.It Xo +.Ft void +.Fn pthread_exit "void *value_ptr" +.Xc +Terminates the calling thread. +.It Xo +.Ft int +.Fn pthread_join "pthread_t thread" "void **value_ptr" +.Xc +Causes the calling thread to wait for the termination of the specified thread. +.It Xo +.Ft int +.Fn pthread_kill "pthread_t thread" "int sig" +.Xc +Delivers a signal to a specified thread. +.It Xo +.Ft int +.Fn pthread_once "pthread_once_t *once_control" "void \*[lp]*init_routine\*[rp]\*[lp]void\*[rp]" +.Xc +Calls an initialization routine once. +.It Xo +.Ft pthread_t +.Fn pthread_self void +.Xc +Returns the thread ID of the calling thread. +.It Xo +.Ft int +.Fn pthread_setcancelstate "int state" "int *oldstate" +.Xc +Sets the current thread's cancelability state. +.It Xo +.Ft int +.Fn pthread_setcanceltype "int type" "int *oldtype" +.Xc +Sets the current thread's cancelability type. +.It Xo +.Ft void +.Fn pthread_testcancel void +.Xc +Creates a cancellation point in the calling thread. +.It Xo +.Ft void +.Fn pthread_yield void +.Xc +Allows the scheduler to run another thread instead of the current one. +.El +.Ss Attribute Object Routines +.Bl -tag -width indent +.It Xo +.Ft int +.Fn pthread_attr_destroy "pthread_attr_t *attr" +.Xc +Destroy a thread attributes object. +.It Xo +.Ft int +.Fo pthread_attr_getinheritsched +.Fa "const pthread_attr_t *attr" "int *inheritsched" +.Fc +.Xc +Get the inherit scheduling attribute from a thread attributes object. +.It Xo +.Ft int +.Fo pthread_attr_getschedparam +.Fa "const pthread_attr_t *attr" "struct sched_param *param" +.Fc +.Xc +Get the scheduling parameter attribute from a thread attributes object. +.It Xo +.Ft int +.Fn pthread_attr_getschedpolicy "const pthread_attr_t *attr" "int *policy" +.Xc +Get the scheduling policy attribute from a thread attributes object. +.It Xo +.Ft int +.Fn pthread_attr_getscope "const pthread_attr_t *attr" "int *contentionscope" +.Xc +Get the contention scope attribute from a thread attributes object. +.It Xo +.Ft int +.Fn pthread_attr_getstacksize "const pthread_attr_t *attr" "size_t *stacksize" +.Xc +Get the stack size attribute from a thread attributes object. +.It Xo +.Ft int +.Fn pthread_attr_getstackaddr "const pthread_attr_t *attr" "void **stackaddr" +.Xc +Get the stack address attribute from a thread attributes object. +.It Xo +.Ft int +.Fn pthread_attr_getdetachstate "const pthread_attr_t *attr" "int *detachstate" +.Xc +Get the detach state attribute from a thread attributes object. +.It Xo +.Ft int +.Fn pthread_attr_init "pthread_attr_t *attr" +.Xc +Initialize a thread attributes object with default values. +.It Xo +.Ft int +.Fn pthread_attr_setinheritsched "pthread_attr_t *attr" "int inheritsched" +.Xc +Set the inherit scheduling attribute in a thread attributes object. +.It Xo +.Ft int +.Fo pthread_attr_setschedparam +.Fa "pthread_attr_t *attr" "const struct sched_param *param" +.Fc +.Xc +Set the scheduling parameter attribute in a thread attributes object. +.It Xo +.Ft int +.Fn pthread_attr_setschedpolicy "pthread_attr_t *attr" "int policy" +.Xc +Set the scheduling policy attribute in a thread attributes object. +.It Xo +.Ft int +.Fn pthread_attr_setscope "pthread_attr_t *attr" "int contentionscope" +.Xc +Set the contention scope attribute in a thread attributes object. +.It Xo +.Ft int +.Fn pthread_attr_setstacksize "pthread_attr_t *attr" "size_t stacksize" +.Xc +Set the stack size attribute in a thread attributes object. +.It Xo +.Ft int +.Fn pthread_attr_setstackaddr "pthread_attr_t *attr" "void *stackaddr" +.Xc +Set the stack address attribute in a thread attributes object. +.It Xo +.Ft int +.Fn pthread_attr_setdetachstate "pthread_attr_t *attr" "int detachstate" +.Xc +Set the detach state in a thread attributes object. +.El +.Ss Mutex Routines +.Bl -tag -width indent +.It Xo +.Ft int +.Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr" +.Xc +Destroy a mutex attributes object. +.It Xo +.Ft int +.Fn pthread_mutexattr_getprioceiling "const pthread_mutexattr_t *restrict attr" "int *restrict ceiling" +.Xc +Obtain priority ceiling attribute of mutex attribute object. +.It Xo +.Ft int +.Fn pthread_mutexattr_getprotocol "const pthread_mutexattr_t *restrict attr" "int *restrict protocol" +.Xc +Obtain protocol attribute of mutex attribute object. +.It Xo +.Ft int +.Fn pthread_mutexattr_gettype "const pthread_mutexattr_t *restrict attr" "int *restrict type" +.Xc +Obtain the mutex type attribute in the specified mutex attributes object. +.It Xo +.Ft int +.Fn pthread_mutexattr_init "pthread_mutexattr_t *attr" +.Xc +Initialize a mutex attributes object with default values. +.It Xo +.Ft int +.Fn pthread_mutexattr_setprioceiling "pthread_mutexattr_t *attr" "int ceiling" +.Xc +Set priority ceiling attribute of mutex attribute object. +.It Xo +.Ft int +.Fn pthread_mutexattr_setprotocol "pthread_mutexattr_t *attr" "int protocol" +.Xc +Set protocol attribute of mutex attribute object. +.It Xo +.Ft int +.Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type" +.Xc +Set the mutex type attribute that is used when a mutex is created. +.It Xo +.Ft int +.Fn pthread_mutex_destroy "pthread_mutex_t *mutex" +.Xc +Destroy a mutex. +.It Xo +.Ft int +.Fo pthread_mutex_init +.Fa "pthread_mutex_t *mutex" "const pthread_mutexattr_t *attr" +.Fc +.Xc +Initialize a mutex with specified attributes. +.It Xo +.Ft int +.Fn pthread_mutex_lock "pthread_mutex_t *mutex" +.Xc +Lock a mutex and block until it becomes available. +.It Xo +.Ft int +.Fo pthread_mutex_timedlock +.Fa "pthread_mutex_t *mutex" "const struct timespec *abstime" +.Fc +.Xc +Lock a mutex and block until it becomes available or until the timeout expires. +.It Xo +.Ft int +.Fn pthread_mutex_trylock "pthread_mutex_t *mutex" +.Xc +Try to lock a mutex, but do not block if the mutex is locked by another thread, +including the current thread. +.It Xo +.Ft int +.Fn pthread_mutex_unlock "pthread_mutex_t *mutex" +.Xc +Unlock a mutex. +.El +.Ss Condition Variable Routines +.Bl -tag -width indent +.It Xo +.Ft int +.Fn pthread_condattr_destroy "pthread_condattr_t *attr" +.Xc +Destroy a condition variable attributes object. +.It Xo +.Ft int +.Fn pthread_condattr_init "pthread_condattr_t *attr" +.Xc +Initialize a condition variable attributes object with default values. +.It Xo +.Ft int +.Fn pthread_cond_broadcast "pthread_cond_t *cond" +.Xc +Unblock all threads currently blocked on the specified condition variable. +.It Xo +.Ft int +.Fn pthread_cond_destroy "pthread_cond_t *cond" +.Xc +Destroy a condition variable. +.It Xo +.Ft int +.Fn pthread_cond_init "pthread_cond_t *cond" "const pthread_condattr_t *attr" +.Xc +Initialize a condition variable with specified attributes. +.It Xo +.Ft int +.Fn pthread_cond_signal "pthread_cond_t *cond" +.Xc +Unblock at least one of the threads blocked on the specified condition variable. +.It Xo +.Ft int +.Fo pthread_cond_timedwait +.Fa "pthread_cond_t *cond" "pthread_mutex_t *mutex" +.Fa "const struct timespec *abstime" +.Fc +.Xc +Unlock the specified mutex, wait no longer than the specified time for +a condition, and then relock the mutex. +.It Xo +.Ft int +.Fn pthread_cond_wait "pthread_cond_t *" "pthread_mutex_t *mutex" +.Xc +Unlock the specified mutex, wait for a condition, and relock the mutex. +.El +.Ss Read/Write Lock Routines +.Bl -tag -width indent +.It Xo +.Ft int +.Fn pthread_rwlock_destroy "pthread_rwlock_t *lock" +.Xc +Destroy a read/write lock object. +.It Xo +.Ft int +.Fo pthread_rwlock_init +.Fa "pthread_rwlock_t *lock" "const pthread_rwlockattr_t *attr" +.Fc +.Xc +Initialize a read/write lock object. +.It Xo +.Ft int +.Fn pthread_rwlock_rdlock "pthread_rwlock_t *lock" +.Xc +Lock a read/write lock for reading, blocking until the lock can be +acquired. +.It Xo +.Ft int +.Fn pthread_rwlock_tryrdlock "pthread_rwlock_t *lock" +.Xc +Attempt to lock a read/write lock for reading, without blocking if the +lock is unavailable. +.It Xo +.Ft int +.Fn pthread_rwlock_trywrlock "pthread_rwlock_t *lock" +.Xc +Attempt to lock a read/write lock for writing, without blocking if the +lock is unavailable. +.It Xo +.Ft int +.Fn pthread_rwlock_unlock "pthread_rwlock_t *lock" +.Xc +Unlock a read/write lock. +.It Xo +.Ft int +.Fn pthread_rwlock_wrlock "pthread_rwlock_t *lock" +.Xc +Lock a read/write lock for writing, blocking until the lock can be +acquired. +.It Xo +.Ft int +.Fn pthread_rwlockattr_destroy "pthread_rwlockattr_t *attr" +.Xc +Destroy a read/write lock attribute object. +.It Xo +.Ft int +.Fo pthread_rwlockattr_getpshared +.Fa "const pthread_rwlockattr_t *attr" "int *pshared" +.Fc +.Xc +Retrieve the process shared setting for the read/write lock attribute +object. +.It Xo +.Ft int +.Fn pthread_rwlockattr_init "pthread_rwlockattr_t *attr" +.Xc +Initialize a read/write lock attribute object. +.It Xo +.Ft int +.Fn pthread_rwlockattr_setpshared "pthread_rwlockattr_t *attr" "int pshared" +.Xc +Set the process shared setting for the read/write lock attribute object. +.El +.Ss Per-Thread Context Routines +.Bl -tag -width indent +.It Xo +.Ft int +.Fn pthread_key_create "pthread_key_t *key" "void \*[lp]*routine\*[rp]\*[lp]void *\*[rp]" +.Xc +Create a thread-specific data key. +.It Xo +.Ft int +.Fn pthread_key_delete "pthread_key_t key" +.Xc +Delete a thread-specific data key. +.It Xo +.Ft "void *" +.Fn pthread_getspecific "pthread_key_t key" +.Xc +Get the thread-specific value for the specified key. +.It Xo +.Ft int +.Fn pthread_setspecific "pthread_key_t key" "const void *value_ptr" +.Xc +Set the thread-specific value for the specified key. +.El +.Ss Cleanup Routines +.Bl -tag -width indent +.It Xo +.Ft int +.Fo pthread_atfork +.Fa "void \*[lp]*prepare\*[rp]\*[lp]void\*[rp]" +.Fa "void \*[lp]*parent\*[rp]\*[lp]void\*[rp]" +.Fa "void \*[lp]*child\*[rp]\*[lp]void\*[rp]" +.Fc +.Xc +Register fork handlers. +.It Xo +.Ft void +.Fn pthread_cleanup_pop "int execute" +.Xc +Remove the routine at the top of the calling thread's cancellation cleanup +stack and optionally invoke it. +.It Xo +.Ft void +.Fn pthread_cleanup_push "void \*[lp]*routine\*[rp]\*[lp]void *\*[rp]" "void *routine_arg" +.Xc +Push the specified cancellation cleanup handler onto the calling thread's +cancellation stack. +.El +.Sh IMPLEMENTATION NOTES +The current +.Fx +POSIX thread implementation is built into the +.Lb libthr +library. +It contains thread-safe versions of +.Lb libc +functions and the thread functions. +Threaded applications are linked with this library. +.Sh SEE ALSO +.Xr libthr 3 , +.Xr pthread_atfork 3 , +.Xr pthread_attr 3 , +.Xr pthread_cancel 3 , +.Xr pthread_cleanup_pop 3 , +.Xr pthread_cleanup_push 3 , +.Xr pthread_cond_broadcast 3 , +.Xr pthread_cond_destroy 3 , +.Xr pthread_cond_init 3 , +.Xr pthread_cond_signal 3 , +.Xr pthread_cond_timedwait 3 , +.Xr pthread_cond_wait 3 , +.Xr pthread_condattr_destroy 3 , +.Xr pthread_condattr_init 3 , +.Xr pthread_create 3 , +.Xr pthread_detach 3 , +.Xr pthread_equal 3 , +.Xr pthread_exit 3 , +.Xr pthread_getspecific 3 , +.Xr pthread_join 3 , +.Xr pthread_key_delete 3 , +.Xr pthread_kill 3 , +.Xr pthread_mutex_destroy 3 , +.Xr pthread_mutex_init 3 , +.Xr pthread_mutex_lock 3 , +.Xr pthread_mutex_trylock 3 , +.Xr pthread_mutex_unlock 3 , +.Xr pthread_mutexattr_destroy 3 , +.Xr pthread_mutexattr_getprioceiling 3 , +.Xr pthread_mutexattr_getprotocol 3 , +.Xr pthread_mutexattr_gettype 3 , +.Xr pthread_mutexattr_init 3 , +.Xr pthread_mutexattr_setprioceiling 3 , +.Xr pthread_mutexattr_setprotocol 3 , +.Xr pthread_mutexattr_settype 3 , +.Xr pthread_np 3 , +.Xr pthread_once 3 , +.Xr pthread_rwlock_destroy 3 , +.Xr pthread_rwlock_init 3 , +.Xr pthread_rwlock_rdlock 3 , +.Xr pthread_rwlock_unlock 3 , +.Xr pthread_rwlock_wrlock 3 , +.Xr pthread_rwlockattr_destroy 3 , +.Xr pthread_rwlockattr_getpshared 3 , +.Xr pthread_rwlockattr_init 3 , +.Xr pthread_rwlockattr_setpshared 3 , +.Xr pthread_self 3 , +.Xr pthread_setcancelstate 3 , +.Xr pthread_setcanceltype 3 , +.Xr pthread_setspecific 3 , +.Xr pthread_testcancel 3 +.Sh STANDARDS +The functions with the +.Nm pthread_ +prefix and not +.Nm _np +suffix or +.Nm pthread_rwlock +prefix conform to +.St -p1003.1-96 . +.Pp +The functions with the +.Nm pthread_ +prefix and +.Nm _np +suffix are non-portable extensions to POSIX threads. +.Pp +The functions with the +.Nm pthread_rwlock +prefix are extensions created by The Open Group as part of the +.St -susv2 . diff --git a/static/freebsd/man3/pthread_affinity_np.3 b/static/freebsd/man3/pthread_affinity_np.3 new file mode 100644 index 00000000..86c43d22 --- /dev/null +++ b/static/freebsd/man3/pthread_affinity_np.3 @@ -0,0 +1,162 @@ +.\"- +.\" Copyright (c) 2010 Xin LI +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 29, 2023 +.Dt PTHREAD_AFFINITY_NP 3 +.Os +.Sh NAME +.Nm pthread_getaffinity_np , +.Nm pthread_setaffinity_np +.Nd manage CPU affinity +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Ft int +.Fn pthread_getaffinity_np "pthread_t td" "size_t cpusetsize" "cpuset_t *cpusetp" +.Ft int +.Fn pthread_setaffinity_np "pthread_t td" "size_t cpusetsize" "const cpuset_t *cpusetp" +.Sh DESCRIPTION +.Fn pthread_getaffinity_np +and +.Fn pthread_setaffinity_np +allow the manipulation of sets of CPUs available to the specified thread. +.Pp +Masks of type +.Ft cpuset_t +are composed using the +.Dv CPU_SET +macros. +If the user-supplied mask is not large enough to fit all of the matching CPUs, +.Fn pthread_getaffinity_np +fails with +.Er ERANGE . +Calls to +.Fn pthread_setaffinity_np +tolerate masks of any size with no restrictions. +The kernel uses the meaningful part of the mask, where the upper bound is +the maximum CPU id present in the system. +If bits for non-existing CPUs are set, calls to +.Fn pthread_setaffinity_np +fail with +.Er EINVAL . +.Pp +The supplied mask should have a size of +.Fa cpusetsize +bytes. +This size is usually provided by calling +.Li sizeof(cpuset_t) +which is ultimately determined by the value of +.Dv CPU_SETSIZE +as defined in +.In sys/cpuset.h . +.Pp +.Fn pthread_getaffinity_np +retrieves the +mask from the thread specified by +.Fa td , +and stores it in the space provided by +.Fa cpusetp . +.Pp +.Fn pthread_setaffinity_np +attempts to set the mask for the thread specified by +.Fa td +to the value in +.Fa cpusetp . +.Sh RETURN VALUES +If successful, the +.Fn pthread_getaffinity_np +and +.Fn pthread_setaffinity_np +functions will return zero. +Otherwise an error number will be returned +to indicate the error. +.Sh ERRORS +The +.Fn pthread_getaffinity_np +and +.Fn pthread_setaffinity_np +functions may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa cpusetp +argument specified when calling +.Fn pthread_setaffinity_np +was not a valid value. +.It Bq Er EDEADLK +The +.Fn pthread_setaffinity_np +call would leave a thread without a valid CPU to run on because the set +does not overlap with the thread's anonymous mask. +.It Bq Er EFAULT +The +.Fa cpusetp +pointer passed was invalid. +.It Bq Er ESRCH +The thread specified by the +.Fa td +argument could not be found. +.It Bq Er ERANGE +The +.Fa cpusetsize +was smaller than needed to fit all of the matching CPUs. +.It Bq Er EPERM +The calling thread did not have the credentials required to complete the +operation. +.El +.Sh SEE ALSO +.Xr cpuset 1 , +.Xr cpuset 2 , +.Xr cpuset_getid 2 , +.Xr cpuset_setid 2 , +.Xr pthread 3 , +.Xr pthread_attr_getaffinity_np 3 , +.Xr pthread_attr_setaffinity_np 3 , +.Xr pthread_np 3 +.Sh STANDARDS +The +.Nm pthread_getaffinity_np +and +.Nm pthread_setaffinity_np +functions are non-standard +.Fx +extensions and may be not available on other operating systems. +.Sh HISTORY +The +.Nm pthread_getaffinity_np +and +.Nm pthread_setaffinity_np +function first appeared in +.Fx 7.2 . +.Sh AUTHORS +.An -nosplit +The +.Nm pthread_getaffinity_np +and +.Nm pthread_setaffinity_np +functions were written by +.An David Xu Aq Mt davidxu@FreeBSD.org , +and this manpage was written by +.An Xin LI Aq Mt delphij@FreeBSD.org . diff --git a/static/freebsd/man3/pthread_atfork.3 b/static/freebsd/man3/pthread_atfork.3 new file mode 100644 index 00000000..5edec13e --- /dev/null +++ b/static/freebsd/man3/pthread_atfork.3 @@ -0,0 +1,114 @@ +.\" Copyright (c) 2004 Alex Vasylenko +.\" 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. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.Dd June 21, 2004 +.Dt PTHREAD_ATFORK 3 +.Os +.Sh NAME +.Nm pthread_atfork +.Nd register fork handlers +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fo pthread_atfork +.Fa "void \*[lp]*prepare\*[rp]\*[lp]void\*[rp]" +.Fa "void \*[lp]*parent\*[rp]\*[lp]void\*[rp]" +.Fa "void \*[lp]*child\*[rp]\*[lp]void\*[rp]" +.Fc +.Sh DESCRIPTION +The +.Fn pthread_atfork +function declares fork handlers to be called before and after +.Xr fork 2 , +in the context of the thread that called +.Xr fork 2 . +.Pp +The handlers registered with +.Fn pthread_atfork +are called at the moments in time described below: +.Bl -tag -width ".Fa prepare" +.It Fa prepare +Before +.Xr fork 2 +processing commences in the parent process. +If more than one +.Fa prepare +handler is registered they will be called in the opposite order +they were registered. +.It Fa parent +After +.Xr fork 2 +completes in the parent process. +If more than one +.Fa parent +handler is registered they will be called in the same order +they were registered. +.It Fa child +After +.Xr fork 2 +processing completes in the child process. +If more than one +.Fa child +handler is registered they will be called in the same order +they were registered. +.El +.Pp +If no handling is desired at one or more of these three points, +a null pointer may be passed as the corresponding fork handler. +.Sh RETURN VALUES +If successful, the +.Fn pthread_atfork +function will return zero. +Otherwise an error number will be returned to indicate the error. +.Sh ERRORS +The +.Fn pthread_atfork +function will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Insufficient table space exists to record the fork handler addresses. +.El +.Sh SEE ALSO +.Xr fork 2 , +.Xr pthread 3 +.Sh STANDARDS +The +.Fn pthread_atfork +function is expected to conform to +.St -p1003.1 . +.Sh AUTHORS +This manpage was written by +.An Alex Vasylenko Aq Mt lxv@omut.org . diff --git a/static/freebsd/man3/pthread_attr.3 b/static/freebsd/man3/pthread_attr.3 new file mode 100644 index 00000000..828195c2 --- /dev/null +++ b/static/freebsd/man3/pthread_attr.3 @@ -0,0 +1,236 @@ +.\" Copyright (C) 2000 Jason Evans . +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 August 17, 2018 +.Dt PTHREAD_ATTR 3 +.Os +.Sh NAME +.Nm pthread_attr_init , +.Nm pthread_attr_destroy , +.Nm pthread_attr_setstack , +.Nm pthread_attr_getstack , +.Nm pthread_attr_setstacksize , +.Nm pthread_attr_getstacksize , +.Nm pthread_attr_setguardsize , +.Nm pthread_attr_getguardsize , +.Nm pthread_attr_setstackaddr , +.Nm pthread_attr_getstackaddr , +.Nm pthread_attr_setdetachstate , +.Nm pthread_attr_getdetachstate , +.Nm pthread_attr_setinheritsched , +.Nm pthread_attr_getinheritsched , +.Nm pthread_attr_setschedparam , +.Nm pthread_attr_getschedparam , +.Nm pthread_attr_setschedpolicy , +.Nm pthread_attr_getschedpolicy , +.Nm pthread_attr_setscope , +.Nm pthread_attr_getscope +.Nd thread attribute operations +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_attr_init "pthread_attr_t *attr" +.Ft int +.Fn pthread_attr_destroy "pthread_attr_t *attr" +.Ft int +.Fn pthread_attr_setstack "pthread_attr_t *attr" " void *stackaddr" "size_t stacksize" +.Ft int +.Fn pthread_attr_getstack "const pthread_attr_t * restrict attr" "void ** restrict stackaddr" "size_t * restrict stacksize" +.Ft int +.Fn pthread_attr_setstacksize "pthread_attr_t *attr" "size_t stacksize" +.Ft int +.Fn pthread_attr_getstacksize "const pthread_attr_t *restrict attr" "size_t *restrict stacksize" +.Ft int +.Fn pthread_attr_setguardsize "pthread_attr_t *attr" "size_t guardsize" +.Ft int +.Fn pthread_attr_getguardsize "const pthread_attr_t * restrict attr" "size_t * restrict guardsize" +.Ft int +.Fn pthread_attr_setstackaddr "pthread_attr_t *attr" "void *stackaddr" +.Ft int +.Fn pthread_attr_getstackaddr "const pthread_attr_t *attr" "void **stackaddr" +.Ft int +.Fn pthread_attr_setdetachstate "pthread_attr_t *attr" "int detachstate" +.Ft int +.Fn pthread_attr_getdetachstate "const pthread_attr_t *attr" "int *detachstate" +.Ft int +.Fn pthread_attr_setinheritsched "pthread_attr_t *attr" "int inheritsched" +.Ft int +.Fn pthread_attr_getinheritsched "const pthread_attr_t *restrict attr" "int *restrct inheritsched" +.Ft int +.Fn pthread_attr_setschedparam "pthread_attr_t *attr" "const struct sched_param *param" +.Ft int +.Fn pthread_attr_getschedparam "const pthread_attr_t *attr" "struct sched_param *param" +.Ft int +.Fn pthread_attr_setschedpolicy "pthread_attr_t *attr" "int policy" +.Ft int +.Fn pthread_attr_getschedpolicy "const pthread_attr_t *restrict attr" "int *restrict policy" +.Ft int +.Fn pthread_attr_setscope "pthread_attr_t *attr" "int contentionscope" +.Ft int +.Fn pthread_attr_getscope "const pthread_attr_t *restrict attr" "int *restrict contentionscope" +.Sh DESCRIPTION +Thread attributes are used to specify parameters to +.Fn pthread_create . +One attribute object can be used in multiple calls to +.Fn pthread_create , +with or without modifications between calls. +.Pp +The +.Fn pthread_attr_init +function initializes +.Fa attr +with all the default thread attributes. +.Pp +The +.Fn pthread_attr_destroy +function destroys +.Fa attr . +.Pp +The +.Fn pthread_attr_set* +functions set the attribute that corresponds to each function name. +.Pp +The +.Fn pthread_attr_get* +functions copy the value of the attribute that corresponds to each function name +to the location pointed to by the second function parameter. +.Sh RETURN VALUES +If successful, these functions return 0. +Otherwise, an error number is returned to indicate the error. +.Sh ERRORS +The +.Fn pthread_attr_init +function will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Out of memory. +.El +.Pp +The +.Fn pthread_attr_destroy +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.El +.Pp +The +.Fn pthread_attr_setstacksize +and +.Fn pthread_attr_setstack +functions will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa stacksize +is less than +.Dv PTHREAD_STACK_MIN . +.El +.Pp +The +.Fn pthread_attr_setdetachstate +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa detachstate . +.El +.Pp +The +.Fn pthread_attr_setinheritsched +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.El +.Pp +The +.Fn pthread_attr_setschedparam +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.It Bq Er ENOTSUP +Invalid value for +.Fa param . +.El +.Pp +The +.Fn pthread_attr_setschedpolicy +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.It Bq Er ENOTSUP +Invalid or unsupported value for +.Fa policy . +.El +.Pp +The +.Fn pthread_attr_setscope +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.It Bq Er ENOTSUP +Invalid or unsupported value for +.Fa contentionscope . +.El +.Sh SEE ALSO +.Xr pthread_attr_affinity_np 3 , +.Xr pthread_attr_get_np 3 , +.Xr pthread_create 3 +.Sh STANDARDS +.Fn pthread_attr_init , +.Fn pthread_attr_destroy , +.Fn pthread_attr_setstacksize , +.Fn pthread_attr_getstacksize , +.Fn pthread_attr_setstackaddr , +.Fn pthread_attr_getstackaddr , +.Fn pthread_attr_setdetachstate , +and +.Fn pthread_attr_getdetachstate +functions conform to +.St -p1003.1-96 +.Pp +The +.Fn pthread_attr_setinheritsched , +.Fn pthread_attr_getinheritsched , +.Fn pthread_attr_setschedparam , +.Fn pthread_attr_getschedparam , +.Fn pthread_attr_setschedpolicy , +.Fn pthread_attr_getschedpolicy , +.Fn pthread_attr_setscope , +and +.Fn pthread_attr_getscope +functions conform to +.St -susv2 diff --git a/static/freebsd/man3/pthread_attr_affinity_np.3 b/static/freebsd/man3/pthread_attr_affinity_np.3 new file mode 100644 index 00000000..0589213c --- /dev/null +++ b/static/freebsd/man3/pthread_attr_affinity_np.3 @@ -0,0 +1,161 @@ +.\"- +.\" Copyright (c) 2010 Xin LI +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 29, 2023 +.Dt PTHREAD_ATTR_AFFINITY_NP 3 +.Os +.Sh NAME +.Nm pthread_attr_getaffinity_np , +.Nm pthread_attr_setaffinity_np +.Nd manage CPU affinity in thread attribute objects +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Ft int +.Fn pthread_attr_getaffinity_np "const pthread_attr_t *pattr" "size_t cpusetsize" "cpuset_t *cpusetp" +.Ft int +.Fn pthread_attr_setaffinity_np "pthread_attr_t *pattr" "size_t cpusetsize" "const cpuset_t *cpusetp" +.Sh DESCRIPTION +The +.Fn pthread_attr_getaffinity_np +and +.Fn pthread_attr_setaffinity_np +functions allow the manipulation of sets of CPUs available to the specified thread attribute object. +.Pp +Masks of type +.Ft cpuset_t +are composed using the +.Dv CPU_SET +macros. +If the user-supplied mask is not large enough to fit all of the matching CPUs, +.Fn pthread_attr_getaffinity_np +fails with +.Er ERANGE . +Calls to +.Fn pthread_attr_setaffinity_np +tolerate masks of any size with no restrictions. +.Fn pthread_attr_setaffinity_np +uses the meaningful part of the mask, where the upper bound is +the maximum CPU id present in the system. +If bits for non-existing CPUs are set, calls to +.Fn pthread_attr_setaffinity_np +fail with +.Er EINVAL . +.Pp +The supplied mask should have a size of +.Fa cpusetsize +bytes. +This size is usually provided by calling +.Li sizeof(cpuset_t) +which is ultimately determined by the value of +.Dv CPU_SETSIZE +as defined in +.In sys/cpuset.h . +.Pp +.Fn pthread_attr_getaffinity_np +retrieves the +mask from the thread attribute object specified by +.Fa pattr , +and stores it in the space provided by +.Fa cpusetp . +.Pp +.Fn pthread_attr_setaffinity_np +sets the mask for the thread attribute object specified by +.Fa pattr +to the value in +.Fa cpusetp . +.Sh RETURN VALUES +If successful, the +.Fn pthread_attr_getaffinity_np +and +.Fn pthread_attr_setaffinity_np +functions will return zero. +Otherwise an error number will be returned +to indicate the error. +.Sh ERRORS +The +.Fn pthread_attr_getaffinity_np +functions will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa pattr +or the attribute specified by it is +.Dv NULL . +.It Bq Er ERANGE +The +.Fa cpusetsize +is too small. +.El +.Pp +The +.Fn pthread_attr_setaffinity_np +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa pattr +or the attribute specified by it is +.Dv NULL . +.It Bq Er EINVAL +The +.Fa cpusetp +specified a CPU that was outside the set supported by the kernel. +.It Bq Er ENOMEM +Insufficient memory exists to store the cpuset mask. +.El +.Sh SEE ALSO +.Xr cpuset 1 , +.Xr cpuset 2 , +.Xr cpuset_getid 2 , +.Xr cpuset_setid 2 , +.Xr pthread_getaffinity_np 3 , +.Xr pthread_np 3 , +.Xr pthread_setaffinity_np 3 +.Sh STANDARDS +The +.Nm pthread_attr_getaffinity_np +and +.Nm pthread_attr_setaffinity_np +functions are non-standard +.Fx +extensions and may be not available on other operating systems. +.Sh HISTORY +The +.Nm pthread_attr_getaffinity_np +and +.Nm pthread_attr_setaffinity_np +functions first appeared in +.Fx 7.2 . +.Sh AUTHORS +.An -nosplit +The +.Nm pthread_attr_getaffinity_np +and +.Nm pthread_attr_setaffinity_np +functions were written by +.An David Xu Aq Mt davidxu@FreeBSD.org , +and this manpage was written by +.An Xin LI Aq Mt delphij@FreeBSD.org . diff --git a/static/freebsd/man3/pthread_attr_get_np.3 b/static/freebsd/man3/pthread_attr_get_np.3 new file mode 100644 index 00000000..07153586 --- /dev/null +++ b/static/freebsd/man3/pthread_attr_get_np.3 @@ -0,0 +1,128 @@ +.\" Copyright (c) 2002,2003 Alexey Zelkin +.\" All rights reserved. +.\" Copyright (c) 2024 The FreeBSD Foundation +.\" +.\" Portions of this documentation were written by Olivier Certner +.\" at Kumacom SARL under sponsorship from the +.\" FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 5, 2024 +.Dt PTHREAD_ATTR_GET_NP 3 +.Os +.Sh NAME +.Nm pthread_attr_get_np +.Nd get attributes of an existing thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Ft int +.Fn pthread_attr_get_np "pthread_t pid" "pthread_attr_t *dst" +.Sh DESCRIPTION +The +.Fn pthread_attr_get_np +function is used to retrieve the attributes of the specified thread into an +existing +.Vt pthread_attr_t +structure. +The attributes' values are the current ones for the target thread, except for +the stack top address if not properly aligned for the architecture, since in +this case its value has been adjusted internally before use. +.Pp +Argument +.Fa dst +must be a pointer to a valid attributes object +.Po +it was initialized at some point by +.Xr pthread_attr_init 3 +and was not destroyed since then +.Pc . +After a successful call to +.Fn pthread_attr_get_np , +the individual attributes' values can be retrieved as usual via the +corresponding accessor functions as documented in +.Xr pthread_attr 3 . +After a failed call to +.Fn pthread_attr_get_np , +the object pointed to by +.Fa dst +is left unmodified, and can continue to be used as if the failed call never +happened. +.Sh RETURN VALUES +If successful, +.Fn pthread_attr_get_np +function returns 0. +Otherwise, an error number is returned to indicate the error. +.Sh EXAMPLES +This function retrieves the stack size of the thread specified by the +.Fa pid +argument: +.Bd -literal +size_t +my_thread_stack_size(pthread_t tid) +{ + pthread_attr_t attr; + size_t size; + + pthread_attr_init(&attr); + pthread_attr_get_np(tid, &attr); + pthread_attr_getstacksize(&attr, &size); + pthread_attr_destroy(&attr); + return (size); +} +.Ed +.Sh ERRORS +The +.Fn pthread_attr_get_np +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +One of the arguments has an invalid value. +.It Bq Er ESRCH +No thread could be found corresponding to that specified by the given +thread ID. +.It Bq Er ENOMEM +There was not enough memory to allocate additional storage needed by the attributes +object's implementation. +.El +.Sh SEE ALSO +.Xr pthread_attr 3 , +.Xr pthread_attr_destroy 3 , +.Xr pthread_attr_getdetachstate 3 , +.Xr pthread_attr_getinheritsched 3 , +.Xr pthread_attr_getschedparam 3 , +.Xr pthread_attr_getschedpolicy 3 , +.Xr pthread_attr_getscope 3 , +.Xr pthread_attr_getstack 3 , +.Xr pthread_attr_getstackaddr 3 , +.Xr pthread_attr_getstacksize 3 , +.Xr pthread_attr_init 3 , +.Xr pthread_np 3 +.Sh AUTHORS +The +.Fn pthread_attr_get_np +function and this manual page were written by +.An Alexey Zelkin Aq Mt phantom@FreeBSD.org , +and the latter was revised by +.An Olivier Certner Aq Mt olce@FreeBSD.org . diff --git a/static/freebsd/man3/pthread_attr_setcreatesuspend_np.3 b/static/freebsd/man3/pthread_attr_setcreatesuspend_np.3 new file mode 100644 index 00000000..3d2f84a4 --- /dev/null +++ b/static/freebsd/man3/pthread_attr_setcreatesuspend_np.3 @@ -0,0 +1,71 @@ +.\" Copyright (c) 2003 Alexey Zelkin +.\" 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 October 12, 2021 +.Dt PTHREAD_ATTR_SETCREATESUSPEND_NP 3 +.Os +.Sh NAME +.Nm pthread_attr_setcreatesuspend_np +.Nd prepare attribute for creation of suspended thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Ft int +.Fn pthread_attr_setcreatesuspend_np "pthread_attr_t *attr" +.Sh DESCRIPTION +The +.Fn pthread_attr_setcreatesuspend_np +instructs +.Xr pthread_create 3 +that the thread created with the +.Fa attr +attribute +should be created and left in a suspended state until explicitly resumed +by the call to +.Fn pthread_resume_np +or +.Fn pthread_resume_all_np . +.Sh RETURN VALUES +.Rv -std pthread_attr_setcreatesuspend_np +.Sh ERRORS +The +.Fn pthread_attr_setcreatesuspend_np +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.El +.Sh SEE ALSO +.Xr pthread_attr_destroy 3 , +.Xr pthread_attr_init 3 , +.Xr pthread_create 3 , +.Xr pthread_np 3 , +.Xr pthread_resume_all_np 3 , +.Xr pthread_resume_np 3 +.Sh AUTHORS +This manual page was written by +.An Alexey Zelkin Aq Mt phantom@FreeBSD.org . diff --git a/static/freebsd/man3/pthread_barrier_destroy.3 b/static/freebsd/man3/pthread_barrier_destroy.3 new file mode 100644 index 00000000..06c8b97e --- /dev/null +++ b/static/freebsd/man3/pthread_barrier_destroy.3 @@ -0,0 +1,154 @@ +.\" Copyright (c) 2004 Michael Telahun Makonnen +.\" 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 August 17, 2018 +.Dt PTHREAD_BARRIER 3 +.Os +.Sh NAME +.Nm pthread_barrier_destroy , pthread_barrier_init , pthread_barrier_wait +.Nd "destroy, initialize or wait on a barrier object" +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_barrier_destroy "pthread_barrier_t *barrier" +.Ft int +.Fn pthread_barrier_init "pthread_barrier_t *restrict barrier" "const pthread_barrierattr_t *attr" "unsigned count" +.Ft int +.Fn pthread_barrier_wait "pthread_barrier_t *barrier" +.Sh DESCRIPTION +The +.Fn pthread_barrier_init +function will initialize +.Fa barrier +with attributes specified in +.Fa attr , +or if it is +.Dv NULL , +with default attributes. +The number of threads that must call +.Fn pthread_barrier_wait +before any of the waiting threads can be +released is specified by +.Fa count . +The +.Fn pthread_barrier_destroy +function will destroy +.Fa barrier +and release any resources that may have been allocated on its behalf. +.Pp +The +.Fn pthread_barrier_wait +function will synchronize calling threads at +.Fa barrier . +The threads will be blocked from +making further progress until +a sufficient number of threads calls this function. +The number of threads that must call it before +any of them will be released is determined by the +.Fa count +argument to +.Fn pthread_barrier_init . +Once the threads have been released the barrier will be reset. +.Sh IMPLEMENTATION NOTES +In +.Lb libthr +the +.Dv PTHREAD_BARRIER_SERIAL_THREAD +return value will +always be returned by the last thread to reach the barrier. +.Sh RETURN VALUES +If successful, +both +.Fn pthread_barrier_destroy +and +.Fn pthread_barrier_init +will return zero. +Otherwise, an error number will be returned to indicate the error. +If the call to +.Fn pthread_barrier_wait +is successful, all but one of the threads will return zero. +That one thread will return +.Dv PTHREAD_BARRIER_SERIAL_THREAD . +Otherwise, an error number will be returned to indicate the error. +.Pp +None of these functions will return +.Er EINTR . +.Sh ERRORS +The +.Fn pthread_barrier_destroy +function will fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +An attempt was made to destroy +.Fa barrier +while it was in use. +.El +.Pp +The +.Fn pthread_barrier_destroy +and +.Fn pthread_barrier_wait +functions may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa barrier +is invalid. +.El +.Pp +The +.Fn pthread_barrier_init +function will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system lacks resources, +other than memory, +to initialize +.Fa barrier . +.It Bq Er EINVAL +The +.Fa count +argument is less than 1. +.It Bq Er ENOMEM +Insufficient memory to initialize +.Fa barrier . +.El +.Sh SEE ALSO +.Xr pthread_barrierattr 3 +.Sh HISTORY +The +.Fn pthread_barrier_destroy , +.Fn pthread_barrier_init +and +.Fn pthread_barrier_wait +functions first appeared in +.Lb libkse +in +.Fx 5.2 , +and in +.Lb libthr +in +.Fx 5.3 . diff --git a/static/freebsd/man3/pthread_barrierattr.3 b/static/freebsd/man3/pthread_barrierattr.3 new file mode 100644 index 00000000..1f5243f9 --- /dev/null +++ b/static/freebsd/man3/pthread_barrierattr.3 @@ -0,0 +1,137 @@ +.\" Copyright (c) 2004 Michael Telahun Makonnen +.\" 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 August 17, 2018 +.Dt PTHREAD_BARRIERATTR 3 +.Os +.Sh NAME +.Nm pthread_barrierattr_destroy , pthread_barrierattr_getpshared , +.Nm pthread_barrierattr_init , pthread_barrierattr_setpshared +.Nd "manipulate a barrier attribute object" +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_barrierattr_destroy "pthread_barrierattr_t *attr" +.Ft int +.Fo pthread_barrierattr_getpshared +.Fa "const pthread_barrierattr_t *restrict attr" "int *restrict pshared" +.Fc +.Ft int +.Fn pthread_barrierattr_init "pthread_barrierattr_t *attr" +.Ft int +.Fo pthread_barrierattr_setpshared +.Fa "pthread_barrierattr_t *attr" "int pshared" +.Fc +.Sh DESCRIPTION +The +.Fn pthread_barrierattr_init +function will initialize +.Fa attr +with default attributes. +The +.Fn pthread_barrierattr_destroy +function will destroy +.Fa attr +and release any resources that may have been allocated on its behalf. +.Pp +The +.Fn pthread_barrierattr_getpshared +function will put the value of the process-shared attribute from +.Fa attr +into the memory area pointed to by +.Fa pshared . +The +.Fn pthread_barrierattr_setpshared +function will set the process-shared attribute of +.Fa attr +to the value specified in +.Fa pshared . +The argument +.Fa pshared +may have one of the following values: +.Bl -tag -width ".Dv PTHREAD_PROCESS_PRIVATE" +.It Dv PTHREAD_PROCESS_PRIVATE +The barrier object it is attached to may only be accessed by +threads in the same process as the one that created the object. +.It Dv PTHREAD_PROCESS_SHARED +The barrier object it is attached to may be accessed by +threads in processes other than the one that created the object. +.El +.Sh RETURN VALUES +If successful, all these functions will return zero. +Otherwise, an error number will be returned to indicate the error. +.Pp +None of these functions will return +.Er EINTR . +.Sh ERRORS +The +.Fn pthread_barrierattr_destroy , +.Fn pthread_barrierattr_getpshared +and +.Fn pthread_barrierattr_setpshared +functions may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.El +.Pp +The +.Fn pthread_barrierattr_init +function will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Insufficient memory to initialize the barrier attribute object +.Fa attr . +.El +.Pp +The +.Fn pthread_barrierattr_setpshared +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified in +.Fa pshared +is not one of the allowed values. +.El +.Sh SEE ALSO +.Xr pthread_barrier_destroy 3 , +.Xr pthread_barrier_init 3 , +.Xr pthread_barrier_wait 3 +.Sh HISTORY +The +.Fn pthread_barrierattr_* +functions first appeared in +.Lb libkse +in +.Fx 5.2 , +and in +.Lb libthr +in +.Fx 5.3 . +Support for process-shared barriers appeared in +.Fx 11.0 . diff --git a/static/freebsd/man3/pthread_cancel.3 b/static/freebsd/man3/pthread_cancel.3 new file mode 100644 index 00000000..33a00300 --- /dev/null +++ b/static/freebsd/man3/pthread_cancel.3 @@ -0,0 +1,80 @@ +.Dd January 17, 1999 +.Dt PTHREAD_CANCEL 3 +.Os +.Sh NAME +.Nm pthread_cancel +.Nd cancel execution of a thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_cancel "pthread_t thread" +.Sh DESCRIPTION +The +.Fn pthread_cancel +function requests that +.Fa thread +be canceled. +The target thread's cancelability state and type determines +when the cancellation takes effect. +When the cancellation is acted on, +the cancellation cleanup handlers for +.Fa thread +are called. +When the last cancellation cleanup handler returns, +the thread-specific data destructor functions will be called for +.Fa thread . +When the last destructor function returns, +.Fa thread +will be terminated. +.Pp +The cancellation processing in the target thread runs asynchronously with +respect to the calling thread returning from +.Fn pthread_cancel . +.Pp +A status of +.Dv PTHREAD_CANCELED +is made available to any threads joining with the target. +The symbolic +constant +.Dv PTHREAD_CANCELED +expands to a constant expression of type +.Ft "(void *)" , +whose value matches no pointer to an object in memory nor the value +.Dv NULL . +.Sh RETURN VALUES +If successful, the +.Fn pthread_cancel +functions will return zero. +Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +The +.Fn pthread_cancel +function will fail if: +.Bl -tag -width Er +.It Bq Er ESRCH +No thread could be found corresponding to that specified by the given +thread ID. +.El +.Sh SEE ALSO +.Xr pthread_cleanup_pop 3 , +.Xr pthread_cleanup_push 3 , +.Xr pthread_exit 3 , +.Xr pthread_join 3 , +.Xr pthread_setcancelstate 3 , +.Xr pthread_setcanceltype 3 , +.Xr pthread_testcancel 3 +.Sh STANDARDS +The +.Fn pthread_cancel +function conforms to +.St -p1003.1-96 . +.Sh AUTHORS +This manual page was written by +.An David Leonard Aq Mt d@openbsd.org +for the +.Ox +implementation of +.Fn pthread_cancel . diff --git a/static/freebsd/man3/pthread_cleanup_pop.3 b/static/freebsd/man3/pthread_cleanup_pop.3 new file mode 100644 index 00000000..2747624b --- /dev/null +++ b/static/freebsd/man3/pthread_cleanup_pop.3 @@ -0,0 +1,72 @@ +.\" Copyright (c) 1997 Brian Cully +.\" 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. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 REGENTS 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 October 25, 2014 +.Dt PTHREAD_CLEANUP_POP 3 +.Os +.Sh NAME +.Nm pthread_cleanup_pop +.Nd call the first cleanup routine +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft void +.Fn pthread_cleanup_pop "int execute" +.Sh DESCRIPTION +The +.Fn pthread_cleanup_pop +function pops the top cleanup routine off of the current threads cleanup +routine stack, and, if +.Fa execute +is non-zero, it will execute the function. +If there is no cleanup routine +then +.Fn pthread_cleanup_pop +does nothing. +.Pp +The +.Fn pthread_cleanup_pop +function is implemented as a macro that closes a block. +Invocations of this function must appear as standalone statements that are +paired with an earlier call of +.Xr pthread_cleanup_push 3 +in the same lexical scope. +.Sh RETURN VALUES +The +.Fn pthread_cleanup_pop +function does not return any value. +.Sh ERRORS +None +.Sh SEE ALSO +.Xr pthread_cleanup_push 3 , +.Xr pthread_exit 3 +.Sh STANDARDS +The +.Fn pthread_cleanup_pop +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_cleanup_push.3 b/static/freebsd/man3/pthread_cleanup_push.3 new file mode 100644 index 00000000..327c2fc3 --- /dev/null +++ b/static/freebsd/man3/pthread_cleanup_push.3 @@ -0,0 +1,74 @@ +.\" Copyright (c) 1997 Brian Cully +.\" 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. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 REGENTS 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 October 25, 2014 +.Dt PTHREAD_CLEANUP_PUSH 3 +.Os +.Sh NAME +.Nm pthread_cleanup_push +.Nd add a cleanup function for thread exit +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft void +.Fn pthread_cleanup_push "void \*[lp]*cleanup_routine\*[rp]\*[lp]void *\*[rp]" "void *arg" +.Sh DESCRIPTION +The +.Fn pthread_cleanup_push +function adds +.Fa cleanup_routine +to the top of the stack of cleanup handlers that +get called when the current thread exits. +.Pp +When +.Fa cleanup_routine +is called, it is passed +.Fa arg +as its only argument. +.Pp +The +.Fn pthread_cleanup_push +function is implemented as a macro that opens a new block. +Invocations of this function must appear as standalone statements that are +paired with a later call of +.Xr pthread_cleanup_pop 3 +in the same lexical scope. +.Sh RETURN VALUES +The +.Fn pthread_cleanup_push +function does not return any value. +.Sh ERRORS +None +.Sh SEE ALSO +.Xr pthread_cleanup_pop 3 , +.Xr pthread_exit 3 +.Sh STANDARDS +The +.Fn pthread_cleanup_push +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_cond_broadcast.3 b/static/freebsd/man3/pthread_cond_broadcast.3 new file mode 100644 index 00000000..77c1a2c2 --- /dev/null +++ b/static/freebsd/man3/pthread_cond_broadcast.3 @@ -0,0 +1,70 @@ +.\" Copyright (c) 1997 Brian Cully +.\" 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. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 REGENTS 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 28, 1998 +.Dt PTHREAD_COND_BROADCAST 3 +.Os +.Sh NAME +.Nm pthread_cond_broadcast +.Nd unblock all threads waiting for a condition variable +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_cond_broadcast "pthread_cond_t *cond" +.Sh DESCRIPTION +The +.Fn pthread_cond_broadcast +function unblocks all threads waiting for the condition variable +.Fa cond . +.Sh RETURN VALUES +If successful, the +.Fn pthread_cond_broadcast +function will return zero, otherwise an error number will be returned +to indicate the error. +.Sh ERRORS +The +.Fn pthread_cond_broadcast +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa cond +is invalid. +.El +.Sh SEE ALSO +.Xr pthread_cond_destroy 3 , +.Xr pthread_cond_init 3 , +.Xr pthread_cond_signal 3 , +.Xr pthread_cond_timedwait 3 , +.Xr pthread_cond_wait 3 +.Sh STANDARDS +The +.Fn pthread_cond_broadcast +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_cond_destroy.3 b/static/freebsd/man3/pthread_cond_destroy.3 new file mode 100644 index 00000000..ec07b030 --- /dev/null +++ b/static/freebsd/man3/pthread_cond_destroy.3 @@ -0,0 +1,77 @@ +.\" Copyright (c) 1997 Brian Cully +.\" 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. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 REGENTS 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 28, 1998 +.Dt PTHREAD_COND_DESTROY 3 +.Os +.Sh NAME +.Nm pthread_cond_destroy +.Nd destroy a condition variable +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_cond_destroy "pthread_cond_t *cond" +.Sh DESCRIPTION +The +.Fn pthread_cond_destroy +function frees the resources allocated by the condition variable +.Fa cond . +.Sh IMPLEMENTATION NOTES +A condition variable can be destroyed immediately after all the threads that +are blocked on it are awakened. +.Sh RETURN VALUES +If successful, the +.Fn pthread_cond_destroy +function will return zero, otherwise an error number will be returned +to indicate the error. +.Sh ERRORS +The +.Fn pthread_cond_destroy +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa cond +is invalid. +.It Bq Er EBUSY +The variable +.Fa cond +is locked by another thread. +.El +.Sh SEE ALSO +.Xr pthread_cond_broadcast 3 , +.Xr pthread_cond_init 3 , +.Xr pthread_cond_signal 3 , +.Xr pthread_cond_timedwait 3 , +.Xr pthread_cond_wait 3 +.Sh STANDARDS +The +.Fn pthread_cond_destroy +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_cond_init.3 b/static/freebsd/man3/pthread_cond_init.3 new file mode 100644 index 00000000..8d3dd79d --- /dev/null +++ b/static/freebsd/man3/pthread_cond_init.3 @@ -0,0 +1,81 @@ +.\" Copyright (c) 1997 Brian Cully +.\" 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. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 REGENTS 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 August 17, 2018 +.Dt PTHREAD_COND_INIT 3 +.Os +.Sh NAME +.Nm pthread_cond_init +.Nd create a condition variable +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_cond_init "pthread_cond_t *restrict cond" "const pthread_condattr_t *restrict attr" +.Sh DESCRIPTION +The +.Fn pthread_cond_init +function creates a new condition variable, with attributes specified with +.Fa attr . +If +.Fa attr +is NULL the default attributes are used. +.Sh RETURN VALUES +If successful, the +.Fn pthread_cond_init +function will return zero and put the new condition variable id into +.Fa cond , +otherwise an error number will be returned to indicate the error. +.Sh ERRORS +The +.Fn pthread_cond_init +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.It Bq Er ENOMEM +The process cannot allocate enough memory to create another condition +variable. +.It Bq Er EAGAIN +The system temporarily lacks the resources to create another condition +variable. +.El +.Sh SEE ALSO +.Xr pthread_cond_broadcast 3 , +.Xr pthread_cond_destroy 3 , +.Xr pthread_cond_signal 3 , +.Xr pthread_cond_timedwait 3 , +.Xr pthread_cond_wait 3 , +.Xr pthread_condattr 3 +.Sh STANDARDS +The +.Fn pthread_cond_init +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_cond_signal.3 b/static/freebsd/man3/pthread_cond_signal.3 new file mode 100644 index 00000000..5eb65650 --- /dev/null +++ b/static/freebsd/man3/pthread_cond_signal.3 @@ -0,0 +1,70 @@ +.\" Copyright (c) 1997 Brian Cully +.\" 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. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 REGENTS 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 28, 1998 +.Dt PTHREAD_COND_SIGNAL 3 +.Os +.Sh NAME +.Nm pthread_cond_signal +.Nd unblock a thread waiting for a condition variable +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_cond_signal "pthread_cond_t *cond" +.Sh DESCRIPTION +The +.Fn pthread_cond_signal +function unblocks one thread waiting for the condition variable +.Fa cond . +.Sh RETURN VALUES +If successful, the +.Fn pthread_cond_signal +function will return zero, otherwise an error number will be returned +to indicate the error. +.Sh ERRORS +The +.Fn pthread_cond_signal +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa cond +is invalid. +.El +.Sh SEE ALSO +.Xr pthread_cond_broadcast 3 , +.Xr pthread_cond_destroy 3 , +.Xr pthread_cond_init 3 , +.Xr pthread_cond_timedwait 3 , +.Xr pthread_cond_wait 3 +.Sh STANDARDS +The +.Fn pthread_cond_signal +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_cond_timedwait.3 b/static/freebsd/man3/pthread_cond_timedwait.3 new file mode 100644 index 00000000..d955bf85 --- /dev/null +++ b/static/freebsd/man3/pthread_cond_timedwait.3 @@ -0,0 +1,99 @@ +.\" Copyright (c) 1997 Brian Cully +.\" 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. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 REGENTS 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 May 9, 2010 +.Dt PTHREAD_COND_TIMEDWAIT 3 +.Os +.Sh NAME +.Nm pthread_cond_timedwait +.Nd "wait on a condition variable for a specific amount of time" +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_cond_timedwait "pthread_cond_t *cond" "pthread_mutex_t *mutex" "const struct timespec *abstime" +.Sh DESCRIPTION +The +.Fn pthread_cond_timedwait +function atomically blocks the current thread waiting on the condition +variable specified by +.Fa cond , +and releases the mutex specified by +.Fa mutex . +The waiting thread unblocks only after another thread calls +.Xr pthread_cond_signal 3 , +or +.Xr pthread_cond_broadcast 3 +with the same condition variable, or if the system time reaches the +time specified in +.Fa abstime , +and the current thread reacquires the lock on +.Fa mutex . +.Pp +The clock used to measure +.Fa abstime +can be specified during creation of the condition variable using +.Xr pthread_condattr_setclock 3 . +.Sh RETURN VALUES +If successful, the +.Fn pthread_cond_timedwait +function will return zero. +Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +The +.Fn pthread_cond_timedwait +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa cond , +.Fa mutex +or +.Fa abstime +is invalid. +.It Bq Er ETIMEDOUT +The system time has reached or exceeded the time specified in +.Fa abstime . +.It Bq Er EPERM +The specified +.Fa mutex +was not locked by the calling thread. +.El +.Sh SEE ALSO +.Xr pthread_cond_broadcast 3 , +.Xr pthread_cond_destroy 3 , +.Xr pthread_cond_init 3 , +.Xr pthread_cond_signal 3 , +.Xr pthread_cond_wait 3 , +.Xr pthread_condattr_setclock 3 +.Sh STANDARDS +The +.Fn pthread_cond_timedwait +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_cond_wait.3 b/static/freebsd/man3/pthread_cond_wait.3 new file mode 100644 index 00000000..c09e7aa6 --- /dev/null +++ b/static/freebsd/man3/pthread_cond_wait.3 @@ -0,0 +1,99 @@ +.\" Copyright (c) 1997 Brian Cully +.\" 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. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 REGENTS 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 August 7, 2019 +.Dt PTHREAD_COND_WAIT 3 +.Os +.Sh NAME +.Nm pthread_cond_wait +.Nd wait on a condition variable +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_cond_wait "pthread_cond_t *restrict cond" "pthread_mutex_t *restrict mutex" +.Sh DESCRIPTION +The +.Fn pthread_cond_wait +function atomically blocks the current thread waiting on the condition +variable specified by +.Fa cond , +and releases the mutex specified by +.Fa mutex . +The waiting thread unblocks only after another thread calls +.Xr pthread_cond_signal 3 , +or +.Xr pthread_cond_broadcast 3 +with the same condition variable, and the current thread reacquires the lock +on +.Fa mutex . +.Sh RETURN VALUES +If successful, the +.Fn pthread_cond_wait +function will return zero. +Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +The +.Fn pthread_cond_wait +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa cond +or the value specified by +.Fa mutex +is invalid. +.It Bq Er EPERM +The specified +.Fa mutex +was not locked by the calling thread. +.It Bq Er EOWNERDEAD +The argument +.Fa mutex +points to a robust mutex and the process containing the previous owning +thread terminated while holding the mutex lock. +The lock was granted to the caller and it is up to the new owner +to make the state consistent. +.It Bq Er ENOTRECOVERABLE +The state protected by the +.Fa mutex +is not recoverable. +.El +.Sh SEE ALSO +.Xr pthread_cond_broadcast 3 , +.Xr pthread_cond_destroy 3 , +.Xr pthread_cond_init 3 , +.Xr pthread_cond_signal 3 , +.Xr pthread_cond_timedwait 3 , +.Xr pthread_mutex_consistent 3 +.Sh STANDARDS +The +.Fn pthread_cond_wait +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_condattr.3 b/static/freebsd/man3/pthread_condattr.3 new file mode 100644 index 00000000..33ad904f --- /dev/null +++ b/static/freebsd/man3/pthread_condattr.3 @@ -0,0 +1,170 @@ +.\" Copyright (C) 2000 Jason Evans . +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 October 27, 2023 +.Dt PTHREAD_CONDATTR 3 +.Os +.Sh NAME +.Nm pthread_condattr_init , +.Nm pthread_condattr_destroy , +.Nm pthread_condattr_getclock , +.Nm pthread_condattr_setclock , +.Nm pthread_condattr_getpshared , +.Nm pthread_condattr_setpshared +.Nd condition attribute operations +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_condattr_init "pthread_condattr_t *attr" +.Ft int +.Fn pthread_condattr_destroy "pthread_condattr_t *attr" +.Ft int +.Fo pthread_condattr_getclock +.Fa "pthread_condattr_t * restrict attr" "clockid_t * restrict clock_id" +.Fc +.Ft int +.Fn pthread_condattr_setclock "pthread_condattr_t *attr" "clockid_t clock_id" +.Ft int +.Fo pthread_condattr_getpshared +.Fa "pthread_condattr_t * restrict attr" "int * restrict pshared" +.Fc +.Ft int +.Fn pthread_condattr_setpshared "pthread_condattr_t *attr" "int pshared" +.Sh DESCRIPTION +Condition attribute objects are used to specify parameters to +.Fn pthread_cond_init . +.Pp +The +.Fn pthread_condattr_init +function initializes a condition attribute object with the default attributes. +.Pp +The +.Fn pthread_condattr_destroy +function destroys a condition attribute object. +.Pp +The +.Fn pthread_condattr_getclock +function will put the value of the clock attribute from +.Fa attr +into the memory area pointed to by +.Fa clock_id . +The +.Fn pthread_condattr_setclock +function will set the clock attribute of +.Fa attr +to the value specified in +.Fa clock_id . +The clock attribute affects the interpretation of +.Fa abstime +in +.Xr pthread_cond_timedwait 3 +and may be set to +.Dv CLOCK_REALTIME +(default), +.Dv CLOCK_TAI , +or +.Dv CLOCK_MONOTONIC . +.Pp +The +.Fn pthread_condattr_getpshared +function will put the value of the process-shared attribute from +.Fa attr +into the memory area pointed to by +.Fa pshared . +The +.Fn pthread_condattr_setpshared +function will set the process-shared attribute of +.Fa attr +to the value specified in +.Fa pshared . +The argument +.Fa pshared +may have one of the following values: +.Bl -tag -width ".Dv PTHREAD_PROCESS_PRIVATE" +.It Dv PTHREAD_PROCESS_PRIVATE +The condition variable it is attached to may only be accessed by +threads in the same process as the one that created the object. +.It Dv PTHREAD_PROCESS_SHARED +The condition variable it is attached to may be accessed by +threads in processes other than the one that created the object. +.El +See +.Xr libthr 3 +for details of the implementation of shared condition variables, +and their limitations. +.Sh RETURN VALUES +If successful, these functions return 0. +Otherwise, an error number is returned to indicate the error. +.Sh ERRORS +The +.Fn pthread_condattr_init +function will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Out of memory. +.El +.Pp +The +.Fn pthread_condattr_destroy +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.El +.Pp +The +.Fn pthread_condattr_setclock +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified in +.Fa clock_id +is not one of the allowed values. +.El +.Pp +The +.Fn pthread_condattr_setpshared +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified in +.Fa pshared +is not one of the allowed values. +.El +.Sh SEE ALSO +.Xr libthr 3 , +.Xr pthread_cond_init 3 , +.Xr pthread_cond_timedwait 3 +.Sh STANDARDS +The +.Fn pthread_condattr_init +and +.Fn pthread_condattr_destroy +functions conform to +.St -p1003.1-96 diff --git a/static/freebsd/man3/pthread_create.3 b/static/freebsd/man3/pthread_create.3 new file mode 100644 index 00000000..2d43ac7b --- /dev/null +++ b/static/freebsd/man3/pthread_create.3 @@ -0,0 +1,147 @@ +.\" Copyright (c) 1996 John Birrell . +.\" 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 John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 REGENTS 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 August 17, 2018 +.Dt PTHREAD_CREATE 3 +.Os +.Sh NAME +.Nm pthread_create +.Nd create a new thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_create "pthread_t *restrict thread" "const pthread_attr_t *restrict attr" "void *(*start_routine)(void *)" "void *restrict arg" +.Sh DESCRIPTION +The +.Fn pthread_create +function is used to create a new thread, with attributes specified by +.Fa attr , +within a process. +If +.Fa attr +is +.Dv NULL , +the default attributes are used. +If the attributes specified by +.Fa attr +are modified later, the thread's attributes are not affected. +Upon +successful completion +.Fn pthread_create +will store the ID of the created thread in the location specified by +.Fa thread . +.Pp +The thread is created executing +.Fa start_routine +with +.Fa arg +as its sole argument. +If the +.Fa start_routine +returns, the effect is as if there was an implicit call to +.Fn pthread_exit +using the return value of +.Fa start_routine +as the exit status. +Note that the thread in which +.Fn main +was originally invoked differs from this. +When it returns from +.Fn main , +the effect is as if there was an implicit call to +.Fn exit +using the return value of +.Fn main +as the exit status. +.Pp +The signal state of the new thread is initialized as: +.Bl -bullet -offset indent +.It +The signal mask is inherited from the creating thread. +.It +The set of signals pending for the new thread is empty. +.El +.Sh RETURN VALUES +If successful, the +.Fn pthread_create +function will return zero. +Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +The +.Fn pthread_create +function can return any of the following errors: +.Bl -tag -width Er +.It Bq Er ENOMEM +The system lacked the necessary resources to create another thread. +.It Bq Er EAGAIN +The system-imposed limit on the total number of threads in a process +.Dv [PTHREAD_THREADS_MAX] +would be exceeded. +.It Bq Er EAGAIN +The +.Dv RACCT_NTHR +limit would be exceeded; see +.Xr racct 2 . +.It Bq Er EPERM +The caller does not have permission to set the scheduling parameters or +scheduling policy. +.It Bq Er EINVAL +A value specified by +.Fa attr +is invalid. +.It Bq Er EDEADLK +The CPU set specified by +.Fa attr +would prevent the thread from running on any CPU. +.It Bq Er EFAULT +The stack base specified by +.Fa attr +is invalid, or the kernel was unable to put required +initial data on the stack. +.El +.Sh SEE ALSO +.Xr cpuset_setaffinity 2 , +.Xr fork 2 , +.Xr racct 2 , +.Xr thr_new 2 , +.Xr pthread_attr 3 , +.Xr pthread_cancel 3 , +.Xr pthread_cleanup_pop 3 , +.Xr pthread_cleanup_push 3 , +.Xr pthread_exit 3 , +.Xr pthread_join 3 +.Sh STANDARDS +The +.Fn pthread_create +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_detach.3 b/static/freebsd/man3/pthread_detach.3 new file mode 100644 index 00000000..93bead1c --- /dev/null +++ b/static/freebsd/man3/pthread_detach.3 @@ -0,0 +1,89 @@ +.\" Copyright (c) 1996-1998 John Birrell . +.\" 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 John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 4, 1996 +.Dt PTHREAD_DETACH 3 +.Os +.Sh NAME +.Nm pthread_detach +.Nd detach a thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_detach "pthread_t thread" +.Sh DESCRIPTION +The +.Fn pthread_detach +function is used to indicate to the implementation that storage for the +thread +.Fa thread +can be reclaimed when the thread terminates. +If +.Fa thread +has not terminated, +.Fn pthread_detach +will not cause it to terminate. +The effect of multiple +.Fn pthread_detach +calls on the same target thread is unspecified. +.Sh RETURN VALUES +If successful, the +.Fn pthread_detach +function will return zero. +Otherwise an error number will be returned to +indicate the error. +Note that the function does not change the value +of errno as it did for some drafts of the standard. +These early drafts +also passed a pointer to pthread_t as the argument. +Beware! +.Sh ERRORS +The +.Fn pthread_detach +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The implementation has detected that the value specified by +.Fa thread +does not refer to a joinable thread. +.It Bq Er ESRCH +No thread could be found corresponding to that specified by the given +thread ID, +.Fa thread . +.El +.Sh SEE ALSO +.Xr pthread_join 3 +.Sh STANDARDS +The +.Fn pthread_detach +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_equal.3 b/static/freebsd/man3/pthread_equal.3 new file mode 100644 index 00000000..6ef861bc --- /dev/null +++ b/static/freebsd/man3/pthread_equal.3 @@ -0,0 +1,67 @@ +.\" Copyright (c) 1996 John Birrell . +.\" 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 John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 4, 1996 +.Dt PTHREAD_EQUAL 3 +.Os +.Sh NAME +.Nm pthread_equal +.Nd compare thread IDs +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_equal "pthread_t t1" "pthread_t t2" +.Sh DESCRIPTION +The +.Fn pthread_equal +function compares the thread IDs +.Fa t1 +and +.Fa t2 . +.Sh RETURN VALUES +The +.Fn pthread_equal +function will return non-zero if the thread IDs +.Fa t1 +and +.Fa t2 +correspond to the same thread, otherwise it will return zero. +.Sh ERRORS +None. +.Sh SEE ALSO +.Xr pthread_create 3 , +.Xr pthread_exit 3 +.Sh STANDARDS +The +.Fn pthread_equal +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_exit.3 b/static/freebsd/man3/pthread_exit.3 new file mode 100644 index 00000000..5c8f6ac4 --- /dev/null +++ b/static/freebsd/man3/pthread_exit.3 @@ -0,0 +1,105 @@ +.\" Copyright (c) 1996 John Birrell . +.\" 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 John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 REGENTS 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 March 15, 2014 +.Dt PTHREAD_EXIT 3 +.Os +.Sh NAME +.Nm pthread_exit +.Nd terminate the calling thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft void +.Fn pthread_exit "void *value_ptr" +.Sh DESCRIPTION +The +.Fn pthread_exit +function terminates the calling thread and makes the value +.Fa value_ptr +available to any successful join with the terminating thread. +Any +cancellation cleanup handlers that have been pushed and are not yet popped +are popped in the reverse order that they were pushed and then executed. +After all cancellation handlers have been executed, if the thread has any +thread-specific data, appropriate destructor functions are called in an +unspecified order. +Thread termination does not release any application +visible process resources, including, but not limited to, mutexes and +file descriptors, nor does it perform any process level cleanup +actions, including, but not limited to, calling +.Fn atexit +routines that may exist. +.Pp +An implicit call to +.Fn pthread_exit +is made when a thread other than the thread in which +.Fn main +was first invoked returns from the start routine that was used to create +it. +The function's return value serves as the thread's exit status. +.Pp +The behavior of +.Fn pthread_exit +is undefined if called from a cancellation handler or destructor function +that was invoked as the result of an implicit or explicit call to +.Fn pthread_exit . +.Pp +After a thread has terminated, the result of access to local (auto) +variables of the thread is undefined. +Thus, references to local variables +of the exiting thread should not be used for the +.Fn pthread_exit +.Fa value_ptr +parameter value. +.Pp +The process will exit with an exit status of 0 after the last thread has +been terminated. +The behavior is as if the implementation called +.Fn exit +with a zero argument at thread termination time. +.Sh RETURN VALUES +The +.Fn pthread_exit +function cannot return to its caller. +.Sh ERRORS +None. +.Sh SEE ALSO +.Xr _exit 2 , +.Xr exit 3 , +.Xr pthread_cancel 3 , +.Xr pthread_create 3 , +.Xr pthread_join 3 +.Sh STANDARDS +The +.Fn pthread_exit +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_getconcurrency.3 b/static/freebsd/man3/pthread_getconcurrency.3 new file mode 100644 index 00000000..c94e7b9e --- /dev/null +++ b/static/freebsd/man3/pthread_getconcurrency.3 @@ -0,0 +1,113 @@ +.\" Copyright (c) 2003 Sergey Osokin +.\" 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 April 11, 2003 +.Dt PTHREAD_GETCONCURRENCY 3 +.Os +.Sh NAME +.Nm pthread_getconcurrency , +.Nm pthread_setconcurrency +.Nd get or set level of concurrency +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_getconcurrency void +.Ft int +.Fn pthread_setconcurrency "int new_level" +.Sh DESCRIPTION +The +.Fn pthread_setconcurrency +function allows an application to inform the threads implementation +of its desired concurrency level, +.Fa new_level . +The actual level of concurrency provided by the implementation +as a result of this function call is unspecified. +If +.Fa new_level +is zero, it causes the implementation to maintain the concurrency +level at its discretion as if +.Fn pthread_setconcurrency +was never called. +The +.Fn pthread_getconcurrency +function returns the value set by a previous call to the +.Fn pthread_setconcurrency +function. +If the +.Fn pthread_setconcurrency +function was not previously called, this function returns zero to +indicate that the implementation is maintaining the concurrency +level. +When an application calls +.Fn pthread_setconcurrency , +it is informing the implementation of its desired concurrency +level. +The implementation uses this as a hint, not a requirement. +.Sh RETURN VALUES +If successful, the +.Fn pthread_setconcurrency +function returns zero. +Otherwise, an error number is returned +to indicate the error. +The +.Fn pthread_getconcurrency +function always returns the concurrency level set by a previous +call to +.Fn pthread_setconcurrency . +If the +.Fn pthread_setconcurrency +function has never been called, +.Fn pthread_getconcurrency +returns zero. +.Sh ERRORS +The +.Fn pthread_setconcurrency +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa new_level +is negative. +.It Bq Er EAGAIN +The value specified by +.Fa new_level +would cause a system resource to be exceeded. +.El +.Sh APPLICATION USAGE +Use of these functions changes the state of the underlying +concurrency upon which the application depends. +Library developers are advised to not use the +.Fn pthread_getconcurrency +and +.Fn pthread_setconcurrency +functions since their use may conflict with an application's +use of these functions. +.Sh STANDARDS +The +.Fn pthread_getconcurrency +and +.Fn pthread_setconcurrency +functions conform to +.St -susv2 . diff --git a/static/freebsd/man3/pthread_getcpuclockid.3 b/static/freebsd/man3/pthread_getcpuclockid.3 new file mode 100644 index 00000000..b372d2df --- /dev/null +++ b/static/freebsd/man3/pthread_getcpuclockid.3 @@ -0,0 +1,84 @@ +.\" Copyright (c) 2012 David Xu +.\" 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. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.Dd August 21, 2012 +.Dt PTHREAD_GETCPUCLOCKID 3 +.Os +.Sh NAME +.Nm pthread_getcpuclockid +.Nd access a thread CPU-time clock +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.In time.h +.Ft int +.Fn pthread_getcpuclockid "pthread_t thread_id" "clockid_t *clock_id" +.Sh DESCRIPTION +The +.Fn pthread_getcpuclockid +returns the clock ID of the CPU-time clock of the thread specified by +.Fa thread_id , +if the thread described by +.Fa thread_id +exists. +.Sh RETURN VALUES +Upon successful completion, +.Fn pthread_getcpuclockid +returns zero; otherwise, an error number is returned to indicate the +error. +.Sh ERRORS +The +.Fn pthread_getcpuclockid +function will fail if: +.Bl -tag -width Er +.It Bq Er ESRCH +The value specified by +.Fa thread_id +does not refer to an existing thread. +.El +.Sh SEE ALSO +.Xr clock_gettime 2 +.Sh STANDARDS +The +.Fn pthread_getcpuclockid +function conforms to +.St -p1003.1-2004 . +.Sh HISTORY +The +.Fn pthread_getcpuclockid +function first appeared in +.Fx 10.0 . +.Sh AUTHORS +.An David Xu Aq Mt davidxu@FreeBSD.org diff --git a/static/freebsd/man3/pthread_getspecific.3 b/static/freebsd/man3/pthread_getspecific.3 new file mode 100644 index 00000000..c9a46729 --- /dev/null +++ b/static/freebsd/man3/pthread_getspecific.3 @@ -0,0 +1,88 @@ +.\" Copyright (c) 1996 John Birrell . +.\" 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 John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 4, 1996 +.Dt PTHREAD_GETSPECIFIC 3 +.Os +.Sh NAME +.Nm pthread_getspecific +.Nd get a thread-specific data value +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft void * +.Fn pthread_getspecific "pthread_key_t key" +.Sh DESCRIPTION +The +.Fn pthread_getspecific +function returns the value currently bound to the specified +.Fa key +on behalf of the calling thread. +.Pp +The effect of calling +.Fn pthread_getspecific +with a +.Fa key +value not obtained from +.Fn pthread_key_create +or after +.Fa key +has been deleted with +.Fn pthread_key_delete +is undefined. +.Pp +The +.Fn pthread_getspecific +function may be called from a thread-specific data destructor function. +A call to +.Fn pthread_getspecific +for the thread-specific data key being destroyed returns the value NULL, +unless the value is changed (after the destructor starts) by a call to +.Fn pthread_setspecific . +.Sh RETURN VALUES +The +.Fn pthread_getspecific +function will return the thread-specific data value associated with the given +.Fa key . +If no thread-specific data value is associated with +.Fa key , +then the value NULL is returned. +.Sh ERRORS +None. +.Sh SEE ALSO +.Xr pthread_key_create 3 , +.Xr pthread_key_delete 3 , +.Xr pthread_setspecific 3 +.Sh STANDARDS +The +.Fn pthread_getspecific +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_getthreadid_np.3 b/static/freebsd/man3/pthread_getthreadid_np.3 new file mode 100644 index 00000000..da7ae545 --- /dev/null +++ b/static/freebsd/man3/pthread_getthreadid_np.3 @@ -0,0 +1,55 @@ +.\" Copyright (c) 2011 Jung-uk Kim +.\" 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 October 12, 2021 +.Dt PTHREAD_GETTHREADID_NP 3 +.Os +.Sh NAME +.Nm pthread_getthreadid_np +.Nd get the calling thread's integral ID +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Ft int +.Fn pthread_getthreadid_np void +.Sh DESCRIPTION +The +.Fn pthread_getthreadid_np +function returns the unique integral ID of the calling thread. +Its semantics is similar to the AIX's +.Fn pthread_getthreadid_np +function. +.Sh RETURN VALUES +The +.Fn pthread_getthreadid_np +function returns the thread integral ID of the calling thread. +.Sh ERRORS +None. +.Sh SEE ALSO +.Xr pthread_np 3 , +.Xr pthread_self 3 +.Sh AUTHORS +This manual page was written by +.An Jung-uk Kim Aq Mt jkim@FreeBSD.org . diff --git a/static/freebsd/man3/pthread_join.3 b/static/freebsd/man3/pthread_join.3 new file mode 100644 index 00000000..671ce7bb --- /dev/null +++ b/static/freebsd/man3/pthread_join.3 @@ -0,0 +1,194 @@ +.\" Copyright (c) 1996-1998 John Birrell . +.\" 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 John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 REGENTS 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 October 12, 2021 +.Dt PTHREAD_JOIN 3 +.Os +.Sh NAME +.Nm pthread_join , +.Nm pthread_peekjoin_np , +.Nm pthread_timedjoin_np +.Nm pthread_tryjoin_np +.Nd inspect thread termination state +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_join "pthread_t thread" "void **value_ptr" +.In pthread_np.h +.Ft int +.Fo pthread_peekjoin_np +.Fa "pthread_t thread" +.Fa "void **value_ptr" +.Fc +.Ft int +.Fo pthread_timedjoin_np +.Fa "pthread_t thread" +.Fa "void **value_ptr" +.Fa "const struct timespec *abstime" +.Fc +.Ft int +.Fn pthread_tryjoin_np "pthread_t thread" "void **value_ptr" +.Sh DESCRIPTION +The +.Fn pthread_join +function suspends execution of the calling thread until the target +.Fa thread +terminates unless the target +.Fa thread +has already terminated. +.Pp +On return from a successful +.Fn pthread_join +call with a non-NULL +.Fa value_ptr +argument, the value passed to +.Fn pthread_exit +by the terminating thread is stored in the location referenced by +.Fa value_ptr . +When a +.Fn pthread_join +returns successfully, the target thread has been terminated. +The results +of multiple simultaneous calls to +.Fn pthread_join +specifying the same target thread are undefined. +If the thread calling +.Fn pthread_join +is cancelled, then the target thread is not detached. +.Pp +The +.Fn pthread_timedjoin_np +function is equivalent to the +.Fn pthread_join +function except it will return +.Er ETIMEDOUT +if target thread does not exit before specified absolute time passes. +.Pp +The +.Fn pthread_peekjoin_np +only peeks into the exit status of the specified thread. +If the thread has not exited, the +.Er EBUSY +error is returned. +Otherwise, zero is returned and the thread exit value is optionally stored +into the location of +.Fa *value_ptr . +The target thread is left unjoined and can be used as an argument for +the +.Fn pthread_join +family of functions again. +.Pp +The +.Fn pthread_tryjoin_np +function joins the thread if it is already terminated, same as +.Fn pthread_join . +If the thread has not yet terminated, the function returns +.Er EBUSY . +.Pp +A thread that has exited but remains unjoined counts against +[_POSIX_THREAD_THREADS_MAX]. +.Sh RETURN VALUES +If successful, the described functions return zero. +Otherwise an error number is returned to indicate the error or +special condition. +.Sh ERRORS +The +.Fn pthread_join , +.Fn pthread_peekjoin_np , +and +.Fn pthread_timedjoin_np +functions will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The implementation has detected that the value specified by +.Fa thread +does not refer to a joinable thread. +.It Bq Er ESRCH +No thread could be found corresponding to that specified by the given +thread ID, +.Fa thread . +.It Bq Er EDEADLK +A deadlock was detected or the value of +.Fa thread +specifies the calling thread. +.It Bq Er EOPNOTSUPP +The implementation detected that another caller is already waiting on +.Fa thread . +.El +.Pp +Additionally, the +.Fn pthread_timedjoin_np +function will fail if: +.Bl -tag -width Er +.It Bq Er ETIMEDOUT +The specified absolute time passed while +.Fn pthread_timedjoin_np +waited for thread exit. +.El +.Pp +The +.Fn pthread_peekjoin_np +and +.Fn pthread_tryjoin_np +functions will also fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +The specified thread has not yet exited. +.El +.Sh SEE ALSO +.Xr wait 2 , +.Xr pthread 3 , +.Xr pthread_create 3 , +.Xr pthread_np 3 +.Sh STANDARDS +The +.Fn pthread_join +function conforms to +.St -p1003.1-96 . +The +.Fn pthread_timedjoin_np +function is a +.Fx +extension which first appeared in +.Fx 6.1 . +The +.Fn pthread_peekjoin_np +function is a +.Fx +extension which first appearead in +.Fx 13.0 . +The +.Fn pthread_tryjoin_np +function is a +.Fx +extension which first appearead in +.Fx 16.0 . diff --git a/static/freebsd/man3/pthread_key_create.3 b/static/freebsd/man3/pthread_key_create.3 new file mode 100644 index 00000000..0faf0a07 --- /dev/null +++ b/static/freebsd/man3/pthread_key_create.3 @@ -0,0 +1,107 @@ +.\" Copyright (c) 1996 John Birrell . +.\" 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 John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 4, 1996 +.Dt PTHREAD_KEY_CREATE 3 +.Os +.Sh NAME +.Nm pthread_key_create +.Nd thread-specific data key creation +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_key_create "pthread_key_t *key" "void (*destructor)(void *)" +.Sh DESCRIPTION +The +.Fn pthread_key_create +function creates a thread-specific data key visible to all threads in the +process. +Key values provided by +.Fn pthread_key_create +are opaque objects used to locate thread-specific data. +Although the same +key value may be used by different threads, the values bound to the key +by +.Fn pthread_setspecific +are maintained on a per-thread basis and persist for the life of the calling +thread. +.Pp +Upon key creation, the value NULL is associated with the new key in all +active threads. +Upon thread creation, the value NULL is associated with all +defined keys in the new thread. +.Pp +An optional destructor function may be associated with each key value. +At +thread exit, if a key value has a non-NULL destructor pointer, and the +thread has a non-NULL value associated with the key, the function pointed +to is called with the current associated value as its sole argument. +The +order of destructor calls is unspecified if more than one destructor exists +for a thread when it exits. +.Pp +If, after all the destructors have been called for all non-NULL values +with associated destructors, there are still some non-NULL values with +associated destructors, then the process is repeated. +If, after at least +[PTHREAD_DESTRUCTOR_ITERATIONS] iterations of destructor calls for +outstanding non-NULL values, there are still some non-NULL values with +associated destructors, the implementation stops calling destructors. +.Sh RETURN VALUES +If successful, the +.Fn pthread_key_create +function will store the newly created key value at the location specified by +.Fa key +and returns zero. +Otherwise an error number will be returned to indicate +the error. +.Sh ERRORS +The +.Fn pthread_key_create +function will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system lacked the necessary resources to create another thread-specific +data key, or the system-imposed limit on the total number of keys per process +[PTHREAD_KEYS_MAX] would be exceeded. +.It Bq Er ENOMEM +Insufficient memory exists to create the key. +.El +.Sh SEE ALSO +.Xr pthread_getspecific 3 , +.Xr pthread_key_delete 3 , +.Xr pthread_setspecific 3 +.Sh STANDARDS +The +.Fn pthread_key_create +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_key_delete.3 b/static/freebsd/man3/pthread_key_delete.3 new file mode 100644 index 00000000..884b261c --- /dev/null +++ b/static/freebsd/man3/pthread_key_delete.3 @@ -0,0 +1,98 @@ +.\" Copyright (c) 1996 John Birrell . +.\" 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 John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 4, 1996 +.Dt PTHREAD_KEY_DELETE 3 +.Os +.Sh NAME +.Nm pthread_key_delete +.Nd delete a thread-specific data key +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_key_delete "pthread_key_t key" +.Sh DESCRIPTION +The +.Fn pthread_key_delete +function deletes a thread-specific data key previously returned by +.Fn pthread_key_create . +The thread-specific data values associated with +.Fa key +need not be NULL at the time that +.Fn pthread_key_delete +is called. +It is the responsibility of the application to free any +application storage or perform any cleanup actions for data structures +related to the deleted key or associated thread-specific data in any threads; +this cleanup can be done either before or after +.Fn pthread_key_delete +is called. +Any attempt to use +.Fa key +following the call to +.Fn pthread_key_delete +results in undefined behavior. +.Pp +The +.Fn pthread_key_delete +function is callable from within destructor functions. +Destructor functions +are not invoked by +.Fn pthread_key_delete . +Any destructor function that may have been associated with +.Fa key +will no longer be called upon thread exit. +.Sh RETURN VALUES +If successful, the +.Fn pthread_key_delete +function will return zero. +Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +The +.Fn pthread_key_delete +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa key +value is invalid. +.El +.Sh SEE ALSO +.Xr pthread_getspecific 3 , +.Xr pthread_key_create 3 , +.Xr pthread_setspecific 3 +.Sh STANDARDS +The +.Fn pthread_key_delete +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_kill.3 b/static/freebsd/man3/pthread_kill.3 new file mode 100644 index 00000000..cb2d76c6 --- /dev/null +++ b/static/freebsd/man3/pthread_kill.3 @@ -0,0 +1,75 @@ +.\" Copyright (C) 2000 Jason Evans . +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 27, 2000 +.Dt PTHREAD_KILL 3 +.Os +.Sh NAME +.Nm pthread_kill +.Nd send a signal to a specified thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.In signal.h +.Ft int +.Fn pthread_kill "pthread_t thread" "int sig" +.Sh DESCRIPTION +The +.Fn pthread_kill +function sends a signal, specified by +.Fa sig , +to a thread, specified by +.Fa thread . +If +.Fa sig +is 0, error checking is performed, but no signal is actually sent. +.Sh RETURN VALUES +If successful, +.Fn pthread_kill +returns 0. +Otherwise, an error number is returned. +.Sh ERRORS +The +.Fn pthread_kill +function will fail if: +.Bl -tag -width Er +.It Bq Er ESRCH +.Fa thread +is an invalid thread ID. +.It Bq Er EINVAL +.Fa sig +is an invalid or unsupported signal number. +.El +.Sh SEE ALSO +.Xr kill 2 , +.Xr pthread_self 3 , +.Xr raise 3 +.Sh STANDARDS +The +.Fn pthread_kill +function conforms to +.St -p1003.1-96 diff --git a/static/freebsd/man3/pthread_main_np.3 b/static/freebsd/man3/pthread_main_np.3 new file mode 100644 index 00000000..58e3b11d --- /dev/null +++ b/static/freebsd/man3/pthread_main_np.3 @@ -0,0 +1,59 @@ +.\" Copyright (c) 2003 Alexey Zelkin +.\" 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 October 12, 2021 +.Dt PTHREAD_MAIN_NP 3 +.Os +.Sh NAME +.Nm pthread_main_np +.Nd identify the initial thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Ft int +.Fn pthread_main_np void +.Sh DESCRIPTION +The +.Fn pthread_main_np +function +is used in userland threads environment to identify the initial thread. +Its semantics is similar to the Solaris's +.Fn thr_main +function. +.Sh RETURN VALUES +The +.Fn pthread_main_np +function returns +1 if the calling thread is the initial thread, +0 if the calling thread is not the initial thread, +and \-1 if the thread's initialization has not yet completed. +.Sh SEE ALSO +.Xr pthread_create 3 , +.Xr pthread_equal 3 , +.Xr pthread_np 3 , +.Xr pthread_self 3 +.Sh AUTHORS +This manual page was written by +.An Alexey Zelkin Aq Mt phantom@FreeBSD.org . diff --git a/static/freebsd/man3/pthread_multi_np.3 b/static/freebsd/man3/pthread_multi_np.3 new file mode 100644 index 00000000..62c4fb45 --- /dev/null +++ b/static/freebsd/man3/pthread_multi_np.3 @@ -0,0 +1,65 @@ +.\" Copyright (c) 2003 Alexey Zelkin +.\" 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 October 12, 2021 +.Dt PTHREAD_MULTI_NP 3 +.Os +.Sh NAME +.Nm pthread_multi_np , +.Nm pthread_single_np +.Nd "switch between multi- and single-threaded scheduling modes" +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Ft int +.Fn pthread_multi_np void +.Ft int +.Fn pthread_single_np void +.Sh DESCRIPTION +The +.Fn pthread_single_np +function switches the process to a single-threaded mode, i.e., +suspends all threads except the current. +The semantics of this function is similar to +.Xr pthread_suspend_all_np 3 . +.Pp +The +.Fn pthread_multi_np +function switches the process to a multi-threaded mode. +The semantics of this function is similar to +.Xr pthread_resume_all_np 3 . +.Sh RETURN VALUES +The +.Fn pthread_multi_np +and +.Nm pthread_single_np +functions always return 0. +.Sh SEE ALSO +.Xr pthread_np 3 , +.Xr pthread_resume_all_np 3 , +.Xr pthread_suspend_all_np 3 +.Sh AUTHORS +This manual page was written by +.An Alexey Zelkin Aq Mt phantom@FreeBSD.org . diff --git a/static/freebsd/man3/pthread_mutex_consistent.3 b/static/freebsd/man3/pthread_mutex_consistent.3 new file mode 100644 index 00000000..e22be52b --- /dev/null +++ b/static/freebsd/man3/pthread_mutex_consistent.3 @@ -0,0 +1,91 @@ +.\" Copyright (c) 2016 The FreeBSD Foundation +.\" +.\" This documentation was written by +.\" Konstantin Belousov under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" 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 AUTHORS 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 AUTHORS 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 March 27, 2017 +.Dt PTHREAD_MUTEX_CONSISTENT 3 +.Os +.Sh NAME +.Nm pthread_mutex_consistent +.Nd mark state protected by robust mutex as consistent +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_mutex_consistent "pthread_mutex_t *mutex" +.Sh DESCRIPTION +If the process containing the thread owning a robust mutex terminates +while holding the mutex, the mutex becomes inconsistent and the next thread +that acquires the mutex lock is notified of the state by the return value +.Er EOWNERDEAD . +In this case, the mutex does not become normally usable again until +the state is marked consistent. +.Pp +The +.Fn pthread_mutex_consistent , +when called with the +.Fa mutex +argument, which points to the initialized robust mutex in an +inconsistent state, marks the by mutex as consistent again. +The consequent unlock of the mutex, by either +.Fn pthread_mutex_unlock +or other methods, allows other contenders to lock the mutex. +.Pp +If the mutex in the inconsistent state is not marked consistent +by the call to +.Fn pthread_mutex_consistent +before unlock, +further attempts to lock the +.Fa mutex +result in the +.Er ENOTRECOVERABLE +condition reported by the locking functions. +.Sh RETURN VALUES +If successful, +.Fn pthread_mutex_consistent +will return zero, otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +The +.Fn pthread_mutex_lock +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The mutex pointed to by the +.Fa mutex +argument is not robust, or is not in the inconsistent state. +.El +.Sh SEE ALSO +.Xr pthread_mutex_init 3 , +.Xr pthread_mutex_lock 3 , +.Xr pthread_mutex_unlock 3 , +.Xr pthread_mutexattr_setrobust 3 +.Sh STANDARDS +The +.Fn pthread_mutex_lock +function conforms to +.St -susv4 . diff --git a/static/freebsd/man3/pthread_mutex_destroy.3 b/static/freebsd/man3/pthread_mutex_destroy.3 new file mode 100644 index 00000000..3627a6c8 --- /dev/null +++ b/static/freebsd/man3/pthread_mutex_destroy.3 @@ -0,0 +1,72 @@ +.\" Copyright (c) 1997 Brian Cully +.\" 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. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 REGENTS 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 29, 1998 +.Dt PTHREAD_MUTEX_DESTROY 3 +.Os +.Sh NAME +.Nm pthread_mutex_destroy +.Nd free resources allocated for a mutex +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_mutex_destroy "pthread_mutex_t *mutex" +.Sh DESCRIPTION +The +.Fn pthread_mutex_destroy +function frees the resources allocated for +.Fa mutex . +.Sh RETURN VALUES +If successful, +.Fn pthread_mutex_destroy +will return zero, otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +The +.Fn pthread_mutex_destroy +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa mutex +is invalid. +.It Bq Er EBUSY +.Fa Mutex +is locked by another thread. +.El +.Sh SEE ALSO +.Xr pthread_mutex_init 3 , +.Xr pthread_mutex_lock 3 , +.Xr pthread_mutex_trylock 3 , +.Xr pthread_mutex_unlock 3 +.Sh STANDARDS +The +.Fn pthread_mutex_destroy +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_mutex_init.3 b/static/freebsd/man3/pthread_mutex_init.3 new file mode 100644 index 00000000..4133cf07 --- /dev/null +++ b/static/freebsd/man3/pthread_mutex_init.3 @@ -0,0 +1,76 @@ +.\" Copyright (c) 1997 Brian Cully +.\" 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. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 REGENTS 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 August 17, 2018 +.Dt PTHREAD_MUTEX_INIT 3 +.Os +.Sh NAME +.Nm pthread_mutex_init +.Nd create a mutex +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_mutex_init "pthread_mutex_t *restrict mutex" "const pthread_mutexattr_t *restrict attr" +.Sh DESCRIPTION +The +.Fn pthread_mutex_init +function creates a new mutex, with attributes specified with +.Fa attr . +If +.Fa attr +is NULL the default attributes are used. +.Sh RETURN VALUES +If successful, +.Fn pthread_mutex_init +will return zero and put the new mutex id into +.Fa mutex , +otherwise an error number will be returned to indicate the error. +.Sh ERRORS +The +.Fn pthread_mutex_init +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.It Bq Er ENOMEM +The process cannot allocate enough memory to create another mutex. +.El +.Sh SEE ALSO +.Xr pthread_mutex_destroy 3 , +.Xr pthread_mutex_lock 3 , +.Xr pthread_mutex_trylock 3 , +.Xr pthread_mutex_unlock 3 , +.Xr pthread_mutexattr 3 +.Sh STANDARDS +The +.Fn pthread_mutex_init +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_mutex_lock.3 b/static/freebsd/man3/pthread_mutex_lock.3 new file mode 100644 index 00000000..ba54cd45 --- /dev/null +++ b/static/freebsd/man3/pthread_mutex_lock.3 @@ -0,0 +1,86 @@ +.\" Copyright (c) 1997 Brian Cully +.\" 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. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 REGENTS 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 August 7, 2019 +.Dt PTHREAD_MUTEX_LOCK 3 +.Os +.Sh NAME +.Nm pthread_mutex_lock +.Nd lock a mutex +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_mutex_lock "pthread_mutex_t *mutex" +.Sh DESCRIPTION +The +.Fn pthread_mutex_lock +function locks +.Fa mutex . +If the mutex is already locked, the calling thread will block until the +mutex becomes available. +.Sh RETURN VALUES +If successful, +.Fn pthread_mutex_lock +will return zero, otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +The +.Fn pthread_mutex_lock +function will fail if: +.Bl -tag -width "Er ENOTRECOVERABLE" +.It Bq Er EINVAL +The value specified by +.Fa mutex +is invalid. +.It Bq Er EDEADLK +A deadlock would occur if the thread blocked waiting for +.Fa mutex . +.It Bq Er EOWNERDEAD +The argument +.Fa mutex +points to a robust mutex and the process containing the previous owning +thread terminated while holding the mutex lock. +The lock was granted to the caller and it is up to the new owner +to make the state consistent. +.It Bq Er ENOTRECOVERABLE +The state protected by the +.Fa mutex +is not recoverable. +.El +.Sh SEE ALSO +.Xr pthread_mutex_consistent 3 , +.Xr pthread_mutex_destroy 3 , +.Xr pthread_mutex_init 3 , +.Xr pthread_mutex_trylock 3 , +.Xr pthread_mutex_unlock 3 +.Sh STANDARDS +The +.Fn pthread_mutex_lock +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_mutex_timedlock.3 b/static/freebsd/man3/pthread_mutex_timedlock.3 new file mode 100644 index 00000000..b6e95edb --- /dev/null +++ b/static/freebsd/man3/pthread_mutex_timedlock.3 @@ -0,0 +1,113 @@ +.\" Copyright (c) 2003 Michael Telahun Makonnen +.\" 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 August 7, 2019 +.Dt PTHREAD_MUTEX_TIMEDLOCK 3 +.Os +.Sh NAME +.Nm pthread_mutex_timedlock +.Nd lock a mutex without blocking indefinitely +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.In time.h +.Ft int +.Fn pthread_mutex_timedlock "pthread_mutex_t *restrict mutex" "const struct timespec *restrict abs_timeout" +.Sh DESCRIPTION +The +.Fn pthread_mutex_timedlock +function will lock +.Fa mutex . +If it is already locked the calling thread will block until +the mutex becomes available or +the timeout, +specified by abs_timeout, +expires. +The time of the timeout is an absolute time and +is not relative to the current time. +.Sh RETURN VALUES +If successful, +.Fn pthread_mutex_timedlock +will return zero, otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +The +.Fn pthread_mutex_timedlock +function will fail if: +.Bl -tag -width Er +.It Bq "Er ENOTRECOVERABLE" +The +.Fa mutex +was created with the protocol attribute having the +value PTHREAD_PRIO_PROTECT and +the calling thread's priority is higher than the +mutex's current priority ceiling. +.It Bq Er EINVAL +The process or thread would have blocked, and +.Fa abs_timeout +specified a nanosecond value less than zero or +greater than or equal to 1 billion. +.It Bq Er EINVAL +The +.Fa mutex +parameter is invalid. +.It Bq Er ETIMEDOUT +The +.Fa mutex +could not be locked before the timeout expired. +.It Bq Er EAGAIN +The +.Fa mutex +could not be acquired because the +maximum number of recursive locks for the +.Fa mutex +has been exceeded. +.It Bq Er EDEADLK +The current thread already owns the +.Fa mutex . +.It Bq Er EOWNERDEAD +The argument +.Fa mutex +points to a robust mutex and the process containing the previous owning +thread terminated while holding the mutex lock. +The lock was granted to the caller and it is up to the new owner +to make the state consistent. +.It Bq Er ENOTRECOVERABLE +The state protected by the +.Fa mutex +is not recoverable. +.El +.Sh SEE ALSO +.Xr pthread_mutex_consistent 3 , +.Xr pthread_mutex_destroy 3 , +.Xr pthread_mutex_init 3 , +.Xr pthread_mutex_lock 3 , +.Xr pthread_mutex_trylock 3 , +.Xr pthread_mutex_unlock 3 +.Sh STANDARDS +The +.Fn pthread_mutex_timedlock +function is expected to conform to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_mutex_trylock.3 b/static/freebsd/man3/pthread_mutex_trylock.3 new file mode 100644 index 00000000..cd08d760 --- /dev/null +++ b/static/freebsd/man3/pthread_mutex_trylock.3 @@ -0,0 +1,87 @@ +.\" Copyright (c) 1997 Brian Cully +.\" 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. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 REGENTS 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 August 7, 2019 +.Dt PTHREAD_MUTEX_TRYLOCK 3 +.Os +.Sh NAME +.Nm pthread_mutex_trylock +.Nd attempt to lock a mutex without blocking +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_mutex_trylock "pthread_mutex_t *mutex" +.Sh DESCRIPTION +The +.Fn pthread_mutex_trylock +function locks +.Fa mutex . +If the mutex is already locked, +.Fn pthread_mutex_trylock +will not block waiting for the mutex, but will return an error condition. +.Sh RETURN VALUES +If successful, +.Fn pthread_mutex_trylock +will return zero, otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +The +.Fn pthread_mutex_trylock +function will fail if: +.Bl -tag -width "Er ENOTRECOVERABLE" +.It Bq Er EINVAL +The value specified by +.Fa mutex +is invalid. +.It Bq Er EBUSY +.Fa Mutex +is already locked. +.It Bq Er EOWNERDEAD +The argument +.Fa mutex +points to a robust mutex and the process containing the previous owning +thread terminated while holding the mutex lock. +The lock was granted to the caller and it is up to the new owner +to make the state consistent. +.It Bq Er ENOTRECOVERABLE +The state protected by the +.Fa mutex +is not recoverable. +.El +.Sh SEE ALSO +.Xr pthread_mutex_consistent 3 , +.Xr pthread_mutex_destroy 3 , +.Xr pthread_mutex_init 3 , +.Xr pthread_mutex_lock 3 , +.Xr pthread_mutex_unlock 3 +.Sh STANDARDS +The +.Fn pthread_mutex_trylock +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_mutex_unlock.3 b/static/freebsd/man3/pthread_mutex_unlock.3 new file mode 100644 index 00000000..eb6866a2 --- /dev/null +++ b/static/freebsd/man3/pthread_mutex_unlock.3 @@ -0,0 +1,85 @@ +.\" Copyright (c) 1997 Brian Cully +.\" 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. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 29, 2016 +.Dt PTHREAD_MUTEX_UNLOCK 3 +.Os +.Sh NAME +.Nm pthread_mutex_unlock +.Nd unlock a mutex +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_mutex_unlock "pthread_mutex_t *mutex" +.Sh DESCRIPTION +If the current thread holds the lock on +.Fa mutex , +then the +.Fn pthread_mutex_unlock +function unlocks +.Fa mutex . +.Pp +If the argument pointed by the +.Fa mutex +is a robust mutex in the inconsistent state, and the call to +.Fn pthread_mutex_consistent +function was not done prior to unlocking, further locking attempts on +the mutex +.Fa mutex +are denied and locking functions return +.Er ENOTRECOVERABLE +error. +.Sh RETURN VALUES +If successful, +.Fn pthread_mutex_unlock +will return zero, otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +The +.Fn pthread_mutex_unlock +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa mutex +is invalid. +.It Bq Er EPERM +The current thread does not hold a lock on +.Fa mutex . +.El +.Sh SEE ALSO +.Xr pthread_mutex_destroy 3 , +.Xr pthread_mutex_init 3 , +.Xr pthread_mutex_lock 3 , +.Xr pthread_mutex_trylock 3 +.Sh STANDARDS +The +.Fn pthread_mutex_unlock +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_mutexattr.3 b/static/freebsd/man3/pthread_mutexattr.3 new file mode 100644 index 00000000..b18d93e2 --- /dev/null +++ b/static/freebsd/man3/pthread_mutexattr.3 @@ -0,0 +1,368 @@ +.\" Copyright (C) 2000 Jason Evans . +.\" Copyright (c) 2021 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" Part of this documentation was written by +.\" Konstantin Belousov under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 October 27, 2023 +.Dt PTHREAD_MUTEXATTR 3 +.Os +.Sh NAME +.Nm pthread_mutexattr_init , +.Nm pthread_mutexattr_destroy , +.Nm pthread_mutexattr_setprioceiling , +.Nm pthread_mutexattr_getprioceiling , +.Nm pthread_mutexattr_setprotocol , +.Nm pthread_mutexattr_getprotocol , +.Nm pthread_mutexattr_setpshared , +.Nm pthread_mutexattr_getpshared , +.Nm pthread_mutexattr_setrobust , +.Nm pthread_mutexattr_getrobust , +.Nm pthread_mutexattr_settype , +.Nm pthread_mutexattr_gettype +.Nd mutex attribute operations +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_mutexattr_init "pthread_mutexattr_t *attr" +.Ft int +.Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr" +.Ft int +.Fo pthread_mutexattr_setprioceiling +.Fa "pthread_mutexattr_t *attr" "int prioceiling" +.Fc +.Ft int +.Fo pthread_mutexattr_getprioceiling +.Fa "const pthread_mutexattr_t *attr" "int *prioceiling" +.Fc +.Ft int +.Fn pthread_mutexattr_setprotocol "pthread_mutexattr_t *attr" "int protocol" +.Ft int +.Fo pthread_mutexattr_getprotocol +.Fa "const pthread_mutexattr_t *restrict attr" "int *restrict protocol" +.Fc +.Ft int +.Fo pthread_mutexattr_setpshared +.Fa "pthread_mutexattr_t *attr" "int shared" +.Fc +.Ft int +.Fo pthread_mutexattr_getpshared +.Fa "const pthread_mutexattr_t *attr" "int *shared" +.Fc +.Ft int +.Fn pthread_mutexattr_setrobust "pthread_mutexattr_t *attr" "int robust" +.Ft int +.Fn pthread_mutexattr_getrobust "pthread_mutexattr_t *attr" "int *robust" +.Ft int +.Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type" +.Ft int +.Fo pthread_mutexattr_gettype +.Fa "const pthread_mutexattr_t *restrict attr" "int *restrict type" +.Fc +.Sh DESCRIPTION +Mutex attributes are used to specify parameters to +.Fn pthread_mutex_init . +One attribute object can be used in multiple calls to +.Fn pthread_mutex_init , +with or without modifications between calls. +.Pp +The +.Fn pthread_mutexattr_init +function initializes +.Fa attr +with all the default mutex attributes. +.Pp +The +.Fn pthread_mutexattr_destroy +function destroys +.Fa attr . +.Pp +The +.Fn pthread_mutexattr_setprioceiling +function sets the priority ceiling for the mutex, used +by threads executed under the +.Dv PTHREAD_PRIO_PROTECT +protocol. +.Pp +The +.Fn pthread_mutexattr_setprotocol +function specifies the protocol to be followed in utilizing mutexes. +The +.Fa protocol +argument can take one of the following values: +.Bl -tag -width PTHREAD_PRIO_PROTECT +.It PTHREAD_PRIO_NONE +Priority and scheduling of the thread owning this mutex is not +affected by its mutex ownership. +.It PTHREAD_PRIO_INHERIT +Request priority-inheritance protocol, where the thread owning the mutex +is executed at the highest priority among priorities of all threads waiting +on any mutex owned by this thread. +.It PTHREAD_PRIO_PROTECT +Request priority-inheritance protocol, where the thread owning the mutex +is executed at highest priority among priorities or priority ceilings of +all threads waiting on any mutex owned by this thread. +.El +.Pp +The +.Fn pthread_mutexattr_setpshared +function sets the process-shared attribute of +.Fa attr +to the value specified in +.Fa pshared . +The argument +.Fa pshared +may have one of the following values: +.Bl -tag -width ".Dv PTHREAD_PROCESS_PRIVATE" +.It Dv PTHREAD_PROCESS_PRIVATE +The mutex may only be used by threads in the same process as the one +that created the object. +.It Dv PTHREAD_PROCESS_SHARED +The mutex may be used by +threads in processes other than the one that created the object, +assuming other processes share access to the memory where the mutex +was allocated. +.El +See +.Xr libthr 3 +for details of the implementation of the shared mutexes, +and their limitations. +.Pp +The +.Fn pthread_mutexattr_setrobust +function specifies robustness attribute of the mutex. +Possible values for the +.Fa robust +argument are +.Bl -tag -width PTHREAD_MUTEX_STALLED +.It PTHREAD_MUTEX_STALLED +No special actions are taken if the thread owning the mutex is terminated +without unlocking the mutex lock. +This can lead to deadlocks if no other thread can unlock the mutex. +This is the default value. +.It PTHREAD_MUTEX_ROBUST +If the process containing the owning thread of a robust mutex, or owning +thread, terminates while holding the mutex lock, the next thread that +acquires the mutex is notified about the termination +by the return value +.Ev EOWNERDEAD +from the locking function. +Then, either +.Xr pthread_mutex_consistent 3 +can be used to repair the mutex lock state, or +.Xr pthread_mutex_unlock 3 +can unlock the mutex lock but also put it an unusable state, +where all further attempts to acquire it result in the +.Ev ENOTRECOVERABLE +error. +.El +.Pp +The +.Fn pthread_mutexattr_settype +function sets the type of the mutex. +The type affects the behavior of calls which lock and unlock the mutex. +The possible values for the +.Fa type +argument are +.Bl -tag -width PTHREAD_MUTEX_ERRORCHECK +.It PTHREAD_MUTEX_NORMAL +Both recursive locking, and unlocking when the lock is not owned by the current +thread, cause an error to be returned from the corresponding functions. +This matches +.Dv PTHREAD_MUTEX_ERRORCHECK +but somewhat contradicts the behavior mandated by POSIX. +.It PTHREAD_MUTEX_ERRORCHECK +Both recursive locking, and unlocking when the lock is not owned by the current +thread, cause an error returned from the corresponding functions. +.It PTHREAD_MUTEX_RECURSIVE +Recursive locking is allowed. +Attempt to unlock when current thread is not an owner of the lock causes +an error to be returned. +.It PTHREAD_MUTEX_DEFAULT +The +.Fx +implementation maps this type to +.Dv PTHREAD_MUTEX_ERRORCHECK +type. +.El +.Pp +The +.Fn pthread_mutexattr_get* +functions copy the value of the attribute that corresponds to each function name +to the location pointed to by the second function parameter. +.Sh RETURN VALUES +If successful, these functions return 0. +Otherwise, an error number is returned to indicate the error. +.Sh ERRORS +The +.Fn pthread_mutexattr_init +function will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Out of memory. +.El +.Pp +The +.Fn pthread_mutexattr_destroy +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.El +.Pp +The +.Fn pthread_mutexattr_setprioceiling +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr , +or invalid value for +.Fa prioceiling . +.El +.Pp +The +.Fn pthread_mutexattr_getprioceiling +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.El +.Pp +The +.Fn pthread_mutexattr_setprotocol +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr , +or invalid value for +.Fa protocol . +.El +.Pp +The +.Fn pthread_mutexattr_getprotocol +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.El +.Pp +The +.Fn pthread_mutexattr_setpshared +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr , +or invalid value for +.Fa shared . +.El +.Pp +The +.Fn pthread_mutexattr_getpshared +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.El +.Pp +The +.Fn pthread_mutexattr_settype +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr , +or invalid value for +.Fa type . +.El +.Pp +The +.Fn pthread_mutexattr_gettype +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.El +.Pp +The +.Fn pthread_mutexattr_setrobust +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr , +or invalid value for +.Fa robust . +.El +.Pp +The +.Fn pthread_mutexattr_getrobust +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.El +.Sh SEE ALSO +.Xr libthr 3 , +.Xr pthread_mutex_init 3 +.Sh STANDARDS +The +.Fn pthread_mutexattr_init +and +.Fn pthread_mutexattr_destroy +functions conform to +.St -p1003.1-96 +.Pp +The +.Fn pthread_mutexattr_setprioceiling , +.Fn pthread_mutexattr_getprioceiling , +.Fn pthread_mutexattr_setprotocol , +.Fn pthread_mutexattr_getprotocol , +.Fn pthread_mutexattr_setpshared , +.Fn pthread_mutexattr_getpshared , +.Fn pthread_mutexattr_settype , +and +.Fn pthread_mutexattr_gettype +functions conform to +.St -susv2 . +The +.Fn pthread_mutexattr_setrobust +and +.Fn pthread_mutexattr_getrobust +functions conform to +.St -susv4 . diff --git a/static/freebsd/man3/pthread_mutexattr_getkind_np.3 b/static/freebsd/man3/pthread_mutexattr_getkind_np.3 new file mode 100644 index 00000000..15eb7061 --- /dev/null +++ b/static/freebsd/man3/pthread_mutexattr_getkind_np.3 @@ -0,0 +1,80 @@ +.\" Copyright (c) 2003 Alexey Zelkin +.\" 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 October 12, 2021 +.Dt PTHREAD_MUTEXATTR_GETKIND_NP 3 +.Os +.Sh NAME +.Nm pthread_mutexattr_getkind_np , +.Nm pthread_mutexattr_setkind_np +.Nd mutex attribute operations (legacy) +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Ft int +.Fn pthread_mutexattr_getkind_np "pthread_mutexattr_t attr" +.Ft int +.Fn pthread_mutexattr_setkind_np "pthread_mutexattr_t *attr" "int kind" +.Sh DESCRIPTION +.Bf -symbolic +These functions are deprecated and non-portable implementation of +the mutex type manipulation. +.Ef +.Pp +It is recommended to use the +.Xr pthread_mutexattr_gettype 3 +and +.Xr pthread_mutexattr_settype 3 +functions instead. +.Sh RETURN VALUES +The +.Fn pthread_mutexattr_getkind_np +function returns a positive value representing the +.Dq kind +of the mutex attribute +.Fa attr +if successful; otherwise the value \-1 is returned and the global variable +.Va errno +is set to indicate the error. +.Pp +.Rv -std pthread_mutexattr_setkind_np +.Sh ERRORS +The +.Fn pthread_mutexattr_getkind_np +and +.Fn pthread_mutexattr_setkind_np +functions will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.El +.Sh SEE ALSO +.Xr pthread_mutex_destroy 3 , +.Xr pthread_mutex_init 3 , +.Xr pthread_mutexattr_gettype 3 , +.Xr pthread_mutexattr_settype 3 , +.Xr pthread_np 3 diff --git a/static/freebsd/man3/pthread_np.3 b/static/freebsd/man3/pthread_np.3 new file mode 100644 index 00000000..c6f0efac --- /dev/null +++ b/static/freebsd/man3/pthread_np.3 @@ -0,0 +1,226 @@ +.\" Copyright (c) 2021 Felix Johnson +.\" +.\" 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 COPYRIGHT HOLDERS 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 COPYRIGHT +.\" HOLDER 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 October 12, 2021 +.Dt PTHREAD_NP 3 +.Os +.Sh NAME +.Nm pthread_np +.Nd FreeBSD extensions to POSIX thread functions +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Sh DESCRIPTION +This manual page documents extensions to the POSIX thread functions. +These extensions may or may not be portable to other operating systems. +.Pp +The POSIX thread functions are summarized in this section in the following +groups: +.Pp +.Bl -bullet -offset indent -compact +.It +Thread Routines +.It +Attribute Object Routines +.It +Mutex Routines +.El +.\" .It +.\" Condition Variable Routines +.\" .It +.\" Read/Write Lock Routines +.\" .It +.\" Per-Thread Context Routines +.\" .It +.\" Cleanup Routines +.Ss Thread Routines +.Bl -tag -width indent +.It Xo +.Ft int +.Fo pthread_getaffinity_np +.Fa "pthread_t td" "size_t cpusetsize" "cpuset_t *cpusetp" +.Fc +.Xc +Get the CPU affinity of a specified thread. +.It Xo +.Ft int +.Fn pthread_get_name_np "pthread_t thread" "char *name" "size_t len" +.Xc +Get the name of a specified thread. +.It Xo +.Ft int +.Fn pthread_getname_np "pthread_t thread" "char *name" "size_t len" +.Xc +Get the name of a specified thread. +.It Xo +.Ft int +.Fn pthread_getthreadid_np void +.Xc +Get the calling thread's integral ID. +.It Xo +.Ft int +.Fn pthread_main_np void +.Xc +Identify the initial thread. +.It Xo +.Ft int +.Fn pthread_multi_np void +.Xc +Sets the thread's scheduling mode to multi-threaded. +.It Xo +.Ft int +.Fn pthread_peekjoin_np "pthread_t thread" "void **value_ptr" +.Xc +Peek into the exit status of a specified thread. +.It Xo +.Ft int +.Fn pthread_resume_all_np void +.Xc +Resume all suspended threads. +.It Xo +.Ft int +.Fo pthread_setaffinity_np +.Fa "pthread_t td" "size_t cpusetsize" "const cpuset_t *cpusetp" +.Fc +.Xc +Set the CPU affinity of a specified thread. +.It Xo +.Ft int +.Fn pthread_set_name_np "pthread_t thread" "char *name" +.Xc +Sets the specified thread's name. +.It Xo +.Ft int +.Fn pthread_setname_np "pthread_t thread" "char *name" +.Xc +Sets the specified thread's name. +.It Xo +.Ft void +.Fn pthread_signals_block_np void +.Xc +Blocks all asynchronous signals, quickly. +.It Xo +.Ft int +.Fn pthread_single_np void +.Xc +Sets the thread's scheduling mode to single-threaded. +.It Xo +.Ft int +.Fn pthread_suspend_np "pthread_t tid" +.Xc +Suspend the specified thread. +.It Xo +.Ft int +.Fn pthread_suspend_all_np void +.Xc +Suspend all active threads. +.It Xo +.Ft int +.Fo pthread_timedjoin_np +.Fa "pthread_t thread" "void **value_ptr" "const struct timespec *abstime" +.Fc +.Xc +A variant of +.Fn pthread_join +with a timeout. +.El +.Ss Attribute Object Routines +.Bl -tag -width indent +.It Xo +.Ft int +.Fo pthread_attr_get_np +.Fa "pthread_t pid" "pthread_attr_t *dst" +.Fc +.Xc +Get the attributes of an existent thread. +.It Xo +.Ft int +.Fo pthread_attr_getaffinity_np +.Fa "const pthread_attr_t *pattr" "size_t cpusetsize" "cpuset_t *cpusetp" +.Fc +.Xc +Get the CPU affinity mask from the thread attribute object. +.It Xo +.Ft int +.Fo pthread_attr_setaffinity_np +.Fa "pthread_attr_t *pattr" "size_t cpusetsize" "const cpuset_t *cpusetp" +.Fc +.Xc +Set the CPU affinity mask for the thread attribute object. +.It Xo +.Ft int +.Fn pthread_attr_setcreatesuspend_np "pthread_attr_t *attr" +.Xc +Permit creation of suspended threads. +.El +.Ss Mutex Routines +.Bl -tag -width indent +.It Xo +.Ft int +.Fn pthread_mutexattr_getkind_np "pthread_mutexattr_t attr" +.Xc +Deprecated, use +.Xr pthread_mutexattr_gettype 3 +instead. +.It Xo +.Ft int +.Fn pthread_mutexattr_setkind_np "pthread_mutexattr_t *attr" +.Xc +Deprecated, use +.Xr pthread_mutexattr_settype 3 +instead. +.El +.\" .Ss Condition Variable Routines +.\" .Bl -tag -width indent +.\" .El +.\" .Ss Read/Write Lock Routines +.\" .Bl -tag -width indent +.\" .El +.\" .Ss Per-Thread Context Routines +.\" .Bl -tag -width indent +.\" .El +.\" .Ss Cleanup Routines +.\" .Bl -tag -width indent +.\" .El +.Sh SEE ALSO +.Xr libthr 3 , +.Xr pthread 3 , +.Xr pthread_affinity_np 3 , +.Xr pthread_attr_affinity_np 3 , +.Xr pthread_attr_get_np 3 , +.Xr pthread_attr_setcreatesuspend_np 3 , +.Xr pthread_getthreadid_np 3 , +.Xr pthread_join 3 , +.Xr pthread_main_np 3 , +.Xr pthread_multi_np 3 , +.Xr pthread_mutexattr_getkind_np 3 , +.Xr pthread_resume_all_np 3 , +.Xr pthread_resume_np 3 , +.Xr pthread_set_name_np 3 , +.Xr pthread_signals_block_np 3 , +.Xr pthread_suspend_all_np 3 , +.Xr pthread_suspend_np 3 , +.Xr pthread_switch_add_np 3 +.Sh STANDARDS +All of these functions are non-portable extensions to POSIX threads. diff --git a/static/freebsd/man3/pthread_once.3 b/static/freebsd/man3/pthread_once.3 new file mode 100644 index 00000000..1ff0a74b --- /dev/null +++ b/static/freebsd/man3/pthread_once.3 @@ -0,0 +1,105 @@ +.\" Copyright (c) 1996 John Birrell . +.\" 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 John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 4, 1996 +.Dt PTHREAD_ONCE 3 +.Os +.Sh NAME +.Nm pthread_once +.Nd dynamic package initialization +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Pp +pthread_once_t +.Fa once_control += PTHREAD_ONCE_INIT; +.Ft int +.Fn pthread_once "pthread_once_t *once_control" "void (*init_routine)(void)" +.Sh DESCRIPTION +The first call to +.Fn pthread_once +by any thread in a process, with a given +.Fa once_control , +will call the +.Fn init_routine +with no arguments. +Subsequent calls to +.Fn pthread_once +with the same +.Fa once_control +will not call the +.Fn init_routine . +On return from +.Fn pthread_once , +it is guaranteed that +.Fn init_routine +has completed. +The +.Fa once_control +parameter is used to determine whether the associated initialization +routine has been called. +.Pp +The function +.Fn pthread_once +is not a cancellation point. +However, if +.Fn init_routine +is a cancellation point and is cancelled, the effect on +.Fa once_control +is as if +.Fn pthread_once +was never called. +.Pp +The constant +.Fa PTHREAD_ONCE_INIT +is defined by header +.In pthread.h . +.Pp +The behavior of +.Fn pthread_once +is undefined if +.Fa once_control +has automatic storage duration or is not initialized by +.Fa PTHREAD_ONCE_INIT . +.Sh RETURN VALUES +If successful, the +.Fn pthread_once +function will return zero. +Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +None. +.Sh STANDARDS +The +.Fn pthread_once +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_resume_all_np.3 b/static/freebsd/man3/pthread_resume_all_np.3 new file mode 100644 index 00000000..411d5a57 --- /dev/null +++ b/static/freebsd/man3/pthread_resume_all_np.3 @@ -0,0 +1,50 @@ +.\" Copyright (c) 2003 Alexey Zelkin +.\" 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 October 12, 2021 +.Dt PTHREAD_RESUME_ALL_NP 3 +.Os +.Sh NAME +.Nm pthread_resume_all_np +.Nd resume all suspended threads +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Ft void +.Fn pthread_resume_all_np void +.Sh DESCRIPTION +The +.Fn pthread_resume_all_np +function causes all active threads to be scanned +and resumes those which were previously suspended. +.Sh SEE ALSO +.Xr pthread_attr_setcreatesuspend_np 3 , +.Xr pthread_np 3 , +.Xr pthread_resume_np 3 , +.Xr pthread_suspend_all_np 3 , +.Xr pthread_suspend_np 3 +.Sh AUTHORS +This manual page was written by +.An Alexey Zelkin Aq Mt phantom@FreeBSD.org . diff --git a/static/freebsd/man3/pthread_resume_np.3 b/static/freebsd/man3/pthread_resume_np.3 new file mode 100644 index 00000000..546e1336 --- /dev/null +++ b/static/freebsd/man3/pthread_resume_np.3 @@ -0,0 +1,71 @@ +.\" Copyright (c) 2003 Alexey Zelkin +.\" 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 October 12, 2021 +.Dt PTHREAD_RESUME_NP 3 +.Os +.Sh NAME +.Nm pthread_resume_np +.Nd resume suspended thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Ft int +.Fn pthread_resume_np "pthread_t tid" +.Sh DESCRIPTION +The +.Fn pthread_resume_np +function, called on a suspended thread, causes it to resume. +If a thread specified by the +.Fa tid +argument is not suspended, no actions will be performed. +.Sh RETURN VALUES +If successful, +.Fn pthread_resume_np +function returns 0. +Otherwise, an error number is returned to indicate the error. +.Sh ERRORS +The +.Fn pthread_resume_np +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by the +.Fa tid +argument is invalid. +.It Bq Er ESRCH +No thread could be found corresponding to the thread ID specified by the +.Fa tid +argument. +.El +.Sh SEE ALSO +.Xr pthread_attr_setcreatesuspend_np 3 , +.Xr pthread_np 3 , +.Xr pthread_resume_all_np 3 , +.Xr pthread_suspend_all_np 3 , +.Xr pthread_suspend_np 3 +.Sh AUTHORS +This manual page was written by +.An Alexey Zelkin Aq Mt phantom@FreeBSD.org . diff --git a/static/freebsd/man3/pthread_rwlock_destroy.3 b/static/freebsd/man3/pthread_rwlock_destroy.3 new file mode 100644 index 00000000..9c50e71f --- /dev/null +++ b/static/freebsd/man3/pthread_rwlock_destroy.3 @@ -0,0 +1,81 @@ +.\" Copyright (c) 1998 Alex Nash +.\" 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 August 4, 1998 +.Dt PTHREAD_RWLOCK_DESTROY 3 +.Os +.Sh NAME +.Nm pthread_rwlock_destroy +.Nd destroy a read/write lock +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_rwlock_destroy "pthread_rwlock_t *lock" +.Sh DESCRIPTION +The +.Fn pthread_rwlock_destroy +function is used to destroy a read/write lock previously created with +.Fn pthread_rwlock_init . +.Sh RETURN VALUES +If successful, the +.Fn pthread_rwlock_destroy +function will return zero. +Otherwise an error number will be returned +to indicate the error. +.Sh ERRORS +The +.Fn pthread_rwlock_destroy +function will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +The caller does not have the privilege to perform the operation. +.El +.Pp +The +.Fn pthread_rwlock_destroy +function may fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +The system has detected an attempt to destroy the object referenced by +.Fa lock +while it is locked. +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.El +.Sh SEE ALSO +.Xr pthread_rwlock_init 3 +.Sh STANDARDS +The +.Fn pthread_rwlock_destroy +function is expected to conform to +.St -susv2 . +.Sh HISTORY +The +.Fn pthread_rwlock_destroy +function first appeared in +.Fx 3.0 . diff --git a/static/freebsd/man3/pthread_rwlock_init.3 b/static/freebsd/man3/pthread_rwlock_init.3 new file mode 100644 index 00000000..e6474199 --- /dev/null +++ b/static/freebsd/man3/pthread_rwlock_init.3 @@ -0,0 +1,98 @@ +.\" Copyright (c) 1998 Alex Nash +.\" 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 August 17, 2018 +.Dt PTHREAD_RWLOCK_INIT 3 +.Os +.Sh NAME +.Nm pthread_rwlock_init +.Nd initialize a read/write lock +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_rwlock_init "pthread_rwlock_t *restrict lock" "const pthread_rwlockattr_t *restrict attr" +.Sh DESCRIPTION +The +.Fn pthread_rwlock_init +function is used to initialize a read/write lock, with attributes +specified by +.Fa attr . +If +.Fa attr +is NULL, the default read/write lock attributes are used. +.Pp +The results of calling +.Fn pthread_rwlock_init +with an already initialized lock are undefined. +.Sh RETURN VALUES +If successful, the +.Fn pthread_rwlock_init +function will return zero. +Otherwise an error number will be returned +to indicate the error. +.Sh ERRORS +The +.Fn pthread_rwlock_init +function will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system lacked the necessary resources (other than memory) to +initialize the lock. +.It Bq Er ENOMEM +Insufficient memory exists to initialize the lock. +.It Bq Er EPERM +The caller does not have sufficient privilege to perform the +operation. +.El +.Pp +The +.Fn pthread_rwlock_init +function may fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +The system has detected an attempt to re-initialize the object +referenced by +.Fa lock , +a previously initialized but not yet destroyed read/write lock. +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.El +.Sh SEE ALSO +.Xr pthread_rwlock_destroy 3 , +.Xr pthread_rwlockattr_init 3 , +.Xr pthread_rwlockattr_setpshared 3 +.Sh STANDARDS +The +.Fn pthread_rwlock_init +function is expected to conform to +.St -susv2 . +.Sh HISTORY +The +.Fn pthread_rwlock_init +function first appeared in +.Fx 3.0 . diff --git a/static/freebsd/man3/pthread_rwlock_rdlock.3 b/static/freebsd/man3/pthread_rwlock_rdlock.3 new file mode 100644 index 00000000..f8403fc8 --- /dev/null +++ b/static/freebsd/man3/pthread_rwlock_rdlock.3 @@ -0,0 +1,125 @@ +.\" Copyright (c) 1998 Alex Nash +.\" 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 August 4, 1998 +.Dt PTHREAD_RWLOCK_RDLOCK 3 +.Os +.Sh NAME +.Nm pthread_rwlock_rdlock , +.Nm pthread_rwlock_tryrdlock +.Nd acquire a read/write lock for reading +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_rwlock_rdlock "pthread_rwlock_t *lock" +.Ft int +.Fn pthread_rwlock_tryrdlock "pthread_rwlock_t *lock" +.Sh DESCRIPTION +The +.Fn pthread_rwlock_rdlock +function acquires a read lock on +.Fa lock +provided that +.Fa lock +is not presently held for writing and no writer threads are +presently blocked on the lock. +If the read lock cannot be +immediately acquired, the calling thread blocks until it can +acquire the lock. +.Pp +The +.Fn pthread_rwlock_tryrdlock +function performs the same action, but does not block if the lock +cannot be immediately obtained (i.e., the lock is held for writing +or there are waiting writers). +.Pp +A thread may hold multiple concurrent read locks. +If so, +.Fn pthread_rwlock_unlock +must be called once for each lock obtained. +.Pp +The results of acquiring a read lock while the calling thread holds +a write lock are undefined. +.Sh IMPLEMENTATION NOTES +To prevent writer starvation, writers are favored over readers. +.Sh RETURN VALUES +If successful, the +.Fn pthread_rwlock_rdlock +and +.Fn pthread_rwlock_tryrdlock +functions will return zero. +Otherwise an error number will be returned +to indicate the error. +.Sh ERRORS +The +.Fn pthread_rwlock_tryrdlock +function will fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +The lock could not be acquired because a writer holds the lock or +was blocked on it. +.El +.Pp +The +.Fn pthread_rwlock_rdlock +and +.Fn pthread_rwlock_tryrdlock +functions may fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The lock could not be acquired because the maximum number of read locks +against +.Fa lock +has been exceeded. +.It Bq Er EDEADLK +The current thread already owns +.Fa lock +for writing. +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.It Bq Er ENOMEM +Insufficient memory exists to initialize the lock (applies to +statically initialized locks only). +.El +.Sh SEE ALSO +.Xr pthread_rwlock_init 3 , +.Xr pthread_rwlock_trywrlock 3 , +.Xr pthread_rwlock_unlock 3 , +.Xr pthread_rwlock_wrlock 3 +.Sh STANDARDS +The +.Fn pthread_rwlock_rdlock +and +.Fn pthread_rwlock_tryrdlock +functions are expected to conform to +.St -susv2 . +.Sh HISTORY +The +.Fn pthread_rwlock_rdlock +function first appeared in +.Fx 3.0 . diff --git a/static/freebsd/man3/pthread_rwlock_timedrdlock.3 b/static/freebsd/man3/pthread_rwlock_timedrdlock.3 new file mode 100644 index 00000000..2b736529 --- /dev/null +++ b/static/freebsd/man3/pthread_rwlock_timedrdlock.3 @@ -0,0 +1,116 @@ +.\" Copyright (c) 2004 Michael Telahun Makonnen +.\" 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 August 17, 2018 +.Dt PTHREAD_RWLOCK_TIMEDRDLOCK 3 +.Os +.Sh NAME +.Nm pthread_rwlock_timedrdlock +.Nd "acquire a read-write lock for reading or give up after a specified period" +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_rwlock_timedrdlock "pthread_rwlock_t *restrict rwlock" "const struct timespec *restrict abs_timeout" +.Sh DESCRIPTION +This function acquires a read lock on the read-write lock +.Fa rwlock . +However, if the lock cannot be +acquired without waiting for another thread to +unlock the lock, +this wait shall be terminated when +.Fa abs_timeout +expires. +.Pp +A thread may hold multiple concurrent read locks. +The +.Xr pthread_rwlock_unlock 3 +function must be called once for each lock acquired. +.Pp +If the thread should be interrupted by a signal, +the +.Fn pthread_rwlock_timedrdlock +function will be automatically restarted after the thread returns from +the signal handler. +.Pp +The calling thread may deadlock if +at the time the call is made it holds a write lock on +.Fa rwlock . +The results are undefined if this function is called with +an uninitialized read-write lock. +.Sh IMPLEMENTATION NOTES +To prevent writer starvation, writers are favored over readers. +.Sh RETURN VALUES +If successful, the +.Fn pthread_rwlock_timedrdlock +function will return zero. +Otherwise, an error number will be returned to indicate the error. +.Pp +This function shall not return an error code of +.Er EINTR . +.Sh ERRORS +The +.Fn pthread_rwlock_timedrdlock +function will fail if: +.Bl -tag -width Er +.It Bq Er ETIMEDOUT +The lock could not be acquired before the specified timeout expired. +.El +.Pp +The +.Fn pthread_rwlock_timedrdlock +function may fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The read lock could not be +acquired because the maximum number of read locks for +.Fa rwlock +would be exceeded. +.It Bq Er EDEADLK +The calling thread already holds a write lock on +.Fa rwlock . +.It Bq Er EINVAL +The value specified by +.Fa rwlock +does not refer to an initialized read-write lock object, +or the +.Fa abs_timeout +nanosecond value is less than zero or +greater than or equal to 1 billion. +.El +.Sh SEE ALSO +.Xr pthread_rwlock_init 3 , +.Xr pthread_rwlock_timedwrlock 3 , +.Xr pthread_rwlock_unlock 3 +.Sh STANDARDS +The +.Fn pthread_rwlock_timedrdlock +function is expected to conform to +.St -p1003.1-96 . +.Sh HISTORY +The +.Fn pthread_rwlock_timedrdlock +function first appeared in +.Fx 5.2 . diff --git a/static/freebsd/man3/pthread_rwlock_timedwrlock.3 b/static/freebsd/man3/pthread_rwlock_timedwrlock.3 new file mode 100644 index 00000000..4543eff4 --- /dev/null +++ b/static/freebsd/man3/pthread_rwlock_timedwrlock.3 @@ -0,0 +1,106 @@ +.\" Copyright (c) 2004 Michael Telahun Makonnen +.\" 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 August 17, 2018 +.Dt PTHREAD_RWLOCK_TIMEDWRLOCK 3 +.Os +.Sh NAME +.Nm pthread_rwlock_timedwrlock +.Nd "acquire a read-write lock for writing or give up after a specified period" +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_rwlock_timedwrlock "pthread_rwlock_t *restrict rwlock" "const struct timespec *restrict abs_timeout" +.Sh DESCRIPTION +This function acquires a write lock on the read-write lock +.Fa rwlock . +However, if the lock cannot be +acquired without waiting for another thread to +unlock the lock, +this wait shall be terminated when +.Fa abs_timeout +expires. +.Pp +If the thread should be interrupted by a signal, +the +.Fn pthread_rwlock_timedwrlock +function will be automatically restarted after the thread returns from +the signal handler. +.Pp +The calling thread may deadlock if +at the time the call is made it holds +.Fa rwlock . +The results are undefined if this function is called with +an uninitialized read-write lock. +.Sh IMPLEMENTATION NOTES +To prevent writer starvation, writers are favored over readers. +.Sh RETURN VALUES +If successful, the +.Fn pthread_rwlock_timedwrlock +function will return zero. +Otherwise, an error number will be returned to indicate the error. +.Pp +This function shall not return an error code of +.Er EINTR . +.Sh ERRORS +The +.Fn pthread_rwlock_timedwrlock +function shall fail if: +.Bl -tag -width Er +.It Bq Er ETIMEDOUT +The lock could not be acquired before the specified timeout expired. +.El +.Pp +The +.Fn pthread_rwlock_timedwrlock +function may fail if: +.Bl -tag -width Er +.It Bq Er EDEADLK +The calling thread already holds +.Fa rwlock . +.It Bq Er EINVAL +The value specified by +.Fa rwlock +does not refer to an initialized read-write lock object, +or the +.Fa abs_timeout +nanosecond value is less than zero or +greater than or equal to 1 billion. +.El +.Sh SEE ALSO +.Xr pthread_rwlock_init 3 , +.Xr pthread_rwlock_timedrdlock 3 , +.Xr pthread_rwlock_unlock 3 +.Sh STANDARDS +The +.Fn pthread_rwlock_timedwrlock +function is expected to conform to +.St -p1003.1-96 . +.Sh HISTORY +The +.Fn pthread_rwlock_timedwrlock +function first appeared in +.Fx 5.2 . diff --git a/static/freebsd/man3/pthread_rwlock_unlock.3 b/static/freebsd/man3/pthread_rwlock_unlock.3 new file mode 100644 index 00000000..8e348e92 --- /dev/null +++ b/static/freebsd/man3/pthread_rwlock_unlock.3 @@ -0,0 +1,80 @@ +.\" Copyright (c) 1998 Alex Nash +.\" 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 August 4, 1998 +.Dt PTHREAD_RWLOCK_UNLOCK 3 +.Os +.Sh NAME +.Nm pthread_rwlock_unlock +.Nd release a read/write lock +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_rwlock_unlock "pthread_rwlock_t *lock" +.Sh DESCRIPTION +The +.Fn pthread_rwlock_unlock +function is used to release the read/write lock previously obtained by +.Fn pthread_rwlock_rdlock , +.Fn pthread_rwlock_wrlock , +.Fn pthread_rwlock_tryrdlock , +or +.Fn pthread_rwlock_trywrlock . +.Sh RETURN VALUES +If successful, the +.Fn pthread_rwlock_unlock +function will return zero. +Otherwise an error number will be returned +to indicate the error. +.Pp +The results are undefined if +.Fa lock +is not held by the calling thread. +.Sh ERRORS +The +.Fn pthread_rwlock_unlock +function may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.It Bq Er EPERM +The current thread does not own the read/write lock. +.El +.Sh SEE ALSO +.Xr pthread_rwlock_rdlock 3 , +.Xr pthread_rwlock_wrlock 3 +.Sh STANDARDS +The +.Fn pthread_rwlock_unlock +function is expected to conform to +.St -susv2 . +.Sh HISTORY +The +.Fn pthread_rwlock_unlock +function first appeared in +.Fx 3.0 . diff --git a/static/freebsd/man3/pthread_rwlock_wrlock.3 b/static/freebsd/man3/pthread_rwlock_wrlock.3 new file mode 100644 index 00000000..58416b27 --- /dev/null +++ b/static/freebsd/man3/pthread_rwlock_wrlock.3 @@ -0,0 +1,104 @@ +.\" Copyright (c) 1998 Alex Nash +.\" 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 August 4, 1998 +.Dt PTHREAD_RWLOCK_WRLOCK 3 +.Os +.Sh NAME +.Nm pthread_rwlock_wrlock , +.Nm pthread_rwlock_trywrlock +.Nd acquire a read/write lock for writing +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_rwlock_wrlock "pthread_rwlock_t *lock" +.Ft int +.Fn pthread_rwlock_trywrlock "pthread_rwlock_t *lock" +.Sh DESCRIPTION +The +.Fn pthread_rwlock_wrlock +function blocks until a write lock can be acquired against +.Fa lock . +The +.Fn pthread_rwlock_trywrlock +function performs the same action, but does not block if the lock +cannot be immediately obtained. +.Pp +The results are undefined if the calling thread already holds the +lock at the time the call is made. +.Sh IMPLEMENTATION NOTES +To prevent writer starvation, writers are favored over readers. +.Sh RETURN VALUES +If successful, the +.Fn pthread_rwlock_wrlock +and +.Fn pthread_rwlock_trywrlock +functions will return zero. +Otherwise an error number will be returned +to indicate the error. +.Sh ERRORS +The +.Fn pthread_rwlock_trywrlock +function will fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +The calling thread is not able to acquire the lock without blocking. +.El +.Pp +The +.Fn pthread_rwlock_wrlock +and +.Fn pthread_rwlock_trywrlock +functions may fail if: +.Bl -tag -width Er +.It Bq Er EDEADLK +The calling thread already owns the read/write lock (for reading +or writing). +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.It Bq Er ENOMEM +Insufficient memory exists to initialize the lock (applies to +statically initialized locks only). +.El +.Sh SEE ALSO +.Xr pthread_rwlock_init 3 , +.Xr pthread_rwlock_rdlock 3 , +.Xr pthread_rwlock_tryrdlock 3 , +.Xr pthread_rwlock_unlock 3 +.Sh STANDARDS +The +.Fn pthread_rwlock_wrlock +and +.Fn pthread_rwlock_trywrlock +functions are expected to conform to +.St -susv2 . +.Sh HISTORY +The +.Fn pthread_rwlock_wrlock +function first appeared in +.Fx 3.0 . diff --git a/static/freebsd/man3/pthread_rwlockattr_destroy.3 b/static/freebsd/man3/pthread_rwlockattr_destroy.3 new file mode 100644 index 00000000..eabfbad7 --- /dev/null +++ b/static/freebsd/man3/pthread_rwlockattr_destroy.3 @@ -0,0 +1,70 @@ +.\" Copyright (c) 1998 Alex Nash +.\" 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 August 4, 1998 +.Dt PTHREAD_RWLOCKATTR_DESTROY 3 +.Os +.Sh NAME +.Nm pthread_rwlockattr_destroy +.Nd destroy a read/write lock attributes object +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_rwlockattr_destroy "pthread_rwlockattr_t *attr" +.Sh DESCRIPTION +The +.Fn pthread_rwlockattr_destroy +function is used to destroy a read/write lock attributes object +previously created with +.Fn pthread_rwlockattr_init . +.Sh RETURN VALUES +If successful, the +.Fn pthread_rwlockattr_destroy +function will return zero. +Otherwise an error number will be returned +to indicate the error. +.Sh ERRORS +The +.Fn pthread_rwlockattr_destroy +function may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.El +.Sh SEE ALSO +.Xr pthread_rwlockattr_init 3 +.Sh STANDARDS +The +.Fn pthread_rwlockattr_destroy +function is expected to conform to +.St -susv2 . +.Sh HISTORY +The +.Fn pthread_rwlockattr_destroy +function first appeared in +.Fx 3.0 . diff --git a/static/freebsd/man3/pthread_rwlockattr_getpshared.3 b/static/freebsd/man3/pthread_rwlockattr_getpshared.3 new file mode 100644 index 00000000..33d7cd32 --- /dev/null +++ b/static/freebsd/man3/pthread_rwlockattr_getpshared.3 @@ -0,0 +1,86 @@ +.\" Copyright (c) 1998 Alex Nash +.\" 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 August 17, 2018 +.Dt PTHREAD_RWLOCKATTR_GETPSHARED 3 +.Os +.Sh NAME +.Nm pthread_rwlockattr_getpshared +.Nd get the process shared attribute +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fo pthread_rwlockattr_getpshared +.Fa "const pthread_rwlockattr_t *restrict attr" "int *restrict pshared" +.Fc +.Sh DESCRIPTION +The +.Fn pthread_rwlockattr_getpshared +function is used to get the process shared setting of a read/write +lock attribute object. +The setting is returned via +.Fa pshared , +and may be one of two values: +.Bl -tag -width PTHREAD_PROCESS_PRIVATE +.It Dv PTHREAD_PROCESS_SHARED +Any thread of any process that has access to the memory where the +read/write lock resides can manipulate the lock. +.It Dv PTHREAD_PROCESS_PRIVATE +Only threads created within the same process as the thread that +initialized the read/write lock can manipulate the lock. +This is +the default value. +.El +.Sh RETURN VALUES +If successful, the +.Fn pthread_rwlockattr_getpshared +function will return zero. +Otherwise an error number will be returned +to indicate the error. +.Sh ERRORS +The +.Fn pthread_rwlockattr_getpshared +function may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.El +.Sh SEE ALSO +.Xr pthread_rwlock_init 3 , +.Xr pthread_rwlockattr_init 3 , +.Xr pthread_rwlockattr_setpshared 3 +.Sh STANDARDS +The +.Fn pthread_rwlockattr_getpshared +function is expected to conform to +.St -susv2 . +.Sh HISTORY +The +.Fn pthread_rwlockattr_getpshared +function first appeared in +.Fx 3.0 . diff --git a/static/freebsd/man3/pthread_rwlockattr_init.3 b/static/freebsd/man3/pthread_rwlockattr_init.3 new file mode 100644 index 00000000..031d010a --- /dev/null +++ b/static/freebsd/man3/pthread_rwlockattr_init.3 @@ -0,0 +1,69 @@ +.\" Copyright (c) 1998 Alex Nash +.\" 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 August 4, 1998 +.Dt PTHREAD_RWLOCKATTR_INIT 3 +.Os +.Sh NAME +.Nm pthread_rwlockattr_init +.Nd initialize a read/write lock attributes object +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_rwlockattr_init "pthread_rwlockattr_t *attr" +.Sh DESCRIPTION +The +.Fn pthread_rwlockattr_init +function is used to initialize a read/write lock attributes object. +.Sh RETURN VALUES +If successful, the +.Fn pthread_rwlockattr_init +function will return zero. +Otherwise an error number will be returned +to indicate the error. +.Sh ERRORS +The +.Fn pthread_rwlockattr_init +function will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Insufficient memory exists to initialize the attributes object. +.El +.Sh SEE ALSO +.Xr pthread_rwlock_init 3 , +.Xr pthread_rwlockattr_destroy 3 , +.Xr pthread_rwlockattr_getpshared 3 , +.Xr pthread_rwlockattr_setpshared 3 +.Sh STANDARDS +The +.Fn pthread_rwlockattr_init +function is expected to conform to +.St -susv2 . +.Sh HISTORY +The +.Fn pthread_rwlockattr_init +function first appeared in +.Fx 3.0 . diff --git a/static/freebsd/man3/pthread_rwlockattr_setpshared.3 b/static/freebsd/man3/pthread_rwlockattr_setpshared.3 new file mode 100644 index 00000000..3ed86f41 --- /dev/null +++ b/static/freebsd/man3/pthread_rwlockattr_setpshared.3 @@ -0,0 +1,90 @@ +.\" Copyright (c) 1998 Alex Nash +.\" 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 May 31, 2016 +.Dt PTHREAD_RWLOCKATTR_SETPSHARED 3 +.Os +.Sh NAME +.Nm pthread_rwlockattr_setpshared +.Nd set the process shared attribute +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_rwlockattr_setpshared "pthread_rwlockattr_t *attr" "int pshared" +.Sh DESCRIPTION +The +.Fn pthread_rwlockattr_setpshared +function sets the process shared attribute of +.Fa attr +to the value referenced by +.Fa pshared . +The +.Fa pshared +argument may be one of two values: +.Bl -tag -width PTHREAD_PROCESS_PRIVATE +.It Dv PTHREAD_PROCESS_SHARED +Any thread of any process that has access to the memory where the +read/write lock resides can manipulate the lock. +.It Dv PTHREAD_PROCESS_PRIVATE +Only threads created within the same process as the thread that +initialized the read/write lock can manipulate the lock. +This is +the default value. +.El +.Sh RETURN VALUES +If successful, the +.Fn pthread_rwlockattr_setpshared +function will return zero. +Otherwise an error number will be returned +to indicate the error. +.Sh ERRORS +The +.Fn pthread_rwlockattr_setpshared +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +or +.Fa pshared +is invalid. +.El +.Sh SEE ALSO +.Xr pthread_rwlock_init 3 , +.Xr pthread_rwlockattr_getpshared 3 , +.Xr pthread_rwlockattr_init 3 +.Sh STANDARDS +The +.Fn pthread_rwlockattr_setpshared +function is expected to conform to +.St -susv2 . +.Sh HISTORY +The +.Fn pthread_rwlockattr_setpshared +function first appeared in +.Fx 3.0 . +Support for process-shared read/write locks appeared in +.Fx 11.0 . diff --git a/static/freebsd/man3/pthread_schedparam.3 b/static/freebsd/man3/pthread_schedparam.3 new file mode 100644 index 00000000..3ba17578 --- /dev/null +++ b/static/freebsd/man3/pthread_schedparam.3 @@ -0,0 +1,100 @@ +.\" Copyright (C) 2000 Jason Evans . +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 October 17, 2022 +.Dt PTHREAD_SCHEDPARAM 3 +.Os +.Sh NAME +.Nm pthread_setschedparam , +.Nm pthread_getschedparam +.Nd thread scheduling parameter manipulation +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_setschedparam "pthread_t thread" "int policy" "const struct sched_param *param" +.Ft int +.Fn pthread_getschedparam "pthread_t thread" "int *restrict policy" "struct sched_param *restrict param" +.Sh DESCRIPTION +The +.Fn pthread_setschedparam +and +.Fn pthread_getschedparam +functions set and get the scheduling parameters of individual threads. +The scheduling policy for a thread can either be +.Dv SCHED_FIFO +(first in, first out), +.Dv SCHED_RR +(round-robin), or +.Dv SCHED_OTHER +(timesharing). +Valid thread priorities (accessed via +.Va param->sched_priority ) +must be within the range returned by the +.Xr sched_get_priority_min 2 +and +.Xr sched_get_priority_max 2 +system calls. +.Sh RETURN VALUES +If successful, these functions return 0. +Otherwise, an error number is returned to indicate the error. +.Sh ERRORS +The +.Fn pthread_setschedparam +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa policy . +.It Bq Er ENOTSUP +Invalid value for scheduling parameters. +.It Bq Er EPERM +The calling thread does not have sufficient privilege to perform the operation. +.It Bq Er ESRCH +Non-existent thread +.Fa thread . +.El +.Pp +The +.Fn pthread_getschedparam +function will fail if: +.Bl -tag -width Er +.It Bq Er ESRCH +Non-existent thread +.Fa thread . +.El +.Sh SEE ALSO +.Xr sched_get_priority_max 2 , +.Xr sched_get_priority_min 2 +.Sh STANDARDS +The +.Fn pthread_setschedparam +and +.Fn pthread_getschedparam +functions conform to +.St -susv2 . diff --git a/static/freebsd/man3/pthread_self.3 b/static/freebsd/man3/pthread_self.3 new file mode 100644 index 00000000..1c485300 --- /dev/null +++ b/static/freebsd/man3/pthread_self.3 @@ -0,0 +1,61 @@ +.\" Copyright (c) 1996 John Birrell . +.\" 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 John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 4, 1996 +.Dt PTHREAD_SELF 3 +.Os +.Sh NAME +.Nm pthread_self +.Nd get the calling thread's ID +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft pthread_t +.Fn pthread_self "void" +.Sh DESCRIPTION +The +.Fn pthread_self +function returns the thread ID of the calling thread. +.Sh RETURN VALUES +The +.Fn pthread_self +function returns the thread ID of the calling thread. +.Sh ERRORS +None. +.Sh SEE ALSO +.Xr pthread_create 3 , +.Xr pthread_equal 3 , +.Xr pthread_getthreadid_np 3 +.Sh STANDARDS +The +.Fn pthread_self +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_set_name_np.3 b/static/freebsd/man3/pthread_set_name_np.3 new file mode 100644 index 00000000..69adcad2 --- /dev/null +++ b/static/freebsd/man3/pthread_set_name_np.3 @@ -0,0 +1,107 @@ +.\" Copyright (c) 2003 Alexey Zelkin +.\" 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 October 12, 2021 +.Dt PTHREAD_SET_NAME_NP 3 +.Os +.Sh NAME +.Nm pthread_get_name_np , +.Nm pthread_getname_np , +.Nm pthread_set_name_np , +.Nm pthread_setname_np +.Nd set and retrieve the thread name +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Ft void +.Fn pthread_get_name_np "pthread_t thread" "char *name" "size_t len" +.Ft int +.Fn pthread_getname_np "pthread_t thread" "char *name" "size_t len" +.Ft void +.Fn pthread_set_name_np "pthread_t thread" "const char *name" +.Ft int +.Fn pthread_setname_np "pthread_t thread" "const char *name" +.Sh DESCRIPTION +The +.Fn pthread_set_name_np +and +.Fn pthread_setname_np +functions apply a copy of the given +.Fa name +to the given +.Fa thread . +.Pp +The +.Fn pthread_get_name_np +and +.Fn pthread_getname_np +functions retrieve the +.Fa name +associated with +.Fa thread . +If +.Fn pthread_set_name_np +was not previously called for +.Fa thread , +the buffer pointed to by +.Fa name +will be empty. +.Sh ERRORS +The +.Nm pthread_getname_np +and +.Nm pthread_setname_np +will fail if +.Bl -tag -width Er +.It Bq Er ESRCH +No thread could be found in the current process corresponding to that +specified by the given thread ID +.Fa thread . +.El +.Pp +Because of the debugging nature of +.Nm pthread_get_name_np +and +.Nm pthread_set_name_np +functions, all errors that may +appear inside are silently ignored. +.Sh SEE ALSO +.Xr thr_set_name 2 , +.Xr pthread_np 3 +.Sh STANDARDS +.Fn pthread_set_name_np +and +.Fn pthread_get_name_np +are non-standard extensions. +.Fn pthread_setname_np +and +.Fn pthread_getname_np +are also non-standard, but are implemented by larger number of operating +systems so they are in fact more portable. +.Sh AUTHORS +This manual page was written by +.An Alexey Zelkin Aq Mt phantom@FreeBSD.org +and +.An Yuri Pankov Aq Mt yuripv@yuripv.net . diff --git a/static/freebsd/man3/pthread_setspecific.3 b/static/freebsd/man3/pthread_setspecific.3 new file mode 100644 index 00000000..59079e35 --- /dev/null +++ b/static/freebsd/man3/pthread_setspecific.3 @@ -0,0 +1,99 @@ +.\" Copyright (c) 1996 John Birrell . +.\" 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 John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 4, 1996 +.Dt PTHREAD_SETSPECIFIC 3 +.Os +.Sh NAME +.Nm pthread_setspecific +.Nd set a thread-specific data value +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_setspecific "pthread_key_t key" "const void *value" +.Sh DESCRIPTION +The +.Fn pthread_setspecific +function associates a thread-specific value with a +.Fa key +obtained via a previous call to +.Fn pthread_key_create . +Different threads can bind different values to the same key. +These values are +typically pointers to blocks of dynamically allocated memory that have been +reserved for use by the calling thread. +.Pp +The effect of calling +.Fn pthread_setspecific +with a key value not obtained from +.Fn pthread_key_create +or after +.Fa key +has been deleted with +.Fn pthread_key_delete +is undefined. +.Pp +The +.Fn pthread_setspecific +function may be called from a thread-specific data destructor function, +however this may result in lost storage or infinite loops if doing so +causes non-NULL key values to remain after +.Bq PTHREAD_DESTRUCTOR_ITERATIONS +iterations of destructor calls have been made. +.Sh RETURN VALUES +If successful, the +.Fn pthread_setspecific +function will return zero. +Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +The +.Fn pthread_setspecific +function will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Insufficient memory exists to associate the value with the +.Fa key . +.It Bq Er EINVAL +The +.Fa key +value is invalid. +.El +.Sh SEE ALSO +.Xr pthread_getspecific 3 , +.Xr pthread_key_create 3 , +.Xr pthread_key_delete 3 +.Sh STANDARDS +The +.Fn pthread_setspecific +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_sigmask.3 b/static/freebsd/man3/pthread_sigmask.3 new file mode 100644 index 00000000..8d2a5d65 --- /dev/null +++ b/static/freebsd/man3/pthread_sigmask.3 @@ -0,0 +1,97 @@ +.\" Copyright (C) 2000 Jason Evans . +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 February 19, 2011 +.Dt PTHREAD_SIGMASK 3 +.Os +.Sh NAME +.Nm pthread_sigmask +.Nd examine and/or change a thread's signal mask +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.In signal.h +.Ft int +.Fn pthread_sigmask "int how" "const sigset_t * restrict set" \ + "sigset_t * restrict oset" +.Sh DESCRIPTION +The +.Fn pthread_sigmask +function examines and/or changes the calling thread's signal mask. +.Pp +If +.Fa set +is not +.Dv NULL , +it specifies a set of signals to be modified, and +.Fa how +specifies what to set the signal mask to: +.Bl -tag -width SIG_UNBLOCK +.It Dv SIG_BLOCK +Union of the current mask and +.Fa set . +.It Dv SIG_UNBLOCK +Intersection of the current mask and the complement of +.Fa set . +.It Dv SIG_SETMASK +.Fa set . +.El +.Pp +If +.Fa oset +is not NULL, the previous signal mask is stored in the location pointed to by +.Fa oset . +.Pp +.Dv SIGKILL +and +.Dv SIGSTOP +cannot be blocked, and will be silently ignored if included in the signal mask. +.Sh RETURN VALUES +If successful, +.Fn pthread_sigmask +returns 0. +Otherwise, an error is returned. +.Sh ERRORS +The +.Fn pthread_sigmask +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa how +is not one of the defined values. +.El +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr sigpending 2 , +.Xr sigprocmask 2 , +.Xr sigsuspend 2 , +.Xr sigsetops 3 +.Sh STANDARDS +The +.Fn pthread_sigmask +function conforms to +.St -p1003.1-96 diff --git a/static/freebsd/man3/pthread_signals_block_np.3 b/static/freebsd/man3/pthread_signals_block_np.3 new file mode 100644 index 00000000..de33f4e6 --- /dev/null +++ b/static/freebsd/man3/pthread_signals_block_np.3 @@ -0,0 +1,81 @@ +.\" Copyright (c) 2025 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" This documentation was written by +.\" Konstantin Belousov under sponsorship +.\" from the FreeBSD Foundation. +.\" +.Dd May 16, 2025 +.Dt PTHREAD_SIGNALS_BLOCK_NP 3 +.Os +.Sh NAME +.Nm pthread_signals_block_np , +.Nm pthread_signals_unblock_np +.Nd fast asynchronous signals blocking and unblocking +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Ft void +.Fn pthread_signals_block_np "void" +.Ft void +.Fn pthread_signals_unblock_np "void" +.Sh DESCRIPTION +The +.Fn pthread_signals_block_np +and +.Fn pthread_signals_unblock_np +functions provide user programs an interface to the fast asynchronous +signals blocking facility +.Xr sigfastblock 2 . +.Pp +Blocking signals with +.Fn pthread_signals_block_np +disables delivery of any asynchronous signal, until unblocked. +Signal blocking establishes a critical section where the execution +flow of the thread cannot be diverted into a signal handler. +Blocking signals is fast, it is performed by a single memory write into +a location established with the kernel. +.Pp +Synchronous signal delivery cannot be blocked in general, including with +these functions. +.Pp +The blocked state established by the +.Fn pthread_signals_block_np +is not completely POSIX-compliant. +Specifically, system calls executed while in a blocked section, +might abort sleep and return +.Er EINTR +upon queuing of an asynchronous signal to the thread, +but the signal handler is not called until the last unblock is done. +.Pp +Calls to +.Nm pthread_signals_block_np +can be nested, and must be complemented by an equal count of +calls to +.Nm pthread_signals_unblock_np +to return the calling thread to the standard mode of signal receiving. +.Pp +An example use of these function might be the construction of the CPU +state that cannot be done atomically, and which includes stages where +the state of the thread is not ABI compliant. +If a signal is delivered while such state is not yet finished, signal +handlers would misbehave. +Using standard functions +.Pq Fn sigprocmask +to establish critical section might be much slower, because +.Fn sigprocmask +is system call, while +.Fn pthread_signals_block_np +consists of a single atomic memory write. +.Sh RETURN VALUES +The functions do not return a value. +.Sh ERRORS +There are no errors reported by the functions. +.Sh SEE ALSO +.Xr sigfastblock 2 , +.Xr sigprocmask 2 , +.Xr pthread_sigmask 3 , +.Xr pthread_np 3 diff --git a/static/freebsd/man3/pthread_sigqueue.3 b/static/freebsd/man3/pthread_sigqueue.3 new file mode 100644 index 00000000..852f6314 --- /dev/null +++ b/static/freebsd/man3/pthread_sigqueue.3 @@ -0,0 +1,102 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright 2024 The FreeBSD Foundation +.\" +.\" This documentation was written by +.\" Konstantin Belousov under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 21, 2024 +.Dt PTHREAD_SIGQUEUE 3 +.Os +.Sh NAME +.Nm pthread_sigqueue +.Nd queue a signal to a specified thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.In signal.h +.Ft int +.Fn pthread_sigqueue "pthread_t thread" "int sig" "const union sigval value" +.Sh DESCRIPTION +The +.Fn pthread_queue +function queues a signal, specified by +.Fa sig , +to a thread, specified by +.Fa thread . +If +.Fa sig +is 0, error checking is performed, but no signal is actually sent. +The +.Fa value +is queued together with the signal, and becomes available in +.Vt siginfo_t +data passed to the signal handler. +.Pp +The +.Nm +function is similar to +.Xr sigqueue 2 , +but targets a thread in the current process instead of a process. +See +.Xr sigqueue 2 +for details about signal queueing and delivery selection. +.Sh RETURN VALUES +If successful, +.Fn pthread_sigqueue +returns 0. +Otherwise, an error number is returned. +.Sh ERRORS +The +.Fn pthread_sigqueue +function will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +No resources are available to queue the signal. +The current process has already queued +.Brq Dv SIGQUEUE_MAX +signals that are still pending, +or a system-wide resource limit has been exceeded. +.It Bq Er ESRCH +.Fa thread +is an invalid thread ID. +.It Bq Er EINVAL +.Fa sig +is an invalid or unsupported signal number. +.El +.Sh SEE ALSO +.Xr sigqueue 2 +.Sh STANDARDS +The +.Fn pthread_sigqueue +function is a +.Fx +extension. +An identical function with the same semantic is available in other +operating systems. diff --git a/static/freebsd/man3/pthread_spin_init.3 b/static/freebsd/man3/pthread_spin_init.3 new file mode 100644 index 00000000..4820ddcf --- /dev/null +++ b/static/freebsd/man3/pthread_spin_init.3 @@ -0,0 +1,123 @@ +.\" Copyright (c) 2004 Michael Telahun Makonnen +.\" 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 May 31, 2016 +.Dt PTHREAD_SPIN_INIT 3 +.Os +.Sh NAME +.Nm pthread_spin_init , pthread_spin_destroy +.Nd "initialize or destroy a spin lock" +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_spin_init "pthread_spinlock_t *lock" "int pshared" +.Ft int +.Fn pthread_spin_destroy "pthread_spinlock_t *lock" +.Sh DESCRIPTION +The +.Fn pthread_spin_init +function will initialize +.Fa lock +to an unlocked state and +allocate any resources necessary to begin using it. +If +.Fa pshared +is set to +.Dv PTHREAD_PROCESS_SHARED , +any thread, +whether belonging to the process in which the spinlock was created or not, +that has access to the memory area where +.Fa lock +resides, can use +.Fa lock . +If it is set to +.Dv PTHREAD_PROCESS_PRIVATE , +it can only be used by threads within the same process. +.Pp +The +.Fn pthread_spin_destroy +function will destroy +.Fa lock +and release any resources that may have been allocated on its behalf. +.Sh RETURN VALUES +If successful, +both +.Fn pthread_spin_init +and +.Fn pthread_spin_destroy +will return zero. +Otherwise, an error number will be returned to indicate the error. +.Pp +Neither of these functions will return +.Er EINTR . +.Sh ERRORS +The +.Fn pthread_spin_init +and +.Fn pthread_spin_destroy +functions will fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +An attempt to initialize or destroy +.Fa lock +while it is in use. +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.El +.Pp +The +.Fn pthread_spin_init +function will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +Insufficient resources, +other than memory, +to initialize +.Fa lock . +.It Bq Er ENOMEM +Insufficient memory to initialize +.Fa lock . +.El +.Sh SEE ALSO +.Xr pthread_spin_lock 3 , +.Xr pthread_spin_unlock 3 +.Sh HISTORY +The +.Fn pthread_spin_init +and +.Fn pthread_spin_destroy +functions first appeared in +.Lb libkse +in +.Fx 5.2 , +and in +.Lb libthr +in +.Fx 5.3 . +Support for process-shared spinlocks appeared in +.Fx 11.0 . diff --git a/static/freebsd/man3/pthread_spin_lock.3 b/static/freebsd/man3/pthread_spin_lock.3 new file mode 100644 index 00000000..4308271a --- /dev/null +++ b/static/freebsd/man3/pthread_spin_lock.3 @@ -0,0 +1,136 @@ +.\" Copyright (c) 2004 Michael Telahun Makonnen +.\" 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 January 22, 2004 +.Dt PTHREAD_SPIN_LOCK 3 +.Os +.Sh NAME +.Nm pthread_spin_lock , pthread_spin_trylock , pthread_spin_unlock +.Nd "lock or unlock a spin lock" +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_spin_lock "pthread_spinlock_t *lock" +.Ft int +.Fn pthread_spin_trylock "pthread_spinlock_t *lock" +.Ft int +.Fn pthread_spin_unlock "pthread_spinlock_t *lock" +.Sh DESCRIPTION +The +.Fn pthread_spin_lock +function will acquire +.Fa lock +if it is not currently owned by another thread. +If the lock cannot be acquired immediately, it will +spin attempting to acquire the lock (it will not sleep) until +it becomes available. +.Pp +The +.Fn pthread_spin_trylock +function is the same as +.Fn pthread_spin_lock +except that if it cannot acquire +.Fa lock +immediately it will return with an error. +.Pp +The +.Fn pthread_spin_unlock +function will release +.Fa lock , +which must have been previously locked by a call to +.Fn pthread_spin_lock +or +.Fn pthread_spin_trylock . +.Sh RETURN VALUES +If successful, all these functions will return zero. +Otherwise, an error number will be returned to indicate the error. +.Pp +None of these functions will return +.Er EINTR . +.Sh ERRORS +The +.Fn pthread_spin_lock , +.Fn pthread_spin_trylock +and +.Fn pthread_spin_unlock +functions will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid or is not initialized. +.El +.Pp +The +.Fn pthread_spin_lock +function may fail if: +.Bl -tag -width Er +.It Bq Er EDEADLK +The calling thread already owns the lock. +.El +.Pp +The +.Fn pthread_spin_trylock +function will fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +Another thread currently holds +.Fa lock . +.El +.Pp +The +.Fn pthread_spin_unlock +function may fail if: +.Bl -tag -width Er +.It Bq Er EPERM +The calling thread does not own +.Fa lock . +.El +.Sh SEE ALSO +.Xr pthread_spin_destroy 3 , +.Xr pthread_spin_init 3 +.Sh HISTORY +The +.Fn pthread_spin_lock , +.Fn pthread_spin_trylock +and +.Fn pthread_spin_unlock +functions first appeared in +.Lb libkse +in +.Fx 5.2 , +and in +.Lb libthr +in +.Fx 5.3 . +.Sh BUGS +The implementation of +.Fn pthread_spin_lock , +.Fn pthread_spin_trylock +and +.Fn pthread_spin_unlock +is expected to conform to +.St -p1003.2 . diff --git a/static/freebsd/man3/pthread_suspend_all_np.3 b/static/freebsd/man3/pthread_suspend_all_np.3 new file mode 100644 index 00000000..c99a08a0 --- /dev/null +++ b/static/freebsd/man3/pthread_suspend_all_np.3 @@ -0,0 +1,59 @@ +.\" Copyright (c) 2003 Alexey Zelkin +.\" 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 October 12, 2021 +.Dt PTHREAD_SUSPEND_ALL_NP 3 +.Os +.Sh NAME +.Nm pthread_suspend_all_np +.Nd suspend all active threads +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Ft void +.Fn pthread_suspend_all_np void +.Sh DESCRIPTION +The +.Fn pthread_suspend_all_np +function causes all active threads to be suspended. +The only exception is the current thread, +the thread that called the +.Fn pthread_suspend_all_np +function. +.Pp +It is not safe for the caller of the +.Fn pthread_suspend_all_np +function to use any non-async signal safe functions, besides +.Xr pthread_resume_all_np 3 , +until threads are resumed, unless measures are taken to ensure +that all threads are suspended at safe points. +.Sh SEE ALSO +.Xr pthread_np 3 , +.Xr pthread_resume_all_np 3 , +.Xr pthread_resume_np 3 , +.Xr pthread_suspend_np 3 +.Sh AUTHORS +This manual page was written by +.An Alexey Zelkin Aq Mt phantom@FreeBSD.org . diff --git a/static/freebsd/man3/pthread_suspend_np.3 b/static/freebsd/man3/pthread_suspend_np.3 new file mode 100644 index 00000000..8e05bac0 --- /dev/null +++ b/static/freebsd/man3/pthread_suspend_np.3 @@ -0,0 +1,76 @@ +.\" Copyright (c) 2003 Alexey Zelkin +.\" 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 October 12, 2021 +.Dt PTHREAD_SUSPEND_NP 3 +.Os +.Sh NAME +.Nm pthread_suspend_np +.Nd suspend a thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Ft int +.Fn pthread_suspend_np "pthread_t tid" +.Sh DESCRIPTION +The +.Fn pthread_suspend_np +function, called on an active thread, causes it to suspend. +.Pp +It is not safe for the caller of the +.Fn pthread_suspend_np +function to use any non-async signal safe functions, except +.Xr pthread_resume_np 3 , +until suspended thread is resumed, unless measures are taken to ensure +that the thread is suspended at a safe point. +.Sh RETURN VALUES +If successful, +.Fn pthread_suspend_np +function returns 0. +Otherwise, an error number is returned to indicate the error. +.Sh ERRORS +The +.Fn pthread_suspend_np +function will fail if: +.Bl -tag -width Er +.It Bq Er EDEADLK +An attempt was made to suspend the current thread. +.It Bq Er EINVAL +The value specified by the +.Fa tid +argument is invalid. +.It Bq Er ESRCH +No thread could be found corresponding to the thread ID specified by the +.Fa tid +argument. +.El +.Sh SEE ALSO +.Xr pthread_np 3 , +.Xr pthread_resume_all_np 3 , +.Xr pthread_resume_np 3 , +.Xr pthread_suspend_all_np 3 +.Sh AUTHORS +This manual page was written by +.An Alexey Zelkin Aq Mt phantom@FreeBSD.org . diff --git a/static/freebsd/man3/pthread_testcancel.3 b/static/freebsd/man3/pthread_testcancel.3 new file mode 100644 index 00000000..c74cdcfe --- /dev/null +++ b/static/freebsd/man3/pthread_testcancel.3 @@ -0,0 +1,263 @@ +.Dd March 18, 2017 +.Dt PTHREAD_TESTCANCEL 3 +.Os +.Sh NAME +.Nm pthread_setcancelstate , +.Nm pthread_setcanceltype , +.Nm pthread_testcancel +.Nd set cancelability state +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_setcancelstate "int state" "int *oldstate" +.Ft int +.Fn pthread_setcanceltype "int type" "int *oldtype" +.Ft void +.Fn pthread_testcancel "void" +.Sh DESCRIPTION +The +.Fn pthread_setcancelstate +function atomically both sets the calling thread's cancelability state +to the indicated +.Fa state +and, if +.Fa oldstate +is not +.Dv NULL , +returns the previous cancelability state at the location referenced by +.Fa oldstate . +Legal values for +.Fa state +are +.Dv PTHREAD_CANCEL_ENABLE +and +.Dv PTHREAD_CANCEL_DISABLE . +The function is async-signal-safe. +.Pp +The +.Fn pthread_setcanceltype +function atomically both sets the calling thread's cancelability type +to the indicated +.Fa type +and, if +.Fa oldtype +is not +.Dv NULL , +returns the previous cancelability type at the location referenced by +.Fa oldtype . +Legal values for +.Fa type +are +.Dv PTHREAD_CANCEL_DEFERRED +and +.Dv PTHREAD_CANCEL_ASYNCHRONOUS . +.Pp +The cancelability state and type of any newly created threads, including the +thread in which +.Fn main +was first invoked, are +.Dv PTHREAD_CANCEL_ENABLE +and +.Dv PTHREAD_CANCEL_DEFERRED +respectively. +.Pp +The +.Fn pthread_testcancel +function creates a cancellation point in the calling thread. +The +.Fn pthread_testcancel +function has no effect if cancelability is disabled. +.Ss Cancelability States +The cancelability state of a thread determines the action taken upon +receipt of a cancellation request. +The thread may control cancellation in +a number of ways. +.Pp +Each thread maintains its own +.Dq cancelability state +which may be encoded in two bits: +.Bl -hang +.It Em Cancelability Enable +When cancelability is +.Dv PTHREAD_CANCEL_DISABLE , +cancellation requests against the target thread are held pending. +.It Em Cancelability Type +When cancelability is enabled and the cancelability type is +.Dv PTHREAD_CANCEL_ASYNCHRONOUS , +new or pending cancellation requests may be acted upon at any time. +When cancelability is enabled and the cancelability type is +.Dv PTHREAD_CANCEL_DEFERRED , +cancellation requests are held pending until a cancellation point (see +below) is reached. +If cancelability is disabled, the setting of the +cancelability type has no immediate effect as all cancellation requests +are held pending; however, once cancelability is enabled again the new +type will be in effect. +.El +.Ss Cancellation Points +Cancellation points will occur when a thread is executing the following +functions: +.Bl -tag -width "Fn pthread_cond_timedwait" -compact +.It Fn accept +.It Fn accept4 +.It Fn aio_suspend +.It Fn connect +.It Fn clock_nanosleep +.It Fn close +.It Fn creat +.It Fn fcntl +The +.Fn fcntl +function is a cancellation point if +.Fa cmd +is +.Dv F_SETLKW . +.It Fn fdatasync +.It Fn fsync +.It Fn kevent +The +.Fn kevent +function is a cancellation point if it is potentially blocking, +such as when the +.Fa nevents +argument is non-zero. +.It Fn mq_receive +.It Fn mq_send +.It Fn mq_timedreceive +.It Fn mq_timedsend +.It Fn msync +.It Fn nanosleep +.It Fn open +.It Fn openat +.It Fn pause +.It Fn poll +.It Fn ppoll +.It Fn pselect +.It Fn pthread_cond_timedwait +.It Fn pthread_cond_wait +.It Fn pthread_join +.It Fn pthread_testcancel +.It Fn read +.It Fn readv +.It Fn recv +.It Fn recvfrom +.It Fn recvmsg +.It Fn select +.It Fn sem_timedwait +.It Fn sem_clockwait_np +.It Fn sem_wait +.It Fn send +.It Fn sendmsg +.It Fn sendto +.It Fn sigsuspend +.It Fn sigtimedwait +.It Fn sigwaitinfo +.It Fn sigwait +.It Fn sleep +.It Fn system +.It Fn tcdrain +.It Fn usleep +.It Fn wait +.It Fn wait3 +.It Fn wait4 +.It Fn wait6 +.It Fn waitid +.It Fn waitpid +.It Fn write +.It Fn writev +.El +.Sh NOTES +The +.Fn pthread_setcancelstate +and +.Fn pthread_setcanceltype +functions are used to control the points at which a thread may be +asynchronously canceled. +For cancellation control to be usable in modular +fashion, some rules must be followed. +.Pp +For purposes of this discussion, consider an object to be a generalization +of a procedure. +It is a set of procedures and global variables written as +a unit and called by clients not known by the object. +Objects may depend +on other objects. +.Pp +First, cancelability should only be disabled on entry to an object, never +explicitly enabled. +On exit from an object, the cancelability state should +always be restored to its value on entry to the object. +.Pp +This follows from a modularity argument: if the client of an object (or the +client of an object that uses that object) has disabled cancelability, it is +because the client does not want to have to worry about how to clean up if the +thread is canceled while executing some sequence of actions. +If an object +is called in such a state and it enables cancelability and a cancellation +request is pending for that thread, then the thread will be canceled, +contrary to the wish of the client that disabled. +.Pp +Second, the cancelability type may be explicitly set to either +.Em deferred +or +.Em asynchronous +upon entry to an object. +But as with the cancelability state, on exit from +an object that cancelability type should always be restored to its value on +entry to the object. +.Pp +Finally, only functions that are cancel-safe may be called from a thread that +is asynchronously cancelable. +.Sh RETURN VALUES +If successful, the +.Fn pthread_setcancelstate +and +.Fn pthread_setcanceltype +functions will return zero. +Otherwise, an error number shall be returned to +indicate the error. +.Sh ERRORS +The function +.Fn pthread_setcancelstate +may fail with: +.Bl -tag -width Er +.It Bq Er EINVAL +The specified state is not +.Dv PTHREAD_CANCEL_ENABLE +or +.Dv PTHREAD_CANCEL_DISABLE . +.El +.Pp +The function +.Fn pthread_setcanceltype +may fail with: +.Bl -tag -width Er +.It Bq Er EINVAL +The specified state is not +.Dv PTHREAD_CANCEL_DEFERRED +or +.Dv PTHREAD_CANCEL_ASYNCHRONOUS . +.El +.Sh SEE ALSO +.Xr pthread_cancel 3 +.Sh STANDARDS +The +.Fn pthread_testcancel +function conforms to +.St -p1003.1-96 . +The standard allows implementations to make many more functions +cancellation points. +.Pp +The +.Fn pthread_setcancelstate +function is async-signal-safe as required by +.St -p1003.1-2024 . +.Sh AUTHORS +This manual page was written by +.An David Leonard Aq Mt d@openbsd.org +for the +.Ox +implementation of +.Xr pthread_cancel 3 . diff --git a/static/freebsd/man3/pthread_yield.3 b/static/freebsd/man3/pthread_yield.3 new file mode 100644 index 00000000..e9ef6491 --- /dev/null +++ b/static/freebsd/man3/pthread_yield.3 @@ -0,0 +1,28 @@ +.\" $OpenBSD: pthread_yield.3,v 1.3 2004/01/25 14:48:32 jmc Exp $ +.\" +.\" PUBLIC DOMAIN: No Rights Reserved. Marco S Hyman +.\" +.Dd September 18, 2006 +.Dt PTHREAD_YIELD 3 +.Os +.Sh NAME +.Nm pthread_yield +.Nd yield control of the current thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft void +.Fn pthread_yield void +.Sh DESCRIPTION +The +.Fn pthread_yield +forces the running thread to relinquish the processor until it again +becomes the head of its thread list. +.Sh SEE ALSO +.Xr sched_yield 2 +.Sh STANDARDS +The +.Fn pthread_yield +is a non-portable (but quite common) extension to +.St -p1003.1-2001 . diff --git a/static/freebsd/man3/qmath.3 b/static/freebsd/man3/qmath.3 new file mode 100644 index 00000000..5c2332f0 --- /dev/null +++ b/static/freebsd/man3/qmath.3 @@ -0,0 +1,387 @@ +.\" +.\" Copyright (c) 2018 Netflix, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions, and the following disclaimer, +.\" without modification, immediately at the beginning of the file. +.\" 2. 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 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 4, 2019 +.Dt QMATH 3 +.Os +.Sh NAME +.Nm qmath +.Nd fixed-point math library based on the +.Dq Q +number format +.Sh SYNOPSIS +.In sys/qmath.h +.Sh DESCRIPTION +The +.Nm +data types and APIs support fixed-point math based on the +.Dq Q +number format. +The APIs have been built around the following data types: +.Vt s8q_t , +.Vt u8q_t , +.Vt s16q_t , +.Vt u16q_t , +.Vt s32q_t , +.Vt u32q_t , +.Vt s64q_t , +and +.Vt u64q_t , +which are referred to generically in the earlier API definitions as +.Fa QTYPE . +The +.Fa ITYPE +refers to the +.Xr stdint 7 +integer types. +.Fa NTYPE +is used to refer to any numeric type and is therefore a superset of +.Fa QTYPE +and +.Fa ITYPE . +.Pp +This scheme can represent Q numbers with +.Bq 2, 4, 6, 8, 16, 32, 48 +bits of precision after the binary radix point, +depending on the +.Fa rpshft +argument to +.Fn Q_INI . +The number of bits available for the integral component is not explicitly +specified, and implicitly consumes the remaining available bits of the chosen Q +data type. +.Pp +Operations on Q numbers maintain the precision of their arguments. +The fractional component is truncated to fit into the destination, +with no rounding. +None of the operations is affected by the floating-point environment. +.Pp +For more details, see the +.Sx IMPLEMENTATION DETAILS +below. +.Sh LIST OF FUNCTIONS +.de Cl +.Bl -column "isgreaterequal" "bessel function of the second kind of the order 0" +.Em "Name Description" +.. +.Ss Functions which create/initialise a Q number +.Cl +.Xr Q_INI 3 initialise a Q number +.El +.Ss Numeric functions which operate on two Q numbers +.Cl +.Xr Q_QADDQ 3 addition +.Xr Q_QDIVQ 3 division +.Xr Q_QMULQ 3 multiplication +.Xr Q_QSUBQ 3 subtraction +.Xr Q_NORMPREC 3 normalisation +.Xr Q_QMAXQ 3 maximum function +.Xr Q_QMINQ 3 minimum function +.Xr Q_QCLONEQ 3 identical copy +.Xr Q_QCPYVALQ 3 representational copy +.El +.Ss Numeric functions which apply integers to a Q number +.Cl +.Xr Q_QADDI 3 addition +.Xr Q_QDIVI 3 division +.Xr Q_QMULI 3 multiplication +.Xr Q_QSUBI 3 subtraction +.Xr Q_QFRACI 3 fraction +.Xr Q_QCPYVALI 3 overwrite +.El +.Ss Numeric functions which operate on a single Q number +.Cl +.Xr Q_QABS 3 absolute value +.Xr Q_Q2D 3 double representation +.Xr Q_Q2F 3 float representation +.El +.Ss Comparison and logic functions +.Cl +.Xr Q_SIGNED 3 determine sign +.Xr Q_LTZ 3 less than zero +.Xr Q_PRECEQ 3 compare bits +.Xr Q_QLTQ 3 less than +.Xr Q_QLEQ 3 less or equal +.Xr Q_QGTQ 3 greater than +.Xr Q_QGEQ 3 greater or equal +.Xr Q_QEQ 3 equal +.Xr Q_QNEQ 3 not equal +.Xr Q_OFLOW 3 would overflow +.Xr Q_RELPREC 3 relative precision +.El +.Ss Functions which manipulate the control/sign data bits +.Cl +.Xr Q_SIGNSHFT 3 sign bit position +.Xr Q_SSIGN 3 sign bit +.Xr Q_CRAWMASK 3 control bitmask +.Xr Q_SRAWMASK 3 sign bitmask +.Xr Q_GCRAW 3 raw control bits +.Xr Q_GCVAL 3 value of control bits +.Xr Q_SCVAL 3 set control bits +.El +.Ss Functions which manipulate the combined integer/fractional data bits +.Cl +.Xr Q_IFRAWMASK 3 integer/fractional bitmask +.Xr Q_IFVALIMASK 3 value of integer bits +.Xr Q_IFVALFMASK 3 value of fractional bits +.Xr Q_GIFRAW 3 raw integer/fractional bits +.Xr Q_GIFABSVAL 3 absolute value of fractional bits +.Xr Q_GIFVAL 3 real value of fractional bits +.Xr Q_SIFVAL 3 set integer/fractional bits +.Xr Q_SIFVALS 3 set separate integer/fractional values +.El +.Ss Functions which manipulate the integer data bits +.Cl +.Xr Q_IRAWMASK 3 integer bitmask +.Xr Q_GIRAW 3 raw integer bits +.Xr Q_GIABSVAL 3 absolute value of integer bits +.Xr Q_GIVAL 3 real value of integer bits +.Xr Q_SIVAL 3 set integer bits +.El +.Ss Functions which manipulate the fractional data bits +.Cl +.Xr Q_FRAWMASK 3 fractional bitmask +.Xr Q_GFRAW 3 raw fractional bits +.Xr Q_GFABSVAL 3 absolute value of fractional bits +.Xr Q_GFVAL 3 real value of fractional bits +.Xr Q_SFVAL 3 set fractional bits +.El +.Ss Miscellaneous functions/variables +.Cl +.Xr Q_NCBITS 3 number of reserved control bits +.Xr Q_BT 3 C data type +.Xr Q_TC 3 casted data type +.Xr Q_NTBITS 3 number of total bits +.Xr Q_NFCBITS 3 number of control-encoded fractional bits +.Xr Q_MAXNFBITS 3 number of maximum fractional bits +.Xr Q_NFBITS 3 number of effective fractional bits +.Xr Q_NIBITS 3 number of integer bits +.Xr Q_RPSHFT 3 bit position of radix point +.Xr Q_ABS 3 absolute value +.Xr Q_MAXSTRLEN 3 number of characters to render string +.Xr Q_TOSTR 3 render string +.Xr Q_SHL 3 left-shifted value +.Xr Q_SHR 3 right-shifted value +.Xr Q_DEBUG 3 render debugging information +.Xr Q_DFV2BFV 3 convert decimal fractional value +.El +.Sh IMPLEMENTATION DETAILS +The +.Nm +data types and APIs support fixed-point math based on the +.Dq Q +number format. +This implementation uses the Q notation +.Em Qm.n , +where +.Em m +specifies the number of bits for integral data +.Pq excluding the sign bit for signed types , +and +.Em n +specifies the number of bits for fractional data. +.Pp +The APIs have been built around the following q_t derived data types: +.Bd -literal -offset indent +typedef int8_t s8q_t; +typedef uint8_t u8q_t; +typedef int16_t s16q_t; +typedef uint16_t u16q_t; +typedef int32_t s32q_t; +typedef uint32_t u32q_t; +typedef int64_t s64q_t; +typedef uint64_t u64q_t; +.Ed +.Pp +These types are referred to generically in the earlier API definitions as +.Fa QTYPE , +while +.Fa ITYPE +refers to the +.Xr stdint 7 +integer types the Q data types are derived from. +.Fa NTYPE +is used to refer to any numeric type and is therefore a superset of +.Fa QTYPE +and +.Fa ITYPE . +.Pp +The 3 least significant bits +.Pq LSBs +of all q_t data types are reserved for embedded control data: +.Bl -dash +.It +bits 1-2 specify the binary radix point shift index operand, with 00,01,10,11 == +1,2,3,4. +.It +bit 3 specifies the radix point shift index operand multiplier as 2 +.Pq 0 +or 16 +.Pq 1 . +.El +.Pp +This scheme can therefore represent Q numbers with +.Bq 2,4,6,8,16,32,48,64 +bits of precision after the binary radix point. +The number of bits available for the integral component is not explicitly +specified, and implicitly consumes the remaining available bits of the chosen Q +data type. +.Pp +Additionally, the most significant bit +.Pq MSB +of signed Q types stores the sign bit, with bit value 0 representing a positive +number and bit value 1 representing a negative number. +Negative numbers are stored as absolute values with the sign bit set, rather +than the more typical two's complement representation. +This avoids having to bit shift negative numbers, which can result in undefined +behaviour from some compilers. +.Pp +This binary representation used for Q numbers therefore comprises a set of +distinct data bit types and associated bit counts. +Data bit types/labels, listed in LSB to MSB order, are: control +.Sq C , +fractional +.Sq F , +integer +.Sq I +and sign +.Sq S . +The following example illustrates the binary representation of a Q20.8 number +represented using a s32q_t variable: +.Bd -literal -offset indent +M L +S S +B B + +3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 +1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 + +S I I I I I I I I I I I I I I I I I I I I F F F F F F F F C C C +.Ed +.Pp +Important bit counts are: total, control, control-encoded fractional, maximum +fractional, effective fractional and integer bits. +.Pp +The count of total bits is derived from the size of the q_t data type. +For example, a s32q_t has 32 total bits. +.Pp +The count of control-encoded fractional bits is derived from calculating the +number of fractional bits per the control bit encoding scheme. +For example, the control bits binary value of 101 encodes a fractional bit +count of 2 x 16 = 32 fractional bits. +.Pp +The count of maximum fractional bits is derived from the difference between the +counts of total bits and control/sign bits. +For example, a s32q_t has a maximum of 32 - 3 - 1 = 28 fractional bits. +.Pp +The count of effective fractional bits is derived from the minimum of the +control-encoded fractional bits and the maximum fractional bits. +For example, a s32q_t with 32 control-encoded fractional bits is effectively +limited to 28 fractional bits. +.Pp +The count of integer bits is derived from the difference between the counts of +total bits and all other non-integer data bits +.Pq the sum of control, fractional and sign bits. +For example, a s32q_t with 8 effective fractional bits has 32 - 3 - 8 - 1 = 20 integer +bits. +The count of integer bits can be zero if all available numeric data bits have +been reserved for fractional data, e.g., when the number of control-encoded +fractional bits is greater than or equal to the underlying Q data type's maximum +fractional bits. +.Sh EXAMPLES +.Ss Calculating area of a circle with r=4.2 and rpshft=16 +.Bd -literal -offset indent +u64q_t a, pi, r; +char buf[32] + +Q_INI(&a, 0, 0, 16); +Q_INI(&pi, 3, 14159, 16); +Q_INI(&r, 4, 2, 16); + +Q_QCLONEQ(&a, r); +Q_QMULQ(&a, r); +Q_QMULQ(&a, pi); + +Q_TOSTR(a, -1, 10, buf, sizeof(buf)); +printf("%s\\n", buf); +.Ed +.Ss Debugging +Declare a Q20.8 s32q_t number +.Fa s32 , +initialise it with the fixed-point value for 5/3, and render a debugging +representation of the variable +.Pq including its full precision decimal C-string representation , +to the console: +.Bd -literal -offset indent +s32q_t s32; +Q_INI(&s32, 0, 0, 8); +Q_QFRACI(&s32, 5, 3); +char buf[Q_MAXSTRLEN(s32, 10)]; +Q_TOSTR(s32, -1, 10, buf, sizeof(buf)); +printf(Q_DEBUG(s32, "", "\\n\\ttostr=%s\\n\\n", 0), buf); +.Ed +.Pp +The above code outputs the following to the console: +.Bd -literal -offset indent +"s32"@0x7fffffffe7d4 + type=s32q_t, Qm.n=Q20.8, rpshft=11, imin=0xfff00001, \\ +imax=0xfffff + qraw=0x00000d53 + imask=0x7ffff800, fmask=0x000007f8, cmask=0x00000007, \\ +ifmask=0x7ffffff8 + iraw=0x00000800, iabsval=0x1, ival=0x1 + fraw=0x00000550, fabsval=0xaa, fval=0xaa + tostr=1.664 +.Ed +.Pp +Note: The +.Qq \e +present in the rendered output above indicates a manual line break inserted to +keep the man page within 80 columns and is not part of the actual output. +.Sh SEE ALSO +.Xr errno 2 , +.Xr math 3 , +.Xr Q_FRAWMASK 3 , +.Xr Q_IFRAWMASK 3 , +.Xr Q_INI 3 , +.Xr Q_IRAWMASK 3 , +.Xr Q_QABS 3 , +.Xr Q_QADDI 3 , +.Xr Q_QADDQ 3 , +.Xr Q_SIGNED 3 , +.Xr Q_SIGNSHFT 3 , +.Xr stdint 7 +.Sh HISTORY +The +.Nm +functions first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +functions and this manual page were written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org +and sponsored by Netflix, Inc. diff --git a/static/freebsd/man3/queue.3 b/static/freebsd/man3/queue.3 new file mode 100644 index 00000000..535358ae --- /dev/null +++ b/static/freebsd/man3/queue.3 @@ -0,0 +1,1487 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 28, 2025 +.Dt QUEUE 3 +.Os +.Sh NAME +.Nm SLIST_CLASS_ENTRY , +.Nm SLIST_CLASS_HEAD , +.Nm SLIST_CONCAT , +.Nm SLIST_EMPTY , +.Nm SLIST_EMPTY_ATOMIC , +.Nm SLIST_ENTRY , +.Nm SLIST_FIRST , +.Nm SLIST_FOREACH , +.Nm SLIST_FOREACH_FROM , +.Nm SLIST_FOREACH_FROM_SAFE , +.Nm SLIST_FOREACH_SAFE , +.Nm SLIST_HEAD , +.Nm SLIST_HEAD_INITIALIZER , +.Nm SLIST_INIT , +.Nm SLIST_INSERT_AFTER , +.Nm SLIST_INSERT_HEAD , +.Nm SLIST_NEXT , +.Nm SLIST_REMOVE , +.Nm SLIST_REMOVE_AFTER , +.Nm SLIST_REMOVE_HEAD , +.Nm SLIST_SPLIT_AFTER , +.Nm SLIST_SWAP , +.Nm STAILQ_CLASS_ENTRY , +.Nm STAILQ_CLASS_HEAD , +.Nm STAILQ_CONCAT , +.Nm STAILQ_EMPTY , +.Nm STAILQ_EMPTY_ATOMIC , +.Nm STAILQ_ENTRY , +.Nm STAILQ_FIRST , +.Nm STAILQ_FOREACH , +.Nm STAILQ_FOREACH_FROM , +.Nm STAILQ_FOREACH_FROM_SAFE , +.Nm STAILQ_FOREACH_SAFE , +.Nm STAILQ_HEAD , +.Nm STAILQ_HEAD_INITIALIZER , +.Nm STAILQ_INIT , +.Nm STAILQ_INSERT_AFTER , +.Nm STAILQ_INSERT_HEAD , +.Nm STAILQ_INSERT_TAIL , +.Nm STAILQ_LAST , +.Nm STAILQ_NEXT , +.Nm STAILQ_REMOVE , +.Nm STAILQ_REMOVE_AFTER , +.Nm STAILQ_REMOVE_HEAD , +.Nm STAILQ_REVERSE , +.Nm STAILQ_SPLIT_AFTER , +.Nm STAILQ_SWAP , +.Nm LIST_CLASS_ENTRY , +.Nm LIST_CLASS_HEAD , +.Nm LIST_CONCAT , +.Nm LIST_EMPTY , +.Nm LIST_EMPTY_ATOMIC , +.Nm LIST_ENTRY , +.Nm LIST_FIRST , +.Nm LIST_FOREACH , +.Nm LIST_FOREACH_FROM , +.Nm LIST_FOREACH_FROM_SAFE , +.Nm LIST_FOREACH_SAFE , +.Nm LIST_HEAD , +.Nm LIST_HEAD_INITIALIZER , +.Nm LIST_INIT , +.Nm LIST_INSERT_AFTER , +.Nm LIST_INSERT_BEFORE , +.Nm LIST_INSERT_HEAD , +.Nm LIST_NEXT , +.Nm LIST_PREV , +.Nm LIST_REMOVE , +.Nm LIST_REPLACE , +.Nm LIST_SPLIT_AFTER , +.Nm LIST_SWAP , +.Nm TAILQ_CLASS_ENTRY , +.Nm TAILQ_CLASS_HEAD , +.Nm TAILQ_CONCAT , +.Nm TAILQ_EMPTY , +.Nm TAILQ_EMPTY_ATOMIC , +.Nm TAILQ_ENTRY , +.Nm TAILQ_FIRST , +.Nm TAILQ_FOREACH , +.Nm TAILQ_FOREACH_FROM , +.Nm TAILQ_FOREACH_FROM_SAFE , +.Nm TAILQ_FOREACH_REVERSE , +.Nm TAILQ_FOREACH_REVERSE_FROM , +.Nm TAILQ_FOREACH_REVERSE_FROM_SAFE , +.Nm TAILQ_FOREACH_REVERSE_SAFE , +.Nm TAILQ_FOREACH_SAFE , +.Nm TAILQ_HEAD , +.Nm TAILQ_HEAD_INITIALIZER , +.Nm TAILQ_INIT , +.Nm TAILQ_INSERT_AFTER , +.Nm TAILQ_INSERT_BEFORE , +.Nm TAILQ_INSERT_HEAD , +.Nm TAILQ_INSERT_TAIL , +.Nm TAILQ_LAST , +.Nm TAILQ_NEXT , +.Nm TAILQ_PREV , +.Nm TAILQ_REMOVE , +.Nm TAILQ_REPLACE , +.Nm TAILQ_SPLIT_AFTER , +.Nm TAILQ_SWAP +.Nd implementations of singly-linked lists, singly-linked tail queues, +lists and tail queues +.Sh SYNOPSIS +.In sys/queue.h +.\" +.Fn SLIST_CLASS_ENTRY "CLASSTYPE" +.Fn SLIST_CLASS_HEAD "HEADNAME" "CLASSTYPE" +.Fn SLIST_CONCAT "SLIST_HEAD *head1" "SLIST_HEAD *head2" "TYPE" "SLIST_ENTRY NAME" +.Fn SLIST_EMPTY "SLIST_HEAD *head" +.Fn SLIST_EMPTY_ATOMIC "SLIST_HEAD *head" +.Fn SLIST_ENTRY "TYPE" +.Fn SLIST_FIRST "SLIST_HEAD *head" +.Fn SLIST_FOREACH "TYPE *var" "SLIST_HEAD *head" "SLIST_ENTRY NAME" +.Fn SLIST_FOREACH_FROM "TYPE *var" "SLIST_HEAD *head" "SLIST_ENTRY NAME" +.Fn SLIST_FOREACH_FROM_SAFE "TYPE *var" "SLIST_HEAD *head" "SLIST_ENTRY NAME" "TYPE *temp_var" +.Fn SLIST_FOREACH_SAFE "TYPE *var" "SLIST_HEAD *head" "SLIST_ENTRY NAME" "TYPE *temp_var" +.Fn SLIST_HEAD "HEADNAME" "TYPE" +.Fn SLIST_HEAD_INITIALIZER "SLIST_HEAD head" +.Fn SLIST_INIT "SLIST_HEAD *head" +.Fn SLIST_INSERT_AFTER "TYPE *listelm" "TYPE *elm" "SLIST_ENTRY NAME" +.Fn SLIST_INSERT_HEAD "SLIST_HEAD *head" "TYPE *elm" "SLIST_ENTRY NAME" +.Fn SLIST_NEXT "TYPE *elm" "SLIST_ENTRY NAME" +.Fn SLIST_REMOVE "SLIST_HEAD *head" "TYPE *elm" "TYPE" "SLIST_ENTRY NAME" +.Fn SLIST_REMOVE_AFTER "TYPE *elm" "SLIST_ENTRY NAME" +.Fn SLIST_REMOVE_HEAD "SLIST_HEAD *head" "SLIST_ENTRY NAME" +.Fn SLIST_SPLIT_AFTER "SLIST_HEAD *head" "TYPE *elm" "SLIST_HEAD *rest" "SLIST_ENTRY NAME" +.Fn SLIST_SWAP "SLIST_HEAD *head1" "SLIST_HEAD *head2" "TYPE" +.\" +.Fn STAILQ_CLASS_ENTRY "CLASSTYPE" +.Fn STAILQ_CLASS_HEAD "HEADNAME" "CLASSTYPE" +.Fn STAILQ_CONCAT "STAILQ_HEAD *head1" "STAILQ_HEAD *head2" +.Fn STAILQ_EMPTY "STAILQ_HEAD *head" +.Fn STAILQ_EMPTY_ATOMIC "STAILQ_HEAD *head" +.Fn STAILQ_ENTRY "TYPE" +.Fn STAILQ_FIRST "STAILQ_HEAD *head" +.Fn STAILQ_FOREACH "TYPE *var" "STAILQ_HEAD *head" "STAILQ_ENTRY NAME" +.Fn STAILQ_FOREACH_FROM "TYPE *var" "STAILQ_HEAD *head" "STAILQ_ENTRY NAME" +.Fn STAILQ_FOREACH_FROM_SAFE "TYPE *var" "STAILQ_HEAD *head" "STAILQ_ENTRY NAME" "TYPE *temp_var" +.Fn STAILQ_FOREACH_SAFE "TYPE *var" "STAILQ_HEAD *head" "STAILQ_ENTRY NAME" "TYPE *temp_var" +.Fn STAILQ_HEAD "HEADNAME" "TYPE" +.Fn STAILQ_HEAD_INITIALIZER "STAILQ_HEAD head" +.Fn STAILQ_INIT "STAILQ_HEAD *head" +.Fn STAILQ_INSERT_AFTER "STAILQ_HEAD *head" "TYPE *listelm" "TYPE *elm" "STAILQ_ENTRY NAME" +.Fn STAILQ_INSERT_HEAD "STAILQ_HEAD *head" "TYPE *elm" "STAILQ_ENTRY NAME" +.Fn STAILQ_INSERT_TAIL "STAILQ_HEAD *head" "TYPE *elm" "STAILQ_ENTRY NAME" +.Fn STAILQ_LAST "STAILQ_HEAD *head" "TYPE *elm" "STAILQ_ENTRY NAME" +.Fn STAILQ_NEXT "TYPE *elm" "STAILQ_ENTRY NAME" +.Fn STAILQ_REMOVE "STAILQ_HEAD *head" "TYPE *elm" "TYPE" "STAILQ_ENTRY NAME" +.Fn STAILQ_REMOVE_AFTER "STAILQ_HEAD *head" "TYPE *elm" "STAILQ_ENTRY NAME" +.Fn STAILQ_REMOVE_HEAD "STAILQ_HEAD *head" "STAILQ_ENTRY NAME" +.Fn STAILQ_REVERSE "STAILQ_HEAD *head" "TYPE" "STAILQ_ENTRY NAME" +.Fn STAILQ_SPLIT_AFTER "STAILQ_HEAD *head" "TYPE *elm" "STAILQ_HEAD *rest" "STAILQ_ENTRY NAME" +.Fn STAILQ_SWAP "STAILQ_HEAD *head1" "STAILQ_HEAD *head2" "TYPE" +.\" +.Fn LIST_CLASS_ENTRY "CLASSTYPE" +.Fn LIST_CLASS_HEAD "HEADNAME" "CLASSTYPE" +.Fn LIST_CONCAT "LIST_HEAD *head1" "LIST_HEAD *head2" "TYPE" "LIST_ENTRY NAME" +.Fn LIST_EMPTY "LIST_HEAD *head" +.Fn LIST_EMPTY_ATOMIC "LIST_HEAD *head" +.Fn LIST_ENTRY "TYPE" +.Fn LIST_FIRST "LIST_HEAD *head" +.Fn LIST_FOREACH "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" +.Fn LIST_FOREACH_FROM "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" +.Fn LIST_FOREACH_FROM_SAFE "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" "TYPE *temp_var" +.Fn LIST_FOREACH_SAFE "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" "TYPE *temp_var" +.Fn LIST_HEAD "HEADNAME" "TYPE" +.Fn LIST_HEAD_INITIALIZER "LIST_HEAD head" +.Fn LIST_INIT "LIST_HEAD *head" +.Fn LIST_INSERT_AFTER "TYPE *listelm" "TYPE *elm" "LIST_ENTRY NAME" +.Fn LIST_INSERT_BEFORE "TYPE *listelm" "TYPE *elm" "LIST_ENTRY NAME" +.Fn LIST_INSERT_HEAD "LIST_HEAD *head" "TYPE *elm" "LIST_ENTRY NAME" +.Fn LIST_NEXT "TYPE *elm" "LIST_ENTRY NAME" +.Fn LIST_PREV "TYPE *elm" "LIST_HEAD *head" "TYPE" "LIST_ENTRY NAME" +.Fn LIST_REMOVE "TYPE *elm" "LIST_ENTRY NAME" +.Fn LIST_REPLACE "TYPE *elm" "TYPE *new" "LIST_ENTRY NAME" +.Fn LIST_SPLIT_AFTER "LIST_HEAD *head" "TYPE *elm" "LIST_HEAD *rest" "LIST_ENTRY NAME" +.Fn LIST_SWAP "LIST_HEAD *head1" "LIST_HEAD *head2" "TYPE" "LIST_ENTRY NAME" +.\" +.Fn TAILQ_CLASS_ENTRY "CLASSTYPE" +.Fn TAILQ_CLASS_HEAD "HEADNAME" "CLASSTYPE" +.Fn TAILQ_CONCAT "TAILQ_HEAD *head1" "TAILQ_HEAD *head2" "TAILQ_ENTRY NAME" +.Fn TAILQ_EMPTY "TAILQ_HEAD *head" +.Fn TAILQ_EMPTY_ATOMIC "TAILQ_HEAD *head" +.Fn TAILQ_ENTRY "TYPE" +.Fn TAILQ_FIRST "TAILQ_HEAD *head" +.Fn TAILQ_FOREACH "TYPE *var" "TAILQ_HEAD *head" "TAILQ_ENTRY NAME" +.Fn TAILQ_FOREACH_FROM "TYPE *var" "TAILQ_HEAD *head" "TAILQ_ENTRY NAME" +.Fn TAILQ_FOREACH_FROM_SAFE "TYPE *var" "TAILQ_HEAD *head" "TAILQ_ENTRY NAME" "TYPE *temp_var" +.Fn TAILQ_FOREACH_REVERSE "TYPE *var" "TAILQ_HEAD *head" "HEADNAME" "TAILQ_ENTRY NAME" +.Fn TAILQ_FOREACH_REVERSE_FROM "TYPE *var" "TAILQ_HEAD *head" "HEADNAME" "TAILQ_ENTRY NAME" +.Fn TAILQ_FOREACH_REVERSE_FROM_SAFE "TYPE *var" "TAILQ_HEAD *head" "HEADNAME" "TAILQ_ENTRY NAME" "TYPE *temp_var" +.Fn TAILQ_FOREACH_REVERSE_SAFE "TYPE *var" "TAILQ_HEAD *head" "HEADNAME" "TAILQ_ENTRY NAME" "TYPE *temp_var" +.Fn TAILQ_FOREACH_SAFE "TYPE *var" "TAILQ_HEAD *head" "TAILQ_ENTRY NAME" "TYPE *temp_var" +.Fn TAILQ_HEAD "HEADNAME" "TYPE" +.Fn TAILQ_HEAD_INITIALIZER "TAILQ_HEAD head" +.Fn TAILQ_INIT "TAILQ_HEAD *head" +.Fn TAILQ_INSERT_AFTER "TAILQ_HEAD *head" "TYPE *listelm" "TYPE *elm" "TAILQ_ENTRY NAME" +.Fn TAILQ_INSERT_BEFORE "TYPE *listelm" "TYPE *elm" "TAILQ_ENTRY NAME" +.Fn TAILQ_INSERT_HEAD "TAILQ_HEAD *head" "TYPE *elm" "TAILQ_ENTRY NAME" +.Fn TAILQ_INSERT_TAIL "TAILQ_HEAD *head" "TYPE *elm" "TAILQ_ENTRY NAME" +.Fn TAILQ_LAST "TAILQ_HEAD *head" "HEADNAME" +.Fn TAILQ_NEXT "TYPE *elm" "TAILQ_ENTRY NAME" +.Fn TAILQ_PREV "TYPE *elm" "HEADNAME" "TAILQ_ENTRY NAME" +.Fn TAILQ_REMOVE "TAILQ_HEAD *head" "TYPE *elm" "TAILQ_ENTRY NAME" +.Fn TAILQ_REPLACE "TAILQ_HEAD *head" "TYPE *elm" "TYPE *new" "TAILQ_ENTRY NAME" +.Fn TAILQ_SPLIT_AFTER "TAILQ_HEAD *head" "TYPE *elm" "TAILQ_HEAD *rest" "TAILQ_ENTRY NAME" +.Fn TAILQ_SWAP "TAILQ_HEAD *head1" "TAILQ_HEAD *head2" "TYPE" "TAILQ_ENTRY NAME" +.\" +.Sh DESCRIPTION +These macros define and operate on four types of data structures which +can be used in both C and C++ source code: +.Bl -enum -compact -offset indent +.It +Lists +.It +Singly-linked lists +.It +Singly-linked tail queues +.It +Tail queues +.El +All four structures support the following functionality: +.Bl -enum -compact -offset indent +.It +Insertion of a new entry at the head of the list. +.It +Insertion of a new entry after any element in the list. +.It +O(1) removal of an entry from the head of the list. +.It +Forward traversal through the list. +.It +Splitting a list in two after any element in the list. +.It +Swapping the contents of two lists. +.El +.Pp +Singly-linked lists are the simplest of the four data structures +and support only the above functionality. +Singly-linked lists are ideal for applications with large datasets +and few or no removals, +or for implementing a LIFO queue. +Singly-linked lists add the following functionality: +.Bl -enum -compact -offset indent +.It +O(n) removal of any entry in the list. +.It +O(n) concatenation of two lists. +.El +.Pp +Singly-linked tail queues add the following functionality: +.Bl -enum -compact -offset indent +.It +Entries can be added at the end of a list. +.It +O(n) removal of any entry in the list. +.It +They may be concatenated. +.El +However: +.Bl -enum -compact -offset indent +.It +All list insertions must specify the head of the list. +.It +Each head entry requires two pointers rather than one. +.It +Code size is about 15% greater and operations run about 20% slower +than singly-linked lists. +.El +.Pp +Singly-linked tail queues are ideal for applications with large datasets and +few or no removals, +or for implementing a FIFO queue. +.Pp +All doubly linked types of data structures (lists and tail queues) +additionally allow: +.Bl -enum -compact -offset indent +.It +Insertion of a new entry before any element in the list. +.It +O(1) removal of any entry in the list. +.El +However: +.Bl -enum -compact -offset indent +.It +Each element requires two pointers rather than one. +.It +Code size and execution time of operations (except for removal) is about +twice that of the singly-linked data-structures. +.El +.Pp +Linked lists are the simplest of the doubly linked data structures. +They add the following functionality over the above: +.Bl -enum -compact -offset indent +.It +O(n) concatenation of two lists. +.It +They may be traversed backwards. +.El +However: +.Bl -enum -compact -offset indent +.It +To traverse backwards, an entry to begin the traversal and the list in +which it is contained must be specified. +.El +.Pp +Tail queues add the following functionality: +.Bl -enum -compact -offset indent +.It +Entries can be added at the end of a list. +.It +They may be traversed backwards, from tail to head. +.It +They may be concatenated. +.El +However: +.Bl -enum -compact -offset indent +.It +All list insertions and removals must specify the head of the list. +.It +Each head entry requires two pointers rather than one. +.It +Code size is about 15% greater and operations run about 20% slower +than singly-linked lists. +.El +.Pp +In the macro definitions, +.Fa TYPE +is the name of a user defined structure. +The structure must contain a field called +.Fa NAME +which is of type +.Li SLIST_ENTRY , +.Li STAILQ_ENTRY , +.Li LIST_ENTRY , +or +.Li TAILQ_ENTRY . +In the macro definitions, +.Fa CLASSTYPE +is the name of a user defined class. +The class must contain a field called +.Fa NAME +which is of type +.Li SLIST_CLASS_ENTRY , +.Li STAILQ_CLASS_ENTRY , +.Li LIST_CLASS_ENTRY , +or +.Li TAILQ_CLASS_ENTRY . +The argument +.Fa HEADNAME +is the name of a user defined structure that must be declared +using the macros +.Li SLIST_HEAD , +.Li SLIST_CLASS_HEAD , +.Li STAILQ_HEAD , +.Li STAILQ_CLASS_HEAD , +.Li LIST_HEAD , +.Li LIST_CLASS_HEAD , +.Li TAILQ_HEAD , +or +.Li TAILQ_CLASS_HEAD . +See the examples below for further explanation of how these +macros are used. +.Sh SINGLY-LINKED LISTS +A singly-linked list is headed by a structure defined by the +.Nm SLIST_HEAD +macro. +This structure contains a single pointer to the first element +on the list. +The elements are singly linked for minimum space and pointer manipulation +overhead at the expense of O(n) removal for arbitrary elements. +New elements can be added to the list after an existing element or +at the head of the list. +An +.Fa SLIST_HEAD +structure is declared as follows: +.Bd -literal -offset indent +SLIST_HEAD(HEADNAME, TYPE) head; +.Ed +.Pp +where +.Fa HEADNAME +is the name of the structure to be defined, and +.Fa TYPE +is the type of the elements to be linked into the list. +A pointer to the head of the list can later be declared as: +.Bd -literal -offset indent +struct HEADNAME *headp; +.Ed +.Pp +(The names +.Li head +and +.Li headp +are user selectable.) +.Pp +The macro +.Nm SLIST_HEAD_INITIALIZER +evaluates to an initializer for the list +.Fa head . +.Pp +The macro +.Nm SLIST_CONCAT +concatenates the list headed by +.Fa head2 +onto the end of the one headed by +.Fa head1 +removing all entries from the former. +Use of this macro should be avoided as it traverses the entirety of the +.Fa head1 +list. +A singly-linked tail queue should be used if this macro is needed in +high-usage code paths or to operate on long lists. +.Pp +The macro +.Nm SLIST_EMPTY +evaluates to true if there are no elements in the list. +The +.Nm SLIST_EMPTY_ATOMIC +variant has the same behavior, but can be safely used in contexts where it is +possible that a different thread is concurrently updating the list. +.Pp +The macro +.Nm SLIST_ENTRY +declares a structure that connects the elements in +the list. +.Pp +The macro +.Nm SLIST_FIRST +returns the first element in the list or NULL if the list is empty. +.Pp +The macro +.Nm SLIST_FOREACH +traverses the list referenced by +.Fa head +in the forward direction, assigning each element in +turn to +.Fa var . +.Pp +The macro +.Nm SLIST_FOREACH_FROM +behaves identically to +.Nm SLIST_FOREACH +when +.Fa var +is NULL, else it treats +.Fa var +as a previously found SLIST element and begins the loop at +.Fa var +instead of the first element in the SLIST referenced by +.Fa head . +.Pp +The macro +.Nm SLIST_FOREACH_SAFE +traverses the list referenced by +.Fa head +in the forward direction, assigning each element in +turn to +.Fa var . +However, unlike +.Fn SLIST_FOREACH +here it is permitted to both remove +.Fa var +as well as free it from within the loop safely without interfering with the +traversal. +.Pp +The macro +.Nm SLIST_FOREACH_FROM_SAFE +behaves identically to +.Nm SLIST_FOREACH_SAFE +when +.Fa var +is NULL, else it treats +.Fa var +as a previously found SLIST element and begins the loop at +.Fa var +instead of the first element in the SLIST referenced by +.Fa head . +.Pp +The macro +.Nm SLIST_INIT +initializes the list referenced by +.Fa head . +.Pp +The macro +.Nm SLIST_INSERT_HEAD +inserts the new element +.Fa elm +at the head of the list. +.Pp +The macro +.Nm SLIST_INSERT_AFTER +inserts the new element +.Fa elm +after the element +.Fa listelm . +.Pp +The macro +.Nm SLIST_NEXT +returns the next element in the list. +.Pp +The macro +.Nm SLIST_REMOVE_AFTER +removes the element after +.Fa elm +from the list. +Unlike +.Fa SLIST_REMOVE , +this macro does not traverse the entire list. +.Pp +The macro +.Nm SLIST_REMOVE_HEAD +removes the element +.Fa elm +from the head of the list. +For optimum efficiency, +elements being removed from the head of the list should explicitly use +this macro instead of the generic +.Fa SLIST_REMOVE +macro. +.Pp +The macro +.Nm SLIST_REMOVE +removes the element +.Fa elm +from the list. +Use of this macro should be avoided as it traverses the entire list. +A doubly-linked list should be used if this macro is needed in +high-usage code paths or to operate on long lists. +.Pp +The macro +.Nm SLIST_SPLIT_AFTER +splits the list referenced by +.Fa head , +making +.Fa rest +reference the list formed by elements after +.Fa elm +in +.Fa head . +.Pp +The macro +.Nm SLIST_SWAP +swaps the contents of +.Fa head1 +and +.Fa head2 . +.Sh SINGLY-LINKED LIST EXAMPLE +.Bd -literal +SLIST_HEAD(slisthead, entry) head = + SLIST_HEAD_INITIALIZER(head); +struct slisthead *headp; /* Singly-linked List head. */ +struct entry { + ... + SLIST_ENTRY(entry) entries; /* Singly-linked List. */ + ... +} *n1, *n2, *n3, *np; + +SLIST_INIT(&head); /* Initialize the list. */ + +n1 = malloc(sizeof(struct entry)); /* Insert at the head. */ +SLIST_INSERT_HEAD(&head, n1, entries); + +n2 = malloc(sizeof(struct entry)); /* Insert after. */ +SLIST_INSERT_AFTER(n1, n2, entries); + +SLIST_REMOVE(&head, n2, entry, entries);/* Deletion. */ +free(n2); + +n3 = SLIST_FIRST(&head); +SLIST_REMOVE_HEAD(&head, entries); /* Deletion from the head. */ +free(n3); + /* Forward traversal. */ +SLIST_FOREACH(np, &head, entries) + np-> ... + /* Safe forward traversal. */ +SLIST_FOREACH_SAFE(np, &head, entries, np_temp) { + np->do_stuff(); + ... + SLIST_REMOVE(&head, np, entry, entries); + free(np); +} + +while (!SLIST_EMPTY(&head)) { /* List Deletion. */ + n1 = SLIST_FIRST(&head); + SLIST_REMOVE_HEAD(&head, entries); + free(n1); +} +.Ed +.Sh SINGLY-LINKED TAIL QUEUES +A singly-linked tail queue is headed by a structure defined by the +.Nm STAILQ_HEAD +macro. +This structure contains a pair of pointers, +one to the first element in the tail queue and the other to +the last element in the tail queue. +The elements are singly linked for minimum space and pointer +manipulation overhead at the expense of O(n) removal for arbitrary +elements. +New elements can be added to the tail queue after an existing element, +at the head of the tail queue, or at the end of the tail queue. +A +.Fa STAILQ_HEAD +structure is declared as follows: +.Bd -literal -offset indent +STAILQ_HEAD(HEADNAME, TYPE) head; +.Ed +.Pp +where +.Li HEADNAME +is the name of the structure to be defined, and +.Li TYPE +is the type of the elements to be linked into the tail queue. +A pointer to the head of the tail queue can later be declared as: +.Bd -literal -offset indent +struct HEADNAME *headp; +.Ed +.Pp +(The names +.Li head +and +.Li headp +are user selectable.) +.Pp +The macro +.Nm STAILQ_HEAD_INITIALIZER +evaluates to an initializer for the tail queue +.Fa head . +.Pp +The macro +.Nm STAILQ_CONCAT +concatenates the tail queue headed by +.Fa head2 +onto the end of the one headed by +.Fa head1 +removing all entries from the former. +.Pp +The macro +.Nm STAILQ_EMPTY +evaluates to true if there are no items on the tail queue. +The +.Nm STAILQ_EMPTY_ATOMIC +variant has the same behavior, but can be safely used in contexts where it is +possible that a different thread is concurrently updating the queue. +.Pp +The macro +.Nm STAILQ_ENTRY +declares a structure that connects the elements in +the tail queue. +.Pp +The macro +.Nm STAILQ_FIRST +returns the first item on the tail queue or NULL if the tail queue +is empty. +.Pp +The macro +.Nm STAILQ_FOREACH +traverses the tail queue referenced by +.Fa head +in the forward direction, assigning each element +in turn to +.Fa var . +.Pp +The macro +.Nm STAILQ_FOREACH_FROM +behaves identically to +.Nm STAILQ_FOREACH +when +.Fa var +is NULL, else it treats +.Fa var +as a previously found STAILQ element and begins the loop at +.Fa var +instead of the first element in the STAILQ referenced by +.Fa head . +.Pp +The macro +.Nm STAILQ_FOREACH_SAFE +traverses the tail queue referenced by +.Fa head +in the forward direction, assigning each element +in turn to +.Fa var . +However, unlike +.Fn STAILQ_FOREACH +here it is permitted to both remove +.Fa var +as well as free it from within the loop safely without interfering with the +traversal. +.Pp +The macro +.Nm STAILQ_FOREACH_FROM_SAFE +behaves identically to +.Nm STAILQ_FOREACH_SAFE +when +.Fa var +is NULL, else it treats +.Fa var +as a previously found STAILQ element and begins the loop at +.Fa var +instead of the first element in the STAILQ referenced by +.Fa head . +.Pp +The macro +.Nm STAILQ_INIT +initializes the tail queue referenced by +.Fa head . +.Pp +The macro +.Nm STAILQ_INSERT_HEAD +inserts the new element +.Fa elm +at the head of the tail queue. +.Pp +The macro +.Nm STAILQ_INSERT_TAIL +inserts the new element +.Fa elm +at the end of the tail queue. +.Pp +The macro +.Nm STAILQ_INSERT_AFTER +inserts the new element +.Fa elm +after the element +.Fa listelm . +.Pp +The macro +.Nm STAILQ_LAST +returns the last item on the tail queue. +If the tail queue is empty the return value is +.Dv NULL . +.Pp +The macro +.Nm STAILQ_NEXT +returns the next item on the tail queue, or NULL this item is the last. +.Pp +The macro +.Nm STAILQ_REMOVE_AFTER +removes the element after +.Fa elm +from the tail queue. +Unlike +.Fa STAILQ_REMOVE , +this macro does not traverse the entire tail queue. +.Pp +The macro +.Nm STAILQ_REMOVE_HEAD +removes the element at the head of the tail queue. +For optimum efficiency, +elements being removed from the head of the tail queue should +use this macro explicitly rather than the generic +.Fa STAILQ_REMOVE +macro. +.Pp +The macro +.Nm STAILQ_REMOVE +removes the element +.Fa elm +from the tail queue. +Use of this macro should be avoided as it traverses the entire list. +A doubly-linked tail queue should be used if this macro is needed in +high-usage code paths or to operate on long tail queues. +.Pp +The macro +.Nm STAILQ_REVERSE +reverses the queue in place. +.Pp +The macro +.Nm STAILQ_SPLIT_AFTER +splits the tail queue referenced by +.Fa head , +making +.Fa rest +reference the tail queue formed by elements after +.Fa elm +in +.Fa head . +.Pp +The macro +.Nm STAILQ_SWAP +swaps the contents of +.Fa head1 +and +.Fa head2 . +.Sh SINGLY-LINKED TAIL QUEUE EXAMPLE +.Bd -literal +STAILQ_HEAD(stailhead, entry) head = + STAILQ_HEAD_INITIALIZER(head); +struct stailhead *headp; /* Singly-linked tail queue head. */ +struct entry { + ... + STAILQ_ENTRY(entry) entries; /* Tail queue. */ + ... +} *n1, *n2, *n3, *np; + +STAILQ_INIT(&head); /* Initialize the queue. */ + +n1 = malloc(sizeof(struct entry)); /* Insert at the head. */ +STAILQ_INSERT_HEAD(&head, n1, entries); + +n1 = malloc(sizeof(struct entry)); /* Insert at the tail. */ +STAILQ_INSERT_TAIL(&head, n1, entries); + +n2 = malloc(sizeof(struct entry)); /* Insert after. */ +STAILQ_INSERT_AFTER(&head, n1, n2, entries); + /* Deletion. */ +STAILQ_REMOVE(&head, n2, entry, entries); +free(n2); + /* Deletion from the head. */ +n3 = STAILQ_FIRST(&head); +STAILQ_REMOVE_HEAD(&head, entries); +free(n3); + /* Forward traversal. */ +STAILQ_FOREACH(np, &head, entries) + np-> ... + /* Safe forward traversal. */ +STAILQ_FOREACH_SAFE(np, &head, entries, np_temp) { + np->do_stuff(); + ... + STAILQ_REMOVE(&head, np, entry, entries); + free(np); +} + /* TailQ Deletion. */ +while (!STAILQ_EMPTY(&head)) { + n1 = STAILQ_FIRST(&head); + STAILQ_REMOVE_HEAD(&head, entries); + free(n1); +} + /* Faster TailQ Deletion. */ +n1 = STAILQ_FIRST(&head); +while (n1 != NULL) { + n2 = STAILQ_NEXT(n1, entries); + free(n1); + n1 = n2; +} +STAILQ_INIT(&head); +.Ed +.Sh LISTS +A list is headed by a structure defined by the +.Nm LIST_HEAD +macro. +This structure contains a single pointer to the first element +on the list. +The elements are doubly linked so that an arbitrary element can be +removed without traversing the list. +New elements can be added to the list after an existing element, +before an existing element, or at the head of the list. +A +.Fa LIST_HEAD +structure is declared as follows: +.Bd -literal -offset indent +LIST_HEAD(HEADNAME, TYPE) head; +.Ed +.Pp +where +.Fa HEADNAME +is the name of the structure to be defined, and +.Fa TYPE +is the type of the elements to be linked into the list. +A pointer to the head of the list can later be declared as: +.Bd -literal -offset indent +struct HEADNAME *headp; +.Ed +.Pp +(The names +.Li head +and +.Li headp +are user selectable.) +.Pp +The macro +.Nm LIST_HEAD_INITIALIZER +evaluates to an initializer for the list +.Fa head . +.Pp +The macro +.Nm LIST_CONCAT +concatenates the list headed by +.Fa head2 +onto the end of the one headed by +.Fa head1 +removing all entries from the former. +Use of this macro should be avoided as it traverses the entirety of the +.Fa head1 +list. +A tail queue should be used if this macro is needed in +high-usage code paths or to operate on long lists. +.Pp +The macro +.Nm LIST_EMPTY +evaluates to true if there are no elements in the list. +The +.Nm LIST_EMPTY_ATOMIC +variant has the same behavior, but can be safely used in contexts where it is +possible that a different thread is concurrently updating the list. +.Pp +The macro +.Nm LIST_ENTRY +declares a structure that connects the elements in +the list. +.Pp +The macro +.Nm LIST_FIRST +returns the first element in the list or NULL if the list +is empty. +.Pp +The macro +.Nm LIST_FOREACH +traverses the list referenced by +.Fa head +in the forward direction, assigning each element in turn to +.Fa var . +.Pp +The macro +.Nm LIST_FOREACH_FROM +behaves identically to +.Nm LIST_FOREACH +when +.Fa var +is NULL, else it treats +.Fa var +as a previously found LIST element and begins the loop at +.Fa var +instead of the first element in the LIST referenced by +.Fa head . +.Pp +The macro +.Nm LIST_FOREACH_SAFE +traverses the list referenced by +.Fa head +in the forward direction, assigning each element in turn to +.Fa var . +However, unlike +.Fn LIST_FOREACH +here it is permitted to both remove +.Fa var +as well as free it from within the loop safely without interfering with the +traversal. +.Pp +The macro +.Nm LIST_FOREACH_FROM_SAFE +behaves identically to +.Nm LIST_FOREACH_SAFE +when +.Fa var +is NULL, else it treats +.Fa var +as a previously found LIST element and begins the loop at +.Fa var +instead of the first element in the LIST referenced by +.Fa head . +.Pp +The macro +.Nm LIST_INIT +initializes the list referenced by +.Fa head . +.Pp +The macro +.Nm LIST_INSERT_HEAD +inserts the new element +.Fa elm +at the head of the list. +.Pp +The macro +.Nm LIST_INSERT_AFTER +inserts the new element +.Fa elm +after the element +.Fa listelm . +.Pp +The macro +.Nm LIST_INSERT_BEFORE +inserts the new element +.Fa elm +before the element +.Fa listelm . +.Pp +The macro +.Nm LIST_NEXT +returns the next element in the list, or NULL if this is the last. +.Pp +The macro +.Nm LIST_PREV +returns the previous element in the list, or NULL if this is the first. +List +.Fa head +must contain element +.Fa elm . +.Pp +The macro +.Nm LIST_REMOVE +removes the element +.Fa elm +from the list. +.Pp +The macro +.Fn LIST_REPLACE +replaces the element +.Fa elm +with +.Fa new +in the list. +The element +.Fa new +must not already be on a list. +.Pp +The macro +.Nm LIST_SPLIT_AFTER +splits the list referenced by +.Fa head , +making +.Fa rest +reference the list formed by elements after +.Fa elm +in +.Fa head . +.Pp +The macro +.Nm LIST_SWAP +swaps the contents of +.Fa head1 +and +.Fa head2 . +.Sh LIST EXAMPLE +.Bd -literal +LIST_HEAD(listhead, entry) head = + LIST_HEAD_INITIALIZER(head); +struct listhead *headp; /* List head. */ +struct entry { + ... + LIST_ENTRY(entry) entries; /* List. */ + ... +} *n1, *n2, *n3, *np, *np_temp; + +LIST_INIT(&head); /* Initialize the list. */ + +n1 = malloc(sizeof(struct entry)); /* Insert at the head. */ +LIST_INSERT_HEAD(&head, n1, entries); + +n2 = malloc(sizeof(struct entry)); /* Insert after. */ +LIST_INSERT_AFTER(n1, n2, entries); + +n3 = malloc(sizeof(struct entry)); /* Insert before. */ +LIST_INSERT_BEFORE(n2, n3, entries); + +LIST_REMOVE(n2, entries); /* Deletion. */ +free(n2); + /* Forward traversal. */ +LIST_FOREACH(np, &head, entries) + np-> ... + + /* Safe forward traversal. */ +LIST_FOREACH_SAFE(np, &head, entries, np_temp) { + np->do_stuff(); + ... + LIST_REMOVE(np, entries); + free(np); +} + +while (!LIST_EMPTY(&head)) { /* List Deletion. */ + n1 = LIST_FIRST(&head); + LIST_REMOVE(n1, entries); + free(n1); +} + +n1 = LIST_FIRST(&head); /* Faster List Deletion. */ +while (n1 != NULL) { + n2 = LIST_NEXT(n1, entries); + free(n1); + n1 = n2; +} +LIST_INIT(&head); +.Ed +.Sh TAIL QUEUES +A tail queue is headed by a structure defined by the +.Nm TAILQ_HEAD +macro. +This structure contains a pair of pointers, +one to the first element in the tail queue and the other to +the last element in the tail queue. +The elements are doubly linked so that an arbitrary element can be +removed without traversing the tail queue. +New elements can be added to the tail queue after an existing element, +before an existing element, at the head of the tail queue, +or at the end of the tail queue. +A +.Fa TAILQ_HEAD +structure is declared as follows: +.Bd -literal -offset indent +TAILQ_HEAD(HEADNAME, TYPE) head; +.Ed +.Pp +where +.Li HEADNAME +is the name of the structure to be defined, and +.Li TYPE +is the type of the elements to be linked into the tail queue. +A pointer to the head of the tail queue can later be declared as: +.Bd -literal -offset indent +struct HEADNAME *headp; +.Ed +.Pp +(The names +.Li head +and +.Li headp +are user selectable.) +.Pp +The macro +.Nm TAILQ_HEAD_INITIALIZER +evaluates to an initializer for the tail queue +.Fa head . +.Pp +The macro +.Nm TAILQ_CONCAT +concatenates the tail queue headed by +.Fa head2 +onto the end of the one headed by +.Fa head1 +removing all entries from the former. +.Pp +The macro +.Nm TAILQ_EMPTY +evaluates to true if there are no items on the tail queue. +The +.Nm TAILQ_EMPTY_ATOMIC +variant has the same behavior, but can be safely used in contexts where it is +possible that a different thread is concurrently updating the queue. +.Pp +The macro +.Nm TAILQ_ENTRY +declares a structure that connects the elements in +the tail queue. +.Pp +The macro +.Nm TAILQ_FIRST +returns the first item on the tail queue or NULL if the tail queue +is empty. +.Pp +The macro +.Nm TAILQ_FOREACH +traverses the tail queue referenced by +.Fa head +in the forward direction, assigning each element in turn to +.Fa var . +.Fa var +is set to +.Dv NULL +if the loop completes normally, or if there were no elements. +.Pp +The macro +.Nm TAILQ_FOREACH_FROM +behaves identically to +.Nm TAILQ_FOREACH +when +.Fa var +is NULL, else it treats +.Fa var +as a previously found TAILQ element and begins the loop at +.Fa var +instead of the first element in the TAILQ referenced by +.Fa head . +.Pp +The macro +.Nm TAILQ_FOREACH_REVERSE +traverses the tail queue referenced by +.Fa head +in the reverse direction, assigning each element in turn to +.Fa var . +.Pp +The macro +.Nm TAILQ_FOREACH_REVERSE_FROM +behaves identically to +.Nm TAILQ_FOREACH_REVERSE +when +.Fa var +is NULL, else it treats +.Fa var +as a previously found TAILQ element and begins the reverse loop at +.Fa var +instead of the last element in the TAILQ referenced by +.Fa head . +.Pp +The macros +.Nm TAILQ_FOREACH_SAFE +and +.Nm TAILQ_FOREACH_REVERSE_SAFE +traverse the list referenced by +.Fa head +in the forward or reverse direction respectively, +assigning each element in turn to +.Fa var . +However, unlike their unsafe counterparts, +.Nm TAILQ_FOREACH +and +.Nm TAILQ_FOREACH_REVERSE +permit to both remove +.Fa var +as well as free it from within the loop safely without interfering with the +traversal. +.Pp +The macro +.Nm TAILQ_FOREACH_FROM_SAFE +behaves identically to +.Nm TAILQ_FOREACH_SAFE +when +.Fa var +is NULL, else it treats +.Fa var +as a previously found TAILQ element and begins the loop at +.Fa var +instead of the first element in the TAILQ referenced by +.Fa head . +.Pp +The macro +.Nm TAILQ_FOREACH_REVERSE_FROM_SAFE +behaves identically to +.Nm TAILQ_FOREACH_REVERSE_SAFE +when +.Fa var +is NULL, else it treats +.Fa var +as a previously found TAILQ element and begins the reverse loop at +.Fa var +instead of the last element in the TAILQ referenced by +.Fa head . +.Pp +The macro +.Nm TAILQ_INIT +initializes the tail queue referenced by +.Fa head . +.Pp +The macro +.Nm TAILQ_INSERT_HEAD +inserts the new element +.Fa elm +at the head of the tail queue. +.Pp +The macro +.Nm TAILQ_INSERT_TAIL +inserts the new element +.Fa elm +at the end of the tail queue. +.Pp +The macro +.Nm TAILQ_INSERT_AFTER +inserts the new element +.Fa elm +after the element +.Fa listelm . +.Pp +The macro +.Nm TAILQ_INSERT_BEFORE +inserts the new element +.Fa elm +before the element +.Fa listelm . +.Pp +The macro +.Nm TAILQ_LAST +returns the last item on the tail queue. +If the tail queue is empty the return value is +.Dv NULL . +.Pp +The macro +.Nm TAILQ_NEXT +returns the next item on the tail queue, or NULL if this item is the last. +.Pp +The macro +.Nm TAILQ_PREV +returns the previous item on the tail queue, or NULL if this item +is the first. +.Pp +The macro +.Nm TAILQ_REMOVE +removes the element +.Fa elm +from the tail queue. +.Pp +The macro +.Fn TAILQ_REPLACE +replaces the element +.Fa elm +with +.Fa new +in the tail queue. +The element +.Fa new +must not already be on a list. +.Pp +The macro +.Nm TAILQ_SPLIT_AFTER +splits the tail queue referenced by +.Fa head , +making +.Fa rest +reference the tail queue formed by elements after +.Fa elm +in +.Fa head . +.Pp +The macro +.Nm TAILQ_SWAP +swaps the contents of +.Fa head1 +and +.Fa head2 . +.Sh TAIL QUEUE EXAMPLE +.Bd -literal +TAILQ_HEAD(tailhead, entry) head = + TAILQ_HEAD_INITIALIZER(head); +struct tailhead *headp; /* Tail queue head. */ +struct entry { + ... + TAILQ_ENTRY(entry) entries; /* Tail queue. */ + ... +} *n1, *n2, *n3, *n4, *np; + +TAILQ_INIT(&head); /* Initialize the queue. */ + +n1 = malloc(sizeof(struct entry)); /* Insert at the head. */ +TAILQ_INSERT_HEAD(&head, n1, entries); + +n1 = malloc(sizeof(struct entry)); /* Insert at the tail. */ +TAILQ_INSERT_TAIL(&head, n1, entries); + +n2 = malloc(sizeof(struct entry)); /* Insert after. */ +TAILQ_INSERT_AFTER(&head, n1, n2, entries); + +n3 = malloc(sizeof(struct entry)); /* Insert before. */ +TAILQ_INSERT_BEFORE(n2, n3, entries); + +TAILQ_REMOVE(&head, n2, entries); /* Deletion. */ +free(n2); + +n4 = malloc(sizeof(struct entry)); /* Replacement. */ +TAILQ_REPLACE(&head, n3, n4, entries); +free(n3); + /* Forward traversal. */ +TAILQ_FOREACH(np, &head, entries) + np-> ... + /* Safe forward traversal. */ +TAILQ_FOREACH_SAFE(np, &head, entries, np_temp) { + np->do_stuff(); + ... + TAILQ_REMOVE(&head, np, entries); + free(np); +} + /* Reverse traversal. */ +TAILQ_FOREACH_REVERSE(np, &head, tailhead, entries) + np-> ... + /* TailQ Deletion. */ +while (!TAILQ_EMPTY(&head)) { + n1 = TAILQ_FIRST(&head); + TAILQ_REMOVE(&head, n1, entries); + free(n1); +} + /* Faster TailQ Deletion. */ +n1 = TAILQ_FIRST(&head); +while (n1 != NULL) { + n2 = TAILQ_NEXT(n1, entries); + free(n1); + n1 = n2; +} +TAILQ_INIT(&head); +.Ed +.Sh DIAGNOSTICS +.Nm queue(3) +provides several diagnostic and debugging facilities. +.Pp +Check code that performs basic integrity and API conformance checks is +automatically inserted when using queue macros in the kernel if compiling it +with +.Va INVARIANTS . +One can request insertion or elision of check code by respectively defining one +of the macros +.Va QUEUE_MACRO_DEBUG_ASSERTIONS +or +.Va QUEUE_MACRO_NO_DEBUG_ASSERTIONS +before first inclusion of +.In sys/queue.h . +When check code encounters an anomaly, it panics the kernel or aborts the +program. +To this end, in the kernel or in +.Va _STANDALONE +builds, it by default calls +.Fn panic , +while in userland builds it prints the diagnostic message on +.Dv stderr +and then calls +.Fn abort . +These behaviors can be overridden by defining a custom +.Fn QMD_PANIC +macro before first inclusion of +.In sys/queue.h . +The diagnostic messages automatically include the source file, line and function +where the failing check occurred. +This behavior can be overridden by defining a custom +.Fn QMD_ASSERT +macro before first inclusion of +.In sys/queue.h . +.Pp +The +.Fn SLIST_REMOVE_PREVPTR +macro is available to aid debugging: +.Bl -hang -offset indent +.It Fn SLIST_REMOVE_PREVPTR "TYPE **prev" "TYPE *elm" "SLIST_ENTRY NAME" +.Pp +Removes element +.Fa elm , +which must directly follow the element whose +.Va &SLIST_NEXT() +is +.Fa prev , +from the list. +This macro may insert, under conditions detailed above, check code that +validates that +.Fa elm +indeed follows +.Fa prev +in the list +.Po +through the +.Fn QMD_SLIST_CHECK_PREVPTR +macro +.Pc . +.El +.Pp +When debugging, it can be useful to trace queue changes. +To enable tracing, define the macro +.Va QUEUE_MACRO_DEBUG_TRACE . +Note that, at the moment, only macros for regular tail queues have been +instrumented. +.Pp +It can also be useful to trash pointers that have been unlinked from a queue, +to detect use after removal. +To enable pointer trashing, define the macro +.Va QUEUE_MACRO_DEBUG_TRASH +at compile time. +Note that, at the moment, only a limited number of macros have been +instrumented. +The macro +.Fn QMD_IS_TRASHED "void *ptr" +returns true if +.Fa ptr +has been trashed by the +.Va QUEUE_MACRO_DEBUG_TRASH +option. +.Sh SEE ALSO +.Xr arb 3 , +.Xr tree 3 +.Sh HISTORY +The +.Nm queue +functions first appeared in +.Bx 4.4 . diff --git a/static/freebsd/man3/sigevent.3 b/static/freebsd/man3/sigevent.3 new file mode 100644 index 00000000..731b3658 --- /dev/null +++ b/static/freebsd/man3/sigevent.3 @@ -0,0 +1,129 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2016 John H. Baldwin +.\" +.\" 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 February 25, 2020 +.Dt SIGEVENT 3 +.Os +.Sh NAME +.Nm sigevent +.Nd "asynchronous event notification" +.Sh SYNOPSIS +.In signal.h +.Sh DESCRIPTION +Some operations permit threads to request asynchronous notification of events +via a +.Vt struct sigevent +structure. +This structure contains several fields that describe the requested notification: +.Bl -column ".Vt void (*)(union sigval)" ".Va sigev_notify_kevent_flags" +.It Sy Type Ta Sy Member Ta Sy Description +.It Vt int Ta sigev_notify Ta notification method +.It Vt int Ta sigev_signo Ta signal number +.It Vt union sigval Ta sigev_value Ta signal value +.It Vt int Ta sigev_notify_kqueue Ta +.Xr kqueue 2 +file descriptor +.It Vt unsigned short Ta sigev_notify_kevent_flags Ta kevent flags +.It Vt lwpid_t Ta sigev_notify_thread_id Ta LWP ID +.It Vt void (*)(union sigval) Ta sigev_notify_function Ta +callback function pointer +.It Vt pthread_attr_t * Ta sigev_notify_attributes Ta +callback thread attributes +.El +.Pp +The +.Va sigev_notify +field specifies the notification method used when the event triggers: +.Bl -tag -width ".Dv SIGEV_THREAD_ID" +.It Dv SIGEV_NONE +No notification is sent. +.It Dv SIGEV_SIGNAL +The signal +.Va sigev_signo +is queued as a real-time signal to the calling process. +The value stored in +.Va sigev_value +will be present in the +.Va si_value +of the +.Vt siginfo_t +structure of the queued signal. +.It Dv SIGEV_THREAD +The notification function in +.Va sigev_notify_function +is called in a separate thread context. +The thread is created with the attributes specified in +.Va *sigev_notify_attributes . +The value stored in +.Va sigev_value +is passed as the sole argument to +.Va sigev_notify_function . +If +.Va sigev_notify_attributes +is +.Dv NULL , +the thread is created with default attributes. +.It Dv SIGEV_KEVENT +A new kevent is posted to the kqueue +.Va sigev_notify_kqueue . +The +.Va udata +member of the kevent structure contains the value stored in +.Va sigev_value . +The meaning of other fields in the kevent are specific to the type of triggered +event. +.It Dv SIGEV_THREAD_ID +The signal +.Va sigev_signo +is queued to the thread whose LWP ID is +.Va sigev_notify_thread_id . +The value stored in +.Va sigev_value +will be present in the +.Va si_value +of the +.Vt siginfo_t +structure of the queued signal. +.El +.Sh NOTES +Note that programs wishing to use +.Dv SIGEV_THREAD +notifications must link against the +.Lb librt . +.Sh SEE ALSO +.Xr aio_read 2 , +.Xr mq_notify 2 , +.Xr timer_create 2 , +.Xr siginfo 3 +.Sh STANDARDS +The +.Vt struct sigevent +type conforms to +.St -p1003.1-2004 . +.Sh HISTORY +The +.Va sigevent +structure first appeared in +.Fx 3.3 . diff --git a/static/freebsd/man3/siginfo.3 b/static/freebsd/man3/siginfo.3 new file mode 100644 index 00000000..59e3ecf8 --- /dev/null +++ b/static/freebsd/man3/siginfo.3 @@ -0,0 +1,348 @@ +.\" Copyright (c) 2005 David Xu +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 February 17, 2021 +.Dt SIGINFO 3 +.Os +.Sh NAME +.Nm siginfo +.Nd "signal generation information" +.Sh SYNOPSIS +.In signal.h +.Sh DESCRIPTION +A process may request signal information when it is catching a signal. +The information specifies why the system generated that signal. +To request signal information in a signal handler, the user can set +.Dv SA_SIGINFO +in +.Va sa_flags +before +.Xr sigaction 2 +is called, +otherwise the user can use +.Xr sigwaitinfo 2 +and +.Xr sigtimedwait 2 +to get signal information. +In either case, the system returns the information in a structure of type +.Vt siginfo_t , +which includes the following information: +.Bl -column ".Vt union signal" ".Va si_overrun" +.It Sy Type Ta Sy Member Ta Sy Description +.It Vt int Ta Va si_signo Ta +signal number +.It Vt int Ta Va si_errno Ta +error number +.It Vt int Ta Va si_code Ta +signal code +.It Vt union sigval Ta Va si_value Ta +signal value +.It Vt pid_t Ta Va si_pid Ta +sending process ID +.It Vt uid_t Ta Va si_uid Ta +sending process's real user ID +.It Vt void Ta Va *si_addr Ta +virtual address +.It Vt int Ta Va si_status Ta +exit value or signal +.It Vt long Ta Va si_band Ta +band event for +.Dv SIGPOLL +.It Vt int Ta Va si_trapno Ta +machine trap code +.It Vt int Ta Va si_timerid Ta +.Tn POSIX +timer ID +.It Vt int Ta Va si_overrun Ta +.Tn POSIX +timer overrun count +.It Vt int Ta Va si_mqd Ta +.Tn POSIX +message queue ID +.It Vt int Ta Va si_syscall Ta +system-call number for system calls blocked by Capsicum +.El +.Pp +The +.Va si_signo +member contains the signal number. +.Pp +The +.Va si_errno +member contains an error number defined in the file +.In errno.h . +.Pp +The +.Va si_code +member contains a code which describes the cause of the signal. +The macros specified in the +.Sy Code +column of the following table are defined +for use as values of +.Va si_code +that are signal-specific or non-signal-specific reasons why the signal was +generated: +.Bl -column ".Dv SIGPOLL" ".Dv CLD_CONTINUED" +.It Sy Signal Ta Sy Code Ta Sy Reason +.It Dv SIGILL Ta Dv ILL_ILLOPC Ta +illegal opcode +.It Ta Dv ILL_ILLOPN Ta +illegal operand +.It Ta Dv ILL_ILLADR Ta +illegal addressing mode +.It Ta Dv ILL_ILLTRP Ta +illegal trap +.It Ta Dv ILL_PRVOPC Ta +illegal privileged opcode +.It Ta Dv ILL_PRVREG Ta +illegal privileged register +.It Ta Dv ILL_COPROC Ta +coprocessor error +.It Ta Dv ILL_BADSTK Ta +internal stack error +.It Dv SIGFPE Ta Dv FPE_INTDIV Ta +integer divide by zero +.It Ta Dv FPE_INTOVF Ta +integer overflow +.It Ta Dv FPE_FLTDIV Ta +floating-point divide by zero +.It Ta Dv FPE_FLTOVF Ta +floating-point overflow +.It Ta Dv FPE_FLTUND Ta +floating-point underflow +.It Ta Dv FPE_FLTRES Ta +floating-point inexact result +.It Ta Dv FPE_FLTINV Ta +invalid floating-point operation +.It Ta Dv FPE_FLTSUB Ta +subscript out of range +.It Dv SIGSEGV Ta Dv SEGV_MAPERR Ta +address not mapped to object +.It Ta Dv SEGV_ACCERR Ta +invalid permissions for mapped object +.It Dv SIGBUS Ta Dv BUS_ADRALN Ta +invalid address alignment +.It Ta Dv BUS_ADRERR Ta +nonexistent physical address +.It Ta Dv BUS_OBJERR Ta +object-specific hardware error +.It Ta Dv BUS_OOMERR Ta +cannot alloc a page to map at fault +.It Dv SIGTRAP Ta Dv TRAP_BRKPT Ta +process breakpoint +.It Ta Dv TRAP_TRACE Ta +process trace trap +.It Ta Dv TRAP_DTRACE Ta +DTrace induced trap +.It Ta Dv TRAP_CAP Ta +capabilities protective trap +.It Dv SIGCHLD Ta Dv CLD_EXITED Ta +child has exited +.It Ta Dv CLD_KILLED Ta +child has terminated abnormally and did not create a core file +.It Ta Dv CLD_DUMPED Ta +child has terminated abnormally and created a core file +.It Ta Dv CLD_TRAPPED Ta +traced child has trapped +.It Ta Dv CLD_STOPPED Ta +child has stopped +.It Ta Dv CLD_CONTINUED Ta +stopped child has continued +.It Dv SIGPOLL Ta Dv POLL_IN Ta +data input available +.It Ta Dv POLL_OUT Ta +output buffers available +.It Ta Dv POLL_MSG Ta +input message available +.It Ta Dv POLL_ERR Ta +I/O error +.It Ta Dv POLL_PRI Ta +high priority input available +.It Ta Dv POLL_HUP Ta +device disconnected +.It Any Ta Dv SI_NOINFO Ta +Only the +.Va si_signo +member is meaningful; the value of all other members is unspecified. +.It Ta Dv SI_USER Ta +signal sent by +.Xr kill 2 +.It Ta Dv SI_QUEUE Ta +signal sent by +.Xr sigqueue 2 +.It Ta Dv SI_TIMER Ta +signal generated by expiration of a timer set by +.Xr timer_settime 2 +.It Ta Dv SI_ASYNCIO Ta +signal generated by completion of an asynchronous I/O request +.It Ta Dv SI_MESGQ Ta +signal generated by arrival of a message on an empty message queue +.It Ta Dv SI_KERNEL Ta +signal generated by miscellaneous parts of the kernel +.It Ta Dv SI_LWP Ta +signal sent by +.Xr pthread_kill 3 +.El +.Pp +For synchronous signals, +.Va si_addr +is generally set to the address of the faulting instruction. +However, synchronous signals raised by a faulting memory access such as +.Dv SIGSEGV +and +.Dv SIGBUS +may report the address of the faulting memory access (if available) in +.Va si_addr +instead. +Additionally +.Dv SIGTRAP +raised by a hardware watchpoint exception may report the data address that +triggered the watchpoint in +.Va si_addr . +.Pp +Synchronous signals set +.Va si_trapno +to a machine-dependent trap number. +.Pp +In addition, the following signal-specific information is available: +.Bl -column ".Dv SIGPOLL" ".Dv CLD_CONTINUED" +.It Sy Signal Ta Sy Member Ta Sy Value +.It Dv SIGCHLD Ta Va si_pid Ta +child process ID +.It Ta Va si_status Ta +exit value or signal; if +.Va si_code +is equal to +.Dv CLD_EXITED , +then it is equal to the exit value of the child process, otherwise, +it is equal to a signal that caused the child process to change state. +.It Ta Va si_uid Ta "real user ID of the process that sent the signal" +.It Dv SIGPOLL Ta Va si_band Ta "band event for" +.Dv POLL_IN , POLL_OUT , +or +.Dv POLL_MSG +.El +.Pp +Finally, the following code-specific information is available: +.Bl -column ".Dv SI_ASYNCIO" ".Va si_overrun" +.It Sy Code Ta Sy Member Ta Sy Value +.It Dv SI_USER Ta Va si_pid Ta +the process ID that sent the signal +.It Ta Va si_uid Ta +real user ID of the process that sent the signal +.It Dv SI_QUEUE Ta Va si_value Ta +the value passed to +.Xr sigqueue 2 +system call +.It Ta Va si_pid Ta +the process ID that sent the signal +.It Ta Va si_uid Ta +real user ID of the process that sent the signal +.It Dv SI_TIMER Ta Va si_value Ta +the value passed to +.Xr timer_create 2 +system call +.It Ta Va si_timerid Ta +the timer ID returned by +.Xr timer_create 2 +system call +.It Ta Va si_overrun Ta +timer overrun count corresponding to the signal +.It Ta Va si_errno Ta +If timer overrun will be +.Brq Dv DELAYTIMER_MAX , +an error code defined in +.In errno.h +is set +.It Dv SI_ASYNCIO Ta Va si_value Ta +the value passed to aio system calls +.It Dv SI_MESGQ Ta Va si_value Ta +the value passed to +.Xr mq_notify 2 +system call +.It Ta Va si_mqd Ta +the ID of the message queue which generated the signal +.It Dv SI_LWP Ta Va si_pid Ta +the process ID that sent the signal +.It Ta Va si_uid Ta +real user ID of the process that sent the signal +.El +.Sh NOTES +Currently, the kernel never generates the +.Dv SIGPOLL +signal. +.Dv SIGCHLD +signal is queued when a process changed its status or exited. +.Tn POSIX +Realtime Extensions like aio, timer, and message queue also queue +signals. +Signals with code +.Dv SI_USER , +.Dv SI_KERNEL +or +.Dv SI_LWP +are only queued if there are sufficient resources; +otherwise, +.Dv SI_NOINFO +results. +For some hardware architectures, the exact value of +.Va si_addr +might not be available. +.Sh SEE ALSO +.Xr aio_read 2 , +.Xr kill 2 , +.Xr mq_notify 2 , +.Xr sigaction 2 , +.Xr sigqueue 2 , +.Xr sigwaitinfo 2 , +.Xr timer_create 2 , +.Xr timer_settime 2 , +.Xr waitpid 2 , +.Xr pthread_kill 3 +.Sh STANDARDS +The +.Vt siginfo_t +type conforms to +.St -p1003.1-2004 . +.Sh HISTORY +Full support for +.Tn POSIX +signal information first appeared in +.Fx 7.0 . +The codes +.Dv SI_USER +and +.Dv SI_KERNEL +can be generated as of +.Fx 8.1 . +The code +.Dv SI_LWP +can be generated as of +.Fx 9.0 . +.Sh AUTHORS +This manual page was written by +.An David Xu Aq Mt davidxu@FreeBSD.org . diff --git a/static/freebsd/man3/snl.3 b/static/freebsd/man3/snl.3 new file mode 100644 index 00000000..04bae466 --- /dev/null +++ b/static/freebsd/man3/snl.3 @@ -0,0 +1,309 @@ +.\" +.\" Copyright (C) 2022 Alexander Chernikov . +.\" +.\" 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 December 16, 2022 +.Dt SNL 3 +.Os +.Sh NAME +.Nm snl_init , +.Nm snl_free , +.Nm snl_read_message , +.Nm snl_send , +.Nm snl_get_seq , +.Nm snl_allocz , +.Nm snl_clear_lb , +.Nm snl_parse_nlmsg , +.Nm snl_parse_header , +.Nm snl_parse_attrs , +.Nm snl_parse_attrs_raw , +.Nm snl_attr_get_flag , +.Nm snl_attr_get_ip , +.Nm snl_attr_get_uint16 , +.Nm snl_attr_get_uint32 , +.Nm snl_attr_get_string , +.Nm snl_attr_get_stringn , +.Nm snl_attr_get_nla , +.Nm snl_field_get_uint8 , +.Nm snl_field_get_uint16 , +.Nm snl_field_get_uint32 +.Nd "simple netlink library" +.Sh SYNOPSIS +.In netlink/netlink_snl.h +.In netlink/netlink_snl_route.h +.Ft "bool" +.Fn snl_init "struct snl_state *ss" "int netlink_family" +.Fn snl_free "struct snl_state *ss" +.Ft "struct nlmsghdr *" +.Fn snl_read_message "struct snl_state *ss" +.Ft "bool" +.Fn snl_send "struct snl_state *ss" "void *data" "int sz" +.Ft "uint32_t" +.Fn snl_get_seq "struct snl_state *ss" +.Ft "void *" +.Fn snl_allocz "struct snl_state *ss" "int len" +.Fn snl_clear_lb "struct snl_state *ss" +.Ft "bool" +.Fn snl_parse_nlmsg "struct snl_state *ss" "struct nlmsghdr *hdr" "const struct snl_hdr_parser *ps" "void *target" +.Ft "bool" +.Fn snl_parse_header "struct snl_state *ss" "void *hdr" "int len" "const struct snl_hdr_parser *ps" "int pslen" "void *target" +.Ft "bool" +.Fn snl_parse_attrs "struct snl_state *ss" "struct nlmsghdr *hdr" "int hdrlen" "const struct snl_attr_parser *ps" "int pslen" "void *target" +.Ft "bool" +.Fn snl_parse_attrs_raw "struct snl_state *ss" "struct nlattr *nla_head" "int len" "const struct snl_attr_parser *ps" "int pslen" "void *target" +.Ft "bool" +.Fn snl_attr_get_flag "struct snl_state *ss" "struct nlattr *nla" "void *target" +.Ft "bool" +.Fn snl_attr_get_uint8 "struct snl_state *ss" "struct nlattr *nla" "void *target" +.Ft "bool" +.Fn snl_attr_get_uint16 "struct snl_state *ss" "struct nlattr *nla" "void *target" +.Ft "bool" +.Fn snl_attr_get_uint32 "struct snl_state *ss" "struct nlattr *nla" "void *target" +.Ft "bool" +.Fn snl_attr_get_uint64 "struct snl_state *ss" "struct nlattr *nla" "void *target" +.Ft "bool" +.Fn snl_attr_get_string "struct snl_state *ss" "struct nlattr *nla" "void *target" +.Ft "bool" +.Fn snl_attr_get_stringn "struct snl_state *ss" "struct nlattr *nla" "void *target" +.Ft "bool" +.Fn snl_attr_get_nla "struct snl_state *ss" "struct nlattr *nla" "void *target" +.Ft "bool" +.Fn snl_attr_get_ip "struct snl_state *ss" "struct nlattr *nla" "void *target" +.Ft "bool" +.Fn snl_attr_get_ipvia "struct snl_state *ss" "struct nlattr *nla" "void *target" +.Sh DESCRIPTION +The +.Xr snl 3 +library provides an easy way of sending and receiving Netlink messages, +taking care of serialisation and deserialisation. +.Ss INITIALISATION +Call +.Fn snl_init +with a pointer to the +.Dv struct snl_state +and the desired Netlink family to initialise the library instance. +To free the library instance, call +.Fn snl_free . +.Pp +The library functions are NOT multithread-safe. +If multithreading is desired, consider initializing an instance +per thread. +.Ss MEMORY ALLOCATION +The library uses pre-allocated extendable memory buffers to handle message parsing. +The typical usage pattern is to allocate the necessary data structures during the +message parsing or writing process via +.Fn snl_allocz +and free all allocated data at once using +.Fn snl_clear_lb +after handling the message. +.Ss COMPOSING AND SENDING MESSAGES +The library does not currently offer any wrappers for writing netlink messages. +Simple request messages can be composed by filling in all needed fields directly. +Example for constructing an interface dump request: +.Bd -literal + struct { + struct nlmsghdr hdr; + struct ifinfomsg ifmsg; + } msg = { + .hdr.nlmsg_type = RTM_GETLINK, + .hdr.nlmsg_flags = NLM_F_DUMP | NLM_F_REQUEST, + .hdr.nlmsg_seq = snl_get_seq(ss), + }; + msg.hdr.nlmsg_len = sizeof(msg); +.Ed +.Fn snl_get_seq +can be used to generate a unique message number. +To send the resulting message, +.Fn snl_send +can be used. +.Ss RECEIVING AND PARSING MESSAGES +To receive a message, use +.Fn snl_read_message . +Currently, this call is blocking. +.Pp +The library provides an easy way to convert the message to the pre-defined C +structure. +For each message type, one needs to define rules, converting the protocol header +fields and the desired attributes to the specified structure. +It can be accomplished by using message parsers. +Each message parser consists of an array of attribute getters and an array of +header field getters. +The former array needs to be sorted by the attribute type. +There is a +.Fn SNL_VERIFY_PARSERS +macro to check if the order is correct. +.Fn SNL_DECLARE_PARSER "parser_name" "family header type" "struct snl_field_parser[]" "struct snl_attr_parser[]" +can be used to create a new parser. +.Fn SNL_DECLARE_ATTR_PARSER "parser_name" "struct snl_field_parser[]" +can be used to create an attribute-only message parser. +.Pp +Each attribute getter needs to be embedded in the following structure: +.Bd -literal +typedef bool snl_parse_attr_f(struct snl_state *ss, struct nlattr *attr, const void *arg, void *target); +struct snl_attr_parser { + uint16_t type; /* Attribute type */ + uint16_t off; /* field offset in the target structure */ + snl_parse_attr_f *cb; /* getter function to call */ + const void *arg; /* getter function custom argument */ +}; +.Ed +The generic attribute getter has the following signature: +.Ft "bool" +.Fn snl_attr_get_ "struct snl_state *ss" "struct nlattr *nla" "const void *arg" "void *target" . +nla contains the pointer of the attribute to use as the datasource. +The target field is the pointer to the field in the target structure. +It is up to the getter to know the type of the target field. +The getter must check the input attribute and return +false if the attribute is not formed correctly. +Otherwise, the getter fetches the attribute value and stores it in the target, +then returns true. +It is possible to use +.Fn snl_allocz +to create the desired data structure . +A number of predefined getters for the common data types exist. +.Fn snl_attr_get_flag +converts a flag-type attribute to an uint8_t value of 1 or 0, depending on the +attribute presence. +.Fn snl_attr_get_uint8 +stores a uint8_t type attribute into the uint8_t target field. +.Fn snl_attr_get_uint16 +stores a uint16_t type attribute into the uint16_t target field. +.Fn snl_attr_get_uint32 +stores a uint32_t type attribute into the uint32_t target field. +.Fn snl_attr_get_uint64 +stores a uint64_t type attribute into the uint64_t target field. +.Fn snl_attr_get_ip +and +.Fn snl_attr_get_ipvia +stores a pointer to the sockaddr structure with the IPv4/IPv6 address contained +in the attribute. +Sockaddr is allocated using +.Fn snl_allocz . +.Fn snl_attr_get_string +stores a pointer to the NULL-terminated string. +The string itself is allocated using +.Fn snl_allocz . +.Fn snl_attr_get_nla +stores a pointer to the specified attribute. +.Fn snl_attr_get_stringn +stores a pointer to the non-NULL-terminated string. +.Pp +Similarly, each family header getter needs to be embedded in the following structure: +.Bd -literal +typedef void snl_parse_field_f(struct snl_state *ss, void *hdr, void *target); +struct snl_field_parser { + uint16_t off_in; /* field offset in the input structure */ + uint16_t off_out;/* field offset in the target structure */ + snl_parse_field_f *cb; /* getter function to call */ +}; +.Ed +The generic field getter has the following signature: +.Ft "void" +snl_field_get_ "struct snl_state *ss" "void *src" "void *target" . +A number of pre-defined getters for the common data types exist. +.Fn "snl_field_get_uint8" +fetches an uint8_t value and stores it in the target. +.Fn "snl_field_get_uint16" +fetches an uint8_t value and stores it in the target. +.Fn "snl_field_get_uint32" +fetches an uint32_t value and stores it in the target. +.Sh EXAMPLES +The following example demonstrates how to list all system interfaces +using netlink. +.Bd -literal +#include + +#include +#include +#include "netlink/netlink_snl.h" +#include "netlink/netlink_snl_route.h" + +struct nl_parsed_link { + uint32_t ifi_index; + uint32_t ifla_mtu; + char *ifla_ifname; +}; + +#define _IN(_field) offsetof(struct ifinfomsg, _field) +#define _OUT(_field) offsetof(struct nl_parsed_link, _field) +static const struct snl_attr_parser ap_link[] = { + { .type = IFLA_IFNAME, .off = _OUT(ifla_ifname), .cb = snl_attr_get_string }, + { .type = IFLA_MTU, .off = _OUT(ifla_mtu), .cb = snl_attr_get_uint32 }, +}; +static const struct snl_field_parser fp_link[] = { + {.off_in = _IN(ifi_index), .off_out = _OUT(ifi_index), .cb = snl_field_get_uint32 }, +}; +#undef _IN +#undef _OUT +SNL_DECLARE_PARSER(link_parser, struct ifinfomsg, fp_link, ap_link); + + +int +main(int ac, char *argv[]) +{ + struct snl_state ss; + + if (!snl_init(&ss, NETLINK_ROUTE)) + return (1); + + struct { + struct nlmsghdr hdr; + struct ifinfomsg ifmsg; + } msg = { + .hdr.nlmsg_type = RTM_GETLINK, + .hdr.nlmsg_flags = NLM_F_DUMP | NLM_F_REQUEST, + .hdr.nlmsg_seq = snl_get_seq(&ss), + }; + msg.hdr.nlmsg_len = sizeof(msg); + + if (!snl_send(&ss, &msg, sizeof(msg))) { + snl_free(&ss); + return (1); + } + + struct nlmsghdr *hdr; + while ((hdr = snl_read_message(&ss)) != NULL && hdr->nlmsg_type != NLMSG_DONE) { + if (hdr->nlmsg_seq != msg.hdr.nlmsg_seq) + break; + + struct nl_parsed_link link = {}; + if (!snl_parse_nlmsg(&ss, hdr, &link_parser, &link)) + continue; + printf("Link#%u %s mtu %u\en", link.ifi_index, link.ifla_ifname, link.ifla_mtu); + } + + return (0); +} +.Ed +.Sh SEE ALSO +.Xr genetlink 4 , +.Xr netlink 4 , +and +.Xr rtnetlink 4 +.Sh HISTORY +The +.Dv SNL +library appeared in +.Fx 13.2 . +.Sh AUTHORS +This library was implemented by +.An Alexander Chernikov Aq Mt melifaro@FreeBSD.org . diff --git a/static/freebsd/man3/stats.3 b/static/freebsd/man3/stats.3 new file mode 100644 index 00000000..7fe1fa61 --- /dev/null +++ b/static/freebsd/man3/stats.3 @@ -0,0 +1,966 @@ +.\" +.\" Copyright (c) 2016-2018 Netflix, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions, and the following disclaimer, +.\" without modification, immediately at the beginning of the file. +.\" 2. 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 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 December 2, 2019 +.Dt STATS 3 +.Os +.Sh NAME +.Nm stats +.Nd statistics gathering +.Sh LIBRARY +.Lb libstats +.Sh SYNOPSIS +.In sys/arb.h +.In sys/qmath.h +.In sys/stats.h +.Ss Stats Blob Template Management Functions +.Ft int +.Fo stats_tpl_alloc +.Fa "const char *name" +.Fa "uint32_t flags" +.Fc +.Ft int +.Fo stats_tpl_fetch_allocid +.Fa "const char *name" +.Fa "uint32_t hash" +.Fc +.Ft int +.Fo stats_tpl_fetch +.Fa "int tpl_id" +.Fa "struct statsblob_tpl **tpl" +.Fc +.Ft int +.Fo stats_tpl_id2name +.Fa "uint32_t tpl_id" +.Fa "char *buf" +.Fa "size_t len" +.Fc +.Ft int +.Fo stats_tpl_sample_rates +.Fa "SYSCTL_HANDLER_ARGS" +.Fc +.Ft int +.Fo stats_tpl_sample_rollthedice +.Fa "struct stats_tpl_sample_rate *rates" +.Fa "int nrates" +.Fa "void *seed_bytes" +.Fa "size_t seed_len" +.Fc +.Ft struct voistatspec +.Fo STATS_VSS_SUM +.Fc +.Ft struct voistatspec +.Fo STATS_VSS_MAX +.Fc +.Ft struct voistatspec +.Fo STATS_VSS_MIN +.Fc +.Ft struct voistatspec +.Fo STATS_VSS_CRHIST<32|64>_LIN +.Fa "lb" +.Fa "ub" +.Fa "stepinc" +.Fa "vsdflags" +.Fc +.Ft struct voistatspec +.Fo STATS_VSS_CRHIST<32|64>_EXP +.Fa "lb" +.Fa "ub" +.Fa "stepbase" +.Fa "stepexp" +.Fa "vsdflags" +.Fc +.Ft struct voistatspec +.Fo "STATS_VSS_CRHIST<32|64>_LINEXP" +.Fa "lb" +.Fa "ub" +.Fa "nlinsteps" +.Fa "stepbase" +.Fa "vsdflags" +.Fc +.Ft struct voistatspec +.Fo "STATS_VSS_CRHIST<32|64>_USR" +.Fa Sy "HBKTS" Ns Pq Sy "CRBKT" Ns ( Em "lb" ) , "..." , +.Fa "vsdflags" +.Fc +.Ft struct voistatspec +.Fo "STATS_VSS_DRHIST<32|64>_USR" +.Fa Sy "HBKTS" Ns Pq Sy "DRBKT" Ns ( Em "lb" , "ub" ) , "..." , +.Fa "vsdflags" +.Fc +.Ft struct voistatspec +.Fo "STATS_VSS_DVHIST<32|64>_USR" +.Fa Sy "HBKTS" Ns Pq Sy "DVBKT" Ns ( Em "val" ) , "..." , +.Fa "vsdflags" +.Fc +.Ft struct voistatspec +.Fo STATS_VSS_TDGSTCLUST<32|64> +.Fa "nctroids" +.Fa "prec" +.Fc +.Ft int +.Fo stats_tpl_add_voistats +.Fa "uint32_t tpl_id" +.Fa "int32_t voi_id" +.Fa "const char *voi_name" +.Fa "enum vsd_dtype voi_dtype" +.Fa "uint32_t nvss" +.Fa "struct voistatspec *vss" +.Fa "uint32_t flags" +.Fc +.Ss Stats Blob Data Gathering Functions +.Ft int +.Fo stats_voi_update__ +.Fa "struct statsblob *sb" +.Fa "int32_t voi_id" +.Fa " voival" +.Fc +.Ss Stats Blob Utility Functions +.Ft struct statsblob * +.Fo stats_blob_alloc +.Fa "uint32_t tpl_id" +.Fa "uint32_t flags" +.Fc +.Ft int +.Fo stats_blob_init +.Fa "struct statsblob *sb" +.Fa "uint32_t tpl_id" +.Fa "uint32_t flags" +.Fc +.Ft int +.Fo stats_blob_clone +.Fa "struct statsblob **dst" +.Fa "size_t dstmaxsz" +.Fa "struct statsblob *src" +.Fa "uint32_t flags" +.Fc +.Ft void +.Fo stats_blob_destroy +.Fa "struct statsblob *sb" +.Fc +.Ft int +.Fo stats_voistat_fetch_dptr +.Fa "struct statsblob *sb" +.Fa "int32_t voi_id" +.Fa "enum voi_stype stype" +.Fa "enum vsd_dtype *retdtype" +.Fa "struct voistatdata **retvsd" +.Fa "size_t *retvsdsz" +.Fc +.Ft int +.Fo stats_voistat_fetch_ +.Fa "struct statsblob *sb" +.Fa "int32_t voi_id" +.Fa "enum voi_stype stype" +.Fa " *ret" +.Fc +.Ft int +.Fo stats_blob_snapshot +.Fa "struct statsblob **dst" +.Fa "size_t dstmaxsz" +.Fa "struct statsblob *src" +.Fa "uint32_t flags" +.Fc +.Ft int +.Fo stats_blob_tostr +.Fa "struct statsblob *sb" +.Fa "struct sbuf *buf" +.Fa "enum sb_str_fmt fmt" +.Fa "uint32_t flags" +.Fc +.Ft int +.Fo stats_voistatdata_tostr +.Fa "const struct voistatdata *vsd" +.Fa "enum vsd_dtype dtype" +.Fa "enum sb_str_fmt fmt" +.Fa "struct sbuf *buf" +.Fa "int objdump" +.Fc +.Ft typedef int +.Fn "\*(lp*stats_blob_visitcb_t\*(rp" "struct sb_visit *sbv" "void *usrctx" +.Ft int +.Fo stats_blob_visit +.Fa "struct statsblob *sb" +.Fa "stats_blob_visitcb_t func" +.Fa "void *usrctx" +.Fc +.Sh DESCRIPTION +The +.Nm +framework facilitates real-time kernel and user space statistics gathering. +The framework is built around the +.Dq statsblob , +an object embedded within a contiguous memory allocation that is mostly opaque +to consumers and stores all required state. +A +.Dq statsblob +object can itself be embedded within other objects either directly or indirectly +using a pointer. +.Pp +Objects or subsystems for which statistics are to be gathered are initialized +from a template +.Dq statsblob , +which acts as the blueprint for an arbitrary set of +Variables Of Interest (VOIs) and their associated statistics. +Each template defines a schema plus associated metadata, which are kept separate +to minimize the memory footprint of blobs. +.Pp +Data gathering hook functions added at appropriate locations within the code +base of interest feed VOI data into the framework for processing. +.Pp +Each +.Dq statsblob , +consists of a +.Vt struct statsblob +header and opaque internal blob structure per the following diagram: +.Bd -literal -offset indent +--------------------------------------------------------- +| struct | uint8_t | +| statsblob | opaque[] | +--------------------------------------------------------- +.Ed +.Pp +The publicly visible 8-byte header is defined as: +.Bd -literal -offset indent +struct statsblob { + uint8_t abi; + uint8_t endian; + uint16_t flags; + uint16_t maxsz; + uint16_t cursz; + uint8_t opaque[]; +}; +.Ed +.Pp +.Va abi +specifies which API version the blob's +.Va opaque +internals conform to +.Pq Dv STATS_ABI_V1 is the only version currently defined . +.Va endian +specifies the endianness of the blob's fields +.Po +.Dv SB_LE +for little endian, +.Dv SB_BE +for big endian, or +.Dv SB_UE +for unknown endianness +.Pc . +.Va cursz +specifies the size of the blob, while +.Va maxsz +specifies the size of the underlying memory allocation in which the +blob is embedded. +Both +.Va cursz +and +.Va maxsz +default to units of bytes, unless a flag is set in +.Va flags +that dictates otherwise. +.Pp +Templates are constructed by associating arbitrary VOI IDs with a set of +statistics, where each statistic is specified using a +.Vt struct voistatspec +per the definition below: +.Bd -literal -offset indent +struct voistatspec { + vss_hlpr_fn hlpr; + struct vss_hlpr_info *hlprinfo; + struct voistatdata *iv; + size_t vsdsz; + uint32_t flags; + enum vsd_dtype vs_dtype : 8; + enum voi_stype stype : 8; +}; +.Ed +.Pp +It is generally expected that consumers will not work with +.Vt struct voistatspec +directly, and instead use the +.Fn STATS_VSS_* +helper macros. +.Pp +The +.Nm +framework offers the following statistics for association with VOIs: +.Bl -tag -width ".Dv VS_STYPE_TDGST" +.It Dv VS_STYPE_SUM +The sum of VOI values. +.It Dv VS_STYPE_MAX +The maximum VOI value. +.It Dv VS_STYPE_MIN +The minimum VOI value. +.It Dv VS_STYPE_HIST +A static bucket histogram of VOI values, including a count of +.Dq out-of-band/bucket +values which did not match any bucket. +Histograms can be specified as +.Dq Em C Ns ontinuous Em R Ns ange +.Pq CRHIST , +.Dq Em D Ns iscrete Em R Ns ange +.Pq DRHIST +or +.Dq Em D Ns iscrete Em V Ns alue +.Pq DVHIST , +with 32 or 64 bit bucket counters, depending on the VOI semantics. +.It Dv VS_STYPE_TDGST +A dynamic bucket histogram of VOI values based on the t-digest method +.Po refer to the t-digest paper in the +.Sx SEE ALSO +section below +.Pc . +.El +.Pp +A +.Dq visitor software design pattern Ns +-like scheme is employed to facilitate iterating over a blob's data without +concern for the blob's structure. +The data provided to visitor callback functions is encapsulated in +.Vt struct sb_visit +per the definition below: +.Bd -literal -offset indent +struct sb_visit { + struct voistatdata *vs_data; + uint32_t tplhash; + uint32_t flags; + int16_t voi_id; + int16_t vs_dsz; + enum vsd_dtype voi_dtype : 8; + enum vsd_dtype vs_dtype : 8; + int8_t vs_stype; + uint16_t vs_errs; +}; +.Ed +.Pp +The +.Fn stats_tpl_sample_rates +and +.Fn stats_tpl_sample_rollthedice +functions utilize +.Vt struct stats_tpl_sample_rate +to encapsulate per-template sample rate information per the definition below: +.Bd -literal -offset indent +struct stats_tpl_sample_rate { + int32_t tpl_slot_id; + uint32_t tpl_sample_pct; +}; +.Ed +.Pp +The +.Va tpl_slot_id +member holds the template's slot ID obtained from +.Fn stats_tpl_alloc +or +.Fn stats_tpl_fetch_allocid . +The +.Va tpl_sample_pct +member holds the template's sample rate as an integer percentage in the range +[0,100]. +.Pp +The +.Vt stats_tpl_sr_cb_t +conformant function pointer that is required as the +.Fa arg1 +of +.Fn stats_tpl_sample_rates +is defined as: +.Bd -literal -offset indent +enum stats_tpl_sr_cb_action { + TPL_SR_UNLOCKED_GET, + TPL_SR_RLOCKED_GET, + TPL_SR_RUNLOCK, + TPL_SR_PUT +}; +typedef int (*stats_tpl_sr_cb_t)(enum stats_tpl_sr_cb_action action, + struct stats_tpl_sample_rate **rates, int *nrates, void *ctx); +.Ed +.Pp +It is required that a conformant function: +.Bl -dash +.It +Return an appropriate +.Xr errno 2 +on error, otherwise 0. +.It +When called with +.Qq action == TPL_SR_*_GET , +return the subsystem's rates list ptr and count, locked or unlocked as +requested. +.It +When called with +.Qq action == TPL_SR_RUNLOCK , +unlock the subsystem's rates list ptr and count. +Pair with a prior +.Qq action == TPL_SR_RLOCKED_GET +call. +.It +When called with +.Qq action == TPL_SR_PUT , +update the subsystem's rates list ptr and count to the sysctl processed values +and return the inactive list details in +.Fa rates +and +.Fa nrates +for garbage collection by +.Fn stats_tpl_sample_rates . +.El +.Pp +Where templates need to be referenced via textual means, for example via a MIB +variable, the following string based template spec formats can be used: +.Bl -enum +.It +.Qq Ns +: +.Ns , for example +.Qq TCP_DEFAULT Ns +:1731235399 +.It +.Qq +.Ns , for example +.Qq TCP_DEFAULT +.It +: +.Ns , for example +:1731235399 +.El +.Pp +The first form is the normative spec format generated by the framework, while +the second and third forms are convenience formats primarily for user input. +The use of inverted commas around the template name is optional. +.Ss MIB Variables +The in-kernel +.Nm +framework exposes the following framework-specific variables in the +.Va kern.stats +branch of the +.Xr sysctl 3 +MIB. +.Bl -tag -width "templates" +.It templates +Read-only CSV list of registered templates in normative template spec form. +.El +.Ss Template Management Functions +The +.Fn stats_tpl_alloc +function allocates a new template with the specified unique name and returns its +runtime-stable template slot ID for use with other API functions. +The +.Fa flags +argument is currently unused. +.Pp +The +.Fn stats_tpl_fetch_allocid +function returns the runtime-stable template slot ID of any registered template +matching the specified name and hash. +.Pp +The +.Fn stats_tpl_fetch +function returns the pointer to the registered template object at the specified +template slot ID. +.Pp +The +.Fn stats_tpl_id2name +function returns the name of the registered template object at the specified +template slot ID. +.Pp +The +.Fn stats_tpl_sample_rates +function provides a generic handler for template sample rates management and +reporting via +.Xr sysctl 3 +MIB variables. +Subsystems can use this function to create a subsystem-specific +.Xr SYSCTL_PROC 9 +MIB variable that manages and reports subsystem-specific template sampling +rates. +Subsystems must supply a +.Vt stats_tpl_sr_cb_t +conformant function pointer as the sysctl's +.Fa arg1 , +which is a callback used to interact with the subsystem's stats template sample +rates list. +Subsystems can optionally specify the sysctl's +.Fa arg2 +as non-zero, which causes a zero-initialized allocation of arg2-sized contextual +memory to be heap-allocated and passed in to all subsystem callbacks made during +the operation of +.Fn stats_tpl_sample_rates . +.Pp +The +.Fn stats_tpl_sample_rollthedice +function makes a weighted random template selection from the supplied array of +template sampling rates. +The cumulative percentage of all sampling rates should not exceed 100. +If no seed is supplied, a PRNG is used to generate a true random number so that +every selection is independent. +If a seed is supplied, selection will be made randomly across different seeds, but +deterministically given the same seed. +.Pp +The +.Fn stats_tpl_add_voistats +function is used to add a VOI and associated set of statistics to the registered +template object at the specified template slot ID. +The set of statistics is passed as an array of +.Vt struct voistatspec +which can be initialized using the +.Fn STATS_VSS_* +helper macros or manually for non-standard use cases. +For static +.Fa vss +arrays, the +.Fa nvss +count of array elements can be determined by passing +.Fa vss +to the +.Fn NVSS +macro. +The +.Dv SB_VOI_RELUPDATE +flag can be passed to configure the VOI for use with +.Fn stats_voi_update_rel_ , +which entails maintaining an extra 8 bytes of state in the blob at each update. +.Ss Data Gathering Functions +The +.Fn stats_voi_update_abs_ +and +.Fn stats_voi_update_rel_ +functions both update all the statistics associated with the VOI identified by +.Fa voi_id . +The +.Dq abs +call uses +.Fa voival +as an absolute value, whereas the +.Dq rel +call uses +.Fa voival +as a value relative to that of the previous update function call, by adding it +to the previous value and using the result for the update. +Relative updates are only possible for VOIs that were added to the template with +the +.Dv SB_VOI_RELUPDATE +flag specified to +.Fn stats_tpl_add_voistats . +.Ss Utility Functions +The +.Fn stats_blob_alloc +function allocates and initializes a new blob based on the registered template +object at the specified template slot ID. +.Pp +The +.Fn stats_blob_init +function initializes a new blob in an existing memory allocation based on the +registered template object at the specified template slot ID. +.Pp +The +.Fn stats_blob_clone +function duplicates the +.Fa src +blob into +.Fa dst , +leaving only the +.Va maxsz +field of +.Fa dst +untouched. +The +.Dv SB_CLONE_ALLOCDST +flag can be passed to instruct the function to allocate a new blob of +appropriate size into which to clone +.Fa src , +storing the new pointer in +.Fa *dst . +The +.Dv SB_CLONE_USRDSTNOFAULT +or +.Dv SB_CLONE_USRDST +flags can be set to respectively signal that +.Xr copyout_nofault 9 +or +.Xr copyout 9 +should be used because +.Fa *dst +is a user space address. +.Pp +The +.Fn stats_blob_snapshot +function calls +.Fn stats_blob_clone +to obtain a copy of +.Fa src +and then performs any additional functions required to produce a coherent +blob snapshot. +The flags interpreted by +.Fn stats_blob_clone +also apply to +.Fn stats_blob_snapshot . +Additionally, the +.Dv SB_CLONE_RSTSRC +flag can be used to effect a reset of the +.Fa src +blob's statistics after a snapshot is successfully taken. +.Pp +The +.Fn stats_blob_destroy +function destroys a blob previously created with +.Fn stats_blob_alloc , +.Fn stats_blob_clone +or +.Fn stats_blob_snapshot . +.Pp +The +.Fn stats_blob_visit +function allows the caller to iterate over the contents of a blob. +The callback function +.Fa func +is called for every VOI and statistic in the blob, passing a +.Vt struct sb_visit +and the user context argument +.Fa usrctx +to the callback function. +The +.Fa sbv +passed to the callback function may have one or more of the following flags set +in the +.Va flags +struct member to provide useful metadata about the iteration: +.Dv SB_IT_FIRST_CB , +.Dv SB_IT_LAST_CB , +.Dv SB_IT_FIRST_VOI , +.Dv SB_IT_LAST_VOI , +.Dv SB_IT_FIRST_VOISTAT , +.Dv SB_IT_LAST_VOISTAT , +.Dv SB_IT_NULLVOI +and +.Dv SB_IT_NULLVOISTAT . +Returning a non-zero value from the callback function terminates the iteration. +.Pp +The +.Fn stats_blob_tostr +renders a string representation of a blob into the +.Xr sbuf 9 +.Fa buf . +Currently supported render formats are +.Dv SB_STRFMT_FREEFORM +and +.Dv SB_STRFMT_JSON . +The +.Dv SB_TOSTR_OBJDUMP +flag can be passed to render version specific opaque implementation detail for +debugging or string-to-binary blob reconstruction purposes. +The +.Dv SB_TOSTR_META +flag can be passed to render template metadata into the string representation, +using the blob's template hash to lookup the corresponding template. +.Pp +The +.Fn stats_voistatdata_tostr +renders a string representation of an individual statistic's data into the +.Xr sbuf 9 +.Fa buf . +The same render formats supported by the +.Fn stats_blob_tostr +function can be specified, and the +.Fa objdump +boolean has the same meaning as the +.Dv SB_TOSTR_OBJDUMP +flag. +.Pp +The +.Fn stats_voistat_fetch_dptr +function returns an internal blob pointer to the specified +.Fa stype +statistic data for the VOI +.Fa voi_id . +The +.Fn stats_voistat_fetch_ +functions are convenience wrappers around +.Fn stats_voistat_fetch_dptr +to perform the extraction for simple data types. +.Sh IMPLEMENTATION NOTES +The following notes apply to STATS_ABI_V1 format statsblobs. +.Ss Space-Time Complexity +Blobs are laid out as three distinct memory regions following the header: +.Bd -literal -offset indent +------------------------------------------------------ +| struct | struct | struct | struct | +| statsblobv1 | voi [] | voistat [] | voistatdata [] | +------------------------------------------------------ +.Ed +.Pp +Blobs store VOI and statistic blob state +.Po +8 bytes for +.Vt struct voi +and 8 bytes for +.Vt struct voistat +respectively +.Pc +in sparse arrays, using the +.Fa voi_id +and +.Vt enum voi_stype +as array indices. +This allows O(1) access to any voi/voistat pair in the blob, at the expense of +8 bytes of wasted memory per vacant slot for templates which do not specify +contiguously numbered VOIs and/or statistic types. +Data storage for statistics is only allocated for non-vacant slot pairs. +.Pp +To provide a concrete example, a blob with the following specification: +.Bl -dash +.It +Two VOIs; ID 0 and 2; added to the template in that order +.It +VOI 0 is of data type +.Vt int64_t , +is configured with +.Dv SB_VOI_RELUPDATE +to enable support for relative updates using +.Fn stats_voi_update_rel_ , +and has a +.Dv VS_STYPE_MIN +statistic associated with it. +.It +VOI 2 is of data type +.Vt uint32_t +with +.Dv VS_STYPE_SUM +and +.Dv VS_STYPE_MAX +statistics associated with it. +.El +.Pp +would have the following memory layout: +.Bd -literal +-------------------------------------- +| header | struct statsblobv1, 32 bytes +|------------------------------------| +| voi[0] | struct voi, 8 bytes +| voi[1] (vacant) | struct voi, 8 bytes +| voi[2] | struct voi, 8 bytes +|------------------------------------| +| voi[2]voistat[VOISTATE] (vacant) | struct voistat, 8 bytes +| voi[2]voistat[SUM] | struct voistat, 8 bytes +| voi[2]voistat[MAX] | struct voistat, 8 bytes +| voi[0]voistat[VOISTATE] | struct voistat, 8 bytes +| voi[0]voistat[SUM] (vacant) | struct voistat, 8 bytes +| voi[0]voistat[MAX] (vacant) | struct voistat, 8 bytes +| voi[0]voistat[MIN] | struct voistat, 8 bytes +|------------------------------------| +| voi[2]voistat[SUM]voistatdata | struct voistatdata_int32, 4 bytes +| voi[2]voistat[MAX]voistatdata | struct voistatdata_int32, 4 bytes +| voi[0]voistat[VOISTATE]voistatdata | struct voistatdata_numeric, 8 bytes +| voi[0]voistat[MIN]voistatdata | struct voistatdata_int64, 8 bytes +-------------------------------------- + TOTAL 136 bytes +.Ed +.Pp +When rendered to string format using +.Fn stats_blob_tostr , +the +.Dv SB_STRFMT_FREEFORM +.Fa fmt +and the +.Dv SB_TOSTR_OBJDUMP +flag, the rendered output is: +.Bd -literal +struct statsblobv1@0x8016250a0, abi=1, endian=1, maxsz=136, cursz=136, \\ + created=6294158585626144, lastrst=6294158585626144, flags=0x0000, \\ + stats_off=56, statsdata_off=112, tplhash=2994056564 + vois[0]: id=0, name="", flags=0x0001, dtype=INT_S64, voistatmaxid=3, \\ + stats_off=80 + vois[0]stat[0]: stype=VOISTATE, flags=0x0000, dtype=VOISTATE, \\ + dsz=8, data_off=120 + voistatdata: prev=0 + vois[0]stat[1]: stype=-1 + vois[0]stat[2]: stype=-1 + vois[0]stat[3]: stype=MIN, flags=0x0000, dtype=INT_S64, \\ + dsz=8, data_off=128 + voistatdata: 9223372036854775807 + vois[1]: id=-1 + vois[2]: id=2, name="", flags=0x0000, dtype=INT_U32, voistatmaxid=2, \\ + stats_off=56 + vois[2]stat[0]: stype=-1 + vois[2]stat[1]: stype=SUM, flags=0x0000, dtype=INT_U32, dsz=4, \\ + data_off=112 + voistatdata: 0 + vois[2]stat[2]: stype=MAX, flags=0x0000, dtype=INT_U32, dsz=4, \\ + data_off=116 + voistatdata: 0 +.Ed +.Pp +Note: The +.Qq \e +present in the rendered output above indicates a manual line break inserted to +keep the man page within 80 columns and is not part of the actual output. +.Ss Locking +The +.Nm +framework does not provide any concurrency protection at the individual blob +level, instead requiring that consumers guarantee mutual exclusion when calling +API functions that reference a non-template blob. +.Pp +The list of templates is protected with a +.Xr rwlock 9 +in-kernel, and +.Xr pthread 3 +rw lock in user space to support concurrency between template management and +blob initialization operations. +.Sh RETURN VALUES +.Fn stats_tpl_alloc +returns a runtime-stable template slot ID on success, or a negative errno on +failure. +-EINVAL is returned if any problems are detected with the arguments. +-EEXIST is returned if an existing template is registered with the same name. +-ENOMEM is returned if a required memory allocation fails. +.Pp +.Fn stats_tpl_fetch_allocid +returns a runtime-stable template slot ID, or negative errno on failure. +-ESRCH is returned if no registered template matches the specified name and/or +hash. +.Pp +.Fn stats_tpl_fetch +returns 0 on success, or ENOENT if an invalid +.Fa tpl_id +is specified. +.Pp +.Fn stats_tpl_id2name +returns 0 on success, or an errno on failure. +EOVERFLOW is returned if the length of +.Fa buf +specified by +.Fa len +is too short to hold the template's name. +ENOENT is returned if an invalid +.Fa tpl_id +is specified. +.Pp +.Fn stats_tpl_sample_rollthedice +returns a valid template slot id selected from +.Fa rates +or -1 if a NULL selection was made, that is no stats collection this roll. +.Pp +.Fn stats_tpl_add_voistats +return 0 on success, or an errno on failure. +EINVAL is returned if any problems are detected with the arguments. +EFBIG is returned if the resulting blob would have exceeded the maximum size. +EOPNOTSUPP is returned if an attempt is made to add more VOI stats to a +previously configured VOI. +ENOMEM is returned if a required memory allocation fails. +.Pp +.Fn stats_voi_update_abs_ +and +.Fn stats_voi_update_rel_ +return 0 on success, or EINVAL if any problems are detected with the arguments. +.Pp +.Fn stats_blob_init +returns 0 on success, or an errno on failure. +EINVAL is returned if any problems are detected with the arguments. +EOVERFLOW is returned if the template blob's +.Fa cursz +is larger than the +.Fa maxsz +of the blob being initialized. +.Pp +.Fn stats_blob_alloc +returns a pointer to a newly allocated and initialized blob based on the +specified template with slot ID +.Fa tpl_id , +or NULL if the memory allocation failed. +.Pp +.Fn stats_blob_clone +and +.Fn stats_blob_snapshot +return 0 on success, or an errno on failure. +EINVAL is returned if any problems are detected with the arguments. +ENOMEM is returned if the SB_CLONE_ALLOCDST flag was specified and the memory +allocation for +.Fa dst +fails. +EOVERFLOW is returned if the src blob's +.Fa cursz +is larger than the +.Fa maxsz +of the +.Fa dst +blob. +.Pp +.Fn stats_blob_visit +returns 0 on success, or EINVAL if any problems are detected with the arguments. +.Pp +.Fn stats_blob_tostr +and +.Fn stats_voistatdata_tostr +return 0 on success, or an errno on failure. +EINVAL is returned if any problems are detected with the arguments, otherwise +any error returned by +.Fn sbuf_error +for +.Fa buf +is returned. +.Pp +.Fn stats_voistat_fetch_dptr +returns 0 on success, or EINVAL if any problems are detected with the arguments. +.Pp +.Fn stats_voistat_fetch_ +returns 0 on success, or an errno on failure. +EINVAL is returned if any problems are detected with the arguments. +EFTYPE is returned if the requested data type does not match the blob's data +type for the specified +.Fa voi_id +and +.Fa stype . +.Sh SEE ALSO +.Xr errno 2 , +.Xr arb 3 , +.Xr qmath 3 , +.Xr tcp 4 , +.Xr sbuf 9 +.Rs +.%A "Ted Dunning" +.%A "Otmar Ertl" +.%T "Computing Extremely Accurate Quantiles Using t-digests" +.%U "https://github.com/tdunning/t-digest/raw/master/docs/t-digest-paper/histo.pdf" +.Re +.Sh HISTORY +The +.Nm +framework first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +framework and this manual page were written by +.An Lawrence Stewart Aq lstewart@FreeBSD.org +and sponsored by Netflix, Inc. +.Sh CAVEATS +Granularity of timing-dependent network statistics, in particular TCP_RTT, +depends on the +.Dv HZ +timer. +To minimize the measurement error avoid using HZ lower than 1000. diff --git a/static/freebsd/man3/stdarg.3 b/static/freebsd/man3/stdarg.3 new file mode 100644 index 00000000..71409508 --- /dev/null +++ b/static/freebsd/man3/stdarg.3 @@ -0,0 +1,243 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 October 18, 2024 +.Dt STDARG 3 +.Os +.Sh NAME +.Nm stdarg +.Nd variable argument lists +.Sh SYNOPSIS +.In stdarg.h +.Ft void +.Fn va_start "va_list ap" last +.Ft type +.Fn va_arg "va_list ap" type +.Ft void +.Fn va_copy "va_list dest" "va_list src" +.Ft void +.Fn va_end "va_list ap" +.Sh DESCRIPTION +A function may be called with a varying number of arguments of varying +types. +The include file +.In stdarg.h +declares a type +.Pq Em va_list +and defines four macros for stepping +through a list of arguments whose number and types are not known to +the called function. +.Pp +The called function must declare an object of type +.Em va_list +which is used by the macros +.Fn va_start , +.Fn va_arg , +.Fn va_copy , +and +.Fn va_end . +.Pp +The +.Fn va_start +macro initializes +.Fa ap +for subsequent use by +.Fn va_arg , +.Fn va_copy , +and +.Fn va_end , +and must be called first. +.Pp +The parameter +.Fa last +is the name of the last parameter before the variable argument list, +i.e., the last parameter of which the calling function knows the type. +.Pp +Because the address of this parameter is used in the +.Fn va_start +macro, it should not be declared as a register variable, or as a +function or an array type. +.Pp +The +.Fn va_arg +macro expands to an expression that has the type and value of the next +argument in the call. +The parameter +.Fa ap +is the +.Em va_list Fa ap +initialized by +.Fn va_start +or +.Fn va_copy . +Each call to +.Fn va_arg +modifies +.Fa ap +so that the next call returns the next argument. +The parameter +.Fa type +is a type name specified so that the type of a pointer to an +object that has the specified type can be obtained simply by +adding a * +to +.Fa type . +.Pp +If there is no next argument, or if +.Fa type +is not compatible with the type of the actual next argument +(as promoted according to the default argument promotions), +random errors will occur. +.Pp +The first use of the +.Fn va_arg +macro after that of the +.Fn va_start +macro returns the argument after +.Fa last . +Successive invocations return the values of the remaining +arguments. +.Pp +The +.Fn va_copy +macro copies a variable argument list, previously initialized by +.Fn va_start , +from +.Fa src +to +.Fa dest . +The state is preserved such that it is equivalent to calling +.Fn va_start +with the same second argument used with +.Fa src , +and calling +.Fn va_arg +the same number of times as called with +.Fa src . +.Pp +The +.Fn va_end +macro cleans up any state associated with the variable argument list +.Fa ap . +.Pp +Each invocation of +.Fn va_start +or +.Fn va_copy +must be paired with a corresponding invocation of +.Fn va_end +in the same function. +.Sh RETURN VALUES +The +.Fn va_arg +macro returns the value of the next argument. +.Pp +The +.Fn va_start , +.Fn va_copy , +and +.Fn va_end +macros return no value. +.Sh EXAMPLES +The function +.Em foo +takes a string of format characters and prints out the argument +associated with each format character based on the type. +.Bd -literal -offset indent +void foo(char *fmt, ...) +{ + va_list ap; + int d; + char c, *s; + + va_start(ap, fmt); + while (*fmt) + switch(*fmt++) { + case 's': /* string */ + s = va_arg(ap, char *); + printf("string %s\en", s); + break; + case 'd': /* int */ + d = va_arg(ap, int); + printf("int %d\en", d); + break; + case 'c': /* char */ + /* Note: char is promoted to int. */ + c = va_arg(ap, int); + printf("char %c\en", c); + break; + } + va_end(ap); +} +.Ed +.Sh COMPATIBILITY +These macros are +.Em not +compatible with the historic macros they replace. +.Sh STANDARDS +The +.Fn va_start , +.Fn va_arg , +.Fn va_copy , +and +.Fn va_end +macros conform to +.St -isoC-99 . +.Sh HISTORY +The +.Fn va_start , +.Fn va_arg +and +.Fn va_end +macros were introduced in +.St -ansiC . +The +.Fn va_copy +macro was introduced in +.St -isoC-99 . +.Sh BUGS +Unlike the +.Em varargs +macros, the +.Nm +macros do not permit programmers to +code a function with no fixed arguments. +This problem generates work mainly when converting +.Em varargs +code to +.Nm +code, +but it also creates difficulties for variadic functions that +wish to pass all of their arguments on to a function +that takes a +.Em va_list +argument, such as +.Xr vfprintf 3 . diff --git a/static/freebsd/man3/stdbit.3 b/static/freebsd/man3/stdbit.3 new file mode 100644 index 00000000..bdee56cc --- /dev/null +++ b/static/freebsd/man3/stdbit.3 @@ -0,0 +1,120 @@ +.\" +.\" Copyright (c) 2025 Robert Clausecker +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd November 9, 2025 +.Dt STDBIT 3 +.Os +.Sh NAME +.Nm stdbit +.Nd bit and byte utilities +.Sh SYNOPSIS +.Lb libc +.In stdbit.h +.Fd #define __STDC_ENDIAN_LITTLE__ +.Fd #define __STDC_ENDIAN_BIG__ +.Fd #define __STDC_ENDIAN_NATIVE__ +.Ft unsigned int +.Fn stdc_count_leading_zeros "value" +.Ft unsigned int +.Fn stdc_count_leading_ones "value" +.Ft unsigned int +.Fn stdc_count_trailing_zeros "value" +.Ft unsigned int +.Fn stdc_count_trailing_ones "value" +.Ft unsigned int +.Fn stdc_first_leading_zero "value" +.Ft unsigned int +.Fn stdc_first_leading_one "value" +.Ft unsigned int +.Fn stdc_first_trailing_zero "value" +.Ft unsigned int +.Fn stdc_first_trailing_one "value" +.Ft unsigned int +.Fn stdc_count_zeros "value" +.Ft unsigned int +.Fn stdc_count_ones "value" +.Ft bool +.Fn stdc_has_single_bit "value" +.Ft unsigned int +.Fn stdc_bit_width "value" +.Ft typeof Ns Pq Em value +.Fn stdc_bit_floor "value" +.Ft typeof Ns Pq Em value +.Fn stdc_bit_ceil "value" +.Sh DESCRIPTION +The +.Dv __STDC_ENDIAN_NATIVE__ +macro describes the byte order or endianness of the machine for which the +program is built. +If the machine has big-endian byte order, this macro is equal to +.Dv __STDC_ENDIAN_BIG__ . +If the machine has little-endian byte order, this macro is equal to +.Dv __STDC_ENDIAN_LITTLE__ . +Otherwise, the macro has a value that is equal to neither. +.Pp +The bit and byte utility functions analyze the bits within a datum. +Each function +.Em func +is provided in five variants +.Nm stdc_ Ns Em func Ns Em _ Ns Em type Ns Pq Em value +where +.Fa value +is of type +.Va unsigned char , +.Va unsigned short , +.Va unsigned int , +.Va unsigned long , +or +.Va unsigned long long +for +.Em type +being +.Sy uc , +.Sy us , +.Sy ui , +.Sy ul , +or +.Sy ull +respectively. +Additionally, for each +.Em func , +a type-generic macro +.Nm stdc_ Ns Em func Ns Pq Em value +that picks the appropriate function +.Nm stdc_ Ns Em func Ns Em _ Ns Em type Ns Pq Em value +based on the type of +.Fa value +is provided. +.Sh SEE ALSO +.Xr arch 7 , +.Xr bitstring 3 , +.Xr ffs 3 , +.Xr fls 3 , +.Xr stdc_count_leading_zeros 3 , +.Xr stdc_count_leading_ones 3 , +.Xr stdc_count_trailing_zeros 3 , +.Xr stdc_count_trailing_ones 3 , +.Xr stdc_first_leading_zero 3 , +.Xr stdc_first_leading_one 3 , +.Xr stdc_first_trailing_zero 3 , +.Xr stdc_first_trailing_one 3 , +.Xr stdc_count_zeros 3 , +.Xr stdc_count_ones 3 , +.Xr stdc_has_single_bit 3 , +.Xr stdc_bit_width 3 , +.Xr stdc_bit_floor 3 , +.Xr stdc_bit_ceil 3 +.Sh STANDARDS +The macros and functions of the +.In stdbit.h +header conform to +.St -isoC-2023 . +.Sh HISTORY +The +.In stdbit.h +header and the macros and functions defined therein where added in +.Fx 15.1. +.Sh AUTHOR +.An Robert Clausecker Aq Mt fuz@FreeBSD.org diff --git a/static/freebsd/man3/stdckdint.3 b/static/freebsd/man3/stdckdint.3 new file mode 100644 index 00000000..4f12b4a8 --- /dev/null +++ b/static/freebsd/man3/stdckdint.3 @@ -0,0 +1,106 @@ +.\"- +.\" Copyright (c) 2023 Dag-Erling Smørgrav +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd September 5, 2023 +.Dt STDCKDINT 3 +.Os +.Sh NAME +.Nm stdckdint +.Nd checked integer arithmetic +.Sh SYNOPSIS +.In stdckdint.h +.Ft bool +.Fn ckd_add "type1 *result" "type2 a" "type3 b" +.Ft bool +.Fn ckd_sub "type1 *result" "type2 a" "type3 b" +.Ft bool +.Fn ckd_mul "type1 *result" "type2 a" "type3 b" +.Sh DESCRIPTION +The function-like macros +.Nm ckd_add , +.Nm ckd_sub , +and +.Nm ckd_mul +perform checked integer addition, subtraction, and multiplication, +respectively. +If the result of adding, subtracting, or multiplying +.Fa a +and +.Fa b +as if their respective types had infinite range fits in +.Ft type1 , +it is stored in the location pointed to by +.Fa result +and the macro evaluates to +.Dv false . +Otherwise, the macro evaluates to +.Dv true +and the contents of the location pointed to by +.Fa result +is the result of the operation wrapped to the range of +.Ft type1 . +.Sh RETURN VALUES +The +.Nm ckd_add , +.Nm ckd_sub , +and +.Nm ckd_mul +macros evaluate to +.Dv true +if the requested operation overflowed the result type and +.Dv false +otherwise. +.Sh EXAMPLES +.Bd -literal -offset indent +#include +#include +#include + +int main(void) +{ + int result; + + assert(!ckd_add(&result, INT_MAX, 0)); + assert(result == INT_MAX); + assert(ckd_add(&result, INT_MAX, 1)); + assert(result == INT_MIN); + + assert(!ckd_sub(&result, INT_MIN, 0)); + assert(result == INT_MIN); + assert(ckd_sub(&result, INT_MIN, 1)); + assert(result == INT_MAX); + + assert(!ckd_mul(&result, INT_MAX / 2, 2)); + assert(result == INT_MAX - 1); + assert(ckd_mul(&result, INT_MAX / 2 + 1, 2)); + assert(result == INT_MIN); + + return 0; +} +.Ed +.\" .Sh STANDARDS +.\" The +.\" .Nm ckd_add , +.\" .Nm ckd_sub , +.\" and +.\" .Nm ckd_mul +.\" macros conform to +.\" .St -isoC-2023 . +.Sh HISTORY +The +.Nm ckd_add , +.Nm ckd_sub , +and +.Nm ckd_mul +macros were first introduced in +.Fx 14.0 . +.Sh AUTHORS +The +.Nm ckd_add , +.Nm ckd_sub , +and +.Nm ckd_mul +macros and this manual page were written by +.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . diff --git a/static/freebsd/man3/sysexits.3 b/static/freebsd/man3/sysexits.3 new file mode 100644 index 00000000..62f79b28 --- /dev/null +++ b/static/freebsd/man3/sysexits.3 @@ -0,0 +1,135 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 1996 Joerg Wunsch. 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 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 May 9, 2024 +.Dt SYSEXITS 3 +.Os +.Sh NAME +.Nm sysexits +.Nd legacy exit status codes for system programs +.Sh SYNOPSIS +.In sysexits.h +.Sh DESCRIPTION +Some commands attempt to describe the nature of a failure condition +by using these pre-defined exit codes. +This interface has been deprecated and is retained only for compatibility. +Its use is discouraged. +.Sh ERRORS +The successful exit is always indicated by a status of 0, or +.Sy EX_OK . +Error numbers begin at +.Sy EX__BASE +to reduce the possibility of clashing with other exit statuses that +random programs may already return. +The meaning of the codes is +approximately as follows: +.Bl -tag -width "EX_UNAVAILABLEXX(XX)" +.It Sy EX_USAGE Pq 64 +The command was used incorrectly, e.g., with the wrong number of +arguments, a bad flag, a bad syntax in a parameter, or whatever. +.It Sy EX_DATAERR Pq 65 +The input data was incorrect in some way. +This should only be used +for user's data and not system files. +.It Sy EX_NOINPUT Pq 66 +An input file (not a system file) did not exist or was not readable. +This could also include errors like +.Dq \&No message +to a mailer (if it cared to catch it). +.It Sy EX_NOUSER Pq 67 +The user specified did not exist. +This might be used for mail +addresses or remote logins. +.It Sy EX_NOHOST Pq 68 +The host specified did not exist. +This is used in mail addresses or +network requests. +.It Sy EX_UNAVAILABLE Pq 69 +A service is unavailable. +This can occur if a support program or file +does not exist. +This can also be used as a catchall message when +something you wanted to do does not work, but you do not know why. +.It Sy EX_SOFTWARE Pq 70 +An internal software error has been detected. +This should be limited +to non-operating system related errors as possible. +.It Sy EX_OSERR Pq 71 +An operating system error has been detected. +This is intended to be +used for such things as +.Dq cannot fork , +.Dq cannot create pipe , +or the like. +It includes things like getuid returning a user that +does not exist in the passwd file. +.It Sy EX_OSFILE Pq 72 +Some system file (e.g., +.Pa /etc/passwd , +.Pa /var/run/utx.active , +etc.) does not exist, cannot be opened, or has some sort of error +(e.g., syntax error). +.It Sy EX_CANTCREAT Pq 73 +A (user specified) output file cannot be created. +.It Sy EX_IOERR Pq 74 +An error occurred while doing I/O on some file. +.It Sy EX_TEMPFAIL Pq 75 +Temporary failure, indicating something that is not really an error. +In sendmail, this means that a mailer (e.g.) could not create a +connection, and the request should be reattempted later. +.It Sy EX_PROTOCOL Pq 76 +The remote system returned something that was +.Dq not possible +during a protocol exchange. +.It Sy EX_NOPERM Pq 77 +You did not have sufficient permission to perform the operation. +This is not intended for file system problems, which should use +.Sy EX_NOINPUT +or +.Sy EX_CANTCREAT , +but rather for higher level permissions. +.It Sy EX_CONFIG Pq 78 +Something was found in an unconfigured or misconfigured state. +.El +.Pp +The numerical values corresponding to the symbolical ones are given in +parenthesis for easy reference. +.Sh SEE ALSO +.Xr err 3 , +.Xr exit 3 , +.Xr style 9 +.Sh HISTORY +The +.Nm +file first appeared in +.Bx 4 . +.Sh AUTHORS +This manual page was written by +.An J\(:org Wunsch . +.Sh BUGS +.Bl -tag -width 0 -compact +.It This interface is not portable. +.It The choice of an appropriate exit value is often ambiguous. +.El diff --git a/static/freebsd/man3/tgmath.3 b/static/freebsd/man3/tgmath.3 new file mode 100644 index 00000000..98dbb743 --- /dev/null +++ b/static/freebsd/man3/tgmath.3 @@ -0,0 +1,160 @@ +.\" Copyright (c) 2004 Stefan Farfeleder +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 4, 2012 +.Dt TGMATH 3 +.Os +.Sh NAME +.Nm tgmath +.Nd "type-generic macros" +.Sh SYNOPSIS +.In tgmath.h +.Sh DESCRIPTION +The header +.In tgmath.h +provides type-generic macros +for +.In math.h +and +.In complex.h +functions that have +.Vt float +(suffixed with +.Sy f ) , +.Vt double +and +.Vt "long double" +(suffixed with +.Sy l ) +versions. +The arguments that vary across the three functions and have type +.Vt float , double +and +.Vt "long double" , +respectively, are called +.Em "generic arguments" . +.Pp +The following rules describe which function is actually called if a +type-generic macro is invoked. +If any generic argument has type +.Vt "long double" +or +.Vt "long double complex" , +the +.Vt "long double" +function is called. +Else, if any generic argument has type +.Vt double , "double complex" +or an integer type, the +.Vt double +version is invoked. +Otherwise, the macro expands to the +.Vt float +implementation. +.Pp +For the macros in the following table, both real and complex functions +exist. +The real functions are prototyped in +.In math.h +and the complex equivalents in +.In complex.h . +The complex function is called if any of the generic arguments is a +complex value. +Otherwise, the real equivalent is called. +.Bl -column -offset indent ".Fn acosh" "Sy real function" ".Sy complex function" +.It Sy Macro Ta Sy real function Ta Sy complex function +.It Fn acos Ta Fn acos Ta Fn cacos +.It Fn asin Ta Fn asin Ta Fn casin +.It Fn atan Ta Fn atan Ta Fn catan +.It Fn acosh Ta Fn acosh Ta Fn cacosh +.It Fn asinh Ta Fn asinh Ta Fn casinh +.It Fn atanh Ta Fn atanh Ta Fn catanh +.It Fn cos Ta Fn cos Ta Fn ccos +.It Fn sin Ta Fn sin Ta Fn csin +.It Fn tan Ta Fn tan Ta Fn ctan +.It Fn cosh Ta Fn cosh Ta Fn ccosh +.It Fn sinh Ta Fn sinh Ta Fn csinh +.It Fn tanh Ta Fn tanh Ta Fn ctanh +.It Fn exp Ta Fn exp Ta Fn cexp +.It Fn log Ta Fn log Ta Fn clog +.It Fn pow Ta Fn pow Ta Fn cpow +.It Fn sqrt Ta Fn sqrt Ta Fn csqrt +.It Fn fabs Ta Fn fabs Ta Fn cabs +.El +.Pp +No complex functions exist for the following macros, so passing a +complex value to a generic argument invokes undefined behaviour: +.Bl -column -offset indent ".Fn nexttoward" ".Fn nexttoward" ".Fn nexttoward" ".Fn nexttoward" +.It Fn atan2 Ta Fn fma Ta Fn llround Ta Fn remainder +.It Fn cbrt Ta Fn fmax Ta Fn log10 Ta Fn remquo +.It Fn ceil Ta Fn fmin Ta Fn log1p Ta Fn rint +.It Fn copysign Ta Fn fmod Ta Fn log2 Ta Fn round +.It Fn erf Ta Fn frexp Ta Fn logb Ta Fn scalbn +.It Fn erfc Ta Fn hypot Ta Fn lrint Ta Fn scalbln +.It Fn exp2 Ta Fn ilogb Ta Fn lround Ta Fn tgamma +.It Fn expm1 Ta Fn ldexp Ta Fn nearbyint Ta Fn trunc +.It Fn fdim Ta Fn lgamma Ta Fn nextafter Ta \& +.It Fn floor Ta Fn llrint Ta Fn nexttoward Ta \& +.El +.Pp +The following macros always expand to a complex function: +.Bl -column -offset indent ".Fn cimag" ".Fn cimag" ".Fn cimag" ".Fn cimag" ".Fn cimag" +.It Fn carg Ta Fn cimag Ta Fn conj Ta Fn cproj Ta Fn creal +.El +.Pp +This header includes +.In complex.h +and +.In math.h . +.Sh STANDARDS +The header +.In tgmath.h +conforms to +.St -isoC-99 . +.Sh HISTORY +The header +.In tgmath.h +first appeared in +.Fx 5.3 . +.Sh COMPILER SUPPORT +Before +.St -isoC-2011 , +the header +.In tgmath.h +could not be implemented with strictly conforming C code and needed +special compiler support. +As of +.St -isoC-2011 , +this header file can be implemented using the +.Fn _Generic +language keyword. +In addition to compilers that support this keyword, this header file +works with GCC. +.Sh BUGS +Many of the functions mentioned here are not prototyped in +.In math.h +or +.In complex.h +as they are not yet implemented. +This prevents the corresponding type-generic macro from working at all. diff --git a/static/freebsd/man3/timeradd.3 b/static/freebsd/man3/timeradd.3 new file mode 100644 index 00000000..97202678 --- /dev/null +++ b/static/freebsd/man3/timeradd.3 @@ -0,0 +1,164 @@ +.\" Copyright (c) 1999 Kelly Yancey +.\" 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. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 REGENTS 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 30, 2018 +.Dt TIMERADD 3 +.Os +.Sh NAME +.Nm timeradd , +.Nm timersub , +.Nm timerclear , +.Nm timerisset , +.Nm timercmp , +.Nm timespecadd , +.Nm timespecsub , +.Nm timespecclear , +.Nm timespecisset , +.Nm timespeccmp +.Nd operations on timevals and timespecs +.Sh SYNOPSIS +.In sys/time.h +.Ft void +.Fn timeradd "struct timeval *a" "struct timeval *b" "struct timeval *res" +.Ft void +.Fn timersub "struct timeval *a" "struct timeval *b" "struct timeval *res" +.Ft void +.Fn timerclear "struct timeval *tvp" +.Ft int +.Fn timerisset "struct timeval *tvp" +.Ft int +.Fn timercmp "struct timeval *a" "struct timeval *b" CMP +.Ft void +.Fn timespecadd "struct timespec *a" "struct timespec *b" "struct timespec *res" +.Ft void +.Fn timespecsub "struct timespec *a" "struct timespec *b" "struct timespec *res" +.Ft void +.Fn timespecclear "struct timespec *ts" +.Ft int +.Fn timespecisset "struct timespec *ts" +.Ft int +.Fn timespeccmp "struct timespec *a" "struct timespec *b" CMP +.Sh DESCRIPTION +These macros are provided for manipulating +.Fa timeval +and +.Fa timespec +structures for use with the +.Xr clock_gettime 2 , +.Xr clock_settime 2 , +.Xr gettimeofday 2 +and +.Xr settimeofday 2 +calls. +The +.Fa timeval +structure is defined in +.In sys/time.h +as: +.Bd -literal +struct timeval { + long tv_sec; /* seconds since Jan. 1, 1970 */ + long tv_usec; /* and microseconds */ +}; +.Ed +.Pp +And the +.Fa timespec +structure is defined in +.In time.h +as: +.Bd -literal +struct timespec { + time_t tv_sec; /* seconds */ + long tv_nsec; /* and nanoseconds */ +}; +.Ed +.Pp +.Fn timeradd +and +.Fn timespecadd +add the time information stored in +.Fa a +to +.Fa b +and store the result in +.Fa res . +The results are simplified such that the value of +.Fa res->tv_usec +or +.Fa res->tv_nsec +is always less than 1 second. +.Pp +.Fn timersub +and +.Fn timespecsub +subtract the time information stored in +.Fa b +from +.Fa a +and store the result +in +.Fa res . +.Pp +.Fn timerclear +and +.Fn timespecclear +initialize their argument to midnight (0 hour) January 1st, 1970 (the Epoch). +.Pp +.Fn timerisset +and +.Fn timespecisset +return true if their argument is set to any time value other than the Epoch. +.Pp +.Fn timercmp +and +.Fn timespeccmp +compare +.Fa a +to +.Fa b +using the comparison operator given in +.Fa CMP , +and return the result of that comparison. +.Sh SEE ALSO +.Xr clock_gettime 2 , +.Xr gettimeofday 2 +.Sh HISTORY +The +.Fn timeradd +family of macros were imported from +.Nx 1.1 , +and appeared in +.Fx 2.2.6 . +The +.Fn timespecadd +family of macros were imported from +.Nx 1.3 +into +.Fx 3.0 , +though they were not exposed to userland until +.Fx 12.0 . diff --git a/static/freebsd/man3/tree.3 b/static/freebsd/man3/tree.3 new file mode 100644 index 00000000..83d005a5 --- /dev/null +++ b/static/freebsd/man3/tree.3 @@ -0,0 +1,816 @@ +.\" $OpenBSD: tree.3,v 1.7 2002/06/12 01:09:20 provos Exp $ +.\" +.\" Copyright 2002 Niels Provos +.\" 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 Niels Provos. +.\" 4. 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 August 2, 2024 +.Dt TREE 3 +.Os +.Sh NAME +.Nm SPLAY_PROTOTYPE , +.Nm SPLAY_GENERATE , +.Nm SPLAY_ENTRY , +.Nm SPLAY_HEAD , +.Nm SPLAY_INITIALIZER , +.Nm SPLAY_ROOT , +.Nm SPLAY_EMPTY , +.Nm SPLAY_NEXT , +.Nm SPLAY_MIN , +.Nm SPLAY_MAX , +.Nm SPLAY_FIND , +.Nm SPLAY_LEFT , +.Nm SPLAY_RIGHT , +.Nm SPLAY_FOREACH , +.Nm SPLAY_INIT , +.Nm SPLAY_INSERT , +.Nm SPLAY_REMOVE , +.Nm RB_PROTOTYPE , +.Nm RB_PROTOTYPE_STATIC , +.Nm RB_PROTOTYPE_INSERT , +.Nm RB_PROTOTYPE_INSERT_COLOR , +.Nm RB_PROTOTYPE_REMOVE , +.Nm RB_PROTOTYPE_REMOVE_COLOR , +.Nm RB_PROTOTYPE_FIND , +.Nm RB_PROTOTYPE_NFIND , +.Nm RB_PROTOTYPE_NEXT , +.Nm RB_PROTOTYPE_PREV , +.Nm RB_PROTOTYPE_MINMAX , +.Nm RB_PROTOTYPE_REINSERT , +.Nm RB_GENERATE , +.Nm RB_GENERATE_STATIC , +.Nm RB_GENERATE_INSERT , +.Nm RB_GENERATE_INSERT_COLOR , +.Nm RB_GENERATE_REMOVE , +.Nm RB_GENERATE_REMOVE_COLOR , +.Nm RB_GENERATE_FIND , +.Nm RB_GENERATE_NFIND , +.Nm RB_GENERATE_NEXT , +.Nm RB_GENERATE_PREV , +.Nm RB_GENERATE_MINMAX , +.Nm RB_GENERATE_REINSERT , +.Nm RB_ENTRY , +.Nm RB_HEAD , +.Nm RB_INITIALIZER , +.Nm RB_ROOT , +.Nm RB_EMPTY , +.Nm RB_NEXT , +.Nm RB_PREV , +.Nm RB_MIN , +.Nm RB_MAX , +.Nm RB_FIND , +.Nm RB_NFIND , +.Nm RB_LEFT , +.Nm RB_RIGHT , +.Nm RB_PARENT , +.Nm RB_FOREACH , +.Nm RB_FOREACH_FROM , +.Nm RB_FOREACH_SAFE , +.Nm RB_FOREACH_REVERSE , +.Nm RB_FOREACH_REVERSE_FROM , +.Nm RB_FOREACH_REVERSE_SAFE , +.Nm RB_INIT , +.Nm RB_INSERT , +.Nm RB_INSERT_NEXT , +.Nm RB_INSERT_PREV , +.Nm RB_REMOVE , +.Nm RB_REINSERT , +.Nm RB_AUGMENT +.Nm RB_AUGMENT_CHECK, +.Nm RB_UPDATE_AUGMENT +.Nd "implementations of splay and rank-balanced (wavl) trees" +.Sh SYNOPSIS +.In sys/tree.h +.Fn SPLAY_PROTOTYPE NAME TYPE FIELD CMP +.Fn SPLAY_GENERATE NAME TYPE FIELD CMP +.Fn SPLAY_ENTRY TYPE +.Fn SPLAY_HEAD HEADNAME TYPE +.Ft "struct TYPE *" +.Fn SPLAY_INITIALIZER "SPLAY_HEAD *head" +.Fn SPLAY_ROOT "SPLAY_HEAD *head" +.Ft bool +.Fn SPLAY_EMPTY "SPLAY_HEAD *head" +.Ft "struct TYPE *" +.Fn SPLAY_NEXT NAME "SPLAY_HEAD *head" "struct TYPE *elm" +.Ft "struct TYPE *" +.Fn SPLAY_MIN NAME "SPLAY_HEAD *head" +.Ft "struct TYPE *" +.Fn SPLAY_MAX NAME "SPLAY_HEAD *head" +.Ft "struct TYPE *" +.Fn SPLAY_FIND NAME "SPLAY_HEAD *head" "struct TYPE *elm" +.Ft "struct TYPE *" +.Fn SPLAY_LEFT "struct TYPE *elm" "SPLAY_ENTRY NAME" +.Ft "struct TYPE *" +.Fn SPLAY_RIGHT "struct TYPE *elm" "SPLAY_ENTRY NAME" +.Fn SPLAY_FOREACH VARNAME NAME "SPLAY_HEAD *head" +.Ft void +.Fn SPLAY_INIT "SPLAY_HEAD *head" +.Ft "struct TYPE *" +.Fn SPLAY_INSERT NAME "SPLAY_HEAD *head" "struct TYPE *elm" +.Ft "struct TYPE *" +.Fn SPLAY_REMOVE NAME "SPLAY_HEAD *head" "struct TYPE *elm" +.Fn RB_PROTOTYPE NAME TYPE FIELD CMP +.Fn RB_PROTOTYPE_STATIC NAME TYPE FIELD CMP +.Fn RB_PROTOTYPE_INSERT NAME TYPE ATTR +.Fn RB_PROTOTYPE_INSERT_COLOR NAME TYPE ATTR +.Fn RB_PROTOTYPE_REMOVE NAME TYPE ATTR +.Fn RB_PROTOTYPE_REMOVE_COLOR NAME TYPE ATTR +.Fn RB_PROTOTYPE_FIND NAME TYPE ATTR +.Fn RB_PROTOTYPE_NFIND NAME TYPE ATTR +.Fn RB_PROTOTYPE_NEXT NAME TYPE ATTR +.Fn RB_PROTOTYPE_PREV NAME TYPE ATTR +.Fn RB_PROTOTYPE_MINMAX NAME TYPE ATTR +.Fn RB_PROTOTYPE_REINSERT NAME TYPE ATTR +.Fn RB_GENERATE NAME TYPE FIELD CMP +.Fn RB_GENERATE_STATIC NAME TYPE FIELD CMP +.Fn RB_GENERATE_INSERT NAME TYPE FIELD CMP ATTR +.Fn RB_GENERATE_INSERT_COLOR NAME TYPE FIELD ATTR +.Fn RB_GENERATE_REMOVE NAME TYPE FIELD ATTR +.Fn RB_GENERATE_REMOVE_COLOR NAME TYPE FIELD ATTR +.Fn RB_GENERATE_FIND NAME TYPE FIELD CMP ATTR +.Fn RB_GENERATE_NFIND NAME TYPE FIELD CMP ATTR +.Fn RB_GENERATE_NEXT NAME TYPE FIELD ATTR +.Fn RB_GENERATE_PREV NAME TYPE FIELD ATTR +.Fn RB_GENERATE_MINMAX NAME TYPE FIELD ATTR +.Fn RB_GENERATE_REINSERT NAME TYPE FIELD CMP ATTR +.Fn RB_ENTRY TYPE +.Fn RB_HEAD HEADNAME TYPE +.Fn RB_INITIALIZER "RB_HEAD *head" +.Ft "struct TYPE *" +.Fn RB_ROOT "RB_HEAD *head" +.Ft "bool" +.Fn RB_EMPTY "RB_HEAD *head" +.Ft "struct TYPE *" +.Fn RB_NEXT NAME "RB_HEAD *head" "struct TYPE *elm" +.Ft "struct TYPE *" +.Fn RB_PREV NAME "RB_HEAD *head" "struct TYPE *elm" +.Ft "struct TYPE *" +.Fn RB_MIN NAME "RB_HEAD *head" +.Ft "struct TYPE *" +.Fn RB_MAX NAME "RB_HEAD *head" +.Ft "struct TYPE *" +.Fn RB_FIND NAME "RB_HEAD *head" "struct TYPE *elm" +.Ft "struct TYPE *" +.Fn RB_NFIND NAME "RB_HEAD *head" "struct TYPE *elm" +.Ft "struct TYPE *" +.Fn RB_LEFT "struct TYPE *elm" "RB_ENTRY NAME" +.Ft "struct TYPE *" +.Fn RB_RIGHT "struct TYPE *elm" "RB_ENTRY NAME" +.Ft "struct TYPE *" +.Fn RB_PARENT "struct TYPE *elm" "RB_ENTRY NAME" +.Fn RB_FOREACH VARNAME NAME "RB_HEAD *head" +.Fn RB_FOREACH_FROM "VARNAME" "NAME" "POS_VARNAME" +.Fn RB_FOREACH_SAFE "VARNAME" "NAME" "RB_HEAD *head" "TEMP_VARNAME" +.Fn RB_FOREACH_REVERSE VARNAME NAME "RB_HEAD *head" +.Fn RB_FOREACH_REVERSE_FROM "VARNAME" "NAME" "POS_VARNAME" +.Fn RB_FOREACH_REVERSE_SAFE "VARNAME" "NAME" "RB_HEAD *head" "TEMP_VARNAME" +.Ft void +.Fn RB_INIT "RB_HEAD *head" +.Ft "struct TYPE *" +.Fn RB_INSERT NAME "RB_HEAD *head" "struct TYPE *elm" +.Ft "struct TYPE *" +.Fn RB_INSERT_NEXT NAME "RB_HEAD *head" "struct TYPE *elm" "struct TYPE *next" +.Ft "struct TYPE *" +.Fn RB_INSERT_PREV NAME "RB_HEAD *head" "struct TYPE *elm" "struct TYPE *prev" +.Ft "struct TYPE *" +.Fn RB_REMOVE NAME "RB_HEAD *head" "struct TYPE *elm" +.Ft "struct TYPE *" +.Fn RB_REINSERT NAME "RB_HEAD *head" "struct TYPE *elm" +.Ft "void" +.Fn RB_AUGMENT NAME "struct TYPE *elm" +.Ft "bool" +.Fn RB_AUGMENT_CHECK NAME "struct TYPE *elm" +.Ft "void" +.Fn RB_UPDATE_AUGMENT NAME "struct TYPE *elm" +.Sh DESCRIPTION +These macros define data structures for different types of trees: +splay trees and rank-balanced (wavl) trees. +.Pp +In the macro definitions, +.Fa TYPE +is the name tag of a user defined structure that must contain a field of type +.Vt SPLAY_ENTRY , +or +.Vt RB_ENTRY , +named +.Fa ENTRYNAME . +The argument +.Fa HEADNAME +is the name tag of a user defined structure that must be declared +using the macros +.Fn SPLAY_HEAD , +or +.Fn RB_HEAD . +The argument +.Fa NAME +has to be a unique name prefix for every tree that is defined. +.Pp +The function prototypes are declared with +.Fn SPLAY_PROTOTYPE , +.Fn RB_PROTOTYPE , +or +.Fn RB_PROTOTYPE_STATIC . +The function bodies are generated with +.Fn SPLAY_GENERATE , +.Fn RB_GENERATE , +or +.Fn RB_GENERATE_STATIC . +See the examples below for further explanation of how these macros are used. +.Sh SPLAY TREES +A splay tree is a self-organizing data structure. +Every operation on the tree causes a splay to happen. +The splay moves the requested +node to the root of the tree and partly rebalances it. +.Pp +This has the benefit that request locality causes faster lookups as +the requested nodes move to the top of the tree. +On the other hand, every lookup causes memory writes. +.Pp +The Balance Theorem bounds the total access time for +.Ar m +operations and +.Ar n +inserts on an initially empty tree as +.Fn O "\*[lp]m + n\*[rp]lg n" . +The +amortized cost for a sequence of +.Ar m +accesses to a splay tree is +.Fn O "lg n" . +.Pp +A splay tree is headed by a structure defined by the +.Fn SPLAY_HEAD +macro. +A +structure is declared as follows: +.Bd -ragged -offset indent +.Fn SPLAY_HEAD HEADNAME TYPE +.Va head ; +.Ed +.Pp +where +.Fa HEADNAME +is the name of the structure to be defined, and struct +.Fa TYPE +is the type of the elements to be inserted into the tree. +.Pp +The +.Fn SPLAY_ENTRY +macro declares a structure that allows elements to be connected in the tree. +.Pp +In order to use the functions that manipulate the tree structure, +their prototypes need to be declared with the +.Fn SPLAY_PROTOTYPE +macro, +where +.Fa NAME +is a unique identifier for this particular tree. +The +.Fa TYPE +argument is the type of the structure that is being managed +by the tree. +The +.Fa FIELD +argument is the name of the element defined by +.Fn SPLAY_ENTRY . +.Pp +The function bodies are generated with the +.Fn SPLAY_GENERATE +macro. +It takes the same arguments as the +.Fn SPLAY_PROTOTYPE +macro, but should be used only once. +.Pp +Finally, +the +.Fa CMP +argument is the name of a function used to compare tree nodes +with each other. +The function takes two arguments of type +.Vt "struct TYPE *" . +If the first argument is smaller than the second, the function returns a +value smaller than zero. +If they are equal, the function returns zero. +Otherwise, it should return a value greater than zero. +The compare +function defines the order of the tree elements. +.Pp +The +.Fn SPLAY_INIT +macro initializes the tree referenced by +.Fa head . +.Pp +The splay tree can also be initialized statically by using the +.Fn SPLAY_INITIALIZER +macro like this: +.Bd -ragged -offset indent +.Fn SPLAY_HEAD HEADNAME TYPE +.Va head += +.Fn SPLAY_INITIALIZER &head ; +.Ed +.Pp +The +.Fn SPLAY_INSERT +macro inserts the new element +.Fa elm +into the tree. +.Pp +The +.Fn SPLAY_REMOVE +macro removes the element +.Fa elm +from the tree pointed by +.Fa head . +.Pp +The +.Fn SPLAY_FIND +macro can be used to find a particular element in the tree. +.Bd -literal -offset indent +struct TYPE find, *res; +find.key = 30; +res = SPLAY_FIND(NAME, head, &find); +.Ed +.Pp +The +.Fn SPLAY_ROOT , +.Fn SPLAY_MIN , +.Fn SPLAY_MAX , +and +.Fn SPLAY_NEXT +macros can be used to traverse the tree: +.Bd -literal -offset indent +for (np = SPLAY_MIN(NAME, &head); np != NULL; np = SPLAY_NEXT(NAME, &head, np)) +.Ed +.Pp +Or, for simplicity, one can use the +.Fn SPLAY_FOREACH +macro: +.Bd -ragged -offset indent +.Fn SPLAY_FOREACH np NAME head +.Ed +.Pp +The +.Fn SPLAY_EMPTY +macro should be used to check whether a splay tree is empty. +.Sh RANK-BALANCED TREES +Rank-balanced (RB) trees are a framework for defining height-balanced +binary search trees, including AVL and red-black trees. +Each tree node has an associated rank. +Balance conditions are expressed by conditions on the differences in +rank between any node and its children. +Rank differences are stored in each tree node. +.Pp +The balance conditions implemented by the RB macros lead to weak AVL +(wavl) trees, which combine the best aspects of AVL and red-black +trees. +Wavl trees rebalance after an insertion in the same way AVL trees do, +with the same worst-case time as red-black trees offer, and with +better balance in the resulting tree. +Wavl trees rebalance after a removal in a way that requires less +restructuring, in the worst case, than either AVL or red-black trees +do. +Removals can lead to a tree almost as unbalanced as a red-black +tree; insertions lead to a tree becoming as balanced as an AVL tree. +.Pp +A rank-balanced tree is headed by a structure defined by the +.Fn RB_HEAD +macro. +A +structure is declared as follows: +.Bd -ragged -offset indent +.Fn RB_HEAD HEADNAME TYPE +.Va head ; +.Ed +.Pp +where +.Fa HEADNAME +is the name of the structure to be defined, and struct +.Fa TYPE +is the type of the elements to be inserted into the tree. +.Pp +The +.Fn RB_ENTRY +macro declares a structure that allows elements to be connected in the tree. +.Pp +In order to use the functions that manipulate the tree structure, +their prototypes need to be declared with the +.Fn RB_PROTOTYPE +or +.Fn RB_PROTOTYPE_STATIC +macro, +where +.Fa NAME +is a unique identifier for this particular tree. +The +.Fa TYPE +argument is the type of the structure that is being managed +by the tree. +The +.Fa FIELD +argument is the name of the element defined by +.Fn RB_ENTRY . +Individual prototypes can be declared with +.Fn RB_PROTOTYPE_INSERT , +.Fn RB_PROTOTYPE_INSERT_COLOR , +.Fn RB_PROTOTYPE_REMOVE , +.Fn RB_PROTOTYPE_REMOVE_COLOR , +.Fn RB_PROTOTYPE_FIND , +.Fn RB_PROTOTYPE_NFIND , +.Fn RB_PROTOTYPE_NEXT , +.Fn RB_PROTOTYPE_PREV , +.Fn RB_PROTOTYPE_MINMAX , +and +.Fn RB_PROTOTYPE_REINSERT +in case not all functions are required. +The individual prototype macros expect +.Fa NAME , +.Fa TYPE , +and +.Fa ATTR +arguments. +The +.Fa ATTR +argument must be empty for global functions or +.Fa static +for static functions. +.Pp +The function bodies are generated with the +.Fn RB_GENERATE +or +.Fn RB_GENERATE_STATIC +macro. +These macros take the same arguments as the +.Fn RB_PROTOTYPE +and +.Fn RB_PROTOTYPE_STATIC +macros, but should be used only once. +As an alternative individual function bodies are generated with the +.Fn RB_GENERATE_INSERT , +.Fn RB_GENERATE_INSERT_COLOR , +.Fn RB_GENERATE_REMOVE , +.Fn RB_GENERATE_REMOVE_COLOR , +.Fn RB_GENERATE_FIND , +.Fn RB_GENERATE_NFIND , +.Fn RB_GENERATE_NEXT , +.Fn RB_GENERATE_PREV , +.Fn RB_GENERATE_MINMAX , +and +.Fn RB_GENERATE_REINSERT +macros. +.Pp +Finally, +the +.Fa CMP +argument is the name of a function used to compare tree nodes +with each other. +The function takes two arguments of type +.Vt "struct TYPE *" . +If the first argument is smaller than the second, the function returns a +value smaller than zero. +If they are equal, the function returns zero. +Otherwise, it should return a value greater than zero. +The compare +function defines the order of the tree elements. +.Pp +The +.Fn RB_INIT +macro initializes the tree referenced by +.Fa head . +.Pp +The rank-balanced tree can also be initialized statically by using the +.Fn RB_INITIALIZER +macro like this: +.Bd -ragged -offset indent +.Fn RB_HEAD HEADNAME TYPE +.Va head += +.Fn RB_INITIALIZER &head ; +.Ed +.Pp +The +.Fn RB_INSERT +macro inserts the new element +.Fa elm +into the tree. +.Pp +The +.Fn RB_INSERT_NEXT +macro inserts the new element +.Fa elm +into the tree immediately after a given element. +.Pp +The +.Fn RB_INSERT_PREV +macro inserts the new element +.Fa elm +into the tree immediately before a given element. +.Pp +The +.Fn RB_REMOVE +macro removes the element +.Fa elm +from the tree pointed by +.Fa head . +.Pp +The +.Fn RB_FIND +and +.Fn RB_NFIND +macros can be used to find a particular element in the tree. +.Pp +The +.Fn RB_FIND +macro returns the element in the tree equal to the provided +key, or +.Dv NULL +if there is no such element. +.Pp +The +.Fn RB_NFIND +macro returns the least element greater than or equal to the provided +key, or +.Dv NULL +if there is no such element. +.Bd -literal -offset indent +struct TYPE find, *res, *resn; +find.key = 30; +res = RB_FIND(NAME, head, &find); +resn = RB_NFIND(NAME, head, &find); +.Ed +.Pp +The +.Fn RB_ROOT , +.Fn RB_MIN , +.Fn RB_MAX , +.Fn RB_NEXT , +and +.Fn RB_PREV +macros can be used to traverse the tree: +.Pp +.Dl "for (np = RB_MIN(NAME, &head); np != NULL; np = RB_NEXT(NAME, &head, np))" +.Pp +Or, for simplicity, one can use the +.Fn RB_FOREACH +or +.Fn RB_FOREACH_REVERSE +macro: +.Bd -ragged -offset indent +.Fn RB_FOREACH np NAME head +.Ed +.Pp +The macros +.Fn RB_FOREACH_SAFE +and +.Fn RB_FOREACH_REVERSE_SAFE +traverse the tree referenced by head +in a forward or reverse direction respectively, +assigning each element in turn to np. +However, unlike their unsafe counterparts, +they permit both the removal of np +as well as freeing it from within the loop safely +without interfering with the traversal. +.Pp +Both +.Fn RB_FOREACH_FROM +and +.Fn RB_FOREACH_REVERSE_FROM +may be used to continue an interrupted traversal +in a forward or reverse direction respectively. +The head pointer is not required. +The pointer to the node from where to resume the traversal +should be passed as their last argument, +and will be overwritten to provide safe traversal. +.Pp +The +.Fn RB_EMPTY +macro should be used to check whether a rank-balanced tree is empty. +.Pp +The +.Fn RB_REINSERT +macro updates the position of the element +.Fa elm +in the tree. +This must be called if a member of a +.Nm tree +is modified in a way that affects comparison, such as by modifying +a node's key. +This is a lower overhead alternative to removing the element +and reinserting it again. +.Pp +The +.Fn RB_AUGMENT +macro updates augmentation data of the element +.Fa elm +in the tree. +By default, it has no effect. +It is not meant to be invoked by the RB user. +If +.Fn RB_AUGMENT +is defined by the RB user, then when an element is inserted or removed +from the tree, it is invoked for every element in the tree that is the +root of an altered subtree, working from the bottom of the tree up to +the top. +It is typically used to maintain some associative accumulation of tree +elements, such as sums, minima, maxima, and the like. +.Pp +The +.Fn RB_AUGMENT_CHECK +macro updates augmentation data of the element +.Fa elm +in the tree. +By default, it does nothing and returns false. +If +.Fn RB_AUGMENT_CHECK +is defined, then when an element is inserted or removed from the tree, +it is invoked for every element in the tree that is the root of an +altered subtree, working from the bottom of the tree up toward the +top, until it returns false to indicate that it did not change the +element and so working further up the tree would change nothing. +It is typically used to maintain some associative accumulation of tree +elements, such as sums, minima, maxima, and the like. +.Pp +The +.Fn RB_UPDATE_AUGMENT +macro updates augmentation data of the element +.Fa elm +and its ancestors in the tree. +If +.Fn RB_AUGMENT +is defined by the RB user, then when an element in the +tree is changed, without changing the order of items in the tree, +invoking this function on that element restores consistency of the +augmentation state of the tree as if the element had been removed and +inserted again. +.Sh EXAMPLES +The following example demonstrates how to declare a rank-balanced tree +holding integers. +Values are inserted into it and the contents of the tree are printed +in order. +To maintain the sum of the values in the tree, each element maintains +the sum of its value and the sums from its left and right subtrees. +Lastly, the internal structure of the tree is printed. +.Bd -literal -offset 3n +#define RB_AUGMENT(entry) sumaug(entry) + +#include +#include +#include +#include + +struct node { + RB_ENTRY(node) entry; + int i, sum; +}; + +int +intcmp(struct node *e1, struct node *e2) +{ + return (e1->i < e2->i ? -1 : e1->i > e2->i); +} + +void +sumaug(struct node *e) +{ + e->sum = e->i; + if (RB_LEFT(e, entry) != NULL) + e->sum += RB_LEFT(e, entry)->sum; + if (RB_RIGHT(e, entry) != NULL) + e->sum += RB_RIGHT(e, entry)->sum; +} + +RB_HEAD(inttree, node) head = RB_INITIALIZER(&head); +RB_GENERATE(inttree, node, entry, intcmp) + +int testdata[] = { + 20, 16, 17, 13, 3, 6, 1, 8, 2, 4, 10, 19, 5, 9, 12, 15, 18, + 7, 11, 14 +}; + +void +print_tree(struct node *n) +{ + struct node *left, *right; + + if (n == NULL) { + printf("nil"); + return; + } + left = RB_LEFT(n, entry); + right = RB_RIGHT(n, entry); + if (left == NULL && right == NULL) + printf("%d", n->i); + else { + printf("%d(", n->i); + print_tree(left); + printf(","); + print_tree(right); + printf(")"); + } +} + +int +main(void) +{ + int i; + struct node *n; + + for (i = 0; i < sizeof(testdata) / sizeof(testdata[0]); i++) { + if ((n = malloc(sizeof(struct node))) == NULL) + err(1, NULL); + n->i = testdata[i]; + RB_INSERT(inttree, &head, n); + } + + RB_FOREACH(n, inttree, &head) { + printf("%d\en", n->i); + } + print_tree(RB_ROOT(&head)); + printf("\enSum of values = %d\en", RB_ROOT(&head)->sum); + return (0); +} +.Ed +.Sh NOTES +Trying to free a tree in the following way is a common error: +.Bd -literal -offset indent +SPLAY_FOREACH(var, NAME, head) { + SPLAY_REMOVE(NAME, head, var); + free(var); +} +free(head); +.Ed +.Pp +Since +.Va var +is freed, the +.Fn FOREACH +macro refers to a pointer that may have been reallocated already. +Proper code needs a second variable. +.Bd -literal -offset indent +for (var = SPLAY_MIN(NAME, head); var != NULL; var = nxt) { + nxt = SPLAY_NEXT(NAME, head, var); + SPLAY_REMOVE(NAME, head, var); + free(var); +} +.Ed +.Pp +Both +.Fn RB_INSERT +and +.Fn SPLAY_INSERT +return +.Dv NULL +if the element was inserted in the tree successfully, otherwise they +return a pointer to the element with the colliding key. +.Pp +Accordingly, +.Fn RB_REMOVE +and +.Fn SPLAY_REMOVE +return the pointer to the removed element otherwise they return +.Dv NULL +to indicate an error. +.Sh SEE ALSO +.Xr arb 3 , +.Xr queue 3 +.Rs +.%A "Bernhard Haeupler" +.%A "Siddhartha Sen" +.%A "Robert E. Tarjan" +.%T "Rank-Balanced Trees" +.%U "http://sidsen.azurewebsites.net/papers/rb-trees-talg.pdf" +.%J "ACM Transactions on Algorithms" +.%V "11" +.%N "4" +.%D "June 2015" +.Re +.Sh HISTORY +The tree macros first appeared in +.Fx 4.6 . +.Sh AUTHORS +The author of the tree macros is +.An Niels Provos . diff --git a/static/freebsd/man3lua/Makefile b/static/freebsd/man3lua/Makefile new file mode 100644 index 00000000..2c25ec48 --- /dev/null +++ b/static/freebsd/man3lua/Makefile @@ -0,0 +1,3 @@ +MAN = $(wildcard *.3lua) + +include ../../mandoc.mk diff --git a/static/freebsd/man3lua/intro.3lua b/static/freebsd/man3lua/intro.3lua new file mode 100644 index 00000000..50594c6a --- /dev/null +++ b/static/freebsd/man3lua/intro.3lua @@ -0,0 +1,63 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2020, Ryan Moeller +.\" +.\" 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 October 24, 2020 +.Dt INTRO 3lua +.Os +.Sh NAME +.Nm intro +.Nd introduction to the Lua modules for flua +.Po +.Fx +Lua +.Pc +.Sh DESCRIPTION +This section describes +.Em flua +.Po +.Fx +Lua +.Pc +and the Lua modules provided in the +.Fx +base system. +.Pp +The Lua modules provided by +.Fx +are: +.Bl -tag -width jail +.It Xr jail 3lua +Wrapper for +.Xr jail 3 . +.El +.Sh SEE ALSO +.Xr jail 3lua +.Sh AUTHORS +.An Ryan Moeller , +with inspiration from +.Nx +intro(3lua), by +.An Marc Balmer . diff --git a/static/freebsd/man4/Makefile b/static/freebsd/man4/Makefile new file mode 100644 index 00000000..4b373fc3 --- /dev/null +++ b/static/freebsd/man4/Makefile @@ -0,0 +1,8 @@ +MAN = $(wildcard *.4) +SUBDIRS = man4.aarch64 \ + man4.arm \ + man4.i386 \ + man4.powerpc + +include ../../mandoc.mk + diff --git a/static/freebsd/man4/aac.4 b/static/freebsd/man4/aac.4 new file mode 100644 index 00000000..f4b431cc --- /dev/null +++ b/static/freebsd/man4/aac.4 @@ -0,0 +1,300 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2000 Scott Long +.\" 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 September 29, 2025 +.Dt AAC 4 +.Os +.Sh NAME +.Nm aac +.Nd Adaptec AdvancedRAID Controller driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd device pci +.Cd device aac +.Cd device aacp +.Pp +To compile in debugging code: +.Cd options AAC_DEBUG=N +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +aac_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the Adaptec AAC family of SCSI Ultra2, Ultra160, +and Ultra320, SATA and SAS RAID controllers. +.Pp +Access to RAID containers is available via the +.Pa /dev/aacd? +device nodes. +The +.Nm aacp +device enables the SCSI pass-thru interface and allows devices connected +to the card such as CD-ROMs to be available via the CAM +.Xr scsi 4 +subsystem. +Note that not all cards allow this interface to be enabled. +.Pp +The +.Pa /dev/aac? +device nodes provide access to the management interface of the controller. +One node exists per installed card. +The aliases +.Pa /dev/afa? +and +.Pa /dev/hpn? +exist for compatibility with the Dell and HP versions of management tools, +respectively. +If the +.Pa aac_linux.ko +and +.Pa linux.ko +modules are loaded, the +Linux-compatible +.Xr ioctl 2 +interface for the management device will be enabled and will allow +Linux-based management applications to control the card. +.Sh HARDWARE +The +.Nm +driver supports the following Parallel SCSI, SATA, and 3G SAS +RAID controllers from the Adaptec AAC family: +.Pp +.Bl -bullet -compact +.It +Adaptec AAC-364 +.It +Adaptec RAID 2045 +.It +Adaptec RAID 2405 +.It +Adaptec RAID 2445 +.It +Adaptec RAID 2805 +.It +Adaptec RAID 3085 +.It +Adaptec RAID 31205 +.It +Adaptec RAID 31605 +.It +Adaptec RAID 5085 +.It +Adaptec RAID 51205 +.It +Adaptec RAID 51245 +.It +Adaptec RAID 51605 +.It +Adaptec RAID 51645 +.It +Adaptec RAID 52445 +.It +Adaptec RAID 5405 +.It +Adaptec RAID 5445 +.It +Adaptec RAID 5805 +.It +Adaptec SAS RAID 3405 +.It +Adaptec SAS RAID 3805 +.It +Adaptec SAS RAID 4000SAS +.It +Adaptec SAS RAID 4005SAS +.It +Adaptec SAS RAID 4800SAS +.It +Adaptec SAS RAID 4805SAS +.It +Adaptec SATA RAID 2020SA ZCR +.It +Adaptec SATA RAID 2025SA ZCR +.It +Adaptec SATA RAID 2026ZCR +.It +Adaptec SATA RAID 2410SA +.It +Adaptec SATA RAID 2420SA +.It +Adaptec SATA RAID 2610SA +.It +Adaptec SATA RAID 2620SA +.It +Adaptec SATA RAID 2810SA +.It +Adaptec SATA RAID 2820SA +.It +Adaptec SATA RAID 21610SA +.It +Adaptec SCSI RAID 2020ZCR +.It +Adaptec SCSI RAID 2025ZCR +.It +Adaptec SCSI RAID 2120S +.It +Adaptec SCSI RAID 2130S +.It +Adaptec SCSI RAID 2130SLP +.It +Adaptec SCSI RAID 2230SLP +.It +Adaptec SCSI RAID 2200S +.It +Adaptec SCSI RAID 2240S +.It +Adaptec SCSI RAID 3230S +.It +Adaptec SCSI RAID 3240S +.It +Adaptec SCSI RAID 5400S +.It +Dell CERC SATA RAID 2 +.It +Dell PERC 2/Si +.It +Dell PERC 2/QC +.It +Dell PERC 3/Si +.It +Dell PERC 3/Di +.It +Dell PERC 320/DC +.It +HP ML110 G2 (Adaptec SATA RAID 2610SA) +.It +HP NetRAID 4M +.It +IBM ServeRAID 8i +.It +IBM ServeRAID 8k +.It +IBM ServeRAID 8s +.It +ICP RAID ICP5045BL +.It +ICP RAID ICP5085BL +.It +ICP RAID ICP5085SL +.It +ICP RAID ICP5125BR +.It +ICP RAID ICP5125SL +.It +ICP RAID ICP5165BR +.It +ICP RAID ICP5165SL +.It +ICP RAID ICP5445SL +.It +ICP RAID ICP5805BL +.It +ICP RAID ICP5805SL +.It +ICP ICP5085BR SAS RAID +.It +ICP ICP9085LI SAS RAID +.It +ICP ICP9047MA SATA RAID +.It +ICP ICP9067MA SATA RAID +.It +ICP ICP9087MA SATA RAID +.It +ICP ICP9014RO SCSI RAID +.It +ICP ICP9024RO SCSI RAID +.It +Legend S220 +.It +Legend S230 +.It +Sun STK RAID REM +.It +Sun STK RAID EM +.It +SG-XPCIESAS-R-IN +.It +SG-XPCIESAS-R-EX +.It +AOC-USAS-S4i +.It +AOC-USAS-S8i +.It +AOC-USAS-S4iR +.It +AOC-USAS-S8iR +.It +AOC-USAS-S8i-LP +.It +AOC-USAS-S8iR-LP +.El +.Sh FILES +.Bl -tag -width /boot/kernel/aac.ko -compact +.It Pa /dev/aac? +aac management interface +.It Pa /dev/aacd? +disk/container interface +.El +.Sh DIAGNOSTICS +Compiling with +.Dv AAC_DEBUG +set to a number between 0 and 3 +will enable increasingly verbose debug messages. +.Pp +The adapter can send status and alert messages asynchronously +to the driver. +These messages are printed on the system console, +and are also queued for retrieval by a management application. +.Sh SEE ALSO +.Xr kld 4 , +.Xr linux 4 , +.Xr scsi 4 , +.Xr kldload 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 4.3 . +.Sh AUTHORS +.An Mike Smith Aq Mt msmith@FreeBSD.org +.An Scott Long Aq Mt scottl@FreeBSD.org +.Sh BUGS +This driver is not compatible with Dell controllers that have version 1.x +firmware. +The firmware version is the same as the kernel version printed in the BIOS +POST and driver attach messages. +.Pp +The controller is not actually paused on suspend/resume. diff --git a/static/freebsd/man4/aacraid.4 b/static/freebsd/man4/aacraid.4 new file mode 100644 index 00000000..0f64f36c --- /dev/null +++ b/static/freebsd/man4/aacraid.4 @@ -0,0 +1,136 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2013 Achim Leubner +.\" 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 September 29, 2025 +.Dt AACRAID 4 +.Os +.Sh NAME +.Nm aacraid +.Nd Adaptec Series 6/7/8 6G and 12G SAS+SATA RAID controller driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd device pci +.Cd device aacraid +.Pp +To compile in debugging code: +.Cd options AACRAID_DEBUG=N +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +aacraid_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the Adaptec by PMC RAID controllers, +including Series 6/7/8 and upcoming families. +.Pp +The RAID containers are handled via the +.Nm aacraidp0 +bus. +The physical buses are represented by the +.Nm aacraidp? +devices (beginning with aacraidp1). +These devices enable the +SCSI pass-passthrough interface and allows devices connected +to the card such as CD-ROMs to be available via the CAM +.Xr scsi 4 +subsystem. +Note that not all cards allow this interface to be enabled. +.Pp +The +.Pa /dev/aacraid? +device nodes provide access to the management interface of the controller. +One node exists per installed card. +If the +.Pa aacraid_linux.ko +and +.Pa linux.ko +modules are loaded, the +Linux-compatible +.Xr ioctl 2 +interface for the management device will be enabled and will allow +Linux-based management applications to control the card. +.Sh HARDWARE +The +.Nm +driver supports the following +Adaptec 6G and 12G SAS/SATA RAID controllers: +.Pp +.Bl -bullet -compact +.It +Adaptec ASR-6405(T|E) +.It +Adaptec ASR-6445 +.It +Adaptec ASR-6805(T|E|Q|TQ) +.It +Adaptec ASR-7085 +.It +Adaptec ASR-7805(Q) +.It +Adaptec ASR-70165 +.It +Adaptec ASR-71605(E|Q) +.It +Adaptec ASR-71685 +.It +Adaptec ASR-72405 +.It +Adaptec Series 8 cards +.El +.Sh FILES +.Bl -tag -width /boot/kernel/aacraid.ko -compact +.It Pa /dev/aacraid? +aacraid management interface +.El +.Sh DIAGNOSTICS +Compiling with +.Dv AACRAID_DEBUG +set to a number between 0 and 3 +will enable increasingly verbose debug messages. +.Pp +The adapter can send status and alert messages asynchronously +to the driver. +These messages are printed on the system console, +and are also queued for retrieval by a management application. +.Sh SEE ALSO +.Xr kld 4 , +.Xr linux 4 , +.Xr scsi 4 , +.Xr kldload 8 +.Sh AUTHORS +.An Achim Leubner Aq Mt achim@FreeBSD.org +.An \&Ed Maste Aq Mt emaste@FreeBSD.org +.An Scott Long Aq Mt scottl@FreeBSD.org +.Sh BUGS +The controller is not actually paused on suspend/resume. diff --git a/static/freebsd/man4/acpi.4 b/static/freebsd/man4/acpi.4 new file mode 100644 index 00000000..91193d89 --- /dev/null +++ b/static/freebsd/man4/acpi.4 @@ -0,0 +1,646 @@ +.\" +.\" Copyright (c) 2001 Michael Smith +.\" 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 March 21, 2026 +.Dt ACPI 4 +.Os +.Sh NAME +.Nm acpi +.Nd Advanced Configuration and Power Management support +.Sh SYNOPSIS +.Cd "device acpi" +.Pp +.Cd "options ACPI_DEBUG" +.Cd "options DDB" +.Sh DESCRIPTION +The +.Nm +driver provides support for the Intel/Microsoft/Compaq/Toshiba ACPI +standard. +This support includes platform hardware discovery (superseding the +PnP and PCI BIOS), as well as power management (superseding APM) and +other features. +ACPI core support is provided by the ACPI CA reference implementation +from Intel. +.Pp +Note that the +.Nm +driver is automatically loaded by the +.Xr loader 8 , +and should only be +compiled into the kernel on platforms where ACPI is mandatory. +.Sh SYSCTL VARIABLES +The +.Nm +driver is intended to provide power management without user intervention. +If the default settings are not optimal, the following sysctls can be +used to modify or monitor +.Nm +behavior. +Note that some variables will be available only if the given hardware supports +them (such as +.Va hw.acpi.acline ) . +.Bl -tag -width indent +.It Va debug.acpi.enable_debug_objects +Enable dumping Debug objects without +.Cd "options ACPI_DEBUG" . +Default is 0, ignore Debug objects. +.It Va dev.cpu.N.cx_usage +Debugging information listing the percent of total usage for each sleep state. +The values are reset when +.Va dev.cpu.N.cx_lowest +is modified. +.It Va dev.cpu.N.cx_lowest +Lowest Cx state to use for idling the CPU. +A scheduling algorithm will select states between +.Li C1 +and this setting +as system load dictates. +To enable ACPI CPU idling control, +.Va machdep.idle +should be set to +.Li acpi +if it is listed in +.Va machdep.idle_available . +.It Va dev.cpu.N.cx_supported +List of supported CPU idle states and their transition latency +in microseconds. +Each state has a type (e.g., +.Li C2 ) . +.Li C1 +is equivalent to the ia32 +.Li HLT +instruction, +.Li C2 +provides a deeper +sleep with the same semantics, and +.Li C3 +provides the deepest sleep +but additionally requires bus mastering to be disabled. +States greater than +.Li C3 +provide even more power savings with the same +semantics as the +.Li C3 +state. +Deeper sleeps provide more power savings but increased transition +latency when an interrupt occurs. +.It Va dev.cpu.N.cx_method +List of supported CPU idle states and their transition methods, as +directed by the firmware. +.It Va hw.acpi.acline +AC line state (1 means online, 0 means on battery power). +.It Va hw.acpi.disable_on_reboot +Disable ACPI during the reboot process. +Most systems reboot fine with ACPI still enabled, but some require +exiting to legacy mode first. +Default is 0, leave ACPI enabled. +.It Va hw.acpi.handle_reboot +Use the ACPI Reset Register capability to reboot the system. +Some newer systems require use of this register, while some only work +with legacy rebooting support. +.It Va hw.acpi.lid_switch_state +Sleep type +.Pq Li awake , Li standby , Li s2mem , Li s2idle , Li hibernate , Li poweroff +to enter when the lid switch (i.e., a notebook screen) is closed, or +.Dq Li NONE +.Pq do nothing . +Default is +.Dq Li NONE . +.It Va hw.acpi.power_button_state +Sleep type +.Pq Li awake , Li standby , Li s2mem , Li s2idle , Li hibernate , Li poweroff +to enter when the power button is pressed, or +.Dq Li NONE +.Pq do nothing . +Default is +.Li poweroff . +.It Va hw.acpi.reset_video +Reset the video adapter from real mode during the resume path. +Some systems need this help, others have display problems if it is enabled. +Default is 0 (disabled). +.It Va hw.acpi.s4bios +Indicate whether the system supports +.Li S4BIOS . +This means that the BIOS can handle all the functions of suspending the +system to disk. +Otherwise, the OS is responsible for suspending to disk +.Pq Li S4OS . +Most current systems do not support +.Li S4BIOS . +.It Va hw.acpi.sleep_button_state +Sleep type +.Pq Li awake , Li standby , Li s2mem , Li s2idle , Li hibernate , Li poweroff +to enter when the sleep button is pressed. +This is usually a special function button on the keyboard. +Default is usually +.Li s2mem +if supported, and +.Li s2idle +if not. +.It Va hw.acpi.sleep_delay +Wait this number of seconds between preparing the system to suspend and +actually entering the suspend state. +Default is 1 second. +.It Va hw.acpi.supported_sleep_state +ACPI S-states +.Pq Li S1 Ns \[en] Ns Li S5 +supported by the BIOS. +.Bl -tag -width indent +.It Li S1 +Quick suspend to RAM. +The CPU enters a lower power state, but most peripherals are left running. +.It Li S2 +Lower power state than +.Li S1 , +but with the same basic characteristics. +Not supported by many systems. +.It Li S3 +Suspend to RAM. +Most devices are powered off, and the system stops running except for +memory refresh. +.It Li S4 +Suspend to disk. +All devices are powered off, and the system stops running. +When resuming, the system starts as if from a cold power on. +Not yet supported by +.Fx +unless +.Li S4BIOS +is available. +.It Li S5 +System shuts down cleanly and powers off. +.El +.It Va hw.acpi.verbose +Enable verbose printing from the various ACPI subsystems. +.El +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Pa /boot/loader.conf . +Many of these tunables also have a matching +.Xr sysctl 8 +entry for access after boot. +.Bl -tag -width indent +.It Va acpi_dsdt_load +Enables loading of a custom ACPI DSDT. +.It Va acpi_dsdt_name +Name of the DSDT table to load, if loading is enabled. +.It Va debug.acpi.disabled +Selectively disables portions of ACPI for debugging purposes. +.It Va debug.acpi.interpreter_slack +Enable less strict ACPI implementations. +Default is 1, ignore common BIOS mistakes. +.It Va debug.acpi.max_threads +Specify the number of task threads that are started on boot. +Limiting this to 1 may help work around various BIOSes that cannot +handle parallel requests. +The default value is 3. +.It Va debug.acpi.quirks +Override any automatic quirks completely. +.It Va debug.acpi.resume_beep +Beep the PC speaker on resume. +This can help diagnose suspend/resume problems. +Default is 0 (disabled). +.It Va hint.acpi.0.disabled +Set this to 1 to disable all of ACPI. +If ACPI has been disabled on your system due to a blacklist entry for your +BIOS, you can set this to 0 to re-enable ACPI for testing. +.It Va hw.acpi.ec.poll_timeout +Delay in milliseconds to wait for the EC to respond. +Try increasing this number if you get the error +.Qq Li AE_NO_HARDWARE_RESPONSE . +.It Va hw.acpi.host_mem_start +Override the assumed memory starting address for PCI host bridges. +.It Va hw.acpi.install_interface , hw.acpi.remove_interface +Install or remove OS interface(s) to control return value of +.Ql _OSI +query method. +When an OS interface is specified in +.Va hw.acpi.install_interface , +.Li _OSI +query for the interface returns it is +.Em supported . +Conversely, when an OS interface is specified in +.Va hw.acpi.remove_interface , +.Li _OSI +query returns it is +.Em not supported . +Multiple interfaces can be specified in a comma-separated list and +any leading white spaces will be ignored. +For example, +.Qq Li FreeBSD, Linux +is a valid list of two interfaces +.Qq Li FreeBSD +and +.Qq Li Linux . +.It Va hw.acpi.hw.acpi.override_isa_irq_polarity (x86) +Forces active-lo polarity for edge-triggered ISA interrupts. +Some older systems incorrectly specify active-lo polarity for ISA +interrupts and this override fixes those systems. +This override is enabled by default on systems with Intel CPUs, +but can be enabled or disabled by setting the tunable explicitly. +.It Va hw.acpi.reset_video +Enables calling the VESA reset BIOS vector on the resume path. +This can fix some graphics cards that have problems such as LCD white-out +after resume. +Default is 0 (disabled). +.It Va hw.acpi.serialize_methods +Allow override of whether methods execute in parallel or not. +Enable this for serial behavior, which fixes +.Qq Li AE_ALREADY_EXISTS +errors for +AML that really cannot handle parallel method execution. +It is off by default since this breaks recursive methods and some IBMs use +such code. +.It Va hw.acpi.verbose +Turn on verbose debugging information about what ACPI is doing. +.It Va hw.pci.link.%s.%d.irq +Override the interrupt to use for this link and index. +This capability should be used carefully, and only if a device is not +working with +.Nm +enabled. +.Qq %s +is the name of the link (e.g., LNKA). +.Qq %d +is the resource index when the link supports multiple IRQs. +Most PCI links only have one IRQ resource, so the below form should be used. +.It Va hw.pci.link.%s.irq +Override the interrupt to use. +This capability should be used carefully, and only if a device is not +working with +.Nm +enabled. +.Qq %s +is the name of the link (e.g., LNKA). +.El +.Sh DISABLING ACPI +Since ACPI support on different platforms varies greatly, there are many +debugging and tuning options available. +.Pp +For machines known not to work with +.Nm +enabled, there is a BIOS blacklist. +Currently, the blacklist only controls whether +.Nm +should be disabled or not. +In the future, it will have more granularity to control features (the +infrastructure for that is already there). +.Pp +To enable +.Nm +(for debugging purposes, etc.) on machines that are on the blacklist, set the +kernel environment variable +.Va hint.acpi.0.disabled +to 0. +Before trying this, consider updating your BIOS to a more recent version that +may be compatible with ACPI. +.Pp +To disable the +.Nm +driver completely, set the kernel environment variable +.Va hint.acpi.0.disabled +to 1. +.Pp +Some i386 machines totally fail to operate with some or all of ACPI disabled. +Other i386 machines fail with ACPI enabled. +Disabling all or part of ACPI on non-i386 platforms (i.e., platforms where +ACPI support is mandatory) may result in a non-functional system. +.Pp +The +.Nm +driver comprises a set of drivers, which may be selectively disabled +in case of problems. +To disable a sub-driver, list it in the kernel +environment variable +.Va debug.acpi.disabled . +Multiple entries can be listed, separated by a space. +.Pp +ACPI sub-devices and features that can be disabled: +.Bl -tag -width ".Li sysresource" +.It Li all +Disable all ACPI features and devices. +.It Li acad +.Pq Vt device +Supports AC adapter. +.It Li bus +.Pq Vt feature +Probes and attaches subdevices. +Disabling will avoid scanning the ACPI namespace entirely. +.It Li children +.Pq Vt feature +Attaches standard ACPI sub-drivers and devices enumerated in the +ACPI namespace. +Disabling this has a similar effect to disabling +.Dq Li bus , +except that the +ACPI namespace will still be scanned. +.It Li button +.Pq Vt device +Supports ACPI button devices (typically power and sleep buttons). +.It Li cmbat +.Pq Vt device +Control-method batteries device. +.It Li cpu +.Pq Vt device +Supports CPU power-saving and speed-setting functions. +.It Li ec +.Pq Vt device +Supports the ACPI Embedded Controller interface, used to communicate +with embedded platform controllers. +.It Li isa +.Pq Vt device +Supports an ISA bus bridge defined in the ACPI namespace, +typically as a child of a PCI bus. +.It Li lid +.Pq Vt device +Supports an ACPI laptop lid switch, which typically puts a +system to sleep. +.It Li mwait +.Pq Vt feature +Do not ask firmware for available x86-vendor specific methods to enter +.Li Cx +sleep states. +Only query and use the generic I/O-based entrance method. +The knob is provided to work around inconsistencies in the tables +filled by firmware. +.It Li quirks +.Pq Vt feature +Do not honor quirks. +Quirks automatically disable ACPI functionality based on the XSDT table's +OEM vendor name and revision date. +.It Li pci +.Pq Vt device +Supports Host to PCI bridges. +.It Li pci_link +.Pq Vt feature +Performs PCI interrupt routing. +.It Li sysresource +.Pq Vt device +Pseudo-devices containing resources which ACPI claims. +.It Li thermal +.Pq Vt device +Supports system cooling and heat management. +.It Li timer +.Pq Vt device +Implements a timecounter using the ACPI fixed-frequency timer. +.It Li video +.Pq Vt device +Supports +.Xr acpi_video 4 +which may conflict with +.Xr agp 4 +device. +.El +.Pp +It is also possible to avoid portions of the ACPI namespace which +may be causing problems, by listing the full path of the root of +the region to be avoided in the kernel environment variable +.Va debug.acpi.avoid . +The object and all of its children will be ignored during the +bus/children scan of the namespace. +The ACPI CA code will still know about the avoided region. +.Sh DEBUGGING OUTPUT +To enable debugging output, +.Nm +must be compiled with +.Cd "options ACPI_DEBUG" . +Debugging output is separated between layers and levels, where a layer is +a component of the ACPI subsystem, and a level is a particular kind +of debugging output. +.Pp +Both layers and levels are specified as a whitespace-separated list of +tokens, with layers listed in +.Va debug.acpi.layer +and levels in +.Va debug.acpi.level . +.Pp +The first set of layers is for ACPI-CA components, and the second is for +.Fx +drivers. +The ACPI-CA layer descriptions include the prefix for the files they +refer to. +The supported layers are: +.Pp +.Bl -tag -compact -width ".Li ACPI_CA_DISASSEMBLER" +.It Li ACPI_UTILITIES +Utility ("ut") functions +.It Li ACPI_HARDWARE +Hardware access ("hw") +.It Li ACPI_EVENTS +Event and GPE ("ev") +.It Li ACPI_TABLES +Table access ("tb") +.It Li ACPI_NAMESPACE +Namespace evaluation ("ns") +.It Li ACPI_PARSER +AML parser ("ps") +.It Li ACPI_DISPATCHER +Internal representation of interpreter state ("ds") +.It Li ACPI_EXECUTER +Execute AML methods ("ex") +.It Li ACPI_RESOURCES +Resource parsing ("rs") +.It Li ACPI_CA_DEBUGGER +Debugger implementation ("db", "dm") +.It Li ACPI_OS_SERVICES +Usermode support routines ("os") +.It Li ACPI_CA_DISASSEMBLER +Disassembler implementation (unused) +.It Li ACPI_ALL_COMPONENTS +All the above ACPI-CA components +.It Li ACPI_AC_ADAPTER +AC adapter driver +.It Li ACPI_BATTERY +Control-method battery driver +.It Li ACPI_BUS +ACPI, ISA, and PCI bus drivers +.It Li ACPI_BUTTON +Power and sleep button driver +.It Li ACPI_EC +Embedded controller driver +.It Li ACPI_FAN +Fan driver +.It Li ACPI_OEM +Platform-specific driver for hotkeys, LED, etc. +.It Li ACPI_POWERRES +Power resource driver +.It Li ACPI_PROCESSOR +CPU driver +.It Li ACPI_SPMC +System power management controller driver +.It Li ACPI_THERMAL +Thermal zone driver +.It Li ACPI_TIMER +Timer driver +.It Li ACPI_ALL_DRIVERS +All the above +.Fx +ACPI drivers +.El +.Pp +The supported levels are: +.Pp +.Bl -tag -compact -width ".Li ACPI_LV_AML_DISASSEMBLE" +.It Li ACPI_LV_INIT +Initialization progress +.It Li ACPI_LV_DEBUG_OBJECT +Stores to objects +.It Li ACPI_LV_INFO +General information and progress +.It Li ACPI_LV_REPAIR +Repair a common problem with predefined methods +.It Li ACPI_LV_ALL_EXCEPTIONS +All the previous levels +.It Li ACPI_LV_PARSE +.It Li ACPI_LV_DISPATCH +.It Li ACPI_LV_EXEC +.It Li ACPI_LV_NAMES +.It Li ACPI_LV_OPREGION +.It Li ACPI_LV_BFIELD +.It Li ACPI_LV_TABLES +.It Li ACPI_LV_VALUES +.It Li ACPI_LV_OBJECTS +.It Li ACPI_LV_RESOURCES +.It Li ACPI_LV_USER_REQUESTS +.It Li ACPI_LV_PACKAGE +.It Li ACPI_LV_VERBOSITY1 +All the previous levels +.It Li ACPI_LV_ALLOCATIONS +.It Li ACPI_LV_FUNCTIONS +.It Li ACPI_LV_OPTIMIZATIONS +.It Li ACPI_LV_VERBOSITY2 +All the previous levels +.It Li ACPI_LV_ALL +Synonym for +.Qq Li ACPI_LV_VERBOSITY2 +.It Li ACPI_LV_MUTEX +.It Li ACPI_LV_THREADS +.It Li ACPI_LV_IO +.It Li ACPI_LV_INTERRUPTS +.It Li ACPI_LV_VERBOSITY3 +All the previous levels +.It Li ACPI_LV_AML_DISASSEMBLE +.It Li ACPI_LV_VERBOSE_INFO +.It Li ACPI_LV_FULL_TABLES +.It Li ACPI_LV_EVENTS +.It Li ACPI_LV_VERBOSE +All levels after +.Qq Li ACPI_LV_VERBOSITY3 +.It Li ACPI_LV_INIT_NAMES +.It Li ACPI_LV_LOAD +.El +.Pp +Selection of the appropriate layer and level values is important +to avoid massive amounts of debugging output. +For example, the following configuration is a good way to gather initial +information. +It enables debug output for both ACPI-CA and the +.Nm +driver, printing basic information about errors, warnings, and progress. +.Bd -literal -offset indent +debug.acpi.layer="ACPI_ALL_COMPONENTS ACPI_ALL_DRIVERS" +debug.acpi.level="ACPI_LV_ALL_EXCEPTIONS" +.Ed +.Pp +Debugging output by the ACPI CA subsystem is prefixed with the +module name in lowercase, followed by a source line number. +Output from the +.Fx Ns -local +code follows the same format, but +the module name is uppercased. +.Sh OVERRIDING YOUR BIOS BYTECODE +ACPI interprets bytecode named AML +(ACPI Machine Language) +provided by the BIOS vendor as a memory image at boot time. +Sometimes, the AML code contains a bug that does not appear when parsed +by the Microsoft implementation. +.Fx +provides a way to override it with your own AML code to work around +or debug such problems. +Note that all AML in your DSDT and any SSDT tables is overridden. +.Pp +In order to load your AML code, you must edit +.Pa /boot/loader.conf +and include the following lines. +.Bd -literal -offset indent +acpi_dsdt_load="YES" +acpi_dsdt_name="/boot/acpi_dsdt.aml" # You may change this name. +.Ed +.Pp +In order to prepare your AML code, you will need the +.Xr acpidump 8 +and +.Xr iasl 8 +utilities and some ACPI knowledge. +.Sh COMPATIBILITY +ACPI is only found and supported on i386/ia32 and amd64. +.Sh SEE ALSO +.Xr kenv 1 , +.Xr acpi_thermal 4 , +.Xr device.hints 5 , +.Xr loader.conf 5 , +.Xr acpiconf 8 , +.Xr acpidump 8 , +.Xr config 8 , +.Xr iasl 8 +.Rs +.%A "Compaq Computer Corporation" +.%A "Intel Corporation" +.%A "Microsoft Corporation" +.%A "Phoenix Technologies Ltd." +.%A "Toshiba Corporation" +.%D August 25, 2003 +.%T "Advanced Configuration and Power Interface Specification" +.%U http://acpi.info/spec.htm +.Re +.Sh AUTHORS +.An -nosplit +The ACPI CA subsystem is developed and maintained by +Intel Architecture Labs. +.Pp +The following people made notable contributions to the ACPI subsystem +in +.Fx : +.An Michael Smith , +.An Takanori Watanabe Aq Mt takawata@jp.FreeBSD.org , +.An Mitsuru IWASAKI Aq Mt iwasaki@jp.FreeBSD.org , +.An Munehiro Matsuda , +.An Nate Lawson , +the ACPI-jp mailing list at +.Aq Mt acpi-jp@jp.FreeBSD.org , +and many other contributors. +.Pp +This manual page was written by +.An Michael Smith Aq Mt msmith@FreeBSD.org . +.Sh BUGS +Many BIOS versions have serious bugs that may cause system instability, +break suspend/resume, or prevent devices from operating properly due to +IRQ routing problems. +Upgrade your BIOS to the latest version available from the vendor before +deciding it is a problem with +.Nm . diff --git a/static/freebsd/man4/acpi_asus.4 b/static/freebsd/man4/acpi_asus.4 new file mode 100644 index 00000000..25c1df95 --- /dev/null +++ b/static/freebsd/man4/acpi_asus.4 @@ -0,0 +1,185 @@ +.\" +.\" Copyright (c) 2004 Philip Paeps +.\" 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 February 8, 2010 +.Dt ACPI_ASUS 4 +.Os +.Sh NAME +.Nm acpi_asus +.Nd Asus Laptop Extras +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device acpi_asus" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +acpi_asus_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the extra ACPI-controlled gadgets, such as hotkeys +and leds, found on recent Asus (and Medion) laptops. +It allows one to use the +.Xr sysctl 8 +interface to manipulate the brightness of the LCD panel and the display output +state. +Hotkey events are passed to +.Xr devd 8 +for easy handling in userspace with the default configuration in +.Pa /etc/devd/asus.conf . +.Pp +Currently, the following Asus laptops are fully supported: +.Pp +.Bl -item -offset indent -compact +.It +xxN +.It +A1x +.It +A2x +.It +A3N +.It +A4D +.It +A6VM +.It +D1x +.It +J1x +.It +L2B +.It +L2D +.It +L2E +.It +L3C +.It +L3D +.It +L3H +.It +L4E +.It +L4R +.It +L5x +.It +L8x +.It +M1A +.It +M2E +.It +M6N +.It +M6R +.It +S1x +.It +S2x +.It +V6V +.It +W5A +.It +Eee PC +.El +.Pp +Additionally, +.Nm +also supports the Asus-compatible +.Em ATK0100 +interface found in +.Em Samsung P30/P35 +laptops. +.Sh SYSCTL VARIABLES +The following sysctls are currently implemented: +.Bl -tag -width indent +.It Va hw.acpi.asus.lcd_brightness +Makes the LCD backlight brighter or dimmer (higher values are brighter). +.It Va hw.acpi.asus.lcd_backlight +Turns the LCD backlight on or off. +.It Va hw.acpi.asus.video_output +Sets the active display to use according to a bitwise OR of the following: +.Pp +.Bl -tag -width indent -compact +.It Li 0 +No display +.It Li 1 +LCD +.It Li 2 +CRT +.It Li 4 +TV-Out +.El +.Pp +Some models also support video switching via the generic +.Xr acpi_video 4 +driver. +Most models do not, however. +.El +.Pp +Defaults for these variables can be set in +.Xr sysctl.conf 5 , +which is parsed at boot-time. +.Sh SEE ALSO +.Xr acpi 4 , +.Xr acpi_asus_wmi 4 , +.Xr acpi_video 4 , +.Xr sysctl.conf 5 , +.Xr sysctl 8 +.Rs +.%T The acpi4asus Project +.%U http://sourceforge.net/projects/acpi4asus/ +.Re +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 5.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver and this manual page were written by +.An Philip Paeps Aq Mt philip@FreeBSD.org . +.Pp +Inspiration came from the +.Em acpi4asus project +started by +.An Julien Lerouge +which maintains a driver implementing this +functionality in the +.Tn Linux +kernel. diff --git a/static/freebsd/man4/acpi_asus_wmi.4 b/static/freebsd/man4/acpi_asus_wmi.4 new file mode 100644 index 00000000..721b7383 --- /dev/null +++ b/static/freebsd/man4/acpi_asus_wmi.4 @@ -0,0 +1,96 @@ +.\" +.\" Copyright (c) 2012 Alexander Motin +.\" 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 March 25, 2024 +.Dt ACPI_ASUS_WMI 4 +.Os +.Sh NAME +.Nm acpi_asus_wmi +.Nd Asus Laptop WMI Extras +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device acpi_asus_wmi" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +acpi_asus_wmi_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the extra WMI-controlled gadgets, such as hotkeys +and leds, found on Asus laptops. +It allows one to use the +.Xr sysctl 8 +interface to manipulate the brightness of the LCD panel and keyboard backlight, +power on/off different internal components, such as WiFi, Bluetooth, camera, +cardreader, etc, read some sensors. +Hotkey events are passed to +.Xr devd 8 +for easy handling in userspace with the default configuration in +.Pa /etc/devd/asus.conf . +Some hotkey events, such as keyboard backlight and touchpad control, are +handled inside the driver. +.Sh SYSCTL VARIABLES +The following sysctls are currently implemented: +.Bl -tag -width indent +.It Va dev.acpi_asus_wmi.0.handle_keys +Specifies whether driver should handle some hardware keys, such as keyboard +backlight, internally. +.El +.Pp +Number of other variables under the same sysctl branch are model-specific. +.Pp +Defaults for these variables can be set in +.Xr sysctl.conf 5 , +which is parsed at boot-time. +.Sh FILES +.Bl -tag -width "/dev/backlight/acpi_asus_wmi0" -compact +.It Pa /dev/backlight/acpi_asus_wmi0 +Keyboard +.Xr backlight 8 +device node. +.El +.Sh SEE ALSO +.Xr acpi 4 , +.Xr acpi_asus 4 , +.Xr acpi_video 4 , +.Xr sysctl.conf 5 , +.Xr backlight 8 , +.Xr devd 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 10.0 . +.Sh AUTHORS +.An Alexander Motin Aq Mt mav@FreeBSD.org diff --git a/static/freebsd/man4/acpi_battery.4 b/static/freebsd/man4/acpi_battery.4 new file mode 100644 index 00000000..49fed625 --- /dev/null +++ b/static/freebsd/man4/acpi_battery.4 @@ -0,0 +1,378 @@ +.\" +.\" Copyright (c) 2019 Takanori Watanabe +.\" 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 February 16, 2020 +.Dt ACPI_BATTERY 4 +.Os +.Sh NAME +.Nm acpi_battery +.Nd ACPI battery management subsystem +.Sh SYNOPSIS +.Cd "device acpi" +.Sh DESCRIPTION +The +.Nm +is a driver for battery management features of the ACPI module. +.Pp +An ACPI-compatible battery device supports either a Control +Method Battery interface or a Smart Battery subsystem interface. +The former is accessed by the AML +.Pq ACPI Machine Language +code control methods, +and the latter is controlled directly through the ACPI EC +.Pq Embedded Controller +typically via an SMBus interface. +.Pp +This driver supports the +.Xr sysctl 8 +and +.Xr ioctl 2 +interfaces as well as the +.Xr devd 8 +event notification interface. +.Sh IOCTLS +Every ioctl for the +.Nm +driver takes a single integer value for the battery unit +number as an argument, +and returns a specific structure for each request. +A special unit number +.Dv ACPI_BATTERY_ALL_UNITS +specifies all of the attached units +and reports accumulated information. +.Bl -tag -width indent +.It Dv ACPIIO_BATT_GET_UNITS Vt int +Returns the number of battery units in the system. +The unit number argument will be ignored. +.It Dv ACPIIO_BATT_GET_BATTINFO Vt struct acpi_battinfo +Returns the following: +.Bl -tag -width indent +.It Va cap +Battery capacity in percent, +.It Va min +Remaining battery life in minutes, +.It Va state +Current status of the battery encoded in the following: +.Bl -tag -width indent +.It Dv ACPI_BATT_STAT_DISCHARG Pq 0x0001 +Battery is discharging, +.It Dv ACPI_BATT_STAT_CHARGING Pq 0x0002 +Battery is being charged, or +.It Dv ACPI_BATT_STAT_CRITICAL Pq 0x0004 +Remaining battery life is critically low. +.El +.Pp +Note that the status bits of each battery will be +consolidated when +.Dv ACPI_BATTERY_ALL_UNITS +is specified. +.It Va rate +Current battery discharging rate in mW. +.Li -1 +means not discharging right now. +.El +.It Dv ACPIIO_BATT_GET_BIX Vt struct acpi_bix +Returns battery information given by the ACPI +.Li _BIX Pq Battery Information +object, +which is the static portion of the Control Method +Battery information. +In the case of a Smart Battery attached to +SMBus or a Control Method Battery with a +.Li _BIF +object, +this ioctl will build a +.Vt struct acpi_bix +structure based on the obtained information +and return it. +.Bl -tag -width indent +.It Va rev +Revision number of the object. +There are the following well-known values: +.Bl -tag -width indent +.It Dv ACPI_BIX_REV_0 Pq 0x0000 +A +.Li _BIX +object in ACPI 4.0. +.It Dv ACPI_BIX_REV_1 Pq 0x0001 +A +.Li _BIX +object in ACPI 6.0. +.It Dv ACPI_BIX_REV_BIF Pq 0xffff +A +.Li _BIX +object built from the +.Li _BIF +object found on the system. +.El +.Pp +Note that this field should be checked by using +.Fn ACPI_BIX_REV_MIN_CHECK var rev +macro when checking the minimum revision number. +.It Va units +Indicates the units used by the battery to report its +capacity and charge rate encoded in the following: +.Bl -tag -width indent +.It ACPI_BIX_UNITS_MW Pq 0x00000000 +in mW +.Pq power +.It ACPI_BIX_UNITS_MA Pq 0x00000001 +in mA +.Pq current +.El +.Pp +Note that capacity is expressed in mWh or mAh, +and rate is expressed in mW or mA, +respectively. +.It Va dcap +The Battery's design capacity, +which is the nominal capacity of a new battery. +This is expressed as power or current depending on +the value of +.Va units . +.It Va lfcap +Predicted battery capacity when fully charged. +Typically this will decrease every charging cycle. +.It btech +Battery technology: +.Bl -tag -width indent +.It 0x00000000 Primary cell Pq non-rechargeable +.It 0x00000001 Secondary cell Pq rechargeable +.El +.It Va dvol +Design voltage in mV, +which is the nominal voltage of a new battery. +.It Va wcap +Design capacity of warning. +When a discharging battery device reaches this capacity, +notification is sent to the system. +.It Va lcap +Design capacity of low. +.It Va cycles +.Pq rev 0 or newer +The number of cycles the battery has experienced. +A cycle means an amount of discharge occurred which was +approximately equal to the value of Design Capacity. +.It Va accuracy +.Pq rev 0 or newer +The accuracy of the battery capacity measurement, +in thousandth of a percent. +.It Va stmax +.Pq rev 0 or newer +The Maximum Sampling Time of the battery in +milliseconds. +This is the maximum duration between two consecutive +measurements of the battery's capacities specified in +.Li _BST . +If two succeeding readings of +.Li _BST +beyond this duration occur, +two different results can be returned. +.It Va stmin +.Pq rev 0 or newer +The Minimum Sampling Time of the battery in +milliseconds. +.It Va aimax +.Pq rev 0 or newer +The Maximum Average Interval of the battery in +milliseconds. +This is the length of time within which the battery +averages the capacity measurements specified in +.Li _BST . +The Sampling Time specifies the frequency of measurements, +and the Average Interval specifies the width of the time +window of every measurement. +.It Va aimin +.Pq rev 0 or newer +The Minimum Average Interval of the battery in +milliseconds. +.It Va gra1 +Battery capacity granularity between +.Va low +and +.Va warning . +This is expressed as power or current depending on +the value of +.Va units . +.It Va gra2 +Battery capacity granularity between +.Va warning +and +.Va full . +This is expressed as power or current depending on +the value of +.Va units . +.It Va model +Model number of the battery as a string. +.It Va serial +Serial number of the battery as a string. +.It Va type +Type identifier of the battery as a string. +.It Va oeminfo +OEM-specific information of the battery as a string. +.It Va scap +.Pq rev 1 or newer +Battery swapping capability encoded in the following: +.Bl -tag -width indent +.It ACPI_BIX_SCAP_NO Pq 0x00000000 +Non-swappable +.It ACPI_BIX_SCAP_COLD Pq 0x00000001 +Cold-swappable +.It ACPI_BIX_SCAP_HOT Pq 0x00000010 +Hot-swappable +.El +.El +.It Dv ACPIIO_BATT_GET_BIF Vt struct acpi_bif +.Pq deprecated +Returns battery information given by the ACPI +.Li _BIF Pq Battery Information +object, +which was deprecated in ACPI 4.0 specification. +The data structure is a subset of +.Vt struct acpi_bix . +.Pp +Note that this ioctl will built a +.Vt struct acpi_bif +structure based on the obtained information +even if this object is not available and a +.Li _BIX +object is found. +.It ACPIIO_BATT_GET_BST Vt struct acpi_bst +Returns battery information given by the ACPI +.Li _BST Pq Battery Status +object, +which is the present battery status. +In the case of a Smart Battery attached to SMBus, +this ioctl will build a +.Vt struct acpi_bst +structure based on the obtained information +and return it. +.Bl -tag -width indent +.It Va state +Battery state. +The value is encoded in the same way as +.Va state +of +.Vt struct acpi_battinfo . +.It Va rate +Battery present rate of charging or discharging. +The unit of the value depends on +.Va unit +of +.Vt struct acpi_bif . +.It Va cap +Battery remaining capacity. +The unit of this value depends on +.Va unit +of +.Vt struct acpi_bif . +.It Va volt +Battery present voltage. +.El +.El +.Sh SYSCTL VARIABLES +The following +.Xr sysctl 8 +variables export battery status. +Note that they are accumulated status of all of the +connected batteries: +.Bl -tag -width indent +.It Va hw.acpi.battery.info_expire +Information cache expiration time in seconds. +The battery information obtained by +.Li _BIX +or +.Li _BIF +object will be stored and reused for successive +read access to this MIB within the specified period. +.It Va hw.acpi.battery.units +Number of battery units in the system. +.It Va hw.acpi.battery.state +Current battery charging status. +This is same as +.Va state +of +.Vt struct acpi_battinfo . +.It Va hw.acpi.battery.rate +Current battery discharging rate in mW. +.It Va hw.acpi.battery.time +Remaining battery life in minutes. +If the battery is not discharging, +the value shows +.Li -1 . +.It Va hw.acpi.battery.life +Battery capacity in percent. +.El +.Sh EVENT NOTIFICATIONS +Battery-related event notifications are sent +to the userland via the +.Xr devd 8 +interface. +See +.Pa /etc/devd.conf +and +.Xr devd.conf 5 +for more details. +Note that notifications are supported only by +the Control Method Battery. +.Pp +The +.Nm +driver sends events with the following attributes: +.Pp +.Bl -tag -width "subsystem" -compact +.It system +.Li ACPI +.It subsystem +.Li CMBAT +.It type +The fully qualified battery object path as in the ASL. +.It notify +An integer designating the event: +.Pp +.Bl -tag -width indent -compact +.It Li 0x80 +Battery status was changed. +.It Li 0x81 +Battery information was changed. +.El +.El +.Sh SEE ALSO +.Xr acpi 4 , +.Xr acpiconf 8 +.Sh AUTHORS +.An -nosplit +.An Nate Lawson Aq Mt njl@FreeBSD.org , +.An Munehiro Matsuda , +.An Takanori Watanabe Aq Mt takawata@FreeBSD.org , +.An Mitsuru IWASAKI Aq Mt iwasaki@FreeBSD.org , +.An Hans Petter Selasky Aq Mt hselasky@FreeBSD.org , +and +.An Hiroki Sato Aq Mt hrs@FreeBSD.org . +.Pp +This manual page was written by +.An Takanori Watanabe Aq Mt takawata@FreeBSD.org +and +.An Hiroki Sato Aq Mt hrs@FreeBSD.org . diff --git a/static/freebsd/man4/acpi_dock.4 b/static/freebsd/man4/acpi_dock.4 new file mode 100644 index 00000000..b2c58627 --- /dev/null +++ b/static/freebsd/man4/acpi_dock.4 @@ -0,0 +1,60 @@ +.\" Copyright (c) 2006 Christian Brueffer +.\" 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 May 20, 2006 +.Dt ACPI_DOCK 4 +.Os +.Sh NAME +.Nm acpi_dock +.Nd "Laptop Docking Station device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device acpi_dock" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +acpi_dock_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for laptop docking stations. +.Sh SEE ALSO +.Xr acpi 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 7.0 . +.Sh AUTHORS +The +.Nm +device driver was written by +.An Mitsuru IWASAKI Aq Mt iwasaki@FreeBSD.org . diff --git a/static/freebsd/man4/acpi_fujitsu.4 b/static/freebsd/man4/acpi_fujitsu.4 new file mode 100644 index 00000000..da74e671 --- /dev/null +++ b/static/freebsd/man4/acpi_fujitsu.4 @@ -0,0 +1,173 @@ +.\" +.\" Copyright (c) 2005 Philip Paeps +.\" 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 February 8, 2010 +.Dt ACPI_FUJITSU 4 +.Os +.Sh NAME +.Nm acpi_fujitsu +.Nd Fujitsu Laptop Extras +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device acpi_fujitsu" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +acpi_fujitsu_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver enables the ACPI-controlled buttons on Fujitsu notebooks. +The button events are sent to userspace via +.Xr devd 8 , +and a +.Xr sysctl 8 +interface is provided to simulate the hardware events. +.Pp +Using this driver, one can control the brightness of the display, the volume +of the speakers, and the internal (eraserhead) mouse pointer. +.Sh SYSCTL VARIABLES +These sysctls are currently implemented: +.Bl -tag -width indent +.It Va hw.acpi.fujitsu.lcd_brightness +Makes the LCD backlight brighter or dimmer. +.It Va hw.acpi.fujitsu.pointer_enable +Enables or disables the internal mouse pointer. +.It Va hw.acpi.fujitsu.volume +Controls the speaker volume. +.It Va hw.acpi.fujitsu.mute +Mutes the speakers. +.El +.Pp +Defaults for these sysctls can be set in +.Xr sysctl.conf 5 . +.Sh EXAMPLES +The following can be added to +.Xr devd.conf 5 +in order to pass button events to a +.Pa /usr/local/sbin/acpi_oem_exec.sh +script: +.Bd -literal -offset indent +notify 10 { + match "system" "ACPI"; + match "subsystem" "FUJITSU"; + action "/usr/local/sbin/acpi_oem_exec.sh $notify fujitsu"; +}; +.Ed +.Pp +A possible +.Pa /usr/local/sbin/acpi_oem_exec.sh +script might look like: +.Bd -literal -offset indent +#!/bin/sh +# +if [ "$1" = "" -o "$2" = "" ] +then + echo "usage: $0 notify oem_name" + exit 1 +fi +NOTIFY=`echo $1` +LOGGER="logger" +CALC="bc" +BC_PRECOMMANDS="scale=2" +ECHO="echo" +CUT="cut" +MAX_LCD_BRIGHTNESS=7 +MAX_VOLUME=16 +OEM=$2 +DISPLAY_PIPE=/tmp/acpi_${OEM}_display + +case ${NOTIFY} in + 0x00) + LEVEL=`sysctl -n hw.acpi.${OEM}.mute` + if [ "$LEVEL" = "1" ] + then + MESSAGE="volume muted" + else + MESSAGE="volume unmuted" + fi + ;; + 0x01) + LEVEL=`sysctl -n hw.acpi.${OEM}.pointer_enable` + if [ "$LEVEL" = "1" ] + then + MESSAGE="pointer enabled" + else + MESSAGE="pointer disabled" + fi + ;; + 0x02) + LEVEL=`sysctl -n hw.acpi.${OEM}.lcd_brightness` + PERCENT=`${ECHO} "${BC_PRECOMMANDS} ; \\ + ${LEVEL} / ${MAX_LCD_BRIGHTNESS} * 100" |\\ + ${CALC} | ${CUT} -d . -f 1` + MESSAGE="brightness level ${PERCENT}%" + ;; + 0x03) + LEVEL=`sysctl -n hw.acpi.${OEM}.volume` + PERCENT=`${ECHO} "${BC_PRECOMMANDS} ; \\ + ${LEVEL} / ${MAX_VOLUME} * 100" | \\ + ${CALC} | ${CUT} -d . -f 1` + MESSAGE="volume level ${PERCENT}%" + ;; + *) + ;; + esac + ${LOGGER} ${MESSAGE} + if [ -p ${DISPLAY_PIPE} ] + then + ${ECHO} ${MESSAGE} >> ${DISPLAY_PIPE} & + fi +exit 0 +.Ed +.Sh SEE ALSO +.Xr acpi 4 , +.Xr sysctl.conf 5 , +.Xr devd 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 5.4 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Sean Bullington Aq Mt shegget@gmail.com , +.An Anish Mistry Aq Mt mistry.7@osu.edu , +and +.An Marc Santcroos Aq Mt marks@ripe.net . +.Pp +This manual page was written by +.An Philip Paeps Aq Mt philip@FreeBSD.org . diff --git a/static/freebsd/man4/acpi_ged.4 b/static/freebsd/man4/acpi_ged.4 new file mode 100644 index 00000000..98baabdd --- /dev/null +++ b/static/freebsd/man4/acpi_ged.4 @@ -0,0 +1,62 @@ +.\" Copyright (c) 2022 Takanori Watanabe +.\" +.\" 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 October 18, 2022 +.Dt ACPI_GED 4 +.Os +.Sh NAME +.Nm acpi_ged +.Nd "ACPI Generic Event Device" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device acpi_ged" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +acpi_ged_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for generic events interface. +This handles interrupts and evaluates the specific ACPI method. +This may generate optionally ACPI notify for another device. +.Sh SEE ALSO +.Xr acpi 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 13.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Takanori Watanabe Aq Mt takawata@FreeBSD.org diff --git a/static/freebsd/man4/acpi_hp.4 b/static/freebsd/man4/acpi_hp.4 new file mode 100644 index 00000000..660d66f5 --- /dev/null +++ b/static/freebsd/man4/acpi_hp.4 @@ -0,0 +1,286 @@ +.\" Copyright (c) 2009 Michael Gmelin +.\" 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 June 19, 2015 +.Dt ACPI_HP 4 +.Os +.Sh NAME +.Nm acpi_hp +.Nd "ACPI extras driver for HP laptops" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device acpi_hp" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +acpi_hp_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for ACPI-controlled features found on HP laptops +that use a WMI enabled BIOS (e.g., HP Compaq 8510p and 6510p). +.Pp +The main purpose of this driver is to provide an interface, +accessible via +.Xr sysctl 8 , +.Xr devd 8 and +.Xr devfs 8 , +through which applications can determine and change the status of +various laptop components and BIOS settings. +.Ss Xr devd 8 Events +Devd events received by +.Xr devd 8 +provide the following information: +.Pp +.Bl -tag -width "subsystem" -offset indent -compact +.It system +.Qq Li ACPI +.It subsystem +.Qq Li HP +.It type +The source of the event in the ACPI namespace. +The value depends on the model. +.It notify +Event code (see below). +.El +.Pp +Event codes: +.Pp +.Bl -tag -width "0xc0" -offset indent -compact +.It Li 0xc0 +WLAN on air status changed to 0 (not on air) +.It Li 0xc1 +WLAN on air status changed to 1 (on air) +.It Li 0xd0 +Bluetooth on air status changed to 0 (not on air) +.It Li 0xd1 +Bluetooth on air status changed to 1 (on air) +.It Li 0xe0 +WWAN on air status changed to 0 (not on air) +.It Li 0xe1 +WWAN on air status changed to 1 (on air) +.El +.Ss Xr devfs 8 Device +You can read /dev/hpcmi to see your current BIOS settings. +The detail level can be adjusted by setting the sysctl +.Va cmi_detail +as described below. +.Sh SYSCTL VARIABLES +The following sysctls are currently implemented: +.Ss WLAN: +.Bl -tag -width indent +.It Va dev.acpi_hp.0.wlan_enabled +Toggle WLAN chip activity. +.It Va dev.acpi_hp.0.wlan_radio +(read-only) +WLAN radio status (controlled by hardware switch) +.It Va dev.acpi_hp.0.wlan_on_air +(read-only) +WLAN on air (chip enabled, hardware switch enabled + enabled in BIOS) +.It Va dev.acpi_hp.0.wlan_enabled_if_radio_on +If set to 1, the WLAN chip will be enabled if the radio is turned on +.It Va dev.acpi_hp.0.wlan_disable_if_radio_off +If set to 1, the WLAN chip will be disabled if the radio is turned off +.El +.Ss Bluetooth: +.Bl -tag -width indent +.It Va dev.acpi_hp.0.bt_enabled +Toggle Bluetooth chip activity. +.It Va dev.acpi_hp.0.bt_radio +(read-only) +Bluetooth radio status (controlled by hardware switch) +.It Va dev.acpi_hp.0.bt_on_air +(read-only) +Bluetooth on air (chip enabled, hardware switch enabled + enabled in BIOS) +.It Va dev.acpi_hp.0.bt_enabled_if_radio_on +If set to 1, the Bluetooth chip will be enabled if the radio is turned on +.It Va dev.acpi_hp.0.bt_disable_if_radio_off +If set to 1, the Bluetooth chip will be disabled if the radio is turned off +.El +.Ss WWAN: +.Bl -tag -width indent +.It Va dev.acpi_hp.0.wwan_enabled +Toggle WWAN chip activity. +.It Va dev.acpi_hp.0.wwan_radio +(read-only) +WWAN radio status (controlled by hardware switch) +.It Va dev.acpi_hp.0.wwan_on_air +(read-only) +WWAN on air (chip enabled, hardware switch enabled + enabled in BIOS) +.It Va dev.acpi_hp.0.wwan_enabled_if_radio_on +If set to 1, the WWAN chip will be enabled if the radio is turned on +.It Va dev.acpi_hp.0.wwan_disable_if_radio_off +If set to 1, the WWAN chip will be disabled if the radio is turned off +.El +.Ss Misc: +.Bl -tag -width indent +.It Va dev.acpi_hp.0.als_enabled +Toggle ambient light sensor (ALS) +.It Va dev.acpi_hp.0.display +(read-only) +Display status (bitmask) +.It Va dev.acpi_hp.0.hdd_temperature +(read-only) +HDD temperature +.It Va dev.acpi_hp.0.is_docked +(read-only) +Docking station status (1 if docked) +.It Va dev.acpi_hp.0.cmi_detail +Bitmask to control detail level in /dev/hpcmi output (values can be ORed). +.Bl -tag -width "0x01" -offset indent -compact +.It Li 0x01 +Show path component of BIOS setting +.It Li 0x02 +Show a list of valid options for the BIOS setting +.It Li 0x04 +Show additional flags of BIOS setting (ReadOnly etc.) +.It Li 0x08 +Query highest BIOS entry instance. +This is broken on many HP models and therefore disabled by default. +.El +.It Va dev.acpi_hp.0.verbose +(read-only) +Set verbosity level +.El +.Pp +Defaults for these sysctls can be set in +.Xr sysctl.conf 5 . +.Sh HARDWARE +The +.Nm +driver has been reported to support the following hardware: +.Pp +.Bl -bullet -compact +.It +HP Compaq 8510p +.It +HP Compaq nx7300 +.El +.Pp +It should work on most HP laptops that feature a WMI enabled BIOS. +.Sh FILES +.Bl -tag -width ".Pa /dev/hpcmi" +.It Pa /dev/hpcmi +Interface to read BIOS settings +.El +.Sh EXAMPLES +The following can be added to +.Xr devd.conf 5 +in order disable the LAN interface when WLAN on air and reenable if it is not: +.Bd -literal -offset indent +notify 0 { + match "system" "ACPI"; + match "subsystem" "HP"; + match "notify" "0xc0"; + action "ifconfig em0 up"; +}; + +notify 0 { + match "system" "ACPI"; + match "subsystem" "HP"; + match "notify" "0xc1"; + action "ifconfig em0 down"; +}; +.Ed +.Pp +Enable the ambient light sensor: +.Bd -literal -offset indent +sysctl dev.acpi_hp.0.als_enabled=1 +.Ed +.Pp +Enable Bluetooth: +.Bd -literal -offset indent +sysctl dev.acpi_hp.0.bt_enabled=1 +.Ed +.Pp +Get BIOS settings: +.Bd -literal -offset indent +cat /dev/hpcmi + +Serial Port Disable +Infrared Port Enable +Parallel Port Disable +Flash Media Reader Disable +USB Ports including Express Card slot Enable +1394 Port Enable +Cardbus Slot Disable +Express Card Slot Disable +(...) +.Ed +.Pp +Set maximum detail level for /dev/hpcmi output: +.Bd -literal -offset indent +sysctl dev.acpi_hp.0.cmi_detail=7 +.Ed +.Sh SEE ALSO +.Xr acpi 4 , +.Xr acpi_wmi 4 , +.Xr sysctl.conf 5 , +.Xr devd 8 , +.Xr devfs 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 8.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Michael Gmelin Aq Mt freebsd@grem.de . +.Pp +It has been inspired by hp-wmi driver, which implements a subset of these +features (hotkeys) on Linux. +.Bl -tag -width indent +.It HP CMI whitepaper: +https://h20331.www2.hp.com/Hpsub/downloads/cmi_whitepaper.pdf +.It wmi-hp for Linux: +https://www.kernel.org +.It WMI and ACPI: +http://www.microsoft.com/whdc/system/pnppwr/wmi/wmi-acpi.mspx +.El +.Pp +This manual page was written by +.An Michael Gmelin Aq Mt freebsd@grem.de . +.Sh BUGS +This driver is experimental and has only been tested on i386 on an +HP Compaq 8510p which featured all supported wireless devices (WWAN/BT/WLAN). +Expect undefined results when operating on different hardware. +.Pp +Loading the driver is slow. +Reading from +.Pa /dev/hpcmi +is even slower. +.Pp +Additional features like HP specific sensor readings or writing BIOS +settings are not supported. diff --git a/static/freebsd/man4/acpi_ibm.4 b/static/freebsd/man4/acpi_ibm.4 new file mode 100644 index 00000000..6b808b77 --- /dev/null +++ b/static/freebsd/man4/acpi_ibm.4 @@ -0,0 +1,504 @@ +.\" Copyright (c) 2005 Christian Brueffer +.\" Copyright (c) 2005 Markus Brueffer +.\" 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 March 13, 2022 +.Dt ACPI_IBM 4 +.Os +.Sh NAME +.Nm acpi_ibm +.Nd "ThinkPad ACPI extras driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device acpi_ibm" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +acpi_ibm_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for hotkeys and other components of ThinkPad laptops. +The main purpose of this driver is to provide an interface, +accessible via +.Xr sysctl 8 +and +.Xr devd 8 , +through which applications can determine the status of +various laptop components. +.Pp +While the +.Xr sysctl 8 +interface is enabled automatically after loading the driver, the +.Xr devd 8 +interface has to be enabled explicitly, as it may alter the default action of +certain keys. +This is done by setting the +.Va events +sysctl as described below. +Specifying which keys should generate events is done by setting a bitmask, +whereas each bit represents one key or key combination. +This bitmask, accessible via the +.Va eventmask +sysctl, is set to +.Va availmask +by default, a value representing all possible keypress events on the specific +ThinkPad model. +.Ss Xr devd 8 Events +Hotkey events received by +.Xr devd 8 +provide the following information: +.Pp +.Bl -tag -width "subsystem" -offset indent -compact +.It system +.Qq Li ACPI +.It subsystem +.Qq Li IBM +.It type +The source of the event in the ACPI namespace. +The value depends on the model. +.It notify +Event code (see below). +.El +.Pp +Depending on the ThinkPad model, event codes may vary. +On a ThinkPad T41p these are as follows: +.Pp +.Bl -tag -width "subsystem" -offset indent -compact +.It Li 0x01 +Fn + F1 +.It Li 0x02 +Fn + F2 +.It Li 0x03 +Fn + F3 (LCD backlight) +.It Li 0x04 +Fn + F4 (Suspend to RAM) +.It Li 0x05 +Fn + F5 (Bluetooth) +.It Li 0x06 +Fn + F6 +.It Li 0x07 +Fn + F7 (Screen expand) +.It Li 0x08 +Fn + F8 +.It Li 0x09 +Fn + F9 +.It Li 0x0a +Fn + F10 +.It Li 0x0b +Fn + F11 +.It Li 0x0c +Fn + F12 (Suspend to disk) +.It Li 0x0d +Fn + Backspace +.It Li 0x0e +Fn + Insert +.It Li 0x0f +Fn + Delete +.It Li 0x10 +Fn + Home (Brightness up) +.It Li 0x11 +Fn + End (Brightness down) +.It Li 0x12 +Fn + PageUp (ThinkLight) +.It Li 0x13 +Fn + PageDown +.It Li 0x14 +Fn + Space (Zoom) +.It Li 0x15 +Volume Up +.It Li 0x16 +Volume Down +.It Li 0x17 +Mute +.It Li 0x18 +Access IBM Button +.El +.Ss Xr led 4 Interface +The +.Nm +driver provides a +.Xr led 4 +interface for the ThinkLight. +The ThinkLight can be made to blink by writing +.Tn ASCII +strings to the +.Pa /dev/led/thinklight +device. +.Sh SYSCTL VARIABLES +The following sysctls are currently implemented: +.Bl -tag -width indent +.It Va dev.acpi_ibm.0.initialmask +(read-only) +Bitmask of ACPI events before the +.Nm +driver was loaded. +.It Va dev.acpi_ibm.0.availmask +(read-only) +Bitmask of all supported ACPI events. +.It Va dev.acpi_ibm.0.events +Enable ACPI events and set the +.Va eventmask +to +.Va availmask . +Without the +.Nm +driver being loaded, only the Fn+F4 button generates an ACPI event. +.It Va dev.acpi_ibm.0.eventmask +Sets the ACPI events which are reported to +.Xr devd 8 . +Fn+F3, Fn+F4 and Fn+F12 always generate ACPI events, regardless which value +.Va eventmask +has. +Depending on the ThinkPad model, the meaning of different bits in the +.Va eventmask +may vary. +On a ThinkPad T41p this is a bitwise OR of the following: +.Pp +.Bl -tag -width indent-two -compact +.It Li 1 +Fn + F1 +.It Li 2 +Fn + F2 +.It Li 4 +Fn + F3 (LCD backlight) +.It Li 8 +Fn + F4 (Suspend to RAM) +.It Li 16 +Fn + F5 (Bluetooth) +.It Li 32 +Fn + F6 +.It Li 64 +Fn + F7 (Screen expand) +.It Li 128 +Fn + F8 +.It Li 256 +Fn + F9 +.It Li 512 +Fn + F10 +.It Li 1024 +Fn + F11 +.It Li 2048 +Fn + F12 (Suspend to disk) +.It Li 4096 +Fn + Backspace +.It Li 8192 +Fn + Insert +.It Li 16384 +Fn + Delete +.It Li 32768 +Fn + Home (Brightness up) +.It Li 65536 +Fn + End (Brightness down) +.It Li 131072 +Fn + PageUp (ThinkLight) +.It Li 262144 +Fn + PageDown +.It Li 524288 +Fn + Space (Zoom) +.It Li 1048576 +Volume Up +.It Li 2097152 +Volume Down +.It Li 4194304 +Mute +.It Li 8388608 +Access IBM Button +.El +.It Va dev.acpi_ibm.0.hotkey +(read-only) +Status of several buttons. +Every time a button is pressed, the respecting bit is toggled. +It is a bitwise OR of the following: +.Pp +.Bl -tag -width indent-two -compact +.It Li 1 +Home Button +.It Li 2 +Search Button +.It Li 4 +Mail Button +.It Li 8 +Access IBM Button +.It Li 16 +Zoom +.It Li 32 +Wireless LAN Button +.It Li 64 +Video Button +.It Li 128 +Hibernate Button +.It Li 256 +ThinkLight Button +.It Li 512 +Screen Expand +.It Li 1024 +Brightness Up/Down Button +.It Li 2048 +Volume Up/Down/Mute Button +.El +.It Va dev.acpi_ibm.0.lcd_brightness +Current brightness level of the display. +.It Va dev.acpi_ibm.0.volume +Speaker volume. +.It Va dev.acpi_ibm.0.mute +Indicates, whether the speakers are muted or not. +.It Va dev.acpi_ibm.0.mic_mute +Indicates, whether the microphone led (present on some model) is on or not. +Note that this does not mean that the microphone input is muted. +.It Va dev.acpi_ibm.0.thinklight +Indicates, whether the ThinkLight keyboard light is activated or not. +.It Va dev.acpi_ibm.0.bluetooth +Toggle Bluetooth chip activity. +.It Va dev.acpi_ibm.0.wlan +(read-only) +Indicates whether the WLAN chip is active or not. +.It Va dev.acpi_ibm.0.fan +Indicates whether the fan is in automatic (1) or manual (0) mode. +Default is automatic mode. +This sysctl should be used with extreme precaution, since disabling automatic +fan control might overheat the ThinkPad and lead to permanent damage if the +.Va fan_level +is not set accordingly. +.It Va dev.acpi_ibm.0.fan_level +Indicates at what speed the fan should run when being in manual mode. +Valid values range from 0 (off) to 7 (max) and 8. +Level 8 is used by the driver to set the fan in unthrottled mode. +In this mode, the fan is set to spin freely and will quickly reach a very +high speed. +Use this mode only if absolutely necessary, e.g., if the system has reached its +critical temperature and it is about to shut down. +The resulting speed differs from model to model. +On a T41p this is as follows: +.Pp +.Bl -tag -width indent-two -compact +.It Li 0 +off +.It Li 1, 2 +~3000 RPM +.It Li 3, 4, 5 +~3600 RPM +.It Li 6, 7 +~4300 RPM +.It Li 8 +~6400 RPM (Full-speed, unthrottled) +.El +.It Va dev.acpi_ibm.0.fan_speed +(read-only) +Fan speed in rounds per minute. +A few older ThinkPads report the fan speed in levels ranging from 0 (off) +to 7 (max). +.It Va dev.acpi_ibm.0.thermal +(read-only) +Shows the readings of up to eight different temperature sensors. +Most ThinkPads include six or more temperature sensors but +only expose the CPU temperature through +.Xr acpi_thermal 4 . +Some ThinkPads have the below sensor layout which might vary depending on the +specific model: +.Pp +.Bl -enum -compact +.It +CPU +.It +Mini PCI Module +.It +HDD +.It +GPU +.It +Built-in battery +.It +UltraBay battery +.It +Built-in battery +.It +UltraBay battery +.El +.It Va dev.acpi_ibm.0.handlerevents +.Xr devd 8 +events handled by +.Nm +when +.Va events +is set to 1. +Events are specified as a whitespace-separated list of event code in +hexadecimal or decimal form. +Note that the event maybe handled twice (e.g., Brightness up/down) if ACPI BIOS +already handled the event. +.El +.Pp +Defaults for these sysctls can be set in +.Xr sysctl.conf 5 . +.Sh FILES +.Bl -tag -width ".Pa /dev/led/thinklight" +.It Pa /dev/led/thinklight +ThinkLight +.Xr led 4 +device node +.El +.Sh EXAMPLES +The following can be added to +.Xr devd.conf 5 +in order to pass button events to a +.Pa /usr/local/sbin/acpi_oem_exec.sh +script: +.Bd -literal -offset indent +notify 10 { + match "system" "ACPI"; + match "subsystem" "IBM"; + action "/usr/local/sbin/acpi_oem_exec.sh $notify ibm"; +}; +.Ed +.Pp +A possible +.Pa /usr/local/sbin/acpi_oem_exec.sh +script might look like: +.Bd -literal -offset indent +#!/bin/sh +# +if [ "$1" = "" -o "$2" = "" ] +then + echo "usage: $0 notify oem_name" + exit 1 +fi +NOTIFY=`echo $1` +LOGGER="logger" +CALC="bc" +BC_PRECOMMANDS="scale=2" +ECHO="echo" +CUT="cut" +MAX_LCD_BRIGHTNESS=7 +MAX_VOLUME=14 +OEM=$2 +DISPLAY_PIPE=/tmp/acpi_${OEM}_display + +case ${NOTIFY} in + 0x05) + LEVEL=`sysctl -n dev.acpi_${OEM}.0.bluetooth` + if [ "$LEVEL" = "1" ] + then + sysctl dev.acpi_${OEM}.0.bluetooth=0 + MESSAGE="bluetooth disabled" + else + sysctl dev.acpi_${OEM}.0.bluetooth=1 + MESSAGE="bluetooth enabled" + fi + ;; + 0x10|0x11) + LEVEL=`sysctl -n dev.acpi_${OEM}.0.lcd_brightness` + PERCENT=`${ECHO} "${BC_PRECOMMANDS} ; \\ + ${LEVEL} / ${MAX_LCD_BRIGHTNESS} * 100" |\\ + ${CALC} | ${CUT} -d . -f 1` + MESSAGE="brightness level ${PERCENT}%" + ;; + 0x12) + LEVEL=`sysctl -n dev.acpi_${OEM}.0.thinklight` + if [ "$LEVEL" = "1" ] + then + MESSAGE="thinklight enabled" + else + MESSAGE="thinklight disabled" + fi + ;; + 0x15|0x16) + LEVEL=`sysctl -n dev.acpi_${OEM}.0.volume` + PERCENT=`${ECHO} "${BC_PRECOMMANDS} ; \\ + ${LEVEL} / ${MAX_VOLUME} * 100" | \\ + ${CALC} | ${CUT} -d . -f 1` + MESSAGE="volume level ${PERCENT}%" + ;; + 0x17) + LEVEL=`sysctl -n dev.acpi_${OEM}.0.mute` + if [ "$LEVEL" = "1" ] + then + MESSAGE="volume muted" + else + MESSAGE="volume unmuted" + fi + ;; + 0x1b) + LEVEL=`sysctl -n dev.acpi_ibm.0.mic_led` + if [ $LEVEL -eq 0 ]; then + sysctl dev.acpi_ibm.0.mic_led=1 + mixer rec.volume=0 + fi + if [ $LEVEL -eq 1 ]; then + sysctl dev.acpi_ibm.0.mic_led=0 + mixer rec.volume=30% + fi + ;; + *) + ;; +esac +${LOGGER} ${MESSAGE} +if [ -p ${DISPLAY_PIPE} ] +then + ${ECHO} ${MESSAGE} >> ${DISPLAY_PIPE} & +fi +exit 0 +.Ed +.Pp +The following example specify that event code 0x04 (Suspend to RAM), +0x10 (Brightness up) and 0x11 (Brightness down) are handled by +.Nm . +.Bd -literal -offset indent +sysctl dev.acpi_ibm.0.handlerevents='0x04 0x10 0x11' +.Ed +.Pp +in +.Xr sysctl.conf 5 : +.Bd -literal -offset indent +dev.acpi_ibm.0.handlerevents=0x04\\ 0x10\\ 0x11 +.Ed +.Sh SEE ALSO +.Xr acpi 4 , +.Xr led 4 , +.Xr sysctl.conf 5 , +.Xr devd 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 6.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Takanori Watanabe Aq Mt takawata@FreeBSD.org +and later mostly rewritten by +.An Markus Brueffer Aq Mt markus@FreeBSD.org . +This manual page was written by +.An Christian Brueffer Aq Mt brueffer@FreeBSD.org +and +.An Markus Brueffer Aq Mt markus@FreeBSD.org . diff --git a/static/freebsd/man4/acpi_panasonic.4 b/static/freebsd/man4/acpi_panasonic.4 new file mode 100644 index 00000000..de9663b5 --- /dev/null +++ b/static/freebsd/man4/acpi_panasonic.4 @@ -0,0 +1,176 @@ +.\" +.\" Copyright (c) 2004 OGAWA Takaya +.\" 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 June 19, 2015 +.Dt ACPI_PANASONIC 4 +.Os +.Sh NAME +.Nm acpi_panasonic +.Nd "ACPI hotkey driver for Panasonic laptops" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device acpi_panasonic" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +acpi_panasonic_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver enables such hotkey facilities of various Panasonic laptops as +changing LCD brightness, controlling mixer volumes, entering sleep or +suspended state and so on. +On the following models it is reported to work: Let's note (or +Toughbook, outside Japan) CF-R1N, CF-R2A and CF-R3. +It may also work on other models as well. +.Pp +The driver consists of three functionalities. +The first is to detect hotkey events and take corresponding actions, +which include changing LCD luminance and speaker mute state. +The second role is to notify occurrences of the event by way of +.Xr devctl 4 +and eventually to +.Xr devd 8 . +The third and last is to provide a way to adjust LCD brightness and +sound mute state via +.Xr sysctl 8 . +.Ss Hotkeys +There are 9 hotkeys available on the supported hardware: +.Pp +.Bl -tag -width 10n -compact -offset indent +.It Sy Fn+F1 +Make LCD backlight darker. +.It Sy Fn+F2 +Make LCD backlight brighter. +.It Sy Fn+F3 +Switch video output between LCD and CRT. +Not supported by the +.Nm +driver. +.It Sy Fn+F4 +Toggle muting the speaker. +.It Sy Fn+F5 +Turn the mixer volume down. +.It Sy Fn+F6 +Turn the mixer volume up. +.It Sy Fn+F7 +Enter suspend-to-RAM state. +.It Sy Fn+F9 +Show battery status. +.It Sy Fn+F10 +Enter suspend-to-disk state. +.El +.Pp +Actions are automatically taken within the driver for +.Sy Fn+F1 , Fn+F2 +and +.Sy Fn+F4 . +For the other events such as +mixer control and showing battery status, +.Xr devd 8 +should take the role as described below. +.Ss Xr devd 8 Events +When notified to +.Xr devd 8 , +the hotkey event provides the following information: +.Pp +.Bl -tag -width 10n -compact -offset indent +.It system +.Qq Li ACPI +.It subsystem +.Qq Li Panasonic +.It type +The source of the event in ACPI namespace. +The value depends on the model but typically +.Qq Li \e_SB_.HKEY . +.It notify +Event code (see below). +.El +.Pp +Event codes to be generated are assigned as follows: +.Bl -tag -width 10n -offset indent +.It 0x81-0x86, 0x89 +.Sy Fn+F +pressed. +0x81 corresponds to +.Sy Fn+F1 , +0x82 corresponds to +.Sy Fn+F2 , +and so on. +.It 0x01-0x07, 0x09, 0x1a +.Sy Fn+F +released. +0x01 corresponds to +.Sy Fn+F1 , +0x02 corresponds to +.Sy Fn+F2 , +and so on. +.El +.Sh SYSCTL VARIABLES +The following MIBs are available: +.Bl -tag -width indent +.It Va hw.acpi.panasonic.lcd_brightness_max +The maximum level of brightness. +This read-only value is +automatically set according to hardware model. +.It Va hw.acpi.panasonic.lcd_brightness_min +The minimum level of brightness. +This read-only value is +automatically set according to hardware model. +.It Va hw.acpi.panasonic.lcd_brightness +Current brightness level of the LCD (read-write). +The value ranges from +.Va hw.acpi.panasonic.lcd_brightness_min +to +.Va hw.acpi.panasonic.lcd_brightness_max . +.It Va hw.acpi.panasonic.sound_mute +A read-write boolean flag to control whether to mute the speaker. +The value 1 means to mute and 0 not. +.El +.Sh SEE ALSO +.Xr acpi 4 , +.Xr devd.conf 5 , +.Xr devd 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 5.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver and this manual page were written by +.An OGAWA Takaya Aq Mt t-ogawa@triaez.kaisei.org +and +.An TAKAHASHI Yoshihiro Aq Mt nyan@FreeBSD.org . diff --git a/static/freebsd/man4/acpi_rapidstart.4 b/static/freebsd/man4/acpi_rapidstart.4 new file mode 100644 index 00000000..606a55d2 --- /dev/null +++ b/static/freebsd/man4/acpi_rapidstart.4 @@ -0,0 +1,82 @@ +.\" Copyright (c) 2013 Takanori Watanabe +.\" 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 May 8, 2013 +.Dt ACPI_RAPIDSTART 4 +.Os +.Sh NAME +.Nm acpi_rapidstart +.Nd "Intel rapid start technology ACPI driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device acpi_rapidstart" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +acpi_rapidstart_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for Intel Rapid Start technology ACPI device interface. +Note that this is only for the ACPI device interface. +This has _CID PNP0C02 so it should be loaded at boot time to avoid attaching +to the acpi_sysresource driver. +.Sh SYSCTLS +The following +.Xr sysctl 8 +nodes are currently implemented: +.Bl -tag -width indent +.It Va dev.acpi_rapidstart.0.ffs +Rapid start flag. +It is a bitwise OR of the following: +.Pp +.Bl -tag -width indent-two -compact +.It Li 1 +Enter Fast Flash Standby in RTC wake. +.It Li 2 +Enter Fast Flash Standby in Critical Battery Wake enable +.El +.It Va dev.acpi_rapidstart.0.ftv +Fast Flash Standby timer value in minutes. +.El +.Sh SEE ALSO +.Xr acpi 4 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 10.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Takanori Watanabe Aq Mt takawata@FreeBSD.org . diff --git a/static/freebsd/man4/acpi_sony.4 b/static/freebsd/man4/acpi_sony.4 new file mode 100644 index 00000000..33c988fb --- /dev/null +++ b/static/freebsd/man4/acpi_sony.4 @@ -0,0 +1,80 @@ +.\" Copyright (c) 2005 Christian Brueffer +.\" 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 February 8, 2010 +.Dt ACPI_SONY 4 +.Os +.Sh NAME +.Nm acpi_sony +.Nd "ACPI notebook controller driver for Sony laptops" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device acpi_sony" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +acpi_sony_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the notebook controller in Sony laptops. +Note that not all features will work on all laptop models. +.Sh SYSCTLS +The following sysctl nodes are currently implemented: +.Bl -tag -width indent +.It Va dev.acpi_sony.0.brightness +Current brightness level of the display. +.It Va dev.acpi_sony.0.brightness_default +Default brightness level of the display (survives reboot). +.It Va dev.acpi_sony.0.contrast +Current contrast level of the display. +.It Va dev.acpi_sony.0.bass_gain +Enable or disable the Bass Gain feature. +.It Va dev.acpi_sony.0.cdp +Turns the CD power on or off. +.It Va dev.acpi_sony.0.azp +Turns the audio power on or off. +.It Va dev.acpi_sony.0.lnp +Turns the wired network interface power on or off. +.El +.Sh SEE ALSO +.Xr acpi 4 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 6.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Takanori Watanabe Aq Mt takawata@FreeBSD.org . diff --git a/static/freebsd/man4/acpi_thermal.4 b/static/freebsd/man4/acpi_thermal.4 new file mode 100644 index 00000000..86efaafe --- /dev/null +++ b/static/freebsd/man4/acpi_thermal.4 @@ -0,0 +1,150 @@ +.\" Copyright (c) 2003 Takanori Watanabe. +.\" 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 November 21, 2022 +.Dt ACPI_THERMAL 4 +.Os +.Sh NAME +.Nm acpi_thermal +.Nd ACPI thermal management subsystem +.Sh SYNOPSIS +.Cd "device acpi" +.Sh DESCRIPTION +The +.Nm +driver provides the thermal management features of the ACPI module. +This driver has a +.Xr sysctl 8 +interface and a +.Xr devd 8 +notification interface. +The sysctls export properties of each ACPI thermal zone object. +.Pp +There can be multiple thermal zones in a system. +For example, each CPU and the enclosure could all be separate thermal +zones, each with its own setpoints and cooling devices. +Thermal zones are numbered sequentially in the order they appear in +the AML. +.Pp +The +.Nm +driver also activates the active cooling system according to +each thermal zone's setpoints. +.Sh SYSCTL VARIABLES +.Bl -tag -width indent +.It Va hw.acpi.thermal.min_runtime +Number of seconds to continue active cooling once started. +A new active cooling level will not be selected until this interval expires. +.It Va hw.acpi.thermal.polling_rate +Number of seconds between polling the current temperature. +.It Va hw.acpi.thermal.user_override +If set to 1, allow user override of various setpoints (below). +The original values for these settings are obtained from the BIOS and +system overheating and possible damage could occur if changed. +Default is 0 (no override). +.It Va hw.acpi.thermal.tz%d.active +Current active cooling system state. +If this is non-negative, the appropriate _AC%d object is running. +Set this value to the desired active cooling level to force +the corresponding fan object to the appropriate level. +.It Va hw.acpi.thermal.tz%d.passive_cooling +If set to 1, passive cooling is enabled. +It does cooling without fans using +.Xr cpufreq 4 +as the mechanism for controlling CPU speed. +Default is enabled for tz0 where it is available. +.It Va hw.acpi.thermal.tz%d.thermal_flags +Current thermal zone status. +These are bit-masked values. +.It Va hw.acpi.thermal.tz%d.temperature +Current temperature for this zone. +.It Va hw.acpi.thermal.tz%d._PSV +Temperature to start passive cooling by throttling down CPU, etc. +This value can be overridden by the user. +.It Va hw.acpi.thermal.tz%d._CR3 +Temperature to start critical suspend to RAM (S3). +This value can be overridden by the user. +.It Va hw.acpi.thermal.tz%d._HOT +Temperature to start critical suspend to disk (S4). +This value can be overridden by the user. +.It Va hw.acpi.thermal.tz%d._CRT +Temperature to start critical shutdown (S5). +This value can be overridden by the user. +.It Va hw.acpi.thermal.tz%d._ACx +Temperatures at which to switch to the corresponding active cooling +level. +The lower the _ACx value, the higher the cooling power. +.El +.Pp +All temperatures are printed in Celsius. +Values can be set in Celsius (by providing a trailing +.Qq C ) +or Kelvin (by leaving off any trailing letter). +When setting a value by +.Xr sysctl 8 , +do not specify a trailing decimal (i.e., 90C instead of 90.0C). +.Sh NOTIFIES +Notifies are passed to userland via +.Xr devd 8 . +See +.Pa /etc/devd.conf +and +.Xr devd.conf 5 +for examples. +The +.Nm +driver sends events with the following attributes: +.Pp +.Bl -tag -width "subsystem" -compact +.It system +.Li ACPI +.It subsystem +.Li Thermal +.It type +The fully qualified thermal zone object path as in the ASL. +.It notify +An integer designating the event: +.Pp +.Bl -tag -width indent -compact +.It Li 0x80 +Current temperature has changed. +.It Li 0x81 +One or more trip points (_ACx, _PSV) have changed. +.It Li 0x82 +One or more device lists (_ALx, _PSL, _TZD) have changed. +.It Li 0xcc +Non-standard notify that the system will shutdown if the temperature +stays above _CRT or _HOT for one more poll cycle. +.El +.El +.Sh SEE ALSO +.Xr acpi 4 , +.Xr cpufreq 4 , +.Xr acpidump 8 +.Sh AUTHORS +.An -nosplit +.An Michael Smith +.Pp +This manual page was written by +.An Takanori Watanabe . diff --git a/static/freebsd/man4/acpi_toshiba.4 b/static/freebsd/man4/acpi_toshiba.4 new file mode 100644 index 00000000..0d8514eb --- /dev/null +++ b/static/freebsd/man4/acpi_toshiba.4 @@ -0,0 +1,126 @@ +.\" +.\" Copyright (c) 2003 Philip Paeps +.\" 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 February 8, 2010 +.Dt ACPI_TOSHIBA 4 +.Os +.Sh NAME +.Nm acpi_toshiba +.Nd Toshiba HCI interface +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device acpi_toshiba" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +acpi_toshiba_load="YES" +.Ed +.Sh DESCRIPTION +HCI is Toshiba's +.Em "Hardware Control Interface" +which is somewhat uniform across their models. +The +.Nm +driver allows the user to manipulate HCI-controlled hardware using a number of +.Xr sysctl 8 +variables. +.Sh SYSCTL VARIABLES +The following sysctls are currently implemented: +.Bl -tag -width indent +.It Va hw.acpi.toshiba.force_fan +Causes active cooling to be forcibly enabled +.Pq Ql 1 +or disabled +.Pq Ql 0 +regardless of the current temperature. +.It Va hw.acpi.toshiba.video_output +Sets the active display to use according to a bitwise OR of the following: +.Pp +.Bl -tag -width indent -compact +.It Li 0 +No display +.It Li 1 +LCD +.It Li 2 +CRT +.It Li 4 +TV-Out +.El +.Pp +Only some systems (i.e., the Libretto L5) support video switching via +this hardware-specific driver. +Use the +.Xr acpi_video 4 +driver for generic video output support. +.It Va hw.acpi.toshiba.lcd_brightness +Makes the LCD backlight brighter or dimmer (higher values are brighter). +.It Va hw.acpi.toshiba.lcd_backlight +Turns the LCD backlight on and off. +.It Va hw.acpi.toshiba.cpu_speed +Sets the CPU speed to the specified speed. +This provides functionality similar to the +.Va hw.acpi.cpu.throttle_state +variable. +Higher sysctl values mean lower CPU speeds. +.El +.Pp +Defaults for these variables can be set in +.Xr sysctl.conf 5 , +which is parsed at boot-time. +.Sh LOADER TUNABLES +The +.Va hw.acpi.toshiba.enable_fn_keys +tunable enables or disables the function keys on the keyboard. +Function keys are enabled by default. +.Pp +This behaviour can be changed at the +.Xr loader 8 +prompt or in +.Xr loader.conf 5 . +.Sh SEE ALSO +.Xr acpi 4 , +.Xr acpi_video 4 , +.Xr loader.conf 5 , +.Xr sysctl.conf 5 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 5.1 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Hiroyuki Aizu Aq Mt aizu@navi.org . +This manual page was written by +.An Philip Paeps Aq Mt philip@FreeBSD.org . diff --git a/static/freebsd/man4/acpi_video.4 b/static/freebsd/man4/acpi_video.4 new file mode 100644 index 00000000..c51c3ff1 --- /dev/null +++ b/static/freebsd/man4/acpi_video.4 @@ -0,0 +1,96 @@ +.\" +.\" Copyright (c) 2004 Mark Santcroos +.\" 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 November 8, 2004 +.Dt ACPI_VIDEO 4 +.Os +.Sh NAME +.Nm acpi_video +.Nd ACPI Video Extensions driver +.Sh SYNOPSIS +.Cd "device acpi_video" +.Sh DESCRIPTION +This driver uses the ACPI Video Extensions to control display switching and +backlight brightness. +The availability of the +.Xr sysctl 8 +variables depends on the functions offered by the host's ACPI implementation. +.Sh SYSCTL VARIABLES +The following sysctls are currently implemented, +where +.Aq Ar device +is +.Va crt , lcd , +or +.Va tv : +.Bl -tag -width indent +.It Va hw.acpi.video. Ns Ao Ar device Ac Ns Va .active +Current state of the output device. +.It Va hw.acpi.video. Ns Ao Ar device Ac Ns Va .levels +List of supported brightness levels. +.It Va hw.acpi.video. Ns Ao Ar device Ac Ns Va .brightness +Current brightness level of the device. +.It Va hw.acpi.video. Ns Ao Ar device Ac Ns Va .fullpower +Preset brightness level to be used in full power mode. +.It Va hw.acpi.video. Ns Ao Ar device Ac Ns Va .economy +Preset brightness level to be used in economy mode. +.El +.Pp +Defaults for these variables can be set in +.Xr sysctl.conf 5 , +which is parsed at boot-time. +.Sh COMPATIBILITY +In order for +.Nm +to attach correctly, +.Nm +should be loaded after any of the DRM kernel modules. +This can be achieved by setting the correct order in +.Xr rc.conf 5 +using the kld_list directive. +.Sh SEE ALSO +.Xr acpi 4 , +.Xr loader.conf 5 , +.Xr sysctl.conf 5 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 5.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Taku YAMAMOTO Aq Mt taku@cent.saitama-u.ac.jp . +This manual page was written by +.An Mark Santcroos Aq Mt marks@ripe.net . +.Sh BUGS +Some systems only perform output switching via SMM even though they export +the proper information via ACPI. +On such systems, the proper hotkeys or OEM driver (for example, +.Xr acpi_toshiba 4 ) +must be used instead. diff --git a/static/freebsd/man4/acpi_wmi.4 b/static/freebsd/man4/acpi_wmi.4 new file mode 100644 index 00000000..e5c5517b --- /dev/null +++ b/static/freebsd/man4/acpi_wmi.4 @@ -0,0 +1,132 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2009 Michael Gmelin +.\" 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 June 12, 2025 +.Dt ACPI_WMI 4 +.Os +.Sh NAME +.Nm acpi_wmi +.Nd ACPI to WMI mapping driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Pp +.Dl Cd "device acpi_wmi" +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Pp +.Dl acpi_wmi_load="YES" +.Sh DESCRIPTION +The +.Nm +driver provides an interface for vendor specific WMI implementations +.Pq e.g. HP and Acer laptops . +It creates +.Pa /dev/wmistat%d , +which can be read to get information about GUIDs found in the system. +.Sh FILES +.Bl -tag -width /dev/wmistat%d -compact +.It Pa /dev/wmistat%d +WMI status devices. +.El +.Sh SYSCTLS +The following sysctl node is currently implemented: +.Bl -tag -width "dev.acpi_wmi.%d.bmof" +.It Va dev.acpi_wmi.%d.bmof +binary Managed Object Format (MOF) buffer +.El +.Sh EXAMPLES +Read GUIDs from the first WMI interface found in the system: +.Bd -literal +# cat /dev/wmistat0 +GUID INST EXPE METH STR EVENT OID +{5FB7F034-2C63-45E9-BE91-3D44E2C707E4} 1 NO WMAA NO NO AA +{95F24279-4D7B-4334-9387-ACCDC67EF61C} 1 NO NO NO 0x80+ - +{2B814318-4BE8-4707-9D84-A190A859B5D0} 1 NO NO NO 0xA0 - +{05901221-D566-11D1-B2F0-00A0C9062910} 1 NO NO NO NO AB +{1F4C91EB-DC5C-460B-951D-C7CB9B4B8D5E} 1 NO WMBA NO NO BA +{2D114B49-2DFB-4130-B8FE-4A3C09E75133} 57 NO NO NO NO BC +{988D08E3-68F4-4C35-AF3E-6A1B8106F83C} 20 NO NO NO NO BD +{14EA9746-CE1F-4098-A0E0-7045CB4DA745} 1 NO NO NO NO BE +{322F2028-0F84-4901-988E-015176049E2D} 2 NO NO NO NO BF +{8232DE3D-663D-4327-A8F4-E293ADB9BF05} 0 NO NO NO NO BG +{8F1F6436-9F42-42C8-BADC-0E9424F20C9A} 0 NO NO NO NO BH +{8F1F6435-9F42-42C8-BADC-0E9424F20C9A} 0 NO NO NO NO BI +.Ed +.Pp +Read first WMI interface description with +.Sy bmf2mof +from +.Pa ports/converters/bmfdec : +.Bd -literal +# sysctl -b dev.acpi_wmi.0.bmof | bmf2mof +[abstract] +class Lenovo_BIOSElement { +}; + +[WMI, Dynamic, Provider("WMIProv"), WmiExpense(1), Description("Bios Setting"), +GUID("{51F5230E-9677-46cd-A1CF-C0B23EE34DB7}"), Locale("MS\\0x409")] +class Lenovo_BiosSetting : Lenovo_BiosElement { + [key, read] String InstanceName; + [read] Boolean Active; + [WmiDataId(1), Description("BIOS setting")] String CurrentSetting; + }; + ... +.Ed +.Sh SEE ALSO +.Xr acpi 4 +.Sh STANDARDS +.Rs +.%T Windows Instrumentation: WMI and ACPI +.%I Microsoft Corporation +.%U https://github.com/microsoft/Windows-driver-samples/tree/main/wmi/wmiacpi +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 8.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Michael Gmelin Aq Mt freebsd@grem.de . +.Pp +Work inspired by the Linux +.Sy acpi-wmi +driver written by Carlos Corbacho. +.Pp +MOF handling inspired by the Linux +.Sy wmi-bmof +driver written by Andy Lutomirski. +.Pp +This manual page was written by +.An Michael Gmelin Aq Mt freebsd@grem.de . diff --git a/static/freebsd/man4/ada.4 b/static/freebsd/man4/ada.4 new file mode 100644 index 00000000..6536be44 --- /dev/null +++ b/static/freebsd/man4/ada.4 @@ -0,0 +1,166 @@ +.\" Copyright (c) 2009 Alexander Motin +.\" 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 December 20, 2017 +.Dt ADA 4 +.Os +.Sh NAME +.Nm ada +.Nd ATA Direct Access device driver +.Sh SYNOPSIS +.Cd device ada +.Sh DESCRIPTION +The +.Nm +driver provides support for direct access devices, implementing the +.Tn ATA +command protocol, that are attached to the system through a host adapter +supported by the CAM subsystem. +.Pp +The host adapter must also be separately configured into the system before an +.Tn ATA +direct access device can be configured. +.Sh COMMAND QUEUING +Command queuing allows the device to process multiple transactions +concurrently, often re-ordering them to reduce the number and length of +seeks. +.Tn ATA +defines two types of queuing: +.Tn TCQ (Tagged Command Queuing, PATA legacy) +and +.Tn NCQ (Native Command Queuing, SATA) . +The +.Nm +device driver takes full advantage of NCQ, when supported. +To ensure that transactions to distant parts of the media, +which may be deferred indefinitely by servicing requests closer to the current +head position, are completed in a timely fashion, an ordered +transaction is sent every 7 seconds during continuous device operation. +.Sh CACHE EFFECTS +Many direct access devices are equipped with read and/or write caches. +Parameters affecting the device's cache are reported in device IDENTIFY data +and can be examined and modified via the +.Xr camcontrol 8 +utility. +.Pp +The read cache is used to store data from device-initiated read ahead +operations as well as frequently used data. +The read cache is transparent +to the user and can be enabled without any adverse effect. +Most devices +with a read cache come from the factory with it enabled. +.Pp +The write cache can greatly decrease the latency of write operations +and allows the device to reorganize writes to increase efficiency and +performance. +This performance gain comes at a price. +Should the device +lose power while its cache contains uncommitted write operations, these +writes will be lost. +The effect of a loss of write transactions on +a file system is non-deterministic and can cause corruption. +Most +devices age write transactions to limit the vulnerability to a few transactions +recently reported as complete, but it is nonetheless recommended that +systems with write cache enabled devices reside on an Uninterruptible +Power Supply (UPS). +The +.Nm +device driver ensures that the cache and media are synchronized upon +final close of the device or an unexpected shutdown (panic) event. +This ensures that it is safe to disconnect power once the operating system +has reported that it has halted. +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width 12 +.It Va kern.cam.ada.retry_count +.Pp +This variable determines how many times the +.Nm +driver will retry a READ or WRITE command. +This does not affect the number of retries used during probe time or for +the +.Nm +driver dump routine. +This value currently defaults to 4. +.It Va kern.cam.ada.default_timeout +.Pp +This variable determines how long the +.Nm +driver will wait before timing out an outstanding command. +The units for this value are seconds, and the default is currently 30 +seconds. +.It Va kern.cam.ada.spindown_shutdown +.Pp +This variable determines whether to spin-down disks when shutting down. +Set to 1 to enable spin-down, 0 to disable. +The default is currently enabled. +.It Va kern.cam.sort_io_queue +.It Va kern.cam.ada. Ns Ar X Ns Va .sort_io_queue +.Pp +These variables determine whether request queue should be sorted trying +to optimize head seeks. +Set to 1 to enable sorting, 0 to disable, -1 to leave it as-is. +The default is sorting enabled for HDDs and disabled SSDs. +.It Va kern.cam.ada.read_ahead +.It Va kern.cam.ada. Ns Ar X Ns Va .read_ahead +.It Va kern.cam.ada.write_cache +.It Va kern.cam.ada. Ns Ar X Ns Va .write_cache +.Pp +These variables determine whether device read-ahead and write caches +should be enabled globally or per-device or disabled. +Set to 1 to enable write cache, 0 to disable, -1 to leave it as-is. +Values modified at runtime take effect only after device reset +.Pq using the reset subcommand of Xr camcontrol 8 . +Because of that, this setting should be changed in +.Pa /boot/loader.conf +instead of +.Pa /etc/sysctl.conf . +The global default is currently 1. +The per-device default is to leave it as-is (follow global setting). +.El +.Sh FILES +.Bl -tag -width ".Pa /dev/ada*" -compact +.It Pa /dev/ada* +ATA device nodes +.El +.Sh SEE ALSO +.Xr ahci 4 , +.Xr cam 4 , +.Xr da 4 , +.Xr mvs 4 , +.Xr nda 4 , +.Xr siis 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 8.0 . +.Sh AUTHORS +.An Alexander Motin Aq Mt mav@FreeBSD.org diff --git a/static/freebsd/man4/adm6996fc.4 b/static/freebsd/man4/adm6996fc.4 new file mode 100644 index 00000000..af9d19b8 --- /dev/null +++ b/static/freebsd/man4/adm6996fc.4 @@ -0,0 +1,66 @@ +.\"- +.\" Copyright (c) 2017 Hiroki Mori +.\" 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 April 5, 2017 +.Dt ADM6996FC 4 +.Os +.Sh NAME +.Nm adm6996fc +.Nd driver for Infineon ADM6996FC fast ethernet switch chip +.Sh SYNOPSIS +.Cd "device mdio" +.Cd "device etherswitch" +.Cd "device adm6996fc" +.Pp +.Cd hint.adm6996fc.0.at="mdio0" +.Sh DESCRIPTION +The +.Nm +device driver provides a management interface to Infineon ADM6996FC fast ethernet switch chip. +This driver use smi interface by ethernet interface. +.Pp +This driver support is port and dot1q vlan. +dot1q support port base tag/untag. +.Sh EXAMPLES +Configure dot1q vlan by etherswitchcfg command. +.Pp +.Dl # etherswitchcfg config vlan_mode dot1q +.Pp +Configure port 5 is tagging port. +.Pp +.Dl # etherswitchcfg port5 addtag +.Sh SEE ALSO +.Xr etherswitch 4 , +.Xr etherswitchcfg 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 12.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Hiroki Mori diff --git a/static/freebsd/man4/ads111x.4 b/static/freebsd/man4/ads111x.4 new file mode 100644 index 00000000..03468a44 --- /dev/null +++ b/static/freebsd/man4/ads111x.4 @@ -0,0 +1,239 @@ +.\" +.\" Copyright (c) 2019 Ian Lepore +.\" +.\" 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 ``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 September 2, 2019 +.Dt ADS111x 4 +.Os +.Sh NAME +.Nm ads111x +.Nd driver for ADS101x and ADS111x i2c analog to digital converters +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ads111x" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ads111x_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the ADS101x/ADS111x family of analog +to digital converter (ADC) devices. +The supported devices are all similar to each other, varying in +features such as resolution and number of input channels. +The devices offer a number of configuration options which can be +set via hints, FDT data, and +.Xr sysctl 8 . +.Pp +The +.Xr sysctl 8 +utility provides access to the voltage measurements made by the device. +Each time the +.Va dev.ads111x...voltage +variable is accessed for a given channel, the driver switches the +chip's internal mux to choose the right input pins for that channel, +directs it to make a single measurement, and returns the measured value +in microvolts. +The amount of time required to make the measurement is a function +of the sampling rate configured for the device. +While device is directed to make a single measurement, it still averages +the input values for the same amount of time as it would to emit one +sample if it were in continuous mode. +For example, if the sample rate were configured as 125 samples per +second, a single measurement would require 8 milliseconds. +.Pp +For devices that support multiple input pins, the device datasheet +describes mux settings to control how those pins are interpreted when +making either single-ended or differential measurements. +There are eight possible ways to combine the inputs from the four pins. +The +.Nm +driver models that by creating a separate output channel for each of +the eight combinations. +To make a measurement on a given pin or pair of pins, you simply access +the voltage variable for the channel number that corresponds the mux +setting number (0 through 7) shown in the datasheet. +When the driver is configured with hints or FDT data, it creates +sysctl variables for just the channels specified in the config data. +When there is no channel config data, it creates all eight possible +channels so that you can access whichever one(s) you need. +.Pp +For devices that include an +.Va alert +output pin, the +.Nm +driver does not directly support the pin in terms of sensing or +acting on changes in the pin state. +However, you may connect the pin to a gpio input or fan controller +or other external device, and use the driver's sysctl variables to +configure behavior and threshold values for the pin. +The driver avoids perturbing your settings as it does other +manipulations to the config register. +.Sh SYSCTL VARIABLES +Sysctl variables are used to access the voltage measurements, and to +change the configuration of the channels. +All writeable variables may also be set as +.Xr loader 8 +tunables. +Channel numbers in these sysctl variables range from 0 through 7. +.Bl -tag -width indent +.It Va dev.ads111x..config +Provides access to the configuration register bits that control the +alert pin configuration. +Other bits which are controlled by the driver are masked out, and +cannot be viewed or changed using this variable. +.It Va dev.ads111x..lo_thresh +Sets the low threshold for activating the alert pin. +.It Va dev.ads111x..hi_thresh +Sets the high threshold for activating the alert pin. +.It Va dev.ads111x...rate_index +Sets the sample rate for the channel. +The device datasheet documents eight available sample rates, chosen +by setting a value of 0 through 7 into the corresponding control +register bits. +This variable sets the value used for those bits when making a +measurement on the given channel. +.Pp +Because measurements are always made in single-shot mode, think of +this variable as controlling the averaging time for a single sample; +the time to make a measurement is 1 / samplerate. +.It Va dev.ads111x...gain_index +Sets the programmable gain amplifier for the channel on devices +which have an internal amplifier. +The device datasheet documents eight available gain values, chosen +by setting a value of 0 through 7 into the corresponding control +register bits. +This variable sets the value used for those bits when making a +measurement on the given channel. +.It Va dev.ads111x...voltage +Reading this variable causes the device to make a measurement on +the corresponding input pin(s) and return the voltage in microvolts. +.Pp +Note that this variable does not appear when you list multiple +sysctl variables -- you must access it specifically by name, because +accessing it triggers device I/O. +.El +.Sh HARDWARE +The +.Nm +driver provides support for the following devices: +.Pp +.Bl -column -compact -offset indent "XXXXXXXX" "XXXXXXXX" +.It ADS1013 Ta ADS1113 +.It ADS1014 Ta ADS1114 +.It ADS1015 Ta ADS1115 +.El +.Sh FDT CONFIGURATION +On an +.Xr fdt 4 +based system, the +.Nm +device is defined as a slave device subnode +of the i2c bus controller node. +All properties documented in the +.Va ads1015.txt +bindings document can be used with the +.Nm +device. +.Pp +The following properties are required in the +.Nm +device subnode: +.Bl -tag -width indent +.It Va compatible +One of the following: +.Bl -column -compact -offset indent ".Dq ti,ads1013" ".Dq ti,ads1113" +.It Dq ti,ads1013 Ta Dq ti,ads1113 +.It Dq ti,ads1014 Ta Dq ti,ads1114 +.It Dq ti,ads1015 Ta Dq ti,ads1115 +.El +.It Va reg +I2c slave address of device. +.El +.Pp +Specific channels can be configured by adding child nodes to the +.Nm +node, as described in the standard ads1015.txt bindings document. +If no channels are configured, sysctl variables will be created +for all possible channels supported by the device type, otherwise +only the specified channels are created. +.Ss Example including channel configuration +.Bd -unfilled -offset indent +adc@48 { + compatible = "ti,ads1115"; + reg = <0x48>; + status = "okay"; + #address-cells = <1>; + #size-cells = <0>; + + channel@6 { + reg = <6>; + ti,gain = <3>; + ti,datarate = <4>; + }; + channel@7 { + reg = <7>; + ti,gain = <1>; + ti,datarate = <7>; + }; +}; +.Ed +.Sh HINTS CONFIGURATION +On a +.Xr device.hints 5 +based system, such as +.Li MIPS , +these values are configurable for +.Nm : +.Bl -tag -width indent +.It Va hint.ads111x..at +The iicbus instance the +.Nm +instance is attached to. +.It Va hint.ads111x...gain_index +The amplifier gain, as described above for the sysctl variable +.Va dev.ads111x...gain_index . +.It Va hint.ads111x...rate_index +The sample rate, as described above for the sysctl variable +.Va dev.ads111x...rate_index . +.El +.Pp +If no channels are configured, sysctl variables will be created +for all possible channels supported by the device type, otherwise +only the specified channels are created. +.Sh SEE ALSO +.Xr fdt 4 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 13.0 . diff --git a/static/freebsd/man4/ae.4 b/static/freebsd/man4/ae.4 new file mode 100644 index 00000000..a871986b --- /dev/null +++ b/static/freebsd/man4/ae.4 @@ -0,0 +1,149 @@ +.\" Copyright (c) 2008 Stanislav Sedov +.\" 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 May 17, 2019 +.Dt AE 4 +.Os +.Sh NAME +.Nm ae +.Nd "Attansic/Atheros L2 FastEthernet controller driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device ae" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_ae_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +device driver provides support for Attansic/Atheros L2 PCIe FastEthernet +controllers. +.Pp +The controller supports hardware Ethernet checksum processing, hardware +VLAN tag stripping/insertion and an interrupt moderation mechanism. +Attansic L2 also features a 64-bit multicast hash filter. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width ".Cm 10baseT/UTP" +.It Cm autoselect +Enable autoselection of the media type and options. +The user can manually override the autoselected mode by +adding media options to +.Xr rc.conf 5 . +.It Cm 10baseT/UTP +Select 10Mbps operation. +.It Cm 100baseTX +Set 100Mbps (FastEthernet) operation. +.El +.Pp +The +.Nm +driver provides support for the following media options: +.Bl -tag -width ".Cm full-duplex" +.It Cm full-duplex +Force full duplex operation. +.It Cm half-duplex +Force half duplex operation. +.El +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports Attansic/Atheros L2 PCIe FastEthernet controllers, and +is known to support the following hardware: +.Pp +.Bl -bullet -compact +.It +ASUS EeePC 701 +.It +ASUS EeePC 900 +.El +.Pp +Other hardware may or may not work with this driver. +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width "xxxxxx" +.It Va hw.ae.msi_disable +This tunable disables MSI support on the Ethernet hardware. +The default value is 0. +.El +.Sh SYSCTL VARIABLES +The +.Nm +driver collects a number of useful MAC counter during the work. +The statistics is available via the +.Va dev.ae.%d.stats +.Xr sysctl 8 +tree, where %d corresponds to the controller number. +.Sh DIAGNOSTICS +.Bl -diag +.It "ae%d: watchdog timeout." +The device has stopped responding to the network, or there is a problem with +the network connection (cable). +.It "ae%d: reset timeout." +The card reset operation has been timed out. +.It "ae%d: Generating random ethernet address." +No valid Ethernet address was found in the controller NVRAM and registers. +Random locally administered address with ASUS OUI identifier will be used +instead. +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +driver and this manual page was written by +.An Stanislav Sedov Aq Mt stas@FreeBSD.org . +It first appeared in +.Fx 7.1 . +.Sh BUGS +The Attansic L2 FastEthernet controller supports DMA but does not use a +descriptor based transfer mechanism via scatter-gather DMA. +Thus the data should be copied to/from the controller memory on each +transmit/receive. +Furthermore, a lot of data alignment restrictions apply. +This may introduce a high CPU load on systems with heavy network activity. +Luckily enough this should not be a problem on modern hardware as L2 does +not support speeds faster than 100Mbps. diff --git a/static/freebsd/man4/aesni.4 b/static/freebsd/man4/aesni.4 new file mode 100644 index 00000000..fbc0c0e5 --- /dev/null +++ b/static/freebsd/man4/aesni.4 @@ -0,0 +1,110 @@ +.\" Copyright (c) 2010 Konstantin Belousov +.\" 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 29, 2020 +.Dt AESNI 4 +.Os +.Sh NAME +.Nm aesni +.Nd "driver for the AES and SHA accelerator on x86 CPUs" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device crypto" +.Cd "device cryptodev" +.Cd "device aesni" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +aesni_load="YES" +.Ed +.Sh DESCRIPTION +Starting with Intel Westmere and AMD Bulldozer, some x86 processors implement a +new set of instructions called AESNI. +The set of six instructions accelerates the calculation of the key +schedule for key lengths of 128, 192, and 256 of the Advanced +Encryption Standard (AES) symmetric cipher, and provides a hardware +implementation of the regular and the last encryption and decryption +rounds. +.Pp +The processor capability is reported as AESNI in the Features2 line at boot. +.Pp +Starting with the Intel Goldmont and AMD Ryzen microarchitectures, some x86 +processors implement a new set of SHA instructions. +The set of seven instructions accelerates the calculation of SHA1 and SHA256 +hashes. +.Pp +The processor capability is reported as SHA in the Structured Extended Features +line at boot. +.Pp +The +.Nm +driver does not attach on systems that lack both CPU capabilities. +On systems that support only one of AESNI or SHA extensions, the driver will +attach and support that one function. +.Pp +The +.Nm +driver registers itself to accelerate AES and SHA operations for +.Xr crypto 4 . +Besides speed, the advantage of using the +.Nm +driver is that the AESNI operation +is data-independent, thus eliminating some attack vectors based on +measuring cache use and timings typically present in table-driven +implementations. +.Sh SEE ALSO +.Xr crypt 3 , +.Xr crypto 4 , +.Xr intro 4 , +.Xr ipsec 4 , +.Xr padlock 4 , +.Xr random 4 , +.Xr crypto 7 , +.Xr crypto 9 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 9.0 . +SHA support was added in +.Fx 12.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Konstantin Belousov Aq Mt kib@FreeBSD.org +and +.An Conrad Meyer Aq Mt cem@FreeBSD.org . +The key schedule calculation code was adopted from the sample provided +by Intel and used in the analogous +.Ox +driver. +The hash step intrinsics implementations were supplied by Intel. diff --git a/static/freebsd/man4/age.4 b/static/freebsd/man4/age.4 new file mode 100644 index 00000000..0cd84147 --- /dev/null +++ b/static/freebsd/man4/age.4 @@ -0,0 +1,184 @@ +.\" Copyright (c) 2008 Pyun YongHyeon +.\" 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 September 18, 2008 +.Dt AGE 4 +.Os +.Sh NAME +.Nm age +.Nd Attansic/Atheros L1 Gigabit Ethernet driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device age" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_age_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +device driver provides support for Attansic/Atheros L1 PCI Express +Gigabit Ethernet controllers. +.Pp +All LOMs supported by the +.Nm +driver have TCP/UDP/IP checksum offload for both transmit and +receive, TCP segmentation offload (TSO), hardware VLAN tag +stripping/insertion features and an interrupt moderation mechanism +as well as a 64-bit multicast hash filter. +.Pp +The L1 also supports Jumbo Frames (up to 10240 bytes), which can be +configured via the interface MTU setting. +Selecting an MTU larger than 1500 bytes with the +.Xr ifconfig 8 +utility configures the adapter to receive and transmit Jumbo Frames. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width ".Cm 10baseT/UTP" +.It Cm autoselect +Enable autoselection of the media type and options. +The user can manually override +the autoselected mode by adding media options to +.Xr rc.conf 5 . +.It Cm 10baseT/UTP +Set 10Mbps operation. +.It Cm 100baseTX +Set 100Mbps (Fast Ethernet) operation. +.It Cm 1000baseTX +Set 1000baseTX operation over twisted pair. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width ".Cm full-duplex" +.It Cm full-duplex +Force full duplex operation. +.It Cm half-duplex +Force half duplex operation. +.El +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver provides support for LOMs based on +Attansic/Atheros L1 Gigabit Ethernet controller chips, including: +.Pp +.Bl -bullet -compact +.It +ASUS M2N8-VMX +.It +ASUS M2V +.It +ASUS M3A +.It +ASUS P2-M2A590G +.It +ASUS P5B-E +.It +ASUS P5B-MX/WIFI-AP +.It +ASUS P5B-VMSE +.It +ASUS P5K +.It +ASUS P5KC +.It +ASUS P5KPL-C +.It +ASUS P5KPL-VM +.It +ASUS P5K-SE +.It +ASUS P5K-V +.It +ASUS P5L-MX +.It +ASUS P5DL2-VM +.It +ASUS P5L-VM 1394 +.It +ASUS G2S +.El +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width "xxxxxx" +.It Va hw.age.msi_disable +This tunable disables MSI support on the Ethernet hardware. +The default value is 0. +.It Va hw.age.msix_disable +This tunable disables MSI-X support on the Ethernet hardware. +The default value is 0. +.El +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width "xxxxxx" +.It Va dev.age.%d.int_mod +Maximum amount of time to delay interrupt processing in units of +2us. +The accepted range is 0 to 65000, the default is 50 (100us). +Value 0 completely disables the interrupt moderation. +.It Va dev.age.%d.process_limit +Maximum amount of Rx events to be processed in the event loop before +rescheduling a taskqueue. +The accepted range is 30 to 255, the default value is 128 events. +The interface does not need to be brought down and up again before +a change takes effect. +.It Va dev.age.%d.stats +Display lots of useful MAC counters maintained in the driver. +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +driver was written by +.An Pyun YongHyeon Aq Mt yongari@FreeBSD.org . +It first appeared in +.Fx 7.1 . diff --git a/static/freebsd/man4/agp.4 b/static/freebsd/man4/agp.4 new file mode 100644 index 00000000..b7a64911 --- /dev/null +++ b/static/freebsd/man4/agp.4 @@ -0,0 +1,180 @@ +.\" Copyright (c) 2001 Yar Tikhiy +.\" 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 October 24, 2025 +.Dt AGP 4 +.Os +.Sh NAME +.Nm agp +.Nd "generic interface to the Accelerated Graphics Port (AGP)" +.Sh SYNOPSIS +.Cd "device agp" +.Sh DEPRECATION NOTICE +The +.Nm +driver is slated to be removed in +.Fx 16.0 . +.Sh DESCRIPTION +The +.Nm +driver provides uniform, abstract methods for controlling +the following devices: +.Pp +.Bl -tag -width "NVIDIA:" -compact +.It Ali: +M1541, M1621 and M1671 host to AGP bridges +.It AMD: +751, 761 and 762 host to AGP bridges +.It ATI: +RS100, RS200, RS250 and RS300 AGP bridges +.It Intel: +i820, i840, i845, i850, and i860 host to AGP bridges +.It Intel: +i810, i810-DC100, i810E, i815, 830M, 845G, 845M, 852GM, 852GME, 855GM, 855GME, 865G, 915G and 915GM SVGA controllers +.It Intel: +82443BX, 82443GX, 82443LX, 82815, 82820, 82830, 82840, 82845, 82845G, 82850, 82855, 82855GM, 82860, 82865, 82875P, E7205 and E7505 host to AGP bridges +.It NVIDIA: +nForce and nForce2 AGP controllers +.It SiS: +530, 540, 550, 620, 630, 645, 645DX, 648, 650, 651, 655, 661, 730, 735, 740, 741, 745, 746, 760 and 5591 host to AGP bridges +.It VIA: +3296, 82C597, 82C598, 82C691, 82C694X, 82C8363, 8235, 8237, 8361, 8367, 8371, 8377, 8501, 8601, 862x, 8633, 8653, 8703, 8753, 8754, 8763, 8783, KT880, PM800, PM880, PN800, PN880, PT880, XM266 and XN266 host to PCI bridges +.El +.Pp +The most common application of +.Nm +is for running +.Xr X 7 Pq Pa ports/x11/xorg-docs +on the Intel i81x controllers. +.Sh IOCTLS +The following +.Xr ioctl 2 +operations can be performed on +.Pa /dev/agpgart , +which are defined in +.In sys/agpio.h : +.Bl -tag -width indent +.It Dv AGPIOC_INFO +Returns state of the +.Nm +system. +The result is a pointer to the following structure: +.Bd -literal +typedef struct _agp_info { + agp_version version; /* version of the driver */ + uint32_t bridge_id; /* bridge vendor/device */ + uint32_t agp_mode; /* mode info of bridge */ + off_t aper_base; /* base of aperture */ + size_t aper_size; /* size of aperture */ + size_t pg_total; /* max pages (swap + system) */ + size_t pg_system; /* max pages (system) */ + size_t pg_used; /* current pages used */ +} agp_info; +.Ed +.It Dv AGPIOC_ACQUIRE +Acquire control of the AGP chipset for use by this client. +Returns +.Er EBUSY +if the AGP chipset is already acquired by another client. +.It Dv AGPIOC_RELEASE +Release control of the AGP chipset. +This does not unbind or free any allocated memory, which is the +responsibility of the client to handle if necessary. +.It Dv AGPIOC_SETUP +Enable the AGP hardware with the relevant mode. +This +.Xr ioctl 2 +takes the following structure: +.Bd -literal +typedef struct _agp_setup { + uint32_t agp_mode; /* mode info of bridge */ +} agp_setup; +.Ed +.Pp +The mode bits are defined in +.In sys/agpio.h . +.It Dv AGPIOC_ALLOCATE +Allocate physical memory suitable for mapping into the AGP aperture. +This +.Xr ioctl 2 +takes the following structure: +.Bd -literal +typedef struct _agp_allocate { + int key; /* tag of allocation */ + size_t pg_count; /* number of pages */ + uint32_t type; /* 0 == normal, other devspec */ + uint32_t physical; /* device specific (some devices + * need a phys address of the + * actual page behind the gatt + * table) */ +} agp_allocate; +.Ed +.Pp +Returns a handle to the allocated memory. +.It Dv AGPIOC_DEALLOCATE +Free the previously allocated memory associated with the handle passed. +.It Dv AGPIOC_BIND +Bind the allocated memory at given offset with the AGP aperture. +Returns +.Er EINVAL +if the memory is already bound or the offset is not at AGP page boundary. +This +.Xr ioctl 2 +takes the following structure: +.Bd -literal +typedef struct _agp_bind { + int key; /* tag of allocation */ + off_t pg_start; /* starting page to populate */ +} agp_bind; +.Ed +.Pp +The tag of allocation is the handle returned by +.Dv AGPIOC_ALLOCATE . +.It Dv AGPIOC_UNBIND +Unbind memory from the AGP aperture. +Returns +.Er EINVAL +if the memory is not bound. +This +.Xr ioctl 2 +takes the following structure: +.Bd -literal +typedef struct _agp_unbind { + int key; /* tag of allocation */ + uint32_t priority; /* priority for paging out */ +} agp_unbind; +.Ed +.El +.Sh FILES +.Bl -tag -width ".Pa /dev/agpgart" -compact +.It Pa /dev/agpgart +AGP device node. +.El +.Sh SEE ALSO +.Xr X 7 Pq Pa ports/x11/xorg +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 4.1 . diff --git a/static/freebsd/man4/ahc.4 b/static/freebsd/man4/ahc.4 new file mode 100644 index 00000000..a2aa911c --- /dev/null +++ b/static/freebsd/man4/ahc.4 @@ -0,0 +1,413 @@ +.\" +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" Copyright (c) 1995, 1996, 1997, 1998, 2000 +.\" Justin T. Gibbs. 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. 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 September 29, 2025 +.Dt AHC 4 +.Os +.Sh NAME +.Nm ahc +.Nd Adaptec VL/ISA/PCI SCSI host adapter driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device scbus" +.Cd "device ahc" +.Pp +For one or more PCI cards: +.Cd "device pci" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ahc_load="YES" +ahc_isa_load="YES" +ahc_pci_load="YES" +.Ed +.Sh DESCRIPTION +This driver provides access to the +.Tn SCSI +bus(es) connected to the Adaptec AIC77xx and AIC78xx +host adapter chips. +.Pp +Driver features include support for twin and wide busses, +fast, ultra or ultra2 synchronous transfers depending on controller type, +tagged queueing, SCB paging, and target mode. +.Pp +Per target configuration performed in the +.Tn SCSI-Select +menu, accessible at boot +is honored by this driver. +This includes synchronous/asynchronous transfers, +maximum synchronous negotiation rate, +wide transfers, +disconnection, +the host adapter's SCSI ID. +For systems that store non-volatile settings in a system specific manner +rather than a serial eeprom directly connected to the aic7xxx controller, +the +.Tn BIOS +must be enabled for the driver to access this information. +This restriction applies to +many chip-down motherboard configurations. +.Pp +Performance and feature sets vary throughout the aic7xxx product line. +The following table provides a comparison of the different chips supported +by the +.Nm +driver. +Note that wide and twin channel features, although always supported +by a particular chip, may be disabled in a particular motherboard or card +design. +.Bd -ragged -offset indent +.Bl -column "aic7895CX" "MIPSX" "PCI/64X" "MaxSyncX" "MaxWidthX" "SCBsX" "2 3 4 5 6 7 8X" +.It Em "Chip" Ta "MIPS" Ta "Bus" Ta "MaxSync" Ta "MaxWidth" Ta "SCBs" Ta "Features" +.It "aic7770" Ta "10" Ta "VL" Ta "10MHz" Ta "16Bit" Ta "4" Ta "1" +.It "aic7850" Ta "10" Ta "PCI/32" Ta "10MHz" Ta "8Bit" Ta "3" Ta "" +.It "aic7860" Ta "10" Ta "PCI/32" Ta "20MHz" Ta "8Bit" Ta "3" Ta "" +.It "aic7870" Ta "10" Ta "PCI/32" Ta "10MHz" Ta "16Bit" Ta "16" Ta "" +.It "aic7880" Ta "10" Ta "PCI/32" Ta "20MHz" Ta "16Bit" Ta "16" Ta "" +.It "aic7890" Ta "20" Ta "PCI/32" Ta "40MHz" Ta "16Bit" Ta "16" Ta "3 4 5 6 7 8" +.It "aic7891" Ta "20" Ta "PCI/64" Ta "40MHz" Ta "16Bit" Ta "16" Ta "3 4 5 6 7 8" +.It "aic7892" Ta "20" Ta "PCI/64" Ta "80MHz" Ta "16Bit" Ta "16" Ta "3 4 5 6 7 8" +.It "aic7895" Ta "15" Ta "PCI/32" Ta "20MHz" Ta "16Bit" Ta "16" Ta "2 3 4 5" +.It "aic7895C" Ta "15" Ta "PCI/32" Ta "20MHz" Ta "16Bit" Ta "16" Ta "2 3 4 5 8" +.It "aic7896" Ta "20" Ta "PCI/32" Ta "40MHz" Ta "16Bit" Ta "16" Ta "2 3 4 5 6 7 8" +.It "aic7897" Ta "20" Ta "PCI/64" Ta "40MHz" Ta "16Bit" Ta "16" Ta "2 3 4 5 6 7 8" +.It "aic7899" Ta "20" Ta "PCI/64" Ta "80MHz" Ta "16Bit" Ta "16" Ta "2 3 4 5 6 7 8" +.El +.Pp +.Bl -enum -compact +.It +Multiplexed Twin Channel Device - One controller servicing two busses. +.It +Multi-function Twin Channel Device - Two controllers on one chip. +.It +Command Channel Secondary DMA Engine - Allows scatter gather list and +SCB prefetch. +.It +64 Byte SCB Support - SCSI CDB is embedded in the SCB to eliminate an extra DMA. +.It +Block Move Instruction Support - Doubles the speed of certain sequencer +operations. +.It +.Sq Bayonet +style Scatter Gather Engine - Improves S/G prefetch performance. +.It +Queuing Registers - Allows queueing of new transactions without pausing the +sequencer. +.It +Multiple Target IDs - Allows the controller to respond to selection as a +target on multiple SCSI IDs. +.El +.Ed +.Sh CONFIGURATION OPTIONS +.Pp +To allow PCI adapters to use memory mapped I/O if enabled: +.Pp +.Cd options AHC_ALLOW_MEMIO=(0 -- disabled, 1 -- enabled) +.Bd -ragged -offset indent +Memory mapped I/O is more efficient than the alternative, programmed I/O. +Most PCI BIOSes will map devices so that either technique for communicating +with the card is available. In some cases, usually when the PCI device is +sitting behind a PCI->PCI bridge, the BIOS may fail to properly initialize +the chip for memory mapped I/O. The typical symptom of this problem is a +system hang if memory mapped I/O is attempted. +.Pp +Most modern motherboards perform the initialization correctly and work fine +with this option enabled and it is the default. This option can also be +dynamically configured through a device hint documented below. +.Ed +.Pp +To statically configure one or more controllers to assume the target role: +.Pp +.Cd options AHC_TMODE_ENABLE= +.Bd -ragged -offset indent +The value assigned to this option should be a bitmap of all units where target +mode is desired. For example, a value of 0x25, would enable target mode on +units 0, 2, and 5. A value of 0x8a enables it for units 1, 3, and 7. +.Pp +Note that controllers can be dynamically configured through a device hint +documented below. +.Ed +.Sh BOOT OPTIONS +The following options are switchable by setting values in +.Pa /boot/device.hints . +.Pp +They are: +.Bl -tag -width indent +.It Va hint.ahc. Ns Ar N Ns Va .tmode_enable +A hint to define whether the SCSI target mode is enabled, defaults to disabled +(0 -- disabled, 1 -- enabled). +.It Va hint.ahc. Ns Ar N Ns Va .allow_memio +A hint to define whether memory mapped io is enabled or disabled for this +adapter, defaults to enabled (0 -- disabled, 1 -- enabled). +.El +.Sh HARDWARE +The +.Nm +driver supports the following VL/ISA/PCI parallel SCSI controllers and cards: +.Pp +.Bl -bullet -compact +.It +Adaptec +.Tn AIC7770 +host adapter chip +.It +Adaptec +.Tn AIC7850 +host adapter chip +.It +Adaptec +.Tn AIC7860 +host adapter chip +.It +Adaptec +.Tn AIC7870 +host adapter chip +.It +Adaptec +.Tn AIC7880 +host adapter chip +.It +Adaptec +.Tn AIC7890 +host adapter chip +.It +Adaptec +.Tn AIC7891 +host adapter chip +.It +Adaptec +.Tn AIC7892 +host adapter chip +.It +Adaptec +.Tn AIC7895 +host adapter chip +.It +Adaptec +.Tn AIC7896 +host adapter chip +.It +Adaptec +.Tn AIC7897 +host adapter chip +.It +Adaptec +.Tn AIC7899 +host adapter chip +.It +Adaptec +.Tn 274X(W) +.It +Adaptec +.Tn 274X(T) +.It +Adaptec +.Tn 2910 +.It +Adaptec +.Tn 2915 +.It +Adaptec +.Tn 2920C +.It +Adaptec +.Tn 2930C +.It +Adaptec +.Tn 2930U2 +.It +Adaptec +.Tn 2940 +.It +Adaptec +.Tn 2940J +.It +Adaptec +.Tn 2940N +.It +Adaptec +.Tn 2940U +.It +Adaptec +.Tn 2940AU +.It +Adaptec +.Tn 2940UW +.It +Adaptec +.Tn 2940UW Dual +.It +Adaptec +.Tn 2940UW Pro +.It +Adaptec +.Tn 2940U2W +.It +Adaptec +.Tn 2940U2B +.It +Adaptec +.Tn 2950U2W +.It +Adaptec +.Tn 2950U2B +.It +Adaptec +.Tn 19160B +.It +Adaptec +.Tn 29160B +.It +Adaptec +.Tn 29160N +.It +Adaptec +.Tn 3940 +.It +Adaptec +.Tn 3940U +.It +Adaptec +.Tn 3940AU +.It +Adaptec +.Tn 3940UW +.It +Adaptec +.Tn 3940AUW +.It +Adaptec +.Tn 3940U2W +.It +Adaptec +.Tn 3950U2 +.It +Adaptec +.Tn 3960 +.It +Adaptec +.Tn 39160 +.It +Adaptec +.Tn 3985 +.It +Adaptec +.Tn 4944UW +.It +Many motherboards with on-board +.Tn SCSI +support +.El +.Sh SCSI CONTROL BLOCKS (SCBs) +Every transaction sent to a device on the SCSI bus is assigned a +.Sq SCSI Control Block +(SCB). +The SCB contains all of the information required by the +controller to process a transaction. +The chip feature table lists +the number of SCBs that can be stored in on-chip memory. +All chips +with model numbers greater than or equal to 7870 allow for the on chip +SCB space to be augmented with external SRAM up to a maximum of 255 SCBs. +Very few Adaptec controller configurations have external SRAM. +.Pp +If external SRAM is not available, SCBs are a limited resource. +Using the SCBs in a straight forward manner would only allow the driver to +handle as many concurrent transactions as there are physical SCBs. +To fully utilize the SCSI bus and the devices on it, +requires much more concurrency. +The solution to this problem is +.Em SCB Paging , +a concept similar to memory paging. +SCB paging takes advantage of +the fact that devices usually disconnect from the SCSI bus for long +periods of time without talking to the controller. +The SCBs for disconnected transactions are only of use to the controller +when the transfer is resumed. +When the host queues another transaction +for the controller to execute, the controller firmware will use a +free SCB if one is available. +Otherwise, the state of the most recently +disconnected (and therefore most likely to stay disconnected) SCB is +saved, via dma, to host memory, and the local SCB reused to start +the new transaction. +This allows the controller to queue up to +255 transactions regardless of the amount of SCB space. +Since the +local SCB space serves as a cache for disconnected transactions, the +more SCB space available, the less host bus traffic consumed saving +and restoring SCB data. +.Sh SEE ALSO +.Xr ahd 4 , +.Xr cd 4 , +.Xr da 4 , +.Xr sa 4 , +.Xr scsi 4 +.Sh HISTORY +The +.Nm +driver appeared in +.Fx 2.0 . +.Sh AUTHORS +The +.Nm +driver, the +.Tn AIC7xxx +sequencer-code assembler, +and the firmware running on the aic7xxx chips was written by +.An Justin T. Gibbs . +.Sh BUGS +Some Quantum drives (at least the Empire 2100 and 1080s) will not run on an +.Tn AIC7870 +Rev B in synchronous mode at 10MHz. +Controllers with this problem have a +42 MHz clock crystal on them and run slightly above 10MHz. +This confuses the drive and hangs the bus. +Setting a maximum synchronous negotiation rate of 8MHz in the +.Tn SCSI-Select +utility will allow normal operation. +.Pp +Although the Ultra2 and Ultra160 products have sufficient instruction +ram space to support both the initiator and target roles concurrently, +this configuration is disabled in favor of allowing the target role +to respond on multiple target ids. +A method for configuring dual role mode should be provided. +.Pp +Tagged Queuing is not supported in target mode. +.Pp +Reselection in target mode fails to function correctly on all high +voltage differential boards as shipped by Adaptec. +Information on +how to modify HVD board to work correctly in target mode is available +from Adaptec. diff --git a/static/freebsd/man4/ahci.4 b/static/freebsd/man4/ahci.4 new file mode 100644 index 00000000..70fe3490 --- /dev/null +++ b/static/freebsd/man4/ahci.4 @@ -0,0 +1,209 @@ +.\" Copyright (c) 2009-2013 Alexander Motin +.\" 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 December 17, 2021 +.Dt AHCI 4 +.Os +.Sh NAME +.Nm ahci +.Nd Serial ATA Advanced Host Controller Interface driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device pci" +.Cd "device scbus" +.Cd "device ahci" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ahci_load="YES" +.Ed +.Pp +The following tunables are settable from the +.Xr loader 8 : +.Bl -ohang +.It Va hint.ahci. Ns Ar X Ns Va .msi +controls Message Signaled Interrupts (MSI) usage by the specified controller. +.Pp +.Bl -tag -width 4n -offset indent -compact +.It 0 +MSI disabled; +.It 1 +single MSI vector used, if supported; +.It 2 +multiple MSI vectors used, if supported (default); +.El +.It Va hint.ahci. Ns Ar X Ns Va .ccc +controls Command Completion Coalescing (CCC) usage by the specified controller. +Non-zero value enables CCC and defines maximum time (in ms), request can wait +for interrupt, if there are some more requests present on controller queue. +CCC reduces number of context switches on systems with many parallel requests, +but it can decrease disk performance on some workloads due to additional +command latency. +.It Va hint.ahci. Ns Ar X Ns Va .direct +controls whether the driver should use direct command completion from +interrupt thread(s), or queue them to CAM completion threads. +Default value depends on number of MSI interrupts supported and number of +implemented SATA ports. +.It Va hint.ahci. Ns Ar X Ns Va .em +controls whether the driver should implement virtual enclosure management +device on top of SGPIO or other interface. +Default value depends on controller capabilities. +.It Va hint.ahcich. Ns Ar X Ns Va .pm_level +controls SATA interface Power Management for the specified channel, +allowing some power to be saved at the cost of additional command +latency. +Possible values: +.Pp +.Bl -tag -width 4n -offset indent -compact +.It 0 +interface Power Management is disabled (default); +.It 1 +device is allowed to initiate PM state change, host is passive; +.It 2 +host initiates PARTIAL PM state transition every time port becomes idle; +.It 3 +host initiates SLUMBER PM state transition every time port becomes idle. +.It 4 +driver initiates PARTIAL PM state transition 1ms after port becomes idle; +.It 5 +driver initiates SLUMBER PM state transition 125ms after port becomes idle. +.El +.Pp +Some controllers, such as ICH8, do not implement modes 2 and 3 with NCQ used. +Because of artificial entering latency, performance degradation in modes +4 and 5 is much smaller then in modes 2 and 3. +.Pp +Note that interface Power Management complicates device presence detection. +A manual bus reset/rescan may be needed after device hot-plug, unless hardware +implements Cold Presence Detection. +.It Va hint.ahcich. Ns Ar X Ns Va .sata_rev +setting to nonzero value limits maximum SATA revision (speed). +Values 1, 2 and 3 are respectively 1.5, 3 and 6Gbps. +.It Va hw.ahci.force +setting to nonzero value forces driver attach to some known AHCI-capable +chips even if they are configured for legacy IDE emulation. +Default is 1. +.El +.Sh DESCRIPTION +This driver provides the +.Xr CAM 4 +subsystem with native access to the +.Tn SATA +ports of AHCI-compatible controllers. +Each SATA port found is represented to CAM as a separate bus with one +target, or, if HBA supports Port Multipliers, 16 targets. +Most of the bus-management details are handled by the SATA-specific +transport of CAM. +Connected ATA disks are handled by the ATA protocol disk peripheral driver +.Xr ada 4 . +ATAPI devices are handled by the SCSI protocol peripheral drivers +.Xr cd 4 , +.Xr da 4 , +.Xr sa 4 , +etc. +.Pp +Driver features include support for Serial ATA and ATAPI devices, +Port Multipliers (including FIS-based switching, when supported), +hardware command queues (up to 32 commands per port), +Native Command Queuing, SATA interface Power Management, device hot-plug +and Message Signaled Interrupts. +.Pp +Driver supports "LED" enclosure management messages, defined by the AHCI. +When supported by hardware, it allows to control per-port activity, locate +and fault LEDs via the +.Xr led 4 +API or emulated +.Xr ses 4 +device for localization and status reporting purposes. +Supporting AHCI controllers may transmit that information to the backplane +controllers via SGPIO interface. +Backplane controllers interpret received +statuses in some way (IBPI standard) to report them using present indicators. +.Sh HARDWARE +The +.Nm +driver supports AHCI compatible controllers having PCI class 1 (mass storage), +subclass 6 (SATA) and programming interface 1 (AHCI). +.Pp +Also, in cooperation with atamarvell and atajmicron drivers of ata(4), +it supports AHCI part of legacy-PATA + AHCI-SATA combined controllers, +such as JMicron JMB36x and Marvell 88SE61xx. +.Pp +The +.Nm +driver also supports AHCI devices that act as PCI bridges for +.Xr nvme 4 +using Intel Rapid Storage Technology (RST). +To use the +.Xr nvme 4 +device, either one must set the SATA mode in the BIOS to AHCI (from RST), +or one must accept the performance with RST enabled due to interrupt sharing. +.Fx +will automatically detect AHCI devices with this extension that are in RST +mode. +When that happens, +.Nm +will attach +.Xr nvme 4 +children to the +.Nm +device. +.Sh FILES +.Bl -tag -width /dev/led/ahcich*.locate +.It Pa /dev/led/ahci*.*.act +activity LED device nodes +.It Pa /dev/led/ahci*.*.fault +fault LED device nodes +.It Pa /dev/led/ahci*.*.locate +locate LED device nodes +.El +.Sh SYSCTL +.Bl -tag +.It Pa dev.ahcich.X.disable_phy +Set to 1 to disable the phy for the drive on channel X. +Set to 0 to enable the phy. +Useful for turning off troublemakers. +Also useful for debugging when you need the ada drive to come and go. +.El +.Sh SEE ALSO +.Xr ada 4 , +.Xr ata 4 , +.Xr cam 4 , +.Xr cd 4 , +.Xr da 4 , +.Xr sa 4 , +.Xr ses 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 8.0 . +.Sh AUTHORS +.An Alexander Motin Aq Mt mav@FreeBSD.org diff --git a/static/freebsd/man4/ahd.4 b/static/freebsd/man4/ahd.4 new file mode 100644 index 00000000..b5347b72 --- /dev/null +++ b/static/freebsd/man4/ahd.4 @@ -0,0 +1,190 @@ +.\" +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" Copyright (c) 1995, 1996, 1997, 1998, 2000 +.\" Justin T. Gibbs. All rights reserved. +.\" Copyright (c) 2002 +.\" Scott Long. 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. 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 September 29, 2025 +.Dt AHD 4 +.Os +.Sh NAME +.Nm ahd +.Nd Adaptec PCI/PCI-X Ultra320 SCSI host adapter driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device pci" +.Cd "device scbus" +.Cd "device ahd" +.Pp +To compile in debugging code: +.Cd options AHD_DEBUG +.Cd options AHD_DEBUG_OPTS= +.Cd options AHD_REG_PRETTY_PRINT +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ahd_load="YES" +.Ed +.Sh DESCRIPTION +This driver provides access to the +.Tn SCSI +bus(es) connected to Adaptec +.Tn AIC79xx +host adapter chips. +.Pp +Driver features include support for narrow and wide busses, +fast, ultra, ultra2, ultra160, and ultra320 synchronous transfers, +packetized transfers, tagged queueing, 512 SCB's, and target mode. +.Pp +The +.Dv AHD_DEBUG_OPTS +option is used to control which diagnostic messages are printed to the +console when +.Dv AHD_DEBUG +is enabled. +Logically OR the following bits together: +.Bl -column -offset indent Value Function +.Em "Value Function" +0x0001 Show miscellaneous information +0x0002 Show sense data +0x0004 Show Serial EEPROM contents +0x0008 Show bus termination settings +0x0010 Show host memory usage +0x0020 Show SCSI protocol messages +0x0040 Show mode pointer of the chip register window +0x0080 Show selection timeouts +0x0100 Show FIFO usage messages +0x0200 Show Queue Full status +0x0400 Show SCB queue status +0x0800 Show inbound packet information +0x1000 Show S/G list information +0x2000 Enable extra diagnostic code in the firmware +.El +.Pp +The +.Dv AHD_REG_PRETTY_PRINT +option compiles in support for human-readable bit definitions for each register +that is printed by the debugging code. +However, it also bloats the compiled +size of the driver by approximately 215KB. +.Pp +Per target configuration performed in the +.Tn SCSI-Select +menu, accessible at boot, +is honored by this driver. +This includes synchronous/asynchronous transfers, +maximum synchronous negotiation rate, +wide transfers, +disconnection, +and the host adapter's +.Tn SCSI +ID. +.Sh CONFIGURATION OPTIONS +To statically configure one or more controllers to assume the target role: +.Pp +.Cd options AHD_TMODE_ENABLE +.Bd -ragged -offset indent +The value assigned to this option should be a bitmap of all units where target +mode is desired. For example, a value of 0x25, would enable target mode on +units 0, 2, and 5. A value of 0x8a enables it for units 1, 3, and 7. +.Pp +Note that controllers can be dynamically configured through a device hint +documented below. + +.Ed +.Sh BOOT OPTIONS +The following options are switchable by setting values in +.Pa /boot/device.hints . +.Pp +They are: +.Bl -tag -width indent +.It Va hint.ahd. Ns Ar N Ns Va .tmode_enable +A hint to define whether the SCSI target mode is enabled (0 -- disabled, 1 -- enabled). +.El +.Sh HARDWARE +The +.Nm +driver supports the following PCI/PCI-X parallel SCSI controllers: +.Pp +.Bl -bullet -compact +.It +Adaptec +.Tn AIC7901 +host adapter chip +.It +Adaptec +.Tn AIC7901A +host adapter chip +.It +Adaptec +.Tn AIC7902 +host adapter chip +.It +Adaptec +.Tn 29320 +host adapter +.It +Adaptec +.Tn 39320 +host adapter +.It +Many motherboards with on-board +.Tn SCSI +support +.El +.Sh SEE ALSO +.Xr ahc 4 , +.Xr cd 4 , +.Xr da 4 , +.Xr sa 4 , +.Xr scsi 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 4.7 . +.Sh AUTHORS +The +.Nm +driver, the +.Tn AIC7xxx +sequencer-code assembler, +and the firmware running on the aic79xx chips was written by +.An Justin T. Gibbs . +This manual page is based on the +.Xr ahc 4 +manual page. +.Sh BUGS +The current generation of 79xx chips do not support target mode in Ultra320 +mode. +Target mode in general has not been well tested in this driver. diff --git a/static/freebsd/man4/aibs.4 b/static/freebsd/man4/aibs.4 new file mode 100644 index 00000000..f3bba5fb --- /dev/null +++ b/static/freebsd/man4/aibs.4 @@ -0,0 +1,206 @@ +.\" $NetBSD: aibs.4,v 1.2 2010/02/09 05:37:25 cnst Exp $ +.\" $OpenBSD: aibs.4,v 1.4 2009/07/30 06:30:45 jmc Exp $ +.\" +.\" Copyright (c) 2009/2010 Constantine A. Murenin +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd April 4, 2010 +.Dt AIBS 4 +.Os +.Sh NAME +.Nm aibs +.Nd "ASUSTeK AI Booster ACPI ATK0110 voltage, temperature and fan sensor" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device aibs" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +aibs_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the voltage, temperature and fan sensors +available through the +.Tn ATK0110 +.Tn ASOC +.Tn ACPI +device +on +.Tn ASUSTeK +motherboards. +The number of sensors of each type, +as well as the description of each sensor, +varies according to the motherboard. +.Pp +The driver supports an arbitrary set of sensors, +provides descriptions regarding what each sensor is used for, +and reports the current values as well as +the supposed range specifications of each sensor's input +as defined by the motherboard manufacturer through +.Tn ACPI . +.Pp +The range specifications are as follows: +.Bl -bullet +.It +Voltage sensors have a lower and an upper range specification. +.It +Temperature sensors have two upper specifications. +.It +Fan sensors may either have only the lower specification, +or, depending on the +.Tn DSDT , +one lower and one upper specification. +.El +.Pp +Sensor readings and the range specifications are made available through the +.Xr sysctl 3 +interface, +and can be monitored with +.Xr sysctl 8 . +For example, on an ASUS V3-P5G965 barebone: +.Bd -literal -offset indent +> sysctl dev.aibs.0.{volt,temp,fan} +dev.aibs.0.volt.0: 1192 850 1600 +dev.aibs.0.volt.1: 3312 2970 3630 +dev.aibs.0.volt.2: 5017 4500 5500 +dev.aibs.0.volt.3: 12302 10200 13800 +dev.aibs.0.temp.0: 28.0C 80.0C 95.0C +dev.aibs.0.temp.1: 55.0C 60.0C 95.0C +dev.aibs.0.fan.0: 878 600 7200 +dev.aibs.0.fan.1: 0 700 7200 +.Pp +> sysctl -d dev.aibs.0.{volt,temp,fan} +dev.aibs.0.volt: +dev.aibs.0.volt.0: Vcore Voltage +dev.aibs.0.volt.1: +3.3 Voltage +dev.aibs.0.volt.2: +5 Voltage +dev.aibs.0.volt.3: +12 Voltage +dev.aibs.0.temp: +dev.aibs.0.temp.0: CPU Temperature +dev.aibs.0.temp.1: MB Temperature +dev.aibs.0.fan: +dev.aibs.0.fan.0: CPU FAN Speed +dev.aibs.0.fan.1: CHASSIS FAN Speed +.Ed +.Pp +Generally, sensors provided by the +.Nm +driver may also be supported by certain other drivers or utilities +that access the +.Tn ISA / +.Tn LPC +or +.Tn I2C / +.Tn SMBus +devices directly. +The precise collection of +.Nm +sensors is comprised of the sensors +specifically utilised in the motherboard +design, which may be supported through +a combination of one or more physical hardware monitoring chips. +.Pp +The +.Nm +driver, however, provides the following advantages +when compared to the native hardware monitoring drivers or other utilities: +.Bl -bullet +.It +Sensor values from +.Nm +are expected to be more reliable. +For example, voltage sensors in many hardware monitoring chips +can only sense voltage from 0 to 2 or 4 volts, and the excessive +voltage is removed by the resistors, which may vary with the motherboard +and with the voltage that is being sensed. +In +.Nm , +the required resistor factors are provided by +the motherboard manufacturer through +.Tn ACPI ; +in the native drivers, the resistor factors +are encoded into the driver based on the chip manufacturer's recommendations. +In essence, sensor values from +.Nm +are very likely to be identical to the readings from the +Hardware Monitor screen in the BIOS. +.It +Sensor descriptions from +.Nm +are more likely to match the markings on the motherboard. +.It +Sensor range specifications are supported by +.Nm . +The range specification is reported +for each individual sensor as suggested by the motherboard manufacturer. +For example, the threshold for the CPU temperature sensor is likely +to be significantly higher than that for the chassis temperature sensor. +.It +Support for newer chips in +.Nm . +Newer chips may miss a native driver, +but should be supported through +.Nm +regardless. +.El +.Sh SEE ALSO +.Xr sysctl 3 , +.Xr acpi 4 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Ox 4.7 , +.Dx 2.5 , +.Nx 6.0 +and +.Fx 9.0 . +.Pp +An earlier version of the driver, +.Nm acpi_aiboost , +first appeared in +.Fx 7.0 +and +.Nx 5.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written for +.Ox , +.Dx , +.Nx +and +.Fx +by +.An Constantine A. Murenin Aq Mt cnst@FreeBSD.org , +Raouf Boutaba Research Group, +David R. Cheriton School of Computer Science, +University of Waterloo. +.Pp +An earlier version of the driver, named +.Nm acpi_aiboost , +was written for +.Fx +by +.An Takanori Watanabe . diff --git a/static/freebsd/man4/aio.4 b/static/freebsd/man4/aio.4 new file mode 100644 index 00000000..21332a3b --- /dev/null +++ b/static/freebsd/man4/aio.4 @@ -0,0 +1,237 @@ +.\"- +.\" Copyright (c) 2002 Dag-Erling Smørgrav +.\" 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. 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 AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 2, 2021 +.Dt AIO 4 +.Os +.Sh NAME +.Nm aio +.Nd asynchronous I/O +.Sh DESCRIPTION +The +.Nm +facility provides system calls for asynchronous I/O. +Asynchronous I/O operations are not completed synchronously by the +calling thread. +Instead, the calling thread invokes one system call to request an +asynchronous I/O operation. +The status of a completed request is retrieved later via a separate +system call. +.Pp +Asynchronous I/O operations on some file descriptor types may block an +AIO daemon indefinitely resulting in process and/or system hangs. +Operations on these file descriptor types are considered +.Dq unsafe +and disabled by default. +They can be enabled by setting +the +.Va vfs.aio.enable_unsafe +sysctl node to a non-zero value. +.Pp +Asynchronous I/O operations on sockets, +raw disk devices, +and regular files on local filesystems do not block +indefinitely and are always enabled. +.Pp +The +.Nm +facility uses kernel processes +(also known as AIO daemons) +to service most asynchronous I/O requests. +These processes are grouped into pools containing a variable number of +processes. +Each pool will add or remove processes to the pool based on load. +Pools can be configured by sysctl nodes that define the minimum +and maximum number of processes as well as the amount of time an idle +process will wait before exiting. +.Pp +One pool of AIO daemons is used to service asynchronous I/O requests for +sockets. +These processes are named +.Dq soaiod . +The following sysctl nodes are used with this pool: +.Bl -tag -width indent +.It Va kern.ipc.aio.num_procs +The current number of processes in the pool. +.It Va kern.ipc.aio.target_procs +The minimum number of processes that should be present in the pool. +.It Va kern.ipc.aio.max_procs +The maximum number of processes permitted in the pool. +.It Va kern.ipc.aio.lifetime +The amount of time a process is permitted to idle in clock ticks. +If a process is idle for this amount of time and there are more processes +in the pool than the target minimum, +the process will exit. +.El +.Pp +A second pool of AIO daemons is used to service all other asynchronous I/O +requests except for I/O requests to raw disks. +These processes are named +.Dq aiod . +The following sysctl nodes are used with this pool: +.Bl -tag -width indent +.It Va vfs.aio.num_aio_procs +The current number of processes in the pool. +.It Va vfs.aio.target_aio_procs +The minimum number of processes that should be present in the pool. +.It Va vfs.aio.max_aio_procs +The maximum number of processes permitted in the pool. +.It Va vfs.aio.aiod_lifetime +The amount of time a process is permitted to idle in clock ticks. +If a process is idle for this amount of time and there are more processes +in the pool than the target minimum, +the process will exit. +.El +.Pp +Asynchronous I/O requests for raw disks are queued directly to the disk +device layer after temporarily wiring the user pages associated with the +request. +These requests are not serviced by any of the AIO daemon pools. +.Pp +Several limits on the number of asynchronous I/O requests are imposed both +system-wide and per-process. +These limits are configured via the following sysctls: +.Bl -tag -width indent +.It Va vfs.aio.max_buf_aio +The maximum number of queued asynchronous I/O requests for raw disks permitted +for a single process. +Asynchronous I/O requests that have completed but whose status has not been +retrieved via +.Xr aio_return 2 +or +.Xr aio_waitcomplete 2 +are not counted against this limit. +.It Va vfs.aio.num_buf_aio +The number of queued asynchronous I/O requests for raw disks system-wide. +.It Va vfs.aio.max_aio_queue_per_proc +The maximum number of asynchronous I/O requests for a single process +serviced concurrently by the default AIO daemon pool. +.It Va vfs.aio.max_aio_per_proc +The maximum number of outstanding asynchronous I/O requests permitted for a +single process. +This includes requests that have not been serviced, +requests currently being serviced, +and requests that have completed but whose status has not been retrieved via +.Xr aio_return 2 +or +.Xr aio_waitcomplete 2 . +.It Va vfs.aio.num_queue_count +The number of outstanding asynchronous I/O requests system-wide. +.It Va vfs.aio.max_aio_queue +The maximum number of outstanding asynchronous I/O requests permitted +system-wide. +.El +.Pp +Asynchronous I/O control buffers should be zeroed before initializing +individual fields. +This ensures all fields are initialized. +.Pp +All asynchronous I/O control buffers contain a +.Vt sigevent +structure in the +.Va aio_sigevent +field which can be used to request notification when an operation completes. +.Pp +For +.Dv SIGEV_KEVENT +notifications, +the +.Va sigevent +.Ap +s +.Va sigev_notify_kqueue +field should contain the descriptor of the kqueue that the event should be attached +to, its +.Va sigev_notify_kevent_flags +field may contain +.Dv EV_ONESHOT , +.Dv EV_CLEAR , and/or +.Dv EV_DISPATCH , and its +.Va sigev_notify +field should be set to +.Dv SIGEV_KEVENT . +The posted kevent will contain: +.Bl -column ".Va filter" +.It Sy Member Ta Sy Value +.It Va ident Ta asynchronous I/O control buffer pointer +.It Va filter Ta Dv EVFILT_AIO +.It Va flags Ta Dv EV_EOF +.It Va udata Ta +value stored in +.Va aio_sigevent.sigev_value +.El +.Pp +For +.Dv SIGEV_SIGNO +and +.Dv SIGEV_THREAD_ID +notifications, +the information for the queued signal will include +.Dv SI_ASYNCIO +in the +.Va si_code +field and the value stored in +.Va sigevent.sigev_value +in the +.Va si_value +field. +.Pp +For +.Dv SIGEV_THREAD +notifications, +the value stored in +.Va aio_sigevent.sigev_value +is passed to the +.Va aio_sigevent.sigev_notify_function +as described in +.Xr sigevent 3 . +.Sh SEE ALSO +.Xr aio_cancel 2 , +.Xr aio_error 2 , +.Xr aio_read 2 , +.Xr aio_readv 2 , +.Xr aio_return 2 , +.Xr aio_suspend 2 , +.Xr aio_waitcomplete 2 , +.Xr aio_write 2 , +.Xr aio_writev 2 , +.Xr lio_listio 2 , +.Xr sigevent 3 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +facility appeared as a kernel option in +.Fx 3.0 . +The +.Nm +kernel module appeared in +.Fx 5.0 . +The +.Nm +facility was integrated into all kernels in +.Fx 11.0 . diff --git a/static/freebsd/man4/alc.4 b/static/freebsd/man4/alc.4 new file mode 100644 index 00000000..5ce5ce97 --- /dev/null +++ b/static/freebsd/man4/alc.4 @@ -0,0 +1,183 @@ +.\" Copyright (c) 2009 Pyun YongHyeon +.\" 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 August 22, 2016 +.Dt ALC 4 +.Os +.Sh NAME +.Nm alc +.Nd Atheros AR813x/AR815x/AR816x/AR817x Gigabit/Fast Ethernet driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device alc" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_alc_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +device driver provides support for Atheros AR813x, AR815x, AR816x +and AR817x PCI Express Gigabit/Fast Ethernet controllers. +.Pp +All LOMs supported by the +.Nm +driver have TCP/UDP/IP checksum offload for transmit, TCP +segmentation offload (TSO), hardware VLAN tag stripping/insertion +features, Wake On Lan (WOL) and an interrupt moderation mechanism +as well as a 64-bit multicast hash filter. +.Pp +The AR813x, AR815x, AR816x and AR817x supports Jumbo Frames (up to +9216, 6144, 9216 and 9216 bytes, respectively), which can be +configured via the interface MTU setting. +Selecting an MTU larger than 1500 bytes with the +.Xr ifconfig 8 +utility configures the adapter to receive and transmit Jumbo Frames. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width ".Cm 10baseT/UTP" +.It Cm autoselect +Enable autoselection of the media type and options. +The user can manually override +the autoselected mode by adding media options to +.Xr rc.conf 5 . +.It Cm 10baseT/UTP +Set 10Mbps operation. +.It Cm 100baseTX +Set 100Mbps (Fast Ethernet) operation. +.It Cm 1000baseTX +Set 1000baseTX operation over twisted pair. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width ".Cm full-duplex" +.It Cm full-duplex +Force full duplex operation. +.It Cm half-duplex +Force half duplex operation. +.El +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +device driver provides support for the following Ethernet controllers: +.Pp +.Bl -bullet -compact +.It +Atheros AR8131 PCI Express Gigabit Ethernet controller +.It +Atheros AR8132 PCI Express Fast Ethernet controller +.It +Atheros AR8151 v1.0 PCI Express Gigabit Ethernet controller +.It +Atheros AR8151 v2.0 PCI Express Gigabit Ethernet controller +.It +Atheros AR8152 v1.1 PCI Express Fast Ethernet controller +.It +Atheros AR8152 v2.0 PCI Express Fast Ethernet controller +.It +Atheros AR8161 PCI Express Gigabit Ethernet controller +.It +Atheros AR8162 PCI Express Fast Ethernet controller +.It +Atheros AR8171 PCI Express Gigabit Ethernet controller +.It +Atheros AR8172 PCI Express Fast Ethernet controller +.It +Killer E2200 Gigabit Ethernet controller +.It +Killer E2400 Gigabit Ethernet controller +.It +Killer E2500 Gigabit Ethernet controller +.El +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width "xxxxxx" +.It Va hw.alc.msi_disable +This tunable disables MSI support on the Ethernet hardware. +The default value is 0. +.It Va hw.alc.msix_disable +This tunable disables MSI-X support on the Ethernet hardware. +The default value is 2, which means to enable or disable MSI-X based on the +card type; for "Killer" cards (E2x00) MSI-X will be disabled, while on other +cards it will be enabled. +Set this to 0 to force MSI-X to be enabled, or 1 to force it to be disabled +regardless of card type. +.El +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width "xxxxxx" +.It Va dev.alc.%d.int_rx_mod +Maximum amount of time to delay receive interrupt processing in +units of 1us. +The accepted range is 0 to 130000, the default is 100(100us). +Value 0 completely disables the interrupt moderation. +.It Va dev.alc.%d.int_tx_mod +Maximum amount of time to delay transmit interrupt processing in +units of 1us. +The accepted range is 0 to 130000, the default is 1000(1ms). +Value 0 completely disables the interrupt moderation. +.It Va dev.alc.%d.process_limit +Maximum amount of Rx frames to be processed in the event loop before +rescheduling a taskqueue. +The accepted range is 32 to 255, the default value is 64 events. +The interface does not need to be brought down and up again before +a change takes effect. +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +driver was written by +.An Pyun YongHyeon Aq Mt yongari@FreeBSD.org . +It first appeared in +.Fx 8.0 . diff --git a/static/freebsd/man4/ale.4 b/static/freebsd/man4/ale.4 new file mode 100644 index 00000000..fe48357c --- /dev/null +++ b/static/freebsd/man4/ale.4 @@ -0,0 +1,159 @@ +.\" Copyright (c) 2008 Pyun YongHyeon +.\" 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 November 12, 2008 +.Dt ALE 4 +.Os +.Sh NAME +.Nm ale +.Nd Atheros AR8121/AR8113/AR8114 Gigabit/Fast Ethernet driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device ale" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_ale_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +device driver provides support for Atheros AR8121 PCI Express +Gigabit Ethernet controllers and Atheros AR8113/AR8114 PCI +Express Fast Ethernet controllers. +.Pp +All LOMs supported by the +.Nm +driver have TCP/UDP/IP checksum offload for both receive and transmit, +TCP segmentation offload (TSO), hardware VLAN tag stripping/insertion +features, Wake On Lan (WOL) and an interrupt coalescing/moderation +mechanism as well as a 64-bit multicast hash filter. +.Pp +The AR8121 also supports Jumbo Frames (up to 8132 bytes), which can +be configured via the interface MTU setting. +Selecting an MTU larger than 1500 bytes with the +.Xr ifconfig 8 +utility configures the adapter to receive and transmit Jumbo Frames. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width ".Cm 10baseT/UTP" +.It Cm autoselect +Enable autoselection of the media type and options. +The user can manually override +the autoselected mode by adding media options to +.Xr rc.conf 5 . +.It Cm 10baseT/UTP +Set 10Mbps operation. +.It Cm 100baseTX +Set 100Mbps (Fast Ethernet) operation. +.It Cm 1000baseTX +Set 1000baseTX operation over twisted pair. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width ".Cm full-duplex" +.It Cm full-duplex +Force full duplex operation. +.It Cm half-duplex +Force half duplex operation. +.El +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +device driver provides support for the following Ethernet controllers: +.Pp +.Bl -bullet -compact +.It +Atheros AR8113 PCI Express Fast Ethernet controller +.It +Atheros AR8114 PCI Express Fast Ethernet controller +.It +Atheros AR8121 PCI Express Gigabit Ethernet controller +.El +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width "xxxxxx" +.It Va hw.ale.msi_disable +This tunable disables MSI support on the Ethernet hardware. +The default value is 0. +.It Va hw.ale.msix_disable +This tunable disables MSI-X support on the Ethernet hardware. +The default value is 0. +.El +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width "xxxxxx" +.It Va dev.ale.%d.int_rx_mod +Maximum amount of time to delay receive interrupt processing in +units of 1us. +The accepted range is 0 to 130000, the default is 30(30us). +Value 0 completely disables the interrupt moderation. +.It Va dev.ale.%d.int_tx_mod +Maximum amount of time to delay transmit interrupt processing in +units of 1us. +The accepted range is 0 to 130000, the default is 1000(1ms). +Value 0 completely disables the interrupt moderation. +.It Va dev.ale.%d.process_limit +Maximum amount of Rx frames to be processed in the event loop before +rescheduling a taskqueue. +The accepted range is 32 to 255, the default value is 128 events. +The interface does not need to be brought down and up again before +a change takes effect. +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +driver was written by +.An Pyun YongHyeon Aq Mt yongari@FreeBSD.org . +It first appeared in +.Fx 7.1 . diff --git a/static/freebsd/man4/alpm.4 b/static/freebsd/man4/alpm.4 new file mode 100644 index 00000000..5f8be943 --- /dev/null +++ b/static/freebsd/man4/alpm.4 @@ -0,0 +1,60 @@ +.\" Copyright (c) 1999 Nicolas Souchu +.\" 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 February 13, 1999 +.Dt ALPM 4 +.Os +.Sh NAME +.Nm alpm +.Nd Acer Aladdin 15x3 Power Management controller driver +.Sh SYNOPSIS +.Cd device smbus +.Cd device smb +.Cd device alpm +.Sh DESCRIPTION +This driver provides access to the +.Tn Aladdin 15x3 Power Management Unit . +Currently, only smbus controller +function is implemented. +.Pp +The embedded SMBus controller of the Aladdin chipset may give you access +to the monitoring facilities of your mainboard. +See +.Xr smb 4 +for writing user code to fetch voltages, temperature and so on from the +monitoring chip of your mainboard. +.Sh SEE ALSO +.Xr smb 4 , +.Xr smbus 4 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 4.0 . +.Sh AUTHORS +This +manual page was written by +.An Nicolas Souchu Aq Mt nsouch@FreeBSD.org . +.Sh BUGS +Only polling mode is supported. diff --git a/static/freebsd/man4/altq.4 b/static/freebsd/man4/altq.4 new file mode 100644 index 00000000..a6138022 --- /dev/null +++ b/static/freebsd/man4/altq.4 @@ -0,0 +1,200 @@ +.\" +.\" Copyright (c) 2004 Max Laier +.\" 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 January 21, 2024 +.Dt ALTQ 4 +.Os +.Sh NAME +.Nm ALTQ +.Nd "alternate queuing of network packets" +.Sh SYNOPSIS +.Cd options ALTQ +.Pp +.Cd options ALTQ_CBQ +.Cd options ALTQ_CODEL +.Cd options ALTQ_RED +.Cd options ALTQ_RIO +.Cd options ALTQ_HFSC +.Cd options ALTQ_CDNR +.Cd options ALTQ_PRIQ +.Cd options ALTQ_FAIRQ +.Sh DESCRIPTION +The +.Nm +system is a framework which provides several disciplines for queuing outgoing +network packets. +This is done by modifications to the interface packet queues. +See +.Xr altq 9 +for details. +.Pp +The user interface for +.Nm +is implemented by the +.Xr pfctl 8 +utility, so please refer to the +.Xr pfctl 8 +and the +.Xr pf.conf 5 +man pages for a complete description of the +.Nm +capabilities and how to use it. +.Ss Kernel Options +The following options in the kernel configuration file are related to +.Nm +operation: +.Pp +.Bl -tag -width ".Dv ALTQ_DEBUG" -compact +.It Dv ALTQ +Enable +.Nm . +.It Dv ALTQ_CBQ +Build the +.Dq "Class Based Queuing" +discipline. +.It Dv ALTQ_CODEL +Build the +.Dq "Controlled Delay" +discipline. +.It Dv ALTQ_RED +Build the +.Dq "Random Early Detection" +extension. +.It Dv ALTQ_RIO +Build +.Dq "Random Early Drop" +for input and output. +.It Dv ALTQ_HFSC +Build the +.Dq "Hierarchical Packet Scheduler" +discipline. +.It Dv ALTQ_CDNR +Build the traffic conditioner. +This option is meaningless at the moment as the conditioner is not used by +any of the available disciplines or consumers. +.It Dv ALTQ_PRIQ +Build the +.Dq "Priority Queuing" +discipline. +.It Dv ALTQ_FAIRQ +Build the +.Dq "Fair Queuing" +discipline. +.It Dv ALTQ_NOPCC +Required if the TSC is unusable. +.It Dv ALTQ_DEBUG +Enable additional debugging facilities. +.El +.Pp +Note that +.Nm Ns -disciplines +cannot be loaded as kernel modules. +In order to use a certain discipline you have to build it into a custom +kernel. +The +.Xr pf 4 +interface, that is required for the configuration process of +.Nm +can be loaded as a module. +.Sh SUPPORTED DEVICES +The driver modifications described in +.Xr altq 9 +are required to use a certain network card with +.Nm . +They have been applied to the following hardware drivers: +.Xr ae 4 , +.Xr age 4 , +.Xr alc 4 , +.Xr ale 4 , +.Xr aue 4 , +.Xr axe 4 , +.Xr bce 4 , +.Xr bfe 4 , +.Xr bge 4 , +.Xr bxe 4 , +.Xr cas 4 , +.Xr dc 4 , +.Xr em 4 , +.Xr epair 4 , +.Xr et 4 , +.Xr fxp 4 , +.Xr gem 4 , +.Xr igb 4 , +.Xr ix 4 , +.Xr jme 4 , +.Xr le 4 , +.Xr liquidio 4 , +.Xr msk 4 , +.Xr mxge 4 , +.Xr my 4 , +.Xr nfe 4 , +.Xr nge 4 , +.Xr qlxgb 4 , +.Xr re 4 , +.Xr rl 4 , +.Xr sge 4 , +.Xr sis 4 , +.Xr sk 4 , +.Xr ste 4 , +.Xr stge 4 , +.Xr ti 4 , +.Xr udav 4 , +.Xr vge 4 , +.Xr vr 4 , +.Xr vte 4 , +and +.Xr xl 4 . +.Pp +The +.Xr tun 4 , +.Xr if_bridge 4 , +.Xr if_vlan 4 , +and +.Xr ng_iface 4 +pseudo drivers also do support +.Nm . +.Pp +An example: +.Bd -literal -offset indent +altq on igb0 cbq queue { def aq } +queue def bandwidth 90% cbq (default borrow) +queue aq bandwidth 10Mb cbq + +pass in on igb0.10 proto udp all queue aq keep state +.Ed +.Sh SEE ALSO +.Xr pf 4 , +.Xr pf.conf 5 , +.Xr ipfw 8 , +.Xr pfctl 8 , +.Xr altq 9 +.Sh HISTORY +The +.Nm +system first appeared in March 1997 and found home in the KAME project +(https://www.kame.net). +It was imported to +.Fx +in 5.3 . diff --git a/static/freebsd/man4/amdpm.4 b/static/freebsd/man4/amdpm.4 new file mode 100644 index 00000000..65d2706e --- /dev/null +++ b/static/freebsd/man4/amdpm.4 @@ -0,0 +1,71 @@ +.\" Copyright (c) 2001 Murray Stokely +.\" Copyright (c) 1999 Takanori Watanabe +.\" 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 December 31, 2005 +.Dt AMDPM 4 +.Os +.Sh NAME +.Nm amdpm +.Nd AMD 756/766/768/8111 Power Management controller driver +.Sh SYNOPSIS +.Cd device smbus +.Cd device smb +.Cd device amdpm +.Sh DESCRIPTION +This driver provides access to +.Tn AMD 756/766/768/8111 Power management controllers . +Currently, only the SMBus 1.0 controller function is implemented. +The SMBus 2.0 functionality of the AMD 8111 controller is supported via the +.Xr amdsmb 4 +driver. +.Pp +The embedded SMBus controller of the AMD 756 chipset may give you access +to the monitoring facilities of your mainboard. +See +.Xr smb 4 +for writing user code to fetch voltages, temperature and so on from the +monitoring chip of your mainboard. +.Sh SEE ALSO +.Xr amdsmb 4 , +.Xr intpm 4 , +.Xr smb 4 , +.Xr smbus 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 4.5 . +.Sh AUTHORS +.An -nosplit +This driver was written by +.An "Matthew C. Forman" . +Based heavily on the +.Nm alpm +driver by +.An Nicolas Souchu . +This manual page was written by +.An Murray Stokely Aq Mt murray@FreeBSD.org . +.Sh BUGS +Only polling mode is supported. diff --git a/static/freebsd/man4/amdsbwd.4 b/static/freebsd/man4/amdsbwd.4 new file mode 100644 index 00000000..676b06fc --- /dev/null +++ b/static/freebsd/man4/amdsbwd.4 @@ -0,0 +1,87 @@ +.\"- +.\" Copyright (c) 2009 Andriy Gapon +.\" 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 September 8, 2016 +.Dt AMDSBWD 4 +.Os +.Sh NAME +.Nm amdsbwd +.Nd device driver for the AMD southbridge watchdog timers +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device amdsbwd" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +amdsbwd_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides +.Xr watchdog 4 +support for the watchdog timers present on +the supported chipsets. +.Sh HARDWARE +The +.Nm +driver supports the following chipsets: +.Pp +.Bl -bullet -compact +.It +AMD SB600/7x0/8x0/9x0 southbridges +.It +AMD Axx/Hudson/Bolton FCHs +.It +AMD FCHs integrated into Family 15h Models 60h-6Fh, 70h-7Fh Processors +.It +AMD FCHs integrated into Family 16h Models 00h-0Fh, 30h-3Fh Processors +.El +.Sh SEE ALSO +.Xr watchdog 4 , +.Xr watchdog 8 , +.Xr watchdogd 8 , +.Xr watchdog 9 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 7.3 +and +.Fx 8.1 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Andriy Gapon Aq Mt avg@FreeBSD.org . +This manual page was written by +.An Andriy Gapon Aq Mt avg@FreeBSD.org . diff --git a/static/freebsd/man4/amdsmb.4 b/static/freebsd/man4/amdsmb.4 new file mode 100644 index 00000000..7f4b471a --- /dev/null +++ b/static/freebsd/man4/amdsmb.4 @@ -0,0 +1,55 @@ +.\" Copyright (c) 2005 Christian Brueffer +.\" 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 December 31, 2005 +.Dt AMDSMB 4 +.Os +.Sh NAME +.Nm amdsmb +.Nd "AMD-8111 SMBus 2.0 controller driver" +.Sh SYNOPSIS +.Cd "device pci" +.Cd "device smbus" +.Cd "device smb" +.Cd "device amdsmb" +.Sh DESCRIPTION +The +.Nm +driver provides access to the AMD-8111 SMBus 2.0 controller. +.Sh SEE ALSO +.Xr amdpm 4 , +.Xr intpm 4 , +.Xr smb 4 , +.Xr smbus 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 6.2 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Ruslan Ermilov Aq Mt ru@FreeBSD.org . diff --git a/static/freebsd/man4/amdsmn.4 b/static/freebsd/man4/amdsmn.4 new file mode 100644 index 00000000..fd3e247a --- /dev/null +++ b/static/freebsd/man4/amdsmn.4 @@ -0,0 +1,62 @@ +.\"- +.\" Copyright (c) 2017 Conrad Meyer +.\" 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 September 5, 2017 +.Dt AMDSMN 4 +.Os +.Sh NAME +.Nm amdsmn +.Nd device driver for +.Tn AMD +processor System Management Network +.Sh SYNOPSIS +To compile this driver into the kernel, place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device amdsmn" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the +following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +amdsmn_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for resources on the System Management Network bus +in +.Tn AMD +Family 17h processors. +.Sh SEE ALSO +.Xr loader 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 12.0 . +.Sh AUTHORS +.An Conrad Meyer Aq Mt cem@FreeBSD.org diff --git a/static/freebsd/man4/amdtemp.4 b/static/freebsd/man4/amdtemp.4 new file mode 100644 index 00000000..cd876f5c --- /dev/null +++ b/static/freebsd/man4/amdtemp.4 @@ -0,0 +1,110 @@ +.\"- +.\" Copyright (c) 2008 Rui Paulo +.\" 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 September 5, 2017 +.Dt AMDTEMP 4 +.Os +.Sh NAME +.Nm amdtemp +.Nd device driver for +.Tn AMD +processor on-die digital thermal sensor +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device amdtemp" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +amdtemp_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the on-die digital thermal sensor present +in +.Tn AMD +Family 0Fh, 10h, 11h, 12h, 14h, 15h, 16h, and 17h processors. +.Pp +For Family 0Fh processors, the +.Nm +driver reports each core's temperature through sysctl nodes, named +.Va dev.amdtemp.%d.core{0,1}.sensor{0,1} . +The driver also creates +.Va dev.cpu.%d.temperature +in the corresponding CPU device's sysctl tree, displaying the maximum +temperature of the two sensors located in each CPU core. +.Pp +For Family 10h, 11h, 12h, 14h, 15h, 16h, and 17h processors, the driver reports +each package's temperature through a sysctl node, named +.Va dev.amdtemp.%d.core0.sensor0 . +The driver also creates +.Va dev.cpu.%d.temperature +in the corresponding CPU device's sysctl tree, displaying the temperature +of the shared sensor located in each CPU package. +.Sh SYSCTL VARIABLES +The following variable is available as both +.Xr sysctl 8 +variable and +.Xr loader 8 +tunable: +.Bl -tag -width indent +.It Va dev.amdtemp.%d.sensor_offset +.El +Add the given offset to the temperature of the sensor. +Default is 0. +.Sh SEE ALSO +.Xr coretemp 4 , +.Xr loader 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 7.1 . +.Sh AUTHORS +.An Rui Paulo Aq Mt rpaulo@FreeBSD.org +.An Norikatsu Shigemura Aq Mt nork@FreeBSD.org +.An Jung-uk Kim Aq Mt jkim@FreeBSD.org +.Sh CAVEATS +For Family 10h and later processors, +.Do +(the reported temperature) is a non-physical temperature measured on +an arbitrary scale and it does not represent an actual physical +temperature like die or case temperature. +Instead, it specifies the processor temperature relative to the point +at which the system must supply the maximum cooling for the processor's +specified maximum case temperature and maximum thermal power dissipation +.Dc +according to +.Rs +.%T BIOS and Kernel Developer's Guide (BKDG) for AMD Processors +.%U http://developer.amd.com/resources/developer-guides-manuals/ +.Re diff --git a/static/freebsd/man4/aout.4 b/static/freebsd/man4/aout.4 new file mode 100644 index 00000000..78c18e0c --- /dev/null +++ b/static/freebsd/man4/aout.4 @@ -0,0 +1,144 @@ +.\" Copyright (c) 2012 Konstantin Belousov +.\" +.\" 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 ``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 August 14, 2012 +.Dt AOUT 4 +.Os +.Sh NAME +.Nm aout +.Nd kernel support for executing binary files in legacy a.out format +.Sh SYNOPSIS +.Bd -literal -offset indent +kldload a.out +.Ed +.Sh DESCRIPTION +The +.Xr a.out 5 +executable format was used before the release of +.Fx 3.0 . +Since i386 was the only supported architecture at that time, +.Xr a.out 5 +executables can only be activated on platforms that support +execution of i386 code, such as i386 and amd64. +.Pp +To add kernel support for old syscalls and old syscall invocation methods, +place the following options in the kernel configuration file: +.Bd -ragged -offset indent +.Cd "options COMPAT_43" +.br +.Cd "options COMPAT_FREEBSD32" +.Ed +.Pp +The +.Va COMPAT_FREEBSD32 +option is only required on 64-bit CPU architectures. +.Pp +The +.Va aout.ko +module needs to be loaded with the +.Xr kldload 8 +utility in order to support the +.Xr a.out 5 +image activator: +.Bd -ragged -offset indent +.Ic kldload aout +.Ed +.Pp +Alternatively, to load the module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +aout_load="YES" +.Ed +.Pp +The +.Xr a.out 5 +format was mainstream quite a long time ago. +Reasonable default settings and security requirements of +modern operating systems today contradict the default environment of that time +and require adjustments of the system to mimic natural environment for +old binaries. +.Pp +The following +.Xr sysctl 8 +tunables are useful for this: +.Bl -tag -offset indent -width "XXXXXXXXXXXXXXXXXXXXXXXXX" +.It Xo Va security.bsd.map_at_zero +.Xc +Set to 1 to allow mapping of process pages at address 0. +Some very old +.Va ZMAGIC +executable images require text mapping at address 0. +.It Xo Va kern.pid_max +.Xc +Old versions of +.Fx +used signed 16-bit type for +.Vt pid_t . +Current kernels use 32-bit type for +.Vt pid_t , +and allow process id's up to 99999. +Such values cannot be represented by old +.Vt pid_t , +mostly causing issues for processes using +.Xr wait 2 +syscalls, for example shells. +Set the sysctl to 30000 to work around the problem. +.It Xo Va kern.elf32.read_exec +.Xc +Set to 1 to force any accessible memory mapping performed by 32-bit +process to allow execution, see +.Xr mmap 2 . +Old i386 CPUs did not have a bit in PTE which disallowed execution +from the page, so many old programs did not specify +.Va PROT_EXEC +even for mapping of executable code. +The sysctl forces +.Va PROT_EXEC +if mapping has any access allowed at all. +The setting is only needed if the host architecture allows +non-executable mappings. +.El +.Sh SEE ALSO +.Xr execve 2 , +.Xr a.out 5 , +.Xr elf 5 , +.Xr sysctl 8 +.Sh HISTORY +The +.Xr a.out 5 +executable format was used on ancient +.At +and served as the main executable format for +.Fx +from the beginning up to +.Fx 2.2.9 . +In +.Fx 3.0 +it was superseded by +.Xr elf 5 . +.Sh AUTHORS +The +.Nm +manual page was written by +.An Konstantin Belousov Aq Mt kib@FreeBSD.org . +.Sh BUGS +On 64bit architectures, not all wrappers for older syscalls are implemented. diff --git a/static/freebsd/man4/apic.4 b/static/freebsd/man4/apic.4 new file mode 100644 index 00000000..022acd87 --- /dev/null +++ b/static/freebsd/man4/apic.4 @@ -0,0 +1,76 @@ +.\" Copyright (c) 2011 Alexander Motin +.\" 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 June 19, 2020 +.Dt APIC 4 +.Os +.Sh NAME +.Nm apic +.Nd Advanced Programmable Interrupt Controller (APIC) driver +.Sh SYNOPSIS +This driver is a mandatory part of amd64 kernel. +To compile this driver into i386 kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device apic" +.Ed +.Pp +The following tunables are settable from the +.Xr loader 8 : +.Bl -ohang +.It Va hint.apic. Ns Ar X Ns Va .clock +controls event timers functionality support. +Setting to 0, disables it. +Default value is 1. +.It Va hint.apic. Ns Ar X Ns Va .disabled +Set this to 1 to disable APIC support, falling back to the legacy PIC. +.El +.Sh DESCRIPTION +There are two components in the Intel APIC system, the local APIC (LAPIC) +and the I/O APIC. +There is one local APIC in each CPU in the system. +There is typically one I/O APIC for each peripheral bus in the system. +.Pp +Local APICs manage all external interrupts for a specific processor. +In addition, they are able to accept and generate inter-processor interrupts +(IPIs). +.Pp +I/O APICs contain a redirection table, which is used to route the interrupts +they receive from peripheral buses to one or more local APICs. +.Pp +Each local APIC includes one 32-bit programmable timer. +This driver uses them to supply kernel with one event timer named "LAPIC". +Event timer provided by the driver supports both one-shot and periodic modes. +Because of local APIC nature it is per-CPU. +The timer frequency is not reported by the platform and so automatically +measured by the driver on the first use. +Depending on CPU model this timer may stop in C3 and deeper CPU sleep states. +Driver automatically adjusts event timer priority and reports it to prevent +entering dangerous sleep states when it is used. +.Sh SEE ALSO +.Xr atrtc 4 , +.Xr attimer 4 , +.Xr eventtimers 4 , +.Xr hpet 4 diff --git a/static/freebsd/man4/appleir.4 b/static/freebsd/man4/appleir.4 new file mode 100644 index 00000000..8717bf1b --- /dev/null +++ b/static/freebsd/man4/appleir.4 @@ -0,0 +1,93 @@ +.\" Copyright (c) 2026 Abdelkader Boudih +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd February 13, 2026 +.Dt APPLEIR 4 +.Os +.Sh NAME +.Nm appleir +.Nd Apple IR receiver driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device appleir" +.Cd "device hidbus" +.Cd "device hid" +.Cd "device evdev" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 Ns : +.Bd -literal -offset indent +appleir_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for Apple IR receivers found in Mac computers +(2006-2011 era). +It supports both Apple Remote controls and generic IR remotes using the +NEC infrared protocol. +.Pp +Supported devices include: +.Bl -bullet -compact +.It +Apple IR Receiver (USB product IDs 0x8240, 0x8241, 0x8242, 0x8243, 0x1440) +.El +.Pp +The driver decodes proprietary Apple Remote button presses and provides +a default keymap for common NEC protocol codes used by generic IR remotes. +Unmapped button codes can be accessed via the raw HID device at +.Pa /dev/hidrawX +for custom userland remapping. +.Pp +The +.Pa /dev/input/eventX +device presents the remote control as an +evdev +input device with standard KEY_* codes suitable for media applications. +.Sh HARDWARE +The +.Nm +driver supports Apple IR receivers with USB vendor ID 0x05ac and the +following product IDs: +.Pp +.Bl -tag -width "0x8242" -compact +.It 0x8240 +Apple IR Receiver (first generation) +.It 0x8241 +Apple IR Receiver +.It 0x8242 +Apple IR Receiver (Mac Mini 2011, MacBook Pro 3,1) +.It 0x8243 +Apple IR Receiver +.It 0x1440 +Apple IR Receiver (slim) +.El +.Sh FILES +.Bl -tag -width ".Pa /dev/input/eventX" -compact +.It Pa /dev/input/eventX +evdev input device +.It Pa /dev/hidrawX +raw HID device for custom button mapping +.El +.Sh SEE ALSO +evdev , +.Xr hidbus 4 , +.Xr usbhid 4 +.Pp +NEC Infrared Transmission Protocol: +.Lk https://techdocs.altium.com/display/FPGA/NEC+Infrared+Transmission+Protocol +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 16.0 . +.Sh AUTHORS +.An Abdelkader Boudih Aq Mt freebsd@seuros.com +.Pp +Based on protocol reverse-engineering by James McKenzie and others. diff --git a/static/freebsd/man4/aq.4 b/static/freebsd/man4/aq.4 new file mode 100644 index 00000000..24850279 --- /dev/null +++ b/static/freebsd/man4/aq.4 @@ -0,0 +1,56 @@ +.\" Copyright (c) 2025 The FreeBSD Foundation +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd December 1, 2025 +.Dt AQ 4 +.Os +.Sh NAME +.Nm aq +.Nd Aquantia / Marvell AQ1xx 10 Gigabit Ethernet driver +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device aq" +.Ed +.Pp +To load the driver as a module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_aq_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +device driver provides support for PCIe 1/2.5/5/10 Gigabit Ethernet adapters +based on +Aquantia (now Marvell) AQtion AQC1xx Ethernet controllers. +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Pp +The +.Nm +driver is experimental, and has a number of caveats and limitations. +.Sh HARDWARE +The +.Nm +driver supports the following 10 Gigabit Ethernet PCIe controllers: +.Pp +.Bl -bullet -compact +.It +aQuantia AQC107 +.It +aQuantia AQC108 +.It +aQuantia AQC109 +.It +aQuantia AQC111 +.It +aQuantia AQC112 +.El +.Sh SEE ALSO +.Xr arp 4 , +.Xr miibus 4 , +.Xr ifconfig 8 diff --git a/static/freebsd/man4/arcmsr.4 b/static/freebsd/man4/arcmsr.4 new file mode 100644 index 00000000..c2e7b437 --- /dev/null +++ b/static/freebsd/man4/arcmsr.4 @@ -0,0 +1,179 @@ +.\" Copyright (c) 2005 Scott Long +.\" 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 April 5, 2026 +.Dt ARCMSR 4 +.Os +.Sh NAME +.Nm arcmsr +.Nd Areca RAID Controller driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device pci" +.Cd "device scbus" +.Cd "device da" +.Cd "device arcmsr" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +arcmsr_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the Areca ARC-11xx, ARC-12xx, ARC-13xx, +ARC-16xx and ARC-18xx series of SAS and SATA RAID controllers. +These controllers feature RAID-0, 1, 3, 5, 6, and 10 and +JBOD acceleration for up to 16 SATA drives. +RAID level and stripe level +migration, online capacity expansion, hot insertion/removal, automatic failover +and rebuild, and SMART are also supported. +Access to the arrays is provided +via the SCSI CAM +.Pa /dev/da? +device nodes. +A management interface is also present via the +.Pa /dev/arcmsr? +device node. +Management tools for i386 and amd64 are available from Areca. +.Sh HARDWARE +The +.Nm +driver supports the following +Areca PCI-X/PCIe SATA/SAS/NVMe RAID host adapters: +.Pp +.Bl -bullet -compact +.It +ARC-1110 +.It +ARC-1120 +.It +ARC-1130 +.It +ARC-1160 +.It +ARC-1170 +.It +ARC-1110ML +.It +ARC-1120ML +.It +ARC-1130ML +.It +ARC-1160ML +.It +ARC-1200 +.It +ARC-1201 +.It +ARC-1203 +.It +ARC-1210 +.It +ARC-1212 +.It +ARC-1213 +.It +ARC-1214 +.It +ARC-1216 +.It +ARC-1220 +.It +ARC-1222 +.It +ARC-1223 +.It +ARC-1224 +.It +ARC-1226 +.It +ARC-1230 +.It +ARC-1231 +.It +ARC-1260 +.It +ARC-1261 +.It +ARC-1270 +.It +ARC-1280 +.It +ARC-1210ML +.It +ARC-1220ML +.It +ARC-1231ML +.It +ARC-1261ML +.It +ARC-1280ML +.It +ARC-1380 +.It +ARC-1381 +.It +ARC-1680 +.It +ARC-1681 +.It +ARC-1880 +.It +ARC-1882 +.It +ARC-1883 +.It +ARC-1884 +.It +ARC-1886 +.El +.Sh FILES +.Bl -tag -width ".Pa /dev/arcmsr?" -compact +.It Pa /dev/da? +Array block device +.It Pa /dev/arcmsr? +Management interface +.El +.Sh SEE ALSO +.Xr da 4 , +.Xr scbus 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 5.4 . +.Sh AUTHORS +The driver was written by +.An Erich Chen Aq Mt erich@areca.com.tw . +.Sh BUGS +The driver has been tested on i386 and amd64. +It likely requires additional +work to function on big-endian architectures. diff --git a/static/freebsd/man4/arswitch.4 b/static/freebsd/man4/arswitch.4 new file mode 100644 index 00000000..5bcd6c68 --- /dev/null +++ b/static/freebsd/man4/arswitch.4 @@ -0,0 +1,92 @@ +.\"- +.\" Copyright (c) 2021 Felix Johnson +.\" +.\" 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 May 11, 2025 +.Dt ARSWITCH 4 +.Os +.Sh NAME +.Nm arswitch +.Nd Atheros AR8000 series Ethernet switch driver +.Sh SYNOPSIS +.Cd "device mdio" +.Cd "device etherswitch" +.Cd "device arswitch" +.Sh DESCRIPTION +The +.Nm +driver provides a management interface to Atheros AR8000 series Ethernet +switch controllers. +The driver uses an +.Xr mdio 4 +or +.Xr miibus 4 +interface to configure the ethernet interface. +.Pp +This driver supports port based vlan, and +IEEE 802.1Q (QinQ). +These options can be configured with the +.Xr etherswitchcfg 8 +command. +.Nm +supports +.Dv addtag , +.Dv striptag , +and +.Dv doubletag . +.Dv addtag +and +.Dv striptag +are mutually exclusive. +.Pp +Setting the switch MAC address is not supported. +.Sh HARDWARE +The +.Nm +driver supports the following Ethernet switch controllers: +.Pp +.Bl -bullet -compact +.It +Atheros AR8327 Seven-port Gigabit Ethernet Switch +.It +Atheros AR8316 Six-port Gigabit Ethernet Switch +.It +Atheros AR8236 Six-port Fast Ethernet Switch +.It +Atheros AR8226 Six-port Fast Ethernet Switch +.It +Atheros AR8216 Six-port Fast Ethernet Switch +.El +.Sh SEE ALSO +.Xr etherswitch 4 , +.Xr etherswitchcfg 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 12.0 . +.Sh AUTHORS +The +.Nm +manual was written by +.An Felix Johnson . diff --git a/static/freebsd/man4/asmc.4 b/static/freebsd/man4/asmc.4 new file mode 100644 index 00000000..9b42d021 --- /dev/null +++ b/static/freebsd/man4/asmc.4 @@ -0,0 +1,198 @@ +.\"- +.\" Copyright (c) 2007, 2008, 2009 Rui Paulo +.\" 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 ``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 March 29, 2026 +.Dt ASMC 4 +.Os +.Sh NAME +.Nm asmc +.Nd device driver for the Apple System Management Controller (SMC) +.Sh SYNOPSIS +To compile this driver into the kernel, place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device asmc" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +asmc_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver controls the Apple System Management Controller (SMC for short) +found on Intel Apple systems. +.Pp +The SMC is known to be found on the following systems: +.Pp +.Bl -bullet -offset indent -compact +.It +MacBook +.It +MacBook Pro +.It +Intel MacMini +.It +Mac Pro +.It +MacBook Air +.It +Intel iMac +.El +.Pp +With this driver, you can configure your keyboard backlight +brightness, check temperatures of several sensors, check the speed of +the internal fans and check the status of the Sudden Motion Sensor. +.Pp +Variables related to the SMC control and inspection are exported via +.Xr sysctl 3 +under the device tree +.Va dev.asmc . +.Sh KEYBOARD BACKLIGHT +On +.Tn MacBook Pro +systems, you can control the keyboard brightness by writing a value to +the +.Va dev.asmc.%d.light.control +sysctl MIB or with +.Xr backlight 8 +utility. +.Pp +The following sysctl MIBs contains the raw value returned by the left +and right light sensors: +.Va dev.asmc.%d.light.left +or +.Va dev.asmc.%d.light.right . +.Sh TEMPERATURES +The number of temperature sensors and their description varies among +systems. +You can inspect the temperature sensors on your system by traversing +the +.Va dev.asmc.temp +sysctl MIB. +.Pp +All values are in degrees celsius. +.Sh SYSTEM FANS +The +.Va dev.asmc.fan.%d +sysctl tree contains the leaf nodes +.Va speed , +.Va safespeed , +.Va minspeed , +.Va maxspeed +and +.Va targetspeed . +Each of these leaf nodes represent the current fan speed, the safest +minimum fan speed, the minimum speed and the maximum speed +respectively. +.Pp +All values are in RPM. +.Sh RAW SMC KEY ACCESS +When the kernel is compiled with the +.Dv ASMC_DEBUG +option, a set of sysctl nodes is provided under +.Va dev.asmc.%d.raw +for reading and writing arbitrary SMC keys by name. +.Pp +.Bl -tag -width "dev.asmc.%d.raw.value" -compact +.It Va dev.asmc.%d.raw.key +Set the 4-character SMC key name to access (e.g.,\& +.Dq AUPO ) . +Setting this automatically queries the key's length and type. +.It Va dev.asmc.%d.raw.value +Read or write the key's value as a hex string. +.It Va dev.asmc.%d.raw.len +The auto-detected value length in bytes (read-only). +.It Va dev.asmc.%d.raw.type +The 4-character SMC type string (e.g.,\& +.Dq ui8 , +.Dq flt ) +(read-only). +.El +.Pp +Example usage: +.Bd -literal -offset indent +sysctl dev.asmc.0.raw.key=AUPO +sysctl dev.asmc.0.raw.value +sysctl dev.asmc.0.raw.value=01 +.Ed +.Sh SUDDEN MOTION SENSOR +The Sudden Motion Sensor (SMS for short) is a device that detects +laptop movement and notifies the operating system via an interrupt. +The sysctl MIBs present under +.Va dev.asmc.sms +all relate to the SMS. +.Pp +The most interesting usage of this device is to park the disk heads +when the laptop is moved harshly. +First, you need to install +.Xr ataidle 8 Pq Pa ports/sysutils/ataidle +and then configure +.Xr devd 8 +the following way: +.Bd -literal -offset indent +notify 0 { + match "system" "ACPI"; + match "subsystem" "asmc"; + action "/usr/local/sbin/ataidle -s X Y"; +}; +.Ed +.Pp +Do not forget to change the +.Ar X +and +.Ar Y +values in the command above. +.Pp +Also, please note that parking the disk heads too many times can +dramatically reduce your hard drive's life span. +Do not rely solely on +the SMS to protect your hard drive: good care and common sense can +increase your hard drive's life. +.Sh FILES +.Bl -tag -width ".Pa /dev/backlight/asmc0" -compact +.It Pa /dev/backlight/asmc0 +Keyboard +.Xr backlight 8 +device node. +.Sh SEE ALSO +.Xr ataidle 8 Pq Pa ports/sysutils/ataidle , +.Xr backlight 8 , +.Xr devd 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 8.0 . +.Sh AUTHORS +.An Rui Paulo Aq Mt rpaulo@FreeBSD.org +(Google Summer of Code project) +.Sh BUGS +Support for the latest models was never tested and is most likely not +fully working. diff --git a/static/freebsd/man4/at45d.4 b/static/freebsd/man4/at45d.4 new file mode 100644 index 00000000..3b49f5cf --- /dev/null +++ b/static/freebsd/man4/at45d.4 @@ -0,0 +1,182 @@ +.\" +.\" Copyright (c) 2019 Ian Lepore +.\" +.\" 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 ``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 March 2, 2019 +.Dt AT45D 4 +.Os +.Sh NAME +.Nm at45d +.Nd driver for DataFlash(tm) non-volatile storage devices +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device at45d" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +at45d_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the family of non-volatile storage +devices known collectively as DataFlash(tm). +DataFlash chips typically have part numbers beginning with AT45DB. +The +.Nm +driver supports only the SPI bus versions of each AT45DB device, +indicated by the last digit of the part number being 1 or 2. +.Pp +The +.Nm +driver uses opcode 0x9f to read the manufacturer and device ID +data to determine whether the device is supported. +The device ID is looked up using a table of data within the driver +which describes the attributes of each supported device, +such as block size, sector size, and device capacity. +When a supported device is found, the +.Nm +driver creates a disk device and makes it accessible at +.Pa /dev/flash/at45d? . +The new disk device is then tasted by the available +.Xr geom 4 +modules as with any disk device. +.Sh HARDWARE +The +.Nm +driver provides support for the following devices: +.Pp +.Bl -bullet -compact +.It +AT45DB011B +.It +AT45DB021B +.It +AT45DB041x +.It +AT45DB081B +.It +AT45DB161x +.It +AT45DB321x +.It +AT45DB321x +.It +AT45DB641E +.It +AT45DB642x +.El +.Sh FDT CONFIGURATION +On an +.Xr fdt 4 +based system, the +.Nm +device is defined as a slave device subnode +of the SPI bus controller node. +All properties documented in the +.Va spibus.txt +bindings document can be used with the +.Nm +device. +The most commonly-used ones are documented below. +.Pp +The following properties are required in the +.Nm +device subnode: +.Bl -tag -width indent +.It Va compatible +Must be the string "atmel,at45". +.It Va reg +Chip select address of device. +.It Va spi-max-frequency +The maximum bus frequency to use when communicating with this slave device. +Actual bus speed may be lower, depending on the capabilities of the SPI +bus controller hardware. +.El +.Pp +The following properties are optional for the +.Nm +device subnode: +.Bl -tag -width indent +.It Va freebsd,sectorsize +The sector size of the disk created for this storage device. +It must be a multiple of the device's page size. +The default is the device page size. +.It Va spi-cpha +Empty property indicating the slave device requires shifted clock +phase (CPHA) mode. +.It Va spi-cpol +Empty property indicating the slave device requires inverse clock +polarity (CPOL) mode. +.It Va spi-cs-high +Empty property indicating the slave device requires chip select active high. +.El +.Sh HINTS CONFIGURATION +On a +.Xr device.hints 5 +based system, such as +.Li MIPS , +these values are configurable for +.Nm : +.Bl -tag -width indent +.It Va hint.at45d.%d.at +The spibus the +.Nm +instance is attached to. +.It Va hint.at45d.%d.clock +The maximum bus frequency to use when communicating with this device. +Actual bus speed may be lower, depending on the capabilities of the SPI +bus controller hardware. +.It Va hint.at45d.%d.cs +The chip-select number to assert when performing I/O for this device. +Set the high bit (1 << 31) to invert the logic level of the chip select line. +.It Va hint.at45d.%d.mode +The SPI mode (0-3) to use when communicating with this device. +.It Va hint.at45d.%d.sectorsize +The sector size of the disk created for this storage device. +It must be a multiple of the device's page size. +The default is the device page size. +.El +.Sh FILES +.Bl -tag -width /dev/flash/at45d? +.It Pa /dev/flash/at45d? +Provides read/write access to the storage device. +.It Pa /dev/flash/spi? +An alias for the +.Pa /dev/at45d? +device, for backwards compatibility with older versions of the driver. +.El +.Sh SEE ALSO +.Xr fdt 4 , +.Xr geom 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 6.0 . diff --git a/static/freebsd/man4/ata.4 b/static/freebsd/man4/ata.4 new file mode 100644 index 00000000..29b6bbef --- /dev/null +++ b/static/freebsd/man4/ata.4 @@ -0,0 +1,253 @@ +.\" Copyright (c) 2011 Alexander Motin +.\" 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 March 23, 2015 +.Dt ATA 4 +.Os +.Sh NAME +.Nm ata +.Nd generic ATA/SATA controller driver +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device scbus" +.Cd "device ata" +.Ed +.Pp +Alternatively, to load the driver as set of modules at boot time, +place some of the following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ata_load="YES" + +ataisa_load="YES" +atapci_load="YES" + +ataacard_load="YES" +ataacerlabs_load="YES" +ataamd_load="YES" +ataati_load="YES" +atacenatek_load="YES" +atacypress_load="YES" +atacyrix_load="YES" +atahighpoint_load="YES" +ataintel_load="YES" +ataite_load="YES" +atajmicron_load="YES" +atamarvell_load="YES" +atamicron_load="YES" +atanational_load="YES" +atanetcell_load="YES" +atanvidia_load="YES" +atapromise_load="YES" +ataserverworks_load="YES" +atasiliconimage_load="YES" +atasis_load="YES" +atavia_load="YES" +.Ed +.Pp +The first line is for the common hardware independent code, and is a +prerequisite for the other modules. +The next three lines are generic bus-specific drivers. +The rest are vendor-specific PCI drivers. +.Pp +The following tunables are settable from the +.Xr loader 8 : +.Bl -ohang +.It Va hw.ata.ata_dma_check_80pin +set to 0 to disable the 80pin cable check (the default is 1, check the cable). +.It Va hint.atapci.X.msi +set to 1 to allow Message Signalled Interrupts (MSI) to be used by the +specified PCI ATA controller, if supported. +.It Va hint.ata.X.devX.mode +limits the initial ATA mode for the specified device on the specified channel. +.It Va hint.ata.X.mode +limits the initial ATA mode for every device on the specified channel. +.It Va hint.ata.X.pm_level +controls SATA interface Power Management for the specified channel, +allowing some power savings at the cost of additional command latency. +Possible values: +.Pp +.Bl -tag -width 4n -offset indent -compact +.It 0 +Interface Power Management is disabled. +This is the default value. +.It 1 +The device is allowed to initiate a PM state change; the host is passive. +.El +.It Va hint.ata. Ns Ar X Ns Va .dev Ns Ar X Ns Va .sata_rev +limits the initial SATA revision (speed) for the specified device +on the specified channel. +Values 1, 2 and 3 are respectively 1.5, 3 and 6Gbps. +.It Va hint.ata. Ns Ar X Ns Va .sata_rev +Same, but for every device on the specified channel. +.El +.Sh DESCRIPTION +The +.Nm +driver gives the +.Xr CAM 4 +subsystem access to the ATA (IDE) and SATA ports +of many generic controllers. +Depending on the controller, each PATA (IDE) +port or each one or two SATA ports are +represented to CAM as a separate bus with one or two targets. +Most of the bus-management details are handled by the ATA/SATA-specific +transport of CAM. +Connected ATA disks are handled by the ATA protocol disk peripheral driver +.Xr ada 4 . +ATAPI devices are handled by the SCSI protocol peripheral drivers +.Xr cd 4 , +.Xr da 4 , +.Xr sa 4 , +etc. +.Pp +This driver supports ATA, and for the most of controllers, ATAPI devices. +Command queuing and SATA port multipliers are not supported. +Device hot-plug and SATA interface power management is supported only on +some controllers. +.Pp +The +.Nm +driver can change the transfer mode when the system is up and running. +See the +.Cm negotiate +subcommand of +.Xr camcontrol 8 . +.Pp +The +.Nm +driver sets the maximum transfer mode supported by the hardware as default. +However, the +.Nm +driver sometimes warns: +.Dq Sy "DMA limited to UDMA33, non-ATA66 cable or device". +This means that +the +.Nm +driver has detected that the required 80 conductor cable is not present +or could not be detected properly, +or that one of the devices on the channel only accepts up +to UDMA2/ATA33. +The +.Va hw.ata.ata_dma_check_80pin +tunable can be set to 0 to disable this check. +.Sh HARDWARE +The +.Nm +driver supports the IDE interface on the following ATA/SATA controllers: +.Pp +.Bl -tag -width "Silicon Image:" -compact +.It Acard: +ATP850P, ATP860A, ATP860R, ATP865A, ATP865R. +.It ALI: +M5228, M5229, M5281, M5283, M5287, M5288, M5289. +.It AMD: +AMD756, AMD766, AMD768, AMD8111, CS5536. +.It ATI: +IXP200, IXP300, IXP400, IXP600, IXP700, IXP800. +.It CMD: +CMD646, CMD646U2, CMD648, CMD649. +.It Cypress: +Cypress 82C693. +.It Cyrix: +Cyrix 5530. +.It HighPoint: +HPT302, HPT366, HPT368, HPT370, HPT371, HPT372, HPT372N, HPT374. +.It Intel: +6300ESB, 31244, PIIX, PIIX3, PIIX4, ESB2, ICH, ICH0, ICH2, ICH3, ICH4, ICH5, +ICH6, ICH7, ICH8, ICH9, ICH10, SCH, PCH. +.It ITE: +IT8211F, IT8212F, IT8213F. +.It JMicron: +JMB360, JMB361, JMB363, JMB365, JMB366, JMB368. +.It Marvell +88SE6101, 88SE6102, 88SE6111, 88SE6121, 88SE6141, 88SE6145. +.It National: +SC1100. +.It NetCell: +NC3000, NC5000. +.It nVidia: +nForce, nForce2, nForce2 MCP, nForce3, nForce3 MCP, nForce3 Pro, nForce4, +MCP51, MCP55, MCP61, MCP65, MCP67, MCP73, MCP77, MCP79, MCP89. +.It Promise: +PDC20246, PDC20262, PDC20263, PDC20265, PDC20267, PDC20268, PDC20269, PDC20270, +PDC20271, PDC20275, PDC20276, PDC20277, PDC20318, PDC20319, PDC20371, PDC20375, +PDC20376, PDC20377, PDC20378, PDC20379, PDC20571, PDC20575, PDC20579, PDC20580, +PDC20617, PDC20618, PDC20619, PDC20620, PDC20621, PDC20622, PDC40518, PDC40519, +PDC40718, PDC40719. +.It ServerWorks: +HT1000, ROSB4, CSB5, CSB6, K2, Frodo4, Frodo8. +.It Silicon Image: +SiI0680, SiI3112, SiI3114, SiI3512. +.It SiS: +SIS180, SIS181, SIS182, SIS5513, SIS530, SIS540, SIS550, SIS620, SIS630, +SIS630S, SIS633, SIS635, SIS730, SIS733, SIS735, SIS745, SIS961, SIS962, +SIS963, SIS964, SIS965. +.It VIA: +VT6410, VT6420, VT6421, VT82C586, VT82C586B, VT82C596, VT82C596B, VT82C686, +VT82C686A, VT82C686B, VT8231, VT8233, VT8233A, VT8233C, VT8235, VT8237, +VT8237A, VT8237S, VT8251, CX700, VX800, VX855, VX900. +.El +.Pp +Some of above chips can be configured for AHCI mode. +In such case they are supported by +.Xr ahci 4 +driver instead. +.Pp +Unknown ATA chipsets are supported in PIO modes, and if the standard +busmaster DMA registers are present and contain valid setup, DMA is +also enabled, although the max mode is limited to UDMA33, as it is +not known what the chipset can do and how to program it. +.Sh NOTES +Please remember that in order to use UDMA4/ATA66 and above modes you +.Em must +use 80 conductor cables. +Please assure that ribbon cables are no longer than 45cm. +In case of rounded ATA cables, the length depends on the +quality of the cables. +SATA cables can be up to 1m long according to the specification. +External SATA cables can be 2m long and more, but not all controllers +work well on long cables, especially at high speeds. +.Sh SEE ALSO +.Xr ada 4 , +.Xr ahci 4 , +.Xr cam 4 , +.Xr cd 4 , +.Xr mvs 4 , +.Xr siis 4 , +.Xr camcontrol 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 4.0 . +It was turned into a +.Xr CAM 4 +interface module in +.Fx 9.0 . +.Sh AUTHORS +.An Alexander Motin Aq Mt mav@FreeBSD.org +.An S\(/oren Schmidt Aq Mt sos@FreeBSD.org diff --git a/static/freebsd/man4/ath.4 b/static/freebsd/man4/ath.4 new file mode 100644 index 00000000..b40ccbd1 --- /dev/null +++ b/static/freebsd/man4/ath.4 @@ -0,0 +1,283 @@ +.\"- +.\" Copyright (c) 2002-2009 Sam Leffler, Errno Consulting +.\" 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, +.\" without modification. +.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer +.\" similar to the "NO WARRANTY" disclaimer below ("Disclaimer") and any +.\" redistribution must be conditioned upon including a substantially +.\" similar Disclaimer requirement for further binary redistribution. +.\" +.\" NO WARRANTY +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTIBILITY +.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL +.\" THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR 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 DAMAGES. +.\"/ +.Dd August 7, 2023 +.Dt ATH 4 +.Os +.Sh NAME +.Nm ath +.Nd "Atheros IEEE 802.11 wireless network driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ath" +.Cd "device ath_hal" +.Cd "device ath_rate_sample" +.Cd "device wlan" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_ath_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for wireless network adapters based on +the Atheros AR5210, AR5211, AR5212, AR5416 and AR9300 programming APIs. +These APIs are used by a wide variety of chips; most all chips with +a PCI, PCIe and/or CardBus interface are supported. +.Pp +Supported features include 802.11 and 802.3 frames, power management, BSS, +IBSS, MBSS, WDS/DWDS TDMA, and host-based access point operation modes. +All host/device interaction is via DMA. +.Pp +The +.Nm +driver encapsulates all IP and ARP traffic as 802.11 frames, however +it can receive either 802.11 or 802.3 frames. +Transmit speed and operating mode is selectable +and depends on the specific chipset. +AR5210-based devices support 802.11a operation with transmit speeds +of 6 Mbps, 9 Mbps, 12 Mbps, 18 Mbps, 24 Mbps, 36 Mbps, 48 Mbps, and 54 Mbps. +AR5211-based devices support 802.11a and 802.11b operation with transmit +speeds as above for 802.11a operation and +1Mbps, 2Mbps, 5.5 Mbps and 11Mbps for 802.11b operation. +AR5212-based devices support 802.11a, 802.11b, and 802.11g operation +with transmit speeds appropriate to each. +AR5416 and later class devices are capable of 802.11n operation. +Most chips also support an Atheros Turbo Mode (TM) that operates in +the 5GHz frequency range with 2x the transmit speeds. +Some chips also support Turbo mode in the 2.4GHz range with 802.11g +though this support is not presently available due to regulatory requirements. +(Note that Turbo modes are, however, +only interoperable with other Atheros-based devices.) +AR5212-based and AR5416-based devices also support half- (10MHz) and quarter-width (5MHz) channels. +The actual transmit speed used is dependent on signal quality and the +.Dq "rate control" +algorithm employed by the driver. +All chips support WEP encryption. +AR5212, AR5416 and later parts have hardware support for the +AES-CCM, TKIP, and Michael cryptographic +operations required for WPA. +To enable encryption, use +.Xr ifconfig 8 +as shown below. +.Pp +The driver supports +.Cm station , +.Cm adhoc , +.Cm adhoc-demo , +.Cm hostap , +.Cm mesh , +.Cm wds , +and +.Cm monitor +mode operation. +Multiple +.Cm hostap +virtual interfaces may be configured for simultaneous +use on cards that use a 5212 or later part. +When multiple interfaces are configured each may have a separate +mac address that is formed by setting the U/L bits in the mac +address assigned to the underlying device. +Any number of +.Cm wds +virtual interfaces may be configured together with +.Cm hostap +interfaces. +Multiple +.Cm station +interfaces may be operated together with +.Cm hostap +interfaces to construct a wireless repeater device. +The driver also support +.Cm tdma +operation when compiled with +.Cd "options IEEE80211_SUPPORT_TDMA" +(which also enables the required 802.11 support). +For more information on configuring this device, see +.Xr ifconfig 8 . +.Pp +Devices supported by the +.Nm +driver come in Cardbus, ExpressCard, Mini-PCI and Mini-PCIe packages. +Wireless cards in Cardbus and ExpressCard slots may be inserted and +ejected on the fly. +.Sh HARDWARE +The +.Nm +driver supports all Atheros Cardbus, ExpressCard, PCI and PCIe cards, +except those that are based on the AR5005VL chipset. +.Sh EXAMPLES +Join a specific BSS network with WEP encryption: +.Bd -literal -offset indent +ifconfig wlan0 create wlandev ath0 +ifconfig wlan0 inet 192.168.0.20 netmask 0xffffff00 ssid my_net \e + wepmode on wepkey 0x8736639624 +.Ed +.Pp +Join/create an 802.11b IBSS network with network name +.Dq Li my_net : +.Bd -literal -offset indent +ifconfig wlan0 create wlandev ath0 wlanmode adhoc +ifconfig wlan0 inet 192.168.0.22 netmask 0xffffff00 ssid my_net \e + mode 11b +.Ed +.Pp +Create an 802.11g host-based access point: +.Bd -literal -offset indent +ifconfig wlan0 create wlandev ath0 wlanmode hostap +ifconfig wlan0 inet 192.168.0.10 netmask 0xffffff00 ssid my_ap \e + mode 11g +.Ed +.Pp +Create an 802.11a mesh station: +.Bd -literal -offset indent +ifconfig wlan0 create wlandev ath0 wlanmode mesh +ifconfig wlan0 meshid my_mesh mode 11a inet 192.168.0.10/24 +.Ed +.Pp +Create two virtual 802.11a host-based access points, one with +WEP enabled and one with no security, and bridge them to +the fxp0 (wired) device: +.Bd -literal -offset indent +ifconfig wlan0 create wlandev ath0 wlanmode hostap \e + ssid paying-customers wepmode on wepkey 0x1234567890 \e + mode 11a up +ifconfig wlan1 create wlandev ath0 wlanmode hostap bssid \e + ssid freeloaders up +ifconfig bridge0 create addm wlan0 addm wlan1 addm fxp0 up +.Ed +.Pp +Create a master node in a two slot TDMA BSS configured to use +2.5 millisecond slots. +.Bd -literal -offset indent +ifconfig wlan0 create wlandev ath0 wlanmode tdma \e + ssid tdma-test tmdaslot 0 tdmaslotlen 2500 \e + channel 36 up +.Ed +.Sh DIAGNOSTICS +.Bl -diag +.It "ath%d: unable to attach hardware; HAL status %u" +The Atheros Hardware Access Layer was unable to configure the hardware +as requested. +The status code is explained in the HAL include file +.Pa sys/dev/ath/ath_hal/ah.h . +.It "ath%d: failed to allocate descriptors: %d" +The driver was unable to allocate contiguous memory for the transmit +and receive descriptors. +This usually indicates system memory is scarce and/or fragmented. +.It "ath%d: unable to setup a data xmit queue!" +The request to the HAL to set up the transmit queue for normal +data frames failed. +This should not happen. +.It "ath%d: unable to setup a beacon xmit queue!" +The request to the HAL to set up the transmit queue for 802.11 beacon frames +failed. +This should not happen. +.It "ath%d: 802.11 address: %s" +The MAC address programmed in the EEPROM is displayed. +.It "ath%d: hardware error; resetting" +An unrecoverable error in the hardware occurred. +Errors of this sort include unrecoverable DMA errors. +The driver will reset the hardware and continue. +.It "ath%d: rx FIFO overrun; resetting" +The receive FIFO in the hardware overflowed before the data could be +transferred to the host. +This typically occurs because the hardware ran short of receive +descriptors and had no place to transfer received data. +The driver will reset the hardware and continue. +.It "ath%d: unable to reset hardware; hal status %u" +The Atheros Hardware Access Layer was unable to reset the hardware +as requested. +The status code is explained in the HAL include file +.Pa sys/dev/ath/ath_hal/ah.h . +This should not happen. +.It "ath%d: unable to start recv logic" +The driver was unable to restart frame reception. +This should not happen. +.It "ath%d: device timeout" +A frame dispatched to the hardware for transmission did not complete in time. +The driver will reset the hardware and continue. +This should not happen. +.It "ath%d: bogus xmit rate 0x%x" +An invalid transmit rate was specified for an outgoing frame. +The frame is discarded. +This should not happen. +.It "ath%d: ath_chan_set: unable to reset channel %u (%u MHz)" +The Atheros Hardware Access Layer was unable to reset the hardware +when switching channels during scanning. +This should not happen. +.It "ath%d: failed to enable memory mapping" +The driver was unable to enable memory-mapped I/O to the PCI device registers. +This should not happen. +.It "ath%d: failed to enable bus mastering" +The driver was unable to enable the device as a PCI bus master for doing DMA. +This should not happen. +.It "ath%d: cannot map register space" +The driver was unable to map the device registers into the host address space. +This should not happen. +.It "ath%d: could not map interrupt" +The driver was unable to allocate an IRQ for the device interrupt. +This should not happen. +.It "ath%d: could not establish interrupt" +The driver was unable to install the device interrupt handler. +This should not happen. +.El +.Sh SEE ALSO +.Xr ath_hal 4 , +.Xr cardbus 4 , +.Xr intro 4 , +.Xr wlan 4 , +.Xr wlan_ccmp 4 , +.Xr wlan_tkip 4 , +.Xr wlan_wep 4 , +.Xr wlan_xauth 4 , +.Xr hostapd 8 , +.Xr ifconfig 8 , +.Xr wpa_supplicant 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 5.2 . +.Sh CAVEATS +Revision A1 of the D-LINK DWL-G520 and DWL-G650 are based on an +Intersil PrismGT chip and are not supported by this driver. +.Sh BUGS +The driver does supports optional station mode power-save operation. +.Pp +The AR5210 can only do WEP in hardware; consequently hardware assisted WEP +is disabled in order to allow software implementations of TKIP and CCMP to +function. +Hardware WEP can be re-enabled by modifying the driver. diff --git a/static/freebsd/man4/ath10k.4 b/static/freebsd/man4/ath10k.4 new file mode 100644 index 00000000..4e23382e --- /dev/null +++ b/static/freebsd/man4/ath10k.4 @@ -0,0 +1,103 @@ +.\"- +.\" Copyright (c) 2022-2024 Bjoern A. Zeeb +.\" +.\" 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 September 30, 2024 +.Dt ATH10K 4 +.Os +.Sh NAME +.Nm ath10k +.Nd Qualcomm Atheros IEEE 802.11ac wireless network driver +.Sh SYNOPSIS +The driver will auto-load without any user interaction using +.Xr devmatch 8 +if enabled in +.Xr rc.conf 5 . +.Pp +Only if auto-loading is explicitly disabled, place the following +lines in +.Xr rc.conf 5 +to manually load the driver as a module at boot time: +.Bd -literal -offset indent +kld_list="${kld_list} if_ath10k" +.Ed +.Pp +It is discouraged to load the driver from +.Xr loader 8 . +.Sh DESCRIPTION +The +.Nm +driver is derived from Qualcomm Atheros' Linux ath10k driver +.Pp +This driver requires firmware to be loaded before it will work. +The package +.Pa wifi-firmware-ath10k-kmod +from the +.Pa ports/net/wifi-firmware-ath10k-kmod +port needs to be installed before the driver is loaded. +Otherwise no +.Xr wlan 4 +interface can be created using +.Xr ifconfig 8 . +The driver uses the +.\" No LinuxKPI man pages so no .Xr here. +.Em linuxkpi_wlan +and +.Em linuxkpi +compat framework to bridge between the Linux and +native +.Fx +driver code as well as to the native +.Xr net80211 4 +wireless stack. +.Pp +While +.Nm +supports all 802.11 a/b/g/n and ac +the compatibility code currently only supports 802.11 a/b/g modes. +Support for 802.11 n/ac is to come. +.Sh HARDWARE +The +.Nm +driver supports PCIe devices with the following chipsets: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It QCA6174 +.It QCA9377 +.It QCA9887 +.It QCA9888 +.It QCA988X +.It QCA9984 +.It QCA99X0 +.El +.Sh SEE ALSO +.Xr wlan 4 , +.Xr ifconfig 8 , +.Xr wpa_supplicant 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 14.0 . +.Sh BUGS +Certainly. diff --git a/static/freebsd/man4/ath_hal.4 b/static/freebsd/man4/ath_hal.4 new file mode 100644 index 00000000..cc534911 --- /dev/null +++ b/static/freebsd/man4/ath_hal.4 @@ -0,0 +1,135 @@ +.\"- +.\" Copyright (c) 2002-2009 Sam Leffler, Errno Consulting +.\" 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, +.\" without modification. +.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer +.\" similar to the "NO WARRANTY" disclaimer below ("Disclaimer") and any +.\" redistribution must be conditioned upon including a substantially +.\" similar Disclaimer requirement for further binary redistribution. +.\" +.\" NO WARRANTY +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTIBILITY +.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL +.\" THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR 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 DAMAGES. +.\"/ +.Dd August 7, 2023 +.Dt ATH_HAL 4 +.Os +.Sh NAME +.Nm ath_hal +.Nd "Atheros Hardware Access Layer (HAL)" +.Sh SYNOPSIS +.Cd "device ath_hal" +or +.Cd "device ath_ar5210" +.Cd "device ath_ar5211" +.Cd "device ath_ar5212" +.Cd "device ath_rf2413" +.Cd "device ath_rf2417" +.Cd "device ath_rf2425" +.Cd "device ath_rf5111" +.Cd "device ath_rf5112" +.Cd "device ath_rf5413" +.Cd "device ath_ar5416" +.\".Cd "device ath_ar5312" +.\".Cd "device ath_rf2136" +.\".Cd "device ath_rf2137" +.Cd "device ath_ar9160" +.Cd "device ath_ar9280" +.Cd "device ath_ar9285" +.Cd "device ath_ar9287" +.Cd "device ath_ar9300" +.Sh DESCRIPTION +The hal provides hardware support for wireless network adapters based on +the Atheros AR5210, AR5211, AR5212, AR5213, AR2413, AR2417, AR2425, +AR5413, AR5416, AR5418, AR5424, AR9160, AR9220, AR9280, AR9285, +AR9287, AR9380, AR9390, AR9580, AR9590, AR9562 and QCA9565 +chips (and companion RF/baseband parts). +This code is part of the +.Xr ath 4 +driver but configured separately to allow fine-grained control +over the set of chips supported. +Selecting +.Nm +enables support for all PCI and Cardbus devices. +.Pp +Some devices come in Cardbus/MiniPCI/PCI format. +Others (for example AR2413, AR2427, AR5418, AR9280, AR9285, AR9287) come in +PCIe, Mini-PCIe or ExpressCard format. +.Pp +Historically this code has been released in a binary-only form +and packaged as a separate module. +With the release of source code for the hal this is no longer true +and the code is tightly integrated with the driver. +.Sh HARDWARE +The following cards are among those supported by the +.Nm +module: +.Pp +.Bl -column -compact "Samsung SWL-5200N" "AR5212" "Cardbus" "a/b/g" +.It Em "Card Chip Bus Standard" +.It "Aztech WL830PC AR5212 CardBus b/g" +.It "D-Link DWL-A650 AR5210 CardBus a" +.It "D-Link DWL-AB650 AR5211 CardBus a/b" +.It "D-Link DWL-A520 AR5210 PCI a" +.It "D-Link DWL-AG520 AR5212 PCI a/b/g" +.It "D-Link DWL-AG650 AR5212 CardBus a/b/g" +.It "D-Link DWL-G520B AR5212 PCI b/g" +.It "D-Link DWL-G650B AR5212 CardBus b/g" +.It "Elecom LD-WL54AG AR5212 Cardbus a/b/g" +.It "Elecom LD-WL54 AR5211 Cardbus a" +.It "Fujitsu E5454 AR5212 Cardbus a/b/g" +.It "Fujitsu FMV-JW481 AR5212 Cardbus a/b/g" +.It "Fujitsu E5454 AR5212 Cardbus a/b/g" +.It "HP NC4000 AR5212 PCI a/b/g" +.It "I/O Data WN-AB AR5212 CardBus a/b" +.It "I/O Data WN-AG AR5212 CardBus a/b/g" +.It "I/O Data WN-A54 AR5212 CardBus a" +.It "Linksys WMP55AG AR5212 PCI a/b/g" +.It "Linksys WPC51AB AR5211 CardBus a/b" +.It "Linksys WPC55AG AR5212 CardBus a/b/g" +.It "NEC PA-WL/54AG AR5212 CardBus a/b/g" +.It "Netgear WAG311 AR5212 PCI a/b/g" +.It "Netgear WAB501 AR5211 CardBus a/b" +.It "Netgear WAG511 AR5212 CardBus a/b/g" +.It "Netgear WG311 (aka WG311v1) AR5212 PCI b/g" +.It "Netgear WG311v2 AR5212 PCI b/g" +.It "Netgear WG311T AR5212 PCI b/g" +.It "Netgear WG511T AR5212 CardBus b/g" +.It "Orinoco 8480 AR5212 CardBus a/b/g" +.It "Orinoco 8470WD AR5212 CardBus a/b/g" +.It "Proxim Skyline 4030 AR5210 CardBus a" +.It "Proxim Skyline 4032 AR5210 PCI a" +.It "Samsung SWL-5200N AR5212 CardBus a/b/g" +.It "SMC SMC2735W AR5210 CardBus a" +.It "Sony PCWA-C700 AR5212 Cardbus a/b" +.It "Sony PCWA-C300S AR5212 Cardbus b/g" +.It "Sony PCWA-C500 AR5210 Cardbus a" +.It "3Com 3CRPAG175 AR5212 CardBus a/b/g" +.It "TP-LINK TL-WDN4800 AR9380 PCIe a/b/g/n" +.El +.Sh SEE ALSO +.Xr ath 4 +.Sh HISTORY +The +.Nm +module first appeared in +.Fx 5.2 . +.Sh BUGS +See +.Xr ath 4 +for known bugs. diff --git a/static/freebsd/man4/atkbd.4 b/static/freebsd/man4/atkbd.4 new file mode 100644 index 00000000..84087364 --- /dev/null +++ b/static/freebsd/man4/atkbd.4 @@ -0,0 +1,231 @@ +.\" +.\" Copyright (c) 1999 +.\" Kazutaka YOKOTA +.\" 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 as +.\" the first lines of this file unmodified. +.\" 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 ``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 January 29, 2008 +.Dt ATKBD 4 +.Os +.Sh NAME +.Nm atkbd +.Nd the AT keyboard interface +.Sh SYNOPSIS +.Cd "options ATKBD_DFLT_KEYMAP" +.Cd "makeoptions ATKBD_DFLT_KEYMAP=_keymap_name_" +.Cd "options KBD_DISABLE_KEYMAP_LOAD" +.Cd "device atkbd" +.Pp +In +.Pa /boot/device.hints : +.Cd hint.atkbd.0.at="atkbdc" +.Cd hint.atkbd.0.irq="1" +.Sh DESCRIPTION +The +.Nm +driver, together with the +.Nm atkbdc +driver, provides access to the AT 84 keyboard or the AT enhanced keyboard +which is connected to the AT keyboard controller. +.Pp +This driver is required for the console driver +.Xr syscons 4 +or +.Xr vt 4 . +.Pp +There can be only one +.Nm +device defined in the kernel configuration file. +This device also requires the +.Nm atkbdc +keyboard controller to be present. +The +.Em irq +number must always be 1; there is no provision of changing the number. +.Ss Function Keys +The AT keyboard has a number of function keys. +They are numbered as follows and can be associated with strings +by the +.Xr kbdcontrol 1 +command. +You can use a keyboard map file (see +.Xr kbdmap 5 ) +to map them to arbitrary keys, particularly +the functions in the range from 65 to 96 +which are not used by default. +.Pp +.Bl -tag -width "Function Key Number" -compact +.It "Function Key number" +Function Key +.It "1, 2,...12" +F1, F2,...\& F12 +.It "13, 14,...24" +Shift+F1, Shift+F2,...\& Shift+F12 +.It "25, 26,...36" +Ctl+F1, Ctl+F2,...\& Ctl+F12 +.It "37, 38,...48" +Shift+Ctl+F1, Shift+Ctl+F2,...\& Shift+Ctl+F12 +.It 49 +Home and Numpad 7 (without NumLock) +.It 50 +Up Arrow and Numpad 8 (without NumLock) +.It 51 +Page Up and Numpad 9 (without NumLock) +.It 52 +Numpad - +.It 53 +Left Arrow and Numpad 4 (without NumLock) +.It 54 +Numpad 5 (without NumLock) +.It 55 +Right Arrow and Numpad 6 (without NumLock) +.It 56 +Numpad + +.It 57 +End and Numpad 1 (without NumLock) +.It 58 +Down Arrow and Numpad 2 (without NumLock) +.It 59 +Page Down and Numpad 3 (without NumLock) +.It 60 +Ins and Numpad 0 (without NumLock) +.It 61 +Del +.It 62 +Left GUI Key +.It 63 +Right GUI Key +.It 64 +Menu +.It "65, 66,...96" +free (not used by default) +.El +.Pp +See the man page for the +.Xr kbdcontrol 1 +command for how to assign a string to the function key. +.Sh DRIVER CONFIGURATION +.Ss Kernel Configuration Options +The following kernel configuration options control the +.Nm +driver. +.Bl -tag -width ATKBD_DFLT +.It Em ATKBD_DFLT_KEYMAP +This option sets the default, built-in keymap of the +.Nm +driver to the named keymap. +See +.Sx EXAMPLES +below. +.It Em KBD_DISABLE_KEYMAP_LOAD +The keymap can be modified by the +.Xr kbdcontrol 1 +command. +This option will disable this feature and prevent the user from +changing key assignment. +.El +.Ss Driver Flags +The +.Nm +driver accepts the following driver flags. +They can be set either in +.Pa /boot/device.hints , +or else from within the boot loader +(see +.Xr loader 8 ) . +.Bl -tag -width FAIL +.It bit 0 (FAIL_IF_NO_KBD) +By default the +.Nm +driver will install even if a keyboard is not actually connected to the +system. +This option prevents the driver from being installed in this situation. +.It bit 1 (NO_RESET) +When this option is given, the +.Nm +driver will not reset the keyboard when initializing it. +It may be useful for laptop computers whose function keys +have special functions and these functions are forgotten when the +keyboard is reset. +.It bit 2 (ALT_SCANCODESET) +Certain keyboards, such as those on some ThinkPad models, behave +like the old XT keyboard and require this option. +.It bit 3 (NO_PROBE_TEST) +When this option is given, the +.Nm +driver will not test the keyboard port during the probe routine. +Some machines hang during boot when this test is performed. +.El +.\".Sh FILES +.Sh EXAMPLES +The +.Nm +driver requires the keyboard controller +.Nm atkbdc . +Thus, the kernel configuration file should contain the following lines. +.Pp +.Dl "device atkbdc" +.Dl "device atkbd" +.Pp +The following example shows how to set the default, built-in keymap +to +.Pa jp.106.kbd . +.Pp +.Dl "device atkbdc" +.Dl "options ATKBD_DFLT_KEYMAP" +.Dl "makeoptions ATKBD_DFLT_KEYMAP=jp.106" +.Dl "device atkbd" +.Pp +In both cases, you also need to have following lines in +.Pa /boot/device.hints . +.Pp +.Dl hint.atkbdc.0.at="isa" +.Dl hint.atkbdc.0.port="0x060" +.Dl hint.atkbd.0.at="atkbdc" +.Dl hint.atkbd.0.irq="1" +.\".Sh DIAGNOSTICS +.\".Sh CAVEATS +.\".Sh BUGS +.Sh SEE ALSO +.Xr kbdcontrol 1 , +.Xr atkbdc 4 , +.Xr psm 4 , +.Xr syscons 4 , +.Xr vt 4 , +.Xr kbdmap 5 , +.Xr loader 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 3.1 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An S\(/oren Schmidt Aq Mt sos@FreeBSD.org +and +.An Kazutaka Yokota Aq Mt yokota@FreeBSD.org . +This manual page was written by +.An Kazutaka Yokota . diff --git a/static/freebsd/man4/atkbdc.4 b/static/freebsd/man4/atkbdc.4 new file mode 100644 index 00000000..48067c98 --- /dev/null +++ b/static/freebsd/man4/atkbdc.4 @@ -0,0 +1,126 @@ +.\" +.\" Copyright (c) 1999 +.\" Kazutaka YOKOTA +.\" 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 as +.\" the first lines of this file unmodified. +.\" 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 ``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 February 26, 2023 +.Dt ATKBDC 4 +.Os +.Sh NAME +.Nm atkbdc +.Nd the AT keyboard controller interface +.Sh SYNOPSIS +.Cd "options KBD_RESETDELAY=N" +.Cd "options KBD_MAXWAIT=N" +.Cd "options KBD_DELAY1=N" +.Cd "options KBD_DELAY2=N" +.Cd "options KBDIO_DEBUG=N" +.Cd "device atkbdc" +.Pp +In +.Pa /boot/device.hints : +.Cd hint.atkbdc.0.at="isa" +.Cd hint.atkbdc.0.port="0x060" +.Sh DESCRIPTION +The keyboard controller +.Nm +provides I/O services for the AT keyboard and PS/2 mouse style +pointing devices. +This controller is required for the keyboard driver +.Nm atkbd +and the PS/2 pointing device driver +.Nm psm . +.Pp +There can be only one +.Nm +device configured in the system. +.Sh DRIVER CONFIGURATION +.Ss Kernel Configuration Options +The following kernel configuration options can be used to control the +.Nm +driver. +They may be set in the kernel configuration file +(see +.Xr config 8 ) . +.Bl -tag -width MOUSE +.It Em KBD_RESETDELAY=X , KBD_MAXWAIT=Y +The keyboard driver +.Nm atkbd +and the pointing device driver +.Nm psm +may ask the +.Nm +driver to reset these devices during the boot process. +It sometimes takes a long time before these devices respond to +the reset command. +These options control how long the +.Nm +driver should +wait before eventually giving up -- the driver will wait +.Fa X +* +.Fa Y +msecs at most. +If the drivers seem unable to detect +devices, you may want to increase these values. +The default values are +200 msec for +.Fa X +and 5 +for +.Fa Y . +.It Em KBD_DELAY1=X, KBD_DELAY2=Y +DELAY1 sets the initial key repeat delay to +.Fa X . +The default value is 500ms. +DELAY2 sets the key repeat delay to +.Fa Y . +The default value is 100ms. +.It Em KBDIO_DEBUG=N +Sets the debug level to +.Fa N . +The default value is zero, which suppresses all debugging output. +.El +.\".Ss Driver Flags +.\".Sh FILES +.\".Sh EXAMPLE +.\".Sh DIAGNOSTICS +.\".Sh CAVEATS +.\".Sh BUGS +.Sh SEE ALSO +.Xr atkbd 4 , +.Xr psm 4 , +.Xr config 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 3.1 . +It is based on the kbdio module in +.Fx 2.2 . +.Sh AUTHORS +The kbdio module, the +.Nm +driver and this manual page were written by +.An Kazutaka Yokota Aq Mt yokota@FreeBSD.org . diff --git a/static/freebsd/man4/atopcase.4 b/static/freebsd/man4/atopcase.4 new file mode 100644 index 00000000..a0c95a9e --- /dev/null +++ b/static/freebsd/man4/atopcase.4 @@ -0,0 +1,134 @@ +.\" Copyright (c) 2023 Vladimir Kondratyev +.\" +.\" 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 August 17, 2023 +.Dt ATOPCASE 4 +.Os +.Sh NAME +.Nm atopcase +.Nd Apple HID-over-SPI transport driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device atopcase" +.Cd "device intelspi" +.Cd "device spibus" +.Cd "device hidbus" +.Cd "device hkbd" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +atopcase_load="YES" +hkbd_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for Human Interface Devices (HID) on +Serial Peripheral Interface (SPI) buses on Apple Intel Macs. +.Sh HARDWARE +The +.Nm +driver supports the following MacBooks produced in 2015-2018 years: +.Pp +.Bl -bullet -compact +.It +Macbook8,1 +.It +Macbook9,1 +.It +Macbook10,1 +.It +MacbookPro11,4 +.It +MacbookPro12,1 +.It +MacbookPro13,1 +.It +MacbookPro13,2 +.It +MacbookPro13,3 +.It +MacbookPro14,1 +.It +MacbookPro14,2 +.It +MacbookPro14,3 +.El +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va hw.hid.atopcase.debug +Debug output level, where 0 is debugging disabled and larger values increase +debug message verbosity. +Default is 0. +.El +.Sh FILES +.Bl -tag -width ".Pa /dev/backlight/atopcase0" -compact +.It Pa /dev/backlight/atopcase0 +Keyboard +.Xr backlight 8 +device node. +.El +.Sh SEE ALSO +.Xr acpi 4 , +.Xr loader.conf 5 , +.Xr backlight 8 , +.Xr loader 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 14.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was originally written by +.An Val Packett Aq Mt val@packett.cool +and marginally improved upon by +.An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org . +.Pp +This manual page was written by +.An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org . +.Sh BUGS +Device interrupts are not acknowledged on some hardware that results in +interrupt storm. +Installation of Darwin OSI in +.Xr acpi 4 +driver fixes the issue. +To install Darwin OSI add following lines to +.Xr loader.conf 5 : +.Bl -tag -width indent +.It Va hw.acpi.install_interface="Darwin" +.It Va hw.acpi.remove_interface="Windows 2009, Windows 2012" +.El diff --git a/static/freebsd/man4/atp.4 b/static/freebsd/man4/atp.4 new file mode 100644 index 00000000..3c0c5934 --- /dev/null +++ b/static/freebsd/man4/atp.4 @@ -0,0 +1,157 @@ +.\" Copyright (c) 2014 Rohit Grover . +.\" 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. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" 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 February 24, 2014 +.Dt ATP 4 +.Os +.Sh NAME +.Nm atp +.Nd Apple touchpad driver +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines into +your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device atp" +.Cd "device hid" +.Cd "device usb" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +atp_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the Apple Internal Trackpad device found in many +Apple laptops. +Older (Fountain/Geyser) and the newer (Wellspring) trackpad +families are all supported through a unified driver. +.Pp +The driver simulates a three\-button mouse using multi\-finger tap detection. +Single finger tap generates a left\-button click; two\-finger tap maps to the +middle button; whereas a three\-finger tap gets treated as a right button +click. +.Pp +There is support for 2\-finger horizontal scrolling, which translates to +page\-back/forward events; vertical multi\-finger scrolling emulates the mouse +wheel. +.Pp +A double\-tap followed by a drag is treated as a selection gesture; a +virtual left\-button click is assumed for the lifespan of the drag. +.Pp +.Nm +supports dynamic reconfiguration using +.Xr sysctl 8 ; +through nodes under +.Nm hw.usb.atp . +Pointer sensitivity can be controlled using the sysctl tunable +.Nm hw.usb.atp.scale_factor . +Smaller values of +.Fa scale_factor +result in faster movement. +. +A simple high-pass filter is used to reduce contributions +from small movements; the threshold for this filter may be controlled by +.Nm hw.usb.atp.small_movement . +. +The maximum tolerable duration of a touch gesture is controlled by +.Nm hw.usb.atp.touch_timeout +(in microseconds); beyond this period, touches are considered to be slides. +(This conversion also happens when a finger stroke accumulates at least +.Nm hw.usb.atp.slide_min_movement +movement (in mickeys). +. +The maximum time (in microseconds) to allow an association between a double- +tap and drag gesture may be controlled by +.Nm hw.usb.atp.double_tap_threshold . +. +Should one want to disable tap detection and rely only upon physical button +presses, set the following sysctl to a value of 2 +.Nm hw.usb.atp.tap_minimum . +. +.Sh HARDWARE +The +.Nm +driver provides support for the following Product IDs: +.Pp +.Bl -bullet -compact +.It +PowerBooks, iBooks (IDs: 0x020e, 0x020f, 0x0210, 0x0214, 0x0215, 0x0216) +.It +Core Duo MacBook & MacBook Pro (IDs: 0x0217, 0x0218, 0x0219) +.It +Core2 Duo MacBook & MacBook Pro (IDs: 0x021a, 0x021b, 0x021c) +.It +Core2 Duo MacBook3,1 (IDs: 0x0229, 0x022a, 0x022b) +.It +12 inch PowerBook and iBook (IDs: 0x030a, 0x030b) +.It +15 inch PowerBook (IDs: 0x020e, 0x020f, 0x0215) +.It +17 inch PowerBook (ID: 0x020d) +.It +Almost all recent Macbook-Pros and Airs (IDs: 0x0223, 0x0223, 0x0224, 0x0224, +0x0225, 0x0225, 0x0230, 0x0230, 0x0231, 0x0231, 0x0232, 0x0232, 0x0236, +0x0236, 0x0237, 0x0237, 0x0238, 0x0238, 0x023f, 0x023f, 0x0240, 0x0241, +0x0242, 0x0243, 0x0244, 0x0245, 0x0246, 0x0247, 0x0249, 0x024a, 0x024b, +0x024c, 0x024d, 0x024e, 0x0252, 0x0252, 0x0253, 0x0253, 0x0254, 0x0254, +0x0259, 0x025a, 0x025b, 0x0262, 0x0262, 0x0263, 0x0264, 0x0290, 0x0291, +0x0292) +.El +.Pp +To discover the product\-id of a touchpad, search for 'Trackpad' in the +output of +.Xr lshal 1 +and look up the property +.Nm usb_device.product_id . +.Sh FILES +.Nm +creates a blocking pseudo\-device file, +.Pa /dev/atp0 , +which presents the mouse as a +.Ar sysmouse +or +.Ar mousesystems +type device\-\-see +.Xr moused 8 +for an explanation of these mouse +types. +.Sh SEE ALSO +.Xr sysmouse 4 , +.Xr usb 4 , +.Xr loader.conf 5 , +.Xr xorg.conf 5 Pq Pa ports/x11/xorg , +.Xr moused 8 , +.Xr sysctl 8 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Rohit Grover Aq Mt rgrover1@gmail.com . diff --git a/static/freebsd/man4/atrtc.4 b/static/freebsd/man4/atrtc.4 new file mode 100644 index 00000000..942d6fe0 --- /dev/null +++ b/static/freebsd/man4/atrtc.4 @@ -0,0 +1,61 @@ +.\" Copyright (c) 2010 Alexander Motin +.\" 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 December 15, 2022 +.Dt ATRTC 4 +.Os +.Sh NAME +.Nm atrtc +.Nd AT Real-Time Clock (RTC) driver +.Sh SYNOPSIS +This driver is a mandatory part of i386/amd64 kernels. +.Pp +The following tunables are settable from the +.Xr loader 8 : +.Bl -ohang +.It Va hint.atrtc. Ns Ar X Ns Va .clock +controls event timers functionality support. +Setting to 0, disables it. +Default value is 1. +.It Va hw.atrtc.enabled +Forces enabling or disabling of the device(s). +Setting to 0 disables it, setting to 1 enables it, bypassing any platform +configuration hints. +Default value is -1 (autodetect). +.El +.Sh DESCRIPTION +This driver uses RTC hardware to supply kernel with time-of-day clock +with 1 second resolution and one event timer. +This hardware uses base frequency of 32768Hz for advancing time-of-day clock +and generating periodic interrupts. +Interrupts could be generated with fixed number of frequencies, from 2Hz to +8192Hz, obtained by dividing base frequency by one of supported power-of-2 +divisors. +.Pp +Event timer provided by the driver is irrelevant to CPU power states. +.Sh SEE ALSO +.Xr apic 4 , +.Xr attimer 4 , +.Xr eventtimers 4 , +.Xr hpet 4 diff --git a/static/freebsd/man4/attimer.4 b/static/freebsd/man4/attimer.4 new file mode 100644 index 00000000..a24cc6fe --- /dev/null +++ b/static/freebsd/man4/attimer.4 @@ -0,0 +1,85 @@ +.\" Copyright (c) 2010 Alexander Motin +.\" 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 May 26, 2014 +.Dt ATTIMER 4 +.Os +.Sh NAME +.Nm attimer +.Nd i8254 Programmable Interval Timer (AT Timer) driver +.Sh SYNOPSIS +This driver is a mandatory part of x86 kernels. +.Pp +The following tunables are settable from the +.Xr loader 8 : +.Bl -ohang +.It Va hint.attimer. Ns Ar X Ns Va .clock +controls support for the event timer functionality. +Setting this value to +.Dv 0 +disables it. +The default value is +.Dv 1 . +.It Va hint.attimer. Ns Ar X Ns Va .timecounter +controls support for the time counter functionality. +Setting this value to +.Dv 0 +disables it. +The default value is +.Dv 1 . +.It Va hw.i8254.freq +allows overriding the default counter frequency. +The same value is also available at run-time via the +.Va machdep.i8254_freq +sysctl. +.El +.Sh DESCRIPTION +This driver uses i8254 Programmable Interval Timer (AT Timer) hardware +to supply the kernel with one timecounter and one event timer, and to generate +sound tones for the system speaker. +This hardware includes three channels. +Each channel includes a 16 bit counter which decreases with a known, +platform-dependent frequency. +Counters can operate in several different modes, including periodic and +one-shot. +The output of each channel has platform-defined wiring: one channel is wired +to the interrupt controller and may be used as event timer, one channel is +wired to the speaker and used to generate sound tones, and one timer is reserved +for platform purposes. +.Pp +The +.Nm +driver uses a single hardware channel to provide both time counter and event +timer functionality. +To make this possible, the respective counter must be running in periodic mode. +As a result, the one-shot event timer mode is supported only when time counter +functionality is disabled. +.Pp +The event timer provided by the driver is irrelevant to CPU power states. +.Sh SEE ALSO +.Xr apic 4 , +.Xr atrtc 4 , +.Xr eventtimers 4 , +.Xr hpet 4 , +.Xr timecounters 4 diff --git a/static/freebsd/man4/audit.4 b/static/freebsd/man4/audit.4 new file mode 100644 index 00000000..54434101 --- /dev/null +++ b/static/freebsd/man4/audit.4 @@ -0,0 +1,158 @@ +.\" Copyright (c) 2006, 2019 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" This software was developed in part by BAE Systems, the University of +.\" Cambridge Computer Laboratory, and Memorial University under DARPA/AFRL +.\" contract FA8650-15-C-7558 ("CADETS"), as part of the DARPA Transparent +.\" Computing (TC) research program. +.\" +.\" 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 AUTHORS 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 AUTHORS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 28, 2019 +.Dt AUDIT 4 +.Os +.Sh NAME +.Nm audit +.Nd Security Event Audit +.Sh SYNOPSIS +.Cd "options AUDIT" +.Sh DESCRIPTION +Security Event Audit is a facility to provide fine-grained, configurable +logging of security-relevant events, and is intended to meet the requirements +of the Common Criteria (CC) Common Access Protection Profile (CAPP) +evaluation. +The +.Fx +.Nm +facility implements the de facto industry standard BSM API, file +formats, and command line interface, first found in the Solaris operating +system. +Information on the user space implementation can be found in +.Xr libbsm 3 . +.Pp +Audit support is enabled at boot, if present in the kernel, using an +.Xr rc.conf 5 +flag. +The audit daemon, +.Xr auditd 8 , +is responsible for configuring the kernel to perform +.Nm , +pushing +configuration data from the various audit configuration files into the +kernel. +.Ss Audit Special Device +The kernel +.Nm +facility provides a special device, +.Pa /dev/audit , +which is used by +.Xr auditd 8 +to monitor for +.Nm +events, such as requests to cycle the log, low disk +space conditions, and requests to terminate auditing. +This device is not intended for use by applications. +.Ss Audit Pipe Special Devices +Audit pipe special devices, discussed in +.Xr auditpipe 4 , +provide a configurable live tracking mechanism to allow applications to +tee the audit trail, as well as to configure custom preselection parameters +to track users and events in a fine-grained manner. +.Ss DTrace Audit Provider +The DTrace Audit Provider, +.Xr dtaudit 4 , +allows D scripts to enable capture of in-kernel audit records for kernel audit +event types, and then process their contents during audit commit or BSM +generation. +.Sh SEE ALSO +.Xr auditreduce 1 , +.Xr praudit 1 , +.Xr audit 2 , +.Xr auditctl 2 , +.Xr auditon 2 , +.Xr getaudit 2 , +.Xr getauid 2 , +.Xr poll 2 , +.Xr select 2 , +.Xr setaudit 2 , +.Xr setauid 2 , +.Xr libbsm 3 , +.Xr auditpipe 4 , +.Xr dtaudit 4 , +.Xr audit.log 5 , +.Xr audit_class 5 , +.Xr audit_control 5 , +.Xr audit_event 5 , +.Xr audit_user 5 , +.Xr audit_warn 5 , +.Xr rc.conf 5 , +.Xr audit 8 , +.Xr auditd 8 , +.Xr auditdistd 8 +.Sh HISTORY +The +.Tn OpenBSM +implementation was created by McAfee Research, the security +division of McAfee Inc., under contract to Apple Computer Inc.\& in 2004. +It was subsequently adopted by the TrustedBSD Project as the foundation for +the OpenBSM distribution. +.Pp +Support for kernel +.Nm +first appeared in +.Fx 6.2 . +.Sh AUTHORS +.An -nosplit +This software was created by McAfee Research, the security research division +of McAfee, Inc., under contract to Apple Computer Inc. +Additional authors include +.An Wayne Salamon , +.An Robert Watson , +and SPARTA Inc. +.Pp +The Basic Security Module (BSM) interface to audit records and audit event +stream format were defined by Sun Microsystems. +.Pp +This manual page was written by +.An Robert Watson Aq Mt rwatson@FreeBSD.org . +.Sh BUGS +The +.Fx +kernel does not fully validate that audit records submitted by user +applications are syntactically valid BSM; as submission of records is limited +to privileged processes, this is not a critical bug. +.Pp +Instrumentation of auditable events in the kernel is not complete, as some +system calls do not generate audit records, or generate audit records with +incomplete argument information. +.Pp +Mandatory Access Control (MAC) labels, as provided by the +.Xr mac 4 +facility, are not audited as part of records involving MAC decisions. +.Pp +Currently the +.Nm +syscalls are not supported for jailed processes. +However, if a process has +.Nm +session state associated with it, audit records will still be produced and a zonename token +containing the jail's ID or name will be present in the audit records. diff --git a/static/freebsd/man4/auditpipe.4 b/static/freebsd/man4/auditpipe.4 new file mode 100644 index 00000000..415216f5 --- /dev/null +++ b/static/freebsd/man4/auditpipe.4 @@ -0,0 +1,255 @@ +.\" Copyright (c) 2006 Robert N. M. Watson +.\" 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 AUTHORS 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 AUTHORS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 28, 2019 +.Dt AUDITPIPE 4 +.Os +.Sh NAME +.Nm auditpipe +.Nd "pseudo-device for live audit event tracking" +.Sh SYNOPSIS +.Cd "options AUDIT" +.Sh DESCRIPTION +While audit trail files +generated with +.Xr audit 4 +and maintained by +.Xr auditd 8 +provide a reliable long-term store for audit log information, current log +files are owned by the audit daemon until terminated making them somewhat +unwieldy for live monitoring applications such as host-based intrusion +detection. +For example, the log may be cycled and new records written to a new file +without notice to applications that may be accessing the file. +.Pp +The audit facility provides an audit pipe facility for applications requiring +direct access to live BSM audit data for the purposes of real-time +monitoring. +Audit pipes are available via a clonable special device, +.Pa /dev/auditpipe , +subject to the permissions on the device node, and provide a +.Qq tee +of the audit event stream. +As the device is clonable, more than one instance of the device may be opened +at a time; each device instance will provide independent access to all +records. +.Pp +The audit pipe device provides discrete BSM audit records; if the read buffer +passed by the application is too small to hold the next record in the +sequence, it will be dropped. +Unlike audit data written to the audit trail, the reliability of record +delivery is not guaranteed. +In particular, when an audit pipe queue fills, records will be dropped. +Audit pipe devices are blocking by default, but support non-blocking I/O, +asynchronous I/O using +.Dv SIGIO , +and polled operation via +.Xr select 2 +and +.Xr poll 2 . +.Pp +Applications may choose to track the global audit trail, or configure local +preselection parameters independent of the global audit trail parameters. +.Ss Audit Pipe Queue Ioctls +The following ioctls retrieve and set various audit pipe record queue +properties: +.Bl -tag -width ".Dv AUDITPIPE_GET_MAXAUDITDATA" +.It Dv AUDITPIPE_GET_QLEN +Query the current number of records available for reading on the pipe. +.It Dv AUDITPIPE_GET_QLIMIT +Retrieve the current maximum number of records that may be queued for reading +on the pipe. +.It Dv AUDITPIPE_SET_QLIMIT +Set the current maximum number of records that may be queued for reading on +the pipe. +The new limit must fall between the queue limit minimum and queue limit +maximum queryable using the following two ioctls. +.It Dv AUDITPIPE_GET_QLIMIT_MIN +Query the lowest possible maximum number of records that may be queued for +reading on the pipe. +.It Dv AUDITPIPE_GET_QLIMIT_MAX +Query the highest possible maximum number of records that may be queued for +reading on the pipe. +.It Dv AUDITPIPE_FLUSH +Flush all outstanding records on the audit pipe; useful after setting initial +preselection properties to delete records queued during the configuration +process which may not match the interests of the user process. +.It Dv AUDITPIPE_GET_MAXAUDITDATA +Query the maximum size of an audit record, which is a useful minimum size for +a user space buffer intended to hold audit records read from the audit pipe. +.El +.Ss Audit Pipe Preselection Mode Ioctls +By default, the audit pipe facility configures pipes to present records +matched by the system-wide audit trail, configured by +.Xr auditd 8 . +However, the preselection mechanism for audit pipes can be configured using +alternative criteria, including pipe-local flags and naflags settings, as +well as auid-specific selection masks. +This allows applications to track events not captured in the global audit +trail, as well as limit records presented to those of specific interest to +the application. +.Pp +The following ioctls configure the preselection mode on an audit pipe: +.Bl -tag -width ".Dv AUDITPIPE_GET_PRESELECT_MODE" +.It Dv AUDITPIPE_GET_PRESELECT_MODE +Return the current preselect mode on the audit pipe. +The ioctl argument should be of type +.Vt int . +.It Dv AUDITPIPE_SET_PRESELECT_MODE +Set the current preselection mode on the audit pipe. +The ioctl argument should be of type +.Vt int . +.El +.Pp +Possible preselection mode values are: +.Bl -tag -width ".Dv AUDITPIPE_PRESELECT_MODE_TRAIL" +.It Dv AUDITPIPE_PRESELECT_MODE_TRAIL +Use the global audit trail preselection parameters to select records for the +audit pipe. +.It Dv AUDITPIPE_PRESELECT_MODE_LOCAL +Use local audit pipe preselection; this model is similar to the global audit +trail configuration model, consisting of global flags and naflags parameters, +as well as a set of per-auid masks. +These parameters are configured using further ioctls. +.El +.Pp +After changing the audit pipe preselection mode, records selected under +earlier preselection configuration may still be in the audit pipe queue. +The application may flush the current record queue after changing the +configuration to remove possibly undesired records. +.Ss Audit Pipe Local Preselection Mode Ioctls +The following ioctls configure the preselection parameters used when an audit +pipe is configured for the +.Dv AUDITPIPE_PRESELECT_MODE_LOCAL +preselection mode. +.Bl -tag -width ".Dv AUDITPIPE_GET_PRESELECT_NAFLAGS" +.It Dv AUDITPIPE_GET_PRESELECT_FLAGS +Retrieve the current default preselection flags for attributable events on +the pipe. +These flags correspond to the +.Va flags +field in +.Xr audit_control 5 . +The ioctl argument should be of type +.Vt au_mask_t . +.It Dv AUDITPIPE_SET_PRESELECT_FLAGS +Set the current default preselection flags for attributable events on the +pipe. +These flags correspond to the +.Va flags +field in +.Xr audit_control 5 . +The ioctl argument should be of type +.Vt au_mask_t . +.It Dv AUDITPIPE_GET_PRESELECT_NAFLAGS +Retrieve the current default preselection flags for non-attributable events +on the pipe. +These flags correspond to the +.Va naflags +field in +.Xr audit_control 5 . +The ioctl argument should be of type +.Vt au_mask_t . +.It Dv AUDITPIPE_SET_PRESELECT_NAFLAGS +Set the current default preselection flags for non-attributable events on the +pipe. +These flags correspond to the +.Va naflags +field in +.Xr audit_control 5 . +The ioctl argument should be of type +.Vt au_mask_t . +.It Dv AUDITPIPE_GET_PRESELECT_AUID +Query the current preselection masks for a specific auid on the pipe. +The ioctl argument should be of type +.Vt "struct auditpipe_ioctl_preselect" . +The auid to query is specified via the +.Va ap_auid +field of type +.Vt au_id_t ; +the mask will be returned via +.Va ap_mask +of type +.Vt au_mask_t . +.It Dv AUDITPIPE_SET_PRESELECT_AUID +Set the current preselection masks for a specific auid on the pipe. +Arguments are identical to +.Dv AUDITPIPE_GET_PRESELECT_AUID , +except that the caller should properly initialize the +.Va ap_mask +field to hold the desired preselection mask. +.It Dv AUDITPIPE_DELETE_PRESELECT_AUID +Delete the current preselection mask for a specific auid on the pipe. +Once called, events associated with the specified auid will use the default +flags mask. +The ioctl argument should be of type +.Vt au_id_t . +.It Dv AUDITPIPE_FLUSH_PRESELECT_AUID +Delete all auid specific preselection specifications. +.El +.Sh EXAMPLES +The +.Xr praudit 1 +utility +may be directly executed on +.Pa /dev/auditpipe +to review the default audit trail. +.Sh SEE ALSO +.Xr poll 2 , +.Xr select 2 , +.Xr audit 4 , +.Xr dtaudit 4 , +.Xr audit_control 5 , +.Xr audit 8 , +.Xr auditd 8 +.Sh HISTORY +The OpenBSM implementation was created by McAfee Research, the security +division of McAfee Inc., under contract to Apple Computer Inc.\& in 2004. +It was subsequently adopted by the TrustedBSD Project as the foundation for +the OpenBSM distribution. +.Pp +Support for kernel audit first appeared in +.Fx 6.2 . +.Sh AUTHORS +The audit pipe facility was designed and implemented by +.An Robert Watson Aq Mt rwatson@FreeBSD.org . +.Pp +The Basic Security Module (BSM) interface to audit records and audit event +stream format were defined by Sun Microsystems. +.Sh BUGS +See the +.Xr audit 4 +manual page for information on audit-related bugs and limitations. +.Pp +The configurable preselection mechanism mirrors the selection model present +for the global audit trail. +It might be desirable to provide a more flexible selection model. +.Pp +The per-pipe audit event queue is fifo, with drops occurring if either the +user thread provides in sufficient for the record on the queue head, or on +enqueue if there is insufficient room. +It might be desirable to support partial reads of records, which would be +more compatible with buffered I/O as implemented in system libraries, and to +allow applications to select which records are dropped, possibly in the style +of preselection. diff --git a/static/freebsd/man4/aue.4 b/static/freebsd/man4/aue.4 new file mode 100644 index 00000000..9b82fdc4 --- /dev/null +++ b/static/freebsd/man4/aue.4 @@ -0,0 +1,208 @@ +.\" +.\" SPDX-License-Identifier: BSD-4-Clause +.\" +.\" Copyright (c) 1997, 1998, 1999 +.\" Bill Paul . 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 Bill Paul. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Bill Paul 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 Bill Paul OR THE VOICES IN HIS HEAD +.\" 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 May 26, 2025 +.Dt AUE 4 +.Os +.Sh NAME +.Nm aue +.Nd ADMtek AN986 Pegasus USB Fast Ethernet driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device uhci" +.Cd "device ohci" +.Cd "device usb" +.Cd "device miibus" +.Cd "device uether" +.Cd "device aue" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_aue_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for USB Fast Ethernet adapters based on the +ADMtek AN986 Pegasus chipset. +.Pp +The LinkSys USB10T adapters that contain the AN986 Pegasus chipset +will operate at 100Base-TX and full-duplex. +.Pp +The Pegasus contains a 10/100 +Ethernet MAC with MII interface and is designed to work with both +Ethernet and HomePNA transceivers. +Although designed to interface with +100Mbps peripherals, the existing USB standard specifies a maximum +transfer speed of 12Mbps. +Users should therefore not expect to actually +achieve 100Mbps speeds with these devices. +.Pp +The Pegasus supports a 64-bit multicast hash table, single perfect +filter entry for the station address and promiscuous mode. +Packets are +received and transmitted over separate USB bulk transfer endpoints. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width xxxxxxxxxxxxxxxxxxxx +.It autoselect +Enable autoselection of the media type and options. +The user can manually override +the autoselected mode by adding media options to the +.Pa /etc/rc.conf +file. +.It 10baseT/UTP +Set 10Mbps operation. +The +.Ar mediaopt +option can also be used to enable +.Ar full-duplex +operation. +Not specifying +.Ar full duplex +implies +.Ar half-duplex +mode. +.It 100baseTX +Set 100Mbps (Fast Ethernet) operation. +The +.Ar mediaopt +option can also be used to enable +.Ar full-duplex +operation. +Not specifying +.Ar full duplex +implies +.Ar half-duplex +mode. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width xxxxxxxxxxxxxxxxxxxx +.It full-duplex +Force full duplex operation. +The interface will operate in +half duplex mode if this media option is not specified. +.El +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports the following USB Fast Ethernet adapters based on the +ADMtek AN986 Pegasus chipset: +.Pp +.Bl -bullet -compact +.It +Abocom UFE1000, DSB650TX_NA +.It +Accton USB320-EC, SpeedStream +.It +ADMtek AN986, AN8511 +.It +Billionton USB100, USB100LP, USB100EL, USBE100 +.It +Corega Ether FEther USB-T, FEther USB-TX, FEther USB-TXS +.It +D-Link DSB-650, DSB-650TX, DSB-650TX-PNA +.It +Elecom LD-USBL/TX +.It +Elsa Microlink USB2Ethernet +.It +HP hn210e +.It +I-O Data USB ETTX +.It +Kingston KNU101TX +.It +LinkSys USB10T adapters that contain the AN986 Pegasus chipset, +USB10TA, USB10TX, USB100TX, USB100H1 +.It +MELCO LUA-TX, LUA2-TX +.It +Netgear FA101 +.It +Planex UE-200TX +.It +Sandberg USB to Network Link (model number 133-06) +.It +Siemens Speedstream +.It +SmartBridges smartNIC +.It +SMC 2202USB +.It +SOHOware NUB100 +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "aue%d: watchdog timeout" +A packet was queued for transmission and a transmit command was +issued, however the device failed to acknowledge the transmission +before a timeout expired. +.It "aue%d: no memory for rx list" +The driver failed to allocate an mbuf for the receiver ring. +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr ifconfig 8 +.Rs +.%T ADMtek AN986 data sheet +.%U http://www.admtek.com.tw +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 4.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Bill Paul Aq Mt wpaul@ee.columbia.edu . diff --git a/static/freebsd/man4/autofs.4 b/static/freebsd/man4/autofs.4 new file mode 100644 index 00000000..a721a6e2 --- /dev/null +++ b/static/freebsd/man4/autofs.4 @@ -0,0 +1,135 @@ +.\" Copyright (c) 2014 The FreeBSD Foundation +.\" +.\" This software was developed by Edward Tomasz Napierala under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" 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 AUTHORS 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 AUTHORS 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 December 2, 2017 +.Dt AUTOFS 4 +.Os +.Sh NAME +.Nm autofs +.Nd "automounter filesystem" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in the +kernel configuration file: +.Bd -ragged -offset indent +.Cd "options AUTOFS" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +autofs_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver is the kernel component of the automounter infrastructure. +Its job is to pass mount requests to the +.Xr automountd 8 +daemon, and pause the processes trying to access the automounted filesystem +until the mount is completed. +It is mounted by the +.Xr automount 8 . +.Sh OPTIONS +These options are available when +mounting +.Nm +file systems: +.Bl -tag -width indent +.It Cm master_options +Mount options for all filesystems specified in the map entry. +.It Cm master_prefix +Filesystem mountpoint prefix. +.El +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va vfs.autofs.debug +Verbosity level for log messages from the +.Nm +driver. +Set to 0 to disable logging or 1 to warn about potential problems. +Larger values enable debugging output. +Defaults to 1. +.It Va vfs.autofs.interruptible +Set to 1 to allow mount requests to be interrupted by signal. +Defaults to 1. +.It Va vfs.autofs.retry_delay +Number of seconds before retrying mount requests. +Defaults to 1. +.It Va vfs.autofs.retry_attempts +Number of attempts before failing mount. +Defaults to 3. +.It Va vfs.autofs.cache +Number of seconds to wait before reinvoking +.Xr automountd 8 +for any given file or directory. +Defaults to 600. +.It Va vfs.autofs.timeout +Number of seconds to wait for +.Xr automountd 8 +to handle the mount request. +Defaults to 30. +.It Va vfs.autofs.mount_on_stat +Set to 1 to trigger mount on +.Xr stat 2 +on mountpoint. +Defaults to 0. +.El +.Sh EXAMPLES +To unmount all mounted +.Nm +filesystems: +.Pp +.Dl "umount -At autofs" +.Pp +To mount +.Nm +filesystems specified in +.Xr auto_master 5 : +.Pp +.Dl "automount" +.Sh SEE ALSO +.Xr auto_master 5 , +.Xr automount 8 , +.Xr automountd 8 , +.Xr autounmountd 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 10.1 . +.Sh AUTHORS +The +.Nm +was developed by +.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org +under sponsorship from the FreeBSD Foundation. diff --git a/static/freebsd/man4/aw_gpio.4 b/static/freebsd/man4/aw_gpio.4 new file mode 100644 index 00000000..5cbc7562 --- /dev/null +++ b/static/freebsd/man4/aw_gpio.4 @@ -0,0 +1,102 @@ +.\"- +.\" Copyright (c) 2017 Emmanuel Vadot +.\" +.\" 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 October 8, 2024 +.Dt AW_GPIO 4 +.Os +.Sh NAME +.Nm aw_gpio +.Nd driver for the GPIO and pin muxing functionalities on Allwinner SoC +.Sh SYNOPSIS +.Cd "device gpio" +.Cd "options SOC_ALLWINNER_A10" +.Cd "options SOC_ALLWINNER_A13" +.Cd "options SOC_ALLWINNER_A20" +.Cd "options SOC_ALLWINNER_A31" +.Cd "options SOC_ALLWINNER_A31S" +.Cd "options SOC_ALLWINNER_A33" +.Cd "options SOC_ALLWINNER_A83T" +.Cd "options SOC_ALLWINNER_H2PLUS" +.Cd "options SOC_ALLWINNER_H3" +.Cd "options SOC_ALLWINNER_A64" +.Cd "options SOC_ALLWINNER_H5" +.Cd "options SOC_ALLWINNER_D1" +.Sh DESCRIPTION +The +.Nm +device driver provides support for the Allwinner pin muxing and GPIO on +Allwinner SoCs. +.Sh HARDWARE +The current version of the +.Nm +driver supports the GPIO/pinmuxing controller with one of the following +compatible strings : +.Pp +.Bl -bullet -compact +.It +allwinner,sun4i-a10-pinctrl +.It +allwinner,sun5i-a13-pinctrl +.It +allwinner,sun7i-a20-pinctrl +.It +allwinner,sun6i-a31-pinctrl +.It +allwinner,sun6i-a31s-pinctrl +.It +allwinner,sun6i-a31-r-pinctrl +.It +allwinner,sun6i-a33-pinctrl +.It +allwinner,sun8i-a83t-pinctrl +.It +allwinner,sun8i-a83t-r-pinctrl +.It +allwinner,sun8i-h3-pinctrl +.It +allwinner,sun50i-h5-pinctrl +.It +allwinner,sun8i-h3-r-pinctrl +.It +allwinner,sun50i-a64-pinctrl +.It +allwinner,sun50i-a64-r-pinctrl +.It +allwinner,sun20i-d1-pinctrl +.El +.Sh SEE ALSO +.Xr fdt 4 , +.Xr gpio 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 10.0 . +.Sh AUTHORS +The +.Nm +device driver was originally written by +.An Ganbold Tsagaankhuu Aq Mt ganbold@freebsd.org . +This manual page was written by +.An Emmanuel Vadot Aq Mt manu@freebsd.org . diff --git a/static/freebsd/man4/aw_mmc.4 b/static/freebsd/man4/aw_mmc.4 new file mode 100644 index 00000000..072835cc --- /dev/null +++ b/static/freebsd/man4/aw_mmc.4 @@ -0,0 +1,75 @@ +.\"- +.\" Copyright (c) 2017 Emmanuel Vadot +.\" +.\" 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 October 20, 2025 +.Dt AW_MMC 4 +.Os +.Sh NAME +.Nm aw_mmc +.Nd driver for the SD/MMC controller in Allwinner SoC +.Sh SYNOPSIS +.Cd "device mmc" +.Sh DESCRIPTION +The +.Nm +device driver provides support for the Allwinner SD/MMC host controller. +.Sh HARDWARE +The current version of the +.Nm +driver supports the SD/MMC controller with one of the following compatible strings : +.Pp +.Bl -bullet -compact +.It +allwinner,sun4i-a10-mmc +.It +allwinner,sun5i-a13-mmc +.It +allwinner,sun7i-a20-mmc +.It +allwinner,sun50i-a64-mmc +.It +allwinner,sun20i-d1-mmc +.El +.Sh SYSCTL VARIABLES +The following read-only variables are available via +.Xr sysctl 8 : +.Bl -tag -width indent +.It Va dev.aw_mmc.req_timeout +Request timeout in seconds (default: 10) . +.El +.Sh SEE ALSO +.Xr fdt 4 , +.Xr mmc 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 10.0 . +.Sh AUTHORS +The +.Nm +device driver was originally written by +.An Alexander Fedorov Aq Mt alexander.fedorov@rtlservice.com . +Later work and this manual page was done by +.An Emmanuel Vadot Aq Mt manu@freebsd.org . diff --git a/static/freebsd/man4/aw_rtc.4 b/static/freebsd/man4/aw_rtc.4 new file mode 100644 index 00000000..1296cd41 --- /dev/null +++ b/static/freebsd/man4/aw_rtc.4 @@ -0,0 +1,68 @@ +.\"- +.\" Copyright (c) 2017 Emmanuel Vadot +.\" +.\" 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 December 10, 2024 +.Dt AW_RTC 4 +.Os +.Sh NAME +.Nm aw_rtc +.Nd driver for the real-time clock (RTC) controller in Allwinner SoC +.Sh DESCRIPTION +The +.Nm +device driver provides support for the Allwinner RTC controller. +.Sh HARDWARE +The current version of the +.Nm +driver supports the RTC controller with any of the following compatible +strings: +.Pp +.Bl -bullet -compact +.It +allwinner,sun4i-a10-rtc +.It +allwinner,sun7i-a20-rtc +.It +allwinner,sun6i-a31-rtc +.It +allwinner,sun8i-h3-rtc +.It +allwinner,sun20i-d1-rtc +.It +allwinner,sun50i-h5-rtc +.It +allwinner,sun50i-h6-rtc +.El +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 11.0 . +.Sh AUTHORS +The +.Nm +device driver was written by +.An Vladimir Belian Aq Mt fate10@gmail.com . +This manual page was written by +.An Emmanuel Vadot Aq Mt manu@freebsd.org . diff --git a/static/freebsd/man4/aw_sid.4 b/static/freebsd/man4/aw_sid.4 new file mode 100644 index 00000000..5cd2f3d5 --- /dev/null +++ b/static/freebsd/man4/aw_sid.4 @@ -0,0 +1,79 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2018 Kyle Evans +.\" +.\" 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 October 8, 2024 +.Dt AW_SID 4 +.Os +.Sh NAME +.Nm aw_sid +.Nd driver for the SID controller in Allwinner SoC +.Sh DESCRIPTION +The +.Nm +device driver provides support for the Allwinner SID (Security ID) controller. +This controller provides root security keys that may be used as either a device +unique ID or to generate a MAC address. +.Sh HARDWARE +The +.Nm +driver supports the SID controller with one of the following compatible +strings: +.Pp +.Bl -bullet -compact +.It +allwinner,sun4i-a10-sid +.It +allwinner,sun7i-a20-sid +.It +allwinner,sun50i-a64-sid +.It +allwinner,sun8i-a83t-sid +.It +allwinner,sun8i-h3-sid +.It +allwinner,sun50i-h5-sid +.It +allwinner,sun20i-d1-sid +.El +.Sh SYSCTL VARIABLES +The following read-only variables are available via +.Xr sysctl 8 : +.Bl -tag -width indent +.It Va dev.aw_sid.rootkey +Root security key for this device. +.El +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 11.0 . +.Sh AUTHORS +The +.Nm +device driver was written by +.An Jared McNeill Aq Mt jmcneill@invisible.ca . +This manual page was written by +.An Kyle Evans Aq Mt kevans@FreeBSD.org . diff --git a/static/freebsd/man4/aw_spi.4 b/static/freebsd/man4/aw_spi.4 new file mode 100644 index 00000000..f8985e1c --- /dev/null +++ b/static/freebsd/man4/aw_spi.4 @@ -0,0 +1,55 @@ +.\"- +.\" Copyright (c) 2018 Emmanuel Vadot +.\" +.\" 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 May 17, 2018 +.Dt AW_SPI 4 +.Os +.Sh NAME +.Nm aw_spi +.Nd driver for the SPI controller in Allwinner SoC +.Sh SYNOPSIS +.Cd "device aw_spi" +.Sh DESCRIPTION +The +.Nm +device driver provides support for the Allwinner SPI host controller. +.Sh HARDWARE +The current version of the +.Nm +driver supports the SPI controller with one of the following compatible strings: +.Pp +.Bl -bullet -compact +.It +allwinner,sun8i-h3-spi +.El +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 12.0 . +.Sh AUTHORS +The +.Nm +device driver was written by +.An Emmanuel Vadot Aq Mt manu@freebsd.org . diff --git a/static/freebsd/man4/aw_syscon.4 b/static/freebsd/man4/aw_syscon.4 new file mode 100644 index 00000000..e32f329e --- /dev/null +++ b/static/freebsd/man4/aw_syscon.4 @@ -0,0 +1,67 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2018 Kyle Evans +.\" +.\" 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 November 11, 2024 +.Dt AW_SYSCON 4 +.Os +.Sh NAME +.Nm aw_syscon +.Nd driver for the system controller in Allwinner SoC +.Sh DESCRIPTION +The +.Nm +device driver provides support for the Allwinner system controller. +This controller provides registers for tying together related functionality in a +common space. +.Nm +is required for ethernet functionality on supported devices. +.Sh HARDWARE +The +.Nm +driver supports the system controller with one of the following compatible +strings: +.Pp +.Bl -bullet -compact +.It +allwinner,sun50i-a64-system-controller +.It +allwinner,sun50i-a64-system-control +.It +allwinner,sun8i-a83t-system-controller +.It +allwinner,sun8i-h3-system-controller +.It +allwinner,sun8i-h3-system-control +.It +allwinner,sun50i-h5-system-control +.It +allwinner,sun20i-d1-system-control +.El +.Sh AUTHORS +The +.Nm +device driver was written by +.An Kyle Evans Aq Mt kevans@FreeBSD.org . diff --git a/static/freebsd/man4/axe.4 b/static/freebsd/man4/axe.4 new file mode 100644 index 00000000..023175fe --- /dev/null +++ b/static/freebsd/man4/axe.4 @@ -0,0 +1,257 @@ +.\" Copyright (c) 1997, 1998, 1999, 2000-2003 +.\" Bill Paul . 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 Bill Paul. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Bill Paul 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 Bill Paul OR THE VOICES IN HIS HEAD +.\" 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 November 24, 2015 +.Dt AXE 4 +.Os +.Sh NAME +.Nm axe +.Nd "ASIX Electronics AX88x7x/760 USB Ethernet driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ehci" +.Cd "device uhci" +.Cd "device ohci" +.Cd "device usb" +.Cd "device miibus" +.Cd "device uether" +.Cd "device axe" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_axe_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for USB Ethernet adapters based on the ASIX +Electronics AX88172, AX88178, AX88772, AX88772A, AX88772B and AX88760 +USB 2.0 chipsets. +.Pp +The AX88172, AX88772, AX88772A, AX88772B and AX88760 contain a 10/100 +Ethernet MAC with MII interface and are designed to work with both +Ethernet and HomePNA transceivers. +The AX88178 has a 10/100/1000 Ethernet MAC with GMII/RGMII interface +for interfacing with Gigabit Ethernet PHY. +.Pp +These devices will operate with +both USB 1.x and USB 2.0 controllers, however performance with 1.x +controllers will be limited since the USB 1.x standard specifies a +maximum transfer speed of 12Mbps. +Users with USB 1.x controllers should therefore not expect to actually +achieve 100Mbps speeds with these devices. +.Pp +All chipsets support a 64-bit multicast hash table, single perfect +filter entry for the station address, all-multicast mode and promiscuous mode. +Packets are +received and transmitted over separate USB bulk transfer endpoints. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width ".Cm 10baseT/UTP" +.It Cm autoselect +Enable autoselection of the media type and options. +The user can manually override +the autoselected mode by adding media options to +.Xr rc.conf 5 . +.It Cm 10baseT/UTP +Set 10Mbps operation. +The +.Xr ifconfig 8 +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 100baseTX +Set 100Mbps (Fast Ethernet) operation. +The +.Xr ifconfig 8 +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 1000baseT +Set 1000Mbps (Gigabit Ethernet) operation (AX88178 only). +The +.Xr ifconfig 8 +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width ".Cm full-duplex" +.It Cm full-duplex +Force full duplex operation. +.It Cm half-duplex +Force half duplex operation. +.El +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports ASIX Electronics AX88172/AX88178/AX88772/AX88772A/AX88772B/AX88760 +based USB Ethernet adapters including: +.Pp +AX88172: +.Bl -bullet -compact +.It +AboCom UF200 +.It +Acer Communications EP1427X2 +.It +ASIX AX88172 +.It +ATen UC210T +.It +Billionton SnapPort +.It +Billionton USB2AR +.It +Buffalo (Melco Inc.) LUA-U2-KTX +.It +Corega USB2_TX +.It +D-Link DUBE100 +.It +Goodway GWUSB2E +.It +JVC MP_PRX1 +.It +LinkSys USB200M +.It +Netgear FA120 +.It +Sitecom LN-029 +.It +System TALKS Inc.\& SGC-X2UL +.El +.Pp +AX88178: +.Bl -bullet -compact +.It +ASIX AX88178 +.It +Belkin F5D5055 +.It +Logitec LAN-GTJ/U2A +.It +Buffalo (Melco Inc.) LUA3-U2-AGT +.It +Planex Communications GU1000T +.It +Sitecom Europe LN-028 +.El +.Pp +AX88772: +.Bl -bullet -compact +.It +ASIX AX88772 +.It +Buffalo (Melco Inc.) LUA3-U2-ATX +.It +D-Link DUBE100B1 +.It +Planex UE-200TX-G +.It +Planex UE-200TX-G2 +.El +.Pp +AX88772A: +.Bl -bullet -compact +.It +ASIX AX88772A +.It +Cisco-Linksys USB200Mv2 +.El +.Pp +AX88772B: +.Bl -bullet -compact +.It +ASIX AX88772B +.It +Lenovo USB 2.0 Ethernet +.El +.Pp +AX88760: +.Bl -bullet -compact +.It +ASIX AX88760 +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "axe%d: watchdog timeout" +A packet was queued for transmission and a transmit command was +issued, however the device failed to acknowledge the transmission +before a timeout expired. +.It "axe%d: no memory for rx list" +The driver failed to allocate an mbuf for the receiver ring. +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr rgephy 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Rs +.%T "ASIX AX88x7x and AX88760 data sheets" +.%U http://www.asix.com.tw +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 5.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Bill Paul Aq Mt wpaul@windriver.com . diff --git a/static/freebsd/man4/axge.4 b/static/freebsd/man4/axge.4 new file mode 100644 index 00000000..7133ee32 --- /dev/null +++ b/static/freebsd/man4/axge.4 @@ -0,0 +1,166 @@ +.\" +.\" SPDX-License-Identifier: BSD-4-Clause +.\" +.\" Copyright (c) 1997, 1998, 1999, 2000-2003 +.\" Bill Paul . 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 Bill Paul. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Bill Paul 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 Bill Paul OR THE VOICES IN HIS HEAD +.\" 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 May 25, 2025 +.Dt AXGE 4 +.Os +.Sh NAME +.Nm axge +.Nd "ASIX Electronics AX88178A/179/179A USB Gigabit Ethernet driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device xhci" +.Cd "device ehci" +.Cd "device uhci" +.Cd "device ohci" +.Cd "device usb" +.Cd "device miibus" +.Cd "device uether" +.Cd "device axge" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_axge_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for USB Gigabit Ethernet adapters based on the ASIX +Electronics AX88179/AX88179A USB 3.0 and AX88178A USB 2.0 chipsets. +.Pp +The AX88179, AX88179A and AX88178A contain a 10/100/1000 Ethernet MAC with a +GMII interface for interfacing with the Gigabit Ethernet PHY. +.Pp +These devices will operate with both USB 1.x and USB 2.0 controllers, and the +AX88179/AX88179A will operate with USB 3.0 controllers. +Packets are received and transmitted over separate USB bulk transfer endpoints. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width ".Cm 10baseT/UTP" +.It Cm autoselect +Enable autoselection of the media type and options. +The user can manually override +the autoselected mode by adding media options to +.Xr rc.conf 5 . +.It Cm 10baseT/UTP +Set 10Mbps operation. +The +.Xr ifconfig 8 +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 100baseTX +Set 100Mbps (Fast Ethernet) operation. +The +.Xr ifconfig 8 +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 1000baseT +Set 1000Mbps (Gigabit Ethernet) operation (AX88178 only). +The +.Xr ifconfig 8 +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width ".Cm full-duplex" +.It Cm full-duplex +Force full duplex operation. +.It Cm half-duplex +Force half duplex operation. +.El +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports the following USB Gigabit Ethernet controllers: +.Pp +.Bl -bullet -compact +.It +ASIX Electronics AX88179A +.It +ASIX Electronics AX88179 +.It +ASIX Electronics AX88178A +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr rgephy 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 10.1 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Kevin Lo Aq Mt kevlo@FreeBSD.org +and +.An Li-Wen Hsu Aq Mt lwhsu@FreeBSD.org . +This manual page was adapted by +.An Mark Johnston Aq Mt markj@FreeBSD.org +from the +.Xr axe 4 +manual page. diff --git a/static/freebsd/man4/axp.4 b/static/freebsd/man4/axp.4 new file mode 100644 index 00000000..41c2737b --- /dev/null +++ b/static/freebsd/man4/axp.4 @@ -0,0 +1,196 @@ +.\" Copyright (c) 2020, Advanced Micro Devices Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright notice, +.\" this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of Advanced Micro Devices Inc., nor the names of its +.\" contributors may be used to endorse or promote products derived from +.\" this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 COPYRIGHT OWNER 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. +.\" +.\" * Other names and brands may be claimed as the property of others. +.\" +.Dd February 19, 2021 +.Dt AXP 4 +.Os +.Sh NAME +.Nm axp +.Nd "Advanced Micro Devices 10G Ethernet driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device iflib" +.Cd "device axp" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_axp_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver enables PCI-E based 10G Ethernet controller inbuilt in the +AMD EPYC processors. +.Pp +The following features are supported. +.Pp +.Bl -bullet -compact +.It +1G/10G SFP+ Link +.It +Jumbo frames (9000 Bytes) +.It +Transmit and Receive checksum offload +.It +TCP segmentation offload (TSO) +.It +VLAN tag insertion/extraction +.It +VLAN checksum offload +.It +VLAN TSO +.It +Receive side steering (RSS) +.It +IPV4 and IPV6 capable +.It +MSI-X interrupts +.It +Split header +.El +.Pp +All the above mentioned features are enabled by default. +.Pp +For hardware related questions, please refer the documentation supplied +along with AMD EPYC processors. +.Sh SYSCTL VARIABLES +The following variables are available as +.Xr sysctl 8 +variables: +.Bl -tag -width indent +.It Va dev.ax.X.mac_stats +Dumps the transmit and receive statistics counter values for the controller. +This includes statistics specific to each transmit and receive queue. +.It Va dev.ax.X.channels_info +Dumps the permissible and default configured transmit and receive channel +information. +.It Va dev.ax.X.ringparam_info +Dumps the permissible and default configured descriptor information for the +transmit and receive queue. +.It Va dev.ax.X.link_ksettings_info +Dumps the current link setting like link mode, speed, duplex settings. +.It Va dev.ax.X.pauseparam_info +Dumps the current flow-control settings. +.It Va dev.ax.X.coalesce_info +Dumps the current interrupt coalescing settings. +.It Va dev.ax.X.link_info +Dumps the current state of the Link. +.It Va dev.ax.X.drv_info +Dumps the driver and controller firmware version information. +.It Va dev.ax.X.YYYY_register +.It Va dev.ax.X.YYYY_register_values +Sysctl to dump a specific register from a specific block of the controller. +YYYY specifies the block. +The following blocks are supported. +.Bl -bullet -compact +.It +xpcs +.It +xgmac +.It +xprop +.It +xi2c +.El +.Pp +Set the offset of the register to the first variable, and then read the value +of the register by reading the second variable. +.It Va dev.ax.X.axgbe_debug_level +Configure the log-level for the driver. +Default is 0. +Supports 0-3. +.It Va dev.ax.X.link_workaround +This variable enables the workaround for an intermittent link issue. +When link does not come up for long time, this variable can be set to 1 to +reset the phy and bring up the link. +.El +.Sh LOADER TUNABLES +The following variable is available as +.Xr loader.conf 5 +tunable. +.Bl -tag -width indent +.It Va dev.ax.X.sph_enable +This variable controls split header feature for the interface. +Default is 1, meaning the split header support is enabled. +.Pp +This variable must be set before loading the driver, either via +.Xr loader.conf 5 +or through +.Xr kenv 1 . +This cannot be modified when driver is loaded. +.Pp +Setting this variable in +.Xr loader.conf 5 +needs the system to be restarted to take effect. +When using +.Xr kenv 1 , +use the wrapper variable +.Va dev.ax.sph_enable , +which will configure(enable/disable) split header support for all +.Nm +interfaces. +.Pp +To use netmap with this device, split header support must be disabled +(set this variable to 0). +.El +.Sh SEE ALSO +.Xr arp 4 , +.Xr iflib 4 , +.Xr netmap 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 13.0 . +.Pp +Another version of the driver is already present in +.Fx . +This driver was named as "axgbe" earlier, which is renamed as "axa" now. +This driver is for the ACPI based Ethernet controllers in the previous/older +version of the hardware. +This driver is authored by +.Aq Mt andrew@FreeBSD.org . +.Sh AUTHORS +The +.Nm +device driver was written by +.An Advanced Micro Devices Inc . +.Pp +For any issues and support requirements, email the details to +.Aq Mt rajesh1.kumar@amd.com . diff --git a/static/freebsd/man4/bce.4 b/static/freebsd/man4/bce.4 new file mode 100644 index 00000000..aab9eaeb --- /dev/null +++ b/static/freebsd/man4/bce.4 @@ -0,0 +1,430 @@ +.\" Copyright (c) 2006-2014 QLogic Corporation +.\" +.\" 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 COPYRIGHT HOLDERS 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 COPYRIGHT OWNER 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 June 4, 2012 +.Dt BCE 4 +.Os +.Sh NAME +.Nm bce +.Nd "QLogic NetXtreme II (BCM5706/5708/5709/5716) PCI/PCIe Gigabit Ethernet adapter driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device bce" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_bce_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports QLogic's NetXtreme II product family, including the +BCM5706, BCM5708, BCM5709 and BCM5716 Ethernet controllers. +.Pp +The NetXtreme II product family is composed of various Converged NIC (or CNIC) +Ethernet controllers which support a TCP Offload Engine (TOE), Remote DMA (RDMA), +and iSCSI acceleration, in addition to standard L2 Ethernet traffic, all on the +same controller. +.Pp +The following features are supported in the +.Nm +driver under +.Fx : +.Pp +.Bl -item -offset indent -compact +.It +IP/TCP/UDP checksum offload +.It +Jumbo frames (up to 9022 bytes) +.It +VLAN tag stripping +.It +Interrupt coalescing +.It +10/100/1000Mbps operation in full-duplex mode +.It +10/100Mbps operation in half-duplex mode +.El +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width ".Cm 10baseT/UTP" +.It Cm autoselect +Enable autoselection of the media type and options. +The user can manually override +the autoselected mode by adding media options to +.Xr rc.conf 5 . +.It Cm 10baseT/UTP +Set 10Mbps operation. +The +.Xr ifconfig 8 +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 100baseTX +Set 100Mbps (Fast Ethernet) operation. +The +.Xr ifconfig 8 +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 1000baseSX +Sets 1000Mbps operation. +Only +.Cm full-duplex +mode is supported at this speed. +.It Cm 1000baseT +Set 1000baseT operation over twisted pair. +Only +.Cm full-duplex +mode is supported. +.It Cm 2500BaseSX +Set 2500Mbps operation. +Only +.Cm full-duplex +mode is supported. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width ".Cm full-duplex" +.It Cm full-duplex +Force full duplex operation. +.It Cm half-duplex +Force half duplex operation. +.El +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver provides support for various NICs based on the QLogic NetXtreme II +family of Gigabit Ethernet controllers, including the +following: +.Pp +.Bl -bullet -compact +.It +QLogic NetXtreme II BCM5706 1000Base-SX +.It +QLogic NetXtreme II BCM5706 1000Base-T +.It +QLogic NetXtreme II BCM5708 1000Base-SX +.It +QLogic NetXtreme II BCM5708 1000Base-T +.It +QLogic NetXtreme II BCM5709 1000Base-SX +.It +QLogic NetXtreme II BCM5709 1000Base-T +.It +QLogic NetXtreme II BCM5716 1000Base-T +.It +Dell PowerEdge 1950 integrated BCM5708 NIC +.It +Dell PowerEdge 2950 integrated BCM5708 NIC +.It +Dell PowerEdge R710 integrated BCM5709 NIC +.It +HP NC370F Multifunction Gigabit Server Adapter +.It +HP NC370T Multifunction Gigabit Server Adapter +.It +HP NC370i Multifunction Gigabit Server Adapter +.It +HP NC371i Multifunction Gigabit Server Adapter +.It +HP NC373F PCIe Multifunc Giga Server Adapter +.It +HP NC373T PCIe Multifunction Gig Server Adapter +.It +HP NC373i Multifunction Gigabit Server Adapter +.It +HP NC373m Multifunction Gigabit Server Adapter +.It +HP NC374m PCIe Multifunction Adapter +.It +HP NC380T PCIe DP Multifunc Gig Server Adapter +.It +HP NC382T PCIe DP Multifunction Gigabit Server Adapter +.It +HP NC382i DP Multifunction Gigabit Server Adapter +.It +HP NC382m DP 1GbE Multifunction BL-c Adapter +.El +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va hw.bce.verbose +Enable/Disable verbose logging and output to the console. +Useful for debugging (default 0). +.It Va hw.bce.msi_enable +Enable/Disable MSI support (default 1). +.It Va hw.bce.tso_enable +Enable/Disable TSO support (default 1). +.It Va hw.bce.strict_rx_mtu +Enable/Disable strict RX frame size checking (default 0). +.It Va hw.bce.hdr_split +Enable/Disable frame header/payload splitting (default 1). +.It Va hw.bce.rx_pages +Set the number of memory pages assigned to receive packets by the driver. +Due to alignment issues, this value can only be of the set +1, 2, 4 or 8 (default 2). +.It Va hw.bce.tx_pages +Set the number of memory pages assigned to transmit packets +by the driver. +Due to alignment issues, this value can only be of the set +1, 2, 4 or 8 (default 2). +.It Va hw.bce.rx_ticks +Time in microsecond ticks to wait before generating a status +block updates due to RX processing activity. +Values from 0-100 are valid. +A value of 0 disables this status block update. +Cannot be set to 0 if hw.bce.rx_quick_cons_trip is also 0 +(default 18). +.It Va hw.bce.rx_ticks_int +Time in microsecond ticks to wait during RX interrupt +processing before generating a status block update. +Values from 0-100 are valid. +Valid values are in the range from 0-100. +A value of 0 disables this status block update (default 18). +.It Va hw.bce.rx_quick_cons_trip +Number of RX Quick BD Chain entries that must be completed +before a status block is generated. +Values from 0-256 are valid. +A value of 0 disables this status block update. +Cannot be set to 0 if hw.bce.rx_ticks is also 0 (default 6). +.It Va hw.bce.rx_quick_cons_trip_int +Number of RX quick BD entries that must be completed before +a status block is generated duing interrupt processing. +Values from 0-256 are valid. +A value of 0 disables this status block update (default 6). +.It Va hw.bce.tx_ticks +Time in microsecond ticks to wait before a status block +update is generated due to TX activity. +Values from 0-100 are valid. +A value of 0 disables this status block update. +Cannot be set to 0 if hw.bce.tx_quick_cons_trip is also 0 +(default 80). +.It Va hw.bce.tx_ticks_int +Time in microsecond ticks to wait in interrupt processing +before a status block update is generated due to TX activity +Values from 0-100 are valid. +A value of 0 disables this status block update (default 80). +.It Va hw.bce.tx_cons_trip +How many TX Quick BD Chain entries that must be completed +before a status block is generated. +Values from 0-100 are valid. +A value of 0 disables this status block update. +Cannot be set to 0 if hw.bce.tx_ticks is also 0 (default 20). +.It Va hw.bce.tx_cons_trip_int +How many TX Quick BD Chain entries that must be completed +before a status block is generated during an interrupt. +Values from 0-100 are valid. +A value of 0 disables this status block update (default 20). +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "bce%d: PCI memory allocation failed!" +The driver has encountered a fatal initialization error. +.It "bce%d: PCI map interrupt failed!" +The driver has encountered a fatal initialization error. +.It "bce%d: Unsupported controller revision (%c%d)" +The driver does not support the controller revision in use. +.It "bce%d: Controller initialization failed!" +The driver has encountered a fatal initialization error. +.It "bce%d: NVRAM test failed!" +The driver could not access the controller NVRAM correctly. +.It "bce%d: DMA resource allocation failed!" +The driver could not allocate DMA memory to setup the controllers +host memory data structures. +.It "bce%d: Interface allocation failed!" +The driver could not create a network interface for the controller. +.It "bce%d: PHY probe failed!" +The driver could not access the PHY used by the controller. +.It "bce%d: Failed to setup IRQ!" +The driver could not initialize the IRQ handler. +.It "bce%d: Error: PHY read timeout!" +The driver could not read a PHY register before the timeout period expired. +.It "bce%d: PHY write timeout!" +The driver could not write to the PHY register because a timeout occurred. +.It "bce%d: Timeout error reading NVRAM at offset 0x%08X!" +The driver could not write to NVRAM because a timeout occurred. +.It "bce%d: Unknown Flash NVRAM found!" +The driver does not recognize the NVRAM device being used and therefore +cannot access it correctly. +.It "bce%d: Invalid NVRAM magic value!" +The driver cannot read NVRAM or the NVRAM is corrupt. +.It "bce%d: Invalid Manufacturing Information NVRAM CRC!" +The driver cannot read NVRAM or the NVRAM is corrupt. +.It "bce%d: Invalid Feature Configuration Information NVRAM CRC!" +The driver cannot read NVRAM or the NVRAM is corrupt. +.It "bce%d: DMA mapping error!" +The driver was unable to map memory into DMA addressable space required +by the controller. +.It "bce%d: Could not allocate parent DMA tag!" +The driver could not allocate a PCI compatible DMA tag. +.It "bce%d: Could not allocate status block DMA tag!" +The driver could not allocate a DMA tag for the controller's +status block. +.It "bce%d: Could not allocate status block DMA memory!" +The driver could not allocate DMA addressable memory for the controller's +status block. +.It "bce%d: Could not map status block DMA memory!" +The driver could not map the status block memory into the controller's DMA +address space. +.It "bce%d: Could not allocate statistics block DMA tag!" +The driver could not allocate a DMA tag for the controller's +statistics block. +.It "bce%d: Could not allocate statistics block DMA memory!" +The driver could not allocate DMA addressable memory for the controller's +statistics block. +.It "bce%d: Could not map statistics block DMA memory!" +The driver could not map the statistics block memory into the controller's DMA +address space. +.It "bce%d: Could not allocate TX descriptor chain DMA tag!" +The driver could not allocate a DMA tag for the controller's +TX chain. +.It "bce%d: Could not allocate TX descriptor chain DMA memory!" +The driver could not allocate DMA addressable memory for the controller's +TX chain. +.It "bce%d: Could not map TX descriptor chain DMA memory!" +The driver could not map the TX descriptor chain memory into the controller's DMA +address space. +.It "bce%d: Could not allocate TX mbuf DMA tag!" +The driver could not allocate a DMA tag for the controller's +TX mbuf memory. +.It "bce%d: Unable to create TX mbuf DMA map!" +The driver could not map the TX mbuf memory into the controller's DMA +address space. +.It "bce%d: Could not allocate RX descriptor chain DMA tag!" +The driver could not allocate a DMA tag for the controller's +RX chain. +.It "bce%d: Could not allocate RX descriptor chain " +The driver could not allocate DMA addressable memory for the controller's +RX chain. +.It "bce%d: Could not map RX descriptor chain DMA memory!" +The driver could not map the RX descriptor chain memory into the controller's DMA +address space. +.It "bce%d: Could not allocate RX mbuf DMA tag!" +The driver could not allocate a DMA tag for the controller's +RX mbuf memory. +.It "bce%d: Unable to create RX mbuf DMA map!" +The driver could not map the RX mbuf memory into the controller's DMA +address space. +.It "bce%d: Firmware synchronization timeout!" +The driver was not able to synchronize with the firmware running on the +controller. +The firmware may be stopped or hung. +.It "bce%d: Invalid Ethernet address!" +The driver was not able to read a valid Ethernet MAC address from NVRAM. +.It "bce%d: Reset failed!" +The driver has encountered a fatal initialization error. +.It "bce%d: Byte swap is incorrect!" +The driver has encountered a fatal initialization error. +Contact the author +with details of the CPU architecture and system chipset in use. +.It "bce%d: Firmware did not complete initialization!" +The driver has encountered a fatal initialization error. +.It "bce%d: Bootcode not running!" +The driver has encountered a fatal initialization error. +.It "bce%d: Error mapping mbuf into RX chain!" +The driver could not map a RX mbuf into DMA addressable memory. +.It "bce%d: Error filling RX chain: rx_bd[0x%04X]!" +The driver was unable to allocate enough mbufs to fill the RX chain +during initialization. +Try increasing the number of mbufs available in +the system, increase system memory, or if using jumbo frames, make sure +enough 9KB mbufs are available. +.It "bce%d: Failed to allocate new mbuf, incoming frame dropped!" +The driver was unable to allocate a new mbuf for the RX chain and reused +the mbuf for the received frame, dropping the incoming frame in the process. +Try increasing the number of mbufs available in the system or increase system +memory. +.It "bce%d: Controller reset failed!" +A fatal initialization error has occurred. +.It "bce%d: Controller initialization failed!" +A fatal initialization error has occurred. +.It "bce%d: Block initialization failed!" +A fatal initialization error has occurred. +.It "bce%d: Error mapping mbuf into TX chain!" +The driver could not map a TX mbuf into DMA addressable memory. +.It "bce%d: Error registering poll function!" +The driver received an error while attempting to register the poll function. +.It "bce%d: Changing VLAN_MTU not supported." +Changing the VLAN MTU is not currently supported by the driver. +.It "bce%d: Cannot change VLAN_HWTAGGING while management firmware (ASF/IPMI/UMP) is running!" +Management firmware to support ASF/IPMI/UMP requires that VLAN +tag stripping be enabled in the controller. +.It "bce%d: Changing VLAN_HWTAGGING not supported!" +Disabling VLAN tag stripping is not currently supported by the driver. +.It "bce%d: Watchdog timeout occurred, resetting!" +The device has stopped responding to the network, there is a problem +with the cable connection, or a driver logic problem has occurred.. +.It "bce%d: Fatal attention detected: 0x%08X!" +A controller hardware failure has occurred. +If the problem continues replace the controller. +.El +.Sh SUPPORT +For support questions please contact your QLogic approved reseller or +QLogic Technical Support at +.Pa http://support.qlogic.com , +or by E-mail at +.Aq Mt support@qlogic.com . +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 6.1 . +.Sh AUTHORS +The +.Nm +driver was written by +.An David Christensen Aq Mt davidch@broadcom.com . diff --git a/static/freebsd/man4/bcm5974.4 b/static/freebsd/man4/bcm5974.4 new file mode 100644 index 00000000..378a2c93 --- /dev/null +++ b/static/freebsd/man4/bcm5974.4 @@ -0,0 +1,83 @@ +.\" Copyright (c) 2022 Vladimir Kondratyev +.\" 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 February 27, 2022 +.Dt BCM5974 4 +.Os +.Sh NAME +.Nm bcm5974 +.Nd Wellspring touchpad driver +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines into +your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device bcm5974" +.Cd "device hidbus" +.Cd "device hid" +.Cd "device usbhid" +.Cd "device usb" +.Cd "device evdev" + +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +bcm5974_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the Wellspring touchpads found in many Apple +laptops. +.Pp +To get multi-touch device working in +.Xr X 7 Pq Pa ports/x11/xorg-docs , +install +.Pa ports/x11-drivers/xf86-input-libinput . +.Sh FILES +.Nm +creates a pseudo-device file, +.Pa /dev/input/eventX +which presents the multi-touch device as an input event device. +.Sh SEE ALSO +.Xr hid 4 , +.Xr loader.conf 5 , +.Xr xorg.conf 5 Pq Pa ports/x11/xorg , +.Xr libinput 4 Pq Pa ports/x11-drivers/xf86-input-libinput . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org . +It is based on +.Xr wsp 4 +driver written by +.An Huang Wen Hui Aq Mt huanghwh@gmail.com . +.Sh BUGS +.Nm +cannot act like +.Xr sysmouse 4 diff --git a/static/freebsd/man4/bcma.4 b/static/freebsd/man4/bcma.4 new file mode 100644 index 00000000..de1a25bf --- /dev/null +++ b/static/freebsd/man4/bcma.4 @@ -0,0 +1,77 @@ +.\" Copyright (c) 2015 Landon Fuller +.\" Copyright (c) 2010 Weongyo Jeong +.\" 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 June 3, 2016 +.Dt BCMA 4 +.Os +.Sh NAME +.Nm bcma +.Nd Broadcom AMBA Backplane driver +.Sh SYNOPSIS +To compile this driver into the kernel, add the following lines to the +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device bhnd" +.Cd "device bcma" +.Ed +.Pp +To load the driver as a module at boot, add this line to +.Xr loader.conf 5 : +.Bd -literal -offset indent +bcma_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides +.Xr bhnd 4 +support for devices using the ARM AMBA-based backplane architecture found +in later Broadcom Home Networking Division's network chipsets and embedded +systems. +.Pp +A common interconnect connects all of the backplane's functional +blocks. +These functional blocks, known as cores, use the ARM AMBA AXI or +APB interface to communicate with devices attached to the interconnect. +.Pp +The IP cores used in +.Xr siba 4 +devices were adapted by Broadcom for compatibility with the new +interconnect. +.Sh SEE ALSO +.Xr bhnd 4 , +.Xr intro 4 , +.Xr siba 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 11.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Landon Fuller Aq Mt landonf@FreeBSD.org . diff --git a/static/freebsd/man4/bfe.4 b/static/freebsd/man4/bfe.4 new file mode 100644 index 00000000..c961683a --- /dev/null +++ b/static/freebsd/man4/bfe.4 @@ -0,0 +1,114 @@ +.\" +.\" Copyright (c) 2003 Stuart Walsh +.\" +.\" 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 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 July 16, 2005 +.Dt BFE 4 +.Os +.Sh NAME +.Nm bfe +.Nd "Broadcom BCM4401 Ethernet Device Driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device bfe" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_bfe_load="YES" +.Ed +.Sh DEPRECATION NOTICE +The +.Nm +driver is unmaintained and may be removed from +.Fx +in a future release. +.Fx . +.Sh DESCRIPTION +The +.Nm +driver provides support for Broadcom BCM4401 based Fast Ethernet adapters. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width ".Cm 10baseT/UTP" +.It Cm autoselect +Enable autoselection of the media type and options. +.It Cm 10baseT/UTP +Set 10Mbps operation. +.It Cm 100baseTX +Set 100Mbps (Fast Ethernet) operation. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width ".Cm full-duplex" +.It Cm full-duplex +Set full duplex operation. +.El +.Pp +For further information on configuring this device, see +.Xr ifconfig 8 . +.Sh DIAGNOSTICS +.Bl -diag +.It "bfe%d: couldn't map memory" +A fatal initialization error has occurred. +.It "bfe%d: couldn't map interrupt" +A fatal initialization error has occurred. +.It "bfe%d: failed to allocate DMA resources" +There are not enough mbufs available for allocation. +.It "bfe%d: watchdog timeout -- resetting" +The device has stopped responding to the network, or there is a problem with +the network connection (cable). +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 5.1 . +.Sh AUTHORS +.An -nosplit +The +.Nm +device driver was written by +.An Stuart Walsh +and +.An Duncan Barclay . +This manual page was written by +.An Stuart Walsh . diff --git a/static/freebsd/man4/bge.4 b/static/freebsd/man4/bge.4 new file mode 100644 index 00000000..fdf46fec --- /dev/null +++ b/static/freebsd/man4/bge.4 @@ -0,0 +1,286 @@ +.\" Copyright (c) 2001 Wind River Systems +.\" Copyright (c) 1997, 1998, 1999, 2000, 2001 +.\" Bill Paul . 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 Bill Paul. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Bill Paul 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 Bill Paul OR THE VOICES IN HIS HEAD +.\" 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 16, 2026 +.Dt BGE 4 +.Os +.Sh NAME +.Nm bge +.Nd "Broadcom BCM57xx/BCM590x Gigabit/Fast Ethernet driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device bge" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_bge_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for various NICs based on the Broadcom BCM570x, +571x, 572x, 575x, 576x, 578x, 5776x and 5778x Gigabit Ethernet controller +chips and the 590x and 5779x Fast Ethernet controller chips. +.Pp +All of these NICs are capable of 10, 100 and 1000Mbps speeds over CAT5 +copper cable, except for the SysKonnect SK-9D41 which supports only +1000Mbps over multimode fiber. +The BCM570x builds upon the technology of the Alteon Tigon II. +It has two R4000 CPU cores and is PCI v2.2 and PCI-X v1.0 compliant. +It supports IP, TCP +and UDP checksum offload for both receive and transmit, +multiple RX and TX DMA rings for QoS applications, rules-based +receive filtering, and VLAN tag stripping/insertion as well as +a 256-bit multicast hash filter. +Additional features may be +provided via value-add firmware updates. +The BCM570x supports TBI (ten bit interface) and GMII +transceivers, which means it can be used with either copper or 1000baseX +fiber applications. +Note however the device only supports a single +speed in TBI mode. +.Pp +Most BCM5700-based cards also use the Broadcom BCM5401 or BCM5411 10/100/1000 +copper gigabit transceivers, +which support autonegotiation of 10, 100 and 1000Mbps modes in +full or half duplex. +.Pp +The BCM5700, BCM5701, BCM5702, BCM5703, BCM5704, BCM5714, BCM5717, BCM5719, +BCM5720, BCM5780 and BCM57765 also support jumbo frames, which can be +configured via the interface MTU setting. +Selecting an MTU larger than 1500 bytes with the +.Xr ifconfig 8 +utility configures the adapter to receive and transmit jumbo frames. +Using jumbo frames can greatly improve performance for certain tasks, +such as file transfers and data streaming. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width ".Cm 10baseT/UTP" +.It Cm autoselect +Enable autoselection of the media type and options. +The user can manually override +the autoselected mode by adding media options to +.Xr rc.conf 5 . +.It Cm 10baseT/UTP +Set 10Mbps operation. +The +.Xr ifconfig 8 +.Ic mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 100baseTX +Set 100Mbps (Fast Ethernet) operation. +The +.Xr ifconfig 8 +.Ic mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 1000baseTX +Set 1000baseTX operation over twisted pair. +Only +.Cm full-duplex +mode is supported. +.It Cm 1000baseSX +Set 1000Mbps (Gigabit Ethernet) operation. +Both +.Cm full-duplex +and +.Cm half-duplex +modes are supported. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width ".Cm full-duplex" +.It Cm full-duplex +Force full duplex operation. +.It Cm half-duplex +Force half duplex operation. +.El +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver provides support for various NICs based on the Broadcom BCM570x +family of Gigabit Ethernet controller chips, including the +following: +.Pp +.Bl -bullet -compact +.It +3Com 3c996-SX (1000baseSX) +.It +3Com 3c996-T (10/100/1000baseTX) +.It +Apple Thunderbolt Display (10/100/1000baseTX) +.It +Apple Thunderbolt to Gigabit Ethernet Adapter (10/100/1000baseTX) +.It +Dell PowerEdge 1750 integrated BCM5704C NIC (10/100/1000baseTX) +.It +Dell PowerEdge 2550 integrated BCM5700 NIC (10/100/1000baseTX) +.It +Dell PowerEdge 2650 integrated BCM5703 NIC (10/100/1000baseTX) +.It +Dell PowerEdge R200 integrated BCM5750 NIC (10/100/1000baseTX) +.It +Dell PowerEdge R300 integrated BCM5722 NIC (10/100/1000baseTX) +.It +IBM x235 server integrated BCM5703x NIC (10/100/1000baseTX) +.It +HP Compaq dc7600 integrated BCM5752 NIC (10/100/1000baseTX) +.It +HP ProLiant NC7760 embedded Gigabit NIC (10/100/1000baseTX) +.It +HP ProLiant NC7770 PCI-X Gigabit NIC (10/100/1000baseTX) +.It +HP ProLiant NC7771 PCI-X Gigabit NIC (10/100/1000baseTX) +.It +HP ProLiant NC7781 embedded PCI-X Gigabit NIC (10/100/1000baseTX) +.It +Netgear GA302T (10/100/1000baseTX) +.It +SysKonnect SK-9D21 (10/100/1000baseTX) +.It +SysKonnect SK-9D41 (1000baseSX) +.El +.Sh LOADER TUNABLES +The following tunables can be set at the +.Xr loader 8 +prompt before booting the kernel, or stored in +.Xr loader.conf 5 . +.Bl -tag -width indent +.It Va hw.bge.allow_asf +Allow the ASF feature for cooperating with IPMI. +Can cause system lockup problems on a small number of systems. +Enabled by default. +.It Va dev.bge.%d.msi +Non-zero value enables MSI support on the Ethernet hardware. +The default value is 1. +.El +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va dev.bge.%d.forced_collapse +Allow collapsing multiple transmit buffers into a single buffer +to increase transmit performance with the cost of CPU cycles. +The default value is 0 to disable transmit buffer collapsing. +.It Va dev.bge.%d.forced_udpcsum +Enable UDP transmit checksum offloading even if controller can generate +UDP datagrams with checksum value 0. +UDP datagrams with checksum value 0 can confuse receiver host as it means +sender did not compute UDP checksum. +The default value is 0 which disables UDP transmit checksum offloading. +The interface need to be brought down and up again before a change takes +effect. +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "bge%d: couldn't map memory" +A fatal initialization error has occurred. +.It "bge%d: couldn't map ports" +A fatal initialization error has occurred. +.It "bge%d: couldn't map interrupt" +A fatal initialization error has occurred. +.It "bge%d: no memory for softc struct!" +The driver failed to allocate memory for per-device instance information +during initialization. +.It "bge%d: failed to enable memory mapping!" +The driver failed to initialize PCI shared memory mapping. +This might +happen if the card is not in a bus-master slot. +.It "bge%d: firmware handshake timed out, found 0xffffffff" +The device was physically disconnected from the system, or there is a problem with +the device causing it to stop responding to the host it is attached to. +.It "bge%d: no memory for jumbo buffers!" +The driver failed to allocate memory for jumbo frames during +initialization. +.It "bge%d: watchdog timeout" +The device has stopped responding to the network, or there is a problem with +the network connection (cable). +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr polling 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 4.5 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Bill Paul Aq Mt wpaul@windriver.com . +.Sh BUGS +Hotplug is not currently supported in +.Fx , +hence, Thunderbolt interfaces need to be connected prior to system power up on +Apple systems in order for the interface to be detected. +Also, due to the lack of hotplug support, Thunderbolt-based interfaces must not be removed +while the system is up as the kernel is currently unable to cope with a +.Nm +interface disappearing. +.Pp +The UDP transmit checksum offloading is disabled by default, see +.Va dev.bge.%d.forced_udpcsum . +To avoid problems when the interface is a member of a +.Xr bridge 4 +interface, all transmit checksum offloading is initially disabled in this case. +Transmit checksum offloading can be enabled using +.Xr ifconfig 8 . diff --git a/static/freebsd/man4/bhnd.4 b/static/freebsd/man4/bhnd.4 new file mode 100644 index 00000000..1bf10398 --- /dev/null +++ b/static/freebsd/man4/bhnd.4 @@ -0,0 +1,81 @@ +.\" Copyright (c) 2015 Landon Fuller +.\" 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 June 3, 2016 +.Dt BHND 4 +.Os +.Sh NAME +.Nm bhnd +.Nd Broadcom Home Networking Division interconnect bus +.Sh SYNOPSIS +To compile this driver into the kernel, add the following lines to the +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device bhnd" +.Ed +.Pp +To load the driver as a module at boot, add this line to +.Xr loader.conf 5 : +.Bd -literal -offset indent +bhnd_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides a unified kernel bus interface to the on-chip +interconnects used in Broadcom Home Networking Division (HND) +devices. +.Pp +The Broadcom HND device family consists of SoCs (System On a Chip) +and host-connected chipsets based on a common library of Broadcom IP +cores connected via an internal hardware bus architecture. +Drivers for these cores are implemented against the unified +.Nm +interface. +.Pp +The Sonic Inc. Silicon Backplane used in earlier HND devices is supported +by the +.Xr siba 4 +BHND driver. +.Pp +The ARM AMBA-based interconnect used in later HND devices is supported by +the +.Xr bcma 4 +BHND driver. +.Sh SEE ALSO +.Xr bcma 4 , +.Xr bhndb 4 , +.Xr intro 4 , +.Xr siba 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 11.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Landon Fuller Aq Mt landonf@FreeBSD.org . diff --git a/static/freebsd/man4/bhnd_chipc.4 b/static/freebsd/man4/bhnd_chipc.4 new file mode 100644 index 00000000..b4fbeea9 --- /dev/null +++ b/static/freebsd/man4/bhnd_chipc.4 @@ -0,0 +1,78 @@ +.\" Copyright (c) 2017 The FreeBSD Foundation +.\" +.\" This documentation was written by Landon Fuller under sponsorship from +.\" the FreeBSD Foundation. +.\" +.\" 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 October 16, 2017 +.Dt BHND_CHIPC 4 +.Os +.Sh NAME +.Nm bhnd_chipc +.Nd Broadcom Home Networking Division ChipCommon Driver +.Sh SYNOPSIS +To compile this driver into the kernel, add this line to the +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device bhnd" +.Ed +.Pp +To compile driver support for all additional devices found in embedded systems, +add the following additional lines to the kernel configuration file: +.Bd -ragged -offset indent +.Cd "device cfi" +.Cd "device gpio" +.Cd "device spibus" +.Cd "device uart" +.Ed +.Pp +To load the driver as a module at boot, add this line to +.Xr loader.conf 5 : +.Bd -literal -offset indent +bhnd_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports the ChipCommon core found in Broadcom Home Networking +Division network chipsets and embedded systems. +.Pp +The ChipCommon core provides an interface to common hardware facilities, +including device identification, UARTs, CFI and SPI flash, One-time Programmable +(OTP) Memory, and GPIO. +.Sh SEE ALSO +.Xr bhnd 4 , +.Xr intro 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 11.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Landon Fuller Aq Mt landonf@FreeBSD.org , +and +.An Michael Zhilin Aq Mt mizhka@FreeBSD.org . diff --git a/static/freebsd/man4/bhnd_pmu.4 b/static/freebsd/man4/bhnd_pmu.4 new file mode 100644 index 00000000..6ad913e4 --- /dev/null +++ b/static/freebsd/man4/bhnd_pmu.4 @@ -0,0 +1,71 @@ +.\" Copyright (c) 2017 The FreeBSD Foundation +.\" +.\" This documentation was written by Landon Fuller under sponsorship from +.\" the FreeBSD Foundation. +.\" +.\" 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 October 16, 2017 +.Dt BHND_PMU 4 +.Os +.Sh NAME +.Nm bhnd_pmu +.Nd Broadcom Home Networking Division PMU Driver +.Sh SYNOPSIS +To compile this driver into the kernel, add this line to the +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device bhnd" +.Ed +.Pp +To load the driver as a module at boot, add this line to +.Xr loader.conf 5 : +.Bd -literal -offset indent +bhnd_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports the Power Management Unit (PMU) found in Broadcom Home +Networking Division network chipsets and embedded systems. +.Pp +The PMU provides a hardware interface for managing the device's clock and power +topology. +.Sh SEE ALSO +.Xr bhnd 4 , +.Xr intro 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 12.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was derived from Broadcom's ISC-licensed Linux PMU drivers, and was +ported to +.Fx +and +.Xr bhnd 4 +by +.An Landon Fuller Aq Mt landonf@FreeBSD.org . diff --git a/static/freebsd/man4/bhndb.4 b/static/freebsd/man4/bhndb.4 new file mode 100644 index 00000000..683ae467 --- /dev/null +++ b/static/freebsd/man4/bhndb.4 @@ -0,0 +1,78 @@ +.\" Copyright (c) 2015 Landon Fuller +.\" Copyright (c) 2017 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" Portions of this documentation were written by Landon Fuller +.\" under sponsorship from the FreeBSD Foundation. +.\" +.\" 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 October 16, 2017 +.Dt BHNDB 4 +.Os +.Sh NAME +.Nm bhndb +.Nd Broadcom Home Networking Division interconnect bridge driver +.Sh SYNOPSIS +To compile this driver into the kernel, add the following lines to the +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device bhnd" +.Cd "device bhndb" +.Ed +.Pp +To load the driver as a module at boot, add this line to +.Xr loader.conf 5 : +.Bd -literal -offset indent +bhndb_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides +.Xr bhnd 4 +host bridge support for Broadcom Home Networking Division's wireless chipsets +and network adapters. +.Pp +To enable use for PCI/PCIe systems, see the +.Xr bhndb_pci 4 +driver. +.Sh SEE ALSO +.Xr bhnd 4 , +.Xr bhndb_pci 4 , +.Xr bwn 4 , +.Xr intro 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 11.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Landon Fuller Aq Mt landonf@FreeBSD.org . +.Sh CAVEATS +The +.Nm +driver does not currently support PCMCIA or SDIO devices. diff --git a/static/freebsd/man4/bhndb_pci.4 b/static/freebsd/man4/bhndb_pci.4 new file mode 100644 index 00000000..53b2d42f --- /dev/null +++ b/static/freebsd/man4/bhndb_pci.4 @@ -0,0 +1,73 @@ +.\" Copyright (c) 2015 Landon Fuller +.\" Copyright (c) 2017 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" Portions of this documentation were written by Landon Fuller +.\" under sponsorship from the FreeBSD Foundation. +.\" +.\" 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 October 16, 2017 +.Dt BHNDB_PCI 4 +.Os +.Sh NAME +.Nm bhndb_pci +.Nd Broadcom Home Networking Division PCI host bridge driver +.Sh SYNOPSIS +To compile this driver into the kernel, add the following lines to the +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device bhnd" +.Cd "device bhndb" +.Cd "device bhndb_pci" +.Cd "device pci" +.Ed +.Pp +To load the driver as a module at boot, add this line to +.Xr loader.conf 5 : +.Bd -literal -offset indent +bhndb_pci_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides +.Xr bhndb 4 +support for the PCI and PCIe host bridge cores found in Broadcom Home Networking +Division's wireless chipsets and network adapters. +.Sh SEE ALSO +.Xr bhnd 4 , +.Xr bhndb 4 , +.Xr bwn 4 , +.Xr intro 4 , +.Xr pci 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 11.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Landon Fuller Aq Mt landonf@FreeBSD.org . diff --git a/static/freebsd/man4/bhyve.4 b/static/freebsd/man4/bhyve.4 new file mode 100644 index 00000000..a87acaf2 --- /dev/null +++ b/static/freebsd/man4/bhyve.4 @@ -0,0 +1,66 @@ +.\" +.\" Copyright (c) 2012 NetApp Inc +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 5, 2013 +.Dt BHYVE 4 +.Os +.Sh NAME +.Nm bhyve +.Nd virtual machine monitor +.Sh SYNOPSIS +.Cd "/usr/sbin/bhyve" +.Cd "/usr/sbin/bhyveload" +.Cd "/usr/sbin/bhyvectl" +.Cd "/boot/kernel/vmm.ko" +.Sh DESCRIPTION +.Nm +is a virtual machine monitor that is hosted by FreeBSD. +It is used to host unmodified guest operating systems on top of FreeBSD. +.Pp +.Nm +relies heavily on hardware assist provided by the CPU and chipset to virtualize +processor and memory resources. +.Sh SEE ALSO +.Xr vmm 4 , +.Xr bhyve 8 , +.Xr bhyvectl 8 , +.Xr bhyveload 8 +.Sh HISTORY +.Nm +first appeared in +.Fx 10.0 , +and was developed at NetApp Inc. +.Sh AUTHORS +.Nm +was developed by +.An -nosplit +.An Peter Grehan Aq Mt grehan@FreeBSD.org +and +.An Neel Natu Aq Mt neel@FreeBSD.org +at NetApp Inc. +.Sh BUGS +.Nm +is considered experimental in +.Fx . diff --git a/static/freebsd/man4/blackhole.4 b/static/freebsd/man4/blackhole.4 new file mode 100644 index 00000000..777a38ee --- /dev/null +++ b/static/freebsd/man4/blackhole.4 @@ -0,0 +1,104 @@ +.\" +.\" blackhole - drop refused TCP or UDP connects +.\" +.\" 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. +.\" +.Dd September 24, 2025 +.Dt BLACKHOLE 4 +.Os +.Sh NAME +.Nm blackhole +.Nd quietly drop refused SCTP, TCP, or UDP packets +.Sh SYNOPSIS +.Cd sysctl net.inet.sctp.blackhole Ns Op = Ns Brq "0 | 1 | 2" +.Cd sysctl net.inet.tcp.blackhole Ns Op = Ns Brq "0 | 1 | 2 | 3" +.Cd sysctl net.inet.tcp.blackhole_local Ns Op = Ns Brq "0 | 1" +.Cd sysctl net.inet.udp.blackhole Ns Op = Ns Brq "0 | 1" +.Cd sysctl net.inet.udp.blackhole_local Ns Op = Ns Brq "0 | 1" +.Sh DESCRIPTION +The +.Nm +.Xr sysctl 8 +MIB is used to control system behaviour when connection requests +are received on SCTP, TCP, or UDP ports where there is no socket listening +or unexpected packets are received on listening sockets. +.Pp +The blackhole behaviour is useful to slow down an attacker who is port-scanning +a system in an attempt to detect vulnerable services. +It might also slow down an attempted denial of service attack. +.Pp +The blackhole behaviour is disabled by default. +If enabled, the locally originated packets would still be responded to, +unless also +.Va net.inet.tcp.blackhole_local +(for TCP) and/or +.Va net.inet.udp.blackhole_local +(for UDP) are enforced. +.Ss SCTP +Setting the SCTP blackhole MIB to a numeric value of one +will prevent sending an ABORT packet in response to an incoming INIT. +A MIB value of two will do the same, but will also prevent sending an ABORT packet +when unexpected packets are received. +.Ss TCP +Normal behaviour, when a TCP SYN segment is received on a port where +there is no socket accepting connections, is for the system to return +a RST segment, and drop the incoming SYN segment. +The connecting system will +see this as a +.Dq Connection refused . +By setting the TCP blackhole +MIB to a numeric value of one, the incoming SYN segment +is merely dropped, and no RST is sent, making the system appear +as a blackhole. +By setting the MIB value to two, any segment arriving +on a closed port is dropped without returning a RST. +Setting the MIB value to three, any segment arriving on a closed port +or an unexpected segment on a listening port is dropped without sending a +RST in reply. +This provides some degree of protection against stealth port scans. +.Ss UDP +Enabling blackhole behaviour turns off the sending +of an ICMP port unreachable message in response to a UDP datagram which +arrives on a port where there is no socket listening. +It must be noted that this behaviour will prevent remote systems from running +.Xr traceroute 8 +to a system. +.Sh WARNING +The SCTP, TCP, and UDP blackhole features should not be regarded as a replacement +for firewall solutions. +Better security would consist of the +.Nm +.Xr sysctl 8 +MIB used in conjunction with one of the available firewall packages. +.Pp +This mechanism is not a substitute for securing a system. +It should be used together with other security mechanisms. +.Sh SEE ALSO +.Xr ip 4 , +.Xr sctp 4 , +.Xr tcp 4 , +.Xr udp 4 , +.Xr ipf 8 , +.Xr ipfw 8 , +.Xr pfctl 8 , +.Xr sysctl 8 +.Sh HISTORY +The TCP and UDP +.Nm +MIBs +first appeared in +.Fx 4.0 . +.Pp +The SCTP +.Nm +MIB first appeared in +.Fx 9.1 . +.Sh AUTHORS +.An Geoffrey M. Rehmet diff --git a/static/freebsd/man4/bnxt.4 b/static/freebsd/man4/bnxt.4 new file mode 100644 index 00000000..5e3ee274 --- /dev/null +++ b/static/freebsd/man4/bnxt.4 @@ -0,0 +1,271 @@ +.\" Copyright (c) 2016 Broadcom, All Rights Reserved. +.\" The term Broadcom refers to Broadcom Limited and/or its subsidiaries +.\" +.\" 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 COPYRIGHT HOLDERS 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 COPYRIGHT OWNER 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 December 10, 2025 +.Dt BNXT 4 +.Os +.Sh NAME +.Nm bnxt +.Nd Broadcom NetXtreme family 10Gb to 400Gb Ethernet driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device iflib" +.Cd "device bnxt" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_bnxt_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for PCIe NICs based on the Broadcom BCM573XX, +BCM574XX, BCM575XX, and BCM576XX Ethernet controllers. +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports the following +Broadcom 10Gb to 400Gb Ethernet controllers: +.Pp +.Bl -bullet -compact +.It +Broadcom BCM57301 NetXtreme-C 10Gb Ethernet Controller +.It +Broadcom BCM57302 NetXtreme-C 10Gb/25Gb Ethernet Controller +.It +Broadcom BCM57304 NetXtreme-C 10Gb/25Gb/40Gb/50Gb Ethernet Controller +.It +Broadcom BCM57304 NetXtreme-C Ethernet Virtual Function +.It +Broadcom BCM57314 NetXtreme-C Ethernet Virtual Function +.It +Broadcom BCM57402 NetXtreme-E 10Gb Ethernet Controller +.It +Broadcom BCM57402 NetXtreme-E Ethernet Partition +.It +Broadcom BCM57404 NetXtreme-E 10Gb/25Gb Ethernet Controller +.It +Broadcom BCM57404 NetXtreme-E Ethernet Virtual Function +.It +Broadcom BCM57404 NetXtreme-E Partition +.It +Broadcom BCM57406 NetXtreme-E 10GBASE-T Ethernet Controller +.It +Broadcom BCM57406 NetXtreme-E Partition +.It +Broadcom BCM57407 NetXtreme-E 10GBase-T Ethernet Controller +.It +Broadcom BCM57407 NetXtreme-E 25Gb Ethernet Controller +.It +Broadcom BCM57407 NetXtreme-E Partition +.It +Broadcom BCM57412 NetXtreme-E Partition +.It +Broadcom BCM57414 NetXtreme-E Ethernet Virtual Function +.It +Broadcom BCM57414 NetXtreme-E Partition +.It +Broadcom BCM57416 NetXtreme-E Partition +.It +Broadcom BCM57417 NetXtreme-E Ethernet Partition +.It +Broadcom BCM57454 NetXtreme-E 10Gb/25Gb/40Gb/50Gb/100Gb Ethernet +.It +Broadcom BCM57502 NetXtreme-E 10Gb/25Gb/50Gb Ethernet +.It +Broadcom N425 BCM57504 NetXtreme-E 10Gb/25Gb Ethernet +.It +Broadcom P425 BCM57504 NetXtreme-E 10Gb/25Gb Ethernet +.It +Broadcom N1100 BCM57504 NetXtreme-E 10Gb/25Gb/50Gb/100Gb Ethernet +.It +Broadcom N2100 BCM57508 Thor 10Gb/25Gb/50Gb/100Gb Ethernet +.It +Broadcom P2100 BCM57508 Thor 10Gb/25Gb/50Gb/100Gb Ethernet +.It +Broadcom N2200 BCM57608 Thor 2 10Gb/25Gb/50Gb/100Gb/200Gb Ethernet +.It +Broadcom P2200 BCM57608 Thor 2 10Gb/25Gb/50Gb/100Gb/200Gb Ethernet +.It +Broadcom N1400 BCM57608 Thor 2 25Gb/50Gb/100Gb/200Gb/400Gb Ethernet +.It +Broadcom P1400 BCM57608 Thor 2 25Gb/50Gb/100Gb/200Gb/400Gb Ethernet +.El +.Sh SYSCTL VARIABLES +These variables must be set before loading the driver, either via +.Xr loader.conf 5 +or through the use of +.Xr kenv 1 . +These are provided by the +.Xr iflib 4 +framework, and might be better documented there. +.Bl -tag -width indent +.It Va dev.bnxt.X.iflib.override_nrxds +Override the number of RX descriptors for each queue. +The value is a comma separated list of three positive integers: the size of the +completion ring, +the size of the receive ring, and the size of the aggregation ring respectively. +The completion ring should be at least the size of the aggregation ring plus +four times the size of the receive ring. +These numbers must be powers of two, and zero means to use the default. +Defaults to 0,0,0. +.It Va dev.bnxt.X.iflib.override_ntxds +Override the number of TX descriptors for each queue. +The value is a comma separated list of two positive integers: the size of the +completion ring, and the size of the transmit ring respectively. +The completion ring should be at least twice the size of the transmit ring. +These numbers must be powers of two, and zero means to use the default. +Defaults to 0,0. +.It Va dev.bnxt.X.iflib.override_qs_enable +When set, allows the number of transmit and receive queues to be different. +If not set, the lower of the number of TX or RX queues will be used for both. +.It Va dev.bnxt.X.iflib.override_nrxqs +Set the number of RX queues. +If zero, the number of RX queues is derived from the number of cores on the +socket connected to the controller. +Defaults to 0. +.It Va dev.bnxt.X.iflib.override_ntxqs +Set the number of TX queues. +If zero, the number of TX queues is derived from the number of cores on the +socket connected to the controller. +.El +.Pp +These +.Xr sysctl 8 +variables can be changed at any time: +.Bl -tag -width indent +.It Va dev.bnxt.X.vlan_only +Require that incoming frames must have a VLAN tag on them that matches one that +is configured for the NIC. +Normally, both frames that have a matching VLAN tag and frames that have no +VLAN tag are accepted. +Defaults to 0. +.It Va dev.bnxt.X.vlan_strip +When non-zero the NIC strips VLAN tags on receive. +Defaults to 0. +.It Va dev.bnxt.X.rx_stall +Enable buffering rather than dropping frames when there are no available host +RX buffers for DMA. +Defaults to 0. +.It Va dev.bnxt.X.rss_type +Comma-separated list of RSS hash types to support. +Default is all types. +Defaults to ipv4,tcp_ipv4,udp_ipv4,ipv6,tcp_ipv6,udp_ipv6. +.It Va dev.bnxt.X.rss_key +Current RSS key. +Defaults to a randomly generated value which is generated for each device +during attach. +.It Va dev.bnxt.X.ver.hwrm_min_ver +Minimum HWRM (HardWare Resource Manager) firmware API to support. +If the firmware implements an older version, a warning will be printed, and the +firmware should be upgraded. +Defaults to 1.2.2. +.El +.Pp +These +.Xr sysctl 8 +variables are read-only: +.Bl -tag -width indent +.It Va dev.bnxt.X.if_name +Current interface name of the device. +This will normally be +.Va bnxtX , +but this can be changed using +.Cm ifconfig name . +This sysctl allows correlating an interface with a child of +.Va dev.bnxt . +.It Va dev.bnxt.X.nvram.* +Information about the NVRAM device which contains the device firmware. +.It Va dev.bnxt.X.ver.* +Version-related information about the device and firmware: +.It Va dev.bnxt.X.ver.hwrm_if +Supported HWRM API version of the currently running firmware. +.It Va dev.bnxt.X.ver.driver_hwrm_if +HWRM API version the driver was built to support. +.It Va dev.bnxt.X.hwstats.* +Per-queue statistics tracked by the hardware. +.It Va dev.bnxt.X.hwstats.port_stats.* +Per-port statistics tracked by the hardware. +.It Va dev.bnxt.X.hwstats.rxq0.drop_pkts +Number of packets dropped by hardware on queue zero. +This number might seem high, but the count includes packets dropped due to +incorrect destination MAC, unsubscribed multicast address, and other normal +reasons to ignore Ethernet frames. +.It Va dev.bnxt.X.hwstats.rxq0.tpa_* +statistics related to HW LRO. +.It Va dev.bnxt.X.hw_lro.* +Enable / Disable HW LRO feature. +Defaults to disable. +Enabling HW LRO could cause issues when forwarding is enabled on host. +.It Va dev.bnxt.X.fc +Enable / Disable Flow Control feature. +Defaults to Enable +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "bnxt%d: %s command returned %s error." +Device firmware rejected a command from the driver. +There might be a driver/firmware HWRM API mismatch. +.It "bnxt%d: Timeout sending %s (timeout: %d) seq %d" +Device firmware unresponsive. +A PCI device reset is likely needed. +.It "bnxt%d: Timeout sending %s (timeout: %d) msg {0x%x 0x%x} len:%d v: %d" +Partial firmware response. +A PCI device reset is likely needed. +.Pp +As of this writing, the system must be rebooted to initiate a PCI device reset. +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr iflib 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 11.1 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Jack Vogel Aq Mt jfvogel@gmail.com +and +.An Stephen Hurd Aq Mt shurd@freebsd.org , +and is currently maintained by +.An Broadcom Limited Aq Mt freebsd.pdl@broadcom.com . diff --git a/static/freebsd/man4/bnxt_re.4 b/static/freebsd/man4/bnxt_re.4 new file mode 100644 index 00000000..e2bb87c3 --- /dev/null +++ b/static/freebsd/man4/bnxt_re.4 @@ -0,0 +1,91 @@ +.\" Copyright (c) 2024 Broadcom, All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS `AS IS' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd May 15, 2024 +.Dt BNXT_RE 4 +.Os +.Sh NAME +.Nm bnxt_re +.Nd "Broadcom NetXtreme-E RoCE driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place these lines in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "options COMPAT_LINUXKPI" +.Cd "device bnxt" +.Cd "device bnxt_re" +.Ed +.Pp +To load the driver as a module at run-time, +run this command as root: +.Bd -literal -offset indent +kldload bnxt_re +.Ed +.Pp +To load the driver as a +module at boot time, place this line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +bnxt_re_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for Remote Direct Memory Access (RDMA) over +Converged Ethernet (RoCE) for Broadcom NetXtreme-E PCI Express network +adapters. +.Sh HARDWARE +The +.Nm +driver provides support for NetXtreme-E BCM575xx 10/20/25/40/50/100/200Gb +network adapters, including: +.Pp +.Bl -bullet -compact +.It +Broadcom BCM57502 NetXtreme-E 10Gb/25Gb/50Gb/100Gb/200Gb Ethernet +.It +Broadcom BCM57504 NetXtreme-E 10Gb/25Gb/50Gb/100Gb/200Gb Ethernet +.It +Broadcom BCM57508 NetXtreme-E 10Gb/25Gb/50Gb/100Gb/200Gb Ethernet +.El +.Sh SUPPORT +For general information and support, +go to the Broadcom support website at: +.Pa http://www.broadcom.com/ . +.Pp +Report driver issues with supported adapters to +.Aq Mt freebsd.pdl@broadcom.com . +.Sh SEE ALSO +.Xr bnxt_re 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 15.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Broadcom . diff --git a/static/freebsd/man4/boottrace.4 b/static/freebsd/man4/boottrace.4 new file mode 100644 index 00000000..01cce4c4 --- /dev/null +++ b/static/freebsd/man4/boottrace.4 @@ -0,0 +1,222 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2022 NetApp, Inc. +.\" +.\" 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 1, 2022 +.Dt BOOTTRACE 4 +.Os +.Sh NAME +.Nm boottrace +.Nd Boot-time, run-time, and shutdown-time tracing facility +.Sh SYNOPSIS +.In sys/boottrace.h +.Sh DESCRIPTION +.Nm +is a kernel-userspace interface for capturing trace events +during system boot and shutdown +.Pq in particular, one-shot events . +.Pp +Event annotations are present in: +.Bl -bullet -compact +.It +the boot and shutdown paths in the +kernel +.It +some key system utilities +.Po +.Xr init 8 , +.Xr shutdown 8 , +.Xr reboot 8 +.Pc +.It +.Xr rc 8 +scripts +.El +.Pp +.Nm +is unconditionally compiled into the kernel and +disabled by default. +.Sh EVENT TABLES +Events are stored in three event tables: boot-time events, run-time events, +and shutdown-time events. +.Bl -column "shutdown-time events" "" +.It Sy Table Name Ta Sy Event Description +.It boot-time events Ta Boot, kernel initialization, and +.Xr rc 8 +execution; +.Xo +until +.Xr init 8 +transitions into multi-user mode +.Xc +.It run-time events Ta Xo +From when the system has completed booting (including +.Xr rc 8 +execution) and +.Xr init 8 +transitions to multi-user mode +until the beginning of shutdown procedures +.Xc +.It shutdown-time events Ta Xo +After initialization of a shutdown, a reboot, or a kernel panic +.Xc +.El +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Nm +features the following loader tunables: +.Bl -tag -width indent +.It Va kern.boottrace.dotrace_kernel +Set to +.Ql 1 +to enable tracing of kernel events. +Default: +.Ql 1 +.Pq enabled . +.It Va kern.boottrace.dotrace_user +Set to +.Ql 1 +to enable tracing of userspace events. +Default: +.Ql 1 +.Pq enabled . +.El +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va kern.boottrace.boottrace +Create a new trace event and write it to the boot-time table. +.Pp +A new trace event consists of a process name and an event description, +separated by a colon +.Pq Ql \&: . +If the colon is missing or if the provided string for the process name is empty, +the process name is inferred from the invoking process +.Pq which is its executable name . +.It Va kern.boottrace.enabled +Set to +.Ql 1 +to enable tracing. +This is a read-only +.Xr sysctl 8 +variable. +Default: +.Ql 0 +.Pq disabled . +.It Va kern.boottrace.log +Show the events stored in boot-time and run-time +tables. +This +is an opaque +.Xr sysctl 8 +variable. +.It Va kern.boottrace.runtrace +Same as +.Va kern.boottrace.boottrace , +but write to the run-time table. +.It Va kern.boottrace.shuttrace +Same as +.Va kern.boottrace.boottrace , +but write to the shutdown-time table. +.It Va kern.boottrace.shutdown_trace +Log shutdown-time events to the console before the system halts. +.It Va kern.boottrace.shutdown_trace_threshold +Set a time threshold for logging shutdown-time events in milliseconds. +An event is ignored +if the time difference to the previous event is less than +the threshold value. +Default: +.Ql 0 +.Pq logs all events . +.El +.Sh EXAMPLES +Create a new trace event with a process name +.Dq foo +and an event description +.Dq bar +using +.Xr sysctl 8 : +.Bd -literal -offset indent +sysctl kern.boottrace.boottrace="foo:bar" +.Ed +.Pp +Here is a sample output of +.Va kern.boottrace.log +.Po shortened with +.Dq [...] +for readability +.Pc : +.Bd -literal +CPU msecs delta process event PID CPUtime IBlks OBlks + 0 44872811 0 kernel sysinit 0x2100001 0 0.00 0 0 + 0 44872812 1 kernel sysinit 0x2110000 0 0.00 0 0 + 0 44872812 0 kernel sysinit 0x2140000 0 0.00 0 0 +[...] + 0 44872817 0 kernel sysinit 0x2800000 0 0.00 0 0 + 0 44873820 1003 kernel sysinit 0x2880000 0 0.00 0 0 + 0 44873820 0 kernel sysinit 0x2888000 0 0.00 0 0 +[...] + 1 44875735 0 kernel sysinit 0xfffffff 0 0.00 0 0 + 1 44875735 0 swapper mi_startup done 0 0.00 0 0 + 0 44875750 15 init init(8) starting... 1 0.00 0 0 + 0 44875751 1 init /etc/rc starting... 1 0.00 0 0 + 0 44875831 80 boottrace /etc/rc.d/rctl start 26 0.00 0 0 + 1 44875839 8 boottrace /etc/rc.d/rctl done 26 0.00 2 0 +[...] + 0 44876446 0 boottrace /etc/rc.d/netif start 390 0.00 0 0 + 1 44881116 4670 boottrace /etc/rc.d/netif done 390 0.12 34 0 +[...] + 0 44882866 1 boottrace /etc/rc.d/securelevel start 1679 0.00 0 0 + 0 44882872 6 boottrace /etc/rc.d/securelevel done 1679 0.00 0 0 + 1 44882879 7 init /etc/rc finished 1 2.22 743 15 +Total measured time: 10068 msecs + + +CPU msecs delta process event PID CPUtime IBlks OBlks + 1 44882880 0 init multi-user start 1 2.22 743 15 + 0 44918215 35335 kldload hwpmc.ko: sysinit 0xd800000 1698 0.00 0 0 +Total measured time: 35335 msecs +.Ed +.Sh SEE ALSO +.Xr tslog 4 , +.Xr boottrace 8 , +.Xr sysctl 8 +.Sh HISTORY +NetApp created +.Nm +to diagnose slow devices and subsystems. +Once upstreamed, +.Nm +was first publicly released with +.Fx 14.0 . +.Sh AUTHORS +This manual page was written by +.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . diff --git a/static/freebsd/man4/bpf.4 b/static/freebsd/man4/bpf.4 new file mode 100644 index 00000000..107d531c --- /dev/null +++ b/static/freebsd/man4/bpf.4 @@ -0,0 +1,1217 @@ +.\" Copyright (c) 2007 Seccuris Inc. +.\" All rights reserved. +.\" +.\" This software was developed by Robert N. M. Watson under contract to +.\" Seccuris Inc. +.\" +.\" 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. +.\" +.\" Copyright (c) 1990 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that: (1) source code distributions +.\" retain the above copyright notice and this paragraph in its entirety, (2) +.\" distributions including binary code include the above copyright notice and +.\" this paragraph in its entirety in the documentation or other materials +.\" provided with the distribution, and (3) all advertising materials mentioning +.\" features or use of this software display the following acknowledgement: +.\" ``This product includes software developed by the University of California, +.\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of +.\" the University nor the names of its contributors may be used to endorse +.\" or promote products derived from this software without specific prior +.\" written permission. +.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED +.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.\" +.\" This document is derived in part from the enet man page (enet.4) +.\" distributed with 4.3BSD Unix. +.\" +.Dd December 10, 2025 +.Dt BPF 4 +.Os +.Sh NAME +.Nm bpf +.Nd Berkeley Packet Filter +.Sh SYNOPSIS +.Cd device bpf +.Sh DESCRIPTION +The Berkeley Packet Filter +provides a raw interface to data link layers in a protocol +independent fashion. +All packets on the network, even those destined for other hosts, +are accessible through this mechanism. +.Pp +The packet filter appears as a character special device, +.Pa /dev/bpf . +After opening the device, the file descriptor must be bound to a +specific network interface with the +.Dv BIOCSETIF +ioctl. +A given interface can be shared by multiple listeners, and the filter +underlying each descriptor will see an identical packet stream. +.Pp +Associated with each open instance of a +.Nm +file is a user-settable packet filter. +Whenever a packet is received by an interface, +all file descriptors listening on that interface apply their filter. +Each descriptor that accepts the packet receives its own copy. +.Pp +A packet can be sent out on the network by writing to a +.Nm +file descriptor. +The writes are unbuffered, meaning only one packet can be processed per write. +Currently, only writes to Ethernets and +.Tn SLIP +links are supported. +.Sh BUFFER MODES +.Nm +devices deliver packet data to the application via memory buffers provided by +the application. +The buffer mode is set using the +.Dv BIOCSETBUFMODE +ioctl, and read using the +.Dv BIOCGETBUFMODE +ioctl. +.Ss Buffered read mode +By default, +.Nm +devices operate in the +.Dv BPF_BUFMODE_BUFFER +mode, in which packet data is copied explicitly from kernel to user memory +using the +.Xr read 2 +system call. +The user process will declare a fixed buffer size that will be used both for +sizing internal buffers and for all +.Xr read 2 +operations on the file. +This size is queried using the +.Dv BIOCGBLEN +ioctl, and is set using the +.Dv BIOCSBLEN +ioctl. +Note that an individual packet larger than the buffer size is necessarily +truncated. +.Ss Zero-copy buffer mode +.Nm +devices may also operate in the +.Dv BPF_BUFMODE_ZEROCOPY +mode, in which packet data is written directly into two user memory buffers +by the kernel, avoiding both system call and copying overhead. +Buffers are of fixed (and equal) size, page-aligned, and an even multiple of +the page size. +The maximum zero-copy buffer size is returned by the +.Dv BIOCGETZMAX +ioctl. +Note that an individual packet larger than the buffer size is necessarily +truncated. +.Pp +The user process registers two memory buffers using the +.Dv BIOCSETZBUF +ioctl, which accepts a +.Vt struct bpf_zbuf +pointer as an argument: +.Bd -literal +struct bpf_zbuf { + void *bz_bufa; + void *bz_bufb; + size_t bz_buflen; +}; +.Ed +.Pp +.Vt bz_bufa +is a pointer to the userspace address of the first buffer that will be +filled, and +.Vt bz_bufb +is a pointer to the second buffer. +.Nm +will then cycle between the two buffers as they fill and are acknowledged. +.Pp +Each buffer begins with a fixed-length header to hold synchronization and +data length information for the buffer: +.Bd -literal +struct bpf_zbuf_header { + volatile u_int bzh_kernel_gen; /* Kernel generation number. */ + volatile u_int bzh_kernel_len; /* Length of data in the buffer. */ + volatile u_int bzh_user_gen; /* User generation number. */ + /* ...padding for future use... */ +}; +.Ed +.Pp +The header structure of each buffer, including all padding, should be zeroed +before it is configured using +.Dv BIOCSETZBUF . +Remaining space in the buffer will be used by the kernel to store packet +data, laid out in the same format as with buffered read mode. +.Pp +The kernel and the user process follow a simple acknowledgement protocol via +the buffer header to synchronize access to the buffer: when the header +generation numbers, +.Vt bzh_kernel_gen +and +.Vt bzh_user_gen , +hold the same value, the kernel owns the buffer, and when they differ, +userspace owns the buffer. +.Pp +While the kernel owns the buffer, the contents are unstable and may change +asynchronously; while the user process owns the buffer, its contents are +stable and will not be changed until the buffer has been acknowledged. +.Pp +Initializing the buffer headers to all 0's before registering the buffer has +the effect of assigning initial ownership of both buffers to the kernel. +The kernel signals that a buffer has been assigned to userspace by modifying +.Vt bzh_kernel_gen , +and userspace acknowledges the buffer and returns it to the kernel by setting +the value of +.Vt bzh_user_gen +to the value of +.Vt bzh_kernel_gen . +.Pp +In order to avoid caching and memory re-ordering effects, the user process +must use atomic operations and memory barriers when checking for and +acknowledging buffers: +.Bd -literal +#include + +/* + * Return ownership of a buffer to the kernel for reuse. + */ +static void +buffer_acknowledge(struct bpf_zbuf_header *bzh) +{ + + atomic_store_rel_int(&bzh->bzh_user_gen, bzh->bzh_kernel_gen); +} + +/* + * Check whether a buffer has been assigned to userspace by the kernel. + * Return true if userspace owns the buffer, and false otherwise. + */ +static int +buffer_check(struct bpf_zbuf_header *bzh) +{ + + return (bzh->bzh_user_gen != + atomic_load_acq_int(&bzh->bzh_kernel_gen)); +} +.Ed +.Pp +The user process may force the assignment of the next buffer, if any data +is pending, to userspace using the +.Dv BIOCROTZBUF +ioctl. +This allows the user process to retrieve data in a partially filled buffer +before the buffer is full, such as following a timeout; the process must +recheck for buffer ownership using the header generation numbers, as the +buffer will not be assigned to userspace if no data was present. +.Pp +As in the buffered read mode, +.Xr kqueue 2 , +.Xr poll 2 , +and +.Xr select 2 +may be used to sleep awaiting the availability of a completed buffer. +They will return a readable file descriptor when ownership of the next buffer +is assigned to user space. +.Pp +In the current implementation, the kernel may assign zero, one, or both +buffers to the user process; however, an earlier implementation maintained +the invariant that at most one buffer could be assigned to the user process +at a time. +In order to both ensure progress and high performance, user processes should +acknowledge a completely processed buffer as quickly as possible, returning +it for reuse, and not block waiting on a second buffer while holding another +buffer. +.Sh IOCTLS +The +.Xr ioctl 2 +command codes below are defined in +.In net/bpf.h . +All commands require +these includes: +.Bd -literal + #include + #include + #include + #include +.Ed +.Pp +Additionally, +.Dv BIOCGETIF +and +.Dv BIOCSETIF +require +.In sys/socket.h +and +.In net/if.h . +.Pp +In addition to +.Dv FIONREAD +the following commands may be applied to any open +.Nm +file. +The (third) argument to +.Xr ioctl 2 +should be a pointer to the type indicated. +.Bl -tag -width BIOCGETBUFMODE +.It Dv BIOCGETIFLIST +.Pq Li "struct bpf_iflist" +Returns list of available tapping points, that can later be attached +to with +.Dv BIOCSETIF . +On entry the +.Vt bi_ubuf +shall point to user supplied buffer. +The +.Vt bi_size +shall specify length of the buffer, or 0 if the request is used +to determine the required length. +The +.Vt bi_count +can be used to limit the output to first +.Va count +entries, otherwise shall be 0. +On return, if the buffer length was enough to accommodate all desired entries, +then the supplied buffer is filled with NUL-terminated names of +available tapping points and +.Vt bi_count +is set to the number of copied names. +Otherwise +.Er ENOSPC +is returned. +.It Dv BIOCGBLEN +.Pq Li u_int +Returns the required buffer length for reads on +.Nm +files. +.It Dv BIOCSBLEN +.Pq Li u_int +Sets the buffer length for reads on +.Nm +files. +The buffer must be set before the file is attached to an interface +with +.Dv BIOCSETIF . +If the requested buffer size cannot be accommodated, the closest +allowable size will be set and returned in the argument. +A read call will result in +.Er EINVAL +if it is passed a buffer that is not this size. +.It Dv BIOCGDLT +.Pq Li u_int +Returns the type of the data link layer underlying the attached interface. +.Er EINVAL +is returned if no interface has been specified. +The device types, prefixed with +.Dq Li DLT_ , +are defined in +.In net/bpf.h . +.It Dv BIOCGDLTLIST +.Pq Li "struct bpf_dltlist" +Returns an array of the available types of the data link layer +underlying the attached interface: +.Bd -literal -offset indent +struct bpf_dltlist { + u_int bfl_len; + u_int *bfl_list; +}; +.Ed +.Pp +The available types are returned in the array pointed to by the +.Va bfl_list +field while their length in u_int is supplied to the +.Va bfl_len +field. +.Er ENOMEM +is returned if there is not enough buffer space and +.Er EFAULT +is returned if a bad address is encountered. +The +.Va bfl_len +field is modified on return to indicate the actual length in u_int +of the array returned. +If +.Va bfl_list +is +.Dv NULL , +the +.Va bfl_len +field is set to indicate the required length of an array in u_int. +.It Dv BIOCSDLT +.Pq Li u_int +Changes the type of the data link layer underlying the attached interface. +.Er EINVAL +is returned if no interface has been specified or the specified +type is not available for the interface. +.It Dv BIOCPROMISC +Forces the interface into promiscuous mode. +All packets, not just those destined for the local host, are processed. +Since more than one file can be listening on a given interface, +a listener that opened its interface non-promiscuously may receive +packets promiscuously. +This problem can be remedied with an appropriate filter. +.Pp +The interface remains in promiscuous mode until all files listening +promiscuously are closed. +.It Dv BIOCFLUSH +Flushes the buffer of incoming packets, +and resets the statistics that are returned by BIOCGSTATS. +.It Dv BIOCGETIF +.Pq Li "struct ifreq" +Returns the name of the hardware interface that the file is listening on. +The name is returned in the ifr_name field of +the +.Li ifreq +structure. +All other fields are undefined. +.It Dv BIOCSETIF +.Pq Li "struct ifreq" +Sets the hardware interface associated with the file. +This +command must be performed before any packets can be read. +The device is indicated by name using the +.Li ifr_name +field of the +.Li ifreq +structure. +Additionally, performs the actions of +.Dv BIOCFLUSH . +.It Dv BIOCSRTIMEOUT +.It Dv BIOCGRTIMEOUT +.Pq Li "struct timeval" +Sets or gets the read timeout parameter. +The argument +specifies the length of time to wait before timing +out on a read request. +This parameter is initialized to zero by +.Xr open 2 , +indicating no timeout. +.It Dv BIOCGSTATS +.Pq Li "struct bpf_stat" +Returns the following structure of packet statistics: +.Bd -literal +struct bpf_stat { + u_int bs_recv; /* number of packets received */ + u_int bs_drop; /* number of packets dropped */ +}; +.Ed +.Pp +The fields are: +.Bl -hang -offset indent +.It Li bs_recv +the number of packets received by the descriptor since opened or reset +(including any buffered since the last read call); +and +.It Li bs_drop +the number of packets which were accepted by the filter but dropped by the +kernel because of buffer overflows +(i.e., the application's reads are not keeping up with the packet traffic). +.El +.It Dv BIOCIMMEDIATE +.Pq Li u_int +Enables or disables +.Dq immediate mode , +based on the truth value of the argument. +When immediate mode is enabled, reads return immediately upon packet +reception. +Otherwise, a read will block until either the kernel buffer +becomes full or a timeout occurs. +This is useful for programs like +.Xr rarpd 8 +which must respond to messages in real time. +The default for a new file is off. +.It Dv BIOCSETF +.It Dv BIOCSETFNR +.Pq Li "struct bpf_program" +Sets the read filter program used by the kernel to discard uninteresting +packets. +An array of instructions and its length is passed in using +the following structure: +.Bd -literal +struct bpf_program { + u_int bf_len; + struct bpf_insn *bf_insns; +}; +.Ed +.Pp +The filter program is pointed to by the +.Li bf_insns +field while its length in units of +.Sq Li struct bpf_insn +is given by the +.Li bf_len +field. +See section +.Sx "FILTER MACHINE" +for an explanation of the filter language. +The only difference between +.Dv BIOCSETF +and +.Dv BIOCSETFNR +is +.Dv BIOCSETF +performs the actions of +.Dv BIOCFLUSH +while +.Dv BIOCSETFNR +does not. +.It Dv BIOCSETWF +.Pq Li "struct bpf_program" +Sets the write filter program used by the kernel to control what type of +packets can be written to the interface. +See the +.Dv BIOCSETF +command for more +information on the +.Nm +filter program. +.It Dv BIOCVERSION +.Pq Li "struct bpf_version" +Returns the major and minor version numbers of the filter language currently +recognized by the kernel. +Before installing a filter, applications must check +that the current version is compatible with the running kernel. +Version numbers are compatible if the major numbers match and the application minor +is less than or equal to the kernel minor. +The kernel version number is returned in the following structure: +.Bd -literal +struct bpf_version { + u_short bv_major; + u_short bv_minor; +}; +.Ed +.Pp +The current version numbers are given by +.Dv BPF_MAJOR_VERSION +and +.Dv BPF_MINOR_VERSION +from +.In net/bpf.h . +An incompatible filter +may result in undefined behavior (most likely, an error returned by +.Fn ioctl +or haphazard packet matching). +.It Dv BIOCGRSIG +.It Dv BIOCSRSIG +.Pq Li u_int +Sets or gets the receive signal. +This signal will be sent to the process or process group specified by +.Dv FIOSETOWN . +It defaults to +.Dv SIGIO . +.It Dv BIOCSHDRCMPLT +.It Dv BIOCGHDRCMPLT +.Pq Li u_int +Sets or gets the status of the +.Dq header complete +flag. +Set to zero if the link level source address should be filled in automatically +by the interface output routine. +Set to one if the link level source +address will be written, as provided, to the wire. +This flag is initialized to zero by default. +.It Dv BIOCSSEESENT +.It Dv BIOCGSEESENT +.Pq Li u_int +These commands are obsolete but left for compatibility. +Use +.Dv BIOCSDIRECTION +and +.Dv BIOCGDIRECTION +instead. +Sets or gets the flag determining whether locally generated packets on the +interface should be returned by BPF. +Set to zero to see only incoming packets on the interface. +Set to one to see packets originating locally and remotely on the interface. +This flag is initialized to one by default. +.It Dv BIOCSDIRECTION +.It Dv BIOCGDIRECTION +.Pq Li u_int +Sets or gets the setting determining whether incoming, outgoing, or all packets +on the interface should be returned by BPF. +Set to +.Dv BPF_D_IN +to see only incoming packets on the interface. +Set to +.Dv BPF_D_INOUT +to see packets originating locally and remotely on the interface. +Set to +.Dv BPF_D_OUT +to see only outgoing packets on the interface. +This setting is initialized to +.Dv BPF_D_INOUT +by default. +.It Dv BIOCSTSTAMP +.It Dv BIOCGTSTAMP +.Pq Li u_int +Set or get format and resolution of the time stamps returned by BPF. +Set to +.Dv BPF_T_MICROTIME , +.Dv BPF_T_MICROTIME_FAST , +.Dv BPF_T_MICROTIME_MONOTONIC , +or +.Dv BPF_T_MICROTIME_MONOTONIC_FAST +to get time stamps in 64-bit +.Vt struct timeval +format. +Set to +.Dv BPF_T_NANOTIME , +.Dv BPF_T_NANOTIME_FAST , +.Dv BPF_T_NANOTIME_MONOTONIC , +or +.Dv BPF_T_NANOTIME_MONOTONIC_FAST +to get time stamps in 64-bit +.Vt struct timespec +format. +Set to +.Dv BPF_T_BINTIME , +.Dv BPF_T_BINTIME_FAST , +.Dv BPF_T_NANOTIME_MONOTONIC , +or +.Dv BPF_T_BINTIME_MONOTONIC_FAST +to get time stamps in 64-bit +.Vt struct bintime +format. +Set to +.Dv BPF_T_NONE +to ignore time stamp. +All 64-bit time stamp formats are wrapped in +.Vt struct bpf_ts . +The +.Dv BPF_T_MICROTIME_FAST , +.Dv BPF_T_NANOTIME_FAST , +.Dv BPF_T_BINTIME_FAST , +.Dv BPF_T_MICROTIME_MONOTONIC_FAST , +.Dv BPF_T_NANOTIME_MONOTONIC_FAST , +and +.Dv BPF_T_BINTIME_MONOTONIC_FAST +are analogs of corresponding formats without _FAST suffix but do not perform +a full time counter query, so their accuracy is one timer tick. +The +.Dv BPF_T_MICROTIME_MONOTONIC , +.Dv BPF_T_NANOTIME_MONOTONIC , +.Dv BPF_T_BINTIME_MONOTONIC , +.Dv BPF_T_MICROTIME_MONOTONIC_FAST , +.Dv BPF_T_NANOTIME_MONOTONIC_FAST , +and +.Dv BPF_T_BINTIME_MONOTONIC_FAST +store the time elapsed since kernel boot. +This setting is initialized to +.Dv BPF_T_MICROTIME +by default. +.It Dv BIOCFEEDBACK +.Pq Li u_int +Set packet feedback mode. +This allows injected packets to be fed back as input to the interface when +output via the interface is successful. +When +.Dv BPF_D_INOUT +direction is set, injected outgoing packet is not returned by BPF to avoid +duplication. +This flag is initialized to zero by default. +.It Dv BIOCLOCK +Set the locked flag on the +.Nm +descriptor. +This prevents the execution of +ioctl commands which could change the underlying operating parameters of +the device. +.It Dv BIOCGETBUFMODE +.It Dv BIOCSETBUFMODE +.Pq Li u_int +Get or set the current +.Nm +buffering mode; possible values are +.Dv BPF_BUFMODE_BUFFER , +buffered read mode, and +.Dv BPF_BUFMODE_ZBUF , +zero-copy buffer mode. +.It Dv BIOCSETZBUF +.Pq Li struct bpf_zbuf +Set the current zero-copy buffer locations; buffer locations may be +set only once zero-copy buffer mode has been selected, and prior to attaching +to an interface. +Buffers must be of identical size, page-aligned, and an integer multiple of +pages in size. +The three fields +.Vt bz_bufa , +.Vt bz_bufb , +and +.Vt bz_buflen +must be filled out. +If buffers have already been set for this device, the ioctl will fail. +.It Dv BIOCGETZMAX +.Pq Li size_t +Get the largest individual zero-copy buffer size allowed. +As two buffers are used in zero-copy buffer mode, the limit (in practice) is +twice the returned size. +As zero-copy buffers consume kernel address space, conservative selection of +buffer size is suggested, especially when there are multiple +.Nm +descriptors in use on 32-bit systems. +.It Dv BIOCROTZBUF +Force ownership of the next buffer to be assigned to userspace, if any data +present in the buffer. +If no data is present, the buffer will remain owned by the kernel. +This allows consumers of zero-copy buffering to implement timeouts and +retrieve partially filled buffers. +In order to handle the case where no data is present in the buffer and +therefore ownership is not assigned, the user process must check +.Vt bzh_kernel_gen +against +.Vt bzh_user_gen . +.It Dv BIOCSETVLANPCP +Set the VLAN PCP bits to the supplied value. +.El +.Sh STANDARD IOCTLS +.Nm +now supports several standard +.Xr ioctl 2 Ns 's +which allow the user to do async and/or non-blocking I/O to an open +.Em bpf +file descriptor. +.Bl -tag -width SIOCGIFADDR +.It Dv FIONREAD +.Pq Li int +Returns the number of bytes that are immediately available for reading. +.It Dv SIOCGIFADDR +.Pq Li "struct ifreq" +Returns the address associated with the interface. +.It Dv FIONBIO +.Pq Li int +Sets or clears non-blocking I/O. +If arg is non-zero, then doing a +.Xr read 2 +when no data is available will return -1 and +.Va errno +will be set to +.Er EAGAIN . +If arg is zero, non-blocking I/O is disabled. +Note: setting this overrides the timeout set by +.Dv BIOCSRTIMEOUT . +.It Dv FIOASYNC +.Pq Li int +Enables or disables async I/O. +When enabled (arg is non-zero), the process or process group specified by +.Dv FIOSETOWN +will start receiving +.Dv SIGIO 's +when packets arrive. +Note that you must do an +.Dv FIOSETOWN +in order for this to take effect, +as the system will not default this for you. +The signal may be changed via +.Dv BIOCSRSIG . +.It Dv FIOSETOWN +.It Dv FIOGETOWN +.Pq Li int +Sets or gets the process or process group (if negative) that should +receive +.Dv SIGIO +when packets are available. +The signal may be changed using +.Dv BIOCSRSIG +(see above). +.El +.Sh BPF HEADER +One of the following structures is prepended to each packet returned by +.Xr read 2 +or via a zero-copy buffer: +.Bd -literal +struct bpf_xhdr { + struct bpf_ts bh_tstamp; /* time stamp */ + uint32_t bh_caplen; /* length of captured portion */ + uint32_t bh_datalen; /* original length of packet */ + u_short bh_hdrlen; /* length of bpf header (this struct + plus alignment padding) */ +}; + +struct bpf_hdr { + struct timeval bh_tstamp; /* time stamp */ + uint32_t bh_caplen; /* length of captured portion */ + uint32_t bh_datalen; /* original length of packet */ + u_short bh_hdrlen; /* length of bpf header (this struct + plus alignment padding) */ +}; +.Ed +.Pp +The fields, whose values are stored in host order, and are: +.Pp +.Bl -tag -compact -width bh_datalen +.It Li bh_tstamp +The time at which the packet was processed by the packet filter. +.It Li bh_caplen +The length of the captured portion of the packet. +This is the minimum of +the truncation amount specified by the filter and the length of the packet. +.It Li bh_datalen +The length of the packet off the wire. +This value is independent of the truncation amount specified by the filter. +.It Li bh_hdrlen +The length of the +.Nm +header, which may not be equal to +.\" XXX - not really a function call +.Fn sizeof "struct bpf_xhdr" +or +.Fn sizeof "struct bpf_hdr" . +.El +.Pp +The +.Li bh_hdrlen +field exists to account for +padding between the header and the link level protocol. +The purpose here is to guarantee proper alignment of the packet +data structures, which is required on alignment sensitive +architectures and improves performance on many other architectures. +The packet filter ensures that the +.Vt bpf_xhdr , +.Vt bpf_hdr +and the network layer +header will be word aligned. +Currently, +.Vt bpf_hdr +is used when the time stamp is set to +.Dv BPF_T_MICROTIME , +.Dv BPF_T_MICROTIME_FAST , +.Dv BPF_T_MICROTIME_MONOTONIC , +.Dv BPF_T_MICROTIME_MONOTONIC_FAST , +or +.Dv BPF_T_NONE +for backward compatibility reasons. +Otherwise, +.Vt bpf_xhdr +is used. +However, +.Vt bpf_hdr +may be deprecated in the near future. +Suitable precautions +must be taken when accessing the link layer protocol fields on alignment +restricted machines. +(This is not a problem on an Ethernet, since +the type field is a short falling on an even offset, +and the addresses are probably accessed in a bytewise fashion). +.Pp +Additionally, individual packets are padded so that each starts +on a word boundary. +This requires that an application +has some knowledge of how to get from packet to packet. +The macro +.Dv BPF_WORDALIGN +is defined in +.In net/bpf.h +to facilitate +this process. +It rounds up its argument to the nearest word aligned value (where a word is +.Dv BPF_ALIGNMENT +bytes wide). +.Pp +For example, if +.Sq Li p +points to the start of a packet, this expression +will advance it to the next packet: +.Dl p = (char *)p + BPF_WORDALIGN(p->bh_hdrlen + p->bh_caplen) +.Pp +For the alignment mechanisms to work properly, the +buffer passed to +.Xr read 2 +must itself be word aligned. +The +.Xr malloc 3 +function +will always return an aligned buffer. +.Sh FILTER MACHINE +A filter program is an array of instructions, with all branches forwardly +directed, terminated by a +.Em return +instruction. +Each instruction performs some action on the pseudo-machine state, +which consists of an accumulator, index register, scratch memory store, +and implicit program counter. +.Pp +The following structure defines the instruction format: +.Bd -literal +struct bpf_insn { + u_short code; + u_char jt; + u_char jf; + bpf_u_int32 k; +}; +.Ed +.Pp +The +.Li k +field is used in different ways by different instructions, +and the +.Li jt +and +.Li jf +fields are used as offsets +by the branch instructions. +The opcodes are encoded in a semi-hierarchical fashion. +There are eight classes of instructions: +.Dv BPF_LD , +.Dv BPF_LDX , +.Dv BPF_ST , +.Dv BPF_STX , +.Dv BPF_ALU , +.Dv BPF_JMP , +.Dv BPF_RET , +and +.Dv BPF_MISC . +Various other mode and +operator bits are or'd into the class to give the actual instructions. +The classes and modes are defined in +.In net/bpf.h . +.Pp +Below are the semantics for each defined +.Nm +instruction. +We use the convention that A is the accumulator, X is the index register, +P[] packet data, and M[] scratch memory store. +P[i:n] gives the data at byte offset +.Dq i +in the packet, +interpreted as a word (n=4), +unsigned halfword (n=2), or unsigned byte (n=1). +M[i] gives the i'th word in the scratch memory store, which is only +addressed in word units. +The memory store is indexed from 0 to +.Dv BPF_MEMWORDS +- 1. +.Li k , +.Li jt , +and +.Li jf +are the corresponding fields in the +instruction definition. +.Dq len +refers to the length of the packet. +.Bl -tag -width BPF_STXx +.It Dv BPF_LD +These instructions copy a value into the accumulator. +The type of the source operand is specified by an +.Dq addressing mode +and can be a constant +.Pq Dv BPF_IMM , +packet data at a fixed offset +.Pq Dv BPF_ABS , +packet data at a variable offset +.Pq Dv BPF_IND , +the packet length +.Pq Dv BPF_LEN , +or a word in the scratch memory store +.Pq Dv BPF_MEM . +For +.Dv BPF_IND +and +.Dv BPF_ABS , +the data size must be specified as a word +.Pq Dv BPF_W , +halfword +.Pq Dv BPF_H , +or byte +.Pq Dv BPF_B . +The semantics of all the recognized +.Dv BPF_LD +instructions follow. +.Bd -literal +BPF_LD+BPF_W+BPF_ABS A <- P[k:4] +BPF_LD+BPF_H+BPF_ABS A <- P[k:2] +BPF_LD+BPF_B+BPF_ABS A <- P[k:1] +BPF_LD+BPF_W+BPF_IND A <- P[X+k:4] +BPF_LD+BPF_H+BPF_IND A <- P[X+k:2] +BPF_LD+BPF_B+BPF_IND A <- P[X+k:1] +BPF_LD+BPF_W+BPF_LEN A <- len +BPF_LD+BPF_IMM A <- k +BPF_LD+BPF_MEM A <- M[k] +.Ed +.It Dv BPF_LDX +These instructions load a value into the index register. +Note that +the addressing modes are more restrictive than those of the accumulator loads, +but they include +.Dv BPF_MSH , +a hack for efficiently loading the IP header length. +.Bd -literal +BPF_LDX+BPF_W+BPF_IMM X <- k +BPF_LDX+BPF_W+BPF_MEM X <- M[k] +BPF_LDX+BPF_W+BPF_LEN X <- len +BPF_LDX+BPF_B+BPF_MSH X <- 4*(P[k:1]&0xf) +.Ed +.It Dv BPF_ST +This instruction stores the accumulator into the scratch memory. +We do not need an addressing mode since there is only one possibility +for the destination. +.Bd -literal +BPF_ST M[k] <- A +.Ed +.It Dv BPF_STX +This instruction stores the index register in the scratch memory store. +.Bd -literal +BPF_STX M[k] <- X +.Ed +.It Dv BPF_ALU +The alu instructions perform operations between the accumulator and +index register or constant, and store the result back in the accumulator. +For binary operations, a source mode is required +.Dv ( BPF_K +or +.Dv BPF_X ) . +.Bd -literal +BPF_ALU+BPF_ADD+BPF_K A <- A + k +BPF_ALU+BPF_SUB+BPF_K A <- A - k +BPF_ALU+BPF_MUL+BPF_K A <- A * k +BPF_ALU+BPF_DIV+BPF_K A <- A / k +BPF_ALU+BPF_MOD+BPF_K A <- A % k +BPF_ALU+BPF_AND+BPF_K A <- A & k +BPF_ALU+BPF_OR+BPF_K A <- A | k +BPF_ALU+BPF_XOR+BPF_K A <- A ^ k +BPF_ALU+BPF_LSH+BPF_K A <- A << k +BPF_ALU+BPF_RSH+BPF_K A <- A >> k +BPF_ALU+BPF_ADD+BPF_X A <- A + X +BPF_ALU+BPF_SUB+BPF_X A <- A - X +BPF_ALU+BPF_MUL+BPF_X A <- A * X +BPF_ALU+BPF_DIV+BPF_X A <- A / X +BPF_ALU+BPF_MOD+BPF_X A <- A % X +BPF_ALU+BPF_AND+BPF_X A <- A & X +BPF_ALU+BPF_OR+BPF_X A <- A | X +BPF_ALU+BPF_XOR+BPF_X A <- A ^ X +BPF_ALU+BPF_LSH+BPF_X A <- A << X +BPF_ALU+BPF_RSH+BPF_X A <- A >> X +BPF_ALU+BPF_NEG A <- -A +.Ed +.It Dv BPF_JMP +The jump instructions alter flow of control. +Conditional jumps +compare the accumulator against a constant +.Pq Dv BPF_K +or the index register +.Pq Dv BPF_X . +If the result is true (or non-zero), +the true branch is taken, otherwise the false branch is taken. +Jump offsets are encoded in 8 bits so the longest jump is 256 instructions. +However, the jump always +.Pq Dv BPF_JA +opcode uses the 32 bit +.Li k +field as the offset, allowing arbitrarily distant destinations. +All conditionals use unsigned comparison conventions. +.Bd -literal +BPF_JMP+BPF_JA pc += k +BPF_JMP+BPF_JGT+BPF_K pc += (A > k) ? jt : jf +BPF_JMP+BPF_JGE+BPF_K pc += (A >= k) ? jt : jf +BPF_JMP+BPF_JEQ+BPF_K pc += (A == k) ? jt : jf +BPF_JMP+BPF_JSET+BPF_K pc += (A & k) ? jt : jf +BPF_JMP+BPF_JGT+BPF_X pc += (A > X) ? jt : jf +BPF_JMP+BPF_JGE+BPF_X pc += (A >= X) ? jt : jf +BPF_JMP+BPF_JEQ+BPF_X pc += (A == X) ? jt : jf +BPF_JMP+BPF_JSET+BPF_X pc += (A & X) ? jt : jf +.Ed +.It Dv BPF_RET +The return instructions terminate the filter program and specify the amount +of packet to accept (i.e., they return the truncation amount). +A return value of zero indicates that the packet should be ignored. +The return value is either a constant +.Pq Dv BPF_K +or the accumulator +.Pq Dv BPF_A . +.Bd -literal +BPF_RET+BPF_A accept A bytes +BPF_RET+BPF_K accept k bytes +.Ed +.It Dv BPF_MISC +The miscellaneous category was created for anything that does not +fit into the above classes, and for any new instructions that might need to +be added. +Currently, these are the register transfer instructions +that copy the index register to the accumulator or vice versa. +.Bd -literal +BPF_MISC+BPF_TAX X <- A +BPF_MISC+BPF_TXA A <- X +.Ed +.El +.Pp +The +.Nm +interface provides the following macros to facilitate +array initializers: +.Fn BPF_STMT opcode operand +and +.Fn BPF_JUMP opcode operand true_offset false_offset . +.Sh SYSCTL VARIABLES +A set of +.Xr sysctl 8 +variables controls the behaviour of the +.Nm +subsystem +.Bl -tag -width indent +.It Va net.bpf.optimize_writers : No 0 +Various programs use BPF to send (but not receive) raw packets +(cdpd, lldpd, dhcpd, dhcp relays, etc. are good examples of such programs). +They do not need incoming packets to be send to them. +Turning this option on +makes new BPF users to be attached to write-only interface list until program +explicitly specifies read filter via +.Fn pcap_set_filter . +This removes any performance degradation for high-speed interfaces. +.It Va net.bpf.stats : +Binary interface for retrieving general statistics. +.It Va net.bpf.zerocopy_enable : No 0 +Permits zero-copy to be used with net BPF readers. +Use with caution. +.It Va net.bpf.maxinsns : No 512 +Maximum number of instructions that BPF program can contain. +Use +.Xr tcpdump 1 +.Fl d +option to determine approximate number of instruction for any filter. +.It Va net.bpf.maxbufsize : No 524288 +Maximum buffer size to allocate for packets buffer. +.It Va net.bpf.bufsize : No 4096 +Default buffer size to allocate for packets buffer. +.El +.Sh EXAMPLES +The following filter is taken from the Reverse ARP Daemon. +It accepts only Reverse ARP requests. +.Bd -literal +struct bpf_insn insns[] = { + BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), + BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_REVARP, 0, 3), + BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20), + BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ARPOP_REVREQUEST, 0, 1), + BPF_STMT(BPF_RET+BPF_K, sizeof(struct ether_arp) + + sizeof(struct ether_header)), + BPF_STMT(BPF_RET+BPF_K, 0), +}; +.Ed +.Pp +This filter accepts only IP packets between host 128.3.112.15 and +128.3.112.35. +.Bd -literal +struct bpf_insn insns[] = { + BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), + BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 8), + BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 26), + BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 2), + BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30), + BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 3, 4), + BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 0, 3), + BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30), + BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 1), + BPF_STMT(BPF_RET+BPF_K, (u_int)-1), + BPF_STMT(BPF_RET+BPF_K, 0), +}; +.Ed +.Pp +Finally, this filter returns only TCP finger packets. +We must parse the IP header to reach the TCP header. +The +.Dv BPF_JSET +instruction +checks that the IP fragment offset is 0 so we are sure +that we have a TCP header. +.Bd -literal +struct bpf_insn insns[] = { + BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), + BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 10), + BPF_STMT(BPF_LD+BPF_B+BPF_ABS, 23), + BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, IPPROTO_TCP, 0, 8), + BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20), + BPF_JUMP(BPF_JMP+BPF_JSET+BPF_K, 0x1fff, 6, 0), + BPF_STMT(BPF_LDX+BPF_B+BPF_MSH, 14), + BPF_STMT(BPF_LD+BPF_H+BPF_IND, 14), + BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 2, 0), + BPF_STMT(BPF_LD+BPF_H+BPF_IND, 16), + BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 0, 1), + BPF_STMT(BPF_RET+BPF_K, (u_int)-1), + BPF_STMT(BPF_RET+BPF_K, 0), +}; +.Ed +.Sh SEE ALSO +.Xr tcpdump 1 , +.Xr ioctl 2 , +.Xr kqueue 2 , +.Xr poll 2 , +.Xr select 2 , +.Xr ng_bpf 4 , +.Xr bpf 9 +.Rs +.%A McCanne, S. +.%A Jacobson V. +.%T "An efficient, extensible, and portable network monitor" +.Re +.Sh HISTORY +The Enet packet filter was created in 1980 by Mike Accetta and +Rick Rashid at Carnegie-Mellon University. +Jeffrey Mogul, at +Stanford, ported the code to +.Bx +and continued its development from +1983 on. +Since then, it has evolved into the Ultrix Packet Filter at +.Tn DEC , +a +.Tn STREAMS +.Tn NIT +module under +.Tn SunOS 4.1 , +and +.Tn BPF . +.Sh AUTHORS +.An -nosplit +.An Steven McCanne , +of Lawrence Berkeley Laboratory, implemented BPF in +Summer 1990. +Much of the design is due to +.An Van Jacobson . +.Pp +Support for zero-copy buffers was added by +.An Robert N. M. Watson +under contract to Seccuris Inc. +.Sh BUGS +The read buffer must be of a fixed size (returned by the +.Dv BIOCGBLEN +ioctl). +.Pp +A file that does not request promiscuous mode may receive promiscuously +received packets as a side effect of another file requesting this +mode on the same hardware interface. +This could be fixed in the kernel with additional processing overhead. +However, we favor the model where +all files must assume that the interface is promiscuous, and if +so desired, must utilize a filter to reject foreign packets. +.Pp +The +.Dv SEESENT , +.Dv DIRECTION , +and +.Dv FEEDBACK +settings have been observed to work incorrectly on some interface +types, including those with hardware loopback rather than software loopback, +and point-to-point interfaces. +They appear to function correctly on a +broad range of Ethernet-style interfaces. diff --git a/static/freebsd/man4/bridge.4 b/static/freebsd/man4/bridge.4 new file mode 100644 index 00000000..3af95225 --- /dev/null +++ b/static/freebsd/man4/bridge.4 @@ -0,0 +1,743 @@ +.\" +.\" SPDX-License-Identifier: BSD-4-Clause +.\" +.\" $NetBSD: bridge.4,v 1.5 2004/01/31 20:14:11 jdc Exp $ +.\" +.\" Copyright 2001 Wasabi Systems, Inc. +.\" All rights reserved. +.\" +.\" Written by Jason R. Thorpe for Wasabi Systems, Inc. +.\" +.\" 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 for the NetBSD Project by +.\" Wasabi Systems, Inc. +.\" 4. The name of Wasabi Systems, Inc. may not be used to endorse +.\" or promote products derived from this software without specific prior +.\" written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``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 WASABI SYSTEMS, INC +.\" 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 October 13, 2025 +.Dt IF_BRIDGE 4 +.Os +.Sh NAME +.Nm if_bridge +.Nd network bridge device +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device if_bridge" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_bridge_load="YES" +bridgestp_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver creates a logical link between two or more IEEE 802 networks +that use the same (or +.Dq "similar enough" ) +framing format. +For example, it is possible to bridge Ethernet and 802.11 networks together, +but it is not possible to bridge Ethernet and Token Ring together. +.Pp +Each +.Nm +interface is created at runtime using interface cloning. +This is +most easily done with the +.Xr ifconfig 8 +.Cm create +command or using the +.Va cloned_interfaces +variable in +.Xr rc.conf 5 . +.Pp +When it is created, the +.Nm +interface gets assigned a link (MAC) address in the range of universally +administered addresses reserved for the FreeBSD Foundation by hashing +the host UUID, jail name, and the interface name. +If this fails, a random, locally administered address is generated instead. +This address is guaranteed to be unique +.Em only +across all +.Nm +interfaces on the local machine. +Thus you can theoretically have two bridges on different machines with +the same link addresses. +The address can be changed by assigning the desired link address using +.Xr ifconfig 8 . +.Pp +If +.Xr sysctl 8 +node +.Va net.link.bridge.inherit_mac +has a non-zero value, the newly created bridge will inherit the MAC +address from its first member instead of choosing a random link-level +address. +This will provide more predictable bridge MAC addresses without any +additional configuration, but currently this feature is known to break +some L2 protocols, for example PPPoE that is provided by +.Xr ng_pppoe 4 +and +.Xr ppp 8 . +Currently this feature is considered as experimental and is turned off +by default. +.Pp +A bridge can be used to provide several services, such as a simple +802.11-to-Ethernet bridge for wireless hosts, or traffic isolation. +.Pp +A bridge works like a switch, forwarding traffic from one interface +to another. +Multicast and broadcast packets are always forwarded to all +interfaces that are part of the bridge. +For unicast traffic, the bridge learns which MAC addresses are associated +with which interfaces and will forward the traffic selectively. +.Pp +By default the bridge logs MAC address port flapping to +.Xr syslog 3 . +This behavior can be disabled by setting the +.Xr sysctl 8 +variable +.Va net.link.bridge.log_mac_flap +to +.Li 0 . +.Pp +All the bridged member interfaces need to be up +in order to pass network traffic. +These can be enabled using +.Xr ifconfig 8 +or +.Va ifconfig_ Ns Ao Ar interface Ac Ns Li ="up" +in +.Xr rc.conf 5 . +.Pp +The MTU of the first member interface to be added is used as the bridge MTU. +All additional members will have their MTU changed to match. +If the MTU of a bridge is changed after its creation, the MTU of all member +interfaces is also changed to match. +.Pp +The TOE, TSO, TXCSUM and TXCSUM6 capabilities on all interfaces added to the +bridge are disabled if any of the interfaces do not support/enable them. +The LRO capability is always disabled. +All the capabilities are restored when the interface is removed from the bridge. +Changing capabilities at run-time may cause NIC reinit and a link flap. +.Pp +The bridge supports +.Dq monitor mode , +where the packets are discarded after +.Xr bpf 4 +processing, and are not processed or forwarded further. +This can be used to multiplex the input of two or more interfaces into a single +.Xr bpf 4 +stream. +This is useful for reconstructing the traffic for network taps +that transmit the RX/TX signals out through two separate interfaces. +.Pp +To allow the host to communicate with bridge members, IP addresses +should be assigned to the +.Nm +interface itself, not to the bridge's member interfaces. +Attempting to assign an IP address to a bridge member interface, or add +a member interface with an assigned IP address to a bridge, will return +an +.Dv EINVAL +.Dq ( "Invalid argument" ) +error. +For compatibility with older releases where this was permitted, setting +the +.Xr sysctl 8 +variable +.Va net.link.bridge.member_ifaddrs +to 1 will permit this configuration. +This sysctl variable will be removed in +.Fx 16.0. +.Sh IPV6 SUPPORT +.Nm +supports the +.Li AF_INET6 +address family on bridge interfaces. +The following +.Xr rc.conf 5 +variable configures an IPv6 link-local address on +.Li bridge0 +interface: +.Bd -literal -offset indent +ifconfig_bridge0_ipv6="inet6 auto_linklocal" +.Ed +.Pp +However, the +.Li AF_INET6 +address family has a concept of scope zone. +Bridging multiple interfaces changes the zone configuration because +multiple links are merged to each other and form a new single link +while the member interfaces still work individually. +This means each member interface still has a separate link-local scope +zone and the +.Nm +interface has another single, +aggregated link-local scope zone at the same time. +This situation is clearly against the description +.Qq zones of the same scope cannot overlap +in Section 5, +RFC 4007. +Although it works in most cases, +it can cause some counterintuitive or undesirable behavior in some +edge cases when both, the +.Nm +interface and one of the member interfaces, have an IPv6 address +and applications use both of them. +.Pp +To prevent this situation, +.Nm +checks whether a link-local scoped IPv6 address is configured on +a member interface to be added and the +.Nm +interface. +When the +.Nm +interface has IPv6 addresses, +IPv6 addresses on the member interface will be automatically removed +before the interface is added. +.Pp +This behavior can be disabled by setting +.Xr sysctl 8 +variable +.Va net.link.bridge.allow_llz_overlap +to +.Li 1 . +.Pp +Note that +.Li ACCEPT_RTADV +and +.Li AUTO_LINKLOCAL +interface flags are not enabled by default on +.Nm +interfaces even when +.Va net.inet6.ip6.accept_rtadv +and/or +.Va net.inet6.ip6.auto_linklocal +is set to +.Li 1 . +.Sh SPANNING TREE +The +.Nm +driver implements the Rapid Spanning Tree Protocol (RSTP or 802.1w) with +backwards compatibility with the legacy Spanning Tree Protocol (STP). +Spanning Tree is used to detect and remove loops in a network topology. +.Pp +RSTP provides faster spanning tree convergence than legacy STP, the protocol +will exchange information with neighbouring switches to quickly transition to +forwarding without creating loops. +.Pp +The code will default to RSTP mode but will downgrade any port connected to a +legacy STP network so is fully backward compatible. +A bridge can be forced to operate in STP mode without rapid state transitions +via the +.Va proto +command in +.Xr ifconfig 8 . +.Pp +The bridge can log STP port changes to +.Xr syslog 3 +by setting the +.Va net.link.bridge.log_stp +node using +.Xr sysctl 8 . +.Sh VLAN SUPPORT +Virtual LANs (VLANs), defined in the IEEE 802.1Q standard, allow traffic +on a bridge to be segregated into separate logical networks which cannot +communicate with each other. +For example, two interfaces in VLAN 10 would be able to communicate +with each other, but not with another interface in VLAN 20. +.Pp +Each VLAN is identified by a number between 1 and 4094 inclusive. +By default, all traffic on the bridge is assigned to "VLAN 0", +a pseudo-VLAN used for historical compatibility. +When VLANs are in use on a bridge, it is recommended to explicitly +assign all traffic to a VLAN rather than using VLAN 0. +.Pp +The bridge implements Independent VLAN Learning (IVL), meaning that +host addresses are learned separately for each VLAN, and the same host +address may exist on several different ports in different VLANs. +.Pp +If a +.Xr vlan 4 +interface is configured on an interface which is also an +.Nm +member interface, all tagged frames will be processed by the +.Xr vlan 4 +interface and will not be visible to the bridge. +This configuration is not recommended and may be unsupported in a +future release. +.Ss Tagged and untagged traffic +Incoming frames on a member interface may be either tagged or untagged. +Tagged frames contain an 802.1Q header indicating which VLAN the +frame belongs to, while untagged frames do not. +When a tagged frame is received, the frame is automatically assigned to +the VLAN in the tag (subject to any configured VLAN access list), +while untagged frames are assigned to the interface's configured +Port VLAN ID (PVID), or to VLAN 0 if no PVID is configured. +.Ss Assigning interfaces to VLANs +An interface's PVID may be configured using the +.Xr ifconfig 8 +.Cm ifuntagged +command: +.Bd -literal -offset indent +ifconfig bridge0 ifuntagged ix0 10 +.Ed +.Pp +Or by using the +.Cm untagged +option to +.Cm addm : +.Bd -literal -offset indent +ifconfig bridge0 addm ix0 untagged 10 +.Ed +.Pp +This will assign all untagged traffic received on the interface to the +specified VLAN, and any traffic transmitted on the interface in this +VLAN will have its VLAN tag (if present) removed. +Conversely, any traffic transmitted on the interface in a different +VLAN will have a tag added, to allow the remote system to assign the +traffic to the appropriate VLAN. +.Ss Host communication in a VLAN +Sometimes it is useful to allow the host itself to communicate in a VLAN, +for example to provide routing to other hosts in the VLAN. +To do this, create a +.Xr vlan 4 +interface on top of the +.Nm +interface with the appropriate VLAN tag. +For example, to allow the host to communicate in VLAN 10: +.Bd -literal -offset indent +ifconfig bridge0.10 create inet6 2001:db8::1/64 +.Ed +.Ss Configuring the VLAN access list (VLAN filtering) +For historical reasons, the default +.Nm +configuration allows all interfaces to send tagged traffic for any VLAN, +meaning that VLANs do not provide security separation. +To restrict which interfaces may communicate in which VLANs, +enable VLAN filtering on the bridge: +.Bd -literal -offset indent +ifconfig bridge0 vlanfilter +.Ed +.Pp +This has the following effects on bridge members: +.Bl -bullet -offset indent +.It +No untagged frames will be accepted from a member interface unless +the interface has a PVID configured. +.It +No tagged frames will be accepted from a member interface unless +the VLAN identifier is present in the interface's VLAN access list. +.It +Frames with stacked tags (Q-in-Q) will not be accepted from a +member interface unless the +.Cm qinq +option (see below) has been configured for that member. +.El +.Pp +To configure the VLAN access list, use the +.Xr ifconfig 8 +.Cm iftagged , +.Cm +iftagged +or +.Cm -iftagged +commands. +For example, to allow an interface to communicate in VLANs 10, 20, +and any VLAN from 100 to 199: +.Bd -literal -offset indent +ifconfig bridge0 iftagged ix0 10,20,100-199 +.Ed +.Ss IEEE 802.1ad (Q-in-Q) configuration +IEEE 802.1ad, also called Q-in-Q or +.Dq tag stacking , +allows a single Ethernet frame to contain multiple tags. +This allows one Ethernet network to transport traffic between endpoints +using its own VLAN tags without interfering with any pre-existing tags, +and is often used in service provider networks to provide +.Dq virtual wire +Ethernet services. +.Pp +When VLAN filtering is enabled, +.Nm +does not permit member interfaces to send Q-in-Q frames, because in +certain configuration this allows +.Dq VLAN-hopping +attacks on the bridge. +For example, consider a bridge with port ix0 configured as a tagged +port in VLAN 10, and port ix1 configured as untagged in VLAN 10 and +tagged in VLAN 20. +If ix0 is allowed to send Q-in-Q frames, then it can send a frame with +two tags: one for VLAN 10, followed by one for VLAN 20. +When the bridge forwards the frame to ix1, it will strip the VLAN tag +for VLAN 10, then forward the frame to ix1 with the tag for VLAN 20 +intact, effectively allowing ix1 to send traffic on VLAN 20 even +though the bridge configuration should not permit that. +.Pp +To permit an interface to send Q-in-Q frames, set the +.Xr ifconfig 8 +.Cm qinq +flag on the interface. +This is only required on the interface which will send Q-in-Q frames, +not the interface receiving the frames. +.Pp +Alternatively, set the +.Cm defqinq +flag on the bridge itself to enable Q-in-Q for all newly-added +interfaces by default. +.Sh PACKET FILTERING +Packet filtering can be used with any firewall package that hooks in via the +.Xr pfil 9 +framework. +When filtering is enabled, bridged packets will pass through the filter +inbound on the originating interface, on the bridge interface and outbound on +the appropriate interfaces. +Either stage can be disabled. +The filtering behavior can be controlled using +.Xr sysctl 8 : +.Bl -tag -width indent +.It Va net.link.bridge.pfil_onlyip +Controls the handling of non-IP packets which are not passed to +.Xr pfil 9 . +Set to +.Li 1 +to only allow IP packets to pass (subject to firewall rules), set to +.Li 0 +to unconditionally pass all non-IP Ethernet frames. +.It Va net.link.bridge.pfil_member +Set to +.Li 1 +to enable filtering on the incoming and outgoing member interfaces, set +to +.Li 0 +to disable it. +.It Va net.link.bridge.pfil_bridge +Set to +.Li 1 +to enable filtering on the bridge interface, set +to +.Li 0 +to disable it. +.It Va net.link.bridge.pfil_local_phys +Set to +.Li 1 +to additionally filter on the physical interface for locally destined packets. +Set to +.Li 0 +to disable this feature. +.It Va net.link.bridge.ipfw +Set to +.Li 1 +to enable layer2 filtering with +.Xr ipfirewall 4 , +set to +.Li 0 +to disable it. +This needs to be enabled for +.Xr dummynet 4 +support. +When +.Va ipfw +is enabled, +.Va pfil_bridge +and +.Va pfil_member +will be disabled so that IPFW +is not run twice; these can be re-enabled if desired. +.It Va net.link.bridge.ipfw_arp +Set to +.Li 1 +to enable layer2 ARP filtering with +.Xr ipfirewall 4 , +set to +.Li 0 +to disable it. +Requires +.Va ipfw +to be enabled. +.El +.Pp +ARP and REVARP packets are forwarded without being filtered and others +that are not IP nor IPv6 packets are not forwarded when +.Va pfil_onlyip +is enabled. +IPFW can filter Ethernet types using +.Cm mac-type +so all packets are passed to +the filter for processing. +.Pp +The packets originating from the bridging host will be seen by +the filter on the interface that is looked up in the routing +table. +.Pp +The packets destined to the bridging host will be seen by the filter +on the interface with the MAC address equal to the packet's destination +MAC. +There are situations when some of the bridge members are sharing +the same MAC address (for example the +.Xr vlan 4 +interfaces: they are currently sharing the +MAC address of the parent physical interface). +It is not possible to distinguish between these interfaces using +their MAC address, excluding the case when the packet's destination +MAC address is equal to the MAC address of the interface on which +the packet was entered to the system. +In this case the filter will see the incoming packet on this +interface. +In all other cases the interface seen by the packet filter is chosen +from the list of bridge members with the same MAC address and the +result strongly depends on the member addition sequence and the +actual implementation of +.Nm . +It is not recommended to rely on the order chosen by the current +.Nm +implementation since it may change in the future. +.Pp +The previous paragraph is best illustrated with the following +pictures. +Let +.Bl -bullet +.It +the MAC address of the incoming packet's destination is +.Nm nn:nn:nn:nn:nn:nn , +.It +the interface on which packet entered the system is +.Nm ifX , +.It +.Nm ifX +MAC address is +.Nm xx:xx:xx:xx:xx:xx , +.It +there are possibly other bridge members with the same MAC address +.Nm xx:xx:xx:xx:xx:xx , +.It +the bridge has more than one interface that are sharing the +same MAC address +.Nm yy:yy:yy:yy:yy:yy ; +we will call them +.Nm vlanY1 , +.Nm vlanY2 , +etc. +.El +.Pp +If the MAC address +.Nm nn:nn:nn:nn:nn:nn +is equal to +.Nm xx:xx:xx:xx:xx:xx +the filter will see the packet on interface +.Nm ifX +no matter if there are any other bridge members carrying the same +MAC address. +But if the MAC address +.Nm nn:nn:nn:nn:nn:nn +is equal to +.Nm yy:yy:yy:yy:yy:yy +then the interface that will be seen by the filter is one of the +.Nm vlanYn . +It is not possible to predict the name of the actual interface +without the knowledge of the system state and the +.Nm +implementation details. +.Pp +This problem arises for any bridge members that are sharing the same +MAC address, not only to the +.Xr vlan 4 +ones: they were taken just as an example of such a situation. +So if one wants to filter the locally destined packets based on +their interface name, one should be aware of this implication. +The described situation will appear at least on the filtering bridges +that are doing IP-forwarding; in some of such cases it is better +to assign the IP address only to the +.Nm +interface and not to the bridge members. +Enabling +.Va net.link.bridge.pfil_local_phys +will let you do the additional filtering on the physical interface. +.Sh NETMAP +.Xr netmap 4 +applications may open a bridge interface in emulated mode. +The netmap application will receive all packets which arrive from member +interfaces. +In particular, packets which would otherwise be forwarded to another +member interface will be received by the netmap application. +.Pp +When the +.Xr netmap 4 +application transmits a packet to the host stack via the bridge interface, +.Nm +receive it and attempts to determine its +.Ql source +interface by looking up the source MAC address in the interface's learning +tables. +Packets for which no matching source interface is found are dropped and the +input error counter is incremented. +If a matching source interface is found, +.Nm +treats the packet as though it was received from the corresponding interface +and handles it normally without passing the packet back to +.Xr netmap 4 . +.Sh EXAMPLES +The following when placed in the file +.Pa /etc/rc.conf +will cause a bridge called +.Dq Li bridge0 +to be created, and will add the interfaces +.Dq Li wlan0 +and +.Dq Li fxp0 +to the bridge, and then enable packet forwarding. +Such a configuration could be used to implement a simple +802.11-to-Ethernet bridge (assuming the 802.11 interface is +in ad-hoc mode). +.Bd -literal -offset indent +cloned_interfaces="bridge0" +ifconfig_bridge0="addm wlan0 addm fxp0 up" +.Ed +.Pp +For the bridge to forward packets, +all member interfaces and the bridge need to be up. +The above example would also require: +.Bd -literal -offset indent +create_args_wlan0="wlanmode hostap" +ifconfig_wlan0="up ssid my_ap mode 11g" +ifconfig_fxp0="up" +.Ed +.Pp +The following will cause a bridge to be created with two VLANs, +10 and 20, where the +.Dq Li em +interfaces can only communicate in their assigned VLANs, +while +.Dq Li ix0 +is a trunk port which can communicate in either VLAN: +.Bd -literal -offset indent +cloned_interfaces="bridge0" +ifconfig_bridge0="vlanfilter \e + addm em0 untagged 10 \e + addm em1 untagged 10 \e + addm em2 untagged 20 \e + addm em3 untagged 20 \e + addm ix0 tagged 10,20" +ifconfig_em0="up" +ifconfig_em1="up" +ifconfig_em2="up" +ifconfig_em3="up" +ifconfig_ix0="up" +.Ed +.Pp +The previous example could be extended to allow the host to +communicate in VLANs 10 and 20: +.Bd -literal -offset indent +vlans_bridge0="10 20" +ifconfig_bridge0_10_ipv6="inet6 2001:db8:0:10::1/64" +ifconfig_bridge0_20_ipv6="inet6 2001:db8:0:20::1/64" +.Ed +.Pp +Consider a system with two 4-port Ethernet boards. +The following will cause a bridge consisting of all 8 ports with +Rapid Spanning Tree enabled to be created: +.Bd -literal -offset indent +ifconfig bridge0 create +ifconfig bridge0 \e + addm fxp0 stp fxp0 \e + addm fxp1 stp fxp1 \e + addm fxp2 stp fxp2 \e + addm fxp3 stp fxp3 \e + addm fxp4 stp fxp4 \e + addm fxp5 stp fxp5 \e + addm fxp6 stp fxp6 \e + addm fxp7 stp fxp7 \e + up +.Ed +.Pp +The bridge can be used as a regular host interface at the same time as bridging +between its member ports. +In this example, the bridge connects em0 and em1, and will receive its IP +address through DHCP: +.Bd -literal -offset indent +cloned_interfaces="bridge0" +ifconfig_bridge0="addm em0 addm em1 DHCP" +ifconfig_em0="up" +ifconfig_em1="up" +.Ed +.Pp +The bridge can tunnel Ethernet across an IP internet using the EtherIP +protocol. +This can be combined with +.Xr ipsec 4 +to provide an encrypted connection. +Create a +.Xr gif 4 +interface and set the local and remote IP addresses for the +tunnel, these are reversed on the remote bridge. +.Bd -literal -offset indent +ifconfig gif0 create +ifconfig gif0 tunnel 1.2.3.4 5.6.7.8 up +ifconfig bridge0 create +ifconfig bridge0 addm fxp0 addm gif0 up +.Ed +.Sh SEE ALSO +.Xr gif 4 , +.Xr ipf 4 , +.Xr ipfw 4 , +.Xr netmap 4 , +.Xr pf 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 6.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm bridge +driver was originally written by +.An Jason L. Wright Aq Mt jason@thought.net +as part of an undergraduate independent study at the University of +North Carolina at Greensboro. +.Pp +This version of the +.Nm +driver has been heavily modified from the original version by +.An Jason R. Thorpe Aq Mt thorpej@wasabisystems.com . +.Pp +Rapid Spanning Tree Protocol (RSTP) support was added by +.An Andrew Thompson Aq Mt thompsa@FreeBSD.org . +.Sh BUGS +The +.Nm +driver currently supports only Ethernet and Ethernet-like (e.g., 802.11) +network devices, which can be configured with the same MTU size as the bridge +device. diff --git a/static/freebsd/man4/bwi.4 b/static/freebsd/man4/bwi.4 new file mode 100644 index 00000000..81e8ef12 --- /dev/null +++ b/static/freebsd/man4/bwi.4 @@ -0,0 +1,149 @@ +.\" Copyright (c) 2009 Christian Brueffer +.\" 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 August 7, 2015 +.Dt BWI 4 +.Os +.Sh NAME +.Nm bwi +.Nd Broadcom BCM43xx IEEE 802.11b/g wireless network driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device bwi" +.Cd "device wlan" +.Cd "device wlan_amrr" +.Cd "device firmware" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_bwi_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for Broadcom BCM43xx based +PCI/CardBus network adapters. +.Pp +It supports +.Cm station +and +.Cm monitor +mode operation. +Only one virtual interface may be configured at any time. +For more information on configuring this device, see +.Xr ifconfig 8 . +.Pp +This driver requires firmware to be loaded before it will work. +The +.Pa ports/net/bwi-firmware-kmod +port needs to be installed before +.Xr ifconfig 8 +will work. +.Sh HARDWARE +The +.Nm +driver supports Broadcom BCM43xx based wireless devices, including: +.Bl -column "Apple Airport Extreme" "BCM4306" "Mini PCI" "a/b/g" -offset 6n +.It Em "Card" Ta Em "Chip" Ta Em "Bus" Ta Em "Standard" +.It "Apple Airport Extreme BCM4306 PCI b/g" +.It "Apple Airport Extreme BCM4318 PCI b/g" +.It "ASUS WL-100g BCM4306 CardBus b/g" +.It "ASUS WL-138g BCM4318 PCI b/g" +.It "Buffalo WLI-CB-G54S BCM4318 CardBus b/g" +.It "Buffalo WLI-PCI-G54S BCM4306 PCI b/g" +.It "Compaq R4035 onboard BCM4306 PCI b/g" +.It "Dell Wireless 1390 BCM4311 Mini PCI b/g" +.It "Dell Wireless 1470 BCM4318 Mini PCI b/g" +.It "Dell Truemobile 1300 r2 BCM4306 Mini PCI b/g" +.It "Dell Truemobile 1400 BCM4309 Mini PCI b/g" +.It "HP nx6125 BCM4319 PCI b/g" +.It "Linksys WPC54G Ver 3 BCM4318 CardBus b/g" +.It "Linksys WPC54GS Ver 2 BCM4318 CardBus b/g" +.It "TRENDnet TEW-401PCplus BCM4306 CardBus b/g" +.It "US Robotics 5411 BCM4318 CardBus b/g" +.El +.Pp +The +.Nm +driver uses the older v3 version of Broadcom's firmware. +While this older firmware does support most BCM43xx parts, the +.Xr bwn 4 +driver works better for the newer chips it supports. +You must use the +.Nm +driver if you are using older Broadcom chipsets (BCM4301, BCM4303 and +BCM4306 rev 2). +The v4 version of the firmware that +.Xr bwn 4 +uses does not support these chips. +.Sh EXAMPLES +Join an existing BSS network (i.e., connect to an access point): +.Bd -literal -offset indent +ifconfig wlan create wlandev bwi0 inet 192.168.0.20 \e + netmask 0xffffff00 +.Ed +.Pp +Join a specific BSS network with network name +.Dq Li my_net : +.Pp +.Dl "ifconfig wlan create wlandev bwi0 ssid my_net up" +.Pp +Join a specific BSS network with 64-bit WEP encryption: +.Bd -literal -offset indent +ifconfig wlan create wlandev bwi0 ssid my_net \e + wepmode on wepkey 0x1234567890 weptxkey 1 up +.Ed +.Sh SEE ALSO +.Xr arp 4 , +.Xr cardbus 4 , +.Xr intro 4 , +.Xr pci 4 , +.Xr wlan 4 , +.Xr wlan_amrr 4 , +.Xr ifconfig 8 , +.Xr wpa_supplicant 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 8.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written for +.Dx +by +.An Sepherosa Ziehau +and subsequently ported to +.Fx . +.Sh BUGS +Some card based on the BCM4306 and BCM4309 chips do not work properly +on channel 1, 2 and 3. diff --git a/static/freebsd/man4/bwn.4 b/static/freebsd/man4/bwn.4 new file mode 100644 index 00000000..a602dea5 --- /dev/null +++ b/static/freebsd/man4/bwn.4 @@ -0,0 +1,169 @@ +.\" Copyright (c) 2009 Christian Brueffer +.\" 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 December 16, 2017 +.Dt BWN 4 +.Os +.Sh NAME +.Nm bwn +.Nd Broadcom BCM43xx SoftMAC IEEE 802.11 wireless network driver +.Sh SYNOPSIS +To compile this driver into the kernel, add the following lines to the kernel +configuration file: +.Bd -ragged -offset indent +.Cd "device bwn" +.Cd "device bhnd" +.Cd "device bhndb" +.Cd "device bhndb_pci" +.Cd "device bcma" +.Cd "device siba" +.Cd "device gpio" +.Cd "device wlan" +.Cd "device wlan_amrr" +.Cd "device firmware" +.Ed +.Pp +To load the driver as a module at boot, add the following lines to +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_bwn_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for Broadcom BCM43xx based +PCI/CardBus network adapters. +.Pp +It supports +.Cm station +and +.Cm monitor +mode operation. +Only one virtual interface may be configured at any time. +For more information on configuring this device, see +.Xr ifconfig 8 . +.Pp +This driver requires firmware to be loaded before it will work. +The +.Pa ports/net/bwn-firmware-kmod +port needs to be installed before +.Xr ifconfig 8 +will work. +In most cases the +.Pa bwn_v4_ucode +kernel module from the port should be used. +However, if an LP (low power) PHY is being used, the +.Pa bwn_v4_lp_ucode +module should be used. +.Sh HARDWARE +The +.Nm +driver supports Broadcom BCM43xx based wireless devices, including: +.Bl -column "Apple Airport Extreme" "BCM4306" "Mini PCI" "a/b/g" +.It Em "Card" Ta Em "Chip" Ta Em "Bus" Ta Em "Standard" +.It "Apple Airport Extreme BCM4318 PCI b/g" +.It "ASUS WL-138g BCM4318 PCI b/g" +.It "Buffalo WLI-CB-G54S BCM4318 CardBus b/g" +.It "Dell Wireless 1390 BCM4311 Mini PCI b/g" +.It "Dell Wireless 1470 BCM4318 Mini PCI b/g" +.It "Dell Truemobile 1400 BCM4309 Mini PCI b/g" +.It "HP Compaq 6715b BCM4312 PCI b/g" +.It "HP nx6125 BCM4319 PCI b/g" +.It "Linksys WPC54G Ver 3 BCM4318 CardBus b/g" +.It "Linksys WPC54GS Ver 2 BCM4318 CardBus b/g" +.It "US Robotics 5411 BCM4318 CardBus b/g" +.El +.Pp +Users of older Broadcom chipsets (BCM4301, BCM4303 and BCM4306 rev 2) +must use +.Xr bwi 4 +because the v4 version of the firmware does not support these chips. +The newer firmware is too big to fit into these old chips. +.Sh EXAMPLES +Join an existing BSS network (i.e., connect to an access point): +.Bd -literal -offset indent +ifconfig wlan create wlandev bwn0 inet 192.168.0.20 \e + netmask 0xffffff00 +.Ed +.Pp +Join a specific BSS network with network name +.Dq Li my_net : +.Pp +.Dl "ifconfig wlan create wlandev bwn0 ssid my_net up" +.Pp +Join a specific BSS network with 64-bit WEP encryption: +.Bd -literal -offset indent +ifconfig wlan create wlandev bwn0 ssid my_net \e + wepmode on wepkey 0x1234567890 weptxkey 1 up +.Ed +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width indent +.It Va hw.bwn.usedma +This tunable enables DMA operations on the hardware. +If the value is 0, PIO mode would be used. +The default value is 1. +.El +.Sh SEE ALSO +.Xr arp 4 , +.Xr bcma 4 , +.Xr bhnd 4 , +.Xr bhndb 4 , +.Xr bwi 4 , +.Xr cardbus 4 , +.Xr intro 4 , +.Xr pci 4 , +.Xr siba 4 , +.Xr wlan 4 , +.Xr wlan_amrr 4 , +.Xr ifconfig 8 , +.Xr wpa_supplicant 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 8.1 . +The driver was updated to support the common Broadcom +.Xr bhnd 4 +bus interface in +.Fx 12.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Weongyo Jeong Aq Mt weongyo@FreeBSD.org . +Support for +.Xr bhnd 4 +was added by +.An Landon Fuller Aq Mt landonf@FreeBSD.org . +.\".Sh BUGS +.\"Some card based on the BCM4306 and BCM4309 chips do not work properly +.\"on channel 1, 2 and 3. +.Sh CAVEATS +Some LP PHY devices have DMA operation problems that in that case try to +use PIO mode. diff --git a/static/freebsd/man4/bxe.4 b/static/freebsd/man4/bxe.4 new file mode 100644 index 00000000..c82565e1 --- /dev/null +++ b/static/freebsd/man4/bxe.4 @@ -0,0 +1,342 @@ +.\" Copyright (c) 2014 Qlogic Corporation. 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 COPYRIGHT HOLDERS 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 COPYRIGHT OWNER OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF +.\" THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 29, 2012 +.Dt BXE 4 +.Os +.Sh NAME +.Nm bxe +.Nd QLogic NetXtreme II Ethernet 10Gb PCIe adapter driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device bxe" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the +following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_bxe_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for PCIe 10Gb Ethernet adapters based on the QLogic +NetXtreme II family of 10Gb chips. +The driver supports Jumbo Frames, VLAN +tagging, checksum offload (IPv4, TCP, UDP, IPv6-TCP, IPv6-UDP), MSI-X +interrupts, TCP Segmentation Offload (TSO), Large Receive Offload (LRO), and +Receive Side Scaling (RSS). +.Sh HARDWARE +The +.Nm +driver provides support for various NICs based on the QLogic NetXtreme II +family of 10Gb Ethernet controller chips, including the following: +.Pp +.Bl -bullet -compact +.It +QLogic NetXtreme II BCM57710 10Gb +.It +QLogic NetXtreme II BCM57711 10Gb +.It +QLogic NetXtreme II BCM57711E 10Gb +.It +QLogic NetXtreme II BCM57712 10Gb +.It +QLogic NetXtreme II BCM57712-MF 10Gb +.It +QLogic NetXtreme II BCM57800 10Gb +.It +QLogic NetXtreme II BCM57800-MF 10Gb +.It +QLogic NetXtreme II BCM57810 10Gb +.It +QLogic NetXtreme II BCM57810-MF 10Gb +.It +QLogic NetXtreme II BCM57840 10Gb / 20Gb +.It +QLogic NetXtreme II BCM57840-MF 10Gb +.El +.Sh CONFIGURATION +There a number of configuration parameters that can be set to tweak the +driver's behavior. +These parameters can be set via the +.Xr loader.conf 5 +file to take effect during the next system boot. +The following parameters affect +ALL instances of the driver. +.Bl -tag -width indent +.It Va hw.bxe.debug +DEFAULT = 0 +.br +Sets the default logging level of the driver. +See the Diagnostics and Debugging +section below for more details. +.It Va hw.bxe.interrupt_mode +DEFAULT = 2 +.br +Sets the default interrupt mode: 0=IRQ, 1=MSI, 2=MSIX. +If set to MSIX and +allocation fails, the driver will roll back and attempt MSI allocation. +If MSI +allocation fails, the driver will roll back and attempt fixed level IRQ +allocation. +If IRQ allocation fails, then the driver load fails. +With MSI/MSIX, +the driver attempts to allocate a vector for each queue in addition to one more +for default processing. +.It Va hw.bxe.queue_count +DEFAULT = 4 +.br +Sets the default number of fast path packet processing queues. +Note that one +MSI/MSIX interrupt vector is allocated per-queue. +.It Va hw.bxe.max_rx_bufs +DEFAULT = 0 +.br +Sets the maximum number of receive buffers to allocate per-queue. +Zero(0) means +to allocate a receive buffer for every buffer descriptor. +By default this +equates to 4080 buffers per-queue which is the maximum value for this config +parameter. +.It Va hw.bxe.hc_rx_ticks +DEFAULT = 25 +.br +Sets the number of ticks for host interrupt coalescing in the receive path. +.It Va hw.bxe.hc_tx_ticks +DEFAULT = 50 +.br +Sets the number of ticks for host interrupt coalescing in the transmit path. +.It Va hw.bxe.rx_budget +DEFAULT = 0xffffffff +.br +Sets the maximum number of receive packets to process in an interrupt. +If the +budget is reached then the remaining/pending packets will be processed in a +scheduled taskqueue. +.It Va hw.bxe.max_aggregation_size +DEFAULT = 32768 +.br +Sets the maximum LRO aggregation byte size. +The higher the value the more +packets the hardware will aggregate. +Maximum is 65K. +.It Va hw.bxe.mrrs +DEFAULT = -1 +.br +Sets the PCI MRRS: -1=Auto, 0=128B, 1=256B, 2=512B, 3=1KB +.It Va hw.bxe.autogreeen +DEFAULT = 0 +.br +Set AutoGrEEEN: 0=HW_DEFAULT, 1=FORCE_ON, 2=FORCE_OFF +.It Va hw.bxe.udp_rss +DEFAULT = 0 +.br +Enable/Disable 4-tuple RSS for UDP: 0=DISABLED, 1=ENABLED +.El +.Pp +Special care must be taken when modifying the number of queues and receive +buffers. +.Fx imposes a limit on the maximum number of +.Xr mbuf 9 +allocations. +If buffer allocations fail, the interface initialization will fail +and the interface will not be usable. +The driver does not make a best effort +for buffer allocations. +It is an all or nothing effort. +.Pp +You can tweak the +.Xr mbuf 9 +allocation limit using +.Xr sysctl 8 +and view the current usage with +.Xr netstat 1 +as follows: +.Bd -literal -offset indent +# netstat -m +# sysctl kern.ipc.nmbclusters +# sysctl kern.ipc.nmbclusters=<#> +.Ed +.Pp +There are additional configuration parameters that can be set on a per-instance +basis to dynamically override the default configuration. +The '#' below must be +replaced with the driver instance / interface unit number: +.Bl -tag -width indent +.It Va dev.bxe.#.debug +DEFAULT = 0 +.br +Sets the default logging level of the driver instance. +See +.Va hw.bxe.debug +above and +the Diagnostics and Debugging section below for more details. +.It Va dev.bxe.#.rx_budget +DEFAULT = 0xffffffff +.br +Sets the maximum number of receive packets to process in an interrupt for the +driver instance. +See +.Va hw.bxe.rx_budget +above for more details. +.El +.Pp +Additional items can be configured using +.Xr ifconfig 8 : +.Bl -tag -width indent +.It Va MTU - Maximum Transmission Unit +DEFAULT = 1500 +.br +RANGE = 46-9184 +.br +# ifconfig bxe# mtu +.It Va Promiscuous Mode +DEFAULT = OFF +.br +# ifconfig bxe# [ promisc | -promisc ] +.It Va Rx/Tx Checksum Offload +DEFAULT = RX/TX CSUM ON +.br +Note that the Rx and Tx settings are not independent. +.br +# ifconfig bxe# [ rxcsum | -rxcsum | txcsum | -txcsum ] +.It Va TSO - TCP Segmentation Offload +DEFAULT = ON +.br +# ifconfig bxe# [ tso | -tso | tso6 | -tso6 ] +.It Va LRO - TCP Large Receive Offload +DEFAULT = ON +.br +# ifconfig bxe# [ lro | -lro ] +.El +.Sh DIAGNOSTICS AND DEBUGGING +There are many statistics exposed by +.Nm +via +.Xr sysctl 8 . +.Pp +To dump the default driver configuration: +.Bd -literal -offset indent +# sysctl -a | grep hw.bxe +.Ed +.Pp +To dump every instance's configuration and detailed statistics: +.Bd -literal -offset indent +# sysctl -a | grep dev.bxe +.Ed +.Pp +To dump information for a single instance (replace the '#' with the driver +instance / interface unit number): +.Bd -literal -offset indent +# sysctl -a | grep dev.bxe.# +.Ed +.Pp +To dump information for all the queues of a single instance: +.Bd -literal -offset indent +# sysctl -a | grep dev.bxe.#.queue +.Ed +.Pp +To dump information for a single queue of a single instance (replace the +additional '#' with the queue number): +.Bd -literal -offset indent +# sysctl -a | grep dev.bxe.#.queue.# +.Ed +.Pp +The +.Nm +driver has the ability to dump a ton of debug messages to the system +log. +The default level of logging can be set with the +.Va hw.bxe.debug +.Xr sysctl 8 . +Take care with this setting as it can result in too +many logs being dumped. +Since this parameter is the default one, it affects +every instance and will dramatically change the timing in the driver. +A better +alternative to aid in debugging is to dynamically change the debug level of a +specific instance with the +.Va dev.bxe.#.debug +.Xr sysctl 8 . +This allows +you to turn on/off logging of various debug groups on-the-fly. +.Pp +The different debug groups that can be toggled are: +.Bd -literal -offset indent +DBG_LOAD 0x00000001 /* load and unload */ +DBG_INTR 0x00000002 /* interrupt handling */ +DBG_SP 0x00000004 /* slowpath handling */ +DBG_STATS 0x00000008 /* stats updates */ +DBG_TX 0x00000010 /* packet transmit */ +DBG_RX 0x00000020 /* packet receive */ +DBG_PHY 0x00000040 /* phy/link handling */ +DBG_IOCTL 0x00000080 /* ioctl handling */ +DBG_MBUF 0x00000100 /* dumping mbuf info */ +DBG_REGS 0x00000200 /* register access */ +DBG_LRO 0x00000400 /* lro processing */ +DBG_ASSERT 0x80000000 /* debug assert */ +DBG_ALL 0xFFFFFFFF /* flying monkeys */ +.Ed +.Pp +For example, to debug an issue in the receive path on bxe0: +.Bd -literal -offset indent +# sysctl dev.bxe.0.debug=0x22 +.Ed +.Pp +When finished turn the logging back off: +.Bd -literal -offset indent +# sysctl dev.bxe.0.debug=0 +.Ed +.Sh SUPPORT +For support questions please contact your QLogic approved reseller or +QLogic Technical Support at +.Pa http://support.qlogic.com , +or by E-mail at +.Aq Mt support@qlogic.com . +.Sh SEE ALSO +.Xr netstat 1 , +.Xr altq 4 , +.Xr arp 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 9.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Eric Davis Aq Mt edavis@broadcom.com , +.An David Christensen Aq Mt davidch@broadcom.com , +and +.An Gary Zambrano Aq Mt zambrano@broadcom.com . diff --git a/static/freebsd/man4/bytgpio.4 b/static/freebsd/man4/bytgpio.4 new file mode 100644 index 00000000..70501914 --- /dev/null +++ b/static/freebsd/man4/bytgpio.4 @@ -0,0 +1,53 @@ +.\" Copyright (c) 2016 +.\" Oleksandr Tymoshenko . 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 May 9, 2017 +.Dt BYTGPIO 4 +.Os +.Sh NAME +.Nm bytgpio +.Nd Intel Bay Trail SoC GPIO controller +.Sh SYNOPSIS +.Cd "device gpio" +.Cd "device bytgpio" +.Sh DESCRIPTION +The +.Nm +is a driver for GPIO controller that can be found in Intel's Bay Trail SoC family. +.Pp +Bay Trail SoC has three banks of GPIO pins exposed to userland as /dev/gpiocN, +where N is 0, 1, and 2. Pins in each bank are pre-named to match names +on boards schematics: GPIO_S0_SCnn, GPIO_S0_NCnn, and GPIO_S5_nn. +.Sh SEE ALSO +.Xr gpio 3 , +.Xr gpio 4 , +.Xr gpioctl 8 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 11.1 . +.Sh AUTHORS +This driver and man page was written by +.An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org . diff --git a/static/freebsd/man4/capsicum.4 b/static/freebsd/man4/capsicum.4 new file mode 100644 index 00000000..2c65ea27 --- /dev/null +++ b/static/freebsd/man4/capsicum.4 @@ -0,0 +1,199 @@ +.\" +.\" Copyright (c) 2011, 2013 Robert N. M. Watson +.\" Copyright (c) 2011 Jonathan Anderson +.\" 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 January 23, 2026 +.Dt CAPSICUM 4 +.Os +.Sh NAME +.Nm Capsicum +.Nd lightweight OS capability and sandbox framework +.Sh SYNOPSIS +.Cd "options CAPABILITY_MODE" +.Cd "options CAPABILITIES" +.Sh DESCRIPTION +.Nm +is a lightweight OS capability and sandbox framework implementing a hybrid +capability system model. +.Nm +is designed to blend capabilities with UNIX. +This approach achieves many of the benefits of least-privilege operation, while +preserving existing UNIX APIs and performance, and presents application authors +with an adoption path for capability-oriented design. +.Pp +Capabilities are unforgeable tokens of authority that can be delegated and must +be presented to perform an action. +.Nm +makes file descriptors into capabilities. +.Pp +.Nm +can be used for application and library compartmentalisation, the +decomposition of larger bodies of software into isolated (sandboxed) +components in order to implement security policies and limit the impact of +software vulnerabilities. +.Pp +.Nm +provides two core kernel primitives: +.Bl -tag -width indent +.It capability mode +A process mode, entered by invoking +.Xr cap_enter 2 , +in which access to global OS namespaces (such as the file system and PID +namespaces) is restricted; only explicitly delegated rights, referenced by +memory mappings or file descriptors, may be used. +Once set, the flag is inherited by future children processes, and may not be +cleared. +.Pp +Access to system calls in capability mode is restricted: some system calls +requiring global namespace access are unavailable, while others are +constrained. +For instance, +.Xr sysctl 2 +can be used to query process-local information such as address space layout, +but also to monitor a system's network connections. +.Xr sysctl 2 +is constrained by explicitly marking \(~~60 of over 15000 parameters as +permitted in capability mode; all others are denied. +.Pp +The system calls which require constraints are +.Xr sysctl 2 , +.Xr shm_open 2 +.Pq which is permitted to create anonymous memory objects but not named ones +and the +.Xr openat 2 +family of system calls. +The +.Xr openat 2 +calls already accept a file descriptor argument as the directory to perform the +.Xr open 2 , +.Xr rename 2 , +etc. relative to; in capability mode the +.Xr openat 2 +family of system calls are constrained so that they can only operate on +objects “under” the provided file descriptor. +.It capabilities +Limit operations that can be called on file descriptors. +For example, a file descriptor returned by +.Xr open 2 +may be refined using +.Xr cap_rights_limit 2 +so that only +.Xr read 2 +and +.Xr write 2 +can be called, but not +.Xr fchmod 2 . +The complete list of the capability rights can be found in the +.Xr rights 4 +manual page. +.El +.Pp +In some cases, +.Nm +requires use of alternatives to traditional POSIX APIs in order to name +objects using capabilities rather than global namespaces: +.Bl -tag -width indent +.It process descriptors +File descriptors representing processes, allowing parent processes to manage +child processes without requiring access to the PID namespace; described in +greater detail in +.Xr procdesc 4 . +.It anonymous shared memory +An extension to the POSIX shared memory API to support anonymous swap objects +associated with file descriptors; described in greater detail in +.Xr shm_open 2 . +.El +.Pp +In some cases, +.Nm +limits the valid values of some parameters to traditional APIs in order to +restrict access to global namespaces: +.Bl -tag -width indent +.It process IDs +Processes can only act upon their own process ID with syscalls such as +.Xr cpuset_setaffinity 2 . +.El +.Pp +.Fx +provides some additional functionality to support application sandboxing that +is not part of +.Nm +itself: +.Bl -tag -width indent +.It Xr capsicum_helpers 3 +A set of a inline functions which simplify modifying programs to use +.Nm . +.It Xr libcasper 3 +A library that provides services for sandboxed applications, such as operating +on files specified on a command line or establishing network connections. +.El +.Sh SEE ALSO +.Xr cap_enter 2 , +.Xr cap_fcntls_limit 2 , +.Xr cap_getmode 2 , +.Xr cap_ioctls_limit 2 , +.Xr cap_rights_limit 2 , +.Xr fchmod 2 , +.Xr open 2 , +.Xr pdfork 2 , +.Xr pdgetpid 2 , +.Xr pdkill 2 , +.Xr pdwait4 2 , +.Xr read 2 , +.Xr shm_open 2 , +.Xr write 2 , +.Xr cap_rights_get 3 , +.Xr capsicum_helpers 3 , +.Xr libcasper 3 , +.Xr procdesc 4 +.Sh HISTORY +.Nm +first appeared in +.Fx 9.0 , +and was developed at the University of Cambridge. +.Sh AUTHORS +.Nm +was developed by +.An -nosplit +.An Robert Watson Aq Mt rwatson@FreeBSD.org +and +.An Jonathan Anderson Aq Mt jonathan@FreeBSD.org +at the University of Cambridge, and +.An Ben Laurie Aq Mt benl@FreeBSD.org +and +.An Kris Kennaway Aq Mt kris@FreeBSD.org +at Google, Inc., and +.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net . +Portions of this manual page are drawn from +.Rs +.%A Robert N. M. Watson +.%A Jonathan Anderson +.%A Ben Laurie +.%A Kris Kennaway +.%T Capsicum: practical capabilities for UNIX +.%J USENIX Security Symposium +.%D August 2010 +.%O DOI: 10.5555/1929820.1929824 +.Re diff --git a/static/freebsd/man4/cardbus.4 b/static/freebsd/man4/cardbus.4 new file mode 100644 index 00000000..fa4bce65 --- /dev/null +++ b/static/freebsd/man4/cardbus.4 @@ -0,0 +1,55 @@ +.\" +.\" Copyright (c) 2002 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. 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 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 9, 2002 +.Dt CARDBUS 4 +.Os +.Sh NAME +.Nm cardbus +.Nd CardBus bus driver +.Sh SYNOPSIS +.Cd device cardbus +.Sh DESCRIPTION +The +.Nm +driver implements the CardBus bus. +The +.Nm +driver supports all cardbus bridges in the system. +.Sh TUNABLES +The driver supports the following tunable parameters, which may be +added to +.Pa /boot/loader.conf +or set via the +.Xr sysctl 8 +command: +.Bl -tag -width ".Cm hw.cardbus.cis_debug" -compact +.It Cm hw.cardbus.debug +Non-zero values cause more verbose information to be printed when a +32-bit CardBus card is inserted or removed. +.It Cm hw.cardbus.cis_debug +Non-zero value causes the CIS parsing of the 32-bit CardBus card to be +much more verbose and include a complete CIS dump. +.El +.Sh SEE ALSO +.Xr pccbb 4 diff --git a/static/freebsd/man4/carp.4 b/static/freebsd/man4/carp.4 new file mode 100644 index 00000000..4b0ece3b --- /dev/null +++ b/static/freebsd/man4/carp.4 @@ -0,0 +1,351 @@ +.\" $OpenBSD: carp.4,v 1.16 2004/12/07 23:41:35 jmc Exp $ +.\" +.\" Copyright (c) 2003, Ryan McBride. All rights reserved. +.\" Copyright (c) 2011, Gleb Smirnoff +.\" +.\" 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 PROJECT 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 PROJECT 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 March 11, 2026 +.Dt CARP 4 +.Os +.Sh NAME +.Nm carp +.Nd Common Address Redundancy Protocol +.Sh SYNOPSIS +.Cd "device carp" +.Sh DESCRIPTION +The CARP allows multiple hosts on the same local network to share a set of +IPv4 and/or IPv6 addresses. +Its primary purpose is to ensure that these +addresses are always available. +.Pp +To use +.Nm , +the administrator needs to configure at a minimum a common virtual host ID +(vhid), and attach at least one IP address to this vhid on each machine which +is to take part in the virtual group. +Additional parameters can also be set on a per-vhid basis: +.Cm advbase +and +.Cm advskew , +which are used to control how frequently the host sends advertisements when it +is the master for a virtual host, and +.Cm pass +which is used to authenticate +.Nm +advertisements. +The +.Cm advbase +parameter stands for +.Dq "advertisement base" . +It is measured in seconds and specifies the base of the advertisement interval. +The +.Cm advskew +parameter stands for +.Dq "advertisement skew" . +It is measured in 1/256 of seconds. +It is added to the base advertisement interval to make one host advertise +a bit slower that the other does. +Both +.Cm advbase +and +.Cm advskew +are put inside CARP advertisements. +These values can be configured using +.Xr ifconfig 8 . +.Pp +CARP defaults to using multicast messages, but can be configured to unicast +announcements to peers using the +.Cm peer +and +.Cm peer6 +parameters. Default addresses can be restored using +.Cm mcast +and +.Cm mcast6 . +Note that TTL verification is disabled if the peer address is not a multicast +address. +These values can be configured using +.Xr ifconfig 8 . +.Pp +.Xr carp 4 +can be configured to use either the non-standard CARP protocol, or VRRPv3 (RFC 5798). +Use the +.Cm carpver +parameter to select either 2 (CARP) or 3 (VRRPv3). +VRRPv3 specific parameters can be configured using the +.Cm vrrpprio +and +.Cm vrrpinterval +parameters. +.Pp +CARP virtual hosts can be configured on multicast-capable interfaces: Ethernet, +layer 2 VLAN, FDDI and Token Ring. +An arbitrary number of virtual host IDs can be configured on an interface. +An arbitrary number of IPv4 or IPv6 addresses can be attached to a particular +vhid. +It is important that all hosts participating in a vhid have the same list +of prefixes configured on the vhid, since all the prefixes are included in the +cryptographic checksum supplied in each advertisement. +Multiple vhids running on one interface participate in master/backup +elections independently. +.Pp +Additionally, there are a number of global parameters which can be set using +.Xr sysctl 8 : +.Bl -tag -width ".Va net.inet.carp.ifdown_demotion_factor" +.It Va net.inet.carp.allow +Allow +.Nm +operation. +When disabled, virtual hosts remain in initial state, neither sending nor +receiving announcements or traffic. +Enabled by default. +.It Va net.inet.carp.preempt +Allow virtual hosts to preempt each other. +When enabled, a vhid in a backup state would preempt a master that +is announcing itself with a lower advskew. +Disabled by default. +.It Va net.inet.carp.dscp +DSCP value in carp packet. +Valid Values are 0 to 63. +A value of 4 is equivalent to the old standard of TOS LOW_DELAY. +TOS values were deprecated and replaced by DSCP in 1998. +The default value is 56 (CS7/Network Control). +.It Va net.inet.carp.log +Determines what events relating to +.Nm +vhids are logged. +A value of 0 disables any logging. +A value of 1 enables logging state changes of +.Nm +vhids. +Values above 1 enable logging of bad +.Nm +packets. +The default value is 1. +.It Va net.inet.carp.demotion +This value shows the current level of CARP demotion. +The value is added to the actual advskew sent in announcements for +all vhids. +During normal system operation the demotion factor is zero. +However, problematic conditions raise its level: when +.Nm +experiences problem with sending announcements, when an interface +running a vhid goes down, or while the +.Xr pfsync 4 +interface is not synchronized. +The demotion factor can be adjusted writing to the sysctl oid. +The signed value supplied to the +.Xr sysctl 8 +command is added to current demotion factor. +This allows to control +.Nm +behaviour depending on some external conditions, for example on the status +of some daemon utility. +.It Va net.inet.carp.ifdown_demotion_factor +This value is added to +.Va net.inet.carp.demotion +when an interface running a vhid goes down. +The default value is 240 (the maximum advskew value). +.It Va net.inet.carp.senderr_demotion_factor +This value is added to +.Va net.inet.carp.demotion +when +.Nm +experiences errors sending its announcements. +The default value is 240 (the maximum advskew value). +.El +.\".Sh ARP level load balancing +.\"A +.\".Nm +.\"interface has limited abilities for load balancing incoming connections +.\"between hosts in an Ethernet network. +.\"For load-balancing operation, one needs several CARP interfaces that +.\"are configured to the same IP address, but to a different vhids. +.\"Once an ARP request is received, the CARP protocol will use a hashing +.\"function against the source IP address in the ARP request to determine +.\"which vhid the request will be assigned to. +.\"If the corresponding CARP interface is the current +.\"master interface, a reply will +.\"be sent to the ARP request; +.\"otherwise it will be ignored. +.\"See the +.\".Sx EXAMPLES +.\"section for a practical example of load balancing. +.\".Pp +.\"The ARP load balancing implemented in +.\".Nm +.\"has some limitations. +.\"First, ARP balancing only works on the local network segment. +.\"It cannot balance traffic that crosses a router, because the +.\"router itself will always be balanced to the same virtual host. +.\"Second, ARP load balancing can lead to asymmetric routing +.\"of incoming and outgoing traffic, and thus combining it with +.\".Xr pfsync 4 +.\"is dangerous, because this creates a race condition between +.\"balanced routers and a host they are serving. +.\"Imagine an incoming packet creating state on the first router, being +.\"forwarded to its destination, and the destination replying faster +.\"than the state information is packed and synced with the second router. +.\"If the reply would be load balanced to second router, it will be +.\"dropped since the second router has not yet received information about +.\"the connection state. +.Sh STATE CHANGE NOTIFICATIONS +Sometimes it is useful to get notified about +.Nm +status change events. +This can be accomplished by using +.Xr devd 8 +hooks. +Master/slave events are signalled under system +.Dv CARP . +The subsystem specifies the vhid and name of the interface where +the master/slave event occurred. +The type of the message displays the new state of the vhid. +Please see +.Xr devd.conf 5 +and the +.Sx EXAMPLES +section for more information. +.Sh EXAMPLES +For firewalls and routers with multiple interfaces, it is desirable to +failover all of the addresses running +.Nm +together, when one of the physical interfaces goes down. +This is achieved by the use of the preempt option. +Enable it on both hosts A and B: +.Pp +.Dl sysctl net.inet.carp.preempt=1 +.Pp +Assume that host A is the preferred master and we are running the +192.168.1.0/24 prefix on em0 and 192.168.2.0/24 on em1. +This is the setup for host A (advskew is above 0 so it could be overwritten +in the emergency situation from the other host): +.Bd -literal -offset indent +ifconfig em0 vhid 1 advskew 100 pass mekmitasdigoat 192.168.1.1/24 +ifconfig em1 vhid 2 advskew 100 pass mekmitasdigoat 192.168.2.1/24 +.Ed +.Pp +The setup for host B is identical, but it has a higher +.Cm advskew : +.Bd -literal -offset indent +ifconfig em0 vhid 1 advskew 200 pass mekmitasdigoat 192.168.1.1/24 +ifconfig em1 vhid 2 advskew 200 pass mekmitasdigoat 192.168.2.1/24 +.Ed +.Pp +When one of the physical interfaces of host A fails, +.Cm advskew +is demoted to a configured value on all its +.Nm +vhids. +Due to the preempt option, host B would start announcing itself, and thus +preempt host A on both interfaces instead of just the failed one. +.\".Pp +.\"In order to set up an ARP balanced virtual host, it is necessary to configure +.\"one virtual host for each physical host which would respond to ARP requests +.\"and thus handle the traffic. +.\"In the following example, two virtual hosts are configured on two hosts to +.\"provide balancing and failover for the IP address 192.168.1.10. +.\".Pp +.\"First the +.\".Nm +.\"interfaces on host A are configured. +.\"The +.\".Cm advskew +.\"of 100 on the second virtual host means that its advertisements will be sent +.\"out slightly less frequently. +.\".Bd -literal -offset indent +.\"ifconfig carp0 create +.\"ifconfig carp0 vhid 1 advskew 100 pass mekmitasdigoat 192.168.1.10/24 +.\"ifconfig carp1 create +.\"ifconfig carp1 vhid 2 advskew 200 pass mekmitasdigoat 192.168.1.10/24 +.\".Ed +.\".Pp +.\"The configuration for host B is identical, except the +.\".Cm advskew +.\"is on virtual host 1 rather than virtual host 2. +.\".Bd -literal -offset indent +.\"ifconfig carp0 create +.\"ifconfig carp0 vhid 1 advskew 200 pass mekmitasdigoat 192.168.1.10/24 +.\"ifconfig carp1 create +.\"ifconfig carp1 vhid 2 advskew 100 pass mekmitasdigoat 192.168.1.10/24 +.\".Ed +.\".Pp +.\"Finally, the ARP balancing feature must be enabled on both hosts: +.\".Pp +.\".Dl sysctl net.inet.carp.arpbalance=1 +.\".Pp +.\"When the hosts receive an ARP request for 192.168.1.10, the source IP address +.\"of the request is used to compute which virtual host should answer the request. +.\"The host which is master of the selected virtual host will reply to the +.\"request, the other(s) will ignore it. +.\".Pp +.\"This way, locally connected systems will receive different ARP replies and +.\"subsequent IP traffic will be balanced among the hosts. +.\"If one of the hosts fails, the other will take over the virtual MAC address, +.\"and begin answering ARP requests on its behalf. +.Pp +Processing of +.Nm +status change events can be set up by using the following devd.conf rule: +.Bd -literal -offset indent +notify 0 { + match "system" "CARP"; + match "subsystem" "[0-9]+@[0-9a-z\.]+"; + match "type" "(MASTER|BACKUP)"; + action "/root/carpcontrol.sh $subsystem $type"; +}; +.Ed +.Pp +To see +.Nm +packets decoded in +.Xr tcpdump 1 +output, one needs to specify the +.Fl T Ar carp +option, otherwise +.Xr tcpdump 1 +will interpret them as VRRP packets: +.Bd -literal -offset indent +tcpdump -npi vlan0 -T carp +.Ed +.Sh SEE ALSO +.Xr tcpdump 1 , +.Xr inet 4 , +.Xr pfsync 4 , +.Xr devd.conf 5 , +.Xr rc.conf 5 , +.Xr ifconfig 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +device first appeared in +.Ox 3.5 . +The +.Nm +device was imported into +.Fx 5.4 . +In +.Fx 10.0 , +.Nm +was significantly rewritten, and is no longer a pseudo-interface. diff --git a/static/freebsd/man4/cas.4 b/static/freebsd/man4/cas.4 new file mode 100644 index 00000000..3032dae5 --- /dev/null +++ b/static/freebsd/man4/cas.4 @@ -0,0 +1,131 @@ +.\" +.\" Copyright (c) 2009 Marius Strobl +.\" 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 April 18, 2023 +.Dt CAS 4 +.Os +.Sh NAME +.Nm cas +.Nd Sun Cassini/Cassini+ and National Semiconductor DP83065 Saturn Gigabit Ethernet driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device cas" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_cas_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the Sun Cassini/Cassini+ and National +Semiconductor DP83065 Saturn Gigabit Ethernet controllers. +.Pp +All controllers supported by the +.Nm +driver have TCP/UDP checksum offload capability for both receive and +transmit, support for the reception and transmission of extended frames +for +.Xr vlan 4 +and an interrupt coalescing/moderation mechanism as well as a 512-bit +multicast hash filter. +.Pp +The +.Nm +driver also supports Jumbo Frames (up to 9022 bytes), which can be +configured via the interface MTU setting. +Selecting an MTU larger than 1500 bytes with the +.Xr ifconfig 8 +utility configures the adapter to receive and transmit Jumbo Frames. +.Sh HARDWARE +The chips supported by the +.Nm +driver are: +.Pp +.Bl -bullet -compact +.It +National Semiconductor DP83065 Saturn Gigabit Ethernet +.It +Sun Cassini Gigabit Ethernet +.It +Sun Cassini+ Gigabit Ethernet +.El +.Pp +The +following add-on cards are known to work with the +.Nm +driver at this time: +.Pp +.Bl -bullet -compact +.It +Sun GigaSwift Ethernet 1.0 MMF (Cassini Kuheen) +(part no.\& 501-5524) +.It +Sun GigaSwift Ethernet 1.0 UTP (Cassini) +(part no.\& 501-5902) +.It +Sun GigaSwift Ethernet UTP (GCS) +(part no.\& 501-6719) +.It +Sun Quad GigaSwift Ethernet UTP (QGE) +(part no.\& 501-6522) +.It +Sun Quad GigaSwift Ethernet PCI-X (QGE-X) +(part no.\& 501-6738) +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver appeared in +.Fx 8.0 +and +.Fx 7.3 . +It is named after the +.Nm +driver which first appeared in +.Ox 4.1 +and supports the same set of controllers but is otherwise unrelated. +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Marius Strobl Aq Mt marius@FreeBSD.org +based on the +.Xr gem 4 +driver. diff --git a/static/freebsd/man4/cc_cdg.4 b/static/freebsd/man4/cc_cdg.4 new file mode 100644 index 00000000..b75cc766 --- /dev/null +++ b/static/freebsd/man4/cc_cdg.4 @@ -0,0 +1,154 @@ +.\" +.\" Copyright (c) 2013 Swinburne University of Technology, Melbourne, Australia +.\" 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 May 13, 2021 +.Dt CC_CDG 4 +.Os +.Sh NAME +.Nm cc_cdg +.Nd CDG Congestion Control Algorithm +.Sh DESCRIPTION +CAIA-Delay Gradient (CDG) is a hybrid congestion control algorithm which reacts +to both packet loss and inferred queuing delay. +It attempts to operate as a delay-based algorithm where possible, but utilises +heuristics to detect loss-based TCP cross traffic and will compete effectively +as required. +CDG is therefore incrementally deployable and suitable for use on shared +networks. +.Pp +During delay-based operation, CDG uses a delay-gradient based probabilistic +backoff mechanism, and will also try to infer non congestion related +packet losses and avoid backing off when they occur. +During loss-based operation, CDG essentially reverts to +.Xr cc_newreno 4 Ns - Ns like +behaviour. +.Pp +CDG switches to loss-based operation when it detects that a configurable number +of consecutive delay-based backoffs have had no measurable effect. +It periodically attempts to return to delay-based operation, but will keep +switching back to loss-based operation as required. +.Sh MIB Variables +The algorithm exposes the following variables in the +.Va net.inet.tcp.cc.cdg +branch of the +.Xr sysctl 3 +MIB: +.Bl -tag -width ".Va exp_backoff_scale" +.It Va version +Current algorithm/implementation version number. +.It Va beta_delay +Delay-based window decrease factor as a percentage (on delay-based backoff, w = +w * beta_delay / 100). +Default is 70. +.It Va beta_loss +Loss-based window decrease factor as a percentage (on loss-based backoff, w = +w * beta_loss / 100). +Default is 50. +.It Va exp_backoff_scale +Scaling parameter for the probabilistic exponential backoff. +Default is 2. +.It Va smoothing_factor +Number of samples used for moving average smoothing (0 means no smoothing). +Default is 8. +.It Va loss_compete_consec_cong +Number of consecutive delay-gradient based congestion episodes which will +trigger loss-based CC compatibility. +Default is 5. +.It Va loss_compete_hold_backoff +Number of consecutive delay-gradient based congestion episodes to hold the +window backoff for loss-based CC compatibility. +Default is 5. +.It Va alpha_inc +If non-zero, this enables an experimental mode where CDG's window increase +factor (alpha) is increased by 1 MSS every +.Va alpha_inc +RTTs during congestion avoidance mode. +(Setting +.Va alpha_inc +to 1 results in the most aggressive growth of the window increase factor over +time. +Use higher +.Va alpha_inc +values for slower growth.) +Default is 0. +.El +.Sh SEE ALSO +.Xr cc_chd 4 , +.Xr cc_cubic 4 , +.Xr cc_dctcp 4 , +.Xr cc_hd 4 , +.Xr cc_htcp 4 , +.Xr cc_newreno 4 , +.Xr cc_vegas 4 , +.Xr h_ertt 4 , +.Xr mod_cc 4 , +.Xr tcp 4 , +.Xr khelp 9 , +.Xr mod_cc 9 +.Rs +.%A "D. A. Hayes" +.%A "G. Armitage" +.%T "Revisiting TCP Congestion Control using Delay Gradients" +.%J "Networking 2011 Proceedings, Part II" +.%D "May 2011" +.%P "328-341" +.Re +.Rs +.%A "N. Khademi" +.%A "G. Armitage" +.%T "Minimising RTT across homogeneous 802.11 WLANs with CAIA Delay-Gradient TCP (v0.1)" +.%R "CAIA Technical Report 121113A" +.%D "November 2012" +.%U "http://caia.swin.edu.au/reports/121113A/CAIA-TR-121113A.pdf" +.Re +.Sh ACKNOWLEDGEMENTS +Development and testing of this software were made possible in part by grants +from the FreeBSD Foundation and The Cisco University Research Program Fund, a +corporate advised fund of Silicon Valley Community Foundation. +.Sh HISTORY +The +.Nm +congestion control module first appeared in +.Fx 9.2 . +.Pp +The module was first released in 2011 by David Hayes whilst working on the +NewTCP research project at Swinburne University of Technology's Centre for +Advanced Internet Architectures, Melbourne, Australia. +More details are available at: +.Pp +http://caia.swin.edu.au/urp/newtcp/ +.Sh AUTHORS +.An -nosplit +The +.Nm +congestion control module was written by +.An David Hayes Aq Mt david.hayes@ieee.org . +This manual page was written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org +and +.An Grenville Armitage Aq Mt garmitage@swin.edu.au . +.Sh BUGS +The underlying algorithm and parameter values are still a work in progress and +may not be optimal for some network scenarios. diff --git a/static/freebsd/man4/cc_chd.4 b/static/freebsd/man4/cc_chd.4 new file mode 100644 index 00000000..82a44dd2 --- /dev/null +++ b/static/freebsd/man4/cc_chd.4 @@ -0,0 +1,127 @@ +.\" +.\" Copyright (c) 2010-2011 The FreeBSD Foundation +.\" +.\" This documentation was written at the Centre for Advanced Internet +.\" Architectures, Swinburne University of Technology, Melbourne, Australia by +.\" David Hayes under sponsorship from the FreeBSD Foundation. +.\" +.\" 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 May 13, 2021 +.Dt CC_CHD 4 +.Os +.Sh NAME +.Nm cc_chd +.Nd CHD Congestion Control Algorithm +.Sh DESCRIPTION +CHD enhances the HD algorithm implemented in +.Xr cc_hd 4 . +It provides tolerance to non-congestion related packet loss and improvements to +coexistence with traditional loss-based TCP flows, especially when the +bottleneck link is lightly multiplexed. +.Pp +Like HD, the algorithm aims to keep network queuing delays below a particular +threshold (queue_threshold) and decides to reduce the congestion window (cwnd) +probabilistically based on its estimate of the network queuing delay. +.Pp +It differs from HD in three key aspects: +.Bl -bullet +.It +The probability of cwnd reduction due to congestion is calculated once per round +trip time instead of each time an acknowledgement is received as done by +.Xr cc_hd 4 . +.It +Packet losses that occur while the queuing delay is less than queue_threshold +do not cause cwnd to be reduced. +.It +CHD uses a shadow window to help regain lost transmission opportunities when +competing with loss-based TCP flows. +.El +.Sh MIB Variables +The algorithm exposes the following tunable variables in the +.Va net.inet.tcp.cc.chd +branch of the +.Xr sysctl 3 +MIB: +.Bl -tag -width ".Va queue_threshold" +.It Va queue_threshold +Queueing congestion threshold (qth) in ticks. +Default is 20. +.It Va pmax +Per RTT maximum backoff probability as a percentage. +Default is 50. +.It Va qmin +Minimum queuing delay threshold (qmin) in ticks. +Default is 5. +.It Va loss_fair +If 1, cwnd is adjusted using the shadow window when a congestion +related loss is detected. +Default is 1. +.It Va use_max +If 1, the maximum RTT seen within the measurement period is used as the basic +delay measurement for the algorithm, otherwise a sampled RTT measurement +is used. +Default is 1. +.El +.Sh SEE ALSO +.Xr cc_cdg 4 , +.Xr cc_cubic 4 , +.Xr cc_dctcp 4 , +.Xr cc_hd 4 , +.Xr cc_htcp 4 , +.Xr cc_newreno 4 , +.Xr cc_vegas 4 , +.Xr h_ertt 4 , +.Xr mod_cc 4 , +.Xr tcp 4 , +.Xr khelp 9 , +.Xr mod_cc 9 +.Rs +.%A "D. A. Hayes" +.%A "G. Armitage" +.%T "Improved coexistence and loss tolerance for delay based TCP congestion control" +.%J "in 35th Annual IEEE Conference on Local Computer Networks" +.%D "October 2010" +.%P "24-31" +.Re +.Sh ACKNOWLEDGEMENTS +Development and testing of this software were made possible in part by grants +from the FreeBSD Foundation and Cisco University Research Program Fund at +Community Foundation Silicon Valley. +.Sh HISTORY +The +.Nm +congestion control module first appeared in +.Fx 9.0 . +.Pp +The module was first released in 2010 by David Hayes whilst working on the +NewTCP research project at Swinburne University of Technology's Centre for +Advanced Internet Architectures, Melbourne, Australia. +More details are available at: +.Pp +http://caia.swin.edu.au/urp/newtcp/ +.Sh AUTHORS +.An -nosplit +The +.Nm +congestion control module and this manual page were written by +.An David Hayes Aq Mt david.hayes@ieee.org . diff --git a/static/freebsd/man4/cc_cubic.4 b/static/freebsd/man4/cc_cubic.4 new file mode 100644 index 00000000..9a145ce3 --- /dev/null +++ b/static/freebsd/man4/cc_cubic.4 @@ -0,0 +1,120 @@ +.\" +.\" Copyright (c) 2009 Lawrence Stewart +.\" Copyright (c) 2010-2011 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" Portions of this documentation were written at the Centre for Advanced +.\" Internet Architectures, Swinburne University of Technology, Melbourne, +.\" Australia by David Hayes under sponsorship from the FreeBSD Foundation. +.\" +.\" 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 February 4, 2023 +.Dt CC_CUBIC 4 +.Os +.Sh NAME +.Nm cc_cubic +.Nd CUBIC Congestion Control Algorithm +.Sh DESCRIPTION +The CUBIC congestion control algorithm was designed to provide increased +throughput in fast and long-distance networks. +The CUBIC congestion control algorithm is the default for TCP. +It attempts to maintain fairness when competing with legacy NewReno TCP in lower +speed scenarios where NewReno is able to operate adequately. +.Pp +The congestion window is increased as a function of the time elapsed since the +last congestion event. +During regular operation, the window increase function follows a cubic function, +with the inflection point set to be the congestion window value reached at the +last congestion event. +CUBIC also calculates an estimate of the congestion window that NewReno would +have achieved at a given time after a congestion event. +When updating the congestion window, the algorithm will choose the larger of the +calculated CUBIC and estimated NewReno windows. +.Pp +CUBIC also backs off less on congestion by changing the multiplicative decrease +factor from 1/2 (used by standard NewReno TCP) to 4/5. +.Pp +The implementation was done in a clean-room fashion, and is based on the +Internet Draft and paper referenced in the +.Sx SEE ALSO +section below. +.Sh MIB Variables +There are currently no tunable MIB variables. +.Sh SEE ALSO +.Xr cc_cdg 4 , +.Xr cc_chd 4 , +.Xr cc_dctcp 4 , +.Xr cc_hd 4 , +.Xr cc_htcp 4 , +.Xr cc_newreno 4 , +.Xr cc_vegas 4 , +.Xr mod_cc 4 , +.Xr tcp 4 , +.Xr mod_cc 9 +.Rs +.%A "Sangtae Ha" +.%A "Injong Rhee" +.%A "Lisong Xu" +.%T "CUBIC for Fast Long-Distance Networks" +.%U "https://tools.ietf.org/id/draft-rhee-tcpm-cubic-02.txt" +.Re +.Rs +.%A "Sangtae Ha" +.%A "Injong Rhee" +.%A "Lisong Xu" +.%T "CUBIC: a new TCP-friendly high-speed TCP variant" +.%J "SIGOPS Oper. Syst. Rev." +.%V "42" +.%N "5" +.%D "July 2008" +.%P "64-74" +.Re +.Sh ACKNOWLEDGEMENTS +Development and testing of this software were made possible in part by grants +from the FreeBSD Foundation and Cisco University Research Program Fund at +Community Foundation Silicon Valley. +.Sh HISTORY +The +.Nm +congestion control module first appeared in +.Fx 9.0 . +.Pp +This became the default congestion algorithm for FreeBSD in version +.Fx 14.0 , +replacing +.Xr cc_newreno 4 . +.Pp +The module was first released in 2009 by Lawrence Stewart whilst studying at +Swinburne University of Technology's Centre for Advanced Internet Architectures, +Melbourne, Australia. +More details are available at: +.Pp +http://caia.swin.edu.au/urp/newtcp/ +.Sh AUTHORS +.An -nosplit +The +.Nm +congestion control module and this manual page were written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org +and +.An David Hayes Aq Mt david.hayes@ieee.org . diff --git a/static/freebsd/man4/cc_dctcp.4 b/static/freebsd/man4/cc_dctcp.4 new file mode 100644 index 00000000..4095cd1e --- /dev/null +++ b/static/freebsd/man4/cc_dctcp.4 @@ -0,0 +1,150 @@ +.\" +.\" Copyright (c) 2014 Midori Kato +.\" Copyright (c) 2014 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" Portions of this documentation were written at Keio University, Japan. +.\" +.\" 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 November 8, 2022 +.Dt CC_DCTCP 4 +.Os +.Sh NAME +.Nm cc_dctcp +.Nd DCTCP Congestion Control Algorithm +.Sh DESCRIPTION +The DCTCP (data center TCP) congestion control algorithm aims to maximise +throughput and minimise latency in data center networks by utilising the +proportion of Explicit Congestion Notification (ECN) marks received from capable +hardware as a congestion signal. +.Pp +DCTCP uses fraction of ECN marked packets to update congestion window. +The window reduction ratio is always <= 1/2. +Only when all of the packets are +marked, congestion window is halved. +.Pp +In order to keep the accuracy of the ECN marked fraction, a DCTCP receiver +mirrors back incoming (or missing) CE marks by setting (or clearing) ECE marks. +This feedback methodology is also adopted when the receiver uses delayed ACK. +.Pp +The +.Fx +DCTCP implementation includes two minor modifications for the one-sided +deployment. +Considering the situation that DCTCP is used as sender and classic +ECN is used as receiver, DCTCP sets the CWR flag as the reaction to the ECE +flag. +In addition, when classic ECN is used as sender and DCTCP is used as +receiver, DCTCP avoids to mirror back ACKs only when the CWR flag is +set in the incoming packet. +.Pp +The other specifications are based on the paper and the RFC referenced +in the +.Sx SEE ALSO +section below. +.Sh MIB Variables +The algorithm exposes the following tunable variables in the +.Va net.inet.tcp.cc.dctcp +branch of the +.Xr sysctl 3 +MIB: +.Bl -tag -width ".Va slowstart" +.It Va alpha +The initial value to estimate the congestion on the link. +The valid range is from 0 to 1024, where 1024 reduces the congestion +window to half, if a CE is observed in the first window and +.Va alpha +could not yet adjust to the congestion level on that path. +Default is 1024. +.It Va shift_g +An estimation gain in the +.Va alpha +calculation. +This influences the responsiveness when adjusting alpha +to the most recent observed window. +Valid range from 0 to 10, the default is 4, resulting in an effective +gain of 1 / ( 2 ^ +.Va shift_g +), or 1/16th. +.It Va slowstart +A flag if the congestion window should be reduced by one half after slow start. +Valid settings 0 and 1, default 0. +.It Va ect1 +Controls if a DCTCP session should use IP ECT(0) marking when sending out +segments (default), or ECT(1) marking making use of L4S infrastructure. +Changes to this setting will only affect new sessions, existing sessions will +retain their previous marking value. +.El +.Sh SEE ALSO +.Xr cc_cdg 4 , +.Xr cc_chd 4 , +.Xr cc_cubic 4 , +.Xr cc_hd 4 , +.Xr cc_htcp 4 , +.Xr cc_newreno 4 , +.Xr cc_vegas 4 , +.Xr mod_cc 4 , +.Xr tcp 4 , +.Xr mod_cc 9 +.Rs +.%A "Mohammad Alizadeh" +.%A "Albert Greenberg" +.%A "David A. Maltz" +.%A "Jitendra Padhye" +.%A "Parveen Patel" +.%A "Balaji Prabhakar" +.%A "Sudipta Sengupta" +.%A "Murari Sridharan" +.%T "Data Center TCP (DCTCP)" +.%U "http://research.microsoft.com/pubs/121386/dctcp-public.pdf" +.%J "ACM SIGCOMM 2010" +.%D "July 2010" +.%P "63-74" +.Re +.Rs +.%A "Stephen Bensley" +.%A "Dave Thaler" +.%A "Praveen Balasubramanian" +.%A "Lars Eggert" +.%A "Glenn Judd" +.%T "Data Center TCP (DCTCP): TCP Congestion Control for Data Centers" +.%U "https://tools.ietf.org/html/rfc8257" +.Re +.Sh HISTORY +The +.Nm +congestion control module first appeared in +.Fx 11.0 . +.Pp +The module was first released in 2014 by Midori Kato studying at Keio +University, Japan. +.Sh AUTHORS +.An -nosplit +The +.Nm +congestion control module and this manual page were written by +.An Midori Kato Mt katoon@sfc.wide.ad.jp +and +.An Lars Eggert Mt lars@netapp.com +with help and modifications from +.An Hiren Panchasara Mt hiren@FreeBSD.org diff --git a/static/freebsd/man4/cc_hd.4 b/static/freebsd/man4/cc_hd.4 new file mode 100644 index 00000000..f401e150 --- /dev/null +++ b/static/freebsd/man4/cc_hd.4 @@ -0,0 +1,119 @@ +.\" +.\" Copyright (c) 2010-2011 The FreeBSD Foundation +.\" +.\" This documentation was written at the Centre for Advanced Internet +.\" Architectures, Swinburne University of Technology, Melbourne, Australia by +.\" David Hayes under sponsorship from the FreeBSD Foundation. +.\" +.\" 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 May 13, 2021 +.Dt CC_HD 4 +.Os +.Sh NAME +.Nm cc_hd +.Nd HD Congestion Control Algorithm +.Sh DESCRIPTION +The HD congestion control algorithm is an implementation of the Hamilton +Institute's delay-based congestion control which aims to keep network queuing +delays below a particular threshold (queue_threshold). +.Pp +HD probabilistically reduces the congestion window (cwnd) based on its estimate +of the network queuing delay. +The probability of reducing cwnd is zero at hd_qmin or less, rising to a maximum +at queue_threshold, and then back to zero at the maximum queuing delay. +.Pp +Loss-based congestion control algorithms such as NewReno probe for network +capacity by filling queues until there is a packet loss. +HD competes with loss-based congestion control algorithms by allowing its +probability of reducing cwnd to drop from a maximum at queue_threshold to be +zero at the maximum queuing delay. +This has been shown to work well when the bottleneck link is highly multiplexed. +.Sh MIB Variables +The algorithm exposes the following tunable variables in the +.Va net.inet.tcp.cc.hd +branch of the +.Xr sysctl 3 +MIB: +.Bl -tag -width ".Va queue_threshold" +.It Va queue_threshold +Queueing congestion threshold (qth) in ticks. +Default is 20. +.It Va pmax +Per packet maximum backoff probability as a percentage. +Default is 5. +.It Va qmin +Minimum queuing delay threshold (qmin) in ticks. +Default is 5. +.El +.Sh SEE ALSO +.Xr cc_cdg 4 , +.Xr cc_chd 4 , +.Xr cc_cubic 4 , +.Xr cc_dctcp 4 , +.Xr cc_htcp 4 , +.Xr cc_newreno 4 , +.Xr cc_vegas 4 , +.Xr h_ertt 4 , +.Xr mod_cc 4 , +.Xr tcp 4 , +.Xr khelp 9 , +.Xr mod_cc 9 +.Rs +.%A "L. Budzisz" +.%A "R. Stanojevic" +.%A "R. Shorten" +.%A "F. Baker" +.%T "A strategy for fair coexistence of loss and delay-based congestion control algorithms" +.%J "IEEE Commun. Lett." +.%D "Jul 2009" +.%V "13" +.%N "7" +.%P "555-557" +.Re +.Sh ACKNOWLEDGEMENTS +Development and testing of this software were made possible in part by grants +from the FreeBSD Foundation and Cisco University Research Program Fund at +Community Foundation Silicon Valley. +.Sh FUTURE WORK +The Hamilton Institute have recently made some improvements to the algorithm +implemented by this module and have called it Coexistent-TCP (C-TCP). +The improvements should be evaluated and potentially incorporated into this +module. +.Sh HISTORY +The +.Nm +congestion control module first appeared in +.Fx 9.0 . +.Pp +The module was first released in 2010 by David Hayes whilst working on the +NewTCP research project at Swinburne University of Technology's Centre for +Advanced Internet Architectures, Melbourne, Australia. +More details are available at: +.Pp +http://caia.swin.edu.au/urp/newtcp/ +.Sh AUTHORS +.An -nosplit +The +.Nm +congestion control module and this manual page were written by +.An David Hayes Aq Mt david.hayes@ieee.org . diff --git a/static/freebsd/man4/cc_htcp.4 b/static/freebsd/man4/cc_htcp.4 new file mode 100644 index 00000000..2441925d --- /dev/null +++ b/static/freebsd/man4/cc_htcp.4 @@ -0,0 +1,136 @@ +.\" +.\" Copyright (c) 2008 Lawrence Stewart +.\" Copyright (c) 2010-2011 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" Portions of this documentation were written at the Centre for Advanced +.\" Internet Architectures, Swinburne University of Technology, Melbourne, +.\" Australia by David Hayes under sponsorship from the FreeBSD Foundation. +.\" +.\" 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 May 13, 2021 +.Dt CC_HTCP 4 +.Os +.Sh NAME +.Nm cc_htcp +.Nd H-TCP Congestion Control Algorithm +.Sh DESCRIPTION +The H-TCP congestion control algorithm was designed to provide increased +throughput in fast and long-distance networks. +It attempts to maintain fairness when competing with legacy NewReno TCP in lower +speed scenarios where NewReno is able to operate adequately. +.Pp +The congestion window is increased as a function of the time elapsed since the +last congestion event. +The window increase algorithm operates like NewReno for the first second after a +congestion event, and then switches to a high-speed mode based on a quadratic +increase function. +.Pp +The implementation was done in a clean-room fashion, and is based on the +Internet Draft and other documents referenced in the +.Sx SEE ALSO +section below. +.Sh MIB Variables +The algorithm exposes the following tunable variables in the +.Va net.inet.tcp.cc.htcp +branch of the +.Xr sysctl 3 +MIB: +.Bl -tag -width ".Va adaptive_backoff" +.It Va adaptive_backoff +Controls use of the adaptive backoff algorithm, which is designed to keep +network queues non-empty during congestion recovery episodes. +Default is 0 (disabled). +.It Va rtt_scaling +Controls use of the RTT scaling algorithm, which is designed to make congestion +window increase during congestion avoidance mode invariant with respect to RTT. +Default is 0 (disabled). +.El +.Sh SEE ALSO +.Xr cc_cdg 4 , +.Xr cc_chd 4 , +.Xr cc_cubic 4 , +.Xr cc_dctcp 4 , +.Xr cc_hd 4 , +.Xr cc_newreno 4 , +.Xr cc_vegas 4 , +.Xr mod_cc 4 , +.Xr tcp 4 , +.Xr mod_cc 9 +.Rs +.%A "D. Leith" +.%A "R. Shorten" +.%T "H-TCP: TCP Congestion Control for High Bandwidth-Delay Product Paths" +.%U "https://tools.ietf.org/id/draft-leith-tcp-htcp-06.txt" +.Re +.Rs +.%A "D. Leith" +.%A "R. Shorten" +.%A "T. Yee" +.%T "H-TCP: A framework for congestion control in high-speed and long-distance networks" +.%B "Proc. PFLDnet" +.%D "2005" +.Re +.Rs +.%A "G. Armitage" +.%A "L. Stewart" +.%A "M. Welzl" +.%A "J. Healy" +.%T "An independent H-TCP implementation under FreeBSD 7.0: description and observed behaviour" +.%J "SIGCOMM Comput. Commun. Rev." +.%V "38" +.%N "3" +.%D "July 2008" +.%P "27-38" +.Re +.Sh ACKNOWLEDGEMENTS +Development and testing of this software were made possible in part by grants +from the FreeBSD Foundation and Cisco University Research Program Fund at +Community Foundation Silicon Valley. +.Sh HISTORY +The +.Nm +congestion control module first appeared in +.Fx 9.0 . +.Pp +The module was first released in 2007 by James Healy and Lawrence Stewart whilst +working on the NewTCP research project at Swinburne University of Technology's +Centre for Advanced Internet Architectures, Melbourne, Australia, which was made +possible in part by a grant from the Cisco University Research Program Fund at +Community Foundation Silicon Valley. +More details are available at: +.Pp +http://caia.swin.edu.au/urp/newtcp/ +.Sh AUTHORS +.An -nosplit +The +.Nm +congestion control module was written by +.An James Healy Aq Mt jimmy@deefa.com +and +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org . +.Pp +This manual page was written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org +and +.An David Hayes Aq Mt david.hayes@ieee.org . diff --git a/static/freebsd/man4/cc_newreno.4 b/static/freebsd/man4/cc_newreno.4 new file mode 100644 index 00000000..0730024a --- /dev/null +++ b/static/freebsd/man4/cc_newreno.4 @@ -0,0 +1,174 @@ +.\" +.\" Copyright (c) 2009 Lawrence Stewart +.\" Copyright (c) 2011 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" Portions of this documentation were written at the Centre for Advanced +.\" Internet Architectures, Swinburne University of Technology, Melbourne, +.\" Australia by Lawrence Stewart under sponsorship from the FreeBSD Foundation. +.\" +.\" 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 February 4, 2023 +.Dt CC_NEWRENO 4 +.Os +.Sh NAME +.Nm cc_newreno +.Nd NewReno Congestion Control Algorithm +.Sh SYNOPSIS +.In netinet/cc/cc_newreno.h +.Sh DESCRIPTION +Details about the algorithm can be found in RFC5681. +.Sh Socket Options +The +.Nm +module supports a number of socket options under TCP_CCALGOOPT (refer to +.Xr tcp 4 +and +.Xr mod_cc 9 for details) +which can +be set with +.Xr setsockopt 2 +and tested with +.Xr getsockopt 2 . +The +.Nm +socket options use this structure defined in +: +.Bd -literal +struct cc_newreno_opts { + int name; + uint32_t val; +} +.Ed +.Bl -tag -width ".Va CC_NEWRENO_BETA_ECN" +.It Va CC_NEWRENO_BETA +Multiplicative window decrease factor, specified as a percentage, applied to +the congestion window in response to a congestion signal per: cwnd = (cwnd * +CC_NEWRENO_BETA) / 100. +Default is 50. +.It Va CC_NEWRENO_BETA_ECN +Multiplicative window decrease factor, specified as a percentage, applied to +the congestion window in response to an ECN congestion signal when +.Va net.inet.tcp.cc.abe=1 +per: cwnd = (cwnd * CC_NEWRENO_BETA_ECN) / 100. +Default is 80. +.Pp +Note that currently the only way to enable +hystart++ is to enable it via socket option. +When enabling it a value of 1 will enable precise internet-draft (version 4) behavior +(subject to any MIB variable settings), other setting (2 and 3) are experimental. +.El +.Pp +Note that hystart++ requires the TCP stack be able to call to the congestion +controller with both the +.Va newround +function as well as the +.Va rttsample +function. +Currently the only TCP stacks that provide this feedback to the +congestion controller is rack. +.Sh MIB Variables +The algorithm exposes these variables in the +.Va net.inet.tcp.cc.newreno +branch of the +.Xr sysctl 3 +MIB: +.Bl -tag -width ".Va beta_ecn" +.It Va beta +Multiplicative window decrease factor, specified as a percentage, applied to +the congestion window in response to a congestion signal per: cwnd = (cwnd * +beta) / 100. +Default is 50. +.It Va beta_ecn +Multiplicative window decrease factor, specified as a percentage, applied to +the congestion window in response to an ECN congestion signal when +.Va net.inet.tcp.cc.abe=1 +per: cwnd = (cwnd * beta_ecn) / 100. +Default is 80. +.El +.Sh SEE ALSO +.Xr cc_cdg 4 , +.Xr cc_chd 4 , +.Xr cc_cubic 4 , +.Xr cc_dctcp 4 , +.Xr cc_hd 4 , +.Xr cc_htcp 4 , +.Xr cc_vegas 4 , +.Xr mod_cc 4 , +.Xr tcp 4 , +.Xr mod_cc 9 +.Rs +.%A "Mark Allman" +.%A "Vern Paxson" +.%A "Ethan Blanton" +.%T "TCP Congestion Control" +.%O "RFC 5681" +.Re +.Rs +.%A "Naeem Khademi" +.%A "Michael Welzl" +.%A "Grenville Armitage" +.%A "Gorry Fairhurst" +.%T "TCP Alternative Backoff with ECN (ABE)" +.%O "RFC 8511" +.Re +.Sh ACKNOWLEDGEMENTS +Development and testing of this software were made possible in part by grants +from the FreeBSD Foundation and Cisco University Research Program Fund at +Community Foundation Silicon Valley. +.Sh HISTORY +The +.Nm +congestion control algorithm first appeared in its modular form in +.Fx 9.0 . +.Pp +This was the default congestion control algorithm in FreeBSD before +version +.Fx 14.0 , +after which +.Xr cc_cubic 4 +replaced it. +.Pp +The module was first released in 2007 by James Healy and Lawrence Stewart whilst +working on the NewTCP research project at Swinburne University of Technology's +Centre for Advanced Internet Architectures, Melbourne, Australia, which was made +possible in part by a grant from the Cisco University Research Program Fund at +Community Foundation Silicon Valley. +More details are available at: +.Pp +http://caia.swin.edu.au/urp/newtcp/ +.Sh AUTHORS +.An -nosplit +The +.Nm +congestion control module was written by +.An James Healy Aq Mt jimmy@deefa.com , +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org +and +.An David Hayes Aq Mt david.hayes@ieee.org . +.Pp +Support for TCP ABE was added by +.An Tom Jones Aq Mt tj@enoti.me . +.Pp +This manual page was written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org . diff --git a/static/freebsd/man4/cc_vegas.4 b/static/freebsd/man4/cc_vegas.4 new file mode 100644 index 00000000..ba755dbc --- /dev/null +++ b/static/freebsd/man4/cc_vegas.4 @@ -0,0 +1,135 @@ +.\" +.\" Copyright (c) 2010-2011 The FreeBSD Foundation +.\" +.\" This documentation was written at the Centre for Advanced Internet +.\" Architectures, Swinburne University of Technology, Melbourne, Australia by +.\" David Hayes under sponsorship from the FreeBSD Foundation. +.\" +.\" 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 May 13, 2021 +.Dt CC_VEGAS 4 +.Os +.Sh NAME +.Nm cc_vegas +.Nd Vegas Congestion Control Algorithm +.Sh DESCRIPTION +The Vegas congestion control algorithm uses what the authors term the actual and +expected transmission rates to determine whether there is congestion along the +network path i.e. +.Bl -item -offset indent +.It +actual rate = (total data sent in a RTT) / RTT +.It +expected rate = cwnd / RTTmin +.It +diff = expected - actual +.El +.Pp +where RTT is the measured instantaneous round trip time and RTTmin is the +smallest round trip time observed during the connection. +.Pp +The algorithm aims to keep diff between two parameters alpha and beta, such +that: +.Bl -item -offset indent +.It +alpha < diff < beta +.El +.Pp +If diff > beta, congestion is inferred and cwnd is decremented by one packet (or +the maximum TCP segment size). +If diff < alpha, then cwnd is incremented by one packet. +Alpha and beta govern the amount of buffering along the path. +.Pp +The implementation was done in a clean-room fashion, and is based on the +paper referenced in the +.Sx SEE ALSO +section below. +.Sh IMPLEMENTATION NOTES +The time from the transmission of a marked packet until the receipt of an +acknowledgement for that packet is measured once per RTT. +This implementation does not implement Brakmo's and Peterson's original +duplicate ACK policy since clock ticks in today's machines are not as coarse as +they were (i.e. 500ms) when Vegas was originally designed. +Note that modern TCP recovery processes such as fast retransmit and SACK are +enabled by default in the TCP stack. +.Sh MIB Variables +The algorithm exposes the following tunable variables in the +.Va net.inet.tcp.cc.vegas +branch of the +.Xr sysctl 3 +MIB: +.Bl -tag -width ".Va alpha" +.It Va alpha +Query or set the Vegas alpha parameter as a number of buffers on the path. +When setting alpha, the value must satisfy: 0 < alpha < beta. +Default is 1. +.It Va beta +Query or set the Vegas beta parameter as a number of buffers on the path. +When setting beta, the value must satisfy: 0 < alpha < beta. +Default is 3. +.El +.Sh SEE ALSO +.Xr cc_cdg 4 , +.Xr cc_chd 4 , +.Xr cc_cubic 4 , +.Xr cc_dctcp 4 , +.Xr cc_hd 4 , +.Xr cc_htcp 4 , +.Xr cc_newreno 4 , +.Xr h_ertt 4 , +.Xr mod_cc 4 , +.Xr tcp 4 , +.Xr khelp 9 , +.Xr mod_cc 9 +.Rs +.%A "L. S. Brakmo" +.%A "L. L. Peterson" +.%T "TCP Vegas: end to end congestion avoidance on a global internet" +.%J "IEEE J. Sel. Areas Commun." +.%D "October 1995" +.%V "13" +.%N "8" +.%P "1465-1480" +.Re +.Sh ACKNOWLEDGEMENTS +Development and testing of this software were made possible in part by grants +from the FreeBSD Foundation and Cisco University Research Program Fund at +Community Foundation Silicon Valley. +.Sh HISTORY +The +.Nm +congestion control module first appeared in +.Fx 9.0 . +.Pp +The module was first released in 2010 by David Hayes whilst working on the +NewTCP research project at Swinburne University of Technology's Centre for +Advanced Internet Architectures, Melbourne, Australia. +More details are available at: +.Pp +http://caia.swin.edu.au/urp/newtcp/ +.Sh AUTHORS +.An -nosplit +The +.Nm +congestion control module and this manual page were written by +.An David Hayes Aq Mt david.hayes@ieee.org . diff --git a/static/freebsd/man4/ccd.4 b/static/freebsd/man4/ccd.4 new file mode 100644 index 00000000..0c2bc996 --- /dev/null +++ b/static/freebsd/man4/ccd.4 @@ -0,0 +1,284 @@ +.\" $NetBSD: ccd.4,v 1.5 1995/10/09 06:09:09 thorpej Exp $ +.\" +.\" Copyright (c) 1994 Jason Downs. +.\" Copyright (c) 1994, 1995 Jason R. Thorpe. +.\" 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 for the NetBSD Project +.\" by Jason Downs and Jason R. Thorpe. +.\" 4. Neither the name of the author nor the names of its contributors +.\" may 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 January 23, 2025 +.Dt CCD 4 +.Os +.Sh NAME +.Nm ccd +.Nd Concatenated Disk driver +.Sh SYNOPSIS +.Cd "device ccd" +.Sh DESCRIPTION +The +.Nm +driver provides the capability of combining one or more disks/partitions +into one virtual disk. +.Pp +This document assumes that you are familiar with how to generate kernels, +how to properly configure disks and devices in a kernel +configuration file, and how to partition disks. +.Pp +In order to compile in support for the +.Nm , +you must add a line similar +to the following to your kernel configuration file: +.Pp +.Dl "device ccd # concatenated disk devices" +.Pp +As of the +.Fx 3.0 +release, you do not need to +configure your kernel with +.Nm +but may instead use it as a kernel loadable +module. +Simply running +.Xr ccdconfig 8 +will load the module into the kernel. +.Pp +A +.Nm +may be either serially concatenated or interleaved. +To serially +concatenate the partitions, specify the interleave factor of 0. +Note that mirroring may not be used with an interleave factor of 0. +.Pp +There is a run-time utility that is used for configuring +.Nm Ns s . +See +.Xr ccdconfig 8 +for more information. +.Ss The Interleave Factor +If a +.Nm +is interleaved correctly, a +.Dq striping +effect is achieved, which can increase sequential read/write +performance. +The interleave factor is expressed in units of +.Dv DEV_BSIZE +(usually 512 bytes). +For large writes, the optimum interleave factor +is typically the size of a track, while for large reads, it is about a +quarter of a track. +(Note that this changes greatly depending on the +number and speed of disks.) +For instance, with eight 7,200 RPM drives +on two Fast-Wide SCSI buses, this translates to about 128 for writes +and 32 for reads. +A larger interleave tends to work better when the +disk is taking a multitasking load by localizing the file I/O from +any given process onto a single disk. +You lose sequential performance when +you do this, but sequential performance is not usually an issue with a +multitasking load. +.Pp +An interleave factor must be specified when using a mirroring configuration, +even when you have only two disks (i.e., the layout winds up being the same +no matter what the interleave factor). +The interleave factor will determine +how I/O is broken up, however, and a value 128 or greater is recommended. +.Pp +.Nm +has an option for a parity disk, but does not currently implement it. +.Pp +The best performance is achieved if all component disks have the same +geometry and size. +Optimum striping cannot occur with different +disk types. +.Pp +For random-access oriented workloads, such as news servers, a larger +interleave factor (e.g., 65,536) is more desirable. +Note that there +is not much +.Nm +can do to speed up applications that are seek-time limited. +Larger +interleave factors will at least reduce the chance of having to seek +two disk-heads to read one directory or a file. +.Ss Disk Mirroring +You can configure the +.Nm +to +.Dq mirror +any even number of disks. +See +.Xr ccdconfig 8 +for how to specify the necessary flags. +For example, if you have a +.Nm +configuration specifying four disks, the first two disks will be mirrored with +the second two disks. +A write will be run to both sides of +the mirror. +A read will be run to either side of the mirror depending +on what the driver believes to be most optimal. +If the read fails, +the driver will automatically attempt to read the same sector from the +other side of the mirror. +Currently +.Nm +uses a dual seek zone model to optimize reads for a multi-tasking load +rather than a sequential load. +.Pp +In an event of a disk +failure, you can use +.Xr dd 1 +to recover the failed disk. +.Pp +Note that a one-disk +.Nm +is not the same as the original partition. +In particular, this means +if you have a file system on a two-disk mirrored +.Nm +and one of the disks fail, you cannot mount and use the remaining +partition as itself; you have to configure it as a one-disk +.Nm . +You cannot replace a disk in a mirrored +.Nm +partition without first backing up the partition, then replacing the disk, +then restoring the partition. +.Ss Linux Compatibility +The +.Tn Linux +compatibility mode does not try to read the label that +.Tn Linux Ns ' +.Xr md 4 +driver leaves on the raw devices. +You will have to give the order +of devices and the interleave factor on your own. +When in +.Tn Linux +compatibility mode, +.Nm +will convert the interleave factor from +.Tn Linux +terminology. +That means you give the same interleave factor that you +gave as chunk size in +.Tn Linux . +.Pp +If you have a +.Tn Linux +.Xr md 4 +device in +.Dq legacy +mode, do not use the +.Dv CCDF_LINUX +flag in +.Xr ccdconfig 8 . +Use the +.Dv CCDF_NO_OFFSET +flag instead. +In that case you have to convert +the interleave factor on your own, usually it is +.Tn Linux Ns ' +chunk size multiplied by two. +.Pp +Using a +.Tn Linux +RAID this way is potentially dangerous and can destroy +the data in there. +Since +.Fx +does not read the label used by +.Tn Linux , +changes in +.Tn Linux +might invalidate the compatibility layer. +.Pp +However, using this is reasonably safe if you test the compatibility +before mounting a RAID read-write for the first time. +Just using +.Xr ccdconfig 8 +without mounting does not write anything to the +.Tn Linux +RAID. +Then you do a +.Nm fsck.ext2fs Pq Pa ports/filesystems/e2fsprogs +on the +.Nm +device using the +.Fl n +flag. +You can mount the file system read-only to check files in there. +If all this works, it is unlikely that there is a problem with +.Nm . +Keep in mind that even when the +.Tn Linux +compatibility mode in +.Nm +is working correctly, bugs in +.Fx Ap s +.Nm ex2fs +implementation would still destroy +your data. +.Sh WARNINGS +If just one (or more) of the disks in a +.Nm +fails, the entire +file system will be lost unless you are mirroring the disks. +.Pp +If one of the disks in a mirror is lost, you should still +be able to back up your data. +If a write error occurs, however, data +read from that sector may be non-deterministic. +It may return the data +prior to the write or it may return the data that was written. +When a +write error occurs, you should recover and regenerate the data as soon +as possible. +.Pp +Changing the interleave or other parameters for a +.Nm +disk usually destroys whatever data previously existed on that disk. +.Sh FILES +.Bl -tag -width ".Pa /dev/ccd*" +.It Pa /dev/ccd* +.Nm +device special files +.El +.Sh SEE ALSO +.Xr dd 1 , +.Xr ccdconfig 8 , +.Xr config 8 , +.Xr disklabel 8 , +.Xr fsck 8 , +.Xr mount 8 , +.Xr newfs 8 +.Sh HISTORY +The concatenated disk driver was originally written at the University of +Utah. diff --git a/static/freebsd/man4/ccr.4 b/static/freebsd/man4/ccr.4 new file mode 100644 index 00000000..de3f3609 --- /dev/null +++ b/static/freebsd/man4/ccr.4 @@ -0,0 +1,118 @@ +.\" Copyright (c) 2017, Chelsio Inc +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY 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 November 25, 2024 +.Dt CCR 4 +.Os +.Sh NAME +.Nm ccr +.Nd "Chelsio T6 crypto accelerator driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ccr" +.Cd "device cxgbe" +.Ed +.Pp +To load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ccr_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the crypto accelerator engine included on +PCI Express Ethernet adapters based on the Chelsio Terminator 6 ASIC (T6). +The driver accelerates AES-CBC, AES-CCM, AES-CTR, AES-GCM, AES-XTS, +SHA1, SHA2-224, SHA2-256, SHA2-384, SHA2-512, +SHA1-HMAC, SHA2-224-HMAC, SHA2-256-HMAC, SHA2-384-HMAC, and SHA2-512-HMAC +operations for +.Xr crypto 9 +consumers such as +.Xr ktls 4 , +.Xr geli 4 , +and +.Xr ipsec 4 . +The driver also supports chaining one of AES-CBC, AES-CTR, or AES-XTS with +SHA1-HMAC, SHA2-224-HMAC, SHA2-256-HMAC, SHA2-384-HMAC, or SHA2-512-HMAC for +encrypt-then-authenticate operations. +For further hardware information and questions related to hardware +requirements, see +.Pa http://www.chelsio.com/ . +.Pp +The +.Nm +driver attaches as a child of an existing Chelsio NIC device and thus +requires that the +.Xr cxgbe 4 +driver be active. +.Sh HARDWARE +The +.Nm +driver supports the crypto accelerator engine included on adapters +based on the T6 ASIC: +.Pp +.Bl -bullet -compact +.It +Chelsio T6225-CR +.It +Chelsio T6225-SO-CR +.It +Chelsio T62100-LP-CR +.It +Chelsio T62100-SO-CR +.It +Chelsio T62100-CR +.El +.Sh SUPPORT +For general information and support, +go to the Chelsio support website at: +.Pa http://www.chelsio.com/ . +.Pp +If an issue is identified with this driver with a supported adapter, +email all the specific information related to the issue to +.Aq Mt support@chelsio.com . +.Sh SEE ALSO +.Xr crypto 4 , +.Xr cxgbe 4 , +.Xr geli 4 , +.Xr ipsec 4 , +.Xr ktls 4 , +.Xr crypto 7 , +.Xr crypto 9 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 12.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An John Baldwin Aq Mt jhb@FreeBSD.org . diff --git a/static/freebsd/man4/cd.4 b/static/freebsd/man4/cd.4 new file mode 100644 index 00000000..02bf96db --- /dev/null +++ b/static/freebsd/man4/cd.4 @@ -0,0 +1,361 @@ +.\" Copyright (c) 1996 +.\" Julian Elischer . 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 April 8, 2022 +.Dt CD 4 +.Os +.Sh NAME +.Nm cd +.Nd SCSI CD-ROM driver +.Sh SYNOPSIS +.Cd device cd +.Sh DESCRIPTION +The +.Nm +driver provides support for a +.Tn SCSI +.Tn CD-ROM +(Compact Disc-Read Only Memory) drive. +In an attempt to look like a regular disk, the +.Nm +driver synthesizes a partition table, with one partition covering the entire +.Tn CD-ROM . +It is possible to modify this partition table using +.Xr disklabel 8 , +but it will only last until the +.Tn CD-ROM +is unmounted. +In general the interfaces are similar to those described by +.Xr ada 4 +and +.Xr da 4 . +.Pp +As the +.Tn SCSI +adapter is probed during boot, the +.Tn SCSI +bus is scanned for devices. +Any devices found which answer as CDROM +(type 5) or WORM (type 4) type devices will be `attached' to the +.Nm +driver. +Prior to +.Fx 2.1 , +the first device found will be attached as +.Li cd0 +the next, +.Li cd1 , +etc. +Beginning in +.Fx 2.1 +it is possible to specify what cd unit a device should +come on line as; refer to +.Xr scsi 4 +for details on kernel configuration. +.Pp +The system utility +.Xr disklabel 8 +may be used to read the synthesized +disk label +structure, which will contain correct figures for the size of the +.Tn CD-ROM +should that information be required. +.Sh KERNEL CONFIGURATION +Any number of +.Tn CD-ROM +devices may be attached to the system regardless of system +configuration as all resources are dynamically allocated. +.Sh IOCTLS +The following +.Xr ioctl 2 +calls which apply to +.Tn SCSI +.Tn CD-ROM +drives are defined +in the header files +.In sys/cdio.h +and +.In sys/disklabel.h . +.Bl -tag -width CDIOCREADSUBCHANNEL +.It Dv CDIOCPLAYTRACKS +.Pq Li "struct ioc_play_track" +Start audio playback given a track address and length. +The structure is defined as follows: +.Bd -literal -offset indent +struct ioc_play_track +{ + u_char start_track; + u_char start_index; + u_char end_track; + u_char end_index; +}; +.Ed +.It Dv CDIOCPLAYBLOCKS +.Pq Li "struct ioc_play_blocks" +Start audio playback given a block address and length. +The structure is defined as follows: +.Bd -literal -offset indent +struct ioc_play_blocks +{ + int blk; + int len; +}; +.Ed +.It Dv CDIOCPLAYMSF +.Pq Li "struct ioc_play_msf" +Start audio playback given a `minutes-seconds-frames' address and +length. +The structure is defined as follows: +.Bd -literal -offset indent +struct ioc_play_msf +{ + u_char start_m; + u_char start_s; + u_char start_f; + u_char end_m; + u_char end_s; + u_char end_f; +}; +.Ed +.It Dv CDIOCREADSUBCHANNEL +.Pq Li "struct ioc_read_subchannel" +Read information from the subchannel at the location specified by this +structure: +.Bd -literal -offset indent +struct ioc_read_subchannel { + u_char address_format; +#define CD_LBA_FORMAT 1 +#define CD_MSF_FORMAT 2 + u_char data_format; +#define CD_SUBQ_DATA 0 +#define CD_CURRENT_POSITION 1 +#define CD_MEDIA_CATALOG 2 +#define CD_TRACK_INFO 3 + u_char track; + int data_len; + struct cd_sub_channel_info *data; +}; +.Ed +.It Dv CDIOREADTOCHEADER +.Pq Li "struct ioc_toc_header" +Return summary information about the table of contents for the mounted +.Tn CD-ROM . +The information is returned into the following structure: +.Bd -literal -offset indent +struct ioc_toc_header { + u_short len; + u_char starting_track; + u_char ending_track; +}; +.Ed +.It Dv CDIOREADTOCENTRYS +.Pq Li "struct ioc_read_toc_entry" +Return information from the table of contents entries mentioned. +.Pq Yes, this command name is misspelled. +The argument structure is defined as follows: +.Bd -literal -offset indent +struct ioc_read_toc_entry { + u_char address_format; + u_char starting_track; + u_short data_len; + struct cd_toc_entry *data; +}; +.Ed +The requested data is written into an area of size +.Li data_len +and pointed to by +.Li data . +.It Dv CDIOCSETPATCH +.Pq Li "struct ioc_patch" +Attach various audio channels to various output channels. +The argument structure is defined thusly: +.Bd -literal -offset indent +struct ioc_patch { + u_char patch[4]; + /* one for each channel */ +}; +.Ed +.It Dv CDIOCGETVOL +.It Dv CDIOCSETVOL +.Pq Li "struct ioc_vol" +Get (set) information about the volume settings of the output channels. +The argument structure is as follows: +.Bd -literal -offset indent +struct ioc_vol +{ + u_char vol[4]; + /* one for each channel */ +}; +.Ed +.It Dv CDIOCSETMONO +Patch all output channels to all source channels. +.It Dv CDIOCSETSTEREO +Patch left source channel to the left output channel and the right +source channel to the right output channel. +.It Dv CDIOCSETMUTE +Mute output without changing the volume settings. +.It Dv CDIOCSETLEFT +.It Dv CDIOCSETRIGHT +Attach both output channels to the left (right) source channel. +.It Dv CDIOCSETDEBUG +.It Dv CDIOCCLRDEBUG +Turn on (off) debugging for the appropriate device. +.It Dv CDIOCPAUSE +.It Dv CDIOCRESUME +Pause (resume) audio play, without resetting the location of the read-head. +.It Dv CDIOCRESET +Reset the drive. +.It Dv CDIOCSTART +.It Dv CDIOCSTOP +Tell the drive to spin-up (-down) the +.Tn CD-ROM . +.It Dv CDIOCALLOW +.It Dv CDIOCPREVENT +Tell the drive to allow (prevent) manual ejection of the +.Tn CD-ROM +disc. +Not all drives support this feature. +.It Dv CDIOCEJECT +Eject the +.Tn CD-ROM . +.It Dv CDIOCCLOSE +Tell the drive to close its door and load the media. +Not all drives support this feature. +.El +.Sh NOTES +When a +.Tn CD-ROM +is changed in a drive controlled by the +.Nm +driver, then the act of changing the media will invalidate the +disklabel and information held within the kernel. +To stop corruption, +all accesses to the device will be discarded until there are no more +open file descriptors referencing the device. +During this period, all +new open attempts will be rejected. +When no more open file descriptors +reference the device, the first next open will load a new set of +parameters (including disklabel) for the drive. +.Pp +The audio code in the +.Nm +driver only support +.Tn SCSI-2 +standard audio commands. +As many +.Tn CD-ROM +manufacturers have not followed the standard, there are many +.Tn CD-ROM +drives for which audio will not work. +Some work is planned to support +some of the more common `broken' +.Tn CD-ROM +drives; however, this is not yet under way. +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width 12 +.It kern.cam.cd.retry_count +.Pp +This variable determines how many times the +.Nm +driver will retry a READ or WRITE command. +This does not affect the number of retries used during probe time or for +the +.Nm +driver dump routine. +This value currently defaults to 4. +.It kern.cam.cd.%d.minimum_cmd_size +.Pp +The +.Nm +driver attempts to automatically determine whether the drive it is talking +to supports 6 byte or 10 byte MODE SENSE/MODE SELECT operations. +Many +.Tn SCSI +drives only support 6 byte commands, and +.Tn ATAPI +drives only support 10 byte commands. +The +.Nm +driver first attempts to determine whether the protocol in use typically +supports 6 byte commands by issuing a CAM Path Inquiry CCB. +It will then default to 6 byte or 10 byte commands as appropriate. +After that, the +.Nm +driver defaults to using 6 byte commands (assuming the protocol the drive +speaks claims to support 6 byte commands), until one fails with a +.Tn SCSI +ILLEGAL REQUEST error. +Then it tries the 10 byte version of the command to +see if that works instead. +Users can change the default via per-drive +sysctl variables and loader tunables. +Where +.Dq %d +is the unit number of the drive in question. +Valid minimum command sizes +are 6 and 10. +Any value above 6 will be rounded to 10, and any value below +6 will be rounded to 6. +.El +.Sh FILES +.Bl -tag -width /dev/cd[0-9][a-h] -compact +.It Pa /dev/cd[0-9][a-h] +raw mode +.Tn CD-ROM +devices +.El +.Sh DIAGNOSTICS +None. +.Sh SEE ALSO +.Xr cam 4 , +.Xr cd9660 4 , +.Xr da 4 , +.Xr disklabel 8 , +.Xr cd 9 +.Sh HISTORY +This +.Nm +driver is based upon the +.Nm +driver written by Julian Elischer, which appeared in +.Bx 386 0.1 . +The +CAM version of the +.Nm +driver was written by Kenneth Merry and first appeared in +.Fx 3.0 . +.Sh BUGS +The names of the structures used for the third argument to +.Fn ioctl +were poorly chosen, and a number of spelling errors have survived in +the names of the +.Fn ioctl +commands. diff --git a/static/freebsd/man4/cd9660.4 b/static/freebsd/man4/cd9660.4 new file mode 100644 index 00000000..a684df37 --- /dev/null +++ b/static/freebsd/man4/cd9660.4 @@ -0,0 +1,84 @@ +.\" +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" Copyright (c) 2017 Enji Cooper +.\" +.\" 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. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission +.\" +.\" THIS DOCUMENTATION 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 January 18, 2025 +.Dt CD9660 4 +.Os +.Sh NAME +.Nm cd9660 +.Nd "ISO-9660 file system" +.Sh SYNOPSIS +To link into the kernel: +.Bd -ragged -offset indent +.Cd "options CD9660" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +cd9660_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver will permit the +.Fx +kernel to access the +.Tn cd9660 +file system. +.Sh EXAMPLES +To mount a +.Nm +volume located on +.Pa /dev/cd0 : +.Pp +.Dl "mount -t cd9660 /dev/cd0 /mnt" +.Sh SEE ALSO +.Xr etdump 1 , +.Xr nmount 2 , +.Xr unmount 2 , +.Xr cd 4 , +.Xr fstab 5 , +.Xr mount 8 , +.Xr mount_cd9660 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Bx 4.4 Lite . +.Sh AUTHORS +.An -nosplit +The +.Nm +kernel implementation was originally written by +.An Pace Willisson Aq Mt pace@blitz.com +and +.An Atsushi Murai Aq Mt amurai@spec.co.jp . +.Pp +This manual page was written by +.An Enji Cooper Aq Mt ngie@FreeBSD.org . diff --git a/static/freebsd/man4/cdce.4 b/static/freebsd/man4/cdce.4 new file mode 100644 index 00000000..3f1d9200 --- /dev/null +++ b/static/freebsd/man4/cdce.4 @@ -0,0 +1,195 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2004 Daniel Hartmeier +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" - Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" - 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 COPYRIGHT HOLDERS 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 +.\" COPYRIGHT HOLDERS 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. +.\" +.\" $NetBSD: cdce.4,v 1.4 2004/12/08 18:35:56 peter Exp $ +.\" +.Dd December 23, 2025 +.Dt CDCE 4 +.Os +.Sh NAME +.Nm cdce +.Nd USB Communication Device Class Ethernet (ECM/NCM) driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device uhci" +.Cd "device ohci" +.Cd "device usb" +.Cd "device miibus" +.Cd "device uether" +.Cd "device cdce" +.Ed +.Pp +Mobile Devices (e.g., Huawei E3372, E5573 and others) +may need additionally the u3g command port: +.Bd -ragged -offset indent +.Cd "device ucom" +.Cd "device u3g" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_cdce_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for USB Host-to-Host (aka USB-to-USB) and +USB-to-Ethernet bridges based on the USB Communication Device Class +Ethernet Control Model (CDC ECM) and Network Control Model (CDC NCM) +specifications. +It also provides device-side CDC ECM support. +.Pp +The USB bridge appears as a regular network interface on both sides, +transporting Ethernet frames. +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Pp +USB 1.x bridges support speeds of up to 12Mbps, and USB 2.0 speeds of +up to 480Mbps. +.Pp +Packets are +received and transmitted over separate USB bulk transfer endpoints. +.Pp +The +.Nm +driver does not support different media types or options. +.Sh HARDWARE +The +.Nm +driver supports USB Ethernet interfaces implementing the +USB Communication Device Class Ethernet Control Model (CDC ECM) or +Network Control Model (CDC NCM) protocol, such as: +.Pp +.Bl -bullet -compact +.It +Android USB tethering +.It +iPhone USB tethering +.It +Realtek RTL8153 USB 3.0 to Gigabit Ethernet controller +.It +Prolific PL-2501 Host-to-Host Bridge controller +.It +Sharp Zaurus PDA +.It +Terayon TJ-715 DOCSIS Cable Modem +.It +Huawei 3G/4G LTE (e.g., E3372, E5573) and other mobile network devices +.El +.Sh EXAMPLES +Mobile +.Nm +Network Devices may need a connect command sequence via the +.Xr u3g 4 +serial command port before activating the NCM/ECM/ACM network interface. +For example: +.Pp +.Dl echo 'AT^NDISUP=1,1,"internet"' > /dev/cuaU[0].0 +.Pp +Wwhere +.Dq internet +is your providers apn name. +.Sh DIAGNOSTICS +.Bl -diag +.It "cdce%d: no union descriptor" +The driver could not fetch an interface descriptor from the USB +device. +For a manually added USB vendor/product, the CDCE_NO_UNION flag +can be tried to work around the missing descriptor. +.It "cdce%d: no data interface" +.It "cdce%d: could not read endpoint descriptor" +.It "cdce%d: unexpected endpoint" +.It "cdce%d: could not find data bulk in/out" +For a manually added USB vendor/product, these errors indicate +that the bridge is not compatible with the driver. +.It "cdce%d: watchdog timeout" +A packet was queued for transmission and a transmit command was +issued, however the device failed to acknowledge the transmission +before a timeout expired. +.It "cdce%d: no memory for rx list -- packet dropped!" +Memory allocation through MGETHDR or MCLGET failed, the system +is running low on mbufs. +.It "cdce%d: abort/close rx/tx pipe failed" +.It "cdce%d: rx/tx list init failed" +.It "cdce%d: open rx/tx pipe failed" +.It "cdce%d: usb error on rx/tx" +.El +.Sh SEE ALSO +.Xr arp 4 , +.Xr cdceem 4 , +.Xr intro 4 , +.Xr ipheth 4 , +.Xr netintro 4 , +.Xr u3g 4 , +.Xr ucom 4 , +.Xr urndis 4 , +.Xr usb 4 , +.Xr ifconfig 8 +.Rs +.%T "Universal Serial Bus Class Definitions for Communication Devices" +.%U http://www.usb.org/developers/devclass_docs/usbcdc11.pdf +.Re +.Rs +.%T "Data sheet Prolific PL-2501 Host-to-Host Bridge/Network Controller" +.%U http://tech.prolific.com.tw/visitor/fcabdl.asp?fid=20679530 +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Ox 3.6 , +.Nx 3.0 +and +.Fx 6.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Craig Boston Aq Mt craig@tobuj.gank.org +based on the +.Xr aue 4 +driver written by +.An Bill Paul Aq Mt wpaul@windriver.com +and ported to +.Ox +by +.An Daniel Hartmeier Aq Mt dhartmei@openbsd.org . +.Sh CAVEATS +Many USB devices notoriously fail to report their class and interfaces +correctly. +Undetected products might work flawlessly when their vendor and product IDs +are added to the driver manually. diff --git a/static/freebsd/man4/cdceem.4 b/static/freebsd/man4/cdceem.4 new file mode 100644 index 00000000..c2a28202 --- /dev/null +++ b/static/freebsd/man4/cdceem.4 @@ -0,0 +1,120 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2019 Edward Tomasz Napierala +.\" +.\" 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 September 18, 2025 +.Dt CDCEEM 4 +.Os +.Sh NAME +.Nm cdceem +.Nd USB Communication Device Class Ethernet Emulation Model driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device uhci" +.Cd "device ohci" +.Cd "device usb" +.Cd "device miibus" +.Cd "device uether" +.Cd "device cdceem" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_cdceem_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for USB devices based on the USB Communication +Device Class Ethernet Emulation Model (CDC EEM) specification. +.Pp +The driver works on both host, and device-side; see +.Xr usb_template 4 +for details. +.Pp +The USB device appears as a regular network interface on both sides, +transporting Ethernet frames. +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Pp +The +.Nm +driver does not support different media types or options. +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va hw.usb.cdceem.debug +Verbosity level for log messages from the +.Nm +driver. +Set to 0 to disable logging or 1 to warn about potential problems. +Larger values enable debugging output. +Defaults to 1. +.It Va hw.usb.cdceem.send_echoes +If set to 1, the driver will send an Echo EEM packet when the +interface is brought up. +While responding to Echo is mandatory, some devices cannot handle it. +Only use for debugging. +Defaults to 0. +.It Va hw.usb.cdceem.send_fake_crc +If set to 1, the driver will use 0xdeadbeef as the CRC value +for outgoing Data EEM packets. +Only use for debugging. +Defaults to 0. +.El +.Sh SEE ALSO +.Xr arp 4 , +.Xr cdce 4 , +.Xr intro 4 , +.Xr ipheth 4 , +.Xr netintro 4 , +.Xr urndis 4 , +.Xr usb 4 , +.Xr usb_template 4 , +.Xr ifconfig 8 +.Rs +.%T "Universal Serial Bus Communications Class Subclass Specification for Ethernet Emulation Model Devices" +.%U https://usb.org/sites/default/files/CDC_EEM10.pdf +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 12.1 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org +under sponsorship from Hewlett Packard Enterprise. diff --git a/static/freebsd/man4/cfi.4 b/static/freebsd/man4/cfi.4 new file mode 100644 index 00000000..3527047e --- /dev/null +++ b/static/freebsd/man4/cfi.4 @@ -0,0 +1,91 @@ +.\"- +.\" Copyright (c) 2015-2016 SRI International +.\" All rights reserved. +.\" +.\" This software was developed by SRI International and the University of +.\" Cambridge Computer Laboratory under DARPA/AFRL contract (FA8750-10-C-0237) +.\" ("CTSRD"), as part of the DARPA CRASH research programme. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 20, 2016 +.Dt CFI 4 +.Os +.Sh NAME +.Nm cfi , +.Nm cfid +.Nd driver for Common Flash Interface (CFI) NOR flash +.Sh SYNOPSIS +.Cd "device cfi" +.Cd "device cfid" +.Cd "options CFI_SUPPORT_STRATAFLASH" +.Cd "options CFI_ARMEDANDDANGEROUS" +.Pp +In +.Pa /boot/device.hints : +.Cd hint.cfi.0.at="nexus0" +.Cd hint.cfi.0.maddr=0x74000000 +.Cd hint.cfi.0.msize=0x4000000 +.Pp +In DTS file: +.Cd flash@74000000 { +.Cd " compatible =" Qo cfi-flash Qc ; +.Cd " reg = <0x74000000 0x4000000>;" +.Cd }; +.Sh DESCRIPTION +The +.Nm +device driver provides a management interface to NOR flash devices supporting +the Common Flash Interface (CFI) specification. +Its companion device +.Nm cfid +provides a +.Xr geom 4 +disk interface to the device. +.Pp +Special support for features of the Intel StrataFlash line are available +with the +.Cd CFI_SUPPORT_STRATAFLASH +kernel option. +Additional support for write-once bits to switch part of Intel StrataFlash +devices to read-only can be enabled by the +.Cd CFI_ARMEDANDDANGEROUS +kernel option. +.Sh SEE ALSO +.Xr led 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 8.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Juniper Networks +with StrataFlash support by +.An Sam Leffler . +This manual page was written by SRI International and the University of +Cambridge Computer Laboratory under DARPA/AFRL contract +.Pq FA8750-10-C-0237 +.Pq Do CTSRD Dc , +as part of the DARPA CRASH research programme. diff --git a/static/freebsd/man4/cfiscsi.4 b/static/freebsd/man4/cfiscsi.4 new file mode 100644 index 00000000..dbf8ed5f --- /dev/null +++ b/static/freebsd/man4/cfiscsi.4 @@ -0,0 +1,109 @@ +.\" Copyright (c) 2013 Edward Tomasz Napierala +.\" Copyright (c) 2015-2017 Alexander Motin +.\" Copyright (c) 2017 Enji Cooper +.\" +.\" 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 May 28, 2017 +.Dt CFISCSI 4 +.Os +.Sh NAME +.Nm cfiscsi +.Nd CAM Target Layer iSCSI target frontend +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device cfiscsi" +.Cd "device ctl" +.Cd "device iscsi" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +cfiscsi_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +subsystem provides the kernel component of an iSCSI target. +The target is the iSCSI server, providing LUNs backed by local files +and volumes to remote initiators. +The userspace component is provided by +.Xr ctld 8 . +.Nm +is implemented as a +.Xr ctl 4 +frontend and uses infrastructure provided by +.Xr iscsi 4 . +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va kern.cam.ctl.iscsi.debug +Verbosity level for log messages from the kernel part of iSCSI target. +Set to 0 to disable logging or 1 to warn about potential problems. +Larger values enable debugging output. +Defaults to 1. +.It Va kern.cam.ctl.iscsi.maxtags +The number of outstanding commands to advertise to each iSCSI initiator. +Current implementation is not very accurate, so do not set this below 2. +Defaults to 256. +.It Va kern.cam.ctl.iscsi.ping_timeout +The number of seconds to wait for the iSCSI initiator to respond to a NOP-In +PDU. +In the event that there is no response within that time the session gets +forcibly terminated. +Set to 0 to disable sending NOP-In PDUs. +Defaults to 5. +.El +.Sh SEE ALSO +.Xr ctl 4 , +.Xr iscsi 4 , +.Xr ctl.conf 5 , +.Xr ctld 8 +.Sh HISTORY +The +.Nm +subsystem first appeared in +.Fx 10.0 +as part of the +.Xr ctl 4 +driver. +It was split off of +.Xr ctl 4 +in +.Fx 12.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +subsystem was developed by +.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org +under sponsorship from the FreeBSD Foundation. +This manual page was written by +.An Enji Cooper Aq Mt ngie@FreeBSD.org . diff --git a/static/freebsd/man4/cfumass.4 b/static/freebsd/man4/cfumass.4 new file mode 100644 index 00000000..bde9b2d6 --- /dev/null +++ b/static/freebsd/man4/cfumass.4 @@ -0,0 +1,141 @@ +.\" Copyright (c) 2017 The FreeBSD Foundation +.\" +.\" This software was developed by Edward Tomasz Napierala under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.Dd April 21, 2018 +.Dt CFUMASS 4 +.Os +.Sh NAME +.Nm cfumass +.Nd USB device side support for Mass Storage Class Transport +.Sh SYNOPSIS +This driver can be compiled into the kernel by placing these lines in +the kernel configuration file: +.Bd -ragged -offset indent +.Cd "device usb" +.Cd "device usb_template" +.Cd "device ctl" +.Cd "device cfumass" +.Ed +.Pp +The driver module can also be loaded at boot by adding this line to +.Xr loader.conf 5 : +.Bd -literal -offset indent +cfumass_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides device side support for emulating an USB mass storage +device compliant with the USB Mass Storage Class Bulk-Only (BBB) Transport +specification, implemented as a +.Xr ctl 4 +frontend driver. +.Pp +To use +.Nm : +.Bl -bullet +.It +.Nm cfumass +must be loaded as a module or compiled into the kernel. +.It +The USB Mass Storage template must be chosen by setting the +.Va hw.usb.template +sysctl to 0. +.It +The USB OTG port must be working in USB device-side mode. +This happens automatically upon connection to a USB host. +.It +There must be a +.Xr ctl 4 +LUN configured for the +.Pa cfumass +port. +.El +.Pp +Upon loading, the driver creates a +.Xr ctl 4 +port named +.Pa cfumass , +presenting the first LUN mapped for that port - usually LUN 0 - to +the USB host. +See +.Xr ctl.conf 5 +and +.Xr ctld 8 +for details on configuring the LUN. +See the +.Cm cfumass_enable +and +.Cm cfumass_dir +.Xr rc 8 +variables in +.Xr rc.conf 5 +for an automated way to configure it at boot. +.Sh SYSCTL VARIABLES +These variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va hw.usb.cfumass.debug +Verbosity level for log messages from the +.Nm +driver. +Set to 0 to disable logging or 1 to warn about potential problems. +Larger values enable debugging output. +Defaults to 1. +.It Va hw.usb.cfumass.ignore_stop +Ignore START STOP UNIT SCSI commands with START and LOEJ bits cleared. +Some initiators send that command to stop the target when the user +attempts to gracefully eject the drive, but fail to start it when the +drive is reconnected. +Set to 0 to handle the command in a standards-compliant way, +1 to ignore it and log a warning, or 2 to ignore it silently. +Defaults to 1. +.It Va hw.usb.cfumass.max_lun +Max LUN number to report to the initiator (USB host). +Must be between 0 and 15. +Some initiators incorrectly handle values larger than 0. +Defaults to 0. +.El +.Sh SEE ALSO +.Xr ctl 4 , +.Xr umass 4 , +.Xr usb 4 , +.Xr usb_template 4 , +.Xr ctl.conf 5 , +.Xr ctld 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 11.1 . +.Sh AUTHORS +The +.Nm +driver was developed by +.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org +under sponsorship from the FreeBSD Foundation. diff --git a/static/freebsd/man4/cgem.4 b/static/freebsd/man4/cgem.4 new file mode 100644 index 00000000..1ca4f8fa --- /dev/null +++ b/static/freebsd/man4/cgem.4 @@ -0,0 +1,300 @@ +.\" +.\" Copyright (c) 2014 Thomas Skibo +.\" 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. 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 AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 10, 2021 +.Dt CGEM 4 +.Os +.Sh NAME +.Nm cgem +.Nd "Cadence GEM Gigabit Ethernet driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ether" +.Cd "device miibus" +.Cd "device cgem" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the Cadence GEM (Gigabit Ethernet MAC). +The Cadence GEM is used in some SoC (System on a Chip) devices such as +the Xilinx Zynq-7000, the Xilinx Zynq UltraScale+, and the SiFive +HiFive Unleashed. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width ".Cm 10baseT/UTP" +.It Cm autoselect +Enable autoselection of the media type and options. +The user can manually override +the autoselected mode using +.Xr ifconfig 8 +or by adding media options to +.Xr rc.conf 5 . +.It Cm 10baseT/UTP +Set 10Mbps operation. +The +.Xr ifconfig 8 +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 100baseTX +Set 100Mbps (Fast Ethernet) operation. +The +.Xr ifconfig 8 +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 1000baseT +Set 1000Mbps (Gigabit Ethernet) operation over twisted pair. +The GEM supports 1000Mbps in +.Cm full-duplex +mode only. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width ".Cm full-duplex" +.It Cm full-duplex +Force full-duplex operation. +.It Cm half-duplex +Force half-duplex operation. +.El +.Pp +The driver provides support for TCP/UDP/IP checksum offloading (although +disabled by default). +The device and driver also support 1536-byte frames for VLANs (vlanmtu). +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width "xxxxxxxx" +.It Va dev.cgem.%d.rxbufs +The number of receive buffers allocated to the hardware. +The default value is 256. +The maximum value is 511. +If this number is increased while the interface is UP, it will not +take effect until the next packet is received. +If this number is decreased while the interface is UP, buffers will +not be immediately removed from the receive buffer ring but the +number of buffers will decrease as packets are received until it +reaches the new value. +.It Va dev.cgem.%d.rxhangwar +This tunable enables a work-around to recover from receive hangs. +The default value is 1. +Set to 0 to disable the work-around. +.El +.Pp +The following read-only variables are available as +.Xr sysctl 8 +variables: +.Bl -tag -width "xxxxxxxx" +.It Va dev.cgem.%d._rxoverruns +This variable counts the number of receive packet buffer overrun interrupts. +.It Va dev.cgem.%d._rxnobufs +This variable counts the number of interrupts due to the GEM buffer ring +going empty. +.It Va dev.cgem.%d._rxdmamapfails +This variable is the number of times bus_dmamap_load_mbuf_sg(9) failed in +the receive path. +.It Va dev.cgem.%d._txfull +The number of times the GEM's transmit ring was full. +.It Va dev.cgem.%d._txdmamapfails +This variable is the number of times bus_dmamap_load_mbuf_sg(9) failed in +the transmit path. +.It Va dev.cgem.%d._txdefrags +This variable is the number of times the driver needed to call m_defrag(9) +because a packet queued for transmit had too many DMA segments. +.It Va dev.cgem.%d._txdefragfails +This variable is the number of times +.Xr m_defrag 9 +failed. +.It Va dev.cgem.%d.stats.* +The following variables are useful MAC counters supplied by the hardware: +.It Va dev.cgem.%d.stats.tx_bytes +A 64-bit counter of the number of bytes transmitted in frames without error. +.It Va dev.cgem.%d.stats.tx_frames +Counter of frames transmitted without error excluding pause frames. +.It Va dev.cgem.%d.stats.tx_frames_bcast +Counter of broadcast frames transmitted without error excluding +pause frames. +.It Va dev.cgem.%d.stats.tx_frames_multi +Counter of multicast frames transmitted without error excluding +pause frames. +.It Va dev.cgem.%d.stats.tx_frames_pause +Counter of pause frames transmitted without error. +.It Va dev.cgem.%d.stats.tx_frames_64b +Counter of 64 byte frames transmitted without error. +.It Va dev.cgem.%d.stats.tx_frames_65to127b +Counter of 65 to 127 byte frames transmitted without error. +.It Va dev.cgem.%d.stats.tx_frames_128to255b +Counter of 128 to 255 byte frames transmitted without error. +.It Va dev.cgem.%d.stats.tx_frames_256to511b +Counter of 256 to 511 byte frames transmitted without error. +.It Va dev.cgem.%d.stats.tx_frames_512to1023b +Counter of 512 to 1023 byte frames transmitted without error. +.It Va dev.cgem.%d.stats.tx_frames_1024to1536b +Counter of 1024 to 1536 byte frames transmitted without error. +.It Va dev.cgem.%d.stats.tx_under_runs +Counter of frames not transmitted due to a transmit underrun. +.It Va dev.cgem.%d.stats.tx_single_collisn +Counter of frames experiencing a single collision before being successfully +transmitted. +.It Va dev.cgem.%d.stats.tx_multi_collisn +Counter of frames experiencing between 2 and 15 collisions before +being successfully transmitted. +.It Va dev.cgem.%d.stats.tx_excsv_collisn +Counter of frames that failed to transmit because they experienced 16 +collisions. +.It Va dev.cgem.%d.stats.tx_late_collisn +Counter of frames that experienced a late collision. +.It Va dev.cgem.%d.stats.tx_deferred_frames +Counter of frames experiencing deferral due to carrier sense being +active on their first attempt at transmission. +.It Va dev.cgem.%d.stats.tx_carrier_sense_errs +Counter of frames transmitted where carrier sense was not seen during +transmission or where carrier sense was deasserted after being asserted +in a transmit frame without collision. +.It Va dev.cgem.%d.stats.rx_bytes +A 64-bit counter of bytes received without error excluding pause +frames. +.It Va dev.cgem.%d.stats.rx_frames +Counter of frames received without error excluding pause frames. +.It Va dev.cgem.%d.stats.rx_frames_bcast +Counter of broadcast frames receive without error excluding pause frames. +.It Va dev.cgem.%d.stats.rx_frames_multi +Counter of multicast frames receive without error excluding pause frames. +.It Va dev.cgem.%d.stats.rx_frames_pause +Counter of pause frames received without error. +.It Va dev.cgem.%d.stats.rx_frames_64b +Counter of 64-byte frames received without error. +.It Va dev.cgem.%d.stats.rx_frames_65to127b +Counter of 65 to 127 byte frames received without error. +.It Va dev.cgem.%d.stats.rx_frames_128to255b +Counter of 128 to 255 byte frames received without error. +.It Va dev.cgem.%d.stats.rx_frames_256to511b +Counter of 256 to 511 byte frames received without error. +.It Va dev.cgem.%d.stats.rx_frames_512to1023b +Counter of 512 to 1023 byte frames received without error. +.It Va dev.cgem.%d.stats.rx_frames_1024to1536b +Counter of 1024 to 1536 byte frames received without error. +.It Va dev.cgem.%d.stats.rx_frames_undersize +Counter of frames received less than 64 bytes in length that +do not also have either a CRC error or an alignment error. +.It Va dev.cgem.%d.stats.rx_frames_oversize +Counter of frames received exceeding 1536 bytes and do not also have either +a CRC error or an alignment error. +.It Va dev.cgem.%d.stats.rx_frames_jabber +Counter of frames received exceeding 1536 bytes and also have either a CRC +error, an alignment error, or a receive symbol error. +.It Va dev.cgem.%d.stats.rx_frames_fcs_errs +Counter of frames received with a bad CRC and are between 64 +and 1536 bytes. +.It Va dev.cgem.%d.stats.rx_frames_length_errs +Counter of frames received that are shorter than that extracted +from the length field. +.It Va dev.cgem.%d.stats.rx_symbol_errs +Counter of receive symbol errors. +.It Va dev.cgem.%d.stats.rx_align_errs +Counter of received frames that are not an integral number of bytes. +.It Va dev.cgem.%d.stats.rx_resource_errs +Counter of frames successfully receive by the MAC but could not be +copied to memory because no receive buffer was available. +.It Va dev.cgem.%d.stats.rx_overrun_errs +Counter of frames that are address recognized but were not copied +to memory due to a receive overrun. +.It Va dev.cgem.%d.stats.rx_frames_ip_hdr_csum_errs +Counter of frames discarded due to an incorrect IP header checksum when +checksum offloading is enabled. +.It Va dev.cgem.%d.stats.rx_frames_tcp_csum_errs +Counter of frames discarded due to an incorrect TCP checksum when +checksum offloading is enabled. +.It Va dev.cgem.%d.stats.rx_frames_udp_csum_errs +Counter of frames discarded due to an incorrect UDP checksum when +checksum offloading is enabled. +.El +.Sh SEE ALSO +.Xr miibus 4 , +.Xr ifconfig 8 +.Rs +.%T "Zynq-7000 SoC Technical Reference Manual (Xilinx doc UG585)" +.%U http://www.xilinx.com/support/documentation/user_guides/\:ug585-Zynq-7000-TRM.pdf +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 10.0 . +.Sh AUTHORS +The +.Nm +driver and this manual page was written by +.An Thomas Skibo Aq Mt thomasskibo@yahoo.com . +.Sh BUGS +The GEM can perform TCP/UDP/IP checksum offloading. +However, when transmit checksum offloading is enabled, the GEM generates and +replaces checksums for all packets it transmits. +In a system that is forwarding packets, the device could potentially correct +the checksum of packet that was corrupted in transit. +For this reason, checksum offloading is disabled by default but can be +enabled using ifconfig(8). +.Pp +When receive checksum offloading is enabled, the device will discard packets +with bad TCP/UDP/IP checksums. +The bad packets will not be counted in any +.Xr netstat 1 +statistics. +There are +.Xr sysctl 8 +variables that count +packets discarded by the hardware (see below). +.Pp +The GEM used in the Zynq-7000 has a bug such that the receiver can +potentially freeze up under a high load. +The issue is described in sec. 16.7 +"Known Issues" of the Zynq-7000 SoC Technical Reference Manual (Xilinx +UG585 v1.7). +The +.Nm +driver implements the work-around suggested in the manual. +It is believed that the bug does not exist in the Zynq UltraScale+ and +SiFive SoCs so the work-around is disabled in those instances and enabled +in all others. +The work-around can be disabled by setting the +.Va dev.cgem.%d.rxhangwar +.Xr sysctl 8 +variable to 0. diff --git a/static/freebsd/man4/ch.4 b/static/freebsd/man4/ch.4 new file mode 100644 index 00000000..a0a5f97b --- /dev/null +++ b/static/freebsd/man4/ch.4 @@ -0,0 +1,351 @@ +.\" Copyright (c) 1996 +.\" Julian Elischer . 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 May 14, 1998 +.Dt CH 4 +.Os +.Sh NAME +.Nm ch +.Nd SCSI media-changer (juke box) driver +.Sh SYNOPSIS +.Cd device ch +.Sh DESCRIPTION +The +.Nm +driver provides support for a +.Em SCSI +media changer. +It allows many slots of media to be multiplexed between +a number of drives. +The changer device may optionally be equipped +with a bar code reader, which reads label information attached to +the media. +.Pp +A SCSI adapter must also be separately configured into the system +before a SCSI changer can be configured. +.Pp +As the SCSI adapter is probed during boot, the +.Em SCSI +bus is scanned for devices. +Any devices found which answer as 'Changer' +type devices will be 'attached' to the +.Nm +driver. +In +.Fx +releases prior to 2.1, the first found will be attached as +.Em ch0 +and the next, +.Em ch1 +etc. +Beginning in 2.1 it is possible to specify what ch unit a device should +come on line as; refer to +.Xr scsi 4 +for details on kernel configuration. +.Sh KERNEL CONFIGURATION +It is only necessary to explicitly configure one +.Nm +device; data structures are dynamically allocated as media changes are found +on the +.Tn SCSI +bus. +.Sh IOCTLS +User mode programs communicate with the changer driver through a +number of ioctls which are described below. +Changer element addresses +used in the communication between the kernel and the changer device are +mapped to zero-based logical addresses. +Element types are specified as follows: +.Bl -tag -width CHET_MT +.It Dv CHET_MT +Medium transport element (picker). +.It Dv CHET_ST +Storage element (slot). +.It Dv CHET_IE +Import/export element (portal). +.It Dv CHET_DT +Data transfer element (drive). +.El +.Pp +The following +.Xr ioctl 2 +calls apply to the changer. +They are defined +in the header file +.In sys/chio.h . +.Bl -tag -width CHIOEXCHANGE +.It Dv CHIOMOVE +.Pq Vt "struct changer_move" +Move a medium from one element to another +.Pq Sy "MOVE MEDIUM" +using the current picker. +The source and destination elements are specified +in a changer_move structure, which includes at least the following +fields: +.Bd -literal -offset indent +u_int cm_fromtype; /* element type to move from */ +u_int cm_fromunit; /* logical unit of from element */ +u_int cm_totype; /* element type to move to */ +u_int cm_tounit; /* logical unit of to element */ +u_int cm_flags; /* misc. flags */ +.Ed +If the +.Dv CM_INVERT +in the +.Va cm_flags +field is set, the medium +changer is instructed to flip the medium while moving it. +.It Dv CHIOEXCHANGE +.Pq Vt "struct changer_exchange" +Move the medium located in the source element to the first destination +element, and move the medium that had been in the first destination +element to the second destination element. +In case of a simple +exchange, the source and second destination elements should be the +same. +The current picker is used to perform the operation. +The addresses of the affected elements is specified to the ioctl in a +.Vt changer_exchange +structure which includes at least the following +fields: +.Bd -literal -offset indent +u_int ce_srctype; /* element type of source */ +u_int ce_srcunit; /* logical unit of source */ +u_int ce_fdsttype; /* element type of first destination */ +u_int ce_fdstunit; /* logical unit of first destination */ +u_int ce_sdsttype; /* element type of second destination */ +u_int ce_sdstunit; /* logical unit of second destination */ +u_int ce_flags; /* misc. flags */ +.Ed +In +.Va ce_flags , +.Dv CM_INVERT1 +and/or +.Dv CM_INVERT2 +may be set +to flip the first or second medium during the exchange operation, +respectively. +.Pp +.Em This operation is untested . +.It Dv CHIOPOSITION +.Pq Vt "struct changer_position" +Position the current picker in front of the specified element. +The element is specified with a changer_position structure, which includes +at least the following elements: +.Bd -literal -offset indent +u_int cp_type; /* element type */ +u_int cp_unit; /* logical unit of element */ +u_int cp_flags; /* misc. flags */ +.Ed +The +.Va cp_flags +field may be set to +.Dv CP_INVERT +to invert the picker during the operation. +.It Dv CHIOGPICKER +.Pq Vt int +Return the logical address of the current picker. +.It Dv CHIOSPICKER +.Pq Vt int +Select the picker specified by the given logical address. +.It Dv CHIOGPARAMS +.Pq Vt "struct changer_params" +Return the configuration parameters for the media changer. +This ioctl +fills the changer_params structure passed by the user with at least the +following fields: +.Bd -literal -offset indent +u_int cp_npickers; /* number of pickers */ +u_int cp_nslots; /* number of slots */ +u_int cp_nportals; /* number of import/export portals */ +u_int cp_ndrives; /* number of drives */ +.Ed +.Pp +This call can be used by applications to query the dimensions of +the jukebox before using the +.Dv CHIGSTATUS +ioctl to query the jukebox status. +.It Dv CHIOIELEM +Perform the +.Sy INITIALIZE ELEMENT STATUS +call on the media changer device. +This forces the media changer to update its internal status +information with respect to loaded media. +It also scans any barcode labels provided that it has a label reader. +The +.Nm +driver's status is not affected by this call. +.It Dv CHIOGSTATUS +.Pq Vt "struct changer_element_status_request" +Perform the +.Sy READ ELEMENT STATUS +call on the media changer device. +This call reads the element status information of the media +changer and converts it to an array of +.Vt changer_element_status +structures. +.Pp +With each call to +.Dv CHIOGSTATUS , +the status of one or more elements of one type may be queried. +.Pp +The application passes a +.Vt changer_element_status_request +structure to the +.Nm +driver which contains the following fields: +.Bd -literal -offset indent +u_int cesr_element_type; +u_int cesr_element_base; +u_int cesr_element_count; +u_int cesr_flags; +struct changer_element_status *cesr_element_status; +.Ed +.Pp +This structure is read by the driver to determine the type, logical +base address and number of elements for which information is to be +returned in the array of +.Vt changer_element_status +structures pointed to by the +.Va cesr_element_status +field. +The application must allocate enough +memory for +.Va cesr_element_count +status structures (see below). +The +.Va cesr_flags +can optionally be set to +.Dv CESR_VOLTAGS +to indicate that volume tag (bar code) information is to be read from +the jukebox and returned. +.Pp +The +.Va cesr_element_base +and +.Va cesr_element_count +fields must be valid with respect to the physical configuration of the changer. +If they are not, the +.Dv CHIOGSTATUS +ioctl returns the +.Er EINVAL +error code. +.Pp +The information about the elements is returned in an array of +.Vt changer_element_status +structures. +This structure include at least the following fields: +.Bd -literal -offset indent +u_int ces_addr; /* element address in media changer */ +u_char ces_flags; /* see CESTATUS definitions below */ +u_char ces_sensecode; /* additional sense code for element */ +u_char ces_sensequal; /* additional sense code qualifier */ +u_char ces_invert; /* invert bit */ +u_char ces_svalid; /* source address (ces_source) valid */ +u_short ces_source; /* source address of medium */ +changer_voltag_t ces_pvoltag; /* primary volume tag */ +changer_voltag_t ces_avoltag; /* alternate volume tag */ +u_char ces_idvalid; /* ces_scsi_id is valid */ +u_char ces_scsi_id; /* SCSI id of element (if ces_idvalid is nonzero) */ +u_char ces_lunvalid; /* ces_scsi_lun is valid */ +u_char ces_scsi_lun; /* SCSI lun of element (if ces_lunvalid is nonzero) */ +.Ed +.Pp +The +.Va ces_addr +field contains the address of the element in the +coordinate system of the media changer. +It is not used by the driver, +and should be used for diagnostic purposes only. +.Pp +The following flags are defined for the +.Va ces_flags +field: +.Bl -tag -width CESTATUS_IMPEXP +.It Dv CESTATUS_FULL +A medium is present. +.It Dv CESTATUS_IMPEXP +The medium has been deposited by the operator (and not by a picker). +.It Dv CESTATUS_EXCEPT +The element is in an exceptional state (e.g.\& invalid barcode label, +barcode not yet scanned). +.It Dv CESTATUS_ACCESS +The element is accessible by the picker. +.It Dv CESTATUS_EXENAB +The element supports medium export. +.It Dv CESTATUS_INENAB +The element supports medium import. +.El +.Pp +Note that not all flags are valid for all element types. +.El +.Sh NOTES +This version of the +.Nm +driver has been tested with a DEC TZ875 (5 slot, one DLT drive) +and a Breece Hill Q47 (60 slot, four DLT drives, barcode reader). +.Pp +Many of the features the +.Nm +driver supports are not thoroughly tested due to the fact that the +devices available for testing do not support the necessary commands. +This is true for alternate volume tags, media flipping, import/export +element handling, multiple picker operation and other things. +.Sh FILES +.Bl -tag -width /dev/ch[0-9] -compact +.It Pa /dev/ch[0-9] +device entries +.El +.Sh DIAGNOSTICS +If the media changer does not support features requested by the +.Nm +driver, it will produce both console error messages and failure return +codes to the ioctls described here. +.Sh SEE ALSO +.Xr chio 1 , +.Xr cam 4 , +.Xr cd 4 , +.Xr da 4 , +.Xr sa 4 +.Sh HISTORY +The +.Nm +driver appeared in +.Bx 386 0.1 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Jason R. Thorpe Aq Mt thorpej@and.com +for And Communications, +.Pa http://www.and.com/ . +It was added to the system by +.An Stefan Grefen Aq Mt grefen@goofy.zdv.uni-mainz.de +who apparently had such a device. +It was ported to CAM by +.An Kenneth Merry Aq Mt ken@FreeBSD.org . +It was updated to support volume tags by +.An Hans Huebner Aq Mt hans@artcom.de . diff --git a/static/freebsd/man4/chromebook_platform.4 b/static/freebsd/man4/chromebook_platform.4 new file mode 100644 index 00000000..932986ef --- /dev/null +++ b/static/freebsd/man4/chromebook_platform.4 @@ -0,0 +1,66 @@ +.\" Copyright (c) 2016 Andriy Gapon +.\" 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 October 13, 2016 +.Dt CHROMEBOOK_PLATFORM 4 +.Os +.Sh NAME +.Nm chromebook_platform +.Nd support driver for hardware on various Chromebook models +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines into +the kernel configuration file: +.Bd -ragged -offset indent +.Cd "device chromebook_platform" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +chromebook_platform_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides automatic configuration for devices that cannot be enumerated +or safely probed. +In particular, I2C peripherals are different from model to model. +.Nm +has a model-specific information about the I2C peripherals, their drivers, +their bus attachments and slave addresses. +.Pp +Note that +.Nm +does not load driver modules for the peripherals. +Those have to be compiled into the kernel or loaded separately. +.Sh SEE ALSO +.Xr cyapa 4 , +.Xr iicbus 4 , +.Xr isl 4 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver and this manual page were written by +.An Andriy Gapon Aq Mt avg@FreeBSD.org . diff --git a/static/freebsd/man4/chvgpio.4 b/static/freebsd/man4/chvgpio.4 new file mode 100644 index 00000000..976ca49d --- /dev/null +++ b/static/freebsd/man4/chvgpio.4 @@ -0,0 +1,63 @@ +.\" Copyright (c) 2017 +.\" Tom Jones 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 November 17, 2017 +.Dt CHVGPIO 4 +.Os +.Sh NAME +.Nm chvgpio +.Nd Intel Cherry View SoC GPIO controller +.Sh SYNOPSIS +.Cd "device gpio" +.Cd "device chvgpio" +.Sh DESCRIPTION +.Nm +supports the GPIO controller that can be found in Intel's Cherry View SoC +family. +.Pp +The Cherry View SoC has 5 banks of GPIO pins, NORTH, EAST, SOUTHEAST, SOUTHWEST +and VIRTUAL. +All but VIRTUAL are exposed to userland as +.Pa /dev/gpiocN , +where N is 0-3. +Pins in each bank are pre-named to match names in the Intel® Atom™ Z8000 +Processor Series Vol 2 +.Sh SEE ALSO +.Xr gpio 3 , +.Xr gpio 4 , +.Xr gpioctl 8 +.Rs +.%T Intel® Atom™ Z8000 Processor Series Vol 1 +.Re +.Rs +.%T Intel® Atom™ Z8000 Processor Series Vol 2 +.Re +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 12 . +.Sh AUTHORS +This driver and man page were written by +.An Tom Jones Aq Mt tj@enoti.me . diff --git a/static/freebsd/man4/ciss.4 b/static/freebsd/man4/ciss.4 new file mode 100644 index 00000000..cf59836c --- /dev/null +++ b/static/freebsd/man4/ciss.4 @@ -0,0 +1,236 @@ +.\" Written by Tom Rhodes +.\" This file is in the public domain. +.\" +.Dd April 6, 2026 +.Dt CISS 4 +.Os +.Sh NAME +.Nm ciss +.Nd Common Interface for SCSI-3 Support driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device scbus" +.Cd "device ciss" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ciss_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver claims to provide a common interface between generic SCSI +transports and intelligent host adapters. +.Pp +The +.Nm +driver supports +.Em CISS +as defined in the document entitled +.%T "CISS Command Interface for SCSI-3 Support Open Specification, Version 1.04, Valence Number 1" , +dated 2000/11/27, produced by Compaq Computer Corporation. +.Pp +We provide a shim layer between the +.Nm +interface and +.Xr CAM 4 , +offloading most of the queueing and being-a-disk chores onto CAM. +Entry to the driver is via the PCI bus attachment +.Fn ciss_probe , +.Fn ciss_attach , +etc.\& and via the CAM interface +.Fn ciss_cam_action , +and +.Fn ciss_cam_poll . +The Compaq +.Nm +adapters require faked responses to get reasonable +behavior out of them. +In addition, the +.Nm +command set is by no means adequate to support the functionality +of a RAID controller, +and thus the supported Compaq adapters utilize portions of the +control protocol from earlier Compaq adapter families. +.Pp +Currently +.Nm +supports the +.Dq simple +and +.Dq performant +transport layer. +.Pp +Non-disk devices (such as internal DATs and devices +attached to the external SCSI bus) are supported as normal CAM devices +provided that they are exported by the controller firmware and are not +marked as being masked. +Masked devices can be exposed by setting the +.Va hw.ciss.expose_hidden_physical +tunable to non-zero at boot time. +Direct Access devices (such as disk +drives) are only exposed as +.Xr pass 4 +devices. +Hot-insertion and removal of devices is supported and notification messages +will be reported to the console and logs. +.Pp +The problem which adapter freezes with the message +.Dq ADAPTER HEARTBEAT FAILED +might be solved by updating the firmware and/or setting the +.Va hw.ciss.nop_message_heartbeat +tunable to non-zero at boot time. +.Sh HARDWARE +The +.Nm +driver supports controllers implementing +Common Interface for SCSI-3 Support Open Specification v1.04, including: +.Pp +.Bl -bullet -compact +.It +Compaq Smart Array 5300 (simple mode only) +.It +Compaq Smart Array 532 +.It +Compaq Smart Array 5i +.It +HP Smart Array 5312 +.It +HP Smart Array 6i +.It +HP Smart Array 641 +.It +HP Smart Array 642 +.It +HP Smart Array 6400 +.It +HP Smart Array 6400 EM +.It +HP Smart Array E200 +.It +HP Smart Array E200i +.It +HP Smart Array E500 +.It +HP Smart Array H240 +.It +HP Smart Array H240ar +.It +HP Smart Array H240nr +.It +HP Smart Array H241 +.It +HP Smart Array H244br +.It +HP Smart Array P212 +.It +HP Smart Array P220i +.It +HP Smart Array P222 +.It +HP Smart Array P230i +.It +HP Smart Array P240nr +.It +HP Smart Array P244br +.It +HP Smart Array P246br +.It +HP Smart Array P400 +.It +HP Smart Array P400i +.It +HP Smart Array P410 +.It +HP Smart Array P410i +.It +HP Smart Array P411 +.It +HP Smart Array P420 +.It +HP Smart Array P420i +.It +HP Smart Array P421 +.It +HP Smart Array P430 +.It +HP Smart Array P430i +.It +HP Smart Array P431 +.It +HP Smart Array P440 +.It +HP Smart Array P440ar +.It +HP Smart Array P441 +.It +HP Smart Array P530 +.It +HP Smart Array P531 +.It +HP Smart Array P542d +.It +HP Smart Array P600 +.It +HP Smart Array P700m +.It +HP Smart Array P712m +.It +HP Smart Array P721m +.It +HP Smart Array P731m +.It +HP Smart Array P741m +.It +HP Smart Array P800 +.It +HP Smart Array P812 +.It +HP Smart Array P822 +.It +HP Smart Array P830 +.It +HP Smart Array P830i +.It +HP Smart Array P840 +.It +HP Smart Array P840ar +.It +HP Smart Array P841 +.It +HP Modular Smart Array 20 (MSA20) +.It +HP Modular Smart Array 500 (MSA500) +.El +.Pp +Additionally, several HP Smart Array controllers are supported by PCI +subdevice ID only, as no model name is available for them: +0x3220, 0x3222, 0x3230, 0x3231, 0x3232, 0x3233, 0x3236, 0x3238, +0x3239, 0x323A, 0x323B, 0x323C, and 0x324B +(all with PCI subvendor 0x103C). +.Sh SEE ALSO +.Xr cam 4 , +.Xr pass 4 , +.Xr xpt 4 , +.Xr loader.conf 5 , +.Xr camcontrol 8 +.Rs +.%T "CISS Command Interface for SCSI-3 Support Open Specification, Version 1.04, Valence Number 1" +.%D 2000/11/27 +.%Q "Compaq Computer Corporation" +.Re +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Mike Smith Aq Mt msmith@FreeBSD.org . +.Pp +This manual page is based on his comments and was written by +.An Tom Rhodes Aq Mt trhodes@FreeBSD.org . diff --git a/static/freebsd/man4/coretemp.4 b/static/freebsd/man4/coretemp.4 new file mode 100644 index 00000000..210b9d0f --- /dev/null +++ b/static/freebsd/man4/coretemp.4 @@ -0,0 +1,73 @@ +.\"- +.\" Copyright (c) 2007 Dag-Erling Smørgrav +.\" 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 August 23, 2007 +.Dt CORETEMP 4 +.Os +.Sh NAME +.Nm coretemp +.Nd device driver for Intel Core on-die digital thermal sensor +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device coretemp" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +coretemp_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the on-die digital thermal sensor present +in Intel Core and newer CPUs. +.Pp +The +.Nm +driver reports each core's temperature through a sysctl node in the +corresponding CPU device's sysctl tree, named +.Va dev.cpu.%d.temperature . +.Sh SEE ALSO +.Xr amdtemp 4 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 7.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Rui Paulo Aq Mt rpaulo@FreeBSD.org +as part of a Google Summer of Code project. +This manual page was written by +.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . diff --git a/static/freebsd/man4/cp2112.4 b/static/freebsd/man4/cp2112.4 new file mode 100644 index 00000000..040aad4c --- /dev/null +++ b/static/freebsd/man4/cp2112.4 @@ -0,0 +1,85 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2020 Andriy Gapon +.\" +.\" 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 August 12, 2020 +.Dt CP2112 4 +.Os +.Sh NAME +.Nm cp2112 +.Nd driver for a USB GPIO and I2C peripheral device +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device cp2112" +.Cd "device usb" +.Cd "device gpio" +.Cd "device iicbus" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +cp2112_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for Silicon Labs CP2112 device. +The device has 8 general purpose I/O pins and an I2C controller that supports +a subset of the I2C protocol. +.Pp +All pins support both input and output modes. +An output pin can be configured either for open-drain or push-pull operation. +Pins 0, 1 and 7 support special functions: I2C transmit indication, +I2C receive indication and clock output respectively. +At the moment the +.Nm +driver does not provide a way to enable and configure the special functions. +.Pp +The I2C controller supports read transactions with up to 512 bytes of data, +write transactions with up to 61 bytes of data and a write followed by +the repeated start followed by a read transactions where the write can be +up to 16 bytes and the read can be up to 512 bytes. +Zero length transfers are not supported. +The +.Nm +driver creates a +.Xr gpio 4 +and +.Xr iicbus 4 +child buses to expose the respective functions. +.Sh SEE ALSO +.Xr gpio 4 , +.Xr iicbus 4 , +.Xr usb 4 +.Sh HISTORY +The +.Nm +driver and this manual page was written by +.An Andriy Gapon Aq Mt avg@FreeBSD.org . diff --git a/static/freebsd/man4/cpuctl.4 b/static/freebsd/man4/cpuctl.4 new file mode 100644 index 00000000..5846fc41 --- /dev/null +++ b/static/freebsd/man4/cpuctl.4 @@ -0,0 +1,196 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2006-2008 Stanislav Sedov +.\" 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 June 20, 2014 +.Dt CPUCTL 4 +.Os +.Sh NAME +.Nm cpuctl +.Nd cpuctl pseudo device +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your kernel +configuration file: +.Bd -ragged -offset indent +.Cd "device cpuctl" +.Ed +.Pp +Alternatively, to load the driver as a module +at boot time, place the following in +.Xr loader.conf 5 : +.Bd -literal -offset indent +cpuctl_load="YES" +.Ed +.Sh DESCRIPTION +The special device +.Pa /dev/cpuctl +presents interface to the system CPU. +It provides functionality to retrieve +CPUID information, read/write machine specific registers (MSR) and perform +CPU firmware updates. +.Pp +For each CPU present in the system, the special device +.Pa /dev/cpuctl%d +with the appropriate index will be created. +For multicore CPUs such a +special device will be created for each core. +.Pp +Currently, only i386 and amd64 processors are +supported. +.Sh IOCTL INTERFACE +All of the supported operations are invoked using the +.Xr ioctl 2 +system call. +Currently, the following ioctls are defined: +.Bl -tag -width indent +.It Dv CPUCTL_RDMSR Fa cpuctl_msr_args_t *args +.It Dv CPUCTL_WRMSR Fa cpuctl_msr_args_t *args +Read/write CPU machine specific register. +The +.Vt cpuctl_msr_args_t +structure is defined in +.In sys/cpuctl.h +as: +.Bd -literal +typedef struct { + int msr; /* MSR to read */ + uint64_t data; +} cpuctl_msr_args_t; +.Ed +.It Dv CPUCTL_MSRSBIT Fa cpuctl_msr_args_t *args +.It Dv CPUCTL_MSRCBIT Fa cpuctl_msr_args_t *args +Set/clear MSR bits according to the mask given in the +.Va data +field. +.It Dv CPUCTL_CPUID Fa cpuctl_cpuid_args_t *args +Retrieve CPUID information. +Arguments are supplied in the following structure: +.Bd -literal +typedef struct { + int level; /* CPUID level */ + uint32_t data[4]; +} cpuctl_cpuid_args_t; +.Ed +.Pp +It is equivalent to the +.Dv CPUCTL_CPUID_COUNT +request with +.Va level_type +set to 0. +.It Dv CPUCTL_CPUID_COUNT Fa cpuctl_cpuid_count_args_t *args +Retrieve CPUID information. +Arguments are supplied in the following structure: +.Bd -literal +typedef struct { + int level; /* CPUID level */ + int level_type; /* CPUID level type */ + uint32_t data[4]; +} cpuctl_cpuid_count_args_t; +.Ed +.Pp +The +.Va level +field indicates the CPUID level to retrieve, +it is loaded into the +.Va %eax +register before the CPUID instruction is executed, +The +.Va level_type +field indicates the CPUID level type to retrieve, +it is loaded into the +.Va %ecx +register. +.Pp +The +.Va data +field is used to store the received CPUID data. +That is, +.Va data[0] +contains the value of +.Va %eax +register after the CPUID instruction is executed, +.Va data[1] +is for +.Va %ebx , +.Va data[2] +for +.Va %ecx , +and +.Va data[3] +for +.Va %edx . +.It Dv CPUCTL_UPDATE cpuctl_update_args_t *args +Update CPU firmware (microcode). +The structure is defined in +.In sys/cpuctl.h +as: +.Bd -literal +typedef struct { + void *data; + size_t size; +} cpuctl_update_args_t; +.Ed +.Pp +The +.Va data +field should point to the firmware image of size +.Va size . +.El +.Pp +For additional information refer to +.Pa cpuctl.h . +.Sh FILES +.Bl -tag -width /dev/cpuctl -compact +.It Pa /dev/cpuctl +.El +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ENXIO +The operation requested is not supported by the device (e.g., unsupported +architecture or the CPU is disabled). +.It Bq Er EINVAL +Incorrect request was supplied, or microcode image is not correct. +.It Bq Er ENOMEM +No physical memory was available to complete the request. +.It Bq Er EFAULT +The firmware image address points outside the process address space. +.El +.Sh SEE ALSO +.Xr hwpmc 4 , +.Xr cpucontrol 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 7.2 . +.Sh AUTHORS +The +.Nm +module and this manual page were written by +.An Stanislav Sedov Aq Mt stas@FreeBSD.org . +.Sh BUGS +Yes, probably, report if any. diff --git a/static/freebsd/man4/cpufreq.4 b/static/freebsd/man4/cpufreq.4 new file mode 100644 index 00000000..beeef3fe --- /dev/null +++ b/static/freebsd/man4/cpufreq.4 @@ -0,0 +1,327 @@ +.\" Copyright (c) 2005 Nate Lawson +.\" 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 April 4, 2022 +.Dt CPUFREQ 4 +.Os +.Sh NAME +.Nm cpufreq +.Nd CPU frequency control framework +.Sh SYNOPSIS +.Cd "device cpufreq" +.Pp +.In sys/cpu.h +.Ft int +.Fn cpufreq_levels "device_t dev" "struct cf_level *levels" "int *count" +.Ft int +.Fn cpufreq_set "device_t dev" "const struct cf_level *level" "int priority" +.Ft int +.Fn cpufreq_get "device_t dev" "struct cf_level *level" +.Ft int +.Fo cpufreq_drv_settings +.Fa "device_t dev" +.Fa "struct cf_setting *sets" +.Fa "int *count" +.Fc +.Ft int +.Fn cpufreq_drv_type "device_t dev" "int *type" +.Ft int +.Fn cpufreq_drv_set "device_t dev" "const struct cf_setting *set" +.Ft int +.Fn cpufreq_drv_get "device_t dev" "struct cf_setting *set" +.Sh DESCRIPTION +The +.Nm +driver provides a unified kernel and user interface to CPU frequency +control drivers. +It combines multiple drivers offering different settings into a single +interface of all possible levels. +Users can access this interface directly via +.Xr sysctl 8 +or by indicating to +.Pa /etc/rc.d/power_profile +that it should switch settings when the AC line state changes via +.Xr rc.conf 5 . +.Sh SYSCTL VARIABLES +These settings may be overridden by kernel drivers requesting alternate +settings. +If this occurs, the original values will be restored once the condition +has passed (e.g., the system has cooled sufficiently). +If a sysctl cannot be set due to an override condition, it will return +.Er EPERM . +.Pp +The frequency cannot be changed if TSC is in use as the timecounter and the +hardware does not support invariant TSC. +This is because the timecounter system needs to use a source that has a +constant rate. +(On invariant TSC hardware, the TSC runs at the P0 rate regardless of the +configured P-state.) +Modern hardware mostly has invariant TSC. +The timecounter source can be changed with the +.Pa kern.timecounter.hardware +sysctl. +Available modes are in +.Pa kern.timecounter.choice +sysctl entry. +.Bl -tag -width indent +.It Va dev.cpu.%d.freq +Current active CPU frequency in MHz. +.It Va dev.cpu.%d.freq_driver +The specific +.Nm +driver used by this cpu. +.It Va dev.cpu.%d.freq_levels +Currently available levels for the CPU (frequency/power usage). +Values are in units of MHz and milliwatts. +.It Va dev.DEVICE.%d.freq_settings +Currently available settings for the driver (frequency/power usage). +Values are in units of MHz and milliwatts. +This is helpful for understanding which settings are offered by which +driver for debugging purposes. +.It Va debug.cpufreq.lowest +Lowest CPU frequency in MHz to offer to users. +This setting is also accessible via a tunable with the same name. +This can be used to disable very low levels that may be unusable on +some systems. +.It Va debug.cpufreq.verbose +Print verbose messages. +This setting is also accessible via a tunable with the same name. +.It Va debug.hwpstate_pstate_limit +If enabled, the AMD hwpstate driver limits administrative control of P-states +(including by +.Xr powerd 8 ) +to the value in the 0xc0010061 MSR, known as "PStateCurLim[CurPstateLimit]." +It is disabled (0) by default. +On some hardware, the limit register seems to simply follow the configured +P-state, which results in the inability to ever raise the P-state back to P0 +from a reduced frequency state. +.El +.Sh SUPPORTED DRIVERS +The following device drivers offer absolute frequency control via the +.Nm +interface. +Usually, only one of these can be active at a time. +.Pp +.Bl -tag -compact -width "hwpstate_intel(4)" +.It acpi_perf +ACPI CPU performance states +.It Xr est 4 +Intel Enhanced SpeedStep +.It hwpstate +AMD Cool'n'Quiet2 used in K10 through Family 17h +.It Xr hwpstate_intel 4 +Intel SpeedShift driver +.It ichss +Intel SpeedStep for ICH +.It powernow +AMD PowerNow!\& and Cool'n'Quiet for K7 and K8 +.It smist +Intel SMI-based SpeedStep for PIIX4 +.El +.Pp +The following device drivers offer relative frequency control and +have an additive effect: +.Pp +.Bl -tag -compact -width "acpi_throttle" +.It acpi_throttle +ACPI CPU throttling +.It p4tcc +Pentium 4 Thermal Control Circuitry +.El +.Sh KERNEL INTERFACE +Kernel components can query and set CPU frequencies through the +.Nm +kernel interface. +This involves obtaining a +.Nm +device, calling +.Fn cpufreq_levels +to get the currently available frequency levels, +checking the current level with +.Fn cpufreq_get , +and setting a new one from the list with +.Fn cpufreq_set . +Each level may actually reference more than one +.Nm +driver but kernel components do not need to be aware of this. +The +.Va total_set +element of +.Vt "struct cf_level" +provides a summary of the frequency and power for this level. +Unknown or irrelevant values are set to +.Dv CPUFREQ_VAL_UNKNOWN . +.Pp +The +.Fn cpufreq_levels +method takes a +.Nm +device and an empty array of +.Fa levels . +The +.Fa count +value should be set to the number of levels available and after the +function completes, will be set to the actual number of levels returned. +If there are more levels than +.Fa count +will allow, it should return +.Er E2BIG . +.Pp +The +.Fn cpufreq_get +method takes a pointer to space to store a +.Fa level . +After successful completion, the output will be the current active level +and is equal to one of the levels returned by +.Fn cpufreq_levels . +.Pp +The +.Fn cpufreq_set +method takes a pointer a +.Fa level +and attempts to activate it. +The +.Fa priority +(i.e., +.Dv CPUFREQ_PRIO_KERN ) +tells +.Nm +whether to override previous settings while activating this level. +If +.Fa priority +is higher than the current active level, that level will be saved and +overridden with the new level. +If a level is already saved, the new level is set without overwriting +the older saved level. +If +.Fn cpufreq_set +is called with a +.Dv NULL +.Fa level , +the saved level will be restored. +If there is no saved level, +.Fn cpufreq_set +will return +.Er ENXIO . +If +.Fa priority +is lower than the current active level's priority, this method returns +.Er EPERM . +.Sh DRIVER INTERFACE +Kernel drivers offering hardware-specific CPU frequency control export +their individual settings through the +.Nm +driver interface. +This involves implementing these methods: +.Fn cpufreq_drv_settings , +.Fn cpufreq_drv_type , +.Fn cpufreq_drv_set , +and +.Fn cpufreq_drv_get . +Additionally, the driver must attach a device as a child of a CPU +device so that these methods can be called by the +.Nm +framework. +.Pp +The +.Fn cpufreq_drv_settings +method returns an array of currently available settings, each of type +.Vt "struct cf_setting" . +The driver should set unknown or irrelevant values to +.Dv CPUFREQ_VAL_UNKNOWN . +All the following elements for each setting should be returned: +.Bd -literal +struct cf_setting { + int freq; /* CPU clock in MHz or 100ths of a percent. */ + int volts; /* Voltage in mV. */ + int power; /* Power consumed in mW. */ + int lat; /* Transition latency in us. */ + device_t dev; /* Driver providing this setting. */ +}; +.Ed +.Pp +On entry to this method, +.Fa count +contains the number of settings that can be returned. +On successful completion, the driver sets it to the actual number of +settings returned. +If the driver offers more settings than +.Fa count +will allow, it should return +.Er E2BIG . +.Pp +The +.Fn cpufreq_drv_type +method indicates the type of settings it offers, either +.Dv CPUFREQ_TYPE_ABSOLUTE +or +.Dv CPUFREQ_TYPE_RELATIVE . +Additionally, the driver may set the +.Dv CPUFREQ_FLAG_INFO_ONLY +flag if the settings it provides are information for other drivers only +and cannot be passed to +.Fn cpufreq_drv_set +to activate them. +.Pp +The +.Fn cpufreq_drv_set +method takes a driver setting and makes it active. +If the setting is invalid or not currently available, it should return +.Er EINVAL . +.Pp +The +.Fn cpufreq_drv_get +method returns the currently-active driver setting. +The +.Vt "struct cf_setting" +returned must be valid for passing to +.Fn cpufreq_drv_set , +including all elements being filled out correctly. +If the driver cannot infer the current setting +(even by estimating it with +.Fn cpu_est_clockrate ) +then it should set all elements to +.Dv CPUFREQ_VAL_UNKNOWN . +.Sh SEE ALSO +.Xr acpi 4 , +.Xr est 4 , +.Xr timecounters 4 , +.Xr powerd 8 , +.Xr sysctl 8 +.Sh AUTHORS +.An Nate Lawson +.An Bruno Ducrot +contributed the +.Pa powernow +driver. +.Sh BUGS +The following drivers have not yet been converted to the +.Nm +interface: +.Xr longrun 4 . +.Pp +Notification of CPU and bus frequency changes is not implemented yet. +.Pp +When multiple CPUs offer frequency control, they cannot be set to different +levels and must all offer the same frequency settings. diff --git a/static/freebsd/man4/crypto.4 b/static/freebsd/man4/crypto.4 new file mode 100644 index 00000000..4242a663 --- /dev/null +++ b/static/freebsd/man4/crypto.4 @@ -0,0 +1,376 @@ +.\" $NetBSD: crypto.4,v 1.24 2014/01/27 21:23:59 pgoyette Exp $ +.\" +.\" Copyright (c) 2008 The NetBSD Foundation, Inc. +.\" Copyright (c) 2014-2021 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" Portions of this documentation were written by John-Mark Gurney +.\" under sponsorship of the FreeBSD Foundation and +.\" Rubicon Communications, LLC (Netgate). +.\" +.\" Portions of this documentation were written by Ararat River +.\" Consulting, LLC under sponsorship of the FreeBSD Foundation. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Coyote Point Systems, Inc. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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. +.\" +.\" +.\" +.\" Copyright (c) 2004 +.\" Jonathan Stone . 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 Jonathan Stone 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 Jonathan Stone OR THE VOICES IN HIS HEAD +.\" 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 October 6, 2021 +.Dt CRYPTO 4 +.Os +.Sh NAME +.Nm crypto , +.Nm cryptodev +.Nd user-mode access to hardware-accelerated cryptography +.Sh SYNOPSIS +.Cd device crypto +.Cd device cryptodev +.Pp +.In sys/ioctl.h +.In sys/time.h +.In crypto/cryptodev.h +.Sh DESCRIPTION +The +.Nm +driver gives user-mode applications access to hardware-accelerated +cryptographic transforms as implemented by the +.Xr crypto 9 +in-kernel interface. +.Pp +The +.Pa /dev/crypto +special device provides an +.Xr ioctl 2 +based interface. +User-mode applications open the special device and +then issue +.Xr ioctl 2 +calls on the descriptor. +User-mode access to +.Pa /dev/crypto +is controlled by the +.Ic kern.cryptodevallowsoft +.Xr sysctl 8 +variable. +If this variable is zero, +then user-mode sessions are only permitted to use cryptography coprocessors. +.Sh THEORY OF OPERATION +Use of the device requires a basic series of steps: +.Bl -enum +.It +Open the +.Pa /dev/crypto +device. +.It +Create a session with +.Dv CIOCGSESSION +or +.Dv CIOCGSESSION2 . +Applications will require at least one symmetric session. +Since cipher and MAC keys are tied to sessions, many +applications will require more. +.It +Submit requests, synchronously with +.Dv CIOCCRYPT +or +.Dv CIOCCRYPTAEAD . +.It +Optionally destroy a session with +.Dv CIOCFSESSION . +.It +Close the +.Pa /dev/crypto +device. +This will automatically close any remaining sessions associated with the +file descriptor. +.El +.Sh SYMMETRIC-KEY OPERATION +.Nm cryptodev +provides a context-based API +to traditional symmetric-key encryption (or privacy) algorithms, +keyed and unkeyed one-way hash (HMAC and MAC) algorithms, +encrypt-then-authenticate (ETA) fused operations, +and authenticated encryption with additional data (AEAD) operations. +For ETA operations, +drivers perform both a privacy algorithm and an integrity-check +algorithm in a single pass over the data: either a fused +encrypt/HMAC-generate operation, or a fused HMAC-verify/decrypt operation. +Similarly, for AEAD operations, +drivers perform either an encrypt/MAC-generate operation +or a MAC-verify/decrypt operation. +.Pp +The algorithm(s) and key(s) to use are specified when a session is +created. +Individual requests are able to specify per-request initialization vectors +or nonces. +.Ss Algorithms +For a list of supported algorithms, see +.Xr crypto 7 . +.Ss IOCTL Request Descriptions +.\" +.Bl -tag -width CIOCGSESSION +.\" +.It Dv CIOCFINDDEV Fa struct crypt_find_op *fop +.Bd -literal +struct crypt_find_op { + int crid; /* driver id + flags */ + char name[32]; /* device/driver name */ +}; + +.Ed +If +.Fa crid +is -1, then find the driver named +.Fa name +and return the id in +.Fa crid . +If +.Fa crid +is not -1, return the name of the driver with +.Fa crid +in +.Fa name . +In either case, if the driver is not found, +.Dv ENOENT +is returned. +.It Dv CIOCGSESSION Fa struct session_op *sessp +.Bd -literal +struct session_op { + uint32_t cipher; /* e.g. CRYPTO_AES_CBC */ + uint32_t mac; /* e.g. CRYPTO_SHA2_256_HMAC */ + + uint32_t keylen; /* cipher key */ + const void *key; + int mackeylen; /* mac key */ + const void *mackey; + + uint32_t ses; /* returns: ses # */ +}; + +.Ed +Create a new cryptographic session on a file descriptor for the device; +that is, a persistent object specific to the chosen +privacy algorithm, integrity algorithm, and keys specified in +.Fa sessp . +The special value 0 for either privacy or integrity +is reserved to indicate that the indicated operation (privacy or integrity) +is not desired for this session. +ETA sessions specify both privacy and integrity algorithms. +AEAD sessions specify only a privacy algorithm. +.Pp +Multiple sessions may be bound to a single file descriptor. +The session ID returned in +.Fa sessp-\*[Gt]ses +is supplied as a required field in the operation structure +.Fa crypt_op +for future encryption or hashing requests. +.\" .Pp +.\" This implementation will never return a session ID of 0 for a successful +.\" creation of a session, which is a +.\" .Nx +.\" extension. +.Pp +For non-zero privacy algorithms, the privacy algorithm +must be specified in +.Fa sessp-\*[Gt]cipher , +the key length in +.Fa sessp-\*[Gt]keylen , +and the key value in the octets addressed by +.Fa sessp-\*[Gt]key . +.Pp +For keyed one-way hash algorithms, the one-way hash must be specified +in +.Fa sessp-\*[Gt]mac , +the key length in +.Fa sessp-\*[Gt]mackey , +and the key value in the octets addressed by +.Fa sessp-\*[Gt]mackeylen . +.\" +.Pp +Support for a specific combination of fused privacy and +integrity-check algorithms depends on whether the underlying +hardware supports that combination. +Not all combinations are supported +by all hardware, even if the hardware supports each operation as a +stand-alone non-fused operation. +.It Dv CIOCGSESSION2 Fa struct session2_op *sessp +.Bd -literal +struct session2_op { + uint32_t cipher; /* e.g. CRYPTO_AES_CBC */ + uint32_t mac; /* e.g. CRYPTO_SHA2_256_HMAC */ + + uint32_t keylen; /* cipher key */ + const void *key; + int mackeylen; /* mac key */ + const void *mackey; + + uint32_t ses; /* returns: ses # */ + int crid; /* driver id + flags (rw) */ + int ivlen; /* length of nonce/IV */ + int maclen; /* length of MAC/tag */ + int pad[2]; /* for future expansion */ +}; + +.Ed +This request is similar to CIOGSESSION but adds additional fields. +.Pp +.Fa sessp-\*[Gt]crid +requests either a specific crypto device or a class of devices (software vs +hardware). +.Pp +.Fa sessp-\*[Gt]ivlen +specifies the length of the IV or nonce supplied with each request. +If this field is set to zero, the default IV or nonce length is used. +.Pp +.Fa sessp-\*[Gt]maclen +specifies the length of the MAC or authentication tag supplied or computed by +each request. +If this field is set to zero, the full MAC is used. +.Pp +The +.Fa sessp-\*[Gt]pad +field must be initialized to zero. +.It Dv CIOCCRYPT Fa struct crypt_op *cr_op +.Bd -literal +struct crypt_op { + uint32_t ses; + uint16_t op; /* e.g. COP_ENCRYPT */ + uint16_t flags; + u_int len; + const void *src; + void *dst; + void *mac; /* must be large enough for result */ + const void *iv; +}; + +.Ed +Request an encryption/decryption (or hash) operation. +To encrypt, set +.Fa cr_op-\*[Gt]op +to +.Dv COP_ENCRYPT . +To decrypt, set +.Fa cr_op-\*[Gt]op +to +.Dv COP_DECRYPT . +The field +.Fa cr_op-\*[Gt]len +supplies the length of the input buffer; the fields +.Fa cr_op-\*[Gt]src , +.Fa cr_op-\*[Gt]dst , +.Fa cr_op-\*[Gt]mac , +.Fa cr_op-\*[Gt]iv +supply the addresses of the input buffer, output buffer, +one-way hash, and initialization vector, respectively. +.Pp +If a session is using either fused encrypt-then-authenticate or +an AEAD algorithm, +decryption operations require the associated hash as an input. +If the hash is incorrect, the +operation will fail with +.Dv EBADMSG +and the output buffer will remain unchanged. +.It Dv CIOCCRYPTAEAD Fa struct crypt_aead *cr_aead +.Bd -literal +struct crypt_aead { + uint32_t ses; + uint16_t op; /* e.g. COP_ENCRYPT */ + uint16_t flags; + u_int len; + u_int aadlen; + u_int ivlen; + const void *src; + void *dst; + const void *aad; /* additional authenticated data */ + void *tag; /* must fit for chosen TAG length */ + const void *iv; +}; + +.Ed +The +.Dv CIOCCRYPTAEAD +is similar to the +.Dv CIOCCRYPT +but provides additional data in +.Fa cr_aead-\*[Gt]aad +to include in the authentication mode. +.It Dv CIOCFSESSION Fa u_int32_t ses_id +Destroys the session identified by +.Fa ses_id . +.El +.Sh SEE ALSO +.Xr aesni 4 , +.Xr ipsec 4 , +.Xr padlock 4 , +.Xr safe 4 , +.Xr crypto 7 , +.Xr geli 8 , +.Xr crypto 9 +.Sh HISTORY +The +.Nm +driver first appeared in +.Ox 3.0 . +The +.Nm +driver was imported to +.Fx 5.0 . +.Sh BUGS +Error checking and reporting is weak. +.Pp +The values specified for symmetric-key key sizes to +.Dv CIOCGSESSION +must exactly match the values expected by +.Xr opencrypto 9 . +The output buffer and MAC buffers supplied to +.Dv CIOCCRYPT +must follow whether privacy or integrity algorithms were specified for +session: if you request a +.No non- Ns Dv NULL +algorithm, you must supply a suitably-sized buffer. diff --git a/static/freebsd/man4/ctl.4 b/static/freebsd/man4/ctl.4 new file mode 100644 index 00000000..cac9e616 --- /dev/null +++ b/static/freebsd/man4/ctl.4 @@ -0,0 +1,221 @@ +.\" Copyright (c) 2013 Edward Tomasz Napierala +.\" Copyright (c) 2015-2017 Alexander Motin +.\" 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 March 29, 2017 +.Dt CTL 4 +.Os +.Sh NAME +.Nm ctl +.Nd CAM Target Layer +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ctl" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ctl_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +subsystem provides SCSI target devices emulation. +It supports features such as: +.Pp +.Bl -bullet -compact +.It +Disk, CD-ROM and processor device emulation +.It +Tagged queueing +.It +SCSI task attribute support (ordered, head of queue, simple tags) +.It +SCSI implicit command ordering support +.It +Full task management support (abort, query, reset, etc.) +.It +Support for multiple ports, initiators, targets and backing stores +.It +Support for VMWare VAAI and Microsoft ODX offload (COMPARE AND WRITE, +XCOPY, POPULATE TOKEN/WRITE USING TOKEN, WRITE SAME and UNMAP) +.It +Persistent reservation support +.It +Extensive VPD/mode/log pages support +.It +Featured error reporting, error injection and basic SMART support +.It +High Availability clustering support with ALUA +.It +All I/O handled in-kernel, no userland context switch overhead +.El +.Pp +The +.Nm +subsystem includes multiple frontends to provide access using different +transport protocols and implementations: +.Bl -tag -width cfumass +.It camsim +Provides access for local system via virtual initiator mode +.Xr CAM 4 +SIM. +.It camtgt +Provides access for remote systems via target mode +.Xr CAM 4 +SIMs, such as Fibre Channel +.Xr isp 4 +and +.Xr mpt 4 . +.It cfumass +Provides access for remote systems via USB Mass Storage Class +Bulk Only (BBB) Transport. +.It ha +Internal frontend used to receive requests from other node ports in +High Availability cluster. +.It ioctl +Provides access for local user-level applications via +.Xr ioctl 2 +based API. +.It iscsi +Provides access for remote systems via the iSCSI protocol using +.Xr cfiscsi 4 . +.It tpc +Internal frontend used to receive requests from Third Party Copy engine, +implementing copy offload operations. +.El +.Pp +The +.Nm +subsystem includes two backends to create logical units using different +kinds of backing stores: +.Bl -tag -width ramdisk +.It block +Stores data in ZFS ZVOLs, files or raw block devices. +.It ramdisk +Stores data in RAM, that makes it mostly useful for performance testing. +Depending on configured capacity can work as black hole, thin or thick +provisioned disk. +.El +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va kern.cam.ctl.debug +Bit mask of enabled CTL log levels: +.Bl -tag -offset indent -compact +.It 1 +log commands with errors; +.It 2 +log all commands; +.It 4 +log data for commands other then READ/WRITE. +.El +Defaults to 0. +.It Va kern.cam.ctl.ha_id +Specifies unique position of this node within High Availability cluster. +Default is 0 -- no HA, 1 and 2 -- HA enabled at specified position. +.It Va kern.cam.ctl.ha_mode +Specifies High Availability cluster operation mode: +.Bl -tag -offset indent -compact +.It 0 +Active/Standby -- primary node has backend access and processes requests, +while secondary can only do basic LUN discovery and reservation; +.It 1 +Active/Active -- both nodes have backend access and process requests, +while secondary node synchronizes processing with primary one; +.It 2 +Active/Active -- primary node has backend access and processes requests, +while secondary node forwards all requests and data to primary one; +.El +All above modes require established connection between HA cluster nodes. +If connection is not configured, secondary node will report Unavailable +state; if configured but not established -- Transitioning state. +Defaults to 0. +.It Va kern.cam.ctl.ha_peer +String value, specifying method to establish connection to peer HA node. +Can be "listen IP:port", "connect IP:port" or empty. +.It Va kern.cam.ctl.ha_link +Reports present state of connection between HA cluster nodes: +.Bl -tag -offset indent -compact +.It 0 +not configured; +.It 1 +configured but not established; +.It 2 +established. +.El +.It Va kern.cam.ctl.ha_role +Specifies default role of this node: +.Bl -tag -offset indent -compact +.It 0 +primary; +.It 1 +secondary. +.El +This role can be overridden on per-LUN basis using "ha_role" LUN option, +so that for one LUN one node is primary, while for another -- another. +Role change from primary to secondary for HA modes 0 and 2 closes backends, +the opposite change -- opens. +If there is no primary node (both nodes are secondary, or secondary node has +no connection to primary one), secondary node(s) report Transitioning state. +State with two primary nodes is illegal (split brain condition). +.El +.Sh TUNABLE VARIABLES +The following variables are available as +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va kern.cam.ctl.max_luns +Specifies the maximum number of LUNs we support, must be a power of 2. +The default value is 1024. +.It Va kern.cam.ctl.max_ports +Specifies the maximum number of ports we support, must be a power of 2. +The default value is 1024. +.El +.Sh SEE ALSO +.Xr cfiscsi 4 , +.Xr cfumass 4 , +.Xr ctladm 8 , +.Xr ctld 8 , +.Xr ctlstat 8 +.Sh HISTORY +The +.Nm +subsystem first appeared in +.Fx 9.1 . +.Sh AUTHORS +The +.Nm +subsystem was originally written by +.An Kenneth Merry Aq Mt ken@FreeBSD.org . +Later work was done by +.An Alexander Motin Aq Mt mav@FreeBSD.org . diff --git a/static/freebsd/man4/cue.4 b/static/freebsd/man4/cue.4 new file mode 100644 index 00000000..2d960e2e --- /dev/null +++ b/static/freebsd/man4/cue.4 @@ -0,0 +1,113 @@ +.\" Copyright (c) 1997, 1998, 1999, 2000 +.\" Bill Paul . 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 Bill Paul. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Bill Paul 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 Bill Paul OR THE VOICES IN HIS HEAD +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF +.\" THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 24, 2019 +.Dt CUE 4 +.Os +.Sh NAME +.Nm cue +.Nd "CATC USB-EL1210A USB Ethernet driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device uhci" +.Cd "device ohci" +.Cd "device usb" +.Cd "device miibus" +.Cd "device uether" +.Cd "device cue" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_cue_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for USB Ethernet adapters based on the Computer +Access Technology Corporation's USB-EL1210A chipset. +.Pp +The USB-EL1210A supports a 512-bit multicast hash filter, single perfect +filter entry for the station address and promiscuous mode. +Packets are +received and transmitted over separate USB bulk transfer endpoints. +.Pp +The CATC chipset supports only 10Mbps half-duplex mode, hence there +are no +.Fn ifmedia +modes to select. +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports CATC USB-EL1210A based USB Ethernet +adapters including: +.Pp +.Bl -bullet -compact +.It +Belkin F5U011/F5U111 +.It +CATC Netmate +.It +CATC Netmate II +.It +SmartBridges SmartLink +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "cue%d: watchdog timeout" +A packet was queued for transmission and a transmit command was +issued, however the device failed to acknowledge the transmission +before a timeout expired. +.It "cue%d: no memory for rx list" +The driver failed to allocate an mbuf for the receiver ring. +.El +.Sh SEE ALSO +.Xr arp 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 4.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Bill Paul Aq Mt wpaul@ee.columbia.edu . diff --git a/static/freebsd/man4/cxgb.4 b/static/freebsd/man4/cxgb.4 new file mode 100644 index 00000000..6eb21322 --- /dev/null +++ b/static/freebsd/man4/cxgb.4 @@ -0,0 +1,132 @@ +.\" Copyright (c) 2007-2008, Chelsio Inc +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright notice, +.\" this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Chelsio Inc nor the names of its +.\" contributors may be used to endorse or promote products derived from +.\" this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 COPYRIGHT OWNER 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. +.\" +.\" * Other names and brands may be claimed as the property of others. +.\" +.Dd March 14, 2007 +.Dt CXGB 4 +.Os +.Sh NAME +.Nm cxgb +.Nd "Chelsio T3 10 Gigabit Ethernet adapter driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device firmware" +.Cd "device cxgb" +.Ed +.Pp +To load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_cxgb_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports Transmit/Receive checksum offload, +Jumbo Frames, TCP segmentation offload (TSO), Large Receive Offload (LRO), +VLAN hardware insertion / extraction, and VLAN checksum offload. +For further hardware information, see +.Pa http://www.chelsio.com/ . +.Pp +For questions related to hardware requirements, +refer to the documentation supplied with your Chelsio T3 adapter. +All hardware requirements listed apply to use with +.Fx . +.Pp +Support for Jumbo Frames is provided via the interface MTU setting. +Selecting an MTU larger than 1500 bytes with the +.Xr ifconfig 8 +utility configures the adapter to receive and transmit Jumbo Frames. +The maximum MTU size for Jumbo Frames is 9000. +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports 10 Gigabit and 1 Gigabit Ethernet adapters based on the T3 and T3B chipset: +.Pp +.Bl -bullet -compact +.It +Chelsio 10GBase-CX4 +.It +Chelsio 10GBase-LR +.It +Chelsio 10GBase-SR +.El +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Sh DIAGNOSTICS +.Bl -diag +.It "cxgb%d: Unable to allocate bus resource: memory" +A fatal initialization error has occurred. +.It "cxgb%d: Unable to allocate bus resource: interrupt" +A fatal initialization error has occurred. +.It "cxgb%d: Could not find firmware image %s" +The appropriate firmware kld module was not installed. +This is a fatal initialization error. +.El +.Sh SUPPORT +For general information and support, +go to the Chelsio support website at: +.Pa http://www.chelsio.com/ . +.Pp +If an issue is identified with the released source code on the supported kernel +with a supported adapter, email the specific information related to the +issue to +.Aq Mt support@chelsio.com . +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 6.3 +and +.Fx 7.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Kip Macy Aq Mt kmacy@FreeBSD.org +with substantial support from +.An Scott Long Aq Mt scottl@FreeBSD.org . diff --git a/static/freebsd/man4/cxgbe.4 b/static/freebsd/man4/cxgbe.4 new file mode 100644 index 00000000..c401deea --- /dev/null +++ b/static/freebsd/man4/cxgbe.4 @@ -0,0 +1,465 @@ +.\" Copyright (c) 2011-2016, Chelsio Inc +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright notice, +.\" this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Chelsio Inc nor the names of its +.\" contributors may be used to endorse or promote products derived from +.\" this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 COPYRIGHT OWNER 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. +.\" +.\" * Other names and brands may be claimed as the property of others. +.\" +.Dd December 17, 2025 +.Dt CXGBE 4 +.Os +.Sh NAME +.Nm cxgbe +.Nd Chelsio T7, T6, T5, and T4 based 1Gb to 400Gb Ethernet driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device cxgbe" +.Ed +.Pp +To load the driver as a +module at boot time, place the following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +t7fw_cfg_load="YES" +t6fw_cfg_load="YES" +t5fw_cfg_load="YES" +t4fw_cfg_load="YES" +if_cxgbe_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for PCI Express Ethernet adapters based on +the Chelsio Terminator 7, Terminator 6, Terminator 5, and Terminator 4 +ASICs (T7, T6, T5, and T4). +The driver supports Jumbo Frames, Transmit/Receive checksum offload, +TCP segmentation offload (TSO), Large Receive Offload (LRO), VLAN +tag insertion/extraction, VLAN checksum offload, VLAN TSO, +VXLAN checksum offload, VXLAN TSO, and Receive Side Steering (RSS). +For further hardware information and questions related to hardware +requirements, see +.Pa http://www.chelsio.com/ . +.Pp +The +.Nm +driver uses different names for devices based on the associated ASIC: +.Bl -column -offset indent "ASIC" "Port Name" "Parent Device" +.It Sy ASIC Ta Sy Port Name Ta Sy Parent Device Ta Sy Virtual Interface +.It T7 Ta che Ta chnex Ta vche +.It T6 Ta cc Ta t6nex Ta vcc +.It T5 Ta cxl Ta t5nex Ta vcxl +.It T4 Ta cxgbe Ta t4nex Ta vcxgbe +.El +.Pp +Loader tunables with the hw.cxgbe prefix apply to all cards. +The driver provides sysctl MIBs for both ports and parent devices using +the names above. +For example, a T5 adapter provides port MIBs under dev.cxl and +adapter-wide MIBs under dev.t5nex. +References to sysctl MIBs in the remainder of this page use +dev. for port MIBs and dev. for adapter-wide MIBs. +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports +400Gb, 200Gb, 50Gb, and 10Gb Ethernet adapters based on the T7 ASIC: +.Pp +.Bl -bullet -compact +.It +Chelsio S71400 +.It +Chelsio S72200 +.It +Chelsio S72200-OCP +.It +Chelsio T72200 +.It +Chelsio T72200-DPU +.It +Chelsio T72200-FH +.It +Chelsio T72200-FH-DPU +.It +Chelsio T72200-OCP +.It +Chelsio S7450-DPU +.It +Chelsio S7450-OCP +.It +Chelsio T71200-iNIC +.It +Chelsio T7250 +.It +Chelsio T7210-BT +.It +Chelsio T7410-BT-OCP +.El +.Pp +The +.Nm +driver supports 100Gb and 25Gb Ethernet adapters based on the T6 ASIC: +.Pp +.Bl -bullet -compact +.It +Chelsio T6225-CR +.It +Chelsio T6225-SO-CR +.It +Chelsio T62100-LP-CR +.It +Chelsio T62100-SO-CR +.It +Chelsio T62100-CR +.El +.Pp +The +.Nm +driver supports 40Gb, 10Gb and 1Gb Ethernet adapters based on the T5 ASIC: +.Pp +.Bl -bullet -compact +.It +Chelsio T580-CR +.It +Chelsio T580-LP-CR +.It +Chelsio T580-LP-SO-CR +.It +Chelsio T560-CR +.It +Chelsio T540-CR +.It +Chelsio T540-LP-CR +.It +Chelsio T522-CR +.It +Chelsio T520-LL-CR +.It +Chelsio T520-CR +.It +Chelsio T520-SO +.It +Chelsio T520-BT +.It +Chelsio T504-BT +.El +.Pp +The +.Nm +driver supports 10Gb and 1Gb Ethernet adapters based on the T4 ASIC: +.Pp +.Bl -bullet -compact +.It +Chelsio T420-CR +.It +Chelsio T422-CR +.It +Chelsio T440-CR +.It +Chelsio T420-BCH +.It +Chelsio T440-BCH +.It +Chelsio T440-CH +.It +Chelsio T420-SO +.It +Chelsio T420-CX +.It +Chelsio T420-BT +.It +Chelsio T404-BT +.El +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +There are multiple tunables that control the number of queues of various +types. +A negative value for such a tunable instructs the driver to create +up to that many queues if there are enough CPU cores available. +.Bl -tag -width indent +.It Va hw.cxgbe.ntxq +Number of NIC tx queues used for a port. +The default is 16 or the number +of CPU cores in the system, whichever is less. +.It Va hw.cxgbe.nrxq +Number of NIC rx queues used for a port. +The default is 8 or the number +of CPU cores in the system, whichever is less. +.It Va hw.cxgbe.nofldtxq +Number of TOE tx queues used for a port. +The default is 8 or the +number of CPU cores in the system, whichever is less. +.It Va hw.cxgbe.nofldrxq +Number of TOE rx queues used for a port. +The default is 2 or the +number of CPU cores in the system, whichever is less. +.It Va hw.cxgbe.num_vis +Number of virtual interfaces (VIs) created for each port. +Each virtual interface creates a separate network interface. +The first virtual interface on each port is required and represents +the primary network interface on the port. +Additional virtual interfaces on a port are named using the Virtual Interface +name from the table above. +Additional virtual interfaces use a single pair of queues +for rx and tx as well an additional pair of queues for TOE rx and tx. +The default is 1. +.It Va hw.cxgbe.holdoff_timer_idx +.It Va hw.cxgbe.holdoff_timer_idx_ofld +Timer index value used to delay interrupts. +The holdoff timer list has the values 1, 5, 10, 50, 100, and 200 +by default (all values are in microseconds) and the index selects a +value from this list. +holdoff_timer_idx_ofld applies to queues used for TOE rx. +The default value is 1 which means the timer value is 5us. +Different interfaces can be assigned different values at any time via the +dev..X.holdoff_tmr_idx and dev..X.holdoff_tmr_idx_ofld sysctls. +.It Va hw.cxgbe.holdoff_pktc_idx +.It Va hw.cxgbe.holdoff_pktc_idx_ofld +Packet-count index value used to delay interrupts. +The packet-count list has the values 1, 8, 16, and 32 by default, +and the index selects a value from this list. +holdoff_pktc_idx_ofld applies to queues used for TOE rx. +The default value is -1 which means packet counting is disabled and interrupts +are generated based solely on the holdoff timer value. +Different interfaces can be assigned different values via the +dev..X.holdoff_pktc_idx and dev..X.holdoff_pktc_idx_ofld sysctls. +These sysctls work only when the interface has never been marked up (as done by +ifconfig up). +.It Va hw.cxgbe.qsize_txq +Number of entries in a transmit queue's descriptor ring. +A buf_ring of the same size is also allocated for additional +software queuing. +See +.Xr ifnet 9 . +The default value is 1024. +Different interfaces can be assigned different values via the +dev..X.qsize_txq sysctl. +This sysctl works only when the interface has never been marked up (as done by +ifconfig up). +.It Va hw.cxgbe.qsize_rxq +Number of entries in a receive queue's descriptor ring. +The default value is 1024. +Different interfaces can be assigned different values via the +dev..X.qsize_rxq sysctl. +This sysctl works only when the interface has never been marked up (as done by +ifconfig up). +.It Va hw.cxgbe.interrupt_types +Permitted interrupt types. +Bit 0 represents INTx (line interrupts), bit 1 MSI, and bit 2 MSI-X. +The default is 7 (all allowed). +The driver selects the best possible type out of the allowed types. +.It Va hw.cxgbe.pcie_relaxed_ordering +PCIe Relaxed Ordering. +-1 indicates the driver should determine whether to enable or disable PCIe RO. +0 disables PCIe RO. +1 enables PCIe RO. +2 indicates the driver should not modify the PCIe RO setting. +The default is -1. +.It Va hw.cxgbe.fw_install +0 prohibits the driver from installing a firmware on the card. +1 allows the driver to install a new firmware if internal driver +heuristics indicate that the new firmware is preferable to the one +already on the card. +2 instructs the driver to always install the new firmware on the card as +long as it is compatible with the driver and is a different version than +the one already on the card. +The default is 1. +.It Va hw.cxgbe.fl_pktshift +Number of padding bytes inserted before the beginning of an Ethernet +frame in the receive buffer. +The default value is 0. +A value of 2 would ensure that the Ethernet payload (usually the IP header) +is at a 4 byte aligned address. +0-7 are all valid values. +.It Va hw.cxgbe.fl_pad +A non-zero value ensures that writes from the hardware to a receive buffer are +padded up to the specified boundary. +The default is -1 which lets the driver pick a pad boundary. +0 disables trailer padding completely. +.It Va hw.cxgbe.cong_drop +Controls the hardware response to congestion. +-1 disables congestion feedback and is not recommended. +0 instructs the hardware to backpressure its pipeline on congestion. +This usually results in the port emitting PAUSE frames. +1 instructs the hardware to drop frames destined for congested queues. +2 instructs the hardware to both backpressure the pipeline and drop frames. +.It Va hw.cxgbe.pause_settings +PAUSE frame settings. +Bit 0 is rx_pause, bit 1 is tx_pause, bit 2 is pause_autoneg. +rx_pause = 1 instructs the hardware to heed incoming PAUSE frames, 0 instructs +it to ignore them. +tx_pause = 1 allows the hardware to emit PAUSE frames when its receive FIFO +reaches a high threshold, 0 prohibits the hardware from emitting PAUSE frames. +pause_autoneg = 1 overrides the rx_pause and tx_pause bits and instructs the +hardware to negotiate PAUSE settings with the link peer. +The default is 7 (all three = 1). +This tunable establishes the default PAUSE settings for all ports. +Settings can be displayed and controlled on a per-port basis via the +dev..X.pause_settings sysctl. +.It Va hw.cxgbe.fec +Forward Error Correction settings. +-1 (default) means driver should automatically pick a value. +0 disables FEC. +Finer grained control can be achieved by setting individual bits. +Bit 0 enables RS FEC, bit 1 enables BASE-R FEC (aka Firecode FEC), bit +2 enables NO FEC, and bit 6 enables the FEC that is recommended by the +transceiver/cable that is plugged in. +These bits can be set together in any combination. +This tunable establishes the default FEC settings for all ports. +Settings can be controlled on a per-port basis via the +dev..X.requested_fec sysctl. +The FEC in use on the link is available in dev..X.link_fec when +the link is up. +.It Va hw.cxgbe.autoneg +Link autonegotiation settings. +This tunable establishes the default autonegotiation settings for all ports. +Settings can be displayed and controlled on a per-port basis via the +dev..X.autoneg sysctl. +0 disables autonegotiation. +1 enables autonegotiation. +The default is -1 which lets the driver pick a value. +dev..X.autoneg is -1 for port and module combinations that do not support +autonegotiation. +.It Va hw.cxgbe.buffer_packing +Allow the hardware to deliver multiple frames in the same receive buffer +opportunistically. +The default is -1 which lets the driver decide. +0 or 1 explicitly disable or enable this feature. +.It Va hw.cxgbe.largest_rx_cluster +.It Va hw.cxgbe.safest_rx_cluster +Sizes of rx clusters. +Each of these must be set to one of the sizes available +(usually 2048, 4096, 9216, and 16384) and largest_rx_cluster must be greater +than or equal to safest_rx_cluster. +The defaults are 16384 and 4096 respectively. +The driver never attempts to allocate a receive buffer larger than +largest_rx_cluster and falls back to allocating buffers of +safest_rx_cluster size if an allocation larger than safest_rx_cluster fails. +Note that largest_rx_cluster merely establishes a ceiling -- the driver is +allowed to allocate buffers of smaller sizes. +.It Va hw.cxgbe.config_file +Select a pre-packaged device configuration file. +A configuration file contains a recipe for partitioning and configuring the +hardware resources on the card. +This tunable is for specialized applications only and should not be used in +normal operation. +The configuration profile currently in use is available in the dev..X.cf +and dev..X.cfcsum sysctls. +.It Va hw.cxgbe.linkcaps_allowed +.It Va hw.cxgbe.niccaps_allowed +.It Va hw.cxgbe.toecaps_allowed +.It Va hw.cxgbe.rdmacaps_allowed +.It Va hw.cxgbe.iscsicaps_allowed +.It Va hw.cxgbe.fcoecaps_allowed +Disallowing capabilities provides a hint to the driver and firmware to not +reserve hardware resources for that feature. +Each of these is a bit field with a bit for each sub-capability within the +capability. +This tunable is for specialized applications only and should not be used in +normal operation. +The capabilities for which hardware resources have been reserved are listed in +dev..X.*caps sysctls. +.It Va hw.cxgbe.tx_vm_wr +Setting this to 1 instructs the driver to use VM work requests to transmit data. +This lets PF interfaces transmit frames to VF interfaces over the internal +switch in the ASIC. +Note that the +.Xr cxgbev 4 +VF driver always uses VM work requests and is not affected by this tunable. +The default value is 0 and should be changed only if PF and VF interfaces need +to communicate with each other. +Different interfaces can be assigned different values using the +dev..X.tx_vm_wr sysctl when the interface is administratively down. +.It Va hw.cxgbe.attack_filter +Set to 1 to enable the "attack filter". +Default is 0. +The attack filter will drop an incoming frame if any of these conditions is +true: src ip/ip6 == dst ip/ip6; tcp and src/dst ip is not unicast; src/dst ip is +loopback (127.x.y.z); src ip6 is not unicast; src/dst ip6 is loopback (::1/128) +or unspecified (::/128); tcp and src/dst ip6 is mcast (ff00::/8). +This facility is available on T4 and T5 based cards only. +.It Va hw.cxgbe.drop_ip_fragments +Set to 1 to drop all incoming IP fragments. +Default is 0. +Note that this drops valid frames. +.It Va hw.cxgbe.drop_pkts_with_l2_errors +Set to 1 to drop incoming frames with Layer 2 length or checksum errors. +Default is 1. +.It Va hw.cxgbe.drop_pkts_with_l3_errors +Set to 1 to drop incoming frames with IP version, length, or checksum errors. +The IP checksum is validated for TCP or UDP packets only. +Default is 0. +.It Va hw.cxgbe.drop_pkts_with_l4_errors +Set to 1 to drop incoming frames with Layer 4 (TCP or UDP) length, +checksum, or other errors. +Default is 0. +.El +.Sh SUPPORT +For general information and support, +go to the Chelsio support website at: +.Pa http://www.chelsio.com/ . +.Pp +If an issue is identified with this driver with a supported adapter, +email all the specific information related to the issue to +.Aq Mt support@chelsio.com . +.Sh SEE ALSO +.Xr arp 4 , +.Xr ccr 4 , +.Xr cxgb 4 , +.Xr cxgbev 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 9.0 . +Support for T5 cards first appeared in +.Fx 9.2 +and +.Fx 10.0 . +Support for T6 cards first appeared in +.Fx 11.1 +and +.Fx 12.0 . +Support for T7 cards first appeared in +.Fx 15.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Navdeep Parhar Aq Mt np@FreeBSD.org . diff --git a/static/freebsd/man4/cxgbev.4 b/static/freebsd/man4/cxgbev.4 new file mode 100644 index 00000000..4ce67aed --- /dev/null +++ b/static/freebsd/man4/cxgbev.4 @@ -0,0 +1,310 @@ +.\" Copyright (c) 2011-2016, Chelsio Inc +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright notice, +.\" this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Chelsio Inc nor the names of its +.\" contributors may be used to endorse or promote products derived from +.\" this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 COPYRIGHT OWNER 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. +.\" +.\" * Other names and brands may be claimed as the property of others. +.\" +.Dd November 10, 2022 +.Dt CXGBEV 4 +.Os +.Sh NAME +.Nm cxgbev +.Nd "Chelsio T4-, T5-, and T6-based 100Gb, 40Gb, 25Gb, 10Gb, and 1Gb Ethernet VF driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device cxgbe" +.Cd "device cxgbev" +.Ed +.Pp +To load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_cxgbev_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for Virtual Functions on PCI Express Ethernet adapters +based on the Chelsio Terminator 4, Terminator 5, and Terminator 6 ASICs +(T4, T5, and T6). +The driver supports Jumbo Frames, Transmit/Receive checksum offload, +TCP segmentation offload (TSO), Large Receive Offload (LRO), VLAN +tag insertion/extraction, VLAN checksum offload, VLAN TSO, and +Receive Side Steering (RSS). +For further hardware information and questions related to hardware +requirements, see +.Pa http://www.chelsio.com/ . +.Pp +The +.Nm +driver uses different names for devices based on the associated ASIC: +.Bl -column -offset indent "ASIC" "Port Name" +.It Sy ASIC Ta Sy Port Name Ta Sy Parent Device +.It T4 Ta cxgbev Ta t4vf +.It T5 Ta cxlv Ta t5vf +.It T6 Ta ccv Ta t6vf +.El +.Pp +Loader tunables with the hw.cxgbe prefix apply to VFs from all cards. +The Physical Function driver for Chelsio Terminator adapters shares these +tunables. +The driver provides sysctl MIBs for both ports and parent devices using +the names above. +For example, a T5 VF provides port MIBs under dev.cxlv and +parent device MIBs under dev.t5vf. +References to sysctl MIBs in the remainder of this page use +dev. for port MIBs and dev. for parent device MIBs. +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports Virtual Functions on 100Gb and 25Gb Ethernet adapters +based on the T6 ASIC: +.Pp +.Bl -bullet -compact +.It +Chelsio T6225-CR +.It +Chelsio T6225-SO-CR +.It +Chelsio T62100-LP-CR +.It +Chelsio T62100-SO-CR +.It +Chelsio T62100-CR +.El +.Pp +The +.Nm +driver supports Virtual Functions on 40Gb, 10Gb and 1Gb Ethernet adapters +based on the T5 ASIC: +.Pp +.Bl -bullet -compact +.It +Chelsio T580-CR +.It +Chelsio T580-LP-CR +.It +Chelsio T580-LP-SO-CR +.It +Chelsio T560-CR +.It +Chelsio T540-CR +.It +Chelsio T540-LP-CR +.It +Chelsio T522-CR +.It +Chelsio T520-LL-CR +.It +Chelsio T520-CR +.It +Chelsio T520-SO +.It +Chelsio T520-BT +.It +Chelsio T504-BT +.El +.Pp +The +.Nm +driver supports Virtual Functions on 10Gb and 1Gb Ethernet adapters based +on the T4 ASIC: +.Pp +.Bl -bullet -compact +.It +Chelsio T420-CR +.It +Chelsio T422-CR +.It +Chelsio T440-CR +.It +Chelsio T420-BCH +.It +Chelsio T440-BCH +.It +Chelsio T440-CH +.It +Chelsio T420-SO +.It +Chelsio T420-CX +.It +Chelsio T420-BT +.It +Chelsio T404-BT +.El +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width indent +.It Va hw.cxgbe.ntxq +Number of tx queues used for a port. +The default is 16 or the number +of CPU cores in the system, whichever is less. +.It Va hw.cxgbe.nrxq +Number of rx queues used for a port. +The default is 8 or the number +of CPU cores in the system, whichever is less. +.It Va hw.cxgbe.holdoff_timer_idx +Timer index value used to delay interrupts. +The holdoff timer list has the values 1, 5, 10, 50, 100, and 200 +by default (all values are in microseconds) and the index selects a +value from this list. +The default value is 1 which means the timer value is 5us. +Different interfaces can be assigned different values at any time via the +dev..X.holdoff_tmr_idx sysctl. +.It Va hw.cxgbe.holdoff_pktc_idx +Packet-count index value used to delay interrupts. +The packet-count list has the values 1, 8, 16, and 32 by default, +and the index selects a value from this list. +The default value is -1 which means packet counting is disabled and interrupts +are generated based solely on the holdoff timer value. +Different interfaces can be assigned different values via the +dev..X.holdoff_pktc_idx sysctl. +This sysctl works only when the interface has never been marked up (as done by +ifconfig up). +.It Va hw.cxgbe.qsize_txq +Number of entries in a transmit queue's descriptor ring. +A buf_ring of the same size is also allocated for additional +software queuing. +See +.Xr ifnet 9 . +The default value is 1024. +Different interfaces can be assigned different values via the +dev..X.qsize_txq sysctl. +This sysctl works only when the interface has never been marked up (as done by +ifconfig up). +.It Va hw.cxgbe.qsize_rxq +Number of entries in a receive queue's descriptor ring. +The default value is 1024. +Different interfaces can be assigned different values via the +dev..X.qsize_rxq sysctl. +This sysctl works only when the interface has never been marked up (as done by +ifconfig up). +.It Va hw.cxgbe.interrupt_types +Permitted interrupt types. +Bit 0 represents INTx (line interrupts), bit 1 MSI, and bit 2 MSI-X. +The default is 7 (all allowed). +The driver selects the best possible type out of the allowed types. +Note that Virtual Functions do not support INTx interrupts and fail +to attach if neither MSI nor MSI-X are enabled. +.It Va hw.cxgbe.fl_pktshift +Number of padding bytes inserted before the beginning of an Ethernet +frame in the receive buffer. +The default value of 2 ensures that the Ethernet payload (usually the IP header) +is at a 4 byte aligned address. +0-7 are all valid values. +.It Va hw.cxgbe.fl_pad +A non-zero value ensures that writes from the hardware to a receive buffer are +padded up to the specified boundary. +The default is -1 which lets the driver pick a pad boundary. +0 disables trailer padding completely. +.It Va hw.cxgbe.buffer_packing +Allow the hardware to deliver multiple frames in the same receive buffer +opportunistically. +The default is -1 which lets the driver decide. +0 or 1 explicitly disable or enable this feature. +.It Va hw.cxgbe.allow_mbufs_in_cluster +1 allows the driver to lay down one or more mbufs within the receive buffer +opportunistically. +This is the default. +0 prohibits the driver from doing so. +.It Va hw.cxgbe.largest_rx_cluster +.It Va hw.cxgbe.safest_rx_cluster +Sizes of rx clusters. +Each of these must be set to one of the sizes available +(usually 2048, 4096, 9216, and 16384) and largest_rx_cluster must be greater +than or equal to safest_rx_cluster. +The defaults are 16384 and 4096 respectively. +The driver never attempts to allocate a receive buffer larger than +largest_rx_cluster and falls back to allocating buffers of +safest_rx_cluster size if an allocation larger than safest_rx_cluster fails. +Note that largest_rx_cluster merely establishes a ceiling -- the driver is +allowed to allocate buffers of smaller sizes. +.El +.Pp +Certain settings and resources for Virtual Functions are dictated +by the parent Physical Function driver. +For example, the Physical Function driver limits the number of queues +available to a Virtual Function. +Some of these limits can be adjusted in the firmware configuration file +used with the Physical Function driver. +.Pp +The PAUSE settings on the port of a Virtual Function are inherited from +the settings of the same port on the Physical Function. +Virtual Functions cannot modify the setting and track changes made to +the associated port's setting by the Physical Function driver. +.Pp +Receive queues on a Virtual Function always drop packets in response to +congestion +.Po +equivalent to setting +.Va hw.cxgbe.cong_drop +to 1 +.Pc . +.Pp +The VF driver currently depends on the PF driver. +As a result, loading the VF driver also loads the PF driver as a +dependency. +.Sh SUPPORT +For general information and support, +go to the Chelsio support website at: +.Pa http://www.chelsio.com/ . +.Pp +If an issue is identified with this driver with a supported adapter, +email all the specific information related to the issue to +.Aq Mt support@chelsio.com . +.Sh SEE ALSO +.Xr arp 4 , +.Xr cxgbe 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 11.1 +and +.Fx 11.1 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Navdeep Parhar Aq Mt np@FreeBSD.org +and +.An John Baldwin Aq Mt jhb@FreeBSD.org . diff --git a/static/freebsd/man4/cyapa.4 b/static/freebsd/man4/cyapa.4 new file mode 100644 index 00000000..d7987842 --- /dev/null +++ b/static/freebsd/man4/cyapa.4 @@ -0,0 +1,228 @@ +.\" Copyright (c) 2015 Michael Gmelin +.\" 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 December 18, 2018 +.Dt CYAPA 4 +.Os +.Sh NAME +.Nm cyapa +.Nd Cypress APA trackpad with I2C interface driver +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines into +the kernel configuration file: +.Bd -ragged -offset indent +.Cd "device cyapa" +.Cd "device ig4" +.Cd "device iicbus" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +cyapa_load="YES" +ig4_load="YES" +.Ed +.Pp +On many Chromebook models this driver can be automatically configured with the +help of the +.Xr chromebook_platform 4 +driver. +Alternatively, the +.Nm +driver can be manually configured in +.Pa /boot/device.hints : +.Cd hint.cyapa.0.at="iicbus0" +.Cd hint.cyapa.0.addr="0xCE" +.Cd hint.cyapa.1.at="iicbus1" +.Cd hint.cyapa.1.addr="0xCE" +.Sh DESCRIPTION +The +.Nm +driver provides support for the Cypress APA trackpad. +It emulates the IntelliMouse PS/2 protocol. +It supports basic mouse ioctls, so that +.Xr moused 8 +is supported properly. +.Ss Trackpad layout +.Bd -literal + 2/3 1/3 + +--------------------+------------+ + | | Middle | + | | Button | + | Left | | + | Button +------------+ + | | Right | + | | Button | + +--------------------+............| + | Thumb/Button Area | 15% + +---------------------------------+ +.Ed +.Ss Trackpad features +.Bl -tag -width 8n +.It Va Two finger scrolling +Use two fingers for Z axis scrolling. +.It Va Button down/second finger +While one finger clicks and holds down the touchpad, the second finger can be +used to move the mouse cursor. +This can be useful for drawing or selecting text. +.It Va Thumb/Button area +The lower 15% of the trackpad will not affect the mouse cursor position. +This allows for high precision clicking, by controlling the cursor with the +index finger and pushing/holding the pad down with the thumb. +.It Va Trackpad button +Push physical button. +The left two thirds of the pad issues a LEFT button event. +The upper right corner issues a MIDDLE button event. +The lower right corner issues a RIGHT button. +Optionally, tap to click can be enabled (see below). +.El +.Pp +On a system using +.Xr device.hints 5 , +these values are configurable for +.Nm : +.Bl -tag -width "hint.cyapa.%d.addr" +.It Va hint.cyapa.%d.at +target +.Xr iicbus 4 . +.It Va hint.cyapa.%d.addr +.Nm +i2c address on the +.Xr iicbus 4 . +.El +.Sh SYSCTL VARIABLES +These +.Xr sysctl 8 +variables are available: +.Bl -tag -width 8n +.It Va debug.cyapa_idle_freq +Scan frequency in idle mode, the default is 1. +.It Va debug.cyapa_slow_freq +Scan frequency in slow mode, the default is 20. +.It Va debug.cyapa_norm_freq +Scan frequency in normal mode, the default is 100. +.It Va debug.cyapa_minpressure +Minimum pressure to detect a finger, the default is 12. +.It Va debug.cyapa_enable_tapclick +Controls tap to click. +Possible values: +.Bl -tag -width 8n +.It 0 +Tap to click is disabled. +This is the default value. +.It 1 +Tap to click always generates a left mouse button event. +.It 2 +Tap to click generates left mouse button event if the left 2/3rds of the pad +are tapped and a right mouse button event otherwise. +.It 3 +Tap to click generates mouse button events as if the physical button was +pressed (see +.Sx DESCRIPTION +above). +.El +.It Va debug.cyapa_tapclick_min_ticks +Minimum tap duration in ticks to create a click, the default is 1. +.It Va debug.cyapa_tapclick_max_ticks +Maximum tap duration in ticks to create a click, the default is 8. +.It Va debug.cyapa_move_min_ticks +Minimum ticks before cursor movement occurs, the default is 4. +.It Va debug.cyapa_scroll_wait_ticks +Ticks to wait before starting to scroll, the default is 0. +.It Va debug.cyapa_scroll_stick_ticks +Ticks while preventing cursor movement on single finger after scroll, +the default is 15. +.It Va debug.cyapa_thumbarea_percent +Size of bottom thumb area in percent, the default is 15. +.It Va debug.cyapa_debug +Setting this to a non-zero value enables debug output to console and syslog, +the default is 0. +.It Va debug.cyapa_reset +Setting this to a non-zero value reinitializes the device. +The sysctl resets to zero immediately. +.El +.Sh FILES +.Nm +creates +.Pa /dev/cyapa0 , +which presents the mouse as an +.Ar IntelliMouse PS/2 +device. +It supports +.Xr moused 8 +levels 0 through 2, level 1 is used by default. +.Sh EXAMPLES +To use +.Nm +with +.Xr moused 8 , +add the following lines to the +.Xr rc.conf 5 +file: +.Pp +.Dl moused_enable="YES" +.Dl moused_port="/dev/cyapa0" +.Pp +If vertical scrolling is not desired, add +.Pp +.Dl moused_flags="-l0" +.Pp +to +.Xr rc.conf 5 . +.Pp +Enable tap to click for the left and the right mouse button and +disable the thumb area by adding these lines to the +.Xr sysctl.conf 5 +file: +.Pp +.Dl debug.cyapa_thumbarea_percent=0 +.Dl debug.cyapa_enable_tapclick=2 +.Sh SEE ALSO +.Xr chromebook_platform 4 , +.Xr ig4 4 , +.Xr iicbus 4 , +.Xr sysmouse 4 , +.Xr moused 8 +.Sh AUTHORS +.An -nosplit +The original +.Nm +driver was written for +.Dx +by +.An Matthew Dillon . +.Pp +It has been ported, modified, and enhanced for +.Fx +by +.An Michael Gmelin Aq Mt freebsd@grem.de . +.Pp +This manual page was written by +.An Michael Gmelin Aq Mt freebsd@grem.de . +.Sh BUGS +The +.Nm +driver detects the device from the I2C address. +This might have unforeseen consequences if the initialization sequence +is sent to an unknown device at that address. diff --git a/static/freebsd/man4/da.4 b/static/freebsd/man4/da.4 new file mode 100644 index 00000000..b5a66f9c --- /dev/null +++ b/static/freebsd/man4/da.4 @@ -0,0 +1,255 @@ +.\" Copyright (c) 1996 +.\" Julian Elischer . 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 September 10, 2022 +.Dt DA 4 +.Os +.Sh NAME +.Nm da +.Nd SCSI Direct Access device driver +.Sh SYNOPSIS +.Cd device da +.Sh DESCRIPTION +The +.Nm +driver provides support for all +.Tn SCSI +devices of the direct access class that are attached to the system +through a supported +.Tn SCSI +Host Adapter. +The direct access class includes disk, magneto-optical, +and solid-state devices. +.Pp +A +.Tn SCSI +Host +adapter must also be separately configured into the system +before a +.Tn SCSI +direct access device can be configured. +.Sh CACHE EFFECTS +Many direct access devices are equipped with read and/or write caches. +Parameters affecting the device's cache are stored in mode page 8, +the caching control page. +Mode pages can be examined and modified via the +.Xr camcontrol 8 +utility. +.Pp +The read cache is used to store data from device-initiated read ahead +operations as well as frequently used data. +The read cache is transparent +to the user and can be enabled without any adverse effect. +Most devices +with a read cache come from the factory with it enabled. +The read cache can be disabled by setting the +.Tn RCD +(Read Cache Disable) bit in the caching control mode page. +.Pp +The write cache can greatly decrease the latency of write operations +and allows the device to reorganize writes to increase efficiency and +performance. +This performance gain comes at a price. +Should the device +lose power while its cache contains uncommitted write operations, these +writes will be lost. +The effect of a loss of write transactions on +a file system is non-deterministic and can cause corruption. +Most +devices age write transactions to limit vulnerability to a few transactions +recently reported as complete, but it is none-the-less recommended that +systems with write cache enabled devices reside on an Uninterruptible +Power Supply (UPS). +The +.Nm +device driver ensures that the cache and media are synchronized upon +final close of the device or an unexpected shutdown (panic) event. +This ensures that it is safe to disconnect power once the operating system +has reported that it has halted. +The write cache can be enabled by setting the +.Tn WCE +(Write Cache Enable) bit in the caching control mode page. +.Sh TAGGED QUEUING +The +.Nm +device driver will take full advantage of the SCSI feature known as tagged +queueing. +Tagged queueing allows the device to process multiple transactions +concurrently, often re-ordering them to reduce the number and length of +seeks. +To ensure that transactions to distant portions of the media, +which may be deferred indefinitely by servicing requests nearer the current +head position, are completed in a timely fashion, an ordered tagged +transaction is sent every 15 seconds during continuous device operation. +.Sh BAD BLOCK RECOVERY +Direct Access devices have the capability of mapping out portions of +defective media. +Media recovery parameters are located in mode page 1, +the Read-Write Error Recovery mode page. +The most important media +remapping features are 'Auto Write Reallocation' and 'Auto Read +Reallocation' which can be enabled via the AWRE and ARRE bits, +respectively, of the Read-Write Error Recovery page. +Many devices do not ship from the factory with these feature enabled. +Mode pages can be examined and modified +via the +.Xr camcontrol 8 +utility. +.Sh KERNEL CONFIGURATION +It is only necessary to explicitly configure one +.Nm +device; data structures are dynamically allocated as disks are found +on the +.Tn SCSI +bus. +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width 12 +.It Va kern.cam.da.default_timeout +This variable determines how long the +.Nm +driver will wait before timing out an outstanding command. +The units for this value are seconds, and the default is currently 60 +seconds. +.It Va kern.cam.da.disable_wp_protection +Disable detection of write-protected disks. +Default is disabled. +.Po +detection of write-protected disks is enabled +.Pc . +.It Va kern.cam.da.enable_biospeedup +Enable +.Dv BIO_SPEEDUP +processing. +Default is enabled. +.It Va kern.cam.da.enable_uma_ccbs +Use UMA for CCBs. +Default is enabled. +.It Va kern.cam.da.poll_period +Media polling period in seconds. +Default is 3 seconds. +.It Va kern.cam.da.retry_count +This variable determines how many times the +.Nm +driver will retry a READ or WRITE command. +This does not affect the number of retries used during probe time or for +the +.Nm +driver dump routine. +This value currently defaults to 4. +.It Va kern.cam.da.send_ordered +Send Ordered Tags. +On shutdown, step through all the +.Nm +peripheral drivers, and if the device is still open, +sync the disk to physical media. +Default is enabled. +.It Va kern.cam.sort_io_queue +.It Va kern.cam.da . Ns Ar X Ns Va .sort_io_queue +These variables determine whether request queue should be sorted trying +to optimize head seeks. +Set to 1 to enable sorting, 0 to disable, -1 to leave it as-is. +The default is sorting enabled for HDDs and disabled for SSDs. +.It Va kern.cam.da . Ns Ar X Ns Va .delete_method +This variable specifies method to handle BIO_DELETE requests: +.Bl -tag -width "ATA_TRIM" +.It ATA_TRIM +ATA TRIM via ATA COMMAND PASS THROUGH command, +.It UNMAP +UNMAP command, +.It WS16 +WRITE SAME(16) command with UNMAP flag, +.It WS10 +WRITE SAME(10) command with UNMAP flag, +.It ZERO +WRITE SAME(10) command without UNMAP flag, +.It DISABLE +disable BIO_DELETE support. +.El +.It Va kern.cam.da . Ns Ar X Ns Va .minimum_cmd_size +This variable determines what the minimum READ/WRITE CDB size is for a +given +.Nm +unit. +Valid minimum command size values are 6, 10, 12 and 16 bytes. +The default is 6 bytes. +.Pp +The +.Nm +driver issues a CAM Path Inquiry CCB at probe time to determine whether the +protocol the device in question speaks (e.g.\& ATAPI) typically does not allow +6 byte commands. +If it does not, the +.Nm +driver will default to using at least 10 byte CDBs. +If a 6 byte READ or WRITE fails with an ILLEGAL REQUEST error, the +.Nm +driver will then increase the default CDB size for the device to 10 bytes and +retry the command. +CDB size is always +chosen as the smallest READ/WRITE CDB that will satisfy the specified minimum +command size, and the LBA and length of the READ or WRITE in question. +(e.g., a write to an LBA larger than 2^32 will require a 16 byte CDB.) +.El +.Sh NOTES +If a device becomes invalidated (media is removed, device becomes unresponsive) +the disklabel and information held within the kernel about the device will +be invalidated. +To avoid corruption of a newly inserted piece of media or +a replacement device, all accesses to the device will be discarded until +the last file descriptor referencing the old device is closed. +During this period, all new open attempts will be rejected. +.Sh FILES +.Bl -tag -width ".Pa /dev/da*" -compact +.It Pa /dev/da* +SCSI disk device nodes +.El +.Sh DIAGNOSTICS +None. +.Sh SEE ALSO +.Xr ada 4 , +.Xr cam 4 , +.Xr geom 4 , +.Xr nda 4 , +.Xr gpart 8 +.Sh HISTORY +The +.Nm +driver was written for the +.Tn CAM +.Tn SCSI +subsystem by +.An Justin T. Gibbs . +Many ideas were gleaned from the +.Nm sd +device driver written and ported from +.Tn Mach +2.5 +by +.An Julian Elischer . diff --git a/static/freebsd/man4/dc.4 b/static/freebsd/man4/dc.4 new file mode 100644 index 00000000..d8a7d7db --- /dev/null +++ b/static/freebsd/man4/dc.4 @@ -0,0 +1,422 @@ +.\" Copyright (c) 1997, 1998, 1999 +.\" Bill Paul . 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 Bill Paul. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Bill Paul 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 Bill Paul OR THE VOICES IN HIS HEAD +.\" 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 26, 2020 +.Dt DC 4 +.Os +.Sh NAME +.Nm dc +.Nd "DEC/Intel 21143 and clone 10/100 Ethernet driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device dc" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_dc_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for several PCI Fast Ethernet adapters and +embedded controllers based on the DEC/Intel 21143 chipset and clones. +.Pp +All of supported chipsets have the same general register layout, DMA +descriptor format and method of operation. +All of the clone chips +are based on the 21143 design with various modifications. +The +21143 itself has support for 10baseT, BNC, AUI, MII and symbol +media attachments, 10 and 100Mbps speeds in full or half duplex, +built in NWAY autonegotiation and wake on LAN. +The 21143 also +offers several receive filter programming options including +perfect filtering, inverse perfect filtering and hash table +filtering. +.Pp +Some clone chips duplicate the 21143 fairly closely while others +only maintain superficial similarities. +Some support only MII +media attachments. +Others use different receiver filter programming +mechanisms. +At least one supports only chained DMA descriptors +(most support both chained descriptors and contiguously allocated +fixed size rings). +Some chips (especially the PNIC) also have +peculiar bugs. +The +.Nm +driver does its best to provide generalized support for all +of these chipsets in order to keep special case code to a minimum. +.Pp +These chips are used by many vendors which makes it +difficult to provide a complete list of all supported cards. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width ".Cm 10baseT/UTP" +.It Cm autoselect +Enable autoselection of the media type and options. +The user can manually override +the autoselected mode by adding media options to the +.Pa /etc/rc.conf +file. +.Pp +Note: the built-in NWAY autonegotiation on the original PNIC 82c168 +chip is horribly broken and is not supported by the +.Nm +driver at this time (see the +.Sx BUGS +section for details). +The original 82c168 appears +on very early revisions of the LinkSys LNE100TX and Matrox FastNIC. +.It Cm 10baseT/UTP +Set 10Mbps operation. +The +.Cm mediaopt +option can also be used to enable +.Cm full-duplex +operation. +Not specifying +.Cm full-duplex +implies +.Cm half-duplex +mode. +.It Cm 100baseTX +Set 100Mbps (Fast Ethernet) operation. +The +.Cm mediaopt +option can also be used to enable +.Cm full-duplex +operation. +Not specifying +.Cm full-duplex +implies +.Cm half-duplex +mode. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width ".Cm full-duplex" +.It Cm full-duplex +Force full duplex operation. +The interface will operate in +half duplex mode if this media option is not specified. +.El +.Pp +Note that the 100baseTX media type may not be available on certain +Intel 21143 adapters which support 10Mbps media attachments only. +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver provides support for the following chipsets: +.Pp +.Bl -bullet -compact +.It +DEC/Intel 21143 +.It +ADMtek AL981 Comet, AN985 Centaur, ADM9511 Centaur II and ADM9513 +Centaur II +.It +ALi/ULi M5261 and M5263 +.It +ASIX Electronics AX88140A and AX88141 +.It +Conexant LANfinity RS7112 (miniPCI) +.It +Davicom DM9009, DM9100, DM9102 and DM9102A +.It +Lite-On 82c168 and 82c169 PNIC +.It +Lite-On/Macronix 82c115 PNIC II +.It +Macronix 98713, 98713A, 98715, 98715A, 98715AEC-C, 98725, 98727 and 98732 +.It +Xircom X3201 (cardbus only) +.El +.Pp +The +following NICs are known to work with the +.Nm +driver at this time: +.Pp +.Bl -bullet -compact +.It +3Com OfficeConnect 10/100B (ADMtek AN985 Centaur-P) +.It +Abocom FE2500 +.It +Accton EN1217 (98715A) +.It +Accton EN2242 MiniPCI +.It +Adico AE310TX (98715A) +.It +Alfa Inc GFC2204 (ASIX AX88140A) +.It +Built in 10Mbps only Ethernet on Compaq Presario 7900 series +desktops (21143, non-MII) +.It +Built in Ethernet on LinkSys EtherFast 10/100 Instant GigaDrive (DM9102, MII) +.It +CNet Pro110B (ASIX AX88140A) +.It +CNet Pro120A (98715A or 98713A) and CNet Pro120B (98715) +.It +Compex RL100-TX (98713 or 98713A) +.It +D-Link DFE-570TX (21143, MII, quad port) +.It +Digital DE500-BA 10/100 (21143, non-MII) +.It +ELECOM Laneed LD-CBL/TXA (ADMtek AN985) +.It +Hawking CB102 CardBus +.It +IBM EtherJet Cardbus Adapter +.It +Intel PRO/100 Mobile Cardbus (versions that use the X3201 chipset) +.It +Jaton XpressNet (Davicom DM9102) +.It +Kingston KNE100TX (21143, MII) +.It +Kingston KNE110TX (PNIC 82c169) +.It +LinkSys LNE100TX (PNIC 82c168, 82c169) +.It +LinkSys LNE100TX v2.0 (PNIC II 82c115) +.It +LinkSys LNE100TX v4.0/4.1 (ADMtek AN985 Centaur-P) +.It +Matrox FastNIC 10/100 (PNIC 82c168, 82c169) +.It +Melco LGY-PCI-TXL +.It +Microsoft MN-120 10/100 CardBus (ADMTek Centaur-C) +.It +Microsoft MN-130 10/100 PCI (ADMTek Centaur-P) +.It +NDC SOHOware SFA110A (98713A) +.It +NDC SOHOware SFA110A Rev B4 (98715AEC-C) +.It +NetGear FA310-TX Rev.\& D1, D2 or D3 (PNIC 82c169) +.It +Netgear FA511 +.It +PlaneX FNW-3602-T (ADMtek AN985) +.It +SMC EZ Card 10/100 1233A-TX (ADMtek AN985) +.It +SVEC PN102-TX (98713) +.It +Xircom Cardbus Realport +.It +Xircom Cardbus Ethernet 10/100 +.It +Xircom Cardbus Ethernet II 10/100 +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "dc%d: couldn't map ports/memory" +A fatal initialization error has occurred. +.It "dc%d: couldn't map interrupt" +A fatal initialization error has occurred. +.It "dc%d: watchdog timeout" +A packet was queued for transmission and a transmit command was +issued, but the device failed to acknowledge the transmission +before a timeout expired. +This can happen if the device is unable +to deliver interrupts for some reason, of if there is a problem with +the network connection (cable or network equipment) that results in a loss +of link. +.It "dc%d: no memory for rx list" +The driver failed to allocate an mbuf for the receiver ring. +.It "dc%d: TX underrun -- increasing TX threshold" +The device generated a transmit underrun error while attempting to +DMA and transmit a packet. +This happens if the host is not able to +DMA the packet data into the NIC's FIFO fast enough. +The driver +will dynamically increase the transmit start threshold so that +more data must be DMAed into the FIFO before the NIC will start +transmitting it onto the wire. +.It "dc%d: TX underrun -- using store and forward mode" +The device continued to generate transmit underruns even after all +possible transmit start threshold settings had been tried, so the +driver programmed the chip for store and forward mode. +In this mode, +the NIC will not begin transmission until the entire packet has been +transferred into its FIFO memory. +.It "dc%d: chip is in D3 power state -- setting to D0" +This message applies only to adapters which support power +management. +Some operating systems place the controller in low power +mode when shutting down, and some PCI BIOSes fail to bring the chip +out of this state before configuring it. +The controller loses all of +its PCI configuration in the D3 state, so if the BIOS does not set +it back to full power mode in time, it will not be able to configure it +correctly. +The driver tries to detect this condition and bring +the adapter back to the D0 (full power) state, but this may not be +enough to return the driver to a fully operational condition. +If +you see this message at boot time and the driver fails to attach +the device as a network interface, you will have to perform a second +warm boot to have the device properly configured. +.Pp +Note that this condition only occurs when warm booting from another +operating system. +If you power down your system prior to booting +.Fx , +the card should be configured correctly. +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr polling 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Rs +.%T ADMtek AL981, AL983 and AL985 data sheets +.%U http://www.admtek.com.tw +.Re +.Rs +.%T ASIX Electronics AX88140A and AX88141 data sheets +.%U http://www.asix.com.tw +.Re +.Rs +.%T Davicom DM9102 data sheet +.%U http://www.davicom.com.tw/userfile/24247/DM9102H-DS-F01-021508.pdf +.Re +.Rs +.%T Intel 21143 Hardware Reference Manual +.%U http://developer.intel.com +.Re +.Rs +.%T Macronix 98713/A, 98715/A and 98725 data sheets +.%U http://www.macronix.com +.Re +.Rs +.%T Macronix 98713/A and 98715/A app notes +.%U http://www.macronix.com +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 4.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Bill Paul Aq Mt wpaul@ee.columbia.edu . +.Sh BUGS +The Macronix application notes claim that in order to put the +chips in normal operation, the driver must write a certain magic +number into the CSR16 register. +The numbers are documented in +the app notes, but the exact meaning of the bits is not. +.Pp +The 98713A seems to have a problem with 10Mbps full duplex mode. +The transmitter works but the receiver tends to produce many +unexplained errors leading to very poor overall performance. +The +98715A does not exhibit this problem. +All other modes on the +98713A seem to work correctly. +.Pp +The original 82c168 PNIC chip has built in NWAY support which is +used on certain early LinkSys LNE100TX and Matrox FastNIC cards, +however it is horribly broken and difficult to use reliably. +Consequently, autonegotiation is not currently supported for this +chipset: the driver defaults the NIC to 10baseT half duplex, and it is +up to the operator to manually select a different mode if necessary. +(Later cards use an external MII transceiver to implement NWAY +autonegotiation and work correctly.) +.Pp +The +.Nm +driver programs 82c168 and 82c169 PNIC chips to use the store and +forward setting for the transmit start threshold by default. +This +is to work around problems with some NIC/PCI bus combinations where +the PNIC can transmit corrupt frames when operating at 100Mbps, +probably due to PCI DMA burst transfer errors. +.Pp +The 82c168 and 82c169 PNIC chips also have a receiver bug that +sometimes manifests during periods of heavy receive and transmit +activity, where the chip will improperly DMA received frames to +the host. +The chips appear to upload several kilobytes of garbage +data along with the received frame data, dirtying several RX buffers +instead of just the expected one. +The +.Nm +driver detects this condition and will salvage the frame; however, +it incurs a serious performance penalty in the process. +.Pp +The PNIC chips also sometimes generate a transmit underrun error when +the driver attempts to download the receiver filter setup frame, which +can result in the receive filter being incorrectly programmed. +The +.Nm +driver will watch for this condition and requeue the setup frame until +it is transferred successfully. +.Pp +The ADMtek AL981 chip (and possibly the AN985 as well) has been observed +to sometimes wedge on transmit: this appears to happen when the driver +queues a sequence of frames which cause it to wrap from the end of the +transmit descriptor ring back to the beginning. +The +.Nm +driver attempts to avoid this condition by not queuing any frames past +the end of the transmit ring during a single invocation of the +.Fn dc_start +routine. +This workaround has a negligible impact on transmit performance. diff --git a/static/freebsd/man4/dcons.4 b/static/freebsd/man4/dcons.4 new file mode 100644 index 00000000..6ef58ea0 --- /dev/null +++ b/static/freebsd/man4/dcons.4 @@ -0,0 +1,123 @@ +.\" Copyright (c) 2003 Hidetoshi Shimokawa +.\" 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 ``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 January 26, 2008 +.Dt DCONS 4 +.Os +.Sh NAME +.Nm dcons +.Nd dumb console device driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "options GDB" +.Cd "device firewire" +.Cd "device dcons" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, +place the following line in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "options GDB" +.Ed +.Pp +and in +.Xr loader.conf 5 : +.Bd -ragged -offset indent +dcons_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +device is a simple console device which just reads from and writes to +an allocated buffer for input and output respectively. +It is of no use by itself and it is supposed that the buffer is accessed +via a bus like +.Xr firewire 4 +or +.Xr kvm 3 +for interaction. +.Pp +The buffer consists of 4 channels. +There are 2 ports, one for the console TTY and another is GDB port, +then each port has an input channel and an output channel. +.Sh FILES +.Bl -tag -width indent -compact +.It Pa /dev/dcons +.It Pa /etc/ttys +.El +.Sh EXAMPLES +If you want to run +.Xr getty 8 +on +.Nm , +insert the following line into +.Xr ttys 5 +and send a +.Dv HUP +signal to +.Xr init 8 +using +.Xr kill 1 . +.Bd -literal -offset indent +dcons "/usr/libexec/getty std.115200" vt100 on secure +.Ed +.Pp +Once the +.Xr fwohci 4 +device is initialized to allow physical access, +the buffer can be accessed from another host via a +.Xr firewire 4 +bus using the +.Xr dconschat 8 +application. +See +.Xr dconschat 8 +for more details. +.Pp +If you want to use +.Nm +as a +.Xr gdb 1 Pq Pa ports/devel/gdb +port, add the following line into +.Xr loader.conf 5 : +.Bd -literal -offset indent +dcons_gdb="1" +.Ed +.Sh SEE ALSO +.Xr dcons_crom 4 , +.Xr ddb 4 , +.Xr firewire 4 , +.Xr fwohci 4 , +.Xr gdb 4 , +.Xr ttys 5 , +.Xr conscontrol 8 , +.Xr dconschat 8 , +.Xr fwcontrol 8 +.Sh AUTHORS +.An Hidetoshi Shimokawa Aq Mt simokawa@FreeBSD.org +.Sh BUGS +This driver is +.Ud diff --git a/static/freebsd/man4/dcons_crom.4 b/static/freebsd/man4/dcons_crom.4 new file mode 100644 index 00000000..4eff05b6 --- /dev/null +++ b/static/freebsd/man4/dcons_crom.4 @@ -0,0 +1,59 @@ +.\" Copyright (c) 2003 Hidetoshi Shimokawa +.\" 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 ``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 June 16, 2003 +.Dt DCONS_CROM 4 +.Os +.Sh NAME +.Nm dcons_crom +.Nd Configuration ROM stub for +.Xr dcons 4 +.Sh SYNOPSIS +.Cd device dcons_crom +.Cd device dcons +.Cd device firewire +.Sh DESCRIPTION +The +.Nm +exposes the buffer address of +.Xr dcons 4 +through the Configuration ROM of +.Xr firewire 4 . +This address is supposed to be used by +.Xr dconschat 8 . +.Sh SEE ALSO +.Xr dcons 4 , +.Xr firewire 4 , +.Xr fwohci 4 , +.Xr dconschat 8 , +.Xr fwcontrol 8 +.Sh AUTHORS +.An Hidetoshi Shimokawa Aq Mt simokawa@FreeBSD.org +.Sh BUGS +If you load +.Pa dcons_crom.ko +manually after the system is booted, you may +have to initiate a bus reset using +.Dq Nm fwcontrol Fl r +to update the Configuration ROM. diff --git a/static/freebsd/man4/ddb.4 b/static/freebsd/man4/ddb.4 new file mode 100644 index 00000000..a882a520 --- /dev/null +++ b/static/freebsd/man4/ddb.4 @@ -0,0 +1,1713 @@ +.\" +.\" Mach Operating System +.\" Copyright (c) 1991,1990 Carnegie Mellon University +.\" Copyright (c) 2007 Robert N. M. Watson +.\" All Rights Reserved. +.\" +.\" Permission to use, copy, modify and distribute this software and its +.\" documentation is hereby granted, provided that both the copyright +.\" notice and this permission notice appear in all copies of the +.\" software, derivative works or modified versions, and any portions +.\" thereof, and that both notices appear in supporting documentation. +.\" +.\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" +.\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR +.\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. +.\" +.\" Carnegie Mellon requests users of this software to return to +.\" +.\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU +.\" School of Computer Science +.\" Carnegie Mellon University +.\" Pittsburgh PA 15213-3890 +.\" +.\" any improvements or extensions that they make and grant Carnegie Mellon +.\" the rights to redistribute these changes. +.\" +.Dd October 31, 2025 +.Dt DDB 4 +.Os +.Sh NAME +.Nm ddb +.Nd interactive kernel debugger +.Sh SYNOPSIS +In order to enable kernel debugging facilities include: +.Bd -ragged -offset indent +.Cd options KDB +.Cd options DDB +.Ed +.Pp +To prevent activation of the debugger on kernel +.Xr panic 9 : +.Bd -ragged -offset indent +.Cd options KDB_UNATTENDED +.Ed +.Pp +In order to print a stack trace of the current thread on the console +for a panic: +.Bd -ragged -offset indent +.Cd options KDB_TRACE +.Ed +.Pp +To print the numerical value of symbols in addition to the symbolic +representation, define: +.Bd -ragged -offset indent +.Cd options DDB_NUMSYM +.Ed +.Pp +To enable the +.Xr gdb 4 +backend, so that remote debugging with +.Xr kgdb 1 Pq Pa ports/devel/gdb +is possible, include: +.Bd -ragged -offset indent +.Cd options GDB +.Ed +.Sh DESCRIPTION +The +.Nm +kernel debugger is an interactive debugger with a syntax inspired by +.Xr gdb 1 Pq Pa ports/devel/gdb . +If linked into the running kernel, +it can be invoked locally with the +.Ql debug +.Xr keymap 5 +action, usually mapped to Ctrl+Alt+Esc, or by setting the +.Va debug.kdb.enter +sysctl to 1. +The debugger is also invoked on kernel +.Xr panic 9 +if the +.Va debug.debugger_on_panic +.Xr sysctl 8 +MIB variable is set non-zero, +which is the default +unless the +.Dv KDB_UNATTENDED +option is specified. +Similarly, if the +.Va debug.debugger_on_recursive_panic +variable is set to +.Dv 1 , +then the debugger will be invoked on a recursive kernel panic. +This variable has a default value of +.Dv 0 , +and has no effect if +.Va debug.debugger_on_panic +is already set non-zero. +.Pp +The current location is called +.Va dot . +The +.Va dot +is displayed with +a hexadecimal format at a prompt. +The commands +.Ic examine +and +.Ic write +update +.Va dot +to the address of the last line +examined or the last location modified, and set +.Va next +to the address of +the next location to be examined or changed. +Other commands do not change +.Va dot , +and set +.Va next +to be the same as +.Va dot . +.Pp +The general command syntax is: +.Ar command Ns Op Li / Ns Ar modifier +.Oo Ar addr Oc Ns Op , Ns Ar count +.Pp +A blank line repeats the previous command from the address +.Va next +with +count 1 and no modifiers. +Specifying +.Ar addr +sets +.Va dot +to the address. +Omitting +.Ar addr +uses +.Va dot . +A missing +.Ar count +is taken +to be 1 for printing commands or infinity for stack traces. +A +.Ar count +of -1 is equivalent to a missing +.Ar count . +Options that are supplied but not supported by the given +.Ar command +are usually ignored. +.Pp +The +.Nm +debugger has a pager feature (like the +.Xr more 1 +command) +for the output. +If an output line exceeds the number set in the +.Va lines +variable, it displays +.Dq Li --More-- +and waits for a response. +The valid responses for it are: +.Pp +.Bl -tag -compact -width ".Li SPC" +.It Li SPC +one more page +.It Li RET +one more line +.It Li q +abort the current command, and return to the command input mode +.El +.Pp +Finally, +.Nm +provides a small (currently 10 items) command history, and offers +simple +.Nm emacs Ns -style +command line editing capabilities. +In addition to +the +.Nm emacs +control keys, the usual ANSI arrow keys may be used to browse through the +history buffer, and move the cursor within the current line. +.Sh COMMANDS +.Ss COMMON DEBUGGER COMMANDS +.Bl -tag -width indent -compact +.It Ic help +Print a short summary of the available commands and command +abbreviations. +.Pp +.It Xo +.Ic examine Ns Op Li / Ns Cm AISabcdghilmorsuxz ... +.Oo Ar addr Oc Ns Op , Ns Ar count +.Xc +.It Xo +.Ic x Ns Op Li / Ns Cm AISabcdghilmorsuxz ... +.Oo Ar addr Oc Ns Op , Ns Ar count +.Xc +Display the addressed locations according to the formats in the modifier. +Multiple modifier formats display multiple locations. +If no format is specified, the last format specified for this command +is used. +.Pp +The format characters are: +.Bl -tag -compact -width indent +.It Cm b +look at by bytes (8 bits) +.It Cm h +look at by half words (16 bits) +.It Cm l +look at by long words (32 bits) +.It Cm g +look at by quad words (64 bits) +.It Cm a +print the location being displayed +.It Cm A +print the location with a line number if possible +.It Cm x +display in unsigned hex +.It Cm z +display in signed hex +.It Cm o +display in unsigned octal +.It Cm d +display in signed decimal +.It Cm u +display in unsigned decimal +.It Cm r +display in current radix, signed +.It Cm c +display low 8 bits as a character. +Non-printing characters are displayed as an octal escape code (e.g., +.Ql \e000 ) . +.It Cm s +display the null-terminated string at the location. +Non-printing characters are displayed as octal escapes. +.It Cm m +display in unsigned hex with character dump at the end of each line. +The location is also displayed in hex at the beginning of each line. +.It Cm i +display as a disassembled instruction +.It Cm I +display as a disassembled instruction with possible alternate formats +depending on the machine. +On i386, this selects the alternate format for the instruction decoding +(16 bits in a 32-bit code segment and vice versa). +.It Cm S +display a symbol name for the pointer stored at the address +.El +.Pp +.It Ic xf +Examine forward: +execute an +.Ic examine +command with the last specified parameters to it +except that the next address displayed by it is used as the start address. +.Pp +.It Ic xb +Examine backward: +execute an +.Ic examine +command with the last specified parameters to it +except that the last start address subtracted by the size displayed by it +is used as the start address. +.Pp +.It Ic print Ns Op Li / Ns Cm acdoruxz +.It Ic p Ns Op Li / Ns Cm acdoruxz +Print +.Ar addr Ns s +according to the modifier character (as described above for +.Cm examine ) . +Valid formats are: +.Cm a , x , z , o , d , u , r , +and +.Cm c . +If no modifier is specified, the last one specified to it is used. +The argument +.Ar addr +can be a string, in which case it is printed as it is. +For example: +.Bd -literal -offset indent +print/x "eax = " $eax "\enecx = " $ecx "\en" +.Ed +.Pp +will print like: +.Bd -literal -offset indent +eax = xxxxxx +ecx = yyyyyy +.Ed +.Pp +.It Ic pprint Ns Oo Li / Ns Cm d depth Oc Oo Ar name Oc +Pretty-print symbol specified by +.Ar name +using CTF debugging data. Works for all symbols exported by the kernel and loaded kernel modules. +.Pp +If the +.Cm d +modifier has been specified, contents of structs nested up to +.Ar depth +levels deep will also be included in the output. +.Pp +.It Ic pprint struct Ns Oo Li / Ns Cm d depth Ic Oc Oo Ar name Oc Ns Op Ns Ar addr +Print memory at +.Ar addr +as struct +.Ar name Ns . +Works for all structs defined by the kernel and loaded kernel modules. +.Pp +If the +.Cm d +modifier has been specified, contents of structs nested up to +.Ar depth +levels deep will also be included in the output. +.Pp +.It Xo +.Ic write Ns Op Li / Ns Cm bhl +.Ar addr expr1 Op Ar expr2 ... +.Xc +.It Xo +.Ic w Ns Op Li / Ns Cm bhl +.Ar addr expr1 Op Ar expr2 ... +.Xc +Write the expressions specified after +.Ar addr +on the command line at succeeding locations starting with +.Ar addr . +The write unit size can be specified in the modifier with a letter +.Cm b +(byte), +.Cm h +(half word) or +.Cm l +(long word) respectively. +If omitted, +long word is assumed. +.Pp +.Sy Warning : +since there is no delimiter between expressions, strange +things may happen. +It is best to enclose each expression in parentheses. +.Pp +.It Ic set Li $ Ns Ar variable Oo Li = Oc Ar expr +Set the named variable or register with the value of +.Ar expr . +Valid variable names are described below. +.Pp +.It Ic break Ns Oo Li / Ns Cm u Oc Oo Ar addr Oc Ns Op , Ns Ar count +.It Ic b Ns Oo Li / Ns Cm u Oc Oo Ar addr Oc Ns Op , Ns Ar count +Set a break point at +.Ar addr . +If +.Ar count +is supplied, the +.Ic continue +command will not stop at this break point on the first +.Ar count +\- 1 times that it is hit. +If the break point is set, a break point number is +printed with +.Ql # . +This number can be used in deleting the break point +or adding conditions to it. +.Pp +If the +.Cm u +modifier is specified, this command sets a break point in user +address space. +Without the +.Cm u +option, the address is considered to be in the kernel +space, and a wrong space address is rejected with an error message. +This modifier can be used only if it is supported by machine dependent +routines. +.Pp +.Sy Warning : +If a user text is shadowed by a normal user space debugger, +user space break points may not work correctly. +Setting a break +point at the low-level code paths may also cause strange behavior. +.Pp +.It Ic delete Op Ar addr +.It Ic d Op Ar addr +.It Ic delete Li # Ns Ar number +.It Ic d Li # Ns Ar number +Delete the specified break point. +The break point can be specified by a +break point number with +.Ql # , +or by using the same +.Ar addr +specified in the original +.Ic break +command, or by omitting +.Ar addr +to get the default address of +.Va dot . +.Pp +.It Ic halt +Halt the system. +.Pp +.It Ic watch Oo Ar addr Oc Ns Op , Ns Ar size +Set a watchpoint for a region. +Execution stops when an attempt to modify the region occurs. +The +.Ar size +argument defaults to 4. +If you specify a wrong space address, the request is rejected +with an error message. +.Pp +.Sy Warning : +Attempts to watch wired kernel memory +may cause unrecoverable error in some systems such as i386. +Watchpoints on user addresses work best. +.Pp +.It Ic hwatch Oo Ar addr Oc Ns Op , Ns Ar size +Set a hardware watchpoint for a region if supported by the +architecture. +Execution stops when an attempt to modify the region occurs. +The +.Ar size +argument defaults to 4. +.Pp +.Sy Warning : +The hardware debug facilities do not have a concept of separate +address spaces like the watch command does. +Use +.Ic hwatch +for setting watchpoints on kernel address locations only, and avoid +its use on user mode address spaces. +.Pp +.It Ic dhwatch Oo Ar addr Oc Ns Op , Ns Ar size +Delete specified hardware watchpoint. +.Pp +.It Ic kill Ar sig pid +Send signal +.Ar sig +to process +.Ar pid . +The signal is acted on upon returning from the debugger. +This command can be used to kill a process causing resource contention +in the case of a hung system. +See +.Xr signal 3 +for a list of signals. +Note that the arguments are reversed relative to +.Xr kill 2 . +.Pp +.It Ic step Ns Oo Li / Ns Cm p Oc Ns Op , Ns Ar count +.It Ic s Ns Oo Li / Ns Cm p Oc Ns Op , Ns Ar count +Single step +.Ar count +times. +If the +.Cm p +modifier is specified, print each instruction at each step. +Otherwise, only print the last instruction. +.Pp +.Sy Warning : +depending on machine type, it may not be possible to +single-step through some low-level code paths or user space code. +On machines with software-emulated single-stepping (e.g., pmax), +stepping through code executed by interrupt handlers will probably +do the wrong thing. +.Pp +.It Ic continue Ns Op Li / Ns Cm c +.It Ic c Ns Op Li / Ns Cm c +Continue execution until a breakpoint or watchpoint. +If the +.Cm c +modifier is specified, count instructions while executing. +Some machines (e.g., pmax) also count loads and stores. +.Pp +.Sy Warning : +when counting, the debugger is really silently single-stepping. +This means that single-stepping on low-level code may cause strange +behavior. +.Pp +.It Ic until Ns Op Li / Ns Cm p +Stop at the next call or return instruction. +If the +.Cm p +modifier is specified, print the call nesting depth and the +cumulative instruction count at each call or return. +Otherwise, +only print when the matching return is hit. +.Pp +.It Ic next Ns Op Li / Ns Cm p +.It Ic match Ns Op Li / Ns Cm p +Stop at the matching return instruction. +If the +.Cm p +modifier is specified, print the call nesting depth and the +cumulative instruction count at each call or return. +Otherwise, only print when the matching return is hit. +.Pp +.It Xo +.Ic trace Ns Op Li / Ns Cm u +.Op Ar pid | tid Ns +.Op , Ns Ar count +.Xc +.It Xo +.Ic t Ns Op Li / Ns Cm u +.Op Ar pid | tid Ns +.Op , Ns Ar count +.Xc +.It Xo +.Ic where Ns Op Li / Ns Cm u +.Op Ar pid | tid Ns +.Op , Ns Ar count +.Xc +.It Xo +.Ic bt Ns Op Li / Ns Cm u +.Op Ar pid | tid Ns +.Op , Ns Ar count +.Xc +Stack trace. +The +.Cm u +option traces user space; if omitted, +.Ic trace +only traces +kernel space. +The optional argument +.Ar count +is the number of frames to be traced. +If +.Ar count +is omitted, all frames are printed. +.Pp +.Sy Warning : +User space stack trace is valid +only if the machine dependent code supports it. +.Pp +.It Xo +.Ic search Ns Op Li / Ns Cm bhl +.Ar addr +.Ar value +.Op Ar mask Ns +.Op , Ns Ar count +.Xc +Search memory for +.Ar value . +The optional +.Ar count +argument limits the search. +.\" +.Pp +.It Xo +.Ic Ic reboot Ns Op Li / Ns Cm s +.Op Ar seconds +.Xc +.It Xo +.Ic Ic reset Ns Op Li / Ns Cm s +.Op Ar seconds +.Xc +Hard reset the system. +If the optional argument +.Ar seconds +is given, the debugger will wait for this long, at most a week, +before rebooting. +When the +.Cm s +modifier is given, the command will skip running any registered shutdown +handlers and attempt the most basic reset. +.Pp +.It Ic thread Ar addr | tid +Switch the debugger to the thread with ID +.Ar tid , +if the argument is a decimal number, or address +.Ar addr , +otherwise. +.Pp +.It Ic watchdog Op Ar exp +Program the +.Xr watchdog 4 +timer to fire in +.Pf 2^ Ar exp +seconds. +If no argument is provided, the watchdog timer is disabled. +.El +.Ss SPECIALIZED HELPER COMMANDS +.Bl -tag -width indent -compact +.It Xo +.Ic findstack +.Ar addr +.Xc +Prints the address of the thread whose kernel-mode stack contains +.Ar addr , +if any. +.Pp +.It Ic show Cm active trace +.It Ic acttrace +Show a stack trace for every thread running on a CPU. +.Pp +.It Ic show Cm all procs Ns Op Li / Ns Cm a +.It Ic ps Ns Op Li / Ns Cm a +Display all process information. +The process information may not be shown if it is not +supported in the machine, or the bottom of the stack of the +target process is not in the main memory at that time. +The +.Cm a +modifier will print command line arguments for each process. +.\" +.Pp +.It Ic show Cm all tcpcbs Ns Op Li / Ns Cm b Ns Cm i Ns Cm l +Show the same output as "show tcpcb" does, but for all +TCP control blocks within the system. +The +.Cm b +modifier will request BBLog entries to be printed. +If the +.Cm i +modifier is provided, the corresponding IP control block is also shown. +Using the +.Cm l +modifier will limit the output to TCP control blocks, which are locked. +.\" +.Pp +.It Ic show Cm all trace +.It Ic alltrace +Show a stack trace for every thread in the system. +.Pp +.It Ic show Cm all ttys +Show all TTY's within the system. +Output is similar to +.Xr pstat 8 , +but also includes the address of the TTY structure. +.\" +.Pp +.It Ic show Cm all vnets +Show the same output as "show vnet" does, but lists all +virtualized network stacks within the system. +.\" +.Pp +.It Ic show Cm allchains +Show the same information like "show lockchain" does, but +for every thread in the system. +.\" +.Pp +.It Ic show Cm alllocks +Show all locks that are currently held. +This command is only available if +.Xr witness 4 +is included in the kernel. +.\" +.Pp +.It Ic show Cm allpcpu +The same as "show pcpu", but for every CPU present in the system. +.\" +.Pp +.It Ic show Cm allrman +Show information related with resource management, including +interrupt request lines, DMA request lines, I/O ports, I/O memory +addresses, and Resource IDs. +.\" +.Pp +.It Ic show Cm apic +Dump data about APIC IDT vector mappings. +.\" +.Pp +.It Ic show Cm badstacks +Walk the +.Xr witness 4 +graph and print any lock-order violations. +This command is only available if +.Xr witness 4 +is included in the kernel. +.\" +.Pp +.It Ic show Cm breaks +Show breakpoints set with the "break" command. +.\" +.Pp +.It Ic show Cm bio Ar addr +Show information about the bio structure +.Vt struct bio +present at +.Ar addr . +See the +.Pa sys/bio.h +header file and +.Xr g_bio 9 +for more details on the exact meaning of the structure fields. +.\" +.Pp +.It Ic show Cm buffer Ar addr +Show information about the buf structure +.Vt struct buf +present at +.Ar addr . +See the +.Pa sys/buf.h +header file for more details on the exact meaning of the structure fields. +.\" +.Pp +.It Ic show Cm callout Ar addr +Show information about the callout structure +.Vt struct callout +present at +.Ar addr . +.\" +.Pp +.It Ic show Cm cdev Op Ar addr +Show the internal devfs state of the cdev structure located at +.Ar addr . +If no argument is provided, show the list of all created cdevs, consisting of +the devfs node name and the +.Vt struct cdev +address. +.\" +.Pp +.It Ic show Cm conifhk +Lists hooks currently waiting for completion in +.Fn run_interrupt_driven_config_hooks . +.\" +.Pp +.It Ic show Cm cpusets +Print numbered root and assigned CPU affinity sets. +See +.Xr cpuset 2 +for more details. +.\" +.Pp +.It Ic show Cm cyrixreg +Show registers specific to the Cyrix processor. +.\" +.Pp +.It Ic show Cm devmap +Prints the contents of the static device mapping table. +Currently only available on the +ARM +architecture. +.\" +.Pp +.It Ic show Cm domain Ar addr +Print protocol domain structure +.Vt struct domain +at address +.Ar addr . +See the +.Pa sys/domain.h +header file for more details on the exact meaning of the structure fields. +.\" +.Pp +.It Ic show Cm ffs Op Ar addr +Show brief information about ffs mount at the address +.Ar addr , +if argument is given. +Otherwise, provides the summary about each ffs mount. +.\" +.Pp +.It Ic show Cm file Ar addr +Show information about the file structure +.Vt struct file +present at address +.Ar addr . +.\" +.Pp +.It Ic show Cm files +Show information about every file structure in the system. +.\" +.Pp +.It Ic show Cm freepages +Show the number of physical pages in each of the free lists. +.\" +.Pp +.It Ic show Cm geom Op Ar addr +If the +.Ar addr +argument is not given, displays the entire GEOM topology. +If +.Ar addr +is given, displays details about the given GEOM object (class, geom, +provider or consumer). +.\" +.Pp +.It Ic show Cm idt +Show IDT layout. +The first column specifies the IDT vector. +The second one is the name of the interrupt/trap handler. +Those functions are machine dependent. +.\" +.Pp +.It Ic show Cm igi_list Ar addr +Show information about the IGMP structure +.Vt struct igmp_ifsoftc +present at +.Ar addr . +.\" +.Pp +.It Ic show Cm iosched Ar addr +Show information about the I/O scheduler +.Vt struct cam_iosched_softc +located at +.Ar addr . +.\" +.Pp +.It Ic show Cm inodedeps Op Ar addr +Show brief information about each inodedep structure. +If +.Ar addr +is given, only inodedeps belonging to the fs located at the +supplied address are shown. +.\" +.Pp +.It Ic show Cm inpcb Ar addr +Show information on IP Control Block +.Vt struct in_pcb +present at +.Ar addr . +.\" +.Pp +.It Ic show Cm intr +Dump information about interrupt handlers. +.\" +.Pp +.It Ic show Cm intrcnt +Dump the interrupt statistics. +.\" +.Pp +.It Ic show Cm irqs +Show interrupt lines and their respective kernel threads. +.\" +.Pp +.It Ic show Cm ktr Ns Op Li / Ns Cm a Ns Cm v Ns Cm V +Print the contents of the +.Xr ktr 4 +trace buffer. +The +.Cm v +modifier will request fully verbose output, causing the file, line number, and +timestamp to be printed for each trace entry. +The +.Cm V +modifier will request only the timestamps to be printed. +The +.Cm a +modifier will request that the output be unpaginated. +.\" +.Pp +.It Ic show Cm lapic +Show information from the local APIC registers for this CPU. +.\" +.Pp +.It Ic show Cm lock Ar addr +Show lock structure. +The output format is as follows: +.Bl -tag -width "flags" +.It Ic class : +Class of the lock. +Possible types include +.Xr mutex 9 , +.Xr rmlock 9 , +.Xr rwlock 9 , +.Xr sx 9 . +.It Ic name : +Name of the lock. +.It Ic flags : +Flags passed to the lock initialization function. +.Em flags +values are lock class specific. +.It Ic state : +Current state of a lock. +.Em state +values are lock class specific. +.It Ic owner : +Lock owner. +.El +.\" +.Pp +.It Ic show Cm lockchain Ar addr +Show all threads a particular thread at address +.Ar addr +is waiting on based on non-spin locks. +.\" +.Pp +.It Ic show Cm lockedbufs +Show the same information as "show buf", but for every locked +.Vt struct buf +object. +.\" +.Pp +.It Ic show Cm lockedvnods +List all locked vnodes in the system. +.\" +.Pp +.It Ic show Cm locks +Prints all locks that are currently acquired. +This command is only available if +.Xr witness 4 +is included in the kernel. +.\" +.Pp +.It Ic show Cm locktree +.\" +.Pp +.It Ic show Cm malloc Ns Op Li / Ns Cm i +Prints +.Xr malloc 9 +memory allocator statistics. +If the +.Cm i +modifier is specified, format output as machine-parseable comma-separated +values ("CSV"). +The output columns are as follows: +.Pp +.Bl -tag -compact -offset indent -width "Requests" +.It Ic Type +Specifies a type of memory. +It is the same as a description string used while defining the +given memory type with +.Xr MALLOC_DECLARE 9 . +.It Ic InUse +Number of memory allocations of the given type, for which +.Xr free 9 +has not been called yet. +.It Ic MemUse +Total memory consumed by the given allocation type. +.It Ic Requests +Number of memory allocation requests for the given +memory type. +.El +.Pp +The same information can be gathered in userspace with +.Dq Nm vmstat Fl m . +.\" +.Pp +.It Ic show Cm map Ns Oo Li / Ns Cm f Oc Ar addr +Prints the VM map at +.Ar addr . +If the +.Cm f +modifier is specified the +complete map is printed. +.\" +.Pp +.It Ic show Cm msgbuf +Print the system's message buffer. +It is the same output as in the +.Dq Nm dmesg +case. +It is useful if you got a kernel panic, attached a serial cable +to the machine and want to get the boot messages from before the +system hang. +.\" +.Pp +.It Ic show Cm mount Op Ar addr +Displays details about the mount point located at +.Ar addr . +If no +.Ar addr +is specified, +displays short info about all currently mounted file systems. +.\" +.Pp +.It Ic show Cm object Ns Oo Li / Ns Cm f Oc Ar addr +Prints the VM object at +.Ar addr . +If the +.Cm f +option is specified the +complete object is printed. +.\" +.Pp +.It Ic show Cm panic +Print the panic message if set. +.\" +.Pp +.It Ic show Cm page +Show statistics on VM pages. +.\" +.Pp +.It Ic show Cm pageq +Show statistics on VM page queues. +.\" +.Pp +.It Ic show Cm pciregs +Print PCI bus registers. +The same information can be gathered in userspace by running +.Dq Nm pciconf Fl lv . +.\" +.Pp +.It Ic show Cm pcpu +Print current processor state. +The output format is as follows: +.Pp +.Bl -tag -compact -offset indent -width "spin locks held:" +.It Ic cpuid +Processor identifier. +.It Ic curthread +Thread pointer, process identifier and the name of the process. +.It Ic curpcb +Control block pointer. +.It Ic fpcurthread +FPU thread pointer. +.It Ic idlethread +Idle thread pointer. +.It Ic APIC ID +CPU identifier coming from APIC. +.It Ic currentldt +LDT pointer. +.It Ic spin locks held +Names of spin locks held. +.El +.\" +.Pp +.It Ic show Cm pgrpdump +Dump process groups present within the system. +.\" +.Pp +.It Ic show Cm prison Op Ar addr +Show the prison structure located at +.Ar addr . +If no +.Ar addr +argument is specified, show information about all prisons in the system. +.\" +.Pp +.It Ic show Cm proc Op Ar addr +Show information about the process structure located at address +.Ar addr , +or the current process if no argument is specified. +.\" +.Pp +.It Ic show Cm procvm Op Ar addr +Show process virtual memory layout for the process located at +.Ar addr , +or the current process if no argument is specified. +.\" +.Pp +.It Ic show Cm protosw Ar addr +Print protocol switch structure +.Vt struct protosw +at address +.Ar addr . +.\" +.Pp +.It Ic show Cm registers Ns Op Li / Ns Cm u +Display the register set. +If the +.Cm u +modifier is specified, the register contents of the thread's previous +trapframe are displayed instead. +Usually, this corresponds to the saved state from userspace. +.\" +.Pp +.It Ic show Cm rman Ar addr +Show resource manager object +.Vt struct rman +at address +.Ar addr . +Addresses of particular pointers can be gathered with "show allrman" +command. +.\" +.Pp +.It Ic show Cm route Ar addr +Show route table result for destination +.Ar addr . +At this time, INET and INET6 formatted addresses are supported. +.\" +.Pp +.It Ic show Cm routetable Oo Ar af Oc +Show full route table or tables. +If +.Ar af +is specified, show only routes for the given numeric address family. +If no argument is specified, dump the route table for all address families. +.\" +.Pp +.It Ic show Cm rtc +Show real time clock value. +Useful for long debugging sessions. +.\" +.Pp +.It Ic show Cm sleepchain +Deprecated. +Now an alias for +.Ic show Cm lockchain . +.\" +.Pp +.It Ic show Cm sleepq Ar addr +.It Ic show Cm sleepqueue Ar addr +Show the +.Xr sleepqueue 9 +structure located at +.Ar addr . +.\" +.Pp +.It Ic show Cm sockbuf Ar addr +Show the socket buffer +.Va struct sockbuf +located at +.Ar addr . +.\" +.Pp +.It Ic show Cm socket Ar addr +Show the socket object +.Vt struct socket +located at +.Ar addr . +.\" +.Pp +.It Ic show Cm sysregs +Show system registers (e.g., +.Li cr0-4 +on i386.) +Not present on some platforms. +.\" +.Pp +.It Ic show Cm tcpcb Ns Oo Li / Ns Cm b Ns Cm i Oc Ar addr +Print TCP control block +.Vt struct tcpcb +lying at address +.Ar addr . +For exact interpretation of output, visit +.Pa netinet/tcp.h +header file. +The +.Cm b +modifier will request BBLog entries to be printed. +If the +.Cm i +modifier is provided, the corresponding IP control block is also shown. +.\" +.Pp +.It Ic show Cm thread Op Ar addr | tid +If no +.Ar addr +or +.Ar tid +is specified, show detailed information about current thread. +Otherwise, print information about the thread with ID +.Ar tid +or kernel address +.Ar addr . +(If the argument is a decimal number, it is assumed to be a tid.) +.\" +.Pp +.It Ic show Cm threads +Show all threads within the system. +Output format is as follows: +.Pp +.Bl -tag -compact -offset indent -width "Second column" +.It Ic First column +Thread identifier (TID) +.It Ic Second column +Thread structure address +.It Ic Third column +Backtrace. +.El +.\" +.Pp +.It Ic show Cm tty Ar addr +Display the contents of a TTY structure in a readable form. +.\" +.Pp +.It Ic show Cm turnstile Ar addr +Show turnstile +.Vt struct turnstile +structure at address +.Ar addr . +Turnstiles are structures used within the +.Fx +kernel to implement +synchronization primitives which, while holding a specific type of lock, cannot +sleep or context switch to another thread. +Currently, those are: +.Xr mutex 9 , +.Xr rwlock 9 , +.Xr rmlock 9 . +.\" +.Pp +.It Ic show Cm uma Ns Op Li / Ns Cm i +Show UMA allocator statistics. +If the +.Cm i +modifier is specified, format output as machine-parseable comma-separated +values ("CSV"). +The output contains the following columns: +.Pp +.Bl -tag -compact -offset indent -width "Total Mem" +.It Cm "Zone" +Name of the UMA zone. +The same string that was passed to +.Xr uma_zcreate 9 +as a first argument. +.It Cm "Size" +Size of a given memory object (slab). +.It Cm "Used" +Number of slabs being currently used. +.It Cm "Free" +Number of free slabs within the UMA zone. +.It Cm "Requests" +Number of allocations requests to the given zone. +.It Cm "Total Mem" +Total memory in use (either allocated or free) by a zone, in bytes. +.It Cm "XFree" +Number of free slabs within the UMA zone that were freed on a different NUMA +domain than allocated. +(The count in the +.Cm "Free" +column is inclusive of +.Cm "XFree" . ) +.El +.Pp +The same information might be gathered in the userspace +with the help of +.Dq Nm vmstat Fl z . +.\" +.Pp +.It Ic show Cm unpcb Ar addr +Shows UNIX domain socket private control block +.Vt struct unpcb +present at the address +.Ar addr . +.\" +.Pp +.It Ic show Cm vmochk +Prints, whether the internal VM objects are in a map somewhere +and none have zero ref counts. +.\" +.Pp +.It Ic show Cm vmopag +Walk the list of VM objects in the system, printing the indices and physical +addresses of the VM pages belonging to each object. +.\" +.Pp +.It Ic show Cm vnet Ar addr +Prints virtualized network stack +.Vt struct vnet +structure present at the address +.Ar addr . +.\" +.Pp +.It Ic show Cm vnode Ar addr +Prints vnode +.Vt struct vnode +structure lying at +.Ar addr . +For the exact interpretation of the output, look at the +.Pa sys/vnode.h +header file. +.\" +.Pp +.It Ic show Cm vnodebufs Ar addr +Shows clean/dirty buffer lists of the vnode located at +.Ar addr . +.\" +.Pp +.It Ic show Cm vpath Ar addr +Walk the namecache to lookup the pathname of the vnode located at +.Ar addr . +.\" +.Pp +.It Ic show Cm watches +Displays all watchpoints. +Shows watchpoints set with "watch" command. +.\" +.Pp +.It Ic show Cm witness +Shows information about lock acquisition coming from the +.Xr witness 4 +subsystem. +.El +.Ss OFFLINE DEBUGGING COMMANDS +.Bl -tag -width indent -compact +.It Ic dump +Initiate a kernel core dump to the device(s) configured by +.Xr dumpon 8 . +.Pp +.It Ic gdb +Switches to remote GDB mode. +In remote GDB mode, another machine is required that runs +.Xr gdb 1 Pq Pa ports/devel/gdb +using the remote debug feature, with a connection to the serial +console port on the target machine. +.Pp +.It Ic netdump Fl s Ar server Oo Fl g Ar gateway Fl c Ar client Fl i Ar iface Oc +Configure +.Xr netdump 4 +with the provided parameters, and immediately perform a netdump. +.Pp +There are some known limitations. +Principally, +.Xr netdump 4 +only supports IPv4 at this time. +The address arguments to the +.Ic netdump +command must be dotted decimal IPv4 addresses. +(Hostnames are not supported.) +At present, the command only works if the machine is in a panic state. +Finally, the +.Nm +.Ic netdump +command does not provide any way to configure compression or encryption. +.Pp +.It Ic netgdb Fl s Ar server Oo Fl g Ar gateway Fl c Ar client Fl i Ar iface Oc +Initiate a +.Xr netgdb 4 +session with the provided parameters. +.Pp +.Ic netgdb +has identical limitations to +.Ic netdump . +.Pp +.It Ic capture on +.It Ic capture off +.It Ic capture reset +.It Ic capture status +.Nm +supports a basic output capture facility, which can be used to retrieve the +results of debugging commands from userspace using +.Xr sysctl 3 . +.Ic capture on +enables output capture; +.Ic capture off +disables capture. +.Ic capture reset +will clear the capture buffer and disable capture. +.Ic capture status +will report current buffer use, buffer size, and disposition of output +capture. +.Pp +Userspace processes may inspect and manage +.Nm +capture state using +.Xr sysctl 8 : +.Pp +.Va debug.ddb.capture.bufsize +may be used to query or set the current capture buffer size. +.Pp +.Va debug.ddb.capture.maxbufsize +may be used to query the compile-time limit on the capture buffer size. +.Pp +.Va debug.ddb.capture.bytes +may be used to query the number of bytes of output currently in the capture +buffer. +.Pp +.Va debug.ddb.capture.data +returns the contents of the buffer as a string to an appropriately privileged +process. +.Pp +This facility is particularly useful in concert with the scripting and +.Xr textdump 4 +facilities, allowing scripted debugging output to be captured and +committed to disk as part of a textdump for later analysis. +The contents of the capture buffer may also be inspected in a kernel core dump +using +.Xr kgdb 1 Pq Pa ports/devel/gdb . +.Pp +.It Ic run +.It Ic script +.It Ic scripts +.It Ic unscript +Run, define, list, and delete scripts. +See the +.Sx SCRIPTING +section for more information on the scripting facility. +.Pp +.It Ic textdump dump +.It Ic textdump set +.It Ic textdump status +.It Ic textdump unset +Use the +.Ic textdump dump +command to immediately perform a textdump. +More information may be found in +.Xr textdump 4 . +The +.Ic textdump set +command may be used to force the next kernel core dump to be a textdump +rather than a traditional memory dump or minidump. +.Ic textdump status +reports whether a textdump has been scheduled. +.Ic textdump unset +cancels a request to perform a textdump as the next kernel core dump. +.El +.Sh VARIABLES +The debugger accesses registers and variables as +.Li $ Ns Ar name . +Register names are as in the +.Dq Ic show Cm registers +command. +Some variables are suffixed with numbers, and may have some modifier +following a colon immediately after the variable name. +For example, register variables can have a +.Cm u +modifier to indicate user register (e.g., +.Dq Li $eax:u ) . +.Pp +Built-in variables currently supported are: +.Pp +.Bl -tag -width ".Va tabstops" -compact +.It Va radix +Input and output radix. +.It Va maxoff +Addresses are printed as +.Dq Ar symbol Ns Li + Ns Ar offset +unless +.Ar offset +is greater than +.Va maxoff . +.It Va maxwidth +The width of the displayed line. +.It Va lines +The number of lines. +It is used by the built-in pager. +Setting it to 0 disables paging. +.It Va tabstops +Tab stop width. +.It Va work Ns Ar xx +Work variable; +.Ar xx +can take values from 0 to 31. +.El +.Sh EXPRESSIONS +Most expression operators in C are supported except +.Ql ~ , +.Ql ^ , +and unary +.Ql & . +Special rules in +.Nm +are: +.Bl -tag -width ".No Identifiers" +.It Identifiers +The name of a symbol is translated to the value of the symbol, which +is the address of the corresponding object. +.Ql \&. +and +.Ql \&: +can be used in the identifier. +If supported by an object format dependent routine, +.Sm off +.Oo Ar filename : Oc Ar func : lineno , +.Sm on +.Oo Ar filename : Oc Ns Ar variable , +and +.Oo Ar filename : Oc Ns Ar lineno +can be accepted as a symbol. +.It Numbers +Radix is determined by the first two letters: +.Ql 0x : +hex, +.Ql 0o : +octal, +.Ql 0t : +decimal; otherwise, follow current radix. +.It Li \&. +.Va dot +.It Li + +.Va next +.It Li .. +address of the start of the last line examined. +Unlike +.Va dot +or +.Va next , +this is only changed by +.Ic examine +or +.Ic write +command. +.It Li ' +last address explicitly specified. +.It Li $ Ns Ar variable +Translated to the value of the specified variable. +It may be followed by a +.Ql \&: +and modifiers as described above. +.It Ar a Ns Li # Ns Ar b +A binary operator which rounds up the left hand side to the next +multiple of right hand side. +.It Li * Ns Ar expr +Indirection. +It may be followed by a +.Ql \&: +and modifiers as described above. +.El +.Sh SCRIPTING +.Nm +supports a basic scripting facility to allow automating tasks or responses to +specific events. +Each script consists of a list of DDB commands to be executed sequentially, +and is assigned a unique name. +Certain script names have special meaning, and will be automatically run on +various +.Nm +events if scripts by those names have been defined. +.Pp +The +.Ic script +command may be used to define a script by name. +Scripts consist of a series of +.Nm +commands separated with the +.Ql \&; +character. +For example: +.Bd -literal -offset indent +script kdb.enter.panic=bt; show pcpu +script lockinfo=show alllocks; show lockedvnods +.Ed +.Pp +The +.Ic scripts +command lists currently defined scripts. +.Pp +The +.Ic run +command execute a script by name. +For example: +.Bd -literal -offset indent +run lockinfo +.Ed +.Pp +The +.Ic unscript +command may be used to delete a script by name. +For example: +.Bd -literal -offset indent +unscript kdb.enter.panic +.Ed +.Pp +These functions may also be performed from userspace using the +.Xr ddb 8 +command. +.Pp +Certain scripts are run automatically, if defined, for specific +.Nm +events. +The follow scripts are run when various events occur: +.Bl -tag -width kdb.enter.powerfail +.It Va kdb.enter.acpi +The kernel debugger was entered as a result of an +.Xr acpi 4 +event. +.It Va kdb.enter.bootflags +The kernel debugger was entered at boot as a result of the debugger boot +flag being set. +.It Va kdb.enter.break +The kernel debugger was entered as a result of a serial or console break. +.It Va kdb.enter.cam +The kernel debugger was entered as a result of a +.Xr CAM 4 +event. +.It Va kdb.enter.mac +The kernel debugger was entered as a result of an assertion failure in the +.Xr mac_test 4 +module of the +TrustedBSD MAC Framework. +.It Va kdb.enter.netgraph +The kernel debugger was entered as a result of a +.Xr netgraph 4 +event. +.It Va kdb.enter.panic +.Xr panic 9 +was called. +.It Va kdb.enter.powerpc +The kernel debugger was entered as a result of an unimplemented interrupt +type on the powerpc platform. +.It Va kdb.enter.sysctl +The kernel debugger was entered as a result of the +.Va debug.kdb.enter +sysctl being set. +.It Va kdb.enter.unionfs +The kernel debugger was entered as a result of an assertion failure in the +union file system. +.It Va kdb.enter.unknown +The kernel debugger was entered, but no reason has been set. +.It Va kdb.enter.vfslock +The kernel debugger was entered as a result of a VFS lock violation. +.It Va kdb.enter.watchdog +The kernel debugger was entered as a result of a watchdog firing. +.It Va kdb.enter.witness +The kernel debugger was entered as a result of a +.Xr witness 4 +violation. +.El +.Pp +In the event that none of these scripts is found, +.Nm +will attempt to execute a default script: +.Bl -tag -width kdb.enter.powerfail +.It Va kdb.enter.default +The kernel debugger was entered, but a script exactly matching the reason for +entering was not defined. +This can be used as a catch-all to handle cases not specifically of interest; +for example, +.Va kdb.enter.witness +might be defined to have special handling, and +.Va kdb.enter.default +might be defined to simply panic and reboot. +.El +.Sh HINTS +On machines with an ISA expansion bus, a simple NMI generation card can be +constructed by connecting a push button between the A01 and B01 (CHCHK# and +GND) card fingers. +Momentarily shorting these two fingers together may cause the bridge chipset to +generate an NMI, which causes the kernel to pass control to +.Nm . +Some bridge chipsets do not generate a NMI on CHCHK#, so your mileage may vary. +The NMI allows one to break into the debugger on a wedged machine to +diagnose problems. +Other bus' bridge chipsets may be able to generate NMI using bus specific +methods. +There are many PCI and PCIe add-in cards which can generate NMI for +debugging. +Modern server systems typically use IPMI to generate signals to enter the +debugger. +The +.Va devel/ipmitool +port can be used to send the +.Cd chassis power diag +command which delivers an NMI to the processor. +Embedded systems often use JTAG for debugging, but rarely use it in +combination with +.Nm . +.Pp +Serial consoles can break to the debugger by sending a BREAK +condition on the serial line. +This requires a kernel built with +.Cd options BREAK_TO_DEBUGGER +is specified in the kernel. +Most terminal emulation programs can send a break sequence with a +special key sequence or menu selection. +Sending the break can be difficult or even happen spuriously in some setups. +An alternative method is to build a kernel with +.Cd options ALT_BREAK_TO_DEBUGGER +then the sequence of CR TILDE CTRL-B enters the debugger; +CR TILDE CTRL-P causes a panic; and +CR TILDE CTRL-R causes an immediate reboot. +In all these sequences, CR represents Carriage Return and is usually +sent by pressing the Enter or Return key. +TILDE is the ASCII tilde character (~). +CTRL-x is Control x, sent by pressing the Control key, then x, then releasing +both. +.Pp +The break-to-debugger behavior can be enabled by setting +.Xr sysctl 8 +.Va debug.kdb.break_to_debugger +to 1. +The alt-break-to-debugger behavior can be enabled by setting +.Xr sysctl 8 +.Va debug.kdb.alt_break_to_debugger +to 1. +The debugger can be entered by setting +.Xr sysctl 8 +.Va debug.kdb.enter +to 1. +.Pp +Output can be interrupted, paused, and resumed with the control +characters CTRL-C, CTRL-S, and CTRL-Q. +Because these control characters are received as in-band data from the +console, there is an input buffer, and once that buffer fills +.Nm +must either stop responding to control characters or drop additional +input while continuing to search for control characters. +This behavior is controlled by the tunable +.Xr sysctl 8 +.Va debug.ddb.prioritize_control_input , +which defaults to 1. +The input buffer size is 512 bytes. +.Sh FILES +Header files mentioned in this manual page can be found below +.Pa /usr/include +directory. +.Pp +.Bl -dash -compact +.It +.Pa sys/buf.h +.It +.Pa sys/domain.h +.It +.Pa netinet/in_pcb.h +.It +.Pa sys/socket.h +.It +.Pa sys/vnode.h +.El +.Sh SEE ALSO +.Xr gdb 1 Pq Pa ports/devel/gdb , +.Xr kgdb 1 Pq Pa ports/devel/gdb , +.Xr acpi 4 , +.Xr CAM 4 , +.Xr gdb 4 , +.Xr mac_ddb 4 , +.Xr mac_test 4 , +.Xr netgraph 4 , +.Xr textdump 4 , +.Xr witness 4 , +.Xr ddb 8 , +.Xr sysctl 8 , +.Xr panic 9 +.Sh HISTORY +The +.Nm +debugger was developed for Mach, and ported to +.Bx 386 0.1 . +This manual page translated from +.Xr man 7 +macros by +.An Garrett Wollman . +.Pp +.An Robert N. M. Watson +added support for +.Nm +output capture, +.Xr textdump 4 +and scripting in +.Fx 7.1 . diff --git a/static/freebsd/man4/devctl.4 b/static/freebsd/man4/devctl.4 new file mode 100644 index 00000000..bf1e5fe2 --- /dev/null +++ b/static/freebsd/man4/devctl.4 @@ -0,0 +1,142 @@ +.\" +.\" Copyright (c) 2002 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. 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 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 September 21, 2020 +.Dt DEVCTL 4 +.Os +.Sh NAME +.Nm devctl +.Nd "device event reporting and device control interface" +.Sh SYNOPSIS +The +.Nm +driver is automatically included in the kernel. +.Sh DESCRIPTION +The +.Nm +device is used to report device events from the kernel. +Future versions will allow for some device control as well. +.Sh IMPLEMENTATION NOTES +This design allows only one reader for +.Pa /dev/devctl . +This is not desirable +in the long run, but will get a lot of hair out of this implementation. +Maybe we should make this device a clonable device. +.Pp +Also note: we specifically do not attach a device to the +.Vt device_t +tree +to avoid potential chicken and egg problems. +One could argue that all of this belongs to the root node. +One could also further argue that the +.Xr sysctl 3 +interface that we have now might more properly be an +.Xr ioctl 2 +interface. +.Pp +.Dv SIGIO +support is included in the driver. +However, the author is not sure that the +.Dv SIGIO +support is done correctly. +It was copied from a driver that had +.Dv SIGIO +support that likely has not been +tested since +.Fx 3.4 +or +.Fx 2.2.8 ! +.Pp +The read channel for this device is used to report changes to +userland in realtime. +We return one record at a time. +If you try to read this device a character at a time, you will lose +the rest of the data. +Listening programs are expected to cope. +.Pp +The sysctl +.Va hw.bus.devctl_queue +can be used to control queue length. +It is set to 0 to disable +.Nm +when no +.Xr devd 8 +is running. +.Sh PROTOCOL +The +.Nm +device +uses an +.Tn ASCII +protocol. +The driver returns one record at a time to its readers. +Each record is terminated with a newline. +The first character of the record is the event type. +.Pp +.Bl -column -compact "Type" "Description" +.Em "Type Description" +! A notify event, such as a link state change. ++ Device node in tree attached. +- Device node in tree detached. +? Unknown device detected. +.El +.Ss Message Formats +Except for the first character in the record, attach and detach +messages have the same format. +.Pp +.D1 Ar T Ns Ar dev Li at Ar parent Li on Ar location +.Pp +.Bl -column -compact "location" "Description" +.Em "Part Description" +.It Ar T Ta "+ or -" +.It Ar dev Ta "The device name that was attached/detached." +.It Ar parent Ta "The device name of the parent bus that attached the device." +.It Ar location Ta "Bus specific location information." +.El +.Pp +The nomatch messages can be used to load devices driver. +If you load a device driver, then one of two things can happen. +If the device driver attaches to something, you will get a device +attached message. +If it does not, then nothing will happen. +.Pp +The attach and detach messages arrive after the event. +This means one cannot use the attach message to load an alternate +driver. +The attach message driver has already claimed this device. +One cannot use the detach messages to flush data to the device. +The device is already gone. +.Pp +All values passed back are of the form +.Sq key=value +or +.Sq key="value" . +When the latter, the string +.Dq value +must have any internal backslashes doubled. +It must also have any internal double quote characters +.Sq " +preceded by a backslash. +All other characters should be passed through. +.Sh SEE ALSO +.Xr devd 8 diff --git a/static/freebsd/man4/devfs.4 b/static/freebsd/man4/devfs.4 new file mode 100644 index 00000000..3022a23d --- /dev/null +++ b/static/freebsd/man4/devfs.4 @@ -0,0 +1,147 @@ +.\" Copyright (c) 1996 +.\" Mike Pritchard . All rights reserved. +.\" +.\" Copyright (c) 1992, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" All rights reserved. +.\" +.\" This code is derived from software donated to Berkeley by +.\" Jan-Simon Pendry. +.\" +.\" 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 June 30, 2022 +.Dt DEVFS 4 +.Os +.Sh NAME +.Nm devfs +.Nd device file system +.Sh SYNOPSIS +.Bd -literal +devfs /dev devfs rw 0 0 +.Ed +.Sh DESCRIPTION +The device file system, or +.Nm , +provides access to kernel's device +namespace in the global file system namespace. +The conventional mount point is +.Pa /dev . +.Pp +The file system includes several directories, links, symbolic links +and devices, some of which can also be written. +In a chroot'ed +environment, +.Xr devfs 8 +can be used to create a new +.Pa /dev +mount point. +.Pp +The +.Xr mknod 8 +tool can be used to recover deleted device entries under +.Nm . +.Pp +The +.Xr fdescfs 4 +filesystem is an alternate means for populating +.Pa /dev/fd . +The character devices that both +.Nm +and +.Xr fdescfs 4 +present in +.Pa /dev/fd +correspond to the open file descriptors of the process +accessing the directory. +.Nm +only creates files for the standard file descriptors +.Pa 0 , +.Pa 1 +and +.Pa 2 . +.Xr fdescfs 4 +creates files for all open descriptors. +.Pp +The options are as follows: +.Bl -tag -width indent +.It Fl o Ar options +Use the specified mount +.Ar options , +as described in +.Xr mount 8 . +The following devfs file system-specific options are available: +.Bl -tag -width indent +.It Cm ruleset Ns No = Ns Ar ruleset +Set ruleset number +.Ar ruleset +as the current ruleset for the mount-point and apply all its rules. +If the ruleset number +.Ar ruleset +does not exist, an empty ruleset with the number +.Ar ruleset +is created. +See +.Xr devfs 8 +for more information on working with devfs rulesets. +.El +.El +.Sh FILES +.Bl -tag -width /dev/XXXX -compact +.It Pa /dev +The normal +.Nm +mount point. +.El +.Sh EXAMPLES +To mount a +.Nm +volume located on +.Pa /mychroot/dev : +.Pp +.Dl "mount -t devfs devfs /mychroot/dev" +.Sh SEE ALSO +.Xr fdescfs 4 , +.Xr devfs 8 , +.Xr mount 8 , +.Xr make_dev 9 +.Sh HISTORY +The +.Nm +file system first appeared in +.Fx 2.0 . +It became the preferred method for accessing devices in +.Fx 5.0 +and the only method in +.Fx 6.0 . +The +.Nm +manual page first appeared in +.Fx 2.2 . +.Sh AUTHORS +The +.Nm +manual page was written by +.An Mike Pritchard Aq Mt mpp@FreeBSD.org . diff --git a/static/freebsd/man4/disc.4 b/static/freebsd/man4/disc.4 new file mode 100644 index 00000000..b767c24f --- /dev/null +++ b/static/freebsd/man4/disc.4 @@ -0,0 +1,73 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 May 25, 2002 +.Dt DISC 4 +.Os +.Sh NAME +.Nm disc +.Nd software discard network interface +.Sh SYNOPSIS +.Cd "device disc" +.Sh DESCRIPTION +The +.Nm +interface is a software discard mechanism which may be +used for performance analysis and/or software testing. +As with other network interfaces, the discard interface must have +network addresses assigned for each address family with which it is to be used. +These addresses +may be set or changed with the +.Dv SIOCSIFADDR +.Xr ioctl 2 . +.Pp +Each +.Nm +interface is created at runtime using interface cloning. +This is +most easily done with the +.Xr ifconfig 8 +.Cm create +command or using the +.Va cloned_interfaces +variable in +.Xr rc.conf 5 . +.Sh SEE ALSO +.Xr inet 4 , +.Xr intro 4 +.\" .Xr ns 4 +.Sh HISTORY +The +.Nm +device appears to have been derived from the +.Xr lo 4 +device around the time of +.Bx 4.4 . +This manpage was adapted from +.Xr lo 4 +and first appeared in +.Fx 5.0 . diff --git a/static/freebsd/man4/disk.4 b/static/freebsd/man4/disk.4 new file mode 100644 index 00000000..97eeb9b7 --- /dev/null +++ b/static/freebsd/man4/disk.4 @@ -0,0 +1,206 @@ +.\" Copyright (c) 2020 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 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 November 20, 2020 +.Dt disk 4 +.Os +.Sh NAME +.Nm disk +.Nd common disk interfaces +.Sh SYNOPSIS +.Cd device cd +.Sh DESCRIPTION +Common block device IOCTLs +.Pp +All the block devices in the system should support these disk +.Xr ioctl 2 +commands defined here. +Much of this information is also available via the +.Xr geom 2 +attributes. +.Sh IOCTLS +The following +.Xr ioctl 2 +calls apply to disk drives, and are defined +in the +.In sys/disk.h +header file. +.Bl -tag -width DIOCGPROVIDERNAME +.It Dv DIOCGSECTORSIZE +.Pq Li "u_int" +Get the sector or block size of the device in bytes. +The sector size is the smallest unit of data which can be transferred +from this device. +This is usually a power of 2 but it might not be (e.g. CDROM audio). +Operations to block devices such as +.Xr lseek 2 , +.Xr read 2 , +and +.Xr write 2 +may only be performed at file offsets that are integral multiple of +this size. +.It Dv DIOCGMEDIASIZE +.Pq Li "off_t" +Get the size of the entire device in bytes. +This should be a multiple of the sector size. +.It Dv DIOCGFWSECTORS +.Pq Li "u_int" +Return the firmware's notion of number of sectors per track. +This value is mostly used for compatibility with various ill designed +disk label formats. +Use this value only when absolutely required. +Its interpretation and use is largely obsolete. +.It Dv DIOCGFWHEADS +.Pq Li "u_int" +Return the firmware's notion of number of heads per cylinder. +This value is mostly used for compatibility with various ill designed +disk label formats. +Use this value only when absolutely required. +Its interpretation and use is largely obsolete. +.It Dv DIOCGFLUSH +Flush write cache of the device. +.It Dv DIOCGDELETE +.Pq Li "off_t[2]" +Mark data on the device as unused. +The first element is the offset to start deleting. +The second element is the length to delete. +Providers may use this information to free storage or instruct storage +devices the contents can be discarded. +.It Dv DIOCGIDENT +.Pq Li "char[DISK_IDENT_SIZE]" +Get the ident for this provider. +Ident is a unique and fixed identifier for this provider. +Ident's properties are as follow: +.Bl -bullet +.It +preserved between reboots, +.It +preserved across a provider being detached/attached, +.It +provider's name can change - ident can't, +.It +ident value should not be based on on-disk metadata; in other +words, copying whole data from one disk to another should not +yield the same ident for the other disk, +.It +there can be more than one provider with the same ident, but +only if they point at exactly the same physical storage, this is +the case for multipathing for example, +.It +GEOM classes that consume a single provider and provide single +provider, like +.Xr geli 8 , +the identifier should be formed by attaching that provider's class +name to the ident of the underlying provider, +.It +ident is an NUL-terminated ASCII string (is printable), +.It +ident is optional and applications can't relay on its presence. +.El +.It Dv DIOCGPROVIDERNAME +.Pq Li "char[MAXPATHLEN]" +Store the provider name for the device in a buffer. +The buffer must be at least MAXPATHLEN bytes long. +.It Dv DIOCGSTRIPESIZE +.Pq Li "off_t" +Get the size of the device's optimal access block in bytes. +This should be a multiple of the sector size. +.It Dv DIOCGSTRIPEOFFSET +.Pq Li "off_t" +Get the offset of the first device's optimal access block in bytes. +This should be a multiple of the sector size. +.It Dv DIOCGPHYSPATH +.Pq Li "char[MAXPATHLEN]" +Get a string defining the physical path for a given provider. +This has similar rules to ident, but is intended to uniquely +identify the physical location of the device, not the current +occupant of that location. +The buffer must be at least MAXPATHLEN bytes long. +.It Dv DIOCGATTR +.Pq Li "struct diocgattr_arg" +.Bd -literal -offset indent +struct diocgattr_arg { + char name[64]; + int len; + union { + char str[DISK_IDENT_SIZE]; + off_t off; + int i; + uint16_t u16; + } value; +}; +.Ed +Get a geom attribute from the provider. +Format of the returned data is specific to the attribute. +.It Dv DIOCZONECMD +.Pq Li "struct disk_zone_arg" +Send disk zone commands. +.It Dv DIOCSKERNELDUMP +.Pq Li "struct diocskerneldump_arg" +Enable/Disable the device for kernel core dumps. +.It Dv DIOCGKERNELDUMP +.Pq Li "struct diocskerneldump_arg" +Get current kernel netdump configuration details for a given index. +.Bd -literal -offset indent +/* + * Sentinel values for kda_index. + * + * If kda_index is KDA_REMOVE_ALL, all dump configurations are cleared. + * + * If kda_index is KDA_REMOVE_DEV, all dump configurations for the specified + * device are cleared. + * + * If kda_index is KDA_REMOVE, only the specified dump configuration for the + * given device is removed from the list of fallback dump configurations. + * + * If kda_index is KDA_APPEND, the dump configuration is added after all + * existing dump configurations. + * + * Otherwise, the new configuration is inserted into the fallback dump list at + * index 'kda_index'. + */ +#define KDA_REMOVE UINT8_MAX +#define KDA_REMOVE_ALL (UINT8_MAX - 1) +#define KDA_REMOVE_DEV (UINT8_MAX - 2) +#define KDA_APPEND (UINT8_MAX - 3) +struct diocskerneldump_arg { + uint8_t kda_index; + uint8_t kda_compression; + uint8_t kda_encryption; + uint8_t kda_key[KERNELDUMP_KEY_MAX_SIZE]; + uint32_t kda_encryptedkeysize; + uint8_t *kda_encryptedkey; + char kda_iface[IFNAMSIZ]; + union kd_ip kda_server; + union kd_ip kda_client; + union kd_ip kda_gateway; + uint8_t kda_af; +}; +.Ed +.El +.Sh HISTORY +The manual page was written by +.An M Warner Losh Aq Mt imp@FreeBSD.org +from text largely derived from +.In sys/disk.h . diff --git a/static/freebsd/man4/divert.4 b/static/freebsd/man4/divert.4 new file mode 100644 index 00000000..647bb72a --- /dev/null +++ b/static/freebsd/man4/divert.4 @@ -0,0 +1,200 @@ +.\" +.Dd January 23, 2026 +.Dt DIVERT 4 +.Os +.Sh NAME +.Nm divert +.Nd kernel packet diversion mechanism +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netinet/in.h +.Ft int +.Fn socket PF_DIVERT SOCK_RAW 0 +.Pp +To enable support for divert sockets, place the following lines in the +kernel configuration file: +.Bd -ragged -offset indent +.Cd "options IPDIVERT" +.Ed +.Pp +Alternatively, to load +the driver +as a module at boot time, add the following lines into the +.Xr loader.conf 5 +file: +.Bd -literal -offset indent +ipdivert_load="YES" +.Ed +.Sh DESCRIPTION +Divert sockets allow to intercept and re-inject packets flowing through +the +.Xr ipfw 4 +and +.Xr pf 4 +firewalls. +A divert socket can be bound to a specific +.Nm +port via the +.Xr bind 2 +system call. +The sockaddr argument shall be sockaddr_in with sin_port set to the +desired value. +Note that the +.Nm +port has nothing to do with TCP/UDP ports. +It is just a cookie whose value depends on the firewall in use. +For +.Xr ipfw 4 +this is the number of the rule which diverted the packet; for +.Xr pf 4 +this is a value which indicates the original direction through the +firewall of the diverted packet. +A divert socket bound to a divert port will receive all packets diverted +to that port by the firewall. +Packets may also be written to a divert port, in which case they re-enter +firewall processing at the next rule. +.Pp +By reading from and writing to a divert socket, matching packets +can be passed through an arbitrary ``filter'' as they travel through +the host machine, special routing tricks can be done, etc. +.Sh READING PACKETS +Packets are diverted either as they are ``incoming'' or ``outgoing.'' +Incoming packets are diverted after reception on an IP interface, +whereas outgoing packets are diverted before next hop forwarding. +.Pp +Diverted packets may be read unaltered via +.Xr read 2 , +.Xr recv 2 , +or +.Xr recvfrom 2 . +In the latter case, the address returned will have its port set to +some tag supplied by the packet diverter, (usually the cookie described +above) and the IP address set to the (first) address of +the interface on which the packet was received (if the packet +was incoming) or +.Dv INADDR_ANY +(if the packet was outgoing). +The interface name (if defined +for the packet) will be placed in the 8 bytes following the address, +if it fits. +.Sh WRITING PACKETS +Writing to a divert socket is similar to writing to a raw IP socket; +the packet is injected ``as is'' into the normal kernel IP packet +processing using +.Xr sendto 2 +and minimal error checking is done. +Packets are distinguished as either incoming or outgoing. +If +.Xr sendto 2 +is used with a destination IP address of +.Dv INADDR_ANY , +then the packet is treated as if it were outgoing, i.e., destined +for a non-local address. +Otherwise, the packet is assumed to be +incoming and full packet routing is done. +.Pp +In the latter case, the +IP address specified must match the address of some local interface, +or an interface name +must be found after the IP address. +If an interface name is found, +that interface will be used and the value of the IP address will be +ignored (other than the fact that it is not +.Dv INADDR_ANY ) . +This is to indicate on which interface the packet +.Dq arrived . +.Pp +Normally, packets read as incoming should be written as incoming; +similarly for outgoing packets. +When reading and then writing back +packets, passing the same socket address supplied by +.Xr recvfrom 2 +unmodified to +.Xr sendto 2 +simplifies things (see below). +.Pp +The port part of the socket address passed to the +.Xr sendto 2 +contains a tag that should be meaningful to the diversion module. +In the +case of +.Xr ipfw 8 +the tag is interpreted as the rule number +.Em after which +rule processing should restart. +.Sh LOOP AVOIDANCE +Packets written into a divert socket +(using +.Xr sendto 2 ) +re-enter the packet filter at the rule number +following the tag given in the port part of the socket address, which +is usually already set at the rule number that caused the diversion +(not the next rule if there are several at the same number). +If the 'tag' +is altered to indicate an alternative re-entry point, care should be taken +to avoid loops, where the same packet is diverted more than once at the +same rule. +.Sh DETAILS +If a packet is diverted but no socket is bound to the +port, or if +.Dv IPDIVERT +is not enabled or loaded in the kernel, the packet is dropped. +.Pp +Incoming packet fragments which get diverted are fully reassembled +before delivery; the diversion of any one fragment causes the entire +packet to get diverted. +If different fragments divert to different ports, +then which port ultimately gets chosen is unpredictable. +.Pp +Note that packets arriving on the divert socket by the +.Xr ipfw 8 +.Cm tee +action are delivered as-is and packet fragments do not get reassembled +in this case. +.Pp +Packets are received and sent unchanged, except that +packets read as outgoing have invalid IP header checksums, and +packets written as outgoing have their IP header checksums overwritten +with the correct value. +Packets written as incoming and having incorrect checksums will be dropped. +Otherwise, all header fields are unchanged (and therefore in network order). +.Pp +Creating a +.Nm +socket requires super-user access. +.Sh ERRORS +Writing to a divert socket can return these errors, along with +the usual errors possible when writing raw packets: +.Bl -tag -width Er +.It Bq Er EINVAL +The packet had an invalid header, or the IP options in the packet +and the socket options set were incompatible. +.It Bq Er EADDRNOTAVAIL +The destination address contained an IP address not equal to +.Dv INADDR_ANY +that was not associated with any interface. +.El +.Sh SEE ALSO +.Xr bind 2 , +.Xr recvfrom 2 , +.Xr sendto 2 , +.Xr socket 2 , +.Xr ipfw 4 , +.Xr pf 4 , +.Xr ipfw 8 +.Sh AUTHORS +.An Archie Cobbs Aq Mt archie@FreeBSD.org , +Whistle Communications Corp. +.Sh BUGS +This is an attempt to provide a clean way for user mode processes +to implement various IP tricks like address translation, but it +could be cleaner. +.Pp +It is questionable whether incoming fragments should be reassembled +before being diverted. +For example, if only some fragments of a +packet destined for another machine do not get routed through the +local machine, the packet is lost. +This should probably be +a settable socket option in any case. diff --git a/static/freebsd/man4/dpms.4 b/static/freebsd/man4/dpms.4 new file mode 100644 index 00000000..ebc99c7c --- /dev/null +++ b/static/freebsd/man4/dpms.4 @@ -0,0 +1,55 @@ +.\" Copyright (c) 2008 Yahoo!, Inc. +.\" All rights reserved. +.\" Written by: John Baldwin +.\" +.\" 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. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" 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 August 23, 2008 +.Dt DPMS 4 +.Os +.Sh NAME +.Nm dpms +.Nd VESA BIOS DPMS driver +.Sh SYNOPSIS +.Cd "device dpms" +.Sh DESCRIPTION +The +.Nm +driver uses the VESA BIOS to manage an external display during suspend and +resume. +When the machine suspends, +the +.Nm +driver turns the external display off. +When the machine resumes, +it restores the display to its state when the driver was first loaded. +.Sh SEE ALSO +.Xr acpi_video 4 +.Sh BUGS +The VESA BIOS DPMS calls do not provide any way to identify a particular +display or adapter to manipulate. +As a result, +this driver may have unexpected results on systems with multiple displays +and/or adapters. diff --git a/static/freebsd/man4/ds1307.4 b/static/freebsd/man4/ds1307.4 new file mode 100644 index 00000000..46d22663 --- /dev/null +++ b/static/freebsd/man4/ds1307.4 @@ -0,0 +1,129 @@ +.\" +.\" Copyright (c) 2015 Luiz Otavio O Souza +.\" 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 ``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 December 10, 2024 +.Dt DS1307 4 +.Os +.Sh NAME +.Nm ds1307 +.Nd 64 x 8, serial, i2c real-time clock (RTC) +.Sh SYNOPSIS +.Cd "device iic" +.Cd "device iicbus" +.Cd "device ds1307" +.Sh DESCRIPTION +The +.Nm +serial real-time clock (RTC) is a low-power, full binary-coded decimal (BCD) +clock/calendar plus 56 bytes of NV SRAM. +.Pp +The +.Nm +has a built-in power-sense circuit that detects power failures and +automatically switches to the backup supply. +Timekeeping operation continues while the part operates from the backup supply. +.Pp +Access to +.Nm +settings is made with the +.Xr sysctl 8 +interface: +.Bd -literal +dev.ds1307.0.%desc: Maxim DS1307 RTC +dev.ds1307.0.%driver: ds1307 +dev.ds1307.0.%location: addr=0xd0 +dev.ds1307.0.%pnpinfo: name=rtc compat=maxim,ds1307 +dev.ds1307.0.%parent: iicbus1 +dev.ds1307.0.sqwe: 1 +dev.ds1307.0.sqw_freq: 32768 +dev.ds1307.0.sqw_out: 0 +.Ed +.Bl -tag -width ".Va dev.ds1307.%d.sqw_freq" +.It Va dev.ds1307.%d.sqwe +If set to 1, the SQW pin drives a square-wave of +.Va dev.ds1307.%d.sqw_freq +frequency. +If set to 0, the output level of SQW pin is controlled by +.Va dev.ds1307.%d.sqw_out . +.It Va dev.ds1307.%d.sqw_freq +Select the frequency of the SQW pin when the square-wave output is enabled on +.Va dev.ds1307.%d.sqwe . +It can be set to 1, 4096, 8192 and 32768. +.It Va dev.ds1307.%d.sqw_out +Set the output level of the SQW pin when +.Va dev.ds1307.%d.sqwe +is set to 0. +.El +.Pp +Please check the +.Nm +datasheet for more details. +.Pp +On a +.Xr device.hints 5 +based system, such as +.Li MIPS , +these values are configurable for +.Nm : +.Bl -tag -width ".Va hint.ds1307.%d.addr" +.It Va hint.ds1307.%d.at +The +.Xr iicbus 4 +that the +.Nm +is connected to. +.It Va hint.ds1307.%d.addr +The i2c address of +.Nm . +.El +.Pp +On a +.Xr FDT 4 +based system the following properties must be set: +.Bl -tag -width ".Va compatible" +.It Va compatible +Must always be set to "dallas,ds1307" or "maxim,ds1307". +.It Va reg +The i2c address of +.Nm . +The default address for +.Nm +is 0xd0. +.El +.Sh SEE ALSO +.Xr fdt 4 , +.Xr iic 4 , +.Xr iicbus 4 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 11.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver and this manual page were written by +.An Luiz Otavio O Souza Aq Mt loos@FreeBSD.org . diff --git a/static/freebsd/man4/ds3231.4 b/static/freebsd/man4/ds3231.4 new file mode 100644 index 00000000..52322eec --- /dev/null +++ b/static/freebsd/man4/ds3231.4 @@ -0,0 +1,146 @@ +.\" +.\" Copyright (c) 2014 Luiz Otavio O Souza +.\" 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 ``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 December 10, 2024 +.Dt DS3231 4 +.Os +.Sh NAME +.Nm ds3231 +.Nd Extremely Accurate i2c-integrated real-time clock (RTC)/TCXO/Crystal +.Sh SYNOPSIS +.Cd "device iic" +.Cd "device iicbus" +.Cd "device ds3231" +.Sh DESCRIPTION +The +.Nm +is a low-cost, extremely accurate I2C realtime clock (RTC) with an +integrated temperature-compensated crystal oscillator (TCXO) and crystal. +.Pp +The device incorporates a battery input and maintains accurate timekeeping +when main power to the device is interrupted. +.Pp +Access to +.Nm +data is made with the +.Xr sysctl 8 +interface: +.Bd -literal +dev.ds3231.0.%desc: Maxim DS3231 RTC +dev.ds3231.0.%driver: ds3231 +dev.ds3231.0.%location: addr=0xd0 +dev.ds3231.0.%pnpinfo: name=rtc compat=maxim,ds3231 +dev.ds3231.0.%parent: iicbus1 +dev.ds3231.0.temperature: 23.2C +dev.ds3231.0.temp_conv: 0 +dev.ds3231.0.bbsqw: 0 +dev.ds3231.0.sqw_freq: 8192 +dev.ds3231.0.sqw_mode: interrupt +dev.ds3231.0.32khz_enable: 1 +.Ed +.Bl -tag -width ".Va dev.ds3231.%d.temperature" +.It Va dev.ds3231.%d.temperature +The read-only value of the current temperature read by the RTC. +.It Va dev.ds3231.%d.temp_conv +Start a new temperature conversion. +When read as 1, a temperature conversion is in progress. +When read as 0 and then set to 1, a temperature conversion is started. +The temperature conversion runs automatically on power up and once every 64 +seconds afterward. +.It Va dev.ds3231.%d.bbsqw +If set to 1 and +.Va dev.ds3231.%d.sqw_mode +is set to square-wave, battery-backed square-wave output is enabled. +If set to 0, the SQW pin will be set to high impendance when the RTC is +being powered by battery. +.It Va dev.ds3231.%d.sqw_freq +Select the frequency of the SQW pin when the square-wave output is enabled on +.Va dev.ds3231.%d.sqw_mode . +It can be set to 1, 1024, 4096, and 8192. +.It Va dev.ds3231.%d.sqw_mode +Set the operation mode for the SQW pin. +It can be set to 'interrupt' (default) or 'square-wave'. +In interrupt mode, the SQW pin is used to generate interrupts for the RTC +alarms. +In square-wave mode, the SQW pin drives a square-wave of +.Va dev.ds3231.%d.sqw_freq +frequency. +.It Va dev.ds3231.%d.32khz_enable +Enable the 32kHz output. +.El +.Pp +Please check the +.Nm +datasheet for more details. +.Pp +On a +.Xr device.hints 5 +based system, such as +.Li MIPS , +these values are configurable for +.Nm : +.Bl -tag -width ".Va hint.ds3231.%d.addr" +.It Va hint.ds3231.%d.at +The +.Xr iicbus 4 +that the +.Nm +is connected to. +.It Va hint.ds3231.%d.addr +The 8-bit i2c address of +.Nm . +The default 8-bit address for +.Nm +is 0xd0. +.El +.Pp +On a +.Xr FDT 4 +based system the following properties must be set: +.Bl -tag -width ".Va compatible" +.It Va compatible +Must always be set to "maxim,ds3231". +.It Va reg +The 7-bit i2c address of +.Nm . +The default 7-bit address for +.Nm +is 0x68. +.El +.Sh SEE ALSO +.Xr fdt 4 , +.Xr iic 4 , +.Xr iicbus 4 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 11.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver and this manual page were written by +.An Luiz Otavio O Souza Aq Mt loos@FreeBSD.org . diff --git a/static/freebsd/man4/dtrace_audit.4 b/static/freebsd/man4/dtrace_audit.4 new file mode 100644 index 00000000..e12d1d93 --- /dev/null +++ b/static/freebsd/man4/dtrace_audit.4 @@ -0,0 +1,174 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2019 Robert N. M. Watson +.\" +.\" This software was developed by BAE Systems, the University of Cambridge +.\" Computer Laboratory, and Memorial University under DARPA/AFRL contract +.\" FA8650-15-C-7558 ("CADETS"), as part of the DARPA Transparent Computing +.\" (TC) research program. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 28, 2019 +.Dt DTRACE_AUDIT 4 +.Os +.Sh NAME +.Nm dtrace_audit +.Nd A DTrace provider for tracing +.Xr audit 4 +events +.Sh SYNOPSIS +.Fn audit:event:aue_*:commit "char *eventname" "struct audit_record *ar" +.Fn audit:event:aue_*:bsm "char *eventname" "struct audit_record *ar" "const void *" "size_t" +.Pp +To compile this module into the kernel, place the following in your kernel +configuration file: +.Bd -literal -offset indent +.Cd "options DTAUDIT" +.Ed +.Pp +Alternatively, to load the module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +dtaudit_load="YES" +.Ed +.Sh DESCRIPTION +The DTrace +.Nm dtaudit +provider allows users to trace events in the kernel security auditing +subsystem, +.Xr audit 4 . +.Xr audit 4 +provides detailed logging of a configurable set of security-relevant system +calls, including key arguments (such as file paths) and return values that are +copied race-free as the system call proceeds. +The +.Nm dtaudit +provider allows DTrace scripts to selectively enable in-kernel audit-record +capture for system calls, and then access those records in either the +in-kernel format or BSM format (\c +.Xr audit.log 5 ) +when the system call completes. +While the in-kernel audit record data structure is subject to change as the +kernel changes over time, it is a much more friendly interface for use in D +scripts than either those available via the DTrace system-call provider or the +BSM trail itself. +.Ss Configuration +The +.Nm dtaudit +provider relies on +.Xr audit 4 +being compiled into the kernel. +.Nm dtaudit +probes become available only once there is an event-to-name mapping installed +in the kernel, normally done by +.Xr auditd 8 +during the boot process, if audit is enabled in +.Xr rc.conf 5 : +.Bd -literal -offset indent +auditd_enable="YES" +.Ed +.Pp +If +.Nm dtaudit +probes are required earlier in boot -- for example, in single-user mode -- or +without enabling +.Xr audit 4 , +they can be preloaded in the boot loader by adding this line to +.Xr loader.conf 5 . +.Bd -literal -offset indent +audit_event_load="YES" +.Ed +.Ss Probes +The +.Fn audit:event:aue_*:commit +probes fire synchronously during system-call return, giving access to two +arguments: a +.Vt char * +audit event name, and +the +.Vt struct audit_record * +in-kernel audit record. +Because the probe fires in system-call return, the user thread has not yet +regained control, and additional information from the thread and process +remains available for capture by the script. +.Pp +The +.Fn audit:event:aue_*:bsm +probes fire asynchronously from system-call return, following BSM conversion +and just prior to being written to disk, giving access to four arguments: a +.Vt char * +audit event name, the +.Vt struct audit_record * +in-kernel audit record, a +.Vt const void * +pointer to the converted BSM record, and a +.Vt size_t +for the length of the BSM record. +.Sh IMPLEMENTATION NOTES +When a set of +.Nm dtaudit +probes are registered, corresponding in-kernel audit records will be captured +and their probes will fire regardless of whether the +.Xr audit 4 +subsystem itself would have captured the record for the purposes of writing it +to the audit trail, or for delivery to a +.Xr auditpipe 4 . +In-kernel audit records allocated only because of enabled +.Xr dtaudit 4 +probes will not be unnecessarily written to the audit trail or enabled pipes. +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr audit 4 , +.Xr audit.log 5 , +.Xr loader.conf 5 , +.Xr rc.conf 5 , +.Xr auditd 8 +.Sh HISTORY +The +.Nm dtaudit +provider first appeared in +.Fx 12.0 . +.Sh AUTHORS +This software and this manual page were developed by BAE Systems, the +University of Cambridge Computer Laboratory, and Memorial University under +DARPA/AFRL contract +.Pq FA8650-15-C-7558 +.Pq Do CADETS Dc , +as part of the DARPA Transparent Computing (TC) research program. +The +.Nm dtaudit +provider and this manual page were written by +.An Robert Watson Aq Mt rwatson@FreeBSD.org . +.Sh BUGS +Because +.Xr audit 4 +maintains its primary event-to-name mapping database in userspace, that +database must be loaded into the kernel before +.Nm dtaudit +probes become available. +.Pp +.Nm dtaudit +is only able to provide access to system-call audit events, not the full +scope of userspace events, such as those relating to login, password change, +and so on. diff --git a/static/freebsd/man4/dtrace_callout_execute.4 b/static/freebsd/man4/dtrace_callout_execute.4 new file mode 100644 index 00000000..1154ed06 --- /dev/null +++ b/static/freebsd/man4/dtrace_callout_execute.4 @@ -0,0 +1,68 @@ +.\" +.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd November 4, 2025 +.Dt DTRACE_CALLOUT_EXECUTE 4 +.Os +.Sh NAME +.Nm dtrace_callout_execute +.Nd a DTrace provider for the callout API +.Sh SYNOPSIS +.Nm callout_execute Ns Cm :kernel::callout_start +.Nm callout_execute Ns Cm :kernel::callout_end +.Sh DESCRIPTION +The +.Nm callout_execute +provider allows for tracing the +.Xr callout 9 +mechanism. +.Pp +The +.Nm callout_execute Ns Cm :kernel::callout_start +probe fires just before a callout. +.Pp +The +.Nm callout_execute Ns Cm :kernel::callout_end +probe fires right after a callout. +.Pp +The only argument to the +.Nm callout_execute +probes, +.Fa args[0] , +is a callout handler +.Ft struct callout * +of the invoked callout. +.Sh EXAMPLES +.Ss Example 1: Graph of Callout Execution Time +The following +.Xr d 7 +script generates a distribution graph of +.Xr callout 9 +execution times: +.Bd -literal -offset 2n +callout_execute:::callout_start +{ + self->cstart = timestamp; +} + +callout_execute:::callout_end +{ + @length = quantize(timestamp - self->cstart); +} +.Ed +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr tracing 7 , +.Xr callout 9 , +.Xr SDT 9 +.Sh AUTHORS +.An -nosplit +The +.Nm callout_execute +provider was written by +.An Robert N. M. Watson Aq Mt rwatson@FreeBSD.org . +.Pp +This manual page was written by +.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . diff --git a/static/freebsd/man4/dtrace_cam.4 b/static/freebsd/man4/dtrace_cam.4 new file mode 100644 index 00000000..e5b7ae34 --- /dev/null +++ b/static/freebsd/man4/dtrace_cam.4 @@ -0,0 +1,42 @@ +.\" Copyright (c) 2026 Netflix, Inc +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd December 26, 2025 +.Dt DTRACE_CAM 4 +.Os +.Sh NAME +.Nm dtrace_cam +.Nd a DTrace provider for tracing events related to CAM +.Sh SYNOPSIS +.Fn cam::xpt:action "union ccb *ccn" +.Fn cam::xpt:done "union ccb *ccb" +.Fn cam::xpt:async-cb "void *cbarg" "uint32_t async_code" "struct cam_path *path" "void *async_Arg" +.Sh DESCRIPTION +The +.Nm cam +provider allows the tracing of CAM events. +The +.Fn cam::xpt_action +probe fires when a CAM Control Block (ccb) is submitted to a CAM SIM driver. +The +.Fn cam::xpt:done +probe fires when that request completes. +The +.Fn cam::xpt:async-cb +probe fires just before an async callback is called. +.Sh ARGUMENTS +.Sh FILES +.Sh EXAMPLES +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr SDT 9 +.Sh HISTORY +The +.Nm cam +provider first appeared in +.Fx +15.1 and 16.0. +.Sh AUTHORS +This manual page was written by +.An Warner Losh Aq Mt imp@FreeBSD.org . diff --git a/static/freebsd/man4/dtrace_dtrace.4 b/static/freebsd/man4/dtrace_dtrace.4 new file mode 100644 index 00000000..b8c31005 --- /dev/null +++ b/static/freebsd/man4/dtrace_dtrace.4 @@ -0,0 +1,191 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> +.\" +.Dd July 14, 2025 +.Dt DTRACE_DTRACE 4 +.Os +.Sh NAME +.Nm dtrace_dtrace +.Nd a DTrace provider for BEGIN, END, and ERROR probes +.Sh SYNOPSIS +.Nm dtrace Ns Cm :::BEGIN +.Nm dtrace Ns Cm :::END +.Nm dtrace Ns Cm :::ERROR +.Sh DESCRIPTION +The +.Nm dtrace +provider implements three special probes related to the life cycle of the +DTrace program itself. +.Ss dtrace:::BEGIN +The +.Nm dtrace Ns Cm :::BEGIN +probe fires at the beginning of a +.Xr dtrace 1 , +program before tracing has begun. +It provides a convenient place for initializing variables +and printing column headers. +.Pp +Variables such as +.Va stack +or +.Va execname +cannot be relied upon in the execution context of the +.Nm dtrace Ns Cm :::BEGIN +probe. +.Ss dtrace:::END +The +.Nm dtrace Ns Cm :::END +probe fires at the end of a +.Xr dtrace 1 +program, when all tracing has stopped. +.Ss dtrace:::ERROR +The +.Nm dtrace Ns Cm :::ERROR +probe fires when an unexpected runtime error occurs in another probe. +.Pp +The following table describes the arguments to +.Nm dtrace Ns Cm :::ERROR . +.Bl -column -offset indent "Argument" "Definition" +.It Sy Argument Ta Sy Definition +.It Fa arg1 Ta Enabled probe identifier (EPID) +of the probe where the runtime error occurred +.It Fa arg2 Ta Index of the action statement that caused the error +.It Fa arg3 Ta DIF offset into the action if available (otherwise -1) +.It Fa arg4 Ta Fault type +.It Fa arg5 Ta Accessed address (or 0 if not applicable) when +.Va arg4 +is of fault type +.Dv DTRACEFLT_BADADDR , DTRACEFLT_BADALIGN , DTRACEFLT_KPRIV , +or +.Dv DTRACEFLT_UPRIV +.El +.Pp +The fault types are: +.Bl -tag -offset indent -width "DTRACEFLT_NOSCRATCH" -compact +.It Dv DTRACEFLT_UNKNOWN +Unknown fault +.It Dv DTRACEFLT_BADADDR +Bad address +.It Dv DTRACEFLT_BADALIGN +Bad alignment +.It Dv DTRACEFLT_ILLOP +Illegal operation +.It Dv DTRACEFLT_DIVZERO +Divide-by-zero +.It Dv DTRACEFLT_NOSCRATCH +Out of scratch space +.It Dv DTRACEFLT_KPRIV +Illegal kernel access +.It Dv DTRACEFLT_UPRIV +Illegal user access +.It Dv DTRACEFLT_TUPOFLOW +Tuple stack overflow +.It Dv DTRACEFLT_BADSTACK +Bad stack +.El +.Sh FILES +.Bl -tag -width '' +.It In sys/dtrace.h +The header file containing the definitions of DTrace fault types. +.El +.Sh EXAMPLES +.Ss Example 1 : Custom Column Headers +The following script uses the +.Nm dtrace Ns Cm :::BEGIN +probe to print column headers. +Note the pragma line setting the +.Ql quiet +option to disable the default column headers. +.Bd -literal -offset 2n +#pragma D option quiet + +dtrace:::BEGIN +{ + printf(" %12s %-20s %-20s %s\en", + "DELTA(us)", "OLD", "NEW", "TIMESTAMP"); +} +.Ed +.Ss Example 2 : Handling Runtime Errors with dtrace:::ERROR +The following script causes a runtime error by dereferencing a pointer +on address +.Ad 19930908 +in the +.Cm BEGIN +probe. +As a result, the +.Cm ERROR +probe fires and prints out +.Dq Oops +along with the probe arguments. +At that point, the program ends and fires the +.Cm END +probe. +.\" It might look weird to define ERROR first, but that is on purpose. +.\" This way the probe IDs and EPIDs are a bit more mixed up +.\" and are easier to understand. +.Bd -literal -offset 2n +ERROR +{ + printf("Oops\en"); + printf("EPID (arg1): %d\en", arg1); + printf("Action index (arg2): %d\en", arg2); + printf("DIF offset (arg3): %d\en", arg3); + printf("Fault type (arg4): %d\en", arg4); + printf("Accessed address (arg5): %X\en", arg5); + exit(1); +} +BEGIN +{ + *(int *)0x19931101; +} +END { + printf("Bye"); +} +.Ed +.Pp +This script will result in the following output: +.Bd -literal -offset 2n +CPU ID FUNCTION:NAME + 2 3 :ERROR Oops +EPID (arg1): 2 +Action index (arg2): 1 +DIF offset (arg3): 16 +Fault type: 1 +arg5: 19931101 + +dtrace: error on enabled probe ID 2 (ID 1: dtrace:::BEGIN): invalid address (0x19931101) in action #1 at DIF offset 16 + 2 2 :END Bye +.Ed +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr tracing 7 +.Rs +.%B The illumos Dynamic Tracing Guide +.%O Chapter dtrace Provider +.%D 2008 +.%U https://illumos.org/books/dtrace/chp-dtrace.html +.Re +.Sh AUTHORS +This manual page was written by +.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . +.Sh CAVEATS +The +.Nm dtrace Ns Cm :::ERROR +probe arguments cannot be accessed through the typed +.Va args[] +array. +.Pp +.Xr dtrace 1 +will not fire the +.Nm dtrace Ns Cm :::ERROR +probe recursively. +If an error occurs in one of the action statements of the +.Nm dtrace Ns Cm :::ERROR , +then +.Xr dtrace 1 +will abort further processing of +the +.Nm dtrace Ns Cm :::ERROR +probe's actions. diff --git a/static/freebsd/man4/dtrace_fbt.4 b/static/freebsd/man4/dtrace_fbt.4 new file mode 100644 index 00000000..3e35bb8c --- /dev/null +++ b/static/freebsd/man4/dtrace_fbt.4 @@ -0,0 +1,332 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> +.\" +.Dd July 16, 2025 +.Dt DTRACE_FBT 4 +.Os +.Sh NAME +.Nm dtrace_fbt +.Nd a DTrace provider for dynamic kernel tracing based on function boundaries +.Sh SYNOPSIS +.Nm fbt Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:entry +.Nm fbt Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:return +.Sh DESCRIPTION +The Function Boundary Tracing +.Pq Nm fbt +provider instruments the entry and return of almost every kernel function +corresponding to an +.Xr elf 5 +symbol in the kernel and loaded kernel modules. +.Pp +.Nm fbt Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:entry +fires whenever the +.Ar function +is called. +.Nm fbt Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:return +fires when the +.Ar function +returns. +.Pp +The +.Ar module +in the probe description is either the name of the loaded kernel module +or +.Ql kernel +for functions compiled into the kernel. +.Ss Function Boundary Instrumentation +The +.Nm fbt +will always instrument a function's entry, but +its return will be intsrumented so long as it can find a +.Ql ret +instruction. +.Pp +In some cases, +.Nm fbt +cannot instrument a function's entry and/or return. +Refer to subsection +.Sx Frame Pointer +for more details. +.Ss Probe Arguments +The arguments of the entry probe +.Pq Nm fbt Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:entry +are the arguments of the traced function call. +.Bl -column -offset indent "Entry Probe Argument" "Definition" +.It Sy Entry Probe Argument Ta Sy Definition +.It Fa args[0] Ta Function's first argument, typed +.Pq e.g., Xr malloc 9 Ap s Ft size_t Fa size +.It Fa args[1] Ta Function's second argument, typed +.Pq e.g., Xr malloc 9 Ap s Ft struct malloc_type Fa *type +.It Fa args[2] Ta Function's third argument, typed +.Pq e.g., Xr malloc 9 Ap s Ft int Fa flags +.It Fa ... Ta ... +.El +.Pp +The arguments of the return probe +.Pq Nm fbt Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:return +are +.Fa args[0] +.Po +the offset of the firing return instruction within the function; +useful to tell apart two different return statements in a single function +.Pc +and +.Fa args[1] +.Pq the return value, if any . +.Bl -column -offset indent "Return Probe Argument" "Definition" +.It Sy Return Probe Argument Ta Sy Definition +.It Fa args[0] Ta Offset of the traced return instruction +.It Fa args[1] Ta Function's return value +.Po e.g., a kernel virtual address if returning from a successful +.Xr malloc 9 +.Pc +.El +.Pp +Subsection +.Sx Example 2 : Getting Details About Probe's Arguments +shows how to get probe's argument count and types directly with +.Xr dtrace 1 +without having to resort to the reading function's source code +or documentation. +.Sh EXAMPLES +.Ss Example 1 : Listing Available FBT Probes +The following example shows how to list all the available +.Nm fbt +probes. +.Bd -literal -offset 2n +# dtrace -l -P fbt + ID PROVIDER MODULE FUNCTION NAME +[...] +31868 fbt kernel hammer_time entry +31869 fbt kernel hammer_time return +[...] +.Ed +.Pp +Since +.Fn hammer_time +is a part of the kernel and not a separate loaded module, the +.Ar module +column displays +.Ql kernel . +.Ss Example 2 : Getting Details About Probe's Arguments +The following example shows how to generate a program stability report of +.Xr malloc 9 Ap s +entry and return probes. +Those reports are useful to view +the probe's number of arguments and their types. +.Bd -literal -offset 2n +# dtrace -l -v -n fbt::malloc:entry +[...] + Argument Types + args[0]: size_t + args[1]: struct malloc_type * + args[2]: int +.Ed +.Pp +The count and types of +.Nm fbt Ns Cm \&::malloc:entry +arguments +match the function signature of +.Xr malloc 9 : +.Va args[0] +is +.Ft size_t , +.Va args[1] +is +.Ft "struct malloc_type *" , +and +.Va "args[2]" +is +.Ft int . +.Bd -literal -offset 2n +# dtrace -l -v -n fbt::malloc:return +[...] + Argument Types + args[0]: int + args[1]: void * +.Ed +.Pp +The +.Cm return +probe reports two arguments and their types: +the return instruction offset +.Pq the usual Ft int +and the function's return value, which in this case is +.Ft void * , +as +.Xr malloc 9 +returns a kernel virtual address. +.Ss Example 3 : Counting Kernel Slab Memory Allocation by Function +.Bd -literal -offset 2n +# dtrace -n 'fbt::kmem*:entry { @[probefunc] = count(); }' +dtrace: description 'fbt::kmem*:entry ' matched 47 probes +^C + kmem_alloc_contig 1 + kmem_alloc_contig_domainset 1 + kmem_cache_reap_active 1 + kmem_alloc_contig_pages 2 + kmem_free 2 + kmem_std_destructor 19 + kmem_std_constructor 26 + kmem_cache_free 151 + kmem_cache_alloc 181 +.Ed +.Ss Example 4 : Counting Kernel Slab Memory Allocation by Calling Function +.Bd -literal -offset 2n +# dtrace -q -n 'fbt::kmem*:entry { @[caller] = count(); } END { printa("%40a %@16d\en", @); }' +^C + kernel`contigmalloc+0x33 1 + kernel`free+0xd3 1 + kernel`kmem_alloc_contig+0x29 1 +kernel`kmem_alloc_contig_domainset+0x19a 1 + zfs.ko`arc_reap_cb_check+0x16 1 +.Ed +.Ss Example 5 : Counting Kernel malloc()'s by Calling Function +.Bd -literal -offset 2n +# dtrace -q -n 'fbt::malloc:entry { @[caller] = count(); } END { printa("%45a %@16d\en", @); }' +^C + kernel`devclass_get_devices+0xa8 1 + kernel`sys_ioctl+0xb7 1 + dtrace.ko`dtrace_ioctl+0x15c1 1 + dtrace.ko`dtrace_ioctl+0x972 2 + dtrace.ko`dtrace_dof_create+0x35 2 + kernel`kern_poll_kfds+0x2f0 4 + kernel`kern_poll_kfds+0x28a 19 +.Ed +.Ss Example 6 : Counting Kernel malloc()'s by Kernel Stack Trace +.Bd -literal -offset 2n +# dtrace -q -n 'fbt::malloc:entry { @[stack()] = count(); }' +^C + dtrace.ko`dtrace_dof_create+0x35 + dtrace.ko`dtrace_ioctl+0x827 + kernel`devfs_ioctl+0xd1 + kernel`VOP_IOCTL_APV+0x2a + kernel`vn_ioctl+0xb6 + kernel`devfs_ioctl_f+0x1e + kernel`kern_ioctl+0x286 + kernel`sys_ioctl+0x12f + kernel`amd64_syscall+0x169 + kernel`0xffffffff81092b0b + 2 +.Ed +.Ss Example 7 : Summarizing vmem_alloc()'s by Arena Name and Size Distribution +.Bd -literal -offset 2n +# dtrace -q -n 'fbt::vmem_alloc:entry { @[args[0]->vm_name] = quantize(arg1); }' +^C + + kernel arena dom + value ------------- Distribution ------------- count + 2048 | 0 + 4096 |@@@@@@@@@@@@@@@@@@@@@@@@@@@ 4 + 8192 |@@@@@@@@@@@@@ 2 + 16384 | 0 +.Ed +.Ss Example 8 : Measuring Total Time Spent Executing a Function +This DTrace script measures the total time spent in +.Fn vm_page* +kernel functions. +The +.Fn quantize +aggregation organizes the measurements into power-of-two buckets, +providing a time distribution in nanoseconds for each function. +.Bd -literal -offset 2n +fbt::vm_page*:entry { + self->start = timestamp; +} + +fbt::vm_page*:return /self->start/ { + @[probefunc] = quantize(timestamp - self->start); + self->start = 0; +} +.Ed +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr dtrace_kinst 4 , +.Xr tracing 7 +.Rs +.%A Brendan Gregg +.%A Jim Mauro +.%B DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD +.%I Prentice Hall +.%P pp. 898\(en903 +.%D 2011 +.%U https://www.brendangregg.com/dtracebook/ +.Re +.Rs +.%B The illumos Dynamic Tracing Guide +.%O Chapter fbt Provider +.%D 2008 +.%U https://illumos.org/books/dtrace/chp-fbt.html#chp-fbt +.Re +.Sh AUTHORS +This manual page was written by +.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . +.Sh CAVEATS +.Ss Stability and Portability +.Nm fbt +probes are by definition tightly coupled to kernel code; if the code underlying +a script changes, the script may fail to run or may produce incorrect results. +Scripts written for one version of +.Fx +might not work on others, +and almost certainly will not work on other operating systems. +.Pp +Individual +.Nm fbt +probes often do not correspond nicely to logical system events. +For example, consider a DTrace script which prints the destination +address of every IP packet as the kernel hands them over +to the network card driver (NIC). +An +.Nm fbt Ns -based +implementation of such a script is a discouragingly difficult task: +it involves instrumenting at least four different functions in different parts +of the IPv4 and IPv6 code. +At the same time, with the +.Xr dtrace_ip 4 +provider the script is a simple one-liner: +.Dl dtrace -n 'ip:::send {printf("%s", args[2]->ip_daddr);}' +.Pp +Make sure to review available +.Xr dtrace 1 +providers first +before implementing a custom script with the +.Nm fbt +provider. +If none of the DTrace providers offer the desired probes, +consider adding new statically-defined tracing probes +.Pq Xr SDT 9 . +.Ss Frame Pointer +Inline functions are not instrumentable by +.Nm fbt +as they lack a frame pointer. +A developer might explicitly disable inlining by adding the +.Ql __noinline +attribute to a function definition, +but of course this requires a recompilation of the kernel. +Building the kernel with +.Fl fno-omit-frame-pointer +is another way of preserving frame pointers. +Note, that sometimes compilers will omit the frame pointer in leaf functions, +even when configured with +.Fl fno-omit-frame-pointer . +.Pp +Function returns via a tail call are also not instrumentable by +.Nm fbt . +As a result, +a function might have an entry probe +and a mix of instrumented and uninstrumentable returns. +.Pp +Use +.Xr dtrace_kinst 4 +to trace arbitrary instructions inside kernel functions +and work around some of the +limitations +of +.Nm fbt . +.Ss Tracing DTrace +The +.Nm fbt +provider cannot attach to functions inside DTrace provider kernel modules. diff --git a/static/freebsd/man4/dtrace_io.4 b/static/freebsd/man4/dtrace_io.4 new file mode 100644 index 00000000..1699ceba --- /dev/null +++ b/static/freebsd/man4/dtrace_io.4 @@ -0,0 +1,121 @@ +.\" Copyright (c) 2015 Mark Johnston +.\" 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 October 26, 2025 +.Dt DTRACE_IO 4 +.Os +.Sh NAME +.Nm dtrace_io +.Nd a DTrace provider for tracing events related to disk I/O +.Sh SYNOPSIS +.Fn io:::start "struct bio *" "struct devstat *" +.Fn io:::done "struct bio *" "struct devstat *" +.Sh DESCRIPTION +The +.Nm io +provider allows the tracing of disk I/O events. +The +.Fn io:::start +probe fires when a I/O request is about to be sent to the backing driver of a +.Xr disk 9 +object. +This occurs after all +.Xr GEOM 4 +transformations have been performed on the request. +The +.Fn io:::done +probe fires when a I/O request is completed. +Both probes take a +.Vt "struct bio *" +representing the I/O request as their first argument. +The second argument is a +.Vt "struct devstat *" +for the underlying +.Xr disk 9 +object. +.Sh ARGUMENTS +The fields of +.Vt "struct bio" +are described in the +.Xr g_bio 9 +manual page, and the fields of +.Vt "struct devstat" +are described in the +.Xr devstat 9 +manual page. +Translators for the +.Vt bufinfo_t +and +.Vt devinfo_t +D types are defined in +.Pa /usr/lib/dtrace/io.d . +.Sh FILES +.Bl -tag -width "/usr/lib/dtrace/io.d" -compact +.It Pa /usr/lib/dtrace/io.d +DTrace type and translator definitions for the +.Nm io +provider. +.El +.Sh EXAMPLES +The following script shows a per-process breakdown of total I/O by disk device: +.Bd -literal -offset indent +#pragma D option quiet + +io:::start +{ + @[args[1]->device_name, execname, pid] = sum(args[0]->bio_length); +} + +END +{ + printf("%10s %20s %10s %15s\\n", "DEVICE", "APP", "PID", "BYTES"); + printa("%10s %20s %10d %15@d\\n", @); +} +.Ed +.Sh COMPATIBILITY +This provider is not compatible with the +.Nm io +provider found in Solaris, as its probes use native +.Fx +argument types. +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr devstat 9 , +.Xr SDT 9 +.Sh HISTORY +The +.Nm io +provider first appeared in +.Fx +9.2 and 10.0. +.Sh AUTHORS +This manual page was written by +.An Mark Johnston Aq Mt markj@FreeBSD.org . +.Sh BUGS +The +.Fn io:::wait-start +and +.Fn io:::wait-done +probes are not currently implemented on +.Fx . diff --git a/static/freebsd/man4/dtrace_ip.4 b/static/freebsd/man4/dtrace_ip.4 new file mode 100644 index 00000000..e9fbdfa3 --- /dev/null +++ b/static/freebsd/man4/dtrace_ip.4 @@ -0,0 +1,283 @@ +.\" Copyright (c) 2015 Mark Johnston +.\" 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 September 14, 2015 +.Dt DTRACE_IP 4 +.Os +.Sh NAME +.Nm dtrace_ip +.Nd a DTrace provider for tracing events related to the IPv4 and IPv6 protocols +.Sh SYNOPSIS +.Fn ip:::receive "pktinfo_t *" "csinfo_t *" "ipinfo_t *" "ifinfo_t *" \ + "ipv4info_t *" "ipv6info_t *" +.Fn ip:::send "pktinfo_t *" "csinfo_t *" "ipinfo_t *" "ifinfo_t *" \ + "ipv4info_t *" "ipv6info_t *" +.Sh DESCRIPTION +The DTrace +.Nm ip +provider allows users to trace events in the +.Xr ip 4 +and +.Xr ip6 4 +protocol implementations. +The +.Fn ip:::send +probe fires whenever the kernel prepares to transmit an IP packet, and the +.Fn ip:::receive +probe fires whenever the kernel receives an IP packet. +The arguments to these probes can be used to obtain detailed information about +the IP headers of the corresponding packet, as well as the network interface on +which the packet was sent or received. +Unlike the +.Xr dtrace_tcp 4 +and +.Xr dtrace_udp 4 +providers, +.Nm ip +provider probes are triggered by forwarded packets. +That is, the probes will fire on packets that are not destined to the local +host. +.Sh ARGUMENTS +The +.Vt pktinfo_t +argument is currently unimplemented and is included for compatibility with other +implementations of this provider. +Its fields are: +.Bl -tag -width "uintptr_t pkt_addr" -offset indent +.It Vt uintptr_t pkt_addr +Always set to 0. +.El +.Pp +The +.Vt csinfo_t +argument is currently unimplemented and is included for compatibility with other +implementations of this provider. +Its fields are: +.Bl -tag -width "uintptr_t cs_addr" -offset indent +.It Vt uintptr_t cs_addr +Always set to 0. +.It Vt uint64_t cs_cid +A pointer to the +.Vt struct inpcb +for this packet, or +.Dv NULL . +.It Vt pid_t cs_pid +Always set to 0. +.El +.Pp +The +.Vt ipinfo_t +argument contains IP fields common to both IPv4 and IPv6 packets. +Its fields are: +.Bl -tag -width "uint32_t ip_plength" -offset indent +.It Vt uint8_t ip_ver +IP version of the packet, 4 for IPv4 packets and 6 for IPv6 packets. +.It Vt uint32_t ip_plength +IP payload size. +This does not include the size of the IP header or IPv6 option headers. +.It Vt string ip_saddr +IP source address. +.It Vt string ip_daddr +IP destination address. +.El +.Pp +The +.Vt ifinfo_t +argument describes the outgoing and incoming interfaces for the packet in the +.Fn ip:::send +and +.Fn ip:::receive +probes respectively. +Its fields are: +.Bl -tag -width "uintptr_t if_addr" -offset indent +.It Vt string if_name +The interface name. +.It Vt int8_t if_local +A boolean value indicating whether or not the interface is a loopback interface. +.It Vt uintptr_t if_addr +A pointer to the +.Vt struct ifnet +which describes the interface. +See the +.Xr ifnet 9 +manual page. +.El +.Pp +The +.Vt ipv4info_t +argument contains the fields of the IP header for IPv4 packets. +This argument is +.Dv NULL +for IPv6 packets. +DTrace scripts should use the +.Fn ip_ver +field in the +.Vt ipinfo_t +argument to determine whether to use this argument. +Its fields are: +.Bl -tag -width "uint16_t ipv4_checksum" -offset indent +.It Vt uint8_t ipv4_ver +IP version. +This will always be 4 for IPv4 packets. +.It Vt uint8_t ipv4_ihl +The IP header length, including options, in 32-bit words. +.It Vt uint8_t ipv4_tos +IP type of service field. +.It Vt uint16_t ipv4_length +The total packet length, including the header, in bytes. +.It Vt uint16_t ipv4_ident +Identification field. +.It Vt uint8_t ipv4_flags +The IP flags. +.It Vt uint16_t ipv4_offset +The fragment offset of the packet. +.It Vt uint8_t ipv4_ttl +Time to live field. +.It Vt uint8_t ipv4_protocol +Next-level protocol ID. +.It Vt string ipv4_protostr +A string containing the name of the encapsulated protocol. +The protocol strings are defined in the +.Va protocol +array in +.Pa /usr/lib/dtrace/ip.d +.It Vt uint16_t ipv4_checksum +The IP checksum. +.It Vt ipaddr_t ipv4_src +IPv4 source address. +.It Vt ipaddr_t ipv4_dst +IPv4 destination address. +.It Vt string ipv4_saddr +A string representation of the source address. +.It Vt string ipv4_daddr +A string representation of the destination address. +.It Vt ipha_t *ipv4_hdr +A pointer to the raw IPv4 header. +.El +.Pp +The +.Vt ipv6info_t +argument contains the fields of the IP header for IPv6 packets. +Its fields are not set for IPv4 packets; as with the +.Vt ipv4info_t +argument, the +.Fn ip_ver +field should be used to determine whether this argument is valid. +Its fields are: +.Bl -tag -width "uint16_t ipv4_checksum" -offset indent +.It Vt uint8_t ipv6_ver +IP version. +This will always be 6 for IPv6 packets. +.It Vt uint8_t ipv6_tclass +The traffic class, used to set the differentiated services codepoint and +extended congestion notification flags. +.It Vt uint32_t ipv6_flow +The flow label of the packet. +.It Vt uint16_t ipv6_plen +The IP payload size, including extension headers, in bytes. +.It Vt uint8_t ipv6_nexthdr +An identifier for the type of the next header. +.It Vt string ipv6_nextstr +A string representation of the type of the next header. +.It Vt uint8_t ipv6_hlim +The hop limit. +.It Vt ip6_addr_t *ipv6_src +IPv6 source address. +.It Vt ip6_addr_t *ipv6_dst +IPv6 destination address. +.It Vt string ipv6_saddr +A string representation of the source address. +.It Vt string ipv6_daddr +A string representation of the destination address. +.It Vt struct ip6_hdr *ipv6_hdr +A pointer to the raw IPv6 header. +.El +.Sh FILES +.Bl -tag -width "/usr/lib/dtrace/ip.d" -compact +.It Pa /usr/lib/dtrace/ip.d +DTrace type and translator definitions for the +.Nm ip +provider. +.El +.Sh EXAMPLES +The following script counts received packets by remote host address. +.Bd -literal -offset indent +ip:::receive +{ + @num[args[2]->ip_saddr] = count(); +} +.Ed +.Pp +This script will print some details of each IP packet as it is sent or received +by the kernel: +.Bd -literal -offset indent +#pragma D option quiet +#pragma D option switchrate=10Hz + +dtrace:::BEGIN +{ + printf(" %10s %30s %-30s %8s %6s\\n", "DELTA(us)", "SOURCE", + "DEST", "INT", "BYTES"); + last = timestamp; +} + +ip:::send +{ + this->elapsed = (timestamp - last) / 1000; + printf(" %10d %30s -> %-30s %8s %6d\\n", this->elapsed, + args[2]->ip_saddr, args[2]->ip_daddr, args[3]->if_name, + args[2]->ip_plength); + last = timestamp; +} + +ip:::receive +{ + this->elapsed = (timestamp - last) / 1000; + printf(" %10d %30s <- %-30s %8s %6d\\n", this->elapsed, + args[2]->ip_daddr, args[2]->ip_saddr, args[3]->if_name, + args[2]->ip_plength); + last = timestamp; +} +.Ed +.Sh COMPATIBILITY +This provider is compatible with the +.Nm ip +providers found in Solaris and Darwin. +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr dtrace_tcp 4 , +.Xr dtrace_udp 4 , +.Xr ip 4 , +.Xr ip6 4 , +.Xr ifnet 9 , +.Xr SDT 9 +.Sh HISTORY +The +.Nm ip +provider first appeared in +.Fx +10.0. +.Sh AUTHORS +This manual page was written by +.An Mark Johnston Aq Mt markj@FreeBSD.org . diff --git a/static/freebsd/man4/dtrace_kinst.4 b/static/freebsd/man4/dtrace_kinst.4 new file mode 100644 index 00000000..c2187689 --- /dev/null +++ b/static/freebsd/man4/dtrace_kinst.4 @@ -0,0 +1,95 @@ +.\" Copyright (c) 2022 Christos Margiolis +.\" 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 16, 2025 +.Dt DTRACE_KINST 4 +.Os +.Sh NAME +.Nm dtrace_kinst +.Nd a DTrace provider for tracing arbitrary instructions in a given kernel function +.Sh SYNOPSIS +kinst::: +.Sh DESCRIPTION +The DTrace +.Nm kinst +provider allows the user to trace any instruction in a given kernel function. + corresponds to the function to be traced, and is the +offset to the specific instruction, and can be obtained from the function's +disassembly using kgdb from the gdb package. +.Pp +.Nm kinst +creates probes on-demand, meaning it searches for and parses the function's +instructions each time +.Xr dtrace 1 +is run, and not at module load time. +This is in contrast to +.Xr dtrace_fbt 4 Ap s +load-time parsing, since +.Nm kinst +can potentially create thousands of probes for just a single function, instead +of up to two (entry and return) in the case of +.Xr dtrace_fbt 4 . +A result of this is that +.Cm dtrace -l -P kinst +will not match any probes. +.Sh IMPLEMENTATION NOTES +The provider is currently implemented only for amd64. +.Sh EXAMPLES +Find the offset corresponding to the third instruction in +.Fn vm_fault +and trace it, printing the contents of the RSI register: +.Bd -literal -offset indent +# kgdb +(kgdb) disas /r vm_fault +Dump of assembler code for function vm_fault: + 0xffffffff80876df0 <+0>: 55 push %rbp + 0xffffffff80876df1 <+1>: 48 89 e5 mov %rsp,%rbp + 0xffffffff80876df4 <+4>: 41 57 push %r15 + +# dtrace -n 'kinst::vm_fault:4 {printf("%#x", regs[R_RSI]);}' + 2 81500 vm_fault:4 0x827c56000 + 2 81500 vm_fault:4 0x827878000 + 2 81500 vm_fault:4 0x1fab9bef0000 + 2 81500 vm_fault:4 0xe16cf749000 + 0 81500 vm_fault:4 0x13587c366000 + ... +.Ed +.Pp +Trace all instructions in +.Fn amd64_syscall : +.Bd -literal -offset indent +# dtrace -n 'kinst::amd64_syscall:' +.Ed +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr dtrace_fbt 4 +.Sh HISTORY +The +.Nm kinst +provider first appeared in +.Fx +14.0. +.Sh AUTHORS +This manual page was written by +.An Christos Margiolis Aq Mt christos@FreeBSD.org . diff --git a/static/freebsd/man4/dtrace_lockstat.4 b/static/freebsd/man4/dtrace_lockstat.4 new file mode 100644 index 00000000..448de91a --- /dev/null +++ b/static/freebsd/man4/dtrace_lockstat.4 @@ -0,0 +1,292 @@ +.\" Copyright (c) 2017 George V. Neville-Neil +.\" 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 September 3, 2025 +.Dt DTRACE_LOCKSTAT 4 +.Os +.Sh NAME +.Nm dtrace_lockstat +.Nd a DTrace provider for tracing kernel locking events +.Sh SYNOPSIS +.Fn lockstat:::adaptive-acquire "struct mtx *" +.Fn lockstat:::adaptive-release "struct mtx *" +.Fn lockstat:::adaptive-spin "struct mtx *" "uint64_t" +.Fn lockstat:::adaptive-block "struct mtx *" "uint64_t" +.Fn lockstat:::spin-acquire "struct mtx *" +.Fn lockstat:::spin-release "struct mtx *" +.Fn lockstat:::spin-spin "struct mtx *" "uint64_t" +.Fn lockstat:::rw-acquire "struct rwlock *" "int" +.Fn lockstat:::rw-release "struct rwlock *" "int" +.Fn lockstat:::rw-block "struct rwlock *" "uint64_t" "int" "int" "int" +.Fn lockstat:::rw-spin "struct rwlock *" "uint64_t" +.Fn lockstat:::rw-upgrade "struct rwlock *" +.Fn lockstat:::rw-downgrade "struct rwlock *" +.Fn lockstat:::sx-acquire "struct sx *" "int" +.Fn lockstat:::sx-release "struct sx *" "int" +.Fn lockstat:::sx-block "struct sx *" "uint64_t" "int" "int" "int" +.Fn lockstat:::sx-spin "struct sx *" "uint64_t" +.Fn lockstat:::sx-upgrade "struct sx *" +.Fn lockstat:::sx-downgrade "struct sx *" +.Fn lockstat:::lockmgr-acquire "struct lock *" "int" +.Fn lockstat:::lockmgr-release "struct lock *" "int" +.Fn lockstat:::lockmgr-disown "struct lock *" "int" +.Fn lockstat:::lockmgr-block "struct lock *" "uint64_t" "int" "int" "int" +.Fn lockstat:::lockmgr-upgrade "struct lock *" +.Fn lockstat:::lockmgr-downgrade "struct lock *" +.Fn lockstat:::thread-spin "struct mtx *" "uint64" +.Sh DESCRIPTION +The DTrace +.Nm lockstat +provider allows the tracing of events related to locking on +.Fx . +.Pp +The +.Nm +provider contains DTrace probes for inspecting kernel lock +state transitions. +Probes exist for the +.Xr lockmgr 9 , +.Xr mutex 9 , +.Xr rwlock 9 , +and +.Xr sx 9 +lock types. +The +.Xr lockstat 1 +utility can be used to collect and display data collected from the +.Nm +provider. +Each type of lock has +.Fn acquire +and +.Fn release +probes which expose the lock structure being operated upon, +as well as probes which fire when a thread contends with other threads +for ownership of a lock. +.Pp +The +.Fn lockstat:::adaptive-acquire +and +.Fn lockstat:::adaptive-release +probes fire when an +.Dv MTX_DEF +.Xr mutex 9 +is acquired and released, respectively. +The only argument is a pointer to the lock structure which describes +the lock being acquired or released. +.Pp +The +.Fn lockstat:::adaptive-spin +probe fires when a thread spins while waiting for a +.Dv MTX_DEF +.Xr mutex 9 +to be released by another thread. +The first argument is a pointer to the lock structure that describes +the lock and the second argument is the amount of time, +in nanoseconds, that the mutex spent spinning. +The +.Fn lockstat:::adaptive-block +probe fires when a thread takes itself off the CPU while trying to acquire an +.Dv MTX_DEF +.Xr mutex 9 +that is owned by another thread. +The first argument is a pointer to the lock structure that describes +the lock and the second argument is the length of time, +in nanoseconds, that the waiting thread was blocked. +The +.Fn lockstat:::adaptive-block +and +.Fn lockstat:::adaptive-spin +probes fire only after the lock has been successfully acquired, +and in particular, after the +.Fn lockstat:::adaptive-acquire +probe fires. +.Pp +The +.Fn lockstat:::spin-acquire +and +.Fn lockstat:::spin-release +probes fire when a +.Dv MTX_SPIN +.Xr mutex 9 +is acquired or released, respectively. +The only argument is a pointer to the lock structure which describes +the lock being acquired or released. +.Pp +The +.Fn lockstat:::spin-spin +probe fires when a thread spins while waiting for a +.Dv MTX_SPIN +.Xr mutex 9 +to be released by another thread. +The first argument is a pointer to the lock structure that describes +the lock and the second argument is the length of the time +spent spinning, in nanoseconds. +The +.Fn lockstat:::spin-spin +probe fires only after the lock has been successfully acquired, +and in particular, after the +.Fn lockstat:::spin-acquire +probe fires. +.Pp +The +.Fn lockstat:::rw-acquire +and +.Fn lockstat:::rw-release +probes fire when a +.Xr rwlock 9 +is acquired or released, respectively. +The first argument is a pointer to the structure which describes +the lock being acquired. +The second argument is +.Dv 0 +if the lock is being acquired or released as a writer, and +.Dv 1 +if it is being acquired or released as a reader. +The +.Fn lockstat:::sx-acquire +and +.Fn lockstat:::sx-release , +and +.Fn lockstat:::lockmgr-acquire +and +.Fn lockstat:::lockmgr-release +probes fire upon the corresponding events for +.Xr sx 9 +and +.Xr lockmgr 9 +locks, respectively. +The +.Fn lockstat:::lockmgr-disown +probe fires when a +.Xr lockmgr 9 +exclusive lock is disowned. +In this state, the lock remains exclusively held, but may be +released by a different thread. +The +.Fn lockstat:::lockmgr-release +probe does not fire when releasing a disowned lock. +The first argument is a pointer to the structure which describes +the lock being disowned. +The second argument is +.Dv 0 , +for compatibility with +.Fn lockstat:::lockmgr-release . +.Pp +The +.Fn lockstat:::rw-block , +.Fn lockstat:::sx-block , +and +.Fn lockstat:::lockmgr-block +probes fire when a thread removes itself from the CPU while +waiting to acquire a lock of the corresponding type. +The +.Fn lockstat:::rw-spin +and +.Fn lockstat:::sx-spin +probes fire when a thread spins while waiting to acquire a lock +of the corresponding type. +All probes take the same set of arguments. +The first argument is a pointer to the lock structure that describes +the lock. +The second argument is the length of time, in nanoseconds, +that the waiting thread was off the CPU or spinning for the lock. +The third argument is +.Dv 0 +if the thread is attempting to acquire the lock as a writer, and +.Dv 1 +if the thread is attempting to acquire the lock as a reader. +The fourth argument is +.Dv 0 +if the thread is waiting for a reader to release the lock, and +.Dv 1 +if the thread is waiting for a writer to release the lock. +The fifth argument is the number of readers that held the lock when +the thread first attempted to acquire the lock. +This argument will be +.Dv 0 +if the fourth argument is +.Dv 1 . +.Pp +The +.Fn lockstat:::lockmgr-upgrade , +.Fn lockstat:::rw-upgrade , +and +.Fn lockstat:::sx-upgrade +probes fire when a thread successfully upgrades a held +.Xr lockmgr 9 , +.Xr rwlock 9 , +or +.Xr sx 9 +shared/reader lock to an exclusive/writer lock. +The only argument is a pointer to the structure which describes +the lock being acquired. +The +.Fn lockstat:::lockmgr-downgrade , +.Fn lockstat:::rw-downgrade , +and +.Fn lockstat:::sx-downgrade +probes fire when a thread downgrades a held +.Xr lockmgr 9 , +.Xr rwlock 9 , +or +.Xr sx 9 +exclusive/writer lock to a shared/reader lock. +.Pp +The +.Fn lockstat:::thread-spin +probe fires when a thread spins on a thread lock, which is a specialized +.Dv MTX_SPIN +.Xr mutex 9 . +The first argument is a pointer to the structure that describes +the lock and the second argument is the length of time, +in nanoseconds, that the thread was spinning. +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr lockstat 1 , +.Xr locking 9 , +.Xr mutex 9 , +.Xr rwlock 9 , +.Xr SDT 9 , +.Xr sx 9 +.Sh HISTORY +The +.Nm +provider first appeared in Solaris. +The +.Fx +implementation of the +.Nm +provider first appeared in +.Fx 9 . +.Sh AUTHORS +This manual page was written by +.An George V. Neville-Neil Aq Mt gnn@FreeBSD.org +and +.An -nosplit +.An Mark Johnston Aq Mt markj@FreeBSD.org . +.Sh BUGS +Probes for +.Xr rmlock 9 +locks have not yet been added. diff --git a/static/freebsd/man4/dtrace_pid.4 b/static/freebsd/man4/dtrace_pid.4 new file mode 100644 index 00000000..1acbdd09 --- /dev/null +++ b/static/freebsd/man4/dtrace_pid.4 @@ -0,0 +1,99 @@ +.\" +.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd November 6, 2025 +.Dt DTRACE_PID 4 +.Os +.Sh NAME +.Nm dtrace_pid +.Nd a DTrace provider for dynamic userspace tracing based on function boundary instrumentation +.Sh SYNOPSIS +.Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:entry +.\" XXX: For some reason Op renders here in bold, so use literal square +.\" brackets instead. +.Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&: Ns No \&[ Ns Ar offset Ns No \&] +.Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:return +.Sh DESCRIPTION +The +.Nm pid +provider implements userspace dynamic tracing +by instrumenting the entry and return of functions in userspace programs. +Refer to +.Xr dtrace_fbt 4 +for more details about function boundary instrumentation. +.Pp +The +.Nm pid +provider provides the following probes: +.Bl -inset +.It Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:entry +instruments the entry of the +.Ar function . +.It Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&: Ns Op Ar offset +instruments the instruction within the +.Ar function +located at +.Ar offset +bytes (expressed as a hexadecimal integer). +.It Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:return +instruments the return from the +.Ar function . +.El +.Ss Probe Arguments +The arguments of the entry probe +.Pq Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:entry +are the arguments of the traced function call. +.Bl -column -offset indent "Entry Probe Argument" "Definition" +.It Sy Entry Probe Argument Ta Sy Definition +.It Ft uint64_t Fa arg0 Ta Function's first argument +.It Ft uint64_t Fa arg1 Ta Function's second argument +.It Ft uint64_t Fa arg2 Ta Function's third argument +.It Fa ... Ta ... +.El +.Pp +The offset probes +.Pq Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&: Ns Op Ar offset +do not define any arguments. +Use +.Va uregs[] +to inspect the registers. +.Pp +The arguments of the return probe +.Pq Nm pid Ns Ar PID Ns Cm \&: Ns Ar module Ns Cm \&: Ns Ar function Ns Cm \&:return +are the program counter and the function's return value. +.Bl -column -offset indent "Return Probe Argument" "Definition" +.It Sy Return Probe Argument Ta Sy Definition +.It Ft uint64_t Fa arg0 Ta Program counter +.It Ft uint64_t Fa arg1 Ta Function's return value +.El +.Pp +Note that all probe arguments within the +.Nm pid +provider are of type +.Ft uint64_t . +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr dtrace_fbt 4 , +.Xr dtrace_kinst 4 , +.Xr elf 5 , +.Xr d 7 , +.Xr tracing 7 +.Rs +.%A Brendan Gregg +.%A Jim Mauro +.%B DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD +.%I Prentice Hall +.%D 2011 +.%U https://www.brendangregg.com/dtracebook/ +.Re +.Rs +.%B The illumos Dynamic Tracing Guide +.%O Chapter pid Provider +.%D 2008 +.%U https://illumos.org/books/dtrace/chp-pid.html +.Re +.Sh AUTHORS +This manual page was written by +.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . diff --git a/static/freebsd/man4/dtrace_priv.4 b/static/freebsd/man4/dtrace_priv.4 new file mode 100644 index 00000000..97bd4c20 --- /dev/null +++ b/static/freebsd/man4/dtrace_priv.4 @@ -0,0 +1,59 @@ +.\" +.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd November 12, 2025 +.Dt DTRACE_PRIV 4 +.Os +.Sh NAME +.Nm dtrace_priv +.Nd a DTrace provider for the kernel privilege checking API +.Sh SYNOPSIS +.Nm priv Ns Cm :kernel:priv_check:priv-ok +.Nm priv Ns Cm :kernel:priv_check:priv-err +.Sh DESCRIPTION +The +.Nm priv +provider allows for tracing the +.Xr priv 9 +API. +.Pp +The +.Nm priv Ns Cm :kernel:priv_check:priv-ok +probe fires upon a successful kernel privilege check. +.Pp +The +.Nm priv Ns Cm :kernel:priv_check:priv-err +probe fires upon a failed kernel privilege check. +.Pp +The only argument to the +.Nm priv +probes, +.Fa args[0] , +is the requested privilege number +.Ft int priv . +.Sh EXAMPLES +.Ss Example 1: Tracing Kernel Privilege Check Failures +The following script captures an array of counters, +one for each stack trace leading to a failed kernel privilege check: +.Bd -literal -offset 2n +priv:::priv-err +{ + @traces[stack()] = count(); +} +.Ed +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr tracing 7 , +.Xr priv 9 , +.Xr SDT 9 +.Sh AUTHORS +.An -nosplit +The +.Nm priv +provider was written by +.An Robert N. M. Watson Aq Mt rwatson@FreeBSD.org . +.Pp +This manual page was written by +.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . diff --git a/static/freebsd/man4/dtrace_proc.4 b/static/freebsd/man4/dtrace_proc.4 new file mode 100644 index 00000000..5e217eb0 --- /dev/null +++ b/static/freebsd/man4/dtrace_proc.4 @@ -0,0 +1,262 @@ +.\" Copyright (c) 2015 Mark Johnston +.\" 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 March 3, 2023 +.Dt DTRACE_PROC 4 +.Os +.Sh NAME +.Nm dtrace_proc +.Nd a DTrace provider for tracing events related to user processes +.Sh SYNOPSIS +.Fn proc:::create "struct proc *" "struct proc *" "int" +.Fn proc:::exec "char *" +.Fn proc:::exec-failure "int" +.Fn proc:::exec-success "char *" +.Fn proc:::exit "int" +.Fn proc:::signal-clear "int" "ksiginfo_t *" +.Fn proc:::signal-discard "struct thread *" "struct proc *" "int" +.Fn proc:::signal-send "struct thread *" "struct proc *" "int" +.Sh DESCRIPTION +The DTrace +.Nm proc +provider provides insight into events related to user processes: process and +thread creation and termination events, and process signalling. +.Pp +The +.Fn proc:::create +probe fires when a user process is created via the +.Xr fork 2 , +.Xr vfork 2 , +.Xr pdfork 2 , +or +.Xr rfork 2 +system calls. +In particular, kernel processes created with the +.Xr kproc 9 +KPI will not trigger this probe. +The +.Fn proc:::create +probe's first two arguments are the new child process and its parent, +respectively. +The third argument is a mask of +.Xr rfork 2 +flags indicating which process resources are to be shared between the parent and +child processes. +.Pp +The +.Fn proc:::exec +probe fires when a process attempts to execute a file. +Its argument is the specified filename for the file. +If the attempt fails because of an error, the +.Fn proc:::exec-failure +probe will subsequently fire, providing the corresponding +.Xr errno 2 +value in its first argument. +Otherwise, the +.Fn proc:::exec-success +probe will fire. +.Pp +The +.Fn proc:::exit +probe fires when a process exits or is terminated. +Its argument is the corresponding +.Dv SIGCHLD +signal code; valid values are documented in the +.Xr siginfo 3 +manual page and defined in +.Pa signal.h . +For example, when a process exits normally, the value of +.Dv args[0] +will be +.Dv CLD_EXITED . +.Pp +The +.Fn proc:::signal-send +probe fires when a signal is about to be sent to a process. +The +.Fn proc:::signal-discard +probe fires when a signal is sent to a process that ignores it. +This probe will fire after the +.Fn proc:::signal-send +probe for the signal in question. +The arguments to these probes are the thread and process to which the signal +will be sent, and the signal number of the signal. +Valid signal numbers are defined in the +.Xr signal 3 +manual page. +The +.Fn proc:::signal-clear +probe fires when a pending signal has been cleared by one of the +.Xr sigwait 2 , +.Xr sigtimedwait 2 , +or +.Xr sigwaitinfo 2 +system calls. +Its arguments are the signal number of the cleared signal, and a pointer to +the corresponding signal information. +The +.Vt siginfo_t +for the signal can be obtained from +.Dv args[1]->ksi_info . +.Sh ARGUMENTS +Though the +.Nm proc +provider probes use native +.Fx +arguments types, standard D types for processes and threads are available. +These are +.Vt psinfo_t +and +.Vt lwpsinfo_t +respectively, and are defined in +.Pa /usr/lib/dtrace/psinfo.d . +This file also defines two global variables, +.Va curpsinfo +and +.Va curlwpsinfo , +which provide representations of the current process and thread using these +types. +.Pp +The fields of +.Vt psinfo_t +are: +.Bl -tag -width "uintptr_t pr_addr" -offset indent +.It Vt int pr_nlwp +Number of threads in the process. +.It Vt pid_t pr_pid +Process ID. +.It Vt pid_t pr_ppid +Process ID of the parent process, or 0 if the process does not have a parent. +.It Vt pid_t pr_pgid +Process ID of the process group leader. +.It Vt pid_t pr_sid +Session ID, or 0 if the process does not belong to a session. +.It Vt pid_t pr_uid +Real user ID. +.It Vt pid_t pr_euid +Effective user ID. +.It Vt pid_t pr_gid +Real group ID. +.It Vt pid_t pr_egid +Effective group ID. +.It Vt uintptr_t pr_addr +Pointer to the +.Vt struct proc +for the process. +.It Vt string pr_psargs +Process arguments. +.It Vt u_int pr_arglen +Length of the process argument string. +.It Vt u_int pr_jailid +Jail ID of the process. +.El +.Pp +The fields of +.Vt lwpsinfo_t +are: +.Bl -tag -width "uintptr_t pr_wchar" -offset indent +.It Vt id_t pr_lwpid +Thread ID. +.It Vt int pr_flag +Thread flags. +.It Vt int pr_pri +Real scheduling priority of the thread. +.It Vt char pr_state +Currently always 0. +.It Vt char pr_sname +Currently always +.Ql \&? . +.It Vt short pr_syscall +Currently always 0. +.It Vt uintptr_t pr_addr +Pointer to the +.Vt struct thread +for the thread. +.It Vt uintptr_t pr_wchan +Current wait address on which the thread is sleeping. +.El +.Sh FILES +.Bl -tag -width "/usr/lib/dtrace/psinfo.d" -compact +.It Pa /usr/lib/dtrace/psinfo.d +DTrace type and translator definitions for the +.Nm proc +provider. +.El +.Sh EXAMPLES +The following script logs process execution events as they occur: +.Bd -literal -offset indent +#pragma D option quiet + +proc:::exec-success +{ + printf("%s", curpsinfo->pr_psargs); +} +.Ed +.Pp +Note that the +.Dv pr_psargs +field is subject to the limit defined by the +.Va kern.ps_arg_cache_limit +sysctl. +In particular, processes with an argument list longer than the value defined by +this sysctl cannot be logged in this way. +.Sh COMPATIBILITY +The +.Nm proc +provider in +.Fx +is not compatible with the +.Nm proc +provider in Solaris. +In particular, +.Fx +uses the native +.Vt "struct proc" +and +.Vt "struct thread" +types for probe arguments rather than translated types. +Additionally, a number of +.Nm proc +provider probes found in Solaris are not currently available on +.Fx . +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr errno 2 , +.Xr fork 2 , +.Xr pdfork 2 , +.Xr rfork 2 , +.Xr vfork 2 , +.Xr siginfo 3 , +.Xr signal 3 , +.Xr dtrace_sched 4 , +.Xr kproc 9 +.Sh HISTORY +The +.Nm proc +provider first appeared in +.Fx +7.1. +.Sh AUTHORS +This manual page was written by +.An Mark Johnston Aq Mt markj@FreeBSD.org . diff --git a/static/freebsd/man4/dtrace_profile.4 b/static/freebsd/man4/dtrace_profile.4 new file mode 100644 index 00000000..07f86663 --- /dev/null +++ b/static/freebsd/man4/dtrace_profile.4 @@ -0,0 +1,129 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> +.\" +.Dd July 14, 2025 +.Dt DTRACE_PROFILE 4 +.Os +.Sh NAME +.Nm dtrace_profile +.Nd a DTrace provider for firing probes at a given time interval +.Sh SYNOPSIS +.Nm profile Ns Cm :::profile- Ns Ar rate Ns Op Ar unit +.Nm profile Ns Cm :::tick- Ns Ar rate Ns Op Ar unit +.Sh DESCRIPTION +The +.Nm profile +provider implements three special probes related to the life cycle of the +DTrace program itself. +.Ss Probes +The +.Nm profile Ns Cm :::profile +probes fire on all CPUs and are suitable for measuring the whole system +periodically. +.Pp +The +.Nm profile Ns Cm :::tick +probes fire on a single CPU, potentially a different one every time. +They are useful, e.g., for printing partial results periodically. +.Ss Rate and Time Units +The +.Nm profile +provider probes will fire at the specified +.Ar rate . +.Pp +The default unit is +.Cm hz . +The +.Nm profile +provider supports the following time units: +.Bl -column -offset indent "ns, nsec" "Definition" +.It Sy Time Unit Ta Sy Definition +.It Cm ns , nsec Ta nanoseconds +.It Cm us , usec Ta microseconds +.It Cm ms , msec Ta milliseconds +.It Cm s , sec Ta seconds +.It Cm m , min Ta minutes +.It Cm h , hour Ta hours +.It Cm d , day Ta days +.It Cm hz Ta Hertz (frequency per second) +.El +.Ss Probe Arguments +The arguments of the +.Nm profile +provider probes +are: +.Bl -tag -width arg0 +.It Va arg0 +The PC (program counter) in the kernel when the probe triggered, +or 0 if the process was not in the kernel at that time. +.It Va arg1 +The PC in the user process when the probe triggered, +or 0 if the process was in the kernel when the probe triggered. +.El +.Pp +Use arguments +.Va arg0 +and +.Va arg1 +to tell if the +.Nm profile +provider probe fired in the kernel or in the userspace context. +.Sh IMPLEMENTATION NOTES +The +.Xr sysctl 8 +variable +.Va kern.dtrace.profile.aframes +controls the number of skipped artificial frames for +the +.Nm profile +provider. +.Sh EXAMPLES +.Ss Example 1 : Profiling On-CPU Kernel Stack Traces +The following DTrace one-liner uses the +.Nm profile +provider to collect stack traces over 60 seconds. +.\" XXX: Keep on one line for easier copy-pasting. +.Bd -literal -offset indent +dtrace -x stackframes=100 -n 'profile-197 /arg0/ {@[stack()] = count();} tick-60s {exit(0);} +.Ed +.Pp +The system is profiled at the 197 Hz to avoid sampling in lockstep +with other periodic activities. +This unnatural frequency minimizes the chance of overlapping with other events. +.Pp +Option +.Fl x Cm stackframes=100 +increases the maximum number of kernel stack frames to unwind during +.Fn stack . +.Pp +Checking if +.Ar arg0 +is not zero makes sure that profiling happens +when the program is in the kernel context. +.Pp +Refer to +.Lk https://www.brendangregg.com/flamegraphs.html +to learn about generating flame graphs from the obtained stack traces. +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr tracing 7 +.Rs +.%B The illumos Dynamic Tracing Guide +.%O Chapter profile Provider +.%D 2008 +.%U https://www.illumos.org/books/dtrace/chp-profile.html +.Re +.Rs +.%A Brendan Gregg +.%A Jim Mauro +.%B DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD +.%I Prentice Hall +.%P pp. 24\(en25 +.%D 2011 +.%U https://www.brendangregg.com/dtracebook/ +.Re +.Sh AUTHORS +This manual page was written by +.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . diff --git a/static/freebsd/man4/dtrace_sched.4 b/static/freebsd/man4/dtrace_sched.4 new file mode 100644 index 00000000..b085ffe4 --- /dev/null +++ b/static/freebsd/man4/dtrace_sched.4 @@ -0,0 +1,225 @@ +.\" Copyright (c) 2015 Mark Johnston +.\" 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 April 18, 2015 +.Dt DTRACE_SCHED 4 +.Os +.Sh NAME +.Nm dtrace_sched +.Nd a DTrace provider for tracing CPU scheduling events +.Sh SYNOPSIS +.Fn sched:::change-pri "struct thread *" "struct proc *" "uint8_t" +.Fn sched:::dequeue "struct thread *" "struct proc *" "void *" +.Fn sched:::enqueue "struct thread *" "struct proc *" "void *" "int" +.Fn sched:::lend-pri "struct thread *" "struct proc *" "uint8_t" "struct thread *" +.Fn sched:::load-change "int" "int" +.Fn sched:::off-cpu "struct thread *" "struct proc *" +.Fn sched:::on-cpu +.Fn sched:::preempt +.Fn sched:::remain-cpu +.Fn sched:::surrender "struct thread *" "struct proc *" +.Fn sched:::sleep +.Fn sched:::tick "struct thread *" "struct proc *" +.Fn sched:::wakeup "struct thread *" "struct proc *" +.Sh DESCRIPTION +The DTrace +.Nm sched +provider allows the tracing of events related to CPU scheduling in the 4BSD and +ULE schedulers. +.Pp +The +.Fn sched:::change-pri +probe fires when a thread's active scheduling priority is about to be updated. +The first two arguments are the thread whose priority is about to be changed, +and the corresponding process. +The third argument is the new absolute priority for the thread, while the +current value is given by +.Dv args[0]->td_priority . +The +.Fn sched:::lend-pri +probe fires when the currently-running thread elevates the priority of another +thread via priority lending. +The first two arguments are the thread whose priority is about to be changed, +and the corresponding process. +The third argument is the new absolute priority for the thread. +The fourth argument is the currently-running thread. +.Pp +The +.Fn sched:::dequeue +probe fires immediately before a runnable thread is removed from a scheduler +run queue. +This may occur when the thread is about to begin execution on a CPU, or because +the thread is being migrated to a different run queue. +The latter event may occur in several circumstances: the scheduler may be +attempting to rebalance load between multiple CPUs, the thread's scheduling +priority may have changed, or the thread's CPU affinity settings may have +changed. +The first two arguments to +.Fn sched:::dequeue +are the thread and corresponding process. +The third argument is currently always +.Dv NULL . +The +.Fn sched:::enqueue +probe fires when a runnable thread is about to be added to a scheduler run +queue. +Its first two arguments are the thread and corresponding process. +The third argument is currently always +.Dv NULL . +The fourth argument is a boolean value that is non-zero if the thread is +enqueued at the beginning of its run queue slot, and zero if the thread is +instead enqueued at the end. +.Pp +The +.Fn sched:::load-change +probe fires after the load of a thread queue is adjusted. +The first argument is the cpuid for the CPU associated with the thread queue, +and the second argument is the adjusted load of the thread queue, i.e., the +number of elements in the queue. +.Pp +The +.Fn sched:::off-cpu +probe is triggered by the scheduler suspending execution of the +currently-running thread, and the +.Fn sched:::on-cpu +probe fires when the current thread has been selected to run on a CPU and is +about to begin or resume execution. +The arguments to +.Fn sched:::off-cpu +are the thread and corresponding process selected to run following the +currently-running thread. +If these two threads are the same, the +.Fn sched:::remain-cpu +probe will fire instead. +.Pp +The +.Fn sched:::surrender +probe fires when the scheduler is called upon to make a scheduling decision by +a thread running on a different CPU, via an interprocessor interrupt. +The arguments to this probe are the interrupted thread and its corresponding +process. +This probe currently always fires in the context of the interrupted thread. +.Pp +The +.Fn sched:::preempt +probe will fire immediately before the currently-running thread is preempted. +When this occurs, the scheduler will select a new thread to run, and one of the +.Fn sched:::off-cpu +or +.Fn sched:::remain-cpu +probes will subsequently fire, depending on whether or not the scheduler selects +the preempted thread. +.Pp +The +.Fn sched:::sleep +probe fires immediately before the currently-running thread is about to suspend +execution and begin waiting for a condition to be met. +The +.Fn sched:::wakeup +probe fires when a thread is set up to resume execution after having gone to +sleep. +Its arguments are the thread being awoken, and the corresponding process. +.Pp +The +.Fn sched:::tick +fires before each scheduler clock tick. +Its arguments are the currently-running thread and its corresponding process. +.Sh ARGUMENTS +The +.Nm sched +provider probes use the kernel types +.Vt "struct proc" +and +.Vt "struct thread" +to represent processes and threads, respectively. +These structures have many fields and are defined in +.Pa sys/proc.h . +In a probe body, the currently-running thread can always be obtained with the +.Va curthread +global variable, which has type +.Vt "struct thread *" . +For example, when a running thread is about to sleep, the +.Fn sched:::sleep +probe fires in the context of that thread, which can be accessed using +.Va curthread . +The +.Va curcpu +global variable contains the cpuid of the CPU on which the currently-running +thread is executing. +.Sh EXAMPLES +The following script gives a breakdown of CPU utilization by process name: +.Bd -literal -offset indent +sched:::on-cpu +{ + self->ts = timestamp; +} + +sched:::off-cpu +/self->ts != 0/ +{ + @[execname] = sum((timestamp - self->ts) / 1000); + self->ts = 0; +} +.Ed +.Pp +Here, DTrace stores a timestamp each time a thread is scheduled to run, and +computes the time elapsed in microseconds when it is descheduled. +The results are summed by process name. +.Sh COMPATIBILITY +This provider is not compatible with the +.Nm sched +provider found in Solaris. +In particular, the probe argument types are native +.Fx +types, and the +.Fn sched:::cpucaps-sleep , +.Fn sched:::cpucaps-wakeup , +.Fn sched:::schedctl-nopreempt , +.Fn sched:::schedctl-preempt , +and +.Fn sched:::schedctl-yield +probes are not available in +.Fx . +.Pp +The +.Fn sched:::lend-pri +and +.Fn sched:::load-change +probes are specific to +.Fx . +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr sched_4bsd 4 , +.Xr sched_ule 4 , +.Xr SDT 9 , +.Xr sleepqueue 9 +.Sh HISTORY +The +.Nm sched +provider first appeared in +.Fx +8.4 and 9.1. +.Sh AUTHORS +This manual page was written by +.An Mark Johnston Aq Mt markj@FreeBSD.org . diff --git a/static/freebsd/man4/dtrace_sctp.4 b/static/freebsd/man4/dtrace_sctp.4 new file mode 100644 index 00000000..6e2f1ed3 --- /dev/null +++ b/static/freebsd/man4/dtrace_sctp.4 @@ -0,0 +1,226 @@ +.\" Copyright (c) 2018 Devin Teske +.\" +.\" 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 June 29, 2023 +.Dt DTRACE_SCTP 4 +.Os +.Sh NAME +.Nm dtrace_sctp +.Nd a DTrace provider for tracing events related to the +.Xr sctp 4 +protocol +.Sh SYNOPSIS +.Fn sctp:cwnd::init uint32_t uint32_t uintptr_t int int +.Fn sctp:cwnd::ack uint32_t uint32_t uintptr_t int int +.Fn sctp:cwnd::rttvar uint64_t uint64_t uint64_t uint64_t uint64_t +.Fn sctp:cwnd::rttstep uint64_t uint64_t uint64_t uint64_t uint64_t +.Fn sctp:cwnd::fr uint32_t uint32_t uintptr_t int int +.Fn sctp:cwnd::to uint32_t uint32_t uintptr_t int int +.Fn sctp:cwnd::bl uint32_t uint32_t uintptr_t int int +.Fn sctp:cwnd::ecn uint32_t uint32_t uintptr_t int int +.Fn sctp:cwnd::pd uint32_t uint32_t uintptr_t int int +.Fn sctp:rwnd:assoc:val uint32_t uint32_t int int +.Fn sctp:flightsize:net:val uint32_t uint32_t uintptr_t int int +.Fn sctp:flightsize:assoc:val uint32_t uint32_t int int +.Fn sctp:::receive "pktinfo_t *" "csinfo_t *" "ipinfo_t *" "sctpsinfo_t *" \ + "sctpinfo_t *" +.Fn sctp:::send "pktinfo_t *" "csinfo_t *" "ipinfo_t *" "sctpsinfo_t *" \ + "sctpinfo_t *" +.Fn sctp:::state-change "void *" "csinfo_t *" "void *" "sctpsinfo_t *" \ + "void *" "sctplsinfo_t *" +.Sh DESCRIPTION +The DTrace +.Nm sctp +provider allows users to trace events in the +.Xr sctp 4 +protocol implementation. +This provider is similar to the +.Xr dtrace_ip 4 +and +.Xr dtrace_udp 4 +providers, +but additionally contains probes corresponding to protocol events at a level +higher than packet reception and transmission. +.Pp +The +.Fn sctp:cwnd:: +probes track changes in the congestion window on a netp. +The +.Fn sctp:rwnd:: +probes track changes in the receiver window for an assoc. +The +.Fn sctp:flightsize:net:val +probe tracks changes in the flight size on a net or assoc and the +.Fn sctp:flightsize:assoc:val +probe provides the total flight version. +.Pp +The arguments of all +.Nm sctp +probes except for +.Fn sctp:cwnd::rtt* +and +.Fn sctp::assoc:val +are the Vtag for this end, +the port number of the local side, +the pointer to +.Dv struct sctp_nets *changing , +the old value of the cwnd, +and the new value of the cwnd. +.Pp +The arguments of +.Fn sctp:::val +are similar to the above except the fourth argument is the up/down amount. +.Pp +The +.Fn sctp:cwnd::rtt* +probe arguments are a bitmap of +.Dv Vtag << 32 | localport << 16 | remoteport , +a bitmap of +.Dv obw | nbw , +a bitmap of +.Dv bwrtt | newrtt , +.Dv flight , +and a bitmap of +.Dv (cwnd << 32) | point << 16 | retval(0/1) . +.Pp +The +.Fn sctp:cwnd::init +probe fires when a remotely-initiated active SCTP open succeeds. +At this point the new connection is in the ESTABLISHED state, and the probe +arguments expose the headers associated with the final ACK of the four-way +handshake. +.Pp +The +.Fn sctp:::send +and +.Fn sctp:::receive +probes fire when the host sends or receives an SCTP packet, respectively. +As with the +.Xr dtrace_udp 4 +provider, +.Nm sctp +probes fire only for packets sent by or to the local host; forwarded packets are +handled in the IP layer and are only visible to the +.Xr dtrace_ip 4 +provider. +.Pp +The +.Fn sctp:::state-change +probe fires upon local SCTP association state transitions. +Its first, third and fifth arguments are currently always +.Dv NULL . +Its last argument describes the from-state in the transition, and the to-state +can be obtained from +.Dv args[3]->sctps_state . +.\" .Sh ARGUMENTS +.Sh FILES +.Bl -tag -width "/usr/lib/dtrace/sctp.d" -compact +.It Pa /usr/lib/dtrace/sctp.d +DTrace type and translator definitions for the +.Nm sctp +provider. +.El +.Sh EXAMPLES +A script that logs SCTP packets in real time: +.Bd -literal -offset indent +#pragma D option quiet +#pragma D option switchrate=10hz + +dtrace:::BEGIN +{ + printf(" %3s %15s:%-5s %15s:%-5s\\n", "CPU", + "LADDR", "LPORT", "RADDR", "RPORT"); +} + +sctp:::send +{ + printf(" %3d %16s:%-5d -> %16s:%-5d\\n", cpu, + args[2]->ip_saddr, args[4]->sctp_sport, + args[2]->ip_daddr, args[4]->sctp_dport); +} + +sctp:::receive +{ + printf(" %3d %16s:%-5d <- %16s:%-5d\\n", cpu, + args[2]->ip_daddr, args[4]->sctp_dport, + args[2]->ip_saddr, args[4]->sctp_sport); +} +.Ed +A script that logs SCTP association state changes as they occur: +.Bd -literal -offset indent +#pragma D option quiet +#pragma D option switchrate=10 + +int last[int]; + +dtrace:::BEGIN +{ + printf(" %3s %12s %-25s %-25s\\n", + "CPU", "DELTA(us)", "OLD", "NEW"); +} + +sctp:::state-change +/ last[args[1]->cs_cid] / +{ + this->elapsed = (timestamp - last[args[1]->cs_cid]) / 1000; + printf(" %3d %12d %-25s -> %-25s\\n", cpu, this->elapsed, + sctp_state_string[args[5]->sctps_state], + sctp_state_string[args[3]->sctps_state]); + last[args[1]->cs_cid] = timestamp; +} + +sctp:::state-change +/ last[args[1]->cs_cid] == 0 / +{ + printf(" %3d %12s %-25s -> %-25s\\n", cpu, "-", + sctp_state_string[args[5]->sctps_state], + sctp_state_string[args[3]->sctps_state]); + last[args[1]->cs_cid] = timestamp; +} +.Ed +.Sh COMPATIBILITY +The +.Fn sctp:::send , +.Fn sctp:::receive , +and +.Fn sctp:::state-change +probes are compatible with the +.Nm sctp +provider in Solaris. +All other probes are only available in FreeBSD. +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr dtrace_ip 4 , +.Xr dtrace_udp 4 , +.Xr dtrace_udplite 4 , +.Xr sctp 4 , +.Xr SDT 9 +.\" .Sh HISTORY +.\" The +.\" .Nm sctp +.\" provider first appeared in +.\" .Fx +.\" UNKNOWN. +.Sh AUTHORS +This manual page was written by +.An Devin Teske Aq Mt dteske@FreeBSD.org . diff --git a/static/freebsd/man4/dtrace_tcp.4 b/static/freebsd/man4/dtrace_tcp.4 new file mode 100644 index 00000000..af57f6e9 --- /dev/null +++ b/static/freebsd/man4/dtrace_tcp.4 @@ -0,0 +1,526 @@ +.\" Copyright (c) 2015 Mark Johnston +.\" 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 2, 2023 +.Dt DTRACE_TCP 4 +.Os +.Sh NAME +.Nm dtrace_tcp +.Nd a DTrace provider for tracing events related to the +.Xr tcp 4 +protocol +.Sh SYNOPSIS +.Fn tcp:::accept-established "pktinfo_t *" "csinfo_t *" "ipinfo_t *" \ + "tcpsinfo_t *" "tcpinfo_t *" +.Fn tcp:::accept-refused "pktinfo_t *" "csinfo_t *" "ipinfo_t *" \ + "tcpsinfo_t *" "tcpinfo_t *" +.Fn tcp:::connect-established "pktinfo_t *" "csinfo_t *" "ipinfo_t *" \ + "tcpsinfo_t *" "tcpinfo_t *" +.Fn tcp:::connect-refused "pktinfo_t *" "csinfo_t *" "ipinfo_t *" \ + "tcpsinfo_t *" "tcpinfo_t *" +.Fn tcp:::connect-request "pktinfo_t *" "csinfo_t *" "ipinfo_t *" \ + "tcpsinfo_t *" "tcpinfo_t *" +.Fn tcp:::receive "pktinfo_t *" "csinfo_t *" "ipinfo_t *" "tcpsinfo_t *" \ + "tcpinfo_t *" +.Fn tcp:::send "pktinfo_t *" "csinfo_t *" "ipinfo_t *" "tcpsinfo_t *" \ + "tcpinfo_t *" +.Fn tcp:::state-change "void *" "csinfo_t *" "void *" "tcpsinfo_t *" "void *" \ + "tcplsinfo_t *" +.Fn tcp:::siftr "siftrinfo_t *" +.Sh DESCRIPTION +The DTrace +.Nm tcp +provider allows users to trace events in the +.Xr tcp 4 +protocol implementation. +This provider is similar to the +.Xr dtrace_ip 4 +and +.Xr dtrace_udp 4 +providers, but additionally contains probes corresponding to protocol events at +a level higher than packet reception and transmission. +All +.Nm tcp +probes except for +.Fn tcp:::state-change +and +.Fn tcp:::siftr +have the same number and type of arguments. +The last three arguments are used to describe a TCP segment: the +.Vt ipinfo_t +argument exposes the version-agnostic fields of the IP header, while the +.Vt tcpinfo_t +argument exposes the TCP header, and the +.Vt tcpsinfo_t +argument describes details of the corresponding TCP connection state, if any. +Their fields are described in the ARGUMENTS section. +.Pp +The +.Fn tcp:::accept-established +probe fires when a remotely-initiated active TCP open succeeds. +At this point the new connection is in the ESTABLISHED state, and the probe +arguments expose the headers associated with the final ACK of the three-way +handshake. +The +.Fn tcp:::accept-refused +probe fires when a SYN arrives on a port without a listening socket. +The probe arguments expose the headers associated with the RST to be transmitted +to the remote host in response to the SYN segment. +.Pp +The +.Fn tcp:::connect-established , +.Fn tcp:::connect-refused , +and +.Fn tcp:::connect-request +probes are similar to the +.Ql accept +probes, except that they correspond to locally-initiated TCP connections. +The +.Fn tcp:::connect-established +probe fires when the SYN-ACK segment of a three-way handshake is received from +the remote host and a final ACK is prepared for transmission. +This occurs immediately after the local connection state transitions from +SYN-SENT to ESTABLISHED. +The probe arguments describe the headers associated with the received SYN-ACK +segment. +The +.Fn tcp:::connect-refused +probe fires when the local host receives a RST segment in response to a SYN +segment, indicating that the remote host refused to open a connection. +The probe arguments describe the IP and TCP headers associated with the received +RST segment. +The +.Fn tcp:::connect-request +probe fires as the kernel prepares to transmit the initial SYN segment of a +three-way handshake. +.Pp +The +.Fn tcp:::send +and +.Fn tcp:::receive +probes fire when the host sends or receives a TCP packet, respectively. +As with the +.Xr dtrace_udp 4 +provider, +.Nm tcp +probes fire only for packets sent by or to the local host; forwarded packets are +handled in the IP layer and are only visible to the +.Xr dtrace_ip 4 +provider. +.Pp +The +.Fn tcp:::state-change +probe fires upon local TCP connection state transitions. +Its first, third and fifth arguments are currently always +.Dv NULL . +Its last argument describes the from-state in the transition, and the to-state +can be obtained from +.Dv args[3]->tcps_state . +.Pp +The +.Fn tcp:::siftr +probe fires when a TCP segment is sent or received by the host. +For a detailed description see +.Xr siftr 4 . +The +.Vt siftrinfo_t +argument provides the information about the TCP connection. +.Sh ARGUMENTS +The +.Vt pktinfo_t +argument is currently unimplemented and is included for compatibility with other +implementations of this provider. +Its fields are: +.Bl -tag -width "uinptr_t pkt_addr" -offset indent +.It Vt uinptr_t pkt_addr +Always set to 0. +.El +.Pp +The +.Vt csinfo_t +argument is currently unimplemented and is included for compatibility with other +implementations of this provider. +Its fields are: +.Bl -tag -width "uintptr_t cs_addr" -offset indent +.It Vt uintptr_t cs_addr +Always set to 0. +.It Vt uint64_t cs_cid +A pointer to the +.Vt struct inpcb +for this packet, or +.Dv NULL . +.It Vt pid_t cs_pid +Always set to 0. +.El +.Pp +The +.Vt ipinfo_t +type is a version-agnostic representation of fields from an IP header. +Its fields are described in the +.Xr dtrace_ip 4 +manual page. +.Pp +The +.Vt tcpsinfo_t +type is used to provide a stable representation of TCP connection state. +Some +.Nm tcp +probes, such as +.Fn tcp:::accept-refused , +fire in a context where there is no TCP connection; this argument is +.Dv NULL +in that case. +Its fields are: +.Bl -tag -width "uint16_t tcps_lport" -offset indent +.It Vt uintptr_t tcps_addr +The address of the corresponding TCP control block. +This is currently a pointer to a +.Vt struct tcpcb . +.It Vt int tcps_local +A boolean indicating whether the connection is local to the host. +Currently unimplemented and always set to -1. +.It Vt int tcps_active +A boolean indicating whether the connection was initiated by the local host. +Currently unimplemented and always set to -1. +.It Vt uint16_t tcps_lport +Local TCP port. +.It Vt uint16_t tcps_rport +Remote TCP port. +.It Vt string tcps_laddr +Local address. +.It Vt string tcps_raddr +Remote address. +.It Vt int32_t tcps_state +Current TCP state. +The valid TCP state values are given by the constants prefixed with +.Ql TCPS_ +in +.Pa /usr/lib/dtrace/tcp.d . +.It Vt uint32_t tcps_iss +Initial send sequence number. +.It Vt uint32_t tcps_suna +Initial sequence number of sent but unacknowledged data. +.It Vt uint32_t tcps_snxt +Next sequence number for send. +.It Vt uint32_t tcps_rack +Sequence number of received and acknowledged data. +.It Vt uint32_t tcps_rnxt +Next expected sequence number for receive. +.It Vt u_long tcps_swnd +TCP send window size. +.It Vt int32_t tcps_snd_ws +Window scaling factor for the TCP send window. +.It Vt u_long tcps_rwnd +TCP receive window size. +.It Vt int32_t tcps_rcv_ws +Window scaling factor for the TCP receive window. +.It Vt u_long tcps_cwnd +TCP congestion window size. +.It Vt u_long tcps_cwnd_ssthresh +Congestion window threshold at which slow start ends and congestion avoidance +begins. +.It Vt uint32_t tcps_sack_fack +Last sequence number selectively acknowledged by the receiver. +.It Vt uint32_t tcps_sack_snxt +Next selectively acknowledge sequence number at which to begin retransmitting. +.It Vt uint32_t tcps_rto +Round-trip timeout, in milliseconds. +.It Vt uint32_t tcps_mss +Maximum segment size. +.It Vt int tcps_retransmit +A boolean indicating that the local sender is retransmitting data. +.It Vt int tcps_srtt +Smoothed round-trip time. +.El +.Pp +The +.Vt tcpinfo_t +type exposes the fields in a TCP segment header in host order. +Its fields are: +.Bl -tag -width "struct tcphdr *tcp_hdr" -offset indent +.It Vt uint16_t tcp_sport +Source TCP port. +.It Vt uint16_t tcp_dport +Destination TCP port. +.It Vt uint32_t tcp_seq +Sequence number. +.It Vt uint32_t tcp_ack +Acknowledgement number. +.It Vt uint8_t tcp_offset +Data offset, in bytes. +.It Vt uint8_t tcp_flags +TCP flags. +.It Vt uint16_t tcp_window +TCP window size. +.It Vt uint16_t tcp_checksum +Checksum. +.It Vt uint16_t tcp_urgent +Urgent data pointer. +.It Vt struct tcphdr *tcp_hdr +A pointer to the raw TCP header. +.El +.Pp +The +.Vt tcplsinfo_t +type is used by the +.Fn tcp:::state-change +probe to provide the from-state of a transition. +Its fields are: +.Bl -tag -width "int32_t tcps_state" -offset indent +.It Vt int32_t tcps_state +A TCP state. +The valid TCP state values are given by the constants prefixed with +.Ql TCPS_ +in +.Pa /usr/lib/dtrace/tcp.d . +.El +.Pp +The +.Vt siftrinfo_t +type is used by the +.Fn tcp:::siftr +probe to provide the state of the TCP connection. +Its fields are: +.Bl -tag -width "u_int sent_inflight_bytes" -offset indent +.It Vt uint8_t direction +Direction of packet that triggered the log message. +Either +.Qq 0 +for in, or +.Qq 1 +for out. +.It Vt uint8_t ipver +The version of the IP protocol being used. +Either +.Qq 1 +for IPv4, or +.Qq 2 +for IPv6. +.It Vt uint16_t lport +The TCP port that the local host is communicating via. +.It Vt uint16_t rport +The TCP port that the remote host is communicating via. +.It Vt string laddr +The IPv4 or IPv6 address of the local host. +.It Vt string raddr +The IPv4 or IPv6 address of the remote host. +.It Vt uint32_t snd_cwnd +The current congestion window (CWND) for the flow, in bytes. +.It Vt uint32_t snd_wnd +The current sending window for the flow, in bytes. +The post scaled value is reported, except during the initial handshake (first +few packets), during which time the unscaled value is reported. +.It Vt uint32_t rcv_wnd +The current receive window for the flow, in bytes. +The post scaled value is always reported. +.It Vt uint32_t t_flags2 +The current value of the t_flags2 for the flow. +.It Vt uint32_t snd_ssthresh +The slow start threshold (SSTHRESH) for the flow, in bytes. +.It Vt int conn_state +A TCP state. +The valid TCP state values are given by the constants prefixed with +.Ql TCPS_ +in +.Pa /usr/lib/dtrace/tcp.d . +.It Vt uint32_t mss +The maximum segment size (MSS) for the flow, in bytes. +.It Vt uint32_t srtt +The current smoothed RTT (SRTT) for the flow in microseconds. +.It Vt u_char sack_enabled +SACK enabled indicator. 1 if SACK enabled, 0 otherwise. +.It Vt u_char snd_scale +The current window scaling factor for the sending window. +.It Vt u_char rcv_scale +The current window scaling factor for the receiving window. +.It Vt u_int t_flags +The current value of the t_flags for the flow. +.It Vt uint32_t rto +The current retransmission timeout (RTO) for the flow in microseconds. +Divide by HZ to get the timeout length in seconds. +.It Vt u_int snd_buf_hiwater +The current size of the socket send buffer in bytes. +.It Vt u_int snd_buf_cc +The current number of bytes in the socket send buffer. +.It Vt u_int rcv_buf_hiwater +The current size of the socket receive buffer in bytes. +.It Vt u_int rcv_buf_cc +The current number of bytes in the socket receive buffer. +.It Vt u_int sent_inflight_bytes +The current number of unacknowledged bytes in-flight. +Bytes acknowledged via SACK are not excluded from this count. +.It Vt int t_segqlen +The current number of segments in the reassembly queue. +.It Vt u_int flowid +Flowid for the connection. +A caveat: Zero '0' either represents a valid flowid or a default value when +the flowid is not being set. +.It Vt u_int flowtype +Flow type for the connection. +Flowtype defines which protocol fields are hashed to produce the flowid. +A complete listing is available in +.Pa /usr/include/sys/mbuf.h +under +.Dv M_HASHTYPE_* . +.El +.Sh FILES +.Bl -tag -width "/usr/lib/dtrace/siftr.d" -compact +.It Pa /usr/lib/dtrace/tcp.d +DTrace type and translator definitions for all the probes of the +.Nm tcp +provider except the +.Nm siftr +probe. +.It Pa /usr/lib/dtrace/siftr.d +DTrace type and translator definitions for the +.Nm siftr +probe of the +.Nm tcp +provider. +.El +.Sh EXAMPLES +The following script logs TCP segments in real time: +.Bd -literal -offset indent +#pragma D option quiet +#pragma D option switchrate=10hz + +dtrace:::BEGIN +{ + printf(" %3s %15s:%-5s %15s:%-5s %6s %s\\n", "CPU", + "LADDR", "LPORT", "RADDR", "RPORT", "BYTES", "FLAGS"); +} + +tcp:::send +{ + this->length = args[2]->ip_plength - args[4]->tcp_offset; + printf(" %3d %16s:%-5d -> %16s:%-5d %6d (", cpu, args[2]->ip_saddr, + args[4]->tcp_sport, args[2]->ip_daddr, args[4]->tcp_dport, + this->length); + printf("%s", args[4]->tcp_flags & TH_FIN ? "FIN|" : ""); + printf("%s", args[4]->tcp_flags & TH_SYN ? "SYN|" : ""); + printf("%s", args[4]->tcp_flags & TH_RST ? "RST|" : ""); + printf("%s", args[4]->tcp_flags & TH_PUSH ? "PUSH|" : ""); + printf("%s", args[4]->tcp_flags & TH_ACK ? "ACK|" : ""); + printf("%s", args[4]->tcp_flags & TH_URG ? "URG|" : ""); + printf("%s", args[4]->tcp_flags == 0 ? "null " : ""); + printf("\\b)\\n"); +} + +tcp:::receive +{ + this->length = args[2]->ip_plength - args[4]->tcp_offset; + printf(" %3d %16s:%-5d <- %16s:%-5d %6d (", cpu, + args[2]->ip_daddr, args[4]->tcp_dport, args[2]->ip_saddr, + args[4]->tcp_sport, this->length); + printf("%s", args[4]->tcp_flags & TH_FIN ? "FIN|" : ""); + printf("%s", args[4]->tcp_flags & TH_SYN ? "SYN|" : ""); + printf("%s", args[4]->tcp_flags & TH_RST ? "RST|" : ""); + printf("%s", args[4]->tcp_flags & TH_PUSH ? "PUSH|" : ""); + printf("%s", args[4]->tcp_flags & TH_ACK ? "ACK|" : ""); + printf("%s", args[4]->tcp_flags & TH_URG ? "URG|" : ""); + printf("%s", args[4]->tcp_flags == 0 ? "null " : ""); + printf("\\b)\\n"); +} +.Ed +The following script logs TCP connection state changes as they occur: +.Bd -literal -offset indent +#pragma D option quiet +#pragma D option switchrate=25hz + +int last[int]; + +dtrace:::BEGIN +{ + printf(" %12s %-20s %-20s %s\\n", + "DELTA(us)", "OLD", "NEW", "TIMESTAMP"); +} + +tcp:::state-change +{ + this->elapsed = (timestamp - last[args[1]->cs_cid]) / 1000; + printf(" %12d %-20s -> %-20s %d\\n", this->elapsed, + tcp_state_string[args[5]->tcps_state], + tcp_state_string[args[3]->tcps_state], timestamp); + last[args[1]->cs_cid] = timestamp; +} + +tcp:::state-change +/last[args[1]->cs_cid] == 0/ +{ + printf(" %12s %-20s -> %-20s %d\\n", "-", + tcp_state_string[args[5]->tcps_state], + tcp_state_string[args[3]->tcps_state], timestamp); + last[args[1]->cs_cid] = timestamp; +} +.Ed +The following script uses the siftr probe to show the current value of CWND +and SSTHRESH when a packet is sent or received: +.Bd -literal -offset indent +#pragma D option quiet +#pragma D option switchrate=10hz + +dtrace:::BEGIN +{ + printf(" %3s %16s:%-5s %16s:%-5s %10s %10s\\n", + "DIR", "LADDR", "LPORT", "RADDR", "RPORT", "CWND", "SSTHRESH"); +} + +tcp:::siftr +{ + printf(" %3s %16s:%-5d %16s:%-5d %10u %10u\\n", + siftr_dir_string[args[0]->direction], + args[0]->laddr, args[0]->lport, args[0]->raddr, args[0]->rport, + args[0]->snd_cwnd, args[0]->snd_ssthresh); +} +.Ed +.Sh COMPATIBILITY +This provider is compatible with the +.Nm tcp +provider in Solaris. +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr dtrace_ip 4 , +.Xr dtrace_sctp 4 , +.Xr dtrace_udp 4 , +.Xr dtrace_udplite 4 , +.Xr siftr 4 , +.Xr tcp 4 , +.Xr SDT 9 +.Sh HISTORY +The +.Nm tcp +provider first appeared in +.Fx +10.0. +.Sh AUTHORS +This manual page was written by +.An Mark Johnston Aq Mt markj@FreeBSD.org . +.Sh BUGS +The +.Vt tcps_local +and +.Vt tcps_active +fields of +.Vt tcpsinfo_t +are not filled in by the translator. diff --git a/static/freebsd/man4/dtrace_udp.4 b/static/freebsd/man4/dtrace_udp.4 new file mode 100644 index 00000000..2e5c40cc --- /dev/null +++ b/static/freebsd/man4/dtrace_udp.4 @@ -0,0 +1,203 @@ +.\" Copyright (c) 2015 Mark Johnston +.\" 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 August 1, 2018 +.Dt DTRACE_UDP 4 +.Os +.Sh NAME +.Nm dtrace_udp +.Nd a DTrace provider for tracing events related to the UDP protocol +.Sh SYNOPSIS +.Fn udp:::receive "pktinfo_t *" "csinfo_t *" "ipinfo_t *" "udpsinfo_t *" \ + "udpinfo_t *" +.Fn udp:::send "pktinfo_t *" "csinfo_t *" "ipinfo_t *" "udpsinfo_t *" \ + "udpinfo_t *" +.Sh DESCRIPTION +The DTrace +.Nm udp +provider allows users to trace events in the +.Xr udp 4 +protocol implementation. +The +.Fn udp:::send +probe fires whenever the kernel prepares to transmit a UDP packet, and the +.Fn udp:::receive +probe fires whenever the kernel receives a UDP packet, unless +the UDP header is incomplete, +the destination port is 0, +the length field is invalid, +or the checksum is wrong. +The arguments to these probes can be used to obtain detailed information about +the IP and UDP headers of the corresponding packet. +.Sh ARGUMENTS +The +.Vt pktinfo_t +argument is currently unimplemented and is included for compatibility with other +implementations of this provider. +Its fields are: +.Bl -tag -width "uintptr_t pkt_addr" -offset indent +.It Vt uintptr_t pkt_addr +Always set to 0. +.El +.Pp +The +.Vt csinfo_t +argument is currently unimplemented and is included for compatibility with other +implementations of this provider. +Its fields are: +.Bl -tag -width "uintptr_t cs_addr" -offset indent +.It Vt uintptr_t cs_addr +Always set to 0. +.It Vt uint64_t cs_cid +A pointer to the +.Vt struct inpcb +for this packet, or +.Dv NULL . +.It Vt pid_t cs_pid +Always set to 0. +.El +.Pp +The +.Vt ipinfo_t +argument contains IP fields common to both IPv4 and IPv6 packets. +Its fields are: +.Bl -tag -width "uint32_t ip_plength" -offset indent +.It Vt uint8_t ip_ver +IP version of the packet, 4 for IPv4 packets and 6 for IPv6 packets. +.It Vt uint32_t ip_plength +IP payload size. +This does not include the size of the IP header or IPv6 option headers. +.It Vt string ip_saddr +IP source address. +.It Vt string ip_daddr +IP destination address. +.El +.Pp +The +.Vt udpsinfo_t +argument contains the state of the UDP connection associated with the packet. +Its fields are: +.Bl -tag -width "uintptr_t udps_addr" -offset indent +.It Vt uintptr_t udps_addr +Pointer to the +.Vt struct inpcb +containing the IP state for the associated socket. +.It Vt uint16_t udps_lport +Local UDP port. +.It Vt uint16_t udps_rport +Remote UDP port. +.It Vt string udps_laddr +Local IPv4 or IPv6 address. +.It Vt string udps_raddr +Remote IPv4 or IPv6 address. +.El +.Pp +The +.Vt udpinfo_t +argument is the raw UDP header of the packet, with all fields in host order. +Its fields are: +.Bl -tag -width "struct udphdr *udp_hdr" -offset indent +.It Vt uint16_t udp_sport +Source UDP port. +.It Vt uint16_t udp_dport +Destination UDP port. +.It Vt uint16_t udp_length +Length of the UDP header and payload, in bytes. +.It Vt uint16_t udp_checksum +A checksum of the UDP header and payload, or 0 if no checksum was calculated. +.It Vt struct udphdr *udp_hdr +A pointer to the raw UDP header. +.El +.Sh FILES +.Bl -tag -width "/usr/lib/dtrace/udp.d" -compact +.It Pa /usr/lib/dtrace/udp.d +DTrace type and translator definitions for the +.Nm udp +provider. +.El +.Sh EXAMPLES +The following script counts transmitted packets by destination port. +.Bd -literal -offset indent +udp:::send +{ + @num[args[4]->udp_dport] = count(); +} +.Ed +.Pp +This script will print some details of each UDP packet as it is sent or received +by the kernel: +.Bd -literal -offset indent +#pragma D option quiet +#pragma D option switchrate=10Hz + +dtrace:::BEGIN +{ + printf(" %10s %36s %-36s %6s\\n", "DELTA(us)", "SOURCE", + "DEST", "BYTES"); + last = timestamp; +} + +udp:::send +{ + this->elapsed = (timestamp - last) / 1000; + self->dest = strjoin(strjoin(args[2]->ip_daddr, ":"), + lltostr(args[4]->udp_dport)); + printf(" %10d %30s:%-5d -> %-36s %6d\\n", this->elapsed, + args[2]->ip_saddr, args[4]->udp_sport, + self->dest, args[4]->udp_length); + last = timestamp; +} + +udp:::receive +{ + this->elapsed = (timestamp - last) / 1000; + self->dest = strjoin(strjoin(args[2]->ip_saddr, ":"), + lltostr(args[4]->udp_sport)); + printf(" %10d %30s:%-5d <- %-36s %6d\\n", this->elapsed, + args[2]->ip_daddr, args[4]->udp_dport, + self->dest, args[4]->udp_length); + last = timestamp; +} +.Ed +.Sh COMPATIBILITY +This provider is compatible with the +.Nm udp +provider in Solaris. +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr dtrace_ip 4 , +.Xr dtrace_sctp 4 , +.Xr dtrace_tcp 4 , +.Xr dtrace_udplite 4 , +.Xr udp 4 , +.Xr SDT 9 +.Sh HISTORY +The +.Nm udp +provider first appeared in +.Fx +10.0. +.Sh AUTHORS +This manual page was written by +.An Mark Johnston Aq Mt markj@FreeBSD.org . diff --git a/static/freebsd/man4/dtrace_udplite.4 b/static/freebsd/man4/dtrace_udplite.4 new file mode 100644 index 00000000..768de095 --- /dev/null +++ b/static/freebsd/man4/dtrace_udplite.4 @@ -0,0 +1,202 @@ +.\" Copyright (c) 2015 Mark Johnston +.\" Copyright (c) 2018 Michael Tuexen +.\" 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 August 1, 2018 +.Dt DTRACE_UDPLITE 4 +.Os +.Sh NAME +.Nm dtrace_udplite +.Nd a DTrace provider for tracing events related to the UDP-Lite protocol +.Sh SYNOPSIS +.Fn udplite:::receive "pktinfo_t *" "csinfo_t *" "ipinfo_t *" "udplitesinfo_t *" \ + "udpliteinfo_t *" +.Fn udplite:::send "pktinfo_t *" "csinfo_t *" "ipinfo_t *" "udplitesinfo_t *" \ + "udpliteinfo_t *" +.Sh DESCRIPTION +The DTrace +.Nm udplite +provider allows users to trace events in the +.Xr udplite 4 +protocol implementation. +The +.Fn udplite:::send +probe fires whenever the kernel prepares to transmit a UDP-Lite packet, and the +.Fn udplite:::receive +probe fires whenever the kernel receives a UDP-Lite packet, unless +the UDP-Lite header is incomplete, +the destination port is 0, +the length field is invalid, +or the checksum is wrong. +The arguments to these probes can be used to obtain detailed information about +the IP and UDP-Lite headers of the corresponding packet. +.Sh ARGUMENTS +The +.Vt pktinfo_t +argument is currently unimplemented and is included for compatibility with other +implementations of this provider. +Its fields are: +.Bl -tag -width "uintptr_t pkt_addr" -offset indent +.It Vt uintptr_t pkt_addr +Always set to 0. +.El +.Pp +The +.Vt csinfo_t +argument is currently unimplemented and is included for compatibility with other +implementations of this provider. +Its fields are: +.Bl -tag -width "uintptr_t cs_addr" -offset indent +.It Vt uintptr_t cs_addr +Always set to 0. +.It Vt uint64_t cs_cid +A pointer to the +.Vt struct inpcb +for this packet, or +.Dv NULL . +.It Vt pid_t cs_pid +Always set to 0. +.El +.Pp +The +.Vt ipinfo_t +argument contains IP fields common to both IPv4 and IPv6 packets. +Its fields are: +.Bl -tag -width "uint32_t ip_plength" -offset indent +.It Vt uint8_t ip_ver +IP version of the packet, 4 for IPv4 packets and 6 for IPv6 packets. +.It Vt uint32_t ip_plength +IP payload size. +This does not include the size of the IP header or IPv6 option headers. +.It Vt string ip_saddr +IP source address. +.It Vt string ip_daddr +IP destination address. +.El +.Pp +The +.Vt udplitesinfo_t +argument contains the state of the UDP-Lite connection associated with the packet. +Its fields are: +.Bl -tag -width "uintptr_t udplites_addr" -offset indent +.It Vt uintptr_t udplites_addr +Pointer to the +.Vt struct inpcb +containing the IP state for the associated socket. +.It Vt uint16_t udplites_lport +Local UDP-Lite port. +.It Vt uint16_t udplites_rport +Remote UDP-Lite port. +.It Vt string udplites_laddr +Local IPv4 or IPv6 address. +.It Vt string udplites_raddr +Remote IPv4 or IPv6 address. +.El +.Pp +The +.Vt udpliteinfo_t +argument is the raw UDP-Lite header of the packet, with all fields in host order. +Its fields are: +.Bl -tag -width "struct udplitehdr *udplite_hdr" -offset indent +.It Vt uint16_t udplite_sport +Source UDP-Lite port. +.It Vt uint16_t udplite_dport +Destination UDP-Lite port. +.It Vt uint16_t udplite_coverage +Checksum coverage of the UDP-Lite header, in bytes, or 0 for full coverage. +.It Vt uint16_t udplite_checksum +A checksum of the UDP-Lite header and payload, or 0 if no checksum was calculated. +.It Vt struct udplitehdr *udplite_hdr +A pointer to the raw UDP-Lite header. +.El +.Sh FILES +.Bl -tag -width "/usr/lib/dtrace/udplite.d" -compact +.It Pa /usr/lib/dtrace/udplite.d +DTrace type and translator definitions for the +.Nm udplite +provider. +.El +.Sh EXAMPLES +The following script counts transmitted packets by destination port. +.Bd -literal -offset indent +udplite:::send +{ + @num[args[4]->udplite_dport] = count(); +} +.Ed +.Pp +This script will print some details of each UDP-Lite packet as it is sent or received +by the kernel: +.Bd -literal -offset indent +#pragma D option quiet +#pragma D option switchrate=10Hz + +dtrace:::BEGIN +{ + printf(" %10s %36s %-36s %6s\\n", "DELTA(us)", "SOURCE", + "DEST", "COV"); + last = timestamp; +} + +udplite:::send +{ + this->elapsed = (timestamp - last) / 1000; + self->dest = strjoin(strjoin(args[2]->ip_daddr, ":"), + lltostr(args[4]->udplite_dport)); + printf(" %10d %30s:%-5d -> %-36s %6d\\n", this->elapsed, + args[2]->ip_saddr, args[4]->udplite_sport, + self->dest, args[4]->udplite_coverage); + last = timestamp; +} + +udplite:::receive +{ + this->elapsed = (timestamp - last) / 1000; + self->dest = strjoin(strjoin(args[2]->ip_saddr, ":"), + lltostr(args[4]->udplite_sport)); + printf(" %10d %30s:%-5d <- %-36s %6d\\n", this->elapsed, + args[2]->ip_daddr, args[4]->udplite_dport, + self->dest, args[4]->udplite_coverage); + last = timestamp; +} +.Ed +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr dtrace_ip 4 , +.Xr dtrace_sctp 4 , +.Xr dtrace_tcp 4 , +.Xr dtrace_udp 4 , +.Xr udplite 4 , +.Xr SDT 9 +.Sh HISTORY +The +.Nm udplite +provider first appeared in +.Fx +12.0. +.Sh AUTHORS +This manual page was written by +.An Mark Johnston Aq Mt markj@FreeBSD.org +and +.An Michael Tuexen Aq Mt tuexen@FreeBSD.org . diff --git a/static/freebsd/man4/dtrace_vfs.4 b/static/freebsd/man4/dtrace_vfs.4 new file mode 100644 index 00000000..528d5da4 --- /dev/null +++ b/static/freebsd/man4/dtrace_vfs.4 @@ -0,0 +1,97 @@ +.\" +.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd November 3, 2025 +.Dt DTRACE_VFS 4 +.Os +.Sh NAME +.Nm dtrace_vfs +.Nd a DTrace provider for Virtual File System +.Sh SYNOPSIS +.Sm off +.Nm vfs Cm : fplookup : Ar function Cm : Ar name +.Nm vfs Cm : namecache : Ar function Cm : Ar name +.Nm vfs Cm : namei : Ar function Cm : Ar name +.Nm vfs Cm : vop : Ar function Cm : Ar name +.Sm on +.Sh DESCRIPTION +The DTrace +.Nm vfs +provider allows users to trace events in the +.Xr VFS 9 +layer, the kernel interface for file systems on +.Fx . +.Pp +Run +.Ql dtrace -l -P vfs +to list all +.Nm vfs +probes. +Add +.Fl v +to generate program stability reports, +which contain information about the number of probe arguments and their types. +.Pp +The +.Cm fplookup +module defines a single probe, +.Fn vfs:fplookup:lookup:done "struct nameidata *ndp" "int line" "bool status_code" , +that instruments the fast path lookup code in +.Xr VFS 9 . +.Pp +The +.Cm namecache +module provides probes related to the +.Xr VFS 9 +cache. +Consult the source code in +.Pa src/sys/kern/vfs_cache.c +for more details. +.Pp +The +.Cm namei +module manages probes related to pathname translation and lookup operations. +Refer to +.Xr namei 9 +to learn more. +.Pp +The +.Cm vop +module contains probes related to the functions responsible for +.Xr vnode 9 +operations. +.Sh COMPATIBILITY +This provider is specific to +.Fx . +.Sh EXAMPLES +Check what lookups failed to be handled in a lockless manner: +.Bd -literal -offset 2n +# dtrace -n 'vfs:fplookup:lookup:done { @[arg1, arg2] = count(); }' +.Ed +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr d 7 , +.Xr SDT 9 , +.Xr namei 9 , +.Xr VFS 9 +.Rs +.%A Brendan Gregg +.%A Jim Mauro +.%B DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD +.%I Prentice Hall +.%P pp. 335\(en351 +.%D 2011 +.%U https://www.brendangregg.com/dtracebook/ +.Re +.Sh AUTHORS +.An -nosplit +The +.Fx +.Nm vfs +provider was written by +.An Robert Watson Aq Mt rwatson@FreeBSD.org . +.Pp +This manual page was written by +.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . diff --git a/static/freebsd/man4/dummymbuf.4 b/static/freebsd/man4/dummymbuf.4 new file mode 100644 index 00000000..08926d28 --- /dev/null +++ b/static/freebsd/man4/dummymbuf.4 @@ -0,0 +1,211 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2024 Igor Ostapenko +.\" +.\" 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. +.\" +.\" Note: The date here should be updated whenever a non-trivial +.\" change is made to the manual page. +.Dd January 6, 2025 +.Dt DUMMYMBUF 4 +.Os +.Sh NAME +.Nm dummymbuf +.Nd "mbuf alteration pfil hooks" +.Sh SYNOPSIS +To compile the driver into the kernel, +place the following line in the +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device dummymbuf" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +dummymbuf_load="YES" +.Ed +.Sh DESCRIPTION +This module is intended to test networking code in the face of unusual mbuf +layouts. +The special +.Xr pfil 9 +hooks are provided for mbuf alteration and can be listed with +.Xr pfilctl 8 +as follows: +.Bd -literal -offset indent + Hook Type + dummymbuf:ethernet Ethernet + dummymbuf:inet6 IPv6 + dummymbuf:inet IPv4 +.Ed +.Pp +To activate a hook it must be linked to the respective +.Xr pfil 9 +head. +.Xr pfilctl 8 +can be used for the linking. +.Pp +Each time a hook is invoked it reads a single shared set of +.Sx RULES +from +.Va net.dummymbuf.rules +sysctl. +The rules are evaluated sequentially and each matching rule performs the +specified operation over the mbuf. +.Pp +After every successfully applied operation the +.Va net.dummymbuf.hits +sysctl counter is increased. +.Pp +A hook returns an altered mbuf for further processing, but it drops a packet +if rules parsing or an operation fails. +Also, the first mbuf of the original chain may be changed. +.Pp +The module is +.Xr VNET 9 +based, hence every +.Xr jail 2 +provides its own set of hooks and sysctl variables. +.Sh RULES +The set of rules is a semicolon separated list. +An empty string is treated as a parsing failure. +A rule conceptually has two parts, filter and operation, with the following +syntax: +.Bd -literal -offset indent +{inet | inet6 | ethernet} {in | out} [ ]; +.Ed +.Ss Filter +The first word of a rule matches +.Xr pfil 9 +type. +The second matches packet's direction, and the third matches the network +interface a packet is coming from. +.Ss Operation +An operation may have arguments separated from its name by space. +The available operations are: +.Bl -tag -width indent +.It pull-head +Unconditionally creates a brand new cluster-based mbuf and links it to be the +first mbuf of the original mbuf chain, with respective packet header moving. +After, the given number of bytes are pulled from the original mbuf chain. +.Pp +If it is asked to pull 0 bytes then the first mbuf of the resulting chain will +be left empty. +Asking to pull more than +.Dv MCLBYTES +is treated as an operation failure. +If a mbuf chain has less data than asked then the entire packet is pulled with +tail mbuf(s) left empty. +.Pp +As a result, only the layout of a mbuf chain is altered, its content logically +is left intact. +.It enlarge +Unconditionally replace the mbuf with an mbuf of the specified size. +.El +.Sh SYSCTL VARIABLES +The following variables are available: +.Bl -tag -width indent +.It Va net.dummymbuf.rules +A string representing a single set of +.Sx RULES +shared among all +.Nm +hooks. +.It Va net.dummymbuf.hits +Number of times a rule has been applied. +It is reset to zero upon writing. +.El +.Sh EXAMPLES +As it was intended, +.Nm +can be found useful for firewall testing. +A mbuf chain could be altered before it hits a firewall to test that the latter +can handle a case respectively. +Thus, it is important to have correct sequence of hooks. +A test case should prepare and enable a firewall first to get its hooks linked. +After, the +.Xr pfilctl 8 +should be used to link +.Nm +hook(s) to put them in front of a firewall. +.Pp +The following links +.Va dummymbuf:inet6 +hook for inbound and puts it in front of other hooks: +.Bd -literal -offset indent +pfilctl link -i dummymbuf:inet6 inet6 +.Ed +.Pp +And this does the same for outbound: +.Bd -literal -offset indent +pfilctl link -o -a dummymbuf:inet6 inet6 +.Ed +.Pp +For instance, we want to test a scenario in which the very first mbuf in a +chain has zero m_len, to verify that a firewall can correctly read the +packet data despite that. +The following set of rules does it for inbound and outbound: +.Bd -literal -offset indent +sysctl net.dummymbuf.rules="inet6 in em0 pull-head 0; inet6 out em0 pull-head 0;" +.Ed +.Pp +It is encouraged to verify +.Va net.dummymbuf.hits +sysctl counter along with other test assertions to make sure that +.Nm +really does its work and there is no false positive due to misconfiguration. +It is a good idea to reset it before the action: +.Bd -literal -offset indent +sysctl net.dummymbuf.hits=0 +.Ed +.Pp +It is equally important to cleanup the things after the test case: +.Bd -literal -offset indent +pfilctl unlink -i dummymbuf:inet6 inet6 +pfilctl unlink -o dummymbuf:inet6 inet6 +sysctl net.dummymbuf.rules="" +.Ed +.Pp +If a test case operates within a temporary vnet then explicit cleanup can be +omitted, the +.Nm +facilities will vanish along with its vnet instance. +.Sh DIAGNOSTICS +.Bl -diag +.It "dummymbuf: : rule parsing failed: " +If everything looks fine then extra spaces removal may help due to the parser +is kept very simple. +.It "dummymbuf: : mbuf operation failed: " +Incorrect operation argument has been found, mbuf allocation has failed, etc. +.El +.Sh SEE ALSO +.Xr jail 2 , +.Xr pfilctl 8 , +.Xr mbuf 9 , +.Xr pfil 9 , +.Xr VNET 9 +.Sh AUTHORS +The module and this manual page were written by +.An Igor Ostapenko Aq Mt pm@igoro.pro . diff --git a/static/freebsd/man4/dummynet.4 b/static/freebsd/man4/dummynet.4 new file mode 100644 index 00000000..ad82cb80 --- /dev/null +++ b/static/freebsd/man4/dummynet.4 @@ -0,0 +1,80 @@ +.\" +.Dd September 10, 2021 +.Dt DUMMYNET 4 +.Os +.Sh NAME +.Nm dummynet +.Nd traffic shaper, bandwidth manager and delay emulator +.Sh DESCRIPTION +The +.Nm +system facility permits the control of traffic +going through the various network interfaces, by applying bandwidth +and queue size limitations, implementing different scheduling and queue +management policies, and emulating delays and losses. +.Pp +The user interface for +.Nm +is implemented by the +.Xr dnctl 8 +utility, so please refer to the +.Xr dnctl 8 +manpage for a complete description of the +.Nm +capabilities and how to use it. +.Ss Kernel Options +The following options in the kernel configuration file are related to +.Nm +operation: +.Pp +.Bl -tag -width ".Dv IPFIREWALL_VERBOSE_LIMIT" -offset indent -compact +.It Dv IPFIREWALL +enable ipfirewall (if +.Nm +is to be used with ipfw) +.It Dv IPFIREWALL_VERBOSE +enable firewall output +.It Dv IPFIREWALL_VERBOSE_LIMIT +limit firewall output +.It Dv DUMMYNET +enable +.Nm +operation +.It Dv HZ +set the timer granularity +.El +.Pp +Generally, the following options are required: +.Bd -literal -offset indent +options IPFIREWALL +options DUMMYNET +options HZ=1000 # strongly recommended +.Ed +.Pp +Additionally, one may want to increase the number +of mbuf clusters (used to store network packets) according to the +sum of the bandwidth-delay products and queue sizes of all configured +pipes. +.Sh SEE ALSO +.Xr setsockopt 2 , +.Xr if_bridge 4 , +.Xr ip 4 , +.Xr pf.conf 5 , +.Xr dnctl 8 , +.Xr ipfw 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +facility +was initially implemented as a testing tool for +.Tn TCP +congestion control by +.An Luigi Rizzo Aq Mt luigi@iet.unipi.it , +as described on ACM Computer Communication Review, Jan.97 issue. +Later it has been modified to work at the +.Tn IP +and bridging levels, integrated with the +.Xr ipfw 4 +packet filter, and extended to +support multiple queueing and scheduling policies. diff --git a/static/freebsd/man4/e6000sw.4 b/static/freebsd/man4/e6000sw.4 new file mode 100644 index 00000000..be80888d --- /dev/null +++ b/static/freebsd/man4/e6000sw.4 @@ -0,0 +1,48 @@ +.\" +.\" Copyright (c) 2025 Alexander Ziaee +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd April 16, 2026 +.Dt E6000SW 4 +.Sh NAME +.Nm e6000sw +.Nd Marvell 88E6000 series Gigabit Ethernet switch driver +.Sh SYNOPSIS +.Cd device mdio +.Cd etherswitch +.Cd e6000sw +.Sh DESCRIPTION +The +.Nm +driver supports Marvell Gigabit Ethernet switch controllers. +.Sh HARDWARE +The +.Nm +driver supports the following Gigabit Ethernet switch controllers: +.Pp +.Bl -bullet -compact +.It +Marvell 88E6190X +.It +Marvell 88E6190 +.It +Marvell 88E6176 +.It +Marvell 88E6172 +.It +Marvell 88E6171 +.It +Marvell 88E6341 +.It +Marvell 88E6141 +.El +.Sh SEE ALSO +.Xr e6060sw 4 , +.Xr etherswitch 4 , +.Xr etherswitchcfg 8 +.Sh HISTORY +The +.Nm +driver appeared in +.Fx 11.0 . diff --git a/static/freebsd/man4/e6060sw.4 b/static/freebsd/man4/e6060sw.4 new file mode 100644 index 00000000..74736f65 --- /dev/null +++ b/static/freebsd/man4/e6060sw.4 @@ -0,0 +1,81 @@ +.\"- +.\" Copyright (c) 2017 Hiroki Mori +.\" 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 May 10, 2025 +.Dt E6060SW 4 +.Os +.Sh NAME +.Nm e6060sw +.Nd Marvell 88E6060/88E6063/88E6065 Fast Ethernet switch driver +.Sh SYNOPSIS +.Cd "device mdio" +.Cd "device etherswitch" +.Cd "device e6060sw" +.Pp +.Cd hint.e6060sw.0.at="mdio0" +.Sh DESCRIPTION +The +.Nm +device driver provides a management interface to Marvell 88E6060 and 88E6065 fast ethernet switch chip. +This driver use smi interface by ethernet interface. +.Pp +88E6060 support is only port vlan. +88E6065 support is port and dot1q vlan. +dot1q support group base tag/untag. +.Sh HARDWARE +The +.Nm +driver supports the following Fast Ethernet switch controllers: +.Pp +.Bl -bullet -compact +.It +Marvell 88E6060 +.It +Marvell 88E6063 +.It +Marvell 88E6065 +.El +.Sh EXAMPLES +Configure dot1q vlan on 88E6065 by etherswitchcfg command. +.Pp +.Dl # etherswitchcfg config vlan_mode dot1q +.Pp +Configure vlangroup with dot1q tag on 88E6065. +This example is port0 as vlan 2. +.Pp +.Dl # etherswitchcfg vlangroup2 vlan 2 members 0,5t port0 pvid 2 +.Sh SEE ALSO +.Xr etherswitch 4 , +.Xr etherswitchcfg 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 12.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Hiroki Mori diff --git a/static/freebsd/man4/edsc.4 b/static/freebsd/man4/edsc.4 new file mode 100644 index 00000000..f7ee4ca5 --- /dev/null +++ b/static/freebsd/man4/edsc.4 @@ -0,0 +1,104 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 March 25, 2007 +.Dt EDSC 4 +.Os +.Sh NAME +.Nm edsc +.Nd Ethernet discard network interface +.Sh SYNOPSIS +.Cd "device edsc" +.Sh DESCRIPTION +The +.Nm +interface is a software discard mechanism which may be +used for performance analysis and software testing. +It imitates an Ethernet device, which +allows for its use in conjunction with such drivers as +.Xr if_bridge 4 +and +.Xr vlan 4 . +.Pp +As with other network interfaces, an +.Nm +interface must have network addresses assigned for each address family +with which it is to be used. +These addresses may be set or changed with the +.Dv SIOCSIFADDR +.Xr ioctl 2 +or +.Xr ifconfig 8 +utility. +.Pp +Each +.Nm +interface is created at runtime using interface cloning. +This is most easily done with the +.Xr ifconfig 8 +.Cm create +command or using the +.Va cloned_interfaces +variable in +.Xr rc.conf 5 . +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr arp 4 , +.Xr if_bridge 4 , +.Xr inet 4 , +.Xr intro 4 , +.Xr vlan 4 , +.Xr rc.conf 5 , +.Xr arp 8 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device was derived from the +.Xr disc 4 +device and first appeared in +.Fx 6.3 . +This manpage was adapted from +.Xr disc 4 . +.Sh CAVEATS +Since outgoing packets are just discarded by +.Nm , +ARP requests stay unreplied. +Consequently, an IP packet cannot be sent via +.Nm +until a static +.Xr arp 4 +entry is created for its next hop using +.Xr arp 8 . +.Pp +Initially an +.Nm +interface has a zero link level address. +It can be changed with +.Xr ifconfig 8 +.Cm lladdr +if needed. diff --git a/static/freebsd/man4/efidev.4 b/static/freebsd/man4/efidev.4 new file mode 100644 index 00000000..defae1f3 --- /dev/null +++ b/static/freebsd/man4/efidev.4 @@ -0,0 +1,162 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2018 Kyle Evans +.\" +.\" 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 June 18, 2021 +.Dt EFIDEV 4 +.Os +.Sh NAME +.Nm efidev , +.Nm efirtc +.Nd user-mode access to UEFI runtime services +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "options EFIRT" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the following +line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +efirt_load="YES" +.Ed +.Pp +The driver may be disabled by setting the +.Xr loader 8 +tunable +.Va efi.rt.disabled +to +.Dq Li 1 . +.Sh DESCRIPTION +The +.Nm +device provides user-mode access to UEFI runtime services. +.Nm +also includes a driver to provide a time-of-day clock using the UEFI +real time clock (RTC). +However, the RTC may not always be available, based on the UEFI firmware. +If the RTC is not available, it will not be registered as a time-of-day clock +and the time related ioctls below will not be functional. +.Pp +.Nm +provides the following ioctls defined in +.In sys/efiio.h +with supplemental structures and constants defined in +.In sys/efi.h : +.Bl -tag -width indent +.It Dv EFIIOC_GET_TABLE Pq Vt "struct efi_get_table_ioc" +Copy the UEFI table specified by the +.Va uuid +field of the +.Vt struct efi_get_table_ioc +into the +.Va buf +field. +The memory size for the buf field can be queried by passing +.Dv NULL +pointer as a buf value. +The required size will be stored in the +.Va table_len +field. +The size of the allocated memory must be specified in the +.Va buf_len +field. +.Bd -literal -offset indent +struct efi_get_table_ioc { + void *buf; + struct uuid uuid; + size_t table_len; + size_t buf_len; +}; +.Ed +.It Dv EFIIOC_GET_TIME Pq Vt "struct efi_tm" +Get the time from the RTC, if the RTC is available. +The +.Vt struct efi_tm +passed is populated with the current time, unless an error occurs. +.Bd -literal -offset indent +struct efi_tm { + uint16_t tm_year; + uint8_t tm_mon + uint8_t tm_mday + uint8_t tm_hour; + uint8_t tm_min; + uint8_t tm_sec; + uint8_t __pad1; + uint32_t tm_nsec; + int16_t tm_tz; + uint8_t tm_dst; + uint8_t __pad2; +}; +.Ed +.It Dv EFIIOC_SET_TIME Pq Vt "struct efi_tm" +Sets the time stored by the RTC, if the RTC is available. +.It Dv EFIIOC_VAR_GET Pq Vt "struct efi_var_ioc" +Gets data from the variable described by the vendor and name fields of the +.Vt struct efi_var_ioc +into the +.Fa data +field. +.Dv EFIIOC_VAR_GET Pq Vt "struct efi_var_ioc" +will also populate the +.Fa attrib +field. +.Bd -literal +struct efi_var_ioc { + efi_char *name; + size_t namesize; + struct uuid vendor; + uint32_t attrib; + void *data; + size_t datasize; +}; +.Ed +.It Dv EFIIOC_VAR_NEXT Pq Vt "struct efi_var_ioc" +Used for enumerating all UEFI variables. +The initial call should use an empty string for the name attribute. +Subsequent calls should supply the vendor uuid and name of the last variable +returned. +.It Dv EFIIOC_VAR_SET Pq Vt "struct efi_var_ioc" +Sets data and attributes for the variable described by the name and vendor in +the +.Vt struct efi_var_ioc . +.El +.Sh FILES +.Bl -tag -width /dev/efi +.It Pa /dev/efi +.El +.Sh SEE ALSO +.Xr efivar 3 , +.Xr efirt 9 +.Sh HISTORY +A +.Nm +device first appeared in +.Fx 11.1 . +.Sh BUGS +.Nm +is currently only available on amd64 and arm64. diff --git a/static/freebsd/man4/ehci.4 b/static/freebsd/man4/ehci.4 new file mode 100644 index 00000000..eb7029f3 --- /dev/null +++ b/static/freebsd/man4/ehci.4 @@ -0,0 +1,111 @@ +.\" $NetBSD: ehci.4,v 1.8 2001/11/21 17:22:56 augustss Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Lennart Augustsson. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 24, 2018 +.Dt EHCI 4 +.Os +.Sh NAME +.Nm ehci +.Nd USB Enhanced Host Controller driver +.Sh SYNOPSIS +.Cd "device ehci" +.Sh DESCRIPTION +The +.Nm +driver provides support for the +.Tn USB +Enhanced Host Controller Interface, +which is used by +.Tn USB +2.0 controllers. +.Pp +.Tn EHCI +controllers are peculiar in that they can only handle the +.Tn USB +2.0 protocol. +This means that they normally have one or more companion controllers +(i.e., +.Xr ohci 4 +or +.Xr uhci 4 ) +handling USB 1.x devices. +Consequently each +.Tn USB +connector is electrically connected to two +.Tn USB +controllers. +The handling of this is totally automatic, +but can be noticed since +.Tn USB +1.x and +.Tn USB +2.0 devices plugged in to the same +connector appear to connect to different USB buses. +.Sh LOADER TUNABLES +When the kernel has been compiled with +.Cd options USB_DEBUG , +some tunables become available that affect the behavior of +.Nm . +These tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width "xxxxxx" +.It Va hw.usb.ehci.lostintrbug +This tunable enables the lost interrupt quirk. +The default value is 0 (off). +.It Va hw.usb.ehci.iaadbug +This tunable enables the EHCI doorbell quirk. +The default value is 0 (off). +.It Va hw.usb.ehci.no_hs +This tunable disables USB devices to attach like HIGH-speed ones and will force all attached devices to attach to the FULL- or LOW-speed companion controller. +The default value is 0 (off). +.El +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va hw.usb.ehci.debug +Debug output level, where 0 is debugging disabled and larger values increase +debug message verbosity. +Default is 0. +.El +.Sh SEE ALSO +.Xr ohci 4 , +.Xr uhci 4 , +.Xr usb 4 , +.Xr xhci 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 5.1 . diff --git a/static/freebsd/man4/em.4 b/static/freebsd/man4/em.4 new file mode 100644 index 00000000..0e9c0856 --- /dev/null +++ b/static/freebsd/man4/em.4 @@ -0,0 +1,348 @@ +.\"- +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" Copyright (c) 2001-2003, Intel Corporation +.\" 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. Neither the name of the Intel Corporation nor the names of its +.\" contributors may be used to endorse or promote products derived from +.\" this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 COPYRIGHT OWNER 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. +.\" +.\" * Other names and brands may be claimed as the property of others. +.\" +.Dd March 20, 2024 +.Dt EM 4 +.Os +.Sh NAME +.Nm em , +.Nm lem , +.Nm igb +.Nd "Intel(R) PRO/1000 Gigabit Ethernet adapter driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device iflib" +.Cd "device em" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_em_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for PCI/PCI-X Gigabit Ethernet adapters based on +the Intel 82540, 82541ER, 82541PI, 82542, 82543, 82544, 82545, 82546, +82546EB, 82546GB, and 82547 controller chips. +.Pp +The +.Nm +driver provides support for PCI Express Gigabit Ethernet adapters +based on the Intel 82571, 82572, 82573, 82574, and 82583 Ethernet +controller chips. +.Pp +The +.Nm +driver provides support for Gigabit Ethernet adapters connected to I/O +Controller Hub (ICH) and Platform Controller Hub (PCH) including Intel +80003ES2LAN, 82562, 82566, 82567, 82577, 82578, 82579, i217, i218, and i219. +.Pp +The +.Nm +driver provides support for PCI Express Gigabit Ethernet adapters +based on the Intel 82575, 82576, 82580, i210, i211, and i35x. +These appear as +.Nm igb +interfaces to maintain compatibility with existing infrastructure. +.Pp +The driver supports Transmit/Receive checksum offload and Jumbo Frames +on all but 82542-based adapters. +.Pp +Furthermore it supports TCP segmentation offload (TSO) on all adapters but +those based on the 82542, 82543, 82544 and 82547 controller chips. +The identification LEDs of the adapters supported by the +.Nm +driver can be controlled via the +.Xr led 4 +API for localization purposes. +For further hardware information, see the +.Pa README +included with the driver. +.Pp +For questions related to hardware requirements, refer to the +documentation supplied with your Intel PRO/1000 adapter. +All hardware requirements listed apply to use with +.Fx . +.Pp +Support for Jumbo Frames is provided via the interface MTU setting. +Selecting an MTU larger than 1500 bytes with the +.Xr ifconfig 8 +utility configures the adapter to receive and transmit Jumbo Frames. +The maximum MTU size for Jumbo Frames is 16114. +.Pp +This driver supports hardware assisted VLANs. +The +.Nm +driver supports the following media types: +.Bl -tag -width ".Cm 10baseT/UTP" +.It Cm autoselect +Enables auto-negotiation for speed and duplex. +.It Cm 10baseT/UTP +Sets 10Mbps operation. +Use the +.Cm mediaopt +option to select +.Cm full-duplex +mode. +.It Cm 100baseTX +Sets 100Mbps operation. +Use the +.Cm mediaopt +option to select +.Cm full-duplex +mode. +.It Cm 1000baseSX +Sets 1000Mbps operation. +Only +.Cm full-duplex +mode is supported at this speed. +.It Cm 1000baseTX +Sets 1000Mbps operation. +Only +.Cm full-duplex +mode is supported at this speed. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width ".Cm full-duplex" +.It Cm full-duplex +Forces full-duplex operation +.It Cm half-duplex +Forces half-duplex operation. +.El +.Pp +Only use +.Cm mediaopt +to set the driver to +.Cm full-duplex . +If +.Cm mediaopt +is not specified, the driver defaults to +.Cm half-duplex . +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports Gigabit Ethernet adapters based on the Intel +82540, 82541ER, 82541PI, 82542, 82543, 82544, 82545, 82546, 82546EB, +82546GB, 82547, 82571, 82572, 82573, 82574, 82575, 82576, and 82580 +controller chips: +.Pp +.Bl -bullet -compact +.It +Intel Gigabit ET Dual Port Server Adapter (82576) +.It +Intel Gigabit VT Quad Port Server Adapter (82575) +.It +Intel Single, Dual and Quad Gigabit Ethernet Controller (82580) +.It +Intel i210 and i211 Gigabit Ethernet Controller +.It +Intel i350 and i354 Gigabit Ethernet Controller +.It +Intel PRO/1000 CT Network Connection (82547) +.It +Intel PRO/1000 F Server Adapter (82543) +.It +Intel PRO/1000 Gigabit Server Adapter (82542) +.It +Intel PRO/1000 GT Desktop Adapter (82541PI) +.It +Intel PRO/1000 MF Dual Port Server Adapter (82546) +.It +Intel PRO/1000 MF Server Adapter (82545) +.It +Intel PRO/1000 MF Server Adapter (LX) (82545) +.It +Intel PRO/1000 MT Desktop Adapter (82540) +.It +Intel PRO/1000 MT Desktop Adapter (82541) +.It +Intel PRO/1000 MT Dual Port Server Adapter (82546) +.It +Intel PRO/1000 MT Quad Port Server Adapter (82546EB) +.It +Intel PRO/1000 MT Server Adapter (82545) +.It +Intel PRO/1000 PF Dual Port Server Adapter (82571) +.It +Intel PRO/1000 PF Quad Port Server Adapter (82571) +.It +Intel PRO/1000 PF Server Adapter (82572) +.It +Intel PRO/1000 PT Desktop Adapter (82572) +.It +Intel PRO/1000 PT Dual Port Server Adapter (82571) +.It +Intel PRO/1000 PT Quad Port Server Adapter (82571) +.It +Intel PRO/1000 PT Server Adapter (82572) +.It +Intel PRO/1000 T Desktop Adapter (82544) +.It +Intel PRO/1000 T Server Adapter (82543) +.It +Intel PRO/1000 XF Server Adapter (82544) +.It +Intel PRO/1000 XT Server Adapter (82544) +.El +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +See +.Xr iflib 4 +for per-instance variables. +.Bl -tag -width indent +.It Va hw.em.disable_crc_stripping +Disable or enable hardware stripping of CRC field. +This is mostly useful on BMC/IPMI shared interfaces where stripping the CRC +causes remote access over IPMI to fail. +Default 0 (enabled). +.It Va hw.em.eee_setting +Disable or enable Energy Efficient Ethernet. +Default 1 (disabled). +.It Va hw.em.smart_pwr_down +Enable or disable smart power down features on newer adapters. +Default 0 (disabled). +.It Va hw.em.sbp +Show bad packets when in promiscuous mode. +Default 0 (off). +.It Va hw.em.rx_int_delay +This value delays the generation of receive interrupts in units of +1.024 microseconds. +The default value is 0, since adapters may hang with this feature +being enabled. +.It Va hw.em.rx_abs_int_delay +If +.Va hw.em.rx_int_delay +is non-zero, this tunable limits the maximum delay in which a receive +interrupt is generated. +.It Va hw.em.tx_int_delay +This value delays the generation of transmit interrupts in units of +1.024 microseconds. +The default value is 64. +.It Va hw.em.tx_abs_int_delay +If +.Va hw.em.tx_int_delay +is non-zero, this tunable limits the maximum delay in which a transmit +interrupt is generated. +.It Va hw.em.max_interrupt_rate +Maximum interrupts per second. +The default value is 8000. +.It Va hw.em.rx_process_limit +Maximum number of received packets to process at a time, -1 means unlimited. +The default value is 100. +.El +.Sh FILES +.Bl -tag -width /dev/led/em* +.It Pa /dev/led/em* +identification LED device nodes +.El +.Sh EXAMPLES +Make the identification LED of em0 blink: +.Pp +.Dl "echo f2 > /dev/led/em0" +.Pp +Turn the identification LED of em0 off again: +.Pp +.Dl "echo 0 > /dev/led/em0" +.Sh DIAGNOSTICS +.Bl -diag +.It "em%d: Unable to allocate bus resource: memory" +A fatal initialization error has occurred. +.It "em%d: Unable to allocate bus resource: interrupt" +A fatal initialization error has occurred. +.It "em%d: watchdog timeout -- resetting" +The device has stopped responding to the network, or there is a problem with +the network connection (cable). +.El +.Sh SUPPORT +For general information and support, +go to the Intel support website at: +.Pa http://support.intel.com . +.Pp +If an issue is identified with the released source code on the supported kernel +with a supported adapter, email the specific information related to the +issue to +.Aq Mt freebsd@intel.com . +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr iflib 4 , +.Xr led 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr polling 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 4.4 . +.Nm +was merged with the +.Nm lem +and +.Nm igb +device drivers and converted to the +.Xr iflib 4 +framework in +.Fx 12.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was originally written by +.An Intel Corporation Aq Mt freebsd@intel.com . +It was merged with the +.Nm igb +driver and converted to the +.Xr iflib 4 +framework by +.An Matthew Macy Aq Mt mmacy@mattmacy.io +and +.An Sean Bruno Aq Mt sbruno@FreeBSD.org . diff --git a/static/freebsd/man4/ena.4 b/static/freebsd/man4/ena.4 new file mode 100644 index 00000000..cb5b9367 --- /dev/null +++ b/static/freebsd/man4/ena.4 @@ -0,0 +1,536 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2015-2024 Amazon.com, Inc. or its affiliates. +.\" 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 COPYRIGHT HOLDERS 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 COPYRIGHT +.\" OWNER 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 November 14, 2024 +.Dt ENA 4 +.Os +.Sh NAME +.Nm ena +.Nd AWS EC2 Elastic Network Adapter (ENA) driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in the +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ena" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_ena_load="YES" +.Ed +.Sh DESCRIPTION +The ENA is a networking interface designed to make good use of modern CPU +features and system architectures. +.Pp +The ENA device exposes a lightweight management interface with a +minimal set of memory mapped registers and extendable command set +through an Admin Queue. +.Pp +The driver supports a range of ENA devices, is link-speed independent +(i.e., the same driver is used for 10GbE, 25GbE, 40GbE, etc.), and has +a negotiated and extendable feature set. +.Pp +Some ENA devices support SR-IOV. +This driver is used for both the SR-IOV Physical Function (PF) and Virtual +Function (VF) devices. +.Pp +The ENA devices enable high speed and low overhead network traffic +processing by providing multiple Tx/Rx queue pairs (the maximum number +is advertised by the device via the Admin Queue), a dedicated MSI-X +interrupt vector per Tx/Rx queue pair, and CPU cacheline optimized +data placement. +.Pp +When RSS is enabled, each Tx/Rx queue pair is bound to a corresponding +CPU core and its NUMA domain. +The order of those bindings is based on the RSS bucket mapping. +For builds with RSS support disabled, the +CPU and NUMA management is left to the kernel. +Receive-side scaling (RSS) is supported for multi-core scaling. +.Pp +The +.Nm +driver and its corresponding devices implement health +monitoring mechanisms such as watchdog, enabling the device and driver +to recover in a manner transparent to the application, as well as +debug logs. +.Pp +Some of the ENA devices support a working mode called Low-latency +Queue (LLQ), which saves several more microseconds. +.Pp +Support for the +.Xr netmap 4 +framework is provided by the +.Nm +driver. +Kernel must be built with the DEV_NETMAP option to be able to use this feature. +.Sh HARDWARE +The +.Nm +driver supports the following PCI vendor ID/device IDs: +.Pp +.Bl -bullet -compact +.It +1d0f:0ec2 - ENA PF +.It +1d0f:1ec2 - ENA PF with LLQ support +.It +1d0f:ec20 - ENA VF +.It +1d0f:ec21 - ENA VF with LLQ support +.El +.Sh LOADER TUNABLES +The +.Nm +driver's behavior can be changed using run-time or boot-time sysctl +arguments. +The boot-time arguments can be set at the +.Xr loader 8 +prompt before booting the kernel, or stored in the +.Xr loader.conf 5 . +The run-time arguments can be set using the +.Xr sysctl 8 +command. +.Pp +Boot-time tunables: +.Bl -tag -width indent +.It Va hw.ena.enable_9k_mbufs +Use 9k mbufs for the Rx descriptors. +The default is 0. +If the node value is set to 1, 9k mbufs will be used for the Rx buffers. +If set to 0, page size mbufs will be used instead. +.Pp +Using 9k buffers for Rx can improve Rx throughput, but in low memory conditions +it might increase allocation time, as the system has to look for 3 contiguous +pages. +This can further lead to OS instability, together with ENA driver reset and NVMe +timeouts. +If network performance is critical and memory capacity is sufficient, the 9k +mbufs can be used. +.It Va hw.ena.force_large_llq_header +Force the driver to use large (224 bytes) or regular (96 bytes) LLQ header size. +The default value is 2 and the recommended LLQ header size will be used. +If the node value is set to 0, the regular size LLQ header will be used, which +is 96B. +In some cases, the packet header can be bigger than this (for example - +IPv6 with multiple extensions). +In such a situation, the large LLQ header size which is 224B should be used, +and can be forced by setting this node value to 1. +Using large LLQ header size will take effect only if the device supports +both LLQ and large LLQ headers. +Otherwise, it will fallback to the no LLQ mode or regular header size. +.Pp +Increasing LLQ header size reduces the size of the Tx queue by half, so it may +affect the number of dropped Tx packets. +.El +.Pp +Run-time tunables: +.Bl -tag -width indent +.It Va hw.ena.log_level +Controls extra logging verbosity of the driver. +The default is 2. +The higher the logging level, the more logs will be printed out. 0 means all +extra logs are disabled and only error logs will be printed out. +Default value (2) reports errors, warnings and is verbose about driver +operation. +.Pp +The possible flags are: +.Pp +.Bl -bullet -compact +.It +0 - ENA_ERR - Enable driver error messages and ena_com error logs. +.It +1 - ENA_WARN - Enable logs for non-critical errors. +.It +2 - ENA_INFO - Make the driver more verbose about its actions. +.It +3 - ENA_DBG - Enable debug logs. +.El +.Pp +NOTE: In order to enable logging on the Tx/Rx data path, driver must be compiled +with ENA_LOG_IO_ENABLE compilation flag. +.Pp +Example: +To enable logs for errors and warnings, the following command should be used: +.Bd -literal -offset indent +sysctl hw.ena.log_level=1 +.Ed +.It Va dev.ena.X.io_queues_nb +Number of the currently allocated and used IO queues. +The default is max_num_io_queues. +Controls the number of IO queue pairs (Tx/Rx). As this call has to reallocate +the queues, it will reset the interface and restart all the queues - this means +that everything, which was currently held in the queue, will be lost, leading to +potential packet drops. +.Pp +This call can fail if the system isn't able to provide the driver with enough +resources. +In that situation, the driver will try to revert the previous number of the IO +queues. +If this also fails, the device reset will be triggered. +.Pp +Example: +To use only 2 Tx and Rx queues for the device ena1, the following command should +be used: +.Bd -literal -offset indent +sysctl dev.ena.1.io_queues_nb=2 +.Ed +.It Va dev.ena.X.rx_queue_size +Size of the Rx queue. +The default is 1024. +Controls the number of IO descriptors for each Rx queue. +The user may want to increase the Rx queue size if they observe a high number of +Rx drops in the driver's statistics. +For performance reasons, the Rx queue size must be a power of 2. +.Pp +This call can fail if the system isn't able to provide the driver with enough +resources. +In that situation, the driver will try to revert to the previous number of the +descriptors. +If this also fails, the device reset will be triggered. +.Pp +Example: +To increase Rx ring size to 8K descriptors for the device ena0, the following +command should be used: +.Bd -literal -offset indent +sysctl dev.ena.0.rx_queue_size=8192 +.Ed +.It Va dev.ena.X.buf_ring_size +Size of the Tx buffer ring (drbr). +The default is 4096. +Input must be a power of 2. +Controls the number of mbufs that can be held in the Tx buffer ring. +The drbr is used as a multiple-producer, single-consumer lockless ring for +buffering extra mbufs coming from the stack in case the Tx procedure is busy +sending the packets, or the Tx ring is full. +Increasing the size of the buffer ring may reduce the number of Tx packets being +dropped in case of a big Tx burst, which cannot be handled by the IO queue +immediately. +Each Tx queue has its own drbr. +.Pp +It is recommended to keep the drbr with at least the default value, but in case +the system lacks the resources, it can be reduced. +This call can fail if the system is not able to provide the driver with enough +resources. +In that situation, the driver will try to revert to the previous number of the +drbr and trigger the device reset. +.Pp +Example: +To set drbr size for interface ena0 to 2048, the following command should +be used: +.Bd -literal -offset indent +sysctl dev.ena.0.buf_ring_size=2048 +.Ed +.It Va dev.ena.X.eni_metrics.sample_interval +Interval in seconds for updating ENI metrics. +The default is 0. +Determines how often (if ever) the ENI metrics should be updated. +The ENI metrics are being updated asynchronously in a timer service in order to +avoid admin queue overload by sysctl node reading. +The value in this node controls the interval between issuing admin commands to +the device, which will update the ENI metrics values. +.Pp +If some application is periodically monitoring the eni_metrics, then the ENI +metrics interval can be adjusted accordingly. +Value 0 turns off the update completely. +Value 1 is the minimum interval and is equal to 1 second. +The maximum allowed update interval is 1 hour. +.Pp +Example: +To update ENI metrics for the device ena1 every 10 seconds, the following +command should be used: +.Bd -literal -offset indent +sysctl dev.ena.1.eni_metrics.sample_interval=10 +.Ed +.It Va dev.ena.X.rss.indir_table_size +RSS indirection table size. +The default is 128. +Returns the number of entries in the RSS indirection table. +.Pp +Example: +To read the RSS indirection table size, the following command should be used: +.Bd -literal -offset indent +sysctl dev.ena.0.rss.indir_table_size +.Ed +.It Va dev.ena.X.rss.indir_table +RSS indirection table mapping. +The default is x:y key-pairs of indir_table_size length. +Updates selected indices of the RSS indirection table. +.Pp +The entry string consists of one or more x:y keypairs, where x stands for +the table index and y for its new value. +Table indices that don't need to be +updated can be omitted from the string and will retain their existing values. +.Pp +If an index is entered more than once, the last value is used. +.Pp +Example: +To update two selected indices in the RSS indirection table, e.g. setting index +0 to queue 5 and then index 5 to queue 0, the following command should be used: +.Bd -literal -offset indent +sysctl dev.ena.0.rss.indir_table="0:5 5:0" +.Ed +.It Va dev.ena.X.rss.key +RSS hash key. +The default is 40 bytes long randomly generated hash key. +Controls the RSS Toeplitz hash algorithm key value. +.Pp +Only available when driver compiled without the kernel side RSS support. +.Pp +Example: +To change the RSS hash key value to +.Pp +0x6d, 0x5a, 0x56, 0xda, 0x25, 0x5b, 0x0e, 0xc2, +.br +0x41, 0x67, 0x25, 0x3d, 0x43, 0xa3, 0x8f, 0xb0, +.br +0xd0, 0xca, 0x2b, 0xcb, 0xae, 0x7b, 0x30, 0xb4, +.br +0x77, 0xcb, 0x2d, 0xa3, 0x80, 0x30, 0xf2, 0x0c, +.br +0x6a, 0x42, 0xb7, 0x3b, 0xbe, 0xac, 0x01, 0xfa +.Pp +the following command should be used: +.Bd -literal -offset indent +sysctl dev.ena.0.rss.key=6d5a56da255b0ec24167253d43a38fb0d0ca2bcbae7b30b477cb2da38030f20c6a42b73bbeac01fa +.Ed +.El +.Sh DIAGNOSTICS +.Ss Device initialization phase +.Bl -diag +.It ena%d: failed to init mmio read less +.Pp +Error occurred during initialization of the mmio register read request. +.It ena%d: Can not reset device +.Pp +Device could not be reset. +.br +Device may not be responding or is already during reset. +.It ena%d: device version is too low +.Pp +Version of the controller is too old and it is not supported by the driver. +.It ena%d: Invalid dma width value %d +.Pp +The controller is unable to request dma transaction width. +.br +Device stopped responding or it demanded invalid value. +.It ena%d: Can not initialize ena admin queue with device +.Pp +Initialization of the Admin Queue failed. +.br +Device may not be responding or there was a problem with initialization of +the resources. +.It ena%d: Cannot get attribute for ena device rc: %d +.Pp +Failed to get attributes of the device from the controller. +.It ena%d: Cannot configure aenq groups rc: %d +.Pp +Errors occurred when trying to configure AENQ groups. +.El +.Ss Driver initialization/shutdown phase +.Bl -diag +.It ena%d: PCI resource allocation failed! +.It ena%d: failed to pmap registers bar +.It ena%d: can not allocate ifnet structure +.It ena%d: Error with network interface setup +.It ena%d: Failed to enable and set the admin interrupts +.It ena%d: Error, MSI-X is already enabled +.It ena%d: Failed to enable MSIX, vectors %d rc %d +.It ena%d: Not enough number of MSI-X allocated: %d +.It ena%d: Error with MSI-X enablement +.It ena%d: could not allocate irq vector: %d +.It ena%d: unable to allocate bus resource: registers! +.It ena%d: unable to allocate bus resource: msix! +.Pp +Resource allocation failed when initializing the device. +.br +Driver will not be attached. +.It ena%d: ENA device init failed (err: %d) +.It ena%d: Cannot initialize device +.Pp +Device initialization failed. +.br +Driver will not be attached. +.It ena%d: failed to register interrupt handler for irq %ju: %d +.Pp +Error occurred when trying to register Admin Queue interrupt handler. +.It ena%d: Cannot setup mgmnt queue intr +.Pp +Error occurred during configuration of the Admin Queue interrupts. +.It ena%d: Enable MSI-X failed +.Pp +Configuration of the MSI-X for Admin Queue failed. +.br +There could be lack of resources or interrupts could not have been configured. +.br +Driver will not be attached. +.It ena%d: VLAN is in use, detach first +.Pp +VLANs are being used when trying to detach the driver. +.br +VLANs must be detached first and then detach routine have to be called again. +.It ena%d: Unmapped RX DMA tag associations +.It ena%d: Unmapped TX DMA tag associations +.Pp +Error occurred when trying to destroy RX/TX DMA tag. +.It ena%d: Cannot init indirect table +.It ena%d: Cannot fill indirect table +.It ena%d: Cannot fill hash function +.It ena%d: Cannot fill hash control +.It ena%d: WARNING: RSS was not properly initialized, it will affect bandwidth +.Pp +Error occurred during initialization of one of RSS resources. +.br +The device will work with reduced performance because all RX packets will be +passed to queue 0 and there will be no hash information. +.It ena%d: LLQ is not supported. Fallback to host mode policy. +.It ena%d: Failed to configure the device mode. Fallback to host mode policy. +.It ena%d: unable to allocate LLQ bar resource. Fallback to host mode policy. +.Pp +Error occurred during Low-latency Queue mode setup. +.br +The device will work, but without the LLQ performance gain. +.It ena%d: failed to enable write combining. +.Pp +Error occurred while setting the Write Combining mode, required for the LLQ. +.It ena%d: failed to tear down irq: %d +.It ena%d: dev has no parent while releasing res for irq: %d +Release of the interrupts failed. +.El +.Ss Additional diagnostic +.Bl -diag +.It ena%d: Invalid MTU setting. new_mtu: %d max_mtu: %d min mtu: %d +.Pp +Requested MTU value is not supported and will not be set. +.It ena%d: Failed to set MTU to %d +.Pp +This message appears when either MTU change feature is not supported, or device +communication error has occurred. +.It ena%d: Keep alive watchdog timeout. +.Pp +Device stopped responding and will be reset. +.It ena%d: Found a Tx that wasn't completed on time, qid %d, index %d. +.Pp +Packet was pushed to the NIC but not sent within given time limit. +.br +It may be caused by hang of the IO queue. +.It ena%d: The number of lost tx completion is above the threshold (%d > %d). Reset the device +.Pp +If too many Tx weren't completed on time the device is going to be reset. +.br +It may be caused by hanged queue or device. +.It ena%d: Trigger reset is on +.Pp +Device will be reset. +.br +Reset is triggered either by watchdog or if too many TX packets were not +completed on time. +.It ena%d: device reset scheduled but trigger_reset is off +.Pp +Reset task has been triggered, but the driver did not request it. +.br +Device reset will not be performed. +.It ena%d: Device reset failed +.Pp +Error occurred while trying to reset the device. +.It ena%d: Cannot initialize device +.It ena%d: Error, mac address are different +.It ena%d: Error, device max mtu is smaller than ifp MTU +.It ena%d: Validation of device parameters failed +.It ena%d: Enable MSI-X failed +.It ena%d: Failed to create I/O queues +.It ena%d: Reset attempt failed. Can not reset the device +.Pp +Error occurred while trying to restore the device after reset. +.It ena%d: Device reset completed successfully, Driver info: %s +.Pp +Device has been correctly restored after reset and is ready to use. +.It ena%d: Allocation for Tx Queue %u failed +.It ena%d: Allocation for Rx Queue %u failed +.It ena%d: Unable to create Rx DMA map for buffer %d +.It ena%d: Failed to create io TX queue #%d rc: %d +.It ena%d: Failed to get TX queue handlers. TX queue num %d rc: %d +.It ena%d: Failed to create io RX queue[%d] rc: %d +.It ena%d: Failed to get RX queue handlers. RX queue num %d rc: %d +.It ena%d: could not allocate irq vector: %d +.It ena%d: failed to register interrupt handler for irq %ju: %d +.Pp +IO resources initialization failed. +.br +Interface will not be brought up. +.It ena%d: LRO[%d] Initialization failed! +.Pp +Initialization of the LRO for the RX ring failed. +.It ena%d: failed to alloc buffer for rx queue +.It ena%d: failed to add buffer for rx queue %d +.It ena%d: refilled rx qid %d with only %d mbufs (from %d) +.Pp +Allocation of resources used on RX path failed. +.br +If happened during initialization of the IO queue, the interface will not be +brought up. +.It ena%d: NULL mbuf in rx_info +.Pp +Error occurred while assembling mbuf from descriptors. +.It ena%d: tx_info doesn't have valid mbuf +.It ena%d: Invalid req_id: %hu +.It ena%d: failed to prepare tx bufs +.Pp +Error occurred while preparing a packet for transmission. +.It ena%d: ioctl promisc/allmulti +.Pp +IOCTL request for the device to work in promiscuous/allmulti mode. +.br +See +.Xr ifconfig 8 +for more details. +.El +.Sh SUPPORT +If an issue is identified with the released source code with a supported +adapter, please email the specific information related to the issue to +.Aq Mt akiyano@amazon.com , +.Aq Mt osamaabb@amazon.com +and +.Aq Mt darinzon@amazon.com . +.Sh SEE ALSO +.Xr netmap 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 11.1 . +.Sh AUTHORS +The +.Nm +driver was developed by Amazon and originally written by +.An Semihalf . diff --git a/static/freebsd/man4/enc.4 b/static/freebsd/man4/enc.4 new file mode 100644 index 00000000..86f14d2b --- /dev/null +++ b/static/freebsd/man4/enc.4 @@ -0,0 +1,142 @@ +.\" $OpenBSD: enc.4,v 1.22 2006/05/26 08:51:29 jmc Exp $ +.\" +.\" Copyright (c) 1999 Angelos D. Keromytis +.\" 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 Angelos D. Keromytis. +.\" 4. 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 August 9, 2017 +.Dt ENC 4 +.Os +.Sh NAME +.Nm enc +.Nd Encapsulating Interface +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device enc" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_enc_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +interface is a software loopback mechanism that allows hosts or +firewalls to filter +.Xr ipsec 4 +traffic using any firewall package that hooks in via the +.Xr pfil 9 +framework. +.Pp +The +.Nm +interface allows an administrator to see incoming and outgoing packets +before and after they will be or have been processed by +.Xr ipsec 4 +via +.Xr tcpdump 1 . +.Pp +The +.Dq Li enc0 +interface inherits all IPsec traffic. +Thus all IPsec traffic can be filtered based on +.Dq Li enc0 , +and all IPsec traffic could be seen by invoking +.Xr tcpdump 1 +on the +.Dq Li enc0 +interface. +.Pp +What can be seen with +.Xr tcpdump 1 +and what will be passed on to the firewalls via the +.Xr pfil 9 +framework can be independently controlled using the following +.Xr sysctl 8 +variables: +.Bl -column net.enc.out.ipsec_filter_mask 0x00000000 0x00000000 +.It Sy "Name Defaults Suggested" +.It "net.enc.out.ipsec_bpf_mask 0x00000003 0x00000001" +.It "net.enc.out.ipsec_filter_mask 0x00000001 0x00000001" +.It "net.enc.in.ipsec_bpf_mask 0x00000001 0x00000002" +.It "net.enc.in.ipsec_filter_mask 0x00000001 0x00000002" +.El +.Pp +For the incoming path a value of +.Li 0x1 +means +.Dq Li before stripping off the outer header +and +.Li 0x2 +means +.Dq Li after stripping off the outer header . +For the outgoing path +.Li 0x1 +means +.Dq Li with only the inner header +and +.Li 0x2 +means +.Dq Li with outer and inner headers . +.Bd -literal +incoming path |------| +---- IPsec processing ---- (before) ---- (after) ----> | | + | Host | +<--- IPsec processing ---- (after) ----- (before) ---- | | +outgoing path |------| +.Ed +.Pp +Most people will want to run with the suggested defaults for +.Cm ipsec_filter_mask +and rely on the security policy database for the outer headers. +.Pp +Note that packets are captured by BPF before firewall processing. +The special value 0x4 can be configured in the +.Ar ipsec_bpf_mask +and packets will be also captured after firewall processing. +.Sh EXAMPLES +To see the packets processed via +.Xr ipsec 4 , +adjust the +.Xr sysctl 8 +variables according to your need and run: +.Pp +.Dl "tcpdump -i enc0" +.Sh SEE ALSO +.Xr tcpdump 1 , +.Xr bpf 4 , +.Xr ipf 4 , +.Xr ipfw 4 , +.Xr ipsec 4 , +.Xr pf 4 diff --git a/static/freebsd/man4/enic.4 b/static/freebsd/man4/enic.4 new file mode 100644 index 00000000..1783b05d --- /dev/null +++ b/static/freebsd/man4/enic.4 @@ -0,0 +1,88 @@ +.\" Copyright 2008-2017 Cisco Systems, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS `AS IS' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd September 7, 2022 +.Dt ENIC 4 +.Os +.Sh NAME +.Nm enic +.Nd "VIC Ethernet NIC driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device iflib" +.Cd "device enic" +.Ed +.Pp +To load the driver as a module at run-time, +run the following command as root: +.Bd -literal -offset indent +kldload if_enic +.Ed +.Pp +To load the driver as a +module at boot time, place the following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_enic_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for Cisco Virtual Interface Card. +Support is limited to basic network connectivity. +Media is controlled by the NIC itself since there can be multiple +virtual PCI NIC devices exposed to the PCI bus. +.Sh HARDWARE +The +.Nm +driver should supports all known Cisco VIC cards. +.Sh CONFIGURATION +The +.Nm +network interface is configured using +.Xr ifconfig 8 +and the +.Xr sysctl 8 +tree at +.Dv dev.enic. . +All configurable entries are also tunables, and can be put directly into the +.Xr loader.conf 5 +for persistent configuration. +.Sh SEE ALSO +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 14.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Cisco UCS team +based of the DPDK driver. diff --git a/static/freebsd/man4/epair.4 b/static/freebsd/man4/epair.4 new file mode 100644 index 00000000..ba42106d --- /dev/null +++ b/static/freebsd/man4/epair.4 @@ -0,0 +1,171 @@ +.\"- +.\" Copyright (c) 2008 The FreeBSD Foundation +.\" +.\" This software was developed by CK Software GmbH under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 30, 2026 +.Dt EPAIR 4 +.Os +.Sh NAME +.Nm epair +.Nd A pair of virtual back-to-back connected Ethernet interfaces +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device epair" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_epair_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +is a pair of Ethernet-like software interfaces, +which are connected back-to-back with a virtual cross-over cable. +.Pp +Each +.Nm +interface pair is created at runtime using interface cloning. +This is most easily done with the +.Xr ifconfig 8 +.Cm create +command or using the +.Va cloned_interfaces +variable in +.Xr rc.conf 5 . +While for cloning you only give either +.Pa epair +or +.Pa epair +the +.Nm +pair will be named like +.Pa epair[ab] . +This means the names of the first +.Nm +interfaces will be +.Pa epair0a +and +.Pa epair0b . +.Pp +Like any other Ethernet interface, an +.Nm +needs to have a network address. +If the tunable +.Va net.link.epair.ether_gen_addr Ns +=0, each +.Nm +will be assigned a random locally administered address, +that is only guaranteed to be unique within one network stack. +The tunable +.Va net.link.epair.ether_gen_addr Ns +=1 will generate a stable MAC address with +.Fx +OUI using +.Xr ether_gen_addr 9 . +This tunable defaults to 1 in +.Fx 15.0 and might be removed in +.Fx 16.0 . +To change the default addresses one may use the SIOCSIFADDR +.Xr ioctl 2 or +.Xr ifconfig 8 utility. +.Pp +The basic intent is to provide connectivity between two virtual +network stack instances. +When connected to an +.Xr if_bridge 4 , +one end of the interface pair can also be part of another (virtual) LAN. +As with any other Ethernet interface, +.Nm epair +can have a +.Xr vlan 4 +configured on top of it. +.Pp +The +.Nm +has RXCSUM and RXCSUM6 enabled because it may receive a packet where the +checksum has already been validated by a physical interface. +.Pp +The +.Nm +supports TXCSUM and TXCSUM6 for TCP and UDP, but only by forwarding the order +to compute the checksum. +Thus, when using an +.Nm +interface, a TCP or UDP sender can offload checksum computation +to a physical interface. +Note that, in case the packet does not leave the host, the checksum is +unnecessary and will be ignored if offloaded. +Such packets contain an incorrect checksum, since it is not computed yet. +TXCSUM and TXCSUM6 are synchronized between the +.Nm +interface pair (i.e., enabling/disabling the capability on one end +enables/disables it on the other end). +In case one end is in a bridge and the bridge disabled TXCSUM or TXCSUM6, +this avoids a sender to send packets with checksum offloading into the +bridge by using the other end. +.Pp +The +.Nm +supports VLAN_HWTAGGING without actually adding a VLAN tag. +The sending +.Nm +end just forwards the offloading information to the other end. +The receiving +.Nm +end leaves the offloading information set to pretend that there was a VLAN tag +in the Ethernet header, which has been removed already. +To avoid a situation where the receiving +.Nm +end has VLAN_HWTAGGING disabled, this capability is synchronized between the +.Nm +interface pair (i.e., enabling/disabling the capability on one end +enables/disables it on the other end). +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr altq 4 , +.Xr bpf 4 , +.Xr if_bridge 4 , +.Xr vlan 4 , +.Xr loader.conf 5 , +.Xr rc.conf 5 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +interface first appeared in +.Fx 8.0 . +.Sh AUTHORS +The +.Nm +interface was written by +.An Bjoern A. Zeeb, CK Software GmbH, +under sponsorship from the FreeBSD Foundation. diff --git a/static/freebsd/man4/est.4 b/static/freebsd/man4/est.4 new file mode 100644 index 00000000..6452f1d4 --- /dev/null +++ b/static/freebsd/man4/est.4 @@ -0,0 +1,118 @@ +.\" +.\" Copyright (c) 2012 Sean Bruno +.\" 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 April 21, 2020 +.Dt EST 4 +.Os +.Sh NAME +.Nm est +.Nd Enhanced Speedstep Technology +.Sh SYNOPSIS +To compile this capability into your kernel +place the following line in your kernel +configuration file: +.Bd -ragged -offset indent +.Cd "device cpufreq" +.Ed +.Sh DESCRIPTION +The +.Nm +interface provides support for the Intel Enhanced Speedstep Technology. +.Pp +Note that +.Nm +capabilities are automatically loaded by the +.Xr cpufreq 4 +driver. +.Sh LOADER TUNABLES +The +.Nm +interface is intended to allow +.Xr cpufreq 4 +to access and implement Intel Enhanced SpeedStep Technology via +.Xr acpi 4 +and the acpi_perf interface accessors. +If the default settings are not optimal, the following sysctls can be +used to modify or monitor +.Nm +behavior. +.Bl -tag -width indent +.It hw.est.msr_info +Attempt to infer information from direct probing of the msr. +Should only be used in diagnostic cases. +.Pq default 0 +.It hw.est.strict +Validate frequency requested is accepted by the CPU when set. +It appears that this will only work on single core cpus. +.Pq default 0 +.El +.Sh SYSCTL VARIABLES +The following +.Xr sysctl 8 +values are available +.Bl -tag -width indent +.It Va dev.est.%d.%desc +Description of support, almost always Enhanced SpeedStep Frequency Control. +.It dev.est.0.%desc: Enhanced SpeedStep Frequency Control +.It Va dev.est.%d.%driver +Driver in use, always est. +.It dev.est.0.%driver: est +.It Va dev.est.%d.%parent +The CPU that is exposing these frequencies. +For example +.Va cpu0 . +.It dev.est.0.%parent: cpu0 +.It Va dev.est.%d.freq_settings . +The valid frequencies that are allowed by this CPU and their step values. +.It dev.est.0.freq_settings: 2201/45000 2200/45000 2000/39581 1900/37387 +1800/34806 1700/32703 1600/30227 1500/28212 1400/25828 1300/23900 1200/21613 +1100/19775 1000/17582 900/15437 800/13723 +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "est%d: on cpu%d" +.Pp +Indicates normal startup of this interface. +.It "est: CPU supports Enhanced Speedstep, but is not recognized." +.It "est: cpu_vendor GenuineIntel, msr 471c471c0600471c" +.It "device_attach: est%d attach returned 6" +.Pp +Indicates all attempts to attach to this interface have failed. +This usually indicates an improper BIOS setting restricting O/S +control of the CPU speeds. +Consult your BIOS documentation for more details. +.El +.Sh COMPATIBILITY +.Nm +is only found on supported Intel CPUs. +.Sh SEE ALSO +.Xr cpufreq 4 +.Rs +.%T "Intel 64 and IA-32 Architectures Software Developer Manuals" +.%U "http://www.intel.com/content/www/us/en/processors/architectures-software-developer-manuals.html" +.Re +.Sh AUTHORS +This manual page was written by +.An Sean Bruno Aq Mt sbruno@FreeBSD.org . diff --git a/static/freebsd/man4/et.4 b/static/freebsd/man4/et.4 new file mode 100644 index 00000000..6f9e37e0 --- /dev/null +++ b/static/freebsd/man4/et.4 @@ -0,0 +1,184 @@ +.\" +.\" Copyright (c) 2007 The DragonFly Project. 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. Neither the name of The DragonFly Project nor the names of its +.\" contributors may be used to endorse or promote products derived +.\" from this software without specific, prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 +.\" COPYRIGHT HOLDERS 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 December 9, 2011 +.Dt ET 4 +.Os +.Sh NAME +.Nm et +.Nd "Agere ET1310 10/100/Gigabit Ethernet driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device et" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_et_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports PCI Express Ethernet adapters based on the Agere ET1310 chip. +.\".Pp +.\"Support for Jumbo Frames is provided via the interface MTU setting. +.\"Selecting an MTU larger than 1500 bytes with the +.\".Xr ifconfig 8 +.\"utility configures the adapter to receive and transmit Jumbo Frames. +.\"The maximum MTU setting for Jumbo Frames is 15572. +.\"This value coincides with the maximum Jumbo Frames size of 15594. +.Pp +The +.Nm +driver supports the following media types: +.Pp +.Bl -tag -width 10baseT/UTP -compact +.It autoselect +Enable autoselection of the media types and options. +The user can manually override +the autoselected mode by adding media options to the +.Pa /etc/rc.conf +file. +.Pp +.It 10baseT/UTP +Set 10Mbps operation. +The +.Ar mediaopt +option can also be used to select either +.Ar full-duplex +or +.Ar half-duplex +modes. +.Pp +.It 100baseTX +Set 100Mbps (Fast Ethernet) operation. +The +.Ar mediaopt +option can also be used to select either +.Ar full-duplex +or +.Ar half-duplex +modes. +.Pp +.It 1000baseT +Set 1000Mbps (Gigabit Ethernet) operation. +The +.Ar mediaopt +option can only be set to +.Ar full-duplex +mode. +.El +.Pp +The +.Nm +driver supports the following +.Ar media +options: +.Pp +.Bl -tag -width full-duplex -compact +.It full-duplex +Force full-duplex operation. +.Pp +.It half-duplex +Force half-duplex operation. +.El +.Pp +Note that the 1000baseT media type is only available +if it is supported by the adapter. +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports Agere ET1310 10/100/Gigabit +Ethernet adapters. +.Sh TUNABLES +.Bl -tag -width ".Va hw.et.rx_intr_npkts" +.It Va hw.et.rx_intr_npkts +This value controls how many packets should be received +before a receive interrupt is generated. +The default value is 32. +It is recommended to set this value above 38 to prevent the host from being +livelocked under a high degree of stress. +.It Va hw.et.rx_intr_delay +This value delays the generation of receive interrupts +in units of ~4 microseconds. +It is used together with +.Va hw.et.rx_intr_npkts +to achieve RX interrupt moderation. +The default value is 20. +.It Va hw.et.tx_intr_nsegs +This value controls how many segments (not packets) should be transmitted +before a transmit interrupt is generated. +The default value is 126. +It is recommended to set this value below 280 to prevent +the TX ring from underflowing. +.It Va hw.et.timer +This value controls how often a timer interrupt should be generated. +It is used together with +.Va hw.et.tx_intr_nsegs +to achieve TX interrupt moderation. +The default value is 1000000000 (nanoseconds). +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Dx 1.11 . +The first +.Fx +release to include it was +.Fx 8.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Sepherosa Ziehau Aq Mt sepherosa@gmail.com +for +.Dx . +It was ported to +.Fx +by +.An Xin LI Aq Mt delphij@FreeBSD.org . diff --git a/static/freebsd/man4/etherswitch.4 b/static/freebsd/man4/etherswitch.4 new file mode 100644 index 00000000..ba8e32c0 --- /dev/null +++ b/static/freebsd/man4/etherswitch.4 @@ -0,0 +1,65 @@ +.\" Copyright (c) 2015 Christian Brueffer +.\" 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 April 5, 2017 +.Dt ETHERSWITCH 4 +.Os +.Sh NAME +.Nm etherswitch +.Nd "Ethernet switch framework" +.Sh SYNOPSIS +To compile the framework into the kernel, +place the following lines in the +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device etherswitch" +.Cd "device miiproxy" +.Cd "device iicbus" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides a framework for Ethernet switch devices. +.Sh FILES +.Bl -tag -width ".Pa /dev/etherswitch?" -compact +.It Pa /dev/etherswitch? +.Nm +device nodes +.El +.Sh SEE ALSO +.Xr adm6996fc 4 , +.Xr ar40xx 4 , +.Xr arswitch 4 , +.Xr e6000sw 4 , +.Xr e6060sw 4 , +.Xr iicbus 4 , +.Xr ksz8995ma 4 , +.Xr etherswitchcfg 8 +.Sh HISTORY +The +.Nm +framework first appeared in +.Fx 10.0 . +.Sh AUTHORS +.An Stefan Bethke diff --git a/static/freebsd/man4/eventtimers.4 b/static/freebsd/man4/eventtimers.4 new file mode 100644 index 00000000..fee3a326 --- /dev/null +++ b/static/freebsd/man4/eventtimers.4 @@ -0,0 +1,151 @@ +.\" Copyright (c) 2010 Alexander Motin +.\" 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 March 13, 2012 +.Dt EVENTTIMERS 4 +.Os +.Sh NAME +.Nm eventtimers +.Nd kernel event timers subsystem +.Sh SYNOPSIS +Kernel uses several types of time-related devices, such as: real time clocks, +time counters and event timers. +Real time clocks responsible for tracking real world time, mostly when system +is down. +Time counters are responsible for generation of monotonically increasing +timestamps for precise uptime tracking purposes, when system is running. +Event timers are responsible for generating interrupts at specified time or +periodically, to run different time-based events. +This page is about the last. +.Sh DESCRIPTION +Kernel uses time-based events for many different purposes: scheduling, +statistics, time keeping, profiling and many other things, based on +.Xr callout 9 +mechanism. +These purposes now grouped into three main callbacks: +.Bl -tag -width ".Fn hardclock" +.It Fn hardclock +.Xr callout 9 +and timekeeping events entry. +Called with frequency defined by +.Va hz +variable, +usually 1000Hz. +.It Fn statclock +statistics and scheduler events entry. +Called with frequency about 128Hz. +.It Fn profclock +profiler events entry. +When enabled, called with frequency about 8KHz. +.El +.Pp +Different platforms provide different kinds of timer hardware. +The goal of the event timers subsystem is to provide unified way to control +that hardware, and to use it, supplying kernel with all required time-based +events. +.Pp +Each driver implementing event timers, registers them at the subsystem. +It is possible to see the list of present event timers, like this, via +.Va kern.eventtimer +sysctl: +.Bd -literal +kern.eventtimer.choice: HPET(550) LAPIC(400) i8254(100) RTC(0) +kern.eventtimer.et.LAPIC.flags: 15 +kern.eventtimer.et.LAPIC.frequency: 0 +kern.eventtimer.et.LAPIC.quality: 400 +kern.eventtimer.et.i8254.flags: 1 +kern.eventtimer.et.i8254.frequency: 1193182 +kern.eventtimer.et.i8254.quality: 100 +kern.eventtimer.et.RTC.flags: 17 +kern.eventtimer.et.RTC.frequency: 32768 +kern.eventtimer.et.RTC.quality: 0 +kern.eventtimer.et.HPET.flags: 7 +kern.eventtimer.et.HPET.frequency: 14318180 +kern.eventtimer.et.HPET.quality: 550 +.Ed +.Pp +where: +.Bl -inset +.It Va kern.eventtimer.et. Ns Ar X Ns Va .flags +is a +bitmask, defining event timer capabilities: +.Bl -tag -offset indent -width indent -compact +.It 1 +periodic mode supported, +.It 2 +one-shot mode supported, +.It 4 +timer is per-CPU, +.It 8 +timer may stop when CPU goes to sleep state, +.It 16 +timer supports only power-of-2 divisors. +.El +.It Va kern.eventtimer.et. Ns Ar X Ns Va .frequency +is a +timer base frequency, +.It Va kern.eventtimer.et. Ns Ar X Ns Va .quality +is an +integral value, defining how good is this timer, comparing to others. +.El +.Pp +Timers management code of the kernel chooses one timer from that list. +Current choice can be read and affected via +.Va kern.eventtimer.timer +tunable/sysctl. +Several other tunables/sysctls are affecting how exactly this timer is used: +.Bl -inset +.It Va kern.eventtimer.periodic +allows to choose periodic and one-shot operation mode. +In periodic mode, periodic interrupts from timer hardware are taken as the +only source of time for time events. +One-shot mode instead uses currently selected time counter to precisely +schedule all needed events and programs event timer to generate interrupt +exactly in specified time. +Default value depends of chosen timer capabilities, but one-shot mode is +preferred, until other is forced by user or hardware. +.It Va kern.eventtimer.singlemul +in periodic mode specifies how much times higher timer frequency should be, +to not strictly alias +.Fn hardclock +and +.Fn statclock +events. +Default values are +1, 2 or 4, depending on configured HZ value. +.It Va kern.eventtimer.idletick +makes each CPU to receive every timer interrupt independently of whether they +busy or not. +By default this options is disabled. +If chosen timer is per-CPU +and runs in periodic mode, this option has no effect - all interrupts are +always generating. +.El +.Sh SEE ALSO +.Xr apic 4 , +.Xr atrtc 4 , +.Xr attimer 4 , +.Xr hpet 4 , +.Xr timecounters 4 , +.Xr eventtimers 9 diff --git a/static/freebsd/man4/exca.4 b/static/freebsd/man4/exca.4 new file mode 100644 index 00000000..d43d359b --- /dev/null +++ b/static/freebsd/man4/exca.4 @@ -0,0 +1,36 @@ +.\" +.\" Copyright (c) 2003 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. 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 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 February 23, 2003 +.Dt EXCA 4 +.Os +.Sh NAME +.Nm exca +.Nd helper module for PC Card and CardBus systems +.Sh DESCRIPTION +The +.Nm +module is used to implement the Intel ExCA interface to +PC Cards. +.Sh SEE ALSO +.Xr pccbb 4 diff --git a/static/freebsd/man4/ext2fs.4 b/static/freebsd/man4/ext2fs.4 new file mode 100644 index 00000000..816ea942 --- /dev/null +++ b/static/freebsd/man4/ext2fs.4 @@ -0,0 +1,104 @@ +.\" +.\" Copyright (c) 2006 Craig Rodrigues +.\" 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. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission +.\" +.\" THIS DOCUMENTATION 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 December 30, 2018 +.Dt EXT2FS 4 +.Os +.Sh NAME +.Nm ext2fs +.Nd "ext2/ext3/ext4 file system" +.Sh SYNOPSIS +To link into the kernel: +.Bd -ragged -offset indent +.Cd "options EXT2FS" +.Ed +.Pp +To load as a kernel loadable module: +.Pp +.Dl "kldload ext2fs" +.Sh DESCRIPTION +The +.Nm +driver will permit the +.Fx +kernel to access +ext2 +file systems and its derivatives. +It currently implements most of the features required by +.Em ext3 +and +.Em ext4 +file systems. +Support for Extended Attributes in +.Em ext4 +is experimental. +Journalling and encryption are currently not supported. +.Sh EXAMPLES +To mount a +.Nm +volume located on +.Pa /dev/ada1s1 : +.Pp +.Dl "mount -t ext2fs /dev/ada1s1 /mnt" +.Sh SEE ALSO +.Xr nmount 2 , +.Xr unmount 2 , +.Xr fstab 5 , +.Xr mount 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 2.2 . +.Sh AUTHORS +.An -nosplit +The +.Nm +kernel implementation is derived from code written, +or modified, +by +.An Godmar Back +using the UFS CSRG sources for CMU Mach. +.Pp +.An John Dyson +did the initial port to +.Fx . +.An Aditya Sarawgi +merged important parts of the allocation code from a clean-room +.Nx +implementation. +.An Zheng Liu +and +.An Fedor Uporov +implemented the read and write support respectively for +.Em ext4 +filesystems. +The +.Fx +community has contributed a huge amount of modifications. +.Pp +The initial version of this manual page was written by +.An Craig Rodrigues Aq Mt rodrigc@FreeBSD.org . diff --git a/static/freebsd/man4/fd.4 b/static/freebsd/man4/fd.4 new file mode 100644 index 00000000..06cc12d2 --- /dev/null +++ b/static/freebsd/man4/fd.4 @@ -0,0 +1,98 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 June 9, 1993 +.Dt FD 4 +.Os +.Sh NAME +.Nm fd , +.Nm stdin , +.Nm stdout , +.Nm stderr +.Nd file descriptor files +.Sh DESCRIPTION +The files +.Pa /dev/fd/0 +through +.Pa /dev/fd/# +refer to file descriptors which can be accessed through the file +system. +If the file descriptor is open and the mode the file is being opened +with is a subset of the mode of the existing descriptor, the call: +.Bd -literal -offset indent +fd = open("/dev/fd/0", mode); +.Ed +.Pp +and the call: +.Bd -literal -offset indent +fd = fcntl(0, F_DUPFD, 0); +.Ed +.Pp +are equivalent. +.Pp +Opening the files +.Pa /dev/stdin , +.Pa /dev/stdout +and +.Pa /dev/stderr +is equivalent to the following calls: +.Bd -literal -offset indent +fd = fcntl(STDIN_FILENO, F_DUPFD, 0); +fd = fcntl(STDOUT_FILENO, F_DUPFD, 0); +fd = fcntl(STDERR_FILENO, F_DUPFD, 0); +.Ed +.Pp +Flags to the +.Xr open 2 +call other than +.Dv O_RDONLY , +.Dv O_WRONLY +and +.Dv O_RDWR +are ignored. +.Sh IMPLEMENTATION NOTES +By default, +.Pa /dev/fd +is provided by +.Xr devfs 4 , +which provides nodes for the first three file descriptors. +Some sites may require nodes for additional file descriptors; these can be +made available by mounting +.Xr fdescfs 4 +on +.Pa /dev/fd . +.Sh FILES +.Bl -tag -width /dev/stderr -compact +.It Pa /dev/fd/# +.It Pa /dev/stdin +.It Pa /dev/stdout +.It Pa /dev/stderr +.El +.Sh SEE ALSO +.Xr devfs 4 , +.Xr fdescfs 4 , +.Xr tty 4 diff --git a/static/freebsd/man4/fdc.4 b/static/freebsd/man4/fdc.4 new file mode 100644 index 00000000..937be207 --- /dev/null +++ b/static/freebsd/man4/fdc.4 @@ -0,0 +1,396 @@ +.\" +.\" Copyright (c) 1994 Wilko Bulte +.\" Copyright (c) 2001 Joerg Wunsch +.\" 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. 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 November 16, 2025 +.Dt FDC 4 +.Os +.Sh NAME +.Nm fdc +.Nd "PC architecture floppy disk controller driver" +.Sh SYNOPSIS +.Cd device fdc +.Pp +In +.Pa /boot/device.hints : +.Cd hint.fdc.0.at="isa" +.Cd hint.fdc.0.port="0x3F0" +.Cd hint.fdc.0.irq="6" +.Cd hint.fdc.0.drq="2" +.Cd hint.fdc.0.flags="0x0" +.Cd hint.fd.0.at="fdc0" +.Cd hint.fd.0.drive="0" +.Cd hint.fd.0.flags="0x0" +.Cd hint.fd.1.at="fdc0" +.Cd hint.fd.1.drive="1" +.Cd hint.fd.1.flags="0x0" +.Sh DEPRECATION NOTICE +The +.Nm +driver is deprecated and may not be present in +.Fx 16.0 +and later. +.Sh DESCRIPTION +.Ss Device Usage +This driver provides access to floppy disk drives. +Floppy disks using +either FM (single-density) or MFM (double or high-density) recording +can be handled. +.Pp +Floppy disk controllers can connect up to four drives each. +The +.Nm +driver can currently handle up to two drives per controller (or four +drives on ACPI). +Upon +driver initialization, an attempt is made to find out the type of the +floppy controller in use. +The known controller types are either the +original NE765 or i8272 chips, or alternatively +.Em enhanced +controllers that are compatible with the NE72065 or i82077 chips. +These enhanced controllers (among other enhancements) implement a FIFO +for floppy data transfers that will automatically be enabled once an +enhanced chip has been detected. +This FIFO activation can be disabled +using the per-controller flags value of +.Ar 0x1 . +.Pp +By default, this driver creates a single device node +.Pa /dev/fd Ns Ar N +for each attached drive with number +.Ar N . +For historical reasons, device nodes that use a trailing UFS-style +partition letter (ranging from +.Sq a +through +.Sq h ) +can also be accessed, which will be implemented as symbolic links to +the main device node. +.Pp +Accessing the main device node will attempt to autodetect the density +of the available medium for multi-density devices. +Thus it is +possible to use either a 720 KB medium or a 1440 KB medium in a +high-density 3.5 inch standard floppy drive. +Normally, this +autodetection will only happen once at the first call to +.Xr open 2 +for the device after inserting the medium. +This assumes the drive +offers proper changeline support so media changes can be detected by +the driver. +To indicate a drive that does not have the changeline support, +this can be overridden using the per-drive device flags value of +.Ar 0x10 +(causing each call to +.Xr open 2 +to perform the autodetection). +.Pp +When trying to use a floppy device with special-density media, other +device nodes can be created, of the form +.Pa /dev/fd Ns Ar N . Ns Ar MMMM , +where +.Ar N +is the drive number, and +.Ar MMMM +is a number between one and four digits describing the device density. +Up to 15 additional subdevices per drive can be created that way. +The +administrator is free to decide on a policy how to assign these +numbers. +The two common policies are to either implement subdevices +numbered 1 through 15, or to use a number that describes the medium +density in kilobytes. +Initially, each of those devices will be +configured to the maximal density that is possible for the drive type +(like 1200 KB for 5.25 inch HD drives or 1440 KB for 3.5 inch HD +drives). +The desired density to be used on that subdevice needs to be +configured using +.Xr fdcontrol 8 . +.Pp +Drive types are configured using the lower four bits of the per-drive +device flags. +The following values can be specified: +.Bl -tag -width 2n -offset indent +.It Ar 1 +5.25 inch double-density device with 40 cylinders (360 KB native +capacity) +.It Ar 2 +5.25 inch high-density device with 80 cylinders (1200 KB native +capacity) +.It Ar 3 +3.5 inch double-density device with 80 cylinders (720 KB native +capacity) +.It Ar 4 +3.5 inch high-density device with 80 cylinders (1440 KB native +capacity) +.It Ar 5 +3.5 inch extra-density device with 80 cylinders (2880 KB native +capacity, usage currently restricted to at most 1440 KB media) +.It Ar 6 +Same as type 5, available for compatibility with some BIOSes +.El +.Pp +On IA32 architectures, the drive type can be specified as 0 for the +drives. +In that case, the CMOS configuration memory will be +consulted to obtain the value for that drive. +The ACPI probe automatically determines these values via the _FDE and +_FDI methods, but this can be overridden by specifying a drive type hint. +.Pp +Normally, each configured drive will be probed at initialization +time, using a short seek sequence. +This is intended to find out about +drives that have been configured but are actually missing or +otherwise not responding. +(The ACPI probe method does not perform this seek.) +In some environments (like laptops with +detachable drives), it might be desirable to bypass this drive probe, +and pretend a drive to be there so the driver autoconfiguration will +work even if the drive is currently not present. +For that purpose, a +per-drive device flags value of +.Ar 0x20 +needs to be specified. +.Ss Programming Interface +In addition to the normal read and write functionality, the +.Nm +driver offers a number of configurable options using +.Xr ioctl 2 . +In order to access any of this functionality, programmers need to +include the header file +.In sys/fdcio.h +into their programs. +The call to +.Xr open 2 +can be performed in two possible ways. +When opening the device +without the +.Dv O_NONBLOCK +flag set, the device is opened in a normal way, which would cause the +main device nodes to perform automatic media density selection, and which +will yield a file descriptor that is fully available for any I/O operation +or any of the following +.Xr ioctl 2 +commands. +.Pp +When opening the device with +.Dv O_NONBLOCK +set, automatic media density selection will be bypassed, and the device +remains in a half-opened state. +No actual I/O operations are possible, but +many of the +.Xr ioctl 2 +commands described below can be performed. +This mode is intended for +access to the device without the requirement to have an accessible +media present, like for status inquiries to the drive, or in order to +format a medium. +.Dv O_NONBLOCK +needs to be cleared before I/O operations are possible on the descriptor, +which requires a prior specification of the density using the +.Dv FD_STYPE +command (see below). +Operations that are not allowed on the half-opened +descriptor will cause an error value of +.Er EAGAIN . +.Pp +The following +.Xr ioctl 2 +commands are currently available: +.Bl -tag -width ".Dv FD_READID" +.It Dv FD_FORM +Used to format a floppy disk medium. +Third argument is a pointer to a +.Vt "struct fd_formb" +specifying which track to format, and which parameters to fill into +the ID fields of the floppy disk medium. +.It Dv FD_GTYPE +Returns the current density definition record for the selected device. +Third argument is a pointer to +.Vt "struct fd_type" . +.It Dv FD_STYPE +Adjusts the density definition of the selected device. +Third argument +is a pointer to +.Vt "struct fd_type" . +For the fixed-density subdevices (1 through 15 per drive), this +operation is restricted to a process with superuser privileges. +For +the auto-selecting subdevice 0, the operation is temporarily allowed +to any process, but this setting will be lost again upon the next +autoselection. +This can be used when formatting a new medium (which +will require to open the device using +.Dv O_NONBLOCK , +and thus to later adjust the density using +.Dv FD_STYPE ) . +.It Dv FD_GOPTS +Obtain the current drive options. +Third argument is a pointer to +.Vt int , +containing a bitwise union of the following possible flag values: +.Bl -tag -width ".Dv FDOPT_NOERRLOG" +.It Dv FDOPT_NORETRY +Do not automatically retry operations upon failure. +.It Dv FDOPT_NOERRLOG +Do not cause +.Dq "hard error" +kernel logs for failed I/O operations. +.It Dv FDOPT_NOERROR +Do not indicate I/O errors when returning from +.Xr read 2 +or +.Xr write 2 +system calls. +The caller is assumed to use +.Dv FD_GSTAT +calls in order to inquire about the success of each operation. +This +is intended to allow even erroneous data from bad blocks to be +retrieved using normal I/O operations. +.It Dv FDOPT_AUTOSEL +Device performs automatic density selection. +Unlike the above flags, +this one is read-only. +.El +.It Dv FD_SOPTS +Set device options, see above for their meaning. +Third argument is a +pointer to +.Vt int . +Drive options will always be cleared when closing the descriptor. +.It Dv FD_CLRERR +Clear the internal low-level error counter. +Normally, controller-level +I/O errors are only logged up to +.Dv FDC_ERRMAX +errors (currently defined to 100). +This command resets the counter. +Requires superuser privileges. +.It Dv FD_READID +Read one sector ID field from the floppy disk medium. +Third argument is +a pointer to +.Vt "struct fdc_readid" , +where the read data will be returned. +Can be used to analyze a floppy +disk medium. +.It Dv FD_GSTAT +Return the recent floppy disk controller status, if available. +Third +argument is a pointer to +.Vt "struct fdc_status" , +where the status registers (ST0, ST1, ST2, C, H, R, and N) are being +returned. +.Er EINVAL +will be caused if no recent status is available. +.It Dv FD_GDTYPE +Returns the floppy disk drive type. +Third argument is a pointer to +.Vt "enum fd_drivetype" . +This type is the same as being used in the per-drive configuration +flags, or in the CMOS configuration data or ACPI namespace on IA32 systems. +.El +.Sh SYSCTL VARIABLES +.Bl -tag -width "debug.fdc.debugflags" +.It Dv debug.fdc.debugflags +Selectively enable debugging by setting one or more flags. +.Bl -tag -width "0x40" +.It Dv 0x01 +Dump device registers on reset. +.It Dv 0x02 +When an IO operation completes, print the number of retries +when that number is greater than zero. +.It Dv 0x04 +Print when the number of retries exceeds +.Dv debug.fdc.retries +.Pq Dv EIO . +Print when the option +.Dv FDOPT_NOERROR +is set and an error would have returned from a write operation. +.It Dv 0x08 +Print detailed IO command information. +.It Dv 0x10 +Print status registers. +.It Dv 0x20 +Print detailed status registers when interrupts complete. +Print the source code line number close to the source of a +non-zero return from a thread worker operation. +.It Dv 0x40 +Print when the disk appears to be lost. +Print cylinder, head, sector, and sector shift information +after a request to read an ID field. +Notify whether a disk probe resulted in finding a disk. +When detecting the density of media present, indicate whether +the autosensing was successful, and if so, the size of the +medium in kilobytes. +Print detailed type information when setting the drive type. +.It Dv 0x80 +Print when an unknown IOCTL is used. +.El +.It Dv debug.fdc.fifo +For enhanced controllers, allows a non-default FIFO +threshold setting. +The default is 8 bytes. +.It Dv debug.fdc.retries +Maximum number of retries to attempt. +The default is 10. +.It Dv debug.fdc.spec1 +Specification byte one (step-rate + head unload). +The default step rate is 6 ms. +The default head unload time is 240 ms. +.It Dv debug.fdc.spec2 +Specification byte two (head load time + no-dma). +The default head load time is 16 ms, and no-dma is 0 +.Pq disabled . +.It Dv debug.fdc.settle +Head settling time in +.Sy settle +/ hz seconds. The default value is set during device attach. +.El +.Sh FILES +.Bl -tag -width ".Pa /dev/fd*" -compact +.It Pa /dev/fd* +floppy disk device nodes +.El +.Sh SEE ALSO +.Xr fdread 1 , +.Xr fdwrite 1 , +.Xr ioctl 2 , +.Xr open 2 , +.Xr read 2 , +.Xr write 2 , +.Xr fdcontrol 8 , +.Xr fdformat 8 +.Sh AUTHORS +.An -nosplit +This man page was initially written by +.An Wilko Bulte , +and later vastly rewritten by +.An J\(:org Wunsch . diff --git a/static/freebsd/man4/fdescfs.4 b/static/freebsd/man4/fdescfs.4 new file mode 100644 index 00000000..f8bf413f --- /dev/null +++ b/static/freebsd/man4/fdescfs.4 @@ -0,0 +1,218 @@ +.\" Copyright (c) 2021 The FreeBSD Foundation +.\" +.\" Copyright (c) 1996 +.\" Mike Pritchard . All rights reserved. +.\" +.\" Copyright (c) 1992, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" All rights reserved. +.\" +.\" This code is derived from software donated to Berkeley by +.\" Jan-Simon Pendry. +.\" +.\" Parts of this documentation was written by +.\" Konstantin Belousov under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 Jul 11, 2023 +.Dt FDESCFS 4 +.Os +.Sh NAME +.Nm fdescfs +.Nd file-descriptor file system +.Sh SYNOPSIS +.Bd -literal +fdescfs /dev/fd fdescfs rw 0 0 +.Ed +.Sh DESCRIPTION +The file-descriptor file system, or +.Nm , +provides access to the per-process file descriptor +namespace in the global file system namespace. +The conventional mount point is +.Pa /dev/fd . +.Pp +The file system's contents +appear as a list of numbered files +which correspond to the open files of the process reading the +directory. +The files +.Pa /dev/fd/0 +through +.Pa /dev/fd/# +refer to file descriptors which can be accessed through the file +system. +.Pp +The following mount options can be used when mounting +.Nm +filesystem: +.Bl -tag -width linrdlnk +.It Cm nodup +For file descriptors referencing vnodes, instead of the +.Xr dup 2 +semantic described above, implement re-opening of the referenced vnode. +See below for more details. +.It Cm linrdlnk +Report the type of the +.Nm +vnode as +.Dv VLNK +instead of +.Fx +traditional +.Dv VCHR . +For +.Xr linux 4 +ABI compatibility mount +.Nm +volume with the +.Cm linrdlnk +option. +.It Cm rdlnk +Treat +.Nm +vnodes as symbolic links consistently, in particular, follow +the resolved name for the name lookups. +This option is strictly stronger than the +.Cm linrdlnk +option, it changes not only the type returned by +.Xr stat 2 , +but also causes the +.Nm +files to behave as symlinks. +.El +.Pp +For +.Nm +mounted without the +.Cm nodup +mount option, +if the file descriptor is open and the mode the file is being opened +with is a subset of the mode of the existing descriptor, the call: +.Bd -literal -offset indent +fd = open("/dev/fd/0", mode); +.Ed +.Pp +and the call: +.Bd -literal -offset indent +fd = fcntl(0, F_DUPFD, 0); +.Ed +.Pp +are equivalent. +Flags to the +.Xr open 2 +call other than +.Dv O_RDONLY , +.Dv O_WRONLY +and +.Dv O_RDWR +are ignored. +.Pp +For +.Nm +mounted with the +.Cm nodup +option, and file descriptor referencing a vnode, the call: +.Bd -literal -offset indent +fd = open("/dev/fd/0", mode); +.Ed +.Pp +reopens the referenced vnode with the specified +.Fa mode . +In other words, the +.Fn open +call above is equivalent to +.Bd -literal -offset indent +fd = openat(0, "", O_EMPTY_PATH, mode); +.Ed +.Pp +In particular, if the file descriptor was opened with the +.Dv O_PATH +flag, then either +.Dv O_EMPTY_PATH +or +.Fn open +over +.Nm +mount with +.Cm nodup +option allows one to convert it to a regularly opened file, +assuming that the current permissions allow the requested +.Fa mode . +.Pp +.Em "Note:" +.Pa /dev/fd/0 , +.Pa /dev/fd/1 +and +.Pa /dev/fd/2 +files are created by default when devfs alone is mounted. +.Nm +creates entries for all file descriptors opened by the process. +.Sh FILES +.Bl -tag -width /dev/stderr -compact +.It Pa /dev/fd/# +.El +.Sh EXAMPLES +To mount a +.Nm +volume located on +.Pa /dev/fd : +.Pp +.Dl "mount -t fdescfs none /dev/fd" +.Pp +For +.Xr linux 4 +ABI compatibility: +.Pp +.Dl "mount -t fdescfs -o linrdlnk none /compat/linux/dev/fd" +.Pp +For substitute of +.Dv O_EMPTY_PATH +flag use: +.Pp +.Dl "mount -t fdescfs -o nodup none /dev/fdpath" +.Sh SEE ALSO +.Xr devfs 4 , +.Xr mount 8 +.Sh HISTORY +The +.Nm +file system first appeared in +.Bx 4.4 . +The +.Nm +manual page first appeared in +.Fx 2.2 . +.Sh AUTHORS +.An -nosplit +The +.Nm +manual page was written by +.An Mike Pritchard Aq Mt mpp@FreeBSD.org , +and was based on the +manual page written by +.An Jan-Simon Pendry . diff --git a/static/freebsd/man4/fdt.4 b/static/freebsd/man4/fdt.4 new file mode 100644 index 00000000..2ac570a5 --- /dev/null +++ b/static/freebsd/man4/fdt.4 @@ -0,0 +1,203 @@ +.\" +.\" Copyright (c) 2010 The FreeBSD Foundation +.\" +.\" This software was developed by Semihalf under sponsorship from +.\" the FreeBSD Foundation. +.\" +.\" 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 March 28, 2019 +.Dt FDT 4 +.Os +.Sh NAME +.Nm fdt +.Nd Flattened Device Tree support +.Sh SYNOPSIS +.Cd "options FDT" +.Cd "makeoptions FDT_DTS_FILE=.dts" +.Cd "options FDT_DTB_STATIC" +.Sh DESCRIPTION +.Em Flattened Device Tree +is a mechanism for describing computer hardware resources, which cannot be +probed or self enumerated, in a uniform and portable way. +The primary consumers of this technology are +.Em embedded systems, +where a lot of designs are based on similar chips, but have different +assignment of pins, memory layout, addresses bindings, interrupts routing and +other resources. +.Pp +Configuration data, which cannot be self discovered in run-time, has to be +supplied from external source. +The concept of a flattened device tree is a +platform and architecture independent approach for resolving such problems. +The idea is inherited from Open Firmware IEEE 1275 device-tree notion, and has +been successfully adopted by the embedded industry. +The scheme works in the following way: +.Bl -bullet +.It +Hardware platform resources are +.Em manually +described in a human readable text source format, where all non +self-enumerating information is gathered. +.It +This source description is converted +.Em (compiled) +into a binary object i.e. a flattened device tree +.Em blob +which is passed to the kernel at boot time. +.It +The kernel (driver) learns about hardware resources details and dependencies +from this [externally supplied] blob, which eliminates the need for embedding +any information about the underlying platform hardware resources in the kernel. +.It +The flattened device tree mechanism in principle does not depend on any +particular first-stage bootloader or firmware features. +The only overall +requirement for the environment is to provide a complete device tree +description to the kernel. +.El +.Pp +The +.Nm +layer allows any platform code in the kernel to retrieve information about +hardware resources from a unified origin, which brings advantages to the +embedded applications (eliminates hard-coded configuration approach, enforces +code to be data driven and extensible) leading to easier porting and +maintenance. +.Sh DEFINITIONS +.Bl -tag -width Ar +.It Va Device tree source (DTS) +The device tree source is a text file which describes hardware resources of a +computer system in a human-readable form, with certain hierarchical structure +(a tree). +The default location for DTS files in the +.Fx +source repository is +.Pa sys/dts +directory. +.It Va Device tree blob (DTB) +The textual device tree description (DTS file) is first converted (compiled) +into a binary object (the device tree blob) i.e. the DTB, which is handed over +to the final consumer (typically kernel) for parsing and processing of its +contents. +.It Va Device tree compiler (DTC) +A utility program executed on the host, which transforms (compiles) a textual +description of a device tree (DTS) into a binary object (DTB). +.It Va Device tree bindings +While the device tree textual description and the binary object are media to +convey the hardware configuration information, an actual meaning and +interpretation of the contents are defined by the device tree +.Pa bindings . +They are certain conventions describing definitions (encoding) of particular +nodes in a device tree and their properties, allowed values, ranges and so on. +Such reference conventions were provided by the legacy Open Firmware bindings, +further supplemented by the ePAPR specification. +.El +.Sh "BUILDING THE WORLD" +In order for the system to support +.Nm +it is required that +.Fx +world be built with the +.Pa WITH_FDT +build knob supplied either via +.Xr src.conf 5 +or command line defined with -D. +.Pp +This creates the user space +.Pa dtc +compiler and enables +.Nm +support in +.Xr loader 8 . +.Sh "BUILDING KERNEL" +There is a couple of options for managing +.Nm +support at the +.Fx +kernel level. +.Bl -tag -width Ar +.It Va makeoptions DTS+=.dts +Specifies device tree source (DTS) files for a given kernel. +The indicated DTS files will be converted (compiled) into a binary form +along with building the kernel itself. +Any DTS file names not written as an absolute path must be specified relative +to the default location of DTS sources i.e., +.Pa sys/dts . +.It Va makeoptions DTSO+=.dtso +Specifies device tree source overlay (DTSO) files for a given kernel. +Overlay files will be built with the kernel as with the makeoption +.Va DTS +described above. +Overlay files specified as relative paths will be relative to the default +location of DTS overlays for the platform being built i.e., +.Pa sys/dts/arm/overlays . +.It Va options FDT +The primary option for enabling +.Nm +support in the kernel. +It covers all low-level and infrastructure parts of +.Nm +kernel support, which primarily are the +.Xr fdtbus 4 +and +.Xr simplebus 4 +drivers, as well as helper routines and libraries. +.It Va makeoptions FDT_DTS_FILE=.dts +Specifies a preferred (default) device tree source (DTS) file for a given +kernel. +It will be built along with the kernel as if it were supplied via the makeoption +.Va DTS +described above. +This makeoption is not mandatory unless FDT_DTB_STATIC is also defined (see +below). +.It Va options FDT_DTB_STATIC +Typically, the device tree blob (DTB) is a stand-alone file, physically +separate from the kernel, but this option lets statically embed a +DTB file into a kernel image. +Note that when this is specified the +FDT_DTS_FILE makeoption becomes mandatory (as there needs to be a DTS file +specified in order to embed it into the kernel image). +.El +.Sh SEE ALSO +.Xr fdtbus 4 , +.Xr openfirm 4 , +.Xr simplebus 4 +.Sh STANDARDS +IEEE Std 1275: IEEE Standard for Boot (Initialization Configuration) Firmware: +Core Requirements and Practices +.Pq Vt Open Firmware . +.Pp +Power.org Standard for Embedded Power Architecture Platform Requirements +.Pq Vt ePAPR . +.Sh HISTORY +The +.Nm +support first appeared in +.Fx 9.0 . +.Sh AUTHORS +The +.Nm +support was developed by Semihalf under sponsorship from the FreeBSD +Foundation. +This manual page was written by +.An Rafal Jaworowski . diff --git a/static/freebsd/man4/fdt_pinctrl.4 b/static/freebsd/man4/fdt_pinctrl.4 new file mode 100644 index 00000000..0eab8f82 --- /dev/null +++ b/static/freebsd/man4/fdt_pinctrl.4 @@ -0,0 +1,124 @@ +.\" Copyright (c) 2018 Oleksandr Tymoshenko +.\" 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 AUTHORS 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 AUTHORS 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 March 3, 2018 +.Dt "FDT_PINCTRL" 4 +.Os +.Sh NAME +.Nm fdt_pinctrl +.Nd FDT I/O pin multiplexing support +.Sh SYNOPSIS +.Cd "device fdt_pinctrl" +.Sh DESCRIPTION +Pin multiplexing is a technology used to re-purpose a single +physical connection (depending on chip packaging it may be +pin, ball, or pad) by routing its signal to any one of several +different SoC internal devices. +For example, based on the actual device design, a single SoC chip +pin might perform any of these roles: SPI clock, I2C +data, GPIO pin, or PWM signal. +Function selection is performed by the pinmux controller, a SoC +hardware block which is usually controlled by a set of registers. +Pinmux controller capabilities and register format depend +on the actual hardware implementation. +.Pp +On +.Xr fdt 4 +based systems, the pinmux controller is represented by a node in +the device tree. +It may have any number of child nodes representing pin +configuration groups. +Properties of such nodes are hardware-specific and handled +by individual pinctrl drivers. +.Ss Example 1 +Pinmux controller device tree node +.Bd -literal +pinctrl@7e220000 { + compatible = "vndr,soc1715-pinctrl"; + reg = <0x7e220000 0x100> + + spi0_pins: spi0 { + vndr,pins = <11 12> + vndr,functions = + } + + i2c0_pins: i2c0 { + ... + } +} +.Ed +.Pp +Client devices are hardware devices that require certain pin +configurations to function properly. +Depending on the state the device is in (active, idle) it might +require different pin configurations. +Each configuration is described by setting the pinctrl-N +property to the list of phandles pointing to specific child +nodes of the pinmux controller node. +N is an integer value starting with 0 and incremented by 1 +for every new set of pin configurations. +pinctrl-0 is a default configuration that is applied in the +.Xr fdt_pinctrl_configure_tree 9 +call. +In addition to referring to pin configurations by index, they +can be referred to by name if the pinctrl-names property is set. +The value of pinctrl-names is a list of strings with names for +each pinctrl-N property. +Client devices can request specific configuration using +.Xr fdt_pinctrl_configure 9 +and +.Xr fdt_pinctrl_configure_by_name 9 . +.Ss Example 2 +.Bd -literal +backlight@7f000000 { + compatible = "vndr,vndr-bl" + reg = <0x7f000000 0x20> + ... + pinctrl-name = "active", "idle" + pinctrl-0 = <&backlight_active_pins> + pinctrl-1 = <&backlight_idle_pins> +} +.Ed +.Pp +The pinctrl driver should implement the FDT_PINCTRL_CONFIGURE +method, register itself as a pin configuration handler by +calling fdt_pinctrl_register function, and call +.Xr fdt_pinctrl_configure_tree 9 +to configure pins for all enabled devices (devices where +the "status" property is not set to "disabled"). +.Sh SEE ALSO +.Xr fdt_pinctrl 9 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 10.2 . +.Sh AUTHORS +.An -nosplit +The +.Nm +device driver was developed by +.An \&Ian Lepore Aq Mt ian@FreeBSD.org . +This manual page was written by +.An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org . diff --git a/static/freebsd/man4/fdtbus.4 b/static/freebsd/man4/fdtbus.4 new file mode 100644 index 00000000..7fb13b01 --- /dev/null +++ b/static/freebsd/man4/fdtbus.4 @@ -0,0 +1,87 @@ +.\" +.\" Copyright (c) 2010 The FreeBSD Foundation +.\" +.\" This software was developed by Semihalf under sponsorship from +.\" the FreeBSD Foundation. +.\" +.\" 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 12, 2010 +.Dt FDTBUS 4 +.Os +.Sh NAME +.Nm fdtbus +.Nd Flattened Device Tree bus driver +.Sh SYNOPSIS +.Cd "options FDT" +.Sh DESCRIPTION +The +.Nm +abstract bus driver is the primary connection and translation layer between +.Xr fdt 4 +hardware resources description and +.Fx +native newbus device drivers framework. +For an embedded system +.Nm +represents peripherals typically found on a highly integrated chip +(system-on-chip). +.Pp +The +.Nm +driver provides generic, common infrastructure for all +.Xr fdt 4 +oriented device drivers, and its main responsibilities are the +following: +.Bl -bullet +.It +Creating newbus children that reflect +.Xr fdt 4 +nodes in the flattened device tree. +.It +Managing SYS_RES_IRQ resources. +.It +Managing SYS_RES_MEMORY, SYS_RES_IOPORT resources. +.El +.Sh SEE ALSO +.Xr fdt 4 , +.Xr openfirm 4 , +.Xr simplebus 4 +.Sh STANDARDS +IEEE Std 1275: IEEE Standard for Boot (Initialization Configuration) Firmware: +Core Requirements and Practices +.Pq Vt Open Firmware . +.Pp +Power.org Standard for Embedded Power Architecture Platform Requirements +.Pq Vt ePAPR . +.Sh HISTORY +The +.Nm +support first appeared in +.Fx 9.0 . +.Sh AUTHORS +The +.Nm +support was developed by Semihalf under sponsorship from the FreeBSD +Foundation. +This manual page was written by +.An Rafal Jaworowski . diff --git a/static/freebsd/man4/ffclock.4 b/static/freebsd/man4/ffclock.4 new file mode 100644 index 00000000..150d0efb --- /dev/null +++ b/static/freebsd/man4/ffclock.4 @@ -0,0 +1,127 @@ +.\" Copyright (c) 2011 The University of Melbourne +.\" All rights reserved. +.\" +.\" This documentation was written by Julien Ridoux at the University of +.\" Melbourne under sponsorship from the FreeBSD Foundation. +.\" +.\" 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 December 1, 2011 +.Dt FFCLOCK 4 +.Os +.Sh NAME +.Nm FFCLOCK +.Nd Feed-forward system clock +.Sh SYNOPSIS +.Cd options FFCLOCK +.Sh DESCRIPTION +The +.Xr ntpd 8 +daemon has been the dominant solution for system clock synchronisation for many +years, which has in turn influenced the design of the system clock. +The ntpd daemon implements a feedback control algorithm which has been +demonstrated to perform poorly in common use cases. +.Pp +Feed-forward clock synchronisation algorithms implemented by an appropriate +daemon, in concert with the +.Nm +kernel support, have been shown to provide highly robust and accurate clock +synchronisation. +In addition to time keeping, the +.Nm +kernel mechanism provides new timestamping capabilities and the ability to +use specialised clocks. +Feed-forward synchronisation is also very well suited for virtualised +environments, reducing the overhead of timekeeping in guests and ensuring +continued smooth operation of the system clock during guest live migration. +.Pp +The +.Nm +kernel support provides feed-forward timestamping functions within the kernel +and system calls to support feed-forward synchronisation daemons +.Po see +.Xr ffclock 2 +.Pc . +.Ss Kernel Options +The following kernel configuration options are related to +.Nm : +.Pp +.Bl -tag -width ".Dv FFCLOCK" -compact +.It Dv FFCLOCK +Enable feed-forward clock support. +.El +.Ss Configuration +When feed-forward clock support is compiled into the kernel, multiple system +clocks become available to choose from. +System clock configuration is possible via the +.Va kern.sysclock +.Xr sysctl 8 +tree which provides the following variables: +.Bl -tag -width " " -offset indent +.It Va kern.sysclock.active +Name of the current active system clock which is serving time. +Set to one of the names in +.Va kern.sysclock.available +in order to change the default active system clock. +.It Va kern.sysclock.available +Lists the names of available system clocks +.Po +read-only +.Pc . +.El +.Pp +Feed-forward system clock configuration is possible via the +.Va kern.sysclock.ffclock +sysctl tree which provides the following variables: +.Bl -tag -width " " -offset indent +.It Va kern.sysclock.ffclock.version +Feed-forward clock kernel version +.Po +read-only +.Pc . +.It Va kern.sysclock.ffclock.ffcounter_bypass +Use reliable hardware timecounter as the feed-forward counter. +Will eventually be useful for virtualised environment like +.Xr xen 4 , +but currently does nothing. +.El +.Sh SEE ALSO +.Xr clock_gettime 2 , +.Xr ffclock 2 , +.Xr bpf 4 , +.Xr timecounters 4 , +.Xr sysctl 8 +.Sh HISTORY +Feed-forward clock support first appeared in +.Fx 10.0 . +.Sh AUTHORS +.An -nosplit +The feed-forward clock support was written by +.An Julien Ridoux Aq Mt jridoux@unimelb.edu.au +in collaboration with +.An Darryl Veitch Aq Mt dveitch@unimelb.edu.au +at the University of Melbourne under sponsorship from the FreeBSD Foundation. +.Pp +This manual page was written by +.An Julien Ridoux Aq Mt jridoux@unimelb.edu.au +and +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org . diff --git a/static/freebsd/man4/ffs.4 b/static/freebsd/man4/ffs.4 new file mode 100644 index 00000000..519ef1d1 --- /dev/null +++ b/static/freebsd/man4/ffs.4 @@ -0,0 +1,333 @@ +.\" Copyright (c) 2001 Networks Associates Technology, Inc. +.\" All rights reserved. +.\" +.\" This software was developed for the FreeBSD Project by Chris +.\" Costello at Safeport Network Services and NAI Labs, the Security +.\" Research Division of Network Associates, Inc. under DARPA/SPAWAR +.\" contract N66001-01-C-8035 ("CBOSS"), as part of the DARPA CHATS +.\" research program. +.\" +.\" 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 AUTHORS 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 AUTHORS 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 February 24, 2026 +.Dt FFS 4 +.Os +.Sh NAME +.Nm ffs , +.Nm ufs +.Nd Berkeley fast file system +.Sh SYNOPSIS +In the kernel configuration file: +.Cd "options FFS" +.Cd "options QUOTA" +.Cd "options SOFTUPDATES" +.Cd "options SUIDDIR" +.Cd "options UFS_ACL" +.Cd "options UFS_DIRHASH" +.Cd "options UFS_EXTATTR" +.Cd "options UFS_EXTATTR_AUTOSTART" +.Cd "options UFS_GJOURNAL" +.Pp +In +.Xr fstab 5 : +.Bd -literal -compact +/dev/disk0a /mnt ufs rw 1 1 +.Ed +.Sh DESCRIPTION +The Berkeley fast file system +provides facilities to store file system data onto a disk device. +.Nm +has been optimized over the years +for speed and reliability +and is the default +.Fx +file system. +.Ss Quotas +.Bl -tag -width 2n +.It Cd "options QUOTA" +This option allows system administrators +to set limits on disk usage +on a per-user basis. +Quotas can be used only on file systems +mounted with the +.Cm quota +option; +see +.Xr quota 1 +and +.Xr edquota 8 . +.El +.Ss Soft Updates +.Bl -tag -width 2n +.It Cd "options SOFTUPDATES" +The soft updates feature tracks writes to the disk +and enforces metadata update dependencies +(e.g., updating free block maps) +to ensure that the file system remains consistent. +.Pp +To create a new file system with the soft updates +enabled, +use +.Xr newfs 8 +command: +.Pp +.D1 Nm newfs Fl U Ar fs +.Pp +.Ar fs +can be either a mount point listed in +.Xr fstab 5 +.Pq e.g. , Pa /usr , +or a disk device +.Pq e.g., Pa /dev/da0a . +.Pp +It is possible to enable soft updates on an +.Em unmounted +file system by using +.Xr tunefs 8 +command: +.Pp +.D1 Nm tunefs Fl n Cm enable Ar fs +.Pp +Soft updates can also add journaling that reduces the time spent by +.Xr fsck_ffs 8 +cleaning up a filesystem after a crash from several minutes to a few seconds. +The journal is placed in an inode named +.Pa .sujournal , +and is kept as a circular log of segments containing +records that describe metadata operations. +.Pp +To create a new file system with both the soft updates +and soft updates journaling enabled, +use the following command: +.Pp +.D1 Nm newfs Fl j Ar fs +.Pp +This runs +.Xr tunefs 8 +command after +.Xr newfs 8 +command with +.Fl U +flag enabled. +It is possible to enable soft updates journaling on an +.Em unmounted +file system by using +.Xr tunefs 8 +command: +.Pp +.D1 Nm tunefs Fl j Cm enable Ar fs +.Pp +This flag automatically enables the soft updates feature +when it is not enabled. +Note that this +.Xr tunefs 8 +command will fail if a file +.Pa .sujournal +already exists before enabling the soft updates journaling. +.El +.Ss File Ownership Inheritance +.Bl -tag -width 2n +.It Cd "options SUIDDIR" +For use in file sharing environments +on networks including +.Tn "Microsoft Windows" +and +.Tn "Apple Macintosh" +computers, +this option allows files on file systems +mounted with the +.Cm suiddir +option +to inherit the ownership of its directory, +i.e., +.Dq "if it's my directory, it must be my file." +.El +.Ss Access Control Lists +.Bl -tag -width 2n +.It Cd "options UFS_ACL" +Access control lists allow the association of +fine-grained discretionary access control information +with files and directories. +This option requires the presence of the +.Dv UFS_EXTATTR +option, and it is recommended that +.Dv UFS_EXTATTR_AUTOSTART +is included as well, +so that ACLs are enabled atomically upon mounting the file system. +.El +.Pp +In order to enable support for ACLs, +two extended attributes must be available in the +.Dv EXTATTR_NAMESPACE_SYSTEM +namespace: +.Pa posix1e.acl_access , +which holds the access ACL, +and +.Pa posix1e.acl_default , +which holds the default ACL for directories. +If you are using file system extended attributes, +the following commands may be used to +allocate space for and create the necessary EA backing files +for ACLs in the root of each file system. +In these examples, the root file system is used; +see +.Sx "Extended Attributes" +for more details. +.Bd -literal -offset indent +mkdir -p /.attribute/system +cd /.attribute/system +extattrctl initattr -p / 388 posix1e.acl_access +extattrctl initattr -p / 388 posix1e.acl_default +.Ed +.Pp +On the next mount of the root file system, +the attributes will be automatically started if +.Dv UFS_EXTATTR_AUTOSTART +is included in the kernel configuration, +and ACLs will be enabled. +.Ss Directory Hashing +.Bl -tag -width 2n +.It Cd "options UFS_DIRHASH" +Implements a hash-based lookup scheme for directories +in order to speed up accesses to very large directories. +.El +.Ss Extended Attributes +.Bl -tag -width 2n +.It Cd "options UFS_EXTATTR" +Extended attributes allow the association of +additional arbitrary metadata with files and directories, +which can be assigned and retrieved from userland +as well as from within the kernel; see +.Xr extattrctl 8 . +.It Cd "options UFS_EXTATTR_AUTOSTART" +If this option is defined, +.Nm +will search for a +.Pa .attribute +subdirectory of the file system root during the mount operation. +If found, extended attribute support will be +automatically started for that file system. +.El +.Ss GEOM-based Journaling +.Bl -tag -width 2n +.It Cd "options UFS_GJOURNAL" +Implements a block level journaling of a UFS file system, +which is for both data and metadata. +To enable this, +create a +.Xr gjournal 8 +GEOM provider for a block device by using the +following command: +.Pp +.D1 Nm gjournal label Ar da0 +.Pp +In this example, +.Pa /dev/da0 +is used as the target block device, +and +.Pa /dev/da0.journal +is created. +Then create a new file system by using +.Xr newfs 8 +with the block level journaling flag and mount it: +.Pp +.D1 Nm newfs Fl J Ar /dev/da0.journal +.D1 Nm mount Fl o Cm async Ar /dev/da0.journal Ar /mnt +.Pp +.Cm async +option is not mandatory but recommended for better performance +because the journaling guarantees the consistency of an +.Cm async +mount. +.Pp +It is also possible to enable the block level journaling +on an existing file system. +To do so, +use +.Xr gjournal 8 +utility to label the underlying block device and +.Xr tunefs 8 +utility to enable the block level journaling flag: +.Pp +.D1 Nm gjournal label Ar da0 +.D1 Nm tunefs Fl J Cm enable Ar /dev/da0.journal +.D1 Nm mount Fl o Cm async Ar /dev/da0.journal Ar /mnt +.El +.Ss Xr sysctl 8 MIBs +The following +.Xr sysctl 8 +MIBs are defined for use with +.Nm : +.Bl -hang -width ".Va vfs.ffs.doreallocblk" +.It Va vfs.ffs.doasyncfree +Asynchronously write out modified i-node and indirect blocks +upon reallocating file system blocks to be contiguous. +.Pq Default: 1 . +.It Va vfs.ffs.doreallocblks +Enable support for the rearrangement of blocks +to be contiguous. +.Pq Default: 1 . +.It Va vfs.ffs.prttimechgs +Print a console message when timestamps for UFS1 filesystems are found +to be in the future and are changed to be the present time. +.Pq Default: 0 . +.El +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 4.5 . +.Sh SEE ALSO +.Xr quota 1 , +.Xr acl 3 , +.Xr extattr 3 , +.Xr edquota 8 , +.Xr extattrctl 8 , +.Xr fsck_ffs 8 , +.Xr sysctl 8 , +.Xr tunefs 8 +.Rs +.%A M. McKusick +.%A W. Joy +.%A S. Leffler +.%A R. Fabry +.%D August 1984 +.%T "A Fast File System for UNIX" +.%J "ACM Transactions on Computer Systems" +.%N 2 +.%V 3 +.%P 181-197 +.Re +.Rs +.%A M. McKusick +.%D June 2000 +.%T "Soft Updates: A Technique for Eliminating Most Synchronous Writes in the Fast Filesystem" +.%J "Proceedings of the Freenix Track at the 1999 Usenix Annual Technical Conference" +.%P 71-84 +.Re +.Rs +.%A M. McKusick +.%A J. Roberson +.%D May 2010 +.%T "Journaled Soft-updates" +.%J "BSD Canada Conference 2010 (BSDCan)" +.Re diff --git a/static/freebsd/man4/filemon.4 b/static/freebsd/man4/filemon.4 new file mode 100644 index 00000000..34cb322d --- /dev/null +++ b/static/freebsd/man4/filemon.4 @@ -0,0 +1,252 @@ +.\" Copyright (c) 2012 +.\" David E. O'Brien . All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgment: +.\" This product includes software developed by David E. O'Brien and +.\" contributors. +.\" 4. Neither the name of the author nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" 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 MERCHANT ABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 19, 2025 +.Dt FILEMON 4 +.Os +.Sh NAME +.Nm filemon +.Nd the filemon device +.Sh SYNOPSIS +.Cd device filemon +.Pp +.In dev/filemon/filemon.h +.Sh DESCRIPTION +The +.Nm +device allows a process to collect file operations data of its children. +The device +.Pa /dev/filemon +responds to two +.Xr ioctl 2 +calls. +.Pp +.Nm +is not intended to be a security auditing tool. +Many system calls are not tracked and binaries using a non-native ABI may not +be fully audited. +It is intended for auditing of processes for the purpose of determining their +dependencies using an efficient and easily parsable format. +An example of this is +.Xr make 1 +which uses this module with +.Sy .MAKE.MODE=meta +to handle incremental builds more smartly. +.Pp +System calls are denoted using the following single letters: +.Pp +.Bl -tag -width indent -compact +.It Ql A +.Xr openat 2 . +The next log entry may be lacking an absolute path or be inaccurate. +.It Ql C +.Xr chdir 2 +.It Ql D +.Xr unlink 2 +.It Ql E +.Xr execve 2 +.It Ql F +.Xr fork 2 , +.Xr vfork 2 +.It Ql L +.Xr link 2 , +.Xr linkat 2 , +.Xr symlink 2 +.It Ql M +.Xr rename 2 +.It Ql R +.Xr open 2 +or +.Xr openat 2 +for read +.It Ql W +.Xr open 2 +or +.Xr openat 2 +for write +.It Ql X +.Xr _exit 2 +.El +.Pp +Note that +.Ql R +following +.Ql W +records can represent a single +.Xr open 2 +for R/W, +or two separate +.Xr open 2 +calls, one for +.Ql R +and one for +.Ql W . +Note that only successful system calls are captured. +.Sh IOCTLS +User mode programs communicate with the +.Nm +driver through a number of ioctls which are described below. +Each takes a single argument. +.Bl -tag -width ".Dv FILEMON_SET_PID" +.It Dv FILEMON_SET_FD +Write the internal tracing buffer to the supplied open file descriptor. +.It Dv FILEMON_SET_PID +Child process ID to trace. +This should normally be done under the control of a parent in the child after +.Xr fork 2 +but before anything else. +See the example below. +.El +.Sh RETURN VALUES +.\" .Rv -std ioctl +The +.Fn ioctl +function returns the value 0 if successful; +otherwise the value \-1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn ioctl +system call +with +.Dv FILEMON_SET_FD +will fail if: +.Bl -tag -width Er +.It Bq Er EEXIST +The +.Nm +handle is already associated with a file descriptor. +.It Bq Er EINVAL +The file descriptor has an invalid type and cannot be used for +tracing. +.It Bq Er EBADF +The file descriptor is invalid or not opened for writing. +.El +.Pp +The +.Fn ioctl +system call +with +.Dv FILEMON_SET_PID +will fail if: +.Bl -tag -width Er +.It Bq Er ESRCH +No process having the specified process ID exists. +.It Bq Er EBUSY +The process ID specified is already being traced and was not the current +process. +.El +.Pp +The +.Fn close +system call on the filemon file descriptor may fail with the errors from +.Xr write 2 +if any error is encountered while writing the log. +It may also fail if: +.Bl -tag -width Er +.It Bq Er EFAULT +An invalid address was used for a traced system call argument, resulting in +no log entry for the system call. +.It Bq Er ENAMETOOLONG +An argument for a traced system call was too long, resulting in +no log entry for the system call. +.El +.Sh FILES +.Bl -tag -width ".Pa /dev/filemon" +.It Pa /dev/filemon +.El +.Sh EXAMPLES +.Bd -literal +#include +#include +#include +#include +#include +#include +#include +#include +#include + +static void +open_filemon(void) +{ + pid_t child, wait_rv; + int fm_fd, fm_log; + + if ((fm_fd = open("/dev/filemon", O_RDWR | O_CLOEXEC)) == -1) + err(1, "open(\e"/dev/filemon\e", O_RDWR)"); + if ((fm_log = open("filemon.out", + O_CREAT | O_WRONLY | O_TRUNC | O_CLOEXEC, DEFFILEMODE)) == -1) + err(1, "open(filemon.out)"); + + if (ioctl(fm_fd, FILEMON_SET_FD, &fm_log) == -1) + err(1, "Cannot set filemon log file descriptor"); + + if ((child = fork()) == 0) { + child = getpid(); + if (ioctl(fm_fd, FILEMON_SET_PID, &child) == -1) + err(1, "Cannot set filemon PID"); + /* Do something here. */ + } else if (child == -1) + err(1, "Cannot fork child"); + else { + while ((wait_rv = wait(&child)) == -1 && + errno == EINTR) + ; + if (wait_rv == -1) + err(1, "cannot wait for child"); + close(fm_fd); + } +} +.Ed +.Pp +Creates a file named +.Pa filemon.out +and configures the +.Nm +device to write the +.Nm +buffer contents to it. +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr ktrace 1 , +.Xr script 1 , +.Xr truss 1 , +.Xr ioctl 2 +.Sh HISTORY +A +.Nm +device appeared in +.Fx 9.1 . +.Sh BUGS +Unloading the module may panic the system, thus requires using +.Ic kldunload -f . diff --git a/static/freebsd/man4/firewire.4 b/static/freebsd/man4/firewire.4 new file mode 100644 index 00000000..99aadb30 --- /dev/null +++ b/static/freebsd/man4/firewire.4 @@ -0,0 +1,130 @@ +.\" Copyright (c) 1998-2002 Katsushi Kobayashi and Hidetoshi Shimokawa +.\" 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 acknowledgement as below: +.\" +.\" This product includes software developed by K. Kobayashi and H. Shimokawa +.\" +.\" 4. 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 January 23, 2025 +.Dt FIREWIRE 4 +.Os +.Sh NAME +.Nm firewire +.Nd IEEE1394 High-performance Serial Bus +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device firewire" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +firewire_load="YES" +.Ed +.Sh DEPRECATION NOTICE +The +.Nm +driver is slated to be removed prior to +.Fx 16.0 . +.Sh DESCRIPTION +.Fx +provides machine-independent bus support and raw drivers for +.Nm +interfaces. +.Pp +The +.Nm +driver consists of two layers: the controller and the +bus layer. +The controller attaches to a physical bus +(like +.Xr pci 4 ) . +The +.Nm +bus attaches to the controller. +Additional drivers can be attached to the bus. +.Pp +Up to 63 devices, including the host itself, can be attached to +a +.Nm +bus. +The root node is dynamically assigned with a PHY device function. +Also, the other +.Nm +bus specific parameters, +e.g., node ID, cycle master, isochronous resource manager and bus +manager, are dynamically assigned, after bus reset is initiated. +On the +.Nm +bus, every device is identified by an EUI 64 address. +.Pp +Debugging over the firewire interface is possible with the +.Xr dcons 4 +driver. +Please see +.Lk https://docs.freebsd.org/en/books/developers-handbook/kerneldebug/#kerneldebug-dcons +for details on how to setup debugging with firewire. +.Sh FILES +.Bl -tag -width "Pa /dev/fwmem0.0" -compact +.It Pa /dev/fw0.0 +.It Pa /dev/fwmem0.0 +.El +.Sh SEE ALSO +.Xr dcons 4 , +.Xr fwe 4 , +.Xr fwip 4 , +.Xr fwohci 4 , +.Xr pci 4 , +.Xr sbp 4 , +.Xr eui64 5 , +.Xr fwcontrol 8 , +.Xr kldload 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 5.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Katsushi Kobayashi +and +.An Hidetoshi Shimokawa +for the +.Fx +project. +.Sh BUGS +See +.Xr fwohci 4 +for security notes. diff --git a/static/freebsd/man4/ftgpio.4 b/static/freebsd/man4/ftgpio.4 new file mode 100644 index 00000000..7a556284 --- /dev/null +++ b/static/freebsd/man4/ftgpio.4 @@ -0,0 +1,54 @@ +.\" Copyright (c) 2022, Stormshield +.\" 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 December 28, 2022 +.Dt FTGPIO 4 +.Os +.Sh NAME +.Nm ftgpio +.Nd GPIO Controller on Fintek Super I/O", +.Sh SYNOPSIS +.Cd "device ftgpio" +.Cd "device gpio" +.Cd "device gpioled" +.Sh DESCRIPTION +The +.Nm +is a driver for the GPIO controller found on Fintek Super I/O chips. +.Sh SEE ALSO +.Xr gpio 3 , +.Xr gpio 4 , +.Xr gpioled 4 , +.Xr superio 4 , +.Xr gpioctl 8 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 14.0 . +.Sh AUTHORS +The +.Nm +driver was partially written by +.An Stéphane Rochoy Aq Mt stéphane.rochoy@stormshield.eu . diff --git a/static/freebsd/man4/ftwd.4 b/static/freebsd/man4/ftwd.4 new file mode 100644 index 00000000..4d157b68 --- /dev/null +++ b/static/freebsd/man4/ftwd.4 @@ -0,0 +1,64 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2012 Bjoern A. Zeeb +.\" Copyright (c) 2019 Andriy Gapon +.\" +.\" 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 November 26, 2020 +.Dt FTWD 4 +.Os +.Sh NAME +.Nm ftwd +.Nd Fintek F81803 watchdog timer +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device superio" +.Cd "device ftwd" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the following +line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ftwd_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides +.Xr watchdog 4 +support for the watchdog timer in the Fintek F81803 chip. +.Sh SEE ALSO +.Xr superio 4 , +.Xr watchdog 4 , +.Xr device.hints 5 , +.Xr watchdog 8 , +.Xr watchdogd 8 , +.Xr watchdog 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org . diff --git a/static/freebsd/man4/full.4 b/static/freebsd/man4/full.4 new file mode 100644 index 00000000..75b0da22 --- /dev/null +++ b/static/freebsd/man4/full.4 @@ -0,0 +1,45 @@ +.\" Copyright (c) 2014 +.\" Eitan Adler . +.\" +.\" 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 May 9, 2021 +.Dt FULL 4 +.Os +.Sh NAME +.Nm full +.Nd the full device +.Sh DESCRIPTION +The +.Nm +device supplies an endless stream of zeros when read. +However, it will always be full when writing to it. +.Sh FILES +.Bl -tag -width /dev/full +.It Pa /dev/full +.El +.Sh SEE ALSO +.Xr null 4 , +.Xr zero 4 +.Sh AUTHORS +This device and man page was written by +.An Eitan Adler Aq Mt eadler@FreeBSD.org . diff --git a/static/freebsd/man4/fusefs.4 b/static/freebsd/man4/fusefs.4 new file mode 100644 index 00000000..33c31f35 --- /dev/null +++ b/static/freebsd/man4/fusefs.4 @@ -0,0 +1,136 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2019 The FreeBSD Foundation +.\" +.\" This documentation was written by BFF Storage Systems, LLC under +.\" sponsorship from the FreeBSD Foundation. +.\" +.\" 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 31, 2019 +.Dt FUSEFS 4 +.Os +.Sh NAME +.Nm fusefs +.Nd "File system in USErspace" +.Sh SYNOPSIS +To link into the kernel: +.Bd -ragged -offset indent +.Cd "options FUSEFS" +.Ed +.Pp +To load as a loadable kernel module: +.Pp +.Dl "kldload fusefs" +.Sh DESCRIPTION +The +.Nm +driver implements a file system that is serviced by a userspace program. +.Pp +There are many uses for +.Nm . +Userspace daemons can access libraries or programming languages that cannot run +in kernel-mode, for example. +.Nm +is also useful for developing and debugging file systems, because a crash of +the daemon will not take down the entire operating system. +Finally, the +.Nm +API is portable. +Many daemons can run on multiple operating systems with minimal modifications. +.Sh SYSCTL VARIABLES +The following +.Xr sysctl 8 +variables are available: +.Bl -tag -width indent +.It Va vfs.fusefs.kernelabi_major +Major version of the FUSE kernel ABI supported by this driver. +.It Va vfs.fusefs.kernelabi_minor +Minor version of the FUSE kernel ABI supported by this driver. +.It Va vfs.fusefs.data_cache_mode +Controls how +.Nm +will cache file data for pre-7.23 file systems. +A value of 0 will disable caching entirely. +Every data access will be forwarded to the daemon. +A value of 1 will select write-through caching. +Reads will be cached in the VFS layer as usual. +Writes will be immediately forwarded to the daemon, and also added to the cache. +A value of 2 will select write-back caching. +Reads and writes will both be cached, and writes will occasionally be flushed +to the daemon by the page daemon. +Write-back caching is usually unsafe, especially for FUSE file systems that +require network access. +.Pp +FUSE file systems using protocol 7.23 or later specify their cache behavior +on a per-mountpoint basis, ignoring this sysctl. +.It Va vfs.fusefs.stats.filehandle_count +Current number of open FUSE file handles. +.It Va vfs.fusefs.stats.lookup_cache_hits +Total number of lookup cache hits. +.It Va vfs.fusefs.stats.lookup_cache_misses +Total number of lookup cache misses. +.It Va vfs.fusefs.stats.node_count +Current number of allocated FUSE vnodes. +.It Va vfs.fusefs.stats.ticket_count +Current number of allocated FUSE tickets, which is roughly equal to the number +of FUSE operations currently being processed by daemons. +.\" Undocumented sysctls +.\" ==================== +.\" vfs.fusefs.enforce_dev_perms: I don't understand it well enough. +.\" vfs.fusefs.iov_credit: I don't understand it well enough +.\" vfs.fusefs.iov_permanent_bufsize: I don't understand it well enough +.El +.Sh SEE ALSO +.Xr mount_fusefs 8 +.Sh HISTORY +The +.Nm fuse +driver was written as the part of the +.Fx +implementation of the FUSE userspace file system framework (see +.Lk https://github.com/libfuse/libfuse ) +and first appeared in the +.Pa sysutils/fusefs-kmod +port, supporting +.Fx 6.0 . +It was added to the base system in +.Fx 10.0 , +and renamed to +.Nm +for +.Fx 12.1 . +.Sh AUTHORS +.An -nosplit +The +.Nm fuse +driver was originally written by +.An Csaba Henk +as a Google Summer of Code project in 2005. +It was further developed by +.An Ilya Putsikau +during Google Summer of Code 2011, and that version was integrated into the +base system by +.An Attilio Rao Aq Mt attilio@FreeBSD.org . +.Pp +This manual page was written by +.An Alan Somers Aq Mt asomers@FreeBSD.org . diff --git a/static/freebsd/man4/fwe.4 b/static/freebsd/man4/fwe.4 new file mode 100644 index 00000000..68d92595 --- /dev/null +++ b/static/freebsd/man4/fwe.4 @@ -0,0 +1,94 @@ +.\" Copyright (c) 2002 Hidetoshi Shimokawa +.\" 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 ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +.\" DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, +.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN +.\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.Dd July 16, 2005 +.Dt FWE 4 +.Os +.Sh NAME +.Nm fwe +.Nd "Ethernet emulation driver for FireWire" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device firewire" +.Cd "device fwe" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_fwe_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides non-standard Ethernet emulation over FireWire (IEEE 1394). +.Pp +.Xr firewire 4 +and +.Xr fwohci 4 +must be configured in the kernel as well. +.Pp +This driver exploits asynchronous stream over IEEE 1394 to carry Ethernet +frames. +The stream channel can be specified by +the +.Va hw.firewire.fwe.stream_ch +.Xr sysctl 8 . +.Pp +This driver supports +.Xr polling 4 +as well if it is compiled with the +.Dv DEVICE_POLLING +option. +.Sh SEE ALSO +.Xr arp 4 , +.Xr firewire 4 , +.Xr fwip 4 , +.Xr fwohci 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr polling 4 , +.Xr ifconfig 8 , +.Xr kldload 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 5.0 . +.Sh AUTHORS +The +.Nm +driver and this manual page were written by +.An Hidetoshi Shimokawa . +.Sh BUGS +This driver emulates Ethernet in a very adhoc way and it does not reserve a +stream channel using an isochronous manager. +Note that this driver uses a protocol which is very different from RFC 2734 +(IPv4 over IEEE 1394). diff --git a/static/freebsd/man4/fwip.4 b/static/freebsd/man4/fwip.4 new file mode 100644 index 00000000..fdd01f1b --- /dev/null +++ b/static/freebsd/man4/fwip.4 @@ -0,0 +1,93 @@ +.\" Copyright (c) 2004 Doug Rabson +.\" Copyright (c) 2002 Hidetoshi Shimokawa +.\" 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 ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +.\" DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, +.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN +.\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 16, 2005 +.Dt FWIP 4 +.Os +.Sh NAME +.Nm fwip +.Nd "IP over FireWire driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device firewire" +.Cd "device fwip" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +firewire_load="YES" +if_fwip_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides standard IP over FireWire (IEEE 1394) based on the +protocols described in RFC 2734 and RFC 3146. +.Pp +The +.Xr firewire 4 +and +.Xr fwohci 4 +drivers +must be configured in the kernel as well. +.Pp +This driver supports +.Xr polling 4 +as well if it is compiled with the +.Dv DEVICE_POLLING +option. +.Sh SEE ALSO +.Xr arp 4 , +.Xr firewire 4 , +.Xr fwe 4 , +.Xr fwohci 4 , +.Xr netintro 4 , +.Xr polling 4 , +.Xr ifconfig 8 , +.Xr kldload 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 5.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver and this manual page were written by +.An Doug Rabson , +based on earlier work by +.An Hidetoshi Shimokawa . +.Sh BUGS +This driver currently does not support the MCAP protocol for multicast +IP over FireWire. +Multicast packets are treated as broadcast packets which is sufficient +for most trivial uses of multicast. diff --git a/static/freebsd/man4/fwohci.4 b/static/freebsd/man4/fwohci.4 new file mode 100644 index 00000000..ec14ddfd --- /dev/null +++ b/static/freebsd/man4/fwohci.4 @@ -0,0 +1,154 @@ +.\" Copyright (c) 1998,1999,2000 Katsushi Kobayashi and Hidetoshi Shimokawa +.\" 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 acknowledgement as below: +.\" +.\" This product includes software developed by K. Kobayashi and H. Shimokawa +.\" +.\" 4. 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 December 24, 2020 +.Dt FWOHCI 4 +.Os +.Sh NAME +.Nm fwohci +.Nd OHCI FireWire chipset device driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device firewire" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +firewire_load="YES" +.Ed +.Pp +To disable physical access (see +.Sx BUGS +section for detail), put the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hw.firewire.phydma_enable=0 +.Ed +.Sh HARDWARE +The +.Nm +driver provides support for PCI/CardBus FireWire interface cards. +The driver supports the following IEEE 1394 OHCI chipsets: +.Pp +.Bl -bullet -compact +.It +Adaptec AHA-894x/AIC-5800 +.It +Apple Pangea +.It +Apple UniNorth +.It +Intel 82372FB +.It +IOGEAR GUF320 +.It +Lucent / Agere FW322/323 +.It +NEC uPD72861 +.It +NEC uPD72870 +.It +NEC uPD72871/2 +.It +NEC uPD72873 +.It +NEC uPD72874 +.It +National Semiconductor CS4210 +.It +Ricoh R5C551 +.It +Ricoh R5C552 +.It +Sony CX3022 +.It +Sony i.LINK (CXD3222) +.It +Texas Instruments PCI4410A +.It +Texas Instruments PCI4450 +.It +Texas Instruments PCI4451 +.It +Texas Instruments TSB12LV22 +.It +Texas Instruments TSB12LV23 +.It +Texas Instruments TSB12LV26 +.It +Texas Instruments TSB43AA22 +.It +Texas Instruments TSB43AB21/A/AI/A-EP +.It +Texas Instruments TSB43AB22/A +.It +Texas Instruments TSB43AB23 +.It +Texas Instruments TSB82AA2 +.It +VIA Fire II (VT6306) +.El +.Sh SEE ALSO +.Xr firewire 4 , +.Xr fwe 4 , +.Xr fwip 4 , +.Xr sbp 4 , +.Xr fwcontrol 8 , +.Xr kldload 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 5.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +device driver was written by +.An Katsushi Kobayashi +and +.An Hidetoshi Shimokawa . +.Sh BUGS +The driver allows physical access from any nodes on the bus by default. +This means that any devices on the bus can read and modify any memory space +which can be accessed by an IEEE 1394 OHCI chip. +It is allowed mostly for +.Xr sbp 4 +devices. +This should be changed to allow it only for specific devices. +Anyway, FireWire is a bus and not expected to be connected with +un-trustable devices because a node can monitor all the traffic. diff --git a/static/freebsd/man4/fxp.4 b/static/freebsd/man4/fxp.4 new file mode 100644 index 00000000..6eae3996 --- /dev/null +++ b/static/freebsd/man4/fxp.4 @@ -0,0 +1,212 @@ +.\" +.\" Copyright (c) 1997 David E. O'Brien +.\" +.\" 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 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 November 26, 2010 +.Dt FXP 4 +.Os +.Sh NAME +.Nm fxp +.Nd "Intel EtherExpress PRO/100 Ethernet device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device fxp" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_fxp_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for Ethernet adapters based on the Intel +i82557, i82558, i82559, i82550, and i82562 chips. +The driver supports TCP/UDP/IP checksum offload for both transmit +and receive on i82550 and i82551. +On i82559 only TCP/UDP checksum offload for receive is supported. +TCP segmentation offload (TSO) for IPv4 as well as VLAN hardware +tag insertion/stripping is supported on i82550 and i82551. +Wake On Lan (WOL) support is provided on all controllers +except i82557, i82259ER and early i82558 revisions. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width "10baseT/UTP" +.It Cm autoselect +Enable autoselection of the media type and options. +The autoselected mode can be overridden by adding the media options to +.Xr rc.conf 5 . +.It Cm 10baseT/UTP +Set 10Mbps operation. +.It Cm 100baseTX +Set 100Mbps (Fast Ethernet) operation. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width "full-duplex" +.It Cm full-duplex +Force full duplex operation. +.It Cm half-duplex +Force half duplex operation. +.El +.Pp +Note that 100baseTX media type is not available on the Pro/10. +For further information on configuring this device, see +.Xr ifconfig 8 . +.Pp +The +.Nm +driver supports reception and transmission of extended frames +for +.Xr vlan 4 . +This capability of +.Nm +can be controlled by means of the +.Cm vlanmtu +parameter +to +.Xr ifconfig 8 . +.Pp +The +.Nm +driver also supports a special link option: +.Bl -tag -width link0 +.It Cm link0 +Some chip revisions have loadable microcode which can be used to reduce the +interrupt load on the host cpu. +Not all boards have microcode support. +Setting the +.Cm link0 +flag with +.Xr ifconfig 8 +will download the microcode to the chip if it is available. +.El +.Sh HARDWARE +Adapters supported by the +.Nm +driver include: +.Pp +.Bl -bullet -compact +.It +Intel EtherExpress PRO/10 +.It +Intel InBusiness 10/100 +.It +Intel PRO/100B / EtherExpressPRO/100 B PCI Adapter +.It +Intel PRO/100+ Management Adapter +.It +Intel PRO/100 VE Desktop Adapter +.It +Intel PRO/100 VM Network Connection +.It +Intel PRO/100 M Desktop Adapter +.It +Intel PRO/100 S Desktop, Server and Dual-Port Server Adapters +.It +Many on-board network interfaces on Intel motherboards +.El +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +The following variables are available as both +.Xr loader 8 +tunables and +.Xr sysctl 8 +variables: +.Bl -tag -width "xxxxxx" +.It Va dev.fxp.%d.int_delay +Maximum amount of time, in microseconds, that an interrupt may +be delayed in an attempt to coalesce interrupts. +This is only effective if the Intel microcode is loaded. +The accepted range is 300 to 3000, the default is 1000. +.It Va dev.fxp.%d.bundle_max +Number of packets that will be bundled, before an interrupt is +generated. +This is only effective if the Intel microcode is loaded. +The accepted range is 1 to 65535, the default is 6. +.El +.Sh SYSCTL VARIABLES +The following variables are available as +.Xr sysctl 8 +variables. +.Bl -tag -width "xxxxxx" +.It Va dev.fxp.%d.rnr +This is a read-only variable and shows the number of events of +RNR (resource not ready). +.It Va dev.fxp.%d.stats +This is a read-only variable and displays useful MAC counters +maintained in the driver. +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "fxp%d: couldn't map memory" +A fatal initialization error has occurred. +.It "fxp%d: couldn't map interrupt" +A fatal initialization error has occurred. +.It "fxp%d: Failed to malloc memory" +There are not enough mbuf's available for allocation. +.It "fxp%d: device timeout" +The device has stopped responding to the network, or there is a problem with +the network connection (cable). +.It "fxp%d: Microcode loaded, int_delay: %d usec bundle_max: %d" +The chip has successfully downloaded the microcode, and changed the +parameterized values to the given settings. +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr polling 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 2.1 . +.Sh AUTHORS +.An -nosplit +The +.Nm +device driver was written by +.An David Greenman . +It has then been updated to use the busdma API and made endian-clean by +.An Maxime Henrion . +This manual page was written by +.An David E. O'Brien . diff --git a/static/freebsd/man4/gdb.4 b/static/freebsd/man4/gdb.4 new file mode 100644 index 00000000..2b18be2d --- /dev/null +++ b/static/freebsd/man4/gdb.4 @@ -0,0 +1,601 @@ +.\" Copyright (c) 2003 Greg Lehey +.\" 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 May 17, 2016 +.Dt GDB 4 +.Os +.Sh NAME +.Nm gdb +.Nd external kernel debugger +.Sh SYNOPSIS +.Cd "makeoptions DEBUG=-g" +.Cd "options DDB" +.Sh DESCRIPTION +The +.Nm +kernel debugger is a variation of +.Xr gdb 1 Pq Pa ports/devel/gdb +which understands some aspects of the +.Fx +kernel environment. +It can be used in a number of ways: +.Bl -bullet +.It +It can be used to examine the memory of the processor on which it runs. +.It +It can be used to analyse a processor dump after a panic. +.It +It can be used to debug another system interactively via a serial or firewire +link. +In this mode, the processor can be stopped and single stepped. +.It +With a firewire link, it can be used to examine the memory of a remote system +without the participation of that system. +In this mode, the processor cannot be stopped and single stepped, but it can be +of use when the remote system has crashed and is no longer responding. +.El +.Pp +When used for remote debugging, +.Nm +requires the presence of the +.Xr ddb 4 +kernel debugger. +Commands exist to switch between +.Nm +and +.Xr ddb 4 . +.Sh PREPARING FOR DEBUGGING +When debugging kernels, it is practically essential to have built a kernel with +debugging symbols +.Pq Cd "makeoptions DEBUG=-g" . +It is easiest to perform operations from the kernel build directory, by default +.Pa /usr/obj/usr/src/sys/GENERIC . +.Pp +First, ensure you have a copy of the debug macros in the directory: +.Pp +.Dl "make gdbinit" +.Pp +This command performs some transformations on the macros installed in +.Pa /usr/src/tools/debugscripts +to adapt them to the local environment. +.Ss "Inspecting the environment of the local machine" +To look at and change the contents of the memory of the system you are running +on, +.Pp +.Dl "gdb -k -wcore kernel.debug /dev/mem" +.Pp +In this mode, you need the +.Fl k +flag to indicate to +.Xr gdb 1 Pq Pa ports/devel/gdb +that the +.Dq "dump file" +.Pa /dev/mem +is a kernel data file. +You can look at live data, and if you include the +.Fl wcore +option, you can change it at your peril. +The system does not stop (obviously), so a number of things will not work. +You can set breakpoints, but you cannot +.Dq continue +execution, so they will not work. +.Ss "Debugging a crash dump" +By default, crash dumps are stored in the directory +.Pa /var/crash . +Investigate them from the kernel build directory with: +.Pp +.Dl "gdb -k kernel.debug /var/crash/vmcore.29" +.Pp +In this mode, the system is obviously stopped, so you can only look at it. +.Ss "Debugging a live system with a remote link" +In the following discussion, the term +.Dq "local system" +refers to the system running the debugger, and +.Dq "remote system" +refers to the live system being debugged. +.Pp +To debug a live system with a remote link, the kernel must be compiled with the +option +.Cd "options DDB" . +The option +.Cd "options BREAK_TO_DEBUGGER" +enables the debugging machine stop the debugged machine once a connection has +been established by pressing +.Ql ^C . +.Ss "Debugging a live system with a remote serial link" +When using a serial port for the remote link on the i386 platform, the serial +port must be identified by setting the flag bit +.Li 0x80 +for the specified interface. +Generally, this port will also be used as a serial console (flag bit +.Li 0x10 ) , +so the entry in +.Pa /boot/device.hints +should be: +.Pp +.Dl hint.sio.0.flags="0x90" +.Ss "Debugging a live system with a remote firewire link" +As with serial debugging, to debug a live system with a firewire link, the +kernel must be compiled with the option +.Cd "options DDB" . +.Pp +A number of steps must be performed to set up a firewire link: +.Bl -bullet +.It +Ensure that both systems have +.Xr firewire 4 +support, and that the kernel of the remote system includes the +.Xr dcons 4 +and +.Xr dcons_crom 4 +drivers. +If they are not compiled into the kernel, load the KLDs: +.Pp +.Dl "kldload firewire" +.Pp +On the remote system only: +.Bd -literal -offset indent +kldload dcons +kldload dcons_crom +.Ed +.Pp +You should see something like this in the +.Xr dmesg 8 +output of the remote system: +.Bd -literal -offset indent +fwohci0: BUS reset +fwohci0: node_id=0x8800ffc0, gen=2, non CYCLEMASTER mode +firewire0: 2 nodes, maxhop <= 1, cable IRM = 1 +firewire0: bus manager 1 +firewire0: New S400 device ID:00c04f3226e88061 +dcons_crom0: on firewire0 +dcons_crom0: bus_addr 0x22a000 +.Ed +.Pp +It is a good idea to load these modules at boot time with the following entry in +.Pa /boot/loader.conf : +.Pp +.Dl dcons_crom_enable="YES" +.Pp +This ensures that all three modules are loaded. +There is no harm in loading +.Xr dcons 4 +and +.Xr dcons_crom 4 +on the local system, but if you only want to load the +.Xr firewire 4 +module, include the following in +.Pa /boot/loader.conf : +.Pp +.Dl firewire_enable="YES" +.It +Next, use +.Xr fwcontrol 8 +to find the firewire node corresponding to the remote machine. +On the local machine you might see: +.Bd -literal -offset indent +# fwcontrol +2 devices (info_len=2) +node EUI64 status + 1 0x00c04f3226e88061 0 + 0 0x000199000003622b 1 +.Ed +.Pp +The first node is always the local system, so in this case, node 0 is the remote +system. +If there are more than two systems, check from the other end to find which node +corresponds to the remote system. +On the remote machine, it looks like this: +.Bd -literal -offset indent +# fwcontrol +2 devices (info_len=2) +node EUI64 status + 0 0x000199000003622b 0 + 1 0x00c04f3226e88061 1 +.Ed +.It +Next, establish a firewire connection with +.Xr dconschat 8 : +.Pp +.Dl "dconschat -br -G 5556 -t 0x000199000003622b" +.Pp +.Li 0x000199000003622b +is the EUI64 address of the remote node, as determined from the output of +.Xr fwcontrol 8 +above. +When started in this manner, +.Xr dconschat 8 +establishes a local tunnel connection from port +.Li localhost:5556 +to the remote debugger. +You can also establish a console port connection with the +.Fl C +option to the same invocation +.Xr dconschat 8 . +See the +.Xr dconschat 8 +manpage for further details. +.Pp +The +.Xr dconschat 8 +utility +does not return control to the user. +It displays error messages and console output for the remote system, so it is a +good idea to start it in its own window. +.It +Finally, establish connection: +.Bd -literal -offset indent +# gdb kernel.debug +GNU gdb 5.2.1 (FreeBSD) +.Em "(political statements omitted)" +Ready to go. Enter 'tr' to connect to the remote target +with /dev/cuau0, 'tr /dev/cuau1' to connect to a different port +or 'trf portno' to connect to the remote target with the firewire +interface. portno defaults to 5556. + +Type 'getsyms' after connection to load kld symbols. + +If you are debugging a local system, you can use 'kldsyms' instead +to load the kld symbols. That is a less obnoxious interface. +(gdb) trf +0xc21bd378 in ?? () +.Ed +.Pp +The +.Ic trf +macro assumes a connection on port 5556. +If you want to use a different port (by changing the invocation of +.Xr dconschat 8 +above), use the +.Ic tr +macro instead. +For example, if you want to use port 4711, run +.Xr dconschat 8 +like this: +.Pp +.Dl "dconschat -br -G 4711 -t 0x000199000003622b" +.Pp +Then establish connection with: +.Bd -literal -offset indent +(gdb) tr localhost:4711 +0xc21bd378 in ?? () +.Ed +.El +.Ss "Non-cooperative debugging a live system with a remote firewire link" +In addition to the conventional debugging via firewire described in the previous +section, it is possible to debug a remote system without its cooperation, once +an initial connection has been established. +This corresponds to debugging a local machine using +.Pa /dev/mem . +It can be very useful if a system crashes and the debugger no longer responds. +To use this method, set the +.Xr sysctl 8 +variables +.Va hw.firewire.fwmem.eui64_hi +and +.Va hw.firewire.fwmem.eui64_lo +to the upper and lower halves of the EUI64 ID of the remote system, +respectively. +From the previous example, the remote machine shows: +.Bd -literal -offset indent +# fwcontrol +2 devices (info_len=2) +node EUI64 status + 0 0x000199000003622b 0 + 1 0x00c04f3226e88061 1 +.Ed +.Pp +Enter: +.Bd -literal -offset indent +# sysctl -w hw.firewire.fwmem.eui64_hi=0x00019900 +hw.firewire.fwmem.eui64_hi: 0 -> 104704 +# sysctl -w hw.firewire.fwmem.eui64_lo=0x0003622b +hw.firewire.fwmem.eui64_lo: 0 -> 221739 +.Ed +.Pp +Note that the variables must be explicitly stated in hexadecimal. +After this, you can examine the remote machine's state with the following input: +.Bd -literal -offset indent +# gdb -k kernel.debug /dev/fwmem0.0 +GNU gdb 5.2.1 (FreeBSD) +.Em "(messages omitted)" +Reading symbols from /boot/kernel/dcons.ko...done. +Loaded symbols for /boot/kernel/dcons.ko +Reading symbols from /boot/kernel/dcons_crom.ko...done. +Loaded symbols for /boot/kernel/dcons_crom.ko +#0 sched_switch (td=0xc0922fe0) at /usr/src/sys/kern/sched_4bsd.c:621 +0xc21bd378 in ?? () +.Ed +.Pp +In this case, it is not necessary to load the symbols explicitly. +The remote system continues to run. +.Sh COMMANDS +The user interface to +.Nm +is via +.Xr gdb 1 Pq Pa ports/devel/gdb , +so +.Xr gdb 1 Pq Pa ports/devel/gdb +commands also work. +This section discusses only the extensions for kernel debugging that get +installed in the kernel build directory. +.Ss "Debugging environment" +The following macros manipulate the debugging environment: +.Bl -tag -width indent +.It Ic ddb +Switch back to +.Xr ddb 4 . +This command is only meaningful when performing remote debugging. +.It Ic getsyms +Display +.Ic kldstat +information for the target machine and invite user to paste it back in. +This is required because +.Nm +does not allow data to be passed to shell scripts. +It is necessary for remote debugging and crash dumps; for local memory debugging +use +.Ic kldsyms +instead. +.It Ic kldsyms +Read in the symbol tables for the debugging machine. +This does not work for +remote debugging and crash dumps; use +.Ic getsyms +instead. +.It Ic tr Ar interface +Debug a remote system via the specified serial or firewire interface. +.It Ic tr0 +Debug a remote system via serial interface +.Pa /dev/cuau0 . +.It Ic tr1 +Debug a remote system via serial interface +.Pa /dev/cuau1 . +.It Ic trf +Debug a remote system via firewire interface at default port 5556. +.El +.Pp +The commands +.Ic tr0 , tr1 +and +.Ic trf +are convenience commands which invoke +.Ic tr . +.Ss "The current process environment" +The following macros are convenience functions intended to make things easier +than the standard +.Xr gdb 1 Pq Pa ports/devel/gdb +commands. +.Bl -tag -width indent +.It Ic f0 +Select stack frame 0 and show assembler-level details. +.It Ic f1 +Select stack frame 1 and show assembler-level details. +.It Ic f2 +Select stack frame 2 and show assembler-level details. +.It Ic f3 +Select stack frame 3 and show assembler-level details. +.It Ic f4 +Select stack frame 4 and show assembler-level details. +.It Ic f5 +Select stack frame 5 and show assembler-level details. +.It Ic xb +Show 12 words in hex, starting at current +.Va ebp +value. +.It Ic xi +List the next 10 instructions from the current +.Va eip +value. +.It Ic xp +Show the register contents and the first four parameters of the current stack +frame. +.It Ic xp0 +Show the first parameter of current stack frame in various formats. +.It Ic xp1 +Show the second parameter of current stack frame in various formats. +.It Ic xp2 +Show the third parameter of current stack frame in various formats. +.It Ic xp3 +Show the fourth parameter of current stack frame in various formats. +.It Ic xp4 +Show the fifth parameter of current stack frame in various formats. +.It Ic xs +Show the last 12 words on stack in hexadecimal. +.It Ic xxp +Show the register contents and the first ten parameters. +.It Ic z +Single step 1 instruction (over calls) and show next instruction. +.It Ic zs +Single step 1 instruction (through calls) and show next instruction. +.El +.Ss "Examining other processes" +The following macros access other processes. +The +.Nm +debugger +does not understand the concept of multiple processes, so they effectively +bypass the entire +.Nm +environment. +.Bl -tag -width indent +.It Ic btp Ar pid +Show a backtrace for the process +.Ar pid . +.It Ic btpa +Show backtraces for all processes in the system. +.It Ic btpp +Show a backtrace for the process previously selected with +.Ic defproc . +.It Ic btr Ar ebp +Show a backtrace from the +.Ar ebp +address specified. +.It Ic defproc Ar pid +Specify the PID of the process for some other commands in this section. +.It Ic fr Ar frame +Show frame +.Ar frame +of the stack of the process previously selected with +.Ic defproc . +.It Ic pcb Ar proc +Show some PCB contents of the process +.Ar proc . +.El +.Ss "Examining data structures" +You can use standard +.Xr gdb 1 Pq Pa ports/devel/gdb +commands to look at most data structures. +The macros in this section are +convenience functions which typically display the data in a more readable +format, or which omit less interesting parts of the structure. +.Bl -tag -width indent +.It Ic bp +Show information about the buffer header pointed to by the variable +.Va bp +in the current frame. +.It Ic bpd +Show the contents +.Pq Vt "char *" +of +.Va bp->data +in the current frame. +.It Ic bpl +Show detailed information about the buffer header +.Pq Vt "struct bp" +pointed at by the local variable +.Va bp . +.It Ic bpp Ar bp +Show summary information about the buffer header +.Pq Vt "struct bp" +pointed at by the parameter +.Ar bp . +.It Ic bx +Print a number of fields from the buffer header pointed at in by the pointer +.Ar bp +in the current environment. +.It Ic vdev +Show some information of the +.Vt vnode +pointed to by the local variable +.Va vp . +.El +.Ss "Miscellaneous macros" +.Bl -tag -width indent +.It Ic checkmem +Check unallocated memory for modifications. +This assumes that the kernel has been compiled with +.Cd "options DIAGNOSTIC" . +This causes the contents of free memory to be set to +.Li 0xdeadc0de . +.It Ic dmesg +Print the system message buffer. +This corresponds to the +.Xr dmesg 8 +utility. +This macro used to be called +.Ic msgbuf . +It can take a very long time over a serial line, +and it is even slower via firewire +or local memory due to inefficiencies in +.Nm . +When debugging a crash dump or over firewire, it is not necessary to start +.Nm +to access the message buffer: instead, use an appropriate variation of +.Bd -literal -offset indent +dmesg -M /var/crash/vmcore.0 -N kernel.debug +dmesg -M /dev/fwmem0.0 -N kernel.debug +.Ed +.It Ic kldstat +Equivalent of the +.Xr kldstat 8 +utility without options. +.It Ic pname +Print the command name of the current process. +.It Ic ps +Show process status. +This corresponds in concept, but not in appearance, to the +.Xr ps 1 +utility. +When debugging a crash dump or over firewire, it is not necessary to start +.Nm +to display the +.Xr ps 1 +output: instead, use an appropriate variation of +.Bd -literal -offset indent +ps -M /var/crash/vmcore.0 -N kernel.debug +ps -M /dev/fwmem0.0 -N kernel.debug +.Ed +.It Ic y +Kludge for writing macros. +When writing macros, it is convenient to paste them +back into the +.Nm +window. +Unfortunately, if the macro is already defined, +.Nm +insists on asking +.Pp +.Dl "Redefine foo?" +.Pp +It will not give up until you answer +.Ql y . +This command is that answer. +It does nothing else except to print a warning +message to remind you to remove it again. +.El +.Sh SEE ALSO +.Xr gdb 1 Pq Pa ports/devel/gdb , +.Xr ps 1 , +.Xr ddb 4 , +.Xr firewire 4 , +.Xr dconschat 8 , +.Xr dmesg 8 , +.Xr fwcontrol 8 , +.Xr kldload 8 +.Sh AUTHORS +This man page was written by +.An Greg Lehey Aq Mt grog@FreeBSD.org . +.Sh BUGS +The +.Xr gdb 1 Pq Pa ports/devel/gdb +debugger +was never designed to debug kernels, and it is not a very good match. +Many problems exist. +.Pp +The +.Nm +implementation is very inefficient, and many operations are slow. +.Pp +Serial debugging is even slower, and race conditions can make it difficult to +run the link at more than 9600 bps. +Firewire connections do not have this problem. +.Pp +The debugging macros +.Dq just grew. +In general, the person who wrote them did so while looking for a specific +problem, so they may not be general enough, and they may behave badly when used +in ways for which they were not intended, even if those ways make sense. +.Pp +Many of these commands only work on the ia32 architecture. diff --git a/static/freebsd/man4/gem.4 b/static/freebsd/man4/gem.4 new file mode 100644 index 00000000..62a8c7b1 --- /dev/null +++ b/static/freebsd/man4/gem.4 @@ -0,0 +1,112 @@ +.\" $NetBSD: gem.4,v 1.2 2003/02/14 15:20:18 grant Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 18, 2023 +.Dt GEM 4 +.Os +.Sh NAME +.Nm gem +.Nd GEM/GMAC Ethernet device driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device gem" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_gem_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the GMAC Ethernet hardware found mostly in +the last Apple PowerBooks G3s and most G4-based Apple hardware. +.Pp +All controllers supported by the +.Nm +driver have TCP checksum offload capability for both receive and transmit, +support for the reception and transmission of extended frames for +.Xr vlan 4 +and a 512-bit multicast hash filter. +.Sh HARDWARE +Chips supported by the +.Nm +driver include: +.Pp +.Bl -bullet -compact +.It +Apple GMAC +.It +Sun GEM Gigabit Ethernet +.El +.Pp +The +following add-on cards are known to work with the +.Nm +driver at this time: +.Pp +.Bl -bullet -compact +.It +Sun Gigabit Ethernet PCI 2.0/3.0 (GBE/P) +(part no.\& 501-4373) +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver appeared in +.Nx 1.6 . +The first +.Fx +version to include it was +.Fx 5.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written for +.Nx +by +.An Eduardo Horvath Aq Mt eeh@NetBSD.org . +It was ported to +.Fx +by +.An Thomas Moestl Aq Mt tmm@FreeBSD.org +and later on improved by +.An Marius Strobl Aq Mt marius@FreeBSD.org . +The man page was written by +.An Thomas Klausner Aq Mt wiz@NetBSD.org . diff --git a/static/freebsd/man4/genet.4 b/static/freebsd/man4/genet.4 new file mode 100644 index 00000000..1de92294 --- /dev/null +++ b/static/freebsd/man4/genet.4 @@ -0,0 +1,184 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2021 Michael J. Karels +.\" +.\" 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 December 8, 2021 +.Dt GENET 4 aarch64 +.Os +.Sh NAME +.Nm genet +.Nd "Raspberry Pi 4 / BCM2711 Gigabit Ethernet controller driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in the +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device genet" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports the BCM2711 Ethernet controller +as found on the Raspberry Pi 4. +.Pp +The following features are supported in the +.Nm +driver in +.Fx : +.Pp +.Bl -item -offset indent -compact +.It +IP/TCP/UDP checksum offload for IPv4 and IPv6 +.It +10/100/1000Mbps operation in full-duplex mode +.It +10/100Mbps operation in half-duplex mode +.El +.Pp +Note that the operation of transmit checksum offload is coupled +for IPv4 and IPv6; to disable it, both must be disabled even if both +address families are not in use. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width ".Cm 10baseT/UTP" +.It Cm autoselect +Enable autoselection of the media type and options. +The user can manually override +the autoselected mode by adding media options to +.Xr rc.conf 5 . +.It Cm 10baseT/UTP +Set 10Mbps operation. +The +.Xr ifconfig 8 +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 100baseTX +Set 100Mbps (Fast Ethernet) operation. +The +.Xr ifconfig 8 +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 1000baseT +Set 1000baseT operation over twisted pair. +Only +.Cm full-duplex +mode is supported. +.El +.Pp +The +.Nm +driver supports the following media options set with the +.Cm mediaopt +option to the +.Xr ifconfig 8 +command: +.Bl -tag -width ".Cm full-duplex" +.It Cm full-duplex +Force full duplex operation. +.It Cm half-duplex +Force half duplex operation. +.El +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports the Ethernet controller portion of the Broadcom BCM2711 +on the Raspberry Pi 4 Model B and related systems. +It utilizes the BCM54213PE PHY. +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +The following loader tunable variable is available, and is also +available as a read-only +.Xr sysctl 8 +variable: +.Bl -tag -width indent +.It Va hw.genet.rx_batch +The maximum number of packets to pass to the link-layer input routine +at one time. +The default is 16. +.El +.Sh SYSCTL VARIABLES +The following variable is available as a +.Xr sysctl 8 +variable: +.Bl -tag -width indent +.It Va hw.genet.tx_hdr_min +When the driver is given an output packet in a buffer chain +in which the first buffer contains only the Ethernet header, +the number of bytes of the packet to add to the Ethernet header +in the first buffer. +Certain packets may be lost if this value is too small. +The default value is 56, and is sufficient for the observed cases to date. +.El +.Sh DIAGNOSTICS +The +.Nm +driver has no diagnostics that are likely in normal operation. +However, when the +.Cm debug +option is set with +.Xr ifconfig 8 , +most failures that cause packet loss in the transmit and receive paths +cause a cryptic diagnostic message naming the failure. +These messages generally make sense only when looking at the driver source. +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 13.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Mike Karels Aq Mt karels@freebsd.org . +Portions are derived from the bcmgenet driver in +.Nx +by Jared McNeill, +and parts of the structure and common code are from the awg driver +for the Allwinner EMAC by Jared McNeill. diff --git a/static/freebsd/man4/genetlink.4 b/static/freebsd/man4/genetlink.4 new file mode 100644 index 00000000..e8da0472 --- /dev/null +++ b/static/freebsd/man4/genetlink.4 @@ -0,0 +1,146 @@ +.\" +.\" Copyright (C) 2022 Alexander Chernikov . +.\" +.\" 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 November 1, 2022 +.Dt GENETLINK 4 +.Os +.Sh NAME +.Nm genetlink +.Nd Generic Netlink +.Sh SYNOPSIS +.In netlink/netlink.h +.In netlink/netlink_generic.h +.Ft int +.Fn socket AF_NETLINK SOCK_DGRAM NETLINK_GENERIC +.Sh DESCRIPTION +The +.Dv NETLINK_GENERIC +is a "container" family, used for dynamic registration of other families +belonging to the various subsystems. +These subsystems provide a string family name during registration and +receive a dynamically-allocated family id. +Allocated family identifiers are then used by applications to get access to +functions provided by that subsystem via netlink. +There are standard methods for resolving string family names to family +identifiers. +A similar mechanism works for the notification groups provided by those +families. +.Pp +All generic netlink families share a common header: +.Bd -literal +struct genlmsghdr { + uint8_t cmd; /* command within the family */ + uint8_t version; /* ABI version for the cmd */ + uint16_t reserved; /* reserved: set to 0 */ +}; +.Ed +The family id is encoded in the +.Dv nlmsg_type +of the base netlink header. +The +.Va cmd +field is the command identifier within the family. +The +.Va version +field is the command version. +.Sh METHODS +The generic Netlink framework provides the base family, +.Dv GENL_ID_CTRL +("nlctrl") with a fixed family id. +This family is used to list the details of all registered families. +.Pp +The following messages are supported by the framework: +.Ss CTRL_CMD_GETFAMILY +Fetches a single family or all registered families, depending on the +.Dv NLM_F_DUMP +flag. +Each family is reported as +.Dv CTRL_CMD_NEWFAMILY +message. +The following filters are recognised by the kernel: +.Pp +.Bd -literal -offset indent -compact +CTRL_ATTR_FAMILY_ID (uint16_t) current family id assigned by kernel +CTRL_ATTR_FAMILY_NAME (string) family name +.Ed +.Ss TLVs +.Bl -tag -width indent +.It Dv CTRL_ATTR_FAMILY_ID +(uint16_t) Dynamically-assigned family identifier. +.It Dv CTRL_ATTR_FAMILY_NAME +(string) Family name. +.It Dv CTRL_ATTR_HDRSIZE +(uint32_t) Family mandatory header size (typically 0). +.It Dv CTRL_ATTR_MAXATTR +(uint32_t) Maximum attribute number valid for the family. +.It Dv CTRL_ATTR_OPS +(nested) List of the operations supported by the family. +The attribute consists of a list of nested TLVs, with attribute values +monotonically incremented, starting from 0. +The following attributes are present in each TLV: +.Bl -tag -width indent +.It Dv CTRL_ATTR_OP_ID +Operation (message) number. +.It Dv CTRL_ATTR_OP_FLAGS +Operation flags. +The following flags are supported: +.Bd -literal -offset indent -compact +GENL_ADMIN_PERM requires elevated permissions +GENL_CMD_CAP_DO operation is a modification request +GENL_CMD_CAP_DUMP operation is a get/dump request +.Ed +.El +.It Dv CTRL_ATTR_MCAST_GROUPS +(nested) List of the notification groups supported by the family. +The attribute consists of a list of nested TLVs, with attribute values +monotonically incremented, starting from 0. +The following attributes are present in each TLV: +.Bl -tag -width indent +.It Dv CTRL_ATTR_MCAST_GRP_ID +Group id that can be used in +.Dv NETLINK_ADD_MEMBERSHIP +.Xr setsockopt 2 . +.It Dv CTRL_ATTR_MCAST_GRP_NAME +(string) Human-readable name of the group. +.El +.El +.Ss Groups +The following groups are defined: +.Bd -literal -offset indent -compact +"notify" Notifies on family registrations/removal. +.Ed +.Sh SEE ALSO +.Xr snl 3 , +.Xr netlink 4 +.Sh HISTORY +The +.Dv NETLINK_GENERIC +protocol family appeared in +.Fx 13.2 . +.Sh AUTHORS +The netlink was implemented by +.An -nosplit +.An Alexander Chernikov Aq Mt melifaro@FreeBSD.org . +It was derived from the Google Summer of Code 2021 project by +.An Ng Peng Nam Sean . diff --git a/static/freebsd/man4/geneve.4 b/static/freebsd/man4/geneve.4 new file mode 100644 index 00000000..fdb752c0 --- /dev/null +++ b/static/freebsd/man4/geneve.4 @@ -0,0 +1,384 @@ +.\" +.\" Copyright (c) 2025-2026 Pouria Mousavizadeh Tehrani +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd March 31, 2026 +.Dt GENEVE 4 +.Os +.Sh NAME +.Nm geneve +.Nd Generic Network Virtualization Encapsulation interface +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Cd device geneve +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Cd if_geneve_load="YES" +.Sh DESCRIPTION +The +.Nm +driver creates a generic network virtualization tunnel interfaces +for Tentant Systems over an L3 (IP/UDP) underlay network that provides +a Layer 2 (ethernet) or Layer 3 service using +.Nm +protocol. +.Pp +This driver corresponds to RFC 8926 for format specification and by default +uses the multicast-learning-based approach for its control plane. +To provide control plane independence all of the driver-specific operations +are implemented using +.Xr rtnetlink 4 +and all the +.Xr ioctl 2 +calls are implemented using the +.Xr nv 9 +library. +Each +.Nm +interface is created at runtime using interface cloning. +This is most easily done with the +.Xr ifconfig 8 +.Cm create +command or using the +.Va cloned_interfaces +variable in +.Xr rc.conf 5 . +The interface may be removed with the +.Xr ifconfig 8 +.Cm destroy +command. +.Pp +The +.Nm +interface must be configured in either L2 or L3 mode. +An L2 +.Nm +tunnel could be used as a backplane between the virtual switches +residing in hypervisors, switches, or other appliances. +.Pp +The L3 +.Nm +tunnel provides virtualized IP forwarding service similar to IP/VRF. +.Pp +By default the +.Nm +driver creates an L2 interface that supports the usual network +.Xr ioctl 2 Ns s +and thus can be used with +.Xr ifconfig 8 +like any other Ethernet interface. +An L2 +.Nm +interface encapsulates the Ethernet frame by prepending IP/UDP and +.Nm +headers. +Thus, the encapsulated (inner) frame is able to be transmitted +over a routed, Layer 3 network to the remote host. +.Pp +The +.Nm +interface may be configured in either unicast or multicast mode. +When in unicast mode, +the interface creates a tunnel to a single remote host, +and all traffic is transmitted to that host. +When in multicast mode, +the interface joins an IP multicast group, +and receives packets sent to the group address, +and transmits packets to either the multicast group address, +or directly to the remote host if there is an appropriate +forwarding table entry. +.Pp +When the +.Nm +interface is brought up, a +.Xr udp 4 +.Xr socket 9 +is created based on the configuration, +such as the local address for unicast mode or +the group address for multicast mode, +and the listening (local) port number. +Since multiple +.Nm +interfaces may be created that either +use the same local address +or join the same group address, +and use the same port, +the driver may share a socket among multiple interfaces. +However, each interface within a socket must belong to +a unique +.Nm +segment per +.Xr vnet 9 . +The analogous +.Xr vlan 4 +configuration would be a physical interface configured as +the parent device for multiple VLAN interfaces, each with +a unique VLAN tag. +Each +.Nm +segment is identified by a 24-bit value in the +.Nm +header called the +.Dq Virtual Network Identifier , +or VNI. +This value can be set with +.Xr ifconfig 8 +.Cm geneveid +parameter. +.Pp +When configured with the +.Xr ifconfig 8 +.Cm genevelearn +parameter, the interface dynamically creates forwarding table entries +from received packets. +An entry in the forwarding table maps the inner source MAC address +to the outer remote IP address. +During transmit, the interface attempts to lookup an entry for +the encapsulated destination MAC address. +If an entry is found, the IP address in the entry is used to directly +transmit the encapsulated frame to the destination. +Otherwise, when configured in multicast mode, +the interface must flood the frame to all hosts in the group. +The maximum number of entries in the table is configurable with the +.Xr ifconfig 8 +.Cm genevemaxaddr +command. +Stale entries in the table are periodically pruned. +The timeout is configurable with the +.Xr ifconfig 8 +.Cm genevetimeout +command. +.Ss MTU +Since the +.Nm +interface encapsulates the Ethernet frame with an IP, UDP, and +.Nm +header, the resulting frame may be larger than the MTU of the +physical network. +The +.Nm +specification recommends the physical network MTU be configured +to use jumbo frames to accommodate the encapsulated frame size. +.Pp +By default, the +.Nm +driver sets its MTU to usual ethernet MTU of 1500 bytes, reduced by +the size of geneve headers prepended which is depends on +.Cm genevemode . +.Pp +Alternatively, the +.Xr ifconfig 8 +.Cm mtu +command may be used to set the fixed MTU size on the +.Nm +interface to allow the encapsulated frame to fit in the +current MTU of the physical network. +If the +.Cm mtu +command was used, system no longer adjust the +.Nm +interface MTU on routing or address changes. +.Ss Hop Limit +TTL value of +.Nm +interface can change by using the +.Xr ifconfig 8 +.Cm genevettl +command and it also can be inherited from carrying packet. +You can set the +.Cm genevettl +to a number value or +.Cm inherit +option to be inherited at the encapsulation and decapsulation point. +.Ss Traffic Class +Just like the TTL value, ToS value can be inherited at the encapsulation point +using +.Xr ifconfig 8 +.Cm genevedscpinherit . +As defined in RFC 8926, ECN value follows the RFC 6040 for both ingress and +egress traffic. +.Ss Don't Fragment +To make sure fragmentation does not happing during transmission, you can +set the +.Xr ifconfig 8 +.Cm genevedf +value to +.Cm set +value which sets the DF bit on IPv4 header and IP_DONTFRAG option on both IPv4 +and IPv6 sockets. +Similar to other options, it can be set to +.Cm inherit +value. +.Ss Multicast +To create the +.Nm +interface with multicast underlay, one must use +.Xr ifconfig 8 +.Cm genevegroup +instead of +.Cm geneveremote +and set it to a multicast address (e.g. ff08::db8:0:1, 239.0.0.1). +One can set the outbound multicast interface with +.Xr ifconfig 8 +.Cm genevedev +to bound its multicast group to specific interface. +.Pp +The +.Cm ip_mroute +kernel module for IPv4 underlay and +.Cm ip6_mroute +for IPv6 underlay must be loaded for +.Xr multicast 4 +to function. +.Sh HARDWARE +The +.Nm +driver supports hardware checksum offload (receive and transmit) and TSO on the +encapsulated traffic over physical interfaces that support these features. +The +.Nm +interface examines the +.Cm genevedev +interface, if one is specified, or the interface hosting the +.Cm genevelocal +address, and configures its capabilities based on the hardware offload +capabilities of that physical interface. +If multiple physical interfaces will transmit or receive traffic for the +.Nm +then they all must have the same hardware capabilities. +The transmit routine of a +.Nm +interface may fail with +.Er ENXIO +if an outbound physical interface does not support +an offload that the +.Nm +interface is requesting. +This can happen if there are multiple physical interfaces involved, with +different hardware capabilities, or an interface capability was disabled after +the +.Nm +interface had already started. +.Sh EXAMPLES +.Bd -literal + Host A (198.51.100.10) + +--------------------+ + | VNI 100 10.1.1.0/24| + | VNI 200 10.2.2.0/24| + +---------+----------+ + | + (198.51.100.0/24) + | + +---------------v---------------+ + | Host B (203.0.113.1) | + | +------+-------+ | + | geneve0| |geneve1| + | +------v----+ +-----v-----+ | + | | bridge0 | | bridge1 | | + | | (VNI 100) | | (VNI 200) | | + | +------+----+ +----+------+ | + | | | | + +--------v-------------v--------+ + epair0b| |epair1b + +------+----+ +----+------+ + | Jail A | | Jail B | + | (10.1.1.x)| | (10.2.2.x)| + +-----------+ +-----------+ +.Ed +Assume host A has the (external) IP address 198.51.100.10 and +two internal addresses of 10.1.1.1/24 and 10.2.2.1/24, while +host B has the external address of 203.0.113.10 and two jails +with their own separate +.Xr VNET 9 . +the following commands will configure the tunnel: +.Pp +On host A, create a l2 +.Nm +interface in unicast mode: +.Bd -literal +ifconfig geneve0 create geneveid 100 genevelocal 198.51.100.10 geneveremote 203.0.113.1 +ifconfig geneve1 create geneveid 200 genevelocal 198.51.100.10 geneveremote 203.0.113.1 +.Ed +.Pp +On host B: +.Bd -literal +ifconfig geneve0 create geneveid 100 genevelocal 203.0.113.1 geneveremote 198.51.100.10 +ifconfig geneve1 create geneveid 200 genevelocal 203.0.113.1 geneveremote 198.51.100.10 +ifconfig bridge0 addm geneve0 addm epair0a +ifconfig bridge1 addm geneve1 addm epair1a +.Ed +.Pp +The example below demonstrate multicast configuration with IPv6: +.Bd -literal + ----------- VNI 42 ----------- + / \\ +2001:db8::1/64 --- Host A ------ Multicast ------- Host B --- 2001:db8::2/64 + 3fff::1 [em0] ff08::db8:1 [em0] 3fff::2 +.Ed +.Pp +Create a +.Nm +interface in multicast mode, +with the +.Cm genevelocal +address of 3fff::1, +and the +.Cm genevegroup +address of ff08::db8:0:1. +The em0 interface will be used to transmit multicast packets. +On host A: +.Bd -literal +ifconfig geneve0 create geneveid 42 genevelocal 3fff::1 genevegroup ff08::db8:1 genevedev em0 +.Ed +.Pp +On host B: +.Bd -literal +ifconfig geneve0 create geneveid 42 genevelocal 3fff::2 genevegroup ff08::db8:1 genevedev em0 +.Ed +.Pp +Once created, the +.Nm +interface can be configured with +.Xr ifconfig 8 . +.Pp +The following when placed in the file +.Pa /etc/rc.conf +will cause a geneve interface called +.Dq Li geneve0 +to be created, and will configure the interface in unicast mode. +.Bd -literal +cloned_interfaces="geneve0" +create_args_geneve0="geneveid 108 genevelocal 192.168.100.1 geneveremote 192.168.100.2" +.Ed +.Sh SEE ALSO +.Xr inet 4 , +.Xr inet6 4 , +.Xr multicast 4 , +.Xr rtnetlink 4 , +.Xr vlan 4 , +.Xr rc.conf 5 , +.Xr ifconfig 8 , +.Xr sysctl 8 +.Rs +.%A "J. Gross, Ed." +.%A "I. Gross, Ed." +.%A "T. Sridhar, Ed." +.%T "Geneve: Generic Network Virtualization Encapsulation" +.%D November 2020 +.%O "RFC 8926" +.Re +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Seyed Pouria Mousavizadeh Tehrani Aq info@spmzt.net +.Sh BUGS +Current geneve implementation with netlink can't set geneve options +other than genevemode during interface cloning in ifconfig without +specifying the interface index. diff --git a/static/freebsd/man4/geom.4 b/static/freebsd/man4/geom.4 new file mode 100644 index 00000000..18ecf7e5 --- /dev/null +++ b/static/freebsd/man4/geom.4 @@ -0,0 +1,505 @@ +.\" +.\" Copyright (c) 2002 Poul-Henning Kamp +.\" Copyright (c) 2002 Networks Associates Technology, Inc. +.\" All rights reserved. +.\" +.\" This software was developed for the FreeBSD Project by Poul-Henning Kamp +.\" and NAI Labs, the Security Research Division of Network Associates, Inc. +.\" under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the +.\" DARPA CHATS research program. +.\" +.\" 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. The names of the authors 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 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 8, 2024 +.Dt GEOM 4 +.Os +.Sh NAME +.Nm GEOM +.Nd "modular disk I/O request transformation framework" +.Sh SYNOPSIS +.Cd options GEOM_CACHE +.Cd options GEOM_CONCAT +.Cd options GEOM_ELI +.Cd options GEOM_GATE +.Cd options GEOM_JOURNAL +.Cd options GEOM_LABEL +.Cd options GEOM_LINUX_LVM +.Cd options GEOM_MAP +.Cd options GEOM_MIRROR +.Cd options GEOM_MOUNTVER +.Cd options GEOM_MULTIPATH +.Cd options GEOM_NOP +.Cd options GEOM_PART_APM +.Cd options GEOM_PART_BSD +.Cd options GEOM_PART_BSD64 +.Cd options GEOM_PART_EBR +.Cd options GEOM_PART_EBR_COMPAT +.Cd options GEOM_PART_GPT +.Cd options GEOM_PART_LDM +.Cd options GEOM_PART_MBR +.Cd options GEOM_RAID +.Cd options GEOM_RAID3 +.Cd options GEOM_SHSEC +.Cd options GEOM_STRIPE +.Cd options GEOM_UZIP +.Cd options GEOM_VIRSTOR +.Cd options GEOM_ZERO +.Sh DESCRIPTION +The +.Nm +framework provides an infrastructure in which +.Dq classes +can perform transformations on disk I/O requests on their path from +the upper kernel to the device drivers and back. +.Pp +Transformations in a +.Nm +context range from the simple geometric +displacement performed in typical disk partitioning modules over RAID +algorithms and device multipath resolution to full blown cryptographic +protection of the stored data. +.Pp +Compared to traditional +.Dq "volume management" , +.Nm +differs from most +and in some cases all previous implementations in the following ways: +.Bl -bullet +.It +.Nm +is extensible. +It is trivially simple to write a new class +of transformation and it will not be given stepchild treatment. +If +someone for some reason wanted to mount IBM MVS diskpacks, a class +recognizing and configuring their VTOC information would be a trivial +matter. +.It +.Nm +is topologically agnostic. +Most volume management implementations +have very strict notions of how classes can fit together, very often +one fixed hierarchy is provided, for instance, subdisk - plex - +volume. +.El +.Pp +Being extensible means that new transformations are treated no differently +than existing transformations. +.Pp +Fixed hierarchies are bad because they make it impossible to express +the intent efficiently. +In the fixed hierarchy above, it is not possible to mirror two +physical disks and then partition the mirror into subdisks, instead +one is forced to make subdisks on the physical volumes and to mirror +these two and two, resulting in a much more complex configuration. +.Nm +on the other hand does not care in which order things are done, +the only restriction is that cycles in the graph will not be allowed. +.Sh "TERMINOLOGY AND TOPOLOGY" +.Nm +is quite object oriented and consequently the terminology +borrows a lot of context and semantics from the OO vocabulary: +.Pp +A +.Dq class , +represented by the data structure +.Vt g_class +implements one +particular kind of transformation. +Typical examples are MBR disk +partition, BSD disklabel, and RAID5 classes. +.Pp +An instance of a class is called a +.Dq geom +and represented by the data structure +.Vt g_geom . +In a typical i386 +.Fx +system, there +will be one geom of class MBR for each disk. +.Pp +A +.Dq provider , +represented by the data structure +.Vt g_provider , +is the front gate at which a geom offers service. +A provider is +.Do +a disk-like thing which appears in +.Pa /dev +.Dc - a logical +disk in other words. +All providers have three main properties: +.Dq name , +.Dq sectorsize +and +.Dq size . +.Pp +A +.Dq consumer +is the backdoor through which a geom connects to another +geom provider and through which I/O requests are sent. +.Pp +The topological relationship between these entities are as follows: +.Bl -bullet +.It +A class has zero or more geom instances. +.It +A geom has exactly one class it is derived from. +.It +A geom has zero or more consumers. +.It +A geom has zero or more providers. +.It +A consumer can be attached to zero or one providers. +.It +A provider can have zero or more consumers attached. +.El +.Pp +All geoms have a rank-number assigned, which is used to detect and +prevent loops in the acyclic directed graph. +This rank number is +assigned as follows: +.Bl -enum +.It +A geom with no attached consumers has rank=1. +.It +A geom with attached consumers has a rank one higher than the +highest rank of the geoms of the providers its consumers are +attached to. +.El +.Sh "SPECIAL TOPOLOGICAL MANEUVERS" +In addition to the straightforward attach, which attaches a consumer +to a provider, and detach, which breaks the bond, a number of special +topological maneuvers exists to facilitate configuration and to +improve the overall flexibility. +.Bl -inset +.It Em TASTING +is a process that happens whenever a new class or new provider +is created, and it provides the class a chance to automatically configure an +instance on providers which it recognizes as its own. +A typical example is the MBR disk-partition class which will look for +the MBR table in the first sector and, if found and validated, will +instantiate a geom to multiplex according to the contents of the MBR. +.Pp +A new class will be offered to all existing providers in turn and a new +provider will be offered to all classes in turn. +.Pp +Exactly what a class does to recognize if it should accept the offered +provider is not defined by +.Nm , +but the sensible set of options are: +.Bl -bullet +.It +Examine specific data structures on the disk. +.It +Examine properties like +.Dq sectorsize +or +.Dq mediasize +for the provider. +.It +Examine the rank number of the provider's geom. +.It +Examine the method name of the provider's geom. +.El +.Pp +Tasting is controlled by the +.Va kern.geom.notaste +sysctl. +To disable tasting, set the sysctl to 1, to +re-enable tasting, set the sysctl to 0. +.It Em ORPHANIZATION +is the process by which a provider is removed while +it potentially is still being used. +.Pp +When a geom orphans a provider, all future I/O requests will +.Dq bounce +on the provider with an error code set by the geom. +Any +consumers attached to the provider will receive notification about +the orphanization when the event loop gets around to it, and they +can take appropriate action at that time. +.Pp +A geom which came into being as a result of a normal taste operation +should self-destruct unless it has a way to keep functioning whilst +lacking the orphaned provider. +Geoms like disk slicers should therefore self-destruct whereas +RAID5 or mirror geoms will be able to continue as long as they do +not lose quorum. +.Pp +When a provider is orphaned, this does not necessarily result in any +immediate change in the topology: any attached consumers are still +attached, any opened paths are still open, any outstanding I/O +requests are still outstanding. +.Pp +The typical scenario is: +.Pp +.Bl -bullet -offset indent -compact +.It +A device driver detects a disk has departed and orphans the provider for it. +.It +The geoms on top of the disk receive the orphanization event and +orphan all their providers in turn. +Providers which are not attached to will typically self-destruct +right away. +This process continues in a quasi-recursive fashion until all +relevant pieces of the tree have heard the bad news. +.It +Eventually the buck stops when it reaches geom_dev at the top +of the stack. +.It +Geom_dev will call +.Xr destroy_dev 9 +to stop any more requests from +coming in. +It will sleep until any and all outstanding I/O requests have +been returned. +It will explicitly close (i.e.: zero the access counts), a change +which will propagate all the way down through the mesh. +It will then detach and destroy its geom. +.It +The geom whose provider is now detached will destroy the provider, +detach and destroy its consumer and destroy its geom. +.It +This process percolates all the way down through the mesh, until +the cleanup is complete. +.El +.Pp +While this approach seems byzantine, it does provide the maximum +flexibility and robustness in handling disappearing devices. +.Pp +The one absolutely crucial detail to be aware of is that if the +device driver does not return all I/O requests, the tree will +not unravel. +.It Em SPOILING +is a special case of orphanization used to protect +against stale metadata. +It is probably easiest to understand spoiling by going through +an example. +.Pp +Imagine a disk, +.Pa da0 , +on top of which an MBR geom provides +.Pa da0s1 +and +.Pa da0s2 , +and on top of +.Pa da0s1 +a BSD geom provides +.Pa da0s1a +through +.Pa da0s1e , +and that both the MBR and BSD geoms have +autoconfigured based on data structures on the disk media. +Now imagine the case where +.Pa da0 +is opened for writing and those +data structures are modified or overwritten: now the geoms would +be operating on stale metadata unless some notification system +can inform them otherwise. +.Pp +To avoid this situation, when the open of +.Pa da0 +for write happens, +all attached consumers are told about this and geoms like +MBR and BSD will self-destruct as a result. +When +.Pa da0 +is closed, it will be offered for tasting again +and, if the data structures for MBR and BSD are still there, new +geoms will instantiate themselves anew. +.Pp +Now for the fine print: +.Pp +If any of the paths through the MBR or BSD module were open, they +would have opened downwards with an exclusive bit thus rendering it +impossible to open +.Pa da0 +for writing in that case. +Conversely, +the requested exclusive bit would render it impossible to open a +path through the MBR geom while +.Pa da0 +is open for writing. +.Pp +From this it also follows that changing the size of open geoms can +only be done with their cooperation. +.Pp +Finally: the spoiling only happens when the write count goes from +zero to non-zero and the retasting happens only when the write count goes +from non-zero to zero. +.It Em CONFIGURE +is the process where the administrator issues instructions +for a particular class to instantiate itself. +There are multiple +ways to express intent in this case - a particular provider may be +specified with a level of override forcing, for instance, a BSD +disklabel module to attach to a provider which was not found palatable +during the TASTE operation. +.Pp +Finally, I/O is the reason we even do this: it concerns itself with +sending I/O requests through the graph. +.It Em "I/O REQUESTS" , +represented by +.Vt "struct bio" , +originate at a consumer, +are scheduled on its attached provider and, when processed, are returned +to the consumer. +It is important to realize that the +.Vt "struct bio" +which enters through the provider of a particular geom does not +.Do +come out on the other side +.Dc . +Even simple transformations like MBR and BSD will clone the +.Vt "struct bio" , +modify the clone, and schedule the clone on their +own consumer. +Note that cloning the +.Vt "struct bio" +does not involve cloning the +actual data area specified in the I/O request. +.Pp +In total, four different I/O requests exist in +.Nm : +read, write, delete, and +.Dq "get attribute". +.Pp +Read and write are self explanatory. +.Pp +Delete indicates that a certain range of data is no longer used +and that it can be erased or freed as the underlying technology +supports. +Technologies like flash adaptation layers can arrange to erase +the relevant blocks before they will become reassigned and +cryptographic devices may want to fill random bits into the +range to reduce the amount of data available for attack. +.Pp +It is important to recognize that a delete indication is not a +request and consequently there is no guarantee that the data actually +will be erased or made unavailable unless guaranteed by specific +geoms in the graph. +If +.Dq "secure delete" +semantics are required, a +geom should be pushed which converts delete indications into (a +sequence of) write requests. +.Pp +.Dq "Get attribute" +supports inspection and manipulation +of out-of-band attributes on a particular provider or path. +Attributes are named by +.Tn ASCII +strings and they will be discussed in +a separate section below. +.El +.Pp +(Stay tuned while the author rests his brain and fingers: more to come.) +.Sh DIAGNOSTICS +Several flags are provided for tracing +.Nm +operations and unlocking +protection mechanisms via the +.Va kern.geom.debugflags +sysctl. +All of these flags are off by default, and great care should be taken in +turning them on. +.Bl -tag -width indent +.It 0x01 Pq Dv G_T_TOPOLOGY +Provide tracing of topology change events. +.It 0x02 Pq Dv G_T_BIO +Provide tracing of buffer I/O requests. +.It 0x04 Pq Dv G_T_ACCESS +Provide tracing of access check controls. +.It 0x08 (unused) +.It 0x10 (allow foot shooting) +Allow writing to Rank 1 providers. +This would, for example, allow the super-user to overwrite the MBR on the root +disk or write random sectors elsewhere to a mounted disk. +The implications are obvious. +.It 0x40 Pq Dv G_F_DISKIOCTL +This is unused at this time. +.It 0x80 Pq Dv G_F_CTLDUMP +Dump contents of gctl requests. +.El +.Sh SEE ALSO +.Xr libgeom 3 , +.Xr geom 8 , +.Xr DECLARE_GEOM_CLASS 9 , +.Xr disk 9 , +.Xr g_access 9 , +.Xr g_attach 9 , +.Xr g_bio 9 , +.Xr g_consumer 9 , +.Xr g_data 9 , +.Xr g_event 9 , +.Xr g_geom 9 , +.Xr g_provider 9 , +.Xr g_provider_by_name 9 +.Sh HISTORY +This software was initially developed for the +.Fx +Project by +.An Poul-Henning Kamp +and NAI Labs, the Security Research Division of Network Associates, Inc.\& +under DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the +DARPA CHATS research program. +.Pp +The following obsolete +.Nm +components were removed in +.Fx 13.0 : +.Bl -bullet -offset indent -compact +.It +.Cd GEOM_BSD , +.It +.Cd GEOM_FOX , +.It +.Cd GEOM_MBR , +.It +.Cd GEOM_SUNLABEL , +and +.It +.Cd GEOM_VOL . +.El +.Pp +Use +.Bl -bullet -offset indent -compact +.It +.Cd GEOM_PART_BSD , +.It +.Cd GEOM_MULTIPATH , +.It +.Cd GEOM_PART_MBR , +and +.It +.Cd GEOM_LABEL +.El +options, respectively, instead. +.Sh AUTHORS +.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org diff --git a/static/freebsd/man4/geom_linux_lvm.4 b/static/freebsd/man4/geom_linux_lvm.4 new file mode 100644 index 00000000..0066a199 --- /dev/null +++ b/static/freebsd/man4/geom_linux_lvm.4 @@ -0,0 +1,86 @@ +.\" +.\" Copyright (c) 2008 Andrew Thompson +.\" 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 October 1, 2013 +.Dt GEOM_LINUX_LVM 4 +.Os +.Sh NAME +.Nm geom_linux_lvm +.Nd "GEOM based Linux LVM logical volume mapping" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "options GEOM_LINUX_LVM" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +geom_linux_lvm_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +framework provides support for mapping Linux LVM volumes to GEOM providers. +.Nm +currently supports linear stripes with segments on one or more physical disks. +The parser is able to read LVM2 Text Format metadata, the logical volumes will +be assembled and made available under +.Pa /dev/linux_lvm/ . +The metadata is read-only, logical volumes cannot be allocated or resized. +.Sh EXAMPLES +To view which +.Nm +devices are available: +.Bd -literal -offset indent +# geom linux_lvm list +Geom name: vg1 +Providers: +1. Name: linux_lvm/vg1-home + Mediasize: 4294967296 (4.0G) + Sectorsize: 512 + Mode: r0w0e0 +2. Name: linux_lvm/vg1-logs + Mediasize: 4294967296 (4.0G) + Sectorsize: 512 + Mode: r0w0e0 +Consumers: +1. Name: ada0s1 + Mediasize: 80023716864 (75G) + Sectorsize: 512 + Mode: r0w0e0 +.Ed +.Sh SEE ALSO +.Xr GEOM 4 , +.Xr geom 8 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Andrew Thompson Aq Mt thompsa@FreeBSD.org . diff --git a/static/freebsd/man4/geom_uzip.4 b/static/freebsd/man4/geom_uzip.4 new file mode 100644 index 00000000..bb6f2000 --- /dev/null +++ b/static/freebsd/man4/geom_uzip.4 @@ -0,0 +1,182 @@ +.\" +.\" Copyright (c) 2006 Ceri Davies +.\" 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 April 28, 2021 +.Dt GEOM_UZIP 4 +.Os +.Sh NAME +.Nm geom_uzip +.Nd "GEOM based compressed disk images and partitions" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device xz" +.Cd "options zstd" +.Cd "options GEOM_UZIP" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +geom_uzip_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +framework provides support for compressed read-only +disk images. +This allows significant storage savings at the expense of +some CPU time on each read. +Data written in the GEOM label area allows +.Nm +to detect compressed images which have been created with +.Xr mkuzip 8 +and presented to the kernel as a logical disk device via +.Xr md 4 . +.Nm +creates a unique +.Pa md#.uzip +device for each image. +.Pp +.Nm +is not limited to supporting only +.Xr md 4 +images. +The image can also reside on a block device. +.Pq For example, a disk, USB flash drive, DVD-ROM, etc . +The appropriate device node will appear with the +.Pa .uzip +suffix. +.Bd -literal -offset indent +# gpart show da0 +=> 0 7833600 da0 BSD (3.7G) + 0 2097152 1 freebsd-ufs (1.0G) + 2097152 5736448 - free - (2.7G) +# gpart add -t freebsd-ufs -s 1G da0 +da0b added +# dd if=/tmp/20160217_dcomp_zcomp.uzip bs=256k of=/dev/da0b +3190+1 records in +3190+1 records out +836331008 bytes transferred in 111.021489 secs (7533055 bytes/sec) +# fsck -t ffs /dev/da0b.uzip +** /dev/da0b.uzip (NO WRITE) +** Last Mounted on /mnt +** Phase 1 - Check Blocks and Sizes +** Phase 2 - Check Pathnames +** Phase 3 - Check Connectivity +** Phase 4 - Check Reference Counts +** Phase 5 - Check Cyl groups +97455 files, 604242 used, 184741 free (2349 frags, 22799 blocks, + 0.3% fragmentation) +# mount -o ro /dev/da0b.uzip /mnt +# df /dev/da0b.uzip +Filesystem 1K-blocks Used Avail Capacity Mounted on +/dev/da0b.uzip 3155932 2416968 738964 77% /mnt +.Ed +.Pp +The +.Nm +device is subsequently used by +.Fx +kernel to access the uncompressed data. +The +.Nm +driver does not allow write operations to the underlying disk image. +To check which +.Dq providers +match a given +.Nm +device: +.Bd -literal -offset indent +# geom uzip list +Geom name: md1.uzip +Providers: +1. Name: md1.uzip + Mediasize: 22003712 (21M) + Sectorsize: 512 +Consumers: +1. Name: md1 + Mediasize: 9563648 (9.1M) + Sectorsize: 512 + +Geom name: da0b.uzip +Providers: +1. Name: da0b.uzip + Mediasize: 3355443200 (3.1G) + Sectorsize: 512 +Consumers: +1. Name: da0b + Mediasize: 1073741824 (1.0G) + Sectorsize: 512 +.Ed +.Pp +.Nm +allows mounting the root file system from a compressed disk partition by +setting the +.Dv vfs.root.mountfrom +tunable. +See +.Xr loader.conf 5 +for details. +.Sh DIAGNOSTICS +Several flags are provided for tracing +.Nm +I/O operations and TOC parsing via the following sysctls. +.Bl -tag -width indent +.It Va kern.geom.uzip.debug +Log level. +Zero disables logging. +Higher values enable more verbose debug logging for +.Nm . +Supported levels are from 0 (no logging) to 4 (maximum amount of logging). +.It Va kern.geom.uzip.debug_block +Log operations involving compressed cluster number. +.El +.Sh SEE ALSO +.Xr GEOM 4 , +.Xr md 4 , +.Xr geom 8 , +.Xr mkuzip 8 +.Sh HISTORY +Zstd support was added in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Max Khon Aq Mt fjoe@FreeBSD.org . +The block de-duplication code as well as some +.Nm +driver optimizations have been contributed by +.An Maxim Sobolev Aq Mt sobomax@FreeBSD.org . +The LZMA decompression support and CLOOP 3.0 support have been added by +.An Aleksandr Rybalko Aq Mt ray@FreeBSD.org . +.Pp +This manual page was written by +.An Ceri Davies Aq Mt ceri@FreeBSD.org . diff --git a/static/freebsd/man4/geom_zero.4 b/static/freebsd/man4/geom_zero.4 new file mode 100644 index 00000000..82e74618 --- /dev/null +++ b/static/freebsd/man4/geom_zero.4 @@ -0,0 +1,174 @@ +.\" +.\" Copyright (c) 2019 Greg White . All rights reserved. +.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd November 9, 2025 +.Dt GEOM_ZERO 4 +.Os +.Sh NAME +.Nm gzero , +.Nm geom_zero +.Nd GEOM-based zero disk/block device +.Sh SYNOPSIS +.Cd "options GEOM_ZERO" +.Pp +In +.Xr loader.conf 5 +or +.Xr sysctl.conf 5 : +.Cd kern.geom.zero.byte +.Cd kern.geom.zero.clear +.Sh DESCRIPTION +.Nm +is a +.Xr GEOM 4 +device simulating a one-exabyte disk. +It throws away any data written to it, +and returns the value of +.Va kern.geom.zero.byte +for every byte read from it. +.Pp +.Nm +differs from +.Xr zero 4 , +which is a regular character device and has an infinite length, +while +.Pa /dev/gzero +is a +.Xr GEOM 4 +provider of large, but limited, size. +.Pp +Consult +.Xr geom 8 +for instructions on how to use the supported commands of the +.Xr GEOM 4 +.Nm ZERO +class. +.Pp +.Nm +is useful for benchmarking performance of GEOM and GEOM classes +where compression of the data does not affect the results +.Po blocks from +.Pa /dev/gzero +compress exceptionally well +.Pc . +Examples of such benchmarks include +comparing the speed of two disk encryption algorithms and +comparing a hardware versus software implementation +of a single encryption algorithm. +.Sh MIB VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width "kern.geom.zero.clear" +.It Va kern.geom.zero.byte +This variable sets the fill byte of the +.Nm +device. +Default: +.Ql 0 . +.It Va kern.geom.zero.clear +This variable controls the clearing of the read data buffer. +If set to +.Ql 0 , +.Nm +will not copy any data into the read data buffers +and just return the read data buffers as they are without modifying them. +In particular, it will not fill the read buffer with the value of +.Va kern.geom.zero.byte . +This is useful for read benchmarking to reduce the measurement noise +caused by extra memory initialization. +Default: +.Ql 1 . +.El +.Sh FILES +.Bl -tag -width /dev/gzero +.It Pa /dev/gzero +The +.Nm +device. +.El +.Sh EXAMPLES +Create the +.Pa /dev/gzero +device by loading the +.Nm geom_zero +kernel module: +.Bd -literal -offset indent +# geom zero load +.Ed +.Pp +Show information about the +.Nm +device: +.Bd -literal -offset indent +# geom zero list +Geom name: gzero +Providers: +1. Name: gzero + Mediasize: 1152921504606846976 (1.0E) + Sectorsize: 512 + Mode: r0w0egzero0 +.Ed +.Pp +Set the fill byte of the +.Nm +device to 70 +.Po decimal for letter +.Dq F +in +.Xr ascii 7 +.Pc : +.Bd -literal -offset indent +# sysctl kern.geom.zero.byte=70 +kern.geom.zero.byte: 0 -> 70 +# head -c 1 /dev/gzero +F +.Ed +.Pp +Benchmark read and write throughput of +.Xr geli 8 Ap s +default encryption algorithm with a 4-KiB sector size: +.Bd -literal -offset indent +# geom zero load +# geli onetime -s 4096 gzero +# sysctl kern.geom.zero.clear=0 +# dd if=/dev/gzero.eli of=/dev/zero bs=4k count=$((1024 * 256)) +262144+0 records in +262144+0 records out +1073741824 bytes transferred in 1.258195 secs (853398307 bytes/sec) +# dd if=/dev/zero of=/dev/gzero.eli bs=4k count=$((1024 * 256)) +262144+0 records in +262144+0 records out +1073741824 bytes transferred in 1.663118 secs (645619658 bytes/sec) +.Ed +.Sh SEE ALSO +.Xr GEOM 4 , +.Xr zero 4 , +.Xr geom 8 , +.Xr sysctl 8 , +.Xr bio 9 +.Sh HISTORY +A +.Nm +device first appeared in +.Fx 6 . +.Sh AUTHORS +.An -nosplit +The +.Nm +device was written by +.An Paweł Jakub Dawidek Aq Mt pjd@FreeBSD.org . +.Pp +The +.Nm +manual page was originally written by +.An Greg White Aq Mt gkwhite@gmail.com +and rewritten by +.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org +before landing in +.Fx . diff --git a/static/freebsd/man4/gif.4 b/static/freebsd/man4/gif.4 new file mode 100644 index 00000000..cc12d91b --- /dev/null +++ b/static/freebsd/man4/gif.4 @@ -0,0 +1,378 @@ +.\" $KAME: gif.4,v 1.28 2001/05/18 13:15:56 itojun Exp $ +.\" +.\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. +.\" Copyright (C) 2024 Hiroki Sato +.\" 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. Neither the name of the project nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT 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 PROJECT 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 August 27, 2025 +.Dt GIF 4 +.Os +.Sh NAME +.Nm gif +.Nd generic tunnel interface +.Sh SYNOPSIS +.Cd "device gif" +.Sh DESCRIPTION +The +.Nm +interface is a generic tunnelling device for IPv4 and IPv6. +It can tunnel IPv[46] traffic over IPv[46]. +Therefore, there can be four possible configurations. +The behavior of +.Nm +is mainly based on RFC2893 IPv6-over-IPv4 configured tunnel. +On +.Nx , +.Nm +can also tunnel ISO traffic over IPv[46] using EON encapsulation. +Note that +.Nm +does not perform GRE encapsulation; use +.Xr gre 4 +for GRE encapsulation. +.Pp +The +.Nm +interface can also tunnel Ethernet traffic over IPv4 or IPv6 +when combined with a +.Xr if_bridge 4 +interface using EtherIP protocol. +See +.Xr if_bridge 4 +for detailed setup. +.Pp +Each +.Nm +interface is created at runtime using interface cloning. +This is +most easily done with the +.Dq Nm ifconfig Cm create +command or using the +.Va ifconfig_ Ns Aq Ar interface +variable in +.Xr rc.conf 5 . +.Pp +To use +.Nm , +the administrator needs to configure the protocol and addresses used for +the outer header. +This can be done by using +.Xr ifconfig 8 +.Cm tunnel , +or +.Dv SIOCSIFPHYADDR +ioctl. +The administrator also needs to configure the protocol and addresses for the +inner header, with +.Xr ifconfig 8 . +Note that IPv6 link-local addresses +.Pq those that start with Li fe80\&:\&: +will be automatically configured whenever possible. +You may need to remove IPv6 link-local addresses manually using +.Xr ifconfig 8 , +if you want to disable the use of IPv6 as the inner header +(for example, if you need a pure IPv4-over-IPv6 tunnel). +Finally, you must modify the routing table to route the packets through the +.Nm +interface. +.Ss MTU Configuration and Path MTU Discovery +The +.Nm +interface uses the fixed length, +.Li 1280 , +to determine whether the outgoing IPv6 packets are split. +This means the MTU value configured on the interface will be ignored +when the outer protocol is IPv6. +When the +.Dv NOCLAMP +interface flag is set, +.Nm +uses the same configured value as IPv4 communications. +This behavior prevents potential issues when the path MTU is +smaller than the interface MTU. +This section describes the reason why the default behavior is different. +The +.Dv NOCLAMP +interface flag can be set using the following command: +.Pp +.Dl ifconfig Ar gif0 Cm noclamp +.Pp +and clear the flag using the following: +.Pp +.Dl ifconfig Ar gif0 Cm -noclamp +.Pp +where +.Ar gif0 +is the actual interface name. +.Pp +A tunnel interface always has an implicit smaller MTU for the inner protocol +than the outer protocol because of the additional header. +Note that the interface MTU on a +.Nm +interface, +the default value is +.Li 1280 , +is used as MTU for the outer protocol. +This means that the MTU for the inner protocol varies depending on the +outer protocol header length. +If an outgoing packet bigger than the inner protocol MTU arrives at a +.Nm +interface for encapsulation, +it will be split into fragments. +Specifically, +if IPv4 is used as the outer protocol, +the inner is 20 octets smaller than the interface MTU. +In the case of the default interface MTU, +.Li 1280 , +inner packets bigger than +.Li 1260 +will be fragmented. +In the case of IPv6, +the inner is 40 octets smaller than the outer. +.Pp +This fragmentation is not harmful though it can degrade the +performance. +Note that while an increased MTU on +.Nm +interface helps to mitigate this reduced performance issue, +it can also cause packet losses on the intermediate narrowest path +between the two communication endpoints in IPv6. +IPv6 allows fragmentation only on the sender, +not on the routers in the communication path. +A big outgoing packet will be dropped on a router with a smaller MTU. +.Pp +In normal IPv6 communication, +an ICMPv6 Packet Too Big error will be sent back to the sender, +who can adjust the packet length and re-send it. +This process is performed in the upper protocols than L3, +such as TCP, +and makes the packet length shorter so that packets go through +the path without fragmentation. +This behavior is known as path MTU discovery. +.Pp +When using a +.Nm +interface, +the Packet Too Big message is generated for the outer protocol. +Since the +.Nm +interface does not translate this error to the inner protocol, +the inner protocol sees it just as a packet loss with no useful +information to adjust the length of the next packets. +In this situation, +path MTU discovery does not work, +and communications of the inner protocol +become stalled. +.Pp +In order to avoid this, +a +.Nm +interface silently splits a packet of over 1240 octets into fragments to make +the outer protocol packets equal or shorter than 1280 octets, +even when the interface MTU is configured as larger than 1280. +Note that this occurs only when the outer protocol is IPv6. +.Li 1280 +is the smallest MTU in IPv6 and guarantees no packet loss occurs +on intermediate routers. +.Pp +As mentioned earlier, +the performance is sub-optimal if the actual path MTU is larger than +.Li 1280 . +A typical confusing scenario is as follows. +The +.Nm +interface can have Ethernet, +whose MTU is usually 1500, +as the inner protocol. +It is called an EtherIP tunnel, +and can be configured by adding the +.Nm +interface as a member of +.Xr if_bridge 4 +interface. +The +.Xr if_bridge 4 +interface forcibly changes the MTU of the +.Nm +interface with those for the other member interfaces, +which are likely 1500. +In this case, +a situation in which the MTU of the +.Nm +interface is 1500 but fragmentation in 1280 octets always occurs. +.Pp +The default behavior is most conservative to prevent confusing packet loss. +Depending on the network configuration, +enabling the +.Dv NOCLAMP +interface flag might be helpful for better performance. +It is crucial to ensure that the path MTU is equal to or larger than +the interface MTU when enabling this flag. +.Ss ECN friendly behavior +The +.Nm +device can be configured to be ECN friendly, as described in +.Dv draft-ietf-ipsec-ecn-02.txt . +This is turned off by default, and can be turned on by the +.Dv IFF_LINK1 +interface flag. +.Pp +Without +.Dv IFF_LINK1 , +.Nm +will show normal behavior, as described in RFC2893. +This can be summarized as follows: +.Bl -tag -width "Ingress" -offset indent +.It Ingress +Set outer TOS bit to +.Dv 0 . +.It Egress +Drop outer TOS bit. +.El +.Pp +With +.Dv IFF_LINK1 , +.Nm +will copy ECN bits +.Dv ( 0x02 +and +.Dv 0x01 +on IPv4 TOS byte or IPv6 traffic class byte) +on egress and ingress, as follows: +.Bl -tag -width "Ingress" -offset indent +.It Ingress +Copy TOS bits except for ECN CE +(masked with +.Dv 0xfe ) +from +inner to outer. +Set ECN CE bit to +.Dv 0 . +.It Egress +Use inner TOS bits with some change. +If outer ECN CE bit is +.Dv 1 , +enable ECN CE bit on the inner. +.El +.Pp +Note that the ECN friendly behavior violates RFC2893. +This should be used in mutual agreement with the peer. +.Ss Security +A malicious party may try to circumvent security filters by using +tunnelled packets. +For better protection, +.Nm +performs both martian and ingress filtering against the outer source address +on egress. +Note that martian/ingress filters are in no way complete. +You may want to secure your node by using packet filters. +Ingress filtering can break tunnel operation in an asymmetrically +routed network. +It can be turned off by +.Dv IFF_LINK2 +bit. +.Ss Miscellaneous +By default, +.Nm +tunnels may not be nested. +This behavior may be modified at runtime by setting the +.Xr sysctl 8 +variable +.Va net.link.gif.max_nesting +to the desired level of nesting. +.Sh SEE ALSO +.Xr gre 4 , +.Xr if_bridge 4 , +.Xr inet 4 , +.Xr inet6 4 , +.Xr ifconfig 8 +.Rs +.%A R. Gilligan +.%A E. Nordmark +.%B RFC2893 +.%T Transition Mechanisms for IPv6 Hosts and Routers +.%D August 2000 +.%U http://tools.ietf.org/html/rfc2893 +.Re +.Rs +.%A Sally Floyd +.%A David L. Black +.%A K. K. Ramakrishnan +.%T "IPsec Interactions with ECN" +.%D December 1999 +.%O draft-ietf-ipsec-ecn-02.txt +.Re +.Rs +.%A R. Housley +.%A S. Hollenbeck +.%T EtherIP: Tunneling Ethernet Frames in IP Datagrams +.%R RFC 3378 +.%D September 2002 +.Re +.\" +.Sh HISTORY +The +.Nm +device first appeared in the WIDE hydrangea IPv6 kit. +.\" +.Sh BUGS +There are many tunnelling protocol specifications, all +defined differently from each other. +The +.Nm +device may not interoperate with peers which are based on different +specifications, +and are picky about outer header fields. +For example, you cannot usually use +.Nm +to talk with IPsec devices that use IPsec tunnel mode. +.Pp +If the outer protocol is IPv4, +.Nm +does not try to perform path MTU discovery for the encapsulated packet +(DF bit is set to 0). +.Pp +If the outer protocol is IPv6, path MTU discovery for encapsulated packets +may affect communication over the interface. +The first bigger-than-pmtu packet may be lost. +To avoid the problem, you may want to set the interface MTU for +.Nm +to 1240 or smaller, when the outer header is IPv6 and the inner header is IPv4. +.Pp +The +.Nm +device does not translate ICMP messages for the outer header into the inner +header. +.Pp +In the past, +.Nm +had a multi-destination behavior, configurable via +.Dv NOCLAMP +flag. +The behavior is obsolete and is no longer supported. +This flag is now used to determine whether performing fragmentation when +the outer protocol is IPv6. diff --git a/static/freebsd/man4/gpio.4 b/static/freebsd/man4/gpio.4 new file mode 100644 index 00000000..b84bfb01 --- /dev/null +++ b/static/freebsd/man4/gpio.4 @@ -0,0 +1,191 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2013, Sean Bruno +.\" 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 August 28, 2025 +.Dt GPIO 4 +.Os +.Sh NAME +.Nm gpiobus +.Nd GPIO bus system +.Sh SYNOPSIS +To compile these devices into your kernel and use the device hints, place the +following lines in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device gpio" +.Cd "device gpioiic" +.Cd "device gpioled" +.Ed +.Pp +Additional device entries for the +.Li ARM +architecture include: +.Bd -ragged -offset indent +.Cd "device a10_gpio" +.Cd "device bcm_gpio" +.Cd "device imx51_gpio" +.Cd "device lpcgpio" +.Cd "device mv_gpio" +.Cd "device ti_gpio" +.Cd "device gpio_avila" +.Cd "device gpio_cambria" +.Cd "device zy7_gpio" +.Cd "device pxagpio" +.Ed +.Pp +Additional device entries for the +.Li MIPS +architecture include: +.Bd -ragged -offset indent +.Cd "device ar71xxx_gpio" +.Cd "device octeon_gpio" +.Cd "device rt305_gpio" +.Ed +.Pp +Additional device entries for the +.Li POWERPC +architecture include: +.Bd -ragged -offset indent +.Cd "device wiigpio" +.Cd "device macgpio" +.Ed +.Pp +Additional device entries for the +.Li RISC-V +architecture include: +.Bd -ragged -offset indent +.Cd "device sifive_gpio" +.Ed +.Sh DESCRIPTION +The +.Nm +system provides a simple interface to the GPIO pins that are usually +available on embedded architectures and can provide bit banging style +devices to the system. +.Pp +The acronym +.Li GPIO +means +.Dq General-Purpose Input/Output. +.Pp +The BUS physically consists of multiple pins that can be configured +for input/output, IRQ delivery, SDA/SCL +.Em iicbus +use, etc. +.Pp +On some embedded architectures (like MIPS), discovery of the bus and +configuration of the pins is done via +.Xr device.hints 5 +in the platform's kernel +.Xr config 5 +file. +.Pp +On some others (like ARM), where +.Xr FDT 4 +is used to describe the device tree, the bus discovery is done via the DTS +passed to the kernel, being either statically compiled in, or by a variety +of ways where the boot loader (or Open Firmware enabled system) passes the +DTS blob to the kernel at boot. +.Pp +On a +.Xr device.hints 5 +based system these hints can be used to configure drivers for devices +attached to +.Nm +pins: +.Bl -tag -width ".Va hint.driver.unit.pin_list" +.It Va hint.driver.unit.at +The +.Nm gpiobus +where the device is attached. +For example, +.Qq gpiobus0 . +.Ar driver +and +.Ar unit +are the driver name and the unit number for the device driver. +.It Va hint.driver.unit.pins +This is a bitmask of the pins on the +.Nm gpiobus +that are connected to the device. +The pins will be allocated to the specified driver instance. +Only pins with numbers from 0 to 31 can be specified using this hint. +.It Va hint.driver.unit.pin_list +This is a list of pin numbers of pins on the +.Nm gpiobus +that are connected to the device. +The pins will be allocated to the specified driver instance. +This is a more user friendly alternative to the +.Ar pins +hint. +Additionally, this hint allows specifying pin numbers greater than 31. +The numbers can be decimal or hexadecimal with 0x prefix. +Any non-digit character can be used as a separator. +For example, it can be a comma, a slash or a space. +The separator can be followed by any number of space characters. +.El +.Pp +The following +.Xr device.hints 5 +are only provided by the +.Cd ar71xx_gpio +driver: +.Bl -tag -width ".Va hint.gpio.function_clear" +.It Va hint.gpio.%d.pinmask +This is a bitmask of pins on the GPIO board that we would like to expose +for use to the host operating system. +To expose pin 0, 4 and 7, use the bitmask of +10010001 converted to the hexadecimal value 0x0091. +.It Va hint.gpio.%d.pinon +This is a bitmask of pins on the GPIO board that will be set to ON at host +start. +To set pin 2, 5 and 13 to be set ON at boot, use the bitmask of +10000000010010 converted to the hexadecimal value 0x2012. +.It Va hint.gpio.function_set +.It Va hint.gpio.function_clear +These are bitmasks of pins that will remap a pin to handle a specific +function (USB, UART TX/RX, etc) in the Atheros function registers. +This is mainly used to set/clear functions that we need when they are set up or +not set up by uBoot. +.El +.Pp +Simply put, each pin of the GPIO interface is connected to an input/output +of some device in a system. +.Sh SEE ALSO +.Xr gpioiic 4 , +.Xr gpioled 4 , +.Xr iicbus 4 , +.Xr device.hints 5 , +.Xr gpioctl 8 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 10.0 . +.Sh AUTHORS +This +manual page was written by +.An Sean Bruno Aq Mt sbruno@FreeBSD.org . diff --git a/static/freebsd/man4/gpioiic.4 b/static/freebsd/man4/gpioiic.4 new file mode 100644 index 00000000..f5a8fba9 --- /dev/null +++ b/static/freebsd/man4/gpioiic.4 @@ -0,0 +1,156 @@ +.\" Copyright (c) 2013, Luiz Otavio O Souza +.\" 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 December 1, 2019 +.Dt GPIOIIC 4 +.Os +.Sh NAME +.Nm gpioiic +.Nd GPIO I2C bit-banging device driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device gpio" +.Cd "device gpioiic" +.Cd "device iicbb" +.Cd "device iicbus" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +gpioiic_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides an IIC bit-banging interface using two GPIO pins for the +SCL and SDA lines on the bus. +.Pp +.Nm +simulates an open collector kind of output when managing the pins on the +bus, even on systems which don't directly support configuring gpio pins +in that mode. +The pins are never driven to the logical value of '1'. +They are driven to '0' or switched to input mode (Hi-Z/tri-state), and +an external pullup resistor pulls the line to the 1 state unless some +other device on the bus is driving it to 0. +.Sh HINTS CONFIGURATION +On a +.Xr device.hints 5 +based system, such as MIPS, these values are configurable for +.Nm : +.Bl -tag -width ".Va hint.gpioiic.%d.atXXX" +.It Va hint.gpioiic.%d.at +The +.Nm gpiobus +you are attaching to. +Normally just gpiobus0 on systems with a single bank of gpio pins. +.It Va hint.gpioiic.%d.pins +This is a bitmask of the pins on the +.Nm gpiobus +that are to be used for SCLOCK and SDATA from the GPIO IIC +bit-banging bus. +To configure pin 0 and 7, use the bitmask of +0b10000001 and convert it to a hexadecimal value of 0x0081. +Please note that this mask should only ever have two bits set +(any other bits - i.e., pins - will be ignored). +Because +.Nm +must be a child of the gpiobus, both gpio pins must be part of that bus. +.It Va hint.gpioiic.%d.scl +Indicates which bit in the +.Va hint.gpioiic.%d.pins +should be used as the SCLOCK +source. +Optional, defaults to 0. +.It Va hint.gpioiic.%d.sda +Indicates which bit in the +.Va hint.gpioiic.%d.pins +should be used as the SDATA +source. +Optional, defaults to 1. +.El +.Sh FDT CONFIGURATION +On an +.Xr FDT 4 +based system, such as ARM, the DTS node for +.Nm gpioiic +conforms to the standard bindings document i2c/i2c-gpio.yaml. +The device node typically appears at the root of the device tree. +The following is an example of a +.Nm +node with one slave device +on the IIC bus: +.Bd -literal +/ { + gpioiic0 { + compatible = "i2c-gpio"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_gpioiic0>; + scl-gpios = <&gpio1 5 GPIO_ACTIVE_HIGH>; + sda-gpios = <&gpio7 11 GPIO_ACTIVE_HIGH>; + status = "okay"; + + /* One slave device on the i2c bus. */ + rtc@51 { + compatible="nxp,pcf2127"; + reg = <0x51>; + status = "okay"; + }; + }; +}; +.Ed +.Pp +Where: +.Bl -tag -width ".Va compatible" +.It Va compatible +Should be set to "i2c-gpio". +The deprecated string "gpioiic" is also accepted for backwards compatibility. +.It Va scl-gpios Va sda-gpios +These properties indicate which GPIO pins should be used for clock +and data on the GPIO IIC bit-banging bus. +There is no requirement that the two pins belong to the same gpio controller. +.It Va pinctrl-names pinctrl-0 +These properties may be required to configure the chosen pins as gpio +pins, unless the pins default to that state on your system. +.El +.Sh SEE ALSO +.Xr fdt 4 , +.Xr gpio 4 , +.Xr iic 4 , +.Xr iicbb 4 , +.Xr iicbus 4 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 10.1 . +.Sh AUTHORS +This +manual page was written by +.An Luiz Otavio O Souza . diff --git a/static/freebsd/man4/gpiokeys.4 b/static/freebsd/man4/gpiokeys.4 new file mode 100644 index 00000000..6d35c571 --- /dev/null +++ b/static/freebsd/man4/gpiokeys.4 @@ -0,0 +1,150 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2020 Andriy Gapon +.\" +.\" 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 August 5, 2020 +.Dt GPIOKEYS 4 +.Os +.Sh NAME +.Nm gpiokeys +.Nd GPIO keys device driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "options FDT" +.Cd "device gpio" +.Cd "device gpiokeys" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +gpiokeys_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides a way to represent a set of general purpose inputs as a +.Xr keyboard 4 +device. +At the moment the driver supports only +.Xr FDT 4 +based systems. +The DTS determines what pins are mapped to buttons and what key codes are +generated for each virtual button. +The +.Xr keyboard 4 +device can be used from userland to monitor for input changes. +.Pp +On an +.Xr FDT 4 +based system +the DTS part for a +.Nm +device usually looks like: +.Bd -literal +/ { + + ... + + gpio_keys { + compatible = "gpio-keys"; + + btn1 { + label = "button1"; + linux,code = ; + gpios = <&gpio 0 3 GPIO_ACTIVE_LOW> + }; + + btn2 { + label = "button2"; + linux,code = ; + gpios = <&gpio 0 4 GPIO_ACTIVE_LOW> + }; + }; +}; +.Ed +.Pp +For more details about the +.Va gpios +property, please consult +.Pa /usr/src/sys/dts/bindings-gpio.txt . +.Pp +The +.Nm +driver supports two properties for specifying a key code. +.Pp +The property +.Va freebsd,code +specifies a +.Fx +native scancode compatible with +.Xr kbdmap 5 +keyboard maps. +.Pp +The property +.Va linux,code +specifies an evdev scancode. +That scancode is internally translated to a native scancode. +Note that not all evdev scancodes have corresponding native scancodes. +If a scancode cannot be translated, then a diagnostic message is printed +and the input is ignored. +.Pp +The property +.Va label +is a descriptive name of a button. +It is used for diagnostic messages only. +This property is optional. +If not set, the node name is used in its place. +.Pp +The property +.Va autorepeat +determines whether autorepeat is enabled for a button. +.Pp +The property +.Va debounce-interval +defines debouncing interval time in milliseconds. +If not specified the interval defaults to 5. +.Sh SEE ALSO +.Xr fdt 4 , +.Xr gpio 4 , +.Xr keyboard 4 , +.Xr kbdmap 5 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 12.2 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org . +This +manual page was written by +.An Andriy Gapon Aq Mt avg@FreeBSD.org . diff --git a/static/freebsd/man4/gpioled.4 b/static/freebsd/man4/gpioled.4 new file mode 100644 index 00000000..45457d20 --- /dev/null +++ b/static/freebsd/man4/gpioled.4 @@ -0,0 +1,173 @@ +.\" Copyright (c) 2013, Luiz Otavio O Souza +.\" 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 May 23, 2019 +.Dt GPIOLED 4 +.Os +.Sh NAME +.Nm gpioled +.Nd GPIO LED generic device driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device gpio" +.Cd "device gpioled" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides glue to attach a +.Xr led 4 +compatible device to a GPIO pin. +Each LED in the system has a +.Pa name +which is used to export a device as +.Pa /dev/led/ . +The GPIO pin can then be controlled by writing to this device as described +in +.Xr led 4 . +.Pp +On a +.Xr device.hints 5 +based system, like +.Li MIPS , +these values are configurable for +.Nm : +.Bl -tag -width ".Va hint.gpioiic.%d.atXXX" +.It Va hint.gpioled.%d.at +The gpiobus you are attaching to. +Normally assigned to gpiobus0. +.It Va hint.gpioled.%d.name +Arbitrary name of device in +.Pa /dev/led/ +to create for +.Xr led 4 . +.It Va hint.gpioled.%d.pins +Which pin on the GPIO interface to map to this instance. +Please note that this mask should only ever have one bit set +(any other bits - i.e., pins - will be ignored). +.It Va hint.gpioled.%d.invert +Use pin inversion. If set to 1, the pin will be set to 0 to light the LED, and 1 +to clear it. +.It Va hint.gpioled.%d.invmode +Whether or not to use hardware support when pin inversion is requested. Must be +one of: +.Bl -tag +.It Va auto +Use hardware pin inversion if available, else fallback to software pin +inversion. This is the default. +.It Va hw +Use hardware pin inversion. +.It Va sw +Use software pin inversion. +.El +.It Va hint.gpioled.%d.state +The initial state of the LED when the driver takes control over it. +If set to 1 or 0, the LED will be on or off correspondingly. +If set to -1, the LED will be kept in its original state. +.El +.Pp +On a +.Xr FDT 4 +based system, like +.Li ARM , +the DTS part for a +.Nm gpioled +device usually looks like: +.Bd -literal +gpio: gpio { + + gpio-controller; + ... + + led0 { + compatible = "gpioled"; + gpios = <&gpio 16 2 0>; /* GPIO pin 16. */ + name = "ok"; + }; + + led1 { + compatible = "gpioled"; + gpios = <&gpio 17 2 0>; /* GPIO pin 17. */ + name = "user-led1"; + }; +}; +.Ed +.Pp +Optionally, you can choose to combine all the LEDs under a single +.Dq gpio-leds +compatible node: +.Bd -literal +simplebus0 { + + ... + + leds { + compatible = "gpio-leds"; + + led0 { + gpios = <&gpio 16 2 0>; + name = "ok" + }; + + led1 { + gpios = <&gpio 17 2 0>; + name = "user-led1" + }; + }; +}; +.Ed +.Pp +Both methods are equally supported and it is possible to have the LEDs +defined with any sort of mix between the methods. +The only restriction is that a GPIO pin cannot be mapped by two different +(gpio)leds. +.Pp +For more details about the +.Va gpios +property, please consult +.Pa /usr/src/sys/dts/bindings-gpio.txt . +.Pp +The property +.Va name +is the arbitrary name of the device in +.Pa /dev/led/ +to create for +.Xr led 4 . +.Sh SEE ALSO +.Xr fdt 4 , +.Xr gpio 4 , +.Xr gpioiic 4 , +.Xr led 4 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 10.1 . +.Sh AUTHORS +This +manual page was written by +.An Luiz Otavio O Souza . diff --git a/static/freebsd/man4/gpioths.4 b/static/freebsd/man4/gpioths.4 new file mode 100644 index 00000000..8b9c7992 --- /dev/null +++ b/static/freebsd/man4/gpioths.4 @@ -0,0 +1,150 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2019 Ian Lepore +.\" +.\" 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 December 8, 2019 +.Dt GPIOTHS 4 +.Os +.Sh NAME +.Nm gpioths +.Nd driver for DHTxx and AM320x temperature and humidity sensors +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device gpioths" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +gpioths_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports the DHTxx and AM320x family of +temperature and humidity sensors. +The driver automatically reads the values from the sensor +once every 5 seconds, and makes the results available via +.Xr sysctl 8 +variables. +.Sh HARDWARE +The +.Nm +driver provides support for the following devices: +.Pp +.Bl -column -compact -offset indent "XXXXXXXX" "XXXXXXXX" +.It DHT11 Ta DHT12 +.It DHT21 Ta DHT22 +.It AM3201 Ta AM3202 +.El +.Pp +The supported devices are all similar to each other, varying +primarily in accuracy and resolution. +The devices require a single wire for data communications, using a +custom protocol which is not compatible with Maxim's 1-wire(tm). +The AM320x devices also support connection to an i2c bus, +but this driver supports only the single-wire connection option. +.Sh SYSCTL VARIABLES +Sysctl variables are used to access the most recent temperature and +humidity measurements. +.Bl -tag -width indent +.It Va dev.gpioths..temperature +The current temperature in integer deciKelvins. +Note that +.Xr sysctl 8 +will convert those units to display in decimal degrees Celsius. +.It Va dev.gpioths..humidity +The current relative humidity, as an integer percentage. +.It Va dev.gpioths..fails +The number of failed attempts to communicate with the sensor since +the last good access. +Cleared whenever a set of measurements is successfully retrieved. +.El +.Sh FDT CONFIGURATION +On an +.Xr fdt 4 +based system, a +.Nm +device node is typically defined directly under the root node, or under +a simplebus node that represents a collection of devices on a board. +.Pp +The following properties are required in the +.Nm +device subnode: +.Bl -tag -width indent +.It Va compatible +Must be "dht11". +.It Va gpios +A reference to the gpio device and pin for data communications. +.El +.Ss Example of adding a sensor with an overlay +.Bd -unfilled -offset indent +/dts-v1/; +/plugin/; +#include + +/ { + compatible = "wand,imx6q-wandboard"; +}; + +&{/} { + dht0 { + compatible = "dht11"; + gpios = <&gpio5 15 GPIO_ACTIVE_HIGH>; + }; +}; +.Ed +.Sh HINTS CONFIGURATION +On a +.Xr device.hints 5 +based system, such as +.Li MIPS , +these values are configurable for +.Nm : +.Bl -tag -width indent +.It Va hint.gpioths..at +The +.Xr gpiobus 4 +instance the +.Nm +instance is attached to. +.It Va hint.gpioths.pins +A bitmask with a single bit set to indicate which gpio pin on the +.Xr gpiobus 4 +to use for data communications. +.El +.Sh SEE ALSO +.Xr fdt 4 , +.Xr gpiobus 4 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 11.1 . diff --git a/static/freebsd/man4/gre.4 b/static/freebsd/man4/gre.4 new file mode 100644 index 00000000..7f46e54e --- /dev/null +++ b/static/freebsd/man4/gre.4 @@ -0,0 +1,275 @@ +.\" $NetBSD: gre.4,v 1.28 2002/06/10 02:49:35 itojun Exp $ +.\" +.\" Copyright 1998 (c) The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Heiko W.Rupp +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 August 21, 2020 +.Dt GRE 4 +.Os +.Sh NAME +.Nm gre +.Nd encapsulating network device +.Sh SYNOPSIS +To compile the +driver into the kernel, place the following line in the kernel +configuration file: +.Bd -ragged -offset indent +.Cd "device gre" +.Ed +.Pp +Alternatively, to load the +driver as a module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_gre_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +network interface pseudo device encapsulates datagrams +into IP. +These encapsulated datagrams are routed to a destination host, +where they are decapsulated and further routed to their final destination. +The +.Dq tunnel +appears to the inner datagrams as one hop. +.Pp +.Nm +interfaces are dynamically created and destroyed with the +.Xr ifconfig 8 +.Cm create +and +.Cm destroy +subcommands. +.Pp +This driver corresponds to RFC 2784. +Encapsulated datagrams are prepended an outer datagram and a GRE header. +The GRE header specifies +the type of the encapsulated datagram and thus allows for tunneling other +protocols than IP. +GRE mode is also the default tunnel mode on Cisco routers. +.Nm +also supports Cisco WCCP protocol, both version 1 and version 2. +.Pp +The +.Nm +interfaces support a number of additional parameters to the +.Xr ifconfig 8 : +.Bl -tag -width "enable_csum" +.It Ar grekey +Set the GRE key used for outgoing packets. +A value of 0 disables the key option. +.It Ar enable_csum +Enables checksum calculation for outgoing packets. +.It Ar enable_seq +Enables use of sequence number field in the GRE header for outgoing packets. +.It Ar udpencap +Enables UDP-in-GRE encapsulation (see the +.Sx GRE-IN-UDP ENCAPSULATION +Section below for details). +.It Ar udpport +Set the source UDP port for outgoing packets. +A value of 0 disables the persistence of source UDP port for outgoing packets. +See the +.Sx GRE-IN-UDP ENCAPSULATION +Section below for details. +.El +.Sh GRE-IN-UDP ENCAPSULATION +The +.Nm +supports GRE in UDP encapsulation as defined in RFC 8086. +A GRE in UDP tunnel offers the possibility of better performance for +load-balancing GRE traffic in transit networks. +Encapsulating GRE in UDP enables use of the UDP source port to provide +entropy to ECMP hashing. +.Pp +The GRE in UDP tunnel uses single value 4754 as UDP destination port. +The UDP source port contains a 14-bit entropy value that is generated +by the encapsulator to identify a flow for the encapsulated packet. +The +.Ar udpport +option can be used to disable this behaviour and use single source UDP +port value. +The value of +.Ar udpport +should be within the ephemeral port range, i.e., 49152 to 65535 by default. +.Pp +Note that a GRE in UDP tunnel is unidirectional; the tunnel traffic is not +expected to be returned back to the UDP source port values used to generate +entropy. +This may impact NAPT (Network Address Port Translator) middleboxes. +If such tunnels are expected to be used on a path with a middlebox, +the tunnel can be configured either to disable use of the UDP source port +for entropy or to enable middleboxes to pass packets with UDP source port +entropy. +.Sh EXAMPLES +.Bd -literal +192.168.1.* --- Router A -------tunnel-------- Router B --- 192.168.2.* + \\ / + \\ / + +------ the Internet ------+ +.Ed +.Pp +Assuming router A has the (external) IP address A and the internal address +192.168.1.1, while router B has external address B and internal address +192.168.2.1, the following commands will configure the tunnel: +.Pp +On router A: +.Bd -literal -offset indent +ifconfig greN create +ifconfig greN inet 192.168.1.1 192.168.2.1 +ifconfig greN inet tunnel A B +route add -net 192.168.2 -netmask 255.255.255.0 192.168.2.1 +.Ed +.Pp +On router B: +.Bd -literal -offset indent +ifconfig greN create +ifconfig greN inet 192.168.2.1 192.168.1.1 +ifconfig greN inet tunnel B A +route add -net 192.168.1 -netmask 255.255.255.0 192.168.1.1 +.Ed +.Pp +In case when internal and external IP addresses are the same, +different routing tables (FIB) should be used. +The default FIB will be applied to IP packets before GRE encapsulation. +After encapsulation GRE interface should set different FIB number to +outgoing packet. +Then different FIB will be applied to such encapsulated packets. +According to this FIB packet should be routed to tunnel endpoint. +.Bd -literal +Host X -- Host A (198.51.100.1) ---tunnel--- Cisco D (203.0.113.1) -- Host E + \\ / + \\ / + +----- Host B ----- Host C -----+ + (198.51.100.254) +.Ed +.Pp +On Host A (FreeBSD): +.Pp +First of multiple FIBs should be configured via loader.conf: +.Bd -literal -offset indent +net.fibs=2 +net.add_addr_allfibs=0 +.Ed +.Pp +Then routes to the gateway and remote tunnel endpoint via this gateway +should be added to the second FIB: +.Bd -literal -offset indent +route add -net 198.51.100.0 -netmask 255.255.255.0 -fib 1 -iface em0 +route add -host 203.0.113.1 -fib 1 198.51.100.254 +.Ed +.Pp +And GRE tunnel should be configured to change FIB for encapsulated packets: +.Bd -literal -offset indent +ifconfig greN create +ifconfig greN inet 198.51.100.1 203.0.113.1 +ifconfig greN inet tunnel 198.51.100.1 203.0.113.1 tunnelfib 1 +.Ed +.Sh NOTES +The MTU of +.Nm +interfaces is set to 1476 by default, to match the value used by Cisco routers. +This may not be an optimal value, depending on the link between the two tunnel +endpoints. +It can be adjusted via +.Xr ifconfig 8 . +.Pp +For correct operation, the +.Nm +device needs a route to the decapsulating host that does not run over the tunnel, +as this would be a loop. +.Pp +The kernel must be set to forward datagrams by setting the +.Va net.inet.ip.forwarding +.Xr sysctl 8 +variable to non-zero. +.Pp +By default, +.Nm +tunnels may not be nested. +This behavior may be modified at runtime by setting the +.Xr sysctl 8 +variable +.Va net.link.gre.max_nesting +to the desired level of nesting. +.Sh SEE ALSO +.Xr gif 4 , +.Xr inet 4 , +.Xr ip 4 , +.Xr me 4 , +.Xr netintro 4 , +.Xr protocols 5 , +.Xr ifconfig 8 , +.Xr sysctl 8 +.Sh STANDARDS +.Rs +.%A S. Hanks +.%A "T. Li" +.%A D. Farinacci +.%A P. Traina +.%D October 1994 +.%R RFC 1701 +.%T Generic Routing Encapsulation (GRE) +.Re +.Pp +.Rs +.%A S. Hanks +.%A "T. Li" +.%A D. Farinacci +.%A P. Traina +.%D October 1994 +.%R RFC 1702 +.%T Generic Routing Encapsulation over IPv4 networks +.Re +.Pp +.Rs +.%A D. Farinacci +.%A "T. Li" +.%A S. Hanks +.%A D. Meyer +.%A P. Traina +.%D March 2000 +.%R RFC 2784 +.%T Generic Routing Encapsulation (GRE) +.Re +.Pp +.Rs +.%A G. Dommety +.%D September 2000 +.%R RFC 2890 +.%T Key and Sequence Number Extensions to GRE +.Re +.Sh AUTHORS +.An Andrey V. Elsukov Aq Mt ae@FreeBSD.org +.An Heiko W.Rupp Aq Mt hwr@pilhuhn.de +.Sh BUGS +The current implementation uses the key only for outgoing packets. +Incoming packets with a different key or without a key will be treated as if they +would belong to this interface. +.Pp +The sequence number field also used only for outgoing packets. diff --git a/static/freebsd/man4/gve.4 b/static/freebsd/man4/gve.4 new file mode 100644 index 00000000..c5627e92 --- /dev/null +++ b/static/freebsd/man4/gve.4 @@ -0,0 +1,310 @@ +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" Copyright (c) 2023-2024 Google LLC +.\" +.\" 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. Neither the name of the copyright holder nor the names of its contributors +.\" may be used to endorse or promote products derived from this software without +.\" specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 COPYRIGHT HOLDER 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 May 20, 2025 +.Dt GVE 4 +.Os +.Sh NAME +.Nm gve +.Nd "Ethernet driver for Google Virtual NIC (gVNIC)" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device gve" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_gve_load="YES" +.Ed +.Sh DESCRIPTION +gVNIC is a virtual network interface designed specifically for Google Compute Engine (GCE). +It is required to support per-VM Tier-1 networking performance, and for using certain VM shapes on GCE. +.Pp +.Nm +is the driver for gVNIC. +It supports the following features: +.Pp +.Bl -bullet -compact +.It +RX checksum offload +.It +TX chesksum offload +.It +TCP Segmentation Offload (TSO) +.It +Large Receive Offload (LRO) in software +.It +Jumbo frames +.It +Receive Side Scaling (RSS) +.El +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +.Nm +binds to a single PCI device ID presented by gVNIC: +.Pp +.Bl -bullet -compact +.It +0x1AE0:0x0042 +.El +.Sh EXAMPLES +.Pp +Change the TX queue count to 4 for the gve0 interface: +.D1 sysctl dev.gve.0.num_tx_queues=4 +.Pp +Change the RX queue count to 4 for the gve0 interface: +.D1 sysctl dev.gve.0.num_rx_queues=4 +.Pp +Change the TX ring size to 512 for the gve0 interface: +.D1 sysctl dev.gve.0.tx_ring_size=512 +.Pp +Change the RX ring size to 512 for the gve0 interface: +.D1 sysctl dev.gve.0.rx_ring_size=512 +.Sh DIAGNOSTICS +The following messages are recorded during driver initialization: +.Bl -diag +.It "Enabled MSIX with %d vectors" +.It "Configured device resources" +.It "Successfully attached %s" +.It "Deconfigured device resources" +.El +.Pp +These messages are seen if driver initialization fails. +Global (across-queues) allocation failures: +.Bl -diag +.It "Failed to configure device resources: err=%d" +.It "No compatible queue formats" +.It "Failed to allocate ifnet struct" +.It "Failed to allocate admin queue mem" +.It "Failed to alloc DMA mem for DescribeDevice" +.It "Failed to allocate QPL page" +.El +.Pp +irq and BAR allocation failures: +.Bl -diag +.It "Failed to acquire any msix vectors" +.It "Tried to acquire %d msix vectors, got only %d" +.It "Failed to setup irq %d for Tx queue %d " +.It "Failed to setup irq %d for Rx queue %d " +.It "Failed to allocate irq %d for mgmnt queue" +.It "Failed to setup irq %d for mgmnt queue, err: %d" +.It "Failed to allocate BAR0" +.It "Failed to allocate BAR2" +.It "Failed to allocate msix table" +.El +.Pp +Rx queue-specific allocation failures: +.Bl -diag +.It "No QPL left for rx ring %d" +.It "Failed to alloc queue resources for rx ring %d" +.It "Failed to alloc desc ring for rx ring %d" +.It "Failed to alloc data ring for rx ring %d" +.El +.Pp +Tx queue-specific allocation failures: +.Bl -diag +.It "No QPL left for tx ring %d" +.It "Failed to alloc queue resources for tx ring %d" +.It "Failed to alloc desc ring for tx ring %d" +.It "Failed to vmap fifo, qpl_id = %d" +.El +.Pp +The following messages are recorded when the interface detach fails: +.Bl -diag +.It "Failed to deconfigure device resources: err=%d" +.El +.Pp +If bootverbose is on, the following messages are recorded when the interface is being brought up: +.Bl -diag +.It "Created %d rx queues" +.It "Created %d tx queues" +.It "MTU set to %d" +.El +.Pp +The following messages are recorded when the interface is being brought down: +.Bl -diag +.It "Destroyed %d rx queues" +.It "Destroyed %d tx queues" +.El +.Pp +These messages are seen if errors are encountered when bringing the interface up or down: +.Bl -diag +.It "Failed to destroy rxq %d, err: %d" +.It "Failed to destroy txq %d, err: %d" +.It "Failed to create rxq %d, err: %d" +.It "Failed to create txq %d, err: %d" +.It "Failed to set MTU to %d" +.It "Invalid new MTU setting. new mtu: %d max mtu: %d min mtu: %d" +.It "Cannot bring the iface up when detached" +.It "Reached max number of registered pages %lu > %lu" +.It "Failed to init lro for rx ring %d" +.El +.Pp +These messages are seen if any admin queue command fails: +.Bl -diag +.It "AQ command(%u): failed with status %d" +.It "AQ command(%u): unknown status code %d" +.It "AQ commands timed out, need to reset AQ" +.It "Unknown AQ command opcode %d" +.El +.Pp +These messages appear if a TX timeout is detected: +.Bl -diag +.It "Found %d timed out packet(s) on txq%d, kicking it for completions" +.It "Found %d timed out packet(s) on txq%d with its last kick %ld sec ago which is less than the cooldown period %d. Resetting device" +.El +.Pp +These messages are recorded when the device is being reset due to an error: +.Bl -diag +.It "Scheduling reset task!" +.It "Waiting until admin queue is released." +.It "Admin queue released" +.El +.Pp +If it was the NIC that requested the reset, this message is recorded: +.Bl -diag +.It "Device requested reset" +.El +.Pp +If the reset fails during the reinitialization phase, this message is recorded: +.Bl -diag +.It "Restore failed!" +.El +.Pp +These two messages correspond to the NIC alerting the driver to link state changes: +.Bl -diag +.It "Device link is up." +.It "Device link is down." +.El +.Pp +Apart from these messages, the driver exposes per-queue packet and error counters as sysctl nodes. +Global (across queues) counters can be read using +.Xr netstat 1 . +.Sh SYSCTL VARIABLES +.Nm +exposes the following +.Xr sysctl 8 +variables: +.Bl -tag -width indent +.It Va hw.gve.driver_version +The driver version. +This is read-only. +.It Va hw.gve.queue_format +The queue format in use. +This is read-only. +.It Va hw.gve.disable_hw_lro +Setting this boot-time tunable to 1 disables Large Receive Offload (LRO) in the NIC. +The default value is 0, which means hardware LRO is enabled by default. +The software LRO stack in the kernel is always used. +This sysctl variable needs to be set before loading the driver, using +.Xr loader.conf 5 . +.It Va hw.gve.allow_4k_rx_buffers +Setting this boot-time tunable to 1 enables support for 4K RX Buffers. +The default value is 0, which means 2K RX Buffers will be used. +4K RX Buffers are only supported on DQO_RDA and DQO_QPL queue formats. +When enabled, 4K RX Buffers will be used either when HW LRO is enabled +or mtu is greated than 2048. +This sysctl variable needs to be set before loading the driver, using +.Xr loader.conf 5 . +.It Va dev.gve.X.num_rx_queues and dev.gve.X.num_tx_queues +Run-time tunables that represent the number of currently used RX/TX queues. +The default value is the max number of RX/TX queues the device can support. +.Pp +This call turns down the interface while setting up the new queues, +which may potentially cause any new packets to be dropped. +This call can fail if the system is not able to provide the driver with enough resources. +In that situation, the driver will revert to the previous number of RX/TX queues. +If this also fails, a device reset will be triggered. +.Pp +Note: sysctl nodes for queue stats remain available even if a queue is removed. +.Pp +.It Va dev.gve.X.rx_ring_size and dev.gve.X.tx_ring_size +Run-time tunables that represent the current ring size for RX/TX queues. +The default value is set to device defaults for ring size. +.Pp +This call turns down the interface while setting up the queues with the new ring size, +which may potentially cause any new packets to be dropped. +This call can fail if the system is not able to provide the driver with enough resources. +In that situation, the driver will try to revert to the previous ring size for RX/TX queues. +If this also fails, the device will be in an unhealthy state and will need to be reloaded. +This value must be a power of 2 and within the defined range. +.Pp +.El +.Sh LIMITATIONS +.Nm +does not support the transmission of VLAN-tagged packets. +All VLAN-tagged traffic is dropped. +.Sh QUEUE FORMATS +.Nm +features different datapath modes called queue formats: +.Pp +.Bl -bullet -compact +.It +GQI_QPL: "QPL" stands for "Queue Page List" and refers to the fact that +hardware expects a fixed bounce buffer and cannot access arbitrary memory. +GQI is the older descriptor format. +The G in "GQI" refers to an older generation of hardware, and the "QI" +stands for "Queue In-order" referring to the fact that the NIC sends +Tx and Rx completions in the same order as the one in which the corresponding +descriptors were posted by the driver. +.It +DQO_RDA: DQO is the descriptor format required to take full advantage of +next generation VM shapes. +"RDA" stands for "Raw DMA Addressing" and refers to the fact that hardware +can work with DMA-ed packets and does not expect them to be copied into or +out of a fixed bounce buffer. +The D in "DQO" refers to a newer generation of hardware, and the "QO" +stands for "Queue Out-of-order" referring to the fact that the NIC might +send Tx and Rx completions in an order different from the one in which +the corresponding descriptors were posted by the driver. +.It +DQO_QPL: The next generation descriptor format in the "QPL" mode. +.El +.Sh SUPPORT +Please email gvnic-drivers@google.com with the specifics of the issue encountered. +.Sh SEE ALSO +.Xr netstat 1 , +.Xr loader.conf 5 , +.Xr ifconfig 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 13.3 . +.Sh AUTHORS +The +.Nm +driver was written by Google. diff --git a/static/freebsd/man4/h_ertt.4 b/static/freebsd/man4/h_ertt.4 new file mode 100644 index 00000000..86ff2285 --- /dev/null +++ b/static/freebsd/man4/h_ertt.4 @@ -0,0 +1,140 @@ +.\" +.\" Copyright (c) 2010-2011 The FreeBSD Foundation +.\" +.\" This documentation was written at the Centre for Advanced Internet +.\" Architectures, Swinburne University of Technology, Melbourne, Australia by +.\" David Hayes under sponsorship from the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR +.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 18, 2012 +.Dt H_ERTT 4 +.Os +.Sh NAME +.Nm h_ertt +.Nd Enhanced Round Trip Time Khelp module +.Sh SYNOPSIS +.In netinet/khelp/h_ertt.h +.Sh DESCRIPTION +The +.Nm +Khelp module works within the +.Xr khelp 9 +framework to provide TCP with a per-connection, low noise estimate of the +instantaneous RTT. +The implementation attempts to be robust in the face of delayed +acknowledgements, TCP Segmentation Offload (TSO), receivers who manipulate TCP +timestamps and lack of the TCP timestamp option altogether. +.Pp +TCP receivers using delayed acknowledgements either acknowledge every second packet +(reflecting the time stamp of the first) or use a timeout to trigger the +acknowledgement if no second packet arrives. +If the heuristic used by +.Nm +determines that the receiver is using delayed acknowledgements, it measures the +RTT using the second packet (the one that triggers the acknowledgement). +It does not measure the RTT if the acknowledgement is for the +first packet, since it cannot be accurately determined. +.Pp +When TSO is in use, +.Nm +will momentarily disable TSO whilst marking a packet to use for a new +measurement. +The process has negligible impact on the connection. +.Pp +.Nm +associates the following struct with each connection's TCP control block: +.Bd -literal +struct ertt { + TAILQ_HEAD(txseginfo_head, txseginfo) txsegi_q; /* Private. */ + long bytes_tx_in_rtt; /* Private. */ + long bytes_tx_in_marked_rtt; + unsigned long marked_snd_cwnd; + int rtt; + int maxrtt; + int minrtt; + int dlyack_rx; /* Private. */ + int timestamp_errors; /* Private. */ + int markedpkt_rtt; /* Private. */ + uint32_t flags; +}; +.Ed +.Pp +The fields marked as private should not be manipulated by any code outside of +the +.Nm +implementation. +The non-private fields provide the following data: +.Bl -tag -width ".Va bytes_tx_in_marked_rtt" -offset indent +.It Va bytes_tx_in_marked_rtt +The number of bytes transmitted in the +.Va markedpkt_rtt . +.It Va marked_snd_cwnd +The value of cwnd for the marked rtt measurement. +.It Va rtt +The most recent RTT measurement. +.It Va maxrtt +The longest RTT measurement that has been taken. +.It Va minrtt +The shortest RTT measurement that has been taken. +.It Va flags +The ERTT_NEW_MEASUREMENT flag will be set by the implementation when a new +measurement is available. +It is the responsibility of +.Nm +consumers to unset the flag if they wish to use it as a notification method for +new measurements. +.El +.Sh SEE ALSO +.Xr cc_chd 4 , +.Xr cc_hd 4 , +.Xr cc_vegas 4 , +.Xr mod_cc 4 , +.Xr hhook 9 , +.Xr khelp 9 +.Sh ACKNOWLEDGEMENTS +Development and testing of this software were made possible in part by grants +from the FreeBSD Foundation and Cisco University Research Program Fund at +Community Foundation Silicon Valley. +.Sh HISTORY +The +.Nm +module first appeared in +.Fx 9.0 . +.Pp +The module was first released in 2010 by David Hayes whilst working on the +NewTCP research project at Swinburne University of Technology's Centre for +Advanced Internet Architectures, Melbourne, Australia. +More details are available at: +.Pp +http://caia.swin.edu.au/urp/newtcp/ +.Sh AUTHORS +.An -nosplit +The +.Nm +Khelp module and this manual page were written by +.An David Hayes Aq Mt david.hayes@ieee.org . +.Sh BUGS +The module maintains enhanced RTT estimates for all new TCP connections created +after the time at which the module was loaded. +It might be beneficial to see if it is possible to have the module only affect +connections which actually care about ERTT estimates. diff --git a/static/freebsd/man4/hconf.4 b/static/freebsd/man4/hconf.4 new file mode 100644 index 00000000..179d95a2 --- /dev/null +++ b/static/freebsd/man4/hconf.4 @@ -0,0 +1,88 @@ +.\" Copyright (c) 2020 Vladimir Kondratyev +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 18, 2021 +.Dt HCONF 4 +.Os +.Sh NAME +.Nm hconf +.Nd MS Windows Precision Touchpad configuration driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device hconf" +.Cd "device hid" +.Cd "device hidbus" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hconf_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for generic MS Windows Precision Touchpad +configuration collection. +It enables the host to configure two different aspects of the device. +One allows the host to select input mode, and the other allows the host to be +selective in what is reported. +.Sh SYSCTL VARIABLES +Next parameters are available as +.Xr sysctl 8 +variables. +Debug parameter is available as +.Xr loader 8 +tunable as well. +.Bl -tag -width indent +.It Va dev.hconf.*.input_mode +HID device input mode: 0 = mouse, 3 = touchpad. +.It Va dev.hconf.*.surface_switch +Enable / disable switch for surface: 1 = on, 0 = off. +.It Va dev.hconf.*.buttons_switch +Enable / disable switch for buttons: 1 = on, 0 = off. +.It Va hw.hid.hconf.debug +Debug output level, where 0 is debugging disabled and larger values increase +debug message verbosity. +Default is 0. +.El +.Sh SEE ALSO +.Xr hms 4 , +.Xr hmt 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org . +Switch parameter support was added by +.An Andriy Gapon Aq Mt avg@FreeBSD.org . diff --git a/static/freebsd/man4/hcons.4 b/static/freebsd/man4/hcons.4 new file mode 100644 index 00000000..6cdf0a7d --- /dev/null +++ b/static/freebsd/man4/hcons.4 @@ -0,0 +1,96 @@ +.\" Copyright (c) 2020 Vladimir Kondratyev +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 23, 2021 +.Dt HCONS 4 +.Os +.Sh NAME +.Nm hcons +.Nd HID consumer page controls driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device hcons" +.Cd "device hid" +.Cd "device hidbus" +.Cd "device hidmap" +.Cd "device evdev" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hcons_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for HID consumer page controls most often used as +"Multimedia keys" found on many keyboards. +.Pp +The +.Pa /dev/input/event* +device presents the consumer page controls as a +.Ar evdev +type device. +.Sh SYSCTL VARIABLES +The following variable is available as both +.Xr sysctl 8 +variable and +.Xr loader 8 +tunable: +.Bl -tag -width indent +.It Va dev.hcons.X.debug +Debug output level, where 0 is debugging disabled and larger values increase +debug message verbosity. +Default is 0. +.El +.Pp +It default value is set with +.Xr loader 8 +tunable: +.Bl -tag -width indent +.It Va hw.hid.hcons.debug +.El +.Sh FILES +.Bl -tag -width /dev/input/event* -compact +.It Pa /dev/input/event* +input event device node. +.El +.Sh SEE ALSO +.Xr iichid 4 , +.Xr usbhid 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org . diff --git a/static/freebsd/man4/hgame.4 b/static/freebsd/man4/hgame.4 new file mode 100644 index 00000000..dd69d9ef --- /dev/null +++ b/static/freebsd/man4/hgame.4 @@ -0,0 +1,130 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2020 Vladimir Kondratyev +.\" +.\" 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 November 30, 2025 +.Dt HGAME 4 +.Os +.Sh NAME +.Nm hgame +.Nd generic HID gamepad, joystick, and controller evdev driver +.Sh SYNOPSIS +.Cd device hgame +.Cd device hid +.Cd device hidbus +.Cd device hidmap +.Cd device evdev +.Pp +In +.Xr sysctl.conf 5 : +.Cd dev.hgame.X.debug +.Pp +In +.Xr loader.conf 5 : +.Cd hw.hid.hgame.debug +.Cd hgame_load +.Sh DESCRIPTION +The +.Nm +driver supports generic game controllers +that attach to the HID transport backend, +and presents them to applications over the +.Sy evdev +interface. +.Pp +If the appropriate hardware is detected, +the driver will be loaded automatically by +.Xr devmatch 8 . +To load the driver manually at boot time, set the +.Va hgame_load +variable to +.Ar YES +at the +.Xr loader 8 +prompt, or add it to +.Xr loader.conf 5 . +.Pp +To give user applications access to the game controllers, +allow user access to the +.Pa /dev/input/event* +nodes with inclusion of user in the +.Em games +group. +.Sh HARDWARE +The +.Nm +driver supports HID gamepads, joysticks, and controllers such as: +.Pp +.Bl -bullet -compact +.It +8bitdo USB Wireless Adapter 2 +.El +.Sh SYSCTL VARIABLES +The following variable is available as both +.Xr sysctl 8 +variable and +.Xr loader 8 +tunable: +.Bl -tag -width indent +.It Va dev.hgame.X.debug +Debug output level, +where 0 is debugging disabled and +larger values increase debug message verbosity. +Default is 0. +.El +.Pp +Its default value is set with +.Xr loader 8 +tunable: +.Bl -tag -width indent +.It Va hw.hid.hgame.debug +.El +.Sh FILES +.Bl -tag -width "/dev/input/event*" -compact +.It Pa /dev/input/event* +input event device +.Pq Sy evdev +node +.El +.Sh SEE ALSO +.Xr iichid 4 , +.Xr ps4dshock 4 , +.Xr usbhid 4 , +.Xr xb360gp 4 , +.Xr devfs.rules 5 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Val Packett Aq Mt val@packett.cool . +.Pp +This manual page was written by +.An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org . diff --git a/static/freebsd/man4/hidbus.4 b/static/freebsd/man4/hidbus.4 new file mode 100644 index 00000000..f8ebaca8 --- /dev/null +++ b/static/freebsd/man4/hidbus.4 @@ -0,0 +1,100 @@ +.\" Copyright (c) 2020 Vladimir Kondratyev +.\" +.\" 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 September 14, 2020 +.Dt HIDBUS 4 +.Os +.Sh NAME +.Nm hidbus +.Nd generic HID bus driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device hidbus" +.Cd "device hid" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hidbus_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for multiple HID driver attachments to single HID +transport backend. +See +.Xr iichid 4 +or +.Xr usbhid 4 . +.Pp +Each HID device can have several components, e.g., a keyboard and +a mouse. +These components use different report identifiers (a byte) combined into +groups called collections to distinguish which one data is coming from. +The +.Nm +driver has other drivers attached that handle particular +kinds of devices and +.Nm +broadcasts data to all of them. +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va hw.hid.hidbus.debug +Debug output level, where 0 is debugging disabled and larger values increase +debug message verbosity. +Default is 0. +.El +.Sh SEE ALSO +.Xr hconf 4 , +.Xr hcons 4 , +.Xr hgame 4 , +.Xr hidraw 4 , +.Xr hkbd 4 , +.Xr hms 4 , +.Xr hmt 4 , +.Xr hpen 4 , +.Xr hsctrl 4 , +.Xr hskbd 4 , +.Xr iichid 4 , +.Xr usbhid 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org . diff --git a/static/freebsd/man4/hidquirk.4 b/static/freebsd/man4/hidquirk.4 new file mode 100644 index 00000000..6474f2a9 --- /dev/null +++ b/static/freebsd/man4/hidquirk.4 @@ -0,0 +1,143 @@ +.\" +.\" Copyright (c) 2010 AnyWi Technologies +.\" All rights reserved. +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd September 16, 2020 +.Dt HIDQUIRK 4 +.Os +.Sh NAME +.Nm hidquirk +.Nd HID quirks module +.Sh SYNOPSIS +To compile this module into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device hid" +.Ed +.Pp +Alternatively, to load the module at boot +time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hidquirk_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +module provides support for adding quirks for HID devices +.Bl -tag -width Ds +.It HQ_HID_IGNORE +device should be ignored by hid class +.It HQ_KBD_BOOTPROTO +device should set the boot protocol +.It HQ_MS_BOOTPROTO +device should set the boot protocol +.It HQ_MS_BAD_CLASS +doesn't identify properly +.It HQ_MS_LEADING_BYTE +mouse sends an unknown leading byte +.It HQ_MS_REVZ +mouse has Z-axis reversed +.It HQ_MS_VENDOR_BTN +mouse has buttons in vendor usage page +.It HQ_SPUR_BUT_UP +spurious mouse button up events +.It HQ_MT_TIMESTAMP +Multitouch device exports HW timestamps +.Dv 0x1b5a01 +.El +.Pp +See +.Pa /sys/dev/hid/hidquirk.h +for the complete list of supported quirks. +.Sh LOADER TUNABLE +The following tunable can be set at the +.Xr loader 8 +prompt before booting the kernel, or stored in +.Xr loader.conf 5 . +.Bl -tag -width indent +.It Va hw.hid.quirk.%d +The value is a string whose format is: +.Bd -literal -offset indent +.Qo BusId VendorId ProductId LowRevision HighRevision HQ_QUIRK,... Qc +.Ed +.Pp +Installs the quirks +.Ic HQ_QUIRK,... +for all HID devices matching +.Ic BusId +and +.Ic VendorId +and +.Ic ProductId +which have a hardware revision between and including +.Ic LowRevision +and +.Ic HighRevision . +.Pp +.Ic BusId , +.Ic VendorId , +.Ic ProductId , +.Ic LowRevision +and +.Ic HighRevision +are all 16 bits numbers which can be decimal or hexadecimal based. +.Pp +A maximum of 100 variables +.Ic hw.hid.quirk.0, .1, ..., .99 +can be defined. +.Pp +If a matching entry is found in the kernel's internal quirks table, it +is replaced by the new definition. +.Pp +Else a new entry is created given that the quirk table is not full. +.Pp +The kernel iterates over the +.Ic hw.hid.quirk.N +variables starting at +.Ic N = 0 +and stops at +.Ic N = 99 +or the first non-existing one. +.El +.Sh EXAMPLES +To install a quirk at boot time, place one or several lines like the +following in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hw.hid.quirk.0="0x18 0x6cb 0x1941 0 0xffff HQ_MT_TIMESTAMP" +.Ed +.Sh HISTORY +The +.Nm +module appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Hans Petter Selasky Aq Mt hselasky@FreeBSD.org +for +.Xr usb 4 +subsystem and adopted to +.Xr hid 4 +by +.An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org . +This manual page is based on +.Xr usb_quirk 4 +manual page written by +.An Nick Hibma Aq Mt n_hibma@FreeBSD.org . diff --git a/static/freebsd/man4/hidraw.4 b/static/freebsd/man4/hidraw.4 new file mode 100644 index 00000000..0353e49a --- /dev/null +++ b/static/freebsd/man4/hidraw.4 @@ -0,0 +1,314 @@ +.\" $NetBSD: uhid.4,v 1.13 2001/12/29 14:41:59 augustss Exp $ +.\" +.\" Copyright (c) 1999, 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Lennart Augustsson. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 27, 2025 +.Dt HIDRAW 4 +.Os +.Sh NAME +.Nm hidraw +.Nd Raw Access to HID devices +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device hidraw" +.Cd "device hid" +.Cd "device hidbus" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hidraw_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides a raw interface to Human Interface Devices (HIDs). +The reports are sent to and received from the device unmodified. +.Pp +The device handles 2 sets of +.Xr ioctl 2 +calls: +.Pp +.Fx +.Xr uhid 4 +\-compatible calls: +.Bl -tag -width indent +.It Dv HIDRAW_GET_REPORT_ID Pq Vt int +Get the report identifier used by this HID report. +.It Dv HIDRAW_GET_REPORT_DESC Pq Vt "struct hidraw_gen_descriptor" +Get the HID report descriptor. +Copies a maximum of +.Va hgd_maxlen +bytes of the report descriptor data into the memory +specified by +.Va hgd_data . +Upon return +.Va hgd_actlen +is set to the number of bytes copied. +Using +this descriptor the exact layout and meaning of data to/from +the device can be found. +The report descriptor is delivered +without any processing. +.Bd -literal +struct hidraw_gen_descriptor { + void *hgd_data; + uint16_t hgd_maxlen; + uint16_t hgd_actlen; + uint8_t hgd_report_type; + ... +}; +.Ed +.It Dv HIDRAW_SET_IMMED Pq Vt int +Sets the device in a mode where each +.Xr read 2 +will return the current value of the input report. +Normally +a +.Xr read 2 +will only return the data that the device reports on its +interrupt pipe. +This call may fail if the device does not support +this feature. +.It Dv HIDRAW_GET_REPORT Pq Vt "struct hidraw_gen_descriptor" +Get a report from the device without waiting for data on +the interrupt pipe. +Copies a maximum of +.Va hgd_maxlen +bytes of the report data into the memory specified by +.Va hgd_data . +Upon return +.Va hgd_actlen +is set to the number of bytes copied. +The +.Va hgd_report_type +field indicates which report is requested. +It should be +.Dv HID_INPUT_REPORT , +.Dv HID_OUTPUT_REPORT , +or +.Dv HID_FEATURE_REPORT . +On a device which uses numbered reports, the first byte of the returned data +is the report number. +The report data begins from the second byte. +For devices which do not use numbered reports, the report data begins at the +first byte. +This call may fail if the device does not support this feature. +.It Dv HIDRAW_SET_REPORT Pq Vt "struct hidraw_gen_descriptor" +Set a report in the device. +The +.Va hgd_report_type +field indicates which report is to be set. +It should be +.Dv HID_INPUT_REPORT , +.Dv HID_OUTPUT_REPORT , +or +.Dv HID_FEATURE_REPORT . +The value of the report is specified by the +.Va hgd_data +and the +.Va hgd_maxlen +fields. +On a device which uses numbered reports, the first byte of data to be sent is +the report number. +The report data begins from the second byte. +For devices which do not use numbered reports, the report data begins at the +first byte. +This call may fail if the device does not support this feature. +.It Dv HIDRAW_GET_DEVICEINFO Pq Vt "struct hidraw_device_info" +Returns information about the device, like vendor ID and product ID. +This call will not issue any hardware transfers. +.El +.Pp +Linux +.Nm +\-compatible calls: +.Bl -tag -width indent +.It Dv HIDIOCGRDESCSIZE Pq Vt int +Get the HID report descriptor size. +Returns the size of the device report descriptor to use with +.Dv HIDIOCGRDESC +.Xr ioctl 2 . +.It Dv HIDIOCGRDESC Pq Vt "struct hidraw_report_descriptor" +Get the HID report descriptor. +Copies a maximum of +.Va size +bytes of the report descriptor data into the memory +specified by +.Va value . +.Bd -literal +struct hidraw_report_descriptor { + uint32_t size; + uint8_t value[HID_MAX_DESCRIPTOR_SIZE]; +}; +.Ed +.It Dv HIDIOCGRAWINFO Pq Vt "struct hidraw_devinfo" +Get structure containing the bus type, the vendor ID (VID), and product ID +(PID) of the device. +The bus type can be one of: +.Dv BUS_USB +or +.Dv BUS_I2C +which are defined in dev/evdev/input.h. +.Bd -literal +struct hidraw_devinfo { + uint32_t bustype; + int16_t vendor; + int16_t product; +}; +.Ed +.It Dv HIDIOCGRAWNAME(len) Pq Vt "char[] buf" +Get device description. +Copies a maximum of +.Va len +bytes of the device description previously set with +.Xr device_set_desc 9 +procedure into the memory +specified by +.Va buf . +.It Dv HIDIOCGRAWPHYS(len) Pq Vt "char[] buf" +Get the newbus path to the device. +.\"For Bluetooth devices, it returns the hardware (MAC) address of the device. +Copies a maximum of +.Va len +bytes of the newbus device path +into the memory +specified by +.Va buf . +.It Dv HIDIOCGFEATURE(len) Pq Vt "void[] buf" +.It Dv HIDIOCGINPUT(len) Pq Vt "void[] buf" +.It Dv HIDIOCGOUTPUT(len) Pq Vt "void[] buf" +Get respectively a feature, input or output report from the device. +Copies a maximum of +.Va len +bytes of the report data into the memory specified by +.Va buf . +The first byte of the supplied buffer should be set to the report +number of the requested report. +For devices which do not use numbered reports, set the first byte to 0. +The report will be returned starting at the first byte of the buffer +(ie: the report number is not returned). +This call may fail if the device does not support this feature. +.It Dv HIDIOCSFEATURE(len) Pq Vt "void[] buf" +.It Dv HIDIOCSINPUT(len) Pq Vt "void[] buf" +.It Dv HIDIOCSOUTPUT(len) Pq Vt "void[] buf" +Set respectively a feature, input or output Report in the device. +The value of the report is specified by the +.Va buf +and the +.Va len +parameters. +Set the first byte of the supplied buffer to the report number. +For devices which do not use numbered reports, set the first byte to 0. +The report data begins in the second byte. +Make sure to set len accordingly, to one more than the length of the report +(to account for the report number). +This call may fail if the device does not support this feature. +.El +.Pp +Use +.Xr read 2 +to get data from the device. +Data should be read in chunks of the +size prescribed by the report descriptor. +On a device which uses numbered reports, the first byte of the returned data +is the report number. +The report data begins from the second byte. +For devices which do not use numbered reports, the report data begins at the +first byte. +.Pp +Use +.Xr write 2 +to send data to the device. +Data should be written in chunks of the +size prescribed by the report descriptor. +The first byte of the buffer passed to +.Xr write 2 +should be set to the report number. +If the device does not use numbered reports, there are 2 operation modes: +.Nm +mode and +.Xr uhid 4 +mode. +In the +.Nm +mode, the first byte should be set to 0 and the report data itself should +begin at the second byte. +In the +.Xr uhid 4 +mode, the report data should begin at the first byte. +The modes can be switched with issuing one of +.Dv HIDIOCGRDESC +or +.Dv HID_GET_REPORT_DESC +.Xr ioctl 2 +accordingly. +Default mode is +.Nm . +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va hw.hid.hidraw.debug +Debug output level, where 0 is debugging disabled and larger values increase +debug message verbosity. +Default is 0. +.El +.Sh FILES +.Bl -tag -width ".Pa /dev/hidraw?" +.It Pa /dev/hidraw? +.El +.Sh SEE ALSO +.Xr usbhidctl 1 , +.Xr hid 4 , +.Xr hidbus 4 , +.Xr uhid 4 +.Sh HISTORY +The +.Xr uhid 4 +driver +appeared in +.Nx 1.4 . +.Nm +protocol support was added in +.Fx 13 +by +.An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org . +This manual page was adopted from +.Nx +by +.An Tom Rhodes Aq Mt trhodes@FreeBSD.org +in April 2002. diff --git a/static/freebsd/man4/hkbd.4 b/static/freebsd/man4/hkbd.4 new file mode 100644 index 00000000..4aefad10 --- /dev/null +++ b/static/freebsd/man4/hkbd.4 @@ -0,0 +1,205 @@ +.\" Copyright (c) 1997, 1998 +.\" Nick Hibma . 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 April 23, 2026 +.Dt HKBD 4 +.Os +.Sh NAME +.Nm hkbd +.Nd HID keyboard driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device hkbd" +.Cd "device hid" +.Cd "device hidbus" +.Cd "device evdev" +.Cd "options EVDEV_SUPPORT" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hkbd_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for keyboards that attach to the HID transport +backend. +.Xr hid 4 , +.Xr hidbus 4 , +and one of +.Xr iichid 4 +or +.Xr usbhid 4 +must be configured in the kernel as well. +.Sh CONFIGURATION +By default, the keyboard subsystem does not create the appropriate devices yet. +Make sure you reconfigure your kernel with the following option in the kernel +config file: +.Pp +.Dl "options KBD_INSTALL_CDEV" +.Pp +If both an AT keyboard HID keyboards are used at the same time, the +AT keyboard will appear as +.Pa kbd0 +in +.Pa /dev . +The HID keyboards will be +.Pa kbd1 , kbd2 , +etc. +You can see some information about the keyboard with the following command: +.Pp +.Dl "kbdcontrol -i < /dev/kbd1" +.Pp +or load a keymap with +.Pp +.Dl "kbdcontrol -l keymaps/pt.iso < /dev/kbd1" +.Pp +See +.Xr kbdcontrol 1 +for more possible options. +.Pp +You can swap console keyboards by using the command +.Pp +.Dl "kbdcontrol -k /dev/kbd1" +.Pp +From this point on, the first HID keyboard will be the keyboard +to be used by the console. +.Pp +If you want to use a HID keyboard as your default and not use an AT keyboard at +all, you will have to remove the +.Cd "device atkbd" +line from the kernel configuration file. +Because of the device initialization order, +the HID keyboard will be detected +.Em after +the console driver +initializes itself and you have to explicitly tell the console +driver to use the existence of the HID keyboard. +This can be done in +one of the following two ways. +.Pp +Run the following command as a part of system initialization: +.Pp +.Dl "kbdcontrol -k /dev/kbd0 < /dev/ttyv0 > /dev/null" +.Pp +(Note that as the HID keyboard is the only keyboard, it is accessed as +.Pa /dev/kbd0 ) +or otherwise tell the console driver to periodically look for a +keyboard by setting a flag in the kernel configuration file: +.Pp +.Dl "device sc0 at isa? flags 0x100" +.Pp +With the above flag, the console driver will try to detect any +keyboard in the system if it did not detect one while it was +initialized at boot time. +.Sh DRIVER CONFIGURATION +.D1 Cd "options KBD_INSTALL_CDEV" +.Pp +Make the keyboards available through a character device in +.Pa /dev . +.Pp +.D1 Cd options HKBD_DFLT_KEYMAP +.D1 Cd makeoptions HKBD_DFLT_KEYMAP=fr.iso +.Pp +The above lines will put the French ISO keymap in the ukbd driver. +You can specify any keymap in +.Pa /usr/share/syscons/keymaps +or +.Pa /usr/share/vt/keymaps +(depending on the console driver being used) with this option. +.Pp +.D1 Cd "options KBD_DISABLE_KEYMAP_LOADING" +.Pp +Do not allow the user to change the keymap. +Note that these options also affect the AT keyboard driver, +.Xr atkbd 4 . +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va hw.hid.hkbd.debug +Debug output level, where 0 is debugging disabled and larger values increase +debug message verbosity. +Default is 0. +.It Va hw.hid.hkbd.apple_swap_cmd_opt +Swap the Command & Option keys on Apple keyboards if set to 1. +Default is 0. +.It Va hw.hid.hkbd.apple_swap_cmd_ctl +Swap the Command & Control keys on Apple keyboards if set to 1. +Default is 0. +.It Va hw.hid.hkbd.apple_fn_mode +Direct access to media keys without holding Fn if set to 1. +Default is 0. +.It Va hw.hid.hkbd.no_leds +Disables setting of keyboard LEDs if set to 1. +Default is 0. +.El +.Sh FILES +.Bl -tag -width ".Pa /dev/input/event*" -compact +.It Pa /dev/kbd* +blocking device nodes +.It Pa /dev/input/event* +input event device nodes. +.El +.Sh EXAMPLES +.D1 Cd "device hkbd" +.Pp +Add the +.Nm +driver to the kernel. +.Sh SEE ALSO +.Xr kbdcontrol 1 , +.Xr hid 4 , +.Xr hidbus 4 , +.Xr iichid 4 , +.Xr syscons 4 , +.Xr usbhid 4 , +.Xr vt 4 , +.Xr config 8 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Lennart Augustsson Aq Mt augustss@cs.chalmers.se +for +.Nx +and was substantially rewritten for +.Fx +by +.An Kazutaka YOKOTA Aq Mt yokota@zodiac.mech.utsunomiya-u.ac.jp . +.Pp +This manual page was written by +.An Nick Hibma Aq Mt n_hibma@FreeBSD.org +with a large amount of input from +.An Kazutaka YOKOTA Aq Mt yokota@zodiac.mech.utsunomiya-u.ac.jp . diff --git a/static/freebsd/man4/hms.4 b/static/freebsd/man4/hms.4 new file mode 100644 index 00000000..1f9738db --- /dev/null +++ b/static/freebsd/man4/hms.4 @@ -0,0 +1,113 @@ +.\" Copyright (c) +.\" 1999 Nick Hibma . All rights reserved. +.\" 2020 Vladimir Kondratyev . +.\" +.\" 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 September 12, 2020 +.Dt HMS 4 +.Os +.Sh NAME +.Nm hms +.Nd HID mouse driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device hms" +.Cd "device hidbus" +.Cd "device hid" +.Cd "device evdev" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hms_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for HID mice that attach to the HID transport +backend. +See +.Xr iichid 4 +or +.Xr usbhid 4 . +Supported are +mice with any number of buttons, mice with a wheel and absolute mice. +.Pp +The +.Pa /dev/input/eventX +device presents the mouse as a +.Ar evdev +type device. +.Sh SYSCTL VARIABLES +The following variable is available as both +.Xr sysctl 8 +variable and +.Xr loader 8 +tunable: +.Bl -tag -width indent +.It Va dev.hms.X.debug +Debug output level, where 0 is debugging disabled and larger values increase +debug message verbosity. +Default is 0. +.El +.Pp +It default value is derived from +.Xr loader 8 +tunable: +.Bl -tag -width indent +.It Va hw.hid.hms.debug +.El +.Sh FILES +.Bl -tag -width /dev/input/eventX -compact +.It Pa /dev/input/eventX +input event device node. +.El +.Sh SEE ALSO +.Xr iichid 4 , +.Xr usbhid 4 , +.Xr xorg.conf 5 Pq Pa ports/x11/xorg +.\".Xr moused 8 +.Sh BUGS +.Nm +cannot act like +.Xr sysmouse 4 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org . +.Pp +This manual page was originally written by +.An Nick Hibma Aq Mt n_hibma@FreeBSD.org +for +.Xr umt 4 +driver and was adopted for +.Nm +by +.An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org . diff --git a/static/freebsd/man4/hmt.4 b/static/freebsd/man4/hmt.4 new file mode 100644 index 00000000..b2eb68d8 --- /dev/null +++ b/static/freebsd/man4/hmt.4 @@ -0,0 +1,77 @@ +.\" Copyright (c) 2014-2020 Vladimir Kondratyev +.\" 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 August 11, 2020 +.Dt HMT 4 +.Os +.Sh NAME +.Nm hmt +.Nd MS Windows 7/8/10 - compatible HID multi-touch device driver +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines into +your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device hmt" +.Cd "device hidbus" +.Cd "device hid" +.Cd "device hconf" +.Cd "device evdev" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hmt_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the MS Windows 7/8/10 - compatible HID +multi-touch devices found in many laptops. +.Pp +To get multi-touch device working in +.Xr X 7 Pq Pa ports/x11/xorg-docs , +install +.Pa ports/x11-drivers/xf86-input-evdev . +.Sh FILES +.Nm +creates a pseudo-device file, +.Pa /dev/input/eventX +which presents the multi-touch device as an input event device. +.Sh SEE ALSO +.Xr hid 4 , +.Xr loader.conf 5 , +.Xr xorg.conf 5 Pq Pa ports/x11/xorg , +.Xr evdev 4 Pq Pa ports/x11-drivers/xf86-input-evdev . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org . +.Sh BUGS +.Nm +cannot act like +.Xr sysmouse 4 diff --git a/static/freebsd/man4/hpen.4 b/static/freebsd/man4/hpen.4 new file mode 100644 index 00000000..d3b69ff1 --- /dev/null +++ b/static/freebsd/man4/hpen.4 @@ -0,0 +1,110 @@ +.\" Copyright (c) 2020 Vladimir Kondratyev +.\" +.\" 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 September 14, 2020 +.Dt HPEN 4 +.Os +.Sh NAME +.Nm hpen +.Nd MS Windows compatible HID pen tablet driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device hpen" +.Cd "device hid" +.Cd "device hidbus" +.Cd "device hidmap" +.Cd "device evdev" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hpen_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for generic MS Windows compatible HID pen tablet +and digitizer that attach to the HID transport backend. +See +.Xr iichid 4 +or +.Xr usbhid 4 . +.Pp +The +.Pa /dev/input/event* +device presents the pen as a +.Ar evdev +type device. +.Sh SYSCTL VARIABLES +The following variable is available as both +.Xr sysctl 8 +variable and +.Xr loader 8 +tunable: +.Bl -tag -width indent +.It Va dev.hpen.X.debug +Debug output level, where 0 is debugging disabled and larger values increase +debug message verbosity. +Default is 0. +.El +.Pp +It's default value is set with +.Xr loader 8 +tunable: +.Bl -tag -width indent +.It Va hw.hid.hpen.debug +.El +.Sh FILES +.Bl -tag -width /dev/input/event* -compact +.It Pa /dev/input/event* +input event device node. +.El +.Sh SEE ALSO +.Xr iichid 4 , +.Xr usbhid 4 , +.Xr xorg.conf 5 Pq Pa ports/x11/xorg +.Sh BUGS +.Nm +cannot act like +.Xr sysmouse 4 . +.Pp +Pen battery charge level reporting is not supported. +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Val Packett Aq Mt val@packett.cool . +.Pp +This manual page was written by +.An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org . diff --git a/static/freebsd/man4/hpet.4 b/static/freebsd/man4/hpet.4 new file mode 100644 index 00000000..684549df --- /dev/null +++ b/static/freebsd/man4/hpet.4 @@ -0,0 +1,110 @@ +.\" Copyright (c) 2010 Alexander Motin +.\" 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 September 14, 2010 +.Dt HPET 4 +.Os +.Sh NAME +.Nm hpet +.Nd High Precision Event Timer driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device acpi" +.Ed +.Pp +The following tunables are settable from the +.Xr loader 8 : +.Bl -ohang +.It Va hint.hpet. Ns Ar X Ns Va .allowed_irqs +is a 32bit mask. +Each set bit allows driver to use respective IRQ, +if BIOS also set respective capability bit in comparator's configuration +register. +Default value is 0xffff0000, except some known broken hardware. +.It Va hint.hpet. Ns Ar X Ns Va .clock +controls event timers functionality support. +Setting to 0, disables it. +Default value is 1. +.It Va hint.hpet. Ns Ar X Ns Va .legacy_route +controls "LegacyReplacement Route" mode. +If enabled, HPET will steal IRQ0 of i8254 timer and IRQ8 of RTC. +Before using it, make sure that respective +drivers are not using interrupts, by setting also: +.Bd -literal +hint.attimer.0.clock=0 +hint.atrtc.0.clock=0 +.Ed +Default value is 0. +.It Va hint.hpet. Ns Ar X Ns Va .per_cpu +controls how much per-CPU event timers should driver attempt to register. +This functionality requires every comparator in a group to have own unshared +IRQ, so it depends on hardware capabilities and interrupts configuration. +Default value is 1. +.El +.Sh DESCRIPTION +This driver uses High Precision Event Timer hardware (part of the chipset, +usually enumerated via ACPI) to supply kernel with one time counter and +several (usually from 3 to 8) event timers. +This hardware includes single main counter with known increment frequency +(10MHz or more), and several programmable comparators (optionally with +automatic reload feature). +When value of the main counter matches current value of any comparator, +interrupt can be generated. +Depending on hardware capabilities and configuration, interrupt can be +delivered as regular I/O APIC interrupt (ISA or PCI) in range from 0 to 31, +or as Front Side Bus interrupt, alike to PCI MSI interrupts, or in so called +"LegacyReplacement Route" HPET can steal IRQ0 of i8254 and IRQ8 of the RTC. +Interrupt can be either edge- or level-triggered. +In last case they could be safely shared with PCI IRQs. +Driver prefers to use FSB interrupts, if supported, to avoid sharing. +If it is not possible, it uses single sharable IRQ from PCI range. +Other modes (LegacyReplacement and ISA IRQs) require special care to setup, +but could be configured manually via device hints. +.Pp +Event timers provided by the driver support both one-shot an periodic modes +and irrelevant to CPU power states. +.Pp +Depending on hardware capabilities and configuration, driver can expose each +comparator as separate event timer or group them into one or several per-CPU +event timers. +In last case interrupt of every of those comparators within +group is bound to specific CPU core. +This is possible only when each of these comparators has own unsharable IRQ. +.Sh SEE ALSO +.Xr acpi 4 , +.Xr apic 4 , +.Xr atrtc 4 , +.Xr attimer 4 , +.Xr eventtimers 4 , +.Xr timecounters 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 6.3 . +Support for event timers was added in +.Fx 9.0 . diff --git a/static/freebsd/man4/hpt27xx.4 b/static/freebsd/man4/hpt27xx.4 new file mode 100644 index 00000000..bec0c711 --- /dev/null +++ b/static/freebsd/man4/hpt27xx.4 @@ -0,0 +1,99 @@ +.\" +.\" Copyright (c) 2011 iXsystems, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY 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 28, 2011 +.Dt HPT27XX 4 +.Os +.Sh NAME +.Nm hpt27xx +.Nd "HighPoint RocketRAID 27xx SAS 6Gb/s HBA card driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device hpt27xx" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hpt27xx_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for HighPoint's RocketRAID 27xx based RAID controller. +.Pp +These devices support SAS disk drives +and provide RAID0 (striping), RAID1 (mirroring), and RAID5 functionality. +.Sh HARDWARE +The +.Nm +driver supports the following SAS +controllers: +.Pp +.Bl -bullet -compact +.It +HighPoint's RocketRAID 271x series +.It +HighPoint's RocketRAID 272x series +.It +HighPoint's RocketRAID 274x series +.It +HighPoint's RocketRAID 276x series +.It +HighPoint's RocketRAID 278x series +.El +.Sh NOTES +The +.Nm +driver only works on the i386 and amd64 platforms as it requires a binary +blob object from the manufacturer which they only supply for these platforms. +The +.Nm +driver does +.Em not +work on i386 with +.Xr pae 4 +enabled. +.Sh SEE ALSO +.Xr kld 4 , +.Xr kldload 8 , +.Xr loader 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 10.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +device driver was written by +.An HighPoint Technologies, Inc. . +This manual page was written by +.An Xin LI Aq Mt delphij@FreeBSD.org +for iXsystems, Inc. diff --git a/static/freebsd/man4/hptiop.4 b/static/freebsd/man4/hptiop.4 new file mode 100644 index 00000000..7ab8cf98 --- /dev/null +++ b/static/freebsd/man4/hptiop.4 @@ -0,0 +1,137 @@ +.\" Copyright (c) 2007 Christian Brueffer +.\" 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 5, 2013 +.Dt HPTIOP 4 +.Os +.Sh NAME +.Nm hptiop +.Nd "HighPoint RocketRAID 3xxx/4xxx device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device hptiop" +.Cd "device scbus" +.Cd "device da" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hptiop_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the HighPoint RocketRAID 3xxx/4xxx series +of SAS and SATA RAID controllers. +.Sh HARDWARE +The +.Nm +driver supports the following SAS and SATA RAID controllers: +.Pp +.Bl -bullet -compact +.It +HighPoint RocketRAID 4522 +.It +HighPoint RocketRAID 4521 +.It +HighPoint RocketRAID 4520 +.It +HighPoint RocketRAID 4322 +.It +HighPoint RocketRAID 4321 +.It +HighPoint RocketRAID 4320 +.It +HighPoint RocketRAID 4311 +.It +HighPoint RocketRAID 4310 +.It +HighPoint RocketRAID 3640 +.It +HighPoint RocketRAID 3622 +.It +HighPoint RocketRAID 3620 +.El +.Pp +The +.Nm +driver also supports the following SAS and SATA RAID controllers that +are already End-of-Life: +.Pp +.Bl -bullet -compact +.It +HighPoint RocketRAID 4211 +.It +HighPoint RocketRAID 4210 +.It +HighPoint RocketRAID 3560 +.It +HighPoint RocketRAID 3540 +.It +HighPoint RocketRAID 3530 +.It +HighPoint RocketRAID 3522 +.It +HighPoint RocketRAID 3521 +.It +HighPoint RocketRAID 3520 +.It +HighPoint RocketRAID 3511 +.It +HighPoint RocketRAID 3510 +.It +HighPoint RocketRAID 3410 +.It +HighPoint RocketRAID 3320 +.It +HighPoint RocketRAID 3220 +.It +HighPoint RocketRAID 3122 +.It +HighPoint RocketRAID 3120 +.It +HighPoint RocketRAID 3020 +.El +.Sh NOTES +The +.Nm +driver has only been tested on the i386 and amd64 platforms. +.Sh SEE ALSO +.Xr cam 4 , +.Xr hptmv 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 7.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An HighPoint Technologies, Inc. diff --git a/static/freebsd/man4/hptmv.4 b/static/freebsd/man4/hptmv.4 new file mode 100644 index 00000000..75cf442b --- /dev/null +++ b/static/freebsd/man4/hptmv.4 @@ -0,0 +1,99 @@ +.\" +.\" Copyright (c) 2004 David E. O'Brien +.\" 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 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 November 17, 2005 +.Dt HPTMV 4 +.Os +.Sh NAME +.Nm hptmv +.Nd "HighPoint RocketRAID 182x device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device hptmv" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hptmv_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for HighPoint's RocketRAID 182x based RAID controller. +.Pp +These devices support ATA disk drives +and provide RAID0 (striping), RAID1 (mirroring), and RAID5 functionality. +.Sh HARDWARE +The +.Nm +driver supports the following ATA RAID +controllers: +.Pp +.Bl -bullet -compact +.It +HighPoint's RocketRAID 182x series +.El +.Sh NOTES +The +.Nm +driver only works on the i386 and amd64 platforms as it requires a binary +blob object from the manufacturer which they only supply for these platforms. +The +.Nm +driver does +.Em not +work on i386 with +.Xr pae 4 +enabled. +.Sh SEE ALSO +.Xr kld 4 , +.Xr kldload 8 , +.Xr loader 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 5.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm +device driver was written by +.An HighPoint Technologies, Inc. , +and ported to +.Fx +by +.An Scott Long . +This manual page was written by +.An David E. O'Brien . +.Sh BUGS +The +.Nm +driver does not support manipulating the RAID from the OS, RAIDs need +to be set up from the on-board BIOS. diff --git a/static/freebsd/man4/hptnr.4 b/static/freebsd/man4/hptnr.4 new file mode 100644 index 00000000..3e0e4e56 --- /dev/null +++ b/static/freebsd/man4/hptnr.4 @@ -0,0 +1,90 @@ +.\"- +.\" Copyright (c) 2013 iXsystems, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY 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 July 5, 2013 +.Dt HPTNR 4 +.Os +.Sh NAME +.Nm hptnr +.Nd "HighPoint DC Series Data Center HBA card driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device hptnr" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hptnr_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for HighPoint's DC Series Data Center HBA card. +.Sh HARDWARE +The +.Nm +driver supports the following SATA +controllers: +.Pp +.Bl -bullet -compact +.It +HighPoint's DC7280 series +.It +HighPoint's Rocket R750 series +.El +.Sh NOTES +The +.Nm +driver only works on the i386 and amd64 platforms as it requires a binary +blob object from the manufacturer which they only supply for these platforms. +The +.Nm +driver does +.Em not +work on i386 with +.Xr pae 4 +enabled. +.Sh SEE ALSO +.Xr kld 4 , +.Xr kldload 8 , +.Xr loader 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 9.2 . +.Sh AUTHORS +.An -nosplit +The +.Nm +device driver was written by +.An HighPoint Technologies, Inc. . +This manual page was written by +.An Xin LI Aq Mt delphij@FreeBSD.org +for iXsystems, Inc. diff --git a/static/freebsd/man4/hptrr.4 b/static/freebsd/man4/hptrr.4 new file mode 100644 index 00000000..6f284eba --- /dev/null +++ b/static/freebsd/man4/hptrr.4 @@ -0,0 +1,140 @@ +.\" +.\" Copyright (c) 2007 Me +.\" 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 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 June 6, 2012 +.Dt HPTRR 4 +.Os +.Sh NAME +.Nm hptrr +.Nd "HighPoint RocketRAID device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device hptrr" +.Cd "device scbus" +.Cd "device da" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hptrr_load="YES" +.Ed +.Pp +The following tunables are settable from the loader: +.Bl -ohang +.It Va hw.hptrr.attach_generic +set to 1 to permit driver attach to chips with generic Marvell (non-HighPoint) +PCI identification. +These chips are also supported by +.Xr ata 4 +and +.Xr mvs 4 . +Some vendors are using same chips, but without providing RAID BIOS. +.El +.Sh DESCRIPTION +The +.Nm +driver provides support for HighPoint's RocketRAID based RAID controllers. +.Pp +These devices support SATA/ATA disk drives +and provide RAID0 (striping), RAID1 (mirroring), and RAID5 functionality. +.Sh HARDWARE +The +.Nm +driver supports the following RAID +controllers: +.Pp +.Bl -bullet -compact +.It +RocketRAID 172x series +.It +RocketRAID 174x series +.It +RocketRAID 2210 +.It +RocketRAID 222x series +.It +RocketRAID 2240 +.It +RocketRAID 230x series +.It +RocketRAID 231x series +.It +RocketRAID 232x series +.It +RocketRAID 2340 +.It +RocketRAID 2522 +.El +.Sh NOTES +The +.Nm +driver only works on the i386 and amd64 platforms as it requires a binary +blob object from the manufacturer which they only supply for these platforms. +The +.Nm +driver does +.Em not +work on i386 with +.Xr pae 4 +enabled. +.Pp +This driver does not support the RR182x series controller. +See the +.Xr hptmv 4 +manual page for details on support. +.Pp +This driver supersedes the older rr232x driver. +.Sh SEE ALSO +.Xr ata 4 , +.Xr cam 4 , +.Xr hptmv 4 , +.Xr mvs 4 , +.Xr loader 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 6.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm +device driver was written by +.An HighPoint Technologies, Inc. , +and ported to +.Fx +by +.An Scott Long . +This manual page was written by +.An David E. O'Brien . +.Sh BUGS +The +.Nm +driver does not support manipulating the RAID from the OS, RAIDs need +to be set up from the on-board BIOS. diff --git a/static/freebsd/man4/hsctrl.4 b/static/freebsd/man4/hsctrl.4 new file mode 100644 index 00000000..fa8ae897 --- /dev/null +++ b/static/freebsd/man4/hsctrl.4 @@ -0,0 +1,96 @@ +.\" Copyright (c) 2020 Vladimir Kondratyev +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 26, 2021 +.Dt HSCTRL 4 +.Os +.Sh NAME +.Nm hsctrl +.Nd HID system controls driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device hsctrl" +.Cd "device hid" +.Cd "device hidbus" +.Cd "device hidmap" +.Cd "device evdev" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hsctrl_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for HID system controls most often used as +"Power off/Sleep keys" found on many keyboards. +.Pp +The +.Pa /dev/input/event* +device presents the consumer page controls as a +.Ar evdev +type device. +.Sh SYSCTL VARIABLES +The following variable is available as both +.Xr sysctl 8 +variable and +.Xr loader 8 +tunable: +.Bl -tag -width indent +.It Va dev.hsctrl.X.debug +Debug output level, where 0 is debugging disabled and larger values increase +debug message verbosity. +Default is 0. +.El +.Pp +It default value is set with +.Xr loader 8 +tunable: +.Bl -tag -width indent +.It Va hw.hid.hsctrl.debug +.El +.Sh FILES +.Bl -tag -width /dev/input/event* -compact +.It Pa /dev/input/event* +input event device node. +.El +.Sh SEE ALSO +.Xr iichid 4 , +.Xr usbhid 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org . diff --git a/static/freebsd/man4/htu21.4 b/static/freebsd/man4/htu21.4 new file mode 100644 index 00000000..81af7518 --- /dev/null +++ b/static/freebsd/man4/htu21.4 @@ -0,0 +1,132 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2021 Andriy Gapon +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 19, 2021 +.Dt HTU21 4 +.Os +.Sh NAME +.Nm htu21 +.Nd driver for HTU21D and compatible temperature and humidity sensors +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device htu21" +.Cd "device iicbus" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +htu21_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides temperature and relative humidity readings over I2C bus +for the supported sensors: +.Bl -bullet -compact +.It +HTU21D +.It +SHT21 +.It +Si7021 +.El +.Pp +The +.Nm +driver reports data via +.Xr sysctl 8 +entries in the device's node in the +.Xr sysctl 8 +tree: +.Bl -tag -width temperature +.It temperature +The temperature, in hundredths of Kelvin. +.It humidity +The relative humidity, in hundredths of a percent. +.It crc_errors +The number of CRC errors in reading the measurements from the device. +.It power +The good power indication. +This can be useful with battery powered sensors. +.It heater +The built-in heater control. +The heater can be used for testing and for recovery from saturation +after high humidity. +.It hold_bus +Whether the sensor should hold SCL low while performing the measurement. +Normally, the sensor releases the bus and NACKs all accessed until the +measurement is completed. +The hold mode may be useful in mult-master environments. +.El +.Pp +On an +.Xr FDT 4 +based system the following properties must be set: +.Bl -tag -width "compatible" +.It Va compatible +Must be set to "meas,htu21". +.It Va reg +The I2C address of +.Nm . +Although, it is hard-wired to 0x40 (7-bit) on all supported sensors. +.El +.Pp +The DTS part for a +.Nm +device usually looks like: +.Bd -literal +/ { + + ... + htu21d { + compatible = "meas,htu21"; + reg = <0x40>; + }; +}; +.Ed +.Sh SEE ALSO +.Xr fdt 4 , +.Xr iicbus 4 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +driver and this manual page was written by +.An Andriy Gapon Aq Mt avg@FreeBSD.org . +.Sh BUGS +There is no way to control the measurement resolution. +.Pp +Some sensor variants do not provide a serial number or use an incompatible +format. +The +.Nm +driver does not distinguish those variants and may complain about incorrect +serial number checksum. diff --git a/static/freebsd/man4/hv_kvp.4 b/static/freebsd/man4/hv_kvp.4 new file mode 100644 index 00000000..db16b4bc --- /dev/null +++ b/static/freebsd/man4/hv_kvp.4 @@ -0,0 +1,95 @@ +.\" +.\" Copyright (c) 2012 Microsoft Corp. +.\" 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 September 10, 2013 +.Dt HYPER-V 4 +.Os +.Sh NAME +.Nm hv_kvp +.Nd Hyper-V Key Value Pair Driver +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in +the system kernel configuration file: +.Bd -ragged -offset indent +.Cd "device hyperv" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides the ability to store, retrieve, modify and delete +key value pairs for +.Fx +guest partitions running on Hyper-V. +Hyper-V allows administrators to store custom metadata in the form +of key value pairs inside the +.Fx +guest partition. +Administrators can use Windows Powershell scripts to add, read, +modify and delete such key value pairs. +.Pp +The driver is bare bones and merely forwards requests to its counterpart +user mode daemon, +.Xr hv_kvp_daemon 8 . +The daemon maintains pools of key value +pairs and does the actual metadata management. +.Pp +The same driver and daemon combination are also used to set and get +IP addresses from a +.Fx +guest. +.Pp +The set functionality is particularly +useful when the +.Fx +guest is assigned a static IP address and is failed over from one +Hyper-V host to another. +After failover, Hyper-V uses the set IP functionality to automatically +update the +.Fx +guest's IP address to its original static value. +.Pp +On the other hand, the get IP functionality is used to update the guest IP +address in the Hyper-V management console window. +.Sh SEE ALSO +.Xr hv_ata_pci_disengage 4 , +.Xr hv_netvsc 4 , +.Xr hv_storvsc 4 , +.Xr hv_utils 4 , +.Xr hv_vmbus 4 , +.Xr hv_kvp_daemon 8 +.Sh HISTORY +Support for +.Nm +first appeared in +.Fx 10.0 . +The driver was developed through a joint effort between Citrix +Incorporated, Microsoft Corporation and Network Appliance Incorporated. +.Sh AUTHORS +.An -nosplit +.Fx +support for +.Nm +was first added by +.An Microsoft BSD Integration Services Team Aq Mt bsdic@microsoft.com . diff --git a/static/freebsd/man4/hv_netvsc.4 b/static/freebsd/man4/hv_netvsc.4 new file mode 100644 index 00000000..e5c70047 --- /dev/null +++ b/static/freebsd/man4/hv_netvsc.4 @@ -0,0 +1,84 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2012 Microsoft Corp. +.\" 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 September 10, 2013 +.Dt HYPER-V 4 +.Os +.Sh NAME +.Nm hv_netvsc +.Nd Hyper-V Network Virtual Service Consumer +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in +the system kernel configuration file: +.Bd -ragged -offset indent +.Cd "device hyperv" +.Ed +.Sh DESCRIPTION +The +.Nm +driver implements the virtual network device for +.Fx +guest +partitions running on Hyper-V. +.Fx +guest partitions running on Hyper-V do not have direct access to +network devices attached to the Hyper-V server. +Although a +.Fx +guest can access network devices using Hyper-V's +full emulation mode, the performance in this mode tends to be unsatisfactory. +.Pp +To counter the above issues, the +.Nm +driver implements a network +Virtual +Service Consumer (VSC) that relays network requests from the guest partition +to the network Virtual Service Provider (VSP) hosted in the root partition +using the high performance data exchange infrastructure provided by +.Xr hv_vmbus 4 +driver. +The VSP in the root partition then forwards the network related requests to +the physical network card. +.Sh SEE ALSO +.Xr hv_ata_pci_disengage 4 , +.Xr hv_storvsc 4 , +.Xr hv_utils 4 , +.Xr hv_vmbus 4 +.Sh HISTORY +Support for +.Nm +first appeared in +.Fx 10.0 . +The driver was developed through a joint effort between Citrix Incorporated, +Microsoft Corporation, and Network Appliance Incorporated. +.Sh AUTHORS +.An -nosplit +.Fx +support for +.Nm +was first added by +.An Microsoft BSD Integration Services Team Aq Mt bsdic@microsoft.com . diff --git a/static/freebsd/man4/hv_storvsc.4 b/static/freebsd/man4/hv_storvsc.4 new file mode 100644 index 00000000..dc77a822 --- /dev/null +++ b/static/freebsd/man4/hv_storvsc.4 @@ -0,0 +1,88 @@ +.\" +.\" Copyright (c) 2012 Microsoft Corp. +.\" 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 September 10, 2013 +.Dt HYPER-V 4 +.Os +.Sh NAME +.Nm hv_storvsc +.Nd Hyper-V Storage Virtual Service Consumer +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in +the system kernel configuration file: +.Bd -ragged -offset indent +.Cd "device hyperv" +.Ed +.Sh DESCRIPTION +The +.Nm +driver implements the virtual store device for +.Fx +guest +partitions running on Hyper-V. +.Fx +guest partitions running on Hyper-V do not have direct access to +storage devices attached to the Hyper-V server. +Although a +.Fx +guest can access storage devices using Hyper-V's +full emulation mode, the performance in this mode tends to be unsatisfactory. +.Pp +To counter the above issues, the +.Nm +driver implements a storage +Virtual +Service Consumer (VSC) that relays storage requests from the guest partition +to the storage Virtual Service Provider (VSP) hosted in the root partition +using the high performance data exchange infrastructure provided by +.Xr hv_vmbus 4 +driver. +The VSP in the root partition then forwards the storage related requests to +the physical storage device. +.Pp +This driver functions by presenting a SCSI HBA interface to the Common Access +Method (CAM) layer. +CAM control blocks (CCBs) are +converted into VSCSI protocol messages which are delivered to the root +partition VSP over the Hyper-V VMBus. +.Sh SEE ALSO +.Xr hv_ata_pci_disengage 4 , +.Xr hv_netvsc 4 , +.Xr hv_utils 4 , +.Xr hv_vmbus 4 +.Sh HISTORY +Support for +.Nm +first appeared in +.Fx 10.0 . +The driver was developed through a joint effort between Citrix Incorporated, +Microsoft Corporation, and Network Appliance Incorporated. +.Sh AUTHORS +.An -nosplit +.Fx +support for +.Nm +was first added by +.An Microsoft BSD Integration Services Team Aq Mt bsdic@microsoft.com . diff --git a/static/freebsd/man4/hv_utils.4 b/static/freebsd/man4/hv_utils.4 new file mode 100644 index 00000000..ae0a40aa --- /dev/null +++ b/static/freebsd/man4/hv_utils.4 @@ -0,0 +1,84 @@ +.\" +.\" Copyright (c) 2012 Microsoft Corp. +.\" 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 September 10, 2013 +.Dt HYPER-V 4 +.Os +.Sh NAME +.Nm hv_utils +.Nd Hyper-V Utilities Driver +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in +the system kernel configuration file: +.Bd -ragged -offset indent +.Cd "device hyperv" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides time keeping, shutdown and heartbeat +functionality for +.Fx +guest partitions running on Hyper-V. +Hyper-V is a hypervisor-based virtualization technology from Microsoft. +The +.Nm +driver is one of the core drivers required to be present in guest +partitions running on Hyper-V. +This driver provides the following +functionalities to guest partitions: +.Pp +(a) Time Keeping: The clock inside the guest partition will remain accurate by +synchronizing to the clock on the virtualization server via Timesync service, +and with the help of the pluggable time source device. +.Pp +(b) Integrated shutdown: Guest partitions running +.Fx +can be shut down from +Hyper-V Manager console by using the +.Qq Shut down +command. +.Pp +(c) Heartbeat: This feature allows the virtualization server to detect whether +the guest partition is running and responsive. +.Sh SEE ALSO +.Xr hv_ata_pci_disengage 4 , +.Xr hv_netvsc 4 , +.Xr hv_storvsc 4 , +.Xr hv_vmbus 4 +.Sh HISTORY +Support for +.Nm +first appeared in +.Fx 10.0 . +The driver was developed through a joint effort between Citrix Incorporated, +Microsoft Corporation, and Network Appliance Incorporated. +.Sh AUTHORS +.An -nosplit +.Fx +support for +.Nm +was first added by +.An Microsoft BSD Integration Services Team Aq Mt bsdic@microsoft.com . diff --git a/static/freebsd/man4/hv_vmbus.4 b/static/freebsd/man4/hv_vmbus.4 new file mode 100644 index 00000000..f4602c76 --- /dev/null +++ b/static/freebsd/man4/hv_vmbus.4 @@ -0,0 +1,92 @@ +.\" +.\" Copyright (c) 2012 Microsoft Corp. +.\" 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 September 10, 2013 +.Dt HYPER-V 4 +.Os +.Sh NAME +.Nm hv_vmbus +.Nd Hyper-V Virtual Machine Bus (VMBus) Driver +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in +the system kernel configuration file: +.Bd -ragged -offset indent +.Cd "device hyperv" +.Cd "device pci" +.Ed +.Sh DESCRIPTION +The +.Nm +provides a high performance communication interface between +guest and root partitions in Hyper-V. +Hyper-V is a hypervisor-based virtualization technology from Microsoft. +Hyper-V supports isolation in terms of a partition. +A partition is a +logical unit of isolation, supported by the hypervisor, in which +operating systems execute. +.Pp +The Microsoft hypervisor must have at least one parent, or root, +partition, running Windows Server operating system. +The virtualization stack runs in the parent partition and has +direct access to the hardware devices. +The root partition then creates the child partitions which host +the guest operating systems. +.Pp +Child partitions do not have direct access to other hardware resources +and are presented +a virtual view of the resources, as virtual devices (VDevs). +Requests to the virtual devices are +redirected either via the VMBus or the hypervisor to the devices in +the parent partition, which handles the requests. +.Pp +The VMBus is a logical inter-partition communication channel. +The parent partition hosts Virtualization Service Providers (VSPs) +which communicate over the VMBus to handle device access requests from +child partitions. +Child partitions host Virtualization Service +Consumers (VSCs) which redirect device requests to VSPs in the parent +partition via the VMBus. +The Hyper-V VMBus driver defines and implements +the interface that facilitate high performance bi-directional communication +between the VSCs and VSPs. +All VSCs utilize the VMBus driver. +.Sh SEE ALSO +.Xr hv_netvsc 4 , +.Xr hv_storvsc 4 , +.Xr hv_utils 4 +.Sh HISTORY +Support for +.Nm +first appeared in +.Fx 10.0 . +The driver was developed through a joint effort between Citrix Incorporated, +Microsoft Corporation, and Network Appliance Incorporated. +.Sh AUTHORS +.An -nosplit +.Fx +support for +.Nm +was first added by +.An Microsoft BSD Integration Services Team Aq Mt bsdic@microsoft.com . diff --git a/static/freebsd/man4/hv_vss.4 b/static/freebsd/man4/hv_vss.4 new file mode 100644 index 00000000..33c7c2ab --- /dev/null +++ b/static/freebsd/man4/hv_vss.4 @@ -0,0 +1,373 @@ +.\" Copyright (c) 2016 Microsoft Corp. +.\" 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 October 12, 2016 +.Dt HV_VSS 4 +.Os +.Sh NAME +.Nm hv_vss +.Nd Hyper-V Volume Shadow Copy Service API +.Sh SYNOPSIS +.In dev/hyperv/hv_snapshot.h +.Bd -literal +#define VSS_SUCCESS 0x00000000 +#define VSS_FAIL 0x00000001 + +enum hv_vss_op_t { + HV_VSS_NONE = 0, + HV_VSS_CHECK, + HV_VSS_FREEZE, + HV_VSS_THAW, + HV_VSS_COUNT +}; + +struct hv_vss_opt_msg { + uint32_t opt; /* operation */ + uint32_t status; /* 0 for success, 1 for error */ + uint64_t msgid; /* an ID used to identify the transaction */ + uint8_t reserved[48]; /* reserved values are all zeroes */ +}; +.Ed +.Sh DESCRIPTION +The freeze or thaw functionality of application is important to guarantee +the application consistent backup. +On windows platform, VSS is defined to do live backup. +But for VM guest running on Hyper-V, the corresponding VSS is +not defined yet. +For example, a running database server instance, it knows when the +applications' freeze/thaw should start or finish. +But it is not aware of the freeze/thaw notification from Hyper-V host. +The +.Nm +is designed to notify application freeze/thaw request. +Thus, it plays a role of broker to forward the freeze/thaw command from Hyper-V host +to userland application if it registered VSS service on +.Fx +VM, and sends the result back to Hyper-V host. +.Pp +Generally, +.Xr hv_vss_daemon 8 +takes the responsibility to freeze/thaw UFS file system, +and it is automatically launched after system boots. +When Hyper-V host wants to take a snapshot of the +.Fx +VM, it will first send VSS capability check to +.Fx +VM. +The +.Nm +received the request and forward the request to userland application if it is +registered. +Only after +.Nm +received the VSS_SUCCESS response from application, the +.Xr hv_vss_daemon 8 +will be informed to check whether file system freeze/thaw is supported. +Any error occurs during this period, +.Nm +will inform Hyper-V host that VSS is not supported. +In addition, there is a default timeout limit before sending response to Hyper-V host. +If the total response time from application and +.Xr hv_vss_daemon 8 +exceeds this value, timeout +will occur and VSS unsupported is responded to Hyper-V host. +.Pp +After Hyper-V host confirmed the +.Fx +VM supports VSS, it will send freeze request to VM, and +.Nm +will first forward it to application. +After application finished freezing, it should inform +.Nm +and file system level freezing will be triggered by +.Xr hv_vss_daemon 8 . +After all freezing on both application and +.Xr hv_vss_daemon 8 +were finished, the +.Nm +will inform Hyper-V host that freezing is done. +Of course, there is a timeout limit as same as VSS capability is set to make sure freezing on +.Fx +VM is not hang. +If there is any error occurs or timeout happened, the freezing is failed on Hyper-V side. +.Pp +Hyper-V host will send thaw request after taking the snapshot, typically, this period is +very short in order not to block the running application. +.Nm +firstly thaw the file system by notifying +.Xr hv_vss_daemon 8 , +then notifies user registered +application. +There is also a timeout check before sending response to Hyper-V host. +.Pp +All the default timeout limit used in VSS capability check, freeze or thaw is the same. +It is 15 seconds currently. +.Sh NOTES +.Nm +only support UFS currently. +If any of file system partition is non UFS, the VSS capability check will fail. +If application does not register VSS, +.Nm +only support backup for file system level consistent. +The device should be closed before it was opened again. +If you want to simultaneously open "/dev/hv_appvss_dev" two or more times, +an error (-1) will be returned, and errno was set. +.Pp +If +.Xr hv_vss_daemon 8 +was killed after system boots, the VSS functionality will not work. +.Sh EXAMPLES +The following is a complete example which does nothing except for waiting 2 seconds when +receiving those notifications from +.Nm +.Bd -literal +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#define UNDEF_FREEZE_THAW (0) +#define FREEZE (1) +#define THAW (2) +#define CHECK (3) + +#define VSS_LOG(priority, format, args...) do { \\ + if (is_debugging == 1) { \\ + if (is_daemon == 1) \\ + syslog(priority, format, ## args); \\ + else \\ + printf(format, ## args); \\ + } else { \\ + if (priority < LOG_DEBUG) { \\ + if (is_daemon == 1) \\ + syslog(priority, format, ## args); \\ + else \\ + printf(format, ## args); \\ + } \\ + } \\ + } while(0) + +#define CHECK_TIMEOUT 1 +#define CHECK_FAIL 2 +#define FREEZE_TIMEOUT 1 +#define FREEZE_FAIL 2 +#define THAW_TIMEOUT 1 +#define THAW_FAIL 2 + +static int is_daemon = 1; +static int is_debugging = 0; +static int simu_opt_waiting = 2; // seconds + +#define GENERIC_OPT(TIMEOUT, FAIL) \\ + do { \\ + sleep(simu_opt_waiting); \\ + if (opt == CHECK_TIMEOUT) { \\ + sleep(simu_opt_waiting * 10); \\ + VSS_LOG(LOG_INFO, "%s timeout simulation\\n", \\ + __func__); \\ + return (0); \\ + } else if (opt == CHECK_FAIL) { \\ + VSS_LOG(LOG_INFO, "%s failure simulation\\n", \\ + __func__); \\ + return (CHECK_FAIL); \\ + } else { \\ + VSS_LOG(LOG_INFO, "%s success simulation\\n", \\ + __func__); \\ + return (0); \\ + } \\ + } while (0) + +static int +check(int opt) +{ + GENERIC_OPT(CHECK_TIMEOUT, CHECK_FAIL); +} + +static int +freeze(int opt) +{ + GENERIC_OPT(FREEZE_TIMEOUT, FREEZE_FAIL); +} + +static int +thaw(int opt) +{ + GENERIC_OPT(THAW_TIMEOUT, THAW_FAIL); +} + +static void usage(const char* cmd) { + fprintf(stderr, + "%s -f <0|1|2>: simulate app freeze." + " 0: successful, 1: freeze timeout, 2: freeze failed\\n" + " -c <0|1|2>: simulate vss feature check" + " -t <0|1|2>: simulate app thaw." + " 0: successful, 1: freeze timeout, 2: freeze failed\\n" + " -d : enable debug mode\\n" + " -n : run this tool under non-daemon mode\\n", cmd); +} + +int +main(int argc, char* argv[]) { + int ch, freezesimuop = 0, thawsimuop = 0, checksimuop = 0, fd, r, error; + uint32_t op; + struct pollfd app_vss_fd[1]; + struct hv_vss_opt_msg userdata; + + while ((ch = getopt(argc, argv, "f:c:t:dnh")) != -1) { + switch (ch) { + case 'f': + /* Run as regular process for debugging purpose. */ + freezesimuop = (int)strtol(optarg, NULL, 10); + break; + case 't': + thawsimuop = (int)strtol(optarg, NULL, 10); + break; + case 'c': + checksimuop = (int)strtol(optarg, NULL, 10); + break; + case 'd': + is_debugging = 1; + break; + case 'n': + is_daemon = 0; + break; + case 'h': + default: + usage(argv[0]); + exit(0); + } + } + + openlog("APPVSS", 0, LOG_USER); + /* Become daemon first. */ + if (is_daemon == 1) + daemon(1, 0); + else + VSS_LOG(LOG_DEBUG, "Run as regular process.\\n"); + + VSS_LOG(LOG_INFO, "HV_VSS starting; pid is: %d\\n", getpid()); + + fd = open(VSS_DEV(APP_VSS_DEV_NAME), O_RDWR); + if (fd < 0) { + VSS_LOG(LOG_ERR, "Fail to open %s, error: %d %s\\n", + VSS_DEV(APP_VSS_DEV_NAME), errno, strerror(errno)); + exit(EXIT_FAILURE); + } + app_vss_fd[0].fd = fd; + app_vss_fd[0].events = POLLIN | POLLRDNORM; + + while (1) { + r = poll(app_vss_fd, 1, INFTIM); + + VSS_LOG(LOG_DEBUG, "poll returned r = %d, revent = 0x%x\\n", + r, app_vss_fd[0].revents); + + if (r == 0 || (r < 0 && errno == EAGAIN) || + (r < 0 && errno == EINTR)) { + /* Nothing to read */ + continue; + } + + if (r < 0) { + /* + * For poll return failure other than EAGAIN, + * we want to exit. + */ + VSS_LOG(LOG_ERR, "Poll failed.\\n"); + perror("poll"); + exit(EIO); + } + + /* Read from character device */ + error = ioctl(fd, IOCHVVSSREAD, &userdata); + if (error < 0) { + VSS_LOG(LOG_ERR, "Read failed.\\n"); + perror("pread"); + exit(EIO); + } + + if (userdata.status != 0) { + VSS_LOG(LOG_ERR, "data read error\\n"); + continue; + } + + op = userdata.opt; + + switch (op) { + case HV_VSS_CHECK: + error = check(checksimuop); + break; + case HV_VSS_FREEZE: + error = freeze(freezesimuop); + break; + case HV_VSS_THAW: + error = thaw(thawsimuop); + break; + default: + VSS_LOG(LOG_ERR, "Illegal operation: %d\\n", op); + error = VSS_FAIL; + } + if (error) + userdata.status = VSS_FAIL; + else + userdata.status = VSS_SUCCESS; + error = ioctl(fd, IOCHVVSSWRITE, &userdata); + if (error != 0) { + VSS_LOG(LOG_ERR, "Fail to write to device\\n"); + exit(EXIT_FAILURE); + } else { + VSS_LOG(LOG_INFO, "Send response %d for %s to kernel\\n", + userdata.status, op == HV_VSS_FREEZE ? "Freeze" : + (op == HV_VSS_THAW ? "Thaw" : "Check")); + } + } + return 0; +} +.Ed +.Sh SEE ALSO +.Xr hv_utils 4 , +.Xr hv_vss_daemon 8 +.Sh HISTORY +The daemon was introduced in October 2016 and developed by Microsoft Corp. +.Sh AUTHORS +.An -nosplit +.Fx +support for +.Nm +was first added by +.An Microsoft BSD Integration Services Team Aq Mt bsdic@microsoft.com . diff --git a/static/freebsd/man4/hwpmc.4 b/static/freebsd/man4/hwpmc.4 new file mode 100644 index 00000000..5b3e9a19 --- /dev/null +++ b/static/freebsd/man4/hwpmc.4 @@ -0,0 +1,967 @@ +.\" Copyright (c) 2003-2008 Joseph Koshy +.\" Copyright (c) 2007,2023 The FreeBSD Foundation +.\" +.\" Portions of this software were developed by A. Joseph Koshy under +.\" sponsorship from the FreeBSD Foundation and Google, Inc. +.\" +.\" Portions of this documentation were written by Mitchell Horne +.\" under sponsorship from the FreeBSD Foundation. +.\" +.\" 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 8, 2023 +.Dt HWPMC 4 +.Os +.Sh NAME +.Nm hwpmc +.Nd "Hardware Performance Monitoring Counter support" +.Sh SYNOPSIS +The following option must be present in the kernel configuration file: +.Bd -ragged -offset indent +.Cd "options HWPMC_HOOKS" +.Ed +.Pp +Additionally, for i386 systems: +.Bd -ragged -offset indent +.Cd "device apic" +.Ed +.Pp +To load the driver as a module at boot time: +.Bd -literal -offset indent +sysrc kld_list+=hwpmc +.Ed +.Pp +Alternatively, to compile the driver into the kernel: +.Bd -ragged -offset indent +.Cd "device hwpmc" +.Ed +.Pp +To enable debugging features +.Po see +.Sx DEBUGGING +.Pc : +.Bd -ragged -offset indent +.Cd "options KTR" +.Cd "options KTR_COMPILE=(KTR_SUBSYS)" +.Cd "options KTR_MASK=(KTR_SUBSYS)" +.Cd "options HWPMC_DEBUG" +.Ed +.Sh DESCRIPTION +The +.Nm +driver virtualizes the hardware performance monitoring facilities in +modern CPUs and provides support for using these facilities from +user level processes. +.Pp +The driver supports multi-processor systems. +.Pp +PMCs are allocated using the +.Dv PMC_OP_PMCALLOCATE +request. +A successful +.Dv PMC_OP_PMCALLOCATE +request will return a handle to the requesting process. +Subsequent operations on the allocated PMC use this handle to denote +the specific PMC. +A process that has successfully allocated a PMC is termed an +.Dq "owner process" . +.Pp +PMCs may be allocated with process or system scope. +.Bl -tag -width ".Em Process-scope" +.It Em "Process-scope" +The PMC is active only when a thread belonging +to a process it is attached to is scheduled on a CPU. +.It Em "System-scope" +The PMC operates independently of processes and +measures hardware events for the system as a whole. +.El +.Pp +PMCs may be allocated for counting or for sampling: +.Bl -tag -width ".Em Counting" +.It Em Counting +In counting modes, the PMCs count hardware events. +These counts are retrievable using the +.Dv PMC_OP_PMCREAD +system call on all architectures. +Some architectures offer faster methods of reading these counts. +.It Em Sampling +In sampling modes, the PMCs are configured to sample the CPU +instruction pointer (and optionally to capture the call chain leading +up to the sampled instruction pointer) after a configurable number of +hardware events have been observed. +Instruction pointer samples and call chain records are usually +directed to a log file for subsequent analysis. +.El +.Pp +Scope and operational mode are orthogonal; a PMC may thus be +configured to operate in one of the following four modes: +.Bl -tag -width indent +.It Process-scope, counting +These PMCs count hardware events whenever a thread in their attached process is +scheduled on a CPU. +These PMCs normally count from zero, but the initial count may be +set using the +.Dv PMC_OP_SETCOUNT +operation. +Applications can read the value of the PMC anytime using the +.Dv PMC_OP_PMCRW +operation. +.It Process-scope, sampling +These PMCs sample the target processes instruction pointer after they +have seen the configured number of hardware events. +The PMCs only count events when a thread belonging to their attached +process is active. +The desired frequency of sampling is set using the +.Dv PMC_OP_SETCOUNT +operation prior to starting the PMC. +Log files are configured using the +.Dv PMC_OP_CONFIGURELOG +operation. +.It System-scope, counting +These PMCs count hardware events seen by them independent of the +processes that are executing. +The current count on these PMCs can be read using the +.Dv PMC_OP_PMCRW +request. +These PMCs normally count from zero, but the initial count may be +set using the +.Dv PMC_OP_SETCOUNT +operation. +.It System-scope, sampling +These PMCs will periodically sample the instruction pointer of the CPU +they are allocated on, and will write the sample to a log for further +processing. +The desired frequency of sampling is set using the +.Dv PMC_OP_SETCOUNT +operation prior to starting the PMC. +Log files are configured using the +.Dv PMC_OP_CONFIGURELOG +operation. +.Pp +System-wide statistical sampling can only be enabled by a process with +super-user privileges. +.El +.Pp +Processes are allowed to allocate as many PMCs as the hardware and +current operating conditions permit. +Processes may mix allocations of system-wide and process-private +PMCs. +Multiple processes may be using PMCs simultaneously. +.Pp +Allocated PMCs are started using the +.Dv PMC_OP_PMCSTART +operation, and stopped using the +.Dv PMC_OP_PMCSTOP +operation. +Stopping and starting a PMC is permitted at any time the owner process +has a valid handle to the PMC. +.Pp +Process-private PMCs need to be attached to a target process before +they can be used. +Attaching a process to a PMC is done using the +.Dv PMC_OP_PMCATTACH +operation. +An already attached PMC may be detached from its target process +using the converse +.Dv PMC_OP_PMCDETACH +operation. +Issuing a +.Dv PMC_OP_PMCSTART +operation on an as yet unattached PMC will cause it to be attached +to its owner process. +The following rules determine whether a given process may attach +a PMC to another target process: +.Bl -bullet -compact +.It +A non-jailed process with super-user privileges is allowed to attach +to any other process in the system. +.It +Other processes are only allowed to attach to targets that they would +be able to attach to for debugging (as determined by +.Xr p_candebug 9 ) . +.El +.Pp +PMCs are released using +.Dv PMC_OP_PMCRELEASE . +After a successful +.Dv PMC_OP_PMCRELEASE +operation the handle to the PMC will become invalid. +.Ss Modifier Flags +The +.Dv PMC_OP_PMCALLOCATE +operation supports the following flags that modify the behavior +of an allocated PMC: +.Bl -tag -width indent +.It Dv PMC_F_CALLCHAIN +This modifier informs sampling PMCs to record a callchain when +capturing a sample. +The maximum depth to which call chains are recorded is specified +by the +.Va "kern.hwpmc.callchaindepth" +kernel tunable. +.It Dv PMC_F_DESCENDANTS +This modifier is valid only for a PMC being allocated in process-private +mode. +It signifies that the PMC will track hardware events for its +target process and the target's current and future descendants. +.It Dv PMC_F_LOG_PROCCSW +This modifier is valid only for a PMC being allocated in process-private +mode. +When this modifier is present, at every context switch, +.Nm +will log a record containing the number of hardware events +seen by the target process when it was scheduled on the CPU. +.It Dv PMC_F_LOG_PROCEXIT +This modifier is valid only for a PMC being allocated in process-private +mode. +With this modifier present, +.Nm +will maintain per-process counts for each target process attached to +a PMC. +At process exit time, a record containing the target process' PID and +the accumulated per-process count for that process will be written to the +configured log file. +.El +.Pp +Modifiers +.Dv PMC_F_LOG_PROCEXIT +and +.Dv PMC_F_LOG_PROCCSW +may be used in combination with modifier +.Dv PMC_F_DESCENDANTS +to track the behavior of complex pipelines of processes. +PMCs with modifiers +.Dv PMC_F_LOG_PROCEXIT +and +.Dv PMC_F_LOG_PROCCSW +cannot be started until their owner process has configured a log file. +.Ss Signals +The +.Nm +driver may deliver signals to processes that have allocated PMCs: +.Bl -tag -width ".Dv SIGBUS" +.It Dv SIGIO +A +.Dv PMC_OP_PMCRW +operation was attempted on a process-private PMC that does not have +attached target processes. +.It Dv SIGBUS +The +.Nm +driver is being unloaded from the kernel. +.El +.Ss PMC ROW DISPOSITIONS +A PMC row is defined as the set of PMC resources at the same hardware +address in the CPUs in a system. +Since process scope PMCs need to move between CPUs following their +target threads, allocation of a process scope PMC reserves all PMCs in +a PMC row for use only with process scope PMCs. +Accordingly a PMC row will be in one of the following dispositions: +.Bl -tag -width ".Dv PMC_DISP_STANDALONE" -compact +.It Dv PMC_DISP_FREE +Hardware counters in this row are free and may be use to satisfy +either of system scope or process scope allocation requests. +.It Dv PMC_DISP_THREAD +Hardware counters in this row are in use by process scope PMCs +and are only available for process scope allocation requests. +.It Dv PMC_DISP_STANDALONE +Some hardware counters in this row have been administratively +disabled or are in use by system scope PMCs. +Non-disabled hardware counters in such a row may be used +for satisfying system scope allocation requests. +No process scope PMCs will use hardware counters in this row. +.El +.Sh COMPATIBILITY +The API and ABI documented in this manual page may change in the future. +This interface is intended to be consumed by the +.Xr pmc 3 +library; other consumers are unsupported. +Applications targeting PMCs should use the +.Xr pmc 3 +library API. +.Sh PROGRAMMING API +The +.Nm +driver operates using a system call number that is dynamically +allotted to it when it is loaded into the kernel. +.Pp +The +.Nm +driver supports the following operations: +.Bl -tag -width indent +.It Dv PMC_OP_CONFIGURELOG +Configure a log file for PMCs that require a log file. +The +.Nm +driver will write log data to this file asynchronously. +If it encounters an error, logging will be stopped and the error code +encountered will be saved for subsequent retrieval by a +.Dv PMC_OP_FLUSHLOG +request. +.It Dv PMC_OP_FLUSHLOG +Transfer buffered log data inside +.Nm +to a configured output file. +This operation returns to the caller after the write operation +has returned. +The returned error code reflects any pending error state inside +.Nm . +.It Dv PMC_OP_GETCAPS +Retrieve the capabilities associated with a specific PMC counter. +Some capabilities may be limited to specific indices (i.e., not available +across all counters within a class). +.It Dv PMC_OP_GETCPUINFO +Retrieve information about the highest possible CPU number for the system, +and the number of hardware performance monitoring counters available per CPU. +.It Dv PMC_OP_GETDRIVERSTATS +Retrieve module statistics (for analyzing the behavior of +.Nm +itself). +.It Dv PMC_OP_GETMODULEVERSION +Retrieve the version number of API. +.It Dv PMC_OP_GETPMCINFO +Retrieve information about the current state of the PMCs on a +given CPU. +.It Dv PMC_OP_PMCADMIN +Set the administrative state (i.e., whether enabled or disabled) for +the hardware PMCs managed by the +.Nm +driver. +The invoking process needs to possess the +.Dv PRIV_PMC_MANAGE +privilege. +.It Dv PMC_OP_PMCALLOCATE +Allocate and configure a PMC. +On successful allocation, a handle to the PMC (a 32 bit value) +is returned. +.It Dv PMC_OP_PMCATTACH +Attach a process mode PMC to a target process. +The PMC will be active whenever a thread in the target process is +scheduled on a CPU. +.Pp +If the +.Dv PMC_F_DESCENDANTS +flag had been specified at PMC allocation time, then the PMC is +attached to all current and future descendants of the target process. +.It Dv PMC_OP_PMCDETACH +Detach a PMC from its target process. +.It Dv PMC_OP_PMCRELEASE +Release a PMC. +.It Dv PMC_OP_PMCRW +Read and write a PMC. +This operation is valid only for PMCs configured in counting modes. +.It Dv PMC_OP_SETCOUNT +Set the initial count (for counting mode PMCs) or the desired sampling +rate (for sampling mode PMCs). +.It Dv PMC_OP_PMCSTART +Start a PMC. +.It Dv PMC_OP_PMCSTOP +Stop a PMC. +.It Dv PMC_OP_WRITELOG +Insert a timestamped user record into the log file. +.El +.Ss i386 Specific API +Some i386 family CPUs support the RDPMC instruction which allows a +user process to read a PMC value without needing to invoke a +.Dv PMC_OP_PMCRW +operation. +On such CPUs, the machine address associated with an allocated PMC is +retrievable using the +.Dv PMC_OP_PMCX86GETMSR +system call. +.Bl -tag -width indent +.It Dv PMC_OP_PMCX86GETMSR +Retrieve the MSR (machine specific register) number associated with +the given PMC handle. +.Pp +The PMC needs to be in process-private mode and allocated without the +.Dv PMC_F_DESCENDANTS +modifier flag, and should be attached only to its owner process at the +time of the call. +.El +.Ss amd64 Specific API +AMD64 CPUs support the RDPMC instruction which allows a +user process to read a PMC value without needing to invoke a +.Dv PMC_OP_PMCRW +operation. +The machine address associated with an allocated PMC is +retrievable using the +.Dv PMC_OP_PMCX86GETMSR +system call. +.Bl -tag -width indent +.It Dv PMC_OP_PMCX86GETMSR +Retrieve the MSR (machine specific register) number associated with +the given PMC handle. +.Pp +The PMC needs to be in process-private mode and allocated without the +.Dv PMC_F_DESCENDANTS +modifier flag, and should be attached only to its owner process at the +time of the call. +.El +.Sh SYSCTL VARIABLES AND LOADER TUNABLES +The behavior of +.Nm +is influenced by the following +.Xr sysctl 8 +and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va kern.hwpmc.callchaindepth Pq integer, read-only +The maximum number of call chain records to capture per sample. +The default is 8. +.It Va kern.hwpmc.debugflags Pq string, read-write +(Only available if the +.Nm +driver was compiled with +.Fl DDEBUG . ) +Control the verbosity of debug messages from the +.Nm +driver. +.It Va kern.hwpmc.hashsize Pq integer, read-only +The number of rows in the hash tables used to keep track of owner and +target processes. +The default is 16. +.It Va kern.hwpmc.logbuffersize Pq integer, read-only +The size in kilobytes of each log buffer used by +.Nm Ns 's +logging function. +The default buffer size is 256KB. +The maximum value is 16MB. +.It Va kern.hwpmc.mincount Pq integer, read-write +The minimum sampling rate for sampling mode PMCs. +The default count is 1000 events. +.It Va kern.hwpmc.mtxpoolsize Pq integer, read-only +The size of the spin mutex pool used by the PMC driver. +The default is 32. +.It Va kern.hwpmc.nbuffers_pcpu Pq integer, read-only +The number of log buffers per CPU used by +.Nm +for logging. +The default is 32. +The product of +.Va kern.hwpmc.nbuffers_pcpu +and +.Va kern.hwpmc.logbuffersize +must not exceed 32MB per CPU. +.It Va kern.hwpmc.nsamples Pq integer, read-only +The number of entries in the per-CPU ring buffer used during sampling. +The default is 512. +.It Va security.bsd.unprivileged_syspmcs Pq boolean, read-write +If set to non-zero, allow unprivileged processes to allocate system-wide +PMCs. +The default value is 0. +.It Va security.bsd.unprivileged_proc_debug Pq boolean, read-write +If set to 0, the +.Nm +driver will only allow privileged processes to attach PMCs to other +processes. +.El +.Pp +These variables may be set in the kernel environment using +.Xr kenv 1 +before +.Nm +is loaded. +.Sh IMPLEMENTATION NOTES +.Ss SMP Symmetry +The kernel driver requires all physical CPUs in an SMP system to have +identical performance monitoring counter hardware. +.Ss Sparse CPU Numbering +On platforms that sparsely number CPUs and which support hot-plugging +of CPUs, requests that specify non-existent or disabled CPUs will fail +with an error. +Applications allocating system-scope PMCs need to be aware of +the possibility of such transient failures. +.Ss x86 TSC Handling +Historically, on the x86 architecture, +.Fx +has permitted user processes running at a processor CPL of 3 to +read the TSC using the RDTSC instruction. +The +.Nm +driver preserves this behavior. +.Ss Intel P4/HTT Handling +On CPUs with HTT support, Intel P4 PMCs are capable of qualifying +only a subset of hardware events on a per-logical CPU basis. +Consequently, if HTT is enabled on a system with Intel Pentium P4 +PMCs, then the +.Nm +driver will reject allocation requests for process-private PMCs that +request counting of hardware events that cannot be counted separately +for each logical CPU. +.Sh DIAGNOSTICS +.Bl -diag +.It "hwpmc: [class/npmc/capabilities]..." +Announce the presence of +.Va npmc +PMCs of class +.Va class , +with capabilities described by bit string +.Va capabilities . +.It "hwpmc: kernel version (0x%x) does not match module version (0x%x)." +The module loading process failed because a version mismatch was detected +between the currently executing kernel and the module being loaded. +.It "hwpmc: this kernel has not been compiled with 'options HWPMC_HOOKS'." +The module loading process failed because the currently executing kernel +was not configured with the required configuration option +.Dv HWPMC_HOOKS . +.It "hwpmc: tunable hashsize=%d must be greater than zero." +A negative value was supplied for tunable +.Va kern.hwpmc.hashsize . +.It "hwpmc: logbuffersize=%d must be greater than zero and less than or equal to %d, resetting to %d." +A negative value was supplied for tunable +.Va kern.hwpmc.logbuffersize . +.It "hwpmc: nbuffers_pcpu=%d must be greater than zero, resetting to %d." +A negative value was supplied for tunable +.Va kern.hwpmc.nbuffers_pcpu . +.It "hwpmc: tunable nsamples=%d out of range." +The value for tunable +.Va kern.hwpmc.nsamples +was negative or greater than 65535. +.It "hwpmc: nbuffers_pcpu=%d * logbuffersize=%d exceeds %dMB per CPU limit, resetting to defaults (%d * %d)." +The product of tunables +.Va kern.hwpmc.nbuffers_pcpu +and +.Va kern.hwpmc.logbuffersize +exceeds the maximum per-CPU memory limit. +Both tunables are reset to their compiled defaults. +.El +.Sh DEBUGGING +The +.Nm +module can be configured to record trace entries using the +.Xr ktr 4 +interface. +This is useful for debugging the driver's functionality, primarily during +development. +This debugging functionality is not enabled by default, and requires +recompiling the kernel and +.Nm +module after adding the following to the kernel config: +.Bd -literal -offset indent +.Cd options KTR +.Cd options KTR_COMPILE=(KTR_SUBSYS) +.Cd options KTR_MASK=(KTR_SUBSYS) +.Cd options HWPMC_DEBUG +.Ed +.Pp +This alone is not enough to enable tracing; one must also configure the +.Va kern.hwpmc.debugflags +.Xr sysctl 8 +variable, which provides fine-grained control over which types of events are +logged to the trace buffer. +.Pp +.Nm +trace events are grouped by 'major' and 'minor' flag types. +The major flag names are as follows: +.Pp +.Bl -tag -width "sampling" -compact -offset indent +.It cpu +CPU events +.It csw +Context switch events +.It logging +Logging events +.It md +Machine-dependent/class-dependent events +.It module +Miscellaneous events +.It owner +PMC owner events +.It pmc +PMC management events +.It process +Process events +.It sampling +Sampling events +.El +.Pp +The minor flags for each major flag group can vary. +The individual minor flag names are: +.Bd -ragged -offset indent +allocaterow, +allocate, +attach, +bind, +config, +exec, +exit, +find, +flush, +fork, +getbuf, +hook, +init, +intr, +linktarget, +mayberemove, +ops, +read, +register, +release, +remove, +sample, +scheduleio, +select, +signal, +swi, +swo, +start, +stop, +syscall, +unlinktarget, +write +.Ed +.Pp +The +.Va kern.hwpmc.debugflags +variable is a string with a custom format. +The string should contain a space-separated list of event specifiers. +Each event specifier consists of the major flag name, followed by an equal sign +(=), followed by a comma-separated list of minor event types. +To track all events for a major group, an asterisk (*) can be given instead of +minor event names. +.Pp +For example, to trace all allocation and release events, set +.Va debugflags +as follows: +.Bd -literal -offset indent +kern.hwpmc.debugflags="pmc=allocate,release md=allocate,release" +.Ed +.Pp +To trace all events in the process and context switch major flag groups: +.Bd -literal -offset indent +kern.hwpmc.debugflags="process=* csw=*" +.Ed +.Pp +To disable all trace events, set the variable to an empty string. +.Bd -literal -offset indent +kern.hwpmc.debugflags="" +.Ed +.Pp +Trace events are recorded by +.Xr ktr 4 , +and can be inspected at run-time using the +.Xr ktrdump 8 +utility, or at the +.Xr ddb 4 +prompt after a panic with the 'show ktr' command. +.Sh ERRORS +A command issued to the +.Nm +driver may fail with the following errors: +.Bl -tag -width Er +.It Bq Er EAGAIN +Helper process creation failed for a +.Dv PMC_OP_CONFIGURELOG +request due to a temporary resource shortage in the kernel. +.It Bq Er EBUSY +A +.Dv PMC_OP_CONFIGURELOG +operation was requested while an existing log was active. +.It Bq Er EBUSY +A DISABLE operation was requested using the +.Dv PMC_OP_PMCADMIN +request for a set of hardware resources currently in use for +process-private PMCs. +.It Bq Er EBUSY +A +.Dv PMC_OP_PMCADMIN +operation was requested on an active system mode PMC. +.It Bq Er EBUSY +A +.Dv PMC_OP_PMCATTACH +operation was requested for a target process that already had another +PMC using the same hardware resources attached to it. +.It Bq Er EBUSY +A +.Dv PMC_OP_PMCRW +request writing a new value was issued on a PMC that was active. +.It Bq Er EBUSY +A +.Dv PMC_OP_PMCSETCOUNT +request was issued on a PMC that was active. +.It Bq Er EDOOFUS +A +.Dv PMC_OP_PMCSTART +operation was requested without a log file being configured for a +PMC allocated with +.Dv PMC_F_LOG_PROCCSW +and +.Dv PMC_F_LOG_PROCEXIT +modifiers. +.It Bq Er EDOOFUS +A +.Dv PMC_OP_PMCSTART +operation was requested on a system-wide sampling PMC without a log +file being configured. +.It Bq Er EEXIST +A +.Dv PMC_OP_PMCATTACH +request was reissued for a target process that already is the target +of this PMC. +.It Bq Er EFAULT +A bad address was passed in to the driver. +.It Bq Er EINVAL +An invalid PMC handle was specified. +.It Bq Er EINVAL +An invalid CPU number was passed in for a +.Dv PMC_OP_GETPMCINFO +operation. +.It Bq Er EINVAL +The +.Ar pm_flags +argument to a +.Dv PMC_OP_CONFIGURELOG +request contained unknown flags. +.It Bq Er EINVAL +A +.Dv PMC_OP_CONFIGURELOG +request to de-configure a log file was issued without a log file +being configured. +.It Bq Er EINVAL +A +.Dv PMC_OP_FLUSHLOG +request was issued without a log file being configured. +.It Bq Er EINVAL +An invalid CPU number was passed in for a +.Dv PMC_OP_PMCADMIN +operation. +.It Bq Er EINVAL +An invalid operation request was passed in for a +.Dv PMC_OP_PMCADMIN +operation. +.It Bq Er EINVAL +An invalid PMC ID was passed in for a +.Dv PMC_OP_PMCADMIN +operation. +.It Bq Er EINVAL +A suitable PMC matching the parameters passed in to a +.Dv PMC_OP_PMCALLOCATE +request could not be allocated. +.It Bq Er EINVAL +An invalid PMC mode was requested during a +.Dv PMC_OP_PMCALLOCATE +request. +.It Bq Er EINVAL +An invalid CPU number was specified during a +.Dv PMC_OP_PMCALLOCATE +request. +.It Bq Er EINVAL +A CPU other than +.Dv PMC_CPU_ANY +was specified in a +.Dv PMC_OP_PMCALLOCATE +request for a process-private PMC. +.It Bq Er EINVAL +A CPU number of +.Dv PMC_CPU_ANY +was specified in a +.Dv PMC_OP_PMCALLOCATE +request for a system-wide PMC. +.It Bq Er EINVAL +The +.Ar pm_flags +argument to an +.Dv PMC_OP_PMCALLOCATE +request contained unknown flags. +.It Bq Er EINVAL +(On Intel Pentium 4 CPUs with HTT support) +A +.Dv PMC_OP_PMCALLOCATE +request for a process-private PMC was issued for an event that does +not support counting on a per-logical CPU basis. +.It Bq Er EINVAL +A PMC allocated for system-wide operation was specified with a +.Dv PMC_OP_PMCATTACH +or +.Dv PMC_OP_PMCDETACH +request. +.It Bq Er EINVAL +The +.Ar pm_pid +argument to a +.Dv PMC_OP_PMCATTACH +or +.Dv PMC_OP_PMCDETACH +request specified an illegal process ID. +.It Bq Er EINVAL +A +.Dv PMC_OP_PMCDETACH +request was issued for a PMC not attached to the target process. +.It Bq Er EINVAL +Argument +.Ar pm_flags +to a +.Dv PMC_OP_PMCRW +request contained illegal flags. +.It Bq Er EINVAL +A +.Dv PMC_OP_PMCX86GETMSR +operation was requested for a PMC not in process-virtual mode, or +for a PMC that is not solely attached to its owner process, or for +a PMC that was allocated with flag +.Dv PMC_F_DESCENDANTS . +.It Bq Er EINVAL +A +.Dv PMC_OP_WRITELOG +request was issued for an owner process without a log file +configured. +.It Bq Er ENOMEM +The system was not able to allocate kernel memory. +.It Bq Er ENOSYS +(On i386 and amd64 architectures) +A +.Dv PMC_OP_PMCX86GETMSR +operation was requested for hardware that does not support reading +PMCs directly with the RDPMC instruction. +.It Bq Er ENXIO +A +.Dv PMC_OP_GETPMCINFO +operation was requested for an absent or disabled CPU. +.It Bq Er ENXIO +A +.Dv PMC_OP_PMCALLOCATE +operation specified allocation of a system-wide PMC on an absent or +disabled CPU. +.It Bq Er ENXIO +A +.Dv PMC_OP_PMCSTART +or +.Dv PMC_OP_PMCSTOP +request was issued for a system-wide PMC that was allocated on a CPU +that is currently absent or disabled. +.It Bq Er EOPNOTSUPP +A +.Dv PMC_OP_PMCALLOCATE +request was issued for PMC capabilities not supported +by the specified PMC class. +.It Bq Er EOPNOTSUPP +(i386 architectures) +A sampling mode PMC was requested on a CPU lacking an APIC. +.It Bq Er EPERM +A +.Dv PMC_OP_PMCADMIN +request was issued by a process without super-user +privilege or by a jailed super-user process. +.It Bq Er EPERM +A +.Dv PMC_OP_PMCATTACH +operation was issued for a target process that the current process +does not have permission to attach to. +.It Bq Er EPERM +(i386 and amd64 architectures) +A +.Dv PMC_OP_PMCATTACH +operation was issued on a PMC whose MSR has been retrieved using +.Dv PMC_OP_PMCX86GETMSR . +.It Bq Er ESRCH +A process issued a PMC operation request without having allocated any +PMCs. +.It Bq Er ESRCH +A process issued a PMC operation request after the PMC was detached +from all of its target processes. +.It Bq Er ESRCH +A +.Dv PMC_OP_PMCATTACH +or +.Dv PMC_OP_PMCDETACH +request specified a non-existent process ID. +.It Bq Er ESRCH +The target process for a +.Dv PMC_OP_PMCDETACH +operation is not being monitored by +.Nm . +.El +.Sh SEE ALSO +.Xr kenv 1 , +.Xr pmc 3 , +.Xr pmclog 3 , +.Xr ddb 4 , +.Xr ktr 4 , +.Xr kldload 8 , +.Xr ktrdump 8 , +.Xr pmccontrol 8 , +.Xr pmcstat 8 , +.Xr sysctl 8 , +.Xr kproc_create 9 , +.Xr p_candebug 9 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 6.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Joseph Koshy Aq Mt jkoshy@FreeBSD.org . +.Sh BUGS +The driver samples the state of the kernel's logical processor support +at the time of initialization (i.e., at module load time). +On CPUs supporting logical processors, the driver could misbehave if +logical processors are subsequently enabled or disabled while the +driver is active. +.Pp +On the i386 architecture, the driver requires that the local APIC on the +CPU be enabled for sampling mode to be supported. +Many single-processor motherboards keep the APIC disabled in BIOS; on +such systems +.Nm +will not support sampling PMCs. +.Sh SECURITY CONSIDERATIONS +PMCs may be used to monitor the actual behavior of the system on hardware. +In situations where this constitutes an undesirable information leak, +the following options are available: +.Bl -enum +.It +Set the +.Xr sysctl 8 +tunable +.Va security.bsd.unprivileged_syspmcs +to 0. +This ensures that unprivileged processes cannot allocate system-wide +PMCs and thus cannot observe the hardware behavior of the system +as a whole. +This tunable may also be set at boot time using +.Xr loader 8 , +or with +.Xr kenv 1 +prior to loading the +.Nm +driver into the kernel. +.It +Set the +.Xr sysctl 8 +tunable +.Va security.bsd.unprivileged_proc_debug +to 0. +This will ensure that an unprivileged process cannot attach a PMC +to any process other than itself and thus cannot observe the hardware +behavior of other processes with the same credentials. +.El +.Pp +System administrators should note that on IA-32 platforms +.Fx +makes the content of the IA-32 TSC counter available to all processes +via the RDTSC instruction. diff --git a/static/freebsd/man4/hwpstate_intel.4 b/static/freebsd/man4/hwpstate_intel.4 new file mode 100644 index 00000000..5b9fbede --- /dev/null +++ b/static/freebsd/man4/hwpstate_intel.4 @@ -0,0 +1,95 @@ +.\" +.\" Copyright (c) 2019 Intel Corporation +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 21, 2020 +.Dt HWPSTATE_INTEL 4 +.Os +.Sh NAME +.Nm hwpstate_intel +.Nd Intel Speed Shift Technology driver +.Sh SYNOPSIS +To compile this driver into your kernel +place the following line in your kernel +configuration file: +.Bd -ragged -offset indent +.Cd "device cpufreq" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for hardware-controlled performance states on Intel +platforms, also known as Intel Speed Shift Technology. +.Sh LOADER TUNABLES +.Bl -tag -width indent +.It Va hint.hwpstate_intel.0.disabled +Can be used to disable +.Nm , +allowing other compatible drivers to manage performance states, like +.Xr est 4 . +Defaults to +.Dv Qq 0 +(enabled). +.It Va machdep.hwpstate_pkg_ctrl +Selects between package-level control (the default) and per-core control. +.Dv Qq 1 +selects package-level control and +.Dv Qq 0 +selects core-level control. +.El +.Sh SYSCTL VARIABLES +The following +.Xr sysctl 8 +values are available +.Bl -tag -width indent +.It Va dev.hwpstate_intel.%d.%desc +Describes the attached driver +.It dev.hwpstate_intel.0.%desc: Intel Speed Shift +.It Va dev.hwpstate_intel.%d.%driver +Driver in use, always hwpstate_intel. +.It dev.hwpstate_intel.0.%driver: hwpstate_intel +.It Va dev.hwpstate_intel.%d.%parent +The CPU that is exposing these frequencies. +For example +.Va cpu0 . +.It dev.hwpstate_intel.0.%parent: cpu0 +.It Va dev.hwpstate_intel.%d.epp +Energy/Performance Preference. +Valid values range from 0 to 100. +Setting this field conveys a hint to the hardware regarding a preference towards +performance (at value 0), energy efficiency (at value 100), or somewhere in +between. +.It dev.hwpstate_intel.0.epp: 0 +.El +.Sh COMPATIBILITY +.Nm +is only found on supported Intel CPUs. +.Sh SEE ALSO +.Xr cpufreq 4 +.Rs +.%T "Intel 64 and IA-32 Architectures Software Developer Manuals" +.%U "http://www.intel.com/content/www/us/en/processors/architectures-software-developer-manuals.html" +.Re +.Sh AUTHORS +This manual page was written by +.An D Scott Phillips Aq Mt scottph@FreeBSD.org . diff --git a/static/freebsd/man4/hwt.4 b/static/freebsd/man4/hwt.4 new file mode 100644 index 00000000..299332c7 --- /dev/null +++ b/static/freebsd/man4/hwt.4 @@ -0,0 +1,144 @@ +.\" +.\" Copyright (c) 2025 Ruslan Bukin +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd July 12, 2025 +.Dt HWT 4 +.Os +.Sh NAME +.Nm hwt +.Nd Hardware Trace Framework +.Sh SYNOPSIS +.Cd "options HWT_HOOKS" +.Cd "device hwt" +.Pp +At least one of: +.Cd "device intel_pt" +.Pq amd64 +.Cd "device coresight" +.Pq arm64 +.Cd "device spe" +.Pq arm64 +.Pp +In +.Xr rc.conf 5 : +.Cd kld_list="hwt" +.Sh DESCRIPTION +The +.Nm +framework provides infrastructure for hardware-assisted tracing. +It collects detailed information about software execution and stores it as +events in highly compressed format into DRAM. +The events cover information about control flow changes of a program, whether +branches taken or not, exceptions taken, timing information, cycles elapsed and +more. +The information collected allows to reconstruct entire program flow of a given +application without noticeable performance impact. +.Sh HARDWARE +The framework supports several tracing technologies found on +.Cd arm64 +and +.Cd amd64 +systems: +.Pp +.Bl -bullet -compact +.It +ARM Coresight +.It +ARM Statistical Profiling Extension (SPE) +.It +Intel Processor Trace (PT) +.El +.Pp +The +.Nm +framework supports two modes of operation: +.Bl -tag -width "Thread mode" +.It Em CPU mode +Capture CPU activity in kernel mode. +.It Em Thread mode +Capture activity of each of a process's threads in user mode. +.El +.Sh MANAGEMENT +When loaded into kernel, the +.Nm +framework provides +.Pa /dev/hwt +character device. +The only +.Xr ioctl 2 +request it accepts is +.Dv HWT_IOC_ALLOC . +This request allocates kernel tracing context (CTX) based on requested mode of +operation, set of CPUs and/or pid. +.Pp +Upon successful CTX allocation, the ioctl returns a CTX identification +number (ident). +.Pp +Each CTX is then managed using its own dedicated character device found at +.Pa "/dev/hwt_${ident}_${d}", +where ident is a unique identification number of tracing context, d is either +cpu_id (in HWT CPU mode) or process pid (in HWT Thread mode). +.Sh HOOKS +During tracing of a target process, HWT records runtime events such as threads +creation, exec and mmap system calls. +These events are logged as "records" within a particular CTX associated with +traced process. +.Pp +Additionally, HWT can suspend the target thread upon exec or mmap system calls +if requested by the user. +This pause allows user-space tools to retrieve the records and adjust tracing +settings before execution continues. +This feature is especially useful when address range filtering is enabled, +allowing tracing of specific functions within the target executable or a +dynamic library. +.Sh KERNEL OPTIONS +The following options in the kernel configuration file are mandatory and +related to +.Nm +operation: +.Pp +.Bl -tag -width ".Dv HWT_HOOKS" -compact +.It Dv HWT_HOOKS +Enable kernel hooks. +.El +.Sh IOCTL INTERFACE +Once a CTX is allocated, its management character device accepts several +.Xr ioctl 2 +requests: +.Bl -tag -width "HWT_IOC_RECORD_GET" +.It Dv HWT_IOC_START +Start tracing. +In HWT CPU mode the tracing does actually start with this +.Xr ioctl 2 +request. +In the Thread mode, the tracing "running" flag set, but tracing begins after +scheduler switches the target thread onto CPU and return to user mode. +.It Dv HWT_IOC_STOP +Stop tracing of the particular CTX. +.It Dv HWT_IOC_RECORD_GET +Copy all or part of records collected during hook invocation and associated +with this CTX to userspace. +.It Dv HWT_IOC_BUFPTR_GET +Get current pointer in buffer that is filled by tracing units in real-time. +.It Dv HWT_IOC_SET_CONFIG +Set architecture-specific config (optional). +.It Dv HWT_IOC_WAKEUP +Wake up a thread that has been put to sleep by HWT framework hooks. +.It Dv HWT_IOC_SVC_BUF +For SPE-only, the kernel is waiting for userspace to notify that it has copied +out a buffer to avoid data loss/overwriting buffers. +.El +.Sh SEE ALSO +.Xr tracing 7 , +.Xr hwt 8 +.Sh HISTORY +The +.Nm +framework first appeared in +.Fx 15.0 . +.Sh AUTHORS +.An Ruslan Bukin Aq Mt br@FreeBSD.org +.An Bojan Novković Aq Mt bnovkov@freebsd.org +.An Zachary Leaf Aq Mt zachary.leaf@arm.com diff --git a/static/freebsd/man4/i2ctinyusb.4 b/static/freebsd/man4/i2ctinyusb.4 new file mode 100644 index 00000000..78169a05 --- /dev/null +++ b/static/freebsd/man4/i2ctinyusb.4 @@ -0,0 +1,85 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2024 Denis Bodor +.\" +.\" 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 February 18, 2024 +.Dt I2CTINYUSB 4 +.Os +.Sh NAME +.Nm i2ctinyusb +.Nd driver for a USB / I2C bridge device +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device i2ctinyusb" +.Cd "device usb" +.Cd "device iicbus" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +i2ctinyusb_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the device designed by Till Harbaum known +as i2c-tiny-usb. This is initially a very simple circuit built with +an Atmel AVR ATtiny45, but a Raspberry Pi Pico (RP2040) implementation +also exists. +.Pp +The +.Nm +driver creates a +.Xr iicbus 4 +child bus to expose the iic functions, enabling I2C sensors, converters +and displays to be connected to any computer with a USB port. +.Pp +More information about this device can be found at: +.Bd -literal -offset indent +https://github.com/harbaum/I2C-Tiny-USB +.Ed +.Pp +and (for the Raspberry Pi Pico version): +.Bd -literal -offset indent +https://github.com/Nicolai-Electronics/rp2040-i2c-interface +.Ed +.Pp +The I2C controller supports read and write transactions with up to 1024 +bytes of data, and a write followed by the repeated start followed by a +read transactions up to 1024 bytes. +Zero length transfers are not supported. +.Sh SEE ALSO +.Xr iicbus 4 , +.Xr usb 4 +.Sh HISTORY +The +.Nm +driver and this manual page was written by +.An Denis Bodor Aq Mt dbodor@rollmops.ninja . diff --git a/static/freebsd/man4/iavf.4 b/static/freebsd/man4/iavf.4 new file mode 100644 index 00000000..d55e084e --- /dev/null +++ b/static/freebsd/man4/iavf.4 @@ -0,0 +1,353 @@ +.\"- +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" Copyright (c) 2013-2018, Intel Corporation +.\" 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. Neither the name of the Intel Corporation nor the names of its +.\" contributors may be used to endorse or promote products derived from +.\" this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 COPYRIGHT OWNER 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. +.\" +.\" * Other names and brands may be claimed as the property of others. +.\" +.Dd May 21, 2024 +.Dt IAVF 4 +.Os +.Sh NAME +.Nm iavf +.Nd "Intel Ethernet Adaptive Virtual Function Driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device iflib" +.Cd "device iavf" +.Ed +.Pp +To load the driver as a module at boot time, place the following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_iavf_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for any PCI Virtual Function created from certain +Intel Ethernet devices. +This driver is compatible with virtual functions bound to devices based on the +following: +.Pp +.Bl -bullet -compact +.It +Intel\(rg Ethernet Controller E810\-C +.It +Intel\(rg Ethernet Controller E810\-XXV +.It +Intel\(rg Ethernet Connection E822\-C +.It +Intel\(rg Ethernet Connection E822\-L +.It +Intel\(rg Ethernet Connection E823\-C +.It +Intel\(rg Ethernet Connection E823\-L +.It +Intel\(rg Ethernet Controller I710 +.It +Intel\(rg Ethernet Controller X710 +.It +Intel\(rg Ethernet Controller XL710 +.It +Intel\(rg Ethernet Network Connection X722 +.It +Intel\(rg Ethernet Controller XXV710 +.It +Intel\(rg Ethernet Controller V710 +.El +.Pp +The associated Physical Function (PF) drivers for this VF driver are: +.Pp +.Bl -bullet -compact +.It +.Xr ice 4 +.It +.Xr ixl 4 +.El +.Pp +For questions related to hardware requirements, refer to the documentation +supplied with your Intel Ethernet Adapter. +All hardware requirements listed apply to use with +.Fx . +.Ss The VF Driver +The VF driver is normally used in a virtualized environment where a host driver +manages SR\-IOV, and provides a VF device to the guest. +.Pp +In the +.Fx +guest, the iavf driver would be loaded and will function using +the VF device assigned to it. +.Pp +The VF driver provides most of the same functionality as the core driver, but +is actually a subordinate to the host. +Access to many controls is accomplished by a request to the host via what is +called the "Admin queue." +These are startup and initialization events, however; once in operation, the +device is self\-contained and should achieve near native performance. +.Pp +Some notable limitations of the VF environment: +.Bl -bullet +.It +The PF can configure the VF to allow promiscuous mode, using a configuration +parameter in +.Xr iovctl.conf 5 ; +otherwise, promiscuous mode will not work +.It +Media info is not available from the PF, so the active media will always be +displayed as auto in +.Xr ifconfig 8 +.El +.Ss Adaptive Virtual Function +Adaptive Virtual Function (AVF) allows the virtual function driver, or VF, to +adapt to changing feature sets of the physical function driver (PF) with which +it is associated. +This allows system administrators to update a PF without having to update all +the VFs associated with it. +All AVFs have a single common device ID and branding string. +.Pp +AVFs have a minimum set of features known as "base mode," but may provide +additional features depending on what features are available in the PF with +which the AVF is associated. +The following are base mode features: +.Bl -bullet -compact +.It +4 Queue Pairs (QP) and associated Configuration Status Registers (CSRs) +for Tx/Rx +.It +iavf descriptors and ring format +.It +Descriptor write\-back completion +.It +1 control queue, with iavf descriptors, CSRs and ring format +.It +5 MSI\-X interrupt vectors and corresponding iavf CSRs +.It +1 Interrupt Throttle Rate (ITR) index +.It +1 Virtual Station Interface (VSI) per VF +.It +1 Traffic Class (TC), TC0 +.It +Receive Side Scaling (RSS) with 64 entry indirection table and key, +configured through the PF +.It +1 unicast MAC address reserved per VF +.It +8 MAC address filters for each VF on an Intel\(rg Ethernet 800 Series device +.It +16 MAC address filters for each VF on an Intel\(rg Ethernet 700 Series device +.It +Stateless offloads \- non\-tunneled checksums +.It +AVF device ID +.It +HW mailbox is used for VF to PF communications +.El +.Sh CONFIGURATION AND TUNING +.Ss Important System Configuration Changes +It is important to note that 100G operation can generate high +numbers of interrupts, often incorrectly being interpreted as +a storm condition in the kernel. +It is suggested that this be resolved by setting +.Va hw.intr_storm_threshold +to 0. +.Pp +The default is 1000. +.Pp +Best throughput results are seen with a large MTU; use 9706 if possible. +The default number of descriptors per ring is 1024. +Increasing this may improve performance, depending on your use case. +.Ss Configuring for no iflib +.Xr iflib 4 +is a common framework for network interface drivers for +.Fx +that uses a shared set of sysctl names. +.Pp +The default +.Nm +driver depends on it, but it can be compiled without it. +.Ss Jumbo Frames +Jumbo Frames support is enabled by changing the Maximum Transmission Unit (MTU) +to a value larger than the default value of 1500. +.Pp +Use the +.Xr ifconfig 8 +command to increase the MTU size. +.Pp +To confirm the MTU used between two specific devices, use +.Xr route 8 : +.Bd -literal -offset indent +route get +.Ed +.Pp +NOTE: +.Bl -bullet +.It +The maximum MTU setting for jumbo frames is 9706. +This corresponds to the maximum jumbo frame size of 9728 bytes. +.It +This driver will attempt to use multiple page-sized buffers to receive +each jumbo packet. +This should help to avoid buffer starvation issues when allocating receive +packets. +.It +Packet loss may have a greater impact on throughput when you use jumbo +frames. +If you observe a drop in performance after enabling jumbo frames, enabling +flow control may mitigate the issue. +.El +.Ss Checksum Offload +Checksum offloading supports both TCP and UDP packets and is supported for both +transmit and receive. +.Pp +TSO (TCP Segmentation Offload) supports both IPv4 and IPv6. +Both of these features are enabled and disabled via +.Xr ifconfig 8 . +.Pp +NOTE: +.Bl -bullet -compact +.It +TSO requires Tx checksum; if Tx checksum is disabled then TSO will also +be disabled. +.El +.Ss LRO +LRO (Large Receive Offload) may provide Rx performance improvement. +However, it is incompatible with packet\-forwarding workloads. +You should carefully evaluate the environment and enable LRO when possible. +.Ss Rx and Tx Descriptor Rings +Allows you to set the Rx and Tx descriptor rings independently. +Set them via these +.Xr iflib 4 +sysctls: +.Bl -tag -width indent +.It dev.iavf.#.iflib.override_nrxds +.It dev.iavf.#.iflib.override_ntxds +.El +.Ss Link\-Level Flow Control (LFC) +The VF driver does not have access to flow control settings. +It must be managed from the host side. +.Sh SEE ALSO +.Xr arp 4 , +.Xr ice 4 , +.Xr iflib 4 , +.Xr ixl 4 , +.Xr netintro 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Pp +See the +.Dq Intel\(rg Ethernet Adapters and Devices User Guide +for additional information on features. +It is available on the Intel website at either of the following: +.Bl -bullet +.It +.Lk https://cdrdv2.intel.com/v1/dl/getContent/705831 +.It +.Lk https://www.intel.com/content/www/us/en/download/19373/adapter\-user\-guide\-for\-intel\-ethernet\-adapters.html +.El +.Pp +For information on how to identify your adapter, and for the latest Intel +network drivers, refer to the Intel Support website: +.Aq Lk http://www.intel.com/support +.Sh CAVEATS +.Ss Driver Buffer Overflow Fix +The fix to resolve CVE\-2016\-8105, referenced in Intel SA\-00069 +.Aq Lk https://www.intel.com/content/www/us/en/security\-center/advisory/intel\-sa\-00069.html , +is included in this and future versions of the driver. +.Ss Network Memory Buffer Allocation +.Fx +may have a low number of network memory buffers (mbufs) by default. +If your mbuf value is too low, it may cause the driver to fail to initialize +and/or cause the system to become unresponsive. +You can check to see if the system is mbuf\-starved by running +.Li "netstat -m" . +Increase the number of mbufs by editing the lines below in +.Xr sysctl.conf 5 : +.Bd -literal -offset indent +kern.ipc.nmbclusters +kern.ipc.nmbjumbop +kern.ipc.nmbjumbo9 +kern.ipc.nmbjumbo16 +kern.ipc.nmbufs +.Ed +.Pp +The amount of memory that you allocate is system specific, and may require +some trial and error. +Also, increasing the following in +.Xr sysctl.conf 5 +could help increase +network performance: +.Bd -literal -offset indent +kern.ipc.maxsockbuf +net.inet.tcp.sendspace +net.inet.tcp.recvspace +net.inet.udp.maxdgram +net.inet.udp.recvspace +.Ed +.Ss UDP Stress Test Dropped Packet Issue +Under small packet UDP stress with the +.Nm +driver, the system may drop UDP packets due to socket buffers being full. +Setting the PF driver's Flow Control variables to the minimum may resolve the +issue. +.Ss Disable LRO when routing/bridging +LRO must be turned off when forwarding traffic. +.Sh SUPPORT +For general information, go to the Intel support website at +.Aq Lk http://www.intel.com/support/ . +.Pp +If an issue is identified with the released source code on a supported kernel +with a supported adapter, email the specific information related to the issue +to +.Aq Mt freebsd@intel.com . +.Sh LEGAL +Intel\(rg is a trademark or registered trademark of Intel Corporation +or its subsidiaries in the United States and / or other countries. +.Pp +Other names and brands may be claimed as the property of others. +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 10.1 +under the name +.Nm ixlv . +It was converted to use +.Xr iflib 4 +and renamed in +.Fx 12.4 . +.Sh AUTHORS +The +.Nm +driver was written by the +.An Intel Corporation Aq Mt freebsd@intel.com diff --git a/static/freebsd/man4/ice.4 b/static/freebsd/man4/ice.4 new file mode 100644 index 00000000..a54a6b3f --- /dev/null +++ b/static/freebsd/man4/ice.4 @@ -0,0 +1,1171 @@ +.\" +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" Copyright (c) 2019-2020, Intel Corporation +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms of the Software, 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. Neither the name of the Intel Corporation nor the names of its +.\" contributors may be used to endorse or promote products derived from +.\" this Software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 COPYRIGHT OWNER 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. +.\" +.\" * Other names and brands may be claimed as the property of others. +.\" +.Dd November 5, 2025 +.Dt ICE 4 +.Os +.Sh NAME +.Nm ice +.Nd Intel Ethernet 800 Series 1GbE to 200GbE driver +.Sh SYNOPSIS +.Cd device iflib +.Cd device ice +.Pp +In +.Xr loader.conf 5 : +.Cd if_ice_load +.Cd hw.ice.enable_health_events +.Cd hw.ice.irdma +.Cd hw.ice.irdma_max_msix +.Cd hw.ice.debug.enable_tx_fc_filter +.Cd hw.ice.debug.enable_tx_lldp_filter +.Cd hw.ice.debug.ice_tx_balance_en +.Pp +In +.Xr sysctl.conf 5 +or +.Xr loader.conf 5 : +.Cd dev.ice.#.current_speed +.Cd dev.ice.#.fw_version +.Cd dev.ice.#.ddp_version +.Cd dev.ice.#.pba_number +.Cd dev.ice.#.hw.mac.* +.Sh DESCRIPTION +The +.Nm +driver provides support for any PCI Express adapter or LOM +.Pq LAN On Motherboard +in the Intel Ethernet 800 Series. +.Pp +The following topics are covered in this manual: +.Pp +.Bl -bullet -compact +.It +.Sx Features +.It +.Sx Dynamic Device Personalization +.It +.Sx Jumbo Frames +.It +.Sx Remote Direct Memory Access +.It +.Sx RDMA Monitoring +.It +.Sx Data Center Bridging +.It +.Sx L3 QoS Mode +.It +.Sx Firmware Link Layer Discovery Protocol Agent +.It +.Sx Link-Level Flow Control +.It +.Sx Forward Error Correction +.It +.Sx Speed and Duplex Configuration +.It +.Sx Disabling physical link when the interface is brought down +.It +.Sx Firmware Logging +.It +.Sx Debug Dump +.It +.Sx Debugging PHY Statistics +.It +.Sx Transmit Balancing +.It +.Sx Thermal Monitoring +.It +.Sx Network Memory Buffer Allocation +.It +.Sx Additional Utilities +.It +.Sx Optics and auto-negotiation +.It +.Sx PCI-Express Slot Bandwidth +.It +.Sx HARDWARE +.It +.Sx LOADER TUNABLES +.It +.Sx SYSCTL VARIABLES +.It +.Sx INTERRUPT STORMS +.It +.Sx IOVCTL OPTIONS +.It +.Sx SUPPORT +.It +.Sx SEE ALSO +.It +.Sx HISTORY +.El +.Ss Features +Support for Jumbo Frames is provided via the interface MTU setting. +Selecting an MTU larger than 1500 bytes with the +.Xr ifconfig 8 +utility configures the adapter to receive and transmit Jumbo Frames. +The maximum MTU size for Jumbo Frames is 9706. +For more information, see the +.Sx Jumbo Frames +section. +.Pp +This driver version supports VLANs. +For information on enabling VLANs, see +.Xr vlan 4 . +For additional information on configuring VLANs, see +.Xr ifconfig 8 Ap s +.Dq VLAN Parameters +section. +.Pp +Offloads are also controlled via the interface, for instance, checksumming for +both IPv4 and IPv6 can be set and unset, TSO4 and/or TSO6, and finally LRO can +be set and unset. +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Pp +The associated Virtual Function (VF) driver for this driver is +.Xr iavf 4 . +.Pp +The associated RDMA driver for this driver is +.Xr irdma 4 . +.Ss Dynamic Device Personalization +The DDP package loads during device initialization. +The driver looks for the +.Sy ice_ddp +module and checks that it contains a valid DDP package file. +.Pp +If the driver is unable to load the DDP package, the device will enter Safe +Mode. +Safe Mode disables advanced and performance features and supports only +basic traffic and minimal functionality, such as updating the NVM or +downloading a new driver or DDP package. +Safe Mode only applies to the affected physical function and does not impact +any other PFs. +See the +.Dq Intel Ethernet Adapters and Devices User Guide +for more details on DDP and Safe Mode. +.Pp +If issues are encountered with the DDP package file, an updated driver or +.Sy ice_ddp +module may need to be downloaded. +See the log messages for more information. +.Pp +The DDP package cannot be updated if any PF drivers are already loaded. +To overwrite a package, unload all PFs and then reload the driver with the +new package. +.Pp +Only one DDP package can be used per driver, +even if more than one installed device uses the driver. +.Pp +Only the first loaded PF per device can download a package for that device. +.Ss Jumbo Frames +Jumbo Frames support is enabled by changing the Maximum Transmission Unit (MTU) +to a value larger than the default value of 1500. +.Pp +Use +.Xr ifconfig 8 +to increase the MTU size. +.Pp +The maximum MTU setting for jumbo frames is 9706. +This corresponds to the maximum jumbo frame size of 9728 bytes. +.Pp +This driver will attempt to use multiple page sized buffers to receive +each jumbo packet. +This should help to avoid buffer starvation issues when allocating receive +packets. +.Pp +Packet loss may have a greater impact on throughput when jumbo frames are in +use. +If a drop in performance is observed after enabling jumbo frames, enabling +flow control may mitigate the issue. +.Ss Remote Direct Memory Access +Remote Direct Memory Access, or RDMA, allows a network device to transfer data +directly to and from application memory on another system, increasing +throughput and lowering latency in certain networking environments. +.Pp +The ice driver supports both the iWARP (Internet Wide Area RDMA Protocol) and +RoCEv2 (RDMA over Converged Ethernet) protocols. +The major difference is that iWARP performs RDMA over TCP, while RoCEv2 uses +UDP. +.Pp +Devices based on the Intel Ethernet 800 Series do not support RDMA when +operating in multiport mode with more than 4 ports. +.Pp +For detailed installation and configuration information for RDMA, see +.Xr irdma 4 . +.Ss RDMA Monitoring +For debugging/testing purposes, a sysctl can be used to set up a mirroring +interface on a port. +The interface can receive mirrored RDMA traffic for packet +analysis tools like +.Xr tcpdump 1 . +This mirroring may impact performance. +.Pp +To use RDMA monitoring, more MSI-X interrupts may need to be reserved. +Before the +.Nm +driver loads, configure the following tunable provided by +.Xr iflib 4 : +.Bd -literal -offset indent +dev.ice..iflib.use_extra_msix_vectors=4 +.Ed +.Pp +The number of extra MSI-X interrupt vectors may need to be adjusted. +.Pp +To create/delete the interface: +.Bd -literal -offset indent +sysctl dev.ice..create_interface=1 +sysctl dev.ice..delete_interface=1 +.Ed +.Pp +The mirrored interface receives both LAN and RDMA traffic. +Additional filters can be configured in tcpdump. +.Pp +To differentiate the mirrored interface from the primary interface, the network +interface naming convention is: +.Bd -literal -offset indent + +.Ed +.Pp +For example, +.Dq Li ice0m0 +is the first mirroring interface on +.Dq Li ice0 . +.Ss Data Center Bridging +Data Center Bridging (DCB) is a configuration Quality of Service +implementation in hardware. +It uses the VLAN priority tag (802.1p) to filter traffic. +That means that there are 8 different priorities that traffic can be filtered +into. +It also enables priority flow control (802.1Qbb) which can limit or eliminate +the number of dropped packets during network stress. +Bandwidth can be allocated to each of these priorities, which is enforced at +the hardware level (802.1Qaz). +.Pp +DCB is normally configured on the network using the DCBX protocol (802.1Qaz), a +specialization of LLDP (802.1AB). The +.Nm +driver supports the following mutually exclusive variants of DCBX support: +.Pp +.Bl -bullet -compact +.It +Firmware-based LLDP Agent +.It +Software-based LLDP Agent +.El +.Pp +In firmware-based mode, firmware intercepts all LLDP traffic and handles DCBX +negotiation transparently for the user. +In this mode, the adapter operates in +.Dq willing +DCBX mode, receiving DCB settings from the link partner (typically a +switch). +The local user can only query the negotiated DCB configuration. +For information on configuring DCBX parameters on a switch, please consult the +switch manufacturer'ss documentation. +.Pp +In software-based mode, LLDP traffic is forwarded to the network stack and user +space, where a software agent can handle it. +In this mode, the adapter can operate in +.Dq nonwilling +DCBX mode and DCB configuration can be both queried and set locally. +This mode requires the FW-based LLDP Agent to be disabled. +.Pp +Firmware-based mode and software-based mode are controlled by the +.Dq fw_lldp_agent +sysctl. +Refer to the Firmware Link Layer Discovery Protocol Agent section for more +information. +.Pp +Link-level flow control and priority flow control are mutually exclusive. +The ice driver will disable link flow control when priority flow control +is enabled on any traffic class (TC). +It will disable priority flow control when link flow control is enabled. +.Pp +To enable/disable priority flow control in software-based DCBX mode: +.Bd -literal -offset indent +sysctl dev.ice..pfc=1 (or 0 to disable) +.Ed +.Pp +Enhanced Transmission Selection (ETS) allows bandwidth to be assigned to certain +TCs, to help ensure traffic reliability. +To view the assigned ETS configuration, use the following: +.Bd -literal -offset indent +sysctl dev.ice..ets_min_rate +.Ed +.Pp +To set the minimum ETS bandwidth per TC, separate the values by commas. +All values must add up to 100. +For example, to set all TCs to a minimum bandwidth of 10% and TC 7 to 30%, +use the following: +.Bd -literal -offset indent +sysctl dev.ice..ets_min_rate=10,10,10,10,10,10,10,30 +.Ed +.Pp +To set the User Priority (UP) to a TC mapping for a port, separate the values +by commas. +For example, to map UP 0 and 1 to TC 0, UP 2 and 3 to TC 1, UP 4 and +5 to TC 2, and UP 6 and 7 to TC 3, use the following: +.Bd -literal -offset indent +sysctl dev.ice..up2tc_map=0,0,1,1,2,2,3,3 +.Ed +.Ss L3 QoS Mode +The +.Nm +driver supports setting DSCP-based Layer 3 Quality of Service (L3 QoS) +in the PF driver. +The driver initializes in L2 QoS mode by default; L3 QoS is disabled by +default. +Use the following sysctl to enable or disable L3 QoS: +.Bd -literal -offset indent +sysctl dev.ice..pfc_mode=1 (or 0 to disable) +.Ed +.Pp +If L3 QoS mode is disabled, it returns to L2 QoS mode. +.Pp +To map a DSCP value to a traffic class, separate the values by commas. +For example, to map DSCPs 0-3 and DSCP 8 to DCB TCs 0-3 and 4, respectively: +.Bd -literal -offset indent +sysctl dev.ice..dscp2tc_map.0-7=0,1,2,3,0,0,0,0 +sysctl dev.ice..dscp2tc_map.8-15=4,0,0,0,0,0,0,0 +.Ed +.Pp +To change the DSCP mapping back to the default traffic class, set all the +values back to 0. +.Pp +To view the currently configured mappings, use the following: +.Bd -literal -offset indent +sysctl dev.ice..dscp2tc_map +.Ed +.Pp +L3 QoS mode is not available when FW-LLDP is enabled. +.Pp +FW-LLDP cannot be enabled if L3 QoS mode is active. +.Pp +Disable FW-LLDP before switching to L3 QoS mode. +.Pp +Refer to the +.Sx Firmware Link Layer Discovery Protocol Agent +section in this README for more information on disabling FW-LLDP. +.Ss Firmware Link Layer Discovery Protocol Agent +Use sysctl to change FW-LLDP settings. +The FW-LLDP setting is per port and persists across boots. +.Pp +To enable the FW-LLDP Agent: +.Bd -literal -offset indent +sysctl dev.ice..fw_lldp_agent=1 +.Ed +.Pp +To disable the FW-LLDP Agebt: +.Bd -literal -offset indent +sysctl dev.ice..fw_lldp_agent=0 +.Ed +.Pp +To check the current LLDP setting: +.Bd -literal -offset indent +sysctl dev.ice..fw_lldp_agent +.Ed +.Pp +The UEFI HII LLDP Agent attribute must be enabled for this setting +to take effect. +If the +.Dq LLDP AGENT +attribute is set to disabled, the FW-LLDP Agent cannot be enabled from the +driver. +.Ss Link-Level Flow Control +Ethernet Flow Control +.Pq IEEE 802.3x or LFC +can be configured with +.Xr sysctl 8 +to enable receiving and transmitting pause frames for +.Nm . +When transmit is enabled, pause frames are generated when the receive packet +buffer crosses a predefined threshold. +When receive is enabled, the transmit unit will halt for the time delay +specified in the firmware when a pause frame is received. +.Pp +Flow Control is disabled by default. +.Pp +Use sysctl to change the flow control settings for a single interface without +reloading the driver: +.Bd -literal -offset indent +sysctl dev.ice..fc +.Ed +.Pp +The available values for flow control are: +.Bd -literal -offset indent +0 = Disable flow control +1 = Enable Rx pause +2 = Enable Tx pause +3 = Enable Rx and Tx pause +.Ed +.Pp +Verify that link flow control was negotiated on the link by checking the +interface entry in +.Xr ifconfig 8 +and looking for the flags +.Dq txpause +and/or +.Dq rxpause +in the +.Dq media +status. +.Pp +The +.Nm +driver requires flow control on both the port and link partner. +If flow control is disabled on one of the sides, the port may appear to +hang on heavy traffic. +.Pp +For more information on priority flow control, refer to the +.Sx Data Center Bridging +section. +.Pp +The VF driver does not have access to flow control. +It must be managed from the host side. +.Ss Forward Error Correction +Forward Error Correction (FEC) improves link stability but increases latency. +Many high quality optics, direct attach cables, and backplane channels can +provide a stable link without FEC. +.Pp +For devices to benefit from this feature, link partners must have FEC enabled. +.Pp +If the +.Va allow_no_fec_modules_in_auto +sysctl is enabled Auto FEC negotiation will include +.Dq No FEC +in case the link partner does not have FEC enabled or is not FEC capable: +.Bd -literal -offset indent +sysctl dev.ice..allow_no_fec_modules_in_auto=1 +.Ed +.Pp +NOTE: This flag is currently not supported on the Intel Ethernet 830 +Series. +.Pp +To show the current FEC settings that are negotiated on the link: +.Bd -literal -offset indent +sysctl dev.ice..negotiated_fec +.Ed +.Pp +To view or set the FEC setting that was requested on the link: +.Bd -literal -offset indent +sysctl dev.ice..requested_fec +.Ed +.Pp +To see the valid FEC modes for the link: +.Bd -literal -offset indent +sysctl -d dev.ice..requested_fec +.Ed +.Ss Speed and Duplex Configuration +The speed and duplex settings cannot be hard set. +.Pp +To have the device change the speeds it will use in auto-negotiation or +force link with: +.Bd -literal -offset indent +sysctl dev.ice..advertise_speed= +.Ed +.Pp +Supported speeds will vary by device. +Depending on the speeds the device supports, valid bits used in a speed mask +could include: +.Bd -literal -offset indent +0x0 - Auto +0x2 - 100 Mbps +0x4 - 1 Gbps +0x8 - 2.5 Gbps +0x10 - 5 Gbps +0x20 - 10 Gbps +0x80 - 25 Gbps +0x100 - 40 Gbps +0x200 - 50 Gbps +0x400 - 100 Gbps +0x800 - 200 Gbps +.Ed +.Ss Disabling physical link when the interface is brought down +When the +.Va link_active_on_if_down +sysctl is set to +.Dq 0 , +the port's link will go down when the interface is brought down. +By default, link will stay up. +.Pp +To disable link when the interface is down: +.Bd -literal -offset indent +sysctl dev.ice..link_active_on_if_down=0 +.Ed +.Ss Firmware Logging +The +.Nm +driver allows for the generation of firmware logs for supported categories of +events, to help debug issues with Customer Support. +Refer to the +.Dq Intel Ethernet Adapters and Devices User Guide +for an overview of this feature and additional tips. +.Pp +At a high level, to capture a firmware log: +.Bl -enum -compact +.It +Set the configuration for the firmware log. +.It +Perform the necessary steps to reproduce the issue. +.It +Capture the firmware log. +.It +Stop capturing the firmware log. +.It +Reset the firmware log settings as needed. +.It +Work with Customer Support to debug the issue. +.El +.Pp +NOTE: Firmware logs are generated in a binary format and must be decoded by +Customer Support. +Information collected is related only to firmware and hardware for debug +purposes. +.Pp +Once the driver is loaded, it will create the +.Va fw_log +sysctl node under the debug section of the driver's sysctl list. +The driver groups these events into categories, called +.Dq modules . +Supported modules include: +.Pp +.Bl -tag -offset indent -compact -width "task_dispatch" +.It Va general +General (Bit 0) +.It Va ctrl +Control (Bit 1) +.It Va link +Link Management (Bit 2) +.It Va link_topo +Link Topology Detection (Bit 3) +.It Va dnl +Link Control Technology (Bit 4) +.It Va i2c +I2C (Bit 5) +.It Va sdp +SDP (Bit 6) +.It Va mdio +MDIO (Bit 7) +.It Va adminq +Admin Queue (Bit 8) +.It Va hdma +Host DMA (Bit 9) +.It Va lldp +LLDP (Bit 10) +.It Va dcbx +DCBx (Bit 11) +.It Va dcb +DCB (Bit 12) +.It Va xlr +XLR (function-level resets; Bit 13) +.It Va nvm +NVM (Bit 14) +.It Va auth +Authentication (Bit 15) +.It Va vpd +Vital Product Data (Bit 16) +.It Va iosf +Intel On-Chip System Fabric (Bit 17) +.It Va parser +Parser (Bit 18) +.It Va sw +Switch (Bit 19) +.It Va scheduler +Scheduler (Bit 20) +.It Va txq +TX Queue Management (Bit 21) +.It Va acl +ACL (Access Control List; Bit 22) +.It Va post +Post (Bit 23) +.It Va watchdog +Watchdog (Bit 24) +.It Va task_dispatch +Task Dispatcher (Bit 25) +.It Va mng +Manageability (Bit 26) +.It Va synce +SyncE (Bit 27) +.It Va health +Health (Bit 28) +.It Va tsdrv +Time Sync (Bit 29) +.It Va pfreg +PF Registration (Bit 30) +.It Va mdlver +Module Version (Bit 31) +.El +.Pp +The verbosity level of the firmware logs can be modified. +It is possible to set only one log level per module, and each level includes the +verbosity levels lower than it. +For instance, setting the level to +.Dq normal +will also log warning and error messages. +Available verbosity levels are: +.Pp +.Bl -item -offset indent -compact +.It +0 = none +.It +1 = error +.It +2 = warning +.It +3 = normal +.It +4 = verbose +.El +.Pp +To set the desired verbosity level for a module, use the following sysctl +command and then register it: +.Bd -literal -offset indent +sysctl dev.ice..debug.fw_log.severity.= +.Ed +.Pp +For example: +.Bd -literal -offset indent +sysctl dev.ice.0.debug.fw_log.severity.link=1 +sysctl dev.ice.0.debug.fw_log.severity.link_topo=2 +sysctl dev.ice.0.debug.fw_log.register=1 +.Ed +.Pp +To log firmware messages after booting, but before the driver initializes, use +.Xr kenv 1 +to set the tunable. +The +.Va on_load +setting tells the device to register the variable as soon as possible during +driver load. +For example: +.Bd -literal -offset indent +kenv dev.ice.0.debug.fw_log.severity.link=1 +kenv dev.ice.0.debug.fw_log.severity.link_topo=2 +kenv dev.ice.0.debug.fw_log.on_load=1 +.Ed +.Pp +To view the firmware logs and redirect them to a file, use the following +command: +.Bd -literal -offset indent +dmesg > log_output +.Ed +.Pp +NOTE: Logging a large number of modules or too high of a verbosity level will +add extraneous messages to dmesg and could hinder debug efforts. +.Ss Debug Dump +Intel Ethernet 800 Series devices support debug dump, +which allows gathering of runtime register values from the firmware for +.Dq clusters +of events and then write the results to a single dump file, for debugging +complicated issues in the field. +.Pp +This debug dump contains a snapshot of the device and its existing hardware +configuration, such as switch tables, transmit scheduler tables, and other +information. +Debug dump captures the current state of the specified cluster(s) and is a +stateless snapshot of the whole device. +.Pp +NOTE: Like with firmware logs, the contents of the debug dump are not +human-readable. +Work with Customer Support to decode the file. +.Pp +Debug dump is per device, not per PF. +.Pp +Debug dump writes all information to a single file. +.Pp +To generate a debug dump file in +.Fx +do the following: +.Pp +Specify the cluster(s) to include in the dump file, using a bitmask and the +following command: +.Bd -literal -offset indent +sysctl dev.ice..debug.dump.clusters= +.Ed +.Pp +To print the complete cluster bitmask and parameter list to the screen, +pass the +.Fl d +argument. +For example: +.Bd -literal -offset indent +sysctl -d dev.ice.0.debug.dump.clusters +.Ed +.Pp +Possible bitmask values for +.Va clusters +are: +.Bl -bullet -compact +.It +0 - Dump all clusters (only supported on Intel Ethernet E810 Series and +Intel Ethernet E830 Series) +.It +0x1 - Switch +.It +0x2 - ACL +.It +0x4 - Tx Scheduler +.It +0x8 - Profile Configuration +.It +0x20 - Link +.It +0x80 - DCB +.It +0x100 - L2P +.It +0x400000 - Manageability Transactions (only supported on Intel Ethernet +E810 Series) +.El +.Pp +For example, to dump the Switch, DCB, and L2P clusters, use the following: +.Bd -literal -offset indent +sysctl dev.ice.0.debug.dump.clusters=0x181 +.Ed +.Pp +To dump all clusters, use the following: +.Bd -literal -offset indent +sysctl dev.ice.0.debug.dump.clusters=0 +.Ed +.Pp +NOTE: Using 0 will skip Manageability Transactions data. +.Pp +If a single cluster is not specified, +the driver will dump all clusters to a single file. +Issue the debug dump command, using the following: +.Bd -literal -offset indent +sysctl -b dev.ice..debug.dump.dump=1 > dump.bin +.Ed +.Pp +NOTE: The driver will not receive the command if the sysctl is not set to +.Dq 1 . +.Pp +Replace +.Dq dump.bin +above with the preferred file name. +.Pp +To clear the +.Va clusters +mask before a subsequent debug dump and then do the dump: +.Bd -literal -offset indent +sysctl dev.ice.0.debug.dump.clusters=0 +sysctl dev.ice.0.debug.dump.dump=1 +.Ed +.Ss Debugging PHY Statistics +The ice driver supports the ability to obtain the values of the PHY registers +from Intel(R) Ethernet 810 Series devices in order to debug link and +connection issues during runtime. +.Pp +The driver provides information about: +.Bl -bullet +.It +Rx and Tx Equalization parameters +.It +RS FEC correctable and uncorrectable block counts +.El +.Pp +Use the following sysctl to read the PHY registers: +.Bd -literal -offset indent +sysctl dev.ice..debug.phy_statistics +.Ed +.Pp +NOTE: The contents of the registers are not human-readable. +Like with firmware logs and debug dump, work with Customer Support +to decode the file. +.Ss Transmit Balancing +Some Intel(R) Ethernet 800 Series devices allow for enabling a transmit +balancing feature to improve transmit performance under certain conditions. +When enabled, this feature should provide more consistent transmit +performance across queues and/or PFs and VFs. +.Pp +By default, transmit balancing is disabled in the NVM. +To enable this feature, use one of the following to persistently change the +setting for the device: +.Bl -bullet +.It +Use the Ethernet Port Configuration Tool (EPCT) to enable the +.Va tx_balancing +option. +Refer to the EPCT readme for more information. +.It +Enable the Transmit Balancing device setting in UEFI HII. +.El +.Pp +When the driver loads, it reads the transmit balancing setting from the NVM and +configures the device accordingly. +.Pp +NOTE: The user selection for transmit balancing in EPCT or HII is persistent +across reboots. +The system must be rebooted for the selected setting to take effect. +.Pp +This setting is device wide. +.Pp +The driver, NVM, and DDP package must all support this functionality to +enable the feature. +.Ss Thermal Monitoring +Intel(R) Ethernet 810 Series and Intel(R) Ethernet 830 Series devices can +display temperature data (in degrees Celsius) via: +.Bd -literal -offset indent +sysctl dev.ice..temp +.Ed +.Ss Network Memory Buffer Allocation +.Fx +may have a low number of network memory buffers (mbufs) by default. +If the number of mbufs available is too low, it may cause the driver to fail +to initialize and/or cause the system to become unresponsive. +Check to see if the system is mbuf-starved by running +.Ic netstat Fl m . +Increase the number of mbufs by editing the lines below in +.Pa /etc/sysctl.conf : +.Bd -literal -offset indent +kern.ipc.nmbclusters +kern.ipc.nmbjumbop +kern.ipc.nmbjumbo9 +kern.ipc.nmbjumbo16 +kern.ipc.nmbufs +.Ed +.Pp +The amount of memory that should be allocated is system specific, +and may require some trial and error. +Also, increasing the following in +.Pa /etc/sysctl.conf +could help increase network performance: +.Bd -literal -offset indent +kern.ipc.maxsockbuf +net.inet.tcp.sendspace +net.inet.tcp.recvspace +net.inet.udp.maxdgram +net.inet.udp.recvspace +.Ed +.Ss Additional Utilities +There are additional tools available from Intel to help configure and update +the adapters covered by this driver. +These tools can be downloaded directly from Intel at +.Lk https://downloadcenter.intel.com , +by searching for their names: +.Bl -bullet +.It +To change the behavior of the QSFP28 ports on E810-C adapters, use the Intel +.Sy Ethernet Port Configuration Tool - FreeBSD . +.It +To update the firmware on an adapter, use the Intel +.Sy Non-Volatile Memory (NVM) Update Utility for Intel Ethernet Network Adapters E810 series - FreeBSD +.El +.Ss Optics and auto-negotiation +Modules based on 100GBASE-SR4, +active optical cable (AOC), and active copper cable (ACC) +do not support auto-negotiation per the IEEE specification. +To obtain link with these modules, +auto-negotiation must be turned off on the link partner's switch ports. +.Pp +Note that adapters also support +all passive and active limiting direct attach cables +that comply with SFF-8431 v4.1 and SFF-8472 v10.4 specifications. +.Ss PCI-Express Slot Bandwidth +Some PCIe x8 slots are actually configured as x4 slots. +These slots have insufficient bandwidth +for full line rate with dual port and quad port devices. +In addition, +if a PCIe v4.0 or v3.0-capable adapter is placed into into a PCIe v2.x +slot, full bandwidth will not be possible. +.Pp +The driver detects this situation and +writes the following message in the system log: +.Bd -ragged -offset indent +PCI-Express bandwidth available for this device +may be insufficient for optimal performance. +Please move the device to a different PCI-e link +with more lanes and/or higher transfer rate. +.Ed +.Pp +If this error occurs, +moving the adapter to a true PCIe x8 or x16 slot will resolve the issue. +For best performance, install devices in the following PCI slots: +.Bl -bullet +.It +Any 100Gbps-capable Intel(R) Ethernet 800 Series device: Install in a +PCIe v4.0 x8 or v3.0 x16 slot +.It +A 200Gbps-capable Intel(R) Ethernet 830 Series device: Install in a +PCIe v5.0 x8 or v4.0 x16 slot +.El +.Pp +For questions related to hardware requirements, +refer to the documentation supplied with the adapter. +.Sh HARDWARE +The +.Nm +driver supports the following +Intel 800 series 1Gb to 200Gb Ethernet controllers: +.Pp +.Bl -bullet -compact +.It +Intel Ethernet Controller E810-C +.It +Intel Ethernet Controller E810-XXV +.It +Intel Ethernet Connection E822-C +.It +Intel Ethernet Connection E822-L +.It +Intel Ethernet Connection E823-C +.It +Intel Ethernet Connection E823-L +.It +Intel Ethernet Connection E825-C +.It +Intel Ethernet Connection E830-C +.It +Intel Ethernet Connection E830-CC +.It +Intel Ethernet Connection E830-L +.It +Intel Ethernet Connection E830-XXV +.It +Intel Ethernet Connection E835-C +.It +Intel Ethernet Connection E835-CC +.It +Intel Ethernet Connection E835-L +.It +Intel Ethernet Connection E835-XXV +.El +.Pp +The +.Nm +driver supports some adapters in this series with SFP28/QSFP28 cages +which have firmware that requires that Intel qualified modules are used; +these qualified modules are listed below. +This qualification check cannot be disabled by the driver. +.Pp +The +.Nm +driver supports 100Gb Ethernet adapters with these QSFP28 modules: +.Pp +.Bl -bullet -compact +.It +Intel 100G QSFP28 100GBASE-SR4 E100GQSFPSR28SRX +.It +Intel 100G QSFP28 100GBASE-SR4 SPTMBP1PMCDF +.It +Intel 100G QSFP28 100GBASE-CWDM4 SPTSBP3CLCCO +.It +Intel 100G QSFP28 100GBASE-DR SPTSLP2SLCDF +.El +.Pp +The +.Nm +driver supports 25Gb and 10Gb Ethernet adapters with these SFP28 modules: +.Pp +.Bl -bullet -compact +.It +Intel 10G/25G SFP28 25GBASE-SR E25GSFP28SR +.It +Intel 25G SFP28 25GBASE-SR E25GSFP28SRX (Extended Temp) +.It +Intel 25G SFP28 25GBASE-LR E25GSFP28LRX (Extended Temp) +.El +.Pp +The +.Nm +driver supports 10Gb and 1Gb Ethernet adapters with these SFP+ modules: +.Pp +.Bl -bullet -compact +.It +Intel 1G/10G SFP+ 10GBASE-SR E10GSFPSR +.It +Intel 1G/10G SFP+ 10GBASE-SR E10GSFPSRG1P5 +.It +Intel 1G/10G SFP+ 10GBASE-SR E10GSFPSRG2P5 +.It +Intel 10G SFP+ 10GBASE-SR E10GSFPSRX (Extended Temp) +.It +Intel 1G/10G SFP+ 10GBASE-LR E10GSFPLR +.El +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +See the +.Xr iflib 4 +man page for more information on using iflib sysctl variables as tunables. +.Bl -tag -width indent +.It Va hw.ice.enable_health_events +Set to 1 to enable firmware health event reporting across all devices. +Enabled by default. +.Pp +If enabled, when the driver receives a firmware health event message, it will +print out a description of the event to the kernel message buffer and if +applicable, possible actions to take to remedy it. +.It Va hw.ice.irdma +Set to 1 to enable the RDMA client interface, required by the +.Xr irdma 4 +driver. +Enabled by default. +.It Va hw.ice.rdma_max_msix +Set the maximum number of per-device MSI-X vectors that are allocated for use +by the +.Xr irdma 4 +driver. +Set to 64 by default. +.It Va hw.ice.debug.enable_tx_fc_filter +Set to 1 to enable the TX Flow Control filter across all devices. +Enabled by default. +.Pp +If enabled, the hardware will drop any transmitted Ethertype 0x8808 control +frames that do not originate from the hardware. +.It Va hw.ice.debug.enable_tx_lldp_filter +Set to 1 to enable the TX LLDP filter across all devices. +Enabled by default. +.Pp +If enabled, the hardware will drop any transmitted Ethertype 0x88cc LLDP frames +that do not originate from the hardware. +This must be disabled in order to use LLDP daemon software such as +.Xr lldpd 8 . +.It Va hw.ice.debug.ice_tx_balance_en +Set to 1 to allow the driver to use the 5-layer Tx Scheduler tree topology if +configured by the DDP package. +.Pp +Enabled by default. +.El +.Sh SYSCTL VARIABLES +.Bl -tag -width indent +.It Va dev.ice.#.current_speed +This is a display of the current link speed of the interface. +This is expected to match the speed of the media type in-use displayed by +.Xr ifconfig 8 . +.It Va dev.ice.#.fw_version +Displays the current firmware and NVM versions of the adapter. +This information should be submitted along with any support requests. +.It Va dev.ice.#.ddp_version +Displays the current DDP package version downloaded to the adapter. +This information should be submitted along with any support requests. +.It Va dev.ice.#.pba_number +Displays the Product Board Assembly Number. +May be used to help identify the type of adapter in use. +This sysctl may not exist depending on the adapter type. +.It Va dev.ice.#.hw.mac.* +This sysctl tree contains statistics collected by the hardware for the port. +.El +.Sh INTERRUPT STORMS +It is important to note that 100G operation can generate high +numbers of interrupts, often incorrectly being interpreted as +a storm condition in the kernel. +It is suggested that this be resolved by setting +.Va hw.intr_storm_threshold +to 0. +.Sh IOVCTL OPTIONS +The driver supports additional optional parameters for created VFs +(Virtual Functions) when using +.Xr iovctl 8 : +.Bl -tag -width indent +.It mac-addr Pq unicast-mac +Set the Ethernet MAC address that the VF will use. +If unspecified, the VF will use a randomly generated MAC address and +.Dq allow-set-mac +will be set to true. +.It mac-anti-spoof Pq bool +Prevent the VF from sending Ethernet frames with a source address +that does not match its own. +Enabled by default. +.It allow-set-mac Pq bool +Allow the VF to set its own Ethernet MAC address. +Disallowed by default. +.It allow-promisc Pq bool +Allow the VF to inspect all of the traffic sent to the port that it is created +on. +Disabled by default. +.It num-queues Pq uint16_t +Specify the number of queues the VF will have. +By default, this is set to the number of MSI-X vectors supported by the VF +minus one. +.It mirror-src-vsi Pq uint16_t +Specify which VSI the VF will mirror traffic from by setting this to a value +other than -1. +All traffic from that VSI will be mirrored to this VF. +Can be used as an alternative method to mirror RDMA traffic to another +interface than the method described in the +.Sx RDMA Monitoring +section. +Not affected by the +.Dq allow-promisc +parameter. +.It max-vlan-allowed Pq uint16_t +Specify maximum number of VLAN filters that the VF can use. +Receiving traffic on a VLAN requires a hardware filter which are a finite +resource; this is used to prevent a VF from starving other VFs or the PF of +filter resources. +By default, this is set to 16. +.It max-mac-filters Pq uint16_t +Specify maximum number of MAC address filters that the VF can use. +Each allowed MAC address requires a hardware filter which are a finite +resource; this is used to prevent a VF from starving other VFs or the PF of +filter resources. +The VF's default mac address does not count towards this limit. +By default, this is set to 64. +.El +.Pp +An up to date list of parameters and their defaults can be found by using +.Xr iovctl 8 +with the +.Fl S +option. +.Pp +For more information on standard and mandatory parameters, see +.Xr iovctl.conf 5 . +.Sh SUPPORT +For general information and support, go to the Intel support website at: +.Lk http://www.intel.com/support/ . +.Pp +If an issue is identified with this driver with a supported adapter, +email all the specific information related to the issue to +.Aq Mt freebsd@intel.com . +.Sh SEE ALSO +.Xr iflib 4 , +.Xr vlan 4 , +.Xr ifconfig 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 12.2 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Intel Corporation Aq Mt freebsd@intel.com . diff --git a/static/freebsd/man4/ichsmb.4 b/static/freebsd/man4/ichsmb.4 new file mode 100644 index 00000000..95b645b1 --- /dev/null +++ b/static/freebsd/man4/ichsmb.4 @@ -0,0 +1,59 @@ +.\" Copyright (c) 1996-1999 Whistle Communications, Inc. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, use and +.\" redistribution of this software, in source or object code forms, with or +.\" without modifications are expressly permitted by Whistle Communications; +.\" provided, however, that: +.\" 1. Any and all reproductions of the source or object code must include the +.\" copyright notice above and the following disclaimer of warranties; and +.\" 2. No rights are granted, in any manner or form, to use Whistle +.\" Communications, Inc. trademarks, including the mark "WHISTLE +.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as +.\" such appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, +.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. +.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY +.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS +.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. +.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES +.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING +.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY +.\" OF SUCH DAMAGE. +.\" +.\" Author: Archie Cobbs +.\" +.Dd July 20, 2016 +.Dt ICHSMB 4 +.Os +.Sh NAME +.Nm ichsmb +.Nd Intel ICH SMBus controller driver +.Sh SYNOPSIS +.Cd device pci +.Cd device smbus +.Cd device smb +.Cd device ichsmb +.Sh DESCRIPTION +The +.Nm +driver provides +.Xr smbus 4 +support for the SMBus controller logical device contained in all Intel +motherboard chipsets starting from 82801AA (ICH). +.Sh SEE ALSO +.Xr intpm 4 , +.Xr ismt 4 , +.Xr smb 4 , +.Xr smbus 4 +.Sh AUTHORS +.An Archie L. Cobbs Aq Mt archie@FreeBSD.org diff --git a/static/freebsd/man4/ichwd.4 b/static/freebsd/man4/ichwd.4 new file mode 100644 index 00000000..25de7377 --- /dev/null +++ b/static/freebsd/man4/ichwd.4 @@ -0,0 +1,98 @@ +.\"- +.\" Copyright (c) 2007 Dag-Erling Smørgrav +.\" 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 January 3, 2026 +.Dt ICHWD 4 +.Os +.Sh NAME +.Nm ichwd +.Nd device driver for the Intel ICH watchdog interrupt timer +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ichwd" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ichwd_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides +.Xr watchdog 4 +support for the watchdog interrupt timer present on +all Intel ICH motherboard chipsets. +.Pp +The ICH WDT counts down in ticks of approximately 0.6 seconds; the +exact value depends on hardware quality and environmental factors. +Supported watchdog intervals range from 2 to 63 ticks. +.Pp +In QEMU, there is a dedicated watchdog implementation for x86 +systems based on the Intel 6300ESB controller hub. +Support for this watchdog is provided by this kernel module. +.Pp +Optionally, set the +.Va hw.i6300esbwd.x.locked=1 +.Xr sysctl 8 +to prevent users from disabling the watchdog timeout check +after it has been enabled. +.Pp +Note that on some ICH-based systems, the WDT may be present but +disabled, either in hardware or by the BIOS. +The +.Nm +driver attempts to detect this condition and will refuse to attach if +it believes the WDT is disabled. +.Sh SEE ALSO +.Xr watchdog 4 , +.Xr watchdog 8 , +.Xr watchdogd 8 , +.Xr watchdog 9 +.Rs +.%T Using the Intel ICH Family Watchdog Timer (WDT) +.%R Intel Application Note AP-725 +.%O Document Number 292273-001 +.Re +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 5.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Wm. Daryl Hawkins Aq Mt dhawkins@tamu.edu +of Texas A&M University and +.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . +This manual page was written by +.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . diff --git a/static/freebsd/man4/icmp.4 b/static/freebsd/man4/icmp.4 new file mode 100644 index 00000000..c8c92a79 --- /dev/null +++ b/static/freebsd/man4/icmp.4 @@ -0,0 +1,276 @@ +.\" Copyright (c) 1986, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 December 11, 2024 +.Dt ICMP 4 +.Os +.Sh NAME +.Nm icmp +.Nd Internet Control Message Protocol +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netinet/in.h +.Ft int +.Fn socket AF_INET SOCK_RAW proto +.Sh DESCRIPTION +.Tn ICMP +is the error and control message protocol used +by +.Tn IP +and the Internet protocol family. +It may be accessed +through a +.Dq raw socket +for network monitoring +and diagnostic functions. +The +.Fa proto +parameter to the socket call to create an +.Tn ICMP +socket +is obtained from +.Xr getprotobyname 3 . +.Tn ICMP +sockets are connectionless, +and are normally used with the +.Xr sendto 2 +and +.Xr recvfrom 2 +calls, though the +.Xr connect 2 +call may also be used to fix the destination for future +packets (in which case the +.Xr read 2 +or +.Xr recv 2 +and +.Xr write 2 +or +.Xr send 2 +system calls may be used). +.Pp +Outgoing packets automatically have an +.Tn IP +header prepended to +them (based on the destination address). +Incoming packets are received with the +.Tn IP +header and options intact. +.Ss Types +ICMP messages are classified according to the type and code fields +present in the ICMP header. +The abbreviations for the types and codes may be used in rules in +.Xr pf.conf 5 . +The following types are defined: +.Bl -column x xxxxxxxxxxxx -offset indent +.It Sy Num Ta Sy Abbrev. Ta Sy Description +.It 0 Ta echorep Ta "Echo reply" +.It 3 Ta unreach Ta "Destination unreachable" +.It 4 Ta squench Ta "Packet loss, slow down" +.It 5 Ta redir Ta "Shorter route exists" +.It 6 Ta althost Ta "Alternate host address" +.It 8 Ta echoreq Ta "Echo request" +.It 9 Ta routeradv Ta "Router advertisement" +.It 10 Ta routersol Ta "Router solicitation" +.It 11 Ta timex Ta "Time exceeded" +.It 12 Ta paramprob Ta "Invalid IP header" +.It 13 Ta timereq Ta "Timestamp request" +.It 14 Ta timerep Ta "Timestamp reply" +.It 15 Ta inforeq Ta "Information request" +.It 16 Ta inforep Ta "Information reply" +.It 17 Ta maskreq Ta "Address mask request" +.It 18 Ta maskrep Ta "Address mask reply" +.It 30 Ta trace Ta Traceroute +.It 31 Ta dataconv Ta "Data conversion problem" +.It 32 Ta mobredir Ta "Mobile host redirection" +.It 33 Ta ipv6-where Ta "IPv6 where-are-you" +.It 34 Ta ipv6-here Ta "IPv6 i-am-here" +.It 35 Ta mobregreq Ta "Mobile registration request" +.It 36 Ta mobregrep Ta "Mobile registration reply" +.It 39 Ta skip Ta SKIP +.It 40 Ta photuris Ta Photuris +.El +.Pp +The following codes are defined: +.Bl -column x xxxxxxxxxxxx xxxxxxxx -offset indent +.It Sy Num Ta Sy Abbrev. Ta Sy Type Ta Sy Description +.It 0 Ta net-unr Ta unreach Ta "Network unreachable" +.It 1 Ta host-unr Ta unreach Ta "Host unreachable" +.It 2 Ta proto-unr Ta unreach Ta "Protocol unreachable" +.It 3 Ta port-unr Ta unreach Ta "Port unreachable" +.It 4 Ta needfrag Ta unreach Ta "Fragmentation needed but DF bit set" +.It 5 Ta srcfail Ta unreach Ta "Source routing failed" +.It 6 Ta net-unk Ta unreach Ta "Network unknown" +.It 7 Ta host-unk Ta unreach Ta "Host unknown" +.It 8 Ta isolate Ta unreach Ta "Host isolated" +.It 9 Ta net-prohib Ta unreach Ta "Network administratively prohibited" +.It 10 Ta host-prohib Ta unreach Ta "Host administratively prohibited" +.It 11 Ta net-tos Ta unreach Ta "Invalid TOS for network" +.It 12 Ta host-tos Ta unreach Ta "Invalid TOS for host" +.It 13 Ta filter-prohib Ta unreach Ta "Prohibited access" +.It 14 Ta host-preced Ta unreach Ta "Precedence violation" +.It 15 Ta cutoff-preced Ta unreach Ta "Precedence cutoff" +.It 0 Ta redir-net Ta redir Ta "Shorter route for network" +.It 1 Ta redir-host Ta redir Ta "Shorter route for host" +.It 2 Ta redir-tos-net Ta redir Ta "Shorter route for TOS and network" +.It 3 Ta redir-tos-host Ta redir Ta "Shorter route for TOS and host" +.It 0 Ta normal-adv Ta routeradv Ta "Normal advertisement" +.It 16 Ta common-adv Ta routeradv Ta "Selective advertisement" +.It 0 Ta transit Ta timex Ta "Time exceeded in transit" +.It 1 Ta reassemb Ta timex Ta "Time exceeded in reassembly" +.It 0 Ta badhead Ta paramprob Ta "Invalid option pointer" +.It 1 Ta optmiss Ta paramprob Ta "Missing option" +.It 2 Ta badlen Ta paramprob Ta "Invalid length" +.It 1 Ta unknown-ind Ta photuris Ta "Unknown security index" +.It 2 Ta auth-fail Ta photuris Ta "Authentication failed" +.It 3 Ta decrypt-fail Ta photuris Ta "Decryption failed" +.El +.Ss MIB (sysctl) Variables +The +.Tn ICMP +protocol implements a number of variables in the +.Va net.inet.icmp +branch of the +.Xr sysctl 3 +MIB, which can also be read or modified with +.Xr sysctl 8 . +.Bl -tag -width ".Va icmplim_output" +.It Va bmcastecho +.Pq Vt boolean +Enable/disable ICMP replies received via broadcast or multicast. +Defaults to false. +.It Va drop_redirect +.Pq Vt boolean +Enable/disable dropping of ICMP Redirect packets. +Defaults to false. +.It Va icmplim +.Pq Vt unsigned integer +Mean rate limit for replies in packets/second. +The actual limit is +.Va icmplim +plus a random jitter limited by +.Va icmplim_jitter . +If set to zero, no limiting will occur. +Defaults to 200. +.It Va icmplim_jitter +.Pq Vt unsigned integer +A random jitter between the negative of +.Va icmplim_jitter +and +.Va icmplim_jitter +is applied to +.Va icmplim +for limiting the sending rate of replies. +.Va icmplim_jitter +must be smaller than +.Va icmplim , +if +.Va icmplim +is not zero. +If set to zero, no jitter will be applied. +Defaults to 16. +.It Va icmplim_output +.Pq Vt boolean +Enable/disable logging of ICMP replies bandwidth limiting. +Defaults to true. +.It Va log_redirect +.Pq Vt boolean +Enable/disable logging of ICMP Redirect packets. +Defaults to false. +.It Va maskfake +.Pq Vt "unsigned integer" +When +.Va maskrepl +is set and this value is non-zero, +it will be used instead of the real address mask when +the system replies to an ICMP Address Mask Request packet. +Defaults to 0. +.It Va maskrepl +.Pq Vt boolean +Enable/disable replies to ICMP Address Mask Request packets. +Defaults to false. +.It Va quotelen +.Pq Vt integer +Number of bytes from original packet to quote in ICMP reply. +This number is internally enforced to be at least 8 bytes (per RFC792) +and at most the maximal space left in the ICMP reply mbuf. +.It Va redirtimeout +.Pq Vt integer +Delay in seconds before expiring route created by ICMP redirect. +.It Va reply_from_interface +.Pq Vt boolean +Use the IP address of the interface the packet came in through for +responses to packets which are not directly addressed to us. +If enabled, this rule is processed before all others. +By default, continue with normal source selection. +Enabling this option is particularly useful on routers because it +makes external traceroutes show the actual path a packet has taken +instead of the possibly different return path. +.It Va reply_src +.Pq Vt str +An interface name used for the ICMP reply source in response to packets +which are not directly addressed to us. +By default continue with normal source selection. +.It Va tstamprepl +.Pq Vt boolean +Enable/disable replies to ICMP Timestamp packets. +Defaults to true. +.El +.Sh ERRORS +A socket operation may fail with one of the following errors returned: +.Bl -tag -width Er +.It Bq Er EISCONN +when trying to establish a connection on a socket which +already has one, or when trying to send a datagram with the destination +address specified and the socket is already connected; +.It Bq Er ENOTCONN +when trying to send a datagram, but +no destination address is specified, and the socket has not been +connected; +.It Bq Er ENOBUFS +when the system runs out of memory for +an internal data structure; +.It Bq Er EADDRNOTAVAIL +when an attempt is made to create a +socket with a network address for which no network interface +exists. +.El +.Sh SEE ALSO +.Xr recv 2 , +.Xr send 2 , +.Xr sysctl 3 , +.Xr inet 4 , +.Xr intro 4 , +.Xr ip 4 , +.Xr pf.conf 5 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +protocol implementation appeared in +.Bx 4.2 . diff --git a/static/freebsd/man4/icmp6.4 b/static/freebsd/man4/icmp6.4 new file mode 100644 index 00000000..8730e3fe --- /dev/null +++ b/static/freebsd/man4/icmp6.4 @@ -0,0 +1,281 @@ +.\" $KAME: icmp6.4,v 1.6 2004/12/27 05:30:56 itojun Exp $ +.\" $OpenBSD: icmp6.4,v 1.19 2004/12/23 20:33:03 jaredy Exp $ +.\" +.\" Copyright (c) 1986, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 November 1, 2018 +.Dt ICMP6 4 +.Os +.Sh NAME +.Nm icmp6 +.Nd Internet Control Message Protocol for IPv6 +.Sh SYNOPSIS +.In sys/socket.h +.In netinet/in.h +.In netinet/icmp6.h +.Ft int +.Fn socket AF_INET6 SOCK_RAW IPPROTO_ICMPV6 +.Sh DESCRIPTION +ICMPv6 is the error and control message protocol used by IPv6 and the +IPv6 protocol family (see +.Xr ip6 4 +and +.Xr inet6 4 ) . +It may be accessed through a +.Dq raw socket +for network monitoring and diagnostic functions. +.Pp +The +.Fa proto +parameter to the +.Xr socket 2 +call to create an ICMPv6 socket may be obtained from +.Xr getprotobyname 3 . +ICMPv6 sockets are connectionless, and are normally used with the +.Xr sendto 2 +and +.Xr recvfrom 2 +calls, though the +.Xr connect 2 +call may also be used to fix the destination for future packets +(in which case +.Xr read 2 +or +.Xr recv 2 +and +.Xr write 2 +or +.Xr send 2 +system calls may be used). +.Pp +Outgoing packets automatically have an IPv6 header prepended to them +(based on the destination address). +Incoming packets on the socket are received with the IPv6 header and any +extension headers removed. +.Ss Types +ICMPv6 messages are classified according to the type and code fields +present in the ICMPv6 header. +The abbreviations for the types and codes may be used in rules in +.Xr pf.conf 5 . +The following types are defined: +.Bl -column x xxxxxxxxxxxx -offset indent +.It Sy Num Ta Sy Abbrev. Ta Sy Description +.It 1 Ta unreach Ta "Destination unreachable" +.It 2 Ta toobig Ta "Packet too big" +.It 3 Ta timex Ta "Time exceeded" +.It 4 Ta paramprob Ta "Invalid IPv6 header" +.It 128 Ta echoreq Ta "Echo service request" +.It 129 Ta echorep Ta "Echo service reply" +.It 130 Ta groupqry Ta "Group membership query" +.It 130 Ta listqry Ta "Multicast listener query" +.It 131 Ta grouprep Ta "Group membership report" +.It 131 Ta listenrep Ta "Multicast listener report" +.It 132 Ta groupterm Ta "Group membership termination" +.It 132 Ta listendone Ta "Multicast listener done" +.It 133 Ta routersol Ta "Router solicitation" +.It 134 Ta routeradv Ta "Router advertisement" +.It 135 Ta neighbrsol Ta "Neighbor solicitation" +.It 136 Ta neighbradv Ta "Neighbor advertisement" +.It 137 Ta redir Ta "Shorter route exists" +.It 138 Ta routrrenum Ta "Route renumbering" +.It 139 Ta fqdnreq Ta "FQDN query" +.It 139 Ta niqry Ta "Node information query" +.It 139 Ta wrureq Ta "Who-are-you request" +.It 140 Ta fqdnrep Ta "FQDN reply" +.It 140 Ta nirep Ta "Node information reply" +.It 140 Ta wrurep Ta "Who-are-you reply" +.It 200 Ta mtraceresp Ta "mtrace response" +.It 201 Ta mtrace Ta "mtrace messages" +.El +.Pp +The following codes are defined: +.Bl -column x xxxxxxxxxxxx xxxxxxxx -offset indent +.It Sy Num Ta Sy Abbrev. Ta Sy Type Ta +.Sy Description +.It 0 Ta noroute-unr Ta unreach Ta "No route to destination" +.It 1 Ta admin-unr Ta unreach Ta "Administratively prohibited" +.It 2 Ta beyond-unr Ta unreach Ta "Beyond scope of source address" +.It 2 Ta notnbr-unr Ta unreach Ta "Not a neighbor (obsolete)" +.It 3 Ta addr-unr Ta unreach Ta "Address unreachable" +.It 4 Ta port-unr Ta unreach Ta "Port unreachable" +.It 0 Ta transit Ta timex Ta "Time exceeded in transit" +.It 1 Ta reassemb Ta timex Ta "Time exceeded in reassembly" +.It 0 Ta badhead Ta paramprob Ta "Erroneous header field" +.It 1 Ta nxthdr Ta paramprob Ta "Unrecognized next header" +.It 2 Ta "" Ta redir Ta "Unrecognized option" +.It 0 Ta redironlink Ta redir Ta "Redirection to on-link node" +.It 1 Ta redirrouter Ta redir Ta "Redirection to better router" +.El +.Ss Headers +All ICMPv6 messages are prefixed with an ICMPv6 header. +This header corresponds to the +.Vt icmp6_hdr +structure and has the following definition: +.Bd -literal -offset indent +struct icmp6_hdr { + uint8_t icmp6_type; /* type field */ + uint8_t icmp6_code; /* code field */ + uint16_t icmp6_cksum; /* checksum field */ + union { + uint32_t icmp6_un_data32[1]; /* type-specific */ + uint16_t icmp6_un_data16[2]; /* type-specific */ + uint8_t icmp6_un_data8[4]; /* type-specific */ + } icmp6_dataun; +} __packed; + +#define icmp6_data32 icmp6_dataun.icmp6_un_data32 +#define icmp6_data16 icmp6_dataun.icmp6_un_data16 +#define icmp6_data8 icmp6_dataun.icmp6_un_data8 +#define icmp6_pptr icmp6_data32[0] /* parameter prob */ +#define icmp6_mtu icmp6_data32[0] /* packet too big */ +#define icmp6_id icmp6_data16[0] /* echo request/reply */ +#define icmp6_seq icmp6_data16[1] /* echo request/reply */ +#define icmp6_maxdelay icmp6_data16[0] /* mcast group membership*/ +.Ed +.Pp +.Va icmp6_type +describes the type of the message. +Suitable values are defined in +.Aq Pa netinet/icmp6.h . +.Va icmp6_code +describes the sub-type of the message and depends on +.Va icmp6_type . +.Va icmp6_cksum +contains the checksum for the message and is filled in by the +kernel on outgoing messages. +The other fields are used for type-specific purposes. +.Ss Filters +Because of the extra functionality of ICMPv6 in comparison to ICMPv4, +a larger number of messages may be potentially received on an ICMPv6 +socket. +Input filters may therefore be used to restrict input to a subset of the +incoming ICMPv6 messages so only interesting messages are returned by the +.Xr recv 2 +family of calls to an application. +.Pp +The +.Vt icmp6_filter +structure may be used to refine the input message set according to the +ICMPv6 type. +By default, all messages types are allowed on newly created raw ICMPv6 +sockets. +The following macros may be used to refine the input set: +.Bl -tag -width Ds +.It Ft void Fn ICMP6_FILTER_SETPASSALL "struct icmp6_filter *filterp" +Allow all incoming messages. +.Va filterp +is modified to allow all message types. +.It Ft void Fn ICMP6_FILTER_SETBLOCKALL "struct icmp6_filter *filterp" +Ignore all incoming messages. +.Va filterp +is modified to ignore all message types. +.It Xo +.Ft void +.Fn ICMP6_FILTER_SETPASS "int type" "struct icmp6_filter *filterp" +.Xc +Allow ICMPv6 messages with the given +.Fa type . +.Va filterp +is modified to allow such messages. +.It Xo +.Ft void +.Fn ICMP6_FILTER_SETBLOCK "int type" "struct icmp6_filter *filterp" +.Xc +Ignore ICMPv6 messages with the given +.Fa type . +.Va filterp +is modified to ignore such messages. +.It Xo +.Ft int +.Fn ICMP6_FILTER_WILLPASS "int type" "const struct icmp6_filter *filterp" +.Xc +Determine if the given filter will allow an ICMPv6 message of the given +type. +.It Xo +.Ft int +.Fn ICMP6_FILTER_WILLBLOCK "int type" "const struct icmp6_filter *filterp" +.Xc +Determine if the given filter will ignore an ICMPv6 message of the given +type. +.El +.Pp +The +.Xr getsockopt 2 +and +.Xr setsockopt 2 +calls may be used to obtain and install the filter on ICMPv6 sockets at +option level +.Dv IPPROTO_ICMPV6 +and name +.Dv ICMP6_FILTER +with a pointer to the +.Vt icmp6_filter +structure as the option value. +.Sh SEE ALSO +.Xr getsockopt 2 , +.Xr recv 2 , +.Xr send 2 , +.Xr setsockopt 2 , +.Xr socket 2 , +.Xr getprotobyname 3 , +.Xr inet6 4 , +.Xr ip6 4 , +.Xr netintro 4 +.Rs +.%A W. Stevens +.%A M. Thomas +.%T Advanced Sockets API for IPv6 +.%N RFC 2292 +.%D February 1998 +.Re +.Rs +.%A A. Conta +.%A S. Deering +.%T "Internet Control Message Protocol (ICMPv6) for the Internet" \ + "Protocol Version 6 (IPv6) Specification" +.%N RFC 2463 +.%D December 1998 +.Re +.Rs +.%A W. Stevens +.%A M. Thomas +.%A E. Nordmark +.%A T. Jinmei +.%T "Advanced Sockets Application Program Interface (API) for IPv6" +.%R RFC 3542 +.%D May 2003 +.Re +.Rs +.%A A. Conta +.%A S. Deering +.%A M. Gupta +.%T "Internet Control Message Protocol (ICMPv6) for the Internet" \ + "Protocol Version 6 (IPv6) Specification" +.%R RFC 4443 +.%D March 2006 +.Re diff --git a/static/freebsd/man4/ida.4 b/static/freebsd/man4/ida.4 new file mode 100644 index 00000000..9c18994d --- /dev/null +++ b/static/freebsd/man4/ida.4 @@ -0,0 +1,79 @@ +.\" Written by Tom Rhodes +.\" This file is public domain +.\" +.Dd February 15, 2017 +.Dt IDA 4 +.Os +.Sh NAME +.Nm ida +.Nd Compaq Intelligent Drive Array Controllers +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device scbus" +.Cd "device ida" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ida_load="YES" +.Ed +.Sh DESCRIPTION +The Compaq Intelligent Drive Array (IDA) technology is used to +distribute data across an array of hard drives. +It unites these hard drives into one or more high-performance logical drives. +The drive array is managed by an array controller. +.Pp +These controllers have the ability to provide fault tolerance for the connected +drives and optionally provide write cache for the logical drives. +It is also possible for an application to access the SCSI bus subsystem +directly by using the pass-through interface. +.Sh HARDWARE +The following controllers are supported by the +.Nm +driver: +.Pp +.Bl -bullet -compact +.It +Compaq SMART Array 221 +.It +Compaq Integrated SMART Array Controller +.It +Compaq SMART Array 4200 +.It +Compaq SMART Array 4250ES +.It +Compaq SMART 3200 Controller +.It +Compaq SMART 3100ES Controller +.It +Compaq SMART-2/DH Controller +.It +Compaq SMART-2/SL Controller +.It +Compaq SMART-2/P Controller +.El +.Sh IMPLEMENTATION NOTES +Extreme caution should be exercised when using the pass-through interface. +It is possible to interfere with normal system I/O and cause hangs if +pass-through is used to an active device. +Pass-through should only be used to a device that is otherwise quiescent. +.Sh SEE ALSO +.Xr cam 4 , +.Xr pass 4 , +.Xr xpt 4 , +.Xr camcontrol 8 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Jonathan Lemon Aq Mt jlemon@FreeBSD.org +and +.An Matthew N. Dodd Aq Mt mdodd@FreeBSD.org . +This manual page was written by +.An Tom Rhodes Aq Mt trhodes@FreeBSD.org . diff --git a/static/freebsd/man4/ietp.4 b/static/freebsd/man4/ietp.4 new file mode 100644 index 00000000..7c6c9eab --- /dev/null +++ b/static/freebsd/man4/ietp.4 @@ -0,0 +1,79 @@ +.\" Copyright (c) 2022 Vladimir Kondratyev +.\" 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 February 27, 2022 +.Dt IETP 4 +.Os +.Sh NAME +.Nm ietp +.Nd Elantech I2C touchpad device driver +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines into +your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ietp" +.Cd "device hidbus" +.Cd "device hid" +.Cd "device iichid" +.Cd "device iicbus" +.Cd "device evdev" + +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ietp_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the Elantech I2C touchpad multi-touch devices +found in many laptops. +.Pp +To get multi-touch device working in +.Xr X 7 Pq Pa ports/x11/xorg-docs , +install +.Pa ports/x11-drivers/xf86-input-libinput . +.Sh FILES +.Nm +creates a pseudo-device file, +.Pa /dev/input/eventX +which presents the multi-touch device as an input event device. +.Sh SEE ALSO +.Xr hid 4 , +.Xr loader.conf 5 , +.Xr xorg.conf 5 Pq Pa ports/x11/xorg , +.Xr libinput 4 Pq Pa ports/x11-drivers/xf86-input-libinput . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org . +.Sh BUGS +.Nm +cannot act like +.Xr sysmouse 4 diff --git a/static/freebsd/man4/if_ipsec.4 b/static/freebsd/man4/if_ipsec.4 new file mode 100644 index 00000000..bd3ef5a2 --- /dev/null +++ b/static/freebsd/man4/if_ipsec.4 @@ -0,0 +1,139 @@ +.\" Copyright (c) 2017 Andrey V. Elsukov +.\" 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 AUTHORS 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 AUTHORS 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 February 6, 2017 +.Dt if_ipsec 4 +.Os +.Sh NAME +.Nm if_ipsec +.Nd IPsec virtual tunneling interface +.Sh SYNOPSIS +The +.Cm if_ipsec +network interface is a part of the +.Fx +IPsec implementation. +To compile it into the kernel, place this line in the kernel +configuration file: +.Bd -ragged -offset indent +.Cd "options IPSEC" +.Ed +.Pp +It can also be loaded as part of the +.Cm ipsec +kernel module if the kernel was compiled with +.Bd -ragged -offset indent +.Cd "options IPSEC_SUPPORT" +.Ed +.Sh DESCRIPTION +The +.Nm +network interface is targeted for creating route-based VPNs. +It can tunnel IPv4 and IPv6 traffic over either IPv4 or IPv6 and secure +it with ESP. +.Pp +.Nm +interfaces are dynamically created and destroyed with the +.Xr ifconfig 8 +.Cm create +and +.Cm destroy +subcommands. +The administrator must configure IPsec +.Cm tunnel +endpoint addresses. +These addresses will be used for the outer IP header of ESP packets. +The administrator can also configure the protocol and addresses for the inner +IP header with +.Xr ifconfig 8 , +and modify the routing table to route the packets through the +.Nm +interface. +.Pp +When the +.Nm +interface is configured, it automatically creates special security policies. +These policies can be used to acquire security associations from the IKE daemon, +which are needed for establishing an IPsec tunnel. +It is also possible to create needed security associations manually with the +.Xr setkey 8 +utility. +.Pp +Each +.Nm +interface has an additional numeric configuration option +.Cm reqid Ar id . +This +.Ar id +is used to distinguish traffic and security policies between several +.Nm +interfaces. +The +.Cm reqid +can be specified on interface creation and changed later. +If not specified, it is automatically assigned. +Note that changing +.Cm reqid +will lead to generation of new security policies, and this +may require creating new security associations. +.Sh EXAMPLES +The example below shows manual configuration of an IPsec tunnel +between two FreeBSD hosts. +Host A has the IP address 192.168.0.3, and host B has the IP address +192.168.0.5. +.Pp +On host A: +.Bd -literal -offset indent +ifconfig ipsec0 create reqid 100 +ifconfig ipsec0 inet tunnel 192.168.0.3 192.168.0.5 +ifconfig ipsec0 inet 172.16.0.3/16 172.16.0.5 +setkey -c +add 192.168.0.3 192.168.0.5 esp 10000 -m tunnel -u 100 -E rijndael-cbc "VerySecureKey!!1"; +add 192.168.0.5 192.168.0.3 esp 10001 -m tunnel -u 100 -E rijndael-cbc "VerySecureKey!!2"; +^D +.Ed +.Pp +On host B: +.Bd -literal -offset indent +ifconfig ipsec0 create reqid 200 +ifconfig ipsec0 inet tunnel 192.168.0.5 192.168.0.3 +ifconfig ipsec0 inet 172.16.0.5/16 172.16.0.3 +setkey -c +add 192.168.0.3 192.168.0.5 esp 10000 -m tunnel -u 200 -E rijndael-cbc "VerySecureKey!!1"; +add 192.168.0.5 192.168.0.3 esp 10001 -m tunnel -u 200 -E rijndael-cbc "VerySecureKey!!2"; +^D +.Ed +.Pp +Note the value 100 on host A and value 200 on host B are used as reqid. +The same value must be used as identifier of the policy entry in the +.Xr setkey 8 +command. +.Sh SEE ALSO +.Xr gif 4 , +.Xr gre 4 , +.Xr ipsec 4 , +.Xr ifconfig 8 , +.Xr setkey 8 +.Sh AUTHORS +.An Andrey V. Elsukov Aq Mt ae@FreeBSD.org diff --git a/static/freebsd/man4/if_ntb.4 b/static/freebsd/man4/if_ntb.4 new file mode 100644 index 00000000..62638d02 --- /dev/null +++ b/static/freebsd/man4/if_ntb.4 @@ -0,0 +1,87 @@ +.\" +.\" Copyright (c) 2016 Alexander Motin +.\" 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 September 2, 2017 +.Dt IF_NTB 4 +.Os +.Sh NAME +.Nm if_ntb +.Nd Virtual Ethernet interface for Non-Transparent Bridges +.Sh SYNOPSIS +To compile this driver into your kernel, +place the following lines in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ntb" +.Cd "device ntb_transport" +.Cd "device if_ntb" +.Ed +.Pp +Or, to load the driver as a module at boot, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_ntb_load="YES" +.Ed +.Pp +The following tunables are settable from the +.Xr loader 8 : +.Bl -ohang +.It Va hw.if_ntb.num_queues +Limits maximal number of queues per interface. +Default is unlimited. +.El +.Sh DESCRIPTION +The +.Nm +driver attaches on top of the +.Xr ntb_transport 4 +driver to utilize one or more of its packet queues to create virtual +Ethernet network interface between the systems. +Typical MTU for the interface is about 64KB to reduce overhead. +Default MAC address for the interface is randomly generated. +.Pp +The +.Nm +driver does not implement any real hardware offload, but since PCIe link is +protected by CRC32, in some situations it may be possible to save some CPU +cycles by enabling fake checksum offload on both link sides via setting +.Cm rxcsum +and +.Cm txcsum +interface options. +.Sh SEE ALSO +.Xr ntb_transport 4 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was developed by Intel and originally written by +.An Carl Delsey Aq Mt carl@FreeBSD.org . +Later improvements were done by +.An Conrad E. Meyer Aq Mt cem@FreeBSD.org +and +.An Alexander Motin Aq Mt mav@FreeBSD.org . +.Sh BUGS +Linux supports only one queue per interface, so manual configuration +may be required for compatibility. diff --git a/static/freebsd/man4/iflib.4 b/static/freebsd/man4/iflib.4 new file mode 100644 index 00000000..349fa402 --- /dev/null +++ b/static/freebsd/man4/iflib.4 @@ -0,0 +1,241 @@ +.Dd January 7, 2026 +.Dt IFLIB 4 +.Os +.Sh NAME +.Nm iflib +.Nd Network Interface Driver Framework +.Sh SYNOPSIS +.Cd "device pci" +.Cd "device iflib" +.Sh DESCRIPTION +.Nm +is a framework for network interface drivers for +.Fx . +It is designed to remove a large amount of the boilerplate that is often +needed for modern network interface devices, allowing driver authors to +focus on the specific code needed for their hardware. +This allows for a shared set of +.Xr sysctl 8 +names, rather than each driver naming them individually. +.Sh SYSCTL VARIABLES +These variables must be set before loading the driver, either via +.Xr loader.conf 5 +or through the use of +.Xr kenv 1 . +They are all prefixed by +.Va dev.X.Y.iflib\&. +where X is the driver name, and Y is the instance number. +.Bl -tag -width indent +.It Va override_nrxds +Override the number of RX descriptors for each queue. +The value is a comma separated list of positive integers. +Some drivers only use a single value, but others may use more. +These numbers must be powers of two, and zero means to use the default. +Individual drivers may have additional restrictions on allowable values. +Defaults to all zeros. +.It Va override_ntxds +Override the number of TX descriptors for each queue. +The value is a comma separated list of positive integers. +Some drivers only use a single value, but others may use more. +These numbers must be powers of two, and zero means to use the default. +Individual drivers may have additional restrictions on allowable values. +Defaults to all zeros. +.It Va override_qs_enable +When set, allows the number of transmit and receive queues to be different. +If not set, the lower of the number of TX or RX queues will be used for both. +.It Va override_nrxqs +Set the number of RX queues. +If zero, the number of RX queues is derived from the number of cores on the +socket connected to the controller. +Defaults to 0. +.It Va override_ntxqs +Set the number of TX queues. +If zero, the number of TX queues is derived from the number of cores on the +socket connected to the controller. +.It Va disable_msix +Disables MSI-X interrupts for the device. +.It Va core_offset +Specifies a starting core offset to assign queues to. +If the value is unspecified or 65535, cores are assigned sequentially across +controllers. +.It Va separate_txrx +Requests that RX and TX queues not be paired on the same core. +If this is zero or not set, an RX and TX queue pair will be assigned to each +core. +When set to a non-zero value, TX queues are assigned to cores following the +last RX queue. +.It Va simple_tx +When set to one, iflib uses a simple transmit routine with no queuing at all. +By default, iflib uses a highly optimized, lockless, transmit queue called +mp_ring. +This performs well when there are more CPU cores than NIC +queues and prevents lock contention for transmit resources. +Unfortunately, mp_ring incurs unneeded overheads on workloads where +resource contention is not a problem (well behaved applications on +systems where there are as many NIC queues as CPU cores). +Note that when this is enabled, the tx_abdicate sysctl is no longer +applicable and is ignored. +Defaults to zero. +.El +.Pp +These +.Xr sysctl 8 +variables can be changed at any time: +.Bl -tag -width indent +.It Va tx_abdicate +Controls how the transmit ring is serviced. +If set to zero, when a frame is submitted to the transmission ring, the same +task that is submitting it will service the ring unless there's already a +task servicing the TX ring. +This ensures that whenever there is a pending transmission, +the transmit ring is being serviced. +This results in higher transmit throughput. +If set to a non-zero value, task returns immediately and the transmit +ring is serviced by a different task. +This returns control to the caller faster and under high receive load, +may result in fewer dropped RX frames. +.It Va tx_defer_mfree +Controls the threshold in packets before iflib will free the memory +(mbufs) for the packets that it has transmitted. +When this is nonzero, mbufs will be freed outside the transmit lock. +Setting this can reduce lock contention and CPU use when using simple_tx. +Note that this applies only when simple_tx is enabled. +.It Va tx_reclaim_thresh +Controls the threshold in packets before iflib will ask the driver +how many transmitted packets can be reclaimed. +Determining how many many packets can be reclaimed can be expensive +on some drivers. +.It Va tx_reclaim_ticks +Controls the time in ticks before iflib will ask the driver +how many transmitted packets can be reclaimed. +Determining how many many packets can be reclaimed can be expensive +on some drivers. +.It Va rx_budget +Sets the maximum number of frames to be received at a time. +Zero (the default) indicates the default (currently 16) should be used. +.El +.Pp +There are also some global sysctls which can change behaviour for all drivers, +and may be changed at any time. +.Bl -tag -width indent +.It Va net.iflib.min_tx_latency +If this is set to a non-zero value, iflib will avoid any attempt to combine +multiple transmits, and notify the hardware as quickly as possible of +new descriptors. +This will lower the maximum throughput, but will also lower transmit latency. +.It Va net.iflib.no_tx_batch +Some NICs allow processing completed transmit descriptors in batches. +Doing so usually increases the transmit throughput by reducing the number of +transmit interrupts. +Setting this to a non-zero value will disable the use of this feature. +.El +.Pp +These +.Xr sysctl 8 +variables are read-only: +.Bl -tag -width indent +.It Va driver_version +A string indicating the internal version of the driver. +.El +.Pp +There are a number of queue state +.Xr sysctl 8 +variables as well: +.Bl -tag -width indent +.It Va txqZ +The following are repeated for each transmit queue, where Z is the transmit +queue instance number: +.Bl -tag -width indent +.It Va r_abdications +Number of consumer abdications in the MP ring for this queue. +An abdication occurs on every ring submission when tx_abdicate is true. +.It Va r_restarts +Number of consumer restarts in the MP ring for this queue. +A restart occurs when an attempt to drain a non-empty ring fails, +and the ring is already in the STALLED state. +.It Va r_stalls +Number of consumer stalls in the MP ring for this queue. +A stall occurs when an attempt to drain a non-empty ring fails. +.It Va r_starts +Number of normal consumer starts in the MP ring for this queue. +A start occurs when the MP ring transitions from IDLE to BUSY. +.It Va r_drops +Number of drops in the MP ring for this queue. +A drop occurs when there is an attempt to add an entry to an MP ring with +no available space. +.It Va r_enqueues +Number of entries which have been enqueued to the MP ring for this queue. +.It Va ring_state +MP (soft) ring state. +This provides a snapshot of the current MP ring state, including the producer +head and tail indexes, the consumer index, and the state. +The state is one of "IDLE", "BUSY", +"STALLED", or "ABDICATED". +.It Va txq_cleaned +The number of transmit descriptors which have been reclaimed. +Total cleaned. +.It Va txq_processed +The number of transmit descriptors which have been processed, but may not yet +have been reclaimed. +.It Va txq_in_use +Descriptors which have been added to the transmit queue, +but have not yet been cleaned. +This value will include both untransmitted descriptors as well as descriptors +which have been processed. +.It Va txq_cidx_processed +The transmit queue consumer index of the next descriptor to process. +.It Va txq_cidx +The transmit queue consumer index of the oldest descriptor to reclaim. +.It Va txq_pidx +The transmit queue producer index where the next descriptor to transmit will +be inserted. +.It Va no_tx_dma_setup +Number of times DMA mapping a transmit mbuf failed for reasons other than +.Er EFBIG . +.It Va txd_encap_efbig +Number of times DMA mapping a transmit mbuf failed due to requiring too many +segments. +.It Va tx_map_failed +Number of times DMA mapping a transmit mbuf failed for any reason +(sum of no_tx_dma_setup and txd_encap_efbig) +.It Va no_desc_avail +Number of times a descriptor couldn't be added to the transmit ring because +the transmit ring was full. +.It Va mbuf_defrag_failed +Number of times both +.Xr m_collapse 9 +and +.Xr m_defrag 9 +failed after an +.Er EFBIG +error +result from DMA mapping a transmit mbuf. +.It Va m_pullups +Number of times +.Xr m_pullup 9 +was called attempting to parse a header. +.It Va mbuf_defrag +Number of times +.Xr m_defrag 9 +was called. +.El +.It Va rxqZ +The following are repeated for each receive queue, where Z is the +receive queue instance number: +.Bl -tag -width indent +.It Va rxq_fl0.credits +Credits currently available in the receive ring. +.It Va rxq_fl0.cidx +Current receive ring consumer index. +.It Va rxq_fl0.pidx +Current receive ring producer index. +.El +.El +.Pp +Additional OIDs useful for driver and iflib development are exposed when the +INVARIANTS and/or WITNESS options are enabled in the kernel. +.Sh SEE ALSO +.Xr iflib 9 +.Sh HISTORY +This framework was introduced in +.Fx 11.0 . diff --git a/static/freebsd/man4/ifmib.4 b/static/freebsd/man4/ifmib.4 new file mode 100644 index 00000000..20b5613b --- /dev/null +++ b/static/freebsd/man4/ifmib.4 @@ -0,0 +1,184 @@ +.\" Copyright 1996 Massachusetts Institute of Technology +.\" +.\" Permission to use, copy, modify, and distribute this software and +.\" its documentation for any purpose and without fee is hereby +.\" granted, provided that both the above copyright notice and this +.\" permission notice appear in all copies, that both the above +.\" copyright notice and this permission notice appear in all +.\" supporting documentation, and that the name of M.I.T. not be used +.\" in advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. M.I.T. makes +.\" no representations about the suitability of this software for any +.\" purpose. It is provided "as is" without express or implied +.\" warranty. +.\" +.\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS +.\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE, +.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT +.\" SHALL M.I.T. 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 26, 2020 +.Dt IFMIB 4 +.Os +.Sh NAME +.Nm ifmib +.Nd Management Information Base for network interfaces +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In sys/sysctl.h +.In sys/time.h +.In net/if.h +.In net/if_mib.h +.Sh DESCRIPTION +The +.Nm +facility is an application of the +.Xr sysctl 3 +interface to provide management information about network interfaces +to client applications such as +.Xr netstat 1 , +.Xr slstat 8 , +and +.Tn SNMP +management agents. +This information is structured as a table, where +each row in the table represents a logical network interface (either a +hardware device or a software pseudo-device like +.Xr lo 4 ) . +There are two columns in the table, each containing a single +structure: one column contains generic information relevant to all +interfaces, and the other contains information specific to the +particular class of interface. +(Generally the latter will implement +the +.Tn SNMP +.Tn MIB +defined for that particular interface class, if one exists and can be +implemented in the kernel.) +.Pp +The +.Nm +facility is accessed via the +.Dq Li net.link.generic +branch of the +.Xr sysctl 3 +MIB. +The manifest constants for each level in the +.Xr sysctl 3 +.Ar name +are defined in +.In net/if_mib.h . +The index of the last row in the table is given by +.Dq Li net.link.generic.system.ifcount +(or, using the manifest constants, +.Dv CTL_NET , +.Dv PF_LINK , +.Dv NETLINK_GENERIC , +.Dv IFMIB_SYSTEM , +.Dv IFMIB_IFCOUNT ) . +A management application searching for a particular interface should +start with row 1 and continue through the table row-by-row until the +desired interface is found, or the interface count is reached. +Note that the table may be sparse, i.e., a given row may not exist, +indicated by an +.Va errno +of +.Er ENOENT . +Such an error should be ignored, and the next row should be checked. +.Pp +The generic interface information, common to all interfaces, +can be accessed via the following procedure: +.Bd -literal -offset indent +int +get_ifmib_general(int row, struct ifmibdata *ifmd) +{ + int name[6]; + size_t len; + + name[0] = CTL_NET; + name[1] = PF_LINK; + name[2] = NETLINK_GENERIC; + name[3] = IFMIB_IFDATA; + name[4] = row; + name[5] = IFDATA_GENERAL; + + len = sizeof(*ifmd); + + return sysctl(name, 6, ifmd, &len, (void *)0, 0); +} +.Ed +.Pp +The fields in +.Li struct ifmibdata +are as follows: +.Bl -tag -width "ifmd_snd_drops" +.It Li ifmd_name +.Pq Li "char []" +the name of the interface, including the unit number +.It Li ifmd_pcount +.Pq Li int +the number of promiscuous listeners +.It Li ifmd_flags +.Pq Li int +the interface's flags (defined in +.In net/if.h ) +.It Li ifmd_snd_len +.Pq Li int +the current instantaneous length of the send queue +.It Li ifmd_snd_drops +.Pq Li int +the number of packets dropped at this interface because the send queue +was full +.It Li ifmd_data +.Pq Li struct if_data +more information from a structure defined in +.In net/if.h +(see +.Xr if_data 9 ) +.El +.Pp +Class-specific information can be retrieved by examining the +.Dv IFDATA_LINKSPECIFIC +column instead. +Note that the form and length of the structure will +depend on the class of interface. +For +.Dv IFT_ETHER , +.Dv IFT_ISO88023 , +and +.Dv IFT_STARLAN +interfaces, the structure is called +.Dq Li struct ifmib_iso_8802_3 +(defined in +.In net/if_mib.h ) , +and implements a superset of the +.Tn "RFC 1650" +MIB for Ethernet-like networks. +.Sh SEE ALSO +.Xr sysctl 3 , +.Xr intro 4 , +.Xr ifnet 9 +.\" .Xr ethermib 4 , +.Rs +.%T "Definitions of Managed Objects for the Ethernet-like Interface Types Using SMIv2" +.%A F. Kastenholz +.%D August 1994 +.%O RFC 1650 +.Re +.Sh HISTORY +The +.Nm +interface first appeared in +.Fx 2.2 . +.Sh BUGS +Many Ethernet-like interfaces do not yet support the Ethernet MIB. +Regardless, all interfaces automatically support the generic MIB. diff --git a/static/freebsd/man4/ig4.4 b/static/freebsd/man4/ig4.4 new file mode 100644 index 00000000..67bad68d --- /dev/null +++ b/static/freebsd/man4/ig4.4 @@ -0,0 +1,82 @@ +.\" Copyright (c) 2015 Michael Gmelin +.\" 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 September 13, 2018 +.Dt IG4 4 +.Os +.Sh NAME +.Nm ig4 +.Nd Synopsys DesignWare I2C Controller +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines into +the kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ig4" +.Cd "device iicbus" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ig4_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides access to peripherals attached to an I2C controller. +.Sh HARDWARE +.Nm +supports the I2C controllers based on Synopsys DesignWare IP that can be found +in Intel(R) Core(TM) processors starting from the fourth generation, Intel(R) +Bay Trail, Apollo Lake SoC families, and some AMD systems. +.Sh SYSCTL VARIABLES +These +.Xr sysctl 8 +variables are available: +.Bl -tag -width "debug.ig4_dump" +.It Va debug.ig4_dump +This sysctl is a zero-based bit mask. +When any of the bits are set, a register dump is printed for +every I2C transfer on an +.Nm +device with the same unit number. +.El +.Sh SEE ALSO +.Xr iic 4 , +.Xr iicbus 4 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written for +.Dx +by +.An Matthew Dillon +and subsequently ported to +.Fx +by +.An Michael Gmelin Aq Mt freebsd@grem.de . +.Pp +This manual page was written by +.An Michael Gmelin Aq Mt freebsd@grem.de . diff --git a/static/freebsd/man4/igc.4 b/static/freebsd/man4/igc.4 new file mode 100644 index 00000000..757c7dd4 --- /dev/null +++ b/static/freebsd/man4/igc.4 @@ -0,0 +1,161 @@ +.\" +.\" Copyright 2021 Intel Corp +.\" Copyright 2021 Rubicon Communications, LLC (Netgate) +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.Dd March 9, 2026 +.Dt IGC 4 +.Os +.Sh NAME +.Nm igc +.Nd Intel Ethernet Controller I225 2.5GbE driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device iflib" +.Cd "device igc" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_igc_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for any PCI Express adapter or LOM (LAN +On Motherboard) based on the Intel I225 Multi Gigabit Controller. +The driver supports Transmit/Receive checksum offload, Jumbo Frames, +MSI/MSI-X, TSO, and RSS. +.Pp +Support for Jumbo Frames is provided via the interface MTU setting. +Selecting an MTU larger than 1500 bytes with the +.Xr ifconfig 8 +utility +configures the adapter to receive and transmit Jumbo Frames. +The maximum MTU size for Jumbo Frames is 9216 bytes. +.Pp +This driver version supports VLAN hardware insertion / extraction, and +VLAN checksum offload. +For information on enabling VLANs, see +.Xr ifconfig 8 . +The +.Nm +driver supports the following media types: +.Bl -tag -width ".Cm 10baseT/UTP" +.It Cm autoselect +Enables auto-negotiation for speed and duplex. +.It Cm 10baseT/UTP +Sets 10Mbps operation. +Use the +.Cm mediaopt +option to select +.Cm half-duplex +mode. +.It Cm 100baseTX +Sets 100Mbps operation. +Use the +.Cm mediaopt +option to select +.Cm half-duplex +mode. +.It Cm 1000baseT +Sets 1000Mbps operation. +Only +.Cm full-duplex +mode is supported at this speed. +.It Cm 2500baseT +Sets 2500Mbps operation. +Only +.Cm full-duplex +mode is supported at this speed. +.El +.Sh HARDWARE +The +.Nm +driver supports the following 2.5Gb Ethernet controllers: +.Pp +.Bl -bullet -compact +.It +I220-V +.It +I221-V +.It +I225-LM +.It +I225-LMvP(2) +.It +I225-V +.It +I225-IT, I225-IT(2) +.It +I225-K, I225-K(2) +.It +I226-LM +.It +I226-LMvP +.It +I226-V +.It +I226-IT +.It +I226-K +.El +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width indent +.It Va hw.igc.igc_disable_crc_stripping +Disable or enable hardware stripping of CRC field. +This is mostly useful on BMC/IPMI shared interfaces where stripping the +CRC causes remote access over IPMI to fail. +Default 0 (enabled). +.It Va hw.igc.sbp +Show bad packets when in promiscuous mode. +Default is false. +.It Va hw.igc.eee_setting +Disable or enable Energy Efficient Ethernet. +Default 1 (disabled). +.It Va hw.igc.max_interrupt_rate +Maximum device interrupts per second. +The default is 8000. +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "igc%d: Hardware Initialization Failed" +A fatal initialization error has occurred. +.It "igc%d: Unable to allocate bus resource: memory" +A fatal initialization error has occurred. +.It "igc%d: Invalid MAC address" +The MAC address programmed into the EEPROM is either empty or a multicast/broadcast +address. +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr iflib 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 13.1 . +.Sh AUTHORS +.An -nosplit +The +.Nm +was originally written by +.An Intel Corporation +and converted to the +.Xr iflib 4 +framework by +.An Netgate . diff --git a/static/freebsd/man4/igmp.4 b/static/freebsd/man4/igmp.4 new file mode 100644 index 00000000..c395be0f --- /dev/null +++ b/static/freebsd/man4/igmp.4 @@ -0,0 +1,136 @@ +.\" +.\" Copyright (c) 2009 Bruce Simpson. +.\" +.\" 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. Neither the name of the project nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT 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 PROJECT 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 March 9, 2009 +.Dt IGMP 4 +.Os +.Sh NAME +.Nm igmp +.Nd Internet Group Management Protocol +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netinet/in.h +.In netinet/in_systm.h +.In netinet/ip.h +.In netinet/igmp.h +.Ft int +.Fn socket AF_INET SOCK_RAW IPPROTO_IGMP +.Sh DESCRIPTION +.Tn IGMP +is a control plane protocol used by IPv4 hosts and routers to +propagate multicast group membership information. +Normally this protocol is not used directly, except by the kernel +itself, in response to multicast membership requests by user +applications. +Routing protocols may open a raw socket to directly interact with +.Nm . +.Pp +As of +.Fx 8.0 , +IGMP version 3 is implemented. +This adds support for Source-Specific Multicast (SSM), whereby +applications may communicate to upstream multicast routers that +they are only interested in receiving multicast streams from +particular sources. +.\" +.Sh SYSCTL VARIABLES +.Bl -tag -width indent +.\" +.It net.inet.igmp.stats +This opaque read-only variable exposes the stack-wide IGMPv3 +protocol statistics to +.Xr netstat 1 . +.\" +.It net.inet.igmp.ifinfo +This opaque read-only variable exposes the per-link IGMPv3 status to +.Xr ifmcstat 8 . +.\" +.It net.inet.igmp.gsrdelay +This variable specifies the time threshold, in seconds, for processing +Group-and-Source Specific Queries (GSR). +As GSR query processing requires maintaining state on the host, +it may cause memory to be allocated, and is therefore a potential +attack point for Denial-of-Service (DoS). +If more than one GSR query is received within this threshold, +it will be dropped, to mitigate the potential for DoS. +.\" +.It net.inet.igmp.default_version +This variable controls the default version of IGMP to be used on all links. +This sysctl is normally set to 3 by default. +.\" +.It net.inet.igmp.legacysupp +If this variable is non-zero, then IGMP v1 and v2 membership reports +received on a link will be allowed to suppress the IGMP v3 state-change +reports which would otherwise be issued by this host. +This sysctl is normally enabled by default. +.\" +.It net.inet.igmp.v2enable +If this variable is non-zero, then IGMP v2 membership queries will be +processed by this host, and backwards compatibility will be enabled +until the v2 'Old Querier Present' timer expires. +This sysctl is normally enabled by default. +.\" +.It net.inet.igmp.v1enable +If this variable is non-zero, then IGMP v1 membership queries will be +processed by this host, and backwards compatibility will be enabled +until the v1 'Old Querier Present' timer expires. +This sysctl is normally enabled by default. +.\" +.It net.inet.igmp.sendlocal +If this variable is non-zero, then IGMP state-changes for groups in +the 224.0.0.0/24 link-scope prefix will be issued. +This behaviour is recommended if deploying +.Fx +in a network environment with layer 2 devices which snoop IGMP traffic +to mitigate multicast propagation throughout the network. +This sysctl is normally enabled by default. +.\" +.It net.inet.igmp.sendra +If this variable is non-zero, then IGMP v2 and v3 reports will contain +the IP Router Alert option. +This sysctl is normally enabled by default. +.\" +.It net.inet.igmp.recvifkludge +If this variable is non-zero, then received IGMP reports which contain +0.0.0.0 as their source will be rewritten to contain the subnet address. +This is useful when there are hosts on-link which have not yet been +configured with a primary IPv4 address. +This sysctl is normally enabled by default. +.\" +.El +.Sh SEE ALSO +.Xr netstat 1 , +.Xr sourcefilter 3 , +.Xr inet 4 , +.Xr multicast 4 , +.Xr ifmcstat 8 +.Sh HISTORY +The +.Nm +manual page re-appeared in +.Fx 8.0 . diff --git a/static/freebsd/man4/iic.4 b/static/freebsd/man4/iic.4 new file mode 100644 index 00000000..ddabb073 --- /dev/null +++ b/static/freebsd/man4/iic.4 @@ -0,0 +1,257 @@ +.\" Copyright (c) 1998, Nicolas Souchu All rights reserved. +.\" Copyright (c) 2006 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 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 May 15, 2015 +.Dt IIC 4 +.Os +.Sh NAME +.Nm iic +.Nd I2C generic I/O device driver +.Sh SYNOPSIS +.Cd "device iic" +.Pp +.In dev/iicbus/iic.h +.Sh DESCRIPTION +The +.Nm +device driver provides generic I/O to any +.Xr iicbus 4 +instance. +In order to control I2C devices, use +.Pa /dev/iic? +with the +following ioctls: +.Bl -tag -width ".Dv I2CRPTSTART" +.It Dv I2CSTART +.Pq Vt "struct iiccmd" +Sends the start condition to the slave specified by the +.Va slave +element to the bus. +The +.Va slave +element consists of a 7-bit address and a read/write bit +(that is, a 7-bit address << 1 | r/w). +A read operation is initiated when the read/write bit is set, or a write +operation when it is cleared. +All other elements are ignored. +If successful, the file descriptor receives exclusive +ownership of the underlying iicbus instance. +.It Dv I2CRPTSTART +.Pq Vt "struct iiccmd" +Sends the repeated start condition to the slave specified by the +.Va slave +element to the bus. +The slave address should be specified as in +.Dv I2CSTART . +All other elements are ignored. +.Dv I2CSTART +must have previously been issued on the same file descriptor. +.It Dv I2CSTOP +No argument is passed. +Sends the stop condition to the bus. +If +.Dv I2CSTART +was previously issued on the file descriptor, the current transaction is +terminated and exclusive ownership of the underlying iicbus instance is +released. +Otherwise, no action is performed. +.It Dv I2CRSTCARD +.Pq Vt "struct iiccmd" +Resets the bus. +The argument is completely ignored. +This command does not require +.Dv I2CSTART +to have been previously issued on the file descriptor. +If it was previously issued, exclusive ownership of the underlying iicbus +instance is released. +.It Dv I2CWRITE +.Pq Vt "struct iiccmd" +Writes data to the +.Xr iicbus 4 . +The bus must already be started by a previous +.Dv I2CSTART +on the file descriptor. +The +.Va slave +element is ignored. +The +.Va count +element is the number of bytes to write. +The +.Va last +element is a boolean flag. +It must be zero when additional read commands will follow, or non-zero if this +is the last command. +The +.Va buf +element is a pointer to the data to write to the bus. +.It Dv I2CREAD +.Pq Vt "struct iiccmd" +Reads data from the +.Xr iicbus 4 . +The bus must already be started by a previous +.Dv I2CSTART +on the file descriptor. +The +.Va slave +element is ignored. +The +.Va count +element is the number of bytes to read. +The +.Va last +element is a boolean flag. +It must be zero when additional read commands will follow, or non-zero if this +is the last command. +The +.Va buf +element is a pointer to where to store the data read from the bus. +Short reads on the bus produce undefined results. +.It Dv I2CRDWR +.Pq Vt "struct iic_rdwr_data" +Generic read/write interface. +Allows for an arbitrary number of commands to be sent to +an arbitrary number of devices on the bus. +Any previous transaction started by +.Dv I2CSTART +must be terminated by +.Dv I2CSTOP +or +.Dv I2CRSTCARD +before +.Dv I2CRDWR +can be issued on the same file descriptor. +A read transfer is specified if +.Dv IIC_M_RD +is set in +.Va flags . +Otherwise the transfer is a write transfer. +The +.Va slave +element specifies the 7-bit address with the read/write bit for the transfer. +The read/write bit will be handled by the iicbus stack based on the specified +transfer operation. +The +.Va len +element is the number of +.Pq Vt "struct iic_msg" +messages encoded on +.Pq Vt "struct iic_rdwr_data" . +The +.Va buf +element is a buffer for that data. +This ioctl is intended to be +.Tn Linux +compatible. +.It Dv I2CSADDR +.Pq Vt "uint8_t" +Associate the specified address with the file descriptor for use by +subsequent +.Xr read 2 +or +.Xr write 2 +calls. +The argument is an 8-bit address (that is, a 7-bit address << 1). +The read/write bit in the least-significant position is ignored. +Any subsequent read or write operation will set or clear that bit as needed. +.El +.Pp +The following data structures are defined in +.In dev/iicbus/iic.h +and referenced above: +.Bd -literal -offset indent +struct iiccmd { + u_char slave; + int count; + int last; + char *buf; +}; + +/* Designed to be compatible with linux's struct i2c_msg */ +struct iic_msg +{ + uint16_t slave; + uint16_t flags; +#define IIC_M_WR 0 /* Fake flag for write */ +#define IIC_M_RD 0x0001 /* read vs write */ +#define IIC_M_NOSTOP 0x0002 /* do not send a I2C stop after message */ +#define IIC_M_NOSTART 0x0004 /* do not send a I2C start before message */ + uint16_t len; /* msg length */ + uint8_t * buf; +}; + +struct iic_rdwr_data { + struct iic_msg *msgs; + uint32_t nmsgs; +}; +.Ed +.Pp +It is also possible to use +.Xr read 2 +or +.Xr write 2 , +in which case the I2C start/stop handshake is managed by +.Xr iicbus 4 . +The address used for the read/write operation is the one passed to the most +recent +.Dv I2CSTART +.Xr ioctl 2 +or +.Dv I2CSADDR +.Xr ioctl 2 +on the open +.Pa /dev/iic? +file descriptor. +Closing the file descriptor clears any addressing state established by a +previous +.Dv I2CSTART +or +.Dv I2CSADDR , +stops any transaction established by a not-yet-terminated +.Dv I2CSTART , +and releases iicbus ownership. +Because addressing state is stored on a per-file-descriptor basis, it is +permissible for multiple file descriptors to be simultaneously open on the +same +.Pa /dev/iic? +device. +Concurrent transactions on those descriptors are synchronized by the +exclusive-ownership requests issued to the underlying iicbus instance. +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr read 2 , +.Xr write 2 , +.Xr iicbus 4 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 3.0 . +.Sh AUTHORS +.An -nosplit +This +manual page was written by +.An Nicolas Souchu +and +.An M. Warner Losh . diff --git a/static/freebsd/man4/iic_gpiomux.4 b/static/freebsd/man4/iic_gpiomux.4 new file mode 100644 index 00000000..d6ebb35b --- /dev/null +++ b/static/freebsd/man4/iic_gpiomux.4 @@ -0,0 +1,85 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2019 Ian Lepore +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 1, 2020 +.Dt IIC_GPIOMUX 4 +.Os +.Sh NAME +.Nm iic_gpiomux +.Nd driver for I2C mux hardware controlled via GPIO +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device iic_gpiomux" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +iic_gpiomux_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports any type of I2C bus multiplexer (mux) hardware that +is controlled by manipulating the state of one or more GPIO pins. +It automatically connects an upstream I2C bus to one of the downstream +buses as needed when slave devices on the downstream buses initiate I/O. +More information on the automatic switching behavior is available in +.Xr iicmux 4 . +.Sh FDT CONFIGURATION +On an +.Xr fdt 4 +based system, an +.Nm +device node may be defined as a child node of any arbitrary bus +in the FDT data. +The +.Va i2c-parent +property indicates the connection to the upstream I2C bus. +The children of the +.Nm +node are additional i2c buses, which will have their own i2c slave +devices described in their child nodes. +.Pp +The +.Nm +driver conforms to the standard +.Bk -words +.Li i2c/i2c-mux-gpio.txt +.Ek +bindings document. +.Sh SEE ALSO +.Xr iicbus 4 , +.Xr iicmux 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 13.0 . diff --git a/static/freebsd/man4/iicbb.4 b/static/freebsd/man4/iicbb.4 new file mode 100644 index 00000000..d446b4d5 --- /dev/null +++ b/static/freebsd/man4/iicbb.4 @@ -0,0 +1,56 @@ +.\" Copyright (c) 1998, Nicolas Souchu +.\" 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 October 25, 1998 +.Dt IICBB 4 +.Os +.Sh NAME +.Nm iicbb +.Nd I2C generic bit-banging driver +.Sh SYNOPSIS +.Cd "device iicbb" +.Pp +.Cd "device lpbb" +.Pp +For one or more iicbus busses: +.Cd "device iicbus" +.Sh DESCRIPTION +The +.Em iicbb +driver provides support to any bit-banging interface for the +.Xr iicbus 4 +system. +.Sh SEE ALSO +.Xr iicbus 4 , +.Xr lpbb 4 , +.Xr ppbus 4 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 3.0 . +.Sh AUTHORS +This +manual page was written by +.An Nicolas Souchu . diff --git a/static/freebsd/man4/iicbus.4 b/static/freebsd/man4/iicbus.4 new file mode 100644 index 00000000..8f0af248 --- /dev/null +++ b/static/freebsd/man4/iicbus.4 @@ -0,0 +1,163 @@ +.\" Copyright (c) 1998, Nicolas Souchu +.\" 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 March 7, 2021 +.Dt IICBUS 4 +.Os +.Sh NAME +.Nm iicbus +.Nd I2C bus system +.Sh SYNOPSIS +.Cd "device iicbus" +.Cd "device iicbb" +.Pp +.Cd "device iic" +.Cd "device ic" +.Cd "device iicsmb" +.Sh DESCRIPTION +The +.Em iicbus +system provides a uniform, modular and architecture-independent +system for the implementation of drivers to control various I2C devices +and to utilize different I2C controllers. +.Sh I2C +I2C is an acronym for Inter Integrated Circuit bus. +The I2C bus was developed +in the early 1980's by Philips semiconductors. +Its purpose was to provide an +easy way to connect a CPU to peripheral chips in a TV-set. +.Pp +The BUS physically consists of 2 active wires and a ground connection. +The active wires, SDA and SCL, are both bidirectional. +Where SDA is the +Serial DAta line and SCL is the Serial CLock line. +.Pp +Every component hooked up to the bus has its own unique address whether it +is a CPU, LCD driver, memory, or complex function chip. +Each of these chips +can act as a receiver and/or transmitter depending on its functionality. +Obviously an LCD driver is only a receiver, while a memory or I/O chip can +both be transmitter and receiver. +Furthermore there may be one or +more BUS MASTERs. +.Pp +The BUS MASTER is the chip issuing the commands on the BUS. +In the I2C protocol +specification it is stated that the IC that initiates a data transfer on the +bus is considered the BUS MASTER. +At that time all the others are regarded to +as the BUS SLAVEs. +As mentioned before, the IC bus is a Multi-MASTER BUS. +This means that more than one IC capable of initiating data transfer can be +connected to it. +.Sh DEVICES +Some I2C device drivers are available: +.Pp +.Bl -column "Device drivers" -compact +.It Em Devices Ta Em Description +.It Sy iic Ta "general i/o operation" +.It Sy ic Ta "network IP interface" +.It Sy iicsmb Ta "I2C to SMB software bridge" +.El +.Sh INTERFACES +The I2C protocol may be implemented by hardware or software. +Software +interfaces rely on very simple hardware, usually two lines +twiddled by 2 registers. +Hardware interfaces are more intelligent and receive +8-bit characters they write to the bus according to the I2C protocol. +.Pp +I2C interfaces may act on the bus as slave devices, allowing spontaneous +bidirectional communications, thanks to the multi-master capabilities of the +I2C protocol. +.Pp +Some I2C interfaces are available: +.Pp +.Bl -column "Interface drivers" -compact +.It Em Interface Ta Em Description +.It Sy pcf Ta "Philips PCF8584 master/slave interface" +.It Sy iicbb Ta "generic bit-banging master-only driver" +.It Sy lpbb Ta "parallel port specific bit-banging interface" +.El +.Sh BUS FREQUENCY CONFIGURATION +The operating frequency of an I2C bus may be fixed or configurable. +The bus may be used as part of some larger standard interface, and that +interface specification may require a fixed frequency. +The driver for that hardware would not honor an attempt to configure a +different speed. +A general purpose I2C bus, such as those found in many embedded systems, +will often support multiple bus frequencies. +.Pp +When a system supports multiple I2C buses, a different frequency can +be configured for each bus by number, represented by the +.Va %d +in the variable names below. +Buses can be configured using any combination of device hints, +Flattened Device Tree (FDT) data, tunables set via +.Xr loader 8 , +or at runtime using +.Xr sysctl 8 . +When configuration is supplied using more than one method, FDT and +hint data will be overridden by a tunable, which can be overridden by +.Xr sysctl 8 . +.Ss Device Hints +Set +.Va hint.iicbus.%d.frequency +to the frequency in Hz, on systems that use device hints to configure +I2C devices. +The hint is also honored by systems that use FDT data if +no frequency is configured using FDT. +.Ss Flattened Device Tree Data +Configure the I2C bus speed using the FDT standard +.Va clock-frequency +property of the node describing the I2C controller hardware. +.Ss Sysctl and Tunable +Set +.Va dev.iicbus.%d.frequency +in +.Xr loader.conf 5 . +The same variable can be changed at any time with +.Xr sysctl 8 . +Reset the bus using +.Xr i2c 8 +or the +.Xr iic 4 +.Va I2CRSTCARD +ioctl to make the change take effect. +.Sh SEE ALSO +.Xr fdt 4 , +.Xr iic 4 , +.Xr iicbb 4 , +.Xr lpbb 4 , +.Xr pcf 4 , +.Xr i2c 8 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 3.0 . +.Sh AUTHORS +This +manual page was written by +.An Nicolas Souchu . diff --git a/static/freebsd/man4/iichid.4 b/static/freebsd/man4/iichid.4 new file mode 100644 index 00000000..02a91d78 --- /dev/null +++ b/static/freebsd/man4/iichid.4 @@ -0,0 +1,94 @@ +.\" Copyright (c) 2020 Vladimir Kondratyev +.\" +.\" 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 September 21, 2020 +.Dt IICHID 4 +.Os +.Sh NAME +.Nm iichid +.Nd I2C HID transport driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device iichid" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +iichid_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides a interface to I2C Human Interface Devices (HIDs). +.Sh SYSCTL VARIABLES +Next parameters are available as +.Xr sysctl 8 +variables. +Debug parameter is available as +.Xr loader 8 +tunable as well. +.Bl -tag -width indent +.It Va dev.iichid.*.sampling_rate_fast +Active sampling rate in num/second (for sampling mode). +.It Va dev.iichid.*.sampling_rate_slow +Idle sampling rate in num/second (for sampling mode). +.It Va dev.iichid.*.sampling_hysteresis +Number of missing samples before enabling of slow mode (for sampling mode). +.It Va hw.iichid.debug +Debug output level, where 0 is debugging disabled and larger values increase +debug message verbosity. +Default is 0. +.El +.Sh SEE ALSO +.Xr ig4 4 +.Sh BUGS +The +.Nm +does not support GPIO interrupts yet. +In that case +.Nm +enables sampling mode with periodic polling of hardware by driver means. +See dev.iichid.*.sampling_* +.Xr sysctl 8 +variables for tuning of sampling parameters. +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Marc Priggemeyer Aq Mt marc.priggemeyer@gmail.com +and +.An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org . +.Pp +This manual page was written by +.An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org . diff --git a/static/freebsd/man4/iicmux.4 b/static/freebsd/man4/iicmux.4 new file mode 100644 index 00000000..878d9d64 --- /dev/null +++ b/static/freebsd/man4/iicmux.4 @@ -0,0 +1,146 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2019 Ian Lepore +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 1, 2020 +.Dt IICMUX 4 +.Os +.Sh NAME +.Nm iicmux +.Nd I2C bus mulitiplexer framework +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device iicmux" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +iicmux_load="YES" +.Ed +.Pp +Note that it is usually not necessary to explicitly load the +driver module, as it will be loaded automatically along with +the driver for the specific mux hardware in use. +.Sh DESCRIPTION +The +.Nm +framework provides support code to help implement drivers for various +I2C bus multiplexer (mux) hardware. +.Nm +is not a standalone driver, +it is a collection of support functions and driver methods which are +used by individual mux hardware drivers. +It will be loaded automatically when needed by a mux hardware driver. +This manual page provides an overview of the I2C mux framework and its +behavior. +.Pp +Generally speaking, an I2C mux is connected to an upstream I2C bus, and to +one or more downstream I2C buses, and it can be commanded to connect +any one of the downstream buses to the upstream bus. +Some hardware may be able to connect multiple downstream buses at the +same time, but that concept is not supported by +.Nm . +.Pp +The +.Nm +framework operates automatically when I2C slave devices initiate I/O. +It does not require (or even allow for) any external control to select +the active downstream bus. +.Pp +When there is no I/O in progress, the mux is said to be in the +.Dq idle +state. +Some mux hardware has the ability to disconnect all downstream buses +when in an idle state. +Other hardware must always have one of the downstream buses connected. +Individual mux hardware drivers typically provide a way to select which +downstream bus (if any) should be connected while in the idle state. +In the absence of such configuration, whichever downstream bus was +last used remains connected to the upstream bus. +.Pp +When an I2C slave device on a bus downstream of a mux initiates I/O, +it first requests exclusive use of the bus by calling +.Fn iicbus_request_bus . +This request is communicated to the bus's parent, which is the +.Nm +framework +mux driver. +Once exclusive bus ownership is obtained, the mux driver +connects the upstream I2C bus to the downstream bus which hosts the +slave device that requested bus ownership. +The mux hardware maintains that upstream-to-downstream connection until +the slave device calls +.Fn iicbus_release_bus . +Before releasing ownership, the mux driver returns the mux hardware to +the idle state. +.Sh FDT CONFIGURATION +On an +.Xr fdt 4 +based system, an I2C mux device node is defined as a child node of its +upstream I2C bus when the mux device is an I2C slave itself. +It may be defined as a child node of any other bus or device in the +system when it is not an I2C slave, in which case the +.Va i2c-parent +property indicates which upstream bus the mux is attached to. +In either case, the children of the mux node are additional I2C buses, which +will have one or more I2C slave devices described in their child nodes. +.Pp +Drivers using the +.Nm +framework conform to the standard +.Bk -words +.Li i2c/i2c-mux.txt +.Ek +bindings document. +.Sh HINTS CONFIGURATION +On a +.Xr device.hints 5 +based system, these values are configurable for +.Nm +framework drivers : +.Bl -tag -width indent +.It Va hint...at +The upstream +.Xr iicbus 4 +the +.Nm +instance is attached to. +.El +.Pp +When configured via hints, the driver automatically adds an iicbus +instance for every downstream bus supported by the chip. +There is currently no way to indicate used versus unused downstream buses. +.Sh SEE ALSO +.Xr iicbus 4 +.Sh HISTORY +The +.Nm +framework first appeared in +.Fx 13.0 . diff --git a/static/freebsd/man4/iicsmb.4 b/static/freebsd/man4/iicsmb.4 new file mode 100644 index 00000000..ffa38000 --- /dev/null +++ b/static/freebsd/man4/iicsmb.4 @@ -0,0 +1,56 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 1998, Nicolas Souchu. 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 August 10, 1998 +.Dt IICSMB 4 +.Os +.Sh NAME +.Nm iicsmb +.Nd I2C to SMBus bridge +.Sh SYNOPSIS +.Cd "device iicsmb" +.Pp +For one or more smbus busses: +.Cd "device smbus" +.Sh DESCRIPTION +The +.Em iicsmb +driver supports SMB commands over +.Xr iicbus 4 +for the +.Xr smbus 4 +system. +.Sh SEE ALSO +.Xr smbus 4 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 3.0 . +.Sh AUTHORS +This +manual page was written by +.An Nicolas Souchu . diff --git a/static/freebsd/man4/imcsmb.4 b/static/freebsd/man4/imcsmb.4 new file mode 100644 index 00000000..4a8f9e50 --- /dev/null +++ b/static/freebsd/man4/imcsmb.4 @@ -0,0 +1,130 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2018 Panasas +.\" +.\" 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 ``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 March 2, 2018 +.Dt IMCSMB 4 +.Os +.Sh NAME +.Nm imcsmb +.Nd Intel integrated Memory Controller (iMC) SMBus controller driver +.Sh SYNOPSIS +.Cd device pci +.Cd device smbus +.Cd device imcsmb +.Pp +Alternatively, to load the driver as a module at boot time, place the following +line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +imcsmb_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides +.Xr smbus 4 +support for the SMBus controller functionality in the integrated Memory +Controllers (iMCs) embedded in Intel Sandybridge-Xeon, Ivybridge-Xeon, +Haswell-Xeon, and Broadwell-Xeon CPUs. +Each CPU implements one or more iMCs, depending on the number of cores; +each iMC implements two SMBus controllers (iMC-SMBs). +The iMC-SMBs are used by the iMCs to read configuration information from the +DIMMs during POST. +They may also be used, by motherboard firmware or a BMC, to monitor the +temperature of the DIMMs. +.Pp +The iMC-SMBs are +.Sy not +general-purpose SMBus controllers. +By their nature, they are only ever attached to DIMMs, so they implement only +the SMBus operations need for communicating with DIMMs. +Specifically: +.Pp +.Bl -dash -offset indent -compact +.It +READB +.It +READW +.It +WRITEB +.It +WRITEW +.El +.Pp +A more detailed discussion of the hardware and driver architecture can be found +at the top of +.Pa sys/dev/imcsmb/imcsmb_pci.c . +.Sh WARNINGS +As mentioned above, firmware might use the iMC-SMBs to read DIMM temperatures. +The public iMC documentation does not describe any sort of coordination +mechanism to prevent requests from different sources -- such as the motherboard +firmware, a BMC, or the operating system -- from interfering with each other. +.Pp +.Bf Sy +Therefore, it is highly recommended that developers contact the motherboard +vendor for any board-specific instructions on how to disable and re-enable DIMM +temperature monitoring. +.Ef +.Pp +DIMM temperature monitoring should be disabled before returning from +.Fn imcsmb_pci_request_bus , +and re-enabled before returning from +.Fn imcsmb_pci_release_bus . +The driver includes comments to that effect at the appropriate locations. +The driver has been tested and shown to work, with only that type of +modification, on certain motherboards from Intel. +.Po +Unfortunately, those modifications were based on material covered under a +non-disclosure agreement, and therefore are not included in this driver. +.Pc +The driver has also been tested and shown to work as-is on various motherboards +from SuperMicro. +.Pp +The +.Xr smb 4 +driver will connect to the +.Xr smbus 4 +instances created by +.Nm . +However, since the IMC-SMBs are not general-purpose SMBus controllers, using +.Xr smbmsg 8 +with those +.Xr smb 4 +devices is not supported. +.Sh SEE ALSO +.Xr jedec_dimm 4 , +.Xr smbus 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 12.0 . +.Sh AUTHORS +The +.Nm +driver was originally written for Panasas by +.An Joe Kloss . +It was substantially refactored, and this manual page was written, by +.An Ravi Pokala Aq Mt rpokala@freebsd.org diff --git a/static/freebsd/man4/inet.4 b/static/freebsd/man4/inet.4 new file mode 100644 index 00000000..08ca67a7 --- /dev/null +++ b/static/freebsd/man4/inet.4 @@ -0,0 +1,366 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 December 31, 2024 +.Dt INET 4 +.Os +.Sh NAME +.Nm inet +.Nd Internet protocol family +.Sh SYNOPSIS +.In sys/types.h +.In netinet/in.h +.Sh DESCRIPTION +The Internet protocol family is a collection of protocols +layered atop the +.Em Internet Protocol +.Pq Tn IP +transport layer, and utilizing the Internet address format. +The Internet family provides protocol support for the +.Dv SOCK_STREAM , SOCK_DGRAM , +and +.Dv SOCK_RAW +socket types; the +.Dv SOCK_RAW +interface provides access to the +.Tn IP +protocol. +.Sh ADDRESSING +Internet addresses are four byte quantities, stored in +network standard format (on little endian machines, such as the +.Tn alpha , +.Tn amd64 +and +.Tn i386 +these are word and byte reversed). +The include file +.In netinet/in.h +defines this address +as a discriminated union. +.Pp +Sockets bound to the Internet protocol family utilize +the following addressing structure, +.Bd -literal -offset indent +struct sockaddr_in { + uint8_t sin_len; + sa_family_t sin_family; + in_port_t sin_port; + struct in_addr sin_addr; + char sin_zero[8]; +}; +.Ed +.Pp +Sockets may be created with the local address +.Dv INADDR_ANY +to affect +.Dq wildcard +matching on incoming messages. +The address in a +.Xr connect 2 +or +.Xr sendto 2 +call may be given as +.Dv INADDR_ANY +to mean +.Dq this host . +The distinguished address +.Dv INADDR_BROADCAST +is allowed as a shorthand for the broadcast address on the primary +network if the first network configured supports broadcast. +.Sh PROTOCOLS +The Internet protocol family is comprised of +the +.Tn IP +network protocol, Internet Control +Message Protocol +.Pq Tn ICMP , +Internet Group Management Protocol +.Pq Tn IGMP , +Transmission Control +Protocol +.Pq Tn TCP , +and User Datagram Protocol +.Pq Tn UDP . +.Tn TCP +is used to support the +.Dv SOCK_STREAM +abstraction while +.Tn UDP +is used to support the +.Dv SOCK_DGRAM +abstraction. +A raw interface to +.Tn IP +is available +by creating an Internet socket of type +.Dv SOCK_RAW . +The +.Tn ICMP +message protocol is accessible from a raw socket. +.Pp +The +.Nm +address on an interface consist of the address itself, the +netmask, either broadcast address in case of a broadcast +interface or peers address in case of point-to-point interface. +The following +.Xr ioctl 2 +commands are provided for a datagram socket in the Internet domain: +.Pp +.Bl -tag -width ".Dv SIOCGIFBRDADDR" -offset indent -compact +.It Dv SIOCAIFADDR +Add address to an interface. +The command requires +.Ft struct in_aliasreq +as argument. +.It Dv SIOCDIFADDR +Delete address from an interface. +The command requires +.Ft struct ifreq +as argument. +.It Dv SIOCGIFADDR +.It Dv SIOCGIFBRDADDR +.It Dv SIOCGIFDSTADDR +.It Dv SIOCGIFNETMASK +Return address information from interface. +The returned value is in +.Ft struct ifreq . +This way of address information retrieval is obsoleted, a +preferred way is to use +.Xr getifaddrs 3 +API. +.El +.Ss MIB (sysctl) Variables +In addition to the variables supported by the transport protocols in +.Va net.inet +(for which the respective manual pages may be consulted), +there are a number of general variables implemented in the +.Va net.inet.ip +branch of the +.Xr sysctl 3 +MIB, which can be also read or modified with +.Xr sysctl 8 . +The following general variables are defined: +.Bl -tag -width ".Va accept_sourceroute" +.It Va accept_sourceroute +Boolean: enable/disable accepting of source-routed IP packets (default false). +.It Va allow_net0 +Boolean: allow forwarding of, and ICMP responses to, packets with addresses in +0.0.0.0/8. +.It Va allow_net240 +Boolean: allow forwarding of, and ICMP responses to, packets with addresses in +240.0.0.0/4. +.It Va curfrags +Integer: Current number of IPv4 fragments across all reassembly queues +in all VNETs (read-only). +.It Va forwarding +Boolean: enable/disable forwarding of IP packets. +Defaults to off. +.It Va fragpackets +Integer: Current number of IPv4 fragment reassembly queue entries +for the VNET (read-only). +.It Va fragttl +Integer: time to live for IPv4 packet fragments in the per-VNET reassemby queue. +.It Va loopback_prefixlen +Integer: prefix length of the address space reserved for loopback purposes. +The default is 8, meaning that 127.0.0.0/8 is reserved for loopback, +and cannot be sent, received, or forwarded on a non-loopback interface. +Use of other values is experimental. +.It Va maxfragbucketsize +Integer: maximum number of reassembly queues per bucket. +Fragmented packets are hashed to buckets. +Each bucket has a list of reassembly queues. +The system must compare the incoming packets to the existing reassembly queues +in the bucket to find a matching reassembly queue. +To preserve system resources, the system limits the number of reassembly +queues allowed in each bucket. +This limit is recalculated when the number of mbuf clusters is changed or +when the value of +.Va maxfragpackets +changes. +This is a per-VNET limit. +.It Va maxfragpackets +Integer: maximum number of fragmented packets the host will accept and +simultaneously hold in the reassembly queue for a particular VNET. +0 means that the host will not accept any fragmented packets for that VNET. +\-1 means that the host will not apply this limit for that VNET. +This limit is recalculated when the number of mbuf clusters is changed. +This is a per-VNET limit. +.It Va maxfrags +Integer: maximum number of fragments the host will accept and simultaneously +hold across all reassembly queues in all VNETs. +If set to 0, reassembly is disabled. +If set to -1, this limit is not applied. +This limit is recalculated when the number of mbuf clusters is changed. +This is a global limit. +.It Va maxfragsperpacket +Integer: maximum number of fragments the host will accept and hold +in the reassembly queue for a packet. +0 means that the host will not accept any fragmented packets for the VNET. +This is a per-VNET limit. +.It Va mcast +Variables under the +.Va net.inet.ip.mcast +node are documented in +.Xr ip 4 . +.It Va no_same_prefix +Boolean: Refuse to create same prefixes on different interfaces. +This is a per-VNET value. +.It Va portrange +Variables under the +.Va net.inet.ip.portrange +node control port ranges used by transport protocols; see +.Xr ip 4 +for details. +.It Va process_options +Integer: control IP options processing. +By setting this variable to 0, all IP options in the incoming packets +will be ignored, and the packets will be passed unmodified. +By setting to 1, IP options in the incoming packets will be processed +accordingly. +By setting to 2, an +.Tn ICMP +.Dq "prohibited by filter" +message will be sent back in response to incoming packets with IP options. +Default is 1. +This +.Xr sysctl 8 +variable affects packets destined for a local host as well as packets +forwarded to some other host. +.It Va random_id +Boolean: control IP IDs generation behavior. +Setting this +.Xr sysctl 8 +to 1 causes the ID field in +.Em non-atomic +IP datagrams (or all IP datagrams, if +.Va rfc6864 +is disabled) to be randomized instead of incremented by 1 with each packet +generated. +This closes a minor information leak which allows remote observers to +determine the rate of packet generation on the machine by watching the +counter. +At the same time, on high-speed links, it can decrease the ID reuse +cycle greatly. +Default is 0 (sequential IP IDs). +IPv6 flow IDs and fragment IDs are always random. +.It Va random_id_collisions +Integer: count of IP ID collisions (read-only, per-VNET). +.It Va random_id_period +Integer: size of the IP ID array, which is the number of previous packets +for which the IDs are recorded. +The number must be between 512 and 32768 inclusive. +This is a per-VNET value. +.It Va random_id_total +Integer: count of IP IDs created (read-only, per-VNET). +.It Va reass_hashsize +Number of hash slots in the IPv4 reassembly queue (loader tunable). +.It Va redirect +Boolean: enable/disable sending of ICMP redirects in response to +.Tn IP +packets for which a better, and for the sender directly reachable, route +and next hop is known. +Defaults to on. +.It Va rfc1122_strong_es +Boolean: in non-forwarding mode +.Pq forwarding is disabled +partially implement the Strong End System model per RFC1122. +If a packet with destination address that is local arrives on a different +interface than the interface the address belongs to, the packet would be +silently dropped. +Enabling this option may break certain setups, e.g. having an alias address(es) +on loopback that are expected to be reachable by outside traffic. +Enabling some other network features, e.g. +.Xr carp 4 +or destination address rewriting +.Xr pfil 4 +filters may override and bypass this check. +Disabled by default. +.It Va rfc6864 +Boolean: control IP IDs generation behaviour. +True value enables RFC6864 support, which specifies that IP ID field of +.Em atomic +datagrams can be set to any value. +The +.Fx implementation sets it to zero. +Enabled by default. +.It Va source_address_validation +Boolean: perform source address validation for packets destined for the local +host. +Consider this as following Section 3.2 of RFC3704/BCP84, where we treat local +host as our own infrastructure. +Forwarded packets are unaffected by this +and it should not be considered an anti-spoof feature for a router. +Enabled by default. +.It Va sourceroute +Boolean: enable/disable forwarding of source-routed IP packets (default false). +.It Va ttl +Integer: default time-to-live +.Pq Dq TTL +to use for outgoing +.Tn IP +packets. +.El +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr socket 2 , +.Xr getifaddrs 3 , +.Xr sysctl 3 , +.Xr icmp 4 , +.Xr intro 4 , +.Xr ip 4 , +.Xr ipfirewall 4 , +.Xr route 4 , +.Xr tcp 4 , +.Xr udp 4 , +.Xr sysctl 8 , +.Xr pfil 9 +.Rs +.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial" +.%B PS1 +.%N 7 +.Re +.Rs +.%T "An Advanced 4.3 BSD Interprocess Communication Tutorial" +.%B PS1 +.%N 8 +.Re +.Sh HISTORY +The +.Nm +protocol interface appeared in +.Bx 4.2 . +The +.Dq protocol cloning +code appeared in +.Fx 2.1 . +.Sh CAVEATS +The Internet protocol support is subject to change as +the Internet protocols develop. +Users should not depend +on details of the current implementation, but rather +the services exported. diff --git a/static/freebsd/man4/inet6.4 b/static/freebsd/man4/inet6.4 new file mode 100644 index 00000000..20d32e03 --- /dev/null +++ b/static/freebsd/man4/inet6.4 @@ -0,0 +1,493 @@ +.\" $KAME: inet6.4,v 1.21 2001/04/05 01:00:18 itojun Exp $ +.\" +.\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. +.\" 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. Neither the name of the project nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT 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 PROJECT OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 31, 2026 +.Dt INET6 4 +.Os +.Sh NAME +.Nm inet6 +.Nd Internet protocol version 6 family +.Sh SYNOPSIS +.In sys/types.h +.In netinet/in.h +.Sh DESCRIPTION +The +.Nm +family is an updated version of +.Xr inet 4 +family. +While +.Xr inet 4 +implements Internet Protocol version 4, +.Nm +implements Internet Protocol version 6. +.Pp +.Nm +is a collection of protocols layered atop the +.Em Internet Protocol version 6 +.Pq Tn IPv6 +transport layer, and utilizing the IPv6 address format. +The +.Nm +family provides protocol support for the +.Dv SOCK_STREAM , SOCK_DGRAM , +and +.Dv SOCK_RAW +socket types; the +.Dv SOCK_RAW +interface provides access to the +.Tn IPv6 +protocol. +.Sh ADDRESSING +IPv6 addresses are 16 byte quantities, stored in network standard byteorder. +The include file +.In netinet/in.h +defines this address +as a discriminated union. +.Pp +Sockets bound to the +.Nm +family utilize the following addressing structure: +.Bd -literal -offset indent +struct sockaddr_in6 { + uint8_t sin6_len; + sa_family_t sin6_family; + in_port_t sin6_port; + uint32_t sin6_flowinfo; + struct in6_addr sin6_addr; + uint32_t sin6_scope_id; +}; +.Ed +.Pp +Sockets may be created with the local address +.Dq Dv :: +(which is equal to IPv6 address +.Dv 0:0:0:0:0:0:0:0 ) +to effect +.Dq wildcard +matching on incoming messages. +.Pp +The IPv6 specification defines scoped addresses, +like link-local or site-local addresses. +A scoped address is ambiguous to the kernel, +if it is specified without a scope identifier. +To manipulate scoped addresses properly from the userland, +programs must use the advanced API defined in RFC2292. +A compact description of the advanced API is available in +.Xr ip6 4 . +If a scoped address is specified without an explicit scope, +the kernel may raise an error. +Note that scoped addresses are not for daily use at this moment, +both from a specification and an implementation point of view. +.Pp +The KAME implementation supports an extended numeric IPv6 address notation +for link-local addresses, +like +.Dq Li fe80::1%de0 +to specify +.Do +.Li fe80::1 +on +.Li de0 +interface +.Dc . +This notation is supported by +.Xr getaddrinfo 3 +and +.Xr getnameinfo 3 . +Some of normal userland programs, such as +.Xr telnet 1 +or +.Xr ftp 1 , +are able to use this notation. +With special programs +like +.Xr ping 8 , +you can specify the outgoing interface by an extra command line option +to disambiguate scoped addresses. +.Pp +Scoped addresses are handled specially in the kernel. +In kernel structures like routing tables or interface structures, +a scoped address will have its interface index embedded into the address. +Therefore, +the address in some kernel structures is not the same as that on the wire. +The embedded index will become visible through a +.Dv PF_ROUTE +socket, kernel memory accesses via +.Xr kvm 3 +and on some other occasions. +HOWEVER, users should never use the embedded form. +For details please consult +.Pa IMPLEMENTATION +supplied with KAME kit. +.Sh PROTOCOLS +The +.Nm +family is comprised of the +.Tn IPv6 +network protocol, Internet Control +Message Protocol version 6 +.Pq Tn ICMPv6 , +Transmission Control Protocol +.Pq Tn TCP , +and User Datagram Protocol +.Pq Tn UDP . +.Tn TCP +is used to support the +.Dv SOCK_STREAM +abstraction while +.Tn UDP +is used to support the +.Dv SOCK_DGRAM +abstraction. +Note that +.Tn TCP +and +.Tn UDP +are common to +.Xr inet 4 +and +.Nm . +A raw interface to +.Tn IPv6 +is available +by creating an Internet socket of type +.Dv SOCK_RAW . +The +.Tn ICMPv6 +message protocol is accessible from a raw socket. +.Ss MIB Variables +A number of variables are implemented in the +.Va net.inet6 +branch of the +.Xr sysctl 3 +MIB. +In addition to the variables supported by the transport protocols +(for which the respective manual pages may be consulted), +the following general variables are defined: +.Bl -tag -width IPV6CTL_MAXFRAGPACKETS +.It Dv IPV6CTL_FORWARDING +.Pq ip6.forwarding +Boolean: enable/disable forwarding of +.Tn IPv6 +packets. +Also, identify if the node is acting as a router. +Defaults to off. +.It Dv IPV6CTL_SENDREDIRECTS +.Pq ip6.redirect +Boolean: enable/disable sending of +.Tn ICMPv6 +redirects in response to unforwardable +.Tn IPv6 +packets. +This option is ignored unless the node is routing +.Tn IPv6 +packets, +and should normally be enabled on all systems. +Defaults to on. +.It Dv IPV6CTL_DEFHLIM +.Pq ip6.hlim +Integer: default hop limit value to use for outgoing +.Tn IPv6 +packets. +This value applies to all the transport protocols on top of +.Tn IPv6 . +There are APIs to override the value. +.It Dv IPV6CTL_MAXFRAGS +.Pq ip6.maxfrags +Integer: maximum number of fragments the host will accept and simultaneously +hold across all reassembly queues in all VNETs. +If set to 0, fragment reassembly is disabled. +If set to -1, this limit is not applied. +This limit is recalculated when the number of mbuf clusters is changed. +This is a global limit. +.It Dv IPV6CTL_MAXFRAGPACKETS +.Pq ip6.maxfragpackets +Integer: maximum number of fragmented packets the node will accept and +simultaneously hold in the reassembly queue for a particular VNET. +0 means that the node will not accept any fragmented packets for that VNET. +-1 means that the node will not apply this limit for that VNET. +This limit is recalculated when the number of mbuf clusters is changed. +This is a per-VNET limit. +.It Dv IPV6CTL_MAXFRAGBUCKETSIZE +.Pq ip6.maxfragbucketsize +Integer: maximum number of reassembly queues per bucket. +Fragmented packets are hashed to buckets. +Each bucket has a list of reassembly queues. +The system must compare the incoming packets to the existing reassembly queues +in the bucket to find a matching reassembly queue. +To preserve system resources, the system limits the number of reassembly +queues allowed in each bucket. +This limit is recalculated when the number of mbuf clusters is changed or +when the value of +.Va ip6.maxfragpackets +changes. +This is a per-VNET limit. +.It Dv IPV6CTL_MAXFRAGSPERPACKET +.Pq ip6.maxfragsperpacket +Integer: maximum number of fragments the host will accept and hold in the +ressembly queue for a packet. +This is a per-VNET limit. +.It Dv IPV6CTL_ACCEPT_RTADV +.Pq ip6.accept_rtadv +Boolean: the default value of a per-interface flag to +enable/disable receiving of +.Tn ICMPv6 +router advertisement packets, +and autoconfiguration of address prefixes and default routers. +The node must be a host +(not a router) +for the option to be meaningful. +Defaults to off. +.It Dv IPV6CTL_AUTO_LINKLOCAL +.Pq ip6.auto_linklocal +Boolean: the default value of a per-interface flag to +enable/disable performing automatic link-local address configuration. +Defaults to on. +.It Dv IPV6CTL_LOG_INTERVAL +.Pq ip6.log_interval +Integer: default interval between +.Tn IPv6 +packet forwarding engine log output +(in seconds). +.It Dv IPV6CTL_HDRNESTLIMIT +.Pq ip6.hdrnestlimit +Integer: default number of the maximum +.Tn IPv6 +extension headers +permitted on incoming +.Tn IPv6 +packets. +If set to 0, the node will accept as many extension headers as possible. +.It Dv IPV6CTL_DAD_COUNT +.Pq ip6.dad_count +Integer: default number of +.Tn IPv6 +DAD +.Pq duplicated address detection +probe packets. +The packets will be generated when +.Tn IPv6 +interface addresses are configured. +.It Dv IPV6CTL_GRAND_COUNT +.Pq ip6.grand_count +Integer: default number of +.Tn IPv6 +GRAND +.Pq gratuitous neighbor discovery +unsolicited NA packets. +The packets will be generated when +.Tn IPv6 +interface addresses are configured or when there are changes to +link-layer interface addresses. +.It Dv IPV6CTL_AUTO_FLOWLABEL +.Pq ip6.auto_flowlabel +Boolean: enable/disable automatic filling of +.Tn IPv6 +flowlabel field, for outstanding connected transport protocol packets. +The field might be used by intermediate routers to identify packet flows. +Defaults to on. +.It Dv IPV6CTL_DEFMCASTHLIM +.Pq ip6.defmcasthlim +Integer: default hop limit value for an +.Tn IPv6 +multicast packet sourced by the node. +This value applies to all the transport protocols on top of +.Tn IPv6 . +There are APIs to override the value as documented in +.Xr ip6 4 . +.It Dv IPV6CTL_GIF_HLIM +.Pq ip6.gifhlim +Integer: default maximum hop limit value for an +.Tn IPv6 +packet generated by +.Xr gif 4 +tunnel interface. +.It Dv IPV6CTL_KAME_VERSION +.Pq ip6.kame_version +String: identifies the version of KAME +.Tn IPv6 +stack implemented in the kernel. +.It Dv IPV6CTL_USE_DEPRECATED +.Pq ip6.use_deprecated +Boolean: enable/disable use of deprecated address, +specified in RFC2462 5.5.4. +Defaults to on. +.It Dv IPV6CTL_RR_PRUNE +.Pq ip6.rr_prune +Integer: default interval between +.Tn IPv6 +router renumbering prefix babysitting, in seconds. +.It Dv IPV6CTL_V6ONLY +.Pq ip6.v6only +Boolean: enable/disable the prohibited use of +.Tn IPv4 +mapped address on +.Dv AF_INET6 +sockets. +Defaults to on. +.It Va ip6.log_cannot_forward +Boolean: log packets that can't be forwarded because of unspecified source +address or destination address beyond the scope of the source address as +described in RFC4443. +Enabled by default. +.It Va ip6.source_address_validation +Boolean: perform source address validation for packets destined for the local +host. +Consider this as following Section 3.2 of RFC3704/BCP84, where we treat local +host as our own infrastructure. +This has no effect on packets to be forwarded, so don't consider it as +anti-spoof feature for a router. +Enabled by default. +.El +.Ss Interaction between IPv4/v6 sockets +By default, +.Fx +does not route IPv4 traffic to +.Dv AF_INET6 +sockets. +The default behavior intentionally violates RFC2553 for security reasons. +Listen to two sockets if you want to accept both IPv4 and IPv6 traffic. +IPv4 traffic may be routed with certain +per-socket/per-node configuration, however, it is not recommended to do so. +Consult +.Xr ip6 4 +for details. +.Pp +The behavior of +.Dv AF_INET6 +TCP/UDP socket is documented in RFC2553. +Basically, it says this: +.Bl -bullet -compact +.It +A specific bind on an +.Dv AF_INET6 +socket +.Xr ( bind 2 +with an address specified) +should accept IPv6 traffic to that address only. +.It +If you perform a wildcard bind +on an +.Dv AF_INET6 +socket +.Xr ( bind 2 +to IPv6 address +.Li :: ) , +and there is no wildcard bind +.Dv AF_INET +socket on that TCP/UDP port, IPv6 traffic as well as IPv4 traffic +should be routed to that +.Dv AF_INET6 +socket. +IPv4 traffic should be seen as if it came from an IPv6 address like +.Li ::ffff:10.1.1.1 . +This is called an IPv4 mapped address. +.It +If there are both a wildcard bind +.Dv AF_INET +socket and a wildcard bind +.Dv AF_INET6 +socket on one TCP/UDP port, they should behave separately. +IPv4 traffic should be routed to the +.Dv AF_INET +socket and IPv6 should be routed to the +.Dv AF_INET6 +socket. +.El +.Pp +However, RFC2553 does not define the ordering constraint between calls to +.Xr bind 2 , +nor how IPv4 TCP/UDP port numbers and IPv6 TCP/UDP port numbers +relate to each other +(should they be integrated or separated). +Implemented behavior is very different from kernel to kernel. +Therefore, it is unwise to rely too much upon the behavior of +.Dv AF_INET6 +wildcard bind sockets. +It is recommended to listen to two sockets, one for +.Dv AF_INET +and another for +.Dv AF_INET6 , +when you would like to accept both IPv4 and IPv6 traffic. +.Pp +It should also be noted that +malicious parties can take advantage of the complexity presented above, +and are able to bypass access control, +if the target node routes IPv4 traffic to +.Dv AF_INET6 +socket. +Users are advised to take care handling connections +from IPv4 mapped address to +.Dv AF_INET6 +sockets. +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr socket 2 , +.Xr sysctl 3 , +.Xr icmp6 4 , +.Xr intro 4 , +.Xr ip6 4 , +.Xr tcp 4 , +.Xr udp 4 +.Rs +.%A A. Conta +.%A S. Deering +.%A M. Gupta +.%T "Internet Control Message Protocol (ICMPv6) for the Internet" \ + "Protocol Version 6 (IPv6) Specification" +.%R RFC 4443 +.%D March 2006 +.Re +.Sh STANDARDS +.Rs +.%A Tatsuya Jinmei +.%A Atsushi Onoe +.%T "An Extension of Format for IPv6 Scoped Addresses" +.%R internet draft +.%D June 2000 +.%N draft-ietf-ipngwg-scopedaddr-format-02.txt +.%O work in progress material +.Re +.Sh HISTORY +The +.Nm +protocol interfaces are defined in RFC2553 and RFC2292. +The implementation described herein appeared in the WIDE/KAME project. +.Sh BUGS +The IPv6 support is subject to change as the Internet protocols develop. +Users should not depend on details of the current implementation, +but rather the services exported. +.Pp +Users are suggested to implement +.Dq version independent +code as much as possible, as you will need to support both +.Xr inet 4 +and +.Nm . diff --git a/static/freebsd/man4/intpm.4 b/static/freebsd/man4/intpm.4 new file mode 100644 index 00000000..d4b01956 --- /dev/null +++ b/static/freebsd/man4/intpm.4 @@ -0,0 +1,84 @@ +.\" Copyright (c) 1999 Takanori Watanabe +.\" 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 September 22, 2016 +.Dt INTPM 4 +.Os +.Sh NAME +.Nm intpm +.Nd Intel PIIX4 Power Management controller driver +.Sh SYNOPSIS +.Cd device pci +.Cd device smbus +.Cd device smb +.Cd device intpm +.Sh DESCRIPTION +The +.Nm +driver provides access to +.Tn Intel PIIX4 +compatible Power Management controllers. +Currently, only +.Xr smbus 4 +controller function is implemented. +.Sh HARDWARE +The +.Nm +driver supports the following chipsets: +.Pp +.Bl -bullet -compact +.It +Intel 82371AB/82443MX +.It +ATI IXP400 +.It +AMD SB600/7x0/8x0/9x0 southbridges +.It +AMD Axx/Hudson/Bolton FCHs +.It +AMD FCH integrated into Family 15h Models 60h-6Fh, 70h-7Fh Processors +.It +AMD FCH integrated into Family 16h Models 00h-0Fh, 30h-3Fh Processors +.El +.Sh SEE ALSO +.Xr amdpm 4 , +.Xr amdsmb 4 , +.Xr ichsmb 4 , +.Xr smb 4 , +.Xr smbus 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 3.4 . +.Sh AUTHORS +This +manual page was written by +.An Takanori Watanabe Aq Mt takawata@shidahara1.planet.sci.kobe-u.ac.jp . +.Sh BUGS +This device requires IRQ 9 exclusively. +To use this, you should enable +ACPI function in BIOS configuration, or PnP mechanism assigns conflicted +IRQ for PnP ISA card. +And do not use IRQ 9 for Non-PnP ISA cards. diff --git a/static/freebsd/man4/intro.4 b/static/freebsd/man4/intro.4 new file mode 100644 index 00000000..e4caf669 --- /dev/null +++ b/static/freebsd/man4/intro.4 @@ -0,0 +1,216 @@ +.\" +.\" Copyright (c) 1996 David E. O'Brien, Joerg Wunsch +.\" Copyright (c) 2019 Andrew Gierth +.\" +.\" 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 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 April 3, 2019 +.Dt INTRO 4 +.Os +.Sh NAME +.Nm intro +.Nd introduction to devices and device drivers +.Sh DESCRIPTION +This section contains information related to devices, device drivers +and miscellaneous hardware. +.Ss The device abstraction +Device is a term used mostly for hardware-related stuff that belongs +to the system, like disks, printers, or a graphics display with its +keyboard. +There are also so-called +.Em pseudo-devices +where a device driver emulates the behaviour of a device in software +without any particular underlying hardware. +A typical example for +the latter class is +.Pa /dev/mem , +a mechanism whereby the physical memory can be accessed using file +access semantics. +.Pp +The device abstraction generally provides a common set of system +calls, which are dispatched to the corresponding device driver by the +upper layers of the kernel. +The set of system calls available for devices is chosen from +.Xr open 2 , +.Xr close 2 , +.Xr read 2 , +.Xr write 2 , +.Xr ioctl 2 , +.Xr select 2 , +and +.Xr mmap 2 . +Not all drivers implement all system calls; for example, calling +.Xr mmap 2 +on a keyboard device is not likely to be useful. +.Pp +Aspects of the device abstraction have changed significantly in +.Fx +over the past two decades. +The section +.Sx Historical Notes +describes some of the more important differences. +.Ss Accessing Devices +Most of the devices in +.Fx +are accessed through +.Em device nodes , +sometimes also called +.Em special files . +They are located within instances of the +.Xr devfs 4 +filesystem, which is conventionally mounted on the directory +.Pa /dev +in the file system hierarchy +(see also +.Xr hier 7 ) . +.Pp +The +.Xr devfs 4 +filesystem creates or removes device nodes automatically according to +the physical hardware recognized as present at any given time. +For pseudo-devices, device nodes may be created and removed dynamically +as required, depending on the nature of the device. +.Pp +Access restrictions to device nodes are usually subject to the regular +file permissions of the device node entry, instead of being enforced +directly by the drivers in the kernel. +But since device nodes are not stored persistently between reboots, +those file permissions are set at boot time from rules specified in +.Xr devfs.conf 5 , +or dynamically according to rules defined in +.Xr devfs.rules 5 +or set using the +.Xr devfs 8 +command. +In the latter case, different rules may be used to make different sets +of devices visible within different instances of the +.Xr devfs 4 +filesystem, which may be used, for example, to prevent jailed +subsystems from accessing unsafe devices. +Manual changes to device +node permissions may still be made, but will not persist. +.Ss Drivers without device nodes +Drivers for network devices do not use device nodes in order to be +accessed. +Their selection is based on other decisions inside the +kernel, and instead of calling +.Xr open 2 , +use of a network device is generally introduced by using the system +call +.Xr socket 2 . +.Ss Configuring a driver into the kernel +For each kernel, there is a configuration file that is used as a base +to select the facilities and drivers for that kernel, and to tune +several options. +See +.Xr config 8 +for a detailed description of the files involved. +The individual manual pages in this section provide a sample line for the +configuration file in their synopsis portions. +See also the files +.Pa /usr/src/sys/conf/NOTES +and +.Pa /usr/src/sys/${ARCH}/conf/NOTES . +.Pp +Drivers need not be statically compiled into the kernel; they may also be +loaded as modules, in which case any device nodes they provide will appear +only after the module is loaded (and has attached to suitable hardware, +if applicable). +.Ss Historical Notes +Prior to +.Fx 6.0 , +device nodes could be created in the traditional way as persistent +entries in the file system. +While such entries can still be created, they no longer function to +access devices. +.Pp +Prior to +.Fx 5.0 , +devices for disk and tape drives existed in two variants, known as +.Em block +and +.Em character +devices, or to use better terms, buffered and unbuffered +(raw) +devices. +The traditional names are reflected by the letters +.Dq Li b +and +.Dq Li c +as the file type identification in the output of +.Dq Li ls -l . +Raw devices were traditionally named with a prefix of +.Dq Li r , +for example +.Pa /dev/rda0 +would denote the raw version of the disk whose buffered device was +.Pa /dev/da0 . +.Em This is no longer the case ; +all disk devices are now +.Dq raw +in the traditional sense, even though they are not given +.Dq Li r +prefixes, and +.Dq buffered +devices no longer exist at all. +.Pp +Buffered devices were accessed through a buffer cache maintained by +the operating system; historically this was the system's primary disk +cache, but in +.Fx +this was rendered obsolete by the introduction of unified virtual +memory management. +Buffered devices could be read or written at any +byte position, with the buffer mechanism handling the reading and +writing of disk blocks. +In contrast, raw disk devices can be read or +written only at positions and lengths that are multiples of the +underlying device block size, and +.Xr write 2 +calls are +.Em synchronous , +not returning to the caller until the data has been handed off to the +device. +.Sh SEE ALSO +.Xr close 2 , +.Xr ioctl 2 , +.Xr mmap 2 , +.Xr open 2 , +.Xr read 2 , +.Xr select 2 , +.Xr socket 2 , +.Xr write 2 , +.Xr devfs 4 , +.Xr hier 7 , +.Xr config 8 +.Sh HISTORY +This manual page first appeared in +.Fx 2.1 . +.Sh AUTHORS +.An -nosplit +This man page has been rewritten by +.An Andrew Gierth +from an earlier version written by +.An J\(:org Wunsch +with initial input by +.An David E. O'Brien . diff --git a/static/freebsd/man4/io.4 b/static/freebsd/man4/io.4 new file mode 100644 index 00000000..fa989f64 --- /dev/null +++ b/static/freebsd/man4/io.4 @@ -0,0 +1,128 @@ +.\" +.\" Copyright (c) 1996 Joerg Wunsch +.\" +.\" 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 June 1, 2010 +.Dt IO 4 +.Os +.Sh NAME +.Nm io +.Nd I/O privilege file +.Sh SYNOPSIS +.Cd "device io" +.Pp +.In sys/types.h +.In sys/ioctl.h +.In dev/io/iodev.h +.In machine/iodev.h +.Bd -literal +struct iodev_pio_req { + u_int access; + u_int port; + u_int width; + u_int val; +}; +.Ed +.Sh DESCRIPTION +The special file +.Pa /dev/io +is a controlled security hole that allows a process to gain I/O +privileges +(which are normally reserved for kernel-internal code). +This can be useful in order to write userland +programs that handle some hardware directly. +.Pp +The usual operations on the device are to open it via the +.Xr open 2 +interface and to send I/O requests to the file descriptor using the +.Xr ioctl 2 +syscall. +.Pp +The +.Xr ioctl 2 +requests available for +.Pa /dev/io +are mostly platform dependent, but there are also some in common between +all of them. +The +.Dv IODEV_PIO +is used by all the architectures in order to request that an I/O operation +be performed. +It takes a 'struct iodev_pio_req' argument that must be previously setup. +.Pp +The +.Fa access +member specifies the type of operation requested. +It may be: +.Bl -tag -width IODEV_PIO_WRITE +.It Dv IODEV_PIO_READ +The operation is an "in" type. +A value will be read from the specified port +(retrieved from the +.Fa port +member) and the result will be stored in the +.Fa val +member. +.It Dv IODEV_PIO_WRITE +The operation is a "out" type. +The value will be fetched from the +.Fa val +member and will be written out to the specified port (defined as the +.Fa port +member). +.El +.Pp +Finally, the +.Fa width +member specifies the size of the operand to be read/written, expressed +in bytes. +.Pp +In addition to any file access permissions on +.Pa /dev/io , +the kernel enforces that only the super-user may open this device. +.Sh LEGACY +The +.Pa /dev/io +interface used to be very i386 specific and worked differently. +The initial implementation simply raised the +.Em IOPL +of the current thread when +.Xr open 2 +was called on the device. +This behaviour is retained in the current implementation as legacy +support for both i386 and amd64 architectures. +.Sh SEE ALSO +.Xr close 2 , +.Xr i386_get_ioperm 2 , +.Xr i386_set_ioperm 2 , +.Xr ioctl 2 , +.Xr open 2 , +.Xr mem 4 +.Sh HISTORY +The +.Nm +file appeared in +.Fx 1.0 . diff --git a/static/freebsd/man4/ioat.4 b/static/freebsd/man4/ioat.4 new file mode 100644 index 00000000..1c0e1dd4 --- /dev/null +++ b/static/freebsd/man4/ioat.4 @@ -0,0 +1,332 @@ +.\" Copyright (c) 2015 EMC / Isilon Storage Division +.\" 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 AUTHORS 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 AUTHORS 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 May 3, 2016 +.Dt IOAT 4 amd64 +.Os +.Sh NAME +.Nm I/OAT +.Nd Intel I/O Acceleration Technology +.Sh SYNOPSIS +To compile this driver into your kernel, +place the following line in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ioat" +.Ed +.Pp +Or, to load the driver as a module at boot, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ioat_load="YES" +.Ed +.Pp +In +.Xr loader.conf 5 : +.Pp +.Cd hw.ioat.force_legacy_interrupts=0 +.Pp +In +.Xr loader.conf 5 or +.Xr sysctl.conf 5 : +.Pp +.Cd hw.ioat.enable_ioat_test=0 +.Cd hw.ioat.debug_level=0 +(only critical errors; maximum of 3) +.Pp +.Ft typedef void +.Fn (*bus_dmaengine_callback_t) "void *arg" "int error" +.Pp +.Ft bus_dmaengine_t +.Fn ioat_get_dmaengine "uint32_t channel_index" +.Ft void +.Fn ioat_put_dmaengine "bus_dmaengine_t dmaengine" +.Ft int +.Fn ioat_get_hwversion "bus_dmaengine_t dmaengine" +.Ft size_t +.Fn ioat_get_max_io_size "bus_dmaengine_t dmaengine" +.Ft int +.Fn ioat_set_interrupt_coalesce "bus_dmaengine_t dmaengine" "uint16_t delay" +.Ft uint16_t +.Fn ioat_get_max_coalesce_period "bus_dmaengine_t dmaengine" +.Ft void +.Fn ioat_acquire "bus_dmaengine_t dmaengine" +.Ft int +.Fn ioat_acquire_reserve "bus_dmaengine_t dmaengine" "uint32_t n" "int mflags" +.Ft void +.Fn ioat_release "bus_dmaengine_t dmaengine" +.Ft struct bus_dmadesc * +.Fo ioat_copy +.Fa "bus_dmaengine_t dmaengine" +.Fa "bus_addr_t dst" +.Fa "bus_addr_t src" +.Fa "bus_size_t len" +.Fa "bus_dmaengine_callback_t callback_fn" +.Fa "void *callback_arg" +.Fa "uint32_t flags" +.Fc +.Ft struct bus_dmadesc * +.Fo ioat_copy_8k_aligned +.Fa "bus_dmaengine_t dmaengine" +.Fa "bus_addr_t dst1" +.Fa "bus_addr_t dst2" +.Fa "bus_addr_t src1" +.Fa "bus_addr_t src2" +.Fa "bus_dmaengine_callback_t callback_fn" +.Fa "void *callback_arg" +.Fa "uint32_t flags" +.Fc +.Ft struct bus_dmadesc * +.Fo ioat_copy_crc +.Fa "bus_dmaengine_t dmaengine" +.Fa "bus_addr_t dst" +.Fa "bus_addr_t src" +.Fa "bus_size_t len" +.Fa "uint32_t *initialseed" +.Fa "bus_addr_t crcptr" +.Fa "bus_dmaengine_callback_t callback_fn" +.Fa "void *callback_arg" +.Fa "uint32_t flags" +.Fc +.Ft struct bus_dmadesc * +.Fo ioat_crc +.Fa "bus_dmaengine_t dmaengine" +.Fa "bus_addr_t src" +.Fa "bus_size_t len" +.Fa "uint32_t *initialseed" +.Fa "bus_addr_t crcptr" +.Fa "bus_dmaengine_callback_t callback_fn" +.Fa "void *callback_arg" +.Fa "uint32_t flags" +.Fc +.Ft struct bus_dmadesc * +.Fo ioat_blockfill +.Fa "bus_dmaengine_t dmaengine" +.Fa "bus_addr_t dst" +.Fa "uint64_t fillpattern" +.Fa "bus_size_t len" +.Fa "bus_dmaengine_callback_t callback_fn" +.Fa "void *callback_arg" +.Fa "uint32_t flags" +.Fc +.Ft struct bus_dmadesc * +.Fo ioat_null +.Fa "bus_dmaengine_t dmaengine" +.Fa "bus_dmaengine_callback_t callback_fn" +.Fa "void *callback_arg" +.Fa "uint32_t flags" +.Fc +.Sh DESCRIPTION +The +.Nm +driver provides a kernel API to a variety of DMA engines on some Intel server +platforms. +.Pp +There is a number of DMA channels per CPU package. +(Typically 4 or 8.) +Each may be used independently. +Operations on a single channel proceed sequentially. +.Pp +Blockfill operations can be used to write a 64-bit pattern to memory. +.Pp +Copy operations can be used to offload memory copies to the DMA engines. +.Pp +Null operations do nothing, but may be used to test the interrupt and callback +mechanism. +.Pp +All operations can optionally trigger an interrupt at completion with the +.Ar DMA_INT_EN +flag. +For example, a user might submit multiple operations to the same channel and +only enable an interrupt and callback for the last operation. +.Pp +The hardware can delay and coalesce interrupts on a given channel for a +configurable period of time, in microseconds. +This may be desired to reduce the processing and interrupt overhead per +descriptor, especially for workflows consisting of many small operations. +Software can control this on a per-channel basis with the +.Fn ioat_set_interrupt_coalesce +API. +The +.Fn ioat_get_max_coalesce_period +API can be used to determine the maximum coalescing period supported by the +hardware, in microseconds. +Current platforms support up to a 16.383 millisecond coalescing period. +Optimal configuration will vary by workflow and desired operation latency. +.Pp +All operations are safe to use in a non-blocking context with the +.Ar DMA_NO_WAIT +flag. +(Of course, allocations may fail and operations requested with +.Ar DMA_NO_WAIT +may return NULL.) +.Pp +Operations that depend on the result of prior operations should use +.Ar DMA_FENCE . +For example, such a scenario can happen when two related DMA operations are +queued. +First, a DMA copy to one location (A), followed directly by a DMA copy +from A to B. +In this scenario, some classes of I/OAT hardware may prefetch A for the second +operation before it is written by the first operation. +To avoid reading a stale value in sequences of dependent operations, use +.Ar DMA_FENCE . +.Pp +All operations, as well as +.Fn ioat_get_dmaengine , +can return NULL in special circumstances. +For example, if the +.Nm +driver is being unloaded, or the administrator has induced a hardware reset, or +a usage error has resulted in a hardware error state that needs to be recovered +from. +.Pp +It is invalid to attempt to submit new DMA operations in a +.Fa bus_dmaengine_callback_t +context. +.Pp +The CRC operations have three distinct modes. +The default mode is to accumulate. +By accumulating over multiple descriptors, a user may gather a CRC over several +chunks of memory and only write out the result once. +.Pp +The +.Ar DMA_CRC_STORE +flag causes the operation to emit the CRC32C result. +If +.Ar DMA_CRC_INLINE +is set, the result is written inline with the destination data (or source in +.Fn ioat_crc +mode). +If +.Ar DMA_CRC_INLINE +is not set, the result is written to the provided +.Fa crcptr . +.Pp +Similarly, the +.Ar DMA_CRC_TEST +flag causes the operation to compare the CRC32C result to an existing checksum. +If +.Ar DMA_CRC_INLINE +is set, the result is compared against the inline four bytes trailing the +source data. +If it is not set, the result is compared against the value pointed to by +.Fa crcptr . +.Pp +.Fn ioat_copy_crc +calculates a CRC32C while copying data. +.Fn ioat_crc +only computes a CRC32C of some data. +If the +.Fa initialseed +argument to either routine is non-NULL, the CRC32C engine is initialized with +the value it points to. +.Sh USAGE +A typical user will lookup the DMA engine object for a given channel with +.Fn ioat_get_dmaengine . +When the user wants to offload a copy, they will first +.Fn ioat_acquire +the +.Ar bus_dmaengine_t +object for exclusive access to enqueue operations on that channel. +Optionally, the user can reserve space by using +.Fn ioat_acquire_reserve +instead. +If +.Fn ioat_acquire_reserve +succeeds, there is guaranteed to be room for +.Fa N +new operations in the internal ring buffer. +.Pp +Then, they will submit one or more operations using +.Fn ioat_blockfill , +.Fn ioat_copy , +.Fn ioat_copy_8k_aligned , +.Fn ioat_copy_crc , +.Fn ioat_crc , +or +.Fn ioat_null . +After queuing one or more individual DMA operations, they will +.Fn ioat_release +the +.Ar bus_dmaengine_t +to drop their exclusive access to the channel. +The routine they provided for the +.Fa callback_fn +argument will be invoked with the provided +.Fa callback_arg +when the operation is complete. +When they are finished with the +.Ar bus_dmaengine_t , +the user should +.Fn ioat_put_dmaengine . +.Pp +Users MUST NOT block between +.Fn ioat_acquire +and +.Fn ioat_release . +Users SHOULD NOT hold +.Ar bus_dmaengine_t +references for a very long time to enable fault recovery and kernel module +unload. +.Pp +For an example of usage, see +.Pa src/sys/dev/ioat/ioat_test.c . +.Sh FILES +.Bl -tag +.It Pa /dev/ioat_test +test device for +.Xr ioatcontrol 8 +.El +.Sh SEE ALSO +.Xr ioatcontrol 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 11.0 . +.Sh AUTHORS +The +.Nm +driver was developed by +.An \&Jim Harris Aq Mt jimharris@FreeBSD.org , +.An \&Carl Delsey Aq Mt carl.r.delsey@intel.com , +and +.An \&Conrad Meyer Aq Mt cem@FreeBSD.org . +This manual page was written by +.An \&Conrad Meyer Aq Mt cem@FreeBSD.org . +.Sh CAVEATS +Copy operation takes bus addresses as parameters, not virtual addresses. +.Pp +Buffers for individual copy operations must be physically contiguous. +.Pp +Copies larger than max transfer size (1MB, but may vary by hardware) are not +supported. +Future versions will likely support this by breaking up the transfer into +smaller sizes. +.Sh BUGS +The +.Nm +driver only supports blockfill, copy, and null operations at this time. +The driver does not yet support advanced DMA modes, such as XOR, that some +I/OAT devices support. diff --git a/static/freebsd/man4/ip.4 b/static/freebsd/man4/ip.4 new file mode 100644 index 00000000..fb5ea398 --- /dev/null +++ b/static/freebsd/man4/ip.4 @@ -0,0 +1,952 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 August 9, 2021 +.Dt IP 4 +.Os +.Sh NAME +.Nm ip +.Nd Internet Protocol +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netinet/in.h +.Ft int +.Fn socket AF_INET SOCK_RAW proto +.Sh DESCRIPTION +.Tn IP +is the transport layer protocol used +by the Internet protocol family. +Options may be set at the +.Tn IP +level +when using higher-level protocols that are based on +.Tn IP +(such as +.Tn TCP +and +.Tn UDP ) . +It may also be accessed +through a +.Dq raw socket +when developing new protocols, or +special-purpose applications. +.Pp +There are several +.Tn IP-level +.Xr setsockopt 2 +and +.Xr getsockopt 2 +options. +.Dv IP_OPTIONS +may be used to provide +.Tn IP +options to be transmitted in the +.Tn IP +header of each outgoing packet +or to examine the header options on incoming packets. +.Tn IP +options may be used with any socket type in the Internet family. +The format of +.Tn IP +options to be sent is that specified by the +.Tn IP +protocol specification (RFC-791), with one exception: +the list of addresses for Source Route options must include the first-hop +gateway at the beginning of the list of gateways. +The first-hop gateway address will be extracted from the option list +and the size adjusted accordingly before use. +To disable previously specified options, +use a zero-length buffer: +.Bd -literal +setsockopt(s, IPPROTO_IP, IP_OPTIONS, NULL, 0); +.Ed +.Pp +.Dv IP_TOS +may be used to set the differential service codepoint (DSCP) and the +explicit congestion notification (ECN) codepoint. +Setting the ECN codepoint - the two least significant bits - on a +socket using a transport protocol implementing ECN has no effect. +.Pp +.Dv IP_TTL +configures the time-to-live (TTL) field in the +.Tn IP +header for +.Dv SOCK_STREAM , SOCK_DGRAM , +and certain types of +.Dv SOCK_RAW +sockets. +For example, +.Bd -literal +int tos = IPTOS_DSCP_EF; /* see */ +setsockopt(s, IPPROTO_IP, IP_TOS, &tos, sizeof(tos)); + +int ttl = 60; /* max = 255 */ +setsockopt(s, IPPROTO_IP, IP_TTL, &ttl, sizeof(ttl)); +.Ed +.Pp +.Dv IP_IPSEC_POLICY +controls IPSec policy for sockets. +For example, +.Bd -literal +const char *policy = "in ipsec ah/transport//require"; +char *buf = ipsec_set_policy(policy, strlen(policy)); +setsockopt(s, IPPROTO_IP, IP_IPSEC_POLICY, buf, ipsec_get_policylen(buf)); +.Ed +.Pp +.Dv IP_MINTTL +may be used to set the minimum acceptable TTL a packet must have when +received on a socket. +All packets with a lower TTL are silently dropped. +This option is only really useful when set to 255, preventing packets +from outside the directly connected networks reaching local listeners +on sockets. +.Pp +.Dv IP_DONTFRAG +may be used to set the Don't Fragment flag on IP packets. +Currently this option is respected only on +.Xr udp 4 +and raw +.Nm +sockets, unless the +.Dv IP_HDRINCL +option has been set. +On +.Xr tcp 4 +sockets, the Don't Fragment flag is controlled by the Path +MTU Discovery option. +Sending a packet larger than the MTU size of the egress interface, +determined by the destination address, returns an +.Er EMSGSIZE +error. +.Pp +If the +.Dv IP_ORIGDSTADDR +option is enabled on a +.Dv SOCK_DGRAM +socket, +the +.Xr recvmsg 2 +call will return the destination +.Tn IP +address and destination port for a +.Tn UDP +datagram. +The +.Vt msg_control +field in the +.Vt msghdr +structure points to a buffer +that contains a +.Vt cmsghdr +structure followed by the +.Tn sockaddr_in +structure. +The +.Vt cmsghdr +fields have the following values: +.Bd -literal +cmsg_len = CMSG_LEN(sizeof(struct sockaddr_in)) +cmsg_level = IPPROTO_IP +cmsg_type = IP_ORIGDSTADDR +.Ed +.Pp +If the +.Dv IP_RECVDSTADDR +option is enabled on a +.Dv SOCK_DGRAM +socket, +the +.Xr recvmsg 2 +call will return the destination +.Tn IP +address for a +.Tn UDP +datagram. +The +.Vt msg_control +field in the +.Vt msghdr +structure points to a buffer +that contains a +.Vt cmsghdr +structure followed by the +.Tn IP +address. +The +.Vt cmsghdr +fields have the following values: +.Bd -literal +cmsg_len = CMSG_LEN(sizeof(struct in_addr)) +cmsg_level = IPPROTO_IP +cmsg_type = IP_RECVDSTADDR +.Ed +.Pp +The source address to be used for outgoing +.Tn UDP +datagrams on a socket can be specified as ancillary data with a type code of +.Dv IP_SENDSRCADDR . +The msg_control field in the msghdr structure should point to a buffer +that contains a +.Vt cmsghdr +structure followed by the +.Tn IP +address. +The cmsghdr fields should have the following values: +.Bd -literal +cmsg_len = CMSG_LEN(sizeof(struct in_addr)) +cmsg_level = IPPROTO_IP +cmsg_type = IP_SENDSRCADDR +.Ed +.Pp +The socket should be either bound to +.Dv INADDR_ANY +and a local port, and the address supplied with +.Dv IP_SENDSRCADDR +shouldn't be +.Dv INADDR_ANY , +or the socket should be bound to a local address and the address supplied with +.Dv IP_SENDSRCADDR +should be +.Dv INADDR_ANY . +In the latter case bound address is overridden via generic source address +selection logic, which would choose IP address of interface closest to +destination. +.Pp +For convenience, +.Dv IP_SENDSRCADDR +is defined to have the same value as +.Dv IP_RECVDSTADDR , +so the +.Dv IP_RECVDSTADDR +control message from +.Xr recvmsg 2 +can be used directly as a control message for +.Xr sendmsg 2 . +.\" +.Pp +If the +.Dv IP_ONESBCAST +option is enabled on a +.Dv SOCK_DGRAM +or a +.Dv SOCK_RAW +socket, the destination address of outgoing +broadcast datagrams on that socket will be forced +to the undirected broadcast address, +.Dv INADDR_BROADCAST , +before transmission. +This is in contrast to the default behavior of the +system, which is to transmit undirected broadcasts +via the first network interface with the +.Dv IFF_BROADCAST +flag set. +.Pp +This option allows applications to choose which +interface is used to transmit an undirected broadcast +datagram. +For example, the following code would force an +undirected broadcast to be transmitted via the interface +configured with the broadcast address 192.168.2.255: +.Bd -literal +char msg[512]; +struct sockaddr_in sin; +int onesbcast = 1; /* 0 = disable (default), 1 = enable */ + +setsockopt(s, IPPROTO_IP, IP_ONESBCAST, &onesbcast, sizeof(onesbcast)); +sin.sin_addr.s_addr = inet_addr("192.168.2.255"); +sin.sin_port = htons(1234); +sendto(s, msg, sizeof(msg), 0, &sin, sizeof(sin)); +.Ed +.Pp +It is the application's responsibility to set the +.Dv IP_TTL +option +to an appropriate value in order to prevent broadcast storms. +The application must have sufficient credentials to set the +.Dv SO_BROADCAST +socket level option, otherwise the +.Dv IP_ONESBCAST +option has no effect. +.Pp +If the +.Dv IP_BINDANY +option is enabled on a +.Dv SOCK_STREAM , +.Dv SOCK_DGRAM +or a +.Dv SOCK_RAW +socket, one can +.Xr bind 2 +to any address, even one not bound to any available network interface in the +system. +This functionality (in conjunction with special firewall rules) can be used for +implementing a transparent proxy. +The +.Dv PRIV_NETINET_BINDANY +privilege is needed to set this option. +.Pp +If the +.Dv IP_RECVTTL +option is enabled on a +.Dv SOCK_DGRAM +socket, the +.Xr recvmsg 2 +call will return the +.Tn IP +.Tn TTL +(time to live) field for a +.Tn UDP +datagram. +The msg_control field in the msghdr structure points to a buffer +that contains a cmsghdr structure followed by the +.Tn TTL . +The cmsghdr fields have the following values: +.Bd -literal +cmsg_len = CMSG_LEN(sizeof(u_char)) +cmsg_level = IPPROTO_IP +cmsg_type = IP_RECVTTL +.Ed +.\" +.Pp +If the +.Dv IP_RECVTOS +option is enabled on a +.Dv SOCK_DGRAM +socket, the +.Xr recvmsg 2 +call will return the +.Tn IP +.Tn TOS +(type of service) field for a +.Tn UDP +datagram. +The msg_control field in the msghdr structure points to a buffer +that contains a cmsghdr structure followed by the +.Tn TOS . +The cmsghdr fields have the following values: +.Bd -literal +cmsg_len = CMSG_LEN(sizeof(u_char)) +cmsg_level = IPPROTO_IP +cmsg_type = IP_RECVTOS +.Ed +.\" +.Pp +If the +.Dv IP_RECVIF +option is enabled on a +.Dv SOCK_DGRAM +socket, the +.Xr recvmsg 2 +call returns a +.Vt "struct sockaddr_dl" +corresponding to the interface on which the +packet was received. +The +.Va msg_control +field in the +.Vt msghdr +structure points to a buffer that contains a +.Vt cmsghdr +structure followed by the +.Vt "struct sockaddr_dl" . +The +.Vt cmsghdr +fields have the following values: +.Bd -literal +cmsg_len = CMSG_LEN(sizeof(struct sockaddr_dl)) +cmsg_level = IPPROTO_IP +cmsg_type = IP_RECVIF +.Ed +.Pp +.Dv IP_PORTRANGE +may be used to set the port range used for selecting a local port number +on a socket with an unspecified (zero) port number. +It has the following +possible values: +.Bl -tag -width IP_PORTRANGE_DEFAULT +.It Dv IP_PORTRANGE_DEFAULT +use the default range of values, normally +.Dv IPPORT_HIFIRSTAUTO +through +.Dv IPPORT_HILASTAUTO . +This is adjustable through the sysctl setting: +.Va net.inet.ip.portrange.first +and +.Va net.inet.ip.portrange.last . +.It Dv IP_PORTRANGE_HIGH +use a high range of values, normally +.Dv IPPORT_HIFIRSTAUTO +and +.Dv IPPORT_HILASTAUTO . +This is adjustable through the sysctl setting: +.Va net.inet.ip.portrange.hifirst +and +.Va net.inet.ip.portrange.hilast . +.It Dv IP_PORTRANGE_LOW +use a low range of ports, which are normally restricted to +privileged processes on +.Ux +systems. +The range is normally from +.Dv IPPORT_RESERVED +\- 1 down to +.Li IPPORT_RESERVEDSTART +in descending order. +This is adjustable through the sysctl setting: +.Va net.inet.ip.portrange.lowfirst +and +.Va net.inet.ip.portrange.lowlast . +.El +.Pp +The range of privileged ports which only may be opened by +root-owned processes may be modified by the +.Va net.inet.ip.portrange.reservedlow +and +.Va net.inet.ip.portrange.reservedhigh +sysctl settings. +The values default to the traditional range, +0 through +.Dv IPPORT_RESERVED +\- 1 +(0 through 1023), respectively. +Note that these settings do not affect and are not accounted for in the +use or calculation of the other +.Va net.inet.ip.portrange +values above. +Changing these values departs from +.Ux +tradition and has security +consequences that the administrator should carefully evaluate before +modifying these settings. +.Pp +Ports are allocated at random within the specified port range in order +to increase the difficulty of random spoofing attacks. +In scenarios such as benchmarking, this behavior may be undesirable. +In these cases, +.Va net.inet.ip.portrange.randomized +can be used to toggle randomization off. +.Ss "Multicast Options" +.Tn IP +multicasting is supported only on +.Dv AF_INET +sockets of type +.Dv SOCK_DGRAM +and +.Dv SOCK_RAW , +and only on networks where the interface +driver supports multicasting. +.Pp +The +.Dv IP_MULTICAST_TTL +option changes the time-to-live (TTL) +for outgoing multicast datagrams +in order to control the scope of the multicasts: +.Bd -literal +u_char ttl; /* range: 0 to 255, default = 1 */ +setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, &ttl, sizeof(ttl)); +.Ed +.Pp +Datagrams with a TTL of 1 are not forwarded beyond the local network. +Multicast datagrams with a TTL of 0 will not be transmitted on any network, +but may be delivered locally if the sending host belongs to the destination +group and if multicast loopback has not been disabled on the sending socket +(see below). +Multicast datagrams with TTL greater than 1 may be forwarded +to other networks if a multicast router is attached to the local network. +.Pp +For hosts with multiple interfaces, where an interface has not +been specified for a multicast group membership, +each multicast transmission is sent from the primary network interface. +The +.Dv IP_MULTICAST_IF +option overrides the default for +subsequent transmissions from a given socket: +.Bd -literal +struct in_addr addr; +setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, &addr, sizeof(addr)); +.Ed +.Pp +where "addr" is the local +.Tn IP +address of the desired interface or +.Dv INADDR_ANY +to specify the default interface. +.Pp +To specify an interface by index, an instance of +.Vt ip_mreqn +may be passed instead. +The +.Vt imr_ifindex +member should be set to the index of the desired interface, +or 0 to specify the default interface. +The kernel differentiates between these two structures by their size. +.Pp +The use of +.Vt IP_MULTICAST_IF +is +.Em not recommended , +as multicast memberships are scoped to each +individual interface. +It is supported for legacy use only by applications, +such as routing daemons, which expect to +be able to transmit link-local IPv4 multicast datagrams (224.0.0.0/24) +on multiple interfaces, +without requesting an individual membership for each interface. +.Pp +.\" +An interface's local IP address and multicast capability can +be obtained via the +.Dv SIOCGIFCONF +and +.Dv SIOCGIFFLAGS +ioctls. +Normal applications should not need to use this option. +.Pp +If a multicast datagram is sent to a group to which the sending host itself +belongs (on the outgoing interface), a copy of the datagram is, by default, +looped back by the IP layer for local delivery. +The +.Dv IP_MULTICAST_LOOP +option gives the sender explicit control +over whether or not subsequent datagrams are looped back: +.Bd -literal +u_char loop; /* 0 = disable, 1 = enable (default) */ +setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, &loop, sizeof(loop)); +.Ed +.Pp +This option +improves performance for applications that may have no more than one +instance on a single host (such as a routing daemon), by eliminating +the overhead of receiving their own transmissions. +It should generally not +be used by applications for which there may be more than one instance on a +single host (such as a conferencing program) or for which the sender does +not belong to the destination group (such as a time querying program). +.Pp +The sysctl setting +.Va net.inet.ip.mcast.loop +controls the default setting of the +.Dv IP_MULTICAST_LOOP +socket option for new sockets. +.Pp +A multicast datagram sent with an initial TTL greater than 1 may be delivered +to the sending host on a different interface from that on which it was sent, +if the host belongs to the destination group on that other interface. +The loopback control option has no effect on such delivery. +.Pp +A host must become a member of a multicast group before it can receive +datagrams sent to the group. +To join a multicast group, use the +.Dv IP_ADD_MEMBERSHIP +option: +.Bd -literal +struct ip_mreqn mreqn; +setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, &mreqn, sizeof(mreqn)); +.Ed +.Pp +where +.Fa mreqn +is the following structure: +.Bd -literal +struct ip_mreqn { + struct in_addr imr_multiaddr; /* IP multicast address of group */ + struct in_addr imr_address; /* local IP address of interface */ + int imr_ifindex; /* interface index */ +} +.Ed +.Pp +.Va imr_ifindex +should be set to the index of a particular multicast-capable interface if +the host is multihomed. +If +.Va imr_ifindex +is non-zero, value of +.Va imr_interface +is ignored. +Otherwise, if +.Va imr_ifindex +is 0, kernel will use IP address from +.Va imr_interface +to lookup the interface. +Value of +.Va imr_interface +may be set to +.Va INADDR_ANY +to choose the default interface, although this is not recommended; this is +considered to be the first interface corresponding to the default route. +Otherwise, the first multicast-capable interface configured in the system +will be used. +.Pp +Legacy +.Vt "struct ip_mreq" , +that lacks +.Va imr_ifindex +field is also supported by +.Dv IP_ADD_MEMBERSHIP +setsockopt. +In this case kernel would behave as if +.Va imr_ifindex +was set to zero: +.Va imr_interface +will be used to lookup interface. +.Pp +Prior to +.Fx 7.0 , +if the +.Va imr_interface +member is within the network range +.Li 0.0.0.0/8 , +it is treated as an interface index in the system interface MIB, +as per the RIP Version 2 MIB Extension (RFC-1724). +In versions of +.Fx +since 7.0, this behavior is no longer supported. +Developers should +instead use the RFC 3678 multicast source filter APIs; in particular, +.Dv MCAST_JOIN_GROUP . +.Pp +Up to +.Dv IP_MAX_MEMBERSHIPS +memberships may be added on a single socket. +Membership is associated with a single interface; +programs running on multihomed hosts may need to +join the same group on more than one interface. +.Pp +To drop a membership, use: +.Bd -literal +struct ip_mreq mreq; +setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, &mreq, sizeof(mreq)); +.Ed +.Pp +where +.Fa mreq +contains the same values as used to add the membership. +Memberships are dropped when the socket is closed or the process exits. +.\" TODO: Update this piece when IPv4 source-address selection is implemented. +.Pp +The IGMP protocol uses the primary IP address of the interface +as its identifier for group membership. +This is the first IP address configured on the interface. +If this address is removed or changed, the results are +undefined, as the IGMP membership state will then be inconsistent. +If multiple IP aliases are configured on the same interface, +they will be ignored. +.Pp +This shortcoming was addressed in IPv6; MLDv2 requires +that the unique link-local address for an interface is +used to identify an MLDv2 listener. +.Ss "Source-Specific Multicast Options" +Since +.Fx 8.0 , +the use of Source-Specific Multicast (SSM) is supported. +These extensions require an IGMPv3 multicast router in order to +make best use of them. +If a legacy multicast router is present on the link, +.Fx +will simply downgrade to the version of IGMP spoken by the router, +and the benefits of source filtering on the upstream link +will not be present, although the kernel will continue to +squelch transmissions from blocked sources. +.Pp +Each group membership on a socket now has a filter mode: +.Bl -tag -width MCAST_EXCLUDE +.It Dv MCAST_EXCLUDE +Datagrams sent to this group are accepted, +unless the source is in a list of blocked source addresses. +.It Dv MCAST_INCLUDE +Datagrams sent to this group are accepted +only if the source is in a list of accepted source addresses. +.El +.Pp +Groups joined using the legacy +.Dv IP_ADD_MEMBERSHIP +option are placed in exclusive-mode, +and are able to request that certain sources are blocked or allowed. +This is known as the +.Em delta-based API . +.Pp +To block a multicast source on an existing group membership: +.Bd -literal +struct ip_mreq_source mreqs; +setsockopt(s, IPPROTO_IP, IP_BLOCK_SOURCE, &mreqs, sizeof(mreqs)); +.Ed +.Pp +where +.Fa mreqs +is the following structure: +.Bd -literal +struct ip_mreq_source { + struct in_addr imr_multiaddr; /* IP multicast address of group */ + struct in_addr imr_sourceaddr; /* IP address of source */ + struct in_addr imr_interface; /* local IP address of interface */ +} +.Ed +.Va imr_sourceaddr +should be set to the address of the source to be blocked. +.Pp +To unblock a multicast source on an existing group: +.Bd -literal +struct ip_mreq_source mreqs; +setsockopt(s, IPPROTO_IP, IP_UNBLOCK_SOURCE, &mreqs, sizeof(mreqs)); +.Ed +.Pp +The +.Dv IP_BLOCK_SOURCE +and +.Dv IP_UNBLOCK_SOURCE +options are +.Em not permitted +for inclusive-mode group memberships. +.Pp +To join a multicast group in +.Dv MCAST_INCLUDE +mode with a single source, +or add another source to an existing inclusive-mode membership: +.Bd -literal +struct ip_mreq_source mreqs; +setsockopt(s, IPPROTO_IP, IP_ADD_SOURCE_MEMBERSHIP, &mreqs, sizeof(mreqs)); +.Ed +.Pp +To leave a single source from an existing group in inclusive mode: +.Bd -literal +struct ip_mreq_source mreqs; +setsockopt(s, IPPROTO_IP, IP_DROP_SOURCE_MEMBERSHIP, &mreqs, sizeof(mreqs)); +.Ed +If this is the last accepted source for the group, the membership +will be dropped. +.Pp +The +.Dv IP_ADD_SOURCE_MEMBERSHIP +and +.Dv IP_DROP_SOURCE_MEMBERSHIP +options are +.Em not accepted +for exclusive-mode group memberships. +However, both exclusive and inclusive mode memberships +support the use of the +.Em full-state API +documented in RFC 3678. +For management of source filter lists using this API, +please refer to +.Xr sourcefilter 3 . +.Pp +The sysctl settings +.Va net.inet.ip.mcast.maxsocksrc +and +.Va net.inet.ip.mcast.maxgrpsrc +are used to specify an upper limit on the number of per-socket and per-group +source filter entries which the kernel may allocate. +.\"----------------------- +.Ss "Raw IP Sockets" +Raw +.Tn IP +sockets are connectionless, +and are normally used with the +.Xr sendto 2 +and +.Xr recvfrom 2 +calls, though the +.Xr connect 2 +call may also be used to fix the destination for future +packets (in which case the +.Xr read 2 +or +.Xr recv 2 +and +.Xr write 2 +or +.Xr send 2 +system calls may be used). +.Pp +If +.Fa proto +is 0, the default protocol +.Dv IPPROTO_RAW +is used for outgoing +packets, and only incoming packets destined for that protocol +are received. +If +.Fa proto +is non-zero, that protocol number will be used on outgoing packets +and to filter incoming packets. +.Pp +Outgoing packets automatically have an +.Tn IP +header prepended to +them (based on the destination address and the protocol +number the socket is created with), +unless the +.Dv IP_HDRINCL +option has been set. +Unlike in previous +.Bx +releases, incoming packets are received with +.Tn IP +header and options intact, leaving all fields in network byte order. +.Pp +.Dv IP_HDRINCL +indicates the complete IP header is included with the data +and may be used only with the +.Dv SOCK_RAW +type. +.Bd -literal +#include +#include + +int hincl = 1; /* 1 = on, 0 = off */ +setsockopt(s, IPPROTO_IP, IP_HDRINCL, &hincl, sizeof(hincl)); +.Ed +.Pp +Unlike previous +.Bx +releases, the program must set all +the fields of the IP header, including the following: +.Bd -literal +ip->ip_v = IPVERSION; +ip->ip_hl = hlen >> 2; +ip->ip_id = 0; /* 0 means kernel set appropriate value */ +ip->ip_off = htons(offset); +ip->ip_len = htons(len); +.Ed +.Pp +The packet should be provided as is to be sent over wire. +This implies all fields, including +.Va ip_len +and +.Va ip_off +to be in network byte order. +See +.Xr byteorder 3 +for more information on network byte order. +If the +.Va ip_id +field is set to 0 then the kernel will choose an +appropriate value. +If the header source address is set to +.Dv INADDR_ANY , +the kernel will choose an appropriate address. +.Sh ERRORS +A socket operation may fail with one of the following errors returned: +.Bl -tag -width Er +.It Bq Er EISCONN +when trying to establish a connection on a socket which +already has one, or when trying to send a datagram with the destination +address specified and the socket is already connected; +.It Bq Er ENOTCONN +when trying to send a datagram, but +no destination address is specified, and the socket has not been +connected; +.It Bq Er ENOBUFS +when the system runs out of memory for +an internal data structure; +.It Bq Er EADDRNOTAVAIL +when an attempt is made to create a +socket with a network address for which no network interface +exists. +.It Bq Er EACCES +when an attempt is made to create +a raw IP socket by a non-privileged process. +.El +.Pp +The following errors specific to +.Tn IP +may occur when setting or getting +.Tn IP +options: +.Bl -tag -width Er +.It Bq Er EINVAL +An unknown socket option name was given. +.It Bq Er EINVAL +The IP option field was improperly formed; +an option field was shorter than the minimum value +or longer than the option buffer provided. +.El +.Pp +The following errors may occur when attempting to send +.Tn IP +datagrams via a +.Dq raw socket +with the +.Dv IP_HDRINCL +option set: +.Bl -tag -width Er +.It Bq Er EINVAL +The user-supplied +.Va ip_len +field was not equal to the length of the datagram written to the socket. +.El +.Sh SEE ALSO +.Xr getsockopt 2 , +.Xr recv 2 , +.Xr send 2 , +.Xr byteorder 3 , +.Xr CMSG_DATA 3 , +.Xr sourcefilter 3 , +.Xr icmp 4 , +.Xr igmp 4 , +.Xr inet 4 , +.Xr intro 4 , +.Xr multicast 4 +.Rs +.%A D. Thaler +.%A B. Fenner +.%A B. Quinn +.%T "Socket Interface Extensions for Multicast Source Filters" +.%N RFC 3678 +.%D Jan 2004 +.Re +.Sh HISTORY +The +.Nm +protocol appeared in +.Bx 4.2 . +The +.Vt ip_mreqn +structure appeared in +.Tn Linux 2.4 . +.Sh BUGS +Before +.Fx 10.0 +packets received on raw IP sockets had the +.Va ip_hl +subtracted from the +.Va ip_len +field. +.Pp +Before +.Fx 11.0 +packets received on raw IP sockets had the +.Va ip_len +and +.Va ip_off +fields converted to host byte order. +Packets written to raw IP sockets were expected to have +.Va ip_len +and +.Va ip_off +in host byte order. diff --git a/static/freebsd/man4/ip17x.4 b/static/freebsd/man4/ip17x.4 new file mode 100644 index 00000000..ac5c9890 --- /dev/null +++ b/static/freebsd/man4/ip17x.4 @@ -0,0 +1,42 @@ +.\" +.\" Copyright (c) 2025 Alexander Ziaee +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd May 18, 2025 +.Dt IP17X 4 +.Sh NAME +.Nm ip17x +.Nd IC Plus IP17x series Fast Ethernet switch driver +.Sh SYNOPSIS +.Cd device mdio +.Cd device etherswitch +.Cd device ip17x +.Sh DESCRIPTION +The +.Nm +driver supports the +IC Plus IP17X series Fast Ethernet switch controllers. +.Sh HARDWARE +The +.Nm +driver supports the following Fast Ethernet switch controllers: +.Pp +.Bl -bullet -compact +.It +IC Plus IP178C +.It +IC Plus IP175D +.It +IC Plus IP175C +.It +IC Plus IP175A +.El +.Sh SEE ALSO +.Xr etherswitch 4 , +.Xr etherswitchcfg 8 +.Sh HISTORY +The +.Nm +driver appeared in +.Fx 10.0 . diff --git a/static/freebsd/man4/ip6.4 b/static/freebsd/man4/ip6.4 new file mode 100644 index 00000000..ce756854 --- /dev/null +++ b/static/freebsd/man4/ip6.4 @@ -0,0 +1,731 @@ +.\" $KAME: ip6.4,v 1.23 2005/01/11 05:56:25 itojun Exp $ +.\" $OpenBSD: ip6.4,v 1.21 2005/01/06 03:50:46 itojun Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 24, 2022 +.Dt IP6 4 +.Os +.Sh NAME +.Nm ip6 +.Nd Internet Protocol version 6 (IPv6) network layer +.Sh SYNOPSIS +.In sys/socket.h +.In netinet/in.h +.Ft int +.Fn socket AF_INET6 SOCK_RAW proto +.Sh DESCRIPTION +The IPv6 network layer is used by the IPv6 protocol family for +transporting data. +IPv6 packets contain an IPv6 header that is not provided as part of the +payload contents when passed to an application. +IPv6 header options affect the behavior of this protocol and may be used +by high-level protocols (such as the +.Xr tcp 4 +and +.Xr udp 4 +protocols) as well as directly by +.Dq raw sockets , +which process IPv6 messages at a lower-level and may be useful for +developing new protocols and special-purpose applications. +.Ss Header +All IPv6 packets begin with an IPv6 header. +When data received by the kernel are passed to the application, this +header is not included in buffer, even when raw sockets are being used. +Likewise, when data are sent to the kernel for transmit from the +application, the buffer is not examined for an IPv6 header: +the kernel always constructs the header. +To directly access IPv6 headers from received packets and specify them +as part of the buffer passed to the kernel, link-level access +.Po +.Xr bpf 4 , +for example +.Pc +must instead be utilized. +.Pp +The header has the following definition: +.Bd -literal -offset indent +struct ip6_hdr { + union { + struct ip6_hdrctl { + uint32_t ip6_un1_flow; /* 20 bits of flow ID */ + uint16_t ip6_un1_plen; /* payload length */ + uint8_t ip6_un1_nxt; /* next header */ + uint8_t ip6_un1_hlim; /* hop limit */ + } ip6_un1; + uint8_t ip6_un2_vfc; /* version and class */ + } ip6_ctlun; + struct in6_addr ip6_src; /* source address */ + struct in6_addr ip6_dst; /* destination address */ +} __packed; + +#define ip6_vfc ip6_ctlun.ip6_un2_vfc +#define ip6_flow ip6_ctlun.ip6_un1.ip6_un1_flow +#define ip6_plen ip6_ctlun.ip6_un1.ip6_un1_plen +#define ip6_nxt ip6_ctlun.ip6_un1.ip6_un1_nxt +#define ip6_hlim ip6_ctlun.ip6_un1.ip6_un1_hlim +#define ip6_hops ip6_ctlun.ip6_un1.ip6_un1_hlim +.Ed +.Pp +All fields are in network-byte order. +Any options specified (see +.Sx Options +below) must also be specified in network-byte order. +.Pp +.Va ip6_flow +specifies the flow ID. +.Va ip6_plen +specifies the payload length. +.Va ip6_nxt +specifies the type of the next header. +.Va ip6_hlim +specifies the hop limit. +.Pp +The top 4 bits of +.Va ip6_vfc +specify the class and the bottom 4 bits specify the version. +.Pp +.Va ip6_src +and +.Va ip6_dst +specify the source and destination addresses. +.Pp +The IPv6 header may be followed by any number of extension headers that start +with the following generic definition: +.Bd -literal -offset indent +struct ip6_ext { + uint8_t ip6e_nxt; + uint8_t ip6e_len; +} __packed; +.Ed +.Ss Options +IPv6 allows header options on packets to manipulate the behavior of the +protocol. +These options and other control requests are accessed with the +.Xr getsockopt 2 +and +.Xr setsockopt 2 +system calls at level +.Dv IPPROTO_IPV6 +and by using ancillary data in +.Xr recvmsg 2 +and +.Xr sendmsg 2 . +They can be used to access most of the fields in the IPv6 header and +extension headers. +.Pp +The following socket options are supported: +.Bl -tag -width Ds +.\" .It Dv IPV6_OPTIONS +.It Dv IPV6_UNICAST_HOPS Fa "int *" +Get or set the default hop limit header field for outgoing unicast +datagrams sent on this socket. +.\" .It Dv IPV6_RECVOPTS Fa "int *" +.\" Get or set the status of whether all header options will be +.\" delivered along with the datagram when it is received. +.\" .It Dv IPV6_RECVRETOPTS Fa "int *" +.\" Get or set the status of whether header options will be delivered +.\" for reply. +.\" .It Dv IPV6_RECVDSTADDR Fa "int *" +.\" Get or set the status of whether datagrams are received with +.\" destination addresses. +.\" .It Dv IPV6_RETOPTS +.\" Get or set IPv6 options. +.It Dv IPV6_MULTICAST_IF Fa "u_int *" +Get or set the interface from which multicast packets will be sent. +For hosts with multiple interfaces, each multicast transmission is sent +from the primary network interface. +The interface is specified as its index as provided by +.Xr if_nametoindex 3 . +A value of zero specifies the default interface. +.It Dv IPV6_MULTICAST_HOPS Fa "int *" +Get or set the default hop limit header field for outgoing multicast +datagrams sent on this socket. +This option controls the scope of multicast datagram transmissions. +.Pp +Datagrams with a hop limit of 1 are not forwarded beyond the local +network. +Multicast datagrams with a hop limit of zero will not be transmitted on +any network but may be delivered locally if the sending host belongs to +the destination group and if multicast loopback (see below) has not been +disabled on the sending socket. +Multicast datagrams with a hop limit greater than 1 may be forwarded to +the other networks if a multicast router (such as +.Xr mrouted 8 Pq Pa ports/net/mrouted ) +is attached to the local network. +.It Dv IPV6_MULTICAST_LOOP Fa "u_int *" +Get or set the status of whether multicast datagrams will be looped back +for local delivery when a multicast datagram is sent to a group to which +the sending host belongs. +.Pp +This option improves performance for applications that may have no more +than one instance on a single host (such as a router daemon) by +eliminating the overhead of receiving their own transmissions. +It should generally not be used by applications for which there may be +more than one instance on a single host (such as a conferencing program) +or for which the sender does not belong to the destination group +(such as a time-querying program). +.Pp +A multicast datagram sent with an initial hop limit greater than 1 may +be delivered to the sending host on a different interface from that on +which it was sent if the host belongs to the destination group on that +other interface. +The multicast loopback control option has no effect on such delivery. +.It Dv IPV6_JOIN_GROUP Fa "struct ipv6_mreq *" +Join a multicast group. +A host must become a member of a multicast group before it can receive +datagrams sent to the group. +.Bd -literal +struct ipv6_mreq { + struct in6_addr ipv6mr_multiaddr; + unsigned int ipv6mr_interface; +}; +.Ed +.Pp +.Va ipv6mr_interface +may be set to zeroes to choose the default multicast interface or to the +index of a particular multicast-capable interface if the host is +multihomed. +Membership is associated with a single interface; programs running on +multihomed hosts may need to join the same group on more than one +interface. +.Pp +If the multicast address is unspecified (i.e., all zeroes), messages +from all multicast addresses will be accepted by this group. +Note that setting to this value requires superuser privileges. +.It Dv IPV6_LEAVE_GROUP Fa "struct ipv6_mreq *" +Drop membership from the associated multicast group. +Memberships are automatically dropped when the socket is closed or when +the process exits. +.It Dv IPV6_ORIGDSTADDR Fa "int *" +Get or set whether a datagram's original destination address and port are +returned as ancillary data along with the payload in subsequent +.Xr recvmsg 2 +calls. +The information is stored in the ancillary data as a +.Tn sockaddr_in6 +structure. +.It Dv IPV6_PORTRANGE Fa "int *" +Get or set the allocation policy of ephemeral ports for when the kernel +automatically binds a local address to this socket. +The following values are available: +.Pp +.Bl -tag -width IPV6_PORTRANGE_DEFAULT -compact +.It Dv IPV6_PORTRANGE_DEFAULT +Use the regular range of non-reserved ports (varies, see +.Xr ip 4 ) . +.It Dv IPV6_PORTRANGE_HIGH +Use a high range (varies, see +.Xr ip 4 ) . +.It Dv IPV6_PORTRANGE_LOW +Use a low, reserved range (600\-1023, see +.Xr ip 4 ) . +.El +.It Dv IPV6_PKTINFO Fa "int *" +Get or set whether additional information about subsequent packets will +be provided as ancillary data along with the payload in subsequent +.Xr recvmsg 2 +calls. +The information is stored in the following structure in the ancillary +data returned: +.Bd -literal +struct in6_pktinfo { + struct in6_addr ipi6_addr; /* src/dst IPv6 address */ + unsigned int ipi6_ifindex; /* send/recv if index */ +}; +.Ed +.It Dv IPV6_HOPLIMIT Fa "int *" +Get or set whether the hop limit header field from subsequent packets +will be provided as ancillary data along with the payload in subsequent +.Xr recvmsg 2 +calls. +The value is stored as an +.Vt int +in the ancillary data returned. +.\" .It Dv IPV6_NEXTHOP Fa "int *" +.\" Get or set whether the address of the next hop for subsequent +.\" packets will be provided as ancillary data along with the payload in +.\" subsequent +.\" .Xr recvmsg 2 +.\" calls. +.\" The option is stored as a +.\" .Vt sockaddr +.\" structure in the ancillary data returned. +.\" .Pp +.\" This option requires superuser privileges. +.It Dv IPV6_HOPOPTS Fa "int *" +Get or set whether the hop-by-hop options from subsequent packets will be +provided as ancillary data along with the payload in subsequent +.Xr recvmsg 2 +calls. +The option is stored in the following structure in the ancillary data +returned: +.Bd -literal +struct ip6_hbh { + uint8_t ip6h_nxt; /* next header */ + uint8_t ip6h_len; /* length in units of 8 octets */ +/* followed by options */ +} __packed; +.Ed +.Pp +The +.Fn inet6_opt_init +routine and family of routines may be used to manipulate this data. +.Pp +This option requires superuser privileges. +.It Dv IPV6_DSTOPTS Fa "int *" +Get or set whether the destination options from subsequent packets will +be provided as ancillary data along with the payload in subsequent +.Xr recvmsg 2 +calls. +The option is stored in the following structure in the ancillary data +returned: +.Bd -literal +struct ip6_dest { + uint8_t ip6d_nxt; /* next header */ + uint8_t ip6d_len; /* length in units of 8 octets */ +/* followed by options */ +} __packed; +.Ed +.Pp +The +.Fn inet6_opt_init +routine and family of routines may be used to manipulate this data. +.Pp +This option requires superuser privileges. +.It Dv IPV6_TCLASS Fa "int *" +Get or set the value of the traffic class field used for outgoing datagrams +on this socket. +The value must be between \-1 and 255. +A value of \-1 resets to the default value. +.It Dv IPV6_RECVTCLASS Fa "int *" +Get or set the status of whether the traffic class header field will be +provided as ancillary data along with the payload in subsequent +.Xr recvmsg 2 +calls. +The header field is stored as a single value of type +.Vt int . +.It Dv IPV6_RTHDR Fa "int *" +Get or set whether the routing header from subsequent packets will be +provided as ancillary data along with the payload in subsequent +.Xr recvmsg 2 +calls. +The header is stored in the following structure in the ancillary data +returned: +.Bd -literal +struct ip6_rthdr { + uint8_t ip6r_nxt; /* next header */ + uint8_t ip6r_len; /* length in units of 8 octets */ + uint8_t ip6r_type; /* routing type */ + uint8_t ip6r_segleft; /* segments left */ +/* followed by routing-type-specific data */ +} __packed; +.Ed +.Pp +The +.Fn inet6_opt_init +routine and family of routines may be used to manipulate this data. +.Pp +This option requires superuser privileges. +.It Dv IPV6_PKTOPTIONS Fa "struct cmsghdr *" +Get or set all header options and extension headers at one time on the +last packet sent or received on the socket. +All options must fit within the size of an mbuf (see +.Xr mbuf 9 ) . +Options are specified as a series of +.Vt cmsghdr +structures followed by corresponding values. +.Va cmsg_level +is set to +.Dv IPPROTO_IPV6 , +.Va cmsg_type +to one of the other values in this list, and trailing data to the option +value. +When setting options, if the length +.Va optlen +to +.Xr setsockopt 2 +is zero, all header options will be reset to their default values. +Otherwise, the length should specify the size the series of control +messages consumes. +.Pp +Instead of using +.Xr sendmsg 2 +to specify option values, the ancillary data used in these calls that +correspond to the desired header options may be directly specified as +the control message in the series of control messages provided as the +argument to +.Xr setsockopt 2 . +.It Dv IPV6_CHECKSUM Fa "int *" +Get or set the byte offset into a packet where the 16-bit checksum is +located. +When set, this byte offset is where incoming packets will be expected +to have checksums of their data stored and where outgoing packets will +have checksums of their data computed and stored by the kernel. +A value of \-1 specifies that no checksums will be checked on incoming +packets and that no checksums will be computed or stored on outgoing +packets. +The offset of the checksum for ICMPv6 sockets cannot be relocated or +turned off. +.It Dv IPV6_V6ONLY Fa "int *" +Get or set whether only IPv6 connections can be made to this socket. +For wildcard sockets, this can restrict connections to IPv6 only. +.\"With +.\".Ox +.\"IPv6 sockets are always IPv6-only, so the socket option is read-only +.\"(not modifiable). +.It Dv IPV6_USE_MIN_MTU Fa "int *" +Get or set whether the minimal IPv6 maximum transmission unit (MTU) size +will be used to avoid fragmentation from occurring for subsequent +outgoing datagrams. +.It Dv IPV6_AUTH_LEVEL Fa "int *" +Get or set the +.Xr ipsec 4 +authentication level. +.It Dv IPV6_ESP_TRANS_LEVEL Fa "int *" +Get or set the ESP transport level. +.It Dv IPV6_ESP_NETWORK_LEVEL Fa "int *" +Get or set the ESP encapsulation level. +.It Dv IPV6_IPCOMP_LEVEL Fa "int *" +Get or set the +.Xr ipcomp 4 +level. +.El +.Pp +The +.Dv IPV6_PKTINFO , +.\" .Dv IPV6_NEXTHOP , +.Dv IPV6_HOPLIMIT , +.Dv IPV6_HOPOPTS , +.Dv IPV6_DSTOPTS , +.Dv IPV6_RTHDR , +and +.Dv IPV6_ORIGDSTADDR +options will return ancillary data along with payload contents in subsequent +.Xr recvmsg 2 +calls with +.Va cmsg_level +set to +.Dv IPPROTO_IPV6 +and +.Va cmsg_type +set to respective option name value (e.g., +.Dv IPV6_HOPTLIMIT ) . +Some of these options may also be used directly as ancillary +.Va cmsg_type +values in +.Xr sendmsg 2 +to set options on the packet being transmitted by the call. +The +.Va cmsg_level +value must be +.Dv IPPROTO_IPV6 . +For these options, the ancillary data object value format is the same +as the value returned as explained for each when received with +.Xr recvmsg 2 . +.Pp +Note that using +.Xr sendmsg 2 +to specify options on particular packets works only on UDP and raw sockets. +To manipulate header options for packets on TCP sockets, only the socket +options may be used. +.Pp +In some cases, there are multiple APIs defined for manipulating an IPv6 +header field. +A good example is the outgoing interface for multicast datagrams, which +can be set by the +.Dv IPV6_MULTICAST_IF +socket option, through the +.Dv IPV6_PKTINFO +option, and through the +.Va sin6_scope_id +field of the socket address passed to the +.Xr sendto 2 +system call. +.Pp +Resolving these conflicts is implementation dependent. +This implementation determines the value in the following way: +options specified by using ancillary data (i.e., +.Xr sendmsg 2 ) +are considered first, +options specified by using +.Dv IPV6_PKTOPTIONS +to set +.Dq sticky +options are considered second, +options specified by using the individual, basic, and direct socket +options (e.g., +.Dv IPV6_UNICAST_HOPS ) +are considered third, +and options specified in the socket address supplied to +.Xr sendto 2 +are the last choice. +.Ss Multicasting +IPv6 multicasting is supported only on +.Dv AF_INET6 +sockets of type +.Dv SOCK_DGRAM +and +.Dv SOCK_RAW , +and only on networks where the interface driver supports +multicasting. +Socket options (see above) that manipulate membership of +multicast groups and other multicast options include +.Dv IPV6_MULTICAST_IF , +.Dv IPV6_MULTICAST_HOPS , +.Dv IPV6_MULTICAST_LOOP , +.Dv IPV6_LEAVE_GROUP , +and +.Dv IPV6_JOIN_GROUP . +.Ss Raw Sockets +Raw IPv6 sockets are connectionless and are normally used with the +.Xr sendto 2 +and +.Xr recvfrom 2 +calls, although the +.Xr connect 2 +call may be used to fix the destination address for future outgoing +packets so that +.Xr send 2 +may instead be used and the +.Xr bind 2 +call may be used to fix the source address for future outgoing +packets instead of having the kernel choose a source address. +.Pp +By using +.Xr connect 2 +or +.Xr bind 2 , +raw socket input is constrained to only packets with their +source address matching the socket destination address if +.Xr connect 2 +was used and to packets with their destination address +matching the socket source address if +.Xr bind 2 +was used. +.Pp +If the +.Ar proto +argument to +.Xr socket 2 +is zero, the default protocol +.Pq Dv IPPROTO_RAW +is used for outgoing packets. +For incoming packets, protocols recognized by kernel are +.Sy not +passed to the application socket (e.g., +.Xr tcp 4 +and +.Xr udp 4 ) +except for some ICMPv6 messages. +The ICMPv6 messages not passed to raw sockets include echo, timestamp, +and address mask requests. +If +.Ar proto +is non-zero, only packets with this protocol will be passed to the +socket. +.Pp +IPv6 fragments are also not passed to application sockets until +they have been reassembled. +If reception of all packets is desired, link-level access (such as +.Xr bpf 4 ) +must be used instead. +.Pp +Outgoing packets automatically have an IPv6 header prepended to them +(based on the destination address and the protocol number the socket +was created with). +Incoming packets are received by an application without the IPv6 header +or any extension headers. +.Pp +Outgoing packets will be fragmented automatically by the kernel if they +are too large. +Incoming packets will be reassembled before being sent to the raw socket, +so packet fragments or fragment headers will never be seen on a raw socket. +.Sh EXAMPLES +The following determines the hop limit on the next packet received: +.Bd -literal +struct iovec iov[2]; +u_char buf[BUFSIZ]; +struct cmsghdr *cm; +struct msghdr m; +int optval; +bool found; +u_char data[2048]; + +/* Create socket. */ + +(void)memset(&m, 0, sizeof(m)); +(void)memset(&iov, 0, sizeof(iov)); + +iov[0].iov_base = data; /* buffer for packet payload */ +iov[0].iov_len = sizeof(data); /* expected packet length */ + +m.msg_name = &from; /* sockaddr_in6 of peer */ +m.msg_namelen = sizeof(from); +m.msg_iov = iov; +m.msg_iovlen = 1; +m.msg_control = (caddr_t)buf; /* buffer for control messages */ +m.msg_controllen = sizeof(buf); + +/* + * Enable the hop limit value from received packets to be + * returned along with the payload. + */ +optval = 1; +if (setsockopt(s, IPPROTO_IPV6, IPV6_HOPLIMIT, &optval, + sizeof(optval)) == -1) + err(1, "setsockopt"); + +found = false; +do { + if (recvmsg(s, &m, 0) == -1) + err(1, "recvmsg"); + for (cm = CMSG_FIRSTHDR(&m); cm != NULL; + cm = CMSG_NXTHDR(&m, cm)) { + if (cm->cmsg_level == IPPROTO_IPV6 && + cm->cmsg_type == IPV6_HOPLIMIT && + cm->cmsg_len == CMSG_LEN(sizeof(int))) { + found = true; + (void)printf("hop limit: %d\en", + *(int *)CMSG_DATA(cm)); + break; + } + } +} while (!found); +.Ed +.Sh DIAGNOSTICS +A socket operation may fail with one of the following errors returned: +.Bl -tag -width EADDRNOTAVAILxx +.It Bq Er EISCONN +when trying to establish a connection on a socket which +already has one or when trying to send a datagram with the destination +address specified and the socket is already connected. +.It Bq Er ENOTCONN +when trying to send a datagram, but +no destination address is specified, and the socket has not been +connected. +.It Bq Er ENOBUFS +when the system runs out of memory for +an internal data structure. +.It Bq Er EADDRNOTAVAIL +when an attempt is made to create a +socket with a network address for which no network interface +exists. +.It Bq Er EACCES +when an attempt is made to create +a raw IPv6 socket by a non-privileged process. +.El +.Pp +The following errors specific to IPv6 may occur when setting or getting +header options: +.Bl -tag -width EADDRNOTAVAILxx +.It Bq Er EINVAL +An unknown socket option name was given. +.It Bq Er EINVAL +An ancillary data object was improperly formed. +.El +.Sh SEE ALSO +.Xr getsockopt 2 , +.Xr recv 2 , +.Xr send 2 , +.Xr setsockopt 2 , +.Xr socket 2 , +.Xr CMSG_DATA 3 , +.Xr if_nametoindex 3 , +.Xr inet6_opt_init 3 , +.Xr bpf 4 , +.Xr icmp6 4 , +.Xr inet6 4 , +.Xr ip 4 , +.Xr netintro 4 , +.Xr tcp 4 , +.Xr udp 4 +.Rs +.%A W. Stevens +.%A M. Thomas +.%T Advanced Sockets API for IPv6 +.%R RFC 2292 +.%D February 1998 +.Re +.Rs +.%A S. Deering +.%A R. Hinden +.%T Internet Protocol, Version 6 (IPv6) Specification +.%R RFC 2460 +.%D December 1998 +.Re +.Rs +.%A R. Gilligan +.%A S. Thomson +.%A J. Bound +.%A W. Stevens +.%T Basic Socket Interface Extensions for IPv6 +.%R RFC 2553 +.%D March 1999 +.Re +.Rs +.%A R. Gilligan +.%A S. Thomson +.%A J. Bound +.%A J. McCann +.%A W. Stevens +.%T Basic Socket Interface Extensions for IPv6 +.%R RFC 3493 +.%D February 2003 +.Re +.Rs +.%A W. Stevens +.%A M. Thomas +.%A E. Nordmark +.%A T. Jinmei +.%T Advanced Sockets Application Program Interface (API) for IPv6 +.%R RFC 3542 +.%D May 2003 +.Re +.Rs +.%A S. Deering +.%A R. Hinden +.%T Internet Protocol, Version 6 (IPv6) Specification +.%R RFC 8200 +.%D July 2017 +.Re +.Rs +.%A W. Stevens +.%A B. Fenner +.%A A. Rudoff +.%T UNIX Network Programming, 3rd Edition +.%I Addison-Wesley Professional +.%D November 2003 +.Re +.Sh STANDARDS +Most of the socket options are defined in RFC 2292 / 3542 or +RFC 2553 / 3493. +The +.Dv IPV6_PORTRANGE +socket option and the conflict resolution rule are not defined in the +RFCs and should be considered implementation dependent. diff --git a/static/freebsd/man4/ipfirewall.4 b/static/freebsd/man4/ipfirewall.4 new file mode 100644 index 00000000..691ed3d3 --- /dev/null +++ b/static/freebsd/man4/ipfirewall.4 @@ -0,0 +1,160 @@ +.\" +.Dd August 19, 2020 +.Dt IPFW 4 +.Os +.Sh NAME +.Nm ipfw +.Nd IP packet filter and traffic accounting +.Sh SYNOPSIS +To compile +the driver +into the kernel, place the following option in the kernel configuration +file: +.Bd -ragged -offset indent +.Cd "options IPFIREWALL" +.Ed +.Pp +Other related kernel options +which may also be useful are: +.Bd -ragged -offset indent +.Cd "options IPFIREWALL_DEFAULT_TO_ACCEPT" +.Cd "options IPDIVERT" +.Cd "options IPFIREWALL_NAT" +.Cd "options IPFIREWALL_NAT64" +.Cd "options IPFIREWALL_NPTV6" +.Cd "options IPFIREWALL_PMOD" +.Cd "options IPFIREWALL_VERBOSE" +.Cd "options IPFIREWALL_VERBOSE_LIMIT=100" +.Cd "options LIBALIAS" +.Ed +.Pp +To load +the driver +as a module at boot time, add the following line into the +.Xr loader.conf 5 +file: +.Bd -literal -offset indent +ipfw_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +system facility allows filtering, +redirecting, and other operations on +.Tn IP +packets travelling through +network interfaces. +.Pp +The default behavior of +.Nm +is to block all incoming and outgoing traffic. +This behavior can be modified, to allow all traffic through the +.Nm +firewall by default, by enabling the +.Dv IPFIREWALL_DEFAULT_TO_ACCEPT +kernel option. +This option may be useful when configuring +.Nm +for the first time. +If the default +.Nm +behavior is to allow everything, it is easier to cope with +firewall-tuning mistakes which may accidentally block all traffic. +.Pp +When using +.Xr natd 8 +in conjunction with +.Nm +as +.Tn NAT +facility, the kernel option +.Dv IPDIVERT +enables diverting packets to +.Xr natd 8 +for translation. +.Pp +When using the in-kernel +.Tn NAT +facility of +.Nm , +the kernel option +.Dv IPFIREWALL_NAT +enables basic +.Xr libalias 3 +functionality in the kernel. +.Pp +When using any of the +.Tn IPv4 +to +.Tn IPv6 +transition mechanisms in +.Nm , +the kernel option +.Dv IPFIREWALL_NAT64 +enables all of these +.Tn NAT64 +methods in the kernel. +.Pp +When using the +.Tn IPv6 +network prefix translation facility of +.Nm , +the kernel option +.Dv IPFIREWALL_NPTV6 +enables this functionality in the kernel. +.Pp +When using the packet modification facility of +.Nm , +the kernel option +.Dv IPFIREWALL_PMOD +enables this functionality in the kernel. +.Pp +To enable logging of packets passing through +.Nm , +enable the +.Dv IPFIREWALL_VERBOSE +kernel option. +The +.Dv IPFIREWALL_VERBOSE_LIMIT +option will prevent +.Xr syslogd 8 +from flooding system logs or causing local Denial of Service. +This option may be set to the number of packets which will be logged on +a per-entry basis before the entry is rate-limited. +.Pp +When using the in-kernel +.Tn NAT +facility of +.Nm , +the kernel option +.Dv LIBALIAS +enables full +.Xr libalias 3 +functionality in the kernel. +Full functionality refers to included support for ftp, bbt, +skinny, irc, pptp and smedia packets, which are missing in the basic +.Xr libalias 3 +functionality accomplished with the +.Dv IPFIREWALL_NAT +kernel option. +.Pp +The user interface for +.Nm +is implemented by the +.Xr ipfw 8 +utility, so please refer to the +.Xr ipfw 8 +man page for a complete description of the +.Nm +capabilities and how to use it. +.Sh SEE ALSO +.Xr setsockopt 2 , +.Xr libalias 3 , +.Xr divert 4 , +.Xr ip 4 , +.Xr ip6 4 , +.Xr ipfw 8 , +.Xr natd 8 , +.Xr sysctl 8 , +.Xr syslogd 8 , +.Xr pfil 9 diff --git a/static/freebsd/man4/ipheth.4 b/static/freebsd/man4/ipheth.4 new file mode 100644 index 00000000..85726dd6 --- /dev/null +++ b/static/freebsd/man4/ipheth.4 @@ -0,0 +1,185 @@ +.\" Copyright (c) 2014 Gavin Atkinson +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" - Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" - 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 COPYRIGHT HOLDERS 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 +.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN +.\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 29, 2022 +.Dt IPHETH 4 +.Os +.Sh NAME +.Nm ipheth +.Nd "USB Apple iPhone/iPad tethered Ethernet driver" +.Sh SYNOPSIS +To load the driver as a module at boot time, place the +following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_ipheth_load="YES" +.Ed +.Pp +Alternatively, to compile this driver into the kernel, place the +following lines in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device uhci" +.Cd "device ohci" +.Cd "device usb" +.Cd "device miibus" +.Cd "device uether" +.Cd "device ipheth" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for network access through Apple +iPhone and iPad devices, often referred to as USB tethering. +.Pp +.Nm +should work with any Apple iPhone or iPad device. +In most cases this must be explicitly enabled on the device first. +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +The device does not support different media types or options. +.Sh HARDWARE +The following devices are supported by the +.Nm +driver: +.Pp +.Bl -bullet -compact +.It +Apple iPhone tethering (all models) +.It +Apple iPad tethering (all models) +.El +.Sh EXAMPLES +.Bl -tag -width 0n +.It Sy Example 1\&: No Manual Configuration +.Pp +The following example shows how to manually configure network access on a +device that is not automatically recognized. +.Pp +First, load the driver and find out the unit and the address of the USB +Apple +device: +.Bd -literal -offset 2n +.Li # Ic kldload ipheth +.Li # Ic usbconfig | grep Apple +ugen0.2: at usbus0, cfg=0 md=HOST spd=HIGH (480Mbps) pwr=ON (500mA) +.Ed +.Pp +In this example, the unit and the address of the device is 0.2 +.Pq Dq Li ugen0.2 , +and its configuration index is 0 +.Pq Dq Li cfg=0 . +.Pp +Secondly, check what other configurations are available for the device: +.Bd -literal -offset 2n +.Li # Ic usbconfig -d 0.2 dump_all_config_desc | grep -E '(^ Conf|iConf)' + Configuration index 0 + iConfiguration = 0x0005 + Configuration index 1 + iConfiguration = 0x0006 + Configuration index 2 + iConfiguration = 0x0007 + Configuration index 3 + iConfiguration = 0x0008 +.Ed +.Pp +In this example, there are 4 different configurations available. +The configuration with index 3 seems to be related to Ethernet. +It is time to configure the device: +.Bd -literal -offset 2n +.Li # Ic usbconfig -d 0.2 set_config 3 +.Li # Ic usbconfig | grep 'Apple.*cfg=3' +ugen0.2: at usbus0, cfg=3 md=HOST spd=HIGH (480Mbps) pwr=ON (500mA) +.Ed +.Pp +At this point the Apple device should ask whether the +.Fx +machine can be trusted +.Po Dq Mobile Data +has to be on +.Pc . +.Pp +A new +.Em ue +USB Ethernet interface should become available: +.Bd -literal -offset 2n +.Li # Ic dmesg | grep 'ue[0-9]' +ue0: on ipheth0 +ue0: bpf attached +ue0: Ethernet address: 4e:7c:5f:2c:5f:7a +.Ed +.Pp +At this point it might be necessary to run +.Xr usbmuxd 1 +.Po available in +.Xr ports 7 +at +.Pa comms/usbmuxd +.Pc : +.Bd -literal -offset 2n +.Li # Ic usbmuxd --enable-exit --foreground --user root --verbose +.Ed +.Pp +Now it is time to configure the network interface: +.Bd -literal -offset 2n +.Li # Ic sysrc ifconfig_ue0="SYNCDHCP" +ifconfig_ue0: -> SYNCDHCP +.Li # Ic service netif restart ue0 +.Ed +.Pp +That is it. +The machine should now be connected to the network via USB tethering. +.El +.Sh SEE ALSO +.Xr arp 4 , +.Xr cdce 4 , +.Xr cdceem 4 , +.Xr intro 4 , +.Xr netintro 4 , +.Xr urndis 4 , +.Xr usb 4 , +.Xr ifconfig 8 , +.Xr usbconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 8.2 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Hans Petter Selasky Aq Mt hselasky@FreeBSD.org . +.Sh BUGS +Some devices are not recognized automatically and may need to be manually +configured to use an alternative configuration with the +.Xr usbconfig 8 +utility. +See +.Sx EXAMPLES +for workarounds. diff --git a/static/freebsd/man4/ipmi.4 b/static/freebsd/man4/ipmi.4 new file mode 100644 index 00000000..0d2e32c0 --- /dev/null +++ b/static/freebsd/man4/ipmi.4 @@ -0,0 +1,212 @@ +.\" +.\" Copyright (c) 2006 Tom Rhodes +.\" 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 October 25, 2017 +.Dt IPMI 4 +.Os +.Sh NAME +.Nm ipmi +.Nd "OpenIPMI compatible IPMI interface driver" +.Sh SYNOPSIS +.Cd "device ipmi" +.Pp +To manually specify I/O attachment in +.Pa /boot/device.hints : +.Cd hint.ipmi.0.at="isa" +.Cd hint.ipmi.0.port="0xCA2" +.Cd hint.ipmi.0.spacing="8" +.Cd hint.ipmi.0.mode="KCS" +.Pp +To manually specify memory attachment in +.Pa /boot/device.hints : +.Cd hint.ipmi.0.at="isa" +.Cd hint.ipmi.0.maddr="0xf0000000" +.Cd hint.ipmi.0.spacing="8" +.Cd hint.ipmi.0.mode="SMIC" +.Pp +Meaning of +.Ar spacing : +.Bl -tag -offset indent -compact -width 0x0 +.It 8 +8 bit alignment +.It 16 +16 bit alignment +.It 32 +32 bit alignment +.El +.Pp +If the +.Ar port +and +.Ar spacing +are not specified the interface type default will be used. +Only specify either the +.Ar port +for I/O access or +.Ar maddr +for memory access. +.Sh DESCRIPTION +The +.Tn IPMI +(Intelligent Platform Management Interface) is a standard for +monitoring system hardware by permitting generic code to detect +and monitor the sensors in a system. +The +.Tn IPMI +standard offers watchdog support, an FRU database, and other +support extensions. +It is currently being adopted by the makers of many +single board and embedded system manufacturers. +.Pp +The +.Nm +driver in +.Fx +is heavily adopted from the standard and +.Tn Linux +driver; however, not all features described in the +standard are supported. +.Pp +The +.Nm +driver implements the power cycling option to +.Xr shutdown 8 +to implement power cycling of the system. +The motherboard's BMC must support the chassis device and the optional +power cycle subcomand of the chassis control command as described in section 28.3 +of the IPMI standard. +The length of time the system is off will be at least one second, but +may be longer if the power cycle interval has been set (see section 28.9). +.Sh IOCTLS +Sending and receiving messages through the +.Nm +driver requires the use of +.Xr ioctl 2 . +The ioctls are used due to the complexity of +data sent to and from the device. +The +.Xr ioctl 2 +command codes below are defined in +.In sys/ipmi.h . +The third argument to +.Xr ioctl 2 +should be a pointer to the type indicated. +.Pp +Currently the following ioctls are supported: +.Bl -tag -width indent +.It Dv IPMICTL_RECEIVE_MSG Pq Vt "struct ipmi_recv" +Receive a message. +Possible error values: +.Bl -tag -width Er +.It Bq Er EAGAIN +No messages are in the process queue. +.It Bq Er EFAULT +An address supplied was invalid. +.It Bq Er EMSGSIZE +The address could not fit in the message buffer and +will remain in the buffer. +.El +.It Dv IPMICTL_RECEIVE_MSG_TRUNC Pq Vt "struct ipmi_recv" +Like +.Dv IPMICTL_RECEIVE_MSG +but if the message cannot fit into the buffer, it +will truncate the contents instead of leaving the data +in the buffer. +.It Dv IPMICTL_SEND_COMMAND Pq Vt "struct ipmi_req" +Send a message to the interface. +Possible error values: +.Bl -tag -width Er +.It Bq Er EFAULT +An address supplied was invalid. +.It Bq Er ENOMEM +Buffers could not be allowed for the command, out of memory. +.El +.It Dv IPMICTL_SET_MY_ADDRESS_CMD Pq Vt "unsigned int" +Set the slave address for source messages. +.It Dv IPMICTL_GET_MY_ADDRESS_CMD Pq Vt "unsigned int" +Get the slave address for source messages. +.It Dv IPMICTL_SET_MY_LUN_CMD Pq Vt "unsigned int" +Set the slave LUN for source messages. +.It Dv IPMICTL_GET_MY_LUN_CMD Pq Vt "unsigned int" +Get the slave LUN for source messages. +.El +.Ss Unimplemented Ioctls +.Bl -tag -width indent +.It Dv IPMICTL_REGISTER_FOR_CMD Pq Vt "struct ipmi_cmdspec" +Register to receive a specific command. +Possible error values: +.Bl -tag -width Er +.It Bq Er EFAULT +An supplied address was invalid. +.It Bq Er EBUSY +The network function/command is already in use. +.It Bq Er ENOMEM +Could not allocate memory. +.El +.It Dv IPMICTL_UNREGISTER_FOR_CMD Pq Vt "struct ipmi_cmdspec" +Unregister to receive a specific command. +Possible error values: +.Bl -tag -width Er +.It Bq Er EFAULT +An address supplied was invalid. +.It Bq Er ENOENT +The network function/command was not found. +.El +.El +.Ss Stub Only Ioctl +.Bl -tag -width indent +.It Dv IPMICTL_SET_GETS_EVENTS_CMD Pq Vt int +Set whether this interface receives events. +Possible error values: +.Bl -tag -width Er +.It Bq Er EFAULT +An address supplied was invalid. +.El +.El +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr watchdog 4 , +.Xr reboot 8 , +.Xr shutdown 8 , +.Xr watchdog 8 , +.Xr watchdogd 8 , +.Xr watchdog 9 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 6.2 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Doug Ambrisko Aq Mt ambrisko@FreeBSD.org . +This manual page was written by +.An Tom Rhodes Aq Mt trhodes@FreeBSD.org . +.Sh BUGS +Not all features of the MontaVista driver are supported. +.Pp +Currently, IPMB and BT modes are not implemented. diff --git a/static/freebsd/man4/ips.4 b/static/freebsd/man4/ips.4 new file mode 100644 index 00000000..134e87df --- /dev/null +++ b/static/freebsd/man4/ips.4 @@ -0,0 +1,202 @@ +.\" +.\" Copyright (c) 2003 Tom Rhodes +.\" 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 August 7, 2009 +.Dt IPS 4 +.Os +.Sh NAME +.Nm ips +.Nd IBM/Adaptec ServeRAID controller driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device pci" +.Cd "device scbus" +.Cd "device ips" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ips_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver claims to support the +.Tn IBM +(now Adaptec) ServeRAID series +.Tn SCSI +controller cards. +.Pp +These cards come with a built in configuration utility stored in +the firmware known as the +.Tn ISPR . +This utility is accessed with the +.Aq Em Ctrl+I +key combination during the initial card +.Tn POST . +.Pp +It is highly recommended that this utility be used to configure the card +before attempting to diagnose the below error messages. +.Pp +In some cases, the +.Nm +driver can have difficulties attaching during +the system initialization period. +To avoid these difficulties, set the +.Va hw.ips.0.disable +tunable to 1. +It will prevent the driver from attaching. +.Sh HARDWARE +Controllers supported by the +.Nm +driver include: +.Pp +.Bl -bullet -compact +.It +IBM ServeRAID 3H +.It +ServeRAID 4L/4M/4H +.It +ServeRAID Series 5 +.It +ServeRAID 6i/6M +.It +ServeRAID 7t/7k/7M +.El +.Pp +Newer ServeRAID controllers are supported by the +.Xr aac 4 +or +.Xr mfi 4 +driver. +.Sh DIAGNOSTICS +Several error codes may be shown when the card initializes the +.Tn IBM +.Tn ISPR +utility and are independent of +.Fx . +.Bl -diag +.It ips%d: failed to get adapter configuration data from device +.It ips%d: failed to get drive configuration data from device +.Pp +Unable to obtain adapter or drive configuration. +.It ips%d iobuf error +.Pp +A buffer input/output error has occurred. +.Bq Er ENXIO +.El +.Ss General adapter errors : +.Bl -diag +.It Attaching bus failed +.Pp +This message is undocumented. +.It WARNING: command timeout. Adapter is in toaster mode, resetting +.Pp +A command timeout has caused the adapter to be reset. +.It AIEE! adapter reset failed, giving up and going home! Have a nice day +.Pp +An error occurred while attempting to reset the adapter. +.It unable to get adapter configuration +.It unable to get drive configuration +.Pp +There was an error when attempting to get configuration information. +.It Adapter error during initialization. +.It adapter initialization failed +.Pp +There was an error while attempting to initialize the adapter. +.It adapter failed config check +.It adapter clear failed +.Pp +There was an error while checking the adapter. +.It device is disabled +.Pp +The adapter is disabled. +.It resource allocation failed +.It irq allocation failed +.It irq setup failed +.Pp +The driver was unable to allocate resources for the device. +.El +.Ss Error messages due to DMA : +.Bl -diag +.It can't alloc command dma tag +.It can't alloc SG dma tag +.It can't alloc dma tag for statue queue +.It dmamap failed +.Pp +Failure to map or allocate DMA resources. +.El +.Ss Cache, buffer, and command errors : +.Bl -diag +.It failed to initialize command buffers +.It no mem for command slots! +.Pp +The +.Nm +driver will return +.Bq Er ENOMEM +in such cases. +.It ERROR: unable to get a command! can't flush cache! +.It ERROR: cache flush command failed! +.It ERROR: unable to get a command! can't update nvram +.It ERROR: nvram update command failed! +.It ERROR: unable to get a command! can't sync cache! +.It ERROR: cache sync command failed! +.It ERROR: unable to get a command! can't sync cache! +.It ERROR: etable command failed! +.El +.Sh COMPATIBILITY +Unlike many of the other +.Tn SCSI +devices in +.Fx , +the +.Nm +driver does not use the +.Xr cam 4 +.Tn SCSI +subsystem. +.Sh SEE ALSO +.Xr aac 4 , +.Xr ch 4 , +.Xr da 4 , +.Xr mfi 4 , +.Xr sysctl 8 +.Sh AUTHORS +The +.Nm +driver was written by +.An -nosplit +.An David Jefferys +and +.An Scott Long Aq Mt scottl@FreeBSD.org . +.Pp +This manual page was written by +.An Tom Rhodes Aq Mt trhodes@FreeBSD.org . diff --git a/static/freebsd/man4/ipsec.4 b/static/freebsd/man4/ipsec.4 new file mode 100644 index 00000000..9fd6207c --- /dev/null +++ b/static/freebsd/man4/ipsec.4 @@ -0,0 +1,448 @@ +.\" $KAME: ipsec.4,v 1.17 2001/06/27 15:25:10 itojun Exp $ +.\" +.\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. +.\" 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. Neither the name of the project nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT 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 PROJECT 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 March 4, 2025 +.Dt IPSEC 4 +.Os +.Sh NAME +.Nm ipsec +.Nd Internet Protocol Security protocol +.Sh SYNOPSIS +.Cd "options IPSEC" +.Cd "options IPSEC_SUPPORT" +.Cd "device crypto" +.Pp +.In sys/types.h +.In netinet/in.h +.In netipsec/ipsec.h +.In netipsec/ipsec6.h +.Sh DESCRIPTION +.Nm +is a security protocol implemented within the Internet Protocol layer +of the networking stack. +.Nm +is defined for both IPv4 and IPv6 +.Xr ( inet 4 +and +.Xr inet6 4 ) . +.Nm +is a set of protocols, +.Tn ESP +(for Encapsulating Security Payload) +.Tn AH +(for Authentication Header), +and +.Tn IPComp +(for IP Payload Compression Protocol) +that provide security services for IP datagrams. +AH both authenticates and guarantees the integrity of an IP packet +by attaching a cryptographic checksum computed using one-way hash functions. +ESP, in addition, prevents unauthorized parties from reading the payload of +an IP packet by also encrypting it. +IPComp tries to increase communication performance by compressing IP payload, +thus reducing the amount of data sent. +This will help nodes on slow links but with enough computing power. +.Nm +operates in one of two modes: transport mode or tunnel mode. +Transport mode is used to protect peer-to-peer communication between end nodes. +Tunnel mode encapsulates IP packets within other IP packets +and is designed for security gateways such as VPN endpoints. +.Pp +System configuration requires the +.Xr crypto 4 +subsystem. +.Pp +The packets can be passed to a virtual +.Xr enc 4 +interface, +to perform packet filtering before outbound encryption and after decapsulation +inbound. +.Pp +To properly filter on the inner packets of an +.Nm +tunnel with firewalls, you can change the values of the following sysctls +.Bl -column net.inet6.ipsec6.filtertunnel default enable +.It Sy "Name Default Enable" +.It "net.inet.ipsec.filtertunnel 0 1" +.It "net.inet6.ipsec6.filtertunnel 0 1" +.El +.\" +.Ss Kernel interface +.Nm +is controlled by a key management and policy engine, +that reside in the operating system kernel. +Key management +is the process of associating keys with security associations, also +know as SAs. +Policy management dictates when new security +associations created or destroyed. +.Pp +The key management engine can be accessed from userland by using +.Dv PF_KEY +sockets. +The +.Dv PF_KEY +socket API is defined in RFC2367. +.Pp +The policy engine is controlled by an extension to the +.Dv PF_KEY +API, +.Xr setsockopt 2 +operations, and +.Xr sysctl 3 +interface. +The kernel implements +an extended version of the +.Dv PF_KEY +interface and allows the programmer to define IPsec policies +which are similar to the per-packet filters. +The +.Xr setsockopt 2 +interface is used to define per-socket behavior, and +.Xr sysctl 3 +interface is used to define host-wide default behavior. +.Pp +The kernel code does not implement a dynamic encryption key exchange protocol +such as IKE +(Internet Key Exchange). +Key exchange protocols are beyond what is necessary in the kernel and +should be implemented as daemon processes which call the +.Nm APIs. +.\" +.Ss Policy management +IPsec policies can be managed in one of two ways, either by +configuring per-socket policies using the +.Xr setsockopt 2 +system calls, or by configuring kernel level packet filter-based +policies using the +.Dv PF_KEY +interface, via the +.Xr setkey 8 +you can define IPsec policies against packets using rules similar to packet +filtering rules. +Refer to +.Xr setkey 8 +on how to use it. +.Pp +Depending on the socket's address family, IPPROTO_IP or IPPROTO_IPV6 +transport level and IP_IPSEC_POLICY or IPV6_IPSEC_POLICY socket options +may be used to configure per-socket security policies. +A properly-formed IPsec policy specification structure can be +created using +.Xr ipsec_set_policy 3 +function and used as socket option value for the +.Xr setsockopt 2 +call. +.Pp +When setting policies using the +.Xr setkey 8 +command, the +.Dq Li default +option instructs the system to use its default policy, as +explained below, for processing packets. +The following sysctl variables are available for configuring the +system's IPsec behavior. +The variables can have one of two values. +A +.Li 1 +means +.Dq Li use , +which means that if there is a security association then use it but if +there is not then the packets are not processed by IPsec. +The value +.Li 2 +is synonymous with +.Dq Li require , +which requires that a security association must exist for the packets +to move, and not be dropped. +These terms are defined in +.Xr ipsec_set_policy 3 . +.Bl -column net.inet6.ipsec6.esp_trans_deflev integerxxx +.It Sy "Name Type Changeable" +.It "net.inet.ipsec.esp_trans_deflev integer yes" +.It "net.inet.ipsec.esp_net_deflev integer yes" +.It "net.inet.ipsec.ah_trans_deflev integer yes" +.It "net.inet.ipsec.ah_net_deflev integer yes" +.It "net.inet6.ipsec6.esp_trans_deflev integer yes" +.It "net.inet6.ipsec6.esp_net_deflev integer yes" +.It "net.inet6.ipsec6.ah_trans_deflev integer yes" +.It "net.inet6.ipsec6.ah_net_deflev integer yes" +.El +.Pp +If the kernel does not find a matching, system wide, policy then the +default value is applied. +The system wide default policy is specified +by the following +.Xr sysctl 8 +variables. +.Li 0 +means +.Dq Li discard +which asks the kernel to drop the packet. +.Li 1 +means +.Dq Li none . +.Bl -column net.inet6.ipsec6.def_policy integerxxx +.It Sy "Name Type Changeable" +.It "net.inet.ipsec.def_policy integer yes" +.It "net.inet6.ipsec6.def_policy integer yes" +.El +.\" +.Ss Miscellaneous sysctl variables +When the +.Nm +protocols are configured for use, all protocols are included in the system. +To selectively enable/disable protocols, use +.Xr sysctl 8 . +.Bl -column net.inet.ipcomp.ipcomp_enable +.It Sy "Name Default" +.It "net.inet.esp.esp_enable On" +.It "net.inet.ah.ah_enable On" +.It "net.inet.ipcomp.ipcomp_enable On" +.El +.Pp +In addition the following variables are accessible via +.Xr sysctl 8 , +for tweaking the kernel's IPsec behavior: +.Bl -column net.inet6.ipsec6.inbonud_call_ike integerxxx +.It Sy "Name Type Changeable" +.It "net.inet.ipsec.ah_cleartos integer yes" +.It "net.inet.ipsec.ah_offsetmask integer yes" +.It "net.inet.ipsec.dfbit integer yes" +.It "net.inet.ipsec.ecn integer yes" +.It "net.inet.ipsec.debug integer yes" +.It "net.inet.ipsec.natt_cksum_policy integer yes" +.It "net.inet.ipsec.check_policy_history integer yes" +.It "net.inet.ipsec.random_id integer yes" +.It "net.inet6.ipsec6.ecn integer yes" +.It "net.inet6.ipsec6.debug integer yes" +.El +.Pp +The variables are interpreted as follows: +.Bl -tag -width 6n +.It Li ipsec.ah_cleartos +If set to non-zero, the kernel clears the type-of-service field in the IPv4 header +during AH authentication data computation. +This variable is used to get current systems to inter-operate with devices that +implement RFC1826 AH. +It should be set to non-zero +(clear the type-of-service field) +for RFC2402 conformance. +.It Li ipsec.ah_offsetmask +During AH authentication data computation, the kernel will include a +16bit fragment offset field +(including flag bits) +in the IPv4 header, after computing logical AND with the variable. +The variable is used for inter-operating with devices that +implement RFC1826 AH. +It should be set to zero +(clear the fragment offset field during computation) +for RFC2402 conformance. +.It Li ipsec.dfbit +This variable configures the kernel behavior on IPv4 IPsec tunnel encapsulation. +If set to 0, the DF bit on the outer IPv4 header will be cleared while +1 means that the outer DF bit is set regardless from the inner DF bit and +2 indicates that the DF bit is copied from the inner header to the +outer one. +The variable is supplied to conform to RFC2401 chapter 6.1. +.It Li ipsec.ecn +If set to non-zero, IPv4 IPsec tunnel encapsulation/decapsulation behavior will +be friendly to ECN +(explicit congestion notification), +as documented in +.Li draft-ietf-ipsec-ecn-02.txt . +.Xr gif 4 +talks more about the behavior. +.It Li ipsec.debug +If set to non-zero, debug messages will be generated via +.Xr syslog 3 . +.It Li ipsec.natt_cksum_policy +Controls how the kernel handles TCP and UDP checksums when ESP in UDP +encapsulation is used for IPsec transport mode. +If set to a non-zero value, the kernel fully recomputes checksums for +inbound TCP segments and UDP datagrams after they are decapsulated and +decrypted. +If set to 0 and original addresses were configured for corresponding SA +by the IKE daemon, the kernel incrementally recomputes checksums for +inbound TCP segments and UDP datagrams. +If addresses were not configured, the checksums are ignored. +.It Li ipsec.check_policy_history +Enables strict policy checking for inbound packets. +By default, inbound security policies check that packets handled by IPsec +have been decrypted and authenticated. +If this variable is set to a non-zero value, each packet handled by IPsec +is checked against the history of IPsec security associations. +The IPsec security protocol, mode, and SA addresses must match. +.It Li ipsec.random_id +Enables randomization of encapsulated IPv4 packets ID. +By default, ID randomization is not enabled. +.El +.Pp +Variables under the +.Li net.inet6.ipsec6 +tree have similar meanings to those described above. +.\" +.Sh PROTOCOLS +The +.Nm +protocol acts as a plug-in to the +.Xr inet 4 +and +.Xr inet6 4 +protocols and therefore supports most of the protocols defined upon +those IP-layer protocols. +The +.Xr icmp 4 +and +.Xr icmp6 4 +protocols may behave differently with +.Nm +because +.Nm +can prevent +.Xr icmp 4 +or +.Xr icmp6 4 +routines from looking into the IP payload. +.\" +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr socket 2 , +.Xr ipsec_set_policy 3 , +.Xr crypto 4 , +.Xr enc 4 , +.Xr icmp6 4 , +.Xr if_ipsec 4 , +.Xr intro 4 , +.Xr ip6 4 , +.Xr setkey 8 , +.Xr sysctl 8 +.\".Xr racoon 8 +.Rs +.%A "S. Kent" +.%A "R. Atkinson" +.%T "IP Authentication Header" +.%O "RFC 2404" +.Re +.Rs +.%A "S. Kent" +.%A "R. Atkinson" +.%T "IP Encapsulating Security Payload (ESP)" +.%O "RFC 2406" +.Re +.Sh STANDARDS +.Rs +.%A Daniel L. McDonald +.%A Craig Metz +.%A Bao G. Phan +.%T "PF_KEY Key Management API, Version 2" +.%R RFC +.%N 2367 +.Re +.Pp +.Rs +.%A "D. L. McDonald" +.%T "A Simple IP Security API Extension to BSD Sockets" +.%R internet draft +.%N "draft-mcdonald-simple-ipsec-api-03.txt" +.%O work in progress material +.Re +.Sh HISTORY +The original +.Nm +implementation appeared in the WIDE/KAME IPv6/IPsec stack. +.Pp +For +.Fx 5.0 +a fully locked IPsec implementation called fast_ipsec was brought in. +The protocols drew heavily on the +.Ox +implementation of the +.Tn IPsec +protocols. +The policy management code was derived from the +.Tn KAME +implementation found +in their +.Tn IPsec +protocols. +The fast_ipsec implementation lacked +.Xr ip6 4 +support but made use of the +.Xr crypto 4 +subsystem. +.Pp +For +.Fx 7.0 +.Xr ip6 4 +support was added to fast_ipsec. +After this the old KAME IPsec implementation was dropped and fast_ipsec +became what now is the only +.Nm +implementation in +.Fx . +.Sh BUGS +There is no single standard for the policy engine API, +so the policy engine API described herein is just for this implementation. +.Pp +AH and tunnel mode encapsulation may not work as you might expect. +If you configure inbound +.Dq require +policy with an AH tunnel or any IPsec encapsulating policy with AH +(like +.Dq Li esp/tunnel/A-B/use ah/transport/A-B/require ) , +tunnelled packets will be rejected. +This is because the policy check is enforced on the inner packet on reception, +and AH authenticates encapsulating +(outer) +packet, not the encapsulated +(inner) +packet +(so for the receiving kernel there is no sign of authenticity). +The issue will be solved when we revamp our policy engine to keep all the +packet decapsulation history. +.Pp +When a large database of security associations or policies is present +in the kernel the +.Dv SADB_DUMP +and +.Dv SADB_SPDDUMP +operations on +.Dv PF_KEY +sockets may fail due to lack of space. +Increasing the socket buffer +size may alleviate this problem. +.Pp +The +.Tn IPcomp +protocol may occasionally error because of +.Xr zlib 3 +problems. +.Pp +This documentation needs more review. diff --git a/static/freebsd/man4/ipw.4 b/static/freebsd/man4/ipw.4 new file mode 100644 index 00000000..0ebee0f1 --- /dev/null +++ b/static/freebsd/man4/ipw.4 @@ -0,0 +1,158 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2004-2006 +.\" Damien Bergamini . 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 unmodified, 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 November 10, 2024 +.Dt IPW 4 +.Os +.Sh NAME +.Nm ipw +.Nd Intel PRO/Wireless 2100 IEEE 802.11a/b driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ipw" +.Cd "device ipwfw" +.Cd "device pci" +.Cd "device wlan" +.Cd "device firmware" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_ipw_load="YES" +.Ed +.Pp +In both cases, place the following line in +.Xr loader.conf 5 +to acknowledge the firmware license (see below): +.Bd -literal -offset indent +legal.intel_ipw.license_ack=1 +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for Intel PRO/Wireless 2100 802.11a/b +wireless network devices in +.Cm station , +.Cm adhoc , +and +.Cm monitor +mode operation. +Only one virtual interface may be configured at any time. +.Pp +This driver requires the firmware built with the +.Nm ipwfw +module to work. +For the loaded firmware to be enabled for use the license at +.Pa /usr/share/doc/legal/intel_ipw.LICENSE +must be agreed by adding the following line to +.Xr loader.conf 5 : +.Pp +.Dl "legal.intel_ipw.license_ack=1" +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver provides support for the +Intel PRO/Wireless 2100a/b MiniPCI network adapter. +.Sh FILES +.Bl -tag -width "/usr/share/doc/legal/intel_ipw.LICENSE" -compact +.It Pa /usr/share/doc/legal/intel_ipw.LICENSE +.Nm +firmware license +.El +.Sh EXAMPLES +Join an existing BSS network (i.e., connect to an access point): +.Pp +.Dl ifconfig wlan create wlandev ipw0 inet 192.0.2.20/24 +.Pp +Join a specific BSS network with network name +.Ar my_net : +.Pp +.Dl ifconfig wlan create wlandev ipw0 ssid my_net up +.Pp +Join a specific BSS network with 64-bit WEP encryption: +.Bd -literal -offset indent +ifconfig wlan create wlandev ipw0 ssid my_net \e + wepmode on wepkey 0x1234567890 weptxkey 1 up +.Ed +.Pp +Join a specific BSS network with 128-bit WEP encryption: +.Bd -literal -offset indent +ifconfig wlan create wlandev ipw0 wlanmode adhoc ssid my_net \e + wepmode on wepkey 0x01020304050607080910111213 weptxkey 1 +.Ed +.Sh DIAGNOSTICS +.Bl -diag +.It "ipw%d: device timeout" +The driver will reset the hardware. +This should not happen. +.It "ipw%d: firmware error" +The onboard microcontroller crashes for some reason. +The driver will reset the hardware. +This should not happen. +.It "ipw%d: timeout waiting for firmware initialization to complete" +The onboard microcontroller failed to initialize in time. +This should not happen. +.It "ipw%d: could not load firmware image '%s'" +The driver failed to load the firmware image using the +.Xr firmware 9 +subsystem. +Verify the +.Xr ipwfw 4 +firmware module is installed and the license agreement +.Xr loader 8 +tunable has been set. +.It "ipw%d: could not load microcode" +An attempt to upload the microcode image to the onboard microcontroller failed. +This should not happen. +.It "ipw%d: could not load firmware" +An attempt to upload the firmware image to the onboard microcontroller failed. +This should not happen. +.El +.Sh SEE ALSO +.Xr ipwfw 4 , +.Xr pci 4 , +.Xr wlan 4 , +.Xr wlan_ccmp 4 , +.Xr wlan_tkip 4 , +.Xr wlan_wep 4 , +.Xr networking 7 , +.Xr ifconfig 8 , +.Xr wpa_supplicant 8 +.Sh AUTHORS +The original +.Nm +driver was written by +.An Damien Bergamini Aq Mt damien.bergamini@free.fr . diff --git a/static/freebsd/man4/ipwfw.4 b/static/freebsd/man4/ipwfw.4 new file mode 100644 index 00000000..df1f1b77 --- /dev/null +++ b/static/freebsd/man4/ipwfw.4 @@ -0,0 +1,73 @@ +.\" Copyright (c) 2009 Sam Leffler, Errno Consulting +.\" 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. 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 October 15, 2015 +.Dt IPWFW 4 +.Os +.Sh NAME +.Nm ipwfw +.Nd "Firmware Module for Intel PRO/Wireless 2100 driver" +.Sh SYNOPSIS +To compile this module into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ipwfw" +.Ed +.Pp +This will include three firmware images inside the kernel. +If you want to pick only the firmware image for the mode you want to operate +your network adapter in choose one of the following: +.Bd -ragged -offset indent +.Cd "device ipwbssfw" +.Cd "device ipwibssfw" +.Cd "device ipwmonitorfw" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ipw_bss_load="YES" +ipw_ibss_load="YES" +ipw_monitor_load="YES" +.Ed +.Sh DESCRIPTION +This module provides access to firmware sets for the +Intel PRO/Wireless 2100 series of IEEE 802.11 adapters. +It may be statically linked into the kernel, or loaded as a module. +.Pp +For the loaded firmware to be enabled for use the license at +.Pa /usr/share/doc/legal/intel_ipw.LICENSE +must be agreed to by adding the following line to +.Xr loader.conf 5 : +.Pp +.Dl "legal.intel_ipw.license_ack=1" +.Sh FILES +.Bl -tag -width ".Pa /usr/share/doc/legal/intel_ipw.LICENSE" -compact +.It Pa /usr/share/doc/legal/intel_ipw.LICENSE +.Nm +firmware license +.El +.Sh SEE ALSO +.Xr ipw 4 , +.Xr firmware 9 diff --git a/static/freebsd/man4/irdma.4 b/static/freebsd/man4/irdma.4 new file mode 100644 index 00000000..b7b78a08 --- /dev/null +++ b/static/freebsd/man4/irdma.4 @@ -0,0 +1,243 @@ +.\" Copyright(c) 2016 - 2022 Intel Corporation +.\" All rights reserved. +.\" +.\" This software is available to you under a choice of one of two +.\" licenses. You may choose to be licensed under the terms of the GNU +.\" General Public License (GPL) Version 2, available from the file +.\" COPYING in the main directory of this source tree, or the +.\" OpenFabrics.org BSD license below: +.\" +.\" Redistribution and use in source and binary forms, with or +.\" without modification, are permitted provided that the following +.\" conditions are met: +.\" +.\" - Redistributions of source code must retain the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer. +.\" +.\" - 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. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +.\" NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS +.\" BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN +.\" ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN +.\" CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +.\" SOFTWARE. +.\" +.Dd March 30, 2022 +.Dt IRDMA 4 +.Os +.Sh NAME +.Nm irdma +.Nd RDMA FreeBSD driver for Intel(R) Ethernet Controller E810 +.Sh SYNOPSIS +This module relies on +.Xr ice 4 +.Bl -tag -width indent +.It The following kernel options should be included in the configuration: +.Cd options OFED +.Cd options OFED_DEBUG_INIT +.Cd options COMPAT_LINUXKPI +.Cd options SDP +.Cd options IPOIB_CM +.El +.Sh DESCRIPTION +.Ss Features +The +.Nm +driver provides RDMA protocol support on RDMA-capable Intel Ethernet 800 Series +NICs which are supported by +.Xr ice 4 +. +.Pp +The driver supports both iWARP and RoCEv2 protocols. +.Sh CONFIGURATION +.Ss TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width indent +.It Va dev.irdma.roce_enable +enables RoCEv2 protocol usage on interface. +.Pp +By default RoCEv2 protocol is used. +.It Va dev.irdma.dcqcn_cc_cfg_valid +indicates that all DCQCN parameters are valid and should be updated in +registers or QP context. +.Pp +Setting this parameter to 1 means that settings in +.Em dcqcn_min_dec_factor , dcqcn_min_rate_MBps , dcqcn_F , dcqcn_T , +.Em dcqcn_B, dcqcn_rai_factor, dcqcn_hai_factor, dcqcn_rreduce_mperiod +are taken into account. +Otherwise default values are used. +.Pp +Note: "roce_enable" must also be set for this tunable to take effect. +.It Va dev.irdma.dcqcn_min_dec_factor +The minimum factor by which the current transmit rate can be changed when +processing a CNP. +Value is given as a percentage (1-100). +.Pp +Note: "roce_enable" and "dcqcn_cc_cfg_valid" must also be set for this tunable +to take effect. +.It Va dev.irdma.dcqcn_min_rate_MBps +The minimum value, in Mbits per second, for rate to limit. +.Pp +Note: "roce_enable" and "dcqcn_cc_cfg_valid" must also be set for this tunable +to take effect. +.It Va dev.irdma.dcqcn_F +The number of times to stay in each stage of bandwidth recovery. +.Pp +Note: "roce_enable" and "dcqcn_cc_cfg_valid" must also be set for this tunable +to take effect. +.It Va dev.irdma.dcqcn_T +The number of microseconds that should elapse before increasing the CWND +in DCQCN mode. +.Pp +Note: "roce_enable" and "dcqcn_cc_cfg_valid" must also be set for this tunable +to take effect. +.It Va dev.irdma.dcqcn_B +The number of bytes to transmit before updating CWND in DCQCN mode. +.Pp +Note: "roce_enable" and "dcqcn_cc_cfg_valid" must also be set for this tunable +to take effect. +.It Va dev.irdma.dcqcn_rai_factor +The number of MSS to add to the congestion window in additive increase mode. +.Pp +Note: "roce_enable" and "dcqcn_cc_cfg_valid" must also be set for this tunable +to take effect. +.It Va dev.irdma.dcqcn_hai_factor +The number of MSS to add to the congestion window in hyperactive increase mode. +.Pp +Note: "roce_enable" and "dcqcn_cc_cfg_valid" must also be set for this tunable +to take effect. +.It Va dev.irdma.dcqcn_rreduce_mperiod +The minimum time between 2 consecutive rate reductions for a single flow. +Rate reduction will occur only if a CNP is received during the relevant time +interval. +.Pp +Note: "roce_enable" and "dcqcn_cc_cfg_valid" must also be set for this tunable +to take effect. +.El +.Ss SYSCTL PROCEDURES +Sysctl controls are available for runtime adjustments. +.Bl -tag -width indent +.It Va dev.irdma.debug +defines level of debug messages. +.Pp +Typical value: 1 for errors only, 0x7fffffff for full debug. +.It Va dev.irdma.dcqcn_enable +enables the DCQCN algorithm for RoCEv2. +.Pp +Note: "roce_enable" must also be set for this sysctl to take effect. +.Pp +Note: The change may be set at any time, but it will be applied only to newly +created QPs. +.El +.Ss TESTING +.Bl -enum +.It +To load the irdma driver, run: +.Bd -literal -offset indent +kldload irdma +.Ed +If if_ice is not already loaded, the system will load it on its own. +Please check whether the value of sysctl +.Va hw.ice.irdma +is 1, if the irdma driver is not loading. +To change the value put: +.Bd -literal -offset indent +hw.ice.irdma=1 +.Ed +in +.Pa /boot/loader.conf +and reboot. +.It +To check that the driver was loaded, run: +.Bd -literal -offset indent +sysctl -a | grep infiniband +.Ed +Typically, if everything goes well, around 190 entries per PF will appear. +.It +Each interface of the card may work in either iWARP or RoCEv2 mode. +To enable RoCEv2 compatibility, add: +.Bd -literal -offset indent +dev.irdma.roce_enable=1 +.Ed +where is a desired ice interface number on which +RoCEv2 protocol needs to be enabled, into: +.Pa /boot/loader.conf +, for instance: +.Bl -tag -width indent +.It dev.irdma0.roce_enable=0 +.It dev.irdma1.roce_enable=1 +.El +will keep iWARP mode on ice0 and enable RoCEv2 mode on interface ice1. +The RoCEv2 mode is the default. +.Pp +To check irdma roce_enable status, run: +.Bd -literal -offset indent +sysctl dev.irdma.roce_enable +.Ed +for instance: +.Bd -literal -offset indent +sysctl dev.irdma2.roce_enable +.Ed +with returned value of '0' indicate the iWARP mode, and the value of '1' +indicate the RoCEv2 mode. +.Pp +Note: An interface configured in one mode will not be able to connect +to a node configured in another mode. +.Pp +Note: RoCEv2 has currently limited support, for functional testing only. +DCB and Priority Flow Controller (PFC) are not currently supported which +may lead to significant performance loss or connectivity issues. +.It +Enable flow control in the ice driver: +.Bd -literal -offset indent +sysctl dev.ice..fc=3 +.Ed +Enable flow control on the switch your system is connected to. +See your switch documentation for details. +.It +The source code for krping software is provided with the kernel in +/usr/src/sys/contrib/rdma/krping/. +To compile the software, change directory to +/usr/src/sys/modules/rdma/krping/ and invoke the following: +.Bl -tag -width indent +.It make clean +.It make +.It make install +.It kldload krping +.El +.It +Start a krping server on one machine: +.Bd -literal -offset indent +echo size=64,count=1,port=6601,addr=100.0.0.189,server > /dev/krping +.Ed +.It +Connect a client from another machine: +.Bd -literal -offset indent +echo size=64,count=1,port=6601,addr=100.0.0.189,client > /dev/krping +.Ed +.El +.Sh SUPPORT +For general information and support, go to the Intel support website at: +.Lk http://support.intel.com/ . +.Pp +If an issue is identified with this driver with a supported adapter, email all +the specific information related to the issue to +.Mt freebsd@intel.com . +.Sh SEE ALSO +.Xr ice 4 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was prepared by +.An Bartosz Sobczak Aq Mt bartosz.sobczak@intel.com . diff --git a/static/freebsd/man4/isci.4 b/static/freebsd/man4/isci.4 new file mode 100644 index 00000000..4d8115f0 --- /dev/null +++ b/static/freebsd/man4/isci.4 @@ -0,0 +1,113 @@ +.\" +.\" Copyright (c) 2012 Intel Corporation +.\" 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, +.\" without modification. +.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer +.\" substantially similar to the "NO WARRANTY" disclaimer below +.\" ("Disclaimer") and any redistribution must be conditioned upon +.\" including a substantially similar Disclaimer requirement for further +.\" binary redistribution. +.\" +.\" NO WARRANTY +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR 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 DAMAGES. +.\" +.\" isci driver man page. +.\" +.\" Author: Jim Harris +.\" +.Dd January 23, 2012 +.Dt ISCI 4 +.Os +.Sh NAME +.Nm isci +.Nd Intel C600 Serial Attached SCSI driver +.Sh SYNOPSIS +To compile this driver into your kernel, +place the following lines in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device scbus" +.Cd "device isci" +.Ed +.Pp +Or, to load the driver as a module at boot, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +isci_load="YES" +.Ed +.Sh HARDWARE +The +.Nm +driver provides support for Intel C600 +.Tn SAS +controllers. +.Sh CONFIGURATION +To force legacy interrupts for all +.Nm +driver instances, set the following tunable value in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hw.isci.force_legacy_interrupts=1 +.Ed +.Sh DEBUGGING +To enable debugging prints from the +.Nm +driver, set the +.Bd -literal -offset indent +hw.isci.debug_level +.Ed +.Pp +variable to a value between 1 and 4 in +.Xr loader.conf 5 . +.Pp +The hardware layer in the +.Nm +driver has extensive logging capabilities +which are disabled by default for performance reasons. +These can be enabled by adding +.Bd -literal -offset indent +options ISCI_LOGGING +.Ed +.Pp +to the kernel configuration file. +.Sh SEE ALSO +.Xr cd 4 , +.Xr ch 4 , +.Xr da 4 , +.Xr pci 4 , +.Xr sa 4 , +.Xr scsi 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 8.3 +and 9.1. +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was developed by Intel and originally written by +.An Jim Harris Aq Mt jimharris@FreeBSD.org +with contributions from +.An Sohaib Ahsan +and input from +.An Scott Long Aq Mt scottl@FreeBSD.org . +.Pp +This man page was written by +.An Jim Harris Aq Mt jimharris@FreeBSD.org . diff --git a/static/freebsd/man4/iscsi.4 b/static/freebsd/man4/iscsi.4 new file mode 100644 index 00000000..77a5e816 --- /dev/null +++ b/static/freebsd/man4/iscsi.4 @@ -0,0 +1,117 @@ +.\" Copyright (c) 2014 Edward Tomasz Napierala +.\" +.\" 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 May 28, 2017 +.Dt ISCSI 4 +.Os +.Sh NAME +.Nm iscsi +.Nd iSCSI initiator +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in the +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device iscsi" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +iscsi_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +subsystem provides the kernel component of an iSCSI initiator, +responsible for implementing the Full Feature Phase of the iSCSI protocol. +The initiator is the iSCSI client, which connects to an iSCSI target, +providing local access to a remote block device. +The userland component is provided by +.Xr iscsid 8 +and both the kernel and userland are configured using +.Xr iscsictl 8 . +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va kern.iscsi.debug +Verbosity level for log messages from the +.Nm +driver. +Set to 0 to disable logging or 1 to warn about potential problems. +Larger values enable debugging output. +Defaults to 1. +.It Va kern.iscsi.ping_timeout +The number of seconds to wait for the target to respond to a NOP-Out +PDU. +In the event that there is no response within that time the session gets +forcibly restarted. +Set to 0 to disable sending NOP-Out PDUs. +Defaults to 5. +.It Va kern.iscsi.iscsid_timeout +The number of seconds to wait for +.Xr iscsid 8 +to establish a session. +After that time +.Nm +will abort and retry. +Defaults to 60. +.It Va kern.iscsi.login_timeout +The number of seconds to wait for a login attempt to succeed. +After that time +.Nm +will abort and retry. +Defaults to 60. +.It Va kern.iscsi.maxtags +The maximum number of outstanding IO requests. +Defaults to 255. +.It Va kern.iscsi.fail_on_disconnection +Controls the behavior after an iSCSI connection has been dropped due to +network problems. +When set to 1, a dropped connection causes the iSCSI device nodes +to be destroyed. +After reconnecting, they will be created again. +By default, the device nodes are left intact. +While the connection is down all input/output operations are suspended, to be +retried after the connection is reestablished. +.El +.Sh SEE ALSO +.Xr iser 4 , +.Xr iscsi.conf 5 , +.Xr iscsictl 8 , +.Xr iscsid 8 +.Sh HISTORY +The +.Nm +subsystem first appeared in +.Fx 10.0 . +.Sh AUTHORS +The +.Nm +subsystem was developed by +.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org +under sponsorship from the FreeBSD Foundation. diff --git a/static/freebsd/man4/iser.4 b/static/freebsd/man4/iser.4 new file mode 100644 index 00000000..496e7b40 --- /dev/null +++ b/static/freebsd/man4/iser.4 @@ -0,0 +1,92 @@ +.\" Copyright (c) 2015, Mellanox Technologies, Inc. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY 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 June 6, 2016 +.Dt ISER 4 +.Os +.Sh NAME +.Nm iser +.Nd iSCSI Extensions for RDMA (iSER) driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in the +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device iser" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +iser_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +(iSCSI Extensions for RDMA) initiator driver extends the iSCSI protocol to RDMA. +It permits data to be transferred directly into and out of SCSI buffers +without intermediate data copies. +iSER uses the RDMA protocol suite to supply higher bandwidth for +block storage transfers (zero copy behavior). +To that fact, it eliminates the +TCP/IP processing overhead while preserving the compatibility with iSCSI protocol. +The initiator is the iSCSI/iSER client, which connects to an iSCSI/iSER target, +providing local access to a remote block device. +The userland component is provided by +.Xr iscsid 8 +and both the kernel and userland are configured using +.Xr iscsictl 8 . +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va kern.iser.debug +Verbosity level for log messages from the +.Nm +driver. +Set to 0 to disable logging or 1 to warn about potential problems. +Larger values enable info and debugging output. +Defaults to 0. +.El +.Sh SEE ALSO +.Xr iscsi 4 , +.Xr iscsi.conf 5 , +.Xr iscsictl 8 , +.Xr iscsid 8 +.Sh HISTORY +The +.Nm +subsystem first appeared in +.Fx 11.0 . +.Sh AUTHORS +The +.Nm +subsystem was developed by +.An Max Gurtovoy Aq Mt maxg@mellanox.com +and +.An Sagi Grimberg Aq Mt sagig@mellanox.com +under sponsorship from Mellanox Technologies. diff --git a/static/freebsd/man4/isl.4 b/static/freebsd/man4/isl.4 new file mode 100644 index 00000000..610c6e47 --- /dev/null +++ b/static/freebsd/man4/isl.4 @@ -0,0 +1,130 @@ +.\" Copyright (c) 2015 Michael Gmelin +.\" 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 December 18, 2018 +.Dt ISL 4 +.Os +.Sh NAME +.Nm isl +.Nd Intersil(TM) I2C ISL29018 sensor driver +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines into +the kernel configuration file: +.Bd -ragged -offset indent +.Cd "device isl" +.Cd "device ig4" +.Cd "device iicbus" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +isl_load="YES" +ig4_load="YES" +.Ed +.Pp +On many Chromebook models this driver can be automatically configured with the +help of the +.Xr chromebook_platform 4 +driver. +Alternatively, the +.Nm +driver can be manually configured in +.Pa /boot/device.hints : +.Cd hint.isl.0.at="iicbus0" +.Cd hint.isl.0.addr="0x88" +.Cd hint.isl.1.at="iicbus1" +.Cd hint.isl.1.addr="0x88" +.Sh DESCRIPTION +The +.Nm +driver provides access to sensor data provided by the Intersil(TM) I2C +ISL29018 Digital Ambient Light Sensor and Proximity Sensor with Interrupt +Function. +Functionality is basic and provided through the +.Xr sysctl 8 +interface. +.Pp +On a system using +.Xr device.hints 5 , +these values are configurable for +.Nm : +.Bl -tag -width "hint.isl.%d.addr" +.It Va hint.isl.%d.at +target +.Xr iicbus 4 . +.It Va hint.isl.%d.addr +.Nm +i2c address on the +.Xr iicbus 4 . +.El +.Sh SYSCTL VARIABLES +The following +.Xr sysctl 8 +variables are available: +.Bl -tag -width "dev.isl.X.resolution" +.It Va dev.isl.X.als +Current ALS (Ambient Light Sensor) readout. +.It Va dev.isl.X.ir +Current IR (InfraRed) sensor readout. +.It Va dev.isl.X.prox +Current proximity sensor readout. +.It Va dev.isl.X.resolution +Current sensor resolution. +.It Va dev.isl.X.range +Current sensor range. +.El +.Sh EXAMPLES +.Ss Ambient light sensor read out +.Bd -literal +$ sysctl dev.isl.0.als +dev.isl.0.als: 64 +.Ed +.Ss Automatically adjust brightness +This requires the port +.Pa graphics/intel-backlight +and only works with laptops using a supported Intel(R) GPU. +.Bd -literal +$ pkg install intel-backlight +$ sh /usr/local/share/examples/intel-backlight/isl_backlight.sh +.Ed +.Sh SEE ALSO +.Xr chromebook_platform 4 , +.Xr ig4 4 , +.Xr iicbus 4 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Michael Gmelin Aq Mt freebsd@grem.de . +.Pp +This manual page was written by +.An Michael Gmelin Aq Mt freebsd@grem.de . +.Sh BUGS +The +.Nm +driver detects the device based from the I2C address. +This might have unforeseen consequences if the initialization sequence +is sent to an unknown device at that address. diff --git a/static/freebsd/man4/ismt.4 b/static/freebsd/man4/ismt.4 new file mode 100644 index 00000000..1c3beec5 --- /dev/null +++ b/static/freebsd/man4/ismt.4 @@ -0,0 +1,58 @@ +.\" +.\" Copyright (c) 2014 Intel Corporation +.\" 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, +.\" without modification. +.\" 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. Neither the name of Intel Corporation nor the names of its +.\" contributors may be used to endorse or promote products derived from +.\" this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR 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 DAMAGES. +.\" +.\" ismt driver man page. +.\" +.\" Author: Jim Harris +.\" +.Dd March 4, 2020 +.Dt ISMT 4 +.Os +.Sh NAME +.Nm ismt +.Nd Intel SMBus Message Transport (SMBus 2.0) driver +.Sh SYNOPSIS +.Cd device pci +.Cd device smbus +.Cd device smb +.Cd device ismt +.Sh DESCRIPTION +This driver provides access to the SMBus 2.0 controller device contained +in the Intel Atom S1200, C2000 and C3000 CPUs. +.Sh SEE ALSO +.Xr ichsmb 4 , +.Xr smb 4 , +.Xr smbus 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 10.3 . +.Sh AUTHORS +.An Jim Harris Aq Mt jimharris@FreeBSD.org diff --git a/static/freebsd/man4/isp.4 b/static/freebsd/man4/isp.4 new file mode 100644 index 00000000..a8f985a5 --- /dev/null +++ b/static/freebsd/man4/isp.4 @@ -0,0 +1,250 @@ +.\" +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" Copyright (c) 2009-2020 Alexander Motin +.\" Copyright (c) 2006 Marcus Alves Grando +.\" Copyright (c) 1998-2001 Matthew Jacob, for NASA/Ames Research Center +.\" +.\" 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. 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 8, 2025 +.Dt ISP 4 +.Os +.Sh NAME +.Nm isp +.Nd Qlogic FibreChannel SCSI Host Adapters driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device scbus" +.Cd "device isp" +.Cd "device ispfw" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +isp_load="YES" +ispfw_load="YES" +.Ed +.Sh DESCRIPTION +This driver provides access to +.Tn FibreChannel +SCSI devices. +.Pp +It supports initiator and target modes of FCP SCSI profile, +utilizing Class 3 and Class 2 connections. +Support is available for Public and Private loops, Point-to-Point +and Fabric connections. +.Pp +Supported FC-Tape functionality is highly recommended for connections +to tape drives that support it. +It encompasses four elements from the T-10 FCP-4 specification: +.Bl -bullet -offset indent +.It +Precise Delivery of Commands +.It +Confirmed Completion of FCP I/O Operations +.It +Retransmission of Unsuccessfully Transmitted IUs +.It +Task Retry Identification +.El +.Pp +Together these features allow for link level error recovery with tape +devices. +Without it, an initiator cannot, for instance, tell whether a tape write +command that has timed out resulted in all, part or none of the data going to +the tape drive. +FC-Tape is automatically enabled when connecting controller that supports +it to a target that supports it. +It may be disabled using configuration and hint options described below. +.Sh HARDWARE +The +.Nm +driver supports the following optical Fibre Channel adapters: +.Bl -column "Qlogic 2690/2692/2694 (2684/2692)" "Speed" "PCI-X" +.It Model: Ta Speed: Ta Bus: +.It Qlogic QLE2874 (2814) Ta 64Gb Ta PCIe +.It Qlogic QLE2870/QLE2872 (2812) Ta 64Gb Ta PCIe +.It Qlogic QLE2774 (2814) Ta 32Gb Ta PCIe +.It Qlogic QLE2770/QLE2772 (2812) Ta 32Gb Ta PCIe +.It Qlogic 2740/2742/2764 (2722/2714) Ta 32Gb Ta PCIe +.It Qlogic 2690/2692/2694 (2684/2692) Ta 16Gb Ta PCIe +.It Qlogic 267x/836x (2031/8031) FCoE Ta 16Gb Ta PCIe +.It Qlogic 256x (2532) Ta 8Gb Ta PCIe +.It Qlogic 246x (2432) Ta 4Gb Ta PCIe +.It Qlogic 2422 Ta 4Gb Ta PCI-X +.El +.Sh FIRMWARE +Firmware loading is supported and handled by +.Xr firmware 9 . +The correct firmware is either loaded automatically, if available for this +type of adapter, or by manually loading the +.Xr ispfw 4 +module. +It is strongly recommended that you use the firmware available from +.Xr ispfw 4 +as it is the one that most likely has been tested with this driver. +.Sh CONFIGURATION OPTIONS +Target mode support for Fibre Channel adapters may be enabled with the +.Pp +.Cd options ISP_TARGET_MODE +.Pp +option. +.Pp +To disable FC-Tape, use the following configuration option: +.Pp +.Cd options ISP_FCTAPE_OFF +.Pp +Note that even if the ISP_FCTAPE_OFF option is used, it may be overridden +by the fctape hint described below. +.Sh BOOT OPTIONS +The following options are switchable by setting values in +.Pa /boot/device.hints . +.Pp +They are: +.Bl -tag -width indent +.It Va hint.isp. Ns Ar N Ns Va .msi +Limit on number of Message Signaled Interrupts (MSI) to be used. +.It Va hint.isp. Ns Ar N Ns Va .msix +Limit on number of Extended Message Signaled Interrupts (MSI-X) to be used. +.It Va hint.isp. Ns Ar N Ns Va .fwload_disable +A hint value to disable loading of firmware provided by +.Xr ispfw 4 . +.It Va hint.isp. Ns Ar N Ns Va .fwload_force +A hint value to prefer firmware provided by +.Xr ispfw 4 , +even if it is older than the firmware in flash on the board. +If fwload_disable is also specified, fwload_force will be ignored. +.Pp +By default, with 27XX and newer controllers, the +.Xr isp 4 +driver will use the newer +firmware. +For older controllers, the +.Xr isp 4 +driver will use the firmware provided by +.Xr ispfw 4 +if it is available, and otherwise use the firmware in flash on the board. +.It Va hint.isp. Ns Ar N Ns Va .ignore_nvram +A hint value to ignore board NVRAM settings for. +Otherwise use NVRAM settings. +.It Va hint.isp. Ns Ar N Ns Va .fullduplex +A hint value to set full duplex mode. +.It Va hint.isp. Ns Ar N Ns Va .topology +A hint value to select topology of connection. +Supported values are: +.Pp +.Bl -tag -width ".Li lport-only" -compact +.It Li lport +Prefer arbitrated loop and fallback to point to point. +.It Li nport +Prefer point to point and fallback to arbitrated loop. +.It Li lport-only +Arbitrated loop only. +.It Li nport-only +Point to point only. +.El +.It Va hint.isp. Ns Ar N Ns Va .portwwn +This should be the full 64 bit World Wide Port Name you would like +to use, overriding the value in NVRAM for the card. +.It Va hint.isp. Ns Ar N Ns Va .nodewwn +This should be the full 64 bit World Wide Node Name you would like +to use, overriding the value in NVRAM for the card. +.It Va hint.isp. Ns Ar N Ns Va .iid +A hint to override or set the Initiator ID or Loop ID. +For Fibre Channel +cards in Local Loop topologies it is +.Ar strongly +recommended that you set this value to non-zero. +.It Va hint.isp. Ns Ar N Ns Va .role +A hint to define default role for isp instance (0 -- none, 1 -- target, +2 -- initiator, 3 -- both). +.It Va hint.isp. Ns Ar N Ns Va .debug +A hint value for a driver debug level (see the file +.Pa /usr/src/sys/dev/isp/ispvar.h +for the values. +.It Va hint.isp. Ns Ar N Ns Va .vports +A hint to create specified number of additional virtual ports. +.It Va hint.isp. Ns Ar N Ns Va .nofctape +Set this to 1 to disable FC-Tape operation on the given isp instance. +.It Va hint.isp. Ns Ar N Ns Va .fctape +Set this to 1 to enable FC-Tape operation on the given isp instance for +targets that support it. +.El +.Sh SYSCTL OPTIONS +.Bl -tag -width indent +.It Va dev.isp. Ns Ar N Ns Va .loop_down_limit +This value says how long to wait in seconds after loop has gone down before +giving up and expiring all of the devices that were visible. +The default is 300 seconds (5 minutes). +A separate (nonadjustable) timeout is used when +booting to not stop booting on lack of FC connectivity. +.It Va dev.isp. Ns Ar N Ns Va .gone_device_time +This value says how long to wait for devices to reappear if they (temporarily) +disappear due to loop or fabric events. +While this timeout is running, I/O +to those devices will simply be held. +.It Va dev.isp. Ns Ar N Ns Va .use_gff_id +.It Va dev.isp. Ns Ar N Ns Va .use_gft_id +Setting those options to 0 allows to disable use of GFF_ID and GFT_ID SNS +requests during FC fabric scan. +It may be useful if switch does not implement them correctly, +preventing some devices from being found. +Disabling them may cause unneeded logins to ports not supporting target role +or even FCP at all. +The default is 1 (enabled). +.It Va dev.isp. Ns Ar N Ns Va .wwnn +This is the readonly World Wide Node Name value for this port. +.It Va dev.isp. Ns Ar N Ns Va .wwpn +This is the readonly World Wide Port Name value for this port. +.It Va dev.isp. Ns Ar N Ns Va .fw_version_flash +The readonly flash firmware version value in the active region of the +controller. +.It Va dev.isp. Ns Ar N Ns Va .fw_version_ispfw +The readonly firmware version value provided by +.Xr ispfw 4 . +.It Va dev.isp. Ns Ar N Ns Va .fw_version_run +The readonly firmware version value currently executed on the controller. +.El +.Sh SEE ALSO +.Xr da 4 , +.Xr intro 4 , +.Xr ispfw 4 , +.Xr sa 4 , +.Xr scsi 4 , +.Xr gmultipath 8 +.Sh AUTHORS +The +.Nm +driver was written by +.An Matthew Jacob +originally for NetBSD at NASA/Ames Research Center. +Later improvement was done by +.An Alexander Motin Aq Mt mav@FreeBSD.org . +.Sh BUGS +The driver currently ignores some NVRAM settings. diff --git a/static/freebsd/man4/ispfw.4 b/static/freebsd/man4/ispfw.4 new file mode 100644 index 00000000..b2f952ce --- /dev/null +++ b/static/freebsd/man4/ispfw.4 @@ -0,0 +1,60 @@ +.\" Copyright (c) 2009-2020 Alexander Motin +.\" Copyright (c) 2000 Matthew Jacob +.\" +.\" 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. 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 October 27, 2023 +.Dt ISPFW 4 +.Os +.Sh NAME +.Nm ispfw +.Nd "Firmware for Qlogic FibreChannel SCSI Host Adapters" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ispfw" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ispfw_load="YES" +.Ed +.Sh DESCRIPTION +This trivial driver provides access to firmware sets for the Qlogic +FibreChannel SCSI Host Adapters. +It may either be +statically linked into the kernel, or loaded as a module. +In either +case, the +.Xr isp 4 +driver will notice that firmware is available to be downloaded onto +Qlogic cards (to replace the usually out of date firmware on the cards). +This will kick the f/w into getting unstuck. +.Sh SEE ALSO +.Xr isp 4 +.Sh AUTHORS +This driver was written by +.An Matthew Jacob . +Later improvement was done by +.An Alexander Motin Aq Mt mav@FreeBSD.org . diff --git a/static/freebsd/man4/itwd.4 b/static/freebsd/man4/itwd.4 new file mode 100644 index 00000000..fd537418 --- /dev/null +++ b/static/freebsd/man4/itwd.4 @@ -0,0 +1,73 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2012 Bjoern A. Zeeb +.\" Copyright (c) 2019 Andriy Gapon +.\" +.\" 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 October 16, 2019 +.Dt ITWD 4 +.Os +.Sh NAME +.Nm itwd +.Nd device driver for ITE Super I/O chips watchdog timer +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device superio" +.Cd "device itwd" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the following +line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +itwd_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides +.Xr watchdog 4 +support for the watchdog timer present on at least the following +Super I/O chips: +.Bl -bullet -compact +.It +IT8721F +.It +IT8728F +.It +IT8771F +.El +.Sh SEE ALSO +.Xr superio 4 , +.Xr watchdog 4 , +.Xr device.hints 5 , +.Xr watchdog 8 , +.Xr watchdogd 8 , +.Xr watchdog 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Andriy Gapon Aq Mt avg@FreeBSD.org . diff --git a/static/freebsd/man4/iwi.4 b/static/freebsd/man4/iwi.4 new file mode 100644 index 00000000..31ef4ec8 --- /dev/null +++ b/static/freebsd/man4/iwi.4 @@ -0,0 +1,171 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2004-2006 +.\" Damien Bergamini . 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 unmodified, 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 November 10, 2024 +.Dt IWI 4 +.Os +.Sh NAME +.Nm iwi +.Nd Intel PRO/Wireless 2200BG/2225BG/2915ABG IEEE 802.11 network driver +.Sh SYNOPSIS +To compile this driver into the kernel, +include the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device iwi" +.Cd "device iwifw" +.Cd "device pci" +.Cd "device wlan" +.Cd "device firmware" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_iwi_load="YES" +.Ed +.Pp +In both cases, place the following line in +.Xr loader.conf 5 +to acknowledge the firmware license (see below): +.Bd -literal -offset indent +legal.intel_iwi.license_ack=1 +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for Intel PRO/Wireless 2200BG/2225BG/2915ABG +IEEE 802.11a/b/g wireless network devices in +.Cm station , +.Cm adhoc , +and +.Cm monitor +mode operation. +Only one virtual interface may be configured at any time. +.Pp +This driver requires the firmware built with the +.Nm iwifw +module to work. +For the loaded firmware to be enabled for use the license at +.Pa /usr/share/doc/legal/intel_iwi.LICENSE +must be agreed by adding the following line to +.Xr loader.conf 5 : +.Pp +.Dl "legal.intel_iwi.license_ack=1" +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports the following wireless network devices: +.Pp +.Bl -bullet -compact +.It +Intel PRO/Wireless 2200BG MiniPCI Network Connection +.It +Intel PRO/Wireless 2225BG PCI Network Connection +.It +Intel PRO/Wireless 2915ABG MiniPCI Network Connection +.El +.Sh FILES +.Bl -tag -width "/usr/share/doc/legal/intel_iwi.LICENSE" -compact +.It Pa /usr/share/doc/legal/intel_iwi.LICENSE +.Nm +firmware license +.El +.Sh EXAMPLES +Join an existing BSS network (i.e., connect to an access point): +.Pp +.Dl ifconfig wlan create wlandev iwi0 inet 192.0.2.20/24 +.Pp +Join a specific BSS network with network name +.Ar my_net : +.Pp +.Dl ifconfig wlan create wlandev iwi0 ssid my_net up +.Pp +Join a specific BSS network with 64-bit WEP encryption: +.Bd -literal -offset indent +ifconfig wlan create wlandev iwi0 ssid my_net \e + wepmode on wepkey 0x1234567890 weptxkey 1 up +.Ed +.Pp +Join a specific BSS network with 128-bit WEP encryption: +.Bd -literal -offset indent +ifconfig wlan create wlandev iwi0 wlanmode adhoc ssid my_net \e + wepmode on wepkey 0x01020304050607080910111213 weptxkey 1 +.Ed +.Sh DIAGNOSTICS +.Bl -diag +.It "iwi%d: device timeout" +The driver will reset the hardware. +This should not happen. +.It "iwi%d: firmware error" +The onboard microcontroller crashed for some reason. +The driver will reset the hardware. +This should not happen. +.It "iwi%d: timeout waiting for firmware initialization to complete" +The onboard microcontroller failed to initialize in time. +This should not happen. +.It "iwi%d: could not load firmware image '%s'" +The driver failed to load the firmware image using the +.Xr firmware 9 +subsystem. +Verify the +.Xr iwifw 4 +firmware module is installed and the license agreement +.Xr loader 8 +tunable has been set. +.It "iwi%d: could not load boot firmware" +An attempt to upload the boot firmware image to the onboard microcontroller +failed. +This should not happen. +.It "iwi%d: could not load microcode" +An attempt to upload the microcode image to the onboard microcontroller failed. +This should not happen. +.It "iwi%d: could not load main firmware" +An attempt to upload the main firmware image to the onboard microcontroller +failed. +This should not happen. +.El +.Sh SEE ALSO +.Xr iwifw 4 , +.Xr pci 4 , +.Xr wlan 4 , +.Xr wlan_ccmp 4 , +.Xr wlan_tkip 4 , +.Xr wlan_wep 4 , +.Xr networking 7 , +.Xr ifconfig 8 , +.Xr wpa_supplicant 8 +.Sh AUTHORS +The original +.Nm +driver was written by +.An Damien Bergamini Aq Mt damien.bergamini@free.fr . diff --git a/static/freebsd/man4/iwifw.4 b/static/freebsd/man4/iwifw.4 new file mode 100644 index 00000000..d4bad24a --- /dev/null +++ b/static/freebsd/man4/iwifw.4 @@ -0,0 +1,73 @@ +.\" Copyright (c) 2009 Sam Leffler, Errno Consulting +.\" 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. 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 October 15, 2015 +.Dt IWIFW 4 +.Os +.Sh NAME +.Nm iwifw +.Nd "Firmware Module for Intel PRO/Wireless 2200BG/2225BG/2915ABG driver" +.Sh SYNOPSIS +To compile this module into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device iwifw" +.Ed +.Pp +This will include three firmware images inside the kernel. +If you want to pick only the firmware image for the mode you want to operate +your network adapter in choose one of the following: +.Bd -ragged -offset indent +.Cd "device iwibssfw" +.Cd "device iwiibssfw" +.Cd "device iwimonitorfw" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +iwi_bss_load="YES" +iwi_ibss_load="YES" +iwi_monitor_load="YES" +.Ed +.Sh DESCRIPTION +This module provides access to firmware sets for the +Intel PRO/Wireless 2200BG/2225BG/2915ABG series of IEEE 802.11 adapters. +It may be statically linked into the kernel, or loaded as a module. +.Pp +For the loaded firmware to be enabled for use the license at +.Pa /usr/share/doc/legal/intel_iwi.LICENSE +must be agreed to by adding the following line to +.Xr loader.conf 5 : +.Pp +.Dl "legal.intel_iwi.license_ack=1" +.Sh FILES +.Bl -tag -width ".Pa /usr/share/doc/legal/intel_iwi.LICENSE" -compact +.It Pa /usr/share/doc/legal/intel_iwi.LICENSE +.Nm +firmware license +.El +.Sh SEE ALSO +.Xr iwi 4 , +.Xr firmware 9 diff --git a/static/freebsd/man4/iwlwifi.4 b/static/freebsd/man4/iwlwifi.4 new file mode 100644 index 00000000..411af54b --- /dev/null +++ b/static/freebsd/man4/iwlwifi.4 @@ -0,0 +1,341 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2021-2025 The FreeBSD Foundation +.\" +.\" This documentation was written by Bj\xc3\xb6rn Zeeb under sponsorship from +.\" the FreeBSD Foundation. +.\" +.\" 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 August 19, 2025 +.Dt IWLWIFI 4 +.Os +.Sh NAME +.Nm iwlwifi +.Nd Intel IEEE 802.11a/b/g/n/ac/ax/be wireless network driver +.Sh SYNOPSIS +The driver will auto-load without any user interaction using +.Xr devmatch 8 +if enabled in +.Xr rc.conf 5 . +.Pp +Only if auto-loading is explicitly disabled, place the following +lines in +.Xr rc.conf 5 +to manually load the driver as a module at boot time: +.Bd -literal -offset indent +kld_list="${kld_list} if_iwlwifi" +.Ed +.Pp +The driver should automatically load any +.Xr iwlwififw 4 +firmware needed for the particular chipset. +See section +.Sx "FILES" +below for how to install the firmware. +.Pp +It is not possible to load the driver from +.Xr loader 8 . +.Sh DESCRIPTION +The +.Nm +driver provides support for Intel Wireless network devices. +.Pp +.Nm +is derived from Intel's Linux iwlwifi driver. +The +.Xr iwm 4 +and +.Xr iwx 4 +drivers together are approximately equivalent to Intel's Linux iwlwifi/mvm +driver. +.Pp +In addition +.Nm +already supports Intel's Linux iwlwifi/mld chipsets. +.Pp +.Nm +still complements the +.Xr iwn 4 +driver which supports older chipsets and would be equivalent to +Intel's Linux iwlwifi/dvm, which +.Nm +does not support. +.Pp +The driver uses the +.\" No LinuxKPI man pages so no .Xr here. +.Sy linuxkpi_wlan +and +.Sy linuxkpi +compat framework to bridge between the Linux and +native +.Fx +driver code as well as to the native +.Xr net80211 4 +wireless stack. +.Sh HARDWARE +The +.Nm +driver supports PCIe devices from the +.Sy mvm +sub-driver with the following chipset generations: +.Pp +.\" awk -F\\t '{ print $5 }' ~/tmp/iwlwifi_pci_ids_name.txt | \ +.\" grep -v undefined | sort -V | uniq | grep -v ^$ | \ +.\" awk '{ printf ".It\n%s\n", $0 }' +.Bl -bullet -compact +.It +7000 +.It +8000 +.It +9000 +.It +22000 +.It +AX210 +.El +.Pp +The +.Nm +driver supports PCIe devices from the +.Sy mld +sub-driver with the following chipset generations: +.Pp +.Bl -bullet -compact +.It +BZ +.It +SC +.El +.Pp +These chipset generations match the following common device names: +.Pp +.Bl -bullet -compact +.\" -------------------------------------------------------------------- +.\" This list is manually generated from a sysctl and post-processing. +.\" Edits will be overwritten on next update. +.\" awk -F\\t '{ if ($2 == "") { next; } if (seen[$2]) { next; } \ +.\" seen[$2]=1; printf ".It\n%s\n", $2; }' iwlwifi_pci_ids_name.txt +.\" -------------------------------------------------------------------- +.It +Intel(R) Dual Band Wireless AC 7260 +.It +Intel(R) Dual Band Wireless N 7260 +.It +Intel(R) Wireless N 7260 +.It +Intel(R) Dual Band Wireless AC 3160 +.It +Intel(R) Dual Band Wireless N 3160 +.It +Intel(R) Wireless N 3160 +.It +Intel(R) Dual Band Wireless AC 3165 +.It +Intel(R) Dual Band Wireless AC 3168 +.It +Intel(R) Dual Band Wireless AC 7265 +.It +Intel(R) Wireless N 7265 +.It +Intel(R) Dual Band Wireless N 7265 +.It +Intel(R) Dual Band Wireless AC 8260 +.It +Intel(R) Dual Band Wireless N 8260 +.It +Intel(R) Dual Band Wireless AC 4165 +.It +Intel(R) Dual Band Wireless AC 8265 +.It +Intel(R) Dual Band Wireless AC 8275 +.It +Killer (R) Wireless-AC 1550 Wireless Network Adapter (9260NGW) 160MHz +.It +Killer (R) Wireless-AC 1550s Wireless Network Adapter (9560NGW) +.It +Killer (R) Wireless-AC 1550i Wireless Network Adapter (9560NGW) +.It +Killer(R) Wireless-AC 1550s Wireless Network Adapter (9560D2W) 160MHz +.It +Killer(R) Wireless-AC 1550i Wireless Network Adapter (9560NGW) 160MHz +.It +Killer(R) Wi-Fi 6E AX1690s 160MHz Wireless Network Adapter (411D2W) +.It +Killer(R) Wi-Fi 6E AX1690i 160MHz Wireless Network Adapter (411NGW) +.It +Intel(R) Wireless-AC 9260-1 +.It +Intel(R) Wi-Fi 6 AX200 160MHz +.It +Killer(R) Wi-Fi 6 AX1650w 160MHz Wireless Network Adapter (200D2W) +.It +Killer(R) Wi-Fi 6 AX1650x 160MHz Wireless Network Adapter (200NGW) +.It +Intel(R) Wi-Fi 6 AX201 160MHz +.It +Killer(R) Wi-Fi 6 AX1650s 160MHz Wireless Network Adapter (201D2W) +.It +Killer(R) Wi-Fi 6 AX1650i 160MHz Wireless Network Adapter (201NGW) +.It +Killer(R) Wi-Fi 6 AX1650s 160MHz Wireless Network Adapter (201NGW) +.It +Killer(R) Wi-Fi 6 AX1650i 160MHz Wireless Network Adapter (201D2W) +.It +Intel(R) Wi-Fi 6E AX211 160MHz +.It +Intel(R) Wi-Fi 6 AX210 160MHz +.It +Killer(R) Wi-Fi 6E AX1675w 160MHz Wireless Network Adapter (210D2W) +.It +Killer(R) Wi-Fi 6E AX1675x 160MHz Wireless Network Adapter (210NGW) +.It +Intel(R) Wi-Fi 6E AX411 160MHz +.It +Killer(R) Wi-Fi 6E AX1675s 160MHz Wireless Network Adapter (211NGW) +.It +Killer(R) Wi-Fi 6E AX1675i 160MHz Wireless Network Adapter (211NGW) +.It +Intel(R) Wireless-AC 9461 160MHz +.It +Intel(R) Wireless-AC 9461 +.It +Intel(R) Wireless-AC 9462 160MHz +.It +Intel(R) Wireless-AC 9462 +.It +Intel(R) Wireless-AC 9560 160MHz +.It +Intel(R) Wireless-AC 9560 +.It +Intel(R) Wireless-AC 9270 160MHz +.It +Intel(R) Wireless-AC 9270 +.It +Intel(R) Wireless-AC 9162 160MHz +.It +Intel(R) Wireless-AC 9162 +.It +Intel(R) Wireless-AC 9260 160MHz +.It +Intel(R) Wireless-AC 9260 +.It +Intel(R) Wi-Fi 6 AX101 +.It +Intel(R) Wi-Fi 6 AX203 +.It +Intel(R) Wi-Fi 6E AX231 160MHz +.It +Intel(R) Wi-Fi 7 BE201 320MHz +.It +Intel(R) Wi-Fi 7 BE200 320MHz +.It +Intel(R) Wi-Fi 7 BE202 160MHz +.It +Intel(R) TBD Sc device +.It +Intel(R) TBD Sc2 device +.It +Intel(R) TBD Sc2f device +.\" -------------------------------------------------------------------- +.El +.Sh LOADER TUNABLES +The +.Nm +driver supports the following +.Xr loader 8 +tunable and read-only +.Xr sysctl 8 +variables: +.Bl -tag -width "compat.linuxkpi.iwlwifi_disable_11ac" +.It Va compat.linuxkpi.iwlwifi_11n_disable +Turn off 802.11n support in the driver. +Default +.Ql 1 . +.It Va compat.linuxkpi.iwlwifi_disable_11ac +Turn off 802.11ac support in the driver. +Default +.Ql 1 . +.El +.Pp +The names of the tunables are derived from the Linux iwlwifi driver +module parameters and are mapped automatically by +.Sy linuxkpi . +They were not adjusted so that they stay consistent with upstream +Linux, e.g., for documentation available and problem investigations. +This left their names inconsistent between themselves and inconsistent to +.Fx +style. +.Pp +The tunables are automatically adjusted by the firmware package for +chipsets which can enable 11n and 11ac. +In case of problems a user may want to override the provided values +in +.Pa /boot/loader.conf.local +with the above defaults. +.Sh FILES +The +.Nm +driver requires firmware from +.Pa ports/net/wifi-firmware-iwlwifi-kmod . +This firmware package will be installed automatically with +.Xr fwget 8 +if the appropriate hardware is detected at installation or runtime. +.Pp +As a last resort for bootstrapping, individual firmware files can be +manually downloaded, e.g., on a different computer and transferred using a +.Xr umass 4 +device. +The firmware files can be found at +.Lk git://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git +with names as requested by the driver. +Copies should be placed into the +.Pa /boot/firmware +directory. +.Sh SEE ALSO +.Xr iwlwififw 4 , +.Xr iwm 4 , +.Xr iwn 4 , +.Xr iwx 4 , +.Xr wlan 4 , +.Xr networking 7 , +.Xr fwget 8 , +.Xr ifconfig 8 , +.Xr wpa_supplicant 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 13.1 . +802.11n and 802.11ac support for the 22000 and later chipsets first appeared in +.Fx 14.3 . +.Sh BUGS +.Lk https://bugs.freebsd.org/bugzilla/showdependencytree.cgi?id=iwlwifi "iwlwifi known bugs" +.Pp +While +.Nm +supports 802.11a/b/g/n/ac/ax/be modes, +the compatibility code currently only supports 802.11a/b/g/n/ac modes. +802.11n/ac is only available on the 22000 and later chipset generations. +802.11ax/be and 6Ghz support are planned. diff --git a/static/freebsd/man4/iwlwififw.4 b/static/freebsd/man4/iwlwififw.4 new file mode 100644 index 00000000..45ee0e75 --- /dev/null +++ b/static/freebsd/man4/iwlwififw.4 @@ -0,0 +1,1583 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2021-2025 The FreeBSD Foundation +.\" +.\" This documentation was written by Bj\xc3\xb6rn Zeeb under sponsorship from +.\" the FreeBSD Foundation. +.\" +.\" 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 May 12, 2025 +.Dt IWLWIFIFW 4 +.Os +.Sh NAME +.Nm iwlwififw +.Nd Firmware for Intel iwlwifi wireless network driver +.Sh SYNOPSIS +The +.Xr iwlwifi 4 +driver should auto-load any firmware needed. +It is discouraged to load the driver or firmware manually from +.Xr loader 8 . +.Sh DESCRIPTION +Firmware files are available from +.Xr ports 7 +for the various chipset models supported +by the +.Xr iwlwifi 4 +driver. +Modern chipsets often require a +.Pa .ucode +and an accompanying +.Pa .pnvm +file. +.Pp +One can use +.Xr fwget 8 +to install the correct firmware package. +.Pp +The list is provided as a reference as to with file prefix is needed for +a specific card as far as it can be determined and the port flavor. +.Pp +.Bl -column -compact "Vendor" "Device" "Subv. " "Subd. " "Flavor" "Firmware-Prefix" +.It Ar Name +.It Ar Vendor Ta Ar Device Ta Ar Subv. Ta Ar Subd. Ta Ar Flavor Ta Ar Firmware-Prefix +.\" --------------------------------------------------------------------- +.\" This list is manually generated from a sysctl and post-processing +.\" by sys/contrib/dev/iwlwifi/zzz_fw_ports_fwget.sh generating the list. +.\" Edits will be overwritten on next update. +.\" --------------------------------------------------------------------- +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0x4070 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0x4072 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0x4170 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0x4c60 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0x4c70 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0x4060 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0x406a Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0x4160 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0x4062 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0x4162 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b2 Ta any Ta 0x4270 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b2 Ta any Ta 0x4272 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b2 Ta any Ta 0x4260 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b2 Ta any Ta 0x426a Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b2 Ta any Ta 0x4262 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0x4470 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0x4472 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0x4460 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0x446a Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0x4462 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0x4870 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0x486e Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0x4a70 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0x4a6e Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0x4a6c Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0x4570 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0x4560 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b2 Ta any Ta 0x4370 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b2 Ta any Ta 0x4360 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0x5070 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0x5072 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0x5170 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0x5770 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0x4020 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0x402a Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b2 Ta any Ta 0x4220 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0x4420 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0xc070 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0xc072 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0xc170 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0xc060 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0xc06a Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0xc160 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0xc062 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0xc162 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0xc770 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0xc760 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b2 Ta any Ta 0xc270 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0xcc70 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0xcc60 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b2 Ta any Ta 0xc272 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b2 Ta any Ta 0xc260 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b2 Ta any Ta 0xc26a Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b2 Ta any Ta 0xc262 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0xc470 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0xc472 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0xc460 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0xc462 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0xc570 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0xc560 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b2 Ta any Ta 0xc370 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0xc360 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0xc020 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0xc02a Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b2 Ta any Ta 0xc220 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless N 7260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b1 Ta any Ta 0xc420 Ta 7000 Ta iwlwifi-7260 +.It "" +.It Intel(R) Dual Band Wireless AC 3160 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b3 Ta any Ta 0x0070 Ta 7000 Ta iwlwifi-3160 +.It "" +.It Intel(R) Dual Band Wireless AC 3160 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b3 Ta any Ta 0x0072 Ta 7000 Ta iwlwifi-3160 +.It "" +.It Intel(R) Dual Band Wireless AC 3160 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b3 Ta any Ta 0x0170 Ta 7000 Ta iwlwifi-3160 +.It "" +.It Intel(R) Dual Band Wireless AC 3160 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b3 Ta any Ta 0x0172 Ta 7000 Ta iwlwifi-3160 +.It "" +.It Intel(R) Dual Band Wireless N 3160 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b3 Ta any Ta 0x0060 Ta 7000 Ta iwlwifi-3160 +.It "" +.It Intel(R) Wireless N 3160 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b3 Ta any Ta 0x0062 Ta 7000 Ta iwlwifi-3160 +.It "" +.It Intel(R) Dual Band Wireless AC 3160 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b4 Ta any Ta 0x0270 Ta 7000 Ta iwlwifi-3160 +.It "" +.It Intel(R) Dual Band Wireless AC 3160 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b4 Ta any Ta 0x0272 Ta 7000 Ta iwlwifi-3160 +.It "" +.It Intel(R) Dual Band Wireless AC 3160 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b3 Ta any Ta 0x0470 Ta 7000 Ta iwlwifi-3160 +.It "" +.It Intel(R) Dual Band Wireless AC 3160 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b3 Ta any Ta 0x0472 Ta 7000 Ta iwlwifi-3160 +.It "" +.It Intel(R) Dual Band Wireless AC 3160 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b4 Ta any Ta 0x0370 Ta 7000 Ta iwlwifi-3160 +.It "" +.It Intel(R) Dual Band Wireless AC 3160 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b3 Ta any Ta 0x8070 Ta 7000 Ta iwlwifi-3160 +.It "" +.It Intel(R) Dual Band Wireless AC 3160 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b3 Ta any Ta 0x8072 Ta 7000 Ta iwlwifi-3160 +.It "" +.It Intel(R) Dual Band Wireless AC 3160 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b3 Ta any Ta 0x8170 Ta 7000 Ta iwlwifi-3160 +.It "" +.It Intel(R) Dual Band Wireless AC 3160 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b3 Ta any Ta 0x8172 Ta 7000 Ta iwlwifi-3160 +.It "" +.It Intel(R) Dual Band Wireless N 3160 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b3 Ta any Ta 0x8060 Ta 7000 Ta iwlwifi-3160 +.It "" +.It Intel(R) Wireless N 3160 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b3 Ta any Ta 0x8062 Ta 7000 Ta iwlwifi-3160 +.It "" +.It Intel(R) Dual Band Wireless AC 3160 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b4 Ta any Ta 0x8270 Ta 7000 Ta iwlwifi-3160 +.It "" +.It Intel(R) Dual Band Wireless AC 3160 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b4 Ta any Ta 0x8370 Ta 7000 Ta iwlwifi-3160 +.It "" +.It Intel(R) Dual Band Wireless AC 3160 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b4 Ta any Ta 0x8272 Ta 7000 Ta iwlwifi-3160 +.It "" +.It Intel(R) Dual Band Wireless AC 3160 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b3 Ta any Ta 0x8470 Ta 7000 Ta iwlwifi-3160 +.It "" +.It Intel(R) Dual Band Wireless AC 3160 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b3 Ta any Ta 0x8570 Ta 7000 Ta iwlwifi-3160 +.It "" +.It Intel(R) Dual Band Wireless AC 3160 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b3 Ta any Ta 0x1070 Ta 7000 Ta iwlwifi-3160 +.It "" +.It Intel(R) Dual Band Wireless AC 3160 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x08b3 Ta any Ta 0x1170 Ta 7000 Ta iwlwifi-3160 +.It "" +.It Intel(R) Dual Band Wireless AC 3165 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x3165 Ta any Ta 0x4010 Ta 7000 Ta iwlwifi-7265D +.It "" +.It Intel(R) Dual Band Wireless AC 3165 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x3165 Ta any Ta 0x4012 Ta 7000 Ta iwlwifi-7265D +.It "" +.It Intel(R) Dual Band Wireless AC 3165 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x3166 Ta any Ta 0x4212 Ta 7000 Ta iwlwifi-7265D +.It "" +.It Intel(R) Dual Band Wireless AC 3165 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x3165 Ta any Ta 0x4410 Ta 7000 Ta iwlwifi-7265D +.It "" +.It Intel(R) Dual Band Wireless AC 3165 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x3165 Ta any Ta 0x4510 Ta 7000 Ta iwlwifi-7265D +.It "" +.It Intel(R) Dual Band Wireless AC 3165 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x3165 Ta any Ta 0x4110 Ta 7000 Ta iwlwifi-7265D +.It "" +.It Intel(R) Dual Band Wireless AC 3165 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x3166 Ta any Ta 0x4310 Ta 7000 Ta iwlwifi-7265D +.It "" +.It Intel(R) Dual Band Wireless AC 3165 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x3166 Ta any Ta 0x4210 Ta 7000 Ta iwlwifi-7265D +.It "" +.It Intel(R) Dual Band Wireless AC 3165 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x3165 Ta any Ta 0x8010 Ta 7000 Ta iwlwifi-7265D +.It "" +.It Intel(R) Dual Band Wireless AC 3165 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x3165 Ta any Ta 0x8110 Ta 7000 Ta iwlwifi-7265D +.It "" +.It Intel(R) Dual Band Wireless AC 3168 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fb Ta any Ta 0x2010 Ta 7000 Ta iwlwifi-3168 +.It "" +.It Intel(R) Dual Band Wireless AC 3168 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fb Ta any Ta 0x2110 Ta 7000 Ta iwlwifi-3168 +.It "" +.It Intel(R) Dual Band Wireless AC 3168 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fb Ta any Ta 0x2050 Ta 7000 Ta iwlwifi-3168 +.It "" +.It Intel(R) Dual Band Wireless AC 3168 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fb Ta any Ta 0x2150 Ta 7000 Ta iwlwifi-3168 +.It "" +.It Intel(R) Dual Band Wireless AC 3168 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fb Ta any Ta 000000 Ta 7000 Ta iwlwifi-3168 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x5010 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x5110 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x5100 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095b Ta any Ta 0x5310 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Wireless N 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095b Ta any Ta 0x5302 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095b Ta any Ta 0x5210 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x5c10 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x5012 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x5412 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x5410 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x5510 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x5400 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x1010 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless N 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x5000 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless N 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x500a Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless N 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095b Ta any Ta 0x5200 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Wireless N 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x5002 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Wireless N 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x5102 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Wireless N 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095b Ta any Ta 0x5202 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x9010 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x9012 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x900a Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x9110 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x9112 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095b Ta any Ta 0x9210 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095b Ta any Ta 0x9200 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x9510 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095b Ta any Ta 0x9310 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x9410 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless N 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x5020 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless N 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x502a Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless N 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x5420 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x5090 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x5190 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x5590 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095b Ta any Ta 0x5290 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x5490 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x5f10 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095b Ta any Ta 0x5212 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095b Ta any Ta 0x520a Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x9000 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x9400 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 7265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x095a Ta any Ta 0x9e10 Ta 7000 Ta iwlwifi-7265 +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x0010 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x1010 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x10b0 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x0130 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x1130 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x0132 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x1132 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x0110 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x01f0 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x0012 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x1012 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x1110 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x0050 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x0250 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x1050 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x0150 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x1150 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f4 Ta any Ta 0x0030 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f4 Ta any Ta 0x1030 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0xc010 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0xc110 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0xd010 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0xc050 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0xd050 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0xd0b0 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0xb0b0 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x8010 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x8110 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x9010 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x9110 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f4 Ta any Ta 0x8030 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f4 Ta any Ta 0x9030 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f4 Ta any Ta 0xc030 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f4 Ta any Ta 0xd030 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x8130 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x9130 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x8132 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x9132 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x8050 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x8150 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x9050 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x9150 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless N 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x0004 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless N 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x0044 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 4165 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f5 Ta any Ta 0x0010 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 4165 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f6 Ta any Ta 0x0030 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x0810 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x0910 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x0850 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x0950 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x0930 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 000000 Ta 8000 Ta iwlwifi-8265 +.It "" +.It Intel(R) Dual Band Wireless AC 8260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24f3 Ta any Ta 0x4010 Ta 8000 Ta iwlwifi-8000C +.It "" +.It Intel(R) Dual Band Wireless AC 8265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fd Ta any Ta 0x0010 Ta 8000 Ta iwlwifi-8265 +.It "" +.It Intel(R) Dual Band Wireless AC 8265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fd Ta any Ta 0x0110 Ta 8000 Ta iwlwifi-8265 +.It "" +.It Intel(R) Dual Band Wireless AC 8265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fd Ta any Ta 0x1110 Ta 8000 Ta iwlwifi-8265 +.It "" +.It Intel(R) Dual Band Wireless AC 8265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fd Ta any Ta 0x1130 Ta 8000 Ta iwlwifi-8265 +.It "" +.It Intel(R) Dual Band Wireless AC 8265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fd Ta any Ta 0x0130 Ta 8000 Ta iwlwifi-8265 +.It "" +.It Intel(R) Dual Band Wireless AC 8265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fd Ta any Ta 0x1010 Ta 8000 Ta iwlwifi-8265 +.It "" +.It Intel(R) Dual Band Wireless AC 8265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fd Ta any Ta 0x10d0 Ta 8000 Ta iwlwifi-8265 +.It "" +.It Intel(R) Dual Band Wireless AC 8265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fd Ta any Ta 0x0050 Ta 8000 Ta iwlwifi-8265 +.It "" +.It Intel(R) Dual Band Wireless AC 8265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fd Ta any Ta 0x0150 Ta 8000 Ta iwlwifi-8265 +.It "" +.It Intel(R) Dual Band Wireless AC 8265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fd Ta any Ta 0x9010 Ta 8000 Ta iwlwifi-8265 +.It "" +.It Intel(R) Dual Band Wireless AC 8265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fd Ta any Ta 0x8110 Ta 8000 Ta iwlwifi-8265 +.It "" +.It Intel(R) Dual Band Wireless AC 8265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fd Ta any Ta 0x8050 Ta 8000 Ta iwlwifi-8265 +.It "" +.It Intel(R) Dual Band Wireless AC 8265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fd Ta any Ta 0x8010 Ta 8000 Ta iwlwifi-8265 +.It "" +.It Intel(R) Dual Band Wireless AC 8265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fd Ta any Ta 0x0810 Ta 8000 Ta iwlwifi-8265 +.It "" +.It Intel(R) Dual Band Wireless AC 8265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fd Ta any Ta 0x9110 Ta 8000 Ta iwlwifi-8265 +.It "" +.It Intel(R) Dual Band Wireless AC 8265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fd Ta any Ta 0x8130 Ta 8000 Ta iwlwifi-8265 +.It "" +.It Intel(R) Dual Band Wireless AC 8265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fd Ta any Ta 0x0910 Ta 8000 Ta iwlwifi-8265 +.It "" +.It Intel(R) Dual Band Wireless AC 8265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fd Ta any Ta 0x0930 Ta 8000 Ta iwlwifi-8265 +.It "" +.It Intel(R) Dual Band Wireless AC 8265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fd Ta any Ta 0x0950 Ta 8000 Ta iwlwifi-8265 +.It "" +.It Intel(R) Dual Band Wireless AC 8265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fd Ta any Ta 0x0850 Ta 8000 Ta iwlwifi-8265 +.It "" +.It Intel(R) Dual Band Wireless AC 8265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fd Ta any Ta 0x1014 Ta 8000 Ta iwlwifi-8265 +.It "" +.It Intel(R) Dual Band Wireless AC 8275 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fd Ta any Ta 0x3e02 Ta 8000 Ta iwlwifi-8265 +.It "" +.It Intel(R) Dual Band Wireless AC 8275 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fd Ta any Ta 0x3e01 Ta 8000 Ta iwlwifi-8265 +.It "" +.It Intel(R) Dual Band Wireless AC 8275 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fd Ta any Ta 0x1012 Ta 8000 Ta iwlwifi-8265 +.It "" +.It Intel(R) Dual Band Wireless AC 8275 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fd Ta any Ta 0x0012 Ta 8000 Ta iwlwifi-8265 +.It "" +.It Intel(R) Dual Band Wireless AC 8265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fd Ta any Ta 0x0014 Ta 8000 Ta iwlwifi-8265 +.It "" +.It Intel(R) Dual Band Wireless AC 8265 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x24fd Ta any Ta 0x9074 Ta 8000 Ta iwlwifi-8265 +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2526 Ta any Ta any Ta 9000 Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x271b Ta any Ta any Ta 9000 Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x271c Ta any Ta any Ta 9000 Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x30dc Ta any Ta any Ta 9000 Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x31dc Ta any Ta any Ta 9000 Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x9df0 Ta any Ta any Ta 9000 Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa370 Ta any Ta any Ta 9000 Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x02f0 Ta any Ta any Ta 22000 Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x06f0 Ta any Ta any Ta 22000 Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x34f0 Ta any Ta any Ta 22000 Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x3df0 Ta any Ta any Ta 22000 Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x4df0 Ta any Ta any Ta 22000 Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x43f0 Ta any Ta any Ta 22000 Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa0f0 Ta any Ta any Ta 22000 Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2723 Ta any Ta any Ta 22000 Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2725 Ta any Ta any Ta AX210 Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7a70 Ta any Ta any Ta AX210 Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7af0 Ta any Ta any Ta AX210 Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x51f0 Ta any Ta any Ta AX210 Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x51f1 Ta any Ta any Ta AX210 Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x54f0 Ta any Ta any Ta AX210 Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7f70 Ta any Ta any Ta AX210 Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2729 Ta any Ta any Ta AX210 Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7e40 Ta any Ta any Ta AX210 Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2727 Ta any Ta any Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x272d Ta any Ta any Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x272b Ta any Ta any Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 000000 Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x0090 Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x0094 Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x0098 Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x009c Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x00c0 Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x00c4 Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x00e0 Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x00e4 Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x00e8 Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x00ec Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x0100 Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x0110 Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x0114 Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x0118 Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x011c Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x0310 Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x0314 Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x0510 Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x0a10 Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x1671 Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x1672 Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x1771 Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x1772 Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x1791 Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x1792 Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x4090 Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x40c4 Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x40e0 Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x4110 Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa840 Ta any Ta 0x4314 Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7740 Ta any Ta any Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x4d40 Ta any Ta any Ta BZ Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xe440 Ta any Ta any Ta SC Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xe340 Ta any Ta any Ta SC Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xd340 Ta any Ta any Ta SC Ta (unknown) +.It "" +.It (unknown) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x6e70 Ta any Ta any Ta SC Ta (unknown) +.It "" +.It Killer (R) Wireless-AC 1550 Wireless Network Adapter (9260NGW) 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2526 Ta any Ta 0x1550 Ta iwlwifi Ta iwlwifi-9260-th-b0-jf-b0 +.It "" +.It Killer (R) Wireless-AC 1550s Wireless Network Adapter (9560NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2526 Ta any Ta 0x1551 Ta iwlwifi Ta iwlwifi-9000-pu-b0-jf-b0 +.It "" +.It Killer (R) Wireless-AC 1550i Wireless Network Adapter (9560NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2526 Ta any Ta 0x1552 Ta iwlwifi Ta iwlwifi-9000-pu-b0-jf-b0 +.It "" +.It Killer (R) Wireless-AC 1550s Wireless Network Adapter (9560NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x30dc Ta any Ta 0x1551 Ta iwlwifi Ta iwlwifi-9000-pu-b0-jf-b0 +.It "" +.It Killer (R) Wireless-AC 1550i Wireless Network Adapter (9560NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x30dc Ta any Ta 0x1552 Ta iwlwifi Ta iwlwifi-9000-pu-b0-jf-b0 +.It "" +.It Killer (R) Wireless-AC 1550s Wireless Network Adapter (9560NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x31dc Ta any Ta 0x1551 Ta iwlwifi Ta iwlwifi-9000-pu-b0-jf-b0 +.It "" +.It Killer (R) Wireless-AC 1550i Wireless Network Adapter (9560NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x31dc Ta any Ta 0x1552 Ta iwlwifi Ta iwlwifi-9000-pu-b0-jf-b0 +.It "" +.It Killer (R) Wireless-AC 1550s Wireless Network Adapter (9560NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa370 Ta any Ta 0x1551 Ta iwlwifi Ta iwlwifi-9000-pu-b0-jf-b0 +.It "" +.It Killer (R) Wireless-AC 1550i Wireless Network Adapter (9560NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa370 Ta any Ta 0x1552 Ta iwlwifi Ta iwlwifi-9000-pu-b0-jf-b0 +.It "" +.It Killer(R) Wireless-AC 1550s Wireless Network Adapter (9560D2W) 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x54f0 Ta any Ta 0x1551 Ta iwlwifi Ta iwlwifi-9000-pu-b0-jf-b0 +.It "" +.It Killer (R) Wireless-AC 1550i Wireless Network Adapter (9560NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x54f0 Ta any Ta 0x1552 Ta iwlwifi Ta iwlwifi-9000-pu-b0-jf-b0 +.It "" +.It Killer(R) Wireless-AC 1550s Wireless Network Adapter (9560D2W) 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x51f0 Ta any Ta 0x1552 Ta iwlwifi Ta iwlwifi-9000-pu-b0-jf-b0 +.It "" +.It Killer(R) Wireless-AC 1550i Wireless Network Adapter (9560NGW) 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x51f0 Ta any Ta 0x1551 Ta iwlwifi Ta iwlwifi-9000-pu-b0-jf-b0 +.It "" +.It Killer(R) Wi-Fi 6E AX1690s 160MHz Wireless Network Adapter (411D2W) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x51f0 Ta any Ta 0x1691 Ta AX210 Ta iwlwifi-so-a0-gf4-a0 +.It "" +.It Killer(R) Wi-Fi 6E AX1690i 160MHz Wireless Network Adapter (411NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x51f0 Ta any Ta 0x1692 Ta AX210 Ta iwlwifi-so-a0-gf4-a0 +.It "" +.It Killer(R) Wi-Fi 6E AX1690i 160MHz Wireless Network Adapter (411NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x51f1 Ta any Ta 0x1692 Ta AX210 Ta iwlwifi-so-a0-gf4-a0 +.It "" +.It Killer(R) Wi-Fi 6E AX1690s 160MHz Wireless Network Adapter (411D2W) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x54f0 Ta any Ta 0x1691 Ta AX210 Ta iwlwifi-so-a0-gf4-a0 +.It "" +.It Killer(R) Wi-Fi 6E AX1690i 160MHz Wireless Network Adapter (411NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x54f0 Ta any Ta 0x1692 Ta AX210 Ta iwlwifi-so-a0-gf4-a0 +.It "" +.It Killer(R) Wi-Fi 6E AX1690s 160MHz Wireless Network Adapter (411D2W) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7a70 Ta any Ta 0x1691 Ta AX210 Ta iwlwifi-so-a0-gf4-a0 +.It "" +.It Killer(R) Wi-Fi 6E AX1690i 160MHz Wireless Network Adapter (411NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7a70 Ta any Ta 0x1692 Ta AX210 Ta iwlwifi-so-a0-gf4-a0 +.It "" +.It Killer(R) Wi-Fi 6E AX1690s 160MHz Wireless Network Adapter (411D2W) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7af0 Ta any Ta 0x1691 Ta AX210 Ta iwlwifi-so-a0-gf4-a0 +.It "" +.It Killer(R) Wi-Fi 6E AX1690i 160MHz Wireless Network Adapter (411NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7af0 Ta any Ta 0x1692 Ta AX210 Ta iwlwifi-so-a0-gf4-a0 +.It "" +.It Intel(R) Wireless-AC 9260-1 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x271c Ta any Ta 0x0214 Ta iwlwifi Ta iwlwifi-9260-th-b0-jf-b0 +.It "" +.It Killer(R) Wi-Fi 6E AX1690s 160MHz Wireless Network Adapter (411D2W) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7e40 Ta any Ta 0x1691 Ta AX210 Ta (null) +.It "" +.It Killer(R) Wi-Fi 6E AX1690i 160MHz Wireless Network Adapter (411NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7e40 Ta any Ta 0x1692 Ta AX210 Ta (null) +.It "" +.It Intel(R) Wi-Fi 6 AX200 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2723 Ta any Ta any Ta 22000 Ta iwlwifi-cc-a0 +.It "" +.It Killer(R) Wi-Fi 6 AX1650w 160MHz Wireless Network Adapter (200D2W) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2723 Ta any Ta 0x1653 Ta 22000 Ta iwlwifi-cc-a0 +.It "" +.It Killer(R) Wi-Fi 6 AX1650x 160MHz Wireless Network Adapter (200NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2723 Ta any Ta 0x1654 Ta 22000 Ta iwlwifi-cc-a0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x43f0 Ta any Ta 0x0070 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x43f0 Ta any Ta 0x0074 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x43f0 Ta any Ta 0x0078 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x43f0 Ta any Ta 0x007c Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Killer(R) Wi-Fi 6 AX1650s 160MHz Wireless Network Adapter (201D2W) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x43f0 Ta any Ta 0x1651 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Killer(R) Wi-Fi 6 AX1650i 160MHz Wireless Network Adapter (201NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x43f0 Ta any Ta 0x1652 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x43f0 Ta any Ta 0x2074 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x43f0 Ta any Ta 0x4070 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa0f0 Ta any Ta 0x0070 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa0f0 Ta any Ta 0x0074 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa0f0 Ta any Ta 0x0078 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa0f0 Ta any Ta 0x007c Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa0f0 Ta any Ta 0x0a10 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Killer(R) Wi-Fi 6 AX1650s 160MHz Wireless Network Adapter (201NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa0f0 Ta any Ta 0x1651 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Killer(R) Wi-Fi 6 AX1650i 160MHz Wireless Network Adapter (201D2W) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa0f0 Ta any Ta 0x1652 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa0f0 Ta any Ta 0x2074 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa0f0 Ta any Ta 0x4070 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0xa0f0 Ta any Ta 0x6074 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x02f0 Ta any Ta 0x0070 Ta 22000 Ta iwlwifi-QuZ-a0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x02f0 Ta any Ta 0x0074 Ta 22000 Ta iwlwifi-QuZ-a0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x02f0 Ta any Ta 0x6074 Ta 22000 Ta iwlwifi-QuZ-a0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x02f0 Ta any Ta 0x0078 Ta 22000 Ta iwlwifi-QuZ-a0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x02f0 Ta any Ta 0x007c Ta 22000 Ta iwlwifi-QuZ-a0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x02f0 Ta any Ta 0x0310 Ta 22000 Ta iwlwifi-QuZ-a0-hr-b0 +.It "" +.It Killer(R) Wi-Fi 6 AX1650s 160MHz Wireless Network Adapter (201D2W) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x02f0 Ta any Ta 0x1651 Ta 22000 Ta iwlwifi-QuZ-a0-hr-b0 +.It "" +.It Killer(R) Wi-Fi 6 AX1650i 160MHz Wireless Network Adapter (201NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x02f0 Ta any Ta 0x1652 Ta 22000 Ta iwlwifi-QuZ-a0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x02f0 Ta any Ta 0x2074 Ta 22000 Ta iwlwifi-QuZ-a0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x02f0 Ta any Ta 0x4070 Ta 22000 Ta iwlwifi-QuZ-a0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x06f0 Ta any Ta 0x0070 Ta 22000 Ta iwlwifi-QuZ-a0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x06f0 Ta any Ta 0x0074 Ta 22000 Ta iwlwifi-QuZ-a0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x06f0 Ta any Ta 0x0078 Ta 22000 Ta iwlwifi-QuZ-a0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x06f0 Ta any Ta 0x007c Ta 22000 Ta iwlwifi-QuZ-a0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x06f0 Ta any Ta 0x0310 Ta 22000 Ta iwlwifi-QuZ-a0-hr-b0 +.It "" +.It Killer(R) Wi-Fi 6 AX1650s 160MHz Wireless Network Adapter (201D2W) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x06f0 Ta any Ta 0x1651 Ta 22000 Ta iwlwifi-QuZ-a0-hr-b0 +.It "" +.It Killer(R) Wi-Fi 6 AX1650i 160MHz Wireless Network Adapter (201NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x06f0 Ta any Ta 0x1652 Ta 22000 Ta iwlwifi-QuZ-a0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x06f0 Ta any Ta 0x2074 Ta 22000 Ta iwlwifi-QuZ-a0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x06f0 Ta any Ta 0x4070 Ta 22000 Ta iwlwifi-QuZ-a0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x34f0 Ta any Ta 0x0070 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x34f0 Ta any Ta 0x0074 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x34f0 Ta any Ta 0x0078 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x34f0 Ta any Ta 0x007c Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x34f0 Ta any Ta 0x0310 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Killer(R) Wi-Fi 6 AX1650s 160MHz Wireless Network Adapter (201NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x34f0 Ta any Ta 0x1651 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Killer(R) Wi-Fi 6 AX1650i 160MHz Wireless Network Adapter (201D2W) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x34f0 Ta any Ta 0x1652 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x34f0 Ta any Ta 0x2074 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x34f0 Ta any Ta 0x4070 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x3df0 Ta any Ta 0x0070 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x3df0 Ta any Ta 0x0074 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x3df0 Ta any Ta 0x0078 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x3df0 Ta any Ta 0x007c Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x3df0 Ta any Ta 0x0310 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Killer(R) Wi-Fi 6 AX1650s 160MHz Wireless Network Adapter (201NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x3df0 Ta any Ta 0x1651 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Killer(R) Wi-Fi 6 AX1650i 160MHz Wireless Network Adapter (201D2W) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x3df0 Ta any Ta 0x1652 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x3df0 Ta any Ta 0x2074 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x3df0 Ta any Ta 0x4070 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x4df0 Ta any Ta 0x0070 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x4df0 Ta any Ta 0x0074 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x4df0 Ta any Ta 0x0078 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x4df0 Ta any Ta 0x007c Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x4df0 Ta any Ta 0x0310 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Killer(R) Wi-Fi 6 AX1650s 160MHz Wireless Network Adapter (201NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x4df0 Ta any Ta 0x1651 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Killer(R) Wi-Fi 6 AX1650i 160MHz Wireless Network Adapter (201D2W) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x4df0 Ta any Ta 0x1652 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x4df0 Ta any Ta 0x2074 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x4df0 Ta any Ta 0x4070 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x4df0 Ta any Ta 0x6074 Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6E AX211 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2725 Ta any Ta 0x0090 Ta AX210 Ta iwlwifi-so-a0-gf-a0 +.It "" +.It Intel(R) Wi-Fi 6 AX210 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2725 Ta any Ta 0x0020 Ta AX210 Ta iwlwifi-ty-a0-gf-a0 +.It "" +.It Intel(R) Wi-Fi 6 AX210 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2725 Ta any Ta 0x2020 Ta AX210 Ta iwlwifi-ty-a0-gf-a0 +.It "" +.It Intel(R) Wi-Fi 6 AX210 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2725 Ta any Ta 0x0024 Ta AX210 Ta iwlwifi-ty-a0-gf-a0 +.It "" +.It Intel(R) Wi-Fi 6 AX210 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2725 Ta any Ta 0x0310 Ta AX210 Ta iwlwifi-ty-a0-gf-a0 +.It "" +.It Intel(R) Wi-Fi 6 AX210 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2725 Ta any Ta 0x0510 Ta AX210 Ta iwlwifi-ty-a0-gf-a0 +.It "" +.It Intel(R) Wi-Fi 6 AX210 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2725 Ta any Ta 0x0a10 Ta AX210 Ta iwlwifi-ty-a0-gf-a0 +.It "" +.It Intel(R) Wi-Fi 6 AX210 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2725 Ta any Ta 0xe020 Ta AX210 Ta iwlwifi-ty-a0-gf-a0 +.It "" +.It Intel(R) Wi-Fi 6 AX210 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2725 Ta any Ta 0xe024 Ta AX210 Ta iwlwifi-ty-a0-gf-a0 +.It "" +.It Intel(R) Wi-Fi 6 AX210 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2725 Ta any Ta 0x4020 Ta AX210 Ta iwlwifi-ty-a0-gf-a0 +.It "" +.It Intel(R) Wi-Fi 6 AX210 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2725 Ta any Ta 0x6020 Ta AX210 Ta iwlwifi-ty-a0-gf-a0 +.It "" +.It Intel(R) Wi-Fi 6 AX210 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2725 Ta any Ta 0x6024 Ta AX210 Ta iwlwifi-ty-a0-gf-a0 +.It "" +.It Killer(R) Wi-Fi 6E AX1675w 160MHz Wireless Network Adapter (210D2W) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2725 Ta any Ta 0x1673 Ta AX210 Ta iwlwifi-ty-a0-gf-a0 +.It "" +.It Killer(R) Wi-Fi 6E AX1675x 160MHz Wireless Network Adapter (210NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2725 Ta any Ta 0x1674 Ta AX210 Ta iwlwifi-ty-a0-gf-a0 +.It "" +.It Intel(R) Wi-Fi 6E AX211 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7a70 Ta any Ta 0x0090 Ta AX210 Ta iwlwifi-so-a0-gf-a0 +.It "" +.It Intel(R) Wi-Fi 6E AX211 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7a70 Ta any Ta 0x0098 Ta AX210 Ta iwlwifi-so-a0-gf-a0 +.It "" +.It Intel(R) Wi-Fi 6E AX411 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7a70 Ta any Ta 0x00b0 Ta AX210 Ta iwlwifi-so-a0-gf4-a0 +.It "" +.It Intel(R) Wi-Fi 6E AX211 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7a70 Ta any Ta 0x0310 Ta AX210 Ta iwlwifi-so-a0-gf-a0 +.It "" +.It Intel(R) Wi-Fi 6E AX211 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7a70 Ta any Ta 0x0510 Ta AX210 Ta iwlwifi-so-a0-gf-a0 +.It "" +.It Intel(R) Wi-Fi 6E AX211 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7a70 Ta any Ta 0x0a10 Ta AX210 Ta iwlwifi-so-a0-gf-a0 +.It "" +.It Intel(R) Wi-Fi 6E AX211 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7af0 Ta any Ta 0x0090 Ta AX210 Ta iwlwifi-so-a0-gf-a0 +.It "" +.It Intel(R) Wi-Fi 6E AX211 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7af0 Ta any Ta 0x0098 Ta AX210 Ta iwlwifi-so-a0-gf-a0 +.It "" +.It Intel(R) Wi-Fi 6E AX411 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7af0 Ta any Ta 0x00b0 Ta AX210 Ta iwlwifi-so-a0-gf4-a0 +.It "" +.It Intel(R) Wi-Fi 6E AX211 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7af0 Ta any Ta 0x0310 Ta AX210 Ta iwlwifi-so-a0-gf-a0 +.It "" +.It Intel(R) Wi-Fi 6E AX211 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7af0 Ta any Ta 0x0510 Ta AX210 Ta iwlwifi-so-a0-gf-a0 +.It "" +.It Intel(R) Wi-Fi 6E AX211 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7af0 Ta any Ta 0x0a10 Ta AX210 Ta iwlwifi-so-a0-gf-a0 +.It "" +.It Killer(R) Wireless-AC 1550s Wireless Network Adapter (9560D2W) 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7a70 Ta any Ta 0x1551 Ta iwlwifi Ta iwlwifi-9000-pu-b0-jf-b0 +.It "" +.It Killer(R) Wireless-AC 1550i Wireless Network Adapter (9560NGW) 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7a70 Ta any Ta 0x1552 Ta iwlwifi Ta iwlwifi-9000-pu-b0-jf-b0 +.It "" +.It Killer(R) Wireless-AC 1550s Wireless Network Adapter (9560D2W) 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7af0 Ta any Ta 0x1551 Ta iwlwifi Ta iwlwifi-9000-pu-b0-jf-b0 +.It "" +.It Killer(R) Wireless-AC 1550i Wireless Network Adapter (9560NGW) 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7af0 Ta any Ta 0x1552 Ta iwlwifi Ta iwlwifi-9000-pu-b0-jf-b0 +.It "" +.It Killer(R) Wi-Fi 6E AX1675s 160MHz Wireless Network Adapter (211NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2726 Ta any Ta 0x1671 Ta AX210 Ta iwlwifi-so-a0-gf-a0 +.It "" +.It Killer(R) Wi-Fi 6E AX1675i 160MHz Wireless Network Adapter (211NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2726 Ta any Ta 0x1672 Ta AX210 Ta iwlwifi-so-a0-gf-a0 +.It "" +.It Killer(R) Wi-Fi 6E AX1675s 160MHz Wireless Network Adapter (211NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x51f0 Ta any Ta 0x1671 Ta AX210 Ta iwlwifi-so-a0-gf-a0 +.It "" +.It Killer(R) Wi-Fi 6E AX1675i 160MHz Wireless Network Adapter (211NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x51f0 Ta any Ta 0x1672 Ta AX210 Ta iwlwifi-so-a0-gf-a0 +.It "" +.It Killer(R) Wi-Fi 6E AX1675s 160MHz Wireless Network Adapter (211NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x51f1 Ta any Ta 0x1671 Ta AX210 Ta iwlwifi-so-a0-gf-a0 +.It "" +.It Killer(R) Wi-Fi 6E AX1675i 160MHz Wireless Network Adapter (211NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x51f1 Ta any Ta 0x1672 Ta AX210 Ta iwlwifi-so-a0-gf-a0 +.It "" +.It Killer(R) Wi-Fi 6E AX1675s 160MHz Wireless Network Adapter (211NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x54f0 Ta any Ta 0x1671 Ta AX210 Ta iwlwifi-so-a0-gf-a0 +.It "" +.It Killer(R) Wi-Fi 6E AX1675i 160MHz Wireless Network Adapter (211NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x54f0 Ta any Ta 0x1672 Ta AX210 Ta iwlwifi-so-a0-gf-a0 +.It "" +.It Killer(R) Wi-Fi 6E AX1675s 160MHz Wireless Network Adapter (211NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7a70 Ta any Ta 0x1671 Ta AX210 Ta iwlwifi-so-a0-gf-a0 +.It "" +.It Killer(R) Wi-Fi 6E AX1675i 160MHz Wireless Network Adapter (211NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7a70 Ta any Ta 0x1672 Ta AX210 Ta iwlwifi-so-a0-gf-a0 +.It "" +.It Killer(R) Wi-Fi 6E AX1675s 160MHz Wireless Network Adapter (211NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7af0 Ta any Ta 0x1671 Ta AX210 Ta iwlwifi-so-a0-gf-a0 +.It "" +.It Killer(R) Wi-Fi 6E AX1675i 160MHz Wireless Network Adapter (211NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7af0 Ta any Ta 0x1672 Ta AX210 Ta iwlwifi-so-a0-gf-a0 +.It "" +.It Killer(R) Wi-Fi 6E AX1675s 160MHz Wireless Network Adapter (211NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7f70 Ta any Ta 0x1671 Ta AX210 Ta iwlwifi-so-a0-gf-a0 +.It "" +.It Killer(R) Wi-Fi 6E AX1675i 160MHz Wireless Network Adapter (211NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7f70 Ta any Ta 0x1672 Ta AX210 Ta iwlwifi-so-a0-gf-a0 +.It "" +.It Killer(R) Wi-Fi 6E AX1675s 160MHz Wireless Network Adapter (211NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7e40 Ta any Ta 0x1671 Ta AX210 Ta (null) +.It "" +.It Killer(R) Wi-Fi 6E AX1675i 160MHz Wireless Network Adapter (211NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x7e40 Ta any Ta 0x1672 Ta AX210 Ta (null) +.It "" +.It Intel(R) Wireless-AC 9461 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta iwlwifi Ta iwlwifi-9000-pu-b0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9461 Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta iwlwifi Ta iwlwifi-9000-pu-b0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9462 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta iwlwifi Ta iwlwifi-9000-pu-b0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9462 Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta iwlwifi Ta iwlwifi-9000-pu-b0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9560 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta iwlwifi Ta iwlwifi-9000-pu-b0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9560 Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta iwlwifi Ta iwlwifi-9000-pu-b0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9270 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2526 Ta any Ta any Ta iwlwifi Ta iwlwifi-9260-th-b0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9270 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2526 Ta any Ta any Ta iwlwifi Ta iwlwifi-9260-th-b0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9162 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x271b Ta any Ta any Ta iwlwifi Ta iwlwifi-9260-th-b0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9162 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x271b Ta any Ta any Ta iwlwifi Ta iwlwifi-9260-th-b0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9260 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2526 Ta any Ta any Ta iwlwifi Ta iwlwifi-9260-th-b0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9260 Ta Ta Ta Ta Ta +.It 0x8086 Ta 0x2526 Ta any Ta any Ta iwlwifi Ta iwlwifi-9260-th-b0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9461 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta 22000 Ta iwlwifi-Qu-b0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9461 Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta 22000 Ta iwlwifi-Qu-b0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9462 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta 22000 Ta iwlwifi-Qu-b0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9462 Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta 22000 Ta iwlwifi-Qu-b0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9560 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta 22000 Ta iwlwifi-Qu-b0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9560 Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta 22000 Ta iwlwifi-Qu-b0-jf-b0 +.It "" +.It Killer (R) Wireless-AC 1550s Wireless Network Adapter (9560NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta 0x1551 Ta 22000 Ta iwlwifi-Qu-b0-jf-b0 +.It "" +.It Killer (R) Wireless-AC 1550i Wireless Network Adapter (9560NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta 0x1552 Ta 22000 Ta iwlwifi-Qu-b0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9461 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta 22000 Ta iwlwifi-Qu-c0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9461 Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta 22000 Ta iwlwifi-Qu-c0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9462 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta 22000 Ta iwlwifi-Qu-c0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9462 Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta 22000 Ta iwlwifi-Qu-c0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9560 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta 22000 Ta iwlwifi-Qu-c0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9560 Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta 22000 Ta iwlwifi-Qu-c0-jf-b0 +.It "" +.It Killer (R) Wireless-AC 1550s Wireless Network Adapter (9560NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta 0x1551 Ta 22000 Ta iwlwifi-Qu-c0-jf-b0 +.It "" +.It Killer (R) Wireless-AC 1550i Wireless Network Adapter (9560NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta 0x1552 Ta 22000 Ta iwlwifi-Qu-c0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9461 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta 22000 Ta iwlwifi-QuZ-a0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9461 Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta 22000 Ta iwlwifi-QuZ-a0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9462 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta 22000 Ta iwlwifi-QuZ-a0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9462 Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta 22000 Ta iwlwifi-QuZ-a0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9560 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta 22000 Ta iwlwifi-QuZ-a0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9560 Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta 22000 Ta iwlwifi-QuZ-a0-jf-b0 +.It "" +.It Killer (R) Wireless-AC 1550s Wireless Network Adapter (9560NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta 0x1551 Ta 22000 Ta iwlwifi-QuZ-a0-jf-b0 +.It "" +.It Killer (R) Wireless-AC 1550i Wireless Network Adapter (9560NGW) Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta 0x1552 Ta 22000 Ta iwlwifi-QuZ-a0-jf-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX101 Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX203 Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta 22000 Ta iwlwifi-Qu-b0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX101 Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta 22000 Ta iwlwifi-Qu-c0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX203 Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta 22000 Ta iwlwifi-Qu-c0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta 22000 Ta iwlwifi-Qu-c0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX101 Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta 22000 Ta iwlwifi-QuZ-a0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX203 Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta 22000 Ta iwlwifi-QuZ-a0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta 22000 Ta iwlwifi-QuZ-a0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta AX210 Ta (null) +.It "" +.It Intel(R) Wi-Fi 6E AX211 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta AX210 Ta (null) +.It "" +.It Intel(R) Wi-Fi 6E AX231 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta AX210 Ta (null) +.It "" +.It Intel(R) Wi-Fi 6 AX203 Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta AX210 Ta iwlwifi-so-a0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX101 Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta AX210 Ta iwlwifi-so-a0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6 AX201 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta AX210 Ta iwlwifi-so-a0-hr-b0 +.It "" +.It Intel(R) Wi-Fi 6E AX211 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta AX210 Ta iwlwifi-so-a0-gf-a0 +.It "" +.It Intel(R) Wi-Fi 6E AX411 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta AX210 Ta iwlwifi-so-a0-gf4-a0 +.It "" +.It Intel(R) Wireless-AC 9560 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta AX210 Ta iwlwifi-so-a0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9560 Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta AX210 Ta iwlwifi-so-a0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9461 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta AX210 Ta iwlwifi-so-a0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9462 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta AX210 Ta iwlwifi-so-a0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9461 Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta AX210 Ta iwlwifi-so-a0-jf-b0 +.It "" +.It Intel(R) Wireless-AC 9462 Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta AX210 Ta iwlwifi-so-a0-jf-b0 +.It "" +.It Intel(R) Wi-Fi 7 BE201 320MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta BZ Ta (null) +.It "" +.It Intel(R) Wi-Fi 7 BE200 320MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta BZ Ta (null) +.It "" +.It Intel(R) Wi-Fi 7 BE202 160MHz Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta BZ Ta (null) +.It "" +.It Intel(R) TBD Sc device Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta SC Ta (null) +.It "" +.It Intel(R) TBD Sc2 device Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta SC Ta (null) +.It "" +.It Intel(R) TBD Sc2f device Ta Ta Ta Ta Ta +.It 0x8086 Ta any Ta any Ta any Ta SC Ta (null) +.\" --------------------------------------------------------------------- +.El +.Pp +.Em Note : +some devices can only be determined correctly at run-time +based on hardware registers (or by other special magic not replicated +in the above listing). +.Sh FILES +A copy of the +.Xr iwlwifi 4 +firmware license is installed along with the +.Pa wifi-firmware-iwlwifi-kmod +package or the +.Pa ports/net/wifi-firmware-iwlwifi-kmod +port (or each of its flavors). +.Sh SEE ALSO +.Xr iwlwifi 4 , +.Xr fwget 8 , +.Xr firmware 9 +.Sh HISTORY +The +.Nm +firmware modules first appeared in +.Fx 13.1 +and were removed before +.Fx 14.3 +and replaced by +.Xr ports 7 +based firmware packages. diff --git a/static/freebsd/man4/iwm.4 b/static/freebsd/man4/iwm.4 new file mode 100644 index 00000000..5249959c --- /dev/null +++ b/static/freebsd/man4/iwm.4 @@ -0,0 +1,192 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2004-2006 +.\" Damien Bergamini . 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 unmodified, 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 November 10, 2024 +.Dt IWM 4 +.Os +.Sh NAME +.Nm iwm +.Nd Intel IEEE 802.11ac wireless network driver +.Sh SYNOPSIS +To compile this driver into the kernel, +include the following lines in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device iwm" +.Cd "device pci" +.Cd "device wlan" +.Cd "device firmware" +.Ed +.Pp +You also need to select a firmware for your device. +Choose one from: +.Bd -ragged -offset indent +.Cd "device iwm3160fw" +.Cd "device iwm3168fw" +.Cd "device iwm7260fw" +.Cd "device iwm7265fw" +.Cd "device iwm7265Dfw" +.Cd "device iwm8000Cfw" +.Cd "device iwm8265fw" +.Cd "device iwm9000fw" +.Cd "device iwm9260fw" +.Ed +.Pp +Or you can use +.Bd -ragged -offset indent +.Cd "device iwmfw" +.Ed +.Pp +to include them all. +.Pp +Alternatively, to load the driver as a +module at boot time, place the following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_iwm_load="YES" +iwm3160fw_load="YES" +iwm3168fw_load="YES" +iwm7260fw_load="YES" +iwm7265fw_load="YES" +iwm7265Dfw_load="YES" +iwm8000Cfw_load="YES" +iwm8265fw_load="YES" +iwm9000fw_load="YES" +iwm9260fw_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports running most Intel Wireless AC series network devices in +.Cm station +mode operation. +Only one virtual interface may be configured at any time. +This driver requires the firmware built with the +.Xr iwmfw 4 +module to work. +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports the following PCIe Wi-Fi devices: +.Pp +.Bl -bullet -compact +.It +Intel Dual Band Wireless AC 3160 +.It +Intel Dual Band Wireless AC 3165 +.It +Intel Dual Band Wireless AC 3168 +.It +Intel Dual Band Wireless AC 7260 +.It +Intel Dual Band Wireless AC 7265 +.It +Intel Dual Band Wireless AC 8260 +.It +Intel Dual Band Wireless AC 8265 +.It +Intel Dual Band Wireless AC 9260 +.It +Intel Dual Band Wireless AC 9270 +.It +Intel Dual Band Wireless AC 946X +.It +Intel Dual Band Wireless AC 9560 +.El +.Sh EXAMPLES +Join an existing BSS network (i.e., connect to an access point): +.Pp +.Dl ifconfig wlan create wlandev iwm0 inet 192.0.2.20/24 +.Pp +Join a specific BSS network with network name +.Ar my_net : +.Pp +.Dl ifconfig wlan create wlandev iwm0 ssid my_net up +.Pp +Join a specific BSS network with 64-bit WEP encryption: +.Bd -literal -offset indent +ifconfig wlan create wlandev iwm0 ssid my_net \e + wepmode on wepkey 0x1234567890 weptxkey 1 up +.Ed +.Pp +Join a specific BSS network with 128-bit WEP encryption: +.Bd -literal -offset indent +ifconfig wlan create wlandev iwm0 wlanmode adhoc ssid my_net \e + wepmode on wepkey 0x01020304050607080910111213 weptxkey 1 +.Ed +.Sh DIAGNOSTICS +.Bl -diag +.It "iwm%d: device timeout" +The driver will reset the hardware. +This should not happen. +.It "iwm%d: firmware error" +The onboard microcontroller crashed for some reason. +The driver will reset the hardware. +This should not happen. +.It "iwm%d: timeout waiting for firmware initialization to complete" +The onboard microcontroller failed to initialize in time. +This should not happen. +.It "iwm%d: could not load firmware image '%s'" +The driver failed to load the firmware image using the +.Xr firmware 9 +subsystem. +Verify the +.Xr iwmfw 4 +firmware module is present. +.It "iwm%d: could not load boot firmware" +An attempt to upload the boot firmware image +to the onboard microcontroller failed. +This should not happen. +.It "iwm%d: could not load microcode" +An attempt to upload the microcode image +to the onboard microcontroller failed. +This should not happen. +.It "iwm%d: could not load main firmware" +An attempt to upload the main firmware image +to the onboard microcontroller failed. +This should not happen. +.El +.Sh SEE ALSO +.Xr iwlwifi 4 , +.Xr iwmfw 4 , +.Xr pci 4 , +.Xr wlan 4 , +.Xr wlan_ccmp 4 , +.Xr wlan_tkip 4 , +.Xr wlan_wep 4 , +.Xr networking 7 , +.Xr ifconfig 8 , +.Xr wpa_supplicant 8 +.Sh BUGS +Currently, +.Nm +only supports 802.11a/b/g modes. +It will not associate to access points that are configured to operate +only in 802.11n/ac modes. diff --git a/static/freebsd/man4/iwmfw.4 b/static/freebsd/man4/iwmfw.4 new file mode 100644 index 00000000..7c749f37 --- /dev/null +++ b/static/freebsd/man4/iwmfw.4 @@ -0,0 +1,75 @@ +.\" Copyright (c) 2009 Sam Leffler, Errno Consulting +.\" 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. 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 February 4, 2023 +.Dt IWMFW 4 +.Os +.Sh NAME +.Nm iwmfw +.Nd "Firmware Module for Intel Wireless driver" +.Sh SYNOPSIS +To compile this module into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device iwmfw" +.Ed +.Pp +This will include firmware images for all +.Xr iwm 4 +devices inside the kernel. +If you want to pick only the firmware image for your network adapter choose one +of the following: +.Bd -ragged -offset indent +.Cd "device iwm3160fw" +.Cd "device iwm3168fw" +.Cd "device iwm7260fw" +.Cd "device iwm7265fw" +.Cd "device iwm7265Dfw" +.Cd "device iwm8000Cfw" +.Cd "device iwm8265fw" +.Cd "device iwm9000fw" +.Cd "device iwm9260fw" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place one of the following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +iwm3160fw_load="YES" +iwm3168fw_load="YES" +iwm7260fw_load="YES" +iwm7265fw_load="YES" +iwm7265Dfw_load="YES" +iwm8000Cfw_load="YES" +iwm8265fw_load="YES" +iwm9000fw_load="YES" +iwm9260fw_load="YES" +.Ed +.Sh DESCRIPTION +This module provides access to firmware sets for the +Intel Dual Band Wireless WiFi 3160, 3165, 3168, 7260, 7265, 8000, 8260, 8265, +9000 and 9260 series of IEEE 802.11n/11ac adapters. +It may be statically linked into the kernel, or loaded as a module. +.Sh SEE ALSO +.Xr iwm 4 , +.Xr firmware 9 diff --git a/static/freebsd/man4/iwn.4 b/static/freebsd/man4/iwn.4 new file mode 100644 index 00000000..55692a53 --- /dev/null +++ b/static/freebsd/man4/iwn.4 @@ -0,0 +1,230 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2004-2006 +.\" Damien Bergamini . 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 unmodified, 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 October 17, 2024 +.Dt IWN 4 +.Os +.Sh NAME +.Nm iwn +.Nd Intel IEEE 802.11n wireless network driver +.Sh SYNOPSIS +To compile this driver into the kernel, +include the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device iwn" +.Cd "device pci" +.Cd "device wlan" +.Cd "device firmware" +.Ed +.Pp +You also need to select a firmware for your device. +Choose one from: +.Bd -ragged -offset indent +.Cd "device iwn1000fw" +.Cd "device iwn100fw" +.Cd "device iwn105fw" +.Cd "device iwn135fw" +.Cd "device iwn2000fw" +.Cd "device iwn2030fw" +.Cd "device iwn4965fw" +.Cd "device iwn5000fw" +.Cd "device iwn5150fw" +.Cd "device iwn6000fw" +.Cd "device iwn6000g2afw" +.Cd "device iwn6000g2bfw" +.Cd "device iwn6050fw" +.Ed +.Pp +Or you can use +.Bd -ragged -offset indent +.Cd "device iwnfw" +.Ed +.Pp +to include them all. +.Pp +Alternatively, to load the driver as a +module at boot time, place the following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_iwn_load="YES" +iwn1000fw_load="YES" +iwn100fw_load="YES" +iwn105fw_load="YES" +iwn135fw_load="YES" +iwn2000fw_load="YES" +iwn2030fw_load="YES" +iwn4965fw_load="YES" +iwn5000fw_load="YES" +iwn5150fw_load="YES" +iwn6000fw_load="YES" +iwn6000g2afw_load="YES" +iwn6000g2bfw_load="YES" +iwn6050fw_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports +.Cm station +and +.Cm monitor +mode operation. +Only one virtual interface may be configured at any time. +For more information on configuring this device, see +.Xr ifconfig 8 . +.Pp +This driver requires the firmware built with the +.Nm iwnfw +module to work. +.Sh HARDWARE +The +.Nm +driver provides support for: +.Pp +.Bl -bullet -compact +.It +Intel Centrino Advanced-N 6200 +.It +Intel Centrino Advanced-N 6205 +.It +Intel Centrino Advanced-N 6230 +.It +Intel Centrino Advanced-N 6235 +.It +Intel Centrino Advanced-N + WiMAX 6250 +.It +Intel Centrino Ultimate-N 6300 +.It +Intel Centrino Wireless-N 100 +.It +Intel Centrino Wireless-N 105 +.It +Intel Centrino Wireless-N 130 +.It +Intel Centrino Wireless-N 135 +.It +Intel Centrino Wireless-N 1000 +.It +Intel Centrino Wireless-N 1030 +.It +Intel Centrino Wireless-N 2200 +.It +Intel Centrino Wireless-N 2230 +.It +Intel Centrino Wireless-N 4965 +.It +Intel Centrino Wireless-N 5100 +.It +Intel Centrino Wireless-N 6150 +.It +Intel Centrino Wireless-N 6200 +.It +Intel Centrino Wireless-N 6250 +.It +Intel Centrino Wireless-N + WiMAX 6150 +.It +Intel Ultimate N WiFi Link 5300 +.It +Intel Wireless WiFi Link 4965 +.It +Intel WiFi Link 5100 +.It +Intel WiMAX/WiFi Link 5150 +.It +Intel WiMAX/WiFi Link 5350 +.El +.Sh EXAMPLES +Join an existing BSS network (i.e., connect to an access point): +.Bd -literal -offset indent +# ifconfig wlan create wlandev iwn0 inet 192.168.0.20 \e + netmask 0xffffff00 +.Ed +.Pp +Join a specific BSS network with network name +.Ql my_net : +.Pp +.Dl # ifconfig wlan create wlandev iwn0 ssid my_net up +.Pp +Join a specific BSS network with 64-bit WEP encryption: +.Bd -literal -offset indent +# ifconfig wlan create wlandev iwn0 ssid my_net \e + wepmode on wepkey 0x1234567890 weptxkey 1 up +.Ed +.Pp +Join a specific BSS network with 128-bit WEP encryption: +.Bd -literal -offset indent +# ifconfig wlan create wlandev iwn0 wlanmode adhoc ssid my_net \e + wepmode on wepkey 0x01020304050607080910111213 weptxkey 1 +.Ed +.Sh DIAGNOSTICS +.Bl -diag +.It "iwn%d: device timeout" +The driver will reset the hardware. +This should not happen. +.It "iwn%d: firmware error" +The onboard microcontroller crashed for some reason. +The driver will reset the hardware. +This should not happen. +.It "iwn%d: timeout waiting for firmware initialization to complete" +The onboard microcontroller failed to initialize in time. +This should not happen. +.It "iwn%d: could not load firmware image '%s'" +The driver failed to load the firmware image using the +.Xr firmware 9 +subsystem. +Verify the +.Xr iwnfw 4 +firmware module is present. +.It "iwn%d: could not load boot firmware" +An attempt to upload the boot firmware image to the onboard microcontroller +failed. +This should not happen. +.It "iwn%d: could not load microcode" +An attempt to upload the microcode image to the onboard microcontroller failed. +This should not happen. +.It "iwn%d: could not load main firmware" +An attempt to upload the main firmware image to the onboard microcontroller +failed. +This should not happen. +.El +.Sh SEE ALSO +.Xr iwnfw 4 , +.Xr pci 4 , +.Xr wlan 4 , +.Xr wlan_ccmp 4 , +.Xr wlan_tkip 4 , +.Xr wlan_wep 4 , +.Xr networking 7 , +.Xr ifconfig 8 , +.Xr wpa_supplicant 8 +.Sh AUTHORS +The original +.Nm +driver was written by +.An Damien Bergamini Aq Mt damien.bergamini@free.fr . diff --git a/static/freebsd/man4/iwnfw.4 b/static/freebsd/man4/iwnfw.4 new file mode 100644 index 00000000..67101f51 --- /dev/null +++ b/static/freebsd/man4/iwnfw.4 @@ -0,0 +1,84 @@ +.\" Copyright (c) 2009 Sam Leffler, Errno Consulting +.\" 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. 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 August 30, 2014 +.Dt IWNFW 4 +.Os +.Sh NAME +.Nm iwnfw +.Nd "Firmware Module for Intel Wireless driver" +.Sh SYNOPSIS +To compile this module into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device iwnfw" +.Ed +.Pp +This will include firmware images for all +.Xr iwn 4 +devices inside the kernel. +If you want to pick only the firmware image for your network adapter choose one +of the following: +.Bd -ragged -offset indent +.Cd "device iwn1000fw" +.Cd "device iwn100fw" +.Cd "device iwn105fw" +.Cd "device iwn135fw" +.Cd "device iwn2000fw" +.Cd "device iwn2030fw" +.Cd "device iwn4965fw" +.Cd "device iwn5000fw" +.Cd "device iwn5150fw" +.Cd "device iwn6000fw" +.Cd "device iwn6000g2afw" +.Cd "device iwn6000g2bfw" +.Cd "device iwn6050fw" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +iwn1000fw_load="YES" +iwn100fw_load="YES" +iwn105fw_load="YES" +iwn135fw_load="YES" +iwn2000fw_load="YES" +iwn2030fw_load="YES" +iwn4965fw_load="YES" +iwn5000fw_load="YES" +iwn5150fw_load="YES" +iwn6000fw_load="YES" +iwn6000g2afw_load="YES" +iwn6000g2bfw_load="YES" +iwn6050fw_load="YES" +.Ed +.Sh DESCRIPTION +This module provides access to firmware sets for the +Intel Wireless WiFi Link 100, 105, 135, 1000, 2000, 2030, 4965, 5000 and 6000 series of +IEEE 802.11n adapters. +It may be +statically linked into the kernel, or loaded as a module. +.Sh SEE ALSO +.Xr iwn 4 , +.Xr firmware 9 diff --git a/static/freebsd/man4/iwx.4 b/static/freebsd/man4/iwx.4 new file mode 100644 index 00000000..5f978b21 --- /dev/null +++ b/static/freebsd/man4/iwx.4 @@ -0,0 +1,160 @@ +.\" +.\" SPDX-License-Identifier: ISC +.\" +.\" $OpenBSD: iwx.4,v 1.21 2025/03/27 15:12:14 jmc Exp $ +.\" +.\" Copyright (c) 2020 Stefan Sperling +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd November 14, 2025 +.Dt IWX 4 amd64 +.Os +.Sh NAME +.Nm iwx +.Nd Intel WiFi 6 IEEE 802.11ax wireless network driver +.Sh SYNOPSIS +To compile this driver into the kernel, +include the following lines in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device iwx" +.Cd "device pci" +.Cd "device wlan" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_iwx_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports the Intel Wi-Fi 6 series of M.2 +wireless network adapters. +If the appropriate hardware is detected, and +.Xr iwlwifi 4 +is blacklisted in +.Xr rc.conf 5 , +the driver will be automatically loaded with +.Xr devmatch 8 . +The +.Nm +driver can be configured at runtime with +.Xr ifconfig 8 +or at boot with +.Xr rc.conf 5 . +.Pp +These are the modes the +.Nm +driver can operate in: +.Bl -tag -width "monitor mode" +.It station mode +This is used when associating with an access point, +through which all traffic passes. +Background scanning is supported in this mode, see +.Xr ifconfig 8 . +Station mode is the default. +.It monitor mode +In this mode the driver is able to receive packets without +associating with an access point. +This disables the internal receive filter and enables the card to +capture packets from networks which it wouldn't normally have access to, +or to scan for access points. +.El +.Sh HARDWARE +The +.Nm +driver supports the following M.2 wireless network adapters: +.Pp +.Bl -bullet -offset indent -compact +.It +Intel Wi-Fi 6 AX200 +.It +Intel Wi-Fi 6 AX201 CNVi +.It +Intel Wi-Fi 6 AX210 +.It +Intel Wi-Fi 6 AX211 CNVi +.El +.Sh SYSCTL VARIABLES +The +.Nm +driver supports the following +.Xr sysctl 8 +variables: +.Bl -tag -width "hw.usb.mtw.debug" +.It Va dev.iwx.?.debug +Specify debug level as a bitmask. +Default +.Ql 0 . +.El +.Sh FILES +The +.Nm +driver requires firmware from +.Pa ports/net/wifi-firmware-iwlwifi-kmod . +This firmware package will be installed automatically with +.Xr fwget 8 +if the appropriate hardware is detected at installation or runtime. +.Sh DIAGNOSTICS +.Bl -diag +.It "iwx0: device timeout" +A frame dispatched to the hardware for transmission did not complete +in time. +The driver will reset the hardware. +This should not happen. +.It "iwx0: fatal firmware error" +For some reason, the firmware crashed. +The driver will reset the hardware. +This should not happen. +.It "iwx0: radio is disabled by hardware switch" +The radio transmitter is off and thus no packet can go out. +The driver will reset the hardware. +Make sure the laptop radio switch is on. +.It "iwx0: could not read firmware ... (error N)" +For some reason, the driver was unable to read the firmware image from +the filesystem. +The file might be missing or corrupted. +.It "iwx0: firmware too short: N bytes" +The firmware image is corrupted and can't be loaded into the adapter. +.It "iwx0: could not load firmware" +An attempt to load the firmware into the adapter failed. +The driver will reset the hardware. +.El +.Sh SEE ALSO +.Xr intro 4 , +.Xr iwlwifi 4 , +.Xr iwlwififw 4 , +.Xr wlan 4 , +.Xr networking 7 , +.Xr fwget 8 , +.Xr ifconfig 8 , +.Xr wpa_supplicant 8 +.Sh HISTORY +The +.Nm +driver appeared in +.Fx 15.0 . +.Sh CAVEATS +The +.Nm +driver does not support hardware encryption offload. +.Pp +The +.Nm +driver does not support 802.11ax. +Additional work is required in +.Xr ieee80211 9 +before those features can be supported. diff --git a/static/freebsd/man4/ix.4 b/static/freebsd/man4/ix.4 new file mode 100644 index 00000000..39ed49aa --- /dev/null +++ b/static/freebsd/man4/ix.4 @@ -0,0 +1,242 @@ +.\" Copyright (c) 2001-2008, Intel Corporation +.\" 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. Neither the name of the Intel Corporation nor the names of its +.\" contributors may be used to endorse or promote products derived from +.\" this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 COPYRIGHT OWNER 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. +.\" +.\" * Other names and brands may be claimed as the property of others. +.\" +.Dd November 10, 2025 +.Dt IX 4 +.Os +.Sh NAME +.Nm ix +.Nd Intel 10Gb Ethernet driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device iflib" +.Cd "device ix" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_ix_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for Intel(R) 10Gb Ethernet PCIe adapters. +The driver supports Jumbo Frames, MSIX, TSO, and RSS. +.Pp +For questions related to hardware requirements, +refer to the documentation supplied with your Intel 10GbE adapter. +All hardware requirements listed apply to use with +.Fx . +.Pp +Support for Jumbo Frames is provided via the interface MTU setting. +Selecting an MTU larger than 1500 bytes with the +.Xr ifconfig 8 +utility configures the adapter to receive and transmit Jumbo Frames. +The maximum MTU size for Jumbo Frames is 9710. +.Pp +This driver version supports VLANs. +For information on enabling VLANs, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports Intel 10Gb Ethernet PCIe adapters, +including: +.Pp +.Bl -bullet -compact +.It +Intel(R) Ethernet E610 +.It +Intel(R) Ethernet X553 +.It +Intel(R) Ethernet X552 +.It +Intel(R) Ethernet X550 +.It +Intel(R) Ethernet X540 Bypass +.It +Intel(R) Ethernet X540 +.It +Intel(R) Ethernet X520 Bypass (82599) +.It +Intel(R) Ethernet X520 (82599) +.It +Intel(R) 10 Gigabit Server Adapter (82598EB) +.El +.Sh LOADER TUNABLES +The +.Nm +driver supports the following loader tunables: +.Bl -tag -width "hw.ix.allow_unsupported_sfp" +.It Va hw.ix.max_interrupt_rate +Maximum interrupts per second. +.It Va hw.ix.flow_control +Default flow control used for all adapters. +.It Va hw.ix.advertise_speed +Default advertised speed for all adapters. +.It Va hw.ix.enable_msix +Enable Message Signalled Interrupts (MSI-X). +.It Va hw.ix.allow_unsupported_sfp +Allow unsupported small form-factor pluggable +.Pq SFP +modules. +Use at your own risk. +.It Va hw.ix.enable_fdir +Enable Flow Director. +Flow Director directs Ethernet packets to the core where the +packet consuming process, application, container, +or microservice is running. +.It Va hw.ix.enable_rss +Enable Receive-Side Scaling (RSS). +When RSS is enabled, all of the receive data processing for +a particular TCP connection is shared across multiple processors +or processor cores. +Without RSS, all of the processing is performed by a single +processor, resulting in inefficient system cache utilization. +This has no effect if your system has only one processing unit. +.It Va hw.ix.enable_aim +Enable Adaptive Interrupt Moderation (AIM). +Vary the interrupt rate over time based on the traffic for +that interrupt vector. +.El +.Sh SYSCTL VARIABLES +The +.Nm +driver supports the following +.Xr sysctl 8 +variables: +.Bl -tag -width "dev.ix.?.debug.fw_log.severity." +.It Va dev.ix.?.debug.dump.clusters +Specify a bitmask to select firmware event clusters +to be included in the debug dump. +Possible values include: +.Pp +.Bl -tag -compact +.It 0 +All clusters excluding Manageability Transactions +.It 0x1 +Link cluster +.It 0x2 +Full CSR Space excluding RCW registers +.El +.Pp +This feature is only supported on E610 devices. +.It Va dev.ix.?.debug.dump.dump +Specify 1 to generate a per-device debugging snapshot. +Output must be redirected to a file +and decoded by Intel Customer Support. +.Pp +This feature is only supported on E610. +.It Va dev.ix.?.debug.fw_log.severity. +Specify firmware logging verbosity level for the specified module. +Available levels include: +.Pp +.Bl -tag -compact +.It 0 +none +.It 1 +error +.It 2 +warning +.It 3 +normal +.It 4 +verbose +.El +.Pp +Supported modules: general, ctrl, link, link_topo, dnl, i2c, sdp, mdio, +adminq, hdma, lldp, dcbx, dcb, xlr, nvm, auth, vpd, iosf, parser, sw, +scheduler, txq, acl, post, watchdog, task_dispatch, mng, synce, health, +tsdrv, pfreg, mdlver. +.Pp +This feature is only supported on E610 devices. +.It Va dev.ix.?.debug.fw_log.register +Specify 1 to apply per-device firmware logging configuration. +.Pp +This feature is only supported on E610 devices. +.It Va dev.ix.?.debug.fw_log.on_load +Enable firmware logging during driver initialization when set via +.Xr kenv 1 . +.Pp +This feature is only supported on E610 devices. +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "ix%d: Unable to allocate bus resource: memory" +A fatal initialization error has occurred. +.It "ix%d: Unable to allocate bus resource: interrupt" +A fatal initialization error has occurred. +.It "ix%d: watchdog timeout -- resetting" +The device has stopped responding to the network, or there is a problem with +the network connection (cable). +.El +.Sh SUPPORT +For general information and support, +go to the Intel support website at: +.Pa http://support.intel.com . +.Pp +If an issue is identified with the released source code on the supported kernel +with a supported adapter, email the specific information related to the +issue to +.Aq Mt freebsd@intel.com . +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr iflib 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr polling 4 , +.Xr vlan 4 , +.Xr ifconfig 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 7.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Intel Corporation Aq Mt freebsd@intel.com . +.Sh CAVEATS +Intel (R) Flow director support is not fully implemented in +.Fx +at this time and additional work is required +before those features can be supported. +.Pp +Enabling flow director may route traffic to the wrong RX queue of the NIC, +resulting in sub-optimal performance on the receive side. diff --git a/static/freebsd/man4/ixl.4 b/static/freebsd/man4/ixl.4 new file mode 100644 index 00000000..fb9d519b --- /dev/null +++ b/static/freebsd/man4/ixl.4 @@ -0,0 +1,308 @@ +.\" Copyright (c) 2013-2018, Intel Corporation +.\" 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. Neither the name of the Intel Corporation nor the names of its +.\" contributors may be used to endorse or promote products derived from +.\" this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 COPYRIGHT OWNER 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. +.\" +.\" * Other names and brands may be claimed as the property of others. +.\" +.Dd August 1, 2023 +.Dt IXL 4 +.Os +.Sh NAME +.Nm ixl +.Nd "Intel Ethernet 700 Series Driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device iflib" +.Cd "device ixl" +.Ed +.Pp +To load the driver as a module at boot time, place the following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_ixl_load="YES" +.Ed +.Sh DESCRIPTION +.Ss Features +The +.Nm +driver provides support for any PCI Express adapter or LOM +(LAN On Motherboard) +in the Intel Ethernet 700 Series. +As of this writing, the series includes devices with these model numbers: +.Pp +.Bl -bullet -compact +.It +XL710 (40G) +.It +X710 (10G) +.It +XXV710 (25G) +.It +X722 (10G) +.El +.Pp +The driver supports Jumbo Frames, TX/RX checksum offload, +TCP segmentation offload (TSO), Large Receive Offload (LRO), VLAN +tag insertion/extraction, VLAN checksum offload, VLAN TSO, and +Receive Side Steering (RSS), all for both IPv4 and IPv6. +For further hardware information and questions related to hardware +requirements, see +.Lk http://support.intel.com/ . +.Pp +Support for Jumbo Frames is provided via the interface MTU setting. +Selecting an MTU larger than 1500 bytes with the +.Xr ifconfig 8 +utility configures the adapter to receive and transmit Jumbo Frames. +The maximum MTU size for Jumbo Frames is 9706. +.Pp +Offloads are also controlled via the interface, for instance, +checksumming for both IPv4 and IPv6 can be set and unset, TSO4 +and/or TSO6, and finally LRO can be set and unset. +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Ss Additional Utilities +There are additional tools available from Intel to help configure and update +the adapters covered by this driver. +These tools can be downloaded directly from Intel at +.Lk https://downloadcenter.intel.com , +by searching for their names, or by installing certain packages: +.Bl -bullet +.It +To change the behavior of the QSFP+ ports on XL710 adapters, use the +Intel QCU (QSFP+ configuration utility); installed by the +.Em sysutils/intel-qcu +package. +.It +To update the firmware on an adapter, use the Intel Non-Volatile Memory (NVM) +Update Utility; installed by the +.Em sysutils/intel-nvmupdate-10g , +.Em sysutils/intel-nvmupdate-40g , +or +.Em sysutils/intel-nvmupdate-100g , +package. +.It +Drivers are provided by Intel outside of the +.Fx +kernel; install the +.Em net/intel-ixl-kmod +package for the latest driver. +.El +.Sh HARDWARE +The +.Nm +driver supports the Intel Ethernet 700 series. +Most adapters in this series with SFP+/SFP28/QSFP+ cages +have firmware that requires that Intel qualified modules are used; these +qualified modules are listed below. +This qualification check cannot be disabled by the driver. +.Pp +The +.Nm +driver supports 40Gb Ethernet adapters with these QSFP+ modules: +.Pp +.Bl -bullet -compact +.It +Intel 4x10G/40G QSFP+ 40GBASE-SR4 E40GQSFPSR +.It +Intel 4x10G/40G QSFP+ 40GBASE-LR4 E40GQSFPLR +.El +.Pp +The +.Nm +driver supports 25Gb Ethernet adapters with these SFP28 modules: +.Pp +.Bl -bullet -compact +.It +Intel 10G/25G SFP28 25GBASE-SR E25GSFP28SR +.It +Intel 10G/25G SFP28 25GBASE-SR E25GSFP28SRX (Extended Temp) +.El +.Pp +The +.Nm +driver supports 25Gb and 10Gb Ethernet adapters with these SFP+ modules: +.Pp +.Bl -bullet -compact +.It +Intel 1G/10G SFP+ SR FTLX8571D3BCV-IT +.It +Intel 1G/10G SFP+ SR AFBR-703SDZ-IN2 +.It +Intel 1G/10G SFP+ LR FTLX1471D3BCV-IT +.It +Intel 1G/10G SFP+ LR AFCT-701SDZ-IN2 +.It +Intel 1G/10G SFP+ 10GBASE-SR E10GSFPSR +.It +Intel 10G SFP+ 10GBASE-SR E10GSFPSRX (Extended Temp) +.It +Intel 1G/10G SFP+ 10GBASE-LR E10GSFPLR +.El +.Pp +Note that adapters also support all passive and active +limiting direct attach cables that comply with SFF-8431 v4.1 and +SFF-8472 v10.4 specifications. +.Pp +This is not an exhaustive list; please consult product documentation for an +up-to-date list of supported media. +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width indent +.It Va hw.ixl.rx_itr +The RX interrupt rate value, set to 62 (124 usec) by default. +.It Va hw.ixl.tx_itr +The TX interrupt rate value, set to 122 (244 usec) by default. +.It Va hw.ixl.i2c_access_method +Access method that driver will use for I2C read and writes via +.Xr sysctl 8 +or verbose +.Xr ifconfig 8 +information display: +.Bd -literal -offset indent +0 - best available method +1 - bit bang via I2CPARAMS register +2 - register read/write via I2CCMD register +3 - Use Admin Queue command (default best) +.Ed +.Pp +Using the Admin Queue is only supported on 710 devices with FW version 1.7 or +newer. +Set to 0 by default. +.It Va hw.ixl.enable_tx_fc_filter +Filter out packets with Ethertype 0x8808 from being sent out by non-adapter +sources. +This prevents (potentially untrusted) software or +.Xr iavf 4 +devices from sending out flow control packets and creating a DoS (Denial of +Service) event. +Enabled by default. +.It Va hw.ixl.enable_head_writeback +When the driver is finding the last TX descriptor processed by the hardware, +use a value written to memory by the hardware instead of scanning the +descriptor ring for completed descriptors. +Enabled by default; disable to mimic the TX behavior found in +.Xr ix 4 . +.El +.Sh SYSCTL PROCEDURES +.Bl -tag -width indent +.It Va dev.ixl.#.fc +Sets the 802.3x flow control mode that the adapter will advertise on the link. +A value of 0 disables flow control, 3 enables full, 1 is RX, and 2 is TX pause. +.Pp +The negotiated flow control setting can be viewed in +.Xr ifconfig 8 , +in the interface's media field. +.It Va dev.ixl.#.advertise_speed +Set the speeds that the interface will advertise on the link. +.Va dev.ixl.#.supported_speeds +contains the speeds that are allowed to be set. +.It Va dev.ixl.#.current_speed +Displays the current speed. +.It Va dev.ixl.#.fw_version +Displays the current firmware and NVM versions of the adapter. +.It Va dev.ixl.#.debug.switch_vlans +Set the Ethertype used by the hardware itself to handle internal +services. +Frames with this Ethertype will be dropped without notice. +Defaults to +.Dv 0x88a8 , +which is a well known number for IEEE 802.1ad VLAN stacking. +If you need 802.1ad support, set this number to any another Ethertype i.e. +.Dv 0xffff . +.El +.Sh INTERRUPT STORMS +It is important to note that 40G operation can generate high +numbers of interrupts, often incorrectly being interpreted as +a storm condition in the kernel. +It is suggested that this be resolved by setting: +.Bl -tag -width indent +.It Va hw.intr_storm_threshold: 0 +.El +.Sh IOVCTL OPTIONS +The driver supports additional optional parameters for created VFs +(Virtual Functions) when using +.Xr iovctl 8 : +.Bl -tag -width indent +.It mac-addr Pq unicast-mac +Set the Ethernet MAC address that the VF will use. +If unspecified, the VF will use a randomly generated MAC address. +.It mac-anti-spoof Pq bool +Prevent the VF from sending Ethernet frames with a source address +that does not match its own. +.It allow-set-mac Pq bool +Allow the VF to set its own Ethernet MAC address +.It allow-promisc Pq bool +Allow the VF to inspect all of the traffic sent to the port. +.It num-queues Pq uint16_t +Specify the number of queues the VF will have. +By default, this is set to the number of MSI-X vectors supported by the VF +minus one. +.El +.Pp +An up to date list of parameters and their defaults can be found by using +.Xr iovctl 8 +with the -S option. +.Sh SUPPORT +For general information and support, +go to the Intel support website at: +.Lk http://support.intel.com/ . +.Pp +If an issue is identified with this driver with a supported adapter, +email all the specific information related to the issue to +.Mt freebsd@intel.com . +.Sh SEE ALSO +.Xr arp 4 , +.Xr iavf 4 , +.Xr iflib 4 , +.Xr netintro 4 , +.Xr vlan 4 , +.Xr ifconfig 8 , +.Xr iovctl 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 10.1 . +It was converted to use +.Xr iflib 9 +in +.Fx 12 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Jack Vogel Aq Mt jfv@freebsd.org +and +.An Eric Joyner Aq Mt erj@freebsd.org . diff --git a/static/freebsd/man4/jedec_dimm.4 b/static/freebsd/man4/jedec_dimm.4 new file mode 100644 index 00000000..db11931e --- /dev/null +++ b/static/freebsd/man4/jedec_dimm.4 @@ -0,0 +1,251 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2016 Andriy Gapon +.\" Copyright (c) 2018 Ravi Pokala +.\" +.\" 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 ``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 January 2, 2026 +.Dt JEDEC_DIMM 4 +.Os +.Sh NAME +.Nm jedec_dimm +.Nd report asset information and temperatures for JEDEC DDR3 / DDR4 DIMMs +.Sh SYNOPSIS +.Bd -ragged -offset indent +.Cd "device jedec_dimm" +.Cd "device smbus" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the following +line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +jedec_dimm_load="YES" +.Ed +.Pp +Addressing information must be manually specified in +.Pa /boot/device.hints : +.Bd -literal -offset indent +.Cd hint.jedec_dimm.0.at="smbus0" +.Cd hint.jedec_dimm.0.addr="0xa0" +.Cd hint.jedec_dimm.0.slotid="Silkscreen" +.Ed +.Sh DESCRIPTION +The +.Nm +driver reports asset information (Part Number, Serial Number) encoded in the +.Dq Serial Presence Detect +(SPD) data on JEDEC DDR3 and DDR4 DIMMs. +It also calculates and reports the memory capacity of the DIMM, in megabytes. +If the DIMM includes a +.Dq Thermal Sensor On DIMM +(TSOD), the temperature is also reported. +.Pp +The +.Nm +driver accesses the SPD and TSOD over the +.Xr smbus 4 . +.Pp +The data is reported via a +.Xr sysctl 8 +interface; all values are read-only: +.Bl -tag -width "dev.jedec_dimm.X.capacity" +.It Va dev.jedec_dimm.X.%desc +a string description of the DIMM, including TSOD and slotid info if present. +.It Va dev.jedec_dimm.X.capacity +the DIMM's memory capacity, in megabytes +.It Va dev.jedec_dimm.X.mfg_week +the week within the year in which the DIMM was manufactured +.It Va dev.jedec_dimm.X.mfg_year +the year in which the DIMM was manufactured +.It Va dev.jedec_dimm.X.part +the manufacturer's part number of the DIMM +.It Va dev.jedec_dimm.X.serial +the manufacturer's serial number of the DIMM +.It Va dev.jedec_dimm.X.slotid +a copy of the corresponding hint, if set +.It Va dev.jedec_dimm.X.temp +if a TSOD is present, the reported temperature +.It Va dev.jedec_dimm.X.type +the DIMM type (DDR3 or DDR4) +.El +.Pp +These values are configurable for +.Nm +via +.Xr device.hints 5 : +.Bl -tag -width "hint.jedec_dimm.X.slotid" +.It Va hint.jedec_dimm.X.at +the +.Xr smbus 4 +to which the DIMM is connected +.It Va hint.jedec_dimm.X.addr +the SMBus address of the SPD. +JEDEC specifies that the four most-significant bits of the address are the +.Dq Device Type Identifier +(DTI), and that the DTI of the SPD is 0xa. +Since the least-significant bit of an SMBus address is the read/write bit, and +is always written as 0, that means the four least-significant bits of the +address must be even. +.It Va hint.jedec_dimm.X.slotid +optional slot identifier. +If populated with the DIMM slot name silkscreened on the motherboard, this +provides a mapping between the DIMM slot name and the DIMM serial number. +That mapping is useful for detailed asset tracking, and makes it easier to +physically locate a specific DIMM when doing a replacement. +This is useful when assembling multiple identical systems, as might be done by +a system vendor. +The mapping between bus/address and DIMM slot must first be determined, either +through motherboard documentation or trial-and-error. +.El +.Pp +If the DIMMs are on an I2C bus behind an +.Xr iicbus 4 +controller, then the +.Xr iicsmb 4 +bridge driver can be used to attach the +.Xr smbus 4 . +.Sh EXAMPLES +Consider two DDR4 DIMMs with the following hints: +.Bd -literal -offset indent +hint.jedec_dimm.0.at="smbus0" +hint.jedec_dimm.0.addr="0xa0" +hint.jedec_dimm.0.slotid="A1" + +hint.jedec_dimm.6.at="smbus1" +hint.jedec_dimm.6.addr="0xa8" +.Ed +.Pp +Their +.Xr sysctl 8 +output (sorted): +.Bd -literal -offset indent +dev.jedec_dimm.0.%desc: DDR4 DIMM w/ Atmel TSOD (A1) +dev.jedec_dimm.0.%driver: jedec_dimm +dev.jedec_dimm.0.%location: addr=0xa0 +dev.jedec_dimm.0.%parent: smbus0 +dev.jedec_dimm.0.%pnpinfo: +dev.jedec_dimm.0.capacity: 16384 +dev.jedec_dimm.0.mfg_week: 30 +dev.jedec_dimm.0.mfg_year: 17 +dev.jedec_dimm.0.part: 36ASF2G72PZ-2G1A2 +dev.jedec_dimm.0.serial: 0ea815de +dev.jedec_dimm.0.slotid: A1 +dev.jedec_dimm.0.temp: 32.7C +dev.jedec_dimm.0.type: DDR4 + +dev.jedec_dimm.6.%desc: DDR4 DIMM w/ TSE2004av compliant TSOD +dev.jedec_dimm.6.%driver: jedec_dimm +dev.jedec_dimm.6.%location: addr=0xa8 +dev.jedec_dimm.6.%parent: smbus1 +dev.jedec_dimm.6.%pnpinfo: +dev.jedec_dimm.6.capacity: 8192 +dev.jedec_dimm.6.mfg_week: 13 +dev.jedec_dimm.6.mfg_year: 19 +dev.jedec_dimm.6.part: VRA9MR8B2H1603 +dev.jedec_dimm.6.serial: 0c4c46ad +dev.jedec_dimm.6.temp: 43.1C +dev.jedec_dimm.6.type: DDR4 +.Ed +.Pp +You can use +.Xr smbmsg 8 +to probe for devices. +.Sh COMPATIBILITY +.Nm +implements a superset of the functionality of the now-deleted +.Xr jedec_ts 4 . +Hints for +.Xr jedec_ts 4 +can be mechanically converted for use with +.Nm . +Two changes are required: +.Bl -enum +.It +In all +.Xr jedec_ts 4 +hints, replace +.Dq jedec_ts +with +.Dq jedec_dimm +.It +In +.Xr jedec_ts 4 +.Dq addr +hints, replace the TSOD DTI +.Dq 0x3 +with the SPD DTI +.Dq 0xa +.El +.Pp +The following +.Xr sed 1 +script will perform the necessary changes: +.Bd -literal -offset indent +sed -i ".old" -e 's/jedec_ts/jedec_dimm/' \\ + -e '/jedec_dimm/s/addr="0x3/addr="0xa/' /boot/device.hints +.Ed +.Sh SEE ALSO +.Xr iicbus 4 , +.Xr iicsmb 4 , +.Xr smbus 4 , +.Xr sysctl 8 +.Sh STANDARDS +.Rs +(DDR3 SPD) +.%A JEDEC +.%T Standard 21-C, Annex K +.Re +.Pp +.Rs +(DDR3 TSOD) +.%A JEDEC +.%T Standard 21-C, TSE2002av +.Re +.Pp +.Rs +(DDR4 SPD) +.%A JEDEC +.%T Standard 21-C, Annex L +.Re +.Pp +.Rs +(DDR4 TSOD) +.%A JEDEC +.%T Standard 21-C, TSE2004av +.Re +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 12.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver and this manual page were written by +.An Ravi Pokala Aq Mt rpokala@freebsd.org . +They are both based in part on the now-deleted +.Xr jedec_ts 4 +driver and manual page, written by +.An Andriy Gapon Aq Mt avg@FreeBSD.org . diff --git a/static/freebsd/man4/jme.4 b/static/freebsd/man4/jme.4 new file mode 100644 index 00000000..097c827c --- /dev/null +++ b/static/freebsd/man4/jme.4 @@ -0,0 +1,194 @@ +.\" Copyright (c) 2008 Pyun YongHyeon +.\" 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 March 4, 2012 +.Dt JME 4 +.Os +.Sh NAME +.Nm jme +.Nd JMicron Gigabit/Fast Ethernet driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device jme" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_jme_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +device driver provides support for JMicron JMC25x PCI Express +Gigabit Ethernet controllers and JMicron JMC26x PCI Express Fast +Ethernet controllers. +.Pp +All LOMs supported by the +.Nm +driver have TCP/UDP/IP checksum offload for both transmit and receive, +TCP segmentation offload (TSO), hardware VLAN tag stripping/insertion +features, Wake On Lan (WOL) and an interrupt coalescing/moderation +mechanism as well as a 64-bit multicast hash filter. +.Pp +The JMC25x also supports Jumbo Frames (up to 9216 bytes), which can be +configured via the interface MTU setting. +Selecting an MTU larger than 1500 bytes with the +.Xr ifconfig 8 +utility configures the adapter to receive and transmit Jumbo Frames. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width ".Cm 10baseT/UTP" +.It Cm autoselect +Enable autoselection of the media type and options. +The user can manually override +the autoselected mode by adding media options to +.Xr rc.conf 5 . +.It Cm 10baseT/UTP +Set 10Mbps operation. +.It Cm 100baseTX +Set 100Mbps (Fast Ethernet) operation. +.It Cm 1000baseTX +Set 1000baseTX operation over twisted pair. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width ".Cm full-duplex" +.It Cm full-duplex +Force full duplex operation. +.It Cm half-duplex +Force half duplex operation. +.El +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +device driver provides support for the following Ethernet controllers: +.Pp +.Bl -bullet -compact +.It +JMicron JMC250 PCI Express Gigabit Ethernet controller +.It +JMicron JMC251 PCI Express Gigabit Ethernet with Card Read Host controller +.It +JMicron JMC260 PCI Express Fast Ethernet controller +.It +JMicron JMC261 PCI Express Gigabit Ethernet with Card Read Host controller +.El +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width "xxxxxx" +.It Va hw.jme.msi_disable +This tunable disables MSI support on the Ethernet hardware. +The default value is 0. +.It Va hw.jme.msix_disable +This tunable disables MSI-X support on the Ethernet hardware. +The default value is 0. +.El +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width "xxxxxx" +.It Va dev.jme.%d.tx_coal_to +This variable sets the maximum amount of time to delay +before sending a Tx completion interrupt, in microseconds. +The accepted range is 1 to 65535; the default is 100 (100us). +.It Va dev.jme.%d.tx_coal_pkt +This variable sets the maximum number of outgoing packets which may be +coalesced together into a single Tx completion interrupt. +The accepted range is 1 to 255; the default is 8. +.It Va dev.jme.%d.rx_coal_to +This variable sets the maximum amount of time to wait for +additional packets to arrive (for possible packet coalescing) +before firing an Rx completion interrupt, in microseconds. +The accepted range is 1 to 65535; the default is 100 (100us). +.It Va dev.jme.%d.rx_coal_pkt +This variable sets the maximum number of incoming packets which may be +coalesced into a single Rx completion interrupt. +The accepted range is 1 to 255; the default is 2. +.It Va dev.jme.%d.process_limit +This variable sets the maximum number of events that will be processed +in a single batch before the handler is requeued into a taskqueue. +The accepted range is 10 to 255; the default value is 128 events. +The interface does not need to be brought down and up again before +a change takes effect. +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +driver was written by +.An Pyun YongHyeon Aq Mt yongari@FreeBSD.org . +It first appeared in +.Fx 7.1 . +.Sh CAVEATS +The +.Nm +driver tries to avoid unnecessary station address reprogramming for +controllers that use eFuse to store station address. +The number of times that eFuse can be safely reprogrammed is 16 at +most. +In addition, there is no way to restore the factory default station +address once the station address has been reprogrammed via eFuse. +It is highly recommended not to reprogram the station address and +it is the responsibility of the administrator to store the original station +address in a safe place when station address is changed. +.Pp +There are two known 1000baseT link establishment issues with JMC25x. +If the full mask revision number of JMC25x controller is less than +or equal to 4 and the link partner enabled the IEEE 802.3az Energy Efficient +Ethernet feature, the controller will not be able to establish a +1000baseT link. +Also, if the length of the cable is longer than 120 meters, the controller +can not establish a 1000baseT link. +The known workaround for these issues is to force manual link +configuration with 100baseTX instead of relying on auto-negotiation. +The full mask revision number of controller can be checked with the +verbose kernel boot option. +Use the lower nibble of the chip revision number to get the +full mask revision of the controller. diff --git a/static/freebsd/man4/kbdmux.4 b/static/freebsd/man4/kbdmux.4 new file mode 100644 index 00000000..7088a158 --- /dev/null +++ b/static/freebsd/man4/kbdmux.4 @@ -0,0 +1,56 @@ +.\" $Id: kbdmux.4,v 1.1 2005/07/14 20:32:10 max Exp $ +.\" +.Dd July 12, 2005 +.Dt KBDMUX 4 +.Os +.Sh NAME +.Nm kbdmux +.Nd "keyboard multiplexer" +.Sh SYNOPSIS +.Cd "device kbdmux" +.Pp +In +.Pa /boot/device.hints : +.Cd hint.kbdmux.0.disabled="1" +.Sh DESCRIPTION +The +.Nm +keyboard driver provides support for basic keyboard multiplexing. +It is built around the idea of a +.Dq "super keyboard" . +The +.Nm +driver +acts as a master keyboard consuming input from all slave keyboards attached to +it. +.Pp +Slave keyboards can be attached to or detached from the +.Nm +keyboard driver with the +.Xr kbdcontrol 1 +utility. +.Sh SEE ALSO +.Xr kbdcontrol 1 , +.Xr atkbd 4 , +.Xr syscons 4 , +.Xr ukbd 4 , +.Xr vt 4 +.Sh HISTORY +The +.Nm +module was implemented in +.Fx 6.0 . +.Sh AUTHORS +.An Maksim Yevmenkin Aq Mt m_evmenkin@yahoo.com +.Sh CAVEATS +The +.Nm +keyboard driver switches all slave keyboards into +.Dv K_RAW +mode. +Thus all slave keyboards attached to the +.Nm +keyboard share the same state. +The +.Nm +keyboard is logically equivalent to one keyboard with lots of duplicated keys. diff --git a/static/freebsd/man4/kcov.4 b/static/freebsd/man4/kcov.4 new file mode 100644 index 00000000..a9e55568 --- /dev/null +++ b/static/freebsd/man4/kcov.4 @@ -0,0 +1,204 @@ +.\"- +.\" Copyright (c) 2020 The FreeBSD Foundation +.\" +.\" This documentation was written by Mark Johnston under sponsorship from +.\" the FreeBSD Foundation. +.\" +.\" 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 August 18, 2020 +.Dt KCOV 4 +.Os +.Sh NAME +.Nm kcov +.Nd interface for collecting kernel code coverage information +.Sh SYNOPSIS +To compile KCOV into the kernel, place the following lines in your kernel +configuration file: +.Bd -ragged -offset indent +.Cd "options COVERAGE" +.Cd "options KCOV" +.Ed +.Pp +The following header file defines the application interface provided +by KCOV: +.Pp +.In sys/kcov.h +.Sh DESCRIPTION +.Nm +is a module that enables collection of code coverage information from the +kernel. +It relies on code instrumentation enabled by the +.Dv COVERAGE +kernel option. +When +.Nm +is enabled by a user-mode thread, it collects coverage information only for +that thread, excluding hard interrupt handlers. +As a result, +.Nm +is not suited to collect comprehensive coverage data for the entire kernel; +its main purpose is to provide input for coverage-guided system call fuzzers. +.Pp +In typical usage, a user-mode thread first allocates a chunk of memory to be +shared with +.Nm . +The thread then enables coverage tracing, with coverage data being written by +the kernel to the shared memory region. +When tracing is disabled, the kernel relinquishes its access to the shared +memory region, and the written coverage data may be consumed. +.Pp +The shared memory buffer can be treated as a 64-bit unsigned integer followed +by an array of records. +The integer records the number of valid records and is updated by the kernel as +coverage information is recorded. +The state of the tracing buffer can be reset by writing the value 0 to this +field. +The record layout depends on the tracing mode set using the +.Dv KIOENABLE +ioctl. +.Pp +Two tracing modes are implemented, +.Dv KCOV_MODE_TRACE_PC +and +.Dv KCOV_MODE_TRACE_CMP . +PC-tracing records a program counter value for each basic block executed while +tracing is enabled. +In this mode, each record is a single 64-bit unsigned integer containing the +program counter value. +Comparison tracing provides information about data flow; information about +dynamic variable comparisons is recorded. +Such records provide information about the results of +.Xr c 7 +.Ql if +or +.Ql switch +statements, for example. +In this mode each record consists of four 64-bit unsigned integers. +The first integer is a bitmask defining attributes of the variables involved in +the comparison. +.Dv KCOV_CMP_CONST +is set if one of the variables has a constant value at compile-time, and +.Dv KCOV_CMP_SIZE(n) +specifies the width of the variables: +.Pp +.Bl -inset -offset indent -compact +.It Dv KCOV_CMP_SIZE(0) : +a comparison of 8-bit integers +.It Dv KCOV_CMP_SIZE(1) : +a comparison of 16-bit integers +.It Dv KCOV_CMP_SIZE(2) : +a comparison of 32-bit integers +.It Dv KCOV_CMP_SIZE(3) : +a comparison of 64-bit integers +.El +.Pp +The second and third fields record the values of the two variables, and the +fourth and final field stores the program counter value of the comparison. +.Sh IOCTL INTERFACE +Applications interact with +.Nm +using the +.Xr ioctl 2 +system call. +Each thread making use of +.Nm +must use a separate file descriptor for +.Fa /dev/kcov . +The following ioctls are defined: +.Bl -tag -width indent +.It Dv KIOSETBUFSIZE Fa size_t entries +Set the size of the tracing buffer in units of +.Dv KCOV_ENTRY_SIZE . +The buffer may then be mapped into the calling thread's address space by +calling +.Xr mmap 2 +on the +.Nm +device file. +.It Dv KIOENABLE Fa int mode +Enable coverage tracing for the calling thread. +Valid modes are +.Dv KCOV_MODE_TRACE_PC +and +.Dv KCOV_MODE_TRACE_CMP . +.It Dv KIODISABLE +Disable coverage tracing for the calling thread. +.El +.Sh FILES +.Nm +creates the +.Pa /dev/kcov +device file. +.Sh EXAMPLES +The following code sample collects information about basic block coverage for +kernel code executed while printing +.Ql "Hello, world" . +.Bd -literal +size_t sz; +uint64_t *buf; +int fd; + +fd = open("/dev/kcov", O_RDWR); +if (fd == -1) + err(1, "open(/dev/kcov)"); +sz = 1ul << 20; /* 1MB */ +if (ioctl(fd, KIOSETBUFSIZE, sz / KCOV_ENTRY_SIZE) != 0) + err(1, "ioctl(KIOSETBUFSIZE)"); +buf = mmap(NULL, sz, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0); +if (buf == MAP_FAILED) + err(1, "mmap"); + +/* Enable PC tracing. */ +if (ioctl(fd, KIOENABLE, KCOV_MODE_TRACE_PC) != 0) + err(1, "ioctl(KIOENABLE)"); + +/* Clear trace records from the preceding ioctl() call. */ +buf[0] = 0; + +printf("Hello, world!\\n"); + +/* Disable PC tracing. */ +if (ioctl(fd, KIODISABLE, 0) != 0) + err(1, "ioctl(KIODISABLE)"); + +for (uint64_t i = 1; i < buf[0]; i++) + printf("%#jx\\n", (uintmax_t)buf[i]); +.Ed +The output of this program can be approximately mapped to line numbers +in kernel source code: +.Bd -literal +# ./kcov-test | sed 1d | addr2line -e /usr/lib/debug/boot/kernel/kernel.debug +.Ed +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr mmap 2 +.Sh HISTORY +.Nm +first appeared in +.Fx 13.0 . +.Sh BUGS +The +.Fx +implementation of +.Nm +does not yet support remote tracing. diff --git a/static/freebsd/man4/keyboard.4 b/static/freebsd/man4/keyboard.4 new file mode 100644 index 00000000..8341ac2a --- /dev/null +++ b/static/freebsd/man4/keyboard.4 @@ -0,0 +1,168 @@ +.\" +.Dd January 8, 1995 +.Dt KEYBOARD 4 +.Os +.Sh NAME +.Nm keyboard +.Nd pc keyboard interface +.Sh DESCRIPTION +The PC keyboard is used as the console character input device. +The keyboard +is owned by the current virtual console. +To switch between the virtual consoles use the sequence +.Ar ALT+Fn , +which means hold down ALT and press one of the function keys. +The +virtual console with the same number as the function key is then +selected as the current virtual console and given exclusive use of +the keyboard and display. +.Pp +The console allows entering values that are not physically +present on the keyboard via a special keysequence. +To use this facility press and hold down ALT, +then enter a decimal number from 0-255 via the numerical keypad, then +release ALT. +The entered value is then used as the ASCII value for one +character. +This way it is possible to enter any ASCII value, not present +on the keyboard. +The console driver also includes a history function. +It is activated by +pressing the scroll-lock key. +This holds the display, and enables the cursor +arrows for scrolling up and down through the last scrolled out lines. +.Pp +The keyboard is configurable to suit the individual user and the different +national layout. +.Pp +The keys on the keyboard can have any of the following functions: +.Pp +.Bl -tag -width "Modifier Key" -compact +.It "Normal key" +Enter the ASCII value associated with the key. +.It "Function key" +Enter a string of ASCII values. +.It "Switch Key" +Switch virtual console. +.It "Modifier Key" +Change the meaning of another key. +.El +.Pp +The keyboard is seen as a number of keys numbered from 1 to n. +This +number is often referred to as the "scancode" for a given key. +The number +of the key is transmitted as an 8 bit char with bit 7 as 0 when a key is +pressed, and the number with bit 7 as 1 when released. +This makes it +possible to make the mapping of the keys fully configurable. +.Pp +The meaning of every key is programmable via the PIO_KEYMAP ioctl call, that +takes a structure keymap_t as argument. +The layout of this structure is as +follows: +.Bd -literal -offset indent + struct keymap { + u_short n_keys; + struct key_t { + u_char map[NUM_STATES]; + u_char spcl; + u_char flgs; + } key[NUM_KEYS]; + }; +.Ed +.Pp +The field n_keys tells the system how many keydefinitions (scancodes) +follows. +Each scancode is then specified in the key_t substructure. +.Pp +Each scancode can be translated to any of 8 different values, depending +on the shift, control, and alt state. +These eight possibilities are +represented by the map array, as shown below: +.Bd -literal + alt + scan cntrl alt alt cntrl + code base shift cntrl shift alt shift cntrl shift + map[n] 0 1 2 3 4 5 6 7 + ---- ------------------------------------------------------ + 0x1E 'a' 'A' 0x01 0x01 'a' 'A' 0x01 0x01 +.Ed +.Pp +This is the default mapping for the key labelled 'A' which normally has +scancode 0x1E. +The eight states are as shown, giving the 'A' key its +normal behavior. +The spcl field is used to give the key "special" treatment, and is +interpreted as follows. +Each bit corresponds to one of the states above. +If the bit is 0 the +key emits the number defined in the corresponding map[] entry. +If the bit is 1 the key is "special". +This means it does not emit +anything; instead it changes the "state". +That means it is a shift, +control, alt, lock, switch-screen, function-key or no-op key. +The bitmap is backwards i.e., +7 for base, 6 for shift etc. +.Pp +The flgs field defines if the key should react on caps-lock (1), +num-lock (2), both (3) or ignore both (0). +.Pp +The +.Xr kbdcontrol 1 +utility is used to load such a description into/outof +the kernel at runtime. +This makes it possible to change the key +assignments at runtime, or more important to get (GIO_KEYMAP ioctl) +the exact key meanings from the kernel (e.g.\& used by the X server). +.Pp +The function keys can be programmed using the SETFKEY ioctl call. +.Pp +This ioctl takes an argument of the type fkeyarg_t: +.Bd -literal -offset indent + struct fkeyarg { + u_short keynum; + char keydef[MAXFK]; + char flen; + }; +.Ed +.Pp +The field keynum defines which function key that is programmed. +The array keydef should contain the new string to be used (MAXFK long), +and the length should be entered in flen. +.Pp +The GETFKEY ioctl call works in a similar manner, except it returns +the current setting of keynum. +.Pp +The function keys are numbered like this: +.Bd -literal -offset indent + F1-F12 key 1 - 12 + Shift F1-F12 key 13 - 24 + Ctrl F1-F12 key 25 - 36 + Ctrl+shift F1-F12 key 37 - 48 + + Home key 49 + Up arrow key 50 + Page Up key 51 + (keypad) - key 52 + Left arrow key 53 + (keypad) 5 key 54 + Right arrow key 55 + (keypad) + key 56 + End key 57 + Down arrow key 58 + Page down key 59 + Insert key 60 + Delete key 61 + + Left window key 62 + Right window key 63 + Menu key 64 +.Ed +.Pp +The +.Xr kbdcontrol 1 +utility also allows changing these values at runtime. +.Sh AUTHORS +.An S\(/oren Schmidt Aq Mt sos@FreeBSD.org diff --git a/static/freebsd/man4/kld.4 b/static/freebsd/man4/kld.4 new file mode 100644 index 00000000..e0186dec --- /dev/null +++ b/static/freebsd/man4/kld.4 @@ -0,0 +1,171 @@ +.\" Copyright (c) 1993 Christopher G. Demetriou +.\" 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. 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 January 13, 2014 +.Dt KLD 4 +.Os +.Sh NAME +.Nm kld +.Nd dynamic kernel linker facility +.Sh DESCRIPTION +The LKM (Loadable Kernel Modules) facility has been deprecated in +.Fx 3.0 +and above in favor of the +.Nm +interface. +This interface, like its +predecessor, allows the system administrator to dynamically add and remove +functionality from a running system. +This ability also helps software +developers to develop new parts of the kernel without constantly rebooting +to test their changes. +.Pp +Various types of modules can be loaded into the system. +There are several defined module types, listed below, which can +be added to the system in a predefined way. +In addition, there +is a generic type, for which the module itself handles loading and +unloading. +.Pp +The +.Fx +system makes extensive use of loadable kernel modules, and provides loadable +versions of most file systems, the +.Tn NFS +client and server, all the screen-savers, and the +.Tn Linux +emulator. +.Nm +modules are placed by default in the +.Pa /boot/kernel +directory along with their matching kernel. +.Pp +The +.Nm +interface is used through the +.Xr kldload 8 , +.Xr kldunload 8 +and +.Xr kldstat 8 +programs. +.Pp +The +.Xr kldload 8 +program can load either +.Xr a.out 5 +or ELF formatted loadable modules. +The +.Xr kldunload 8 +program unloads any given loaded module, if no other module is dependent +upon the given module. +The +.Xr kldstat 8 +program is used to check the status of the modules currently loaded into the +system. +.Pp +Kernel modules may only be loaded or unloaded if the system security level +.Va kern.securelevel +is less than one. +.Sh "MODULE TYPES" +.Bl -ohang +.It Em "Device Driver modules" +New block and character device +drivers may be loaded into the system with +.Nm . +Device nodes for the loaded drivers are automatically created when a +module is loaded and destroyed when it is unloaded by +.Xr devfs 4 . +You can specify userland programs that will run when new devices +become available as a result of loading modules, or existing devices +go away when modules are unloaded, by configuring +.Xr devd 8 . +.El +.Sh FILES +.Bl -tag -width /usr/include/sys/module.h -compact +.It Pa /boot/kernel +directory containing module binaries built for the kernel also +residing in the directory. +.It Pa /usr/include/sys/module.h +file containing definitions required to compile a +.Nm +module +.It Pa /usr/share/examples/kld +example source code implementing a sample kld module +.El +.Sh SEE ALSO +.Xr kldfind 2 , +.Xr kldfirstmod 2 , +.Xr kldload 2 , +.Xr kldnext 2 , +.Xr kldstat 2 , +.Xr kldunload 2 , +.Xr devfs 4 , +.Xr devd 8 , +.Xr kldload 8 , +.Xr kldstat 8 , +.Xr kldunload 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +facility appeared in +.Fx 3.0 +and was designed as a replacement for the +.Nm lkm +facility, which was similar in functionality to the loadable kernel modules +facility provided by +.Tn SunOS +4.1.3. +.Sh AUTHORS +The +.Nm +facility was originally implemented by +.An Doug Rabson Aq Mt dfr@FreeBSD.org . +.Sh BUGS +If a module B, is dependent on another module A, but is not compiled with +module A as a dependency, then +.Xr kldload 8 +fails to load module B, even if module A is already present in the system. +.Pp +If multiple modules are dependent on module A, and are compiled with module +A as a dependency, then +.Xr kldload 8 +loads an instance of module A when any of the modules are loaded. +.Pp +If a custom entry point is used for a module, and the module is compiled as +an +.Sq ELF +binary, then +.Xr kldload 8 +fails to execute the entry point. +.Pp +.Xr kldload 8 +points the user to read +.Xr dmesg 8 +for any error encountered while loading a module. +.Pp +When system internal interfaces change, old modules often cannot +detect this, and such modules when loaded will often cause crashes or +mysterious failures. diff --git a/static/freebsd/man4/ksyms.4 b/static/freebsd/man4/ksyms.4 new file mode 100644 index 00000000..1b905a9c --- /dev/null +++ b/static/freebsd/man4/ksyms.4 @@ -0,0 +1,133 @@ +.\" Copyright (c) 2008-2009 Stacey Son +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 August 2, 2017 +.Dt KSYMS 4 +.Os +.Sh NAME +.Nm ksyms +.Nd kernel symbol table interface +.Sh SYNOPSIS +.Cd "device ksyms" +.Sh DESCRIPTION +The +.Pa /dev/ksyms +character device provides a read-only interface to a snapshot of the kernel +symbol table. +The in-kernel symbol manager is designed to be able to handle +many types of symbols tables, however, only +.Xr elf 5 +symbol tables are supported by this device. +The ELF format image contains two +sections: a symbol table and a corresponding string table. +.Bl -tag -width indent -offset indent +.It Dv Symbol Table +The SYMTAB section contains the symbol table entries present in the current +running kernel, including the symbol table entries of any loaded modules. +The symbols are ordered by the kernel module load time starting with kernel file +symbols first, followed by the first loaded module's symbols and so on. +.It Dv String Table +The STRTAB section contains the symbol name strings from the kernel and any +loaded modules that the symbol table entries reference. +.El +.Pp +Elf formatted symbol table data read from the +.Pa /dev/ksyms +file represents the state of the kernel at the time when the device is opened. +Since +.Pa /dev/ksyms +has no text or data, most of the fields are initialized to NULL. +The +.Nm +driver does not block the loading or unloading of modules into the kernel +while the +.Pa /dev/ksyms +file is open but may contain stale data. +.Sh FILES +.Bl -tag -width /dev/ksymsX +.It Pa /dev/ksyms +.El +.Sh ERRORS +An +.Xr open 2 +of +.Pa /dev/ksyms +will fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +The device is already open. +A process must close +.Pa /dev/ksyms +before it can be opened again. +.It Bq Er ENOMEM +There is a resource shortage in the kernel. +.It Bq Er ENXIO +The driver was unsuccessful in creating a snapshot of the kernel symbol +table. +This may occur if the kernel was in the process of loading or +unloading a module. +.El +.Sh SEE ALSO +.Xr nlist 3 , +.Xr elf 5 , +.Xr kldload 8 +.Sh HISTORY +A +.Nm +device exists in many different operating systems. +This implementation is similar in function to the Solaris and NetBSD +.Nm +driver. +.Pp +The +.Nm +driver first appeared in +.Fx 8.0 +to support +.Xr lockstat 1 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Stacey Son Aq Mt sson@FreeBSD.org . +.Sh BUGS +Because files can be dynamically linked into the kernel at any time the symbol +information can vary. +When you open the +.Pa /dev/ksyms +file, you have access to an ELF image which represents a snapshot of the state +of the kernel symbol information at that instant in time. +Keeping the device open does not block the loading or unloading of kernel +modules. +To get a new snapshot you must close and re-open the device. +.Pp +A process is only allowed to open the +.Pa /dev/ksyms +file once at a time. +The process must close the +.Pa /dev/ksyms +before it is allowed to open it again. diff --git a/static/freebsd/man4/ksz8995ma.4 b/static/freebsd/man4/ksz8995ma.4 new file mode 100644 index 00000000..cd1939cb --- /dev/null +++ b/static/freebsd/man4/ksz8995ma.4 @@ -0,0 +1,67 @@ +.\"- +.\" Copyright (c) 2017 Hiroki Mori +.\" 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 April 6, 2017 +.Dt KSZ8995MA 4 +.Os +.Sh NAME +.Nm ksz8995ma +.Nd driver for Micrel KSZ8995MA fast ethernet switch chip +.Sh SYNOPSIS +.Cd "device spibus" +.Cd "device etherswitch" +.Cd "device ksz8995ma" +.Pp +.Cd hint.ksz8995ma.0.at="spibus0" +.Sh DESCRIPTION +The +.Nm +device driver provides a management interface to Micrel KSZ8995MA fast ethernet switch chip. +This driver use spi interface. +KSZ8995 series have many vertion but only support MA/FQ version. +.Pp +This driver support is port and dot1q vlan. +dot1q support port base tag/untag. +.Sh EXAMPLES +Configure dot1q vlan by etherswitchcfg command. +.Pp +.Dl # etherswitchcfg config vlan_mode dot1q +.Pp +Configure port 5 is tagging port. +.Pp +.Dl # etherswitchcfg port5 addtag +.Sh SEE ALSO +.Xr etherswitch 4 , +.Xr etherswitchcfg 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 12.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Hiroki Mori diff --git a/static/freebsd/man4/ktls.4 b/static/freebsd/man4/ktls.4 new file mode 100644 index 00000000..56b03d45 --- /dev/null +++ b/static/freebsd/man4/ktls.4 @@ -0,0 +1,257 @@ +.\" Copyright (c) 2020, Chelsio Inc +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright notice, +.\" this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Chelsio Inc nor the names of its +.\" contributors may be used to endorse or promote products derived from +.\" this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 COPYRIGHT OWNER 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. +.\" +.\" * Other names and brands may be claimed as the property of others. +.\" +.Dd October 31, 2024 +.Dt KTLS 4 +.Os +.Sh NAME +.Nm ktls +.Nd kernel Transport Layer Security +.Sh SYNOPSIS +.Cd options KERN_TLS +.Sh DESCRIPTION +The +.Nm +facility allows the kernel to perform Transport Layer Security (TLS) +framing on TCP sockets. +With +.Nm , +the initial handshake for a socket using TLS is performed in userland. +Once the session keys are negotiated, +they are provided to the kernel via the +.Dv TCP_TXTLS_ENABLE +and +.Dv TCP_RXTLS_ENABLE +socket options. +Both socket options accept a +.Vt struct tls_enable +structure as their argument. +The members of this structure describe the cipher suite used for the +TLS session and provide the session keys used for the respective +direction. +.Pp +.Nm +only permits the session keys to be set once in each direction. +As a result, +applications must disable rekeying when using +.Nm . +.Ss Modes +.Nm +can operate in different modes. +A given socket may use different modes for transmit and receive, +or a socket may only offload a single direction. +The available modes are: +.Bl -tag -width "Dv TCP_TLS_MODE_IFNET" +.It Dv TCP_TLS_MODE_NONE +.Nm +is not enabled. +.It Dv TCP_TLS_MODE_SW +TLS records are encrypted or decrypted in the kernel in the socket +layer via +.Xr crypto 9 . +Typically the encryption or decryption is performed in software, +but it may also be performed by co-processors. +.It Dv TCP_TLS_MODE_IFNET +TLS records are encrypted or decrypted by the network interface card (NIC). +In this mode, the network stack does not work with encrypted data. +Instead, the NIC encrypts TLS records as they are being transmitted, +or decrypts received TLS records before providing them to the host. +.Pp +Network interfaces which support this feature will advertise the +.Dv TXTLS4 +(for IPv4) +and/or +.Dv TXTLS6 +(for IPv6) +capabilities as reported by +.Xr ifconfig 8 . +These capabilities can also be controlled by +.Xr ifconfig 8 . +.Pp +If a network interface supports rate limiting +(also known as packet pacing) for TLS offload, +the interface will advertise the +.Dv TXTLS_RTLMT +capability. +.It Dv TCP_TLS_MODE_TOE +TLS records are encrypted by the NIC using a TCP offload engine (TOE). +This is similar to +.Dv TCP_TLS_MODE_IFNET +in that the network stack does not work with encrypted data. +However, this mode works in tandem with a TOE to handle interactions +between TCP and TLS. +.El +.Ss Transmit +Once TLS transmit is enabled by a successful set of the +.Dv TCP_TXTLS_ENABLE +socket option, +all data written on the socket is stored in TLS records and encrypted. +Most data is transmitted in application layer TLS records, +and the kernel chooses how to partition data among TLS records. +Individual TLS records with a fixed length and record type can be sent +by +.Xr sendmsg 2 +with the TLS record type set in a +.Dv TLS_SET_RECORD_TYPE +control message. +The payload of this control message is a single byte holding the desired +TLS record type. +This can be used to send TLS records with a type other than +application data (for example, handshake messages) or to send +application data records with specific contents (for example, empty +fragments). +.Pp +The current TLS transmit mode of a socket can be queried via the +.Dv TCP_TXTLS_MODE +socket option. +A socket using TLS transmit offload can also set the +.Dv TCP_TXTLS_MODE +socket option to toggle between +.Dv TCP_TLS_MODE_SW +and +.Dv TCP_TLS_MODE_IFNET . +.Ss Receive +Once TLS receive is enabled by a successful set of the +.Dv TCP_RXTLS_ENABLE +socket option, +all data read from the socket is returned as decrypted TLS records. +Each received TLS record must be read from the socket using +.Xr recvmsg 2 . +Each received TLS record will contain a +.Dv TLS_GET_RECORD +control message along with the decrypted payload. +The control message contains a +.Vt struct tls_get_record +which includes fields from the TLS record header. +If an invalid or corrupted TLS record is received, +.Xr recvmsg 2 +will fail with one of the following errors: +.Bl -tag -width Er +.It Bq Er EINVAL +The version fields in a TLS record's header did not match the version required +by the +.Vt struct tls_enable +structure used to enable in-kernel TLS. +.It Bq Er EMSGSIZE +A TLS record's length was either too small or too large. +.It Bq Er EMSGSIZE +The connection was closed after sending a truncated TLS record. +.It Bq Er EBADMSG +The TLS record failed to match the included authentication tag. +.El +.Pp +The current TLS receive mode of a socket can be queried via the +.Dv TCP_RXTLS_MODE +socket option. +At present, +the mode cannot be changed. +.Ss Sysctl Nodes +.Nm +uses several sysctl nodes under the +.Va kern.ipc.tls +node. +A few of them are described below: +.Bl -tag -width ".Va kern.ipc.tls.cbc_enable" +.It Va kern.ipc.tls.enable +Determines if new kernel TLS sessions can be created. +.It Va kern.ipc.tls.cbc_enable +Determines if new kernel TLS sessions with a cipher suite using AES-CBC +can be created. +.It Va kern.ipc.tls.sw +A tree of nodes containing statistics for TLS sessions using +.Dv TCP_TLS_MODE_SW . +.It Va kern.ipc.tls.ifnet +A tree of nodes containing statistics for TLS sessions using +.Dv TCP_TLS_MODE_IFNET . +.It Va kern.ipc.tls.toe +A tree of nodes containing statistics for TLS sessions using +.Dv TCP_TLS_MODE_TOE . +.It Va kern.ipc.tls.stats +A tree of nodes containing various kernel TLS statistics. +.El +.Pp +The +.Va kern.ipc.mb_use_ext_pgs +sysctl controls whether the kernel may use unmapped mbufs. +They are required for TLS transmit. +.Ss Supported Hardware +The +.Xr cxgbe 4 +and +.Xr mlx5en 4 +drivers include support for the +.Dv TCP_TLS_MODE_IFNET +mode. +.Pp +The +.Xr cxgbe 4 +driver includes support for the +.Dv TCP_TLS_MODE_TOE +mode. +.Ss Supported Libraries +OpenSSL 3.0 and later include support for +.Nm . +The +.Fa security/openssl* +and +.Fa security/gnutls +ports may also be built with support for +.Nm +by enabling the +.Dv KTLS +option. +OpenSSL in the base system includes KTLS support when built with +.Dv WITH_OPENSSL_KTLS . +.Pp +Applications using a supported library should generally work with +.Nm +without any changes provided they use standard interfaces such as +.Xr SSL_read 3 +and +.Xr SSL_write 3 . +Additional performance may be gained by the use of +.Xr SSL_sendfile 3 . +.Sh IMPLEMENTATION NOTES +.Nm +assumes the presence of a direct map of physical memory when performing +software encryption and decryption. +As a result, it is only supported on architectures with a direct map. +.Sh SEE ALSO +.Xr cxgbe 4 , +.Xr mlx5en 4 , +.Xr tcp 4 , +.Xr src.conf 5 , +.Xr ifconfig 8 , +.Xr sysctl 8 , +.Xr crypto 9 +.Sh HISTORY +Kernel TLS first appeared in +.Fx 13.0 . diff --git a/static/freebsd/man4/ktr.4 b/static/freebsd/man4/ktr.4 new file mode 100644 index 00000000..f1a35c7d --- /dev/null +++ b/static/freebsd/man4/ktr.4 @@ -0,0 +1,208 @@ +.\" Copyright (c) 2001 John H. Baldwin +.\" +.\" 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 March 26, 2021 +.Dt KTR 4 +.Os +.Sh NAME +.Nm ktr +.Nd kernel tracing facility +.Sh SYNOPSIS +.Cd options KTR +.Cd options ALQ +.Cd options KTR_ALQ +.Cd options KTR_COMPILE=(KTR_LOCK|KTR_INTR|KTR_PROC) +.Cd options KTR_CPUMASK=0x3 +.Cd options KTR_ENTRIES=8192 +.Cd options KTR_MASK=(KTR_INTR|KTR_PROC) +.Cd options KTR_VERBOSE +.Sh DESCRIPTION +The +.Nm +facility allows kernel events to be logged while the kernel executes so that +they can be examined later when debugging. +The only mandatory option to enable +.Nm +is +.Dq Li options KTR . +.Pp +The +.Dv KTR_ENTRIES +option sets the size of the buffer of events. +The size of the buffer in the currently running kernel can be found via the +sysctl +.Va debug.ktr.entries . +By default the buffer contains 1024 entries. +.Ss Event Masking +Event levels can be enabled or disabled to trim excessive and overly verbose +logging. +First, a mask of events is specified at compile time via the +.Dv KTR_COMPILE +option to limit which events are actually compiled into the kernel. +The default value for this option is for all events to be enabled. +.Pp +Secondly, the actual events logged while the kernel runs can be further +masked via the run time event mask. +The +.Dv KTR_MASK +option sets the default value of the run time event mask. +The runtime event mask can also be set by the +.Xr loader 8 +via the +.Va debug.ktr.mask +environment variable. +It can also be examined and set after booting via the +.Va debug.ktr.mask +sysctl. +By default the run time mask is set to block any tracing. +The definitions of the event mask bits can be found in +.In sys/ktr_class.h . +.Pp +Furthermore, there is a CPU event mask whose default value can be changed via +the +.Dv KTR_CPUMASK +option. +When two or more parameters to +.Dv KTR_CPUMASK , +are used, it is important they are not separated by whitespace. +A CPU must have the bit corresponding to its logical id set in this bitmask +for events that occur on it to be logged. +This mask can be set by the +.Xr loader 8 +via the +.Va debug.ktr.cpumask +environment variable. +It can also be examined and set after booting via the +.Va debug.ktr.cpumask +sysctl. +By default, only CPUs specified in +.Dv KTR_CPUMASK +will log events. +See +.Pa sys/conf/NOTES +for more information. +.Ss Verbose Mode +By default, events are only logged to the internal buffer for examination +later, but if the verbose flag is set then they are dumped to the kernel +console as well. +This flag can also be set from the loader via the +.Va debug.ktr.verbose +environment variable, or it can be examined and set after booting via the +.Va debug.ktr.verbose +sysctl. +If the flag is set to zero, which is the default, then verbose output is +disabled. +If the flag is set to one, then the contents of the log message and the CPU +number are printed to the kernel console. +If the flag is greater than one, then the filename and line number of the +event are output to the console in addition to the log message and the CPU +number. +The +.Dv KTR_VERBOSE +option sets the flag to one. +.Ss Examining the Events +The KTR buffer can be examined from within +.Xr ddb 4 +via the +.Ic show ktr Op Cm /vV +command. +This command displays the contents of the trace buffer one page at a time. +At the +.Dq Li --more-- +prompt, the Enter key displays one more entry and prompts again. +The spacebar displays another page of entries. +Any other key quits. +By default the timestamp, filename, and line number are not displayed with +each log entry. +If the +.Cm /v +modifier is specified, then they are displayed in addition to the normal +output. +If the +.Cm /V +modifier is specified, then just the timestamp is displayed in +addition to the normal output. +Note that the events are displayed in reverse chronological order. +That is, the most recent events are displayed first. +.Ss Logging ktr to Disk +The +.Dv KTR_ALQ +option can be used to log +.Nm +entries to disk for post analysis using the +.Xr ktrdump 8 +utility. +This option depends on the +.Dv ALQ +option. +Due to the potentially high volume of trace messages the trace mask should be +selected carefully. +This feature is configured through a group of sysctls. +.Bl -tag -width ".Va debug.ktr.alq_enable" +.It Va debug.ktr.alq_file +displays or sets the file that +.Nm +will log to. +By default its value is +.Pa /tmp/ktr.out . +If the file name is changed while +.Nm +is enabled it will not take effect until +the next invocation. +.It Va debug.ktr.alq_enable +enables logging of +.Nm +entries to disk if it is set to one. +Setting this to 0 will terminate logging to disk and revert to +logging to the normal ktr ring buffer. +Data is not sent to the ring buffer while logging to disk. +.It Va debug.ktr.alq_max +is the maximum number of entries that will be recorded to disk, or 0 for +infinite. +This is helpful for limiting the number of particularly high frequency entries +that are recorded. +.It Va debug.ktr.alq_depth +determines the number of entries in the write buffer. +This is the buffer that holds entries before they are written to disk and +defaults to the value of the +.Dv KTR_ENTRIES +option. +.It Va debug.ktr.alq_failed +records the number of times we failed to write an entry due to overflowing the +write buffer. +This may happen if the frequency of the logged +.Nm +messages outpaces the depth +of the queue. +.It Va debug.ktr.alq_cnt +records the number of entries that have currently been written to disk. +.El +.Sh SEE ALSO +.Xr ktrdump 8 , +.Xr alq 9 , +.Xr ktr 9 +.Sh HISTORY +The KTR kernel tracing facility first appeared in +.Bsx 3.0 +and was imported into +.Fx 5.0 . diff --git a/static/freebsd/man4/kue.4 b/static/freebsd/man4/kue.4 new file mode 100644 index 00000000..a92af09f --- /dev/null +++ b/static/freebsd/man4/kue.4 @@ -0,0 +1,142 @@ +.\" Copyright (c) 1997, 1998, 1999, 2000 +.\" Bill Paul . 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 Bill Paul. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Bill Paul 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 Bill Paul OR THE VOICES IN HIS HEAD +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF +.\" THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 24, 2019 +.Dt KUE 4 +.Os +.Sh NAME +.Nm kue +.Nd "Kawasaki LSI KL5KUSB101B USB Ethernet driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device uhci" +.Cd "device ohci" +.Cd "device usb" +.Cd "device miibus" +.Cd "device uether" +.Cd "device kue" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_kue_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for USB Ethernet adapters based on the Kawasaki +LSI KL5KLUSB101B chipset. +.Pp +The KL5KLUSB101B supports a 128-entry multicast filter, single perfect +filter entry for the station address and promiscuous mode. +Packets are +received and transmitted over separate USB bulk transfer endpoints. +.Pp +The Kawasaki chipset supports only 10Mbps half-duplex mode, hence there +are no +.Fn ifmedia +modes to select. +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports Kawasaki LSI KL5KLUSB101B based USB Ethernet +adapters including: +.Pp +.Bl -bullet -compact +.It +3Com 3c19250 +.It +3Com 3c460 HomeConnect Ethernet USB Adapter +.It +ADS Technologies USB-10BT +.It +AOX USB101 +.It +ATen UC10T +.It +Abocom URE 450 +.It +Corega USB-T +.It +D-Link DSB-650C +.It +Entrega NET-USB-E45, NET-HUB-3U1E +.It +I/O Data USB ETT +.It +Kawasaki DU-H3E +.It +LinkSys USB10T +.It +Netgear EA101 +.It +Peracom USB Ethernet Adapter +.It +Psion Gold Port USB Ethernet adapter +.It +SMC 2102USB, 2104USB +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "kue%d: watchdog timeout" +A packet was queued for transmission and a transmit command was +issued, however the device failed to acknowledge the transmission +before a timeout expired. +.It "kue%d: no memory for rx list" +The driver failed to allocate an mbuf for the receiver ring. +.El +.Sh SEE ALSO +.Xr arp 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 4.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Bill Paul Aq Mt wpaul@ee.columbia.edu . +.Sh BUGS +The +.Nm +driver does not accumulate Ethernet collisions statistics because the +Kawasaki firmware does not appear to maintain any internal statistics. diff --git a/static/freebsd/man4/kvmclock.4 b/static/freebsd/man4/kvmclock.4 new file mode 100644 index 00000000..55ee5fc1 --- /dev/null +++ b/static/freebsd/man4/kvmclock.4 @@ -0,0 +1,96 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2023 Klara, Inc. +.\" +.\" 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 February 1, 2023 +.Dt KVMCLOCK 4 +.Os +.Sh NAME +.Nm kvmclock +.Nd Para-virtualized clock driver for x86 KVM guests +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device kvm_clock" +.Ed +.Sh DESCRIPTION +This driver reads time-keeping information from the para-virtualized clock +device provided by the KVM hypervisor on Linux hosts. +The +.Nm +driver is only implemented on i386 and amd64 platforms. +It acts as a +.Xr timecounters 4 +device and is preferred over the Time Stamp Counter (TSC) when available. +The driver exports timekeeping information via +.Pa /dev/pvclock , +enabling the implementation of +.Xr clock_gettime 2 +and related functions without entering the kernel. +.Pp +The +.Nm +driver works by accessing a per-vCPU timekeeping structure maintained by the +hypervisor. +It uses a combination of TSC readings and information from the shared structure +to produce a high-resolution timecounter which is invariant under hypervisor +events such as vCPU migration and live VM migration. +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va dev.kvmclock.0.vdso_enable_without_rdtscp +By default, timekeeping information is exported to userspace only when the +(virtual) CPU announces support for the +.Dq rdtscp +instruction. +Setting this sysctl to 1 overrides this behavior, allowing timekeeping +information to be exported even in the absence of +.Dq rdtscp +support. +However, this breaks compatibility with copies of +.Pa /lib/libc.so.7 +released prior to +.Fx 14.0 , +and statically linked binaries which embed a copy of the system C library. +Thus, this sysctl value should not be changed if the system may execute +binaries older than +.Fx 14.0 . +.It Va dev.kvmclock.0.vdso_force_unstable +Mark the timecounter as unstable for userspace consumers. +This is mostly useful for debugging the driver and userspace timekeeping code, +and generally should not be touched. +.El +.Sh SEE ALSO +.Xr timecounters 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 13.1 . diff --git a/static/freebsd/man4/lagg.4 b/static/freebsd/man4/lagg.4 new file mode 100644 index 00000000..4eaed2cf --- /dev/null +++ b/static/freebsd/man4/lagg.4 @@ -0,0 +1,251 @@ +.\" $OpenBSD: trunk.4,v 1.18 2006/06/09 13:53:34 jmc Exp $ +.\" +.\" Copyright (c) 2005, 2006 Reyk Floeter +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd January 16, 2023 +.Dt LAGG 4 +.Os +.Sh NAME +.Nm lagg +.Nd link aggregation and link failover interface +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device lagg" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_lagg_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +interface allows aggregation of multiple network interfaces as one virtual +.Nm +interface for the purpose of providing fault-tolerance and high-speed links. +.Pp +Each +.Nm +interface is created at runtime using interface cloning. +This is +most easily done with the +.Xr ifconfig 8 +.Cm create +command or using the +.Va cloned_interfaces +variable in +.Xr rc.conf 5 . +.Pp +A +.Nm +interface can be created using the +.Ic ifconfig lagg Ns Ar N Ic create +command. +It can use different link aggregation protocols specified +using the +.Ic laggproto Ar proto +option. +Child interfaces can be added using the +.Ic laggport Ar child-iface +option and removed using the +.Ic -laggport Ar child-iface +option. +.Pp +The driver currently supports the aggregation protocols +.Ic failover +(the default), +.Ic lacp , +.Ic loadbalance , +.Ic roundrobin , +.Ic broadcast , +and +.Ic none . +The protocols determine which ports are used for outgoing traffic +and whether a specific port accepts incoming traffic. +The interface link state is used to validate if the port is active or +not. +.Bl -tag -width loadbalance +.It Ic failover +Sends traffic only through the active port. +If the master port becomes unavailable, +the next active port is used. +The first interface added is the master port; +any interfaces added after that are used as failover devices. +.Pp +By default, received traffic is only accepted when it is received +through the active port. +This constraint can be relaxed by setting the +.Va net.link.lagg.failover_rx_all +.Xr sysctl 8 +variable to a nonzero value, +which is useful for certain bridged network setups. +.It Ic lacp +Supports the IEEE 802.1AX (formerly 802.3ad) Link Aggregation Control Protocol +(LACP) and the Marker Protocol. +LACP will negotiate a set of aggregable links with the peer in to one or more +Link Aggregated Groups. +Each LAG is composed of ports of the same speed, set to full-duplex operation. +The traffic will be balanced across the ports in the LAG with the greatest +total speed, in most cases there will only be one LAG which contains all ports. +In the event of changes in physical connectivity, Link Aggregation will quickly +converge to a new configuration. +.It Ic loadbalance +Balances outgoing traffic across the active ports based on hashed +protocol header information and accepts incoming traffic from +any active port. +This is a static setup and does not negotiate aggregation with the peer or +exchange frames to monitor the link. +The hash includes the Ethernet source and destination address, and, if +available, the VLAN tag, and the IP source and destination address. +.It Ic roundrobin +Distributes outgoing traffic using a round-robin scheduler +through all active ports and accepts incoming traffic from +any active port. +Using +.Ic roundrobin +mode can cause unordered packet arrival at the client. +Throughput might be limited as the client performs CPU-intensive packet +reordering. +.It Ic broadcast +Sends frames to all ports of the LAG and receives frames on +any port of the LAG. +.It Ic none +This protocol is intended to do nothing: it disables any traffic without +disabling the +.Nm +interface itself. +.El +.Pp +The MTU of the first interface to be added is used as the lagg MTU. +All additional interfaces are required to have exactly the same value. +.Pp +The +.Ic loadbalance +and +.Ic lacp +modes will use the RSS hash from the network card if available to avoid +computing one, this may give poor traffic distribution if the hash is invalid +or uses less of the protocol header information. +Local hash computation can be forced per interface by setting the +.Cm -use_flowid +.Xr ifconfig 8 +flag. +The default for new interfaces is set via the +.Va net.link.lagg.default_use_flowid +.Xr sysctl 8 . +.Pp +When creating a +.Nm +interface, the +.Ic laggtype +can be specified as either +.Cm ethernet +or +.Cm infiniband . +If neither is specified then the default is +.Cm ethernet . +.Sh EXAMPLES +Create a link aggregation using LACP with two +.Xr bge 4 +Gigabit Ethernet interfaces: +.Bd -literal -offset indent +# ifconfig bge0 up +# ifconfig bge1 up +# ifconfig lagg0 create +# ifconfig lagg0 laggproto lacp laggport bge0 laggport bge1 \e + 192.168.1.1 netmask 255.255.255.0 +.Ed +.Pp +Create a link aggregation using ROUNDROBIN with two +.Xr bge 4 +Gigabit Ethernet interfaces and set a stride of 500 packets +per interface: +.Bd -literal -offset indent +# ifconfig bge0 up +# ifconfig bge1 up +# ifconfig lagg0 create +# ifconfig lagg0 laggproto roundrobin laggport bge0 laggport bge1 \e + 192.168.1.1 netmask 255.255.255.0 +# ifconfig lagg0 rr_limit 500 +.Ed +.Pp +The following example uses an active failover interface to set up roaming +between wired and wireless networks using two network devices. +Whenever the wired master interface is unplugged, the wireless failover +device will be used: +.Bd -literal -offset indent +# ifconfig em0 ether 00:11:22:33:44:55 up +# ifconfig wlan0 create wlandev ath0 ssid my_net up +# ifconfig lagg0 create +# ifconfig lagg0 laggproto failover laggport em0 laggport wlan0 \e + 192.168.1.1 netmask 255.255.255.0 +.Ed +.Pp +(Note the MAC address of the wired device is forced to match that of the +wireless device, +.Sq 00:11:22:33:44:55 +in this example, as some common wireless devices will not allow MAC +addresses to be changed.) +.Pp +The following example shows how to create an infiniband failover interface. +.Bd -literal -offset indent +# ifconfig ib0 up +# ifconfig ib1 up +# ifconfig lagg0 create laggtype infiniband +# ifconfig lagg0 laggproto failover laggport ib0 laggport ib1 \e + 1.1.1.1 netmask 255.255.255.0 +.Ed +.Pp +Configure two ethernets for failover with static IP in +.Pa /etc/rc.conf : +.Bd -literal -offset indent +cloned_interfaces="lagg0" +ifconfig_lagg0="laggproto failover laggport bge0 laggport bge1 \e + 10.1.29.21/24" +ifconfig_bge0="up" +ifconfig_bge1="up" +.Ed +.Sh SEE ALSO +.Xr ng_one2many 4 , +.Xr rc.conf 5 , +.Xr ifconfig 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +device first appeared in +.Fx 6.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written under the name +.Nm trunk +by +.An Reyk Floeter Aq Mt reyk@openbsd.org . +The LACP implementation was written by +.An YAMAMOTO Takashi +for +.Nx . +.Sh BUGS +There is no way to configure LACP administrative variables, including system +and port priorities. +The current implementation always performs active-mode LACP and uses 0x8000 as +system and port priorities. diff --git a/static/freebsd/man4/led.4 b/static/freebsd/man4/led.4 new file mode 100644 index 00000000..cf1685f0 --- /dev/null +++ b/static/freebsd/man4/led.4 @@ -0,0 +1,188 @@ +.\" Copyright (c) 2003 Sergey A. Osokin +.\" 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 ``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 24, 2007 +.Dt LED 4 +.Os +.Sh NAME +.Nm led +.Nd API for manipulating LED's, lamps and other annunciators +.Sh SYNOPSIS +.In dev/led/led.h +.Pp +.Fd "typedef void led_t(void *priv, int onoff);" +.Ft struct cdev * +.Fn led_create_state "led_t *func" "void *priv" "char const *name" "int state" +.Ft struct cdev * +.Fn led_create "led_t *func" "void *priv" "char const *name" +.Ft void +.Fn led_destroy "struct cdev *" +.Sh DESCRIPTION +The +.Nm +driver provides generic support for handling LEDs, lamps and other +annunciators. +.Pp +The hardware driver must supply a function to turn the annunciator on and off +and the device +.Fa name +of the annunciator relative to +.Pa /dev/led/ . +The +.Fa priv +argument is passed back to this on/off function and can be used however +the hardware driver sees fit. +.Pp +The lamp can be controlled by opening and writing +.Tn ASCII +strings to the +.Pa /dev/led/bla +device. +.Pp +In the following, we will use this special notation to indicate the resulting +output of the annunciator: +.Pp +.Bl -tag -width indent -offset indent -compact +.It Ic * +The annunciator is on for 1/10th second. +.It Ic _ +The annunciator is off for 1/10th second. +.El +.Pp +State can be set directly, and since the change happens immediately, +it is possible to flash the annunciator with very short periods and +synchronize it with program events. +It should be noted that there is a non-trivial overhead, so this may +not be usable for benchmarking or measuring short intervals. +.Pp +.Bl -tag -width indent -offset indent -compact +.It Ic 0 +Turn the annunciator off immediately. +.It Ic 1 +Turn the annunciator on immediately. +.El +.Pp +Flashing can be set with a given period. +The pattern continues endlessly. +.Pp +.Bl -tag -width indent -offset indent -compact +.It Ic f +_* +.It Ic f1 +_* +.It Ic f2 +__** +.It Ic f3 +___*** +.It ... +.It Ic f9 +_________********* +.El +.Pp +Three high-level commands are available: +.Bl -tag -width indent -offset indent +.It Ic d%d +Numbers. +Each digit is blinked out at 1/10th second, zero as ten pulses. +Between digits a one second pause and after the last +digit a two second pause after which the sequence is repeated. +.It Ic s%s +String. +This gives full control over the annunciator. +Letters +.Ql A +.No ... +.Ql J +turn the annunciator on for from 1/10th to one full +second. +Letters +.Ql a +.No ... +.Ql j +turn the annunciator off for 1/10th +to one full second. +Letters +.Ql u +and +.Ql U +turn the annunciator off and on respectively when the next +UTC second starts. +Unless terminated with a +.Ql \&. , +the sequence is immediately repeated. +.It Ic m%s +Morse. +.Pp +.Bl -tag -width indent -offset indent -compact +.It Ql \&. +becomes +.Ql _* +.It Ql - +becomes +.Sq Li _*** +.It Ql "\ " +becomes +.Sq Li __ +.It Ql \en +becomes +.Sq Li ____ +.El +.El +.Pp +The sequence is repeated after a one second pause. +.Sh FILES +.Bl -tag -width ".Pa /dev/led/*" +.It Pa /dev/led/* +.El +.Sh EXAMPLES +A +.Sq Li d12 +flashes the lamp +.Pp +.Dl *__________*_*______________________________ +.Pp +A +.Sq Li sAaAbBa +flashes +.Pp +.Dl *_*__**_ +.Bd -literal +/usr/bin/morse -l "Soekris rocks" > /dev/led/error +.Ed +.Sh SEE ALSO +.Xr morse 6 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 5.2 . +.Sh AUTHORS +.An -nosplit +This software was written by +.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org . +.Pp +This manual page was written by +.An Sergey A. Osokin Aq Mt osa@FreeBSD.org +and +.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org . diff --git a/static/freebsd/man4/lge.4 b/static/freebsd/man4/lge.4 new file mode 100644 index 00000000..6d527b9c --- /dev/null +++ b/static/freebsd/man4/lge.4 @@ -0,0 +1,155 @@ +.\" Copyright (c) 2001 Wind River Systems +.\" Copyright (c) 1997, 1998, 1999, 2000, 2001 +.\" Bill Paul . 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 Bill Paul. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Bill Paul 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 Bill Paul OR THE VOICES IN HIS HEAD +.\" 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 16, 2005 +.Dt LGE 4 +.Os +.Sh NAME +.Nm lge +.Nd "Level 1 LXT1001 NetCellerator PCI Gigabit Ethernet adapter driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device lge" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_lge_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for various NICs based on the Level 1 LXT1001 +NetCellerator Gigabit Ethernet controller chip. +.Pp +The LXT1001 supports fiber PHYs and also a GMII port for use with +10/100/1000 copper PHYs, however there are currently no NICs on the +market that use this feature. +.Pp +The LXT1001 supports TCP/IP checksum offload for receive and +VLAN-based filtering as well as a 64-bit multicast hash filter. +It also supports jumbo frames, which can be configured +via the interface MTU setting. +Selecting an MTU larger than 1500 bytes with the +.Xr ifconfig 8 +utility configures the adapter to receive and transmit jumbo frames. +Using jumbo frames can greatly improve performance for certain tasks, +such as file transfers and data streaming. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width ".Cm 1000baseSX" +.It Cm autoselect +Enable autoselection of the media type and options. +The user can manually override +the autoselected mode by adding media options to +.Xr rc.conf 5 . +.It Cm 1000baseSX +Set 1000baseSX operation over fiber optic cable. +Both +.Cm full-duplex +and +.Cm half-duplex +modes are supported. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width ".Cm full-duplex" +.It Cm full-duplex +Force full duplex operation. +.It Cm half-duplex +Force half duplex operation. +.El +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +Adapters supported by the +.Nm +driver include: +.Pp +.Bl -bullet -compact +.It +SMC TigerCard 1000 (SMC9462SX) +.It +D-Link DGE-500SX +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "lge%d: couldn't map memory" +A fatal initialization error has occurred. +.It "lge%d: couldn't map ports" +A fatal initialization error has occurred. +.It "lge%d: couldn't map interrupt" +A fatal initialization error has occurred. +.It "lge%d: no memory for softc struct!" +The driver failed to allocate memory for per-device instance information +during initialization. +.It "lge%d: failed to enable memory mapping!" +The driver failed to initialize PCI shared memory mapping. +This might +happen if the card is not in a bus-master slot. +.It "lge%d: no memory for jumbo buffers!" +The driver failed to allocate memory for jumbo frames during +initialization. +.It "lge%d: watchdog timeout" +The device has stopped responding to the network, or there is a problem with +the network connection (cable). +.El +.Sh SEE ALSO +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr ifconfig 8 +.Rs +.%T Level 1 LXT1001 Programming Manual +.%U https://www.FreeBSD.org/~wpaul/Level1/LXT1001SRM.pdf +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 4.4 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Bill Paul Aq Mt william.paul@windriver.com . diff --git a/static/freebsd/man4/lindebugfs.4 b/static/freebsd/man4/lindebugfs.4 new file mode 100644 index 00000000..34a19600 --- /dev/null +++ b/static/freebsd/man4/lindebugfs.4 @@ -0,0 +1,95 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2022, Jake Freeland +.\" +.\" 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 August 10, 2022 +.Dt LINDEBUGFS 4 +.Os +.Sh NAME +.Nm lindebugfs +.Nd Linux file system for debugging +.Sh SYNOPSIS +.Bd -literal +lindebugfs /sys/kernel/debug lindebugfs rw 0 0 +.Ed +.Sh DESCRIPTION +The debug file system, or debugfs, makes process debugging easier by +providing a simple API for data transfer between the kernel and user +space. +Debugfs is not a general-purpose file system and should not be used as +a storage medium. +Instead, developers can implement the debugfs interface in their code +to generate debug information about their program at runtime. +FreeBSD's +.Nm +uses the +.Xr pseudofs 9 +file system construction kit to model itself after Linux's debugfs. +The +.Nm +API is intended for use with programs that take advantage of FreeBSD's +LinuxKPI compatibility layer. +.Pp +When mounted, +.Nm +will populate with pseudo files from any running process that calls +.Nm debugfs_create_file() . +Since +.Nm +is a pseudo file system, file contents will be generated dynamically +based on program provided file operations. +The current +.Nm +implementation formally supports seq_file and simple_attr_file virtual +file formats. +.Sh EXAMPLES +Load the +.Nm +kernel module: +.Pp +.Dl "kldload lindebugfs" +.Pp +Mount the +.Nm +file system on +.Pa /sys/kernel/debug : +.Pp +.Dl "mount -t lindebugfs lindebugfs /sys/kernel/debug" +.Sh SEE ALSO +.Xr mount 1 , +.Xr linprocfs 4 , +.Xr linsysfs 4 , +.Xr linux 4 , +.Xr pseudofs 9 +.Sh HISTORY +The +.Nm +file system first appeared in +.Fx 12.1 . +.Sh AUTHORS +.An -nosplit +The initial implementation for +.Nm +was created by Matthew Macy. +This manual page was written by Jake Freeland. diff --git a/static/freebsd/man4/linprocfs.4 b/static/freebsd/man4/linprocfs.4 new file mode 100644 index 00000000..043dedbd --- /dev/null +++ b/static/freebsd/man4/linprocfs.4 @@ -0,0 +1,167 @@ +.\" Written by Garrett Wollman +.\" This file is in the public domain. +.\" +.Dd December 26, 2025 +.Dt LINPROCFS 4 +.Os +.Sh NAME +.Nm linprocfs +.Nd Linux process file system +.Sh SYNOPSIS +.Bd -literal +linprocfs /compat/linux/proc linprocfs rw 0 0 +.Ed +.Sh DESCRIPTION +The Linux process file system, or +.Nm , +emulates a subset of Linux' process file system and is required for +the complete operation of some Linux binaries. +.Pp +The +.Nm +provides a two-level view of process space. +At the highest level, processes themselves are named, according to +their process ids in decimal, with no leading zeros. +There is also a special node called +.Pa self +which always refers to the process making the lookup request. +.Pp +Each process node is a directory containing several files: +.Bl -tag -width oom_score_adj +.It Pa auxv +The auxiliary vector passed to the program. +.It Pa cmdline +The command line used to execute the process. +.It Pa cwd +A symbolic link pointing to the current work directory of the process. +.It Pa environ +The list of environment variables and values of the process. +Every variable and pair value is separated from the next by a NULL byte. +.It Pa exe +A reference to the vnode from which the process text was read. +This can be used to gain access to the process' symbol table, +or to start another copy of the process. +.It Pa limits +The soft and hard limits for the process along with the units used. +.It Pa maps +Memory map of the process. +.It Pa mem +The complete virtual memory image of the process. +Only those addresses which exist in the process can be accessed. +Reads and writes to this file modify the process. +Writes to the text segment remain private to the process. +.It Pa mountinfo +Information about mount points. +.It Pa mounts +Similar to the above. +.It Pa oom_score_adj +Score adjustment for the Out Of Memory killer. +.It Pa root +Symbolic link to the root directory for this process. +.It Pa stat +Process statistics. +It includes user, nice, system, idle, iowait, irq, softirq, +steal, guest and guest_nice. +.It Pa statm +Process size statistics. +It includes total program size, resident set size, number of resident shared +pages (unused), text size, library size (unused), data + stack and dirty pages +(unused). +.It Pa status +Process statistics in human readable form. +It includes process name, state, PID, +etc. +.It Pa task +Dummy directory to avoid problems in specific software such as Chromium. +.El +.Pp +Each node is owned by the process's user, and belongs to that user's +primary group, except for the +.Pa mem +node, which belongs to the +.Li kmem +group. +.Sh FILES +.Bl -tag -width /compat/linux/proc/filesystems -compact +.It Pa /compat/linux/proc +The normal mount point for +.Nm . +.It Pa /compat/linux/proc/cmdline +Contains the path of the kernel image used to boot the system. +.It Pa /compat/linux/proc/cpuinfo +CPU vendor and model information in human-readable form. +.It Pa /compat/linux/proc/devices +List of character and block devices. +The later is usually empty on +.Fx . +.It Pa /compat/linux/proc/filesystems +List of supported filesystems. +For pseudo filesystems, the first column contains +.Em nodev . +.It Pa /compat/linux/proc/meminfo +System memory information in human-readable form. +.It Pa /compat/linux/proc/modules +Loaded kernel modules. +Empty for now. +.It Pa /compat/linux/proc/mounts +Devices corresponding mount points. +.It Pa /compat/linux/proc/mtab +Same as above. +.It Pa /compat/linux/proc/partitions +Partition information including major and minor numbers, number of blocks and +name. +The rest of the fields are set to zero. +.It Pa /compat/linux/proc/stat +System statistics. +For each cpu it includes at most user time, nice time, system +time and idle time, iowait (time waiting for I/O to complete), times serving +irqs and softirq, steal, guest and guest_nice times that represent times spent +in different modes in a virtualized environment. +The last columns are set to zero. +This file also contains brief statistics for disks, context switches and +more. +.It Pa /compat/linux/proc/swap +Information about the swap device if any. +.It Pa /compat/linux/proc/uptime +Time since the last boot and time spent in idle state. +.It Pa /compat/linux/proc/version +Version of the emulated linux system. +.It Pa /compat/linux/proc/ Ns Ao Ar pid Ac +A directory containing process information for process +.Ar pid . +.It Pa /compat/linux/proc/self +A symlink to a directory containing process information for the current process. +.El +.Sh EXAMPLES +To mount a +.Nm +file system on +.Pa /compat/linux/proc : +.Pp +.Dl "mount -t linprocfs linprocfs /compat/linux/proc" +.Sh SEE ALSO +.Xr mount 2 , +.Xr unmount 2 , +.Xr auxv 3 , +.Xr linux 4 , +.Xr procfs 5 , +.Xr pseudofs 9 +.Sh HISTORY +The +.Nm +first appeared in +.Fx 4.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +was derived from +.Nm procfs +by +.An Pierre Beyssac . +This manual page was written by +.An Dag-Erling Sm\(/orgrav , +based on the +.Xr procfs 5 +manual page by +.An Garrett Wollman . diff --git a/static/freebsd/man4/linsysfs.4 b/static/freebsd/man4/linsysfs.4 new file mode 100644 index 00000000..045e1af8 --- /dev/null +++ b/static/freebsd/man4/linsysfs.4 @@ -0,0 +1,98 @@ +.\" Written by Garrett Wollman +.\" This file is in the public domain. +.\" +.Dd November 13, 2019 +.Dt LINSYSFS 4 +.Os +.Sh NAME +.Nm linsysfs +.Nd Linux kernel objects file system +.Sh SYNOPSIS +.Bd -literal +linsysfs /compat/linux/sys linsysfs rw 0 0 +.Ed +.Sh DESCRIPTION +The +.Tn Linux +system file system, or +.Nm , +emulates a subset of the +.Tn Linux +sys file system and is required for +the complete operation of some +.Tn Linux +binaries. +.Pp +The +.Nm +provides a two-level view of devices. +At the highest level, PCI devices themselves are named, according to +their bus, slot and function in the system hierarchy. +PCI storage devices are listed in the +.Pa scsi_host +class with a device symlink +to the PCI directories of the devices. +.Pp +Each device node is a directory containing some files and directories: +.Bl -tag -width ".Pa status" +.It Pa host +A place holder for storage host information. +.It Pa pci_id +A directory for the +.Pa pci_id +that contains either the device information or another directory structure +for a PCI bridge. +.El +.Pp +Each host node of scsi_host is a directory containing some files and directories: +.Bl -tag -width ".Pa proc_name" +.It Pa proc_name +The +.Tn Linux +registered driver name for these devices. +.It Pa device +A symlink to the PCI device directory. +.El +.Sh FILES +.Bl -tag -width ".Pa /compat/linux/sys/devices/pci0000:00" -compact +.It Pa /compat/linux/sys +The normal mount point for +.Nm . +.It Pa /compat/linux/sys/class/scsi_host +The storage host node. +.It Pa /compat/linux/sys/devices/pci0000:00 +The PCI device hierarchy node. +.El +.Sh EXAMPLES +The most common usage follows: +.Pp +.Dl "mount -t linsysfs linsysfs /compat/linux/sys" +.Pp +where +.Pa /compat/linux/sys +is a mount point. +.Sh SEE ALSO +.Xr nmount 2 , +.Xr unmount 2 , +.Xr linprocfs 4 , +.Xr linux 4 , +.Xr pseudofs 9 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 6.2 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was derived from +.Nm linprocfs +by +.An Doug Ambrisko . +This manual page was edited by +.An Doug Ambrisko , +based on the +.Xr linprocfs 4 +manual page by +.An Garrett Wollman . diff --git a/static/freebsd/man4/linux.4 b/static/freebsd/man4/linux.4 new file mode 100644 index 00000000..711ac11e --- /dev/null +++ b/static/freebsd/man4/linux.4 @@ -0,0 +1,198 @@ +.\" Copyright (c) 2000 Sheldon Hearn +.\" 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 May 19, 2024 +.Dt LINUX 4 +.Os +.Sh NAME +.Nm linux +.Nd Linux ABI support +.Sh SYNOPSIS +To enable the Linux ABI at boot time, place the following line in +.Xr rc.conf 5 : +.Bd -literal -offset indent +linux_enable="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +kernel module provides limited Linux ABI (application binary interface) +compatibility, making it possible to run many unmodified Linux applications +without the need for virtualization or emulation. +Some of the facilities provided are: +.Bl -bullet +.It +Linux to native system call translation +.It +Linux-specific system calls +.It +Special signal handling for Linux processes +.It +Path translation mechanism +.It +Linux-specific virtual file systems +.El +.Pp +The path translation mechanism makes Linux processes look up file paths +under +.Va emul_path +(defaulting to +.Pa /compat/linux ) +before +.Pa / . +For example, when a Linux process attempts to open +.Pa /etc/passwd , +it will first access +.Pa /compat/linux/etc/passwd , +falling back to +.Pa /etc/passwd +if the compat path does not exist. +This is used to make sure Linux processes load Linux shared libraries +instead of their similarly-named FreeBSD counterparts, and also +to provide alternative versions of certain other files and virtual +file systems. +.Pp +To install Linux shared libraries and system files into +.Pa /compat/linux , +either use the +.Pa emulators/linux_base-c7 +port or package, +or +.Xr debootstrap 8 +installed from +.Pa sysutils/debootstrap . +.Pp +To avoid mounting Linux-specific filesystems at startup, add the following +line to the +.Xr rc.conf 5 +file: +.Pp +.Dl linux_mounts_enable="NO" +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va compat.linux.debug +Enable debugging messages. +Set to 0 to silence them. +Defaults to 3. +A setting of 1 prints debug messages, tells about unimplemented stuff (only +once). +Set to 2 is like 1, but also prints messages about implemented but not tested +stuff (only once). +Setting it to 3 or higher is like 2, but no rate limiting of messages. +.It Va compat.linux.default_openfiles +Default soft openfiles resource limit for Linux applications. +Set to -1 to disable the limit. +Defaults to 1024. +.It Va compat.linux.emul_path +Path to the Linux run-time environment. +Defaults to +.Pa /compat/linux . +.It Va compat.linux.osname +Linux kernel operating system name. +Defaults to "Linux". +.It Va compat.linux.osrelease +Linux kernel operating system release. +Changing this to something else is discouraged on non-development systems, +because it may change the way Linux programs work. +Some versions of GNU libc are known to use different syscalls depending +on the value of this sysctl. +.It Va compat.linux.oss_version +Linux Open Sound System version. +Defaults to 198144. +.It Va compat.linux.preserve_vstatus +When set to 1, it prevents Linux applications from resetting the +.Xr termios 4 +VSTATUS setting. +From a user perspective, this makes +.Va SIGINFO +work for Linux executables. +Defaults to 1. +.It Va compat.linux.setid_allowed +Enable handling of set-user-ID and set-group-ID mode bits for the new +process image file when image is to be executed under Linux ABI. +When set to 0, new Linux images always use credentials of the program +that issued the +.Xr execve 2 +call, regardless of the image file mode. +This might be reasonable or even required, because +.Fx +does not emulate the Linux environment completely, and missed features +may result in security vulnerabilities. +Defaults to 1. +.It Va compat.linux32.emulate_i386 +In the x86_64 (amd64) world enable the real i386 Linuxulator behavior. +For example, when set to 0, Linux uname -m will return "x86_64" even if +uname itself is a i386 Linux executable. When set to 1, Linux i386 +uname -m will return "i686". +Defaults to 0. +.El +.Sh FILES +.Bl -tag -width /compat/linux/dev/shm -compact +.It Pa /compat/linux +Linux run-time environment +.It Pa /compat/linux/dev +device file system, see +.Xr devfs 4 +.It Pa /compat/linux/dev/fd +file descriptor file system mounted with the +.Cm linrdlnk +option, see +.Xr fdescfs 4 +.It Pa /compat/linux/dev/mqueue +symbolic link to a mqueuefs mount, see +.Xr mqueuefs 4 +.It Pa /compat/linux/dev/shm +in-memory file system, see +.Xr tmpfs 4 +.It Pa /compat/linux/proc +Linux process file system, see +.Xr linprocfs 4 +.It Pa /compat/linux/sys +Linux kernel objects file system, see +.Xr linsysfs 4 +.El +.Sh SEE ALSO +.Xr brandelf 1 , +.Xr fdescfs 4 , +.Xr linprocfs 4 , +.Xr linsysfs 4 , +.Xr mqueuefs 4 , +.Xr pty 4 , +.Xr tmpfs 4 , +.Xr elf 5 +.Sh HISTORY +Linux ABI support first appeared for i386 in +.Fx 2.1 . +Support for amd64 binaries first appeared in +.Fx 10.3 . +Support for arm64 binaries first appeared in +.Fx 12.0 . +.Sh BUGS +Support for some of the Linux-specific system calls and system call arguments +is missing. diff --git a/static/freebsd/man4/linuxkpi.4 b/static/freebsd/man4/linuxkpi.4 new file mode 100644 index 00000000..cd4135c2 --- /dev/null +++ b/static/freebsd/man4/linuxkpi.4 @@ -0,0 +1,42 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 The FreeBSD Foundation +.\" +.\" This documentation was written by Bj\xc3\xb6rn Zeeb under sponsorship from +.\" the FreeBSD Foundation. +.\" +.Dd June 13, 2025 +.Dt LINUXKPI 4 +.Os +.Sh NAME +.Nm linuxkpi +.Nd Linux Kernel Programming Interface support +.Sh DESCRIPTION +The +.Nm +kernel module provides a limited KPI (kernel programming interface) to allow +Linux kernel drivers and other Linux kernel code to be compiled on +.Fx +and used along the +.Fx +kernel with little or no modification. +.Pp +While historically +.Em OpenFabrics Enterprise Distribution (Infiniband) , +and certain vendor drivers have used +.Nm . +.Em drm-kmod +for graphics driver support +and +.Xr linuxkpi_wlan 4 +for wireless drivers are prominent consumers. +.Pp +.Nm +is not to be confused with +.Xr linux 4 +which provides limited Linux ABI (application binary interface) compatibility +to allow running Linux application binaries unmodified on +.Fx . +.Sh SEE ALSO +.Xr linuxkpi_wlan 4 diff --git a/static/freebsd/man4/linuxkpi_wlan.4 b/static/freebsd/man4/linuxkpi_wlan.4 new file mode 100644 index 00000000..65c77d8d --- /dev/null +++ b/static/freebsd/man4/linuxkpi_wlan.4 @@ -0,0 +1,141 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 The FreeBSD Foundation +.\" +.\" This documentation was written by Bj\xc3\xb6rn Zeeb under sponsorship from +.\" the FreeBSD Foundation. +.\" +.Dd December 28, 2025 +.Dt LINUXKPI_WLAN 4 +.Os +.Sh NAME +.Nm linuxkpi_wlan +.Nd LinuxKPI 802.11 support +.Sh DESCRIPTION +The +.Nm +kernel module provides an 802.11 compat layer to translate between Linux +802.11 drivers and the native net8011 wireless stack. +It currently supports +.Em mac80211 +based drivers. +Parts of the +.Em cfg80211 +exist but there is no code for net80211 to drive it. +.Pp +.Nm +currently supports the following +.Em wlanmode +operating modes: +.Bl -tag -width monitor -compact +.It Cm sta +client station in an infrastructure bss (IBSS). +.El +.Pp +Compat code for 802.11n (HT) and 802.11ac (VHT) is implemented but +support may vary for different drivers due to different KPI usage. +.Pp +Crypto support for hardware acceleration needs to be enabled using the +.Va compat.linuxkpi.80211.hw_crypto +tunable. +The following cipher suites are supported: +.Bl -tag -width CCMP -compact +.It Cm tkip +Support for +.Xr wlan_tkip 4 +has to be manually enabled using the +.Va compat.linuxkpi.80211.tkip +tunable. +.It Cm ccmp +Support for +.Xr wlan_ccmp 4 +is available. +.It Cm gcmp +Support for +.Xr wlan_gcmp 4 +is available. +.El +Further cipher suites will be implemented as soon as +.Xr net80211 4 +grows support. +While it would be possible to implement +.Xr wlan_wep 4 +support, it was decided not to do so given +.Em Wired Equivalent Privacy (WEP) +has been deprecated since 2004. +.Pp +The list of supported drivers includes +.Xr iwlwifi 4 , +.Xr rtw88 4 , +and +.Xr rtw89 4 . +.Sh SYSCTL VARIABLES AND LOADER TUNABLES +The +.Nm +module supports the following +.Xr loader 8 +tunable and read-only +.Xr sysctl 8 +variables: +.Bl -tag -width "compat.linuxkpi.80211.hw_crypto" +.It Va compat.linuxkpi.80211.hw_crypto +Turn on hardware crypto offload support. +Default +.Ql 0 . +.It Va compat.linuxkpi.80211.tkip +Turn on support for +.Xr wlan_tkip 4 +offloading. +Default +.Ql 0 . +.El +.Pp +The +.Nm +module supports the following +.Xr sysctl 8 +variables: +.Bl -tag -width "compat.linuxkpi.80211.IF.dump_stas" +.It Va compat.linuxkpi.80211.debug +If the kernel is compiled with +.Dv IEEE80211_DEBUG +or +.Dv LINUXKPI_DEBUG_80211 +is manually enabled, the sysctl is a bitmask to turn on individual +debug messages. +See +.Pa sys/compat/linuxkpi/common/src/linux_80211.h +for details. +.It Va compat.linuxkpi.80211.IF.dump_stas +Print statistics for a given, associated +.Xr wlan 4 +interface; typically IF would be +.Em wlan0 . +.It Va compat.linuxkpi.80211.IF.dump_stas_queues +Like +.Va compat.linuxkpi.80211.IF.dump_stas +but also print queue statistics. +This sysctl is +.Sq hidden +and normally only needed for debugging purposes. +.El +.Sh SEE ALSO +.Xr iwlwifi 4 , +.Xr linuxkpi 4 , +.Xr rtw88 4 , +.Xr rtw89 4 , +.Xr wlan 4 +.Sh HISTORY +The +.Nm +module first appeared in +.Fx 13.1 . +Support for IEEE 802.11n and 802.11ac in +.Nm +first appeared in +.Fx 14.3 . +.Sh AUTHORS +LinuxKPI 802.11 support was developed by +.An Bjoern A. Zeeb +under sponsorship from the FreeBSD Foundation. diff --git a/static/freebsd/man4/liquidio.4 b/static/freebsd/man4/liquidio.4 new file mode 100644 index 00000000..27372e60 --- /dev/null +++ b/static/freebsd/man4/liquidio.4 @@ -0,0 +1,132 @@ +.\" BSD LICENSE +.\" +.\" Copyright(c) 2017 Cavium, Inc.. All rights reserved. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" * Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" * 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. +.\" * Neither the name of Cavium, Inc. nor the names of its +.\" contributors may be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 COPYRIGHT +.\" OWNER(S) 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 August 17, 2017 +.Dt LIQUIDIO 4 +.Os +.Sh NAME +.Nm liquidio +.Nd Cavium 10Gb/25Gb Ethernet driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device lio" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_lio_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for 23XX 10Gb/25Gb Ethernet adapters. +The driver supports Jumbo Frames, Transmit/Receive checksum +offload, TCP segmentation offload (TSO), Large Receive Offload (LRO), +VLAN tag insertion/extraction, VLAN checksum offload, +VLAN TSO, and Receive Side Steering (RSS) +.Pp +Support for Jumbo Frames is provided via the interface MTU setting. +Selecting an MTU larger than 1500 bytes with the +.Xr ifconfig 8 +utility configures the adapter to receive and transmit Jumbo Frames. +The maximum MTU size for Jumbo Frames is 16000. +.Pp +For more information on configuring this device, see ifconfig(8). +.Sh HARDWARE +The +.Nm +driver supports the following cards: +.Pp +.Bl -bullet -compact +.It +LiquidIO II CN2350 210SV/225SV +.It +LiquidIO II CN2360 210SV/225SV +.El +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width indent +.It Va hw.lio.fw_type +.Pp +String that specifies type of firmware to be loaded. +Default is "nic". Use "none" to load firmware from flash. +.It Va hw.lio.num_queues_per_pf0 +.Pp +Unsigned integers that specify number of queues per PF0. +Valid range is 0 to 64. +Use 0 to derive autoconfigures based on the number of +cpus with a max of 8 +.It Va hw.lio.num_queues_per_pf1 +.Pp +Unsigned integers that specify number of queues per PF1. +Valid range is 0 to 64. +Use 0 to derive autoconfigures based on the number of +cpus with a max of 8 +.It Va hw.lio.console_bitmask +.Pp +Bitmask indicating which consoles have debug output +redirected to syslog. +.It Va hw.lio.rss +.Pp +To enable/disable driver RSS support +.It Va hw.lio.hwlro +.Pp +To enable/disable hardware LRO +.El +.Sh SUPPORT +For general information and support, +go to the Cavium support website at: +.Pa http://support.cavium.com . +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 12.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Derek Chickles Aq Mt derek.chickles@cavium.com . diff --git a/static/freebsd/man4/lm75.4 b/static/freebsd/man4/lm75.4 new file mode 100644 index 00000000..1eecdfad --- /dev/null +++ b/static/freebsd/man4/lm75.4 @@ -0,0 +1,186 @@ +.\" +.\" Copyright (c) 2014 Luiz Otavio O Souza +.\" 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 ``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 December 26, 2017 +.Dt LM75 4 +.Os +.Sh NAME +.Nm lm75 +.Nd lm75 i2c digital temperature sensor driver +.Sh SYNOPSIS +.Cd "device iic" +.Cd "device iicbus" +.Cd "device lm75" +.Sh DESCRIPTION +The +.Nm +driver provides access to sensor data and configuration over the +.Xr iicbus 4 . +.Pp +It provides an easy and simple way to check the functionality of an i2c bus +as it provides read and write access to the +.Nm +configuration register. +.Pp +The access to +.Nm +data is made via the +.Xr sysctl 8 +interface: +.Bd -literal +dev.lm75.0.%desc: LM75 temperature sensor +dev.lm75.0.%driver: lm75 +dev.lm75.0.%location: addr=0x49 +dev.lm75.0.%pnpinfo: name=lm750 compat=national,lm75 +dev.lm75.0.%parent: iicbus3 +dev.lm75.0.temperature: 27.1C +dev.lm75.0.thyst: 75.0C +dev.lm75.0.tos: 80.0C +dev.lm75.0.faults: 1 +dev.lm75.0.mode: comparator +dev.lm75.0.polarity: active-low +dev.lm75.0.shutdown: 0 +.Ed +.Bl -tag -width ".Va dev.lm75.%d.temperature" +.It Va dev.lm75.%d.temperature +Is the read-only value of the current temperature read by the sensor. +.It Va dev.lm75.%d.thyst +Sets the hysteresis temperature. +Once the temperature gets over the overtemperature shutdown value (tos) +it needs to drop below the hysteresis temperature to disable the output +(interrupt) pin again. +.It Va dev.lm75.%d.tos +Sets the overtemperature shutdown value. +Once the temperature gets over this value the output pin will be enabled. +The way the output (interrupt) pin works, depends on the mode configuration. +.It Va dev.lm75.%d.faults +Is the number of faults that must occur consecutively to activate the +interrupt (output) pin. +It can be set to 1, 2, 4, and 6. +.It Va dev.lm75.%d.mode +Sets the operation mode for the sensor interrupt pin. +It can be set to 'comparator' (default) or 'interrupt'. +.It Va dev.lm75.%d.polarity +Sets the polarity of the sensor interrupt pin. +It can be set to 'active-low' (default) or 'active-high'. +Please note that the output pin is an open-drain output and it needs a +proper pull-up resistor to work. +.It Va dev.lm75.%d.shutdown +When set to '1' it shuts down the sensor. +The temperature conversion stops but the sensor remains with its i2c bus +active, i.e., it can be woken up by setting this option to '0' again. +.El +.Pp +Please check the +.Nm +datasheet for more details. +.Pp +When used together with +.Xr snmp_lm75 3 +it allows the monitoring of +.Nm +temperature data over SNMP. +.Pp +The +.Nm +driver supports both the low and the high resolution models. +.Pp +The low resolution model (lm75) provides a 9 bit output with the LSB +representing 0.5C. +.Pp +The high resolution model (lm75a) provides an 11 bit output with the LSB +representing 0.125C. +.Pp +The driver tries to auto-detect the +.Nm +model, but the detection of some +.Nm +clones may not work reliably. +.Pp +On a +.Xr device.hints 5 +based system, such as +.Li MIPS , +these values are configurable for +.Nm : +.Bl -tag -width ".Va hint.lm75.%d.addr" +.It Va hint.lm75.%d.at +Is the +.Xr iicbus 4 +you are attaching to. +.It Va hint.lm75.%d.addr +Is the +.Nm +i2c address on the +.Xr iicbus 4 . +.El +.Pp +On a +.Xr FDT 4 +based system, such as +.Li ARM , +the DTS part for a +.Nm +device usually looks like: +.Bd -literal +i2c { + /* Properties describing the controller appear here. */ + ... + lm750@49 { + compatible = "national,lm75"; + reg = <0x49>; + }; +}; +.Ed +.Pp +Where: +.Bl -tag -width ".Va compatible" +.It Va compatible +Should always be set to "national,lm75". +.It Va reg +Indicates which 7-bit i2c address the +.Nm +is wired at. +.Nm +temperature sensors can be wired to 8 different addresses, allowing up to 8 +sensors on the same +.Xr iicbus 4 . +.El +.Sh SEE ALSO +.Xr snmp_lm75 3 , +.Xr fdt 4 , +.Xr iic 4 , +.Xr iicbus 4 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 11.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver and this manual page were written by +.An Luiz Otavio O Souza Aq Mt loos@FreeBSD.org . diff --git a/static/freebsd/man4/lo.4 b/static/freebsd/man4/lo.4 new file mode 100644 index 00000000..7bad739e --- /dev/null +++ b/static/freebsd/man4/lo.4 @@ -0,0 +1,87 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. +.\" Copyright (c) 2009 Robert N. M. Watson +.\" 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 June 23, 2024 +.Dt LO 4 +.Os +.Sh NAME +.Nm lo +.Nd software loopback network interface +.Sh SYNOPSIS +.Cd "device loop" +.Sh DESCRIPTION +The +.Nm loop +interface is a software loopback mechanism which may be +used for performance analysis, software testing, and/or local +communication. +As with other network interfaces, the loopback interface must have +network addresses assigned for each address family with which it is to be used. +These addresses +may be set with the appropriate +.Xr ioctl 2 +commands for corresponding address families. +The loopback interface should be the last interface configured, +as protocols may use the order of configuration as an indication of priority. +The loopback should +.Em never +be configured first unless no hardware +interfaces exist. +.Pp +If the transmit checksum offload capability flag is enabled on a loopback +interface, checksums will not be generated by IP, UDP, TCP, or SCTP for packets +sent on the interface. +.Pp +If the receive checksum offload capability flag is enabled on a loopback +interface, checksums will not be validated by IP, UDP, TCP, or SCTP for packets +received on the interface. +.Pp +By default, both receive and transmit checksum flags will be enabled, in +order to avoid the overhead of checksumming for local communication where +data corruption is unlikely. +If transmit checksum generation is disabled, then validation should also be +disabled in order to avoid packets being dropped due to invalid checksums. +.Sh DIAGNOSTICS +.Bl -diag +.It lo%d: can't handle af%d. +The interface was handed +a message with addresses formatted in an unsuitable address +family; the packet was dropped. +.El +.Sh SEE ALSO +.Xr inet 4 , +.Xr intro 4 +.\" .Xr ns 4 +.Sh HISTORY +The +.Nm +device appeared in +.Bx 4.2 . +The current checksum generation and validation avoidance policy appeared in +.Fx 8.0 . diff --git a/static/freebsd/man4/lp.4 b/static/freebsd/man4/lp.4 new file mode 100644 index 00000000..8ca65696 --- /dev/null +++ b/static/freebsd/man4/lp.4 @@ -0,0 +1,240 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 A.R.Gordon, andrew.gordon@net-tel.co.uk +.\" 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" 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. +.\" +.\" Id: man4.i386/lp.4,v 1.9 1999/02/14 12:06:16 nsouch Exp +.\" +.Dd March 4, 1996 +.Dt LP 4 +.Os +.Sh NAME +.Nm lp +.Nd printer port Internet Protocol driver +.Sh SYNOPSIS +.Nm ifconfig +.Ar plip0 +.Ar myaddress hisaddress +.Op Fl link0 +.Pp +.Cd "device ppbus" +.Cd "device plip" +.Cd "device ppc" +.Sh DESCRIPTION +The +.Nm +driver allows a PC parallel printer port to be used as a +point-to-point network interface between two similarly configured systems. +Data is transferred 4 bits at a time, using the printer status lines for +input: hence there is no requirement for special bidirectional hardware +and any standard AT-compatible printer port with working interrupts may be used. +.Pp +During the boot process, for each +.Nm plip +device which is probed and has an interrupt assigned, a corresponding +.Nm network +device is created. +.Pp +Configuring an +.Nm +device with +.Xr ifconfig 8 +causes the corresponding +.Nm parallel port bus +to be reserved for PLIP until the network interface is configured 'down'. +.Pp +The communication protocol is selected by the +.Cm link0 +flag: +.Bl -tag -width Fl +.It Fl link0 +(default) Use +.Fx +mode (LPIP). +This is the simpler of the two modes +and therefore slightly more efficient. +.It Cm link0 +Use Crynwr/Linux compatible mode (CLPIP). +This mode has a simulated Ethernet +packet header, and is easier to interface to other types of equipment. +.El +.Pp +The interface MTU defaults to 1500, but may be set to any value. +Both ends +of the link must be configured with the same MTU. +.Ss Cable Connections +The cable connecting the two parallel ports should be wired as follows: +.Bd -literal + Pin Pin Description + 2 15 Data0 -> ERROR* + 3 13 Data1 -> SLCT + 4 12 Data2 -> PE + 5 10 Data3 -> ACK* + 6 11 Data4 -> BUSY + 15 2 ERROR* -> Data0 + 13 3 SLCT -> Data1 + 12 4 PE -> Data2 + 10 5 ACK* -> Data3 + 11 6 BUSY -> Data4 + 18-25 18-25 Ground +.Ed +.Pp +Cables with this wiring are widely available as 'Laplink' cables, and +are often coloured yellow. +.Pp +The connections are symmetric, and provide 5 lines in each direction (four +data plus one handshake). +The two modes use the same wiring, but make a +different choice of which line to use as handshake. +.Ss FreeBSD LPIP mode +The signal lines are used as follows: +.Bl -tag -width dataxxxx(Pinxx) +.It Em Data0 (Pin 2) +Data out, bit 0. +.It Em Data1 (Pin 3) +Data out, bit 1. +.It Em Data2 (Pin 4) +Data out, bit 2. +.It Em Data3 (Pin 5) +Handshake out. +.It Em Data4 (Pin 6) +Data out, bit 3. +.It Em ERROR* (pin 15) +Data in, bit 0. +.It Em SLCT (pin 13) +Data in, bit 1. +.It Em PE (pin 12) +Data in, bit 2. +.It Em BUSY (pin 11) +Data in, bit 3. +.It Em ACK* (pin 10) +Handshake in. +.El +.Pp +When idle, all data lines are at zero. +Each byte is signalled in four steps: +sender writes the 4 most significant bits and raises the handshake line; +receiver reads the 4 bits and raises its handshake to acknowledge; +sender places the 4 least significant bits on the data lines and lowers +the handshake; receiver reads the data and lowers its handshake. +.Pp +The packet format has a two-byte header, comprising the fixed values 0x08, +0x00, immediately followed by the IP header and data. +.Pp +The start of a packet is indicated by simply signalling the first byte +of the header. +The end of the packet is indicated by inverting +the data lines (i.e., writing the ones-complement of the previous nibble +to be transmitted) without changing the state of the handshake. +.Pp +Note that the end-of-packet marker assumes that the handshake signal and +the data-out bits can be written in a single instruction - otherwise +certain byte values in the packet data would falsely be interpreted +as end-of-packet. +This is not a problem for the PC printer port, +but requires care when implementing this protocol on other equipment. +.Ss Crynwr/Linux CLPIP mode +The signal lines are used as follows: +.Bl -tag -width dataxxxx(Pinxx) +.It Em Data0 (Pin 2) +Data out, bit 0. +.It Em Data1 (Pin 3) +Data out, bit 1. +.It Em Data2 (Pin 4) +Data out, bit 2. +.It Em Data3 (Pin 5) +Data out, bit 3. +.It Em Data4 (Pin 6) +Handshake out. +.It Em ERROR* (pin 15) +Data in, bit 0. +.It Em SLCT (pin 13) +Data in, bit 1. +.It Em PE (pin 12) +Data in, bit 2. +.It Em ACK* (pin 10) +Data in, bit 3. +.It Em BUSY (pin 11) +Handshake in. +.El +.Pp +When idle, all data lines are at zero. +Each byte is signalled in four steps: +sender writes the 4 least significant bits and raises the handshake line; +receiver reads the 4 bits and raises its handshake to acknowledge; +sender places the 4 most significant bits on the data lines and lowers +the handshake; receiver reads the data and lowers its handshake. +[Note that this is the opposite nibble order to LPIP mode]. +.Pp +Packet format is: +.Bd -literal +Length (least significant byte) +Length (most significant byte) +12 bytes of supposed MAC addresses (ignored by FreeBSD). +Fixed byte 0x08 +Fixed byte 0x00 + +Checksum byte. +.Ed +.Pp +The length includes the 14 header bytes, but not the length bytes themselves +nor the checksum byte. +.Pp +The checksum is a simple arithmetic sum of all the bytes (again, including +the header but not checksum or length bytes). +.Fx +calculates +outgoing checksums, but does not validate incoming ones. +.Pp +The start of packet has to be signalled specially, since the line chosen +for handshake-in cannot be used to generate an interrupt. +The sender writes the value 0x08 to the data lines, and waits for the receiver +to respond by writing 0x01 to its data lines. +The sender then starts +signalling the first byte of the packet (the length byte). +.Pp +End of packet is deduced from the packet length and is not signalled +specially (although the data lines are restored to the zero, idle +state to avoid spuriously indicating the start of the next packet). +.Sh SEE ALSO +.Xr ppbus 4 , +.Xr ppc 4 , +.Xr ifconfig 8 +.Sh BUGS +Busy-waiting loops are used while handshaking bytes, (and worse still when +waiting for the receiving system to respond to an interrupt for the start +of a packet). +Hence a fast system talking to a slow one will consume +excessive amounts of CPU. +This is unavoidable in the case of CLPIP mode +due to the choice of handshake lines; it could theoretically be improved +in the case of LPIP mode. +.Pp +Polling timeouts are controlled by counting loop iterations rather than +timers, and so are dependent on CPU speed. +This is somewhat stabilised +by the need to perform (slow) ISA bus cycles to actually read the port. diff --git a/static/freebsd/man4/lpbb.4 b/static/freebsd/man4/lpbb.4 new file mode 100644 index 00000000..73d9d601 --- /dev/null +++ b/static/freebsd/man4/lpbb.4 @@ -0,0 +1,77 @@ +.\" Copyright (c) 1998, Nicolas Souchu +.\" 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 October 25, 1998 +.Dt LPBB 4 +.Os +.Sh NAME +.Nm lpbb +.Nd parallel port I2C bit-banging interface +.Sh SYNOPSIS +.Cd "device iicbus" +.Cd "device iicbb" +.Pp +.Cd "device lpbb" +.Cd "device iic" +.Sh DESCRIPTION +The +.Em lpbb +driver supports the Philips official I2C parallel bit-banging interface. +.Bd -literal + + LS05 pin 14 (Vcc) o ------- + | | | + +--+--+---------------------+--+--+------------+------+-o 1 | + | | | | | | ===.1uF | +5V | + -------- [R][R][R] 3x10K 3x10K [R][R][R] LS05 | | | + | | | | | | | | pin 7 o-+------+-o 2 | + | 12 o-+--+ | | 3|\\ 4 | | | (Gnd) | GND | + | 17 o-+-----|--|----| >o-------------+--|--|--------------+ | | + | | | | |/ 8 /|9 | | 10 /|11 +----+-o 3 | + | 15 o-+-----+--|--------------o< |------+--|------o< |----+ | SCL | + | | | 1|\\ 2 \\| | \\| | | + | 9 o-+--------|----| >o-------------------+--------------+----+-o 4 | + | | | |/ 6 /|5 | | SDA | + | 11 o-+--------+----------------------------------o< |----+ ------- + | 10 o-+-+ \\| 4-pin + | 13 o-+-+--oGND Connector + | 25 o-+-+ ------------------ Part List -------------------------- + -------- | 1 - .1 uF capacitor | 6 - 10K 5% resistors | + 25-pin male D | 1 - 4-pin connector | 1 - 25-pin male D connector | + connector to PC | 1 - 74LS05 open collector hex inverter | + printer port ------------------------------------------------------- +.Ed +.Sh SEE ALSO +.Xr iicbb 4 , +.Xr iicbus 4 , +.Xr ppbus 4 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 3.0 . +.Sh AUTHORS +This +manual page was written by +.An Nicolas Souchu . diff --git a/static/freebsd/man4/lpt.4 b/static/freebsd/man4/lpt.4 new file mode 100644 index 00000000..aea1a832 --- /dev/null +++ b/static/freebsd/man4/lpt.4 @@ -0,0 +1,96 @@ +.\" +.\" Copyright (c) 1993 Christopher G. Demetriou +.\" Copyright (c) 1994 Geoffrey M. Rehmet +.\" Copyright (c) 1999 Nicolas Souchu +.\" 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 February 14, 1999 +.Dt LPT 4 +.Os +.Sh NAME +.Nm lpt +.Nd generic printer device driver +.Sh SYNOPSIS +.Cd "device ppc" +.Cd "device ppbus" +.Cd "device lpt" +.Sh DESCRIPTION +The current +.Em lpt +driver is the port of the original lpt driver to the +.Xr ppbus 4 +system. +.Pp +One purpose of this port was to allow parallel port sharing with other +parallel devices. +Secondly, inb()/outb() calls have been replaced by ppbus +function calls. +lpt is now arch-independent thanks to the ppbus interface. +See +.Xr ppbus 4 +for more info about the ppbus system. +.Pp +The parallel port bus is allocated by lpt when the printer device is opened +and released only when the transfer is completed: either when the device +is closed or when the entire buffer is sent in interrupt driven mode. +.Pp +The driver can be configured to be either interrupt-driven, or +to poll the printer. +Ports that are configured to be +interrupt-driven can be switched to polled mode by using the +.Xr lptcontrol 8 +command. +.Pp +Depending on your hardware, extended capabilities may be configured with the +.Xr lptcontrol 8 +command. +With an ECP/ISA port, you can take advantage +of FIFO and DMA. +.Pp +In order to retrieve printer info from /dev/lpt0, just apply the +.Nm cat +command to the device. +If the printer supports IEEE1284 nibble mode and has +data to send to the host, you will get it. +.Sh FILES +.Bl -tag -width Pa -compact +.It Pa /dev/lpt0 +first parallel port driver +.El +.Sh SEE ALSO +.Xr ppbus 4 , +.Xr ppc 4 , +.Xr lptcontrol 8 +.Sh HISTORY +This driver replaces the functionality of the lpa +driver, which is now defunct. +.Sh BUGS +There are lots of them, especially in cheap parallel port implementations. +.Pp +It is only possible to open a lpt port when a printer is connected and +on-line, making it impossible to run +.Xr lptcontrol 8 +when there is no printer connected. +.Pp +This driver could still stand a rewrite. diff --git a/static/freebsd/man4/ltc430x.4 b/static/freebsd/man4/ltc430x.4 new file mode 100644 index 00000000..91a0fe5d --- /dev/null +++ b/static/freebsd/man4/ltc430x.4 @@ -0,0 +1,143 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2019 Ian Lepore +.\" +.\" 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 September 2, 2020 +.Dt LTC430X 4 +.Os +.Sh NAME +.Nm ltc430x +.Nd driver for LTC4305 and LTC4306 I2C mux chips +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ltc430x" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ltc430x_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports the LTC4305 and LTC4306 I2C bus multiplexer (mux) chips. +It automatically connects an upstream I2C bus to one of several downstream +buses as needed when slave devices on the downstream buses initiate I/O. +More information on the automatic switching behavior is available in +.Xr iicmux 4 . +.Sh FDT CONFIGURATION +On an +.Xr fdt 4 +based system, an +.Nm +device node is defined as a child node of its upstream i2c bus. +The children of the +.Nm +node are additional i2c buses, which will have their own i2c slave +devices described in their child nodes. +.Pp +The +.Nm +driver conforms to the standard +.Bk -words +.Li i2c/i2c-mux-ltc4306.txt +.Ek +bindings document, except that the following optional properties +are not currently supported and will be ignored if present: +.Bl -bullet -compact -inset -offset indent +.It +enable-gpios +.It +gpio-controller +.It +#gpio-cells +.It +ltc,downstream-accelerators-enable +.It +ltc,upstream-accelerators-enable +.El +.Pp +In addition, the following additional property is supported: +.Bl -tag -offset indent -width indent +.It Va freebsd,ctlreg2 +A value to store into the chip's control register 2 during initialization. +Consult the chip datasheet for the meaning of the various bits in +the register. +.El +.Sh HINTS CONFIGURATION +On a +.Xr device.hints 5 +based system, the following hints are required: +.Bl -tag -offset indent -width indent +.It Va hint.ltc430x..at +The upstream +.Xr iicbus 4 +the +.Nm +instance is attached to. +.It Va hint.ltc430x..addr +The slave address of the +.Nm +instance on the upstream bus. +.It Va hint.ltc430x..chip_type +The type of chip the driver is controlling. +Valid values are +.Dq ltc4305 +and +.Dq ltc4306 . +.El +.Pp +The following hints are optional: +.Bl -tag -offset indent -width indent +.It Va hint.ltc430x..ctlreg2 +A value to store into the chip's control register 2 during initialization. +Consult the chip datasheet for the meaning of the various bits in +the register. +This hint is optional; when missing, the driver does not update control +register 2. +.It Va hint.ltc430x..idle_disconnect +Whether to disconnect all downstream busses from the upstream bus when idle. +If set to zero, the most recently used downstream bus is left connected to +the upstream bus after IO completes. +Any non-zero value causes all downstream busses to be disconnected when idle. +This hint is optional; when missing, the driver behaves as if it were zero. +.El +.Pp +When configured via hints, the driver automatically adds an iicbus +instance for every downstream bus supported by the chip. +There is currently no way to indicate used versus unused downstream channels. +.Sh SEE ALSO +.Xr iicbus 4 , +.Xr iicmux 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 13.0 . diff --git a/static/freebsd/man4/mac.4 b/static/freebsd/man4/mac.4 new file mode 100644 index 00000000..bdb7de01 --- /dev/null +++ b/static/freebsd/man4/mac.4 @@ -0,0 +1,258 @@ +.\" Copyright (c) 2003 Networks Associates Technology, Inc. +.\" All rights reserved. +.\" +.\" This software was developed for the FreeBSD Project by Chris Costello +.\" at Safeport Network Services and Network Associates Labs, the +.\" Security Research Division of Network Associates, Inc. under +.\" DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the +.\" DARPA CHATS research program. +.\" +.\" 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 AUTHORS 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 AUTHORS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 16, 2026 +.Dt MAC 4 +.Os +.Sh NAME +.Nm mac +.Nd Mandatory Access Control +.Sh SYNOPSIS +.Cd "options MAC" +.Sh DESCRIPTION +.Ss Introduction +The Mandatory Access Control, or MAC, framework allows administrators to +finely control system security by providing for a loadable security policy +architecture. +It is important to note that due to its nature, MAC security policies may +only restrict access relative to one another and the base system policy; +they cannot override traditional +.Ux +security provisions such as file permissions and superuser checks. +.Pp +Currently, the following MAC policy modules are shipped with +.Fx : +.Bl -column ".Xr mac_seeotheruids 4" "ddb(4) interface restrictions" ".Em Labeling" "boot only" +.It Sy Name Ta Sy Description Ta Sy Labeling Ta Sy "Load time" +.It Xr mac_biba 4 Ta "Biba integrity policy" Ta yes Ta boot only +.It Xr mac_bsdextended 4 Ta "File system firewall" Ta no Ta any time +.It Xr mac_ddb 4 Ta "ddb(4) interface restrictions" Ta no Ta any time +.It Xr mac_do 4 Ta "Change command's uid/gid" Ta no Ta any time +.It Xr mac_ifoff 4 Ta "Interface silencing" Ta no Ta any time +.It Xr mac_ipacl 4 Ta "IP Address access control" Ta no Ta any time +.It Xr mac_lomac 4 Ta "Low-Watermark MAC policy" Ta yes Ta boot only +.It Xr mac_mls 4 Ta "Confidentiality policy" Ta yes Ta boot only +.It Xr mac_ntpd 4 Ta "Non-root NTP Daemon policy" Ta no Ta any time +.It Xr mac_partition 4 Ta "Process partition policy" Ta yes Ta any time +.It Xr mac_portacl 4 Ta "Port bind(2) access control" Ta no Ta any time +.It Xr mac_priority 4 Ta "Scheduling priority policy" Ta no Ta any time +.It Xr mac_seeotheruids 4 Ta "See-other-UIDs policy" Ta no Ta any time +.It Xr mac_test 4 Ta "MAC testing policy" Ta no Ta any time +.El +.Ss MAC Labels +Each system subject (processes, sockets, etc.) and each system object +(file system objects, jails, sockets, etc.) can carry with it a MAC label. +MAC labels contain data in an arbitrary format +taken into consideration in making access control decisions +for a given operation. +Most MAC labels on system subjects and objects +can be modified directly or indirectly by the system +administrator. +The format for a given policy's label may vary depending on the type +of object or subject being labeled. +More information on the format for MAC labels can be found in the +.Xr maclabel 7 +man page. +.Ss MAC Support for UFS2 File Systems +By default, file system enforcement of labeled MAC policies relies on +a single file system label +(see +.Sx "MAC Labels" ) +in order to make access control decisions for all the files in a particular +file system. +With some policies, this configuration may not allow administrators to take +full advantage of features. +In order to enable support for labeling files on an individual basis +for a particular file system, +the +.Dq multilabel +flag must be enabled on the file system. +To set the +.Dq multilabel +flag, drop to single-user mode and unmount the file system, +then execute the following command: +.Pp +.Dl "tunefs -l enable" Ar filesystem +.Pp +where +.Ar filesystem +is either the mount point +(in +.Xr fstab 5 ) +or the special file +(in +.Pa /dev ) +corresponding to the file system on which to enable multilabel support. +.Ss Policy Enforcement +Policy enforcement is divided into the following areas of the system: +.Bl -ohang +.It Sy "File System" +File system mounts, modifying directories, modifying files, etc. +.It Sy Jails +Creating, modifying, removing, and attaching to jails +.It Sy KLD +Loading, unloading, and retrieving statistics on loaded kernel modules +.It Sy Network +Network interfaces, +.Xr bpf 4 , +packet delivery and transmission, +interface configuration +.Xr ( ioctl 2 , +.Xr ifconfig 8 ) +.It Sy Pipes +Creation of and operation on +.Xr pipe 2 +objects +.It Sy Processes +Debugging +(e.g.\& +.Xr ktrace 2 ) , +process visibility +.Pq Xr ps 1 , +process execution +.Pq Xr execve 2 , +signalling +.Pq Xr kill 2 +.It Sy Sockets +Creation of and operation on +.Xr socket 2 +objects +.It Sy System +Kernel environment +.Pq Xr kenv 1 , +system accounting +.Pq Xr acct 2 , +.Xr reboot 2 , +.Xr settimeofday 2 , +.Xr swapon 2 , +.Xr sysctl 3 , +.Xr nfsd 8 Ns +-related operations +.It Sy VM +.Xr mmap 2 Ns +-ed files +.El +.Ss Setting MAC Labels +From the command line, each type of system object has its own means for setting +and modifying its MAC policy label. +.Bl -column "user (by login class)" "Xr setfmac 8 , Xr setfsmac 8" -offset indent +.It Sy "Subject/Object" Ta Sy "Utility" +.It "File system object" Ta Xr setfmac 8 , Xr setfsmac 8 +.It Jail Ta Xr jail 8 +.It "Network interface" Ta Xr ifconfig 8 +.It "TTY (by login class)" Ta Xr login.conf 5 +.It "User (by login class)" Ta Xr login.conf 5 +.El +.Pp +Additionally, the +.Xr su 1 +and +.Xr setpmac 8 +utilities can be used to run a command with a different process label than +the shell's current label. +.Ss Programming With MAC +MAC security enforcement itself is transparent to application +programs, with the exception that some programs may need to be aware of +additional +.Xr errno 2 +returns from various system calls. +.Pp +The interface for retrieving, handling, and setting policy labels +is documented in the +.Xr mac 3 +man page. +.\" *** XXX *** +.\" Support for this feature is poor and should not be encouraged. +.\" +.\" .It Va security.mac.mmap_revocation +.\" Revoke +.\" .Xr mmap 2 +.\" access to files on subject relabel. +.\" .It Va security.mac.mmap_revocation_via_cow +.\" Revoke +.\" .Xr mmap 2 +.\" access to files via copy-on-write semantics; +.\" mapped regions will still appear writable, but will no longer +.\" effect a change on the underlying vnode. +.\" (Default: 0). +.Sh SEE ALSO +.Xr mac 3 , +.Xr mac_biba 4 , +.Xr mac_bsdextended 4 , +.Xr mac_ddb 4 , +.Xr mac_do 4 , +.Xr mac_ifoff 4 , +.Xr mac_ipacl 4 , +.Xr mac_lomac 4 , +.Xr mac_mls 4 , +.Xr mac_none 4 , +.Xr mac_ntpd 4 , +.Xr mac_partition 4 , +.Xr mac_portacl 4 , +.Xr mac_priority 4 , +.Xr mac_seeotheruids 4 , +.Xr mac_stub 4 , +.Xr mac_test 4 , +.Xr login.conf 5 , +.Xr maclabel 7 , +.Xr jail 8 , +.Xr getfmac 8 , +.Xr getpmac 8 , +.Xr setfmac 8 , +.Xr setpmac 8 , +.Xr mac 9 +.Rs +.%B "The FreeBSD Handbook" +.%T "Mandatory Access Control" +.%U https://docs.FreeBSD.org/en/books/handbook/mac/ +.Re +.Sh HISTORY +The +.Nm +implementation first appeared in +.Fx 5.0 +and was developed by the +.Tn TrustedBSD +Project. +.Sh AUTHORS +This software was contributed to the +.Fx +Project by Network Associates Labs, +the Security Research Division of Network Associates +Inc. +under DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Sh BUGS +While the MAC Framework design is intended to support the containment of +the root user, not all attack channels are currently protected by entry +point checks. +As such, MAC Framework policies should not be relied on, in isolation, +to protect against a malicious privileged user. diff --git a/static/freebsd/man4/mac_biba.4 b/static/freebsd/man4/mac_biba.4 new file mode 100644 index 00000000..acab6b3e --- /dev/null +++ b/static/freebsd/man4/mac_biba.4 @@ -0,0 +1,234 @@ +.\" Copyright (c) 2002-2004 Networks Associates Technology, Inc. +.\" All rights reserved. +.\" +.\" This software was developed for the FreeBSD Project by Chris Costello +.\" at Safeport Network Services and Network Associates Laboratories, the +.\" Security Research Division of Network Associates, Inc. under +.\" DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the +.\" DARPA CHATS research program. +.\" +.\" 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 AUTHORS 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 AUTHORS 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 November 18, 2002 +.Dt MAC_BIBA 4 +.Os +.Sh NAME +.Nm mac_biba +.Nd "Biba data integrity policy" +.Sh SYNOPSIS +To compile Biba into your kernel, place the following lines in your kernel +configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Cd "options MAC_BIBA" +.Ed +.Pp +Alternately, to load the Biba module at boot time, place the following line +in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Ed +.Pp +and in +.Xr loader.conf 5 : +.Bd -literal -offset indent +mac_biba_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +policy module implements the Biba integrity model, +which protects the integrity of system objects and subjects by means of +a strict information flow policy. +In Biba, all system subjects and objects are assigned integrity labels, made +up of hierarchal grades, and non-hierarchal components. +Together, these label elements permit all labels to be placed in a partial +order, with information flow protections based on a dominance operator +describing the order. +The hierarchal grade field is expressed as a value between 0 and 65535, +with higher values reflecting higher integrity. +The non-hierarchal compartment field is expressed as a set of up to 256 +components, numbered from 0 to 255. +A complete label consists of both hierarchal and non-hierarchal elements. +.Pp +Three special label values exist: +.Bl -column -offset indent ".Li biba/equal" "lower than all other labels" +.It Sy Label Ta Sy Comparison +.It Li biba/low Ta "lower than all other labels" +.It Li biba/equal Ta "equal to all other labels" +.It Li biba/high Ta "higher than all other labels" +.El +.Pp +The +.Dq Li biba/high +label is assigned to system objects which affect the integrity of the system +as a whole. +The +.Dq Li biba/equal +label +may be used to indicate that a particular subject or object is exempt from +the Biba protections. +These special label values are not specified as containing any compartments, +although in a label comparison, +.Dq Li biba/high +appears to contain all compartments, +.Dq Li biba/equal +the same compartments as the other label to which it is being compared, +and +.Dq Li biba/low +none. +.Pp +In general, Biba access control takes the following model: +.Bl -bullet +.It +A subject at the same integrity level as an object may both read from +and write to the object as though Biba protections were not in place. +.It +A subject at a higher integrity level than an object may write to the object, +but not read the object. +.It +A subject at a lower integrity level than an object may read the object, +but not write to the object. +.It +If the subject and object labels may not be compared in the partial order, +all access is restricted. +.El +.Pp +These rules prevent subjects of lower integrity from influencing the +behavior of higher integrity subjects by preventing the flow of information, +and hence control, from allowing low integrity subjects to modify either +a high integrity object or high integrity subjects acting on those objects. +Biba integrity policies may be appropriate in a number of environments, +both from the perspective of preventing corruption of the operating system, +and corruption of user data if marked as higher integrity than the attacker. +In traditional trusted operating systems, the Biba integrity model is used +to protect the Trusted Code Base (TCB). +.Pp +The Biba integrity model is similar to +.Xr mac_lomac 4 , +with the exception that LOMAC permits access by a higher integrity subject +to a lower integrity object, but downgrades the integrity level of the subject +to prevent integrity rules from being violated. +Biba is a fixed label policy in that all subject and object label changes are +explicit, whereas LOMAC is a floating label policy. +.Pp +The Biba integrity model is also similar to +.Xr mac_mls 4 , +with the exception that the dominance operator and access rules are reversed, +preventing the downward flow of information rather than the upward flow of +information. +Multi-Level Security (MLS) protects the confidentiality, rather than the +integrity, of subjects and objects. +.Ss Label Format +Almost all system objects are tagged with an effective, active label element, +reflecting the integrity of the object, or integrity of the data contained +in the object. +In general, objects labels are represented in the following form: +.Pp +.Sm off +.D1 Li biba / Ar grade : compartments +.Sm on +.Pp +For example: +.Bd -literal -offset indent +biba/10:2+3+6 +biba/low +.Ed +.Pp +Subject labels consist of three label elements: an effective (active) label, +as well as a range of available labels. +This range is represented using two ordered Biba label elements, and when set +on a process, permits the process to change its active label to any label of +greater or equal integrity to the low end of the range, and lesser or equal +integrity to the high end of the range. +In general, subject labels are represented in the following form: +.Pp +.Sm off +.D1 Li biba / Ar effectivegrade : effectivecompartments ( lograde : locompartments - +.D1 Ar higrade : hicompartments ) +.Sm on +.Pp +For example: +.Bd -literal -offset indent +biba/10:2+3+6(5:2+3-20:2+3+4+5+6) +biba/high(low-high) +.Ed +.Pp +Valid ranged labels must meet the following requirement regarding their +elements: +.Pp +.D1 Ar rangehigh No \[>=] Ar effective No \[>=] Ar rangelow +.Pp +One class of objects with ranges currently exists, the network interface. +In the case of the network interface, the effective label element references the +default label for packets received over the interface, and the range +represents the range of acceptable labels of packets to be transmitted over +the interface. +.Ss Runtime Configuration +The following +.Xr sysctl 8 +MIBs are available for fine-tuning the enforcement of this MAC policy. +.Bl -tag -width ".Va security.mac.biba.ptys_equal" +.It Va security.mac.biba.enabled +Enables enforcement of the Biba integrity policy. +(Default: 1). +.It Va security.mac.biba.ptys_equal +Label +.Xr pty 4 Ns s +as +.Dq Li biba/equal +upon creation. +(Default: 0). +.It Va security.mac.biba.revocation_enabled +Revoke access to objects if the label is changed to dominate the subject. +(Default: 0). +.El +.Sh SEE ALSO +.Xr mac 4 , +.Xr mac_bsdextended 4 , +.Xr mac_ifoff 4 , +.Xr mac_lomac 4 , +.Xr mac_mls 4 , +.Xr mac_none 4 , +.Xr mac_partition 4 , +.Xr mac_portacl 4 , +.Xr mac_seeotheruids 4 , +.Xr mac_test 4 , +.Xr maclabel 7 , +.Xr mac 9 +.Sh HISTORY +The +.Nm +policy module first appeared in +.Fx 5.0 +and was developed by the +.Tn TrustedBSD +Project. +.Sh AUTHORS +This software was contributed to the +.Fx +Project by Network Associates Labs, +the Security Research Division of Network Associates +Inc. +under DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. diff --git a/static/freebsd/man4/mac_bsdextended.4 b/static/freebsd/man4/mac_bsdextended.4 new file mode 100644 index 00000000..2131ca85 --- /dev/null +++ b/static/freebsd/man4/mac_bsdextended.4 @@ -0,0 +1,147 @@ +.\" Copyright (c) 2002 Networks Associates Technology, Inc. +.\" All rights reserved. +.\" +.\" This software was developed for the FreeBSD Project by Chris Costello +.\" at Safeport Network Services and Network Associates Laboratories, the +.\" Security Research Division of Network Associates, Inc. under +.\" DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the +.\" DARPA CHATS research program. +.\" +.\" 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 AUTHORS 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 AUTHORS 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 October 11, 2024 +.Dt MAC_BSDEXTENDED 4 +.Os +.Sh NAME +.Nm mac_bsdextended +.Nd "file system firewall policy" +.Sh SYNOPSIS +To compile the file system firewall policy into your kernel, +place the following lines in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Cd "options MAC_BSDEXTENDED" +.Ed +.Pp +Alternately, to load the file system firewall policy module at boot time, +place the following line in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Ed +.Pp +and in +.Xr loader.conf 5 : +.Bd -literal -offset indent +mac_bsdextended_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +security policy module provides an interface for the system administrator +to impose mandatory rules regarding users and some system objects. +Rules are uploaded to the module +(typically using +.Xr ugidfw 8 , +or some other tool utilizing +.Xr libugidfw 3 ) +where they are stored internally +and used to determine whether to allow or deny specific accesses +(see +.Xr ugidfw 8 ) . +.Sh IMPLEMENTATION NOTES +While the traditional +.Xr mac 9 +entry points are implemented, +policy labels are not used; +instead, access control decisions are made by iterating through the internal +list of rules until a rule +which denies the particular access +is found, +or the end of the list is reached. +The +.Nm +policy works similar to +.Xr ipfw 8 +or by using a +.Em first match semantic . +This means that not all rules are applied, +only the first matched rule; thus if +Rule A allows access and Rule B blocks +access, Rule B will never be applied. +.Sh SYSCTL VARIABLES +The following sysctls may be used to tweak the behavior of +.Nm : +.Bl -tag -width indent +.It Va security.mac.bsdextended.enabled +Set to zero or one to toggle the policy off or on. +.It Va security.mac.bsdextended.rule_count +List the number of defined rules, the maximum rule count is +current set at 256. +.It Va security.mac.bsdextended.rule_slots +List the number of rule slots currently being used. +.It Va security.mac.bsdextended.firstmatch_enabled +Toggle between the old all rules match functionality +and the new first rule matches functionality. +This is enabled by default. +.It Va security.mac.bsdextended.logging +Log all access violations via the +.Dv AUTHPRIV +.Xr syslog 3 +facility. +.It Va security.mac.bsdextended.rules +Currently does nothing interesting. +.El +.Sh SEE ALSO +.Xr libugidfw 3 , +.Xr syslog 3 , +.Xr mac 4 , +.Xr mac_biba 4 , +.Xr mac_ddb 4 , +.Xr mac_ifoff 4 , +.Xr mac_lomac 4 , +.Xr mac_mls 4 , +.Xr mac_none 4 , +.Xr mac_partition 4 , +.Xr mac_portacl 4 , +.Xr mac_seeotheruids 4 , +.Xr mac_test 4 , +.Xr ipfw 8 , +.Xr ugidfw 8 , +.Xr mac 9 +.Sh HISTORY +The +.Nm +policy module first appeared in +.Fx 5.0 +and was developed by the +.Tn TrustedBSD +Project. +.Pp +The "match first case" and logging capabilities were later added by +.An Tom Rhodes Aq Mt trhodes@FreeBSD.org . +.Sh AUTHORS +This software was contributed to the +.Fx +Project by NAI Labs, the Security Research Division of Network Associates +Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. diff --git a/static/freebsd/man4/mac_ddb.4 b/static/freebsd/man4/mac_ddb.4 new file mode 100644 index 00000000..5127fa78 --- /dev/null +++ b/static/freebsd/man4/mac_ddb.4 @@ -0,0 +1,108 @@ +.\" Copyright (c) 2022 Klara Systems +.\" +.\" This software was developed by Mitchell Horne +.\" under sponsorship from Juniper Networks and Klara Systems. +.\" +.\" 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 AUTHORS 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 AUTHORS 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 June 29, 2022 +.Dt MAC_DDB 4 +.Os +.Sh NAME +.Nm mac_ddb +.Nd "Restricted kernel debugger interface policy" +.Sh SYNOPSIS +To compile the ddb policy +into your kernel, place the following lines in your kernel +configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Cd "options MAC_DDB" +.Ed +.Pp +Alternately, to load the ddb module at boot time, place the following line +in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Ed +.Pp +and in +.Xr loader.conf 5 : +.Bd -literal -offset indent +mac_ddb_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +policy module implements a MAC policy which restricts the set of commands that +can be used at the +.Xr ddb 4 +command prompt. +The subset of permitted commands is limited to those which do not read or write +to arbitrary memory locations. +This is done to deter the possible extraction of system secrets while still +allowing enough debugger functionality to diagnose a kernel panic. +For example, the +.Ic trace +or +.Ic show registers +commands are allowed by this policy, but +.Ic show Cm buffer Ar addr +is not. +.Pp +All debugger commands that are declared with the +.Va DB_CMD_MEMSAFE +flag are allowed by +.Nm . +The policy provides validation functions to conditionally allow some additional +commands, based on the user provided arguments. +.Pp +When loaded, the +.Nm +policy also ensures that only the +.Xr ddb 4 +debugger backend may be executed; +.Xr gdb 4 +may not. +.Ss Label Format +No labels are defined for +.Nm . +.Sh SEE ALSO +.Xr ddb 4 , +.Xr mac 4 , +.Xr mac_biba 4 , +.Xr mac_bsdextended 4 , +.Xr mac_ifoff 4 , +.Xr mac_lomac 4 , +.Xr mac_mls 4 , +.Xr mac_none 4 , +.Xr mac_partition 4 , +.Xr mac_portacl 4 , +.Xr mac_seeotheruids 4 , +.Xr mac_test 4 , +.Xr mac 9 +.Sh BUGS +While the MAC Framework design is intended to support the containment of +the root user, not all attack channels are currently protected by entry +point checks. +As such, MAC Framework policies should not be relied on, in isolation, +to protect against a malicious privileged user. diff --git a/static/freebsd/man4/mac_do.4 b/static/freebsd/man4/mac_do.4 new file mode 100644 index 00000000..d0293207 --- /dev/null +++ b/static/freebsd/man4/mac_do.4 @@ -0,0 +1,454 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2024 Baptiste Daroussin +.\" Copyright (c) 2024 The FreeBSD Foundation +.\" +.\" Portions of this documentation were written by Olivier Certner +.\" at Kumacom SARL under sponsorship from the FreeBSD +.\" Foundation. +.\" +.Dd June 11, 2025 +.Dt MAC_DO 4 +.Os +.Sh NAME +.Nm mac_do +.Nd "policy allowing unprivileged users to change process credentials" +.Sh SYNOPSIS +To compile the +.Sy mac_do +policy into your kernel, place the following lines in your kernel configuration +file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Cd "options MAC_DO" +.Ed +.Pp +Alternately, to load this policy module at boot time, place the following line +in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Ed +.Pp +and in +.Xr loader.conf 5 : +.Bd -literal -offset indent +mac_do_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +policy module allows unprivileged users to change process credentials according +to rules configured by the administrator. +It supports per-jail configuration. +.Pp +Currently, the +.Nm +policy module only produces effects to processes spawned from the +.Pa /usr/bin/mdo +executable, please see +.Xr mdo 1 +for more details on this program. +.Sh CREDENTIALS RULES +Rules specify which transitions of process credentials +.Nm +will allow, based on current process credentials and the desired final ones. +They are passed by an administrator in the form of a string having the specific +syntax described below in a top-bottom manner. +They have been designed to be able to finely describe the desired target +credentials in a safe and compact way. +.Ss Top-Level List of Rules +At the top, rules are a possibly empty list of individual rules separated by +a semi-colon +.Pq Ql ";" : +.Dl Ao rules Ac \ ⟶\ Oo Ao rule Ac Oo So ";" Sc Ao rule Ac Oc Ns * Oc +They form a disjunction, i.e., +.Nm +authorizes a credentials transition as soon as at least one rule in the list +matches. +.Pp +One rule is composed of a +.Li Aq from +part +.Pq also called Dq match +and a +.Li Aq to +part +.Pq also called Dq target , +in this order, separated by a greater-than sign +.Pq Ql > : +.Dl Ao rule Ac \ ⟶\ Ao from Ac So > Sc Ao to Ac +.Ss Rule's Ao from Ac Part +The first part of a rule, +.Li Aq from , +is matched against the credentials of the process requesting some credentials +transition. +It has the form: +.Dl Ao from Ac \ ⟶\ Ao type Ac So = Sc Ao id Ac +.Pp +.Li Aq type +must be: +.Dl Ao type Ac \ ⟶\ Op So uid Sc | So gid Sc +i.e., one of the literal strings +.Ql uid +or +.Ql gid . +.Li Aq id +must be the numerical ID of a user or group and is matched against the current +process real ID of the corresponding type, and on type +.Ql gid +additionally against the supplementary groups. +.Ss Rule's Ao to Ac Part +The second part of a rule, +.Li Aq to , +is a comma-separated +.Pq Ql "," +non-empty list of target clauses: +.Dl Ao to Ac \ ⟶\ Ao target_clause Ac Oo So "," Sc Ao target_clause Ac Oc Ns * +Target clauses of a given rule also form a disjunction, i.e., the IDs they +specify are alternatives for the target credentials, except in some cases +described below. +.Pp +The next subsections describe the syntax of target clauses, the defaults that +apply and the principle of non-redundancy and non-contradiction in each rule's +.Li Aq to +part. +.Ss Target Clauses +A target clause in a rule's +.Li Aq to +part must be of one of the following forms: +.Dl Ao target_clause Ac \ ⟶\ So any Sc +.Dl Ao target_clause Ac \ ⟶\ Ao flags Ac Ao type Ac So = Sc Ao id Ac +The first form is a compact way to specify that any target credentials are +allowed. +The second form is similar to that of +.Li Aq from +clauses, with the following extensions: +.Bl -bullet -compact +.It +.Li Aq id +may also be a literal +.Ql * +or +.Ql any +or +.Ql "." . +.Ql * +and +.Ql any +both designate any ID for the specified +.Li Aq type , +and are treated identically. +.Ql "." +designates the process' current IDs for the specified +.Li Aq type , +as explained below. +.It +.Li Aq flags +may contain at most one of the +.Ql + , +.Ql - +and +.Ql "!" +characters, and may be non-empty only when +.Li Aq type +is +.Ql gid . +Additionally, if +.Li Aq id +is +.Ql * +or +.Ql any , +only the +.Ql + +flag may appear. +.El +.Pp +For target clauses of +.Ql gid +type, an absence of flag indicates that the specified group ID is allowed as the +real, effective and/or saved group IDs +.Pq the Do primary Dc groups . +Conversely, the presence of any allowed flag indicates that the specification +concerns supplementary groups. +Each flag has a specific meaning: +.Bl -bullet -compact +.It +.Ql + +indicates that the group ID is allowed as a supplementary group. +.It +.Ql "!" +indicates that the group ID is mandatory, i.e., it must be listed in the +supplementary groups. +.It +.Ql - +indicates that the group ID must not be listed in the supplementary groups. +.El +A specification with +.Ql - +is only useful in conjunction with a +.Ql + Ns +-tagged specification where only one of them has +.Ql "." +as its +.Li Aq id . +Target clauses having the +.Ql "!" +or +.Ql - +flag are +.Dq forcing +clauses, and as such do not take part in the disjunction of the other +target clauses but rather unconditionally apply in their rule. +.Pp +.Ql "." +is a placeholder for IDs that the calling process already has on privilege +check. +For type +.Ql uid , +it designates any of the process' real, effective or +saved user IDs. +For type +.Ql gid , +its effect depends on whether flags are present. +If none is present, it designates any of the process' real, effective or saved +group IDs. +If one is present, it designates any of the process' supplementary groups. +.Ss Defaults for the Ao to Ac Part +If the +.Li Aq to +part does not list a target clause with type +.Ql uid , +any of the current user IDs of the calling process is accepted. +In other words, in this case, +.Nm +behaves as if a target clause of: +.Dl uid=. +had been listed. +.Pp +Similarly, if the +.Li Aq to +part does not list a target clause with type +.Ql gid , +all the groups of the calling process are assumed to be required. +More precisely, each of the desired real, effective and saved group IDs must be +one of the current real, effective or saved group ID, and all supplementary +groups must be the same as those that are current. +It is as if the +.Li Aq to +part had contained the following two clauses: +.Dl gid=.,!gid=. +.Ss Non-Redundancy and Non-Contradiction in a Ao to Ac Part +No two target clauses of a single rule may express the exact same logical intent +nor contradictory ones. +.Pp +In practice, no two clauses may display the same ID except for group IDs but +only if, each time the same ID appears, it does so with a different flag, or no +flags only once. +Additionally, the specified flags in multiple occurrences must not be +contradictory. +For example, the same group ID appearing with both +.Ql + +and +.Ql - +will cause rejection of the rule. +.Ss Parsing Specifics +Any amount of whitespace is allowed around tokens of the above grammar, except +that there may be no spaces between +.Li Aq flags +and +.Li Aq id +in target clauses. +.Pp +For convenience, numerical IDs may be specified as negative integers, which are +then converted to unsigned ones as specified in the C standard for the +.Vt uid_t +and +.Vt gid_t +types, which are both 64-bit unsigned integers. +.Sh RUNTIME CONFIGURATION +The following +.Xr sysctl 8 +knobs are available: +.Bl -tag -width indent +.It Va security.mac.do.enabled +Enable the +.Nm +policy. +(Default: 1). +.It Va security.mac.do.rules +The list of credential rules, whose syntax is described in the +.Sx CREDENTIALS RULES +section above. +This list is specific to each jail. +Please see the +.Sx JAIL SUPPORT +section below for more details on the interaction of +.Nm +with jails. +.It Va security.mac.do.print_parse_error +Logs a message on trying to set incorrect rules via the +.Va security.mac.do.rules +.Xr sysctl 8 +knob. +.El +.Sh JAIL SUPPORT +.Nm +supports per-jail configuration of rules. +.Pp +By default, at creation, a new jail has no credentials rules, effectively +disabling +.Nm +for its processes. +.Pp +The following jail parameters are defined: +.Bl -tag -width indent +.It Va mac.do +Possible values are: +.Bl -tag -width "'disable'" -compact +.It Ql enable +.Nm +will enforce specific credential rules in the jail. +The +.Va mac.do.rules +jail parameter must also be set in this case. +.It Ql disable +Disables +.Nm +in the jail. +Strictly equivalent to jail creation's default behavior and to setting the rules +to an empty string. +.It Ql inherit +The jail's credentials rules are inherited from the jail's parent +.Pq which may themselves have been inherited . +Modified rules propagate to all children jails configured for inheritance. +.El +.It Va mac.do.rules +The credentials rules for the jail. +It is always equal to the value that can be retrieved by the +.Xr sysctl 8 +knob +.Va security.mac.do.rules +described in section +.Sx RUNTIME CONFIGURATION . +If set, and the jail parameter +.Va mac.do +is not so explicitly, the value of the latter will default to +.Ql disable +if empty, else to +.Ql enable . +.El +.Pp +Each jail must have +.Xr mdo 1 +installed at path +.Pa /usr/bin/mdo , +as this path is currently not configurable. +.Sh EXAMPLES +Here are several examples of single rules matching processes having a real user +ID of 10001: +.Bl -tag -width indent +.It Li uid=10001>uid=10002 +Allows the process to switch all of its real, effective or saved user ID to +10002, but keeping the groups it is already in, and with the same +primary/supplementary groups split. +.It Li uid=10001>uid=10002,uid=10003 +Same as the first example, but also allows to switch to UID 10003 instead of +10002, or possibly having both in different user IDs. +.It Li uid=10001>uid=10002,gid=10002 +Same as the first example, but the new primary groups must be set to 10002 and +no supplementary groups should be set. +.It Li uid=10001>uid=10002,gid=10002,+gid=.\& +Same as the previous example, but in addition allowing to retain any current +supplementary groups. +.It Li uid=10001>uid=10002,gid=10002,!gid=.\& +Same as the previous example, but with the additional constraint that all +current supplementary groups must be kept. +.It Li uid=10001>uid=10002,gid=10002,+gid=.,-gid=10001 +Same as +.Ql uid=10001>uid=10002,gid=10002,+gid=.\& +above, but 10001 cannot be retained as a supplementary group. +.It Li uid=10001>uid=10002,gid=10002,+gid=.,!gid=10003 +Same as +.Ql uid=10001>uid=10002,gid=10002,+gid=.\& +above, with the additional constraint that 10003 must appear in the +supplementary groups. +.It Li uid=10001>uid=10002,gid=*,+gid=* +Same as the first example, but lifting any constraints on groups, allowing the +process to become part of any groups it sees fit. +.El +.Pp +Here are several examples of single rules matching processes having 10001 as +their real group IDs or in their supplementary groups: +.Bl -tag -width indent +.It Li gid=10001>uid=0 +Makes 10001 a more powerful +.Ql wheel +group, allowing its members to switch to root without password. +.It Li gid=10001>gid=10002 +Allows the process to enter GID 10002 as a primary group, but only if +giving up all its supplementary groups. +.It Li gid=10001>gid=10002,+gid=.\& +Same as the previous example, but allows to retain any current supplementary +groups. +.It Li gid=10001>gid=10002,!gid=.\& +Same as the previous example, but with the additional constraint that all +current supplementary groups must be kept. +.El +.Sh SEE ALSO +.Xr mdo 1 , +.Xr setcred 2 , +.Xr mac 4 , +.Xr jail 8 , +.Xr sysctl 8 +.Sh AUTHORS +.An Olivier Certner Aq Mt olce@FreeBSD.org +.An Baptiste Daroussin Aq Mt bapt@FreeBSD.org +.Sh BUGS +Currently, +.Nm +considers only credentials transitions requested through the +.Xr setcred 2 +system call. +This system call was in large part created so that +.Nm +can see whole credentials transitions to decide whether to authorize them, which +the traditional UNIX's piecewise approach of successively changing different +parts of them cannot allow. +.Pp +However, calls to traditional or standard credentials-changing functions can be +considered as full transitions on their own, however limited, and as such should +be equally monitored by +.Nm . +Future work will lift this restriction. +.Sh SECURITY CONSIDERATIONS +The threat model for +.Nm +is to consider userland programs as generally untrustable to decide upon which +credentials changes are acceptable. +It is in contrast with the traditional UNIX way to change credentials, in which +specialized programs are installed with the setuid bit, giving them full +administrator privileges so that they are effectively able to establish new +ones. +Vulnerabilities in such credentials-changing programs can have catastrophic +consequences on the integrity of the system. +.Pp +Consequently, +.Nm +does not rely on companion userland programs to decide whether some credentials +transition is acceptable. +Instead, it maintains its own configuration independently from the userland +password and group databases. +Establishing this configuration currently itself relies on userland programs +issuing calls to +.Xr sysctl 3 +or +.Xr jail 2 . +It should thus be established near system boot or jail start, before any +possible attacks could happen on the system, and further measures should be +taken to ensure that potential corruptions does not affect the configuration in +subsequent restarts, such as re-establishing pristine state or ensuring that the +boot procedure up to the configuration of +.Nm +can be trusted. diff --git a/static/freebsd/man4/mac_ifoff.4 b/static/freebsd/man4/mac_ifoff.4 new file mode 100644 index 00000000..05332c8c --- /dev/null +++ b/static/freebsd/man4/mac_ifoff.4 @@ -0,0 +1,123 @@ +.\" Copyright (c) 2002 Networks Associates Technology, Inc. +.\" All rights reserved. +.\" +.\" This software was developed for the FreeBSD Project by Chris Costello +.\" at Safeport Network Services and Network Associates Laboratories, the +.\" Security Research Division of Network Associates, Inc. under +.\" DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the +.\" DARPA CHATS research program. +.\" +.\" 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 AUTHORS 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 AUTHORS 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 25, 2015 +.Dt MAC_IFOFF 4 +.Os +.Sh NAME +.Nm mac_ifoff +.Nd "interface silencing policy" +.Sh SYNOPSIS +To compile the interface silencing policy into your kernel, +place the following lines in your kernel +configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Cd "options MAC_IFOFF" +.Ed +.Pp +Alternately, to load the interface silencing policy module at boot time, +place the following line in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Ed +.Pp +and in +.Xr loader.conf 5 : +.Bd -literal -offset indent +mac_ifoff_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +interface silencing module allows administrators to enable and disable +incoming and outgoing data flow on system network interfaces +via the +.Xr sysctl 8 +interface. +.Pp +To disable network traffic over the loopback +.Pq Xr lo 4 +interface, set the +.Xr sysctl 8 +OID +.Va security.mac.ifoff.lo_enabled +to 0 (default 1). +.Pp +To enable network traffic over other interfaces, +set the +.Xr sysctl 8 +OID +.Va security.mac.ifoff.other_enabled +to 1 (default 0). +.Pp +To allow BPF traffic to be received, +even while other traffic is disabled, +set the +.Xr sysctl 8 +OID +.Va security.mac.ifoff.bpfrecv_enabled +to 1 (default 0). +.Ss Label Format +No labels are defined. +.Sh SEE ALSO +.Xr mac 4 , +.Xr mac_bsdextended 4 , +.Xr mac_lomac 4 , +.Xr mac_mls 4 , +.Xr mac_none 4 , +.Xr mac_partition 4 , +.Xr mac_portacl 4 , +.Xr mac_seeotheruids 4 , +.Xr mac_test 4 , +.Xr mac 9 +.Sh HISTORY +The +.Nm +policy module first appeared in +.Fx 5.0 +and was developed by the +.Tn TrustedBSD +Project. +.Sh AUTHORS +This software was contributed to the +.Fx +Project by Network Associates Labs, +the Security Research Division of Network Associates +Inc. +under DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Sh BUGS +While the MAC Framework design is intended to support the containment of +the root user, not all attack channels are currently protected by entry +point checks. +As such, MAC Framework policies should not be relied on, in isolation, +to protect against a malicious privileged user. diff --git a/static/freebsd/man4/mac_ipacl.4 b/static/freebsd/man4/mac_ipacl.4 new file mode 100644 index 00000000..5ff5ad3f --- /dev/null +++ b/static/freebsd/man4/mac_ipacl.4 @@ -0,0 +1,164 @@ +.\" Copyright (c) 2019, 2023 Shivank Garg +.\" +.\" This code was developed as a Google Summer of Code 2019 project +.\" under the guidance of Bjoern A. Zeeb. +.\" +.\" 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 AUTHORS 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 AUTHORS 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 25, 2023 +.Dt MAC_IPACL 4 +.Os +.Sh NAME +.Nm mac_ipacl +.Nd "IP Address access control policy" +.Sh SYNOPSIS +Add the following lines in your kernel configuration file to compile the +IP address access control policy into your kernel: +.Bd -ragged -offset indent +.Cd "options MAC" +.Cd "options MAC_IPACL" +.Ed +.Pp +To load the mac_ipacl policy module at boot time, add the +following line in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Ed +.Pp +and in +.Xr loader.conf 5 add: +.Pp +.Dl "mac_ipacl_load=""YES""" +.Sh DESCRIPTION +The +.Nm +policy allows the root of the host to use the +.Xr sysctl 8 +interface to limit the +.Xr VNET 9 +jail's ability to set IPv4 and IPv6 addresses. +So, the host can +define rules for jails and their interfaces about IP addresses +with +.Xr sysctl 8 +MIBs. +.Pp +Its default behavior is to deny all IP addresses for the jail if +.Nm +policy is enforced and allow/deny IP (or subnets) according to the +.Va security.mac.ipacl.rules +string specified with +.Xr sysctl 8 +.Ss Runtime Configuration +The following +.Xr sysctl 8 +MIBs are used to control enforcement and behavior of this MAC Policy. +.Bl -tag -width indent +.It Va security.mac.ipacl.ipv4 +Enforce +.Nm +for IPv4 addresses. +(Default: 1). +.It Va security.mac.ipacl.ipv6 +Enforce +.Nm +for IPv6 addresses. +(Default: 1). +.It Va security.mac.ipacl.rules +The IP address access control list is specified in the following format: +.Pp +.Sm off +.D1 jid , allow , interface , addr_family , IP_addr / prefix Op @ jid , ... +.Sm on +.Bl -tag -width "interface" +.It jid +Describe the jail id of the jail for which the rule is written. +.It allow +1 for allow and 0 for deny. +Decides action performed for the rule. +.It interface +Name of the interface the rule is enforced for. +If the interface is left empty then it is a wildcard to enforce the +rule for all interfaces. +.It addr_family +Address family of the IP_addr. +The input to be given as AF_INET or AF_INET6 +string only. +.It IP_addr +IP address (or subnet) to be allowed/denied. +Action depends on the prefix length. +.It prefix +Prefix length of the subnet to be enforced by the policy. +-1 implies the policy is enforced for the individual IP address. +For a non-negative value, a range of IP addresses (present in subnet) +which is calculated as subnet = IP_addr & mask. +.El +.El +.Sh EXAMPLES +Behavior of the +.Nm +policy module for different inputs of sysctl variable: +.Bl -tag -width "1." +.It 1. +Assign ipv4=1, ipv6=0 and rules="1,1,,AF_INET,169.254.123.123/-1" +.Pp +It allow only 169.254.123.123 IPv4 address for all interfaces (wildcard) of jail 1. +It allows all IPv6 addresses since the policy is not enforced for IPv6. +.It 2. +Assign ipv4=1, ipv6=1 and rules="1,1,epair0b,AF_INET6,fe80::/32@1,0,epair0b,AF_INET6,fe80::abcd/-1" +.Pp +It denies all IPv4 addresses as the policy is enforced but no rules are specified +about it. +It allows all IPv6 addresses in subnet fe80::/32 except +fe80::abcd for interface epair0b only. +.It 3. +Assign ipv4=1, ipv6=1, rules="2,1,,AF_INET6,fc00::/7@2,0,,AF_INET6,fc00::1111:2200/120@2,1,,AF_INET6,fc00::1111:2299/-1@1,1,,AF_INET,198.51.100.0/24" +.Pp +It allows IPv4 in subnet 198.51.100.0/24 for jail 2 and +all interfaces. +It allows IPv6 addresses in subnet fc00::/7 but +denies subnet fc00::1111:2200/120, and allows individual IP +fc00::1111:2299 from the denied subnet for all interfaces in jail 2. +.El +Please refer to mac/ipacl tests-framework for wide variety of examples on using +the ipacl module. +.Sh LIMITATIONS/PRECAUTIONS +In the case where multiple rules are applicable to an IP address or +a set of IP addresses, the rule that is defined later in the list +determines the outcome, disregarding any previous rule for that IP +address. +.Sh FUTURE WORKS +Rules are given with sysctl interface which gets very complex to give them +all in command line. +It has to be simplified with a better way to input those rules. +.Sh SEE ALSO +.Xr mac 4 , +.Xr mac 9 +.Sh AUTHORS +The +.Nm +policy module was developed as a Google Summer of Code Project in 2019 +by +.An -nosplit +.An "Shivank Garg" Aq Mt shivank@FreeBSD.org +under the guidance of +.An "Bjoern A. Zeeb" Aq Mt bz@FreeBSD.org . diff --git a/static/freebsd/man4/mac_lomac.4 b/static/freebsd/man4/mac_lomac.4 new file mode 100644 index 00000000..702646f9 --- /dev/null +++ b/static/freebsd/man4/mac_lomac.4 @@ -0,0 +1,220 @@ +.\" Copyright (c) 2002 Networks Associates Technology, Inc. +.\" All rights reserved. +.\" +.\" This software was developed for the FreeBSD Project by Chris Costello +.\" at Safeport Network Services and Network Associates Laboratories, the +.\" Security Research Division of Network Associates, Inc. under +.\" DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the +.\" DARPA CHATS research program. +.\" +.\" 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 AUTHORS 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 AUTHORS 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 February 25, 2012 +.Dt MAC_LOMAC 4 +.Os +.Sh NAME +.Nm mac_lomac +.Nd "Low-watermark Mandatory Access Control data integrity policy" +.Sh SYNOPSIS +To compile LOMAC into your kernel, place the following lines in your kernel +configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Cd "options MAC_LOMAC" +.Ed +.Pp +Alternately, to load the LOMAC module at boot time, place the following line +in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Ed +.Pp +and in +.Xr loader.conf 5 : +.Bd -literal -offset indent +mac_lomac_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +policy module implements the LOMAC integrity model, +which protects the integrity of system objects and subjects by means of +an information flow policy coupled with the subject demotion +via floating labels. +In LOMAC, all system subjects and objects are assigned integrity labels, made +up of one or more hierarchical grades, depending on their types. +Together, these label elements permit all labels to be placed in a partial +order, with information flow protections and demotion decisions +based on a dominance operator +describing the order. +The hierarchal grade field or fields are expressed +as a value between 0 and 65535, +with higher values reflecting higher integrity. +.Pp +Three special label component values exist: +.Bl -column -offset indent ".Sy Label" "dominated by all other labels" +.It Sy Label Ta Sy Comparison +.It Li low Ta "dominated by all other labels" +.It Li equal Ta "equal to all other labels" +.It Li high Ta "dominates all other labels" +.El +.Pp +The +.Dq Li high +label is assigned to system objects which affect the integrity of the system +as a whole. +The +.Dq Li equal +label +may be used to indicate that a particular subject or object is exempt from +the LOMAC protections. +For example, a label of +.Dq Li lomac/equal(equal-equal) +might be used on a subject which is to be used to administratively relabel +anything on the system. +.Pp +Almost all system objects are tagged with a single, active label element, +reflecting the integrity of the object, or integrity of the data contained +in the object. +File system objects may contain an additional auxiliary label which +determines the inherited integrity level for new files created in a +directory or the alternate label assumed by the subject upon execution of +an executable. +In general, objects labels are represented in the following form: +.Pp +.Sm off +.D1 Li lomac / Ar grade Bq Ar auxgrade +.Sm on +.Pp +For example: +.Bd -literal -offset indent +lomac/10[2] +lomac/low +.Ed +.Pp +Subject labels consist of three label elements: a single (active) label, +as well as a range of available labels. +This range is represented using two ordered LOMAC label elements, and when set +on a process, permits the process to change its active label to any label of +greater or equal integrity to the low end of the range, and lesser or equal +integrity to the high end of the range. +In general, subject labels are represented in the following form: +.Pp +.Sm off +.D1 Li lomac / Ar singlegrade ( lograde No - Ar higrade ) +.Sm on +.Pp +Modification of objects is restricted to access via the following comparison: +.Pp +.D1 Ar subject Ns :: Ns Ar higrade No \[>=] Ar target-object Ns :: Ns Ar grade +.Pp +Modification of subjects is the same, as the target subject's single grade +is the only element taken into comparison. +.Pp +Demotion of a subject occurs when the following comparison is true: +.Pp +.D1 Ar subject Ns :: Ns Ar singlegrade No > Ar object Ns :: Ns Ar grade +.Pp +When demotion occurs, the subject's +.Ar singlegrade +and +.Ar higrade +are reduced to the +object's grade, as well as the +.Ar lograde +if necessary. +When the demotion occurs, in addition to the permission of the subject being +reduced, shared +.Xr mmap 2 +objects which it has opened in its memory space may be revoked according to +the following +.Xr sysctl 3 +variables: +.Pp +.Bl -bullet -compact +.It +.Va security.mac.lomac.revocation_enabled +.It +.Va security.mac.enforce_vm +.It +.Va security.mac.mmap_revocation +.It +.Va security.mac.mmap_revocation_via_cow +.El +.Pp +Upon execution of a file, if the executable has an auxiliary label, and that +label is within the current range of +.Ar lograde Ns - Ns Ar higrade , +it will be assumed by the subject immediately. +After this, demotion is performed just as with any other read operation, with +the executable as the target. +Through the use of auxiliary labels, programs may be initially executed +at a lower effective integrity level, +while retaining the ability to raise it again. +.Pp +These rules prevent subjects of lower integrity from influencing the +behavior of higher integrity subjects by preventing the flow of information, +and hence control, from allowing low integrity subjects to modify either +a high integrity object or high integrity subjects acting on those objects. +LOMAC integrity policies may be appropriate in a number of environments, +both from the perspective of preventing corruption of the operating system, +and corruption of user data if marked as higher integrity than the attacker. +.Pp +The LOMAC security model is quite similar to that of +.Xr mac_biba 4 +and +.Xr mac_mls 4 +in various ways. +More background information on this can be found in their respective +man pages. +.Sh SEE ALSO +.Xr mmap 2 , +.Xr sysctl 3 , +.Xr mac 4 , +.Xr mac_biba 4 , +.Xr mac_bsdextended 4 , +.Xr mac_ddb 4 , +.Xr mac_ifoff 4 , +.Xr mac_mls 4 , +.Xr mac_none 4 , +.Xr mac_partition 4 , +.Xr mac_portacl 4 , +.Xr mac_seeotheruids 4 , +.Xr mac_test 4 , +.Xr mac 9 +.Sh HISTORY +The +.Nm +policy module first appeared in +.Fx 5.0 +and was developed by the +.Tn TrustedBSD +Project. +.Sh AUTHORS +This software was contributed to the +.Fx +Project by Network Associates Labs, +the Security Research Division of Network Associates +Inc. +under DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. diff --git a/static/freebsd/man4/mac_mls.4 b/static/freebsd/man4/mac_mls.4 new file mode 100644 index 00000000..608c1a72 --- /dev/null +++ b/static/freebsd/man4/mac_mls.4 @@ -0,0 +1,242 @@ +.\" Copyright (c) 2002-2004 Networks Associates Technology, Inc. +.\" All rights reserved. +.\" +.\" This software was developed for the FreeBSD Project by Chris Costello +.\" at Safeport Network Services and Network Associates Laboratories, the +.\" Security Research Division of Network Associates, Inc. under +.\" DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the +.\" DARPA CHATS research program. +.\" +.\" 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 AUTHORS 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 AUTHORS 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 25, 2015 +.Dt MAC_MLS 4 +.Os +.Sh NAME +.Nm mac_mls +.Nd "Multi-Level Security confidentiality policy" +.Sh SYNOPSIS +To compile MLS into your kernel, place the following lines in your kernel +configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Cd "options MAC_MLS" +.Ed +.Pp +Alternately, to load the MLS module at boot time, place the following line +in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Ed +.Pp +and in +.Xr loader.conf 5 : +.Bd -literal -offset indent +mac_mls_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +policy module implements the Multi-Level Security, or MLS model, +which controls access between subjects and objects based on their +confidentiality by means of a strict information flow policy. +Each subject and object in the system has an MLS label associated with it; +each subject's MLS label contains information on its clearance level, +and each object's MLS label contains information on its classification. +.Pp +In MLS, all system subjects and objects are assigned confidentiality labels, +made up of a sensitivity level and zero or more compartments. +Together, these label elements permit all labels to be placed in a partial +order, with confidentiality protections based on a dominance operator +describing the order. +The sensitivity level is expressed as a value between 0 and +65535, with higher values reflecting higher sensitivity levels. +The compartment field is expressed as a set of up to 256 components, +numbered from 1 to 256. +A complete label consists of both sensitivity and compartment +elements. +.Pp +With normal labels, dominance is defined as a label having a higher +or equal active sensitivity level, and having at least +all of the same compartments as the label to which it is being compared. +With respect to label comparisons, +.Dq Li lower +is defined as being dominated by the label to which it is being compared, +and +.Dq Li higher +is defined as dominating the label to which it is being compared, +and +.Dq Li equal +is defined as both labels being able to satisfy the dominance requirements +over one another. +.Pp +Three special label values exist: +.Bl -column -offset indent ".Li mls/equal" "dominated by all other labels" +.It Sy Label Ta Sy Comparison +.It Li mls/low Ta "dominated by all other labels" +.It Li mls/equal Ta "equal to all other labels" +.It Li mls/high Ta "dominates all other labels" +.El +.Pp +The +.Dq Li mls/equal +label may be applied to subjects and objects for which no enforcement of the +MLS security policy is desired. +.Pp +The MLS model enforces the following basic restrictions: +.Bl -bullet +.It +Subjects may not observe the processes of another subject if its +clearance level is lower than the clearance level of the object it is +attempting to observe. +.It +Subjects may not read, write, or otherwise observe objects without proper +clearance (e.g.\& subjects may not observe objects whose classification label +dominates its own clearance label) +.It +Subjects may not write to objects with a lower classification level than +its own clearance level. +.It +A subject may read and write to an object if its clearance level is equal +to the object's classification level as though MLS protections were not in +place. +.El +.Pp +These rules prevent subjects of lower clearance from gaining access +information classified beyond its clearance level in order to protect the +confidentiality of classified information, subjects of higher clearance +from writing to objects of lower classification in order to prevent the +accidental or malicious leaking of information, and subjects of lower +clearance from observing subjects of higher clearance altogether. +In traditional trusted operating systems, the MLS confidentiality model is +used in concert with the Biba integrity model +.Xr ( mac_biba 4 ) +in order to protect the Trusted Code Base (TCB). +.Ss Label Format +Almost all system objects are tagged with an effective, active label element, +reflecting the classification of the object, or classification of the data +contained in the object. +In general, object labels are represented in the following form: +.Pp +.Sm off +.D1 Li mls / Ar grade : compartments +.Sm on +.Pp +For example: +.Bd -literal -offset indent +mls/10:2+3+6 +mls/low +.Ed +.Pp +Subject labels consist of three label elements: an effective (active) label, +as well as a range of available labels. +This range is represented using two ordered MLS label elements, and when set +on a process, permits the process to change its active label to any label of +greater or equal integrity to the low end of the range, and lesser or equal +integrity to the high end of the range. +In general, subject labels are represented in the following form: +.Pp +.Sm off +.D1 Li mls / Ar effectivegrade : effectivecompartments ( lograde : locompartments No - +.D1 Ar higrade : hicompartments ) +.Sm on +.Pp +For example: +.Bd -literal -offset indent +mls/10:2+3+6(5:2+3-20:2+3+4+5+6) +mls/high(low-high) +.Ed +.Pp +Valid ranged labels must meet the following requirement regarding their +elements: +.Pp +.D1 Ar rangehigh No \[>=] Ar effective No \[>=] Ar rangelow +.Pp +One class of objects with ranges currently exists, the network interface. +In the case of the network interface, the effective label element references +the default label for packets received over the interface, and the range +represents the range of acceptable labels of packets to be transmitted over +the interface. +.Ss Runtime Configuration +The following +.Xr sysctl 8 +MIBs are available for fine-tuning the enforcement of this MAC policy. +.Bl -tag -width ".Va security.mac.mls.ptys_equal" +.It Va security.mac.mls.enabled +Enables the enforcement of the MLS confidentiality policy. +(Default: 1). +.It Va security.mac.mls.ptys_equal +Label +.Xr pty 4 Ns s +as +.Dq Li mls/equal +upon creation. +(Default: 0). +.It Va security.mac.mls.revocation_enabled +Revoke access to objects if the label is changed to a more sensitive +level than the subject. +(Default: 0). +.El +.Sh IMPLEMENTATION NOTES +Currently, the +.Nm +policy relies on superuser status +.Pq Xr suser 9 +in order to change network interface MLS labels. +This will eventually go away, but it is currently a liability and may +allow the superuser to bypass MLS protections. +.Sh SEE ALSO +.Xr mac 4 , +.Xr mac_biba 4 , +.Xr mac_bsdextended 4 , +.Xr mac_ddb 4 , +.Xr mac_ifoff 4 , +.Xr mac_lomac 4 , +.Xr mac_none 4 , +.Xr mac_partition 4 , +.Xr mac_portacl 4 , +.Xr mac_seeotheruids 4 , +.Xr mac_test 4 , +.Xr maclabel 7 , +.Xr mac 9 +.Sh HISTORY +The +.Nm +policy module first appeared in +.Fx 5.0 +and was developed by the +.Tn TrustedBSD +Project. +.Sh AUTHORS +This software was contributed to the +.Fx +Project by Network Associates Laboratories, +the Security Research Division of Network Associates +Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Sh BUGS +While the MAC Framework design is intended to support the containment of +the root user, not all attack channels are currently protected by entry +point checks. +As such, MAC Framework policies should not be relied on, in isolation, +to protect against a malicious privileged user. diff --git a/static/freebsd/man4/mac_none.4 b/static/freebsd/man4/mac_none.4 new file mode 100644 index 00000000..ee930906 --- /dev/null +++ b/static/freebsd/man4/mac_none.4 @@ -0,0 +1,104 @@ +.\" Copyright (c) 2002, 2003 Networks Associates Technology, Inc. +.\" All rights reserved. +.\" +.\" This software was developed for the FreeBSD Project by Chris Costello +.\" at Safeport Network Services and Network Associates Laboratories, the +.\" Security Research Division of Network Associates, Inc. under +.\" DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the +.\" DARPA CHATS research program. +.\" +.\" 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 AUTHORS 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 AUTHORS 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 25, 2015 +.Dt MAC_NONE 4 +.Os +.Sh NAME +.Nm mac_none +.Nd "null MAC policy module" +.Sh SYNOPSIS +To compile the null policy +into your kernel, place the following lines in your kernel +configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Cd "options MAC_NONE" +.Ed +.Pp +Alternately, to load the none module at boot time, place the following line +in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Ed +.Pp +and in +.Xr loader.conf 5 : +.Bd -literal -offset indent +mac_none_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +policy module implements a none MAC policy that has no effect on +access control in the system. +Unlike +.Xr mac_stub 4 , +none of the MAC entry points are defined. +.Ss Label Format +No labels are defined for +.Nm . +.Sh SEE ALSO +.Xr mac 4 , +.Xr mac_biba 4 , +.Xr mac_bsdextended 4 , +.Xr mac_ddb 4 , +.Xr mac_ifoff 4 , +.Xr mac_lomac 4 , +.Xr mac_mls 4 , +.Xr mac_partition 4 , +.Xr mac_portacl 4 , +.Xr mac_seeotheruids 4 , +.Xr mac_stub 4 , +.Xr mac_test 4 , +.Xr mac 9 +.Sh HISTORY +The +.Nm +policy module first appeared in +.Fx 5.0 +and was developed by the +.Tn TrustedBSD +Project. +.Sh AUTHORS +This software was contributed to the +.Fx +Project by Network Associates Labs, +the Security Research Division of Network Associates +Inc. +under DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Sh BUGS +While the MAC Framework design is intended to support the containment of +the root user, not all attack channels are currently protected by entry +point checks. +As such, MAC Framework policies should not be relied on, in isolation, +to protect against a malicious privileged user. diff --git a/static/freebsd/man4/mac_ntpd.4 b/static/freebsd/man4/mac_ntpd.4 new file mode 100644 index 00000000..083af4b6 --- /dev/null +++ b/static/freebsd/man4/mac_ntpd.4 @@ -0,0 +1,111 @@ +.\" Copyright (c) 2018 Ian Lepore +.\" +.\" 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 AUTHORS 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 AUTHORS 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 20, 2018 +.Dt MAC_NTPD 4 +.Os +.Sh NAME +.Nm mac_ntpd +.Nd "policy allowing ntpd to run as non-root user" +.Sh SYNOPSIS +To compile the ntpd policy into your kernel, place the following lines +in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Cd "options MAC_NTPD" +.Ed +.Pp +Alternately, to load the ntpd policy module at boot time, +place the following line in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Ed +.Pp +and in +.Xr loader.conf 5 : +.Bd -literal -offset indent +mac_ntpd_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +policy grants any process running as user +.Sq ntpd +(uid 123) the privileges needed to manipulate +system time, and to (re-)bind to the privileged NTP port. +.Pp +When +.Xr ntpd 8 +is started with +.Sq Fl u Ar [:group] +on the command line, it performs all initializations requiring root +privileges, then drops root privileges by switching to the given user id. +From that point on, the only privileges it requires are the ability +to manipulate system time, and the ability to re-bind a UDP socket +to the NTP port (port 123) after a network interface change. +.Pp +With the +.Nm +policy active, it may also be possible to start ntpd as a non-root user, +because the default ntpd options don't require any additional root +privileges beyond those granted by the policy. +.Ss Privileges Granted +The exact set of kernel privileges granted to any process running +with the configured uid is: +.Bl -inset -compact -offset indent +.It Dv PRIV_ADJTIME +.It Dv PRIV_CLOCK_SETTIME +.It Dv PRIV_NTP_ADJTIME +.It Dv PRIV_NETINET_RESERVEDPORT +.It Dv PRIV_NETINET_REUSEPORT +.El +.Ss Runtime Configuration +The following +.Xr sysctl 8 +MIBs are available for fine-tuning this MAC policy. +All +.Xr sysctl 8 +variables can also be set as +.Xr loader 8 +tunables in +.Xr loader.conf 5 . +.Bl -tag -width indent +.It Va security.mac.ntpd.enabled +Enable the +.Nm +policy. +(Default: 1). +.It Va security.mac.ntpd.uid +The numeric uid of the ntpd user. +(Default: 123). +.El +.Sh SEE ALSO +.Xr mac 4 , +.Xr ntpd 8 +.Sh HISTORY +MAC first appeared in +.Fx 5.0 +and +.Nm +first appeared in +.Fx 12.0 . diff --git a/static/freebsd/man4/mac_partition.4 b/static/freebsd/man4/mac_partition.4 new file mode 100644 index 00000000..f526601e --- /dev/null +++ b/static/freebsd/man4/mac_partition.4 @@ -0,0 +1,124 @@ +.\" Copyright (c) 2002 Networks Associates Technology, Inc. +.\" All rights reserved. +.\" +.\" This software was developed for the FreeBSD Project by Chris Costello +.\" at Safeport Network Services and Network Associates Laboratories, the +.\" Security Research Division of Network Associates, Inc. under +.\" DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the +.\" DARPA CHATS research program. +.\" +.\" 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 AUTHORS 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 AUTHORS 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 25, 2015 +.Dt MAC_PARTITION 4 +.Os +.Sh NAME +.Nm mac_partition +.Nd "process partition policy" +.Sh SYNOPSIS +To compile the process partition policy into your kernel, +place the following lines in your kernel +configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Cd "options MAC_PARTITION" +.Ed +.Pp +Alternately, to load the process partition module at boot time, +place the following line in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Ed +.Pp +and in +.Xr loader.conf 5 : +.Bd -literal -offset indent +mac_partition_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +policy module implements a process partition policy, +which allows administrators to place running processes into +.Dq partitions , +based on their numeric process partition +(specified in the process's MAC label). +Processes with a specified partition can only see processes that are in the +same partition. +If no partition is specified for a process, it can see all other processes +in the system +(subject to other MAC policy restrictions not defined in this man page). +No provisions for placing processes into multiple partitions are available. +.Ss Label Format +Partition labels take on the following format: +.Pp +.Sm off +.Dl Li partition / Ar value +.Sm on +.Pp +Where +.Ar value +can be any integer value or +.Dq Li none . +For example: +.Bd -literal -offset indent +partition/1 +partition/20 +partition/none +.Ed +.Sh SEE ALSO +.Xr mac 4 , +.Xr mac_biba 4 , +.Xr mac_bsdextended 4 , +.Xr mac_ddb 4 , +.Xr mac_ifoff 4 , +.Xr mac_lomac 4 , +.Xr mac_mls 4 , +.Xr mac_none 4 , +.Xr mac_portacl 4 , +.Xr mac_seeotheruids 4 , +.Xr mac_test 4 , +.Xr maclabel 7 , +.Xr mac 9 +.Sh HISTORY +The +.Nm +policy module first appeared in +.Fx 5.0 +and was developed by the +.Tn TrustedBSD +Project. +.Sh AUTHORS +This software was contributed to the +.Fx +Project by Network Associates Labs, +the Security Research Division of Network Associates +Inc. +under DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Sh BUGS +While the MAC Framework design is intended to support the containment of +the root user, not all attack channels are currently protected by entry +point checks. +As such, MAC Framework policies should not be relied on, in isolation, +to protect against a malicious privileged user. diff --git a/static/freebsd/man4/mac_portacl.4 b/static/freebsd/man4/mac_portacl.4 new file mode 100644 index 00000000..ca7be679 --- /dev/null +++ b/static/freebsd/man4/mac_portacl.4 @@ -0,0 +1,216 @@ +.\" Copyright (c) 2003 Networks Associates Technology, Inc. +.\" All rights reserved. +.\" +.\" This software was developed for the FreeBSD Project by Chris Costello +.\" at Safeport Network Services and Network Associates Labs, the +.\" Security Research Division of Network Associates, Inc. under +.\" DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the +.\" DARPA CHATS research program. +.\" +.\" 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 AUTHORS 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 AUTHORS 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 December 9, 2004 +.Dt MAC_PORTACL 4 +.Os +.Sh NAME +.Nm mac_portacl +.Nd "network port access control policy" +.Sh SYNOPSIS +To compile the port access control policy into your kernel, +place the following lines in your kernel +configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Cd "options MAC_PORTACL" +.Ed +.Pp +Alternately, to load the port access control policy module at boot time, +place the following line in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Ed +.Pp +and in +.Xr loader.conf 5 : +.Pp +.Dl "mac_portacl_load=""YES""" +.Sh DESCRIPTION +The +.Nm +policy allows administrators to administratively limit binding to +local +.Tn UDP +and +.Tn TCP +ports via the +.Xr sysctl 8 +interface. +.Pp +In order to enable the +.Nm +policy, MAC policy must be enforced on sockets +(see +.Xr mac 4 ) , +and the port(s) protected by +.Nm +must not be included in the range specified by +the +.Va net.inet.ip.portrange.reservedlow +and +.Va net.inet.ip.portrange.reservedhigh +.Xr sysctl 8 +MIBs. +.Pp +The +.Nm +policy only affects ports explicitly bound by a user process (either +for a listen/outgoing +.Tn TCP +socket, or a send/receive +.Tn UDP +socket). +This policy will not limit ports bound implicitly for outgoing +connections where the process has not explicitly selected a port: +these are automatically selected by the IP stack. +.Pp +When +.Nm +is enabled, it will control binding access to ports up to the port +number set in the +.Va security.mac.portacl.port_high +.Xr sysctl 8 +variable. +By default, all attempts to bind to +.Nm +controlled ports will fail if not explicitly allowed by the port +access control list, though binding by the superuser will be allowed, +if the +.Xr sysctl 8 +variable +.Va security.mac.portacl.suser_exempt +is set to a non-zero value. +.Ss Runtime Configuration +The following +.Xr sysctl 8 +MIBs are available for fine-tuning the enforcement of this MAC policy. +All +.Xr sysctl 8 +variables, except +.Va security.mac.portacl.rules , +can also be set as +.Xr loader 8 +tunables in +.Xr loader.conf 5 . +.Bl -tag -width indent +.It Va security.mac.portacl.enabled +Enforce the +.Nm +policy. +(Default: 1). +.It Va security.mac.portacl.port_high +The highest port number +.Nm +will enforce rules for. +(Default: 1023). +.It Va security.mac.portacl.rules +The port access control list is specified in the following format: +.Pp +.Sm off +.D1 Ar idtype : id : protocol : port Op , Ar idtype : id : protocol : port , ... +.Sm on +.Bl -tag -width ".Ar protocol" +.It Ar idtype +Describes the type of subject match to be performed. +Either +.Li uid +for user ID matching, or +.Li gid +for group ID matching. +.It Ar id +The user or group ID (depending on +.Ar idtype ) +allowed to bind to the specified port. +.Bf -emphasis +NOTE: User and group names are not valid; only the actual ID numbers +may be used. +.Ef +.It Ar protocol +Describes which protocol this entry applies to. +Either +.Li tcp +or +.Li udp +are supported. +.It Ar port +Describes which port this entry applies to. +.Bf -emphasis +NOTE: MAC security policies may not override other security system policies +by allowing accesses that they may deny, such as +.Va net.inet.ip.portrange.reservedlow / +.Va net.inet.ip.portrange.reservedhigh . +.Ef +If the specified port falls within the range specified, the +.Nm +entry will not function +(i.e., even the specified user/group may not be able to bind to the specified +port). +.El +.It Va security.mac.portacl.suser_exempt +Allow superuser (i.e., root) to bind to all +.Nm +protected ports, even if the port access control list does not +explicitly allow this. +(Default: 1). +.It Va security.mac.portacl.autoport_exempt +Allow applications to use automatic binding to port 0. +Applications use port 0 as a request for automatic port allocation when +binding an IP address to a socket. +This tunable will exempt port 0 allocation from rule checking. +(Default: 1). +.El +.Sh SEE ALSO +.Xr mac 3 , +.Xr ip 4 , +.Xr mac_biba 4 , +.Xr mac_bsdextended 4 , +.Xr mac_ddb 4 , +.Xr mac_ifoff 4 , +.Xr mac_mls 4 , +.Xr mac_none 4 , +.Xr mac_partition 4 , +.Xr mac_seeotheruids 4 , +.Xr mac_test 4 , +.Xr mac 9 +.Sh HISTORY +MAC first appeared in +.Fx 5.0 +and +.Nm +first appeared in +.Fx 5.1 . +.Sh AUTHORS +This software was contributed to the +.Fx +Project by NAI Labs, the Security Research Division of Network Associates +Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. diff --git a/static/freebsd/man4/mac_priority.4 b/static/freebsd/man4/mac_priority.4 new file mode 100644 index 00000000..c63197d5 --- /dev/null +++ b/static/freebsd/man4/mac_priority.4 @@ -0,0 +1,128 @@ +.\" Copyright (c) 2021 Florian Walpen +.\" +.\" 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 AUTHORS 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 AUTHORS 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 December 14, 2021 +.Dt MAC_PRIORITY 4 +.Os +.Sh NAME +.Nm mac_priority +.Nd "policy for scheduling privileges of non-root users" +.Sh SYNOPSIS +To compile the mac_priority policy into your kernel, place the following lines +in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Cd "options MAC_PRIORITY" +.Ed +.Pp +Alternately, to load the mac_priority policy module at boot time, +place the following line in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Ed +.Pp +and in +.Xr loader.conf 5 : +.Bd -literal -offset indent +mac_priority_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +policy grants scheduling privileges based on +.Xr group 5 +membership. +Users or processes in the group +.Sq realtime +(gid 47) are allowed to run threads and processes with realtime scheduling +priority. +Users or processes in the group +.Sq idletime +(gid 48) are allowed to run threads and processes with idle scheduling +priority. +.Pp +With the +.Nm +realtime policy active, privileged users may use the +.Xr rtprio 1 +utility to start processes with realtime priority. +Privileged applications can promote threads and processes to realtime +priority through the +.Xr rtprio 2 +system calls. +.Pp +When the idletime policy is active, privileged users may use the +.Xr idprio 1 +utility to start processes with idle priority. +Privileged applications can demote threads and processes to idle +priority through the +.Xr rtprio 2 +system calls. +.Ss Privileges Granted +The realtime policy grants the following kernel privileges to any process +running with the realtime group id: +.Bl -inset -offset indent -compact +.It Dv PRIV_SCHED_RTPRIO +.It Dv PRIV_SCHED_SETPOLICY +.El +.Pp +The kernel privilege granted by the idletime policy is: +.Bl -inset -offset indent -compact +.It Dv PRIV_SCHED_IDPRIO +.El +.Ss Runtime Configuration +The following +.Xr sysctl 8 +MIBs are available for fine-tuning this MAC policy. +All +.Xr sysctl 8 +variables can also be set as +.Xr loader 8 +tunables in +.Xr loader.conf 5 . +.Bl -tag -width indent +.It Va security.mac.priority.realtime +Enable the realtime policy. +(Default: 1). +.It Va security.mac.priority.realtime_gid +The numeric gid of the realtime group. +(Default: 47). +.It Va security.mac.priority.idletime +Enable the idletime policy. +(Default: 1). +.It Va security.mac.priority.idletime_gid +The numeric gid of the idletime group. +(Default: 48). +.El +.Sh SEE ALSO +.Xr idprio 1 , +.Xr rtprio 1 , +.Xr rtprio 2 , +.Xr mac 4 +.Sh HISTORY +MAC first appeared in +.Fx 5.0 +and +.Nm +first appeared in +.Fx 13.1 . diff --git a/static/freebsd/man4/mac_seeotheruids.4 b/static/freebsd/man4/mac_seeotheruids.4 new file mode 100644 index 00000000..04f67ebb --- /dev/null +++ b/static/freebsd/man4/mac_seeotheruids.4 @@ -0,0 +1,122 @@ +.\" Copyright (c) 2002 Networks Associates Technology, Inc. +.\" All rights reserved. +.\" +.\" This software was developed for the FreeBSD Project by Chris Costello +.\" at Safeport Network Services and Network Associates Laboratories, the +.\" Security Research Division of Network Associates, Inc. under +.\" DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the +.\" DARPA CHATS research program. +.\" +.\" 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 AUTHORS 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 AUTHORS 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 Februrary 26, 2026 +.Dt MAC_SEEOTHERUIDS 4 +.Os +.Sh NAME +.Nm mac_seeotheruids +.Nd "simple policy controlling whether users see other users" +.Sh SYNOPSIS +To compile the +policy into your kernel, place the following lines in your kernel +configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Cd "options MAC_SEEOTHERUIDS" +.Ed +.Pp +Alternately, to load the module at boot time, place the following line +in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Ed +.Pp +and in +.Xr loader.conf 5 : +.Bd -literal -offset indent +mac_seeotheruids_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +policy module, when enabled, denies users to see processes or sockets owned +by other users. +.Pp +To enable +.Nm , +set the sysctl OID +.Va security.mac.seeotheruids.enabled +to 1. +To permit superuser awareness of other credentials by virtue of privilege, +set the sysctl OID +.Va security.mac.seeotheruids.suser_privileged +to 1. +.Pp +To allow users to see processes and sockets owned by the same primary group, +set the sysctl OID +.Va security.mac.seeotheruids.primarygroup_enabled +to 1. +.Pp +To allow processes with a specific group ID to be exempt from the policy, +set the sysctl OID +.Va security.mac.seeotheruids.specificgid_enabled +to 1, and +.Va security.mac.seeotheruids.specificgid +to the list of group IDs to be exempted. +.Ss Label Format +No labels are defined for +.Nm . +.Sh SEE ALSO +.Xr mac 4 , +.Xr mac_biba 4 , +.Xr mac_bsdextended 4 , +.Xr mac_ddb 4 , +.Xr mac_ifoff 4 , +.Xr mac_lomac 4 , +.Xr mac_mls 4 , +.Xr mac_none 4 , +.Xr mac_partition 4 , +.Xr mac_portacl 4 , +.Xr mac_test 4 , +.Xr mac 9 +.Sh HISTORY +The +.Nm +policy module first appeared in +.Fx 5.0 +and was developed by the +.Tn TrustedBSD +Project. +.Sh AUTHORS +This software was contributed to the +.Fx +Project by Network Associates Labs, +the Security Research Division of Network Associates +Inc. +under DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Sh BUGS +While the MAC Framework design is intended to support the containment of +the root user, not all attack channels are currently protected by entry +point checks. +As such, MAC Framework policies should not be relied on, in isolation, +to protect against a malicious privileged user. diff --git a/static/freebsd/man4/mac_stub.4 b/static/freebsd/man4/mac_stub.4 new file mode 100644 index 00000000..7126898e --- /dev/null +++ b/static/freebsd/man4/mac_stub.4 @@ -0,0 +1,107 @@ +.\" Copyright (c) 2002, 2003 Networks Associates Technology, Inc. +.\" All rights reserved. +.\" +.\" This software was developed for the FreeBSD Project by Chris Costello +.\" at Safeport Network Services and Network Associates Laboratories, the +.\" Security Research Division of Network Associates, Inc. under +.\" DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the +.\" DARPA CHATS research program. +.\" +.\" 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 AUTHORS 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 AUTHORS 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 25, 2015 +.Dt MAC_STUB 4 +.Os +.Sh NAME +.Nm mac_stub +.Nd "MAC policy stub module" +.Sh SYNOPSIS +To compile the stub policy +into your kernel, place the following lines in your kernel +configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Cd "options MAC_STUB" +.Ed +.Pp +Alternately, to load the stub module at boot time, place the following line +in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Ed +.Pp +and in +.Xr loader.conf 5 : +.Bd -literal -offset indent +mac_stub_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +policy module implements a stub MAC policy that has no effect on +access control in the system. +Unlike +.Xr mac_none 4 , +each MAC entry point is defined as a +.Dq no-op , +so the policy module will be entered for each event, but no change +in system behavior should result. +.Ss Label Format +No labels are defined for +.Nm . +.Sh SEE ALSO +.Xr mac 4 , +.Xr mac_biba 4 , +.Xr mac_bsdextended 4 , +.Xr mac_ddb 4 , +.Xr mac_ifoff 4 , +.Xr mac_lomac 4 , +.Xr mac_mls 4 , +.Xr mac_none 4 , +.Xr mac_partition 4 , +.Xr mac_portacl 4 , +.Xr mac_seeotheruids 4 , +.Xr mac_test 4 , +.Xr mac 9 +.Sh HISTORY +The +.Nm +policy module first appeared in +.Fx 5.1 +and was developed by the +.Tn TrustedBSD +Project. +.Sh AUTHORS +This software was contributed to the +.Fx +Project by Network Associates Labs, +the Security Research Division of Network Associates +Inc. +under DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Sh BUGS +While the MAC Framework design is intended to support the containment of +the root user, not all attack channels are currently protected by entry +point checks. +As such, MAC Framework policies should not be relied on, in isolation, +to protect against a malicious privileged user. diff --git a/static/freebsd/man4/mac_test.4 b/static/freebsd/man4/mac_test.4 new file mode 100644 index 00000000..6c5c056e --- /dev/null +++ b/static/freebsd/man4/mac_test.4 @@ -0,0 +1,108 @@ +.\" Copyright (c) 2002 Networks Associates Technology, Inc. +.\" All rights reserved. +.\" +.\" This software was developed for the FreeBSD Project by Chris Costello +.\" at Safeport Network Services and Network Associates Laboratories, the +.\" Security Research Division of Network Associates, Inc. under +.\" DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the +.\" DARPA CHATS research program. +.\" +.\" 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 AUTHORS 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 AUTHORS 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 25, 2015 +.Dt MAC_TEST 4 +.Os +.Sh NAME +.Nm mac_test +.Nd MAC framework testing policy +.Sh SYNOPSIS +To compile the testing policy +into your kernel, place the following lines in your kernel +configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Cd "options MAC_TEST" +.Ed +.Pp +Alternately, to load the testing module at boot time, place the following line +in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "options MAC" +.Ed +.Pp +and in +.Xr loader.conf 5 : +.Bd -literal -offset indent +mac_test_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +policy module implements a testing facility for the MAC framework. +Among other things, +.Nm +will try to catch corrupt labels the system is attempting to destroy and +drop to the debugger. +Additionally, a set of statistics regarding the number of times various +MAC framework entry points have been called is stored in the +.Va security.mac.test +.Xr sysctl 8 +tree. +.Ss Label Format +No labels are defined for +.Nm . +.Sh SEE ALSO +.Xr mac 4 , +.Xr mac_biba 4 , +.Xr mac_bsdextended 4 , +.Xr mac_ddb 4 , +.Xr mac_ifoff 4 , +.Xr mac_lomac 4 , +.Xr mac_mls 4 , +.Xr mac_none 4 , +.Xr mac_partition 4 , +.Xr mac_portacl 4 , +.Xr mac_seeotheruids 4 , +.Xr mac 9 +.Sh HISTORY +The +.Nm +policy module first appeared in +.Fx 5.0 +and was developed by the +.Tn TrustedBSD +Project. +.Sh AUTHORS +This software was contributed to the +.Fx +Project by Network Associates Labs, +the Security Research Division of Network Associates +Inc. +under DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Sh BUGS +While the MAC Framework design is intended to support the containment of +the root user, not all attack channels are currently protected by entry +point checks. +As such, MAC Framework policies should not be relied on, in isolation, +to protect against a malicious privileged user. diff --git a/static/freebsd/man4/malo.4 b/static/freebsd/man4/malo.4 new file mode 100644 index 00000000..00b4ce4c --- /dev/null +++ b/static/freebsd/man4/malo.4 @@ -0,0 +1,116 @@ +.\"- +.\" Copyright (c) 2008 Weongyo Jeong +.\" 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, +.\" without modification. +.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer +.\" similar to the "NO WARRANTY" disclaimer below ("Disclaimer") and any +.\" redistribution must be conditioned upon including a substantially +.\" similar Disclaimer requirement for further binary redistribution. +.\" 3. Neither the names of the above-listed copyright holders nor the names +.\" of any contributors may be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" +.\" NO WARRANTY +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTIBILITY +.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL +.\" THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR 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 DAMAGES. +.\"/ +.Dd June 24, 2015 +.Dt MALO 4 +.Os +.Sh NAME +.Nm malo +.Nd "Marvell Libertas IEEE 802.11b/g wireless network driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device malo" +.Cd "device pci" +.Cd "device wlan" +.Cd "device firmware" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_malo_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for Marvell Libertas 88W8335 based PCI +and Cardbus network adapters. +.Nm +supports +.Cm station +and +.Cm monitor +mode operation. +Only one virtual interface may be configured at any time. +For more information on configuring this device, see +.Xr ifconfig 8 . +.Pp +This driver requires firmware to be loaded before it will work. +The +.Pa ports/net/malo-firmware-kmod +port needs to be installed before +.Xr ifconfig 8 +will work. +.Sh HARDWARE +The following cards are among those supported by the +.Nm +driver: +.Bl -column "Netgear WG311v3" "88W8335" "PCI" "b/g" +.Em "Card" Ta Em "Chip" Ta Em "Bus" Ta Em "Standard" +.It "Netgear WG311v3" Ta "88W8335" Ta "PCI" Ta "b/g" +.It "Tenda TWL542P" Ta "88W8335" Ta "PCI" Ta "b/g" +.It "U-Khan UW-2054i" Ta "88W8335" Ta "PCI" Ta "b/g" +.El +.Sh EXAMPLES +Join an existing BSS network (i.e., connect to an access point): +.Bd -literal -offset indent +ifconfig wlan create wlandev malo0 inet 192.168.0.20 \e + netmask 0xffffff00 +.Ed +.Pp +Join a specific BSS network with network name +.Dq Li my_net : +.Pp +.Dl "ifconfig wlan create wlandev malo0 ssid my_net up" +.Pp +Join a specific BSS network with 64-bit WEP encryption: +.Bd -literal -offset indent +ifconfig wlan create wlandev malo0 ssid my_net \e + wepmode on wepkey 0x1234567890 weptxkey 1 up +.Ed +.Sh SEE ALSO +.Xr cardbus 4 , +.Xr pci 4 , +.Xr wlan 4 , +.Xr wlan_ccmp 4 , +.Xr wlan_tkip 4 , +.Xr wlan_wep 4 , +.Xr ifconfig 8 , +.Xr wpa_supplicant 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 7.1 . diff --git a/static/freebsd/man4/man4.aarch64/Makefile b/static/freebsd/man4/man4.aarch64/Makefile new file mode 100644 index 00000000..4bdc15c4 --- /dev/null +++ b/static/freebsd/man4/man4.aarch64/Makefile @@ -0,0 +1,3 @@ +MAN = $(wildcard *.4) + +include ../../../mandoc.mk diff --git a/static/freebsd/man4/man4.aarch64/armv8crypto.4 b/static/freebsd/man4/man4.aarch64/armv8crypto.4 new file mode 100644 index 00000000..0f763adc --- /dev/null +++ b/static/freebsd/man4/man4.aarch64/armv8crypto.4 @@ -0,0 +1,81 @@ +.\" Copyright (c) 2016 The FreeBSD Foundation +.\" +.\" This software was developed by Andrew Turner under +.\" sponsorship from the FreeBSD Foundation. +.\" +.\" 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 29, 2020 +.Dt ARMV8CRYPTO 4 aarch64 +.Os +.Sh NAME +.Nm armv8crypto +.Nd "driver for the AES accelerator on ARM CPUs" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device crypto" +.Cd "device armv8crypto" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +armv8crypto_load="YES" +.Ed +.Sh DESCRIPTION +Starting with the ARMv8 architecture ARM Limited has added optional +cryptography instructions to accelerate AES, SHA-1, SHA-2, and +finite field arithmetic. +.Pp +The processor capability is reported as AES in the Instruction Set +Attributes 0 line at boot. +The +.Nm +driver does not attach on systems that lack the required CPU capability. +.Pp +The +.Nm +driver registers itself to accelerate AES operations for +.Xr crypto 4 . +.Sh SEE ALSO +.Xr crypt 3 , +.Xr crypto 4 , +.Xr intro 4 , +.Xr ipsec 4 , +.Xr random 4 , +.Xr crypto 7 , +.Xr crypto 9 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 11.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Andrew Turner Aq Mt andrew@FreeBSD.org . diff --git a/static/freebsd/man4/man4.aarch64/enetc.4 b/static/freebsd/man4/man4.aarch64/enetc.4 new file mode 100644 index 00000000..e7cfcb7e --- /dev/null +++ b/static/freebsd/man4/man4.aarch64/enetc.4 @@ -0,0 +1,69 @@ +.\" - +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2021 Alstom Group. +.\" Copyright (c) 2021 Semihalf. +.\" +.\" 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 ``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 June 11, 2021 +.Dt ENETC 4 aarch64 +.Os +.Sh NAME +.Nm enetc +.Nd "Freescale ENETC PCIe Gigabit Ethernet driver" +.Sh SYNOPSIS +To compile this driver into the kernel the following lines must be present +in the kernel configuration file: +.sp +.Cd "options SOC_NXP_LS" +.Cd "device pci" +.Cd "device fdt" +.Cd "device iflib" +.Cd "device enetc" +.Sh DESCRIPTION +The +.Nm +driver provides support for ENETC Gigabit Ethernet NIC found in LS1028A SoC. +.Xr iflib 9 +is used to communicate with the rest of kernel. +Both physical ports, as well as virtual interfaces connected to the internal +switch are supported. +.Pp +The following hardware offloads have been implemented in this version +of the driver: +.Bd -literal +- Receive IP checksum validation. +- VLAN tag insertion and extraction. +- VLAN tag based packet filtering. +.Ed +.Pp +For more information about configuring this device refer to +.Xr ifconfig 8 . +.Sh SEE ALSO +.Xr vlan 4 , +.Xr ifconfig 8 , +.Xr iflib 9 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 14.0 . diff --git a/static/freebsd/man4/man4.aarch64/felix.4 b/static/freebsd/man4/man4.aarch64/felix.4 new file mode 100644 index 00000000..b97f3c21 --- /dev/null +++ b/static/freebsd/man4/man4.aarch64/felix.4 @@ -0,0 +1,83 @@ +.\" - +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2021 Alstom Group. +.\" Copyright (c) 2021 Semihalf. +.\" +.\" 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 June 21, 2021 +.Dt FELIX 4 aarch64 +.Os +.Sh NAME +.Nm felix +.Nd "driver for Microchip Ocelot Felix switch" +.Sh SYNOPSIS +To compile this driver into the kernel the following lines must be present +in the kernel configuration file: +.sp +.Cd "options SOC_NXP_LS" +.Cd "device pci" +.Cd "device fdt" +.Cd "device mdio" +.Cd "device enetc" +.Cd "device etherswitch" +.Cd "device felix" +.Sh DESCRIPTION +The +.Nm +driver provides a management interface to Microchip Ocelot Felix switch (VSC9959) +found in NXP LS1028A SoC. It is a PCI device, part of the larger ENETC +root complex. The driver is using +.Xr etherswitch 4 +framework. +.Pp +This driver supports only dot1q vlan. dot1q support port base addtag, striptag, +dropuntagged, dropuntagged. +.Sh EXAMPLES +Configure dot1q vlan by etherswitchcfg command. +.Pp +.Dl # etherswitchcfg config vlan_mode dot1q +.Pp +Configure port 5 is tagging port. +.Pp +.Dl # etherswitchcfg port5 addtag +.Pp +Disable port 5 is tagging port. +.Pp +.Dl # etherswitchcfg port5 -addtag +.Sh SEE ALSO +.Xr etherswitch 4 , +.Xr etherswitchcfg 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 14.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Kornel Duleba (mindal@semihalf.com) +and +.An Lukasz Hajec (lha@semihalf.com) + diff --git a/static/freebsd/man4/man4.aarch64/rk_gpio.4 b/static/freebsd/man4/man4.aarch64/rk_gpio.4 new file mode 100644 index 00000000..b2767dd6 --- /dev/null +++ b/static/freebsd/man4/man4.aarch64/rk_gpio.4 @@ -0,0 +1,60 @@ +.\"- +.\" Copyright (c) 2018 Emmanuel Vadot +.\" +.\" 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 Apr 26, 2018 +.Dt RK_GPIO 4 aarch64 +.Os +.Sh NAME +.Nm rk_gpio +.Nd driver for the gpio controller on RockChip SoCs +.Sh SYNOPSIS +.Cd "options SOC_ROCKCHIP_RK3328" +.Sh DESCRIPTION +The +.Nm +device driver provides support for the gpio controller device present +on RockChip SoC. +.Sh HARDWARE +The current version of the +.Nm +driver supports the gpio banks with one of the following +compatible strings : +.Pp +.Bl -bullet -compact +.It +rockchip,gpio-bank +.El +.Sh SEE ALSO +.Xr gpiobus 4 , +.Xr gpioctl 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 12.0 . +.Sh AUTHORS +The +.Nm +device driver and manpage was written by +.An Emmanuel Vadot Aq Mt manu@freebsd.org . diff --git a/static/freebsd/man4/man4.aarch64/rk_grf.4 b/static/freebsd/man4/man4.aarch64/rk_grf.4 new file mode 100644 index 00000000..b01a9309 --- /dev/null +++ b/static/freebsd/man4/man4.aarch64/rk_grf.4 @@ -0,0 +1,57 @@ +.\"- +.\" Copyright (c) 2018 Emmanuel Vadot +.\" +.\" 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 Apr 26, 2018 +.Dt RK_GRF 4 aarch64 +.Os +.Sh NAME +.Nm rk_grf +.Nd driver for the General Register Files controller on RockChip SoCs +.Sh SYNOPSIS +.Cd "options SOC_ROCKCHIP_rk3328" +.Sh DESCRIPTION +The +.Nm +device driver provides support for the RockChip General Register Files +system controller. +.Sh HARDWARE +The current version of the +.Nm +driver supports the GRF controller with one of the following +compatible strings : +.Pp +.Bl -bullet -compact +.It +rockchip,rk3328-grf +.El +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 12.0 . +.Sh AUTHORS +The +.Nm +device driver and manpage was written by +.An Emmanuel Vadot Aq Mt manu@freebsd.org . diff --git a/static/freebsd/man4/man4.aarch64/rk_grf_gpio.4 b/static/freebsd/man4/man4.aarch64/rk_grf_gpio.4 new file mode 100644 index 00000000..2bfbebce --- /dev/null +++ b/static/freebsd/man4/man4.aarch64/rk_grf_gpio.4 @@ -0,0 +1,42 @@ +.\" +.\" Copyright (c) 2025 Stephen Hurd +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd March 18, 2025 +.Dt RK_GRF_GPIO 4 aarch64 +.Os +.Sh NAME +.Nm rk_grf_gpio +.Nd RockChip GPIO_MUTE pin driver +.Sh SYNOPSIS +.Cd "options SOC_ROCKCHIP_rk3328" +.Sh DESCRIPTION +The +.Nm +driver provides a single-pin, output-only +.Xr gpio 3 +unit whose single pin is named GPIO_MUTE. +This controls the output of the GPIO_MUTE pin on the SoC. +.Pp +This gpio is usually used to control another device on the board, +so is not usually available for user software. +.Sh HARDWARE +The +.Nm +driver supports the following GRF GPIO controller: +.Pp +.Bl -bullet -compact +.It +rockchip,rk3328-grf-gpio +.El +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 15.0 . +.Sh AUTHORS +The +.Nm +driver and manual were written by +.An Stephen Hurd Aq Mt shurd@freebsd.org . diff --git a/static/freebsd/man4/man4.aarch64/rk_i2c.4 b/static/freebsd/man4/man4.aarch64/rk_i2c.4 new file mode 100644 index 00000000..363cdeac --- /dev/null +++ b/static/freebsd/man4/man4.aarch64/rk_i2c.4 @@ -0,0 +1,62 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2018 Emmanuel Vadot +.\" +.\" 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 June 14, 2018 +.Dt RK_I2C 4 aarch64 +.Os +.Sh NAME +.Nm rk_i2c +.Nd driver for the i2c controller on RockChip SoCs +.Sh SYNOPSIS +.Cd "options SOC_ROCKCHIP_RK3328" +.Sh DESCRIPTION +The +.Nm +device driver provides support for the i2c controller device present +on RockChip SoC. +.Sh HARDWARE +The current version of the +.Nm +driver supports the i2c controller with one of the following +compatible strings : +.Pp +.Bl -bullet -compact +.It +rockchip,rk3328-i2c +.El +.Sh SEE ALSO +.Xr iic 4 , +.Xr iicbus 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 12.0 . +.Sh AUTHORS +The +.Nm +device driver and manpage was written by +.An Emmanuel Vadot Aq Mt manu@freebsd.org . diff --git a/static/freebsd/man4/man4.aarch64/rk_pinctrl.4 b/static/freebsd/man4/man4.aarch64/rk_pinctrl.4 new file mode 100644 index 00000000..2be5f363 --- /dev/null +++ b/static/freebsd/man4/man4.aarch64/rk_pinctrl.4 @@ -0,0 +1,59 @@ +.\"- +.\" Copyright (c) 2018 Emmanuel Vadot +.\" +.\" 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 Apr 26, 2018 +.Dt RK_PINCTRL 4 aarch64 +.Os +.Sh NAME +.Nm rk_pinctrl +.Nd driver for the pin multiplexing on RockChip SoCs +.Sh SYNOPSIS +.Cd "options SOC_ROCKCHIP_RK3328" +.Sh DESCRIPTION +The +.Nm +device driver provides support for the pin multiplexing device present +on RockChip SoC. +.Sh HARDWARE +The current version of the +.Nm +driver supports the pin controller with one of the following +compatible strings : +.Pp +.Bl -bullet -compact +.It +rockchip,rk3328-pinctrl +.El +.Sh SEE ALSO +.Xr fdt_pinctrl 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 12.0 . +.Sh AUTHORS +The +.Nm +device driver and manpage was written by +.An Emmanuel Vadot Aq Mt manu@freebsd.org . diff --git a/static/freebsd/man4/man4.arm/Makefile b/static/freebsd/man4/man4.arm/Makefile new file mode 100644 index 00000000..4bdc15c4 --- /dev/null +++ b/static/freebsd/man4/man4.arm/Makefile @@ -0,0 +1,3 @@ +MAN = $(wildcard *.4) + +include ../../../mandoc.mk diff --git a/static/freebsd/man4/man4.arm/am335x_dmtpps.4 b/static/freebsd/man4/man4.arm/am335x_dmtpps.4 new file mode 100644 index 00000000..bec5ff77 --- /dev/null +++ b/static/freebsd/man4/man4.arm/am335x_dmtpps.4 @@ -0,0 +1,161 @@ +.\" +.\" Copyright (c) 2015 Ian Lepore +.\" 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 ``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 August 12, 2015 +.Dt AM335X_DMTPPS 4 arm +.Os +.Sh NAME +.Nm am335x_dmtpps +.Nd RFC 2783 Pulse Per Second API driver for AM335x systems +.Sh SYNOPSIS +.Cd "device am335x_dmtpps" +.Pp +Optional in +.Pa /boot/loader.conf : +.Cd hw.am335x_dmtpps.input="pin name" +.\" +.Sh DESCRIPTION +The +.Nm +device driver provides a system time counter that includes precise +capture of Pulse Per Second (PPS) signals emitted by GPS receivers +and other timing devices. +The +.Nm +driver may be compiled into the kernel or loaded as a module. +.Pp +The AM335x timer hardware captures the value of the system time counter +on the leading edge of the PPS pulse. +Because the capture is done by the hardware there is no interrupt +latency in the measurement. +The time counter runs at 24Mhz, providing a measurement resolution +of 42 nanoseconds. +.Pp +To use the PPS timing information provided by this driver with +.Xr ntpd 8 , +symlink the +.Pa /dev/dmtpps +device to +.Pa /dev/pps0 +and configure server +.Va 127.127.22.0 +in +.Xr ntp.conf 5 +to configure a type 22 (ATOM) refclock. +.\" +.Sh DRIVER CONFIGURATION +The AM335x hardware provides four timer devices with a capture input +pin, DMTimer4 through DMTimer7. +Because it also provides the active system time counter, +only one instance of the +.Nm +driver can be active at a time. +The driver uses system pin configuration to determine which hardware +timer device to use. +Configure the timer input pin in the system's FDT data, or by +supplying the pin name using a tunable variable in +.Xr loader.conf 5 . +.Pp +To use a standard kernel and FDT data, use +.Xr loader.conf 5 +to load the +.Nm +module and set the +.Va hw.am335x_dmtpps.input +tunable variable to the name of the input pin, one of the following: +.Pp +.Bl -tag -width "GPMC_ADVn_ALE MMMM" -offset MMMM -compact +.It Em Name +.Em Hardware +.It P8-7 +DMTimer4; Beaglebone P8 header pin 7. +.It P8-8 +DMTimer7; Beaglebone P8 header pin 8. +.It P8-9 +DMTimer5; Beaglebone P8 header pin 9. +.It P8-10 +DMTimer6; Beaglebone P8 header pin 10. +.It GPMC_ADVn_ALE +DMTimer4. +.It GPMC_BEn0_CLE +DMTimer5. +.It GPMC_WEn +DMTimer6. +.It GPMC_OEn_REn +DMTimer7. +.El +.Pp +To configure the +.Nm +driver using FDT data, create a new pinctrl node by referencing the standard +.Va am33xx_pinmux +driver node (which is defined in am33xx.dtsi) in your dts file. +For example: +.Bd -literal + &am33xx_pinmux { + timer4_pins: timer4_pins { + pinctrl-single,pins = <0x90 (PIN_INPUT | MUX_MODE2)>; + }; + }; +.Ed +.Pp +Add pinctrl properties referencing +.Va timer4_pins +to the standard +.Va timer4 +device node (also defined in am33xx.dtsi) by referencing it in +your dts file as follows: +.Bd -literal + &timer4 { + pinctrl-names = "default"; + pinctrl-0 = <&timer4_pins>; + }; +.Ed +.\" +.Sh FILES +.Bl -tag -width ".Pa /dev/dmtpps" -compact +.It Pa /dev/dmtpps +The device providing +.Xr ioctl 2 +access to the RFC 2783 API. +.El +.\" +.Sh SEE ALSO +.Xr timecounters 4 , +.Xr loader.conf 5 , +.Xr ntp.conf 5 , +.Xr ntpd 8 +.\" +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 11.0 . +.\" +.Sh AUTHORS +The +.Nm +device driver and this manual page were written by +.An Ian Lepore Aq Mt ian@FreeBSD.org . diff --git a/static/freebsd/man4/man4.arm/ar40xx.4 b/static/freebsd/man4/man4.arm/ar40xx.4 new file mode 100644 index 00000000..e314d30d --- /dev/null +++ b/static/freebsd/man4/man4.arm/ar40xx.4 @@ -0,0 +1,35 @@ +.\" +.\" Copyright (c) 2025 Alexander Ziaee +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd May 10, 2025 +.Dt AR40XX 4 arm +.Sh NAME +.Nm ar40xx_switch +.Nd Qualcomm IPQ4018/IPQ4019 Gigabit Ethernet switch driver +.Sh SYNOPSIS +.Cd device mdio +.Cd etherswitch +.Cd ar40xx_switch +.Sh DESCRIPTION +The +.Nm +driver supports the Gigabit Ethernet switch inside the +Qualcomm IPQ4018/IPQ4019 SoC. +.Sh HARDWARE +The +.Nm +driver supports the following Gigabit Ethernet switch controllers: +.Pp +.Bl -bullet -compact +.It +Qualcomm IPQ 4019 Five-port Gigabit Ethernet Switch +.It +Qualcomm IPQ 4018 Five-port Gigabit Ethernet Switch +.El +.Sh SEE ALSO +.Xr etherswitch 4 , +.Xr etherswitchcfg 8 +.Sh CAVEATS +This driver currently only supports L2 port/VLAN mapping modes. diff --git a/static/freebsd/man4/man4.arm/bcm283x_pwm.4 b/static/freebsd/man4/man4.arm/bcm283x_pwm.4 new file mode 100644 index 00000000..71d7f0cc --- /dev/null +++ b/static/freebsd/man4/man4.arm/bcm283x_pwm.4 @@ -0,0 +1,108 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2017 Poul-Henning Kamp +.\" 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 ``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 September 10, 2018 +.Dt BCM283X_PWM 4 arm +.Os +.Sh NAME +.Nm bcm283x_pwm +.Nd bcm283x_pwm - driver for Raspberry Pi 2/3 PWM +.Sh SYNOPSIS +.Cd "kldload bcm283x_clkman" +.Cd "kldload bcm283x_pwm" +.Sh DESCRIPTION +The +.Nm +driver provides access to the PWM engine on GPIO12 of Raspberry Pi 2 and 3 hardware. +.Pp +The PWM hardware is controlled via the +.Xr sysctl 8 +interface: +.Bd -literal +dev.pwm.0.mode: 1 +dev.pwm.0.mode2: 1 +dev.pwm.0.freq: 125000000 +dev.pwm.0.ratio: 2500 +dev.pwm.0.ratio2: 2500 +dev.pwm.0.period: 10000 +dev.pwm.0.period2: 10000 +dev.pwm.0.pwm_freq: 12500 +dev.pwm.0.pwm_freq2: 12500 +.Ed +.Bl -tag -width ".Va dev.pwm" +.It Va dev.pwm.0.mode , dev.pwm.0.mode2 +PWM Mode for channels 1 and 2. +Three modes exist, 0=off, 1=PWM, 2=N/M. +The N/M mode is a first order delta-sigma mode, which makes a quite +handy DAC output with a trivial RC lowpass filter. +.Pp +.It Va dev.pwm.0.freq +The input frequency to the PWM hardware in Hz. +Applies to both channels 1 and 2. +Minimum frequency is 123 kHz, maximum frequency is 125 MHz. +.It Va dev.pwm.0.period , dev.pwm.0.period2 +The period length in cycles. +In PWM mode, the output frequencies will be +( +.Va dev.pwm.0.freq +/ +.Va dev.pwm.period +) and ( +.Va dev.pwm.0.freq2 +/ +.Va dev.pwm.0.period2 +). +In N/M mode this is the 'M'. +.It Va dev.pwm.0.ratio , dev.pwm.0.ratio2 +The "on" period in cycles for PWM channels 1 and 2. +In PWM mode, to get a 25% dutycycle, set this to 25% of +.Va dev.pwm.0.period +or +.Va dev.pwm.0.period2 , +as appropriate. +In N/M mode this is the 'N'. +.It Va dev.pwm.0.pwm_freq , dev.pwm.0.pwm_freq2 +The calculated PWM output frequencies in PWM mode, for channels 1 and 2. +.El +.Pp +.Sh NOTES +Currently the +.Nm +driver ignores the 'status="disabled"' flag in the DTB, assuming that +if you load the driver, you want it to work. +.Sh SEE ALSO +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 12.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver and this manual page were written by +.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org . diff --git a/static/freebsd/man4/man4.arm/devcfg.4 b/static/freebsd/man4/man4.arm/devcfg.4 new file mode 100644 index 00000000..cbc20581 --- /dev/null +++ b/static/freebsd/man4/man4.arm/devcfg.4 @@ -0,0 +1,93 @@ +.\" +.\" Copyright (c) 2013 Thomas Skibo +.\" 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. 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 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 February 28, 2013 +.Dt DEVCFG 4 arm +.Os +.Sh NAME +.Nm devcfg +.Nd Zynq PL device config interface +.Sh SYNOPSIS +.Cd device devcfg +.Sh DESCRIPTION +The special file +.Pa /dev/devcfg +can be used to configure the PL (FPGA) section of the Xilinx Zynq-7000. +.Pp +On the first write to the character device at file offset 0, the +.Nm +driver +asserts the top-level PL reset signals, disables the PS-PL level shifters, +and clears the PL configuration. +Write data is sent to the PCAP (processor configuration access port). +When the PL asserts the DONE signal, the devcfg driver will enable the level +shifters and release the top-level PL reset signals. +.Pp +The PL (FPGA) can be configured by writing the bitstream to the character +device like this: +.Bd -literal -offset indent +cat design.bit.bin > /dev/devcfg +.Ed +.Pp +The file should not be confused with the .bit file output by the FPGA +design tools. +It is the binary form of the configuration bitstream. +The Xilinx +.Ic promgen +tool can do the conversion: +.Bd -literal -offset indent +promgen -b -w -p bin -data_width 32 -u 0 design.bit -o design.bit.bin +.Ed +.Sh SYSCTL VARIABLES +The +.Nm +driver provides the following +.Xr sysctl 8 +variables: +.Bl -tag -width 4n +.It Va hw.fpga.pl_done +.Pp +This variable always reflects the status of the PL's DONE signal. +A 1 means the PL section has been properly programmed. +.It Va hw.fpga.en_level_shifters +.Pp +This variable controls if the PS-PL level shifters are enabled after the +PL section has been reconfigured. +This variable is 1 by default but setting it to 0 allows the PL section to be +programmed with configurations that do not interface to the PS section of the +part. +Changing this value has no effect on the level shifters until the next device +reconfiguration. +.El +.Sh FILES +.Bl -tag -width 12n +.It Pa /dev/devcfg +Character device for the +.Nm +driver. +.El +.Sh SEE ALSO +Zynq-7000 SoC Technical Reference Manual (Xilinx doc UG585) +.Sh AUTHORS +.An Thomas Skibo diff --git a/static/freebsd/man4/man4.arm/dwcotg.4 b/static/freebsd/man4/man4.arm/dwcotg.4 new file mode 100644 index 00000000..e6e8c797 --- /dev/null +++ b/static/freebsd/man4/man4.arm/dwcotg.4 @@ -0,0 +1,29 @@ +.\" +.\" Copyright (c) 2025 Alexander Ziaee +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd November 5, 2025 +.Dt DWCOTG 4 arm +.Os +.Sh NAME +.Nm dwcotg +.Nd Synopsys DesignWare USB controller driver +.Sh SYNOPSIS +.Cd device acpi +.Cd device fdt +.Cd device dwcotg +.Sh HARDWARE +The +.Nm +driver supports the +Synopsys DesignWare USB controller found in many embedded devices. +.Sh SEE ALSO +.Xr usb_template 4 +.Sh HISTORY +The +.Nm +driver appeared in +.Fx 10.0 . +.Sh AUTHORS +.An Hans Petter Selasky diff --git a/static/freebsd/man4/man4.arm/imx6_ahci.4 b/static/freebsd/man4/man4.arm/imx6_ahci.4 new file mode 100644 index 00000000..50689e32 --- /dev/null +++ b/static/freebsd/man4/man4.arm/imx6_ahci.4 @@ -0,0 +1,63 @@ +.\" +.\" Copyright (c) 2018 Ian Lepore +.\" 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 ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 7, 2018 +.Dt IMX6_AHCI 4 arm +.Os +.Sh NAME +.Nm imx6_ahci +.Nd device driver for the NXP i.MX6 on-chip SATA controller +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ahci" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +imx6_ahci_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides +support for the on-chip SATA controller found on some models of +the NXP i.MX6 chip. +The driver is a thin glue layer to interpret the platform's FDT +data and marshall resources for the standard +.Xr ahci 4 +driver. +.Sh SEE ALSO +.Xr ahci 4 , +.Xr fdt 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 12.0 . diff --git a/static/freebsd/man4/man4.arm/imx6_snvs.4 b/static/freebsd/man4/man4.arm/imx6_snvs.4 new file mode 100644 index 00000000..2c1db97b --- /dev/null +++ b/static/freebsd/man4/man4.arm/imx6_snvs.4 @@ -0,0 +1,76 @@ +.\" +.\" Copyright (c) 2018 Ian Lepore +.\" 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 ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 8, 2018 +.Dt IMX6_SNVS 4 arm +.Os +.Sh NAME +.Nm imx6_snvs +.Nd device driver for the NXP i.MX6 on-chip Realtime Clock +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device imx6_snvs" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +imx6_snvs_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides +support for the i.MX6 on-chip realtime clock. +It provides the time of day with a resolution of approximately +30 microseconds. +.Pp +.Sq SNVS +stands for Secure Non-Volatile Storage, and refers to the subsystem +within the chip that (optionally) remains powered by a battery when +the rest of the system is powered down. +The on-chip realtime clock is part of that subsystem. +Other features of the SNVS subsystem are related to security, tamper +monitoring, and power control; the +.Nm +driver does not currently support those features. +.Pp +Many i.MX6 systems do not use a battery to provide power to the SNVS +due to its relatively high power draw. In such systems, this driver +is able to provide a very accurate time following a reboot, but cannot +provide time at all if the power is cycled. If the system provides an +i2c or other type of alternate realtime clock with lower resolution, +there is value in configuring both clock drivers. +Doing so allows SNVS to provide accurate time after a reboot, while the +external clock provides approximate time after power cycling. +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 12.0 . diff --git a/static/freebsd/man4/man4.arm/imx_spi.4 b/static/freebsd/man4/man4.arm/imx_spi.4 new file mode 100644 index 00000000..54a5339e --- /dev/null +++ b/static/freebsd/man4/man4.arm/imx_spi.4 @@ -0,0 +1,88 @@ +.\" +.\" Copyright (c) 2018 Ian Lepore +.\" 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 ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 9, 2018 +.Dt IMX_SPI 4 arm +.Os +.Sh NAME +.Nm imx_spi +.Nd device driver for the NXP i.MX family Serial Peripheral Interface (SPI) +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device imx_spi" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +imx_spi_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the +.Sq ECSPI +(Enhanced Configurable SPI) hardware present on the NXP i.MX family +of processors. +While the ECSPI hardware supports both master and slave mode, +this driver currently operates only in master mode. +.Pp +Due to hardware quirks, the +.Nm +driver requires that all chip select pins be configured as GPIO pins. +Use the FDT property +.Sq cs-gpios +to specify which pins to use as chip selects. +You may use any GPIO pins, including the ones that the hardware would +normally use as SPI select pins; just configure them as GPIO in the +.Xr fdt_pinctrl 4 +data. +.Pp +.Sh SYSCTL VARIABLES +The following variables are available via +.Xr sysctl 8 , +and as +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va dev.imx_spi.%d.debug +Output debugging info when non-zero. +A value of 1 displays information about bus transfers, +2 adds information about bus clock frequency and chip select activity, +and 3 adds information about interrupt handling. +.El +.Sh SEE ALSO +.Xr fdt 4 , +.Xr fdt_pinctrl 4 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 12.0 . diff --git a/static/freebsd/man4/man4.arm/imx_wdog.4 b/static/freebsd/man4/man4.arm/imx_wdog.4 new file mode 100644 index 00000000..cb4d0e13 --- /dev/null +++ b/static/freebsd/man4/man4.arm/imx_wdog.4 @@ -0,0 +1,110 @@ +.\" +.\" Copyright (c) 2018 Ian Lepore +.\" 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 ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 7, 2018 +.Dt IMX_WDOG 4 arm +.Os +.Sh NAME +.Nm imx_wdog +.Nd device driver for the NXP i.MX5 and i.MX6 watchdog timer +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device imxwdt" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +imx_wdog_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides +.Xr watchdog 4 +support for the watchdog timer present on NXP i.MX5 and i.MX6 processors. +The i.MX watchdog hardware supports programmable timeouts ranging from +0.5 to 128 seconds, in half-second increments. +Once activated, the watchdog hardware cannot be deactivated, but the +timeout period can be changed to any valid non-zero value. +.Pp +At power-on, a special 16-second +.Sq power-down timer +mode is automatically enabled by the hardware. +It will assert the external WDOG_B signal, which may be connected to +external hardware that causes the system to reset or power-down. +The power-down timer is often reset by the boot loader (typically U-Boot). +If the power-down timer is still active at the time when the normal +watchdog is first enabled, the +.Nm +driver automatically disables it. +.Pp +The +.Nm +driver supports the FDT +.Va fsl,external-reset +property by enabling the assertion of the WDOG_B external timeout signal +when the property is present. +When running this way, the need to reset the system due to watchdog +timeout is signaled by driving the WDOG_B line low; some external +entity is expected to assert the chip's POR pin in response. +The +.Nm +driver attempts to backstop this external reset by scheduling an +interrupt to occur as well. +The interrupt handler waits 1 second for the external reset to occur, +then it triggers a normal software reset. +Note that the WDOG_B signal can be configured to use a variety of +pins on the chip. +For the +.Va fsl,external-reset +property to be effective, the signal must be connected to an appropriate +pin by the system's FDT pinctrl data. +.Pp +The +.Nm +driver supports the FDT +.Va timeout-secs +property by enabling the watchdog as soon as the driver attaches, +using the given timeout value. +This extends watchdog protection to much of the system startup process, +but it still requires that +.Xr watchdogd 4 +be configured to service the watchdog. +.Sh SEE ALSO +.Xr fdt 4 , +.Xr watchdog 4 , +.Xr watchdog 8 , +.Xr watchdogd 8 , +.Xr watchdog 9 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 10.0 . diff --git a/static/freebsd/man4/man4.arm/mge.4 b/static/freebsd/man4/man4.arm/mge.4 new file mode 100644 index 00000000..cba9327e --- /dev/null +++ b/static/freebsd/man4/man4.arm/mge.4 @@ -0,0 +1,158 @@ +.\" +.\" Copyright (c) 2008 Semihalf, Rafal Jaworowski +.\" +.\" 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 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 November 27, 2008 +.Dt MGE 4 arm +.Os +.Sh NAME +.Nm mge +.Nd "Marvell Gigabit Ethernet device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device mge" +.Cd "device miibus" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for gigabit Ethernet controller integrated in Marvell +system-on-chip devices. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width xxxxxxxxxxxxxxxxxxxx +.It autoselect +Enable autoselection of the media type and options +.It 10baseT/UTP +Set 10Mbps operation +.It 100baseTX +Set 100Mbps operation +.It 1000baseT +Set 1000baseT operation +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width xxxxxxxxxxxxxxxxxxxx +.It full-duplex +Set full duplex operation +.El +.Pp +The +.Nm +driver supports polled operation when the system is configured with +DEVICE_POLLING kernel option, see +.Xr polling 4 +for more details. +.Pp +The +.Nm +driver supports reception and transmission of extended frames +for +.Xr vlan 4 . +This capability of +.Nm +can be controlled by means of the +.Cm vlanmtu +parameter +to +.Xr ifconfig 8 . +.Pp +The +.Nm +driver supports interrupts coalescing (IC) so that raising a transmit/receive +frame interrupt is delayed, if possible, until a threshold-defined period of +time has elapsed. +The following sysctls regulate this behaviour (separately for each path): +.Bl -tag -width indent +.It Va dev.mge.X.int_coal.rx_time +.It Va dev.mge.X.int_coal.tx_time +.Pp +Value of 0 disables IC on the given path, value greater than zero corresponds +to a real time period and is expressed in units equivalent to 64 ticks of the +MGE clock. +Maximum allowed value depends on MGE hardware revision. +User provided values larger than supported will be trimmed to the maximum +supported. +More details are available in the reference manual of the device. +.El +.Sh HARDWARE +Gigabit Ethernet controllers built into the following Marvell systems-on-chip +are known to work with the +.Nm +driver: +.Pp +.Bl -bullet -compact +.It +Orion 88F5182 +.It +Orion 88F5281 +.It +Kirkwood 88F6281 (MGE V2) +.It +Discovery MV78100 (MGE V2) +.El +.Pp +There are also Marvell system controllers for PowerPC processors, which +include a variation of this gigabit Ethernet module integrated on chip, and +they should also work with the +.Nm +driver, but this wasn't tested: +.Pp +.Bl -bullet -compact +.It +MV64430 +.It +MV64460, MV64461, MV64462 +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr polling 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 8.0 . +.Sh AUTHORS +.An -nosplit +The base version of +.Nm +device driver was written by +.An Grzegorz Bernacki. +It has been extended with advanced features (polling, interrupt coalescing, +multicast, h/w checksum calculation etc.) by +.An Piotr Ziecik . +This manual page was written by +.An Rafal Jaworowski . diff --git a/static/freebsd/man4/man4.arm/ti_adc.4 b/static/freebsd/man4/man4.arm/ti_adc.4 new file mode 100644 index 00000000..fb59e1d3 --- /dev/null +++ b/static/freebsd/man4/man4.arm/ti_adc.4 @@ -0,0 +1,126 @@ +.\" +.\" Copyright (c) 2014 Luiz Otavio O Souza +.\" 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 ``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 June 1, 2014 +.Dt TI_ADC 4 arm +.Os +.Sh NAME +.Nm ti_adc +.Nd TI AM3XXX analog to digital converter driver +.Sh SYNOPSIS +.Cd "device ti_adc" +.Sh DESCRIPTION +The +.Nm +driver provides access to the AIN (analog inputs) on am3xxx SoCs. +.Pp +It provides raw readings of the converted values for each analog inputs. +.Pp +The access to +.Nm +data is made via the +.Xr sysctl 8 +interface: +.Bd -literal +dev.ti_adc.0.%desc: TI ADC controller +dev.ti_adc.0.%driver: ti_adc +dev.ti_adc.0.%pnpinfo: name=adc@44E0D000 compat=ti,adc +dev.ti_adc.0.%parent: simplebus0 +dev.ti_adc.0.clockdiv: 2400 +dev.ti_adc.0.ain.0.enable: 0 +dev.ti_adc.0.ain.0.open_delay: 0 +dev.ti_adc.0.ain.0.samples_avg: 0 +dev.ti_adc.0.ain.0.input: 0 +dev.ti_adc.0.ain.1.enable: 0 +dev.ti_adc.0.ain.1.open_delay: 0 +dev.ti_adc.0.ain.1.samples_avg: 0 +dev.ti_adc.0.ain.1.input: 0 +dev.ti_adc.0.ain.2.enable: 0 +dev.ti_adc.0.ain.2.open_delay: 0 +dev.ti_adc.0.ain.2.samples_avg: 0 +dev.ti_adc.0.ain.2.input: 0 +dev.ti_adc.0.ain.3.enable: 0 +dev.ti_adc.0.ain.3.open_delay: 0 +dev.ti_adc.0.ain.3.samples_avg: 0 +dev.ti_adc.0.ain.3.input: 0 +dev.ti_adc.0.ain.4.enable: 0 +dev.ti_adc.0.ain.4.open_delay: 0 +dev.ti_adc.0.ain.4.samples_avg: 0 +dev.ti_adc.0.ain.4.input: 0 +dev.ti_adc.0.ain.5.enable: 0 +dev.ti_adc.0.ain.5.open_delay: 0 +dev.ti_adc.0.ain.5.samples_avg: 0 +dev.ti_adc.0.ain.5.input: 0 +dev.ti_adc.0.ain.6.enable: 1 +dev.ti_adc.0.ain.6.open_delay: 0 +dev.ti_adc.0.ain.6.samples_avg: 4 +dev.ti_adc.0.ain.6.input: 2308 +dev.ti_adc.0.ain.7.enable: 1 +dev.ti_adc.0.ain.7.open_delay: 0 +dev.ti_adc.0.ain.7.samples_avg: 0 +dev.ti_adc.0.ain.7.input: 3812 +.Ed +.Pp +On Beaglebone-black the analog input 7 is connected to the 3V3B rail through +a voltage divisor (2:1). +The 3V3B voltage rail comes from the TL5209 LDO regulator which is limited +to 500mA maximum. +.Pp +Global settings: +.Bl -tag -width ".Va dev.ti_adc.0.clockdiv" +.It Va dev.ti_adc.0.clockdiv +Sets the ADC clock prescaler. +The minimum value is 10 and the maximum is 65535. +The ADC clock is based on CLK_M_OSC (24Mhz) / clockdiv. +This gives a maximum of ~2.4Mhz for the ADC clock and ~10Khz for the default +setting (clockdiv = 2400). +.El +.Pp +Settings per input: +.Bl -tag -width ".Va dev.ti_adc.0.ain.%d.samples_avg" +.It Va dev.ti_adc.0.ain.%d.enable +Enable the conversion for the input. +Each input should be individually enabled before it can be used. +When all the inputs are disabled, the ADC is turned off. +.It Va dev.ti_adc.0.ain.%d.open_delay +Sets the number of ADC clock cycles to wait after applying the input +configuration and before start the ADC conversion. +.It Va dev.ti_adc.0.ain.%d.samples_avg +Sets the number of samples average used on each input, it can be set to 0 +(no samples average), 2, 4, 8, or 16. +.It Va dev.ti_adc.0.ain.%d.input +Is the converted raw value of the voltage applied on the analog input. +It is made of a 12 bit value (0 ~ 4095). +.El +.Sh SEE ALSO +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 10.1 . +.Sh AUTHORS +.An -nosplit +The driver and this manual page was written by +.An Luiz Otavio O Souza Aq Mt loos@FreeBSD.org . diff --git a/static/freebsd/man4/man4.i386/CPU_ELAN.4 b/static/freebsd/man4/man4.i386/CPU_ELAN.4 new file mode 100644 index 00000000..c77b6cdc --- /dev/null +++ b/static/freebsd/man4/man4.i386/CPU_ELAN.4 @@ -0,0 +1,157 @@ +.\" Copyright (c) 2003 Poul-Henning Kamp +.\" 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 REGENTS 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 REGENTS 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 November 23, 2003 +.Dt CPU_ELAN 4 i386 +.Os +.Sh NAME +.Nm CPU_ELAN +.Nd AMD Elan 520 CPU support +.Sh SYNOPSIS +.Cd "options CPU_ELAN" +.Cd "options CPU_ELAN_PPS" +.Cd "options CPU_ELAN_XTAL" +.Bl -item -compact +.It +.Va machdep.elan_gpio_config +.It +.Va machdep.elan_freq +.El +.Cd "options CPU_SOEKRIS" +.Sh DESCRIPTION +The +.Cd "options CPU_ELAN" +enables support for the AMD Elan 520 CPU. +.Pp +A device +.Pa /dev/elan-mmcr +exports the MMCR register bank to userland +using +.Xr mmap 2 . +.Pp +The +.Tn i8254 +timer will be adjusted to the slightly unorthodox +frequency 1189161 Hz (32768 * 45 * 25 / 31) employed by the Elan. +.Pp +A timecounter named +.Dq Li ELAN +is implemented using the general purpose timer 2, +but it will not be usable unless HZ is configured at 150 or higher. +This timecounter is much better than the +.Dq Li i8254 +timecounter and should be +used at all times. +.Pp +The +.Va machdep.elan_gpio_config +.Xr sysctl 8 +variable +enables configuration of the GPIO pins of the CPU. +The string must be exactly 32 characters long. +A +.Ql - +means the GPIO is unavailable. +A +.Ql l +(lower-case ell) configures a +.Xr led 4 +device (active low). +A +.Ql L +configures a +.Xr led 4 +device (active high). +A +.Ql \&. +means no configuration for this GPIO. +These +.Xr led 4 +devices will be named +.Pa /dev/led/gpio%d . +For meaning of +.Ql P , +.Ql e +and +.Ql E , +see under +.Cd "options CPU_ELAN_PPS" . +.Pp +The +.Cd "options CPU_ELAN_XTAL" +and the +.Va machdep.elan_freq +.Xr sysctl 8 +variable +can be used to set the CPU clock crystal frequency in Hz. +The default is 33333333 Hz. +.Pp +The +.Cd "options CPU_ELAN_PPS" +enables precision timestamping using the RFC2783 PPS-API via the +.Pa /dev/elan-mmcr +device. +The resolution will be approximately 125 nsec +and the precision \(+- 125 nsec. +(For 125 nsec read +.Dq "4 / CPU clock crystal frequency" . ) +.Pp +The input signal must be connected to the TMR1IN pin and +a GPIO pin. +The GPIO pin must be configured with a +.Ql P +in +.Va machdep.elan_gpio_config . +.Pp +In addition, one GPIO pin can be configured with either +.Ql e +(active low) +or +.Ql E +(active high) to become a +.Dq echo +output of the input signal. +Please notice that this signal is not suitable for calibration. +.Pp +If the +.Cd "options CPU_SOEKRIS" +is given, the support will additionally be tailored to the +Soekris Engineering 45xx series of embedded computers. +The +.Dq error +led will be configured (as +.Pa /dev/led/error ) +and the GPIO pins which are not +available will be disabled. +.Sh SEE ALSO +.Xr led 4 , +.Xr timecounters 4 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +code first appeared in +.Fx 4.7 . +.Sh AUTHORS +.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org diff --git a/static/freebsd/man4/man4.i386/Makefile b/static/freebsd/man4/man4.i386/Makefile new file mode 100644 index 00000000..4bdc15c4 --- /dev/null +++ b/static/freebsd/man4/man4.i386/Makefile @@ -0,0 +1,3 @@ +MAN = $(wildcard *.4) + +include ../../../mandoc.mk diff --git a/static/freebsd/man4/man4.i386/apm.4 b/static/freebsd/man4/man4.i386/apm.4 new file mode 100644 index 00000000..48248e8a --- /dev/null +++ b/static/freebsd/man4/man4.i386/apm.4 @@ -0,0 +1,159 @@ +.\" LP (Laptop Package) +.\" +.\" Copyright (c) 1994 by HOSOKAWA, Tatsumi +.\" +.\" This software may be used, modified, copied, and distributed, in +.\" both source and binary form provided that the above copyright and +.\" these terms are retained. Under no circumstances is the author +.\" responsible for the proper functioning of this software, nor does +.\" the author assume any responsibility for damages incurred with its +.\" use. +.\" +.Dd November 1, 1994 +.Dt APM 4 i386 +.Os +.Sh NAME +.Nm apm +.Nd APM BIOS interface +.Sh SYNOPSIS +.Cd device apm +.Sh DEPRECATION NOTICE +This driver is scheduled for removal prior to the release of +.Fx 13.0 . +.Sh DESCRIPTION +.Nm +is an interface to the Intel / Microsoft APM (Advanced Power Management) BIOS +on laptop PCs. +.Pp +.Nm +provides the following power management functions. +.Bl -enum -offset indent +.It +When the system wakes up from suspended mode, +.Nm +adjusts the system clock to RTC. +.It +When the system wakes up from suspended mode, +.Nm +passes a message to +.Xr syslogd 8 +comprising of system wakeup time and elapsed time during suspended mode. +.It +.Nm +slows CPU clock when there are no system activities (runnable processes, +interrupts, etc.). +This function is available only on systems whose APM +supports CPU idling. +.It +.Nm +exports an application interface as a character device. +Applications +can control APM, or retrieve APM status information via this interface. +.Nm +exports the following interfaces. +These symbols are defined in +.In machine/apm_bios.h . +.Bl -tag -width 4n -offset indent +.It Sy APMIO_SUSPEND +Suspend system. +.It Sy APMIO_GET +Get power management information. +.It Sy APMIO_ENABLE +.It Sy APMIO_DISABLE +Enable / Disable power management. +.It Sy APMIO_HALTCPU +.It Sy APMIO_NOTHALTCPU +Control execution of HLT in the kernel context switch routine. +.It Sy APMIO_GETPWSTATUS +Get per battery information. +.Pp +Some APM implementations execute the HLT +(Halt CPU until an interrupt occurs) +instruction in the +.Dq Em Idle CPU +call, while others do not. +Thus enabling this may result in +redundant HLT executions because +.Dq Em Idle CPU +is called from the kernel context switch routine that inherently executes +HLT. +This may reduce peak system performance. +.Pp +Also the system hangs up if HLT instruction is disabled in the kernel +context switch routine, and if the APM implementation of the machine +does not execute HLT in +.Dq Em Idle CPU . +On some implementations that do not support CPU clock slowdown, APM +might not execute HLT. +.Nm +disables +.Sy APMIO_NOTHALTCPU +operation on such machines. +.Pp +The current version of +.Nm +does not call +.Dq Em Idle CPU +from the kernel context switch routine if clock slowdown is not supported, +and it executes HLT instruction by default. +Therefore, there is +no need to use these two operations in most cases. +.El +.Pp +These interfaces are used by +.Xr apm 8 . +.It +.Nm +polls APM events and handles the following events. +.Bl -column "xxxxxxxxxxxxxxxxx" "xxxxxxxxxxxxx" "xxxxxxxx" +.It Sy "Name" Ta Sy "Action" Ta Sy "Description" +.It Dv "PMEV_STANDBYREQ" Ta No "suspend system" Ta "standby request" +.It Dv "PMEV_SUSPENDREQ" Ta No "suspend system" Ta "suspend request" +.It Dv "PMEV_USERSUSPENDREQ" Ta No "suspend system" Ta "user suspend request" +.It Dv "PMEV_CRITSUSPEND" Ta No "suspend system" Ta "critical suspend request" +.It Dv "PMEV_NORMRESUME" Ta No "resume system" Ta "normal resume" +.It Dv "PMEV_CRITRESUME" Ta No "resume system" Ta "critical resume" +.It Dv "PMEV_STANDBYRESUME" Ta No "resume system" Ta "standby resume" +.It Dv "PMEV_BATTERYLOW" Ta No "notify message" Ta "battery low" +.It Dv "PMEV_UPDATETIME" Ta No "adjust clock" Ta "update time" +.El +.El +.Sh SEE ALSO +.Xr apm 8 , +.Xr zzz 8 +.Sh AUTHORS +.An Tatsumi Hosokawa Aq Mt hosokawa@jp.FreeBSD.org +.Sh BUGS +WARNING! +Many, if not most, of the implementations of APM-bios in laptops +today are buggy. +You may be putting your LCD-display and batteries at +a risk by using this interface. +(The reason this is not a problem for +MS-Windows is that they use the real-mode interface.) +If you see any +weird behavior from your system with this code in use, unplug the +power and batteries ASAP, if not immediately, and disable this code. +.Pp +We are very interested in getting this code working, so please send your +observations of any anomalous behavior to us. +.Pp +When +.Nm +is active, calling the BIOS setup routine by using hot-keys, +may cause serious trouble when resuming the system. +BIOS setup programs should be called during bootstrap, or from DOS. +.Pp +Some APM implementations cannot handle events such as pushing the +power button or closing the cover. +On such implementations, the system +.Ar must +be suspended +.Ar only +by using +.Xr apm 8 +or +.Xr zzz 8 . +.Pp +Disk spin-down, LCD backlight control, and power on demand have not +been supported on the current version. diff --git a/static/freebsd/man4/man4.i386/glxiic.4 b/static/freebsd/man4/man4.i386/glxiic.4 new file mode 100644 index 00000000..5e193799 --- /dev/null +++ b/static/freebsd/man4/man4.i386/glxiic.4 @@ -0,0 +1,105 @@ +.\" Copyright (c) 2011 Henrik Brix Andersen +.\" 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 ``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 May 15, 2011 +.Dt GLXIIC 4 i386 +.Os +.Sh NAME +.Nm glxiic +.Nd Geode LX CS5536 I2C controller driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device pci" +.Cd "device isa" +.Cd "device glxiic" +.Cd "device iicbus" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +glxiic_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports the System Management Bus controller of the Geode LX +series CS5536 Companion Device. +The Geode LX is a member of the AMD Geode family of integrated x86 system chips. +.Pp +Although AMD refers to this device as a System Management Bus (SMBus) +controller, it is really an I2C controller (it lacks SMBus ALERT# and +Alert Response support). +.Pp +The +.Nm +driver supports both I2C master and slave mode. +.Sh SYSCTL VARIABLE +The +.Nm +driver supports the following variable as both +.Xr sysctl 8 +and +.Xr loader 8 +tunable: +.Bl -tag -width indent +.It Va dev.glxiic.0.timeout +This variable controls the I2C bus timeout in milliseconds. +The default timeout is 35 milliseconds. +A value of zero disables the timeout. +.El +.Sh CAVEAT +The +.Nm +driver uses the interrupt line number configured by the board firmware +by default. +If no interrupt line number has been configured by the board firmware +(or to override the interrupt line number configured by board firmware), +place the following line in +.Xr device.hints 5 : +.Bd -ragged -offset indent +hint.glxiic.0.irq="10" +.Ed +.Pp +The interrupt line number must be between 1 and 15. +.Sh SEE ALSO +.Xr iicbus 4 , +.Xr device.hints 5 , +.Xr loader.conf 5 , +.Xr loader 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +device driver and manual page first appeared in +.Fx 9.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +device driver and manual page were written by +.An Henrik Brix Andersen Aq Mt brix@FreeBSD.org . diff --git a/static/freebsd/man4/man4.i386/glxsb.4 b/static/freebsd/man4/man4.i386/glxsb.4 new file mode 100644 index 00000000..3dbd650a --- /dev/null +++ b/static/freebsd/man4/man4.i386/glxsb.4 @@ -0,0 +1,96 @@ +.\" $OpenBSD: glxsb.4,v 1.5 2007/05/31 19:19:54 jmc Exp $ +.\" +.\"Copyright (c) 2006 Tom Cosgrove +.\" +.\"Permission to use, copy, modify, and distribute this software for any +.\"purpose with or without fee is hereby granted, provided that the above +.\"copyright notice and this permission notice appear in all copies. +.\" +.\"THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\"WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\"MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\"ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\"WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\"ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\"OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd July 29, 2020 +.Dt GLXSB 4 i386 +.Os +.Sh NAME +.Nm glxsb +.Nd Geode LX Security Block crypto accelerator +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device crypto" +.Cd "device glxsb" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +glxsb_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports the security block of the Geode LX series processors. +The Geode LX is a member of the AMD Geode family +of integrated x86 system chips. +.Pp +Driven by periodic checks for available data from the generator, +.Nm +supplies entropy to the +.Xr random 4 +driver for common usage. +.Pp +.Nm +also supports acceleration of AES-128-CBC operations for +.Xr crypto 4 . +It also registers itself to accelerate other HMAC algorithms, although +there is no hardware acceleration for those algorithms. +This is only needed so +.Nm +can work with +.Xr ipsec 4 . +.Sh CAVEAT +The +.Xr crypto 9 +framework will fail to open the crypto session on the device if the AES +key's length is != 128 bits. +This prevents the use of the +.Nm +device driver with AES keys of length != 128 bits. +.Sh SEE ALSO +.Xr crypto 4 , +.Xr intro 4 , +.Xr ipsec 4 , +.Xr pci 4 , +.Xr random 4 , +.Xr crypto 7 , +.Xr crypto 9 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Ox 4.1 . +The +.Nm +device driver was imported into +.Fx 7.1 . +.Sh AUTHORS +.An -nosplit +The +.Nm +device driver was written for +.Ox +by +.An Tom Cosgrove . +It was ported to +.Fx +by +.An Patrick Lamaiziere Aq Mt patfbsd@davenulle.org . diff --git a/static/freebsd/man4/man4.i386/longrun.4 b/static/freebsd/man4/man4.i386/longrun.4 new file mode 100644 index 00000000..329fcd4f --- /dev/null +++ b/static/freebsd/man4/man4.i386/longrun.4 @@ -0,0 +1,65 @@ +.\" Copyright (c) 2001 Tamotsu HATTORI +.\" Copyright (c) 2001 Mitsuru IWASAKI +.\" 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 June 30, 2001 +.Dt LONGRUN 4 i386 +.Os +.Sh NAME +.Nm longrun +.Nd Transmeta(TM) Crusoe(TM) LongRun(TM) support +.Sh SYNOPSIS +LongRun support is a collection of power saving modes for the +Transmeta Crusoe chips, similar in scope to Intel's SpeedStep. +The following +.Xr sysctl 8 +MIBs control the different CPU modes: +.Bl -column ".Va hw.crusoe.percentage" ".Vt integer" "Changeable" +.It Sy "Name Type Changeable Description" +.It Va hw.crusoe.longrun Ta Vt integer Ta yes Ta "LongRun mode:" +.It Ta Ta Ta "0: minimum frequency mode" +.It Ta Ta Ta "1: power-saving mode" +.It Ta Ta Ta "2: performance mode" +.It Ta Ta Ta "3: maximum frequency mode" +.It Va hw.crusoe.frequency Ta Vt integer Ta no Ta "Current frequency (MHz)." +.It Va hw.crusoe.voltage Ta Vt integer Ta no Ta "Current voltage (mV)." +.It Va hw.crusoe.percentage Ta Vt integer Ta no Ta "Processing performance (%)." +.El +.Sh EXAMPLES +Print the current status: +.Pp +.Dl "% sysctl hw.crusoe" +.Pp +To set LongRun mode to performance oriented variable frequency mode +(less power savings): +.Pp +.Dl "# sysctl hw.crusoe.longrun=2" +.Sh HISTORY +The Transmeta(TM) Crusoe(TM) LongRun(TM) support first appeared in +.Fx 4.4 . +.Sh AUTHORS +.An -nosplit +LongRun support and this manual page were written by +.An Tamotsu HATTORI Aq Mt athlete@kta.att.ne.jp +and +.An Mitsuru IWASAKI Aq Mt iwasaki@FreeBSD.org . diff --git a/static/freebsd/man4/man4.i386/npx.4 b/static/freebsd/man4/man4.i386/npx.4 new file mode 100644 index 00000000..982360c5 --- /dev/null +++ b/static/freebsd/man4/man4.i386/npx.4 @@ -0,0 +1,110 @@ +.\" +.\" Copyright (c) 1993 Christopher G. Demetriou +.\" 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 Christopher G. Demetriou. +.\" 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. +.\" +.\" $Id: npx.4,v 1.1 1993/08/06 10:58:03 cgd Exp $ +.\" +.Dd August 28, 1993 +.Dt NPX 4 i386 +.Os +.Sh NAME +.Nm npx +.Nd Numeric Processing Extension coprocessor +.Sh SYNOPSIS +.Cd "device npx" +.Cd hint.npx.0.at="nexus" +.Cd hint.npx.0.port="0x0F0" +.Cd hint.npx.0.flags="0x0" +.Cd hint.npx.0.irq="13" +.Sh DESCRIPTION +The +.Nm +driver enables the use of the system's Numeric Processing Extension +coprocessor. +Numeric processing extensions are present in +systems with +.Tn 486DX +CPUs and in systems with +.Tn 387 +or +.Tn 487SX +coprocessors. +The +.Nm +driver is required for proper system functioning. +If there is no NPX in the system, the system will not boot. +.Pp +The flags for +.Pa npx0 +are: +.Pp +.Bl -tag -width indent -compact +.It 0x01 +do not use the NPX registers to optimize bcopy. +.It 0x02 +do not use the NPX registers to optimize bzero. +.It 0x04 +do not use the NPX registers to optimize copyin or copyout. +.El +.Pp +The NPX registers are normally used +to optimize copying and zeroing +when all of the following conditions are satisfied: +.Pp +.Bl -enum -compact +.It +.Cd "cpu I586_CPU" +is an option +.It +the CPU is an i586 (perhaps not a Pentium) +.It +the probe for +.Pa npx0 +succeeds +.It +INT 16 exception handling works. +.El +.Pp +Then copying and zeroing +using the NPX registers +is normally 30-100% faster. +.Pp +The flags can be used +to control cases +where it does not work or is slower. +Setting them at boot time +using hints works correctly +(the optimizations are not used +until later in the bootstrap +when +.Pa npx0 +is attached). +.Sh BUGS +There are lots of them, especially on old cheap motherboards. +In particular, some motherboards do not have the interrupt lines from +the NPX to the CPU wired properly. diff --git a/static/freebsd/man4/man4.i386/pae.4 b/static/freebsd/man4/man4.i386/pae.4 new file mode 100644 index 00000000..3ebb2bff --- /dev/null +++ b/static/freebsd/man4/man4.i386/pae.4 @@ -0,0 +1,125 @@ +.\" +.\" Copyright (c) 2003 Networks Associates Technology, Inc. +.\" All rights reserved. +.\" +.\" This software was developed for the FreeBSD Project by Jake Burkholder, +.\" Safeport Network Services, and Network Associates Laboratories, the +.\" Security Research Division of Network Associates, Inc. under +.\" DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the DARPA +.\" CHATS research program. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 8, 2003 +.Dt PAE 4 i386 +.Os +.Sh NAME +.Nm PAE +.Nd Physical Address Extensions +.Sh SYNOPSIS +.Cd "options PAE" +.Sh DESCRIPTION +The +.Dv PAE +option provides support for the physical address extensions capability +of the +.Tn Intel +.Tn Pentium Pro +and above CPUs, +and allows for up to 64 gigabytes of memory to be used in systems capable +of supporting it. +With the +.Dv PAE +option, memory above 4 gigabytes is simply added to the general page pool. +The system makes no distinction between memory above or below 4 gigabytes, +and no specific facility is provided for a process or the kernel to access +more memory than they would otherwise be able to access, through a sliding +window or otherwise. +.Sh SEE ALSO +.Xr smp 4 , +.Xr tuning 7 , +.Xr config 8 , +.Xr bus_dma 9 +.Sh HISTORY +The +.Dv PAE +option first appeared in +.Fx 4.9 +and +.Fx 5.1 . +.Sh AUTHORS +.An Jake Burkholder Aq Mt jake@FreeBSD.org +.Sh BUGS +Since KLD modules are not compiled with the same options headers that +the kernel is compiled with, +they must not be loaded into a kernel compiled with the +.Dv PAE +option. +.Pp +Many devices or their device drivers are not capable of direct memory access +to physical addresses above 4 gigabytes. +In order to make use of direct memory access IO in a system with more than +4 gigabytes of memory when the +.Dv PAE +option is used, +these drivers must use a facility for remapping or substituting physical +memory which is not accessible to the device. +One such facility is provided by the +.Nm busdma +interface. +Device drivers which do not account for such devices will not work reliably +in a system with more than 4 gigabytes of memory when the +.Dv PAE +option is used, +and may cause data corruption. +The +.Pa PAE +kernel configuration file includes the +.Dv PAE +option, and explicitly excludes all device drivers which are known to not work +or have not been tested in a system with the +.Dv PAE +option and more than 4 gigabytes of memory. +.Pp +Many parameters which determine how memory is used in the kernel are based on +the amount of physical memory. +The formulas used to determine the values of these parameters for specific +memory configurations may not take into account the fact there may be more +than 4 gigabytes of memory, and may not scale well to these memory +configurations. +In particular, +it may be necessary to increase the amount of virtual address space available +to the kernel, +or to reduce the amount of a specific resource that is heavily used, +in order to avoid running out of virtual address space. +The +.Dv KVA_PAGES +option may be used to increase the kernel virtual address space, +and the +.Va kern.maxvnodes +.Xr sysctl 8 +may be used to decrease the number of vnodes allowed, +an example of a resource that the kernel is likely to overallocate in +large memory configurations. +For optimal performance and stability it may be necessary to consult the +.Xr tuning 7 +manual page, and make adjustments to the parameters documented there. diff --git a/static/freebsd/man4/man4.i386/pbio.4 b/static/freebsd/man4/man4.i386/pbio.4 new file mode 100644 index 00000000..927ac46c --- /dev/null +++ b/static/freebsd/man4/man4.i386/pbio.4 @@ -0,0 +1,185 @@ +.\" Copyright (c) 2000-2002 +.\" Diomidis D. Spinellis, Athens, Greece +.\" 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 as +.\" the first lines of this file unmodified. +.\" 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 Diomidis D. Spinellis ``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 Diomidis D. Spinellis 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 14, 2005 +.Dt PBIO 4 i386 +.Os +.Sh NAME +.Nm pbio +.Nd 8255 parallel peripheral interface basic +.Tn I/O +driver +.Sh SYNOPSIS +.Cd "device pbio" +.Pp +In +.Pa /boot/device.hints : +.Cd hint.pbio.0.at="isa" +.Cd hint.pbio.0.port="0x360" +.Pp +.In dev/pbio/pbioio.h +.Sh DESCRIPTION +The +.Nm +driver supports direct access to the Intel 8255A programmable +peripheral interface (PPI) chip running in mode 0 (simple +.Tn I/O ) . +Such an interface provides 24 digital +.Tn I/O +lines. +The driver is designed for performing +.Tn I/O +under program control using +peripherals such as the +.Tn Advantech +.Tn PCL-724 +card, which emulates the Intel 8255A PPI in mode 0. +Other 8255A-based peripherals such as the +.Tn BMC +Messsysteme +.Tn PIO24II +card have also been reported to work. +.Pp +The PPI provides two 8-bit ports (port A and port B) and +two 4-bit ports (port C upper, port C lower). +Each port can be individually programmed for input and +(latched) output, +and appears at a different offset of the device's base +.Tn I/O +address. +.Pp +A separate register allows the configuration of ports for input +or output. +The device is so simple, that reliably probing for it when +input data arrives at its terminals is impossible; +therefore the kernel configuration has to specify the +device's base address. +The device driver provides four character devices that +correspond to the peripheral's +.Tn I/O +ports. +Opening a device for read or write automatically configures +the corresponding hardware port for input or output. +At boot time all ports are set configured for input to avoid damaging +external circuitry. +.Pp +A set of +.Xr ioctl 2 +requests allow polled input and paced output to be +efficiently performed at the driver level without expensive +user/kernel context switching. +The driver can perform +.Tn I/O +in three different ways: +.Bl -tag -width ".No Differential" +.It Basic +The read or write operation returns immediately after reading +or writing the data to the port at bus speed. +.It Paced +Data is transferred from or to the port at intervals specified +by a separate +.Xr ioctl 2 +call. +.It Differential +(Input only.) +Only port values that differ from the previous port value are returned. +.El +.Pp +The pacing interval is specified in +.Em Hz +unit increments. +Setting a pace of +.Ar n +seconds +will result in no more than one value being read or written every +.Ar n +seconds. +Single byte read/write operations will take at least +.Ar n +seconds to complete. +.Pp +The following +.Xr ioctl 2 +calls are supported: +.Bl -tag -width ".Dv PBIO_SETIPACE" +.It Dv PBIO_SETDIFF +accepts a pointer to an integer as the third argument, +and sets the driver for differential input if the integer is non-zero. +The input pace speed determines the periodic interval the driver will use to +examine the port for a changed value. +.It Dv PBIO_GETDIFF +accepts a pointer to an integer as the third argument, +and sets the integer to the last set value for differential input. +.It Dv PBIO_SETIPACE +accepts a pointer to an integer as the third argument, +and sets the driver's input pacing speed to the value of that integer. +.It Dv PBIO_GETIPACE +accepts a pointer to an integer as the third argument, +and sets the integer to the last set value for the input pace. +.It Dv PBIO_SETOPACE +accepts a pointer to an integer as the third argument, +and sets the driver's output pacing speed to the value of that integer. +.It Dv PBIO_GETOPACE +accepts a pointer to an integer as the third argument, +and sets the integer to the last set value for the output pace. +.El +.Sh FILES +.Bl -tag -width ".Pa /dev/pbio0ch" -compact +.It Pa /dev/pbio0a +Port A (8 bit +.Tn I/O ) . +.It Pa /dev/pbio0b +Port B (8 bit +.Tn I/O ) . +.It Pa /dev/pbio0ch +Port C upper (4 bit +.Tn I/O ) . +.It Pa /dev/pbio0cl +Port C lower (4 bit +.Tn I/O ) . +.El +.Sh SEE ALSO +.Rs +.%A "Diomidis Spinellis" +.%T "The information furnace: Consolidated home control" +.%D "2003" +.%J "Personal and Ubiquitous Computing" +.%N 1 +.%V 7 +.%P "53-69" +.Re +.Sh HISTORY +The +.Nm +device was first used under +.Fx 4.1 . +.Sh AUTHORS +.An Diomidis D. Spinellis Aq Mt dds@aueb.gr +.Sh BUGS +One of the +.Tn PCL-724 +card's inputs can optionally be wired to generate an interrupt. +This feature is not supported. diff --git a/static/freebsd/man4/man4.i386/pnp.4 b/static/freebsd/man4/man4.i386/pnp.4 new file mode 100644 index 00000000..3afa48ae --- /dev/null +++ b/static/freebsd/man4/man4.i386/pnp.4 @@ -0,0 +1,83 @@ +.\" Copyright (c) 1997 Luigi Rizzo +.\" +.\" 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 ``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 September 20, 2001 +.Dt PNP 4 i386 +.Os +.Sh NAME +.Nm pnp +.Nd support for +.Dq "Plug and Play" +(PnP) ISA devices +.Sh DESCRIPTION +The +.Nm +driver enumerates ISA devices which support +.Dq "Plug and Play ISA Specification" +in the system. +It assigns ISA bus resources (interrupt line, DMA channel, I/O ports, +and memory region) to each device and activates it. +.Pp +If it cannot assign necessary resources to a PnP ISA device without +causing conflict with other devices in the system, +the device will not be activated and will be unavailable +to programs. +.Sh SEE ALSO +.Xr pnpbios 4 +.Sh STANDARDS +.Rs +.%A Intel +.%A Microsoft +.%T "Plug and Play ISA Specification, Version 1.0a" +.%D "May 5, 1994" +.Re +.Pp +.Rs +.%T "Clarifications to the Plug and Play ISA Specification, Version 1.0a" +.%D "December 10, 1994" +.Re +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 2.2.5 . +It has been substantially updated in subsequent versions. +.Sh AUTHORS +.An -nosplit +PnP support was originally written +for +.Fx 2.2.5 +by +.An Luigi Rizzo , +based on initial work done by +.An Sujal Patel . +.Sh CAVEATS +It is not possible to disable individual PnP ISA devices. +The +.Nm +driver will find all devices conforming the PnP ISA specification +and try to activate them all. +.Pp +There is no way to explicitly assign particular resource to +the PnP ISA device. +The resource assignment is fully automatic and there is +no provision for manual override. diff --git a/static/freebsd/man4/man4.i386/pnpbios.4 b/static/freebsd/man4/man4.i386/pnpbios.4 new file mode 100644 index 00000000..20097fc5 --- /dev/null +++ b/static/freebsd/man4/man4.i386/pnpbios.4 @@ -0,0 +1,83 @@ +.\" +.\" Copyright (c) 2001 +.\" Kazutaka YOKOTA +.\" 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 as +.\" the first lines of this file unmodified. +.\" 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 ``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 September 20, 2001 +.Dt PNPBIOS 4 i386 +.Os +.Sh NAME +.Nm pnpbios +.Nd support for embedded devices on the motherboard +.Sh DESCRIPTION +The +.Nm +driver enumerates embedded ISA devices on the motherboard whose BIOS +supports +.Dq "Plug and Play BIOS Specification" . +It assigns ISA bus resources (interrupt line, DMA channel, I/O ports, +and memory region) to each device and activates it. +.Pp +If it cannot assign necessary resources to a device without +causing conflict with other devices in the system, +the device will not be activated and will be unavailable +to programs. +.Sh SEE ALSO +.Xr pnp 4 +.Sh STANDARDS +.Rs +.%A Compaq +.%A Phenix +.%A Intel +.%T "Plug and Play BIOS Specification Version 1.0A" +.%D May 5, 1994 +.Re +.Pp +.Rs +.%A Compaq +.%A Phenix +.%A Intel +.%T "Plug and Play BIOS CLARIFICATION Paper for Plug and Play BIOS Specification Version 1.0A" +.%D October 6, 1994 +.Re +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 4.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Mike Smith . +.Sh CAVEATS +There is no explicit way to disable individual embedded devices. +The +.Nm +driver will find all devices reported by the +.Dq "Plug and Play (PnP)" +BIOS and try to activate them all. +.Pp +There is no way to explicitly assign particular resource to a device. +The resource assignment is fully automatic and there is +no provision for manual override. diff --git a/static/freebsd/man4/man4.i386/sbni.4 b/static/freebsd/man4/man4.i386/sbni.4 new file mode 100644 index 00000000..e311d82e --- /dev/null +++ b/static/freebsd/man4/man4.i386/sbni.4 @@ -0,0 +1,130 @@ +.\" Written by Denis I. Timofeev, 2002. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 8, 2002 +.Dt SBNI 4 i386 +.Os +.Sh NAME +.Nm sbni +.Nd Granch SBNI12 leased line modem driver +.Sh SYNOPSIS +.Cd "device sbni" +.Sh DESCRIPTION +The +.Nm +driver provides support for leased line modems of following models: +.Pp +.Bl -bullet -compact +.It +SBNI12-02, SBNI12D-02 +.It +SBNI12-04, SBNI12D-04 +.It +SBNI12-05, SBNI12D-05, ISA and PCI +.It +SBNI12-10, SBNI12D-10, ISA and PCI +.El +.Pp +and a kit for data link over a voice band: +.Bl -bullet +.It +SBNI12-11, SBNI12D-11, ISA and PCI. +.El +.Pp +In addition to the standard port and IRQ specifications, the +.Nm +driver also supports a number of +.Va flags +which can set baud rate, receive level, and low three bytes of Ethernet +MAC-address (high three are always +.Li 00:ff:01 ) , +because Granch modems are +presented to the system as Ethernet-like network cards. +.Pp +The high byte of the +.Va flags +is a bit field, it is used to specify SBNI adapter receive level/baud rate: +.Bl -tag -width "Bits 0-3:" -offset indent +.It "Bits 0-3:" +receive level (0x00..0x0f) +.It "Bits 4-5:" +baud rate number: +.Pp +.Bl -inset -compact +.It "00 -" +0 baud rate (2Mb in fast mode/500kb in slow) +.It "01 -" +1 baud rate (1Mb/250kb) +.It "10 -" +2 baud rate (500kb/125kb) +.It "11 -" +3 baud rate (250kb/62.5kb) +.El +.It "Bit 6:" +use fixed receive level +.Pp +if bit 6 is set then receive level will be set according +to bits 0-3 value, otherwise receive level will be +autodetected +.It "Bit 7:" +use fixed baud rate +.Pp +if bit 7 is set then baud rate will be set according to +bits 4-5 value, otherwise baud rate is set to 2Mb +.El +.Sh FILES +The sources for the driver reside in: +.Pp +.Bl -tag -width ".Pa /sys/dev/sbni/if_sbni.c" -compact +.It Pa /sys/dev/sbni/if_sbni.c +.It Pa /sys/dev/sbni/if_sbnireg.h +.It Pa /sys/dev/sbni/if_sbnivar.h +.El +.Sh SEE ALSO +.Xr arp 4 , +.Xr netintro 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 4.6 . +.Sh AUTHORS +.An -nosplit +The +.Nm +device driver for +.Fx +4.x was written by +.An Denis I. Timofeev , +partially based on +.An David Greenman Ns 's +.Xr ed 4 +driver. +Earlier versions (available on +.Pa ftp.granch.com ) +were written by +.An Alexey V. Zverev . +.Pp +SBNI12 hardware was designed by +.An Alexey V. Chirkov . diff --git a/static/freebsd/man4/man4.i386/smapi.4 b/static/freebsd/man4/man4.i386/smapi.4 new file mode 100644 index 00000000..494e4bcc --- /dev/null +++ b/static/freebsd/man4/man4.i386/smapi.4 @@ -0,0 +1,151 @@ +.\" +.\" Copyright (c) 2003 Tom Rhodes +.\" 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 April 1, 2003 +.Dt SMAPI 4 i386 +.Os +.Sh NAME +.Nm smapi +.Nd "System Management Application Program Interface driver" +.Sh DESCRIPTION +Many +.Tn IBM Thinkpad +laptops utilize a special software interface known as +.Tn SMAPI +(System Management Application Program Interface). +This interface controls various aspects of the system including: +.Bl -bullet +.It +System Interface +(the +.Tn BIOS +can store system information such as the system identifier), +.It +System Configuration (where devices such as the display can be configured), +.It +Power Management (software can interact with the +.Tn SMAPI BIOS +for Power Management control). +.El +.Pp +Client software must locate a +.Dq "header image" +stored in the +.Li F000 +segment in the +.Tn Thinkpad ROM +(read-only memory), which resides at the 16-byte boundary. +This is considered the +.Dq "Entry Point" +for the service. +.Pp +The +.Dq "header image" +stores information like: +.Bl -bullet +.It +signature, +.It +.Tn SMAPI +version (major and minor), +.It +header image length, +.It +checksum information (which verifies the image), +.It +an Information Word (used to identify the +.Tn BIOS +service level), +.It +Real Mode Entry Point (where clients using the +Real/V86 mode for the far-call value), +.It +and finally a 16-bit/32-bit Protected Mode Entry +Point: base code address which specifies the +.Tn BIOS +physical address. +The client must prepare a 64 kilobyte selector for this +.Tn BIOS ) . +.El +.Pp +To invoke the +.Tn SMAPI BIOS , +a far-call must be used on the entry point specified in the header file. +All other information should be stored in the client data area. +The client is required to prepare both an input and output parameter in a +data area of its own. +This area can be +.Dq informed +by pushing those pointers into its stack before the far-calls. +.Pp +The +.Tn SMAPI BIOS +uses the stack and data areas with the selector during a +.Tn BIOS +invocation, thus the caller must define the same privilege area as the +.Tn BIOS . +.Pp +The parameter structure will be made up by using the input and output +fields prepared by the caller. +The input field will specify the function request to the +.Tn BIOS . +The +.Tn BIOS +will then drop a return value into the output field. +These fields are made up of three parts. +The first holds parameters, function numbers, and return codes. +The next will contain an offset in hexadecimal. +Finally a length field which is comprised of Byte, Word, or Double Word. +.Sh SEE ALSO +.Rs +.%B "IBM Thinkpad 560/560E Technical Reference" +.%O "06J0536 S76H-7587-01" +.Re +.Rs +.%B "IBM Thinkpad 560Z Technical Reference" +.%O "xxxxxxx xxxx-xxxx-xx" +.Re +.Rs +.%B "IBM Thinkpad 600 Technical Reference" +.%O "xxxxxxx xxxx-xxxx-xx" +.Re +.Rs +.%B "IBM Thinkpad 760XD/760XL/765D/765L Technical Reference" +.%O "06J0537 S30H-2433-02" +.Re +.Rs +.%B "IBM Thinkpad 770 Technical Reference" +.%O "05L1739 S05L-1739-00" +.Re +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Matthew N. Dodd Aq Mt mdodd@FreeBSD.org . +This manual page was written by +.An Tom Rhodes Aq Mt trhodes@FreeBSD.org +and +.An Matthew N. Dodd Aq Mt mdodd@FreeBSD.org . diff --git a/static/freebsd/man4/man4.i386/vpd.4 b/static/freebsd/man4/man4.i386/vpd.4 new file mode 100644 index 00000000..83970ee1 --- /dev/null +++ b/static/freebsd/man4/man4.i386/vpd.4 @@ -0,0 +1,88 @@ +.\" Copyright (c) 2003 Matthew N. Dodd +.\" 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 August 31, 2004 +.Dt VPD 4 i386 +.Os +.Sh NAME +.Nm vpd +.Nd "Vital Product Data kernel interface" +.Sh SYNOPSIS +.Cd "device vpd" +.Sh DESCRIPTION +.Tn IBM ThinkPad +notebooks (and most +.Tn IBM +desktop PCs) have a 48-byte +Vital Product Data (VPD) structure located in the BIOS Shadow RAM. +.Pp +The VPD provides machine type and model information, the build ID +(this is roughly the BIOS version) and serial number information. +.Pp +The +.Nm +driver scans the BIOS area and claims the memory used by the VPD +structure. +It provides the +.Xr sysctl 3 +branch +.Va hw.vpd +to allow this information to be accessed by the userland. +The following variables are provided, one per VPD attachment (there should +only be one): +.Pp +.Bl -tag -width ".Dv MACHINE_MODEL" -compact +.It Dv MACHINE_TYPE +.Pq Va machine.type +Machine type. +.It Dv MACHINE_MODEL +.Pq Va machine.model +Machine model. +.It Dv BUILD_ID +.Pq Va build.id +BIOS Build ID. +.It Dv SERIAL_BOX +.Pq Va serial.box +Box Serial Number. +.It Dv SERIAL_PLANAR +.Pq Va serial.planar +Motherboard Serial Number. +.El +.Sh SEE ALSO +.Rs +.%T "TP General - Using the BIOS Build ID to identify IBM ThinkPad systems" +.%N "Reference #: MIGR-45120" +.%D "November 22, 2002" +.%U "http://www.ibm.com/support/docview.wss?uid=psg1MIGR-45120" +.Re +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 5.1 . +.Sh AUTHORS +The +.Nm +driver and this manual page were written by +.An Matthew N. Dodd Aq Mt mdodd@FreeBSD.org . diff --git a/static/freebsd/man4/man4.powerpc/Makefile b/static/freebsd/man4/man4.powerpc/Makefile new file mode 100644 index 00000000..4bdc15c4 --- /dev/null +++ b/static/freebsd/man4/man4.powerpc/Makefile @@ -0,0 +1,3 @@ +MAN = $(wildcard *.4) + +include ../../../mandoc.mk diff --git a/static/freebsd/man4/man4.powerpc/abtn.4 b/static/freebsd/man4/man4.powerpc/abtn.4 new file mode 100644 index 00000000..7421d0a0 --- /dev/null +++ b/static/freebsd/man4/man4.powerpc/abtn.4 @@ -0,0 +1,113 @@ +.\"- +.\" Copyright (c) 2011 Justin Hibbits +.\" Copyright (c) 2009 Nathan Whitehorn +.\" 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 ``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 October 16, 2011 +.Dt ABTN 4 powerpc +.Os +.Sh NAME +.Nm abtn +.Nd ADB Keyboard Special Keys Driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device adb" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the extended Fn keys on Apple notebooks with an ADB +interface. +.Sh HARDWARE +The +.Nm +driver supports extended keyboard keys (special F-keys) on the following devices: +.Pp +.Bl -bullet -compact +.It +Apple iBook Keyboard +.It +Apple PowerBook Keyboard +.El +.Sh EVENTS +The +.Nm +driver sends events to +.Xr devd 8 +for the following events under the +.Cd PMU +system, and +.Cd keys +subsystem: +.Pp +.Bl -bullet -compact +.It +.Cd brightness +- Generates +.Cd up +and +.Cd down +notify types matching the pressed key. +.It +.Cd mute +.It +.Cd volume +- Generates +.Cd up +and +.Cd down +notify types matching the pressed key. +.It +.Cd eject +.El +.Pp +Examples are included in /etc/devd/apple.conf. +.Sh SEE ALSO +.Xr adb 4 , +.Xr akbd 4 , +.Xr cuda 4 , +.Xr pmu 4 , +.Xr devd 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Nx 5.0 +and was ported to +.Fx 10.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Tsubai Masanari +for +.Nx +and ported to +.Fx +by +.An Justin Hibbits . diff --git a/static/freebsd/man4/man4.powerpc/adb.4 b/static/freebsd/man4/man4.powerpc/adb.4 new file mode 100644 index 00000000..6041484b --- /dev/null +++ b/static/freebsd/man4/man4.powerpc/adb.4 @@ -0,0 +1,67 @@ +.\"- +.\" Copyright (c) 2009 Nathan Whitehorn +.\" 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 ``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 December 3, 2009 +.Dt ADB 4 powerpc +.Os +.Sh NAME +.Nm adb +.Nd Apple Desktop Bus +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device adb" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the Apple Desktop Bus, which is a simple +multi-drop bus used in general for input peripherals in older Apple +Macintosh hardware. +.Pp +The Apple Desktop Bus provides attachment for up to 16 devices, +including multiple devices of a single type, but not does support +hot-plugging. +.Sh SEE ALSO +Apple Tech Note HW01: ADB - The Untold Story: Space Aliens Ate My Mouse: +.Pa http://developer.apple.com/legacy/mac/library/technotes/hw/hw_01.html +.Pp +.Xr akbd 4 , +.Xr ams 4 , +.Xr cuda 4 , +.Xr pmu 4 +.Sh HISTORY +The +.Nm +device driver appeared in +.Fx 8.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Nathan Whitehorn Aq Mt nwhitehorn@FreeBSD.org . diff --git a/static/freebsd/man4/man4.powerpc/akbd.4 b/static/freebsd/man4/man4.powerpc/akbd.4 new file mode 100644 index 00000000..3406f5a1 --- /dev/null +++ b/static/freebsd/man4/man4.powerpc/akbd.4 @@ -0,0 +1,102 @@ +.\"- +.\" Copyright (c) 2009 Nathan Whitehorn +.\" 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 ``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 December 3, 2009 +.Dt AKBD 4 powerpc +.Os +.Sh NAME +.Nm akbd +.Nd ADB Keyboard Driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device adb" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for all keyboards attached to the Apple Desktop +Bus (ADB). +.Sh HARDWARE +Devices supported by the +.Nm +driver include: +.Pp +.Bl -bullet -compact +.It +Apple Extended Keyboard +.It +Apple Keyboard II +.It +Apple iBook Keyboard +.It +Apple PowerBook Keyboard +.El +.Sh EVENTS +The +.Nm +driver sends events to +.Xr devd 8 +for the following events under the +.Cd PMU +system: +.Pp +.Bl -bullet -compact +.It +Power button - +.Cd "Button" +subsystem, +.Cd "pressed" +type. +.El +.Sh SYSCTL VARIABLES +The +.Nm +driver supports the following sysctl variable for configuring the Fn keys: +.Bl -tag -width indent +.It Va dev.akbd.%d.fn_keys_function_as_primary +Set the Fn keys to be their F-key type as default. A value of 0 causes the +F-keys keys to work as special keys by default ( +.Xr abtn 4 ) +and a value of 1 sets them to behave as F-keys by default. +.El +.Sh SEE ALSO +.Xr abtn 4 , +.Xr adb 4 , +.Xr cuda 4 , +.Xr pmu 4 +.Sh HISTORY +The +.Nm +device driver appeared in +.Fx 8.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Nathan Whitehorn Aq Mt nwhitehorn@FreeBSD.org . diff --git a/static/freebsd/man4/man4.powerpc/ams.4 b/static/freebsd/man4/man4.powerpc/ams.4 new file mode 100644 index 00000000..d7fa922e --- /dev/null +++ b/static/freebsd/man4/man4.powerpc/ams.4 @@ -0,0 +1,84 @@ +.\"- +.\" Copyright (c) 2009 Nathan Whitehorn +.\" 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 ``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 December 3, 2009 +.Dt AMS 4 powerpc +.Os +.Sh NAME +.Nm ams +.Nd ADB Mouse Driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device adb" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for mice and trackpads attached to the Apple Desktop +Bus (ADB) implementing both the base and extended ADB mouse protocols. +.Sh HARDWARE +Devices supported by the +.Nm +driver include: +.Pp +.Bl -bullet -compact +.It +Apple Mouse +.It +ADB Extended Mouse +.It +MacAlly 2-Button Mouse +.It +Apple iBook Trackpad +.It +Apple PowerBook Trackpad +.El +.Sh SYSCTL VARIABLES +.Bl -tag -width indent +.It Va dev.ams.%d.tapping +On ADB trackpads, setting this sysctl to 1 causes taps on the trackpad to +be interpreted as button clicks. +.El +.Sh SEE ALSO +Apple Tech Note HW01: ADB - The Untold Story: Space Aliens Ate My Mouse: +.Pa http://developer.apple.com/legacy/mac/library/technotes/hw/hw_01.html +.Pp +.Xr adb 4 , +.Xr cuda 4 , +.Xr pmu 4 +.Sh HISTORY +The +.Nm +device driver appeared in +.Fx 8.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Nathan Whitehorn Aq Mt nwhitehorn@FreeBSD.org . diff --git a/static/freebsd/man4/man4.powerpc/cuda.4 b/static/freebsd/man4/man4.powerpc/cuda.4 new file mode 100644 index 00000000..a52b9a44 --- /dev/null +++ b/static/freebsd/man4/man4.powerpc/cuda.4 @@ -0,0 +1,77 @@ +.\"- +.\" Copyright (c) 2009 Nathan Whitehorn +.\" 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 ``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 December 3, 2009 +.Dt CUDA 4 powerpc +.Os +.Sh NAME +.Nm cuda +.Nd Apple CUDA I/O Controller Driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device adb" +.Cd "device cuda" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the CUDA VIA (Versatile Interface Attachment) +chip found in pre-Core99 Apple hardware, such as the Power Macintosh G3. +.Pp +The Apple CUDA controller is a multi-purpose ASIC that provides power +control and an +.Xr adb 4 +interface. +.Sh HARDWARE +Chips supported by the +.Nm +driver include: +.Pp +.Bl -bullet -compact +.It +Apple CUDA I/O Controller +.El +.Sh SEE ALSO +.Xr adb 4 +.Sh HISTORY +The +.Nm +device driver appeared in +.Nx 4.0 , +and then in +.Fx 8.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Michael Lorenz Aq Mt macallan@NetBSD.org +and ported to +.Fx +by +.An Nathan Whitehorn Aq Mt nwhitehorn@FreeBSD.org . diff --git a/static/freebsd/man4/man4.powerpc/dtsec.4 b/static/freebsd/man4/man4.powerpc/dtsec.4 new file mode 100644 index 00000000..f18de90c --- /dev/null +++ b/static/freebsd/man4/man4.powerpc/dtsec.4 @@ -0,0 +1,117 @@ +.\" +.\" Copyright (c) 2016 Justin Hibbits +.\" +.\" 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 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 October 31, 2017 +.Dt DTSEC 4 powerpc +.Os +.Sh NAME +.Nm dtsec +.Nd "Freescale Datapath Acceleration Architecture-based Three-Speed Ethernet Controller device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "include ""dpaa/config.dpaa"" +.Cd "device dpaa" +.Cd "device miibus" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the DPAA-based gigabit Ethernet controller +integrated in some of the Freescale system-on-chip devices. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width xxxxxxxxxxxxxxxxxxxx +.It autoselect +Enable autoselection of the media type and options +.It 10baseT/UTP +Set 10Mbps operation +.It 100baseTX +Set 100Mbps operation +.It 1000baseT +Set 1000baseT operation +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width xxxxxxxxxxxxxxxxxxxx +.It full-duplex +Set full duplex operation +.El +.Pp +The +.Nm +driver supports two operating modes: +.Bl -tag -width xxxxxxxxxxxxxxxxxxxx +.It Regular +Normal mode, utilizing the full datapath acceleration, Buffer Manager, and Queue +Manager. +.It Independent +Runs disconnected from the Buffer Manager and Queue Manager. +.El +.Sh HARDWARE +Gigabit Ethernet controllers built into the following Freescale +system-on-chip devices are known to work with the +.Nm +driver: +.Pp +.Bl -bullet -compact +.It +P2041, P3041 +.It +P5010, P5020 +.El +.Pp +Additionally, the following devices are expected to work, but are untested: +.Bl -bullet -compact +.It +P4080, P4040 +.It +P5040 +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 11.0 . +.Sh AUTHORS +.An -nosplit +The base version of +.Nm +device driver was written by +.An Semihalf . +This manual page was written by +.An Justin Hibbits . diff --git a/static/freebsd/man4/man4.powerpc/llan.4 b/static/freebsd/man4/man4.powerpc/llan.4 new file mode 100644 index 00000000..b78109ca --- /dev/null +++ b/static/freebsd/man4/man4.powerpc/llan.4 @@ -0,0 +1,59 @@ +.\"- +.\" Copyright (c) 2015 Nathan Whitehorn +.\" 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 ``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 February 19, 2015 +.Dt LLAN 4 powerpc +.Os +.Sh NAME +.Nm llan +.Nd POWER Logical Lan +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device llan" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the inter-partition logical LAN controller +provided by PAPR-compliant POWER hypervisors (such as PowerVM and PowerKVM). +On some firmwares, advanced offload features are supported by the hypervisor, +but these are not currently supported by the driver. +.Sh SEE ALSO +.Xr vtnet 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver appeared in +.Fx 10.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Nathan Whitehorn Aq Mt nwhitehorn@FreeBSD.org . diff --git a/static/freebsd/man4/man4.powerpc/ofw_console.4 b/static/freebsd/man4/man4.powerpc/ofw_console.4 new file mode 100644 index 00000000..fca85a1f --- /dev/null +++ b/static/freebsd/man4/man4.powerpc/ofw_console.4 @@ -0,0 +1,110 @@ +.\"- +.\" Copyright (c) 2001 Miodrag Vallat. +.\" Copyright (c) 2005 Marius Strobl +.\" 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. Redistribution 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 ``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. +.\" +.\" from: OpenBSD: pcons.4,v 1.4 2003/06/02 16:16:26 miod Exp +.\" +.Dd January 16, 2021 +.Dt OFW_CONSOLE 4 powerpc +.Os +.Sh NAME +.Nm ofw_console +.Nd "Open Firmware console" +.Sh SYNOPSIS +.Cd "cpu AIM" +.Cd "options OFWCONS_POLL_HZ=N" +.Pp +.Cd "options KDB" +.Cd "options DDB" +.Cd "options ALT_BREAK_TO_DEBUGGER" +.Sh DESCRIPTION +The +.Nm +driver provides a simple text console, +using the Open Firmware services for input and output. +It will use the Open Firmware console devices set via the +.Va input-device +and +.Va output-device +variables. +.Pp +This driver is deprecated and only provided as a fallback console mechanism +if the real console hardware can not be driven by +.Fx . +.Pp +In case the +.Nm +console appears to work too slowly, its responsiveness probably can be improved +by including +.Cd "options OFWCONS_POLL_HZ=N" . +When omitted, +.Dv OFWCONS_POLL_HZ +defaults to 4. +For example, on +.Tn Sun Ultra 2 +a value of 20 or higher works best. +Too high values, on the other hand, can cause +.Nm +to unnecessarily consume CPU. +.Sh FILES +.Bl -tag -width ".Pa /dev/keyboard" -compact +.It Pa /dev/console +.It Pa /dev/keyboard +terminal input device in case the console input device is the keyboard +.It Pa /dev/screen +terminal output device in case the console output device is the screen +.It Pa /dev/tty[a-z] +terminal device in case both the console input and output device is tty[a-z] +.El +.Sh SEE ALSO +.Xr akbd 4 , +.Xr powermac_nvram 4 , +.Xr vt 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 5.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Benno Rice Aq Mt benno@FreeBSD.org . +.Sh CAVEATS +Since the Open Firmware will handle BREAK +(or Stop-A) +sequences before +.Nm , +the preferred way to enter +.Xr ddb 4 +when using +.Nm +is to include +.Cd "options ALT_BREAK_TO_DEBUGGER" +in a ddb-enabled kernel, and enter the alternate BREAK sequence +(RETURN TILDE CTRL-b). +.Sh BUGS +The +.Nm +driver also not attach to the hardware resources it actually talks to. diff --git a/static/freebsd/man4/man4.powerpc/pmu.4 b/static/freebsd/man4/man4.powerpc/pmu.4 new file mode 100644 index 00000000..4dfb31f1 --- /dev/null +++ b/static/freebsd/man4/man4.powerpc/pmu.4 @@ -0,0 +1,114 @@ +.\"- +.\" Copyright (c) 2008 Nathan Whitehorn +.\" 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 ``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 December 6, 2008 +.Dt PMU 4 powerpc +.Os +.Sh NAME +.Nm pmu +.Nd Apple PMU99 Power Management Driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device adb" +.Cd "device pmu" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the Power Management Unit (PMU) found in Apple +Core99 hardware. +This includes late G3 laptops, all G4 machines, early G5 +desktops and all G5 XServes. +.Pp +The Apple PMU controller is a multi-purpose ASIC that provides power +management and thermal control, as well as an ADB bus for the internal +keyboard and mouse on laptops. +.Sh HARDWARE +Chips supported by the +.Nm +driver include: +.Pp +.Bl -bullet -compact +.It +Apple KeyLargo PMU +.It +Apple K2-KeyLargo PMU +.El +.Sh SYSCTL VARIABLES +The +.Nm +driver provides power management services in addition to an +.Xr adb 4 +interface. +The following sysctls can be used to control the +power management behavior and to examine current system power and +thermal conditions. +.Bl -tag -width indent +.It Va dev.pmu.%d.server_mode +Restart after power failure behavior (1 causes system to reboot after power +cut, 0 causes system to remain off). +.It Va dev.pmu.%d.batteries.%d.present +Indicates whether the relevant battery is inserted. +.It Va dev.pmu.%d.batteries.%d.charging +Indicates whether the battery is currently charging. +.It Va dev.pmu.%d.batteries.%d.charge +The current battery charge, in milliamp hours. +.It Va dev.pmu.%d.batteries.%d.maxcharge +The battery's self-reported maximum charge, in milliamp hours. +.It Va dev.pmu.%d.batteries.%d.rate +The current into the battery, in milliamps. +While the battery is discharging, +this will be negative. +.It Va dev.pmu.%d.batteries.%d.voltage +Battery voltage, in millivolts. +.It Va dev.pmu.%d.batteries.%d.time +Estimated time until full battery charge (or discharge), in minutes. +.It Va dev.pmu.%d.batteries.%d.life +Current fraction of the battery's maximum charge, in percent. +.El +.Sh SEE ALSO +.Xr acpi 4 , +.Xr adb 4 , +.Xr led 4 +.Sh HISTORY +The +.Nm +device driver appeared in +.Nx 4.0 , +and then in +.Fx 8.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Michael Lorenz Aq Mt macallan@NetBSD.org +and ported to +.Fx +by +.An Nathan Whitehorn Aq Mt nwhitehorn@FreeBSD.org . diff --git a/static/freebsd/man4/man4.powerpc/powermac_nvram.4 b/static/freebsd/man4/man4.powerpc/powermac_nvram.4 new file mode 100644 index 00000000..ed15cb79 --- /dev/null +++ b/static/freebsd/man4/man4.powerpc/powermac_nvram.4 @@ -0,0 +1,65 @@ +.\"- +.\" Copyright (c) 2006 Maxim Sobolev +.\" 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 ``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 June 19, 2020 +.Dt POWERMAC_NVRAM 4 powerpc +.Os +.Sh NAME +.Nm powermac_nvram +.Nd "non-volatile RAM" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device powermac_nvram" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +powermac_nvram_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides access to the Open Firmware configuration NVRAM +available on the Apple PowerPC-based machines. +.Pp +This driver currently supports "Core99" machines containing a Sharp, Micron, +or AMD NVRAM. +.Sh SEE ALSO +.Xr nvram 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 7.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Maxim Sobolev Aq Mt sobomax@FreeBSD.org . diff --git a/static/freebsd/man4/man4.powerpc/smu.4 b/static/freebsd/man4/man4.powerpc/smu.4 new file mode 100644 index 00000000..852a08ab --- /dev/null +++ b/static/freebsd/man4/man4.powerpc/smu.4 @@ -0,0 +1,124 @@ +.\"- +.\" Copyright (c) 2010 Nathan Whitehorn +.\" 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 ``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 February 22, 2010 +.Dt SMU 4 powerpc +.Os +.Sh NAME +.Nm smu +.Nd Apple System Management Unit Driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device smu" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the System Management Unit (SMU) found in many +Apple G5 systems. +This includes most Power Macintosh G5 and all iMac G5 systems. +.Pp +The Apple SMU controller provides software power management and thermal +control functionality, and is responsible for managing system cooling +devices. +.Sh HARDWARE +Chips supported by the +.Nm +driver include: +.Pp +.Bl -bullet -compact +.It +Apple System Management Unit +.El +.Sh THERMAL MANAGEMENT +The +.Nm +driver provides basic automatic thermal management. +Without a userspace daemon providing more advanced control, the driver will +attempt to maintain system temperatures in a conservative range through +coarse-grained control of system cooling devices (see below). +Automatic kernel-level thermal control will take over if more than 3 +seconds elapses between userspace cooling setting adjustments. +.Sh SYSCTL VARIABLES +The +.Nm +driver provides power management services and thermal readout through a +sysctl interface. +The following sysctls can be used to control the power management behavior +and to examine current system power and thermal conditions. +.Bl -tag -width indent +.It Va dev.smu.%d.server_mode +Restart after power failure behavior (1 causes system to reboot after power +cut, 0 causes system to remain off). +.It Va dev.smu.%d.target_temp +Target system temperature, in degrees Celsius. +The +.Nm +driver will attempt to adjust fans to maintain the temperature of the +warmest component in the system at or below this level. +.It Va dev.smu.%d.critical_temp +System critical temperature, in degrees Celsius. +If any component in the system exceeds this temperature, the machine +will be shut down within 500 ms. +.It Va dev.smu.%d.fans.%s.minrpm +Minimum allowed speed for this fan. +.It Va dev.smu.%d.fans.%s.maxrpm +Maximum allowed speed for this fan. +.It Va dev.smu.%d.fans.%s.rpm +Current speed for this fan. +The fan speed can be adjusted by changing this sysctl. +If more than 3 seconds elapses between fan speed adjustments, the kernel will +resume automatic control of the fan. +.It Va dev.smu.%d.sensors.%s +Current reading from this sensor. +Four sensor types are supported. +Temperature sensors are in units of degrees Celsius, current sensors in +milliamps, voltage sensors in millivolts, and power sensors in milliwatts. +.El +.Sh LED INTERFACE +The +.Nm +driver provides an +.Xr led 4 +annunciator interface at +.Pa /dev/led/sleepled . +.Sh SEE ALSO +.Xr acpi 4 , +.Xr led 4 , +.Xr pmu 4 +.Sh HISTORY +The +.Nm +device driver appeared in +.Fx 8.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Nathan Whitehorn Aq Mt nwhitehorn@FreeBSD.org . diff --git a/static/freebsd/man4/man4.powerpc/snd_ai2s.4 b/static/freebsd/man4/man4.powerpc/snd_ai2s.4 new file mode 100644 index 00000000..7a3cd9cb --- /dev/null +++ b/static/freebsd/man4/man4.powerpc/snd_ai2s.4 @@ -0,0 +1,86 @@ +.\"- +.\" Copyright (c) 2009 Nathan Whitehorn +.\" 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 ``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 January 20, 2009 +.Dt SND_AI2S 4 powerpc +.Os +.Sh NAME +.Nm snd_ai2s +.Nd "Apple I2S audio device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device sound" +.Cd "device snd_ai2s" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +snd_ai2s_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the Apple I2S audio controllers found +predominantly in G4 and G5 machines, along with the snapper and tumbler +codecs. Some machines (e.g. the Mac Mini) do not have configurable +codecs and so lack hardware volume control. +.Sh HARDWARE +Chips supported by the +.Nm +driver include: +.Pp +.Bl -bullet -compact +.It +Apple Tumbler Audio +.It +Apple Snapper Audio +.El +.Sh SEE ALSO +.Xr snd_davbus 4 , +.Xr sound 4 +.Sh HISTORY +The +.Nm +device driver appeared in +.Nx 2.0 +and then in +.Fx 8.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Tsubai Masanari Aq Mt tsubai@netbsd.org , +and ported to +.Fx +by +.An Marco Trillo Aq Mt marcotrillo@gmail.com . +.Sh BUGS +Recording and operation with non-44.1 Khz audio are not currently supported. diff --git a/static/freebsd/man4/man4.powerpc/snd_davbus.4 b/static/freebsd/man4/man4.powerpc/snd_davbus.4 new file mode 100644 index 00000000..028225ac --- /dev/null +++ b/static/freebsd/man4/man4.powerpc/snd_davbus.4 @@ -0,0 +1,78 @@ +.\"- +.\" Copyright (c) 2009 Nathan Whitehorn +.\" 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 ``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 January 20, 2009 +.Dt SND_DAVBUS 4 powerpc +.Os +.Sh NAME +.Nm snd_davbus +.Nd "Apple Davbus audio device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device sound" +.Cd "device snd_davbus" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +snd_davbus_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the Apple Davbus audio controllers found in +many G3-era Apple machines. +.Sh HARDWARE +Chips supported by the +.Nm +driver include: +.Pp +.Bl -bullet -compact +.It +Apple Burgundy Audio +.It +Apple Screamer Audio +.El +.Sh SEE ALSO +.Xr snd_ai2s 4 , +.Xr sound 4 +.Sh HISTORY +The +.Nm +device driver appeared in +.Fx 8.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Marco Trillo Aq Mt marcotrillo@gmail.com . +.Sh BUGS +Recording is not currently supported. diff --git a/static/freebsd/man4/man4.powerpc/tsec.4 b/static/freebsd/man4/man4.powerpc/tsec.4 new file mode 100644 index 00000000..09510e32 --- /dev/null +++ b/static/freebsd/man4/man4.powerpc/tsec.4 @@ -0,0 +1,157 @@ +.\" +.\" Copyright (c) 2009 Semihalf, Rafal Jaworowski +.\" +.\" 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 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 February 20, 2015 +.Dt TSEC 4 powerpc +.Os +.Sh NAME +.Nm tsec +.Nd "Freescale Three-Speed Ethernet Controller device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device tsec" +.Cd "device miibus" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the gigabit Ethernet controller integrated in +some of the Freescale system-on-chip devices. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width xxxxxxxxxxxxxxxxxxxx +.It autoselect +Enable autoselection of the media type and options +.It 10baseT/UTP +Set 10Mbps operation +.It 100baseTX +Set 100Mbps operation +.It 1000baseT +Set 1000baseT operation +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width xxxxxxxxxxxxxxxxxxxx +.It full-duplex +Set full duplex operation +.El +.Pp +The +.Nm +driver supports polled operation when the system is configured with +DEVICE_POLLING kernel option, see +.Xr polling 4 +for more details. +.Pp +The +.Nm +driver supports reception and transmission of extended frames +for +.Xr vlan 4 . +This capability of +.Nm +can be controlled by means of the +.Cm vlanmtu +parameter +to +.Xr ifconfig 8 . +.Pp +The +.Nm +driver supports interrupts coalescing (IC) so that raising a transmit/receive +frame interrupt is delayed, if possible, until a threshold-defined period of +time has elapsed, or a threshold-defined frame counter has been reached +(whichever occurs first). +The following sysctls regulate this behaviour: +.Bl -tag -width indent +.It Va dev.tsec.X.int_coal.rx_time +.It Va dev.tsec.X.int_coal.rx_count +.It Va dev.tsec.X.int_coal.tx_time +.It Va dev.tsec.X.int_coal.tx_count +.Pp +Value of 0 for either time or count disables IC on the given path. +Time value +1-65535 corresponds to a real time period and is expressed in units equivalent +to 64 ticks of the TSEC clock. +Count 1-255 represents the number of frames +(note that value of 1 is equivalent to IC disabled). +User provided values +larger than supported will be trimmed to the maximum supported. +More details +are available in the reference manual of the device. +.El +.Sh HARDWARE +Gigabit Ethernet controllers built into the following Freescale +system-on-chip devices are known to work with the +.Nm +driver: +.Pp +.Bl -bullet -compact +.It +MPC8349 +.It +MPC8533, MPC8541, MPC8555 +.El +.Pp +The enhanced version of the controller (eTSEC), integrated in the following +devices, is also supported by this driver: +.Pp +.Bl -bullet -compact +.It +MPC8548, MPC8572 +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr polling 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 8.0 . +.Sh AUTHORS +.An -nosplit +The base version of +.Nm +device driver was written by +.An Piotr Kruszynski . +It has been extended with polling and interrupt coalescing support by +.An Rafal Jaworowski . +It has been further enhanced with multicast, h/w checksum calculation and vlan +support by +.An Piotr Ziecik . +This manual page was written by +.An Rafal Jaworowski . diff --git a/static/freebsd/man4/max44009.4 b/static/freebsd/man4/max44009.4 new file mode 100644 index 00000000..474bec7d --- /dev/null +++ b/static/freebsd/man4/max44009.4 @@ -0,0 +1,90 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2020 Andriy Gapon +.\" +.\" 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 November 6, 2021 +.Dt MAX44009 4 +.Os +.Sh NAME +.Nm max44009 +.Nd driver for MAX44009 Ambient Light Sensor +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device max44009" +.Cd "device iicbus" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +max44009_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver reports illuminance data from MAX44009 Ambient Light Sensor. +.Pp +The +.Nm +driver reports data via +.Xr sysctl 8 +entry in the device's node in the +.Xr sysctl 8 +tree: +.Bl -tag -width illuminance +.It Va illuminance +The illuminance, in lux units. +.El +.Pp +On an +.Xr FDT 4 +based system the following properties must be set: +.Bl -tag -width "compatible" +.It Va compatible +Must be set to +.Qq maxim,max44009 . +.It Va reg +The I2C address of +.Nm +which can be either 0x4a or 0x4b. +.El +.Sh SEE ALSO +.Xr fdt 4 , +.Xr iicbus 4 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +driver and this manual page was written by +.An Andriy Gapon Aq Mt avg@FreeBSD.org . +.Sh BUGS +The +.Nm +driver does not support illuminance thresholds and the corresponding +interrupt. diff --git a/static/freebsd/man4/mca.4 b/static/freebsd/man4/mca.4 new file mode 100644 index 00000000..11d88519 --- /dev/null +++ b/static/freebsd/man4/mca.4 @@ -0,0 +1,277 @@ +.\" +.\" Copyright (c) 2026 The FreeBSD Project +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd January 14, 2026 +.Dt MCA 4 amd64 +.Os +.Sh NAME +.Nm mca +.Nd Machine Check Architecture +.Sh DESCRIPTION +The +.Nm +subsystem provides support for the x86 Machine Check Architecture. +The CPU uses this architecture to report various hardware problems, +ranging from correctible errors to uncorrectible fatal errors. +The +.Nm +subsystem processes the errors reported by the CPU and logs them +according to the user-supplied configuration. +.Pp +The +.Nm +subsystem is automatically compiled into every x86 kernel. +.Sh LOGGING +By default, every message is logged to four locations: +.Bl -bullet +.It +The console +.It +The system log (using the +.Dv LOG_KERN +.Xr syslog 3 +facility) +.It +An in-kernel cache of event records +.It +A statistics array +.El +.Pp +An administrator can disable console logging of non-fatal errors using the +.Va hw.mca.uselog +.Xr sysctl 8 +or tunable setting. +Fatal errors are always logged to the console. +.Pp +The in-kernel cache of event records can be accessed from userspace using the +.Va hw.mca.records +.Xr sysctl 8 +node. +By default, the in-kernel cache of event records grows without bound and +contains records for all +.Nm +events received since system boot. +The cache can be limited (in which case it turns into a ring buffer) or +disabled altogether using the +.Va hw.mca.maxcount +.Xr sysctl 8 +or tunable setting. +.Pp +The statistics array can be retrieved using the +.Va hw.mca.stats +.Xr sysctl 8 +node. +.Sh SYSCTL VARIABLES +The subsystem has a number of configuration options to control the +way events are processed and logged. +These options are configured via +.Xr sysctl 8 +variables or tunables. +These settings control things such as log destination, event limiting, +and sampling. +These settings directly impact both the completeness of logs and the performance +impact of processing +.Nm +events. +A system administrator may want to review these and modify them to obtain +the appropriate behavior in their environment. +.Bl -tag -width indent +.It Va hw.mca.enabled +(Only settable as a tunable.) +.Pp +If set to 0, the CPU is not configured to send +.Nm +messages to the kernel. +.Pp +Default is 1 (enabled). +.It Va hw.mca.log_corrected +(Settable as a tunable or sysctl.) +.Pp +If enabled, corrected messages are logged to console, syslog, the in-kernel +event cache, and the statistics array (subject to separate configuration +controlling those facilities). +If disabled, corrected messages are only logged to the in-kernel event +cache (subject to separate configuration controlling that facility). +.Pp +Default is 1 (enabled). +.It Va hw.mca.intel6h_HSD131 +(Only settable as a tunable.) +.Pp +This setting enables a workaround for benign corrected parity errors which +may be reported by certain Intel desktop Haswell CPUs. +(The name "HSD131" comes from the name of the Intel erratum report about this +issue.) +.Pp +Default is 0 (disabled). +.It Va hw.mca.amd10h_L1TP +(Only settable as a tunable.) +.Pp +Enable logging of level one TLB parity errors on certain AMD CPUs. +This option has no impact on other CPUs. +.Pp +Default is 1 (enabled). +.It Va hw.mca.erratum383 +(Only settable as a tunable.) +.Pp +This setting enables a workaround for Erratum 383 on AMD Family 10h CPUs. +The erratum changes the way pages are promoted to or demoted from being +super-pages. +On affected AMD CPUs, either +.Va hw.mca.amd10h_L1TP +or +.Va hw.mca.erratum383 +must be on. +If both are off, the system will dynamically enable +.Va hw.mca.erratum383 +at boot time. +.Pp +Default is 0 (disabled). +.It Va hw.mca.uselog +(Settable as a tunable or sysctl.) +.Pp +If enabled, the system will send messages about non-fatal +.Nm +events to syslog and not to the console. +If disabled, the system will send messages about non-fatal +.Nm +events to both syslog and the console. +Fatal events are always logged to the console. +.Pp +Default is false (disabled). +.It Va hw.mca.stats +(Read-only sysctl.) +.Pp +This returns an array of +.Va MCA_T_COUNT +uint64_t values. +The +.Vt "enum mca_stat_types" +definition in +.In x86/mca.h +provides the value of +.Va MCA_T_COUNT +and the index values for various event types. +.It Va hw.mca.log_interval +(Settable as a tunable or sysctl.) +.Pp +This sets the minimum time (in seconds) between logging correctible errors. +The rate limit is only applied after the system records a reasonable +number of errors of the same type. +The goal is to reduce the impact of the system seeing and attempting to log +a burst of similar errors, which can be expensive (especially when printed +to the console). +If this setting is 0, no rate limit is applied. +.Pp +Default is 0 (no rate limit). +.It Va hw.mca.cmc_throttle +(Settable as a tunable or sysctl. Only available if +.Xr apic 4 +support is enabled and the hardware supports CMC interrupt throttling.) +.Pp +This sets the maximum time (in seconds) to throttle CMC interrupts. +In normal operation, the system attempts to receive CMC interrupts as soon as +an event occurs. +However, if a high rate of events occurs in a short time, the system will +begin throttling the CMC interrupts. +While the events continue to occur at a high rate, the system will gradually +increase the throttling interval until it reaches the +.Va hw.mca.cmc_throttle +setting. +.Pp +Default is 60 seconds. +.It Va hw.mca.count +(Read-only sysctl.) +.Pp +This returns the current number of +.Nm +records in the in-kernel cache. +This can be used to determine how many records are available to read with the +.Va hw.mca.records +.Xr sysctl 8 +interface. +It can also be used to monitor the amount of memory used by the in-kernel +record cache. +.It Va hw.mca.maxcount +(Settable as a tunable or sysctl.) +.Pp +This setting controls the size and behavior of the in-kernel cache of +.Nm +records. +If the setting is -1, the in-kernel cache grows without bounds and contains a +complete record events since boot or the last time the +.Va hw.mca.maxcount +setting was changed. +If the setting is 0, the in-kernel cache is disabled. +If the setting is a positive integer, the in-kernel cache functions as a ring +buffer with the number of entries defined by the setting. +.Pp +Default is -1 (unlimited). +.It Va hw.mca.interval +(Settable as a tunable or sysctl.) +.Pp +This setting controls how often (in seconds) the kernel should proactively +scan for new +.Nm +events. +In many circumstances, the CPU will send an interrupt to signal new events. +However, there are cases where the periodic scan for events will discover +new events. +.Pp +Default is 300 seconds. +.It Va hw.mca.force_scan +(Settable only as a sysctl.) +.Pp +Setting this to any non-zero value will force an immediate scan for +.Nm +events. +Setting this to zero has no effect. +This is functionally a write-only setting. +The current value is always 0, even when a scan is running. +.Pp +Default is 0 (no scan requested). +.It Va hw.mca.records.n +(Read-only sysctl.) +.Pp +This is used to copy +.Nm +records from the in-kernel cache to a user space process. +The +.Va n +value in the +.Xr sysctl 8 +node is an integer index into the in-kernel cache. +(Or, put differently, the "new" value describes how many records the kernel +should skip to find the desired record.) +The return value is a +.Vt "struct mca_record" , +which is defined in +.In x86/mca.h . +.El +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Pa /boot/loader.conf . +The tunables all have corresponding +.Xr sysctl 8 +entries. +The tunables are listed above in the +.Sx SYSCTL VARIABLES +section. +.Sh COMPATIBILITY +.Nm +is only available on x86 systems. +.Sh SEE ALSO +.Xr loader.conf 5 , +.Xr sysctl 8 , +.Xr syslogd 8 +.Sh AUTHORS +The +.Nm +subsystem was originally written by +.An John Baldwin Aq Mt jhb@FreeBSD.org . +.Pp +This manual page was written by +.An Jonathan Looney Aq Mt jtl@FreeBSD.org . diff --git a/static/freebsd/man4/md.4 b/static/freebsd/man4/md.4 new file mode 100644 index 00000000..1da26ddd --- /dev/null +++ b/static/freebsd/man4/md.4 @@ -0,0 +1,168 @@ +.\" ---------------------------------------------------------------------------- +.\" "THE BEER-WARE LICENSE" (Revision 42): +.\" wrote this file. As long as you retain this notice you +.\" can do whatever you want with this stuff. If we meet some day, and you think +.\" this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp +.\" ---------------------------------------------------------------------------- +.\" +.Dd July 16, 2025 +.Dt MD 4 +.Os +.Sh NAME +.Nm md +.Nd memory disk +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device md" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +geom_md_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for four kinds of memory backed virtual disks: +.Bl -tag -width preload +.It Cm malloc +Backing store is allocated using +.Xr malloc 9 . +Only one malloc-bucket is used, which means that all +.Nm +devices with +.Cm malloc +backing must share the malloc-per-bucket-quota. +The exact size of this quota varies, in particular with the amount +of RAM in the +system. +The exact value can be determined with +.Xr vmstat 8 . +.It Cm preload +A module loaded by +.Xr loader 8 +with type +.Sq md_image +is used for backing store. +For backwards compatibility the type +.Sq mfs_root +is also recognized. +See the description of module loading directives in +.Xr loader.conf 5 +and note that the module name will either be an absolute path to the image file +or the name of a file in the +.Va module_path . +.Pp +If the kernel is created with option +.Dv MD_ROOT +the first preloaded image found will become the root file system. +.It Cm vnode +A regular file is used as backing store. +This allows for mounting ISO images without the tedious +detour over actual physical media. +.It Cm swap +Backing store is allocated from buffer memory. +Pages get pushed out to the swap when the system is under memory +pressure, otherwise they stay in the operating memory. +Using +.Cm swap +backing is generally preferable over +.Cm malloc +backing. +.El +.Pp +For more information, please see +.Xr mdconfig 8 . +.Sh EXAMPLES +To create a kernel with a ramdisk or MD file system, your kernel config +needs the following options: +.Bd -literal -offset indent +options MD_ROOT # MD is a potential root device +options MD_ROOT_READONLY # disallow mounting root writeable +options MD_ROOT_SIZE=8192 # 8MB ram disk +makeoptions MFS_IMAGE=/h/foo/ARM-MD +options ROOTDEVNAME=\\"ufs:md0\\" +.Ed +.Pp +The image in +.Pa /h/foo/ARM-MD +will be loaded as the initial image each boot. +To create the image to use, please follow the steps to create a file-backed +disk found in the +.Xr mdconfig 8 +man page. +Other tools will also create these images, such as NanoBSD. +.Sh ARM KERNEL OPTIONS +On the armv7 architecture, an MD_ROOT image larger than +approximately 55 MiB may require building a custom kernel using +several tuning options related to kernel memory usage. +.Bl -tag -width indent +.It Cd options LOCORE_MAP_MB= +This configures how much memory is mapped for the kernel during +the early initialization stages. +The value must be at least as large as the kernel plus all preloaded +modules, including the root image. +There is no downside to setting this value too large, as long +as it does not exceed the amount of physical memory. +The default is 64 MiB. +.It Cd options NKPT2PG= +This configures the number of kernel L2 page table pages to +preallocate during kernel initialization. +Each L2 page can map 4 MiB of kernel space. +The value must be large enough to map the kernel plus all preloaded +modules, including the root image. +The default value is 32, which is sufficient to map 128 MiB. +.It Cd options VM_KMEM_SIZE_SCALE= +This configures the amount of kernel virtual address (KVA) space to +dedicate to the kmem_arena map. +The scale value is the ratio of physical to virtual pages. +The default value of 3 allocates a page of KVA for each 3 pages +of physical ram in the system. +The kernel and modules, including the root image, also consume KVA. +The combination of a large root image and the default scaling +may preallocate so much KVA that there is not enough +remaining address space to allocate kernel stacks, IO buffers, +and other resources that are not part of kmem_arena. +Overallocating kmem_arena space is likely to manifest as failure to +launch userland processes with "cannot allocate kernel stack" messages. +Setting the scale value too high may result in kernel failure to allocate +memory because kmem_arena is too small, and the failure may require +significant runtime to manifest. +Empirically, a value of 5 works well for a 200 MiB root image on +a system with 2 GiB of physical ram. +.El +.Sh SEE ALSO +.Xr gpart 8 , +.Xr loader 8 , +.Xr mdconfig 8 , +.Xr mdmfs 8 , +.Xr newfs 8 , +.Xr vmstat 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 4.0 +as a cleaner replacement +for the MFS functionality previously used in +.Tn PicoBSD +and in the +.Fx +installation process. +.Pp +The +.Nm +driver did a hostile takeover of the +.Sy vn +driver in +.Fx 5.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org . diff --git a/static/freebsd/man4/mdio.4 b/static/freebsd/man4/mdio.4 new file mode 100644 index 00000000..b889dd6d --- /dev/null +++ b/static/freebsd/man4/mdio.4 @@ -0,0 +1,52 @@ +.\" Written by Landon Fuller for the FreeBSD Project. +.\" Based on the miibus(4) manual page written by Tom Rhodes. +.\" Please see the /usr/src/COPYRIGHT file for copyright information. +.\" +.Dd December 17, 2015 +.Dt MDIO 4 +.Os +.Sh NAME +.Nm mdio +.Nd IEEE 802.3 Management Data Input/Output interface +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device mdio" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides an interconnection between the Media Access Control (MAC) +sublayer and Physical Layer (PHY) entities' control and status registers, +as defined by the IEEE 802.3 Standard. +.Pp +The +.Nm +layer allows device drivers to share common support code for various +external PHY devices. +.Pp +.Tn MDIO +is one of two signal interfaces that comprise the +Media Independent Interface (MII) defined by the IEEE 802.3 +Standard. +The +.Xr miibus 4 +driver provides support for devices that require full +.Tn MII +support. +.Sh SEE ALSO +.Xr miibus 4 +.Sh STANDARDS +More information on +.Tn MDIO +can be found in the IEEE 802.3 Standard. +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 10.0 . +.Sh AUTHORS +The driver was written by +.An Stefan Bethke Aq Mt stb@lassitu.de . diff --git a/static/freebsd/man4/me.4 b/static/freebsd/man4/me.4 new file mode 100644 index 00000000..9c8795b5 --- /dev/null +++ b/static/freebsd/man4/me.4 @@ -0,0 +1,82 @@ +.\" Copyright (c) Andrey V. Elsukov +.\" 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 AUTHORS 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 AUTHORS 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 March 4, 2026 +.Dt ME 4 +.Os +.Sh NAME +.Nm me +.Nd encapsulating network device +.Sh SYNOPSIS +To compile the +driver into the kernel, place the following line in the kernel +configuration file: +.Bd -ragged -offset indent +.Cd "device me" +.Ed +.Pp +Alternatively, to load the +driver as a module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_me_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +network interface is a point-to-point pseudo device encapsulating datagrams +into IP. +These encapsulated datagrams are routed to a destination host, +where they are decapsulated and further routed to their final destination. +.Pp +.Nm +interfaces are dynamically created and destroyed with the +.Xr ifconfig 8 +.Cm create +and +.Cm destroy +subcommands. +.Pp +This driver corresponds to RFC 2004. +Datagrams are encapsulated into IP with a shorter encapsulation. +The original +IP header is modified and the modifications are inserted between the +so modified header and the original payload. +The protocol number 55 is used for outer header. +.Sh NOTES +For correct operation, the +.Nm +device needs a route to the decapsulating host that does not run over the tunnel, +as this would be a loop. +.Sh SEE ALSO +.Xr gif 4 , +.Xr gre 4 , +.Xr inet 4 , +.Xr ip 4 , +.Xr netintro 4 , +.Xr protocols 5 , +.Xr ifconfig 8 , +.Xr sysctl 8 +.Sh AUTHORS +.An Andrey V. Elsukov Aq Mt ae@FreeBSD.org diff --git a/static/freebsd/man4/mem.4 b/static/freebsd/man4/mem.4 new file mode 100644 index 00000000..595cb8a6 --- /dev/null +++ b/static/freebsd/man4/mem.4 @@ -0,0 +1,314 @@ +.\" Copyright (c) 1991 The Regents of the University of California. +.\" 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 March 24, 2024 +.Dt MEM 4 +.Os +.Sh NAME +.Nm mem , +.Nm kmem +.Nd memory files +.Sh SYNOPSIS +.Cd "device mem" +.Sh DESCRIPTION +The special file +.Pa /dev/mem +is an interface to the physical memory of the computer. +Byte offsets in this file are interpreted as physical memory addresses. +Reading and writing this file is equivalent to reading and writing +memory itself. +Only offsets within the bounds of +.Pa /dev/mem +are allowed. +.Pp +Kernel virtual memory is accessed through the interface +.Pa /dev/kmem +in the same manner as +.Pa /dev/mem . +Only kernel virtual addresses that are currently mapped to memory are allowed. +.Pp +On ISA the I/O memory space begins at physical address 0x000a0000 +and runs to 0x00100000. +The +per-process data +size +for the current process +is +.Dv UPAGES +long, and ends at virtual +address 0xf0000000. +.Sh IOCTL INTERFACE +.Ss Address Properties +The +.Dv MEM_EXTRACT_PADDR +ioctl can be used to look up the physical address and NUMA domain of a given +virtual address in the calling process' address space. +The request is described by +.Bd -literal +struct mem_extract { + uint64_t me_vaddr; /* input */ + uint64_t me_paddr; /* output */ + int me_domain; /* output */ + int me_state; /* output */ +}; +.Ed +.Pp +The ioctl returns an error if the address is not valid. +The information returned by +.Dv MEM_EXTRACT_PADDR +may be out of date by the time that the ioctl call returns. +Specifically, concurrent system calls, page faults, or system page reclamation +activity may have unmapped the virtual page or replaced the backing physical +page before the ioctl call returns. +Wired pages, e.g., those locked by +.Xr mlock 2 , +will not be reclaimed by the system. +.Pp +The +.Fa me_state +field provides information about the state of the virtual page: +.Bl -tag -width indent +.It Dv ME_STATE_INVALID +The virtual address is invalid. +.It Dv ME_STATE_VALID +The virtual address is valid but is not mapped at the time of the ioctl call. +.It Dv ME_STATE_MAPPED +The virtual address corresponds to a physical page mapping, and the +.Fa me_paddr +and +.Fa me_domain +fields are valid. +.El +.Ss Memory Ranges +.Pp +Several architectures allow attributes to be associated with ranges of physical +memory. +These attributes can be manipulated via +.Fn ioctl +calls performed on +.Pa /dev/mem . +Declarations and data types are to be found in +.In sys/memrange.h . +.Pp +The specific attributes, and number of programmable ranges may vary between +architectures. +The full set of supported attributes is: +.Bl -tag -width indent +.It Dv MDF_UNCACHEABLE +The region is not cached. +.It Dv MDF_WRITECOMBINE +Writes to the region may be combined or performed out of order. +.It Dv MDF_WRITETHROUGH +Writes to the region are committed synchronously. +.It Dv MDF_WRITEBACK +Writes to the region are committed asynchronously. +.It Dv MDF_WRITEPROTECT +The region cannot be written to. +.El +.Pp +Memory ranges are described by +.Bd -literal +struct mem_range_desc { + uint64_t mr_base; /* physical base address */ + uint64_t mr_len; /* physical length of region */ + int mr_flags; /* attributes of region */ + char mr_owner[8]; +}; +.Ed +.Pp +In addition to the region attributes listed above, the following flags +may also be set in the +.Fa mr_flags +field: +.Bl -tag -width indent +.It MDF_FIXBASE +The region's base address cannot be changed. +.It MDF_FIXLEN +The region's length cannot be changed. +.It MDF_FIRMWARE +The region is believed to have been established by the system firmware. +.It MDF_ACTIVE +The region is currently active. +.It MDF_BOGUS +We believe the region to be invalid or otherwise erroneous. +.It MDF_FIXACTIVE +The region cannot be disabled. +.It MDF_BUSY +The region is currently owned by another process and may not be +altered. +.El +.Pp +Operations are performed using +.Bd -literal +struct mem_range_op { + struct mem_range_desc *mo_desc; + int mo_arg[2]; +}; +.Ed +.Pp +The +.Dv MEMRANGE_GET +ioctl is used to retrieve current memory range attributes. +If +.Va mo_arg[0] +is set to 0, it will be updated with the total number of memory range +descriptors. +If greater than 0, the array at +.Va mo_desc +will be filled with a corresponding number of descriptor structures, +or the maximum, whichever is less. +.Pp +The +.Dv MEMRANGE_SET +ioctl is used to add, alter and remove memory range attributes. +A range +with the +.Dv MDF_FIXACTIVE +flag may not be removed; a range with the +.Dv MDF_BUSY +flag may not be removed or updated. +.Pp +.Va mo_arg[0] +should be set to +.Dv MEMRANGE_SET_UPDATE +to update an existing or establish a new range, or to +.Dv MEMRANGE_SET_REMOVE +to remove a range. +.Ss Live Kernel Dumps +.Pp +The +.Dv MEM_KERNELDUMP +ioctl will initiate a kernel dump against the running system, the contents of +which will be written to a process-owned file descriptor. +The resulting dump output will be in minidump format. +The request is described by +.Bd -literal +struct mem_livedump_arg { + int fd; /* input */ + int flags /* input */ + uint8_t compression /* input */ +}; +.Ed +.Pp +The +.Va fd +field is used to pass the file descriptor. +.Pp +The +.Va flags +field is currently unused and must be set to zero. +.Pp +The +.Va compression +field can be used to specify the desired compression to +be applied to the dump output. +The supported values are defined in +.In sys/kerneldump.h ; +that is, +.Dv KERNELDUMP_COMP_NONE , +.Dv KERNELDUMP_COMP_GZIP , +or +.Dv KERNELDUMP_COMP_ZSTD . +.Pp +Kernel dumps taken against the running system may have inconsistent kernel data +structures due to allocation, deallocation, or modification of memory +concurrent to the dump procedure. +Thus, the resulting core dump is not guaranteed to be usable. +A system under load is more likely to produce an inconsistent result. +Despite this, live kernel dumps can be useful for offline debugging of certain +types of kernel bugs, such as deadlocks, or in inspecting a particular part of +the system's state. +.Sh RETURN VALUES +.Ss MEM_EXTRACT_PADDR +The +.Dv MEM_EXTRACT_PADDR +ioctl always returns a value of zero. +.Ss MEMRANGE_GET/MEMRANGE_SET +.Bl -tag -width Er +.It Bq Er EOPNOTSUPP +Memory range operations are not supported on this architecture. +.It Bq Er ENXIO +No memory range descriptors are available (e.g., firmware has not enabled +any). +.It Bq Er EINVAL +The memory range supplied as an argument is invalid or overlaps another +range in a fashion not supported by this architecture. +.It Bq Er EBUSY +An attempt to remove or update a range failed because the range is busy. +.It Bq Er ENOSPC +An attempt to create a new range failed due to a shortage of hardware +resources (e.g., descriptor slots). +.It Bq Er ENOENT +An attempt to remove a range failed because no range matches the descriptor +base/length supplied. +.It Bq Er EPERM +An attempt to remove a range failed because the range is permanently +enabled. +.El +.Ss MEM_KERNELDUMP +.Bl -tag -width Er +.It Bq Er EOPNOTSUPP +Kernel minidumps are not supported on this architecture. +.It Bq Er EPERM +An attempt to begin the kernel dump failed because the calling thread lacks the +.It Bq Er EBADF +The supplied file descriptor was invalid, or does not have write permission. +.It Bq Er EBUSY +An attempt to begin the kernel dump failed because one is already in progress. +.It Bq Er EINVAL +An invalid or unsupported value was specified in +.Va flags . +.It Bq Er EINVAL +An invalid or unsupported compression type was specified. +.Dv PRIV_KMEM_READ +privilege. +.El +.Sh FILES +.Bl -tag -width /dev/kmem -compact +.It Pa /dev/mem +.It Pa /dev/kmem +.El +.Sh SEE ALSO +.Xr kvm 3 , +.Xr memcontrol 8 +.Sh HISTORY +The +.Pa /dev/mem +file appeared in +.At v1 +and +.Pa /dev/kmem +in +.At v5 . +The ioctl interface for memory range attributes was added in +.Fx 3.2 . +.Sh BUGS +Busy range attributes are not yet managed correctly. +.Pp +This device is required for all users of +.Xr kvm 3 +to operate. diff --git a/static/freebsd/man4/mfi.4 b/static/freebsd/man4/mfi.4 new file mode 100644 index 00000000..6b660c4c --- /dev/null +++ b/static/freebsd/man4/mfi.4 @@ -0,0 +1,155 @@ +.\" Copyright (c) 2006 Scott Long +.\" 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 April 19, 2023 +.Dt MFI 4 +.Os +.Sh NAME +.Nm mfi +.Nd "LSI MegaRAID SAS driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device pci" +.Cd "device mfi" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +mfi_load="YES" +.Ed +.Sh DESCRIPTION +This driver is for LSI's next generation PCI Express SAS RAID controllers. +Access to RAID arrays (logical disks) from this driver is provided via +.Pa /dev/mfid? +device nodes. +A simple management interface is also provided on a per-controller basis via +the +.Pa /dev/mfi? +device node. +.Pp +The +.Nm +name is derived from the phrase "MegaRAID Firmware Interface", which is +substantially different than the old "MegaRAID" interface and thus requires +a new driver. +Older SCSI and SATA MegaRAID cards are supported by +.Xr amr 4 +and will not work with this driver. +.Pp +Two sysctls are provided to tune the +.Nm +driver's behavior when a request is made to remove a mounted volume. +By default the driver will disallow any requests to remove a mounted volume. +If the sysctl +.Va dev.mfi.%d.delete_busy_volumes +is set to 1, +then the driver will allow mounted volumes to be removed. +.Pp +A tunable is provided to adjust the +.Nm +driver's behaviour when attaching to a card. +By default the driver will attach to all known cards with high probe priority. +If the tunable +.Va hw.mfi.mrsas_enable +is set to 1, +then the driver will reduce its probe priority to allow +.Xr mrsas 4 +to attach to the card instead of +.Nm . +.Pp +.Nm +does not provide ATA TRIM support. +Refer to +.Xr mrsas 4 +if TRIM support is required. +.Sh HARDWARE +The +.Nm +driver supports the following hardware: +.Pp +.Bl -bullet -compact +.It +LSI MegaRAID SAS 1078 +.It +LSI MegaRAID SAS 8408E +.It +LSI MegaRAID SAS 8480E +.It +LSI MegaRAID SAS 9240 +.It +LSI MegaRAID SAS 9260 +.It +Dell PERC5 +.It +Dell PERC6 +.It +Fujitsu RAID Controller SAS 6Gbit/s 1GB (D3116) +.It +IBM ServeRAID M1015 SAS/SATA +.It +IBM ServeRAID M1115 SAS/SATA +.It +IBM ServeRAID M5015 SAS/SATA +.It +IBM ServeRAID M5110 SAS/SATA +.It +IBM ServeRAID-MR10i +.It +Intel RAID Controller SRCSAS18E +.It +Intel RAID Controller SROMBSAS18E +.El +.Sh FILES +.Bl -tag -width ".Pa /dev/mfid?" -compact +.It Pa /dev/mfid? +array/logical disk interface +.It Pa /dev/mfi? +management interface +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "mfid%d: Unable to delete busy device" +An attempt was made to remove a mounted volume. +.El +.Sh SEE ALSO +.Xr amr 4 , +.Xr pci 4 , +.Xr mfiutil 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 6.1 . +.Sh AUTHORS +The +.Nm +driver and this manual page were written by +.An Scott Long Aq Mt scottl@FreeBSD.org . +.Sh BUGS +The driver does not support big-endian architectures at this time. diff --git a/static/freebsd/man4/mgb.4 b/static/freebsd/man4/mgb.4 new file mode 100644 index 00000000..0d26951d --- /dev/null +++ b/static/freebsd/man4/mgb.4 @@ -0,0 +1,84 @@ +.\" Copyright (c) 2019 The FreeBSD Foundation. +.\" +.\" 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 September 28, 2021 +.Dt MGB 4 +.Os +.Sh NAME +.Nm mgb +.Nd "Microchip LAN743x PCIe Gigabit Ethernet driver" +.Sh SYNOPSIS +To load the driver as a module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_mgb_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver is experimental, and has a number of caveats and limitations. +It is currently available only as a kernel module. +.Pp +The +.Nm +device driver provides support for PCIe Gigabit Ethernet adapters based on +Microchip's LAN7430 and LAN7431. +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports Microchip PCIe Gigabit Ethernet interfaces, including: +.Pp +.Bl -bullet -compact +.It +Microchip LAN7430 PCIe Gigabit Ethernet controller with PHY +.It +Microchip LAN7431 PCIe Gigabit Ethernet controller with RGMII interface +.El +.Sh SEE ALSO +.Xr arp 4 , +.Xr miibus 4 , +.Xr ifconfig 8 +.Sh CAVEATS +The driver does not yet implement support for many hardware features, +including: +.Bl -bullet -compact +.It +Multiple RX queue support +.It +RX and TX checksum offload +.It +Hardware VLAN tagging or untagging +.It +Multicast receive packet filtering +.It +Wake on LAN (WoL) +.It +LSO +.It +RSS +.El +.Pp +LAN7431 support is completely untested. diff --git a/static/freebsd/man4/miibus.4 b/static/freebsd/man4/miibus.4 new file mode 100644 index 00000000..9291d3d8 --- /dev/null +++ b/static/freebsd/man4/miibus.4 @@ -0,0 +1,177 @@ +.\" Written by Tom Rhodes for the FreeBSD Project. +.\" Please see the /usr/src/COPYRIGHT file for copyright information. +.\" +.\" This document takes information from the IEEE 802.3 Standard +.\" along with various comments from Peter Wemm, Robert Watson, and Bill Paul. +.\" Originally this file looked much like the NetBSD mii(4) manual page, but +.\" I doubt you would ever notice due to large differences. +.\" +.Dd December 26, 2020 +.Dt MIIBUS 4 +.Os +.Sh NAME +.Nm miibus +.Nd IEEE 802.3 Media Independent Interface network bus +.Sh SYNOPSIS +For most network interface cards (NIC): +.Cd "device miibus" +.Sh DESCRIPTION +The +.Nm +driver provides an interconnection between the Media Access Control (MAC) +sublayer, the Physical Layer entities (PHY), Station Management (STA) +entities, and the PHY Layer as defined by the IEEE 802.3 Standard. +.Pp +The +.Nm +layer allows network device drivers to share common support +code for various external PHY devices. +Most 10/100 network interface cards either use an MII transceiver +or have built-in transceivers that can be programmed using an MII +interface. +The +.Nm +driver currently handles all of the media detection, +selection, and reporting using the ifmedia interface. +A generic driver has been included for all PHYs that are not +handled by a specific driver, this is possible because all +10/100 PHYs implement the same general register set along with +their vendor specific register set. +.Pp +The following network device drivers use the +.Nm +interface: +.Pp +.Bl -tag -compact -width ".Xr fxp 4" +.It Xr ae 4 +Attansic/Atheros L2 Fast Ethernet +.It Xr age 4 +Attansic/Atheros L1 Gigabit Ethernet +.It Xr alc 4 +Atheros AR8131/AR8132 PCIe Ethernet +.It Xr ale 4 +Atheros AR8121/AR8113/AR8114 PCIe Ethernet +.It Xr aue 4 +ADMtek USB Ethernet +.It Xr axe 4 +ASIX Electronics AX88172 USB Ethernet +.It Xr axge 4 +ASIX Electronics AX88178A/AX88179 USB Ethernet +.It Xr bce 4 +Broadcom NetXtreme II Gigabit Ethernet +.It Xr bfe 4 +Broadcom BCM4401 Ethernet +.It Xr bge 4 +Broadcom BCM570xx Gigabit Ethernet +.It Xr cas 4 +Sun Cassini/Cassini+ and National Semiconductor DP83065 Saturn +.It Xr dc 4 +DEC/Intel 21143 and various workalikes +.It Xr ed 4 +NE[12]000, SMC Ultra, 3c503, DS8390 cards +.It Xr et 4 +Agere ET1310 Gigabit Ethernet +.It Xr fxp 4 +Intel EtherExpress PRO/100B +.It Xr gem 4 +Sun ERI, Sun GEM and Apple GMAC Ethernet +.It Xr jme 4 +JMicron JMC250 Gigabit/JMC260 Fast Ethernet +.It Xr lge 4 +Level 1 LXT1001 NetCellerator Gigabit Ethernet +.It Xr msk 4 +Marvell/SysKonnect Yukon II Gigabit Ethernet +.It Xr nfe 4 +NVIDIA nForce MCP Networking Adapter +.It Xr nge 4 +National Semiconductor DP83820/DP83821 Gigabit Ethernet +.It Xr re 4 +Realtek 8139C+/8169/8169S/8110S +.It Xr rl 4 +Realtek 8129/8139 +.It Xr rue 4 +Realtek RTL8150 USB To Fast Ethernet +.It Xr sge 4 +Silicon Integrated Systems SiS190/191 Ethernet +.It Xr sis 4 +Silicon Integrated Systems SiS 900/SiS 7016 +.It Xr sk 4 +SysKonnect SK-984x and SK-982x Gigabit Ethernet +.It Xr smsc 4 +SMSC LAN9xxx USB Fast Ethernet +.It Xr ste 4 +Sundance ST201 (D-Link DFE-550TX) +.It Xr stge 4 +Sundance/Tamarack TC9021 Gigabit Ethernet +.It Xr udav 4 +Davicom DM9601 USB Ethernet +.It Xr ure 4 +Realtek RTL8152 USB To Fast Ethernet +.It Xr vge 4 +VIA VT612x PCI Gigabit Ethernet +.It Xr vr 4 +VIA Rhine, Rhine II +.It Xr vte 4 +DM&P Vortex86 RDC R6040 Fast Ethernet +.It Xr xl 4 +3Com 3c90x +.El +.Sh COMPATIBILITY +The implementation of +.Nm +was originally intended to have similar API interfaces +to +.Bsx 3.0 +and +.Nx , +but as a result are not well behaved newbus device drivers. +.Sh SEE ALSO +.Xr ae 4 , +.Xr age 4 , +.Xr alc 4 , +.Xr ale 4 , +.Xr arp 4 , +.Xr aue 4 , +.Xr axe 4 , +.Xr axge 4 , +.Xr bce 4 , +.Xr bfe 4 , +.Xr bge 4 , +.Xr cas 4 , +.Xr dc 4 , +.Xr ed 4 , +.Xr et 4 , +.Xr fxp 4 , +.Xr gem 4 , +.Xr jme 4 , +.Xr lge 4 , +.Xr msk 4 , +.Xr netintro 4 , +.Xr nfe 4 , +.Xr nge 4 , +.Xr re 4 , +.Xr rgephy 4 , +.Xr rl 4 , +.Xr rue 4 , +.Xr sge 4 , +.Xr sis 4 , +.Xr sk 4 , +.Xr smsc 4 , +.Xr ste 4 , +.Xr stge 4 , +.Xr udav 4 , +.Xr ure 4 , +.Xr vge 4 , +.Xr vr 4 , +.Xr vte 4 , +.Xr xl 4 +.Sh STANDARDS +More information on MII can be found in the IEEE 802.3 Standard. +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 3.3 . +.Sh AUTHORS +This manual page was written by +.An Tom Rhodes Aq Mt trhodes@FreeBSD.org . diff --git a/static/freebsd/man4/mld.4 b/static/freebsd/man4/mld.4 new file mode 100644 index 00000000..539138d8 --- /dev/null +++ b/static/freebsd/man4/mld.4 @@ -0,0 +1,100 @@ +.\" +.\" Copyright (c) 2009 Bruce Simpson. +.\" +.\" 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. Neither the name of the project nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT 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 PROJECT OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 8, 2013 +.Dt MLD 4 +.Os +.Sh NAME +.Nm mld +.Nd Multicast Listener Discovery Protocol +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netinet/in.h +.In netinet/in_systm.h +.In netinet/ip6.h +.In netinet/icmp6.h +.In netinet6/mld6.h +.Ft int +.Fn socket AF_INET6 SOCK_RAW IPPROTO_ICMPV6 +.Sh DESCRIPTION +.Tn MLD +is a control plane protocol used by IPv6 hosts and routers to +propagate multicast group membership information. +Normally this protocol is not used directly, except by the kernel +itself, in response to multicast membership requests by user +applications. +Multicast routing protocol daemons may open a raw socket to directly +interact with +.Nm +and receive membership reports. +.Pp +As of +.Fx 8.0 , +MLD version 2 is implemented. +This adds support for Source-Specific Multicast (SSM), whereby +applications may communicate to upstream multicast routers that +they are only interested in receiving multicast streams from +particular sources. +The retransmission of state-change reports adds some robustness +to the protocol. +.\" +.Sh SYSCTL VARIABLES +.Bl -tag -width indent +.\" +.It net.inet6.mld.ifinfo +This opaque read-only variable exposes the per-link MLDv2 status to +.Xr ifmcstat 8 . +.\" +.It net.inet6.mld.gsrdelay +This variable specifies the time threshold, in seconds, for processing +Group-and-Source Specific Queries (GSR). +As GSR query processing requires maintaining state on the host, +it may cause memory to be allocated, and is therefore a potential +attack point for Denial-of-Service (DoS). +If more than one GSR query is received within this threshold, +it will be dropped, to mitigate the potential for DoS. +.\" +.It net.inet6.mld.v1enable +If this variable is non-zero, then MLDv1 membership queries (and host +reports) will be processed by this host, and backwards compatibility +will be enabled until the v1 'Older Version Querier Present' timer expires. +This sysctl is normally enabled by default. +.\" +.El +.Sh SEE ALSO +.Xr netstat 1 , +.Xr sourcefilter 3 , +.Xr icmp6 4 , +.Xr inet 4 , +.Xr multicast 4 , +.Xr ifmcstat 8 +.Sh HISTORY +The +.Nm +manual page appeared in +.Fx 8.0 . diff --git a/static/freebsd/man4/mlx.4 b/static/freebsd/man4/mlx.4 new file mode 100644 index 00000000..4b9ab707 --- /dev/null +++ b/static/freebsd/man4/mlx.4 @@ -0,0 +1,244 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2003 David O'Brien +.\" Copyright (c) 2000 Jeroen Ruigrok van der Werven +.\" Copyright (c) 2000 Michael Smith +.\" 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. 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 May 27, 2025 +.Dt MLX 4 +.Os +.Sh NAME +.Nm mlx +.Nd Mylex DAC-family Parallel SCSI RAID driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device pci" +.Cd "device mlx" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +mlx_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for Mylex DAC-family PCI to SCSI RAID controllers, +including versions relabeled by Digital/Compaq. +.Sh HARDWARE +The +.Nm +driver supports the following Parallel SCSI RAID controllers: +.Pp +.Bl -bullet -compact +.It +Mylex DAC960P (Wide Fast SCSI-2) +.It +Mylex DAC960PD / DEC KZPSC (Wide Fast SCSI-2) +.It +Mylex DAC960PDU (Ultra SCSI-3) +.It +Mylex DAC960PL (Wide Fast SCSI-2) +.It +Mylex DAC960PJ (Wide Ultra SCSI-3) +.It +Mylex DAC960PG (Wide Ultra SCSI-3) +.It +Mylex DAC960PU / DEC PZPAC (Wide Ultra SCSI-3) +.It +Mylex AcceleRAID 150 (DAC960PRL) (Wide Ultra2 SCSI) +.It +Mylex AcceleRAID 250 (DAC960PTL1) (Wide Ultra2 SCSI) +.It +Mylex eXtremeRAID 1100 (DAC1164P) (Wide Ultra2 SCSI) +.It +RAIDarray 230 controllers, aka the Ultra-SCSI DEC KZPAC-AA (1-ch, 4MB +cache), KZPAC-CA (3-ch, 4MB), KZPAC-CB (3-ch, 8MB cache) +.El +.Sh DIAGNOSTICS +.Ss Controller initialisation phase +.Bl -diag +.It mlx%d: controller initialisation in progress... +.It mlx%d: initialisation complete +.Pp +The controller firmware is performing/has completed initialisation. +.It mlx%d: physical drive %d:%d not responding +.Pp +The drive at channel:target is not responding; it may have failed or +been removed. +.It mlx%d: spinning up drives... +.Pp +Drive startup is in progress; this may take several minutes. +.It mlx%d: configuration checksum error +.Pp +The array configuration has become corrupted. +.It mlx%d: mirror race recovery in progress +.It mlx%d: mirror race on a critical system drive +.It mlx%d: mirror race recovery failed +.Pp +These error codes are undocumented. +.It mlx%d: physical drive %d:%d COD mismatch +.Pp +Configuration data on the drive at channel:target does not match the +rest of the array. +.It mlx%d: system drive installation aborted +.Pp +Errors occurred preventing one or more system drives from being configured. +.It mlx%d: new controller configuration found +.Pp +The controller has detected a configuration on disk which supersedes the +configuration in its nonvolatile memory. +It will reset and come up with the new configuration. +.It mlx%d: FATAL MEMORY PARITY ERROR +.Pp +Firmware detected a fatal memory error; the driver will not attempt to +attach to this controller. +.It mlx%d: unknown firmware initialisation error %x:%x:%x +.Pp +An unknown error occurred during initialisation; it will be ignored. +.El +.Ss Driver initialisation/shutdown phase: +.Bl -diag +.It mlx%d: can't allocate scatter/gather DMA tag +.It mlx%d: can't allocate buffer DMA tag +.It mlx%d: can't allocate s/g table +.It mlx%d: can't make initial s/g list mapping +.It mlx%d: can't make permanent s/g list mapping +.It mlx%d: can't allocate interrupt +.It mlx%d: can't set up interrupt +.Pp +A resource allocation error occurred while initialising the driver; +initialisation has failed and the driver will not attach to this +controller. +.It mlx%d: error fetching drive status +.Pp +The current status of all system drives could not be fetched; attachment +of system drives will be aborted. +.It mlx%d: device_add_child failed +.Pp +Creation of the system drive instances failed; attachment of one or more +system drives may have been aborted. +.It mlxd%d: detaching... +.Pp +The indicated system drive is being detached. +.It mlxd%d: still open, can't detach +.Pp +The indicated system drive is still open or mounted; +the controller cannot be detached. +.It mlx%d: flushing cache... +.Pp +The controller cache is being flushed prior to detach or shutdown. +.El +.Ss Operational diagnostics: +.Bl -diag +.It mlx%d: ENQUIRY failed - %s +.It mlx%d: ENQUIRY2 failed +.It mlx%d: ENQUIRY_OLD failed +.It mlx%d: FLUSH failed - %s +.It mlx%d: CHECK ASYNC failed - %s +.It mlx%d: REBUILD ASYNC failed - %s +.It mlx%d: command failed - %s +.Pp +The controller rejected a command for the reason given. +.It mlx%d: I/O beyond end of unit (%u,%d > %u) +.It mlx%d: I/O error - %s +.Pp +An I/O error was reported by the controller. +.It mlx%d: periodic enquiry failed - %s +.Pp +An attempt to poll the controller for status failed for the reason given. +.It mlx%d: mlx_periodic_enquiry: unknown command %x +.Pp +The periodic status poll has issued a command which has become corrupted. +.It mlxd%d: drive offline +.It mlxd%d: drive online +.It mlxd%d: drive critical +.Pp +The system disk indicated has changed state. +.It mlx%d: physical drive %d:%d reset +.It mlx%d: physical drive %d:%d killed %s +.It "mlx%d: physical drive %d:%d error log: sense = %d asc = %x asq = %x" +.It "mlx%d: info %4D csi %4D" +.Pp +The drive at channel:target has been reset, killed for the given reason, +or experienced a SCSI error. +.It mlx%d: unknown log message type %x +.It mlx%d: error reading message log - %s +.Pp +An error occurred while trying to read the controller's message log. +.It mlxd%d: consistency check started +.It mlx%d: consistency check completed +.Pp +A user-initiated consistency check has started/completed. +.It mlx%d: drive rebuild started for %d:%d +.It mlx%d: drive rebuild completed +.Pp +A user-initiated physical drive rebuild has started/completed. +.It mlx%d: background check/rebuild operation started +.It mlx%d: background check/rebuild operation completed +.Pp +An automatic system drive consistency check +or physical drive rebuild has started/completed. +.It mlx%d: channel %d pausing for %d seconds +.It mlx%d: channel %d resuming +.It mlx%d: pause command failed - %s +.It mlx%d: pause failed for channel %d +.It mlx%d: resume command failed - %s +.It mlx%d: resume failed for channel %d +.Pp +Controller/channel pause operation notification. +(Channel pause is not currently supported on any controller.) +.It mlx%d: controller wedged (not taking commands) +.Pp +The controller is not responding to attempts to submit new commands. +.It mlx%d: duplicate done event for slot %d +.It mlx%d: done event for nonbusy slot %d +.Pp +Corruption has occurred in either the controller's onboard list of commands +or in the driver. +.El +.Sh SEE ALSO +.Xr mlxcontrol 8 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Michael Smith Aq Mt msmith@FreeBSD.org . +.Pp +This manual page was written by +.An Jeroen Ruigrok van der Werven Aq Mt asmodai@FreeBSD.org +and +.An Michael Smith Aq Mt msmith@FreeBSD.org . +.Sh BUGS +The DEC KZPSC has insufficient flash ROM to hold any reasonably recent firmware. +This has caused problems for this driver. +.Pp +The driver does not yet support the version 6.x firmware as found in the +AcceleRAID 352 and eXtremeRAID 2000 and 3000 products. diff --git a/static/freebsd/man4/mlx4en.4 b/static/freebsd/man4/mlx4en.4 new file mode 100644 index 00000000..69d29045 --- /dev/null +++ b/static/freebsd/man4/mlx4en.4 @@ -0,0 +1,93 @@ +.\" Copyright (c) 2016 Mellanox Technologies +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS `AS IS' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd March 1, 2017 +.Dt MLX4EN 4 +.Os +.Sh NAME +.Nm mlx4en +.Nd "Mellanox ConnectX-3 10GbE/40GbE network adapter driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place these lines in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "options COMPAT_LINUXKPI" +.Cd "device mlx4" +.Cd "device mlx4en" +.Ed +.Pp +To load the driver as a module at run-time, +run this command as root: +.Bd -literal -offset indent +kldload mlx4en +.Ed +.Pp +To load the driver as a +module at boot time, place this line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +mlx4en_load="YES" +.Ed +.Sh DESCRIPTION +Mellanox ConnectX adapter cards with Virtual Protocol Interconnect +(VPI) provide the highest performing and most flexible interconnect +solution for Enterprise Data Centers, High-Performance Computing, and +Embedded environments. +Clustered data bases, parallelized applications, transactional +services and high-performance embedded I/O applications will achieve +significant performance improvements resulting in reduced completion +time and lower cost per operation. +.Sh HARDWARE +The +.Nm +driver supports the following network adapters: +.Pp +.Bl -bullet -compact +.It +Mellanox ConnectX-2 (ETH) +.It +Mellanox ConnectX-3 (ETH) +.El +.Sh SUPPORT +For general information and support, +go to the Mellanox support website at: +.Lk http://www.mellanox.com/ . +.Pp +If an issue is identified with this driver and a supported network adapter, +please email the specific information to +.Aq Mt freebsd-drivers@mellanox.com . +.Sh SEE ALSO +.Xr mlx4ib 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 9.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Mellanox Technologies . diff --git a/static/freebsd/man4/mlx4ib.4 b/static/freebsd/man4/mlx4ib.4 new file mode 100644 index 00000000..536b8cab --- /dev/null +++ b/static/freebsd/man4/mlx4ib.4 @@ -0,0 +1,93 @@ +.\" Copyright (c) 2016 Mellanox Technologies +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS `AS IS' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd March 1, 2017 +.Dt MLX4IB 4 +.Os +.Sh NAME +.Nm mlx4ib +.Nd "Mellanox ConnectX-3 10GbE/40GbE network adapter driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place these lines in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "options COMPAT_LINUXKPI" +.Cd "device mlx4" +.Cd "device mlx4ib" +.Ed +.Pp +To load the driver as a module at run-time, +run this command as root: +.Bd -literal -offset indent +kldload mlx4ib +.Ed +.Pp +To load the driver as a +module at boot time, place this line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +mlx4ib_load="YES" +.Ed +.Sh DESCRIPTION +Mellanox ConnectX adapter cards with Virtual Protocol Interconnect +(VPI) provide the highest performing and most flexible interconnect +solution for Enterprise Data Centers, High-Performance Computing, and +Embedded environments. +Clustered data bases, parallelized applications, transactional +services and high-performance embedded I/O applications will achieve +significant performance improvements resulting in reduced completion +time and lower cost per operation. +.Sh HARDWARE +The +.Nm +driver supports the following network adapters: +.Pp +.Bl -bullet -compact +.It +Mellanox ConnectX-2 (IB) +.It +Mellanox ConnectX-3 (IB) +.El +.Sh SUPPORT +For general information and support, +go to the Mellanox support website at: +.Lk http://www.mellanox.com/ . +.Pp +If an issue is identified with this driver and a supported network adapter, +please email the specific information to +.Aq Mt freebsd-drivers@mellanox.com . +.Sh SEE ALSO +.Xr mlx4en 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 9.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Mellanox Technologies . diff --git a/static/freebsd/man4/mlx5en.4 b/static/freebsd/man4/mlx5en.4 new file mode 100644 index 00000000..7d92e222 --- /dev/null +++ b/static/freebsd/man4/mlx5en.4 @@ -0,0 +1,132 @@ +.\" Copyright (c) 2015 Mellanox Technologies +.\" Copyright (c) 2021 NVIDIA corporation & affiliates +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS `AS IS' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd July 20, 2021 +.Dt MLX5EN 4 +.Os +.Sh NAME +.Nm mlx5en +.Nd "NVIDIA Mellanox ConnectX-4/5/6 [Dx/Ex/Lx] based 200Gb, 100Gb, 50Gb, 40Gb, 25Gb and 10Gb ethernet adapter driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "options COMPAT_LINUXKPI" +.Cd "options RATELIMIT" +.Cd "options KERN_TLS" +.Cd "device xz" +.Cd "device mlxfw" +.Cd "device firmware" +.Cd "device mlx5" +.Cd "device mlx5en" +.Ed +.Pp +To load the driver as a module at run-time, +run the following command as root: +.Bd -literal -offset indent +kldload mlx5en +.Ed +.Pp +To load the driver as a +module at boot time, place the following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +mlx5en_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for PCI Express Ethernet adapters based on +ConnectX-4/5/6 [Dx, Ex and Lx variants]. +The driver supports Jumbo Frames, Transmit and Receive checksum offload, +TCP segmentation offload (TSO), Large Receive Offload (LRO), +HW Large Receive Offload (HW LRO), VLAN tag insertion and extraction, +VLAN checksum offload, VLAN TSO, hardware rate limiting (TXRTLMT), +stateless VxLAN hardware offload for receive and transmit, +HW TLS offload for transmit, Receive Side Steering (RSS) and +.Xr numa 4 +awareness. +.Pp +The network interface name is +.Dv mce +which corresponds to a PCI function, +.Dv mlx_core , +where +.Dv +is a number starting at zero. +There is at most one network interface per PCI function. +.Pp +For further information and questions related to hardware +requirements, see +.Pa https://www.mellanox.com . +.Sh HARDWARE +The +.Nm +driver supports 200Gb, 100Gb, 50Gb, 40Gb, 25Gb and 10Gb ethernet adapters. +.Pp +.Bl -bullet -compact +.It +ConnectX-6 supports 10/20/25/40/50/56/100Gb/200Gb/s speeds. +.It +ConnectX-5 supports 10/20/25/40/50/56/100Gb/s speeds. +.It +ConnectX-4 supports 10/20/25/40/50/56/100Gb/s speeds. +.It +ConnectX-4 LX supports 10/25/40/50Gb/s speeds and reduced power consumption. +.El +.Sh CONFIGURATION +The +.Nm +network interface is configured using +.Xr ifconfig 8 +and the +.Xr sysctl 8 +tree at +.Dv dev.mce. . +All configurable entries are also tunables, and can be put directly into the +.Xr loader.conf 5 +for persistent configuration. +.Sh SUPPORT +For general information and support, +go to the NVIDIA Mellanox networking support website at: +.Pa https://www.mellanox.com . +.Pp +If an issue is identified with this driver using a supported adapter, +e-mail all the specific information related to the issue to +.Aq Mt nbu-freebsd-drivers@nvidia.com . +.Sh SEE ALSO +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 11.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An NVIDIA Mellanox networking . diff --git a/static/freebsd/man4/mlx5ib.4 b/static/freebsd/man4/mlx5ib.4 new file mode 100644 index 00000000..71d634b2 --- /dev/null +++ b/static/freebsd/man4/mlx5ib.4 @@ -0,0 +1,122 @@ +.\" Copyright (c) 2017 Mellanox Technologies +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS `AS IS' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd August 23, 2017 +.Dt MLX5IB 4 +.Os +.Sh NAME +.Nm mlx5ib +.Nd "Mellanox ConnectX-4 and ConnectX-4 LX based 100Gb, 50Gb, 40Gb, 25Gb and 10Gb network adapter driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place these lines in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "options COMPAT_LINUXKPI" +.Cd "device mlx5" +.Cd "device mlx5ib" +.Ed +.Pp +To load the driver as a module at run-time, +run this command as root: +.Bd -literal -offset indent +kldload mlx5ib +.Ed +.Pp +To load the driver as a +module at boot time, place this line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +mlx5ib_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for infiniband and Remote DMA over Converged Ethernet, +RoCE, for PCI Express network adapters based on ConnectX-4 and ConnectX-4 LX. +.br +For further hardware information and questions related to hardware +requirements, see +.Pa http://www.mellanox.com/ . +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports 100Gb, 50Gb, 40Gb, 25Gb and 10Gb network adapters. +ConnectX-4 supports: 10/20/25/40/50/56/100Gb/s speeds. +ConnectX-4 LX supports: 10/25/40/50Gb/s speeds (and reduced power consumption): +.Pp +.Bl -bullet -compact +.It +Mellanox MCX455A-ECAT +.It +Mellanox MCX456A-ECAT +.It +Mellanox MCX415A-CCAT +.It +Mellanox MCX416A-CCAT +.It +Mellanox MCX455A-FCAT +.It +Mellanox MCX456A-FCAT +.It +Mellanox MCX415A-BCAT +.It +Mellanox MCX416A-BCAT +.It +Mellanox MCX4131A-GCAT +.It +Mellanox MCX4131A-BCAT +.It +Mellanox MCX4121A-ACAT +.It +Mellanox MCX4111A-ACAT +.It +Mellanox MCX4121A-XCAT +.It +Mellanox MCX4111A-XCAT +.El +.Sh SUPPORT +For general information and support, +go to the Mellanox support website at: +.Pa http://www.mellanox.com/ . +.Pp +If an issue is identified with this driver with a supported adapter, +email all the specific information related to the issue to +.Aq Mt freebsd-drivers@mellanox.com . +.Sh SEE ALSO +.Xr mlx5en 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 12.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Mellanox Technologies . diff --git a/static/freebsd/man4/mlx5io.4 b/static/freebsd/man4/mlx5io.4 new file mode 100644 index 00000000..ebfbb41a --- /dev/null +++ b/static/freebsd/man4/mlx5io.4 @@ -0,0 +1,189 @@ +.\" +.\" Copyright (c) 2018, 2019 Mellanox Technologies +.\" 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 October 2, 2019 +.Dt mlx5io 4 +.Os +.Sh NAME +.Nm mlx5io +.Nd IOCTL interface to manage Connect-X 4/5/6 Mellanox network adapters +.Sh SYNOPSIS +.In dev/mlx5/mlx5io.h +.Sh DESCRIPTION +The +.Nm +interface is provided for management of the Connect-X4, 5 and 6 network adapters +in the aspects not covered by the generic network configuration, +mostly related to the PCIe attachment and internal card working. +Interface consists of the commands, which are passed by means of +.Xr ioctl 2 +on the file descriptor, opened from the +.Pa /dev/mlx5ctl +device node. +.Pp +The following commands are implemented: +.Bl -tag -width indent +.It Dv MLX5_FWDUMP_FORCE +Take the snapshot of the firmware registers state and store it in the +kernel buffer. +The buffer must be empty, in other words, no dumps should be written so +far, or existing dump cleared with the +.Dv MLX5_FWDUMP_RESET +command for the specified device. +The argument for the command should point to the +.Vt struct mlx5_tool_addr +structure, containing the PCIe bus address of the device. +.Bd -literal +struct mlx5_tool_addr { + uint32_t domain; + uint8_t bus; + uint8_t slot; + uint8_t func; +}; +.Ed +.It Dv MLX5_FWDUMP_RESET +Clear the stored firmware dump, preparing the kernel buffer for +the next dump. +The argument for the command should point to the +.Vt struct mlx5_tool_addr +structure, containing the PCIe bus address of the device. +.It Dv MLX5_FWDUMP_GET +Fetch the stored firmware dump into the user memory. +The argument to the command should point to the input/output +.Vt struct mlx5_fwdump_get +structure. +Its +.Dv devaddr +field specifies the address of the device, the +.Dv buf +fields points to the array of +.Vt struct mlx5_fwdump_reg +of records of the registers values, the size of the array is specified +in the +.Dv reg_cnt +field. +.Bd -literal +struct mlx5_fwdump_get { + struct mlx5_tool_addr devaddr; + struct mlx5_fwdump_reg *buf; + size_t reg_cnt; + size_t reg_filled; /* out */ +}; +.Ed +.Pp +On successful return, the +.Dv reg_filled +field reports the number of the +.Dv buf +array elements actually filled with the registers values. +If +.Dv buf +contains the +.Dv NULL +pointer, no registers are filled, but +.Dv reg_filled +still contains the number of registers that should be passed for +the complete dump. +.Pp +The +.Vt struct mlx5_fwdump_reg +element contains the address of the register in the field +.Dv addr , +and its value in the field +.Dv val . +.Bd -literal +struct mlx5_fwdump_reg { + uint32_t addr; + uint32_t val; +}; +.Ed +.It Dv MLX5_FW_UPDATE +Requests firmware update (flash) on the adapter specified by the +.Dv devaddr +using the firmware image in +.Dv MFA2 +format. +The argument for the ioctl command is the +.Vt struct mlx5_fw_update +with the following definition. +.Bd -literal +struct mlx5_fw_update { + struct mlx5_tool_addr devaddr; + void *img_fw_data; + size_t img_fw_data_len; +}; +.Ed +Image address in memory is passed in +.Dv img_fw_data , +the length of the image is specified in +.Dv img_fw_data_len +field. +.It Dv MLX5_FW_RESET +Requests PCIe link-level reset on the device. +The address of the device is specified by the +.Vt struct mlx5_tool_addr +structure, which should be passed as an argument. +.It Dv MLX5_EEPROM_GET +Fetch EEPROM information. +The argument to the command should point to the input/output +.Vt struct mlx5_eeprom_get +structure where, the +.Dv devaddr +field specifies the address of the device. +.Bd -literal +struct mlx5_eeprom_get { + struct mlx5_tool_addr devaddr; + size_t eeprom_info_page_valid; + uint32_t *eeprom_info_buf; + size_t eeprom_info_out_len; +}; +.Ed +.Pp +On successful return, the +.Dv eeprom_info_out_len +field reports the length of the EEPROM information. +.Dv eeprom_info_buf +field contains the actual EEPROM information. +.Dv eeprom_info_page_valid +field reports the third page validity. +.El +.Sh FILES +The +.Pa /dev/mlx5ctl +.Xr devfs 4 +node is used to pass commands to the driver. +.Sh RETURN VALUES +If successful, the IOCTL returns zero. +Otherwise, -1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh SEE ALSO +.Xr errno 2 , +.Xr ioctl 2 , +.Xr mlx5en 4 , +.Xr mlx5ib 4 , +.Xr mlx5tool 8 +and +.Xr pci 9 . diff --git a/static/freebsd/man4/mmc.4 b/static/freebsd/man4/mmc.4 new file mode 100644 index 00000000..394f7bb3 --- /dev/null +++ b/static/freebsd/man4/mmc.4 @@ -0,0 +1,56 @@ +.\" +.\" Copyright (c) 2007 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. 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 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 June 10, 2021 +.Dt MMC 4 +.Os +.Sh NAME +.Nm mmc +.Nd MultiMediaCard and SD Card bus driver +.Sh SYNOPSIS +.Cd device mmc +.Sh DESCRIPTION +The +.Nm +driver implements the MMC and SD Card bus. +The +.Nm +driver supports all MMC and SD bridges in the system. +All SD or MMC cards in the system attach to an instance of +.Nm . +The +.Nm +bus typically has only one slot, and only memory cards. +MultiMediaCards exist only in memory. +SD Cards exist as memory, I/O, or combination cards. +.Sh SEE ALSO +.Xr mmcsd 4 , +.Xr sdhci 4 +.Rs +.%T "SD Specifications, Part 1, Physical Layer, Simplified Specification" +.Re +.Rs +.%T "The MultiMediaCard System Specification" +.Re +.Sh BUGS +SDIO cards currently do not work. diff --git a/static/freebsd/man4/mmcsd.4 b/static/freebsd/man4/mmcsd.4 new file mode 100644 index 00000000..07d7e963 --- /dev/null +++ b/static/freebsd/man4/mmcsd.4 @@ -0,0 +1,51 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2007 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. 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 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 October 2, 2025 +.Dt MMCSD 4 +.Os +.Sh NAME +.Nm mmcsd +.Nd MMC and SD memory card driver +.Sh SYNOPSIS +.Cd device mmcsd +.Sh HARDWARE +The +.Nm +driver implements direct access block device for MMC and SD memory cards. +.Sh SEE ALSO +.Xr mmc 4 , +.Xr sdhci 4 +.Rs +.%T "SD Specifications, Part 1, Physical Layer, Simplified Specification" +.Re +.Rs +.%T "The MultiMediaCard System Specification" +.Re +.Sh HISTORY +The +.Nm +driver appeared in +.Fx 7.0 . diff --git a/static/freebsd/man4/mod_cc.4 b/static/freebsd/man4/mod_cc.4 new file mode 100644 index 00000000..f17c6100 --- /dev/null +++ b/static/freebsd/man4/mod_cc.4 @@ -0,0 +1,207 @@ +.\" +.\" Copyright (c) 2010-2011 The FreeBSD Foundation +.\" +.\" This documentation was written at the Centre for Advanced Internet +.\" Architectures, Swinburne University of Technology, Melbourne, Australia by +.\" David Hayes and Lawrence Stewart under sponsorship from the FreeBSD +.\" Foundation. +.\" +.\" 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 September 13, 2022 +.Dt MOD_CC 4 +.Os +.Sh NAME +.Nm mod_cc +.Nd Modular congestion control +.Sh DESCRIPTION +The modular congestion control framework allows the TCP implementation to +dynamically change the congestion control algorithm used by new and existing +connections. +Algorithms are identified by a unique +.Xr ascii 7 +name. +Algorithm modules can be compiled into the kernel or loaded as kernel modules +using the +.Xr kld 4 +facility. +.Pp +The default algorithm is CUBIC, and all connections use the default unless +explicitly overridden using the +.Dv TCP_CONGESTION +socket option (see +.Xr tcp 4 +for details). +The default can be changed using a +.Xr sysctl 3 +MIB variable detailed in the +.Sx MIB Variables +section below. +.Pp +Algorithm specific parameters can be set or queried using the +.Dv TCP_CCALGOOPT +socket option (see +.Xr tcp 4 +for details). +Callers must pass a pointer to an algorithm specific data, and specify +its size. +.Pp +Unloading a congestion control module will fail if it is used as a +default by any Vnet. +When unloading a module, the Vnet default is +used to switch a connection to an alternate congestion control. +Note that the new congestion control module may fail to initialize its +internal memory, if so it will fail the module unload. +If this occurs often times retrying the unload will succeed since the temporary +memory shortage as the new CC module malloc's memory, that prevented the +switch is often transient. +.Sh MIB Variables +The framework exposes the following variables in the +.Va net.inet.tcp.cc +branch of the +.Xr sysctl 3 +MIB: +.Bl -tag -width ".Va hystartplusplus.css_growth_div" +.It Va available +Read-only list of currently available congestion control algorithms by name. +.It Va algorithm +Returns the current default congestion control algorithm when read, and changes +the default when set. +When attempting to change the default algorithm, this variable should be set to +one of the names listed by the +.Va net.inet.tcp.cc.available +MIB variable. +.It Va abe +Enable support for RFC 8511, +which alters the window decrease factor applied to the congestion window in +response to an ECN congestion signal. +Refer to individual congestion control man pages to determine if they implement +support for ABE and for configuration details. +.It Va abe_frlossreduce +If non-zero, apply standard beta instead of ABE-beta during ECN-signalled +congestion recovery episodes if loss also needs to be repaired. +.It Va hystartplusplus.bblogs +This boolean controls if black box logging will be done for hystart++ events. +If set to zero (the default) no logging is performed. +If set to one then black box logs will be generated on all hystart++ events. +.It Va hystartplusplus.css_rounds +This value controls the number of rounds that CSS runs for. +The default value matches the current internet-draft of 5. +.It Va hystartplusplus.css_growth_div +This value controls the divisor applied to slowstart during CSS. +The default value matches the current internet-draft of 4. +.It Va hystartplusplus.n_rttsamples +This value controls how many rtt samples must be collected in each round for +hystart++ to be active. +The default value matches the current internet-draft of 8. +.It Va hystartplusplus.maxrtt_thresh +This value controls the maximum rtt variance clamp when considering if CSS is needed. +The default value matches the current internet-draft of 16000 (in microseconds). +For further explanation please see the internet-draft. +.It Va hystartplusplus.minrtt_thresh +This value controls the minimum rtt variance clamp when considering if CSS is needed. +The default value matches the current internet-draft of 4000 (in microseconds). +For further explanation please see the internet-draft. +.El +.Pp +Each congestion control module may also expose other MIB variables +to control their behaviour. +Note that both NewReno and CUBIC now support Hystart++ based on the version 3 of the internet-draft. +.Sh Kernel Configuration +All of the available congestion control modules may also be loaded +via kernel configuration options. +A kernel configuration is required to have at least one congestion control +algorithm built into it via kernel option and a system default specified. +Compilation of the kernel will fail if these two conditions are not met. +.Sh Kernel Configuration Options +The framework exposes the following kernel configuration options. +.Bl -tag -width ".Va CC_NEWRENO" +.It Va CC_NEWRENO +This directive loads the NewReno congestion control algorithm. +.It Va CC_CUBIC +This directive loads the CUBIC congestion control algorithm and is included +in GENERIC by default. +.It Va CC_VEGAS +This directive loads the vegas congestion control algorithm, note that +this algorithm also requires the TCP_HHOOK option as well. +.It Va CC_CDG +This directive loads the cdg congestion control algorithm, note that +this algorithm also requires the TCP_HHOOK option as well. +.It Va CC_DCTCP +This directive loads the dctcp congestion control algorithm. +.It Va CC_HD +This directive loads the hd congestion control algorithm, note that +this algorithm also requires the TCP_HHOOK option as well. +.It Va CC_CHD +This directive loads the chd congestion control algorithm, note that +this algorithm also requires the TCP_HHOOK option as well. +.It Va CC_HTCP +This directive loads the htcp congestion control algorithm. +.It Va CC_DEFAULT +This directive specifies the string that represents the name of the system default algorithm, the GENERIC kernel +defaults this to CUBIC. +.El +.Sh SEE ALSO +.Xr cc_cdg 4 , +.Xr cc_chd 4 , +.Xr cc_cubic 4 , +.Xr cc_dctcp 4 , +.Xr cc_hd 4 , +.Xr cc_htcp 4 , +.Xr cc_newreno 4 , +.Xr cc_vegas 4 , +.Xr tcp 4 , +.Xr config 5 , +.Xr config 8 , +.Xr mod_cc 9 +.Sh ACKNOWLEDGEMENTS +Development and testing of this software were made possible in part by grants +from the FreeBSD Foundation and Cisco University Research Program Fund at +Community Foundation Silicon Valley. +.Sh HISTORY +The +.Nm +modular congestion control framework first appeared in +.Fx 9.0 . +.Pp +The framework was first released in 2007 by James Healy and Lawrence Stewart +whilst working on the NewTCP research project at Swinburne University of +Technology's Centre for Advanced Internet Architectures, Melbourne, Australia, +which was made possible in part by a grant from the Cisco University Research +Program Fund at Community Foundation Silicon Valley. +More details are available at: +.Pp +http://caia.swin.edu.au/urp/newtcp/ +.Sh AUTHORS +.An -nosplit +The +.Nm +facility was written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org , +.An James Healy Aq Mt jimmy@deefa.com +and +.An David Hayes Aq Mt david.hayes@ieee.org . +.Pp +This manual page was written by +.An David Hayes Aq Mt david.hayes@ieee.org +and +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org . diff --git a/static/freebsd/man4/mos.4 b/static/freebsd/man4/mos.4 new file mode 100644 index 00000000..da17306b --- /dev/null +++ b/static/freebsd/man4/mos.4 @@ -0,0 +1,96 @@ +.\" +.\" Copyright (c) 2011 Rick van der Zwet +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd November 24, 2015 +.Dt MOS 4 +.Os +.Sh NAME +.Nm mos +.Nd Moschip MCS7730/MCS7830/MCS7832 USB Ethernet driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device uhci" +.Cd "device ohci" +.Cd "device ehci" +.Cd "device usb" +.Cd "device miibus" +.Cd "device uether" +.Cd "device mos" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_mos_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for USB Ethernet adapters based on the +Moschip MCS7730/MCS7830/MCS7832 chipset. +.Pp +The adapters that contain the Moschip MCS7730/MCS7830/MCS7832 chipset +will operate at 100Base-TX and full-duplex. +.Pp +The Moschip contains a 10/100 +Ethernet MAC with MII interface and is designed to work with both +Ethernet and HomePNA transceivers. +Although designed to interface with +100Mbps peripherals, this only works with USB 2.0. The existing USB 1.0 +standard specifies a maximum transfer speed of 12Mbps. +USB 1.0 Users should therefore not expect to actually achieve 100Mbps speeds +with these devices. +.Pp +The Moschip supports a 64-bit multicast hash table, single perfect +filter entry for the station address and promiscuous mode. +Packets are +received and transmitted over separate USB bulk transfer endpoints. +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +Adapters supported by the +.Nm +driver include: +.Pp +.Bl -bullet -compact +.It +Sitecom LN030 +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr ifconfig 8 +.Rs +.%T ADMtek AN986 data sheet +.%O http://www.moschip.com/data/products/MCS7830/Data%20Sheet_7830.pdf +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 8.2 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Rick van der Zwet info@rickvanderzwet.nl . diff --git a/static/freebsd/man4/mouse.4 b/static/freebsd/man4/mouse.4 new file mode 100644 index 00000000..affc7fb7 --- /dev/null +++ b/static/freebsd/man4/mouse.4 @@ -0,0 +1,376 @@ +.\" +.\" Copyright (c) 1997 +.\" Kazutaka YOKOTA +.\" 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 as +.\" the first lines of this file unmodified. +.\" 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 ``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 December 3, 1997 +.Dt MOUSE 4 +.Os +.Sh NAME +.Nm mouse +.Nd mouse and pointing device drivers +.Sh SYNOPSIS +.In sys/mouse.h +.Sh DESCRIPTION +The mouse drivers +.Xr psm 4 , +.Xr ums 4 +and +.Xr sysmouse 4 +provide user programs with movement and button state information of the mouse. +Currently there are specific device drivers for bus, InPort, PS/2, and USB mice. +The serial mouse is not directly supported by a dedicated driver, but +it is accessible via the serial device driver or via +.Xr moused 8 +and +.Xr sysmouse 4 . +.Pp +The user program simply opens a mouse device with a +.Xr open 2 +call and reads +mouse data from the device via +.Xr read 2 . +Movement and button states are usually encoded in fixed-length data packets. +Some mouse devices may send data in variable length of packets. +Actual protocol (data format) used by each driver differs widely. +.Pp +The mouse drivers may have ``non-blocking'' attribute which will make +the driver return immediately if mouse data is not available. +.Pp +Mouse device drivers often offer several levels of operation. +The current operation level can be examined and changed via +.Xr ioctl 2 +commands. +The level zero is the lowest level at which the driver offers the basic +service to user programs. +Most drivers provide horizontal and vertical movement of the mouse +and state of up to three buttons at this level. +At the level one, if supported by the driver, mouse data is encoded +in the standard format +.Dv MOUSE_PROTO_SYSMOUSE +as follows: +.Pp +.Bl -tag -width Byte_1 -compact +.It Byte 1 +.Bl -tag -width bit_7 -compact +.It bit 7 +Always one. +.It bit 6..3 +Always zero. +.It bit 2 +Left button status; cleared if pressed, otherwise set. +.It bit 1 +Middle button status; cleared if pressed, otherwise set. +Always one, +if the device does not have the middle button. +.It bit 0 +Right button status; cleared if pressed, otherwise set. +.El +.It Byte 2 +The first half of horizontal movement count in two's complement; +-128 through 127. +.It Byte 3 +The first half of vertical movement count in two's complement; +-128 through 127. +.It Byte 4 +The second half of the horizontal movement count in two's complement; +-128 through 127. +To obtain the full horizontal movement count, add +the byte 2 and 4. +.It Byte 5 +The second half of the vertical movement count in two's complement; +-128 through 127. +To obtain the full vertical movement count, add +the byte 3 and 5. +.It Byte 6 +The bit 7 is always zero. +The lower 7 bits encode the first half of +Z axis movement count in two's complement; -64 through 63. +.It Byte 7 +The bit 7 is always zero. +The lower 7 bits encode the second half of +the Z axis movement count in two's complement; -64 through 63. +To obtain the full Z axis movement count, add the byte 6 and 7. +.It Byte 8 +The bit 7 is always zero. +The bits 0 through 6 reflect the state +of the buttons 4 through 10. +If a button is pressed, the corresponding bit is cleared. +Otherwise +the bit is set. +.El +.Pp +The first 5 bytes of this format is compatible with the MouseSystems +format. +The additional 3 bytes have their MSBs always set to zero. +Thus, if the user program can interpret the MouseSystems data format and +tries to find the first byte of the format by detecting the bit pattern +10000xxxb, +it will discard the additional bytes, thus, be able to decode x, y +and states of 3 buttons correctly. +.Pp +Device drivers may offer operation levels higher than one. +Refer to manual pages of individual drivers for details. +.Sh IOCTLS +The following +.Xr ioctl 2 +commands are defined for the mouse drivers. +The degree of support +varies from one driver to another. +This section gives general +description of the commands. +Refer to manual pages of individual drivers for specific details. +.Pp +.Bl -tag -width MOUSE -compact +.It Dv MOUSE_GETLEVEL Ar int *level +.It Dv MOUSE_SETLEVEL Ar int *level +These commands manipulate the operation level of the mouse driver. +.Pp +.It Dv MOUSE_GETHWINFO Ar mousehw_t *hw +Returns the hardware information of the attached device in the following +Except for the +.Dv iftype +field, the device driver may not always fill the structure with correct +values. +Consult manual pages of individual drivers for details of support. +.Bd -literal +typedef struct mousehw { + int buttons; /* number of buttons */ + int iftype; /* I/F type */ + int type; /* mouse/track ball/pad... */ + int model; /* I/F dependent model ID */ + int hwid; /* I/F dependent hardware ID */ +} mousehw_t; +.Ed +.Pp +The +.Dv buttons +field holds the number of buttons detected by the driver. +The driver +may put an arbitrary value, such as two, in this field, if it cannot +determine the exact number. +.Pp +The +.Dv iftype +is the type of interface: +.Dv MOUSE_IF_SERIAL , +.Dv MOUSE_IF_BUS , +.Dv MOUSE_IF_INPORT , +.Dv MOUSE_IF_PS2 , +.Dv MOUSE_IF_USB , +.Dv MOUSE_IF_SYSMOUSE +or +.Dv MOUSE_IF_UNKNOWN . +.Pp +The +.Dv type +tells the device type: +.Dv MOUSE_MOUSE , +.Dv MOUSE_TRACKBALL , +.Dv MOUSE_STICK , +.Dv MOUSE_PAD , +or +.Dv MOUSE_UNKNOWN . +.Pp +The +.Dv model +may be +.Dv MOUSE_MODEL_GENERIC +or one of +.Dv MOUSE_MODEL_XXX +constants. +.Pp +The +.Dv hwid +is the ID value returned by the pointing device. +It +depend on the interface type; refer to the manual page of +specific mouse drivers for possible values. +.Pp +.It Dv MOUSE_GETMODE Ar mousemode_t *mode +The command reports the current operation parameters of the mouse driver. +.Bd -literal +typedef struct mousemode { + int protocol; /* MOUSE_PROTO_XXX */ + int rate; /* report rate (per sec) */ + int resolution; /* MOUSE_RES_XXX, -1 if unknown */ + int accelfactor; /* acceleration factor */ + int level; /* driver operation level */ + int packetsize; /* the length of the data packet */ + unsigned char syncmask[2]; /* sync. bits */ +} mousemode_t; +.Ed +.Pp +The +.Dv protocol +field tells the format in which the device status is returned +when the mouse data is read by the user program. +It is one of +.Dv MOUSE_PROTO_XXX +constants. +.Pp +The +.Dv rate +field is the status report rate (reports/sec) at which the device will send +movement reports to the host computer. +-1 if unknown or not applicable. +.Pp +The +.Dv resolution +field holds a value specifying resolution of the pointing device. +It is a positive value or one of +.Dv MOUSE_RES_XXX +constants. +.Pp +The +.Dv accelfactor +field holds a value to control acceleration feature. +It must be zero or greater. +If it is zero, acceleration is disabled. +.Pp +The +.Dv packetsize +field tells the length of the fixed-size data packet or the length +of the fixed part of the variable-length packet. +The size depends on the interface type, the device type and model, the +protocol and the operation level of the driver. +.Pp +The array +.Dv syncmask +holds a bit mask and pattern to detect the first byte of the +data packet. +.Dv syncmask[0] +is the bit mask to be ANDed with a byte. +If the result is equal to +.Dv syncmask[1] , +the byte is likely to be the first byte of the data packet. +Note that this method of detecting the first byte is not 100% reliable, +thus, should be taken only as an advisory measure. +.Pp +.It Dv MOUSE_SETMODE Ar mousemode_t *mode +The command changes the current operation parameters of the mouse driver +as specified in +.Ar mode . +Only +.Dv rate , +.Dv resolution , +.Dv level +and +.Dv accelfactor +may be modifiable. +Setting values in the other field does not generate +error and has no effect. +.Pp +If you do not want to change the current setting of a field, put -1 +there. +You may also put zero in +.Dv resolution +and +.Dv rate , +and the default value for the fields will be selected. +.Pp +.It Dv MOUSE_READDATA Ar mousedata_t *data +The command reads the raw data from the device. +.Bd -literal +typedef struct mousedata { + int len; /* # of data in the buffer */ + int buf[16]; /* data buffer */ +} mousedata_t; +.Ed +.Pp +The calling process must fill the +.Dv len +field with the number of bytes to be read into the buffer. +This command may not be supported by all drivers. +.Pp +.It Dv MOUSE_READSTATE Ar mousedata_t *state +The command reads the raw state data from the device. +It uses the same structure as above. +This command may not be supported by all drivers. +.Pp +.It Dv MOUSE_GETSTATUS Ar mousestatus_t *status +The command returns the current state of buttons and +movement counts in the following structure. +.Bd -literal +typedef struct mousestatus { + int flags; /* state change flags */ + int button; /* button status */ + int obutton; /* previous button status */ + int dx; /* x movement */ + int dy; /* y movement */ + int dz; /* z movement */ +} mousestatus_t; +.Ed +.Pp +The +.Dv button +and +.Dv obutton +fields hold the current and the previous state of the mouse buttons. +When a button is pressed, the corresponding bit is set. +The mouse drivers may support up to 31 buttons with the bit 0 through 31. +Few button bits are defined as +.Dv MOUSE_BUTTON1DOWN +through +.Dv MOUSE_BUTTON8DOWN . +The first three buttons correspond to left, middle and right buttons. +.Pp +If the state of the button has changed since the last +.Dv MOUSE_GETSTATUS +call, the corresponding bit in the +.Dv flags +field will be set. +If the mouse has moved since the last call, the +.Dv MOUSE_POSCHANGED +bit in the +.Dv flags +field will also be set. +.Pp +The other fields hold movement counts since the last +.Dv MOUSE_GETSTATUS +call. +The internal counters will be reset after every call to this +command. +.El +.Sh FILES +.Bl -tag -width /dev/sysmouseXX -compact +.It Pa /dev/cuau%d +serial ports +.It Pa /dev/psm%d +PS/2 mouse device +.It Pa /dev/sysmouse +virtual mouse device +.It Pa /dev/ums%d +USB mouse device +.El +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr psm 4 , +.Xr sysmouse 4 , +.Xr ums 4 , +.Xr moused 8 +.\".Sh HISTORY +.Sh AUTHORS +This manual page was written by +.An Kazutaka Yokota Aq Mt yokota@FreeBSD.org . diff --git a/static/freebsd/man4/mpi3mr.4 b/static/freebsd/man4/mpi3mr.4 new file mode 100644 index 00000000..f07ce13d --- /dev/null +++ b/static/freebsd/man4/mpi3mr.4 @@ -0,0 +1,81 @@ +.\" +.\" Copyright (c) 2023 Netflix, Inc +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" mpi3mr driver man page. +.\" +.Dd June 14, 2023 +.Dt MPI3MR 4 +.Os +.Sh NAME +.Nm mpi3mr +.Nd "Broadcom MPIMR 3.0 IT/IR 24Gb/s SAS Tri-Mode RAID PCIe 4.0 driver" +.Sh SYNOPSIS +.\" To compile this driver into the kernel, place these lines in the kernel +.\" configuration file: +.\" .Bd -ragged -offset indent +.\" .Cd "device pci" +.\" .Cd "device scbus" +.\" .Cd "device mpi3mr" +.\" .Ed +.\" .Pp +The driver can be loaded as a module at boot time by placing this line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +mpi3mr_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for Broadcom Ltd. MPIMR 3.0 IT/IR PCIe 4 controller. +.Sh HARDWARE +These controllers are supported by the +.Nm +driver: +.Pp +.Bl -bullet -compact +.It +Broadcom Ltd. SAS 4116 Tri-Mode RAID Adapter +.It +Broadcom Ltd. 9670W-16i 24G PCIe 4.0 Tri-Mode RAID Adapters +.It +Broadcom Ltd. 9670-24i 24G PCIe 4.0 Tri-Mode RAID Adapters +.It +Broadcom Ltd. 9660-16i 24G PCIe 4.0 Tri-Mode RAID Adapters +.It +Broadcom Ltd. 9620-16i 24G PCIe 4.0 Tri-Mode RAID Adapters +.It +Broadcom Ltd. 9600-24i 24G PCIe 4.0 Tri-Mode RAID Adapters +.It +Broadcom Ltd. 9600-16i 24G PCIe 4.0 Tri-Mode RAID Adapters +.It +Broadcom Ltd. 9600W-16e 24G PCIe 4.0 Tri-Mode RAID Adapters +.It +Broadcom Ltd. 9600-16e 24G PCIe 4.0 Tri-Mode RAID Adapters +.It +Broadcom Ltd. 9600-8i8e 24G PCIe 4.0 Tri-Mode RAID Adapters +.El +.Sh SEE ALSO +.Xr cam 4 , +.Xr cd 4 , +.Xr ch 4 , +.Xr da 4 , +.Xr mpr 4 , +.Xr pci 4 , +.Xr sa 4 , +.Xr scsi 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 14.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Sumit Saxena Aq Mt sumit.saxena@broadcom.com , +and +.An Chandrakanth Patil Aq Mt chandrakanth.patil@broadcom.com . +This manual page was written by +.An Warner Losh Aq Mt imp@FreeBSD.org . diff --git a/static/freebsd/man4/mpr.4 b/static/freebsd/man4/mpr.4 new file mode 100644 index 00000000..a88b99ae --- /dev/null +++ b/static/freebsd/man4/mpr.4 @@ -0,0 +1,415 @@ +.\" +.\" Copyright (c) 2010 Spectra Logic Corporation +.\" Copyright (c) 2014 LSI Corp +.\" Copyright (c) 2015-2017 Avago Technologies +.\" Copyright (c) 2015-2022 Broadcom Ltd. +.\" 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, +.\" without modification. +.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer +.\" substantially similar to the "NO WARRANTY" disclaimer below +.\" ("Disclaimer") and any redistribution must be conditioned upon +.\" including a substantially similar Disclaimer requirement for further +.\" binary redistribution. +.\" +.\" NO WARRANTY +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR 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 DAMAGES. +.\" +.\" mpr driver man page. +.\" +.\" Author: Ken Merry +.\" Author: Stephen McConnell +.\" +.\" $Id$ +.\" +.Dd September 28, 2025 +.Dt MPR 4 +.Os +.Sh NAME +.Nm mpr +.Nd "LSI Fusion-MPT 3/3.5 IT/IR 12Gb/s Serial Attached SCSI/SATA/PCIe driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place these lines in the kernel +configuration file: +.Bd -ragged -offset indent +.Cd "device pci" +.Cd "device scbus" +.Cd "device mpr" +.Ed +.Pp +The driver can be loaded as a module at boot time by placing this line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +mpr_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for Broadcom Ltd./Avago Tech (LSI) +Fusion-MPT 3/3.5 IT/IR +.Tn SAS/PCIe +controllers. +.Sh HARDWARE +The +.Nm +driver supports the following SATA/SAS/NVMe RAID controllers: +.Pp +.Bl -bullet -compact +.It +Broadcom Ltd./Avago Tech (LSI) SAS 3004 (4 Port SAS) +.It +Broadcom Ltd./Avago Tech (LSI) SAS 3008 (8 Port SAS) +.It +Broadcom Ltd./Avago Tech (LSI) SAS 3108 (8 Port SAS) +.It +Broadcom Ltd./Avago Tech (LSI) SAS 3216 (16 Port SAS) +.It +Broadcom Ltd./Avago Tech (LSI) SAS 3224 (24 Port SAS) +.It +Broadcom Ltd./Avago Tech (LSI) SAS 3316 (16 Port SAS) +.It +Broadcom Ltd./Avago Tech (LSI) SAS 3324 (24 Port SAS) +.It +Broadcom Ltd./Avago Tech (LSI) SAS 3408 (8 Port SAS/PCIe) +.It +Broadcom Ltd./Avago Tech (LSI) SAS 3416 (16 Port SAS/PCIe) +.It +Broadcom Ltd./Avago Tech (LSI) SAS 3508 (8 Port SAS/PCIe) +.It +Broadcom Ltd./Avago Tech (LSI) SAS 3516 (16 Port SAS/PCIe) +.It +Broadcom Ltd./Avago Tech (LSI) SAS 3616 (16 Port SAS/PCIe) +.It +Broadcom Ltd./Avago Tech (LSI) SAS 3708 (8 Port SAS/PCIe) +.It +Broadcom Ltd./Avago Tech (LSI) SAS 3716 (16 Port SAS/PCIe) +.It +Broadcom Ltd./Avago Tech (LSI) SAS 3808 (8 Port SAS/PCIe) +.It +Broadcom Ltd./Avago Tech (LSI) SAS 3816 (16 Port SAS/PCIe) +.It +Broadcom Ltd./Avago Tech (LSI) SAS 3916 (16 Port SAS/PCIe) +.El +.Sh CONFIGURATION +In all tunable descriptions below, X represents the adapter number. +.Pp +To disable MSI interrupts for all +.Nm +driver instances, set this tunable value in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hw.mpr.disable_msi=1 +.Ed +.Pp +To disable MSI interrupts for a specific +.Nm +driver instance, set this tunable value in +.Xr loader.conf 5 : +.Bd -literal -offset indent +dev.mpr.X.disable_msi=1 +.Ed +.Pp +To disable MSI-X interrupts for all +.Nm +driver instances, set this tunable value in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hw.mpr.disable_msix=1 +.Ed +.Pp +To disable MSI-X interrupts for a specific +.Nm +driver instance, set this tunable value in +.Xr loader.conf 5 : +.Bd -literal -offset indent +dev.mpr.X.disable_msix=1 +.Ed +.Pp +To set the maximum number of DMA chains allocated for all adapters, set +this tunable in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hw.mpr.max_chains=NNNN +.Ed +.Pp +To set the maximum number of DMA chains allocated for a specific adapter, +set this tunable in +.Xr loader.conf 5 : +.Bd -literal -offset indent +dev.mpr.X.max_chains=NNNN +.Ed +.Pp +The default max_chains value is 16384. +.Pp +The current number of free chain frames is stored in the +dev.mpr.X.chain_free +.Xr sysctl 8 +variable. +.Pp +The lowest number of free chain frames seen since boot is stored in the +dev.mpr.X.chain_free_lowwater +.Xr sysctl 8 +variable. +.Pp +The number of times that chain frame allocations have failed since boot is +stored in the +dev.mpr.X.chain_alloc_fail +.Xr sysctl 8 +variable. +This can be used to determine whether the max_chains tunable should be +increased to help performance. +.Pp +The current number of active I/O commands is shown in the +dev.mpr.X.io_cmds_active +.Xr sysctl 8 +variable. +.Pp +The current number of free PRP pages is stored in the +dev.mpr.X.prp_pages_free +.Xr sysctl 8 +variable. +PRP pages are used by NVMe devices for I/O transfers, much like Scatter/Gather +lists. +.Pp +The lowest number of free PRP pages seen since boot is stored in the +dev.mpr.X.prp_pages_free_lowwater +.Xr sysctl 8 +variable. +.Pp +The number of times that PRP page allocations have failed since boot is +stored in the +dev.mpr.X.prp_page_alloc_fail +.Xr sysctl 8 +variable. +.Pp +To set the maximum number of pages that will be used per I/O for all adapters, +set this tunable in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hw.mpr.max_io_pages=NNNN +.Ed +.Pp +To set the maximum number of pages that will be used per I/O for a specific +adapter, set this tunable in +.Xr loader.conf 5 : +.Bd -literal -offset indent +dev.mpr.X.max_io_pages=NNNN +.Ed +.Pp +The default max_io_pages value is -1, meaning that the maximum I/O size that +will be used per I/O will be calculated using the IOCFacts values stored in +the controller. +The lowest value that the driver will use for max_io_pages is 1, otherwise +IOCFacts will be used to calculate the maximum I/O size. +The smaller I/O size calculated from either max_io_pages or IOCFacts will be the +maximum I/O size used by the driver. +.Pp +The highest number of active I/O commands seen since boot is stored in the +dev.mpr.X.io_cmds_highwater +.Xr sysctl 8 +variable. +.Pp +Devices can be excluded from +.Nm +control for all adapters by setting this tunable in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hw.mpr.exclude_ids=Y +.Ed +.Pp +Y represents the target ID of the device. +If more than one device is to be excluded, target IDs are separated by commas. +.Pp +Devices can be excluded from +.Nm +control for a specific adapter by setting this tunable in +.Xr loader.conf 5 : +.Bd -literal -offset indent +dev.mpr.X.exclude_ids=Y +.Ed +.Pp +Y represents the target ID of the device. +If more than one device is to be excluded, target IDs are separated by commas. +.Pp +The adapter can issue the +.Sy StartStopUnit +SCSI command to SATA direct-access devices during shutdown. +This allows the device to quiesce powering down. +To control this feature for all adapters, set the +.Bd -literal -offset indent +hw.mpr.enable_ssu +.Ed +.Pp +tunable in +.Xr loader.conf 5 +to one of these values: +.Bl -tag -width 6n -offset indent +.It 0 +Do not send SSU to either HDDs or SSDs. +.It 1 +Send SSU to SSDs, but not to HDDs. +This is the default value. +.It 2 +Send SSU to HDDs, but not to SSDs. +.It 3 +Send SSU to both HDDs and SSDs. +.El +.Pp +To control this feature for a specific adapter, set this tunable value in +.Xr loader.conf 5 : +.Bd -literal -offset indent +dev.mpr.X.enable_ssu +.Ed +.Pp +The same set of values are valid as when setting this tunable for all adapters. +.Pp +SATA disks that take several seconds to spin up and fail the SATA Identify +command might not be discovered by the driver. +This problem can sometimes be overcome by increasing the value of the spinup +wait time in +.Xr loader.conf 5 +with the +.Bd -literal -offset indent +hw.mpr.spinup_wait_time=NNNN +.Ed +.Pp +tunable. +NNNN represents the number of seconds to wait for SATA devices to spin up when +the device fails the initial SATA Identify command. +.Pp +Spinup wait times can be set for specific adapters in +.Xr loader.conf 5 : +with the +.Bd -literal -offset indent +dev.mpr.X.spinup_wait_time=NNNN +.Ed +.Pp +tunable. +NNNN is the number of seconds to wait for SATA devices to spin up when they fail +the initial SATA Identify command. +.Pp +The driver can map devices discovered by the adapter so that target IDs +corresponding to a specific device persist across resets and reboots. +In some cases it is possible for devices to lose their mapped IDs due to +unexpected behavior from certain hardware, such as some types of enclosures. +To overcome this problem, a tunable is provided that will force the driver to +map devices using the Phy number associated with the device. +This feature is not recommended if the topology includes multiple +enclosures/expanders. +If multiple enclosures/expanders are present in the topology, Phy numbers are +repeated, causing all devices at these Phy numbers except the first device to +fail enumeration. +To control this feature for all adapters, set the +.Bd -literal -offset indent +hw.mpr.use_phy_num +.Ed +.Pp +tunable in +.Xr loader.conf 5 +to one of these values: +.Bl -tag -width 6n -offset indent +.It -1 +Only use Phy numbers to map devices and bypass the driver's mapping logic. +.It 0 +Never use Phy numbers to map devices. +.It 1 +Use Phy numbers to map devices, but only if the driver's mapping logic fails +to map the device that is being enumerated. +This is the default value. +.El +.Pp +To control this feature for a specific adapter, set this tunable value in +.Xr loader.conf 5 : +.Bd -literal -offset indent +dev.mpr.X.use_phy_num +.Ed +.Pp +The same set of values are valid as when setting this tunable for all adapters. +.Sh DEBUGGING +Driver diagnostic printing is controlled in +.Xr loader.conf 5 +by using the global +.Va hw.mpr.debug_level +and per-device +.Va dev.mpr.X.debug_level +tunables. +One can alter the debug level for any adapter at run-time using the +.Xr sysctl 8 +variable +.Va dev.mpr.X.debug_level . +.Pp +All +.Va debug_level +variables can be named by either an integer value or a text string. +Multiple values can be specified together by either ORing the +integer values or by providing a comma-separated list of names. +A text string prefixed by +.Qq + +adds the specified debug levels to the existing set, while the prefix +.Qq - +removes them from the existing set. +The current +.Va debug_level +status is reported in both formats for convenience. +The following levels are available: +.Bl -column "FlagXX" "NameXXXX" "Description" -offset indent +.It Em Flag Ta Em Name Ta Em Description +.It 0x0001 Ta info Ta Basic information (enabled by default) +.It 0x0002 Ta fault Ta Driver faults (enabled by default) +.It 0x0004 Ta event Ta Controller events +.It 0x0008 Ta log Ta Logging data from controller +.It 0x0010 Ta recovery Ta Tracing of recovery operations +.It 0x0020 Ta error Ta Parameter errors and programming bugs +.It 0x0040 Ta init Ta System initialization operations +.It 0x0080 Ta xinfo Ta More detailed information +.It 0x0100 Ta user Ta Tracing of user-generated commands (IOCTL) +.It 0x0200 Ta mapping Ta Tracing of device mapping +.It 0x0400 Ta trace Ta Tracing through driver functions +.El +.Sh SEE ALSO +.Xr cam 4 , +.Xr cd 4 , +.Xr ch 4 , +.Xr da 4 , +.Xr mps 4 , +.Xr mpt 4 , +.Xr pci 4 , +.Xr sa 4 , +.Xr scsi 4 , +.Xr targ 4 , +.Xr loader.conf 5 , +.Xr mprutil 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 9.3 . +.Sh AUTHORS +The +.Nm +driver was originally written by +.An -nosplit +.An Scott Long Aq Mt scottl@FreeBSD.org . +It has been improved and tested by LSI Corporation, +Avago Technologies (formerly LSI), and Broadcom Ltd. (formerly Avago). +.Pp +This manual page was written by +.An Ken Merry Aq Mt ken@FreeBSD.org +with additional input from +.An Stephen McConnell Aq Mt slm@FreeBSD.org . diff --git a/static/freebsd/man4/mps.4 b/static/freebsd/man4/mps.4 new file mode 100644 index 00000000..5bcb55a5 --- /dev/null +++ b/static/freebsd/man4/mps.4 @@ -0,0 +1,385 @@ +.\" +.\" Copyright (c) 2010 Spectra Logic Corporation +.\" Copyright (c) 2014 LSI Corp +.\" Copyright (c) 2015-2017 Avago Technologies +.\" Copyright (c) 2015-2017 Broadcom Ltd. +.\" 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, +.\" without modification. +.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer +.\" substantially similar to the "NO WARRANTY" disclaimer below +.\" ("Disclaimer") and any redistribution must be conditioned upon +.\" including a substantially similar Disclaimer requirement for further +.\" binary redistribution. +.\" +.\" NO WARRANTY +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR 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 DAMAGES. +.\" +.\" mps driver man page. +.\" +.\" Author: Ken Merry +.\" Author: Stephen McConnell +.\" +.\" $Id: //depot/SpectraBSD/head/share/man/man4/mps.4#6 $ +.\" +.Dd June 1, 2019 +.Dt MPS 4 +.Os +.Sh NAME +.Nm mps +.Nd "LSI Fusion-MPT 2 IT/IR 6Gb/s Serial Attached SCSI/SATA driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place these lines in the kernel +configuration file: +.Bd -ragged -offset indent +.Cd "device pci" +.Cd "device scbus" +.Cd "device mps" +.Ed +.Pp +The driver can be loaded as a module at boot time by placing this line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +mps_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for Broadcom Ltd./Avago Tech (LSI) +Fusion-MPT 2 IT/IR +.Tn SAS +controllers and WarpDrive solid state storage cards. +.Sh HARDWARE +These controllers are supported by the +.Nm +driver: +.Pp +.Bl -bullet -compact +.It +Broadcom Ltd./Avago Tech (LSI) SAS 2004 (4 Port SAS) +.It +Broadcom Ltd./Avago Tech (LSI) SAS 2008 (8 Port SAS) +.It +Broadcom Ltd./Avago Tech (LSI) SAS 2108 (8 Port SAS) +.It +Broadcom Ltd./Avago Tech (LSI) SAS 2116 (16 Port SAS) +.It +Broadcom Ltd./Avago Tech (LSI) SAS 2208 (8 Port SAS) +.It +Broadcom Ltd./Avago Tech (LSI) SAS 2308 (8 Port SAS) +.It +Broadcom Ltd./Avago Tech (LSI) SSS6200 Solid State Storage +.It +Intel Integrated RAID Module RMS25JB040 +.It +Intel Integrated RAID Module RMS25JB080 +.It +Intel Integrated RAID Module RMS25KB040 +.It +Intel Integrated RAID Module RMS25KB080 +.El +.Sh CONFIGURATION +In all tunable descriptions below, X represents the adapter number. +.Pp +To disable MSI interrupts for all +.Nm +driver instances, set this tunable value in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hw.mps.disable_msi=1 +.Ed +.Pp +To disable MSI interrupts for a specific +.Nm +driver instance, set this tunable value in +.Xr loader.conf 5 : +.Bd -literal -offset indent +dev.mps.X.disable_msi=1 +.Ed +.Pp +To disable MSI-X interrupts for all +.Nm +driver instances, set this tunable value in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hw.mps.disable_msix=1 +.Ed +.Pp +To disable MSI-X interrupts for a specific +.Nm +driver instance, set this tunable value in +.Xr loader.conf 5 : +.Bd -literal -offset indent +dev.mps.X.disable_msix=1 +.Ed +.Pp +To set the maximum number of DMA chains allocated for all adapters, set this +tunable in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hw.mps.max_chains=NNNN +.Ed +.Pp +To set the maximum number of DMA chains allocated for a specific adapter, +set this tunable in +.Xr loader.conf 5 : +.Bd -literal -offset indent +dev.mps.X.max_chains=NNNN +.Ed +.Pp +The default max_chains value is 16384. +.Pp +The current number of free chain frames is stored in the +dev.mps.X.chain_free +.Xr sysctl 8 +variable. +.Pp +The lowest number of free chain frames seen since boot is stored in the +dev.mps.X.chain_free_lowwater +.Xr sysctl 8 +variable. +.Pp +The number of times that chain frame allocations have failed since boot is +stored in the +dev.mps.X.chain_alloc_fail +.Xr sysctl 8 +variable. +This can be used to determine whether the max_chains tunable should be +increased to help performance. +.Pp +The current number of active I/O commands is shown in the +dev.mps.X.io_cmds_active +.Xr sysctl 8 +variable. +.Pp +To set the maximum number of pages that will be used per I/O for all adapters, +set this tunable in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hw.mps.max_io_pages=NNNN +.Ed +.Pp +To set the maximum number of pages that will be used per I/O for a specific +adapter, set this tunable in +.Xr loader.conf 5 : +.Bd -literal -offset indent +dev.mps.X.max_io_pages=NNNN +.Ed +.Pp +The default max_io_pages value is -1, meaning that the maximum I/O size that +will be used per I/O will be calculated using the IOCFacts values stored in +the controller. +The lowest value that the driver will use for max_io_pages is 1, otherwise +IOCFacts will be used to calculate the maximum I/O size. +The smaller I/O size calculated from either max_io_pages or IOCFacts will be the +maximum I/O size used by the driver. +.Pp +The highest number of active I/O commands seen since boot is stored in the +dev.mps.X.io_cmds_highwater +.Xr sysctl 8 +variable. +.Pp +Devices can be excluded from +.Nm +control for all adapters by setting this tunable in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hw.mps.exclude_ids=Y +.Ed +.Pp +Y represents the target ID of the device. +If more than one device is to be excluded, target IDs are separated by commas. +.Pp +Devices can be excluded from +.Nm +control for a specific adapter by setting this tunable in +.Xr loader.conf 5 : +.Bd -literal -offset indent +dev.mps.X.exclude_ids=Y +.Ed +.Pp +Y represents the target ID of the device. +If more than one device is to be excluded, target IDs are separated by commas. +.Pp +The adapter can issue the +.Sy StartStopUnit +SCSI command to SATA direct-access devices during shutdown. +This allows the device to quiesce powering down. +To control this feature for all adapters, set the +.Bd -literal -offset indent +hw.mps.enable_ssu +.Ed +.Pp +tunable in +.Xr loader.conf 5 +to one of these values: +.Bl -tag -width 6n -offset indent +.It 0 +Do not send SSU to either HDDs or SSDs. +.It 1 +Send SSU to SSDs, but not to HDDs. +This is the default value. +.It 2 +Send SSU to HDDs, but not to SSDs. +.It 3 +Send SSU to both HDDs and SSDs. +.El +.Pp +To control this feature for a specific adapter, set this tunable value in +.Xr loader.conf 5 : +.Bd -literal -offset indent +dev.mps.X.enable_ssu +.Ed +.Pp +The same set of values are valid as when setting this tunable for all adapters. +.Pp +SATA disks that take several seconds to spin up and fail the SATA Identify +command might not be discovered by the driver. +This problem can sometimes be overcome by increasing the value of the spinup +wait time in +.Xr loader.conf 5 +with the +.Bd -literal -offset indent +hw.mps.spinup_wait_time=NNNN +.Ed +.Pp +tunable. +NNNN represents the number of seconds to wait for SATA devices to spin up when +the device fails the initial SATA Identify command. +.Pp +Spinup wait times can be set for specific adapters in +.Xr loader.conf 5 : +with the +.Bd -literal -offset indent +dev.mps.X.spinup_wait_time=NNNN +.Ed +.Pp +tunable. +NNNN is the number of seconds to wait for SATA devices to spin up when they fail +the initial SATA Identify command. +.Pp +The driver can map devices discovered by the adapter so that target IDs +corresponding to a specific device persist across resets and reboots. +In some cases it is possible for devices to lose their mapped IDs due to +unexpected behavior from certain hardware, such as some types of enclosures. +To overcome this problem, a tunable is provided that will force the driver to +map devices using the Phy number associated with the device. +This feature is not recommended if the topology includes multiple +enclosures/expanders. +If multiple enclosures/expanders are present in the topology, Phy numbers are +repeated, causing all devices at these Phy numbers except the first device to +fail enumeration. +To control this feature for all adapters, set the +.Bd -literal -offset indent +hw.mps.use_phy_num +.Ed +.Pp +tunable in +.Xr loader.conf 5 +to one of these values: +.Bl -tag -width 6n -offset indent +.It -1 +Only use Phy numbers to map devices and bypass the driver's mapping logic. +.It 0 +Never use Phy numbers to map devices. +.It 1 +Use Phy numbers to map devices, but only if the driver's mapping logic fails +to map the device that is being enumerated. +This is the default value. +.El +.Pp +To control this feature for a specific adapter, set this tunable value in +.Xr loader.conf 5 : +.Bd -literal -offset indent +dev.mps.X.use_phy_num +.Ed +.Pp +The same set of values are valid as when setting this tunable for all adapters. +.Sh DEBUGGING +Driver diagnostic printing is controlled in +.Xr loader.conf 5 +by using the global +.Va hw.mps.debug_level +and per-device +.Va dev.mps.X.debug_level +tunables. +One can alter the debug level for any adapter at run-time using the +.Xr sysctl 8 +variable +.Va dev.mps.X.debug_level . +.Pp +All +.Va debug_level +variables can be named by either an integer value or a text string. +Multiple values can be specified together by either ORing the +integer values or by providing a comma-separated list of names. +A text string prefixed by +.Qq + +adds the specified debug levels to the existing set, while the prefix +.Qq - +removes them from the existing set. +The current +.Va debug_level +status is reported in both formats for convenience. +The following levels are available: +.Bl -column "FlagXX" "NameXXXX" "Description" -offset indent +.It Em Flag Ta Em Name Ta Em Description +.It 0x0001 Ta info Ta Basic information (enabled by default) +.It 0x0002 Ta fault Ta Driver faults (enabled by default) +.It 0x0004 Ta event Ta Controller events +.It 0x0008 Ta log Ta Logging data from controller +.It 0x0010 Ta recovery Ta Tracing of recovery operations +.It 0x0020 Ta error Ta Parameter errors and programming bugs +.It 0x0040 Ta init Ta System initialization operations +.It 0x0080 Ta xinfo Ta More detailed information +.It 0x0100 Ta user Ta Tracing of user-generated commands (IOCTL) +.It 0x0200 Ta mapping Ta Tracing of device mapping +.It 0x0400 Ta trace Ta Tracing through driver functions +.El +.Sh SEE ALSO +.Xr cam 4 , +.Xr cd 4 , +.Xr ch 4 , +.Xr da 4 , +.Xr mpr 4 , +.Xr mpt 4 , +.Xr pci 4 , +.Xr sa 4 , +.Xr scsi 4 , +.Xr targ 4 , +.Xr loader.conf 5 , +.Xr mpsutil 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 9.0 . +.Sh AUTHORS +The +.Nm +driver was originally written by +.An -nosplit +.An Scott Long Aq Mt scottl@FreeBSD.org . +It has been improved and tested by LSI Corporation, +Avago Technologies (formerly LSI), and Broadcom Ltd. (formerly Avago). +.Pp +This manual page was written by +.An Ken Merry Aq Mt ken@FreeBSD.org +with additional input from +.An Stephen McConnell Aq Mt slm@FreeBSD.org . diff --git a/static/freebsd/man4/mpt.4 b/static/freebsd/man4/mpt.4 new file mode 100644 index 00000000..1f6fa3e3 --- /dev/null +++ b/static/freebsd/man4/mpt.4 @@ -0,0 +1,193 @@ +.\" $NetBSD: mpt.4,v 1.1 2003/04/16 22:32:15 thorpej Exp $ +.\" +.\" Copyright (c) 2003 Wasabi Systems, Inc. +.\" All rights reserved. +.\" +.\" Written by Jason R. Thorpe for Wasabi Systems, Inc. +.\" +.\" 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 for the NetBSD Project by +.\" Wasabi Systems, Inc. +.\" 4. The name of Wasabi Systems, Inc. may not be used to endorse +.\" or promote products derived from this software without specific prior +.\" written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``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 WASABI SYSTEMS, INC +.\" 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 16, 2021 +.Dt MPT 4 +.Os +.Sh NAME +.Nm mpt +.Nd LSI Fusion-MPT SCSI/Fibre Channel driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device scbus" +.Cd "device mpt" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +mpt_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support +for the LSI Logic Fusion-MPT family of +.Tn SCSI , +.Tn Fibre Channel +and +.Tn SAS +controllers. +.Sh HARDWARE +The following controllers are supported by the +.Nm +driver: +.Pp +.Bl -bullet -compact +.It +LSI Logic 53c1030, +LSI Logic LSI2x320-X +(Single and Dual Ultra320 +.Tn SCSI ) +.It +LSI Logic AS1064, +LSI Logic AS1068 +.Pq Tn SAS/SATA +.It +LSI Logic FC909 +(1Gb/s +.Tn Fibre Channel ) +.It +LSI Logic FC909A +(Dual 1Gb/s +.Tn Fibre Channel ) +.It +LSI Logic FC919, +LSI Logic 7102XP-LC +(Single 2Gb/s +.Tn Fibre Channel ) +.It +LSI Logic FC929, +LSI Logic FC929X, +LSI Logic 7202XP-LC +(Dual 2Gb/s +.Tn Fibre Channel ) +.It +LSI Logic FC949X +(Dual 4Gb/s +.Tn Fibre Channel ) +.It +LSI Logic FC949E, +LSI Logic FC949ES +(Dual 4Gb/s +.Tn Fibre Channel PCI-Express) +.El +.Pp +The +.Tn Ultra 320 SCSI +controller chips supported by the +.Nm +driver can be found onboard on many systems including: +.Pp +.Bl -bullet -compact +.It +Dell PowerEdge 1750 through 2850 +.It +IBM eServer xSeries 335 +.El +.Pp +These systems also contain Integrated RAID Mirroring and Integrated +RAID Mirroring Enhanced which this driver also supports. +.Pp +The +.Tn SAS +controller chips are also present on many new AMD/Opteron based systems, +like the Sun 4100. +Note that this controller can drive both SAS and SATA +drives or a mix of them at the same time. +The Integrated RAID Mirroring +available for these controllers is poorly supported at best. +.Pp +The +.Tn Fibre Channel +controller chipset are supported by a broad variety of speeds and systems. +The +.Tn Apple +Fibre Channel HBA is in fact the +.Tn FC949ES +card. +.Pp +This driver also supports target mode for Fibre Channel cards. +This support may be enabled by setting the desired role of the core via +the LSI Logic firmware utility that establishes what roles the card +can take on - no separate compilation is required. +.Sh WARNINGS +Most controllers supported by the +.Nm +driver suffer from limitations on supported disk size (mostly <2TB). +While most controllers will truncate usable disk size, others might +behave unexpectedly and can cause severe data loss. +Refer to the datasheet of the chipset and firmware version for information +about supported disk size and limitations. +.Sh SEE ALSO +.Xr cd 4 , +.Xr ch 4 , +.Xr da 4 , +.Xr mps 4 , +.Xr pci 4 , +.Xr sa 4 , +.Xr scsi 4 , +.Xr targ 4 , +.Xr gmultipath 8 , +.Xr mptutil 8 +.Rs +.%T "LSI Logic Website" +.%U http://www.lsi.com/ +.Re +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 4.6 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was originally written for +.Fx +by +.An Greg Ansley +and marginally improved upon +by +.An Matt Jacob Aq Mt mjacob@FreeBSD.org . +.Pp +.An Justin Gibbs Aq Mt gibbs@FreeBSD.org +and +.An Scott Long Aq Mt scottl@FreeBSD.org +have made more substantial improvements. diff --git a/static/freebsd/man4/mqueuefs.4 b/static/freebsd/man4/mqueuefs.4 new file mode 100644 index 00000000..384a3e3e --- /dev/null +++ b/static/freebsd/man4/mqueuefs.4 @@ -0,0 +1,122 @@ +.\" Copyright (c) 2005 David Xu +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 November 30, 2005 +.Dt MQUEUEFS 4 +.Os +.Sh NAME +.Nm mqueuefs +.Nd POSIX message queue file system +.Sh SYNOPSIS +To link into kernel: +.Pp +.Cd "options P1003_1B_MQUEUE" +.Pp +To load as a kernel loadable module: +.Pp +.Dl "kldload mqueuefs" +.Sh DESCRIPTION +The +.Nm +module will permit the +.Fx +kernel to support +.Tn POSIX +message queue. +The module contains system calls to manipulate +.Tn POSIX +message queues. +It also contains a file system to implement a view for all message queues of +the system. +This helps users to keep track of their message queues and make +it more easily usable without having to invent additional tools. +.Pp +The most common usage is as follows: +.Pp +.Dl "mount -t mqueuefs null /mnt/mqueue" +.Pp +where +.Pa /mnt/mqueue +is a mount point. +.Pp +It is possible to define an entry in +.Pa /etc/fstab +that looks similar to: +.Bd -literal +null /mnt/mqueue mqueuefs rw 0 0 +.Ed +.Pp +This will mount +.Nm +at the +.Pa /mnt/mqueue +mount point during system boot. +Using +.Pa /mnt/mqueue +as a permanent mount point is not advised as its intention +has always been to be a temporary mount point. +See +.Xr hier 7 +for more information on +.Fx +directory layout. +.Pp +Some common tools can be used on the file system, e.g.: +.Xr cat 1 , +.Xr chmod 1 , +.Xr chown 8 , +.Xr ls 1 , +.Xr rm 1 , +etc. +To use only the message queue system calls, it is not necessary for +user to mount the file system, just load the module or compile it +into the kernel. +Manually creating a file, for example, +.Dq Li "touch /mnt/mqueue/myqueue" , +will create a message queue named +.Pa myqueue +in the kernel, default +message queue attributes will be applied to the queue. +It is not +advised to use this method to create a queue; +it is better to use the +.Xr mq_open 2 +system call to create a queue as it +allows the user to specify different attributes. +.Pp +To see the queue's attributes, just read the file: +.Pp +.Dl "cat /mnt/mqueue/myqueue" +.Sh SEE ALSO +.Xr mq_open 2 , +.Xr nmount 2 , +.Xr unmount 2 , +.Xr mount 8 , +.Xr umount 8 +.Sh AUTHORS +This manual page was written by +.An David Xu Aq Mt davidxu@FreeBSD.org . diff --git a/static/freebsd/man4/mrsas.4 b/static/freebsd/man4/mrsas.4 new file mode 100644 index 00000000..6645835d --- /dev/null +++ b/static/freebsd/man4/mrsas.4 @@ -0,0 +1,389 @@ +.\" +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" Copyright (c) 2014 LSI Corp +.\" All rights reserved. +.\" Author: Kashyap Desai +.\" Support: freebsdraid@lsi.com +.\" +.\" 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. Neither the name of the nor the names of its +.\" contributors may be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 +.\" COPYRIGHT HOLDER 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. +.\" +.\" The views and conclusions contained in the software and documentation +.\" are those of the authors and should not be interpreted as representing +.\" official policies, either expressed or implied, of the FreeBSD Project. +.\" +.Dd January 6, 2026 +.Dt MRSAS 4 +.Os +.Sh NAME +.Nm mrsas +.Nd Broadcom/LSI MegaRAID 6/12Gb/s SAS+SATA RAID controller driver +.Sh SYNOPSIS +.Cd "device pci" +.Cd "device mrsas" +.Pp +In +.Xr loader.conf 5 : +.Cd mrsas_load="YES" +.Pp +In +.Xr sysctl.conf 5 : +.Cd dev.mrsas.X.disable_ocr +.Cd dev.mrsas.X.fw_outstanding +.Cd dev.mrsas.X.mrsas_fw_fault_check_delay +.Cd dev.mrsas.X.mrsas_io_timeout +.Cd hw.mrsas.X.debug_level +.Sh DESCRIPTION +The +.Nm +driver will detect Broadcom/LSI's 6Gb/s and 12Gb/s +PCI Express SAS/SATA/NVMe RAID controllers. +A disk +.Pq virtual disk/physical disk +attached to the +.Nm +driver will be visible to the user through +.Xr camcontrol 8 +as +.Pa /dev/da? +device nodes. +A simple management interface is also provided per-controller via the +.Pa /dev/mrsas? +device node. +.Pp +The +.Nm +name is derived from the phrase "MegaRAID SAS HBA", which is +substantially different than the old "MegaRAID" Driver +.Xr mfi 4 +which does not connect targets to the +.Xr cam 4 +layer and thus requires a new driver which attaches targets to the +.Xr cam 4 +layer. +Older MegaRAID controllers are supported by +.Xr mfi 4 +and will not work with +.Nm , +but both the +.Xr mfi 4 +and +.Nm +drivers can detect and manage the +Broadcom/LSI MegaRAID SAS 2208/2308/3008/3108 series of controllers. +.Pp +The +.Xr device.hints 5 +option is provided to tune the +.Nm +driver's behavior for LSI MegaRAID SAS 2208/2308/3008/3108 controllers. +By default, the +.Xr mfi 4 +driver will detect these controllers. +See the +.Sx PRIORITY +section to know more about driver priority for MR-Fusion devices. +.Pp +.Nm +will provide a priority of (-30) (between +.Dv BUS_PROBE_DEFAULT +and +.Dv BUS_PROBE_LOW_PRIORITY ) +at probe call for device id's 0x005B, 0x005D, and +0x005F so that +.Nm +does not take control of these devices without user intervention. +.Pp +Solid-state drives (SSD) get ATA TRIM support with +.Nm +if underlying adapter allows it. +This may require configuring SSD as Non-RAID drive +rather then JBOD virtual mode. +.Sh HARDWARE +The +.Nm +driver supports the following LSI/Broadcom SATA/SAS RAID controllers: +.Pp +.Bl -column -compact "LSI MegaRAID SAS 9380" "Invader/Fury" "12Gb/s" +.It Controller Ta Chip Ta Speed +.It Broadcom SAS3916 Ta Aero Ta 12Gb/s +.It Broadcom SAS3908 Ta Aero Ta 12Gb/s +.It LSI MegaRAID SAS 9380 Ta Invader/Fury Ta 12Gb/s +.It LSI MegaRAID SAS 9361 Ta Invader/Fury Ta 12Gb/s +.It LSI MegaRAID SAS 9341 Ta Invader/Fury Ta 12Gb/s +.It LSI MegaRAID SAS 9286 Ta Thunderbolt Ta 6Gb/s +.It LSI MegaRAID SAS 9285 Ta Thunderbolt Ta 6Gb/s +.It LSI MegaRAID SAS 9272 Ta Thunderbolt Ta 6Gb/s +.It LSI MegaRAID SAS 9271 Ta Thunderbolt Ta 6Gb/s +.It LSI MegaRAID SAS 9270 Ta Thunderbolt Ta 6Gb/s +.It LSI MegaRAID SAS 9267 Ta Thunderbolt Ta 6Gb/s +.It LSI MegaRAID SAS 9266 Ta Thunderbolt Ta 6Gb/s +.It LSI MegaRAID SAS 9265 Ta Thunderbolt Ta 6Gb/s +.It LSI SAS 3108 Ta Ta 12Gb/s +.It LSI SAS 3008 Ta Ta 12Gb/s +.It LSI SAS 2308 Ta Ta 6Gb/s +.It LSI SAS 2208 Ta Ta 6Gb/s +.It DELL PERC H830 Ta Invader/Fury Ta 12Gb/s +.It DELL PERC H810 Ta Thunderbolt Ta 6Gb/s +.It DELL PERC H730/P Ta Invader/Fury Ta 12Gb/s +.It DELL PERC H710/P Ta Thunderbolt Ta 6Gb/s +.It DELL PERC H330 Ta Invader/Fury Ta 12Gb/s +.It Fujitsu D3116 Ta Thunderbolt Ta 6Gb/s +.El +.Sh CONFIGURATION +To disable Online Controller Reset(OCR) for a specific +.Nm +driver instance, set the +following tunable value in +.Xr loader.conf 5 : +.Pp +.Dl Va dev.mrsas.X.disable_ocr=1 +.Pp +where X is the adapter number. +.Pp +To change the I/O timeout value for a specific +.Nm +driver instance, set the following tunable value in +.Xr loader.conf 5 : +.Pp +.Dl Va dev.mrsas.X.mrsas_io_timeout=NNNNNN +.Pp +where NNNNNN is the timeout value in milli-seconds. +.Pp +To change the firmware fault check timer value for a specific +.Nm +driver instance, set the following tunable value in +.Xr loader.conf 5 : +.Pp +.Dl Va dev.mrsas.X.mrsas_fw_fault_check_delay=NN +.Pp +where NN is the fault check delay value in seconds. +.Pp +The current number of active I/O commands is shown in the +.Va dev.mrsas.X.fw_outstanding +.Xr sysctl 8 +variable. +.Sh DEBUGGING +To enable debugging prints from the +.Nm +driver, set the +.Va hw.mrsas.X.debug_level +variable, where X is the adapter number, either in +.Xr loader.conf 5 +or via +.Xr sysctl 8 . +The following bits have the described effects: +.Bl -tag -width indent -offset indent +.It 0x01 +Enable informational prints. +.It 0x02 +Enable tracing prints. +.It 0x04 +Enable prints for driver faults. +.It 0x08 +Enable prints for OCR and I/O timeout. +.It 0x10 +Enable prints for AEN events. +.El +.Sh PRIORITY +The +.Nm +driver will always set a default (-30) priority in the PCI subsystem for +selection of MR-Fusion cards. +(It is between +.Dv BUS_PROBE_DEFAULT +and +.Dv BUS_PROBE_LOW_PRIORITY ) . +MR-Fusion Controllers include all cards with the +Device IDs - +0x005B, +0x005D, +0x005F. +.Pp +The +.Xr mfi 4 +driver will set a priority of either +.Dv BUS_PROBE_DEFAULT +or +.Dv BUS_PROBE_LOW_PRIORITY +(depending on the device.hints setting) in the PCI +subsystem for selection of MR-Fusion cards. +With the above design in place, the +.Xr mfi 4 +driver will attach to a MR-Fusion card +given that it has a higher priority than +.Nm . +.Pp +Using +.Pa /boot/device.hints +(as mentioned below), the user can provide a preference +for the +.Nm +driver to detect a MR-Fusion card instead of the +.Xr mfi 4 +driver. +.Bd -ragged -offset indent +.Cd hw.mfi.mrsas_enable="1" +.Ed +.Pp +At boot time, the +.Xr mfi 4 +driver will get priority to detect MR-Fusion controllers by default. +Before +changing this default driver selection policy, +LSI advises users to understand how the driver selection policy works. +LSI's policy is to provide priority to +the +.Xr mfi 4 +driver to detect MR-Fusion cards, +but allow for the ability to choose the +.Nm +driver to detect MR-Fusion cards. +.Pp +LSI recommends setting +.Va hw.mfi.mrsas_enable="0" +for customers who are using the older +.Xr mfi 4 +driver and do not want to switch to +.Nm . +For those using a MR-Fusion controller for the first time, +LSI recommends using the +.Nm +driver and setting +.Va hw.mfi.mrsas_enable="1". +.Pp +Changing the default behavior is well tested under most conditions, +but unexpected behavior may pop up +if more complex and unrealistic operations are executed +by switching between the +.Xr mfi 4 +and +.Nm +drivers for MR-Fusion. +Switching drivers is designed to happen only one time. +Although multiple switching is possible, it is not recommended. +The user should decide from +.Sy boot +which driver they want to use for the MR-Fusion card. +.Pp +The user may see different device names when switching from +.Xr mfi 4 +to +.Nm . +This behavior +.Sy works as intended +and the user needs to change the +.Xr fstab 5 +entry manually if they are doing any experiments with +.Xr mfi 4 +and +.Nm +interoperability. +.Sh FILES +.Bl -tag -width "/dev/mrsas?" -compact +.It Pa /dev/da? +array/logical disk interface +.It Pa /dev/mrsas? +management interface +.El +.Sh SEE ALSO +.Xr cam 4 , +.Xr mfi 4 , +.Xr pci 4 , +.Xr device.hints 5 , +.Xr camcontrol 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 10.1 . +.Bd -ragged +.Cd "mfi Driver:" +.Xr mfi 4 +is the old +.Fx +driver which started with support for Gen-1 Controllers and +was extended to support up to MR-Fusion +.Pq Device ID = 0x005B, 0x005D, 0x005F . +.Ed +.Bd -ragged +.Cd "mrsas Driver:" +.Nm +is the new driver reworked by LSI which supports Thunderbolt and onward +products. +The SAS+SATA RAID controller with device id 0x005B is referred to as +the Thunderbolt controller throughout this man page. +.Ed +.Bd -ragged +.Sy cam aware HBA drivers: +.Fx +has a +.Xr cam 4 +layer which attaches storage devices and provides a +common access mechanism to storage controllers and attached devices. +The +.Nm +driver is +.Xr cam 4 +aware and devices associated with +.Nm +can be seen using +.Xr camcontrol 8 . +The +.Xr mfi 4 +driver does not understand the +.Xr cam 4 +layer and it directly associates storage disks to the block layer. +.Pp +.Sy Thunderbolt Controller: +This is the 6Gb/s MegaRAID HBA card which has device id 0x005B. +.Pp +.Sy Invader Controller: +This is 12Gb/s MegaRAID HBA card which has device id 0x005D. +.Pp +.Sy Fury Controller: +This is the 12Gb/s MegaRAID HBA card which has device id 0x005F. +.Ed +.Sh AUTHORS +The +.Nm +driver and this manual page were written by +.An Kashyap Desai Aq Mt Kashyap.Desai@lsi.com . +.Sh CAVEATS +The +.Nm +driver exposes devices as +.Pa /dev/da? , +whereas +.Xr mfi 4 +exposes devices as +.Pa /dev/mfid? . +.Pp +.Nm +does not support the Linux Emulator Interface, +.Xr mfiutil 8 , +or device name aliases for switching drivers without editing +.Xr fstab 5 . diff --git a/static/freebsd/man4/msdosfs.4 b/static/freebsd/man4/msdosfs.4 new file mode 100644 index 00000000..d823934d --- /dev/null +++ b/static/freebsd/man4/msdosfs.4 @@ -0,0 +1,75 @@ +.\" Written by Tom Rhodes +.\" This file is in the public domain. +.\" +.Dd September 27, 2018 +.Dt MSDOSFS 4 +.Os +.Sh NAME +.Nm msdosfs +.Nd MS-DOS (FAT) file system +.Sh SYNOPSIS +.Cd "options MSDOSFS" +.Sh DESCRIPTION +The +.Nm +driver will permit the +.Fx +kernel to read and write MS-DOS based file systems. +.Pp +The most common usage follows: +.Pp +.Dl "mount -t msdosfs /dev/ada0sN /mnt" +.Pp +where +.Ar N +is the partition number and +.Pa /mnt +is a mount point. +Some users tend to create a +.Pa /dos +directory for +.Nm +mount points. +This helps to keep better track of the file system, +and make it more easily accessible. +.Pp +It is possible to define an entry in +.Pa /etc/fstab +that looks similar to: +.Bd -literal +/dev/ada0sN /dos msdosfs rw 0 0 +.Ed +.Pp +This will mount an MS-DOS based partition at the +.Pa /dos +mount point during system boot. +Using +.Pa /mnt +as a permanent mount point is not advised as its intention +has always been to be a temporary mount point for floppy and +ZIP disks. +See +.Xr hier 7 +for more information on +.Fx +directory layout. +.Sh EXAMPLES +Determine which FAT file system version (e.g, FAT16, FAT32) +is a partition formatted with: +.Bd -literal -offset indent +file -s /dev/da0s1 +.Ed +.Pp +.Xr gpart 8 +may also be used to extract this information. +.Sh SEE ALSO +.Xr mount 2 , +.Xr unmount 2 , +.Xr fsck_msdosfs 8 , +.Xr mount 8 , +.Xr mount_msdosfs 8 , +.Xr newfs_msdos 8 , +.Xr umount 8 +.Sh AUTHORS +This manual page was written by +.An Tom Rhodes Aq Mt trhodes@FreeBSD.org . diff --git a/static/freebsd/man4/msk.4 b/static/freebsd/man4/msk.4 new file mode 100644 index 00000000..f73299c5 --- /dev/null +++ b/static/freebsd/man4/msk.4 @@ -0,0 +1,253 @@ +.\" Copyright (c) 2006 Pyun YongHyeon +.\" 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 May 23, 2011 +.Dt MSK 4 +.Os +.Sh NAME +.Nm msk +.Nd Marvell/SysKonnect Yukon II Gigabit Ethernet adapter driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device msk" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_msk_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +device driver provides support for various NICs based on the +Marvell/SysKonnect Yukon II Gigabit Ethernet controller chip. +.Pp +All NICs supported by the +.Nm +driver have TCP/UDP/IP checksum offload for transmit, TCP +segmentation offload (TSO), hardware VLAN tag stripping/insertion +features and an interrupt moderation mechanism as well as a 64-bit +multicast hash filter. +The Yukon II supports TBI (ten bit interface) and GMII +transceivers, which means it can be used with either copper or +1000baseX fiber applications. +.Pp +The Yukon II also supports Jumbo Frames (up to 9022 bytes), which can be +configured via the interface MTU setting. +Selecting an MTU larger than 1500 bytes with the +.Xr ifconfig 8 +utility configures the adapter to receive and transmit Jumbo Frames. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width ".Cm 10baseT/UTP" +.It Cm autoselect +Enable autoselection of the media type and options. +The user can manually override +the autoselected mode by adding media options to +.Xr rc.conf 5 . +.It Cm 10baseT/UTP +Set 10Mbps operation. +The +.Xr ifconfig 8 +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 100baseTX +Set 100Mbps (Fast Ethernet) operation. +The +.Xr ifconfig 8 +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 1000baseTX +Set 1000baseTX operation over twisted pair. +The +.Xr ifconfig 8 +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 1000baseSX +Set 1000Mbps (Gigabit Ethernet) operation. +Both +.Cm full-duplex +and +.Cm half-duplex +modes are supported. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width ".Cm full-duplex" +.It Cm full-duplex +Force full duplex operation. +.It Cm half-duplex +Force half duplex operation. +.El +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver provides support for various NICs based on the Marvell/SysKonnect +Yukon II based Gigabit Ethernet controller chips, including: +.Pp +.Bl -bullet -compact +.It +D-Link 550SX Gigabit Ethernet +.It +D-Link 560SX Gigabit Ethernet +.It +D-Link 560T Gigabit Ethernet +.It +Marvell Yukon 88E8021CU Gigabit Ethernet +.It +Marvell Yukon 88E8021 SX/LX Gigabit Ethernet +.It +Marvell Yukon 88E8022CU Gigabit Ethernet +.It +Marvell Yukon 88E8022 SX/LX Gigabit Ethernet +.It +Marvell Yukon 88E8061CU Gigabit Ethernet +.It +Marvell Yukon 88E8061 SX/LX Gigabit Ethernet +.It +Marvell Yukon 88E8062CU Gigabit Ethernet +.It +Marvell Yukon 88E8062 SX/LX Gigabit Ethernet +.It +Marvell Yukon 88E8035 Fast Ethernet +.It +Marvell Yukon 88E8036 Fast Ethernet +.It +Marvell Yukon 88E8038 Fast Ethernet +.It +Marvell Yukon 88E8039 Fast Ethernet +.It +Marvell Yukon 88E8040 Fast Ethernet +.It +Marvell Yukon 88E8040T Fast Ethernet +.It +Marvell Yukon 88E8042 Fast Ethernet +.It +Marvell Yukon 88E8048 Fast Ethernet +.It +Marvell Yukon 88E8050 Gigabit Ethernet +.It +Marvell Yukon 88E8052 Gigabit Ethernet +.It +Marvell Yukon 88E8053 Gigabit Ethernet +.It +Marvell Yukon 88E8055 Gigabit Ethernet +.It +Marvell Yukon 88E8056 Gigabit Ethernet +.It +Marvell Yukon 88E8057 Gigabit Ethernet +.It +Marvell Yukon 88E8058 Gigabit Ethernet +.It +Marvell Yukon 88E8059 Gigabit Ethernet +.It +Marvell Yukon 88E8070 Gigabit Ethernet +.It +Marvell Yukon 88E8071 Gigabit Ethernet +.It +Marvell Yukon 88E8072 Gigabit Ethernet +.It +Marvell Yukon 88E8075 Gigabit Ethernet +.It +SysKonnect SK-9Sxx Gigabit Ethernet +.It +SysKonnect SK-9Exx Gigabit Ethernet +.El +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width indent +.It Va hw.msk.msi_disable +This tunable disables MSI support on the Ethernet hardware. +The default value is 0. +.El +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va dev.mskc.%d.int_holdoff +Maximum number of time to delay interrupts. +The valid range is 0 to 34359738 for 125MHz clock in units of 1us, +the default is 100 (100us). +The interface need to be brought down and up again before a change +takes effect. +.It Va dev.mskc.%d.process_limit +Maximum amount of Rx events to be processed in the event loop before +rescheduling a taskqueue. +The accepted range is 30 to 256, the default value is 128 events. +The interface does not need to be brought down and up again before +a change takes effect. +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +driver was written by +.An Pyun YongHyeon Aq Mt yongari@FreeBSD.org +and it is based on +.Xr sk 4 +and Marvell's +.Fx +driver. +It first appeared in +.Fx 7.0 +and +.Fx 6.3 . diff --git a/static/freebsd/man4/mt7915.4 b/static/freebsd/man4/mt7915.4 new file mode 100644 index 00000000..ba67a77a --- /dev/null +++ b/static/freebsd/man4/mt7915.4 @@ -0,0 +1,111 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2023-2024 Bjoern A. Zeeb +.\" +.\" 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 November 10, 2024 +.Dt MT7915 4 +.Os +.Sh NAME +.Nm mt7915 +.Nd MediaTek IEEE 802.11ax wireless network driver +.Sh SYNOPSIS +The driver will auto-load without any user interaction using +.Xr devmatch 8 +if enabled in +.Xr rc.conf 5 . +.Pp +Only if auto-loading is explicitly disabled, place the following +lines in +.Xr rc.conf 5 +to manually load the driver as a module at boot time: +.Bd -literal -offset indent +kld_list="${kld_list} if_mt7915" +.Ed +.Pp +The driver should automatically load any +firmware needed for the particular chipset. +.Pp +It is discouraged to load the driver from +.Xr loader 8 . +.Sh DESCRIPTION +The +.Nm +driver provides support for MediaTek MT7915E wireless network devices. +.Nm +is derived from MediaTek's Linux mt76 driver. +.Pp +This driver requires firmware to be loaded before it will work. +The package +.Pa wifi-firmware-mt76-kmod +from the +.Pa ports/net/wifi-firmware-mt76-kmod +port needs to be installed before the driver is loaded. +Otherwise no +.Xr wlan 4 +interface can be created using +.Xr ifconfig 8 . +One can use +.Xr fwget 8 +to install the correct firmware package. +.Pp +The driver uses the +.\" No LinuxKPI man pages so no .Xr here. +.Sy linuxkpi_wlan +and +.Sy linuxkpi +compat framework to bridge between the Linux and +native +.Fx +driver code as well as to the native +.Xr net80211 4 +wireless stack. +.Sh HARDWARE +The +.Nm +driver supports PCIe devices with the following chipsets: +.Pp +.Bl -bullet -offset indent -compact +.It +MediaTek MT7915E +.El +.Sh SEE ALSO +.Xr wlan 4 , +.Xr networking 7 , +.Xr fwget 8 , +.Xr ifconfig 8 , +.Xr wpa_supplicant 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 14.0 . +.Sh BUGS +Certainly. +.Pp +While +.Nm +supports 802.11a/b/g/n/ac/ax modes, +the compatibility code currently only supports 802.11a/b/g modes. +Support for 802.11n/ac/ax is yet to come. diff --git a/static/freebsd/man4/mt7921.4 b/static/freebsd/man4/mt7921.4 new file mode 100644 index 00000000..fe9efa77 --- /dev/null +++ b/static/freebsd/man4/mt7921.4 @@ -0,0 +1,111 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2023-2024 Bjoern A. Zeeb +.\" +.\" 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 November 10, 2024 +.Dt MT7921 4 +.Os +.Sh NAME +.Nm mt7921 +.Nd MediaTek IEEE 802.11ax wireless network driver +.Sh SYNOPSIS +The driver will auto-load without any user interaction using +.Xr devmatch 8 +if enabled in +.Xr rc.conf 5 . +.Pp +Only if auto-loading is explicitly disabled, place the following +lines in +.Xr rc.conf 5 +to manually load the driver as a module at boot time: +.Bd -literal -offset indent +kld_list="${kld_list} if_mt7921" +.Ed +.Pp +The driver should automatically load any +firmware needed for the particular chipset. +.Pp +It is discouraged to load the driver from +.Xr loader 8 . +.Sh DESCRIPTION +The +.Nm +driver provides support for MediaTek MT7921E wireless network devices. +.Nm +is derived from MediaTek's Linux mt76 driver. +.Pp +This driver requires firmware to be loaded before it will work. +The package +.Pa wifi-firmware-mt76-kmod +from the +.Pa ports/net/wifi-firmware-mt76-kmod +port needs to be installed before the driver is loaded. +Otherwise no +.Xr wlan 4 +interface can be created using +.Xr ifconfig 8 . +One can use +.Xr fwget 8 +to install the correct firmware package. +.Pp +The driver uses the +.\" No LinuxKPI man pages so no .Xr here. +.Sy linuxkpi_wlan +and +.Sy linuxkpi +compat framework to bridge between the Linux and +native +.Fx +driver code as well as to the native +.Xr net80211 4 +wireless stack. +.Sh HARDWARE +The +.Nm +driver supports PCIe devices with the following chipsets: +.Pp +.Bl -bullet -offset indent -compact +.It +MediaTek MT7921E +.El +.Sh SEE ALSO +.Xr wlan 4 , +.Xr networking 7 , +.Xr fwget 8 , +.Xr ifconfig 8 , +.Xr wpa_supplicant 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 14.0 . +.Sh BUGS +Certainly. +.Pp +While +.Nm +supports 802.11a/b/g/n/ac/ax modes, +the compatibility code currently only supports 802.11a/b/g modes. +Support for 802.11n/ac/ax is to come. diff --git a/static/freebsd/man4/mtio.4 b/static/freebsd/man4/mtio.4 new file mode 100644 index 00000000..34414e5f --- /dev/null +++ b/static/freebsd/man4/mtio.4 @@ -0,0 +1,411 @@ +.\" Copyright (c) 1996 +.\" Mike Pritchard . All rights reserved. +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 February 12, 2015 +.Dt MTIO 4 +.Os +.Sh NAME +.Nm mtio +.Nd FreeBSD magtape interface +.Sh DESCRIPTION +The special files +named +.Pa /dev/[en]sa* +refer to SCSI tape drives, +which may be attached to the system. +.Pa /dev/sa*.ctl +are control devices that can be used to issue ioctls to the SCSI +tape driver to set parameters that are required to last beyond the +unmounting of a tape. +.Pp +The rewind devices automatically rewind +when the last requested read, write or seek has finished, or the end of the tape +has been reached. +The letter +.Ql n +is prepended to +the name of the no-rewind devices. +The letter +.Ql e +is prepended to the name of the eject devices. +.Pp +Tapes can be written with either fixed length records or variable length +records. +See +.Xr sa 4 +for more information. +Two filemarks mark the end of a tape, and +one filemark marks the end of a tape file. +If the tape is not to be rewound it is positioned with the +head in between the two tape marks, where the next write +will over write the second end-of-file marker. +.Pp +All of the magtape devices may be manipulated with the +.Xr mt 1 +command. +.Pp +A number of +.Xr ioctl 2 +operations are available +on raw magnetic tape. +The following definitions are from +.In sys/mtio.h : +.Bd -literal +#ifndef _SYS_MTIO_H_ +#define _SYS_MTIO_H_ + +#ifndef _KERNEL +#include +#endif +#include + +/* + * Structures and definitions for mag tape io control commands + */ + +/* structure for MTIOCTOP - mag tape op command */ +struct mtop { + short mt_op; /* operations defined below */ + int32_t mt_count; /* how many of them */ +}; + +/* operations */ +#define MTWEOF 0 /* write an end-of-file record */ +#define MTFSF 1 /* forward space file */ +#define MTBSF 2 /* backward space file */ +#define MTFSR 3 /* forward space record */ +#define MTBSR 4 /* backward space record */ +#define MTREW 5 /* rewind */ +#define MTOFFL 6 /* rewind and put the drive offline */ +#define MTNOP 7 /* no operation, sets status only */ +#define MTCACHE 8 /* enable controller cache */ +#define MTNOCACHE 9 /* disable controller cache */ + +#if defined(__FreeBSD__) +/* Set block size for device. If device is a variable size dev */ +/* a non zero parameter will change the device to a fixed block size */ +/* device with block size set to that of the parameter passed in. */ +/* Resetting the block size to 0 will restore the device to a variable */ +/* block size device. */ + +#define MTSETBSIZ 10 + +/* Set density values for device. Sets the value for the opened mode only. */ + +#define MTSETDNSTY 11 + +#define MTERASE 12 /* erase to EOM */ +#define MTEOD 13 /* Space to EOM */ +#define MTCOMP 14 /* select compression mode 0=off, 1=def */ +#define MTRETENS 15 /* re-tension tape */ +#define MTWSS 16 /* write setmark(s) */ +#define MTFSS 17 /* forward space setmark */ +#define MTBSS 18 /* backward space setmark */ +#define MTLOAD 19 /* load tape in drive */ +#define MTWEOFI 20 /* write an end-of-file record without waiting*/ + +#define MT_COMP_ENABLE 0xffffffff +#define MT_COMP_DISABLED 0xfffffffe +#define MT_COMP_UNSUPP 0xfffffffd + +/* + * Values in mt_dsreg that say what the device is doing + */ +#define MTIO_DSREG_NIL 0 /* Unknown */ +#define MTIO_DSREG_REST 1 /* Doing Nothing */ +#define MTIO_DSREG_RBSY 2 /* Communicating with tape (but no motion) */ +#define MTIO_DSREG_WR 20 /* Writing */ +#define MTIO_DSREG_FMK 21 /* Writing Filemarks */ +#define MTIO_DSREG_ZER 22 /* Erasing */ +#define MTIO_DSREG_RD 30 /* Reading */ +#define MTIO_DSREG_FWD 40 /* Spacing Forward */ +#define MTIO_DSREG_REV 41 /* Spacing Reverse */ +#define MTIO_DSREG_POS 42 /* Hardware Positioning (direction unknown) */ +#define MTIO_DSREG_REW 43 /* Rewinding */ +#define MTIO_DSREG_TEN 44 /* Retensioning */ +#define MTIO_DSREG_UNL 45 /* Unloading */ +#define MTIO_DSREG_LD 46 /* Loading */ + +#endif /* __FreeBSD__ */ + +/* structure for MTIOCGET - mag tape get status command */ + +struct mtget { + short mt_type; /* type of magtape device */ +/* the following two registers are grossly device dependent */ + short mt_dsreg; /* ``drive status'' register */ + short mt_erreg; /* ``error'' register */ +/* end device-dependent registers */ + /* + * Note that the residual count, while maintained, may be + * be nonsense because the size of the residual may (greatly) + * exceed 32 K-bytes. Use the MTIOCERRSTAT ioctl to get a + * more accurate count. + */ + short mt_resid; /* residual count */ +#if defined (__FreeBSD__) + int32_t mt_blksiz; /* presently operating blocksize */ + int32_t mt_density; /* presently operating density */ + uint32_t mt_comp; /* presently operating compression */ + int32_t mt_blksiz0; /* blocksize for mode 0 */ + int32_t mt_blksiz1; /* blocksize for mode 1 */ + int32_t mt_blksiz2; /* blocksize for mode 2 */ + int32_t mt_blksiz3; /* blocksize for mode 3 */ + int32_t mt_density0; /* density for mode 0 */ + int32_t mt_density1; /* density for mode 1 */ + int32_t mt_density2; /* density for mode 2 */ + int32_t mt_density3; /* density for mode 3 */ +/* the following are not yet implemented */ + uint32_t mt_comp0; /* compression type for mode 0 */ + uint32_t mt_comp1; /* compression type for mode 1 */ + uint32_t mt_comp2; /* compression type for mode 2 */ + uint32_t mt_comp3; /* compression type for mode 3 */ +/* end not yet implemented */ +#endif + int32_t mt_fileno; /* relative file number of current position */ + int32_t mt_blkno; /* relative block number of current position */ +}; + +/* structure for MTIOCERRSTAT - tape get error status command */ +/* really only supported for SCSI tapes right now */ +struct scsi_tape_errors { + /* + * These are latched from the last command that had a SCSI + * Check Condition noted for these operations. The act + * of issuing an MTIOCERRSTAT unlatches and clears them. + */ + uint8_t io_sense[32]; /* Last Sense Data For Data I/O */ + int32_t io_resid; /* residual count from last Data I/O */ + uint8_t io_cdb[16]; /* Command that Caused the Last Data Sense */ + uint8_t ctl_sense[32]; /* Last Sense Data For Control I/O */ + int32_t ctl_resid; /* residual count from last Control I/O */ + uint8_t ctl_cdb[16]; /* Command that Caused the Last Control Sense */ + /* + * These are the read and write cumulative error counters. + * (how to reset cumulative error counters is not yet defined). + * (not implemented as yet but space is being reserved for them) + */ + struct { + uint32_t retries; /* total # retries performed */ + uint32_t corrected; /* total # corrections performed */ + uint32_t processed; /* total # corrections successful */ + uint32_t failures; /* total # corrections/retries failed */ + uint64_t nbytes; /* total # bytes processed */ + } wterr, rderr; +}; + +union mterrstat { + struct scsi_tape_errors scsi_errstat; + char _reserved_padding[256]; +}; + +struct mtrblim { + uint32_t granularity; + uint32_t min_block_length; + uint32_t max_block_length; +}; + +typedef enum { + MT_LOCATE_DEST_OBJECT = 0x00, + MT_LOCATE_DEST_FILE = 0x01, + MT_LOCATE_DEST_SET = 0x02, + MT_LOCATE_DEST_EOD = 0x03 +} mt_locate_dest_type; + +typedef enum { + MT_LOCATE_BAM_IMPLICIT = 0x00, + MT_LOCATE_BAM_EXPLICIT = 0x01 +} mt_locate_bam; + +typedef enum { + MT_LOCATE_FLAG_IMMED = 0x01, + MT_LOCATE_FLAG_CHANGE_PART = 0x02 +} mt_locate_flags; + +struct mtlocate { + mt_locate_flags flags; + mt_locate_dest_type dest_type; + mt_locate_bam block_address_mode; + int64_t partition; + uint64_t logical_id; + uint8_t reserved[64]; +}; + +typedef enum { + MT_EXT_GET_NONE, + MT_EXT_GET_OK, + MT_EXT_GET_NEED_MORE_SPACE, + MT_EXT_GET_ERROR +} mt_ext_get_status; + +struct mtextget { + uint32_t alloc_len; + char *status_xml; + uint32_t fill_len; + mt_ext_get_status status; + char error_str[128]; + uint8_t reserved[64]; +}; + +#define MT_EXT_GET_ROOT_NAME "mtextget" +#define MT_DENSITY_ROOT_NAME "mtdensity" +#define MT_MEDIA_DENSITY_NAME "media_density" +#define MT_DENSITY_REPORT_NAME "density_report" +#define MT_MEDIUM_TYPE_REPORT_NAME "medium_type_report" +#define MT_MEDIA_REPORT_NAME "media_report" +#define MT_DENSITY_ENTRY_NAME "density_entry" + +#define MT_DENS_WRITE_OK 0x80 +#define MT_DENS_DUP 0x40 +#define MT_DENS_DEFLT 0x20 + + +#define MT_PARAM_FIXED_STR_LEN 32 +union mt_param_value { + int64_t value_signed; + uint64_t value_unsigned; + char *value_var_str; + char value_fixed_str[MT_PARAM_FIXED_STR_LEN]; + uint8_t reserved[64]; +}; + +typedef enum { + MT_PARAM_SET_NONE, + MT_PARAM_SET_SIGNED, + MT_PARAM_SET_UNSIGNED, + MT_PARAM_SET_VAR_STR, + MT_PARAM_SET_FIXED_STR +} mt_param_set_type; + +typedef enum { + MT_PARAM_STATUS_NONE, + MT_PARAM_STATUS_OK, + MT_PARAM_STATUS_ERROR +} mt_param_set_status; + +#define MT_PARAM_VALUE_NAME_LEN 64 +struct mtparamset { + char value_name[MT_PARAM_VALUE_NAME_LEN]; + mt_param_set_type value_type; + int value_len; + union mt_param_value value; + mt_param_set_status status; + char error_str[128]; +}; + +#define MT_PARAM_ROOT_NAME "mtparamget" +#define MT_PROTECTION_NAME "protection" + +/* + * Set a list of parameters. + */ +struct mtsetlist { + int num_params; + int param_len; + struct mtparamset *params; +}; + +/* + * Constants for mt_type byte. These are the same + * for controllers compatible with the types listed. + */ +#define MT_ISTS 0x01 /* TS-11 */ +#define MT_ISHT 0x02 /* TM03 Massbus: TE16, TU45, TU77 */ +#define MT_ISTM 0x03 /* TM11/TE10 Unibus */ +#define MT_ISMT 0x04 /* TM78/TU78 Massbus */ +#define MT_ISUT 0x05 /* SI TU-45 emulation on Unibus */ +#define MT_ISCPC 0x06 /* SUN */ +#define MT_ISAR 0x07 /* SUN */ +#define MT_ISTMSCP 0x08 /* DEC TMSCP protocol (TU81, TK50) */ +#define MT_ISCY 0x09 /* CCI Cipher */ +#define MT_ISCT 0x0a /* HP 1/4 tape */ +#define MT_ISFHP 0x0b /* HP 7980 1/2 tape */ +#define MT_ISEXABYTE 0x0c /* Exabyte */ +#define MT_ISEXA8200 0x0c /* Exabyte EXB-8200 */ +#define MT_ISEXA8500 0x0d /* Exabyte EXB-8500 */ +#define MT_ISVIPER1 0x0e /* Archive Viper-150 */ +#define MT_ISPYTHON 0x0f /* Archive Python (DAT) */ +#define MT_ISHPDAT 0x10 /* HP 35450A DAT drive */ +#define MT_ISMFOUR 0x11 /* M4 Data 1/2 9track drive */ +#define MT_ISTK50 0x12 /* DEC SCSI TK50 */ +#define MT_ISMT02 0x13 /* Emulex MT02 SCSI tape controller */ + +/* mag tape io control commands */ +#define MTIOCTOP _IOW('m', 1, struct mtop) /* do a mag tape op */ +#define MTIOCGET _IOR('m', 2, struct mtget) /* get tape status */ +/* these two do not appear to be used anywhere */ +#define MTIOCIEOT _IO('m', 3) /* ignore EOT error */ +#define MTIOCEEOT _IO('m', 4) /* enable EOT error */ +/* + * When more SCSI-3 SSC (streaming device) devices are out there + * that support the full 32 byte type 2 structure, we'll have to + * rethink these ioctls to support all the entities they haul into + * the picture (64 bit blocks, logical file record numbers, etc..). + */ +#define MTIOCRDSPOS _IOR('m', 5, uint32_t) /* get logical blk addr */ +#define MTIOCRDHPOS _IOR('m', 6, uint32_t) /* get hardware blk addr */ +#define MTIOCSLOCATE _IOW('m', 5, uint32_t) /* seek to logical blk addr */ +#define MTIOCHLOCATE _IOW('m', 6, uint32_t) /* seek to hardware blk addr */ +#define MTIOCERRSTAT _IOR('m', 7, union mterrstat) /* get tape errors */ +/* + * Set EOT model- argument is number of filemarks to end a tape with. + * Note that not all possible values will be accepted. + */ +#define MTIOCSETEOTMODEL _IOW('m', 8, uint32_t) +/* Get current EOT model */ +#define MTIOCGETEOTMODEL _IOR('m', 8, uint32_t) +#define MTIOCRBLIM _IOR('m', 9, struct mtrblim) /* get block limits */ +#define MTIOCEXTLOCATE _IOW('m', 10, struct mtlocate) /* seek to position */ +#define MTIOCEXTGET _IOWR('m', 11, struct mtextget) /* get tape status */ +#define MTIOCPARAMGET _IOWR('m', 12, struct mtextget) /* get tape params */ +#define MTIOCPARAMSET _IOWR('m', 13, struct mtparamset) /* set tape params */ +#define MTIOCSETLIST _IOWR('m', 14, struct mtsetlist) /* set N params */ + +#ifndef _KERNEL +#define DEFTAPE "/dev/nsa0" +#endif + +#endif /* !_SYS_MTIO_H_ */ +.Ed +.Sh FILES +.Bl -tag -width /dev/[en]sa* -compact +.It Pa /dev/[en]sa* +.El +.Sh SEE ALSO +.Xr mt 1 , +.Xr tar 1 , +.Xr sa 4 +.Sh HISTORY +The +.Nm +manual appeared in +.Bx 4.2 . +An i386 version first appeared in +.Fx 2.2 . diff --git a/static/freebsd/man4/mtkswitch.4 b/static/freebsd/man4/mtkswitch.4 new file mode 100644 index 00000000..c879df16 --- /dev/null +++ b/static/freebsd/man4/mtkswitch.4 @@ -0,0 +1,45 @@ +.\" +.\" Copyright (c) 2025 Alexander Ziaee +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd May 19, 2025 +.Dt MTKSWITCH 4 +.Sh NAME +.Nm mtkswitch +.Nd MediaTek/Ralink Ethernet switch driver +.Sh SYNOPSIS +.Cd device mdio +.Cd device etherswitch +.Cd device mtkswitch +.Sh DESCRIPTION +The +.Nm +driver supports MediaTek/Ralink Ethernet switch controllers. +.Sh HARDWARE +The +.Nm +driver supports the following Ethernet switch controllers: +.Pp +.Bl -bullet -compact +.It +MediaTek MT7628 (5 port Fast Ethernet) +.It +MediaTek MT7621 (5 port Gigabit Ethernet) +.It +MediaTek MT7620 (5 port Fast Ethernet) +.It +Ralink RT5350 (5 port Fast Ethernet) +.It +Ralink RT3352 (5 port Fast Ethernet) +.It +Ralink RT3050 (5 port Fast Ethernet) +.El +.Sh SEE ALSO +.Xr etherswitch 4 , +.Xr etherswitchcfg 8 +.Sh HISTORY +The +.Nm +driver appeared in +.Fx 11.0 . diff --git a/static/freebsd/man4/mtw.4 b/static/freebsd/man4/mtw.4 new file mode 100644 index 00000000..6aa59d84 --- /dev/null +++ b/static/freebsd/man4/mtw.4 @@ -0,0 +1,118 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2024 Jesper Schmitz Mouridsen +.\" +.\" 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 May 3, 2025 +.Dt MTW 4 +.Os +.Sh NAME +.Nm mtw +.Nd MediaTek MT7601U USB IEEE 802.11n wireless network driver +.Sh SYNOPSIS +.Cd device usb +.Cd device mtw +.Cd device wlan +.Pp +In +.Xr rc.conf 5 : +.Cd kld_list="if_mtw" +.Sh DESCRIPTION +This module provides support for +MediaTek MT7601U USB wireless network adapters. +If the appropriate hardware is detected, +the driver will be automatically loaded with +.Xr devmatch 8 . +If driver autoloading is explicitly disabled, enable the module in +.Xr rc.conf 5 . +The +.Nm +driver can be configured at runtime with +.Xr ifconfig 8 +or at boot with +.Xr rc.conf 5 . +.Sh HARDWARE +The +.Nm +driver supports MediaTek MT7601U based USB wireless network adapters +including (but not all of them tested): +.Pp +.Bl -bullet -compact +.It +ASUS USB-N10 v2 +.It +D-Link DWA-127 rev B1 +.It +Edimax EW-7711UAn v2 +.It +Foxconn WFU03 +.It +Tenda U2 +.It +Tenda W311MI v2 +.It +TP-LINK TL-WN727N v4 (tested working) +.It +Yealink WF40 +.El +.Sh FILES +The +.Nm +driver requires firmware from +.Pa ports/net/wifi-firmware-mt7601u-kmod . +This firmware package will be installed automatically with +.Xr fwget 8 +if the appropriate hardware is detected at installation or runtime. +.Sh SEE ALSO +.Xr usb 4 , +.Xr wlan 4 , +.Xr networking 7 , +.Xr fwget 8 , +.Xr wpa_supplicant 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Ox 7.1 +and +.Fx 15.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An James Hastings Aq Mt hastings@openbsd.org +and ported to +.Fx +by +.An Jesper Schmitz Mouridsen Aq Mt jsm@FreeBSD.org . +.Sh BUGS +.Nm +only works in +.Cm station +mode and +.Cm monitor +mode. +The firmware does not always reinitialize when reloading the module, +or when rebooting, without first unplugging the device. diff --git a/static/freebsd/man4/muge.4 b/static/freebsd/man4/muge.4 new file mode 100644 index 00000000..2a1b0f60 --- /dev/null +++ b/static/freebsd/man4/muge.4 @@ -0,0 +1,66 @@ +.\" Copyright (c) 2018 The FreeBSD Foundation. +.\" +.\" 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 June 11, 2018 +.Dt MUGE 4 +.Os +.Sh NAME +.Nm muge +.Nd "Microchip LAN78xx USB Gigabit Ethernet driver" +.Sh SYNOPSIS +To load the driver as a module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_muge_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +device driver provides support for USB Gigabit Ethernet adapters based on +Microchip's LAN78xx and LAN7515 chipsets. +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports Microchip USB Gigabit Ethernet interfaces, including: +.Pp +.Bl -bullet -compact +.It +Microchip LAN7800 USB 3.1 Gigabit Ethernet controller with PHY +.It +Microchip LAN7850 USB 2.0 Gigabit Ethernet controller with PHY +.It +Microchip LAN7515 USB 2 hub and Gigabit Ethernet controller with PHY +.El +.Sh SEE ALSO +.Xr arp 4 , +.Xr miibus 4 , +.Xr usb 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 12.0 . diff --git a/static/freebsd/man4/multicast.4 b/static/freebsd/man4/multicast.4 new file mode 100644 index 00000000..84c6c5c4 --- /dev/null +++ b/static/freebsd/man4/multicast.4 @@ -0,0 +1,1027 @@ +.\" Copyright (c) 2001-2003 International Computer Science Institute +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining a +.\" copy of this software and associated documentation files (the "Software"), +.\" to deal in the Software without restriction, including without limitation +.\" the rights to use, copy, modify, merge, publish, distribute, sublicense, +.\" and/or sell copies of the Software, and to permit persons to whom the +.\" Software is furnished to do so, subject to the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included in +.\" all copies or substantial portions of the Software. +.\" +.\" The names and trademarks of copyright holders may not be used in +.\" advertising or publicity pertaining to the software without specific +.\" prior permission. Title to copyright in this software and any associated +.\" documentation will at all times remain with the copyright holders. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +.\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +.\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +.\" AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +.\" LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +.\" FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +.\" DEALINGS IN THE SOFTWARE. +.\" +.Dd February 13, 2026 +.Dt MULTICAST 4 +.Os +.\" +.Sh NAME +.Nm multicast +.Nd Multicast Routing +.\" +.Sh SYNOPSIS +.Cd "options MROUTING" +.Pp +.In sys/types.h +.In sys/socket.h +.In netinet/in.h +.In netinet/ip_mroute.h +.In netinet6/ip6_mroute.h +.Ft int +.Fn getsockopt "int s" IPPROTO_IP MRT_INIT "void *optval" "socklen_t *optlen" +.Ft int +.Fn setsockopt "int s" IPPROTO_IP MRT_INIT "const void *optval" "socklen_t optlen" +.Ft int +.Fn getsockopt "int s" IPPROTO_IPV6 MRT6_INIT "void *optval" "socklen_t *optlen" +.Ft int +.Fn setsockopt "int s" IPPROTO_IPV6 MRT6_INIT "const void *optval" "socklen_t optlen" +.Sh DESCRIPTION +.Tn "Multicast routing" +is used to efficiently propagate data +packets to a set of multicast listeners in multipoint networks. +If unicast is used to replicate the data to all listeners, +then some of the network links may carry multiple copies of the same +data packets. +With multicast routing, the overhead is reduced to one copy +(at most) per network link. +.Pp +All multicast-capable routers must run a common multicast routing +protocol. +It is recommended that either +Protocol Independent Multicast - Sparse Mode (PIM-SM), +or Protocol Independent Multicast - Dense Mode (PIM-DM) +are used, as these are now the generally accepted protocols +in the Internet community. +The +.Sx HISTORY +section discusses previous multicast routing protocols. +.Pp +To start multicast routing, +the user must enable multicast forwarding in the kernel +(see +.Sx SYNOPSIS +about the kernel configuration options), +and must run a multicast routing capable user-level process. +From developer's point of view, +the programming guide described in the +.Sx "Programming Guide" +section should be used to control the multicast forwarding in the kernel. +.\" +.Ss Programming Guide +This section provides information about the basic multicast routing API. +The so-called +.Dq advanced multicast API +is described in the +.Sx "Advanced Multicast API Programming Guide" +section. +.Pp +First, a multicast routing socket must be open. +That socket would be used +to control the multicast forwarding in the kernel. +Note that most operations below require certain privilege +(i.e., root privilege): +.Bd -literal +/* IPv4 */ +int mrouter_s4; +mrouter_s4 = socket(AF_INET, SOCK_RAW, IPPROTO_IGMP); +.Ed +.Bd -literal +int mrouter_s6; +mrouter_s6 = socket(AF_INET6, SOCK_RAW, IPPROTO_ICMPV6); +.Ed +.Pp +Note that if the router needs to open an IGMP or ICMPv6 socket +(in case of IPv4 and IPv6 respectively) +for sending or receiving of IGMP or MLD multicast group membership messages, +then the same +.Va mrouter_s4 +or +.Va mrouter_s6 +sockets should be used +for sending and receiving respectively IGMP or MLD messages. +In case of +.Bx Ns +-derived kernel, it may be possible to open separate sockets +for IGMP or MLD messages only. +However, some other kernels (e.g., +.Tn Linux ) +require that the multicast +routing socket must be used for sending and receiving of IGMP or MLD +messages. +Therefore, for portability reason the multicast +routing socket should be reused for IGMP and MLD messages as well. +.Pp +After the multicast routing socket is open, it can be used to enable +multicast forwarding in the kernel: +.Bd -literal +/* IPv4 */ +int v = 1; +setsockopt(mrouter_s4, IPPROTO_IP, MRT_INIT, (void *)&v, sizeof(v)); +.Ed +.Bd -literal +/* IPv6 */ +int v = 1; +setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_INIT, (void *)&v, sizeof(v)); +\&... +/* If necessary, filter all ICMPv6 messages */ +struct icmp6_filter filter; +ICMP6_FILTER_SETBLOCKALL(&filter); +setsockopt(mrouter_s6, IPPROTO_ICMPV6, ICMP6_FILTER, (void *)&filter, + sizeof(filter)); +.Ed +.Pp +When applied to the multicast routing socket, the +.Dv MRT_DONE +and +.Dv MRT6_DONE +socket options disable multicast forwarding in the kernel: +.Bd -literal +/* IPv4 */ +int v = 1; +setsockopt(mrouter_s4, IPPROTO_IP, MRT_DONE, (void *)&v, sizeof(v)); +.Ed +.Bd -literal +/* IPv6 */ +int v = 1; +setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_DONE, (void *)&v, sizeof(v)); +.Ed +.Pp +Closing the socket has the same effect. +.Pp +After multicast forwarding is enabled, the multicast routing socket +can be used to enable PIM processing in the kernel if we are running PIM-SM or +PIM-DM +(see +.Xr pim 4 ) . +.Pp +For each network interface (e.g., physical or a virtual tunnel) +that would be used for multicast forwarding, a corresponding +multicast interface must be added to the kernel: +.Bd -literal +/* IPv4 */ +struct vifctl vc; +memset(&vc, 0, sizeof(vc)); +/* Assign all vifctl fields as appropriate */ +vc.vifc_vifi = vif_index; +vc.vifc_flags = vif_flags; +vc.vifc_threshold = min_ttl_threshold; +vc.vifc_rate_limit = 0; +memcpy(&vc.vifc_lcl_addr, &vif_local_address, sizeof(vc.vifc_lcl_addr)); +setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_VIF, (void *)&vc, + sizeof(vc)); +.Ed +.Pp +The +.Va vif_index +must be unique per vif. +The +.Va vif_flags +contains the +.Dv VIFF_* +flags as defined in +.In netinet/ip_mroute.h . +The +.Dv VIFF_TUNNEL +flag is no longer supported by +.Fx . +Users who wish to forward multicast datagrams over a tunnel should consider +configuring a +.Xr gif 4 +or +.Xr gre 4 +tunnel and using it as a physical interface. +.Pp +The +.Va min_ttl_threshold +contains the minimum TTL a multicast data packet must have to be +forwarded on that vif. +Typically, it would have value of 1. +.Pp +The +.Va max_rate_limit +argument is no longer supported in +.Fx +and should be set to 0. +Users who wish to rate-limit multicast datagrams should consider the use of +.Xr dummynet 4 +or +.Xr altq 4 . +.Pp +The +.Va vif_local_address +contains the local IP address of the corresponding local interface. +The +.Va vif_remote_address +contains the remote IP address in case of DVMRP multicast tunnels. +.Bd -literal +/* IPv6 */ +struct mif6ctl mc; +memset(&mc, 0, sizeof(mc)); +/* Assign all mif6ctl fields as appropriate */ +mc.mif6c_mifi = mif_index; +mc.mif6c_flags = mif_flags; +mc.mif6c_pifi = pif_index; +setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_ADD_MIF, (void *)&mc, + sizeof(mc)); +.Ed +.Pp +The +.Va mif_index +must be unique per vif. +The +.Va mif_flags +contains the +.Dv MIFF_* +flags as defined in +.In netinet6/ip6_mroute.h . +The +.Va pif_index +is the physical interface index of the corresponding local interface. +.Pp +A multicast interface is deleted by: +.Bd -literal +/* IPv4 */ +vifi_t vifi = vif_index; +setsockopt(mrouter_s4, IPPROTO_IP, MRT_DEL_VIF, (void *)&vifi, + sizeof(vifi)); +.Ed +.Bd -literal +/* IPv6 */ +mifi_t mifi = mif_index; +setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_DEL_MIF, (void *)&mifi, + sizeof(mifi)); +.Ed +.Pp +After the multicast forwarding is enabled, and the multicast virtual +interfaces are +added, the kernel may deliver upcall messages (also called signals +later in this text) on the multicast routing socket that was open +earlier with +.Dv MRT_INIT +or +.Dv MRT6_INIT . +The IPv4 upcalls have +.Vt "struct igmpmsg" +header (see +.In netinet/ip_mroute.h ) +with field +.Va im_mbz +set to zero. +Note that this header follows the structure of +.Vt "struct ip" +with the protocol field +.Va ip_p +set to zero. +The IPv6 upcalls have +.Vt "struct mrt6msg" +header (see +.In netinet6/ip6_mroute.h ) +with field +.Va im6_mbz +set to zero. +Note that this header follows the structure of +.Vt "struct ip6_hdr" +with the next header field +.Va ip6_nxt +set to zero. +.Pp +The upcall header contains field +.Va im_msgtype +and +.Va im6_msgtype +with the type of the upcall +.Dv IGMPMSG_* +and +.Dv MRT6MSG_* +for IPv4 and IPv6 respectively. +The values of the rest of the upcall header fields +and the body of the upcall message depend on the particular upcall type. +.Pp +If the upcall message type is +.Dv IGMPMSG_NOCACHE +or +.Dv MRT6MSG_NOCACHE , +this is an indication that a multicast packet has reached the multicast +router, but the router has no forwarding state for that packet. +Typically, the upcall would be a signal for the multicast routing +user-level process to install the appropriate Multicast Forwarding +Cache (MFC) entry in the kernel. +.Pp +An MFC entry is added by: +.Bd -literal +/* IPv4 */ +struct mfcctl mc; +memset(&mc, 0, sizeof(mc)); +memcpy(&mc.mfcc_origin, &source_addr, sizeof(mc.mfcc_origin)); +memcpy(&mc.mfcc_mcastgrp, &group_addr, sizeof(mc.mfcc_mcastgrp)); +mc.mfcc_parent = iif_index; +for (i = 0; i < maxvifs; i++) + mc.mfcc_ttls[i] = oifs_ttl[i]; +setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_MFC, + (void *)&mc, sizeof(mc)); +.Ed +.Bd -literal +/* IPv6 */ +struct mf6cctl mc; +memset(&mc, 0, sizeof(mc)); +memcpy(&mc.mf6cc_origin, &source_addr, sizeof(mc.mf6cc_origin)); +memcpy(&mc.mf6cc_mcastgrp, &group_addr, sizeof(mf6cc_mcastgrp)); +mc.mf6cc_parent = iif_index; +for (i = 0; i < maxvifs; i++) + if (oifs_ttl[i] > 0) + IF_SET(i, &mc.mf6cc_ifset); +setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_ADD_MFC, + (void *)&mc, sizeof(mc)); +.Ed +.Pp +The +.Va source_addr +and +.Va group_addr +are the source and group address of the multicast packet (as set +in the upcall message). +The +.Va iif_index +is the virtual interface index of the multicast interface the multicast +packets for this specific source and group address should be received on. +The +.Va oifs_ttl[] +array contains the minimum TTL (per interface) a multicast packet +should have to be forwarded on an outgoing interface. +If the TTL value is zero, the corresponding interface is not included +in the set of outgoing interfaces. +Note that in case of IPv6 only the set of outgoing interfaces can +be specified. +.Pp +An MFC entry is deleted by: +.Bd -literal +/* IPv4 */ +struct mfcctl mc; +memset(&mc, 0, sizeof(mc)); +memcpy(&mc.mfcc_origin, &source_addr, sizeof(mc.mfcc_origin)); +memcpy(&mc.mfcc_mcastgrp, &group_addr, sizeof(mc.mfcc_mcastgrp)); +setsockopt(mrouter_s4, IPPROTO_IP, MRT_DEL_MFC, + (void *)&mc, sizeof(mc)); +.Ed +.Bd -literal +/* IPv6 */ +struct mf6cctl mc; +memset(&mc, 0, sizeof(mc)); +memcpy(&mc.mf6cc_origin, &source_addr, sizeof(mc.mf6cc_origin)); +memcpy(&mc.mf6cc_mcastgrp, &group_addr, sizeof(mf6cc_mcastgrp)); +setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_DEL_MFC, + (void *)&mc, sizeof(mc)); +.Ed +.Pp +The following method can be used to get various statistics per +installed MFC entry in the kernel (e.g., the number of forwarded +packets per source and group address): +.Bd -literal +/* IPv4 */ +struct sioc_sg_req sgreq; +memset(&sgreq, 0, sizeof(sgreq)); +memcpy(&sgreq.src, &source_addr, sizeof(sgreq.src)); +memcpy(&sgreq.grp, &group_addr, sizeof(sgreq.grp)); +ioctl(mrouter_s4, SIOCGETSGCNT, &sgreq); +.Ed +.Bd -literal +/* IPv6 */ +struct sioc_sg_req6 sgreq; +memset(&sgreq, 0, sizeof(sgreq)); +memcpy(&sgreq.src, &source_addr, sizeof(sgreq.src)); +memcpy(&sgreq.grp, &group_addr, sizeof(sgreq.grp)); +ioctl(mrouter_s6, SIOCGETSGCNT_IN6, &sgreq); +.Ed +.Pp +The following method can be used to get various statistics per +multicast virtual interface in the kernel (e.g., the number of forwarded +packets per interface): +.Bd -literal +/* IPv4 */ +struct sioc_vif_req vreq; +memset(&vreq, 0, sizeof(vreq)); +vreq.vifi = vif_index; +ioctl(mrouter_s4, SIOCGETVIFCNT, &vreq); +.Ed +.Bd -literal +/* IPv6 */ +struct sioc_mif_req6 mreq; +memset(&mreq, 0, sizeof(mreq)); +mreq.mifi = vif_index; +ioctl(mrouter_s6, SIOCGETMIFCNT_IN6, &mreq); +.Ed +.Ss Advanced Multicast API Programming Guide +If we want to add new features in the kernel, it becomes difficult +to preserve backward compatibility (binary and API), +and at the same time to allow user-level processes to take advantage of +the new features (if the kernel supports them). +.Pp +One of the mechanisms that allows us to preserve the backward +compatibility is a sort of negotiation +between the user-level process and the kernel: +.Bl -enum +.It +The user-level process tries to enable in the kernel the set of new +features (and the corresponding API) it would like to use. +.It +The kernel returns the (sub)set of features it knows about +and is willing to be enabled. +.It +The user-level process uses only that set of features +the kernel has agreed on. +.El +.\" +.Pp +To support backward compatibility, if the user-level process does not +ask for any new features, the kernel defaults to the basic +multicast API (see the +.Sx "Programming Guide" +section). +.\" XXX: edit as appropriate after the advanced multicast API is +.\" supported under IPv6 +Currently, the advanced multicast API exists only for IPv4; +in the future there will be IPv6 support as well. +.Pp +Below is a summary of the expandable API solution. +Note that all new options and structures are defined +in +.In netinet/ip_mroute.h +and +.In netinet6/ip6_mroute.h , +unless stated otherwise. +.Pp +The user-level process uses new +.Fn getsockopt Ns / Ns Fn setsockopt +options to +perform the API features negotiation with the kernel. +This negotiation must be performed right after the multicast routing +socket is open. +The set of desired/allowed features is stored in a bitset +(currently, in +.Vt uint32_t ; +i.e., maximum of 32 new features). +The new +.Fn getsockopt Ns / Ns Fn setsockopt +options are +.Dv MRT_API_SUPPORT +and +.Dv MRT_API_CONFIG . +Example: +.Bd -literal +uint32_t v; +getsockopt(sock, IPPROTO_IP, MRT_API_SUPPORT, (void *)&v, sizeof(v)); +.Ed +.Pp +would set in +.Va v +the pre-defined bits that the kernel API supports. +The eight least significant bits in +.Vt uint32_t +are same as the +eight possible flags +.Dv MRT_MFC_FLAGS_* +that can be used in +.Va mfcc_flags +as part of the new definition of +.Vt "struct mfcctl" +(see below about those flags), which leaves 24 flags for other new features. +The value returned by +.Fn getsockopt MRT_API_SUPPORT +is read-only; in other words, +.Fn setsockopt MRT_API_SUPPORT +would fail. +.Pp +To modify the API, and to set some specific feature in the kernel, then: +.Bd -literal +uint32_t v = MRT_MFC_FLAGS_DISABLE_WRONGVIF; +if (setsockopt(sock, IPPROTO_IP, MRT_API_CONFIG, (void *)&v, sizeof(v)) + != 0) { + return (ERROR); +} +if (v & MRT_MFC_FLAGS_DISABLE_WRONGVIF) + return (OK); /* Success */ +else + return (ERROR); +.Ed +.Pp +In other words, when +.Fn setsockopt MRT_API_CONFIG +is called, the +argument to it specifies the desired set of features to +be enabled in the API and the kernel. +The return value in +.Va v +is the actual (sub)set of features that were enabled in the kernel. +To obtain later the same set of features that were enabled, then: +.Bd -literal +getsockopt(sock, IPPROTO_IP, MRT_API_CONFIG, (void *)&v, sizeof(v)); +.Ed +.Pp +The set of enabled features is global. +In other words, +.Fn setsockopt MRT_API_CONFIG +should be called right after +.Fn setsockopt MRT_INIT . +.Pp +Currently, the following set of new features is defined: +.Bd -literal +#define MRT_MFC_FLAGS_DISABLE_WRONGVIF (1 << 0) /* disable WRONGVIF signals */ +#define MRT_MFC_FLAGS_BORDER_VIF (1 << 1) /* border vif */ +#define MRT_MFC_RP (1 << 8) /* enable RP address */ +#define MRT_MFC_BW_UPCALL (1 << 9) /* enable bw upcalls */ +.Ed +.\" .Pp +.\" In the future there might be: +.\" .Bd -literal +.\" #define MRT_MFC_GROUP_SPECIFIC (1 << 10) /* allow (*,G) MFC entries */ +.\" .Ed +.\" .Pp +.\" to allow (*,G) MFC entries (i.e., group-specific entries) in the kernel. +.\" For now this is left-out until it is clear whether +.\" (*,G) MFC support is the preferred solution instead of something more generic +.\" solution for example. +.\" +.\" 2. The newly defined struct mfcctl2. +.\" +.Pp +The advanced multicast API uses a newly defined +.Vt "struct mfcctl2" +instead of the traditional +.Vt "struct mfcctl" . +The original +.Vt "struct mfcctl" +is kept as is. +The new +.Vt "struct mfcctl2" +is: +.Bd -literal +/* + * The new argument structure for MRT_ADD_MFC and MRT_DEL_MFC overlays + * and extends the old struct mfcctl. + */ +struct mfcctl2 { + /* the mfcctl fields */ + struct in_addr mfcc_origin; /* ip origin of mcasts */ + struct in_addr mfcc_mcastgrp; /* multicast group associated*/ + vifi_t mfcc_parent; /* incoming vif */ + u_char mfcc_ttls[MAXVIFS];/* forwarding ttls on vifs */ + + /* extension fields */ + uint8_t mfcc_flags[MAXVIFS];/* the MRT_MFC_FLAGS_* flags*/ + struct in_addr mfcc_rp; /* the RP address */ +}; +.Ed +.Pp +The new fields are +.Va mfcc_flags[MAXVIFS] +and +.Va mfcc_rp . +Note that for compatibility reasons they are added at the end. +.Pp +The +.Va mfcc_flags[MAXVIFS] +field is used to set various flags per +interface per (S,G) entry. +Currently, the defined flags are: +.Bd -literal +#define MRT_MFC_FLAGS_DISABLE_WRONGVIF (1 << 0) /* disable WRONGVIF signals */ +#define MRT_MFC_FLAGS_BORDER_VIF (1 << 1) /* border vif */ +.Ed +.Pp +The +.Dv MRT_MFC_FLAGS_DISABLE_WRONGVIF +flag is used to explicitly disable the +.Dv IGMPMSG_WRONGVIF +kernel signal at the (S,G) granularity if a multicast data packet +arrives on the wrong interface. +Usually, this signal is used to +complete the shortest-path switch in case of PIM-SM multicast routing, +or to trigger a PIM assert message. +However, it should not be delivered for interfaces that are not in +the outgoing interface set, and that are not expecting to +become an incoming interface. +Hence, if the +.Dv MRT_MFC_FLAGS_DISABLE_WRONGVIF +flag is set for some of the +interfaces, then a data packet that arrives on that interface for +that MFC entry will NOT trigger a WRONGVIF signal. +If that flag is not set, then a signal is triggered (the default action). +.Pp +The +.Dv MRT_MFC_FLAGS_BORDER_VIF +flag is used to specify whether the Border-bit in PIM +Register messages should be set (in case when the Register encapsulation +is performed inside the kernel). +If it is set for the special PIM Register kernel virtual interface +(see +.Xr pim 4 ) , +the Border-bit in the Register messages sent to the RP will be set. +.Pp +The remaining six bits are reserved for future usage. +.Pp +The +.Va mfcc_rp +field is used to specify the RP address (in case of PIM-SM multicast routing) +for a multicast +group G if we want to perform kernel-level PIM Register encapsulation. +The +.Va mfcc_rp +field is used only if the +.Dv MRT_MFC_RP +advanced API flag/capability has been successfully set by +.Fn setsockopt MRT_API_CONFIG . +.Pp +.\" +.\" 3. Kernel-level PIM Register encapsulation +.\" +If the +.Dv MRT_MFC_RP +flag was successfully set by +.Fn setsockopt MRT_API_CONFIG , +then the kernel will attempt to perform +the PIM Register encapsulation itself instead of sending the +multicast data packets to user level (inside +.Dv IGMPMSG_WHOLEPKT +upcalls) for user-level encapsulation. +The RP address would be taken from the +.Va mfcc_rp +field +inside the new +.Vt "struct mfcctl2" . +However, even if the +.Dv MRT_MFC_RP +flag was successfully set, if the +.Va mfcc_rp +field was set to +.Dv INADDR_ANY , +then the +kernel will still deliver an +.Dv IGMPMSG_WHOLEPKT +upcall with the +multicast data packet to the user-level process. +.Pp +In addition, if the multicast data packet is too large to fit within +a single IP packet after the PIM Register encapsulation (e.g., if +its size was on the order of 65500 bytes), the data packet will be +fragmented, and then each of the fragments will be encapsulated +separately. +Note that typically a multicast data packet can be that +large only if it was originated locally from the same hosts that +performs the encapsulation; otherwise the transmission of the +multicast data packet over Ethernet for example would have +fragmented it into much smaller pieces. +.\" +.\" Note that if this code is ported to IPv6, we may need the kernel to +.\" perform MTU discovery to the RP, and keep those discoveries inside +.\" the kernel so the encapsulating router may send back ICMP +.\" Fragmentation Required if the size of the multicast data packet is +.\" too large (see "Encapsulating data packets in the Register Tunnel" +.\" in Section 4.4.1 in the PIM-SM spec +.\" draft-ietf-pim-sm-v2-new-05.{txt,ps}). +.\" For IPv4 we may be able to get away without it, but for IPv6 we need +.\" that. +.\" +.\" 4. Mechanism for "multicast bandwidth monitoring and upcalls". +.\" +.Pp +Typically, a multicast routing user-level process would need to know the +forwarding bandwidth for some data flow. +For example, the multicast routing process may want to timeout idle MFC +entries, or in case of PIM-SM it can initiate (S,G) shortest-path switch if +the bandwidth rate is above a threshold for example. +.Pp +The original solution for measuring the bandwidth of a dataflow was +that a user-level process would periodically +query the kernel about the number of forwarded packets/bytes per +(S,G), and then based on those numbers it would estimate whether a source +has been idle, or whether the source's transmission bandwidth is above a +threshold. +That solution is far from being scalable, hence the need for a new +mechanism for bandwidth monitoring. +.Pp +Below is a description of the bandwidth monitoring mechanism. +.Bl -bullet +.It +If the bandwidth of a data flow satisfies some pre-defined filter, +the kernel delivers an upcall on the multicast routing socket +to the multicast routing process that has installed that filter. +.It +The bandwidth-upcall filters are installed per (S,G). +There can be +more than one filter per (S,G). +.It +Instead of supporting all possible comparison operations +(i.e., < <= == != > >= ), there is support only for the +<= and >= operations, +because this makes the kernel-level implementation simpler, +and because practically we need only those two. +Further, the missing operations can be simulated by secondary +user-level filtering of those <= and >= filters. +For example, to simulate !=, then we need to install filter +.Dq bw <= 0xffffffff , +and after an +upcall is received, we need to check whether +.Dq measured_bw != expected_bw . +.It +The bandwidth-upcall mechanism is enabled by +.Fn setsockopt MRT_API_CONFIG +for the +.Dv MRT_MFC_BW_UPCALL +flag. +.It +The bandwidth-upcall filters are added/deleted by the new +.Fn setsockopt MRT_ADD_BW_UPCALL +and +.Fn setsockopt MRT_DEL_BW_UPCALL +respectively (with the appropriate +.Vt "struct bw_upcall" +argument of course). +.El +.Pp +From application point of view, a developer needs to know about +the following: +.Bd -literal +/* + * Structure for installing or delivering an upcall if the + * measured bandwidth is above or below a threshold. + * + * User programs (e.g. daemons) may have a need to know when the + * bandwidth used by some data flow is above or below some threshold. + * This interface allows the userland to specify the threshold (in + * bytes and/or packets) and the measurement interval. Flows are + * all packet with the same source and destination IP address. + * At the moment the code is only used for multicast destinations + * but there is nothing that prevents its use for unicast. + * + * The measurement interval cannot be shorter than some Tmin (currently, 3s). + * The threshold is set in packets and/or bytes per_interval. + * + * Measurement works as follows: + * + * For >= measurements: + * The first packet marks the start of a measurement interval. + * During an interval we count packets and bytes, and when we + * pass the threshold we deliver an upcall and we are done. + * The first packet after the end of the interval resets the + * count and restarts the measurement. + * + * For <= measurement: + * We start a timer to fire at the end of the interval, and + * then for each incoming packet we count packets and bytes. + * When the timer fires, we compare the value with the threshold, + * schedule an upcall if we are below, and restart the measurement + * (reschedule timer and zero counters). + */ + +struct bw_data { + struct timeval b_time; + uint64_t b_packets; + uint64_t b_bytes; +}; + +struct bw_upcall { + struct in_addr bu_src; /* source address */ + struct in_addr bu_dst; /* destination address */ + uint32_t bu_flags; /* misc flags (see below) */ +#define BW_UPCALL_UNIT_PACKETS (1 << 0) /* threshold (in packets) */ +#define BW_UPCALL_UNIT_BYTES (1 << 1) /* threshold (in bytes) */ +#define BW_UPCALL_GEQ (1 << 2) /* upcall if bw >= threshold */ +#define BW_UPCALL_LEQ (1 << 3) /* upcall if bw <= threshold */ +#define BW_UPCALL_DELETE_ALL (1 << 4) /* delete all upcalls for s,d*/ + struct bw_data bu_threshold; /* the bw threshold */ + struct bw_data bu_measured; /* the measured bw */ +}; + +/* max. number of upcalls to deliver together */ +#define BW_UPCALLS_MAX 128 +/* min. threshold time interval for bandwidth measurement */ +#define BW_UPCALL_THRESHOLD_INTERVAL_MIN_SEC 3 +#define BW_UPCALL_THRESHOLD_INTERVAL_MIN_USEC 0 +.Ed +.Pp +The +.Vt bw_upcall +structure is used as an argument to +.Fn setsockopt MRT_ADD_BW_UPCALL +and +.Fn setsockopt MRT_DEL_BW_UPCALL . +Each +.Fn setsockopt MRT_ADD_BW_UPCALL +installs a filter in the kernel +for the source and destination address in the +.Vt bw_upcall +argument, +and that filter will trigger an upcall according to the following +pseudo-algorithm: +.Bd -literal + if (bw_upcall_oper IS ">=") { + if (((bw_upcall_unit & PACKETS == PACKETS) && + (measured_packets >= threshold_packets)) || + ((bw_upcall_unit & BYTES == BYTES) && + (measured_bytes >= threshold_bytes))) + SEND_UPCALL("measured bandwidth is >= threshold"); + } + if (bw_upcall_oper IS "<=" && measured_interval >= threshold_interval) { + if (((bw_upcall_unit & PACKETS == PACKETS) && + (measured_packets <= threshold_packets)) || + ((bw_upcall_unit & BYTES == BYTES) && + (measured_bytes <= threshold_bytes))) + SEND_UPCALL("measured bandwidth is <= threshold"); + } +.Ed +.Pp +In the same +.Vt bw_upcall +the unit can be specified in both BYTES and PACKETS. +However, the GEQ and LEQ flags are mutually exclusive. +.Pp +Basically, an upcall is delivered if the measured bandwidth is >= or +<= the threshold bandwidth (within the specified measurement +interval). +For practical reasons, the smallest value for the measurement +interval is 3 seconds. +If smaller values are allowed, then the bandwidth +estimation may be less accurate, or the potentially very high frequency +of the generated upcalls may introduce too much overhead. +For the >= operation, the answer may be known before the end of +.Va threshold_interval , +therefore the upcall may be delivered earlier. +For the <= operation however, we must wait +until the threshold interval has expired to know the answer. +.Pp +Example of usage: +.Bd -literal +struct bw_upcall bw_upcall; +/* Assign all bw_upcall fields as appropriate */ +memset(&bw_upcall, 0, sizeof(bw_upcall)); +memcpy(&bw_upcall.bu_src, &source, sizeof(bw_upcall.bu_src)); +memcpy(&bw_upcall.bu_dst, &group, sizeof(bw_upcall.bu_dst)); +bw_upcall.bu_threshold.b_data = threshold_interval; +bw_upcall.bu_threshold.b_packets = threshold_packets; +bw_upcall.bu_threshold.b_bytes = threshold_bytes; +if (is_threshold_in_packets) + bw_upcall.bu_flags |= BW_UPCALL_UNIT_PACKETS; +if (is_threshold_in_bytes) + bw_upcall.bu_flags |= BW_UPCALL_UNIT_BYTES; +do { + if (is_geq_upcall) { + bw_upcall.bu_flags |= BW_UPCALL_GEQ; + break; + } + if (is_leq_upcall) { + bw_upcall.bu_flags |= BW_UPCALL_LEQ; + break; + } + return (ERROR); +} while (0); +setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_BW_UPCALL, + (void *)&bw_upcall, sizeof(bw_upcall)); +.Ed +.Pp +To delete a single filter, then use +.Dv MRT_DEL_BW_UPCALL , +and the fields of bw_upcall must be set +exactly same as when +.Dv MRT_ADD_BW_UPCALL +was called. +.Pp +To delete all bandwidth filters for a given (S,G), then +only the +.Va bu_src +and +.Va bu_dst +fields in +.Vt "struct bw_upcall" +need to be set, and then just set only the +.Dv BW_UPCALL_DELETE_ALL +flag inside field +.Va bw_upcall.bu_flags . +.Pp +The bandwidth upcalls are received by aggregating them in the new upcall +message: +.Bd -literal +#define IGMPMSG_BW_UPCALL 4 /* BW monitoring upcall */ +.Ed +.Pp +This message is an array of +.Vt "struct bw_upcall" +elements (up to +.Dv BW_UPCALLS_MAX += 128). +The upcalls are +delivered when there are 128 pending upcalls, or when 1 second has +expired since the previous upcall (whichever comes first). +In an +.Vt "struct upcall" +element, the +.Va bu_measured +field is filled-in to +indicate the particular measured values. +However, because of the way +the particular intervals are measured, the user should be careful how +.Va bu_measured.b_time +is used. +For example, if the +filter is installed to trigger an upcall if the number of packets +is >= 1, then +.Va bu_measured +may have a value of zero in the upcalls after the +first one, because the measured interval for >= filters is +.Dq clocked +by the forwarded packets. +Hence, this upcall mechanism should not be used for measuring +the exact value of the bandwidth of the forwarded data. +To measure the exact bandwidth, the user would need to +get the forwarded packets statistics with the +.Fn ioctl SIOCGETSGCNT +mechanism +(see the +.Sx Programming Guide +section) . +.Pp +Note that the upcalls for a filter are delivered until the specific +filter is deleted, but no more frequently than once per +.Va bu_threshold.b_time . +For example, if the filter is specified to +deliver a signal if bw >= 1 packet, the first packet will trigger a +signal, but the next upcall will be triggered no earlier than +.Va bu_threshold.b_time +after the previous upcall. +.\" +.Sh SEE ALSO +.Xr getsockopt 2 , +.Xr recvfrom 2 , +.Xr recvmsg 2 , +.Xr setsockopt 2 , +.Xr socket 2 , +.Xr sourcefilter 3 , +.Xr altq 4 , +.Xr dummynet 4 , +.Xr gif 4 , +.Xr gre 4 , +.Xr icmp6 4 , +.Xr igmp 4 , +.Xr inet 4 , +.Xr inet6 4 , +.Xr intro 4 , +.Xr ip 4 , +.Xr ip6 4 , +.Xr mld 4 , +.Xr pim 4 +.\" +.Sh HISTORY +The Distance Vector Multicast Routing Protocol (DVMRP) +was the first developed multicast routing protocol. +Later, other protocols such as Multicast Extensions to OSPF (MOSPF) +and Core Based Trees (CBT), were developed as well. +Routers at autonomous system boundaries may now exchange multicast +routes with peers via the Border Gateway Protocol (BGP). +Many other routing protocols are able to redistribute multicast routes +for use with +.Dv PIM-SM +and +.Dv PIM-DM . +.Sh AUTHORS +.An -nosplit +The original multicast code was written by +.An David Waitzman +(BBN Labs), +and later modified by the following individuals: +.An Steve Deering +(Stanford), +.An Mark J. Steiglitz +(Stanford), +.An Van Jacobson +(LBL), +.An Ajit Thyagarajan +(PARC), +.An Bill Fenner +(PARC). +The IPv6 multicast support was implemented by the KAME project +.Pq Pa https://www.kame.net , +and was based on the IPv4 multicast code. +The advanced multicast API and the multicast bandwidth +monitoring were implemented by +.An Pavlin Radoslavov +(ICSI) +in collaboration with +.An Chris Brown +(NextHop). +The IGMPv3 and MLDv2 multicast support was implemented by +.An Bruce Simpson . +.Pp +This manual page was written by +.An Pavlin Radoslavov +(ICSI). diff --git a/static/freebsd/man4/mvs.4 b/static/freebsd/man4/mvs.4 new file mode 100644 index 00000000..516a1ddc --- /dev/null +++ b/static/freebsd/man4/mvs.4 @@ -0,0 +1,169 @@ +.\" Copyright (c) 2009 Alexander Motin +.\" 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 March 23, 2015 +.Dt MVS 4 +.Os +.Sh NAME +.Nm mvs +.Nd Marvell Serial ATA Host Controller driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device pci" +.Cd "device scbus" +.Cd "device mvs" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +mvs_load="YES" +.Ed +.Pp +The following tunables are settable from the +.Xr loader 8 : +.Bl -ohang +.It Va hint.mvs. Ns Ar X Ns Va .msi +controls Message Signaled Interrupts (MSI) usage by the specified controller. +.It Va hint.mvs. Ns Ar X Ns Va .ccc +controls Command Completion Coalescing (CCC) usage by the specified controller. +Non-zero value enables CCC and defines maximum time (in us), request can wait +for interrupt. +CCC reduces number of context switches on systems with many parallel requests, +but it can decrease disk performance on some workloads due to additional +command latency. +.It Va hint.mvs. Ns Ar X Ns Va .cccc +defines number of completed commands for CCC, which trigger interrupt without +waiting for specified coalescing timeout. +.It Va hint.mvsch. Ns Ar X Ns Va .pm_level +controls SATA interface Power Management for the specified channel, +allowing some power to be saved at the cost of additional command +latency. +Possible values: +.Pp +.Bl -tag -width 4n -offset indent -compact +.It 0 +interface Power Management is disabled (default); +.It 1 +device is allowed to initiate PM state change, host is passive; +.It 4 +driver initiates PARTIAL PM state transition 1ms after port becomes idle; +.It 5 +driver initiates SLUMBER PM state transition 125ms after port becomes idle. +.El +.Pp +Note that interface Power Management is not compatible with +device presence detection. +A manual bus reset is needed on device hot-plug. +.It Va hint.mvsch. Ns Ar X Ns Va .sata_rev +setting to nonzero value limits maximum SATA revision (speed). +Values 1, 2 and 3 are respectively 1.5, 3 and 6Gbps. +.El +.Sh DESCRIPTION +This driver provides the +.Xr CAM 4 +subsystem with native access to the +.Tn SATA +ports of several generations (Gen-I/II/IIe) of Marvell SATA controllers. +Each SATA port found is represented to CAM as a separate bus with one +target, or, if HBA supports Port Multipliers (Gen-II/IIe), 16 targets. +Most of the bus-management details are handled by the SATA-specific +transport of CAM. +Connected ATA disks are handled by the ATA protocol disk peripheral driver +.Xr ada 4 . +ATAPI devices are handled by the SCSI protocol peripheral drivers +.Xr cd 4 , +.Xr da 4 , +.Xr sa 4 , +etc. +.Pp +Driver features include support for Serial ATA and ATAPI devices, +Port Multipliers (including FIS-based switching, when supported), +hardware command queues (up to 31 command per port), +Native Command Queuing, SATA interface Power Management, device hot-plug +and Message Signaled Interrupts. +.Sh HARDWARE +The +.Nm +driver supports the following controllers: +.Pp +Gen-I (SATA 1.5Gbps): +.Bl -bullet -compact -offset "xxxxxx" +.It +88SX5040 +.It +88SX5041 +.It +88SX5080 +.It +88SX5081 +.El +.Pp +Gen-II (SATA 3Gbps, NCQ, PMP): +.Bl -bullet -compact -offset "xxxxxx" +.It +88SX6040 +.It +88SX6041 (including Adaptec 1420SA) +.It +88SX6080 +.It +88SX6081 +.El +.Pp +Gen-IIe (SATA 3Gbps, NCQ, PMP with FBS): +.Bl -bullet -compact -offset "xxxxxx" +.It +88SX6042 +.It +88SX7042 (including Adaptec 1430SA) +.It +88F5182 SoC +.It +88F6281 SoC +.It +MV78100 SoC +.El +.Pp +Note, that this hardware supports command queueing and FIS-based switching +only for ATA DMA commands. +ATAPI and non-DMA ATA commands executed one by one for each port. +.Sh SEE ALSO +.Xr ada 4 , +.Xr ata 4 , +.Xr cam 4 , +.Xr cd 4 , +.Xr da 4 , +.Xr sa 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 8.1 . +.Sh AUTHORS +.An Alexander Motin Aq Mt mav@FreeBSD.org diff --git a/static/freebsd/man4/mwl.4 b/static/freebsd/man4/mwl.4 new file mode 100644 index 00000000..9eecc080 --- /dev/null +++ b/static/freebsd/man4/mwl.4 @@ -0,0 +1,191 @@ +.\"- +.\" Copyright (c) 2009 Sam Leffler, Errno Consulting +.\" 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, +.\" without modification. +.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer +.\" similar to the "NO WARRANTY" disclaimer below ("Disclaimer") and any +.\" redistribution must be conditioned upon including a substantially +.\" similar Disclaimer requirement for further binary redistribution. +.\" +.\" NO WARRANTY +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTIBILITY +.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL +.\" THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR 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 DAMAGES. +.\"/ +.Dd July 8, 2009 +.Dt MWL 4 +.Os +.Sh NAME +.Nm mwl +.Nd "Marvell 88W8363 IEEE 802.11n wireless network driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device mwl" +.Cd "device mwlfw" +.Cd "device wlan" +.Cd "device firmware" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_mwl_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for IEEE 802.11n wireless network adapters based on +Marvell 88W8363 parts. +PCI and/or CardBus interfaces are supported. +.Pp +This driver requires the firmware built with the +.Nm mwlfw +module to work. +Normally this module is loaded on demand by the driver but it may +also be compiled into the kernel. +.Pp +Supported features include 802.11n, power management, BSS, MBSS, +and host-based access point operation modes. +All host/device interaction is via DMA. +.Pp +The +.Nm +driver encapsulates IP and ARP traffic as 802.11 frames, however +it can receive either 802.11 or 802.3 frames. +Devices support 802.11n, 802.11a, 802.11g, and 802.11b operation with +transmit speeds appropriate to each. +The actual transmit speed used is dependent on signal quality and the +.Dq "rate control" +algorithm implemented in the firmware. +All chips have hardware support for WEP, +AES-CCM, TKIP, and Michael cryptographic operations. +.Pp +The driver supports +.Cm station , +.Cm hostap , +.Cm mesh , +and +.Cm wds +mode operation. +Multiple +.Cm hostap +virtual interfaces may be configured for simultaneous use. +When multiple interfaces are configured each may have a separate +mac address that is formed by setting the U/L bits in the mac +address assigned to the underlying device. +Any number of +.Cm wds +virtual interfaces may be configured together with +.Cm hostap +interfaces. +Multiple +.Cm station +interfaces may be operated together with +.Cm hostap +interfaces to construct a wireless repeater device. +For more information on configuring this device, see +.Xr ifconfig 8 . +.Pp +Devices supported by the +.Nm +driver come in either Cardbus or mini-PCI packages. +Wireless cards in Cardbus slots may be inserted and ejected on the fly. +.Sh EXAMPLES +Join an existing BSS network (ie: connect to an access point): +.Bd -literal -offset indent +ifconfig wlan create wlandev mwl0 inet 192.168.0.20 \e + netmask 0xffffff00" +.Ed +.Pp +Join a specific BSS network with network name +.Dq Li my_net : +.Bd -literal -offset indent +ifconfig wlan create wlandev mwl0 inet 192.168.0.20 \e + netmask 0xffffff00 ssid my_net" +.Ed +.Pp +Join a specific BSS network with WEP encryption: +.Bd -literal -offset indent +ifconfig wlan0 create wlandev mwl0 +ifconfig wlan0 inet 192.168.0.20 netmask 0xffffff00 ssid my_net \e + wepmode on wepkey 0x8736639624 +.Ed +.Pp +Create an 802.11g host-based access point: +.Bd -literal -offset indent +ifconfig wlan0 create wlandev mwl0 wlanmode hostap +ifconfig wlan0 inet 192.168.0.10 netmask 0xffffff00 ssid my_ap \e + mode 11g +.Ed +.Pp +Create an 802.11a mesh station: +.Bd -literal -offset indent +ifconfig wlan0 create wlandev mwl0 wlanmode mesh +ifconfig wlan0 meshid my_mesh mode 11a inet 192.168.0.10/24 +.Ed +.Pp +Create two virtual 802.11a host-based access points, one +with WEP enabled and one with no security, and bridge them to +the fxp0 (wired) device: +.Bd -literal -offset indent +ifconfig wlan0 create wlandev mwl0 wlanmode hostap \e + ssid paying-customers wepmode on wepkey 0x1234567890 \e + mode 11a up +ifconfig wlan1 create wlandev mwl0 wlanmode hostap bssid \e + ssid freeloaders up +ifconfig bridge0 create addm wlan0 addm wlan1 addm fxp0 up +.Ed +.Sh DIAGNOSTICS +.Bl -diag +.It "mwl%d: unable to setup builtin firmware" +There was a problem downloading and/or setting up the firmware. +The device is not usable. +.It "mwl%d: failed to setup descriptors: %d" +There was a problem setting up the DMA data structures. +This typically is caused by not being able to allocate contiguous memory. +.It "mwl%d: transmit timeout" +A frame dispatched to the hardware for transmission did not complete in time. +This should not happen. +.It "mwl%d: device not present" +A cardbus device was ejected while active; the request to the firmware +was not completed. +.El +.Sh SEE ALSO +.Xr cardbus 4 , +.Xr intro 4 , +.Xr mwlfw 4 , +.Xr pci 4 , +.Xr wlan 4 , +.Xr wlan_ccmp 4 , +.Xr wlan_tkip 4 , +.Xr wlan_wep 4 , +.Xr wlan_xauth 4 , +.Xr hostapd 8 , +.Xr ifconfig 8 , +.Xr wpa_supplicant 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 8.0 . +.Sh BUGS +The driver does not support power-save operation in station mode; +consequently power use is suboptimal (e.g. on a laptop). diff --git a/static/freebsd/man4/mwlfw.4 b/static/freebsd/man4/mwlfw.4 new file mode 100644 index 00000000..e6fdc955 --- /dev/null +++ b/static/freebsd/man4/mwlfw.4 @@ -0,0 +1,50 @@ +.\" Copyright (c) 2009 Sam Leffler, Errno Consulting +.\" 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. 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 June 9, 2009 +.Dt MWLFW 4 +.Os +.Sh NAME +.Nm mwlfw +.Nd "Firmware Module for Marvell 88W8363 Wireless driver" +.Sh SYNOPSIS +To compile this module into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device mwlfw" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +mwlfw_load="YES" +.Ed +.Sh DESCRIPTION +This module provides access to firmware sets for the +Marvell 88W8363 IEEE 802.11n wireless adapters. +It may be +statically linked into the kernel, or loaded as a module. +.Sh SEE ALSO +.Xr mwl 4 , +.Xr firmware 9 diff --git a/static/freebsd/man4/mx25l.4 b/static/freebsd/man4/mx25l.4 new file mode 100644 index 00000000..a48b153e --- /dev/null +++ b/static/freebsd/man4/mx25l.4 @@ -0,0 +1,199 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2019 Ian Lepore +.\" +.\" 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 ``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 November 11, 2025 +.Dt MX25L 4 +.Os +.Sh NAME +.Nm mx25l +.Nd SpiFlash compatible non-volatile storage devices driver +.Sh SYNOPSIS +.Cd device mx25l +.Pp +In +.Xr loader.conf 5 : +.Cd mx25l_load="YES" +.Sh DESCRIPTION +The +.Nm +driver provides support for the family of non-volatile storage +devices known collectively as SpiFlash(tm). +SpiFlash chips typically have part numbers beginning with EN25, +IS25, MX25, S25, SST25, or W25. +.Pp +The +.Nm +driver uses opcode 0x9f to read the manufacturer and device ID +data to determine whether the device is supported. +The device ID is looked up using a table of data within the driver +which describes the attributes of each supported device, +such as block size, sector size, and device capacity. +When a supported device is found, the +.Nm +driver creates a disk device and makes it accessible at +.Pa /dev/flash/spi? . +The new disk device is then tasted by the available +.Xr geom 4 +modules as with any disk device. +.Sh HARDWARE +The +.Nm +driver supports the following spi flash memory devices: +.Pp +.Bl -bullet -compact +.It +AT25DF641 +.It +EN25F32 +.It +EN25P32 +.It +EN25P64 +.It +EN25Q32 +.It +EN25Q64 +.It +GD25Q64 +.It +M25P32 +.It +M25P64 +.It +MX25L1606E +.It +MX25LL128 +.It +MX25LL256 +.It +MX25LL32 +.It +MX25LL64 +.It +N25Q64 +.It +S25FL032 +.It +S25FL064 +.It +S25FL128 +.It +S25FL256S +.It +SST25VF010A +.It +SST25VF032B +.It +W25Q128 +.It +W25Q256 +.It +W25Q32 +.It +W25Q64 +.It +W25Q64BV +.It +W25X32 +.It +W25X64 +.El +.Sh FDT CONFIGURATION +On an +.Xr fdt 4 +based system, the +.Nm +device is defined as a slave device subnode +of the SPI bus controller node. +All properties documented in the +.Va spibus.txt +bindings document can be used with the +.Nm +device. +The most commonly-used ones are documented below. +.Pp +The following properties are required in the +.Nm +device subnode: +.Bl -tag -width indent +.It Va compatible +Must be the string "jedec,spi-nor". +.It Va reg +Chip select address of device. +.It Va spi-max-frequency +The maximum bus frequency to use when communicating with this slave device. +Actual bus speed may be lower, depending on the capabilities of the SPI +bus controller hardware. +.El +.Pp +The following properties are optional for the +.Nm +device subnode: +.Bl -tag -width indent +.It Va spi-cpha +Empty property indicating the slave device requires shifted clock +phase (CPHA) mode. +.It Va spi-cpol +Empty property indicating the slave device requires inverse clock +polarity (CPOL) mode. +.It Va spi-cs-high +Empty property indicating the slave device requires chip select active high. +.El +.Sh HINTS CONFIGURATION +On a +.Xr device.hints 5 +based system, such as +.Li MIPS , +these values are configurable for +.Nm : +.Bl -tag -width indent +.It Va hint.mx25l.%d.at +The spibus the +.Nm +instance is attached to. +.It Va hint.mx25l.%d.clock +The maximum bus frequency to use when communicating with this device. +Actual bus speed may be lower, depending on the capabilities of the SPI +bus controller hardware. +.It Va hint.mx25l.%d.cs +The chip-select number to assert when performing I/O for this device. +Set the high bit (1 << 31) to invert the logic level of the chip select line. +.It Va hint.mx25l.%d.mode +The SPI mode (0-3) to use when communicating with this device. +.El +.Sh FILES +.Bl -tag -width /dev/flash/spi? +.It Pa /dev/flash/spi? +Provides read/write access to the storage device. +.El +.Sh SEE ALSO +.Xr fdt 4 , +.Xr geom 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 8.0 . diff --git a/static/freebsd/man4/mxge.4 b/static/freebsd/man4/mxge.4 new file mode 100644 index 00000000..85cd79a4 --- /dev/null +++ b/static/freebsd/man4/mxge.4 @@ -0,0 +1,183 @@ +.\" Copyright (c) 2006, Myricom Inc +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright notice, +.\" this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Myricom Inc nor the names of its +.\" contributors may be used to endorse or promote products derived from +.\" this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 COPYRIGHT OWNER 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. +.\" +.\" * Other names and brands may be claimed as the property of others. +.\" +.Dd February 13, 2008 +.Dt MXGE 4 +.Os +.Sh NAME +.Nm mxge +.Nd "Myricom Myri10GE 10 Gigabit Ethernet adapter driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device firmware" +.Cd "device mxge" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_mxge_load="YES" +mxge_ethp_z8e_load="YES" +mxge_eth_z8e_load="YES" +mxge_rss_ethp_z8e_load="YES" +mxge_rss_eth_z8e_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for PCI Express 10 Gigabit Ethernet adapters based on +the Myricom LANai Z8E chip. +The driver supports Transmit/Receive checksum offload, +Jumbo Frames, TCP segmentation offload (TSO) as well +as Large Receive Offload (LRO). +For further hardware information, see +.Pa http://www.myri.com/ . +.Pp +For questions related to hardware requirements, +refer to the documentation supplied with your Myri10GE adapter. +All hardware requirements listed apply to use with +.Fx . +.Pp +Support for Jumbo Frames is provided via the interface MTU setting. +Selecting an MTU larger than 1500 bytes with the +.Xr ifconfig 8 +utility configures the adapter to receive and transmit Jumbo Frames. +The maximum MTU size for Jumbo Frames is 9000. +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports 10 Gigabit Ethernet adapters based on the +Myricom LANai Z8E chips: +.Pp +.Bl -bullet -compact +.It +Myricom 10GBase-CX4 (10G-PCIE-8A-C, 10G-PCIE-8AL-C) +.It +Myricom 10GBase-R (10G-PCIE-8A-R, 10G-PCIE-8AL-R) +.It +Myricom 10G XAUI over ribbon fiber (10G-PCIE-8A-Q, 10G-PCIE-8AL-Q) +.El +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width indent +.It Va hw.mxge.flow_control_enabled +Whether or not hardware flow control is enabled on the adapter. +The default value is 1. +.It Va hw.mxge.intr_coal_delay +This value delays the generation of all interrupts in units of +1 microsecond. +The default value is 30. +.It Va hw.mxge.skip_pio_read +This value determines whether or not the driver may omit doing a +PIO read in the interrupt handler which ensures that the interrupt +line has been deasserted when using xPIC interrupts. +A non-zero value +may result in lower CPU overhead, however it may also result in +spurious interrupts. +The default value is 0. +This tunable has no effect when the device is +using MSI or MSI-X interrupts. +.It Va hw.mxge.max_slices +This value determines the maximum number of slices the driver +will attempt to use. +The default value is 1. +A slice is comprised +of a set of receive queues and an associated interrupt thread. +When using multiple slices, the NIC hashes traffic to different slices +based on the value of +.Va hw.mxge.rss_hashtype . +Using multiple slices requires that your motherboard and Myri10GE NIC +both be capable of MSI-X. +Older Myri10GE NICs can be field upgraded to add +MSI-X using the "10G NIC Tool Kit" for FreeBSD which is available from +.Pa http://www.myri.com/scs/download-10g-tools.html . +.It Va hw.mxge.rss_hashtype +This value determines how incoming traffic is steered to different +slices. +This tunable is ignored when using just a single slice. +The legal values for this tunable are: +.Bl -tag -width "XXXX" +.It 1 +Hash on the source and destination IPv4 addresses. +.It 2 +Hash on source and destination IPv4 addresses and if the packet +is TCP, then also hash on the TCP source and destination ports. +.It 4 +Hash on the TCP or UDP source ports. +This is the default value. +.El +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "mxge%d: Unable to allocate bus resource: memory" +A fatal initialization error has occurred. +.It "mxge%d: Unable to allocate bus resource: interrupt" +A fatal initialization error has occurred. +.It "mxge%d: Could not find firmware image %s" +The appropriate firmware kld module was not installed. +This is a non-fatal initialization error, but will +result in running in a reduced performance mode. +.El +.Sh SUPPORT +For general information and support, +go to the Myricom support website at: +.Pa http://www.myri.com/scs/ . +.Pp +If an issue is identified with the released source code on the supported kernel +with a supported adapter, email the specific information related to the +issue to +.Aq Mt help@myri.com . +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 6.3 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Andrew Gallatin Aq Mt gallatin@FreeBSD.org . diff --git a/static/freebsd/man4/my.4 b/static/freebsd/man4/my.4 new file mode 100644 index 00000000..fc238631 --- /dev/null +++ b/static/freebsd/man4/my.4 @@ -0,0 +1,87 @@ +.\" Copyright (c) 2003 Hiten M. Pandya +.\" 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 AUTHORS AND ITS 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 THE 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 December 26, 2020 +.Dt MY 4 +.Os +.Sh NAME +.Nm my +.Nd "Myson Technology Ethernet PCI driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device my" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_my_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for various NICs based on the Myson chipset. +The Myson chipset is a variant of the DEC Tulip NIC chipset. +.Pp +The driver will work with almost any MII-compliant PHY, thus failure to +positively identify the chip is not a fatal error. +.Sh HARDWARE +The +.Nm +driver provides support for various NICs based on the Myson chipset. +Supported models include: +.Pp +.Bl -bullet -compact +.It +Myson MTD800 PCI Fast Ethernet chip +.It +Myson MTD803 PCI Fast Ethernet chip +.It +Myson MTD89X PCI Gigabit Ethernet chip +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr netintro 4 , +.Xr pci 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 4.6 . +.Sh AUTHORS +The +.Nm +driver was written by Myson Technology Inc. +.Pp +This manual page was written by +.An Hiten M. Pandya Aq Mt hmp@FreeBSD.org . +.Sh BUGS +The +.Nm +driver does not support Power Management Events (PME). diff --git a/static/freebsd/man4/nctgpio.4 b/static/freebsd/man4/nctgpio.4 new file mode 100644 index 00000000..84eb1ccb --- /dev/null +++ b/static/freebsd/man4/nctgpio.4 @@ -0,0 +1,54 @@ +.\" +.Dd Apr 18, 2023 +.Dt NCTGPIO 4 +.Os +.Sh NAME +.Nm nctgpio +.Nd GPIO controller on Nuvoton and Winbond Super I/Os +.Sh SYNOPSIS +.Cd "device gpio" +.Cd "device nctgpio" +.Cd "device superio" +.Sh DESCRIPTION +The +.Nm +is a driver for GPIO controller that can be found in Nuvoton and Winbond Super I/O chips. +.Pp +The +.Nm +driver supports the following chips: +.Pp +.Bl -bullet -compact +.It +Nuvoton NCT5104D +.It +Nuvoton NCT5104D (PC-Engines APU) +.It +Nuvoton NCT5104D (PC-Engines APU3) +.It +Nuvoton NCT5585D +.It +Nuvoton NCT6116D +.It +Nuvoton NCT6779 +.It +Nuvoton NCT6796D-E +.It +Winbond 83627DHG +.El + +.Sh SEE ALSO +.Xr gpio 3 , +.Xr gpio 4 , +.Xr gpioctl 8 +.Sh HISTORY +The driver first appeared in +.Fx 11.0 . +And the +manual page first appeared in +.Fx 14.0 . +.Sh AUTHORS +The driver was initially written by +.An Daniel Wyatt Aq Mt daniel@dewyatt.com . +This man page was written by +.An Stéphane Rochoy Aq Mt stephane.rochoy@stormshield.eu . diff --git a/static/freebsd/man4/ncthwm.4 b/static/freebsd/man4/ncthwm.4 new file mode 100644 index 00000000..5076a888 --- /dev/null +++ b/static/freebsd/man4/ncthwm.4 @@ -0,0 +1,52 @@ +.\" +.Dd Apr 18, 2023 +.Dt NCTHWM 4 +.Os +.Sh NAME +.Nm ncthwm +.Nd Hardware monitoring controller on Nuvoton Super I/Os +.Sh SYNOPSIS +.Cd "device ncthwm" +.Cd "device superio" +.Sh DESCRIPTION +The +.Nm +is a driver for hardware monitoring controller that can be found in Nuvoton +Super I/O chips. It expose fan speed via +.Xr sysctl 8 . + +.Pp +The +.Nm +driver supports the following chips: +.Pp +.Bl -bullet -compact +.It +Nuvoton NCT6779 +.It +Nuvoton NCT6796D-E +.El + +.Sh SYSCTL VARIABLES +These variables are available as read-only +.Xr sysctl 8 +variables: +.Bl -tag -width indent +.It Va dev.ncthwm.0.CPUFAN +CPU fan speed in RPM. +.It Va dev.ncthwm.0.SYSFAN +System fan speed in RPM. +.It Va dev.ncthwm.0.AUXFAN0 +AUX0 fan speed in RPM. +.It Va dev.ncthwm.0.AUXFAN1 +AUX1 fan speed in RPM. +.It Va dev.ncthwm.0.AUXFAN2 +AUX2 fan speed in RPM. +.El + +.Sh HISTORY +The driver first appeared in +.Fx 14.0 . +.Sh AUTHORS +The driver was initially written by +.An Stéphane Rochoy Aq Mt stephane.rochoy@stormshield.eu . diff --git a/static/freebsd/man4/nda.4 b/static/freebsd/man4/nda.4 new file mode 100644 index 00000000..e45b2905 --- /dev/null +++ b/static/freebsd/man4/nda.4 @@ -0,0 +1,215 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2017 Netflix, Inc. +.\" +.\" 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 October 2, 2025 +.Dt NDA 4 +.Os +.Sh NAME +.Nm nda +.Nd NVMe Direct Access device driver +.Sh SYNOPSIS +.Cd device nvme +.Cd device scbus +.Sh DESCRIPTION +The +.Nm +driver provides support for direct access devices, implementing the +.Tn NVMe +command protocol, that are attached to the system through a host adapter +supported by the CAM subsystem. +.Sh HARDWARE +The +.Nm +driver supports NVMe +.Pq Non-Volatile Memory Express +storage devices connected via PCIe or over NVMF +.Pq NVMe over Fabric +via the CAM subsystem. +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width 12 +.It Va hw.nvme.use_nvd +The +.Xr nvme 4 +driver will create +.Nm +device nodes for block storage when set to 0. +Create +.Xr nvd 4 +device nodes for block storage when set to 1. +See +.Xr nvd 4 +when set to 1. +.It Va kern.cam.nda.nvd_compat +When set to 1, +.Xr nvd 4 +aliases will be created for all +.Nm +devices, including partitions and other +.Xr geom 4 +providers that take their names from the disk's name. +.Xr nvd 4 +devices will not, however, be reported in the +.Va kern.disks +.Xr sysctl 8 . +.It Va kern.cam.nda.sort_io_queue +This variable determines whether the software queued entries are +sorted in LBA order or not. +Sorting is almost always a waste of time. +The default is to not sort. +.It Va kern.cam.nda.enable_biospeedup +This variable determines if the +.Nm +devices participate in the speedup protocol. +When the device participates in the speedup, then when the upper layers +send a +.Va BIO_SPEEDUP , +all current +.Va BIO_DELETE +requests not yet sent to the hardware are completed successfully immediate +without sending them to the hardware. +Used in low disk space scenarios when the filesystem encounters +a critical shortage and needs blocks immediately. +Since trims have maximum benefit when the LBA is unused for a long time, +skipping the trim when space is needed for immediate writes results in little to +no excess wear. +When participation is disabled, +.Va BIO_SPEEDUP +requests are ignored. +.It Va kern.cam.nda.max_trim +The maximum number of LBA ranges to be collected together for each DSM trims +send to the hardware. +Defaults to 256, which is the maximum number of ranges the protocol supports. +Sometimes poor trim performance can be mitigated by limiting the number of +ranges sent to the device. +This value must be between 1 and 256 inclusive. +.El +.Pp +The following report per-device settings, and are read-only unless +otherwise indicated. +Replace +.Va N +with the device unit number. +.Bl -tag -width 12 +.It Va kern.cam.nda.N.rotating +This variable reports whether the storage volume is spinning or +flash. +Its value is hard coded to 0 indicating flash. +.It Va kern.cam.nda.N.unmapped_io +This variable reports whether the +.Nm +driver accepts unmapped I/O for this unit. +.It Va kern.cam.nda.N.flags +This variable reports the current flags. +.Bl -tag -width 12 +.It Va OPEN +The device is open. +.It Va DIRTY +Set when a write to the drive is scheduled. +Cleared after flush commands. +.It Va SCTX_INIT +Internal flag set after +.Xr sysctl 8 +nodes have been created. +.El +.It Va kern.cam.nda.N.sort_io_queue +Same as the +.Va kern.cam.nda.sort_io_queue +tunable. +.It Va kern.cam.nda.N.trim_ticks +Writable. +When greater than zero, hold trims for up to this many ticks before sending +to the drive. +Sometimes waiting a little bit to collect more trims to send at one time +improves trim performance. +When 0, no delaying of trims are done. +.It Va kern.cam.nda.N.trim_goal +Writable. +When delaying a bit to collect multiple trims, send the accumulated DSM TRIM to +the drive. +.It Va kern.cam.nda.N.trim_lbas +Total number of LBAs that have been trimmed. +.It Va kern.cam.nda.N.trim_ranges +Total number of LBA ranges that have been trimmed. +.It Va kern.cam.nda.N.trim_count +Total number of trims sent to the hardware. +.It Va kern.cam.nda.N.deletes +Total number of +.Va BIO_DELETE +requests queued to the device. +.El +.Sh NAMESPACE MAPPING +Each +.Xr nvme 4 +drive has one or more namespaces associated with it. +One instance of the +.Nm +driver will be created for each of the namespaces on +the drive. +All the +.Nm +nodes for a +.Xr nvme 4 +device are at target 0. +However, the namespace ID maps to the CAM lun, as reported +in kernel messages and in the +.Va devlist +sub command of +.Xr camcontrol 8 . +.Pp +Namespaces are managed with the +.Va ns +sub command of +.Xr nvmecontrol 8 . +Not all drives support namespace management, +but all drives support at least one namespace. +Device nodes for +.Nm +will be created and destroyed dynamically as +namespaces are activated or detached. +.Sh FILES +.Bl -tag -width ".Pa /dev/nda*" -compact +.It Pa /dev/nda* +NVMe storage device nodes +.El +.Sh SEE ALSO +.Xr cam 4 , +.Xr geom 4 , +.Xr nvd 4 , +.Xr nvme 4 , +.Xr gpart 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 12.0 . +.Sh AUTHORS +.An Warner Losh Aq Mt imp@FreeBSD.org diff --git a/static/freebsd/man4/net80211.4 b/static/freebsd/man4/net80211.4 new file mode 100644 index 00000000..912a6c31 --- /dev/null +++ b/static/freebsd/man4/net80211.4 @@ -0,0 +1,1326 @@ +.\"- +.\" Copyright (c) 2009 Sam Leffler, Errno Consulting +.\" 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, +.\" without modification. +.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer +.\" similar to the "NO WARRANTY" disclaimer below ("Disclaimer") and any +.\" redistribution must be conditioned upon including a substantially +.\" similar Disclaimer requirement for further binary redistribution. +.\" +.\" NO WARRANTY +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTIBILITY +.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL +.\" THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR 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 DAMAGES. +.\" +.Dd August 7, 2020 +.Dt NET80211 4 +.Os +.Sh NAME +.Nm net80211 +.Nd standard interface to IEEE 802.11 devices +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In net/if.h +.In net/ethernet.h +.In net80211/ieee80211_ioctl.h +.Sh DESCRIPTION +This section describes the standard programming +interface to configure and retrieve status information +for IEEE 802.11 devices that depend on the +.Xr wlan 4 +module for operation. +The interface is via one +of the following +.Xr ioctl 2 +calls on a socket: +.Bl -tag -width ".Dv SIOCG80211" +.It Dv SIOCG80211 +Get configuration or status information. +.It Dv SIOCS80211 +Set configuration information. +.El +.Pp +These requests are made via a modified +.Vt ifreq +structure. +This structure is defined as follows: +.Bd -literal +struct ieee80211req { + char i_name[IFNAMSIZ]; /* if_name, e.g. "wi0" */ + uint16_t i_type; /* req type */ + int16_t i_val; /* Index or simple value */ + int16_t i_len; /* Index or simple value */ + void *i_data; /* Extra data */ +}; +.Ed +.Pp +Requests that are not supported by the underlying device return +-1 and set the global variable errno to +.Er EOPNOTSUPP . +.Dv SIOCG80211 +requests that return data to an application place small values in +.Va i_val +or in a user-specified buffer pointed to by +.Va i_data . +When an indirect buffer is used +.Va i_len +specifies how large the indirect buffer is and on return it is set by the +system to the actual amount of data returned. +.Dv SIOCS80211 +requests use a similar scheme with data passed to the system taken either +from +.Va i_val +or an indirect buffer pointed to by +.Va i_data . +.Pp +For +.Dv SIOCG80211 +the following values of +.Va i_type +are valid: +.Bl -tag -width indent +.It Dv IEEE80211_IOC_AMPDU +Return whether or not AMPDU is enabled in +.Va i_val . +AMPDU is an aggregation scheme that is part of the 802.11n specification +and is used only when operating on an HT channel. +The value returned is one of: +0 (AMPDU disabled), +1 (AMPDU enabled for transmit), +2 (AMPDU enabled for receive), +and +3 (AMPDU enabled for transmit and receive). +The 802.11n specification says a compliant station must receive AMPDU but +may not support transmitting AMPDU frames. +Disabling AMPDU receive is mainly useful for testing and working around bugs. +.It Dv IEEE80211_IOC_AMPDU_DENSITY +Return the minimum density for bursting AMPDU frames in +.Va i_val . +The value returned is one of: +0 (no time restriction), +1 (1/4 usec), +2 (1/2 usec), +3 (1 usec), +4 (2 usec), +5 (4 usec), +6 (8 usec), +and +7 (16 usec). +.It Dv IEEE80211_IOC_AMPDU_LIMIT +Return the limit on the size of AMPDU frames in +.Va i_val . +The value returned is one of: +0 (8 kilobytes), +1 (16 kilobytes), +2 (32 kilobytes), +and +3 (64 kilobytes). +.It Dv IEEE80211_IOC_AMSDU +Return whether or not AMSDU is enabled in +.Va i_val . +AMSDU is an aggregation scheme that is part of the 802.11n specification +and is used only when operating on an HT channel. +The value returned is one of: +0 (AMSDU disabled), +1 (AMSDU enabled for transmit), +2 (AMSDU enabled for receive), +and +3 (AMSDU enabled for transmit and receive). +The 802.11n specification says a compliant station must receive AMSDU but +may not support transmitting AMSDU frames. +Disabling AMSDU receive is mainly useful for testing and working around bugs. +.It Dv IEEE80211_IOC_AMSDU_LIMIT +Return the limit on the size of AMSDU frames in +.Va i_val . +The value returned is one of: +3839 (bytes) +and +7935 (bytes). +Note these values are specified by 802.11n; arbitrary values are not allowed. +.It Dv IEEE80211_IOC_APBRIDGE +Return whether AP bridging is enabled in +.Va i_val . +Normally packets sent between stations associated +to the same access point are delivered without going through system layers +that do packet filtering; when AP bridging is disabled packets are +passed up the system to be forwarded using some other mechanism. +This value will be non-zero when AP bridging is enabled and otherwise zero. +.It Dv IEEE80211_IOC_APPIE +Return an application information element via +.Va i_data . +Application IE's are maintained for many 802.11 frames; the +request must identify the frame to return an IE for in +.Va i_val . +For example, to retrieve the IE sent in each Beacon frame +.Va i_val +would be set to +.Va IEEE80211_FC0_SUBTYPE_BEACON | IEEE80211_FC0_TYPE_MGT . +If no information element is installed then +.Er EINVAL +is returned. +If the data buffer for returning data is too small to hold the information +element the value is truncated; this permits querying the presence of +data by requesting zero bytes of data be returned. +.It Dv IEEE80211_IOC_AUTHMODE +Return the current authentication mode in +.Va i_val . +Valid values are +.Dv IEEE80211_AUTH_NONE +(no authentication), +.Dv IEEE80211_AUTH_OPEN +(open authentication), +.Dv IEEE80211_AUTH_SHARED +(shared key authentication), +.Dv IEEE80211_AUTH_8021X +(802.1x only authentication), +and +.Dv IEEE80211_AUTH_WPA +(WPA/802.11i/802.1x authentication). +.It Dv IEEE80211_IOC_BEACON_INTERVAL +Return the time between Beacon frames (in TU) in +.Va i_val . +.It Dv IEEE80211_IOC_BGSCAN +Return whether background scanning is enabled in +.Va i_val . +When this value is non-zero and operating in station mode +the station will periodically leave +the current channel and scan for neighboring stations. +See also +.Dv IEEE80211_IOC_BGSCAN_IDLE +and +.Dv IEEE80211_IOC_BGSCAN_INTERVAL . +.It Dv IEEE80211_IOC_BGSCAN_IDLE +Return in +.Va i_val +the minimum time (msecs) a station must be idle +(i.e. not transmitting or receiving frames) +before it will do a background scan. +See also +.Dv IEEE80211_IOC_BGSCAN_INTERVAL . +.It Dv IEEE80211_IOC_BGSCAN_INTERVAL +Return in +.Va i_val +the minimum time (seconds) between background scan operations. +See also +.Dv IEEE80211_IOC_BGSCAN_IDLE . +.It Dv IEEE80211_IOC_BMISSTHRESHOLD +Return in +.Va i_val +the number of consecutive missed Beacon frames before the system will +attempt to roam to a different/better access point. +.It Dv IEEE80211_IOC_BSSID +Return the MAC address for the current BSS identifier via +.Va i_data . +When the interface is running, the bssid is either the value +configured locally (e.g. for an IBSS network started by the local station) +or the value adopted when joining an existing network. +For WDS interfaces this value is the address of the remote station. +When the interface is not running, the bssid returned is the desired +bssid, if any, that has been configured. +.It Dv IEEE80211_IOC_BURST +Return whether or not packet bursting is enabled in +.Va i_val . +If this value is non-zero then the system will try to send packets closely +spaced to improve throughput. +.It Dv IEEE80211_IOC_CHANINFO +Return the set of available channels via +.Va i_data . +Note this data should be used by user applications to map between +channel specifications (frequency and attributes) and IEEE channel numbers +as user applications may not have the necessary information to do +this directly (e.g. for 900MHz radios, operation in the Public Safety Band). +.It Dv IEEE80211_IOC_CHANLIST +Return the current list of usable channels via +.Va i_data . +The channel list is returned as a bit vector with bit N set to 1 if +IEEE channel number N is available for use. +.It Dv IEEE80211_IOC_CHANNEL +Return the IEEE channel number of the current channel in +.Va i_val . +Note this request is deprecated; use +.Dv IEEE80211_IOC_CURCHAN +instead. +.It Dv IEEE80211_IOC_COUNTERMEASURES +Return whether TKIP Countermeasures are enabled in +.Va i_val . +This value will be non-zero when Countermeasures are enabled and +otherwise zero. +.It Dv IEEE80211_IOC_CURCHAN +Return information for the current channel via +.Va i_data . +This information includes the IEEE channel number, the frequency, and +attributes that describe the operating constraints (e.g. Passive Scan, +DFS, usage restrictions). +.It Dv IEEE80211_IOC_DEVCAPS +Return device capabilities in the data buffer pointed at by +.Va i_data . +The buffer must be large enough to return the number of available +channels but otherwise may be made small to limit how much information +is returned. +.It Dv IEEE80211_IOC_DFS +Return whether or not Dynamic Frequency Selection (DFS) is enabled in +.Va i_val . +DFS embodies several facilities including detection of overlapping +radar signals, dynamic transmit power control, and channel selection +according to a least-congested criteria. +DFS support is mandatory for some 5GHz frequencies in certain +locales (e.g. ETSI). +By default DFS is enabled according to the regulatory definitions +and the current country code, regdomain, and channel. +.It Dv IEEE80211_IOC_DOTD +Return whether or not 802.11d support is enabled in +.Va i_val . +When 802.11d is enabled in station mode, Beacon frames that advertise +a country code different than the currently configured country code will +cause an event to be dispatched to user applications. +This event can be used by the station to adopt that country code and +operate according to the associated regulatory constraints. +When operating as an access point with 802.11d enabled the Beacon and +ProbeResponse frames transmitted will advertise the current regulatory +domain settings. +.It Dv IEEE80211_IOC_DOTH +Return whether 802.11h support is enabled in +.Va i_val . +When 802.11h is enabled Beacon and ProbeResponse frames will have +the SpectrumMgt bit set in the capabilities field and +country and power constraint information elements will be present. +802.11h support also includes handling Channel Switch Announcements (CSA) +which are a mechanism to coordinate channel changes by an access point. +By default 802.11h is enabled if the device is capable. +.It Dv IEEE80211_IOC_DROPUNENCRYPTED +Return, in +.Va i_val , +whether unencrypted packets transmit/received should be discarded. +This value will be zero if unencrypted packets will be accepted and +non-zero if they are to be discarded. +.It Dv IEEE80211_IOC_DTIM_PERIOD +Return the period (in beacon intervals) between DTIM events in +.Va i_val . +.It Dv IEEE80211_IOC_DWDS +Return, in +.Va i_val , +whether or not Dynamic WDS support is enabled. +Dynamic WDS is a facility by which packets may be tunneled over normal +Infrastructure BSS associations using 4-address (WDS) frames. +.It Dv IEEE80211_IOC_FF +Return, in +.Va i_val , +whether Atheros fast-frames support is enabled. +Fast-frames is a non-standard protocol extension that aggregates multiple +frames to improve throughput. +Note that enabling fast-frames support does not guarantee use; +the client and access point must negotiate its use. +.It Dv IEEE80211_IOC_FRAGTHRESHOLD +Return, in +.Va i_val , +the threshold (in bytes) for enabling fragmentation frames. +Packets larger than this value will automatically be split into multiple +fragmented frames that are sent one after the other. +.It Dv IEEE80211_IOC_GREENFIELD +Return, in +.Va i_val , +whether or not Greenfield preamble use is enabled. +This setting is meaningful only when operating with 802.11n on an HT channel. +.It Dv IEEE80211_IOC_HIDESSID +Return, in +.Va i_val , +whether SSID hiding/cloaking is enabled. +SSID hiding is only meaningful when operating as an access point. +When this is enabled Beacon frames do not include the SSID and +ProbeRequest frames are not answered unless they include the AP's SSID. +This value will be non-zero when SSID hiding is enabled and otherwise zero. +.It Dv IEEE80211_IOC_HTCOMPAT +Return, in +.Va i_val , +whether or not 802.11n compatibility support is enabled. +The 802.11n protocol specification went through several incompatible iterations. +Some vendors implemented 11n support to older specifications that +will not interoperate with a purely 11n-compliant station. +In particular the information elements included in management frames +for old devices are different. +When compatibility support is enabled both standard and compatible data +will be provided and/or accepted. +.It Dv IEEE80211_IOC_HTCONF +Return the setting for automatic promotion of HT channels in +.Va i_val . +Promotion happens when the system must select a channel and may choose +between legacy, HT20, and HT40 operation (e.g. when scanning). +Valid values are: +0 (do not promote, use legacy), +1 (promote to HT20), +and +2 (promote to HT40). +.It Dv IEEE80211_IOC_HTPROTMODE +Return, in +.Va i_val , +the technique used to protect HT frames in a mixed 802.11n network. +Valid values are: +.Dv IEEE80211_PROTMODE_OFF +(no protection enabled) +and +.Dv IEEE80211_PROTMODE_RTSCTS +(send RTS and wait for CTS). +.It Dv IEEE80211_IOC_HWMP_MAXHOPS +Return the maximum acceptable hop count in an HWMP path in +.Va i_val . +.It Dv IEEE80211_IOC_HWMP_ROOTMODE +Return the setting for Mesh root mode operation in +.Va i_val . +Valid values are: +.Dv IEEE80211_HWMP_ROOTMODE_DISABLED +(root mode is disabled), +.Dv IEEE80211_HWMP_ROOTMODE_NORMAL +(send broadcast Path Request frames), +.Dv IEEE80211_HWMP_ROOTMODE_PROACTIVE +(send broadcast Path Request frames and force replies) +and +.Dv IEEE80211_HWMP_ROOTMODE_RANN +(send broadcast Root Announcement (RANN) frames). +.It Dv IEEE80211_IOC_IC_NAME +Return the underlying hardware +.Xr device 9 +name in the buffer pointed to by +.Va i_data +and the name length including terminating NUL character in +.Va i_len . +If the buffer length is too small to hold the full name +.Er EINVAL +will be returned. +.It Dv IEEE80211_IOC_INACTIVITY +Return whether or not the system handles inactivity processing in +.Va i_val . +When inactivity processing is enabled the system will track stations +that have not transmitted frames and periodically probe them to +check if they are still present. +Stations that are inactive and do not respond to probes are dropped. +.It Dv IEEE80211_IOC_MACCMD +Return information about the state of the MAC address +access control list (ACL) system. +There are two requests supported: +.Dv IEEE80211_MACCMD_POLICY +(to retrieve the current policy in +.Va i_val ), +and +.Dv IEEE80211_MACCMD_LIST +to retrieve the list installed/active ACL's via +.Va i_data . +The +.Xr wlan_acl 4 +module must be installed and enabled or +.Er EINVAL +will be returned. +.It Dv IEEE80211_IOC_MESH_AP +Return whether or not Mesh AP support is enabled in +.Va i_val . +.It Dv IEEE80211_IOC_MESH_ID +Return the Mesh ID in the buffer pointed to by +.Va i_data . +.It Dv IEEE80211_IOC_MESH_FWRD +Return whether or not packet forwarding support is enabled in +.Va i_val . +.It Dv IEEE80211_IOC_MESH_PP_METRIC +Return the link metric protocol in the buffer pointed to by +.Va i_data . +.It Dv IEEE80211_IOC_MESH_PP_PATH +Return the path selection protocol in the buffer pointed to by +.Va i_data . +.It Dv IEEE80211_IOC_MESH_RTCMD +Return information about the state of the Mesh routing tables. +One request is supported: +.Dv IEEE80211_MESH_RTCMD_LIST +to retrieve the contents of the routing table in the buffer pointed to by +.Va i_data . +.It Dv IEEE80211_IOC_MESH_TTL +Return, in +.Va i_val , +the Mesh Time To Live (TTL) setting installed in packets +transmitted by this mesh node. +.It Dv IEEE80211_IOC_NUMSSIDS +Return the number of SSIDs supported in +.Va i_val . +.It Dv IEEE80211_IOC_NUMWEPKEYS +Return the number of WEP keys supported in +.Va i_val . +.It Dv IEEE80211_IOC_POWERSAVE +Return the current powersaving mode in +.Va i_val . +Valid values are +.Dv IEEE80211_POWERSAVE_OFF +(power save operation is disabled) +and +.Dv IEEE80211_POWERSAVE_ON +(power save operation is enabled). +.It Dv IEEE80211_IOC_POWERSAVESLEEP +Return the powersave sleep time in TU in +.Va i_val . +This value is also termed the listen interval and represents the maximum time +a station will sleep before waking to retrieve packets buffered by +an access point. +.It Dv IEEE80211_IOC_PRIVACY +Return the current MLME setting for PRIVACY in +.Va i_val . +When PRIVACY is enabled all data packets must be encrypted. +This value will be zero if PRIVACY is disabled and +non-zero when PRIVACY is enabled. +.It Dv IEEE80211_IOC_PROTMODE +Return the current 802.11g protection mode in +.Va i_val . +Protection is the mechanism used to safeguard 802.11b stations operating +on an 802.11g network. +Valid values are +.Dv IEEE80211_PROTMODE_OFF +(no protection enabled), +.Dv IEEE80211_PROTMODE_CTS +(send CTS to yourself), +and +.Dv IEEE80211_PROTMODE_RTSCTS +(send RTS and wait for CTS). +.It Dv IEEE80211_IOC_PUREG +Return whether ``pure 11g'' mode is enabled in +.Va i_val . +This setting is meaningful only for access point operation; +when non-zero, 802.11b stations will not be allowed to associate. +.It Dv IEEE80211_IOC_PUREN +Return whether ``pure 11n'' mode is enabled in +.Va i_val . +This setting is meaningful only for access point operation; +when non-zero, legacy (non-11n capable) stations will not be +allowed to associate. +.It Dv IEEE80211_IOC_REGDOMAIN +Return the regulatory state in the buffer pointed to by +.Va i_data . +.It Dv IEEE80211_IOC_RIFS +Return whether or not Reduced InterFrame Spacing (RIFS) is enabled in +.Va i_val . +This setting is meaningful only when operating with 802.11n on an HT channel. +.It Dv IEEE80211_IOC_ROAM +Return station roaming parameters in the buffer pointed to by +.Va i_data . +.It Dv IEEE80211_IOC_ROAMING +Return the current roaming mode in +.Va i_val . +Roaming mode specifies which entity controls operation of the MLME +state machine when operating as a station in an Infrastructure BSS. +Valid values are: +.Dv IEEE80211_ROAMING_DEVICE +(driver/firmware is in control), +.Dv IEEE80211_ROAMING_AUTO +(host 802.11 layer is in control), +and +.Dv IEEE80211_ROAMING_MANUAL +(application is in control). +.It Dv IEEE80211_IOC_RTSTHRESHOLD +Return the threshold (in bytes) for enabling transmission of RTS frames in +.Va i_val . +Packets larger than this value will automatically have an RTS frame +sent preceding it to reduce the likelihood of packet loss. +.It Dv IEEE80211_IOC_SCAN_RESULTS +Return the current contents of the scan cache in the data area pointed to by +.Va i_data . +.It Dv IEEE80211_IOC_SCANVALID +Return in +.Va i_val +how long (in seconds) results from a scan operation will be considered valid. +When scan results are no longer valid and they are needed (e.g. to roam) the +system will initiate a scan operation to replenish the scan cache. +.It Dv IEEE80211_IOC_SHORTGI +Return whether or not Short Guard Interval (SGI) is enabled in +.Va i_val . +Note SGI is only used when operating with 802.11n on an HT channel. +.It Dv IEEE80211_IOC_SMPS +Return the Spatial Multiplexing Power Save (SMPS) setting in +.Va i_val . +This setting is meaningful only when operating with 802.11n on an HT channel. +Valid values are: +.Dv IEEE80211_HTCAP_SMPS_DYNAMIC +(Dynamic SMPS is enabled), +.Dv IEEE80211_HTCAP_SMPS_ENA +(Static SMPS is enabled), +and +.Dv IEEE80211_HTCAP_SMPS_OFF +(SMPS is disabled). +.It Dv IEEE80211_IOC_SSID +Return the requested SSID in the buffer pointed to by +.Va i_data . +If +.Va i_val +is \(>= 0 then the request refers to the configured value for that slot. +Generally, 0 is the only valid value, but some interfaces support more +SSIDs. +.It Dv IEEE80211_IOC_STA_INFO +Return information about the current state of the specified station(s) via +.Va i_data . +The MAC address of a single station may be passed in or, if the broadcast +address is supplied, information about all stations will be returned. +If a single station is requested and the MAC address is unknown then +.Er ENOENT +will be returned. +.It Dv IEEE80211_IOC_STA_STATS +Return collected statistics for the specified station via +.Va i_data . +The MAC address of the desired station is passed in; if it is unknown +.Er ENOENT +will be returned. +.It Dv IEEE80211_IOC_STA_VLAN +Return any VLAN tag assigned to a station via +.Va i_data . +.It Dv IEEE80211_IOC_TDMA_SLOT +Return the slot number for the station in +.Va i_val . +Slot number zero is the master station in a TDMA network. +.It Dv IEEE80211_IOC_TDMA_SLOTCNT +Return the count of slots in the TDMA network in +.Va i_val . +.It Dv IEEE80211_IOC_TDMA_SLOTLEN +Return the length (in usecs) of the TDMA slot assigned to each +station in the network in +.Va i_val . +.It Dv IEEE80211_IOC_TDMA_BINTERVAL +Return the number of superframes between Beacon frames in +.Va i_val . +A TDMA network with N slots and slot length T has a superframe of NxT. +.It Dv IEEE80211_IOC_TSN +Return whether or not Transitional Security Network (TSN) is enabled in +.Va i_val . +.It Dv IEEE80211_IOC_TURBOP +Return whether Atheros Dynamic Turbo mode is enabled in +.Va i_val . +Dynamic Turbo mode is a non-standard protocol extension available only +on Atheros devices where channel width is dynamically +changed between 20MHz and 40MHz. +Note that enabling Dynamic Turbo mode support does not guarantee use; +both client and access point must use Atheros devices and support must +be enabled on both sides. +.It Dv IEEE80211_IOC_TXPARAMS +Return transmit parameters in the buffer pointed to by +.Va i_data . +.It Dv IEEE80211_IOC_TXPOWER +Return the transmit power limit in .5 dBm units in +.Va i_val . +This value represents the effective maximum and is calculated according to +the maximum power allowed by local regulations, any user-specified +power limit, and the maximum power the device is capable of. +.It Dv IEEE80211_IOC_TXPOWMAX +Return the user-specified maximum transmit power in .5 dBm units in +.Va i_val . +The maximum setting is applied after any regulatory cap. +.It Dv IEEE80211_IOC_WEP +Return the current WEP status in +.Va i_val . +Valid values are: +.Dv IEEE80211_WEP_ON +(enabled for all packets sent and received), +.Dv IEEE80211_WEP_OFF +(disabled), +and +.Dv IEEE80211_WEP_MIXED +(enabled for transmit and receive but also willing to receive +unencrypted frames). +This request is deprecated; use +.Dv IEEE80211_IOC_PRIVACY +and +.Dv IEEE80211_IOC_UNENCRYPTED +instead. +.It Dv IEEE80211_IOC_WEPKEY +Return the requested WEP key via +.Va i_data . +The key number is specified in +.Va i_val +and may be 0-3. +If the device does not support returning the WEP key or the user is not +root then the key may be returned as all zeros. +This request is deprecated in favor of +.Dv IEEE80211_IOC_WPAKEY . +.It Dv IEEE80211_IOC_WEPTXKEY +Return the number of the WEP key used for transmission in +.Va i_val . +.It Dv IEEE80211_IOC_WME +Return whether 802.11e/WME/WMM support is enabled in +.Va i_val . +This value will be non-zero when support is enabled and otherwise zero. +.It Dv IEEE80211_IOC_WME_CWMIN +Return the WME CWmin setting (log2) for the specified Access Class (AC) in +.Va i_val . +The AC is passed in through +.Va i_len +together with an optional IEEE80211_WMEPARAM_BSS flag to indicate if the +parameter for the BSS or the channel is desired. +If WME is not supported then +.Er EINVAL +will be returned. +.It Dv IEEE80211_IOC_WME_CWMAX +Return the WME CWmax setting (log2) for the specified Access Class (AC) in +.Va i_val . +See +.Dv IEEE80211_IOC_WME_CWMIN +above for more details. +.It Dv IEEE80211_IOC_WME_AIFS +Return the WME AIFS setting for the specified Access Class (AC) in +.Va i_val . +See +.Dv IEEE80211_IOC_WME_CWMIN +above for more details. +.It Dv IEEE80211_IOC_WME_TXOPLIMIT +Return the WME TxOpLimit (msec) for the specified Access Class (AC) in +.Va i_val . +See +.Dv IEEE80211_IOC_WME_CWMIN +above for more details. +.It Dv IEEE80211_IOC_WME_ACM +Return the WME Admission Control Mechanism (ACM) setting +for the specified Access Class (AC) in +.Va i_val . +This value is meaningful only for the BSS (not channel). +See +.Dv IEEE80211_IOC_WME_CWMIN +above for more details. +.It Dv IEEE80211_IOC_WME_ACKPOLICY +Return the WME ACK Policy setting +for the specified Access Class (AC) in +.Va i_val . +When this value is zero frames will be transmitted without waiting for +an Acknowledgement. +This value is meaningful only for the channel (not BSS). +See +.Dv IEEE80211_IOC_WME_CWMIN +above for more details. +.It Dv IEEE80211_IOC_WPA +Return the WPA configuration in +.Va i_val . +Valid values are +0 (WPA is not enabled), +1 (WPA1 is enabled), +2 (WPA2/802.11i is enabled), +and +3 (WPA1 and WPA2/802.11i are both enabled). +.It Dv IEEE80211_IOC_WPAIE +Return any WPA information element for an associated station via +.Va i_data . +The request passed in through +.Va i_data +identifies the MAC address of the desired station. +If an RSN (802.11i) element is present it is returned; otherwise any WPA +element is returned. +Note this request is deprecated; use +.Dv IEEE80211_IOC_WPAIE2 +instead. +.It Dv IEEE80211_IOC_WPAIE2 +Return any WPA information elements for an associated station via +.Va i_data . +The request passed in through +.Va i_data +identifies the MAC address of the desired station. +One or both of RSN (802.11i) and WPA elements may be returned. +.It Dv IEEE80211_IOC_WPAKEY +Return the requested cryptographic key in the buffer pointed to by +.Va i_data . +The key number is specified in +.Va i_val +and may be 0-3. +A key number of zero is used to retrieve a station's unicast cipher key +when operating with WPA enabled. +If the user is not root then the key data returned is all zeros. +.It Dv IEEE80211_IOC_WPS +Return whether or not Wi-FI Protected Setup (WPS) is enabled in +.Va i_val . +.El +.Pp +For +.Dv SIOCS80211 +the following values of +.Va i_type +are valid. +Note that changing a value on an interface that is running may +cause the interface to be +.Sq reset . +Resets may be handled without altering the state if the parameter +does not affect the MLME state (e.g. RTS threshold), but in some +cases the interface may need to scan for a new network or clear +state (including any associated stations); in that case the interface +is said to be +.Sq restarted +(it is equivalent to marking the interface down and back up). +The information below identifies whether changing a value affects the +state of a running interface. +.Bl -tag -width indent +.It Dv IEEE80211_IOC_ADDMAC +Add an entry to the MAC address Access Control List (ACL) database using +the value pointed to by +.Va i_data . +The +.Xr wlan_acl 4 +module must be installed and enabled or +.Er EINVAL +will be returned. +.It Dv IEEE80211_IOC_AMPDU +Set whether or not AMPDU is enabled for transmit and/or receive +using the value in +.Va i_val . +This request causes a running interface operating on an HT channel +to be reset. +See +.Dv IEEE80211_IOC_AMPDU +above for details. +.It Dv IEEE80211_IOC_AMPDU_DENSITY +Set the minimum density for bursting AMPDU frames to the value in +.Va i_val . +This request causes a running interface to be reset. +See +.Dv IEEE80211_IOC_AMPDU_DENSITY +above for details. +.It Dv IEEE80211_IOC_AMPDU_LIMIT +Set the limit on the size of AMPDU frames to the value in +.Va i_val . +This request causes a running interface to be reset. +See +.Dv IEEE80211_IOC_AMPDU_LIMIT +above for details. +.It Dv IEEE80211_IOC_AMSDU +Set whether or not AMSDU is enabled for transmit and/or receive +using the value in +.Va i_val . +This request causes a running interface operating on an HT channel +to be reset. +See +.Dv IEEE80211_IOC_AMSDU +above for details. +.It Dv IEEE80211_IOC_AMSDU_LIMIT +Set the limit on the size of AMSDU frames to the value in +.Va i_val . +This request causes a running interface to be reset. +See +.Dv IEEE80211_IOC_AMSDU_LIMIT +above for details. +.It Dv IEEE80211_IOC_APBRIDGE +Set whether AP bridging is enabled using the value in +.Va i_val . +See +.Dv IEEE80211_IOC_APBRIDGE +above for details. +.It Dv IEEE80211_IOC_APPIE +Set an application information element using the data pointed to by +.Va i_data . +This request causes a running interface to be restarted if the WPA +information element is changed. +See +.Dv IEEE80211_IOC_APPIE +above for details. +.It Dv IEEE80211_IOC_AUTHMODE +Set the current authentication mode using the value in +.Va i_val . +This request causes a running interface to be restarted. +See +.Dv IEEE80211_IOC_AUTHMODE +above for details. +This request causes a running interface to be restarted. +.It Dv IEEE80211_IOC_BEACON_INTERVAL +Set the time between Beacon frames (in TU) to the value in +.Va i_val . +This request causes a running interface to be restarted. +.It Dv IEEE80211_IOC_BGSCAN +Set whether background scanning is enabled using the value in +.Va i_val . +.It Dv IEEE80211_IOC_BGSCAN_IDLE +Set the minimum time (in msecs) a station must be idle +before it will do a background scan to the value in +.Va i_val . +.It Dv IEEE80211_IOC_BGSCAN_INTERVAL +Set the minimum time (seconds) between background scan operations to the value in +.Va i_val . +.It Dv IEEE80211_IOC_BMISSTHRESHOLD +Set the number of consecutive missed Beacon frames before the system will +attempt to roam to the value in +.Va i_val . +This request causes a running interface to be reset. +.It Dv IEEE80211_IOC_BSSID +Set the 802.11 MAC address for the desired BSS identifier according to +.Va i_data . +This request causes a running interface to be restarted. +.It Dv IEEE80211_IOC_BURST +Set whether or not packet bursting is enabled using the value in +.Va i_val . +This request causes a running interface to be reset. +.It Dv IEEE80211_IOC_CHANNEL +Set the desired/current channel to the value given by +.Va i_val . +This request causes a running interface to +immediately change to the specified channel if possible; +otherwise the interface will be restarted. +Note this request is deprecated; use +.Dv IEEE80211_IOC_CURCHAN +instead. +.It Dv IEEE80211_IOC_CHANLIST +Set the list of available channels using the channel list pointed to by +.Va i_data . +The channel list is a bit vector with bit N set to 1 if +IEEE channel number N is available for use. +The specified channel list is checked against the set of supported +channels and any channels not supported are silently ignored. +If the intersection of the channel list and the supported channels is empty +.Er EINVAL +is returned. +Note the current channel may be marked invalid after installing a +new channel list. +This request causes a running interface to be restarted. +.It Dv IEEE80211_IOC_COUNTERMEASURES +Set whether TKIP Countermeasures are enabled using the value in +.Va i_val . +This request can only be used when the authentication mode is set +WPA; otherwise +.Er EOPNOTSUPP +will be returned. +.It Dv IEEE80211_IOC_CURCHAN +Set the current channel using the information referenced by +.Va i_data . +This request causes a running interface to +immediately change to the specified channel if possible; +otherwise the interface will be restarted. +.It Dv IEEE80211_IOC_DELKEY +Delete the key specified by the information referenced by +.Va i_data . +.It Dv IEEE80211_IOC_DELMAC +Remove an entry in the MAC address Access Control List (ACL) database using +the value pointed to by +.Va i_data . +The +.Xr wlan_acl 4 +module must be installed and enabled or +.Er EINVAL +will be returned. +.It Dv IEEE80211_IOC_DFS +Set whether or not Dynamic Frequency Selection (DFS) is enabled +using the value in +.Va i_val . +This request will fail with +.Er EINVAL +if 802.11h support is not enabled. +See +.Dv IEEE80211_IOC_DFS +above for details. +.It Dv IEEE80211_IOC_DOTD +Set whether or not 802.11d support is enabled using the value in +.Va i_val . +This request causes a running interface to be restarted. +See +.Dv IEEE80211_IOC_DOTD +above for details. +.It Dv IEEE80211_IOC_DOTH +Return whether 802.11h support is enabled using the value in +.Va i_val . +See +.Dv IEEE80211_IOC_DOTH +above for details. +.It Dv IEEE80211_IOC_DROPUNENCRYPTED +Set whether unencrypted packets transmit/received should be discarded +using the value in +.Va i_val . +.It Dv IEEE80211_IOC_DTIM_PERIOD +Set the period (in beacon intervals) between DTIM events to the value in +.Va i_val . +This request causes a running interface to be restarted. +.It Dv IEEE80211_IOC_DWDS +Set whether or not Dynamic WDS support is enabled using the value in +.Va i_val . +See +.Dv IEEE80211_IOC_DWDS +above for details. +.It Dv IEEE80211_IOC_FF +Set whether Atheros fast-frames support is enabled using the value in +.Va i_val . +This request causes a running interface to be restarted. +See +.Dv IEEE80211_IOC_FF +above for details. +.It Dv IEEE80211_IOC_FRAGTHRESHOLD +Set the threshold (in bytes) for enabling fragmentation frames using the value in +.Va i_val . +This request causes a running interface to be reset. +See +.Dv IEEE80211_IOC_FRAGTHRESHOLD +above for details. +.It Dv IEEE80211_IOC_GREENFIELD +Set whether or not Greenfield preamble use is enabled using the value in +.Va i_val . +This request causes a running interface to be reset. +See +.Dv IEEE80211_IOC_GREENFIELD +above for details. +.It Dv IEEE80211_IOC_HIDESSID +Set whether SSID hiding/cloaking is enabled using the value in +.Va i_val . +This request causes a running interface to be reset. +See +.Dv IEEE80211_IOC_HIDESSID +above for details. +.It Dv IEEE80211_IOC_HTCOMPAT +Set whether or not 802.11n compatibility support is enabled using the value in +.Va i_val . +This request causes a running interface to be reset if operating on HT channel. +See +.Dv IEEE80211_IOC_HTCOMPAT +above for details. +.It Dv IEEE80211_IOC_HTCONF +Set automatic promotion of HT channels using the value in +.Va i_val . +This request causes a running interface to be restarted. +See +.Dv IEEE80211_IOC_HTCONF +above for details. +.It Dv IEEE80211_IOC_HTPROTMODE +Set the technique used to protect HT frames in a mixed 802.11n network +using the value in +.Va i_val . +This request causes a running interface to be reset. +See +.Dv IEEE80211_IOC_HTPROTMODE +above for details. +.It Dv IEEE80211_IOC_HWMP_MAXHOPS +Set the maximum acceptable hop count in an HWMP path according to +.Va i_val . +Values must be in the range [0-255]. +.It Dv IEEE80211_IOC_HWMP_ROOTMODE +Set the Mesh root mode operation according to +.Va i_val . +Valid values are +.Dv IEEE80211_HWMP_ROOTMODE_DISABLED +(root mode is disabled), +.Dv IEEE80211_HWMP_ROOTMODE_NORMAL +(send broadcast Path Request frames), +.Dv IEEE80211_HWMP_ROOTMODE_PROACTIVE +(send broadcast Path Request frames and force replies) +and +.Dv IEEE80211_HWMP_ROOTMODE_RANN +(send broadcast Root Announcement (RANN) frames). +.It Dv IEEE80211_IOC_INACTIVITY +Set whether or not the system handles inactivity processing using the value in +.Va i_val . +When inactivity processing is enabled the system will track stations +that have not transmitted frames and periodically probe them to +check if they are still present. +Stations that are inactive and do not respond to probes are dropped. +.It Dv IEEE80211_IOC_MACCMD +Change the state of the MAC address Access Control List (ACL) system. +There are several requests supported: +.Dv IEEE80211_MACCMD_POLICY_OPEN +(set the current policy to disable ACL use), +.Dv IEEE80211_MACCMD_POLICY_ALLOW +(set the current policy to allow only addresses listed in the database), +.Dv IEEE80211_MACCMD_POLICY_DENY +(set the current policy to deny addresses listed in the database), +.Dv IEEE80211_MACCMD_POLICY_RADUS +(set the current policy to enable use of a RADIUS backend), +.Dv IEEE80211_MACCMD_FLUSH +(flush all addresses from the database), +and +.Dv IEEE80211_MACCMD_DETACH +(detach the ACL subsystem, disabling it). +The +.Xr wlan_acl 4 +module must be installed or +.Er EINVAL +will be returned. +.It Dv IEEE80211_IOC_MESH_AP +Set whether or not Mesh AP support is enabled using +.Va i_val . +.It Dv IEEE80211_IOC_MESH_FWRD +Set whether or not packet forwarding support is enabled using +.Va i_val . +.It Dv IEEE80211_IOC_MESH_ID +Set the Mesh ID using the value pointed to by +.Va i_data . +A Mesh ID can be up to +.Dv IEEE80211_MESHID_LEN +bytes long. +.It Dv IEEE80211_IOC_MESH_PP_METRIC +Set the link metric protocol using the value pointed to by +.Va i_data . +.It Dv IEEE80211_IOC_MESH_PP_PATH +Set the path selection protocol using the value pointed to by +.Va i_data . +.It Dv IEEE80211_IOC_MESH_RTCMD +Manipulate the state of the Mesh routing tables. +Several requests are supported: +.Dv IEEE80211_MESH_RTCMD_FLUSH +(flush the contents of the routing table), +.Dv IEEE80211_MESH_RTCMD_ADD +(add an entry for the MAC address specified in +.Va i_data +and start the Peer discovery process), +and +.Dv IEEE80211_MESH_RTCMD_DELETE +(delete the entry corresponding to the MAC address specified in +.Va i_data ). +.It Dv IEEE80211_IOC_MESH_TTL +Set the Mesh Time To Live (TTL) setting installed in packets +transmitted by this mesh node using +.Va i_val . +.It Dv IEEE80211_IOC_MLME +Explicitly control the MLME state machine for a station using the +MLME request pointed to by +.Va i_data . +There are several MLME operations supported: +.Dv IEEE80211_MLME_ASSOC +(request association to an access point), +.Dv IEEE80211_MLME_DIASSOC +(diassociate the specified station), +.Dv IEEE80211_MLME_DEAUTH +(deauthenticate the specified station), +.Dv IEEE80211_MLME_AUHORIZE +(mark the specified station authorized to pass data frames), +.Dv IEEE80211_MLME_UNAUTHORIZE +(revoke the specified station's ability to pass data frames), +and +.Dv IEEE80211_MLME_AUTH +(request authentication to an access point). +Note when this facility is used for stations operating in infrastructure mode +the roaming mode should be set to manual. +.It Dv IEEE80211_IOC_POWERSAVE +Set the current powersaving mode to the value in +.Va i_val . +See +.Dv IEEE80211_IOC_POWERSAVE +above for valid values. +This request causes a running interface to be reset. +.It Dv IEEE80211_IOC_POWERSAVESLEEP +Set the powersave sleep time in TU to the value in +.Va i_val . +This request causes a running interface to be reset. +.It Dv IEEE80211_IOC_PRIVACY +Set the current MLME setting for PRIVACY using the value in +.Va i_val . +See +.Dv IEEE80211_IOC_PRIVACY +above for details. +.It Dv IEEE80211_IOC_PROTMODE +Set the current 802.11g protection mode to the value in +.Va i_val . +This request causes a running interface to be reset. +See +.Dv IEEE80211_IOC_PROTMODE +above for details. +This request causes a running interface to be reset. +.It Dv IEEE80211_IOC_PUREG +Set whether ``pure 11g'' mode is enabled using the value in +.Va i_val . +This request causes a running interface to be restarted. +See +.Dv IEEE80211_IOC_PUREG +above for details. +.It Dv IEEE80211_IOC_PUREN +Set whether ``pure 11n'' mode is enabled using the value in +.Va i_val . +This request causes a running interface to be restarted. +See +.Dv IEEE80211_IOC_PUREN +above for details. +.It Dv IEEE80211_IOC_REGDOMAIN +Set the regulatory state using the data referenced by +.Va i_data . +This request can only be issued when all interfaces cloned from the +underlying physical device are marked down; otherwise +.Er EBUSY +is returned. +Note the new regulatory data may invalidate any desired channel. +.It Dv IEEE80211_IOC_RIFS +Set whether or not Reduced InterFrame Spacing (RIFS) is enabled +using the value in +.Va i_val . +This setting is meaningful only when operating with 802.11n on an HT channel. +This request causes a running interface to be reset. +.It Dv IEEE80211_IOC_ROAM +Set station roaming parameters using the data pointed to by +.Va i_data . +.It Dv IEEE80211_IOC_ROAMING +Set the current roaming mode to the value in +.Va i_val . +See +.Dv IEEE80211_IOC_ROAMING +above for details. +.It Dv IEEE80211_IOC_RTSTHRESHOLD +Set the threshold (in bytes) for enabling transmission of RTS frames +to the value in +.Va i_val . +This request causes a running interface to be reset. +See +.Dv IEEE80211_IOC_RTSTHRESHOLD +above for details. +.It Dv IEEE80211_IOC_SCANVALID +Set the age (in seconds) that results from a scan operation will be +considered valid. +When scan results are no longer valid and they are needed (e.g. to roam) the +system will initiate a scan operation to replenish the scan cache. +.It Dv IEEE80211_IOC_SCAN_REQ +Request a scan operation using the parameters pointed to by +.Va i_val . +The underlying device must be running or +.Er ENXIO +will be returned. +Values for +.Va sr_duration , +.Va sr_mindwell , +and +.Va sr_maxdwell +shorter than 1 clock tick are rounded up to a tick. +If more SSID's are supplied than the system is capable of handling +the extra ones are silently ignored. +If a scan operation is already in progress the request will be +(silently) ignored. +.It Dv IEEE80211_IOC_SCAN_CANCEL +Cancel any pending/active scan operation. +.It Dv IEEE80211_IOC_SHORTGI +Set whether or not Short Guard Interval (SGI) is enabled using the value in +.Va i_val . +Note SGI is only used when operating on an HT (802.11n) channel. +This request causes a running interface to be reset. +.It Dv IEEE80211_IOC_SMPS +Set the Spatial Multiplexing Power Save (SMPS) setting to the value in +.Va i_val . +This request causes a running interface to be reset. +See +.Dv IEEE80211_IOC_SMPS +above for details. +.It Dv IEEE80211_IOC_SSID +Set the desired SSID using the value pointed to by +.Va i_data . +The string may be at most IEEE80211_NWID_LEN bytes. +This request causes a running interface to be restarted. +.It Dv IEEE80211_IOC_STA_STATS +Clear accumulated statistics for the specified station. +.It Dv IEEE80211_IOC_STA_VLAN +Set the VLAN tag for the specified station using the information pointed to by +.Va i_data . +.It Dv IEEE80211_IOC_TDMA_BINTERVAL +Set the interval between Beacon frames to the value in +.Va i_val . +Values must be positive. +This request causes a running interface to be reset. +.It Dv IEEE80211_IOC_TDMA_SLOT +Set the current TDMA slot to the value in +.Va i_val . +Values must be in the range [0-slotcnt]. +Slot 0 identifies the master in the TDMA network; if it running it will +immediately start sending Beacon frames. +.It Dv IEEE80211_IOC_TDMA_SLOTCNT +Set the number of slots in the TDMA network to the value in +.Va i_val . +This request causes a running interface to be reset. +.It Dv IEEE80211_IOC_TDMA_SLOTLEN +Set the length of the TDMA slot assigned to each station in the network +to the value in +.Va i_val . +Slot lengths must be in the range 200 usecs to 1024 milliseconds +(though values outside the range 1-200ms are unlikely to work well). +This request causes a running interface to be reset. +.It Dv IEEE80211_IOC_TSN +Set whether or not Transitional Security Network (TSN) is enabled +using the value in +.Va i_val . +.It Dv IEEE80211_IOC_TURBOP +Set whether Atheros Dynamic Turbo mode is enabled using the value in +.Va i_val . +This request causes a running interface to be restarted. +.It Dv IEEE80211_IOC_TXPARAMS +Set transmit parameters using the data pointed to be +.Va i_data . +This request causes a running interface to be restarted. +.It Dv IEEE80211_IOC_TXPOWER +Set the maximum transmit power limit in .5 dBm units to the value in +.Va i_val . +This request causes a running interface to be reset. +.It Dv IEEE80211_IOC_WEP +Set the current WEP mode to the value in +.Va i_val . +See +.Dv IEEE80211_IOC_WEP +above for valid values. +This request causes a running interface to be restarted. +Note this request is deprecated; use +.Dv IEEE80211_IOC_PRIVACY +and +.Dv IEEE80211_IOC_DROPUNENCRYPTED +instead. +.It Dv IEEE80211_IOC_WEPKEY +Set the WEP key indicated by +.Va i_val +using the data pointed to by +.Va i_data . +Note this request is deprecated; use +.Dv IEEE80211_IOC_WPAKEY +instead. +.It Dv IEEE80211_IOC_WEPTXKEY +Set the default transmit key used for transmission to the value in +.Va i_val . +.It Dv IEEE80211_IOC_WME +Set whether or not WME/WMM support is enabled using the value in +.Va i_val . +This request causes a running interface to be reset. +.It Dv IEEE80211_IOC_WME_ACKPOLICY +Set the WME ACK Policy for the Access Class (AC) specified in +.Va i_len +using the value in +.Va i_val . +.It Dv IEEE80211_IOC_WME_ACM +Set the WME Admission Control Mechanism for the Access Class (AC) specified in +.Va i_len +using the value in +.Va i_val . +.It Dv IEEE80211_IOC_WME_AIFS +Set the WME AIFS parameter for the Access Class (AC) specified in +.Va i_len +using the value in +.Va i_val . +.It Dv IEEE80211_IOC_WME_CWMAX +Set the WME CWmax parameter for the Access Class (AC) specified in +.Va i_len +using the value in +.Va i_val . +.It Dv IEEE80211_IOC_WME_CWMIN +Set the WME CWmin parameter for the Access Class (AC) specified in +.Va i_len +using the value in +.Va i_val . +.It Dv IEEE80211_IOC_WME_TXOPLIMIT +Set the WME TxOpLimit parameter for the Access Class (AC) specified in +.Va i_len +using the value in +.Va i_val . +.It Dv IEEE80211_IOC_WPA +Set the WPA configuration using the value in +.Va i_val . +This request causes a running interface to be reset. +See +.Dv IEEE80211_IOC_WPA +above for details. +.It Dv IEEE80211_IOC_WPAKEY +Set the requested cryptographic key using data in the buffer pointed to by +.Va i_data . +See +.Dv IEEE80211_IOC_WPAKEY +for details. +.It Dv IEEE80211_IOC_WPS +Set whether or not Wi-FI Protected Setup (WPS) is enabled using the value in +.Va i_val . +.El +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr wlan 4 , +.Xr wlan_acl 4 , +.Xr wlan_xauth 4 , +.Xr hostapd 8 , +.Xr ifconfig 8 , +.Xr wpa_supplicant 8 diff --git a/static/freebsd/man4/netdump.4 b/static/freebsd/man4/netdump.4 new file mode 100644 index 00000000..daf0d6ae --- /dev/null +++ b/static/freebsd/man4/netdump.4 @@ -0,0 +1,165 @@ +.\"- +.\" Copyright (c) 2018 Mark Johnston +.\" +.\" 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 November 10, 2022 +.Dt NETDUMP 4 +.Os +.Sh NAME +.Nm netdump +.Nd protocol for transmitting kernel dumps to a remote server +.Sh SYNOPSIS +To compile netdump client support into the kernel, place the following lines in +your kernel configuration file: +.Bd -ragged -offset indent +.Cd "options INET" +.Cd "options DEBUGNET" +.Cd "options NETDUMP" +.Ed +.Sh DESCRIPTION +netdump is a UDP-based protocol for transmitting kernel dumps to a remote host. +A netdump client is a panicking kernel, and a netdump server is a host +running the +.Nm +daemon, available in ports as +.Pa ports/ftp/netdumpd . +.Nm +clients are configured using the +.Xr dumpon 8 +utility or the +.Ic netdump +command in +.Xr ddb 4 . +.Pp +.Nm +client messages consist of a fixed-size header followed by a variable-sized +payload. +The header contains the message type, a sequence number, the offset of +the payload data in the kernel dump, and the length of the payload data +(not including the header). +The message types are +.Dv HERALD , FINISHED , KDH , VMCORE , +and +.Dv EKCD_KEY . +.Nm +server messages have a fixed size and contain only the sequence number of +the client message. +These messages indicate that the server has successfully processed the +client message with the corresponding sequence number. +All client messages are acknowledged this way. +Server messages are always sent to port 20024 of the client. +.Pp +To initiate a +.Nm , +the client sends a +.Dv HERALD +message to the server at port 20023. +The client may include a relative path in its payload, in which case the +.Nm +server should attempt to save the dump at that path relative to its configured +dump directory. +The server will acknowledge the +.Dv HERALD +using a random source port, and the client must send all subsequent messages +to that port. +.Pp +The +.Dv KDH , VMCORE , +and +.Dv EKCD_KEY +message payloads contain the kernel dump header, dump contents, and +dump encryption key respectively. +The offset in the message header should be treated as a seek offset +in the corresponding file. +There are no ordering requirements for these messages. +.Pp +A +.Nm +is completed by sending the +.Dv FINISHED +message to the server. +.Pp +The following network drivers support netdump: +.Xr alc 4 , +.Xr bge 4 , +.Xr bnxt 4 , +.Xr bxe 4 , +.Xr cxgb 4 , +.Xr em 4 , +.Xr igb 4 , +.Xr ix 4 , +.Xr ixl 4 , +.Xr mlx4en 4 , +.Xr mlx5en 4 , +.Xr re 4 , +.Xr vtnet 4 . +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +variables: +.Bl -tag -width "indent" +.It Va net.netdump.debug +Control debug message verbosity. +Debug messages are disabled by default, but are useful when troubleshooting +or when developing driver support. +.It Va net.netdump.path +Specify a path relative to the server's dump directory in which to store +the dump. +For example, if the +.Nm +server is configured to store dumps in +.Pa /var/crash , +a path of +.Dq foo +will cause the server to attempt to store dumps from the client in +.Pa /var/crash/foo . +The server will not automatically create the relative directory. +.It Va net.netdump.polls +The client will poll the configured network interface while waiting for +acknowledgements. +This parameter controls the maximum number of poll attempts before giving +up, which typically results in a re-transmit. +Each poll attempt takes 0.5ms. +.It Va net.netdump.retries +The number of times the client will re-transmit a packet before aborting +a dump due to a lack of acknowledgement. +The default may be too small in environments with lots of packet loss. +.It Va net.netdump.arp_retries +The number of times the client will attempt to learn the MAC address of +the configured gateway or server before giving up and aborting the dump. +.El +.Sh SEE ALSO +.Xr decryptcore 8 , +.Xr dumpon 8 , +.Xr savecore 8 +.Sh HISTORY +.Nm +client support first appeared in +.Fx 12.0 . +.Sh BUGS +Only IPv4 is supported. +.Pp +.Nm +may only be used after the kernel has panicked. diff --git a/static/freebsd/man4/netfpga10g_nf10bmac.4 b/static/freebsd/man4/netfpga10g_nf10bmac.4 new file mode 100644 index 00000000..3a6fc363 --- /dev/null +++ b/static/freebsd/man4/netfpga10g_nf10bmac.4 @@ -0,0 +1,68 @@ +.\"- +.\" Copyright (c) 2014 Bjoern A. Zeeb +.\" All rights reserved. +.\" +.\" This software was developed by SRI International and the University of +.\" Cambridge Computer Laboratory under DARPA/AFRL contract FA8750-11-C-0249 +.\" ("MRC2"), as part of the DARPA MRC research programme. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 17, 2014 +.Dt NETFPGA10G_NF10BMAC 4 +.Os +.Sh NAME +.Nm netfpga10g_nf10bmac +.Nd driver for the NetFPGA-10G Embedded CPU Ethernet Core +.Sh SYNOPSIS +.Cd "device netfpga10g_nf10bmac" +.Sh DESCRIPTION +The +.Nm +device driver provides support for the NetFPGA-10G Embedded CPU Ethernet +Core. +.Sh HARDWARE +The current version of the +.Nm +driver works with one PIO mode interface of the +NetFPGA-10G Embedded CPU Ethernet Core version 1.00a. +.Sh SEE ALSO +.Xr netintro 4 , +.Xr ifconfig 8 +.Rs +.%T NetFPGA-10G Wiki +.%U https://github.com/NetFPGA/NetFPGA-public/wiki +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 11.0 . +.Sh AUTHORS +This software and this manual page were +developed by SRI International and the University of Cambridge Computer +Laboratory under DARPA/AFRL contract +.Pq FA8750-11-C-0249 +.Pq Do MRC2 Dc , +as part of the DARPA MRC research programme. +The device driver was written by +.An Bjoern A. Zeeb . diff --git a/static/freebsd/man4/netgdb.4 b/static/freebsd/man4/netgdb.4 new file mode 100644 index 00000000..a86431fa --- /dev/null +++ b/static/freebsd/man4/netgdb.4 @@ -0,0 +1,148 @@ +.\"- +.\" Copyright (c) 2019 Conrad Meyer +.\" +.\" 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 November 10, 2022 +.Dt NETGDB 4 +.Os +.Sh NAME +.Nm netgdb +.Nd protocol for debugging the kernel with GDB over the network +.Sh SYNOPSIS +To compile NetGDB support into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "options DDB" +.Cd "options GDB" +.Cd "options INET" +.Cd "options DEBUGNET" +.Cd "options NETGDB" +.Ed +.Sh DESCRIPTION +.Nm +is a UDP-based protocol for communicating with a remote GDB client via an +intermediary proxy. +.Pp +A +.Nm +session is started by using the +.Ic netgdb Fl s Ar server Oo Fl g Ar gateway Fl c Ar client Fl i Ar iface Oc +command in +.Xr ddb 4 +to connect to a proxy server. +When the connection is made, the proxy server logs a message that a +.Nm +client has connected. +It subsequently establishes a TCP listening socket and logs a message +specifying which port it is listening on. +Then it waits for a GDB client to connect. +The GDB command to connect is: +.Bd -ragged -offset indent +.Ic target remote Aq Ar proxyip:proxyport +.Ed +.Pp +At this point, the server proxies traffic back and forth between +.Nm +and the ordinary GDB client, speaking the ordinary GDB remote protocol. +The +.Nm +session is identical to any other kernel GDB session from the perspective +of the GDB debugger. +.Sh IMPLEMENTATION NOTES +The UDP protocol is based on the same packet structure and a subset of the +exact same message types as +.Xr netdump 4 . +It uses the +.Dv HERALD , +.Dv DATA ( née VMCORE ) , +and +.Dv FINISHED +message types. +Like +.Xr netdump 4 , +the client's initial +.Dv HERALD +message is acknowledged from a random source port, and the client sends +subsequent communication to that port. +.Pp +Unlike +.Xr netdump 4 , +the initial +.Dv HERALD +port is 20025. +Additionally, +the proxy server sends responses to the source port of the client's initial +.Dv HERALD , +rather than a separate reserved port. +.Nm +message and acknowledgements are bidirectional. +The sequence number and acknowledgement protocol is otherwise identical to +the unidirectional version used by netdump; it just runs in both directions. +Acknowledgements are sent to and from the same addresses and ports as +regular messages. +.Pp +The first version of the +.Nm +protocol uses the protocol number +.Dv Sq 0x2515f095 +in the 32-bit +.Va aux2 +parameter of the initial +.Dv HERALD +message. +.Pp +The list of supported network drivers and protocol families is identical to +that of +.Xr netdump 4 . +.Sh DIAGNOSTICS +The following variable is available via both +.Xr sysctl 8 +and +.Xr loader 8 +(as a tunable): +.Bl -tag -width "indent" +.It Va debug.gdb.netgdb.debug +Control debug message verbosity. +Debug messages are disabled by default. +They may be enabled by setting the variable to a non-zero value. +.El +.Sh SEE ALSO +.Xr ddb 4 , +.Xr gdb 4 , +.Xr netdump 4 +.Sh HISTORY +.Nm +first appeared in +.Fx 13.0 . +.Sh BUGS +.Nm +may only be used after the kernel has panicked, due to limitations in the +treatment of locking primitives under +.Xr ddb 4 . +.Sh SECURITY CONSIDERATIONS +Version 1 of the +.Nm +protocol has no security properties whatsoever. +All messages are sent and acknowledged in cleartext, and no message +authentication codes are used to prevent attackers from forging messages. +It is absolutely inappropriate for use across the public internet. diff --git a/static/freebsd/man4/netgraph.4 b/static/freebsd/man4/netgraph.4 new file mode 100644 index 00000000..154f8f1e --- /dev/null +++ b/static/freebsd/man4/netgraph.4 @@ -0,0 +1,1475 @@ +.\" Copyright (c) 1996-1999 Whistle Communications, Inc. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, use and +.\" redistribution of this software, in source or object code forms, with or +.\" without modifications are expressly permitted by Whistle Communications; +.\" provided, however, that: +.\" 1. Any and all reproductions of the source or object code must include the +.\" copyright notice above and the following disclaimer of warranties; and +.\" 2. No rights are granted, in any manner or form, to use Whistle +.\" Communications, Inc. trademarks, including the mark "WHISTLE +.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as +.\" such appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, +.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. +.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY +.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS +.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. +.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES +.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING +.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY +.\" OF SUCH DAMAGE. +.\" +.\" Authors: Julian Elischer +.\" Archie Cobbs +.\" +.\" $Whistle: netgraph.4,v 1.7 1999/01/28 23:54:52 julian Exp $ +.\" +.Dd September 29, 2021 +.Dt NETGRAPH 4 +.Os +.Sh NAME +.Nm netgraph +.Nd "graph based kernel networking subsystem" +.Sh DESCRIPTION +The +.Nm +system provides a uniform and modular system for the implementation +of kernel objects which perform various networking functions. +The objects, known as +.Em nodes , +can be arranged into arbitrarily complicated graphs. +Nodes have +.Em hooks +which are used to connect two nodes together, forming the edges in the graph. +Nodes communicate along the edges to process data, implement protocols, etc. +.Pp +The aim of +.Nm +is to supplement rather than replace the existing kernel networking +infrastructure. +It provides: +.Pp +.Bl -bullet -compact +.It +A flexible way of combining protocol and link level drivers. +.It +A modular way to implement new protocols. +.It +A common framework for kernel entities to inter-communicate. +.It +A reasonably fast, kernel-based implementation. +.El +.Ss Nodes and Types +The most fundamental concept in +.Nm +is that of a +.Em node . +All nodes implement a number of predefined methods which allow them +to interact with other nodes in a well defined manner. +.Pp +Each node has a +.Em type , +which is a static property of the node determined at node creation time. +A node's type is described by a unique +.Tn ASCII +type name. +The type implies what the node does and how it may be connected +to other nodes. +.Pp +In object-oriented language, types are classes, and nodes are instances +of their respective class. +All node types are subclasses of the generic node +type, and hence inherit certain common functionality and capabilities +(e.g., the ability to have an +.Tn ASCII +name). +.Pp +Nodes may be assigned a globally unique +.Tn ASCII +name which can be +used to refer to the node. +The name must not contain the characters +.Ql .\& +or +.Ql \&: , +and is limited to +.Dv NG_NODESIZ +characters (including the terminating +.Dv NUL +character). +.Pp +Each node instance has a unique +.Em ID number +which is expressed as a 32-bit hexadecimal value. +This value may be used to refer to a node when there is no +.Tn ASCII +name assigned to it. +.Ss Hooks +Nodes are connected to other nodes by connecting a pair of +.Em hooks , +one from each node. +Data flows bidirectionally between nodes along +connected pairs of hooks. +A node may have as many hooks as it +needs, and may assign whatever meaning it wants to a hook. +.Pp +Hooks have these properties: +.Bl -bullet +.It +A hook has an +.Tn ASCII +name which is unique among all hooks +on that node (other hooks on other nodes may have the same name). +The name must not contain the characters +.Ql .\& +or +.Ql \&: , +and is +limited to +.Dv NG_HOOKSIZ +characters (including the terminating +.Dv NUL +character). +.It +A hook is always connected to another hook. +That is, hooks are +created at the time they are connected, and breaking an edge by +removing either hook destroys both hooks. +.It +A hook can be set into a state where incoming packets are always queued +by the input queueing system, rather than being delivered directly. +This can be used when the data is sent from an interrupt handler, +and processing must be quick so as not to block other interrupts. +.It +A hook may supply overriding receive data and receive message functions, +which should be used for data and messages received through that hook +in preference to the general node-wide methods. +.El +.Pp +A node may decide to assign special meaning to some hooks. +For example, connecting to the hook named +.Va debug +might trigger +the node to start sending debugging information to that hook. +.Ss Data Flow +Two types of information flow between nodes: data messages and +control messages. +Data messages are passed in +.Vt mbuf chains +along the edges +in the graph, one edge at a time. +The first +.Vt mbuf +in a chain must have the +.Dv M_PKTHDR +flag set. +Each node decides how to handle data received through one of its hooks. +.Pp +Along with data, nodes can also receive control messages. +There are generic and type-specific control messages. +Control messages have a common +header format, followed by type-specific data, and are binary structures +for efficiency. +However, node types may also support conversion of the +type-specific data between binary and +.Tn ASCII +formats, +for debugging and human interface purposes (see the +.Dv NGM_ASCII2BINARY +and +.Dv NGM_BINARY2ASCII +generic control messages below). +Nodes are not required to support these conversions. +.Pp +There are three ways to address a control message. +If there is a sequence of edges connecting the two nodes, the message +may be +.Dq source routed +by specifying the corresponding sequence +of +.Tn ASCII +hook names as the destination address for the message (relative +addressing). +If the destination is adjacent to the source, then the source +node may simply specify (as a pointer in the code) the hook across which the +message should be sent. +Otherwise, the recipient node's global +.Tn ASCII +name +(or equivalent ID-based name) is used as the destination address +for the message (absolute addressing). +The two types of +.Tn ASCII +addressing +may be combined, by specifying an absolute start node and a sequence +of hooks. +Only the +.Tn ASCII +addressing modes are available to control programs outside the kernel; +use of direct pointers is limited to kernel modules. +.Pp +Messages often represent commands that are followed by a reply message +in the reverse direction. +To facilitate this, the recipient of a +control message is supplied with a +.Dq return address +that is suitable for addressing a reply. +.Pp +Each control message contains a 32-bit value, called a +.Dq typecookie , +indicating the type of the message, i.e.\& how to interpret it. +Typically each type defines a unique typecookie for the messages +that it understands. +However, a node may choose to recognize and +implement more than one type of messages. +.Pp +If a message is delivered to an address that implies that it arrived +at that node through a particular hook (as opposed to having been directly +addressed using its ID or global name) then that hook is identified to the +receiving node. +This allows a message to be re-routed or passed on, should +a node decide that this is required, in much the same way that data packets +are passed around between nodes. +A set of standard +messages for flow control and link management purposes are +defined by the base system that are usually +passed around in this manner. +Flow control message would usually travel +in the opposite direction to the data to which they pertain. +.Ss Netgraph is (Usually) Functional +In order to minimize latency, most +.Nm +operations are functional. +That is, data and control messages are delivered by making function +calls rather than by using queues and mailboxes. +For example, if node +A wishes to send a data +.Vt mbuf +to neighboring node B, it calls the +generic +.Nm +data delivery function. +This function in turn locates +node B and calls B's +.Dq receive data +method. +There are exceptions to this. +.Pp +Each node has an input queue, and some operations can be considered to +be +.Em writers +in that they alter the state of the node. +Obviously, in an SMP +world it would be bad if the state of a node were changed while another +data packet were transiting the node. +For this purpose, the input queue implements a +.Em reader/writer +semantic so that when there is a writer in the node, all other requests +are queued, and while there are readers, a writer, and any following +packets are queued. +In the case where there is no reason to queue the +data, the input method is called directly, as mentioned above. +.Pp +A node may declare that all requests should be considered as writers, +or that requests coming in over a particular hook should be considered to +be a writer, or even that packets leaving or entering across a particular +hook should always be queued, rather than delivered directly (often useful +for interrupt routines who want to get back to the hardware quickly). +By default, all control message packets are considered to be writers +unless specifically declared to be a reader in their definition. +(See +.Dv NGM_READONLY +in +.In netgraph/ng_message.h . ) +.Pp +While this mode of operation +results in good performance, it has a few implications for node +developers: +.Bl -bullet +.It +Whenever a node delivers a data or control message, the node +may need to allow for the possibility of receiving a returning +message before the original delivery function call returns. +.It +.Nm Netgraph +provides internal synchronization between nodes. +Data always enters a +.Dq graph +at an +.Em edge node . +An +.Em edge node +is a node that interfaces between +.Nm +and some other part of the system. +Examples of +.Dq edge nodes +include device drivers, the +.Vt socket , ether , tty , +and +.Vt ksocket +node type. +In these +.Em edge nodes , +the calling thread directly executes code in the node, and from that code +calls upon the +.Nm +framework to deliver data across some edge +in the graph. +From an execution point of view, the calling thread will execute the +.Nm +framework methods, and if it can acquire a lock to do so, +the input methods of the next node. +This continues until either the data is discarded or queued for some +device or system entity, or the thread is unable to acquire a lock on +the next node. +In that case, the data is queued for the node, and execution rewinds +back to the original calling entity. +The queued data will be picked up and processed by either the current +holder of the lock when they have completed their operations, or by +a special +.Nm +thread that is activated when there are such items +queued. +.It +It is possible for an infinite loop to occur if the graph contains cycles. +.El +.Pp +So far, these issues have not proven problematical in practice. +.Ss Interaction with Other Parts of the Kernel +A node may have a hidden interaction with other components of the +kernel outside of the +.Nm +subsystem, such as device hardware, +kernel protocol stacks, etc. +In fact, one of the benefits of +.Nm +is the ability to join disparate kernel networking entities together in a +consistent communication framework. +.Pp +An example is the +.Vt socket +node type which is both a +.Nm +node and a +.Xr socket 2 +in the protocol family +.Dv PF_NETGRAPH . +Socket nodes allow user processes to participate in +.Nm . +Other nodes communicate with socket nodes using the usual methods, and the +node hides the fact that it is also passing information to and from a +cooperating user process. +.Pp +Another example is a device driver that presents +a node interface to the hardware. +.Ss Node Methods +Nodes are notified of the following actions via function calls +to the following node methods, +and may accept or reject that action (by returning the appropriate +error code): +.Bl -tag -width 2n +.It Creation of a new node +The constructor for the type is called. +If creation of a new node is allowed, constructor method may allocate any +special resources it needs. +For nodes that correspond to hardware, this is typically done during the +device attach routine. +Often a global +.Tn ASCII +name corresponding to the +device name is assigned here as well. +.It Creation of a new hook +The hook is created and tentatively +linked to the node, and the node is told about the name that will be +used to describe this hook. +The node sets up any special data structures +it needs, or may reject the connection, based on the name of the hook. +.It Successful connection of two hooks +After both ends have accepted their +hooks, and the links have been made, the nodes get a chance to +find out who their peer is across the link, and can then decide to reject +the connection. +Tear-down is automatic. +This is also the time at which +a node may decide whether to set a particular hook (or its peer) into +the +.Em queueing +mode. +.It Destruction of a hook +The node is notified of a broken connection. +The node may consider some hooks +to be critical to operation and others to be expendable: the disconnection +of one hook may be an acceptable event while for another it +may effect a total shutdown for the node. +.It Preshutdown of a node +This method is called before real shutdown, which is discussed below. +While in this method, the node is fully operational and can send a +.Dq goodbye +message to its peers, or it can exclude itself from the chain and reconnect +its peers together, like the +.Xr ng_tee 4 +node type does. +.It Shutdown of a node +This method allows a node to clean up +and to ensure that any actions that need to be performed +at this time are taken. +The method is called by the generic (i.e., superclass) +node destructor which will get rid of the generic components of the node. +Some nodes (usually associated with a piece of hardware) may be +.Em persistent +in that a shutdown breaks all edges and resets the node, +but does not remove it. +In this case, the shutdown method should not +free its resources, but rather, clean up and then call the +.Fn NG_NODE_REVIVE +macro to signal the generic code that the shutdown is aborted. +In the case where the shutdown is started by the node itself due to hardware +removal or unloading (via +.Fn ng_rmnode_self ) , +it should set the +.Dv NGF_REALLY_DIE +flag to signal to its own shutdown method that it is not to persist. +.El +.Ss Sending and Receiving Data +Two other methods are also supported by all nodes: +.Bl -tag -width 2n +.It Receive data message +A +.Nm +.Em queueable request item , +usually referred to as an +.Em item , +is received by this function. +The item contains a pointer to an +.Vt mbuf . +.Pp +The node is notified on which hook the item has arrived, +and can use this information in its processing decision. +The receiving node must always +.Fn NG_FREE_M +the +.Vt mbuf chain +on completion or error, or pass it on to another node +(or kernel module) which will then be responsible for freeing it. +Similarly, the +.Em item +must be freed if it is not to be passed on to another node, by using the +.Fn NG_FREE_ITEM +macro. +If the item still holds references to +.Vt mbufs +at the time of +freeing then they will also be appropriately freed. +Therefore, if there is any chance that the +.Vt mbuf +will be +changed or freed separately from the item, it is very important +that it be retrieved using the +.Fn NGI_GET_M +macro that also removes the reference within the item. +(Or multiple frees of the same object will occur.) +.Pp +If it is only required to examine the contents of the +.Vt mbufs , +then it is possible to use the +.Fn NGI_M +macro to both read and rewrite +.Vt mbuf +pointer inside the item. +.Pp +If developer needs to pass any meta information along with the +.Vt mbuf chain , +he should use +.Xr mbuf_tags 9 +framework. +.Bf -symbolic +Note that old +.Nm +specific meta-data format is obsoleted now. +.Ef +.Pp +The receiving node may decide to defer the data by queueing it in the +.Nm +NETISR system (see below). +It achieves this by setting the +.Dv HK_QUEUE +flag in the flags word of the hook on which that data will arrive. +The infrastructure will respect that bit and queue the data for delivery at +a later time, rather than deliver it directly. +A node may decide to set +the bit on the +.Em peer +node, so that its own output packets are queued. +.Pp +The node may elect to nominate a different receive data function +for data received on a particular hook, to simplify coding. +It uses the +.Fn NG_HOOK_SET_RCVDATA hook fn +macro to do this. +The function receives the same arguments in every way +other than it will receive all (and only) packets from that hook. +.It Receive control message +This method is called when a control message is addressed to the node. +As with the received data, an +.Em item +is received, with a pointer to the control message. +The message can be examined using the +.Fn NGI_MSG +macro, or completely extracted from the item using the +.Fn NGI_GET_MSG +which also removes the reference within the item. +If the item still holds a reference to the message when it is freed +(using the +.Fn NG_FREE_ITEM +macro), then the message will also be freed appropriately. +If the +reference has been removed, the node must free the message itself using the +.Fn NG_FREE_MSG +macro. +A return address is always supplied, giving the address of the node +that originated the message so a reply message can be sent anytime later. +The return address is retrieved from the +.Em item +using the +.Fn NGI_RETADDR +macro and is of type +.Vt ng_ID_t . +All control messages and replies are +allocated with the +.Xr malloc 9 +type +.Dv M_NETGRAPH_MSG , +however it is more convenient to use the +.Fn NG_MKMESSAGE +and +.Fn NG_MKRESPONSE +macros to allocate and fill out a message. +Messages must be freed using the +.Fn NG_FREE_MSG +macro. +.Pp +If the message was delivered via a specific hook, that hook will +also be made known, which allows the use of such things as flow-control +messages, and status change messages, where the node may want to forward +the message out another hook to that on which it arrived. +.Pp +The node may elect to nominate a different receive message function +for messages received on a particular hook, to simplify coding. +It uses the +.Fn NG_HOOK_SET_RCVMSG hook fn +macro to do this. +The function receives the same arguments in every way +other than it will receive all (and only) messages from that hook. +.El +.Pp +Much use has been made of reference counts, so that nodes being +freed of all references are automatically freed, and this behaviour +has been tested and debugged to present a consistent and trustworthy +framework for the +.Dq type module +writer to use. +.Ss Addressing +The +.Nm +framework provides an unambiguous and simple to use method of specifically +addressing any single node in the graph. +The naming of a node is +independent of its type, in that another node, or external component +need not know anything about the node's type in order to address it so as +to send it a generic message type. +Node and hook names should be +chosen so as to make addresses meaningful. +.Pp +Addresses are either absolute or relative. +An absolute address begins +with a node name or ID, followed by a colon, followed by a sequence of hook +names separated by periods. +This addresses the node reached by starting +at the named node and following the specified sequence of hooks. +A relative address includes only the sequence of hook names, implicitly +starting hook traversal at the local node. +.Pp +There are a couple of special possibilities for the node name. +The name +.Ql .\& +(referred to as +.Ql .: ) +always refers to the local node. +Also, nodes that have no global name may be addressed by their ID numbers, +by enclosing the hexadecimal representation of the ID number within +the square brackets. +Here are some examples of valid +.Nm +addresses: +.Bd -literal -offset indent +\&.: +[3f]: +foo: +\&.:hook1 +foo:hook1.hook2 +[d80]:hook1 +.Ed +.Pp +The following set of nodes might be created for a site with +a single physical frame relay line having two active logical DLCI channels, +with RFC 1490 frames on DLCI 16 and PPP frames over DLCI 20: +.Bd -literal +[type SYNC ] [type FRAME] [type RFC1490] +[ "Frame1" ](uplink)<-->(data)[](dlci16)<-->(mux)[ ] +[ A ] [ B ](dlci20)<---+ [ C ] + | + | [ type PPP ] + +>(mux)[] + [ D ] +.Ed +.Pp +One could always send a control message to node C from anywhere +by using the name +.Dq Li Frame1:uplink.dlci16 . +In this case, node C would also be notified that the message +reached it via its hook +.Va mux . +Similarly, +.Dq Li Frame1:uplink.dlci20 +could reliably be used to reach node D, and node A could refer +to node B as +.Dq Li .:uplink , +or simply +.Dq Li uplink . +Conversely, B can refer to A as +.Dq Li data . +The address +.Dq Li mux.data +could be used by both nodes C and D to address a message to node A. +.Pp +Note that this is only for +.Em control messages . +In each of these cases, where a relative addressing mode is +used, the recipient is notified of the hook on which the +message arrived, as well as +the originating node. +This allows the option of hop-by-hop distribution of messages and +state information. +Data messages are +.Em only +routed one hop at a time, by specifying the departing +hook, with each node making +the next routing decision. +So when B receives a frame on hook +.Va data , +it decodes the frame relay header to determine the DLCI, +and then forwards the unwrapped frame to either C or D. +.Pp +In a similar way, flow control messages may be routed in the reverse +direction to outgoing data. +For example a +.Dq "buffer nearly full" +message from +.Dq Li Frame1: +would be passed to node B +which might decide to send similar messages to both nodes +C and D. +The nodes would use +.Em "direct hook pointer" +addressing to route the messages. +The message may have travelled from +.Dq Li Frame1: +to B +as a synchronous reply, saving time and cycles. +.Ss Netgraph Structures +Structures are defined in +.In netgraph/netgraph.h +(for kernel structures only of interest to nodes) +and +.In netgraph/ng_message.h +(for message definitions also of interest to user programs). +.Pp +The two basic object types that are of interest to node authors are +.Em nodes +and +.Em hooks . +These two objects have the following +properties that are also of interest to the node writers. +.Bl -tag -width 2n +.It Vt "struct ng_node" +Node authors should always use the following +.Ic typedef +to declare +their pointers, and should never actually declare the structure. +.Pp +.Fd "typedef struct ng_node *node_p;" +.Pp +The following properties are associated with a node, and can be +accessed in the following manner: +.Bl -tag -width 2n +.It Validity +A driver or interrupt routine may want to check whether +the node is still valid. +It is assumed that the caller holds a reference +on the node so it will not have been freed, however it may have been +disabled or otherwise shut down. +Using the +.Fn NG_NODE_IS_VALID node +macro will return this state. +Eventually it should be almost impossible +for code to run in an invalid node but at this time that work has not been +completed. +.It Node ID Pq Vt ng_ID_t +This property can be retrieved using the macro +.Fn NG_NODE_ID node . +.It Node name +Optional globally unique name, +.Dv NUL +terminated string. +If there +is a value in here, it is the name of the node. +.Bd -literal -offset indent +if (NG_NODE_NAME(node)[0] != '\e0') ... + +if (strcmp(NG_NODE_NAME(node), "fred") == 0) ... +.Ed +.It A node dependent opaque cookie +Anything of the pointer type can be placed here. +The macros +.Fn NG_NODE_SET_PRIVATE node value +and +.Fn NG_NODE_PRIVATE node +set and retrieve this property, respectively. +.It Number of hooks +The +.Fn NG_NODE_NUMHOOKS node +macro is used +to retrieve this value. +.It Hooks +The node may have a number of hooks. +A traversal method is provided to allow all the hooks to be +tested for some condition. +.Fn NG_NODE_FOREACH_HOOK node fn arg rethook +where +.Fa fn +is a function that will be called for each hook +with the form +.Fn fn hook arg +and returning 0 to terminate the search. +If the search is terminated, then +.Fa rethook +will be set to the hook at which the search was terminated. +.El +.It Vt "struct ng_hook" +Node authors should always use the following +.Ic typedef +to declare +their hook pointers. +.Pp +.Fd "typedef struct ng_hook *hook_p;" +.Pp +The following properties are associated with a hook, and can be +accessed in the following manner: +.Bl -tag -width 2n +.It A hook dependent opaque cookie +Anything of the pointer type can be placed here. +The macros +.Fn NG_HOOK_SET_PRIVATE hook value +and +.Fn NG_HOOK_PRIVATE hook +set and retrieve this property, respectively. +.It \&An associate node +The macro +.Fn NG_HOOK_NODE hook +finds the associated node. +.It A peer hook Pq Vt hook_p +The other hook in this connected pair. +The +.Fn NG_HOOK_PEER hook +macro finds the peer. +.It References +The +.Fn NG_HOOK_REF hook +and +.Fn NG_HOOK_UNREF hook +macros +increment and decrement the hook reference count accordingly. +After decrement you should always assume the hook has been freed +unless you have another reference still valid. +.It Override receive functions +The +.Fn NG_HOOK_SET_RCVDATA hook fn +and +.Fn NG_HOOK_SET_RCVMSG hook fn +macros can be used to set override methods that will be used in preference +to the generic receive data and receive message functions. +To unset these, use the macros to set them to +.Dv NULL . +They will only be used for data and +messages received on the hook on which they are set. +.El +.Pp +The maintenance of the names, reference counts, and linked list +of hooks for each node is handled automatically by the +.Nm +subsystem. +Typically a node's private info contains a back-pointer to the node or hook +structure, which counts as a new reference that must be included +in the reference count for the node. +When the node constructor is called, +there is already a reference for this calculated in, so that +when the node is destroyed, it should remember to do a +.Fn NG_NODE_UNREF +on the node. +.Pp +From a hook you can obtain the corresponding node, and from +a node, it is possible to traverse all the active hooks. +.Pp +A current example of how to define a node can always be seen in +.Pa src/sys/netgraph/ng_sample.c +and should be used as a starting point for new node writers. +.El +.Ss Netgraph Message Structure +Control messages have the following structure: +.Bd -literal +#define NG_CMDSTRSIZ 32 /* Max command string (including null) */ + +struct ng_mesg { + struct ng_msghdr { + u_char version; /* Must equal NG_VERSION */ + u_char spare; /* Pad to 4 bytes */ + uint16_t spare2; + uint32_t arglen; /* Length of cmd/resp data */ + uint32_t cmd; /* Command identifier */ + uint32_t flags; /* Message status flags */ + uint32_t token; /* Reply should have the same token */ + uint32_t typecookie; /* Node type understanding this message */ + u_char cmdstr[NG_CMDSTRSIZ]; /* cmd string + \0 */ + } header; + char data[]; /* placeholder for actual data */ +}; + +#define NG_ABI_VERSION 12 /* Netgraph kernel ABI version */ +#define NG_VERSION 8 /* Netgraph message version */ +#define NGF_ORIG 0x00000000 /* The msg is the original request */ +#define NGF_RESP 0x00000001 /* The message is a response */ +.Ed +.Pp +Control messages have the fixed header shown above, followed by a +variable length data section which depends on the type cookie +and the command. +Each field is explained below: +.Bl -tag -width indent +.It Va version +Indicates the version of the +.Nm +message protocol itself. +The current version is +.Dv NG_VERSION . +.It Va arglen +This is the length of any extra arguments, which begin at +.Va data . +.It Va flags +Indicates whether this is a command or a response control message. +.It Va token +The +.Va token +is a means by which a sender can match a reply message to the +corresponding command message; the reply always has the same token. +.It Va typecookie +The corresponding node type's unique 32-bit value. +If a node does not recognize the type cookie it must reject the message +by returning +.Er EINVAL . +.Pp +Each type should have an include file that defines the commands, +argument format, and cookie for its own messages. +The typecookie +ensures that the same header file was included by both sender and +receiver; when an incompatible change in the header file is made, +the typecookie +.Em must +be changed. +The de-facto method for generating unique type cookies is to take the +seconds from the Epoch at the time the header file is written +(i.e., the output of +.Dq Nm date Fl u Li +%s ) . +.Pp +There is a predefined typecookie +.Dv NGM_GENERIC_COOKIE +for the +.Vt generic +node type, and +a corresponding set of generic messages which all nodes understand. +The handling of these messages is automatic. +.It Va cmd +The identifier for the message command. +This is type specific, +and is defined in the same header file as the typecookie. +.It Va cmdstr +Room for a short human readable version of +.Va command +(for debugging purposes only). +.El +.Pp +Some modules may choose to implement messages from more than one +of the header files and thus recognize more than one type cookie. +.Ss Control Message ASCII Form +Control messages are in binary format for efficiency. +However, for +debugging and human interface purposes, and if the node type supports +it, control messages may be converted to and from an equivalent +.Tn ASCII +form. +The +.Tn ASCII +form is similar to the binary form, with two exceptions: +.Bl -enum +.It +The +.Va cmdstr +header field must contain the +.Tn ASCII +name of the command, corresponding to the +.Va cmd +header field. +.It +The arguments field contains a +.Dv NUL Ns +-terminated +.Tn ASCII +string version of the message arguments. +.El +.Pp +In general, the arguments field of a control message can be any +arbitrary C data type. +.Nm Netgraph +includes parsing routines to support +some pre-defined datatypes in +.Tn ASCII +with this simple syntax: +.Bl -bullet +.It +Integer types are represented by base 8, 10, or 16 numbers. +.It +Strings are enclosed in double quotes and respect the normal +C language backslash escapes. +.It +IP addresses have the obvious form. +.It +Arrays are enclosed in square brackets, with the elements listed +consecutively starting at index zero. +An element may have an optional index and equals sign +.Pq Ql = +preceding it. +Whenever an element +does not have an explicit index, the index is implicitly the previous +element's index plus one. +.It +Structures are enclosed in curly braces, and each field is specified +in the form +.Ar fieldname Ns = Ns Ar value . +.It +Any array element or structure field whose value is equal to its +.Dq default value +may be omitted. +For integer types, the default value +is usually zero; for string types, the empty string. +.It +Array elements and structure fields may be specified in any order. +.El +.Pp +Each node type may define its own arbitrary types by providing +the necessary routines to parse and unparse. +.Tn ASCII +forms defined +for a specific node type are documented in the corresponding man page. +.Ss Generic Control Messages +There are a number of standard predefined messages that will work +for any node, as they are supported directly by the framework itself. +These are defined in +.In netgraph/ng_message.h +along with the basic layout of messages and other similar information. +.Bl -tag -width indent +.It Dv NGM_CONNECT +Connect to another node, using the supplied hook names on either end. +.It Dv NGM_MKPEER +Construct a node of the given type and then connect to it using the +supplied hook names. +.It Dv NGM_SHUTDOWN +The target node should disconnect from all its neighbours and shut down. +Persistent nodes such as those representing physical hardware +might not disappear from the node namespace, but only reset themselves. +The node must disconnect all of its hooks. +This may result in neighbors shutting themselves down, and possibly a +cascading shutdown of the entire connected graph. +.It Dv NGM_NAME +Assign a name to a node. +Nodes can exist without having a name, and this +is the default for nodes created using the +.Dv NGM_MKPEER +method. +Such nodes can only be addressed relatively or by their ID number. +.It Dv NGM_RMHOOK +Ask the node to break a hook connection to one of its neighbours. +Both nodes will have their +.Dq disconnect +method invoked. +Either node may elect to totally shut down as a result. +.It Dv NGM_NODEINFO +Asks the target node to describe itself. +The four returned fields +are the node name (if named), the node type, the node ID and the +number of hooks attached. +The ID is an internal number unique to that node. +.It Dv NGM_LISTHOOKS +This returns the information given by +.Dv NGM_NODEINFO , +but in addition +includes an array of fields describing each link, and the description for +the node at the far end of that link. +.It Dv NGM_LISTNAMES +This returns an array of node descriptions (as for +.Dv NGM_NODEINFO ) +where each entry of the array describes a named node. +All named nodes will be described. +.It Dv NGM_LISTNODES +This is the same as +.Dv NGM_LISTNAMES +except that all nodes are listed regardless of whether they have a name or not. +.It Dv NGM_LISTTYPES +This returns a list of all currently installed +.Nm +types. +.It Dv NGM_TEXT_STATUS +The node may return a text formatted status message. +The status information is determined entirely by the node type. +It is the only +.Dq generic +message +that requires any support within the node itself and as such the node may +elect to not support this message. +The text response must be less than +.Dv NG_TEXTRESPONSE +bytes in length (presently 1024). +This can be used to return general +status information in human readable form. +.It Dv NGM_BINARY2ASCII +This message converts a binary control message to its +.Tn ASCII +form. +The entire control message to be converted is contained within the +arguments field of the +.Dv NGM_BINARY2ASCII +message itself. +If successful, the reply will contain the same control +message in +.Tn ASCII +form. +A node will typically only know how to translate messages that it +itself understands, so the target node of the +.Dv NGM_BINARY2ASCII +is often the same node that would actually receive that message. +.It Dv NGM_ASCII2BINARY +The opposite of +.Dv NGM_BINARY2ASCII . +The entire control message to be converted, in +.Tn ASCII +form, is contained +in the arguments section of the +.Dv NGM_ASCII2BINARY +and need only have the +.Va flags , cmdstr , +and +.Va arglen +header fields filled in, plus the +.Dv NUL Ns +-terminated string version of +the arguments in the arguments field. +If successful, the reply +contains the binary version of the control message. +.El +.Ss Flow Control Messages +In addition to the control messages that affect nodes with respect to the +graph, there are also a number of +.Em flow control +messages defined. +At present these are +.Em not +handled automatically by the system, so +nodes need to handle them if they are going to be used in a graph utilising +flow control, and will be in the likely path of these messages. +The default action of a node that does not understand these messages should +be to pass them onto the next node. +Hopefully some helper functions will assist in this eventually. +These messages are also defined in +.In netgraph/ng_message.h +and have a separate cookie +.Dv NG_FLOW_COOKIE +to help identify them. +They will not be covered in depth here. +.Sh INITIALIZATION +The base +.Nm +code may either be statically compiled +into the kernel or else loaded dynamically as a KLD via +.Xr kldload 8 . +In the former case, include +.Pp +.D1 Cd "options NETGRAPH" +.Pp +in your kernel configuration file. +You may also include selected +node types in the kernel compilation, for example: +.Pp +.D1 Cd "options NETGRAPH" +.D1 Cd "options NETGRAPH_SOCKET" +.D1 Cd "options NETGRAPH_ECHO" +.Pp +Once the +.Nm +subsystem is loaded, individual node types may be loaded at any time +as KLD modules via +.Xr kldload 8 . +Moreover, +.Nm +knows how to automatically do this; when a request to create a new +node of unknown type +.Ar type +is made, +.Nm +will attempt to load the KLD module +.Pa ng_ Ns Ao Ar type Ac Ns Pa .ko . +.Pp +Types can also be installed at boot time, as certain device drivers +may want to export each instance of the device as a +.Nm +node. +.Pp +In general, new types can be installed at any time from within the +kernel by calling +.Fn ng_newtype , +supplying a pointer to the type's +.Vt "struct ng_type" +structure. +.Pp +The +.Fn NETGRAPH_INIT +macro automates this process by using a linker set. +.Sh EXISTING NODE TYPES +Several node types currently exist. +Each is fully documented in its own man page: +.Bl -tag -width indent +.It SOCKET +The socket type implements two new sockets in the new protocol domain +.Dv PF_NETGRAPH . +The new sockets protocols are +.Dv NG_DATA +and +.Dv NG_CONTROL , +both of type +.Dv SOCK_DGRAM . +Typically one of each is associated with a socket node. +When both sockets have closed, the node will shut down. +The +.Dv NG_DATA +socket is used for sending and receiving data, while the +.Dv NG_CONTROL +socket is used for sending and receiving control messages. +Data and control messages are passed using the +.Xr sendto 2 +and +.Xr recvfrom 2 +system calls, using a +.Vt "struct sockaddr_ng" +socket address. +.It HOLE +Responds only to generic messages and is a +.Dq black hole +for data. +Useful for testing. +Always accepts new hooks. +.It ECHO +Responds only to generic messages and always echoes data back through the +hook from which it arrived. +Returns any non-generic messages as their own response. +Useful for testing. +Always accepts new hooks. +.It TEE +This node is useful for +.Dq snooping . +It has 4 hooks: +.Va left , right , left2right , +and +.Va right2left . +Data entering from the +.Va right +is passed to the +.Va left +and duplicated on +.Va right2left , +and data entering from the +.Va left +is passed to the +.Va right +and duplicated on +.Va left2right . +Data entering from +.Va left2right +is sent to the +.Va right +and data from +.Va right2left +to +.Va left . +.It RFC1490 MUX +Encapsulates/de-encapsulates frames encoded according to RFC 1490. +Has a hook for the encapsulated packets +.Pq Va downstream +and one hook +for each protocol (i.e., IP, PPP, etc.). +.It FRAME RELAY MUX +Encapsulates/de-encapsulates Frame Relay frames. +Has a hook for the encapsulated packets +.Pq Va downstream +and one hook +for each DLCI. +.It FRAME RELAY LMI +Automatically handles frame relay +.Dq LMI +(link management interface) operations and packets. +Automatically probes and detects which of several LMI standards +is in use at the exchange. +.It TTY +This node is also a line discipline. +It simply converts between +.Vt mbuf +frames and sequential serial data, allowing a TTY to appear as a +.Nm +node. +It has a programmable +.Dq hotkey +character. +.It ASYNC +This node encapsulates and de-encapsulates asynchronous frames +according to RFC 1662. +This is used in conjunction with the TTY node +type for supporting PPP links over asynchronous serial lines. +.It ETHERNET +This node is attached to every Ethernet interface in the system. +It allows capturing raw Ethernet frames from the network, as well as +sending frames out of the interface. +.It INTERFACE +This node is also a system networking interface. +It has hooks representing each protocol family (IP, IPv6) +and appears in the output of +.Xr ifconfig 8 . +The interfaces are named +.Dq Li ng0 , +.Dq Li ng1 , +etc. +.It ONE2MANY +This node implements a simple round-robin multiplexer. +It can be used +for example to make several LAN ports act together to get a higher speed +link between two machines. +.It Various PPP related nodes +There is a full multilink PPP implementation that runs in +.Nm . +The +.Pa net/mpd5 +port can use these modules to make a very low latency high +capacity PPP system. +It also supports +.Tn PPTP +VPNs using the PPTP node. +.It PPPOE +A server and client side implementation of PPPoE. +Used in conjunction with +either +.Xr ppp 8 +or the +.Pa net/mpd5 +port. +.It BRIDGE +This node, together with the Ethernet nodes, allows a very flexible +bridging system to be implemented. +.It KSOCKET +This intriguing node looks like a socket to the system but diverts +all data to and from the +.Nm +system for further processing. +This allows +such things as UDP tunnels to be almost trivially implemented from the +command line. +.El +.Pp +Refer to the section at the end of this man page for more nodes types. +.Sh NOTES +Whether a named node exists can be checked by trying to send a control message +to it (e.g., +.Dv NGM_NODEINFO ) . +If it does not exist, +.Er ENOENT +will be returned. +.Pp +All data messages are +.Vt mbuf chains +with the +.Dv M_PKTHDR +flag set. +.Pp +Nodes are responsible for freeing what they allocate. +There are three exceptions: +.Bl -enum +.It +.Vt Mbufs +sent across a data link are never to be freed by the sender. +In the +case of error, they should be considered freed. +.It +Messages sent using one of +.Fn NG_SEND_MSG_* +family macros are freed by the recipient. +As in the case above, the addresses +associated with the message are freed by whatever allocated them so the +recipient should copy them if it wants to keep that information. +.It +Both control messages and data are delivered and queued with a +.Nm +.Em item . +The item must be freed using +.Fn NG_FREE_ITEM item +or passed on to another node. +.El +.Sh FILES +.Bl -tag -width indent +.It In netgraph/netgraph.h +Definitions for use solely within the kernel by +.Nm +nodes. +.It In netgraph/ng_message.h +Definitions needed by any file that needs to deal with +.Nm +messages. +.It In netgraph/ng_socket.h +Definitions needed to use +.Nm +.Vt socket +type nodes. +.It In netgraph/ng_ Ns Ao Ar type Ac Ns Pa .h +Definitions needed to use +.Nm +.Ar type +nodes, including the type cookie definition. +.It Pa /boot/kernel/netgraph.ko +The +.Nm +subsystem loadable KLD module. +.It Pa /boot/kernel/ng_ Ns Ao Ar type Ac Ns Pa .ko +Loadable KLD module for node type +.Ar type . +.It Pa src/sys/netgraph/ng_sample.c +Skeleton +.Nm +node. +Use this as a starting point for new node types. +.El +.Sh USER MODE SUPPORT +There is a library for supporting user-mode programs that wish +to interact with the +.Nm +system. +See +.Xr netgraph 3 +for details. +.Pp +Two user-mode support programs, +.Xr ngctl 8 +and +.Xr nghook 8 , +are available to assist manual configuration and debugging. +.Pp +There are a few useful techniques for debugging new node types. +First, implementing new node types in user-mode first +makes debugging easier. +The +.Vt tee +node type is also useful for debugging, especially in conjunction with +.Xr ngctl 8 +and +.Xr nghook 8 . +.Pp +Also look in +.Pa /usr/share/examples/netgraph +for solutions to several +common networking problems, solved using +.Nm . +.Sh SEE ALSO +.Xr socket 2 , +.Xr netgraph 3 , +.Xr ng_async 4 , +.Xr ng_bluetooth 4 , +.Xr ng_bpf 4 , +.Xr ng_bridge 4 , +.Xr ng_btsocket 4 , +.Xr ng_car 4 , +.Xr ng_cisco 4 , +.Xr ng_device 4 , +.Xr ng_echo 4 , +.Xr ng_eiface 4 , +.Xr ng_etf 4 , +.Xr ng_ether 4 , +.Xr ng_frame_relay 4 , +.Xr ng_gif 4 , +.Xr ng_gif_demux 4 , +.Xr ng_hci 4 , +.Xr ng_hole 4 , +.Xr ng_hub 4 , +.Xr ng_iface 4 , +.Xr ng_ip_input 4 , +.Xr ng_ipfw 4 , +.Xr ng_ksocket 4 , +.Xr ng_l2cap 4 , +.Xr ng_l2tp 4 , +.Xr ng_lmi 4 , +.Xr ng_mppc 4 , +.Xr ng_nat 4 , +.Xr ng_netflow 4 , +.Xr ng_one2many 4 , +.Xr ng_patch 4 , +.Xr ng_ppp 4 , +.Xr ng_pppoe 4 , +.Xr ng_pptpgre 4 , +.Xr ng_rfc1490 4 , +.Xr ng_socket 4 , +.Xr ng_split 4 , +.Xr ng_tee 4 , +.Xr ng_tty 4 , +.Xr ng_ubt 4 , +.Xr ng_UI 4 , +.Xr ng_vjc 4 , +.Xr ng_vlan 4 , +.Xr ngctl 8 , +.Xr nghook 8 +.Sh HISTORY +The +.Nm +system was designed and first implemented at Whistle Communications, Inc.\& +in a version of +.Fx 2.2 +customized for the Whistle InterJet. +It first made its debut in the main tree in +.Fx 3.4 . +.Sh AUTHORS +.An -nosplit +.An Julian Elischer Aq Mt julian@FreeBSD.org , +with contributions by +.An Archie Cobbs Aq Mt archie@FreeBSD.org . diff --git a/static/freebsd/man4/netintro.4 b/static/freebsd/man4/netintro.4 new file mode 100644 index 00000000..c6f8966e --- /dev/null +++ b/static/freebsd/man4/netintro.4 @@ -0,0 +1,442 @@ +.\" Copyright (c) 1983, 1990, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 October 14, 2020 +.Dt NETINTRO 4 +.Os +.Sh NAME +.Nm networking +.Nd introduction to networking facilities +.Sh SYNOPSIS +.In sys/types.h +.In sys/time.h +.In sys/socket.h +.In net/if.h +.In net/route.h +.Sh DESCRIPTION +This section is a general introduction to the networking facilities +available in the system. +Documentation in this part of section +4 is broken up into three areas: +.Em protocol families +(domains), +.Em protocols , +and +.Em network interfaces . +.Pp +All network protocols are associated with a specific +.Em protocol family . +A protocol family provides basic services to the protocol +implementation to allow it to function within a specific +network environment. +These services may include +packet fragmentation and reassembly, routing, addressing, and +basic transport. +A protocol family may support multiple +methods of addressing, though the current protocol implementations +do not. +A protocol family is normally comprised of a number of protocols, one per +.Xr socket 2 +type. +It is not required that a protocol family support all socket types. +A protocol family may contain multiple +protocols supporting the same socket abstraction. +.Pp +A protocol supports one of the socket abstractions detailed in +.Xr socket 2 . +A specific protocol may be accessed either by creating a +socket of the appropriate type and protocol family, or +by requesting the protocol explicitly when creating a socket. +Protocols normally accept only one type of address format, +usually determined by the addressing structure inherent in +the design of the protocol family/network architecture. +Certain semantics of the basic socket abstractions are +protocol specific. +All protocols are expected to support +the basic model for their particular socket type, but may, +in addition, provide non-standard facilities or extensions +to a mechanism. +For example, a protocol supporting the +.Dv SOCK_STREAM +abstraction may allow more than one byte of out-of-band +data to be transmitted per out-of-band message. +.Pp +A network interface is similar to a device interface. +Network interfaces comprise the lowest layer of the +networking subsystem, interacting with the actual transport +hardware. +An interface may support one or more protocol families and/or address formats. +The SYNOPSIS section of each network interface +entry gives a sample specification +of the related drivers for use in providing +a system description to the +.Xr config 8 +program. +The DIAGNOSTICS section lists messages which may appear on the console +and/or in the system error log, +.Pa /var/log/messages +(see +.Xr syslogd 8 ) , +due to errors in device operation. +.Sh PROTOCOLS +The system currently supports the +Internet +protocols, the Xerox Network Systems(tm) protocols, +and some of the +.Tn ISO OSI +protocols. +Raw socket interfaces are provided to the +.Tn IP +protocol +layer of the +Internet, and to the +.Tn IDP +protocol of Xerox +.Tn NS . +Consult the appropriate manual pages in this section for more +information regarding the support for each protocol family. +.Sh ADDRESSING +Associated with each protocol family is an address +format. +All network addresses adhere to a general structure, +called a sockaddr, described below. +However, each protocol +imposes finer and more specific structure, generally renaming +the variant, which is discussed in the protocol family manual +page alluded to above. +.Bd -literal -offset indent +struct sockaddr { + u_char sa_len; + u_char sa_family; + char sa_data[14]; +}; +.Ed +.Pp +The field +.Va sa_len +contains the total length of the structure, +which may exceed 16 bytes. +The following address values for +.Va sa_family +are known to the system +(and additional formats are defined for possible future implementation): +.Bd -literal +#define AF_UNIX 1 /* local to host (pipes, portals) */ +#define AF_INET 2 /* internetwork: UDP, TCP, etc. */ +#define AF_NS 6 /* Xerox NS protocols */ +#define AF_CCITT 10 /* CCITT protocols, X.25 etc */ +#define AF_HYLINK 15 /* NSC Hyperchannel */ +#define AF_ISO 18 /* ISO protocols */ +.Ed +.Sh ROUTING +.Fx +provides some packet routing facilities. +The kernel maintains a routing information database, which +is used in selecting the appropriate network interface when +transmitting packets. +.Pp +A user process (or possibly multiple co-operating processes) +maintains this database by sending messages over a special kind +of socket. +This supplants fixed size +.Xr ioctl 2 +used in earlier releases. +.Pp +This facility is described in +.Xr route 4 . +.Sh INTERFACES +Each network interface in a system corresponds to a +path through which messages may be sent and received. +A network interface usually has a hardware device associated with it, though +certain interfaces such as the loopback interface, +.Xr lo 4 , +do not. +.Pp +The following +.Xr ioctl 2 +calls may be used to manipulate network interfaces. +The +.Fn ioctl +is made on a socket (typically of type +.Dv SOCK_DGRAM ) +in the desired domain. +Most of the requests supported in earlier releases +take an +.Vt ifreq +structure as its parameter. +This structure has the form +.Bd -literal +struct ifreq { +#define IFNAMSIZ 16 + char ifr_name[IFNAMSIZ]; /* if name, e.g. "en0" */ + union { + struct sockaddr ifru_addr; + struct sockaddr ifru_dstaddr; + struct sockaddr ifru_broadaddr; + struct ifreq_buffer ifru_buffer; + short ifru_flags[2]; + short ifru_index; + int ifru_metric; + int ifru_mtu; + int ifru_phys; + int ifru_media; + caddr_t ifru_data; + int ifru_cap[2]; + } ifr_ifru; +#define ifr_addr ifr_ifru.ifru_addr /* address */ +#define ifr_dstaddr ifr_ifru.ifru_dstaddr /* other end of p-to-p link */ +#define ifr_broadaddr ifr_ifru.ifru_broadaddr /* broadcast address */ +#define ifr_buffer ifr_ifru.ifru_buffer /* user supplied buffer with its length */ +#define ifr_flags ifr_ifru.ifru_flags[0] /* flags (low 16 bits) */ +#define ifr_flagshigh ifr_ifru.ifru_flags[1] /* flags (high 16 bits) */ +#define ifr_metric ifr_ifru.ifru_metric /* metric */ +#define ifr_mtu ifr_ifru.ifru_mtu /* mtu */ +#define ifr_phys ifr_ifru.ifru_phys /* physical wire */ +#define ifr_media ifr_ifru.ifru_media /* physical media */ +#define ifr_data ifr_ifru.ifru_data /* for use by interface */ +#define ifr_reqcap ifr_ifru.ifru_cap[0] /* requested capabilities */ +#define ifr_curcap ifr_ifru.ifru_cap[1] /* current capabilities */ +#define ifr_index ifr_ifru.ifru_index /* interface index */ +}; +.Ed +.Pp +.Fn Ioctl +requests to obtain addresses and requests both to set and +retrieve other data are still fully supported +and use the +.Vt ifreq +structure: +.Bl -tag -width SIOCGIFBRDADDR +.It Dv SIOCGIFADDR +Get interface address for protocol family. +.It Dv SIOCGIFDSTADDR +Get point to point address for protocol family and interface. +.It Dv SIOCGIFBRDADDR +Get broadcast address for protocol family and interface. +.It Dv SIOCSIFCAP +Attempt to set the enabled capabilities field for the interface +to the value of the +.Va ifr_reqcap +field of the +.Vt ifreq +structure. +Note that, depending on the particular interface features, +some capabilities may appear hard-coded to enabled, or toggling +a capability may affect the status of other ones. +The supported capabilities field is read-only, and the +.Va ifr_curcap +field is unused by this call. +.It Dv SIOCGIFCAP +Get the interface capabilities fields. +The values for supported and enabled capabilities will be returned in the +.Va ifr_reqcap +and +.Va ifr_curcap +fields of the +.Vt ifreq +structure, respectively. +.It Dv SIOCGIFDESCR +Get the interface description, returned in the +.Va buffer +field of +.Va ifru_buffer +struct. +The user supplied buffer length should be defined in the +.Va length +field of +.Va ifru_buffer +struct passed in as parameter, and the length would include +the terminating nul character. +If there is not enough space to hold the interface length, +no copy would be done and the +.Va buffer +field of +.Va ifru_buffer +would be set to NULL. +The kernel will store the buffer length in the +.Va length +field upon return, regardless whether the buffer itself is +sufficient to hold the data. +.It Dv SIOCSIFDESCR +Set the interface description to the value of the +.Va buffer +field of +.Va ifru_buffer +struct, with +.Va length +field specifying its length (counting the terminating nul). +.It Dv SIOCSIFFLAGS +Set interface flags field. +If the interface is marked down, +any processes currently routing packets through the interface +are notified; +some interfaces may be reset so that incoming packets are no longer received. +When marked up again, the interface is reinitialized. +.It Dv SIOCGIFFLAGS +Get interface flags. +.It Dv SIOCSIFMETRIC +Set interface routing metric. +The metric is used only by user-level routers. +.It Dv SIOCGIFMETRIC +Get interface metric. +.It Dv SIOCIFCREATE +Attempt to create the specified interface. +If the interface name is given without a unit number the system +will attempt to create a new interface with an arbitrary unit number. +On successful return the +.Va ifr_name +field will contain the new interface name. +.It Dv SIOCIFDESTROY +Attempt to destroy the specified interface. +.El +.Pp +There are two requests that make use of a new structure: +.Bl -tag -width SIOCGIFBRDADDR +.It Dv SIOCAIFADDR +An interface may have more than one address associated with it +in some protocols. +This request provides a means to +add additional addresses (or modify characteristics of the +primary address if the default address for the address family +is specified). +Rather than making separate calls to +set destination or broadcast addresses, or network masks +(now an integral feature of multiple protocols) +a separate structure is used to specify all three facets simultaneously +(see below). +One would use a slightly tailored version of this struct specific +to each family (replacing each sockaddr by one +of the family-specific type). +Where the sockaddr itself is larger than the +default size, one needs to modify the +.Fn ioctl +identifier itself to include the total size, as described in +.Fn ioctl . +.It Dv SIOCDIFADDR +This requests deletes the specified address from the list +associated with an interface. +It also uses the +.Vt ifaliasreq +structure to allow for the possibility of protocols allowing +multiple masks or destination addresses, and also adopts the +convention that specification of the default address means +to delete the first address for the interface belonging to +the address family in which the original socket was opened. +.It Dv SIOCGIFALIAS +This request provides means to get additional addresses +together with netmask and broadcast/destination from an +interface. +It also uses the +.Vt ifaliasreq +structure. +.It Dv SIOCGIFCONF +Get interface configuration list. +This request takes an +.Vt ifconf +structure (see below) as a value-result parameter. +The +.Va ifc_len +field should be initially set to the size of the buffer +pointed to by +.Va ifc_buf . +On return it will contain the length, in bytes, of the +configuration list. +.It Dv SIOCIFGCLONERS +Get list of clonable interfaces. +This request takes an +.Vt if_clonereq +structure (see below) as a value-result parameter. +The +.Va ifcr_count +field should be set to the number of +.Dv IFNAMSIZ +sized strings that can be fit in the buffer pointed to by +.Va ifcr_buffer . +On return, +.Va ifcr_total +will be set to the number of clonable interfaces and the buffer pointed +to by +.Va ifcr_buffer +will be filled with the names of clonable interfaces aligned on +.Dv IFNAMSIZ +boundaries. +.El +.Bd -literal +/* +* Structure used in SIOCAIFADDR request. +*/ +struct ifaliasreq { + char ifra_name[IFNAMSIZ]; /* if name, e.g. "en0" */ + struct sockaddr ifra_addr; + struct sockaddr ifra_broadaddr; + struct sockaddr ifra_mask; +}; +.Ed +.Bd -literal +/* +* Structure used in SIOCGIFCONF request. +* Used to retrieve interface configuration +* for machine (useful for programs which +* must know all networks accessible). +*/ +struct ifconf { + int ifc_len; /* size of associated buffer */ + union { + caddr_t ifcu_buf; + struct ifreq *ifcu_req; + } ifc_ifcu; +#define ifc_buf ifc_ifcu.ifcu_buf /* buffer address */ +#define ifc_req ifc_ifcu.ifcu_req /* array of structures returned */ +}; +.Ed +.Bd -literal +/* Structure used in SIOCIFGCLONERS request. */ +struct if_clonereq { + int ifcr_total; /* total cloners (out) */ + int ifcr_count; /* room for this many in user buffer */ + char *ifcr_buffer; /* buffer for cloner names */ +}; +.Ed +.Bd -literal +/* Structure used in SIOCGIFDESCR and SIOCSIFDESCR requests */ +struct ifreq_buffer { + size_t length; /* length of the buffer */ + void *buffer; /* pointer to userland space buffer */ +}; +.Ed +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr socket 2 , +.Xr intro 4 , +.Xr config 8 , +.Xr routed 8 , +.Xr ifnet 9 +.Sh HISTORY +The +.Nm netintro +manual appeared in +.Bx 4.3 tahoe . diff --git a/static/freebsd/man4/netlink.4 b/static/freebsd/man4/netlink.4 new file mode 100644 index 00000000..90934bfe --- /dev/null +++ b/static/freebsd/man4/netlink.4 @@ -0,0 +1,358 @@ +.\" +.\" Copyright (C) 2022 Alexander Chernikov . +.\" +.\" 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 November 30, 2022 +.Dt NETLINK 4 +.Os +.Sh NAME +.Nm Netlink +.Nd Kernel network configuration protocol +.Sh SYNOPSIS +.In netlink/netlink.h +.In netlink/netlink_route.h +.Ft int +.Fn socket AF_NETLINK SOCK_RAW "int family" +.Sh DESCRIPTION +Netlink is a user-kernel message-based communication protocol primarily used +for network stack configuration. +Netlink is easily extendable and supports large dumps and event +notifications, all via a single socket. +The protocol is fully asynchronous, allowing one to issue and track multiple +requests at once. +Netlink consists of multiple families, which commonly group the commands +belonging to the particular kernel subsystem. +Currently, the supported families are: +.Pp +.Bd -literal -offset indent -compact +NETLINK_ROUTE network configuration, +NETLINK_GENERIC "container" family +.Ed +.Pp +The +.Dv NETLINK_ROUTE +family handles all interfaces, addresses, neighbors, routes, and VNETs +configuration. +More details can be found in +.Xr rtnetlink 4 . +The +.Dv NETLINK_GENERIC +family serves as a +.Do container Dc , +allowing registering other families under the +.Dv NETLINK_GENERIC +umbrella. +This approach allows using a single netlink socket to interact with +multiple netlink families at once. +More details can be found in +.Xr genetlink 4 . +.Pp +Netlink has its own sockaddr structure: +.Bd -literal +struct sockaddr_nl { + uint8_t nl_len; /* sizeof(sockaddr_nl) */ + sa_family_t nl_family; /* netlink family */ + uint16_t nl_pad; /* reserved, set to 0 */ + uint32_t nl_pid; /* automatically selected, set to 0 */ + uint32_t nl_groups; /* multicast groups mask to bind to */ +}; +.Ed +.Pp +Typically, filling this structure is not required for socket operations. +It is presented here for completeness. +.Sh PROTOCOL DESCRIPTION +The protocol is message-based. +Each message starts with the mandatory +.Va nlmsghdr +header, followed by the family-specific header and the list of +type-length-value pairs (TLVs). +TLVs can be nested. +All headers and TLVS are padded to 4-byte boundaries. +Each +.Xr send 2 or +.Xr recv 2 +system call may contain multiple messages. +.Ss BASE HEADER +.Bd -literal +struct nlmsghdr { + uint32_t nlmsg_len; /* Length of message including header */ + uint16_t nlmsg_type; /* Message type identifier */ + uint16_t nlmsg_flags; /* Flags (NLM_F_) */ + uint32_t nlmsg_seq; /* Sequence number */ + uint32_t nlmsg_pid; /* Sending process port ID */ +}; +.Ed +.Pp +The +.Va nlmsg_len +field stores the whole message length, in bytes, including the header. +This length has to be rounded up to the nearest 4-byte boundary when +iterating over messages. +The +.Va nlmsg_type +field represents the command/request type. +This value is family-specific. +The list of supported commands can be found in the relevant family +header file. +.Va nlmsg_seq +is a user-provided request identifier. +An application can track the operation result using the +.Dv NLMSG_ERROR +messages and matching the +.Va nlmsg_seq +. +The +.Va nlmsg_pid +field is the message sender id. +This field is optional for userland. +The kernel sender id is zero. +The +.Va nlmsg_flags +field contains the message-specific flags. +The following generic flags are defined: +.Pp +.Bd -literal -offset indent -compact +NLM_F_REQUEST Indicates that the message is an actual request to the kernel +NLM_F_ACK Request an explicit ACK message with an operation result +.Ed +.Pp +The following generic flags are defined for the "GET" request types: +.Pp +.Bd -literal -offset indent -compact +NLM_F_ROOT Return the whole dataset +NLM_F_MATCH Return all entries matching the criteria +.Ed +These two flags are typically used together, aliased to +.Dv NLM_F_DUMP +.Pp +The following generic flags are defined for the "NEW" request types: +.Pp +.Bd -literal -offset indent -compact +NLM_F_CREATE Create an object if none exists +NLM_F_EXCL Don't replace an object if it exists +NLM_F_REPLACE Replace an existing matching object +NLM_F_APPEND Append to an existing object +.Ed +.Pp +The following generic flags are defined for the replies: +.Pp +.Bd -literal -offset indent -compact +NLM_F_MULTI Indicates that the message is part of the message group +NLM_F_DUMP_INTR Indicates that the state dump was not completed +NLM_F_DUMP_FILTERED Indicates that the dump was filtered per request +NLM_F_CAPPED Indicates the original message was capped to its header +NLM_F_ACK_TLVS Indicates that extended ACK TLVs were included +.Ed +.Ss TLVs +Most messages encode their attributes as type-length-value pairs (TLVs). +The base TLV header: +.Bd -literal +struct nlattr { + uint16_t nla_len; /* Total attribute length */ + uint16_t nla_type; /* Attribute type */ +}; +.Ed +The TLV type +.Pq Va nla_type +scope is typically the message type or group within a family. +For example, the +.Dv RTN_MULTICAST +type value is only valid for +.Dv RTM_NEWROUTE +, +.Dv RTM_DELROUTE +and +.Dv RTM_GETROUTE +messages. +TLVs can be nested; in that case internal TLVs may have their own sub-types. +All TLVs are packed with 4-byte padding. +.Ss CONTROL MESSAGES +A number of generic control messages are reserved in each family. +.Pp +.Dv NLMSG_ERROR +reports the operation result if requested, optionally followed by +the metadata TLVs. +The value of +.Va nlmsg_seq +is set to its value in the original messages, while +.Va nlmsg_pid +is set to the socket pid of the original socket. +The operation result is reported via +.Vt "struct nlmsgerr": +.Bd -literal +struct nlmsgerr { + int error; /* Standard errno */ + struct nlmsghdr msg; /* Original message header */ +}; +.Ed +If the +.Dv NETLINK_CAP_ACK +socket option is not set, the remainder of the original message will follow. +If the +.Dv NETLINK_EXT_ACK +socket option is set, the kernel may add a +.Dv NLMSGERR_ATTR_MSG +string TLV with the textual error description, optionally followed by the +.Dv NLMSGERR_ATTR_OFFS +TLV, indicating the offset from the message start that triggered an error. +Some operations may return additional metadata encapsulated in the +.Dv NLMSGERR_ATTR_COOKIE +TLV. +The metadata format is specific to the operation. +If the operation reply is a multipart message, then no +.Dv NLMSG_ERROR +reply is generated, only a +.Dv NLMSG_DONE +message, closing multipart sequence. +.Pp +.Dv NLMSG_DONE +indicates the end of the message group: typically, the end of the dump. +It contains a single +.Vt int +field, describing the dump result as a standard errno value. +.Sh SOCKET OPTIONS +Netlink supports a number of custom socket options, which can be set with +.Xr setsockopt 2 +with the +.Dv SOL_NETLINK +.Fa level : +.Bl -tag -width indent +.It Dv NETLINK_ADD_MEMBERSHIP +Subscribes to the notifications for the specific group (int). +.It Dv NETLINK_DROP_MEMBERSHIP +Unsubscribes from the notifications for the specific group (int). +.It Dv NETLINK_LIST_MEMBERSHIPS +Lists the memberships as a bitmask. +.It Dv NETLINK_CAP_ACK +Instructs the kernel to send the original message header in the reply +without the message body. +.It Dv NETLINK_EXT_ACK +Acknowledges ability to receive additional TLVs in the ACK message. +.El +.Pp +Additionally, netlink overrides the following socket options from the +.Dv SOL_SOCKET +.Fa level : +.Bl -tag -width indent +.It Dv SO_RCVBUF +Sets the maximum size of the socket receive buffer. +If the caller has +.Dv PRIV_NET_ROUTE +permission, the value can exceed the currently-set +.Va kern.ipc.maxsockbuf +value. +.El +.Sh SYSCTL VARIABLES +A set of +.Xr sysctl 8 +variables is available to tweak run-time parameters: +.Bl -tag -width indent +.It Va net.netlink.sendspace +Default send buffer for the netlink socket. +Note that the socket sendspace has to be at least as long as the longest +message that can be transmitted via this socket. +.El +.Bl -tag -width indent +.It Va net.netlink.recvspace +Default receive buffer for the netlink socket. +Note that the socket recvspace has to be least as long as the longest +message that can be received from this socket. +.El +.Bl -tag -width indent +.It Va net.netlink.nl_maxsockbuf +Maximum receive buffer for the netlink socket that can be set via +.Dv SO_RCVBUF +socket option. +.El +.Sh DEBUGGING +Netlink implements per-functional-unit debugging, with different severities +controllable via the +.Va net.netlink.debug +branch. +These messages are logged in the kernel message buffer and can be seen in +.Xr dmesg 8 +. +The following severity levels are defined: +.Bl -tag -width indent +.It Dv LOG_DEBUG(7) +Rare events or per-socket errors are reported here. +This is the default level, not impacting production performance. +.It Dv LOG_DEBUG2(8) +Socket events such as groups memberships, privilege checks, commands and dumps +are logged. +This level does not incur significant performance overhead. +.It Dv LOG_DEBUG3(9) +All socket events, each dumped or modified entities are logged. +Turning it on may result in significant performance overhead. +.El +.Sh ERRORS +Netlink reports operation results, including errors and error metadata, by +sending a +.Dv NLMSG_ERROR +message for each request message. +The following errors can be returned: +.Bl -tag -width Er +.It Bq Er EPERM +when the current privileges are insufficient to perform the required operation; +.It Bo Er ENOBUFS Bc or Bo Er ENOMEM Bc +when the system runs out of memory for +an internal data structure; +.It Bq Er ENOTSUP +when the requested command is not supported by the family or +the family is not supported; +.It Bq Er EINVAL +when some necessary TLVs are missing or invalid, detailed info +may be provided in NLMSGERR_ATTR_MSG and NLMSGERR_ATTR_OFFS TLVs; +.It Bq Er ENOENT +when trying to delete a non-existent object. +.Pp +Additionally, a socket operation itself may fail with one of the errors +specified in +.Xr socket 2 +, +.Xr recv 2 +or +.Xr send 2 +. +.El +.Sh SEE ALSO +.Xr snl 3 , +.Xr genetlink 4 , +.Xr rtnetlink 4 +.Rs +.%A "J. Salim" +.%A "H. Khosravi" +.%A "A. Kleen" +.%A "A. Kuznetsov" +.%T "Linux Netlink as an IP Services Protocol" +.%O "RFC 3549" +.Re +.Sh HISTORY +The netlink protocol appeared in +.Fx 13.2 . +.Sh AUTHORS +The netlink was implemented by +.An -nosplit +.An Alexander Chernikov Aq Mt melifaro@FreeBSD.org . +It was derived from the Google Summer of Code 2021 project by +.An Ng Peng Nam Sean . diff --git a/static/freebsd/man4/netmap.4 b/static/freebsd/man4/netmap.4 new file mode 100644 index 00000000..6be0c866 --- /dev/null +++ b/static/freebsd/man4/netmap.4 @@ -0,0 +1,1200 @@ +.\" Copyright (c) 2011-2014 Matteo Landi, Luigi Rizzo, Universita` di Pisa +.\" 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. +.\" +.\" This document is derived in part from the enet man page (enet.4) +.\" distributed with 4.3BSD Unix. +.\" +.Dd October 10, 2024 +.Dt NETMAP 4 +.Os +.Sh NAME +.Nm netmap +.Nd a framework for fast packet I/O +.Sh SYNOPSIS +.Cd device netmap +.Sh DESCRIPTION +.Nm +is a framework for extremely fast and efficient packet I/O +for userspace and kernel clients, and for Virtual Machines. +It runs on +.Fx , +Linux and some versions of Windows, and supports a variety of +.Nm netmap ports , +including +.Bl -tag -width XXXX +.It Nm physical NIC ports +to access individual queues of network interfaces; +.It Nm host ports +to inject packets into the host stack; +.It Nm VALE ports +implementing a very fast and modular in-kernel software switch/dataplane; +.It Nm netmap pipes +a shared memory packet transport channel; +.It Nm netmap monitors +a mechanism similar to +.Xr bpf 4 +to capture traffic +.El +.Pp +All these +.Nm netmap ports +are accessed interchangeably with the same API, +and are at least one order of magnitude faster than +standard OS mechanisms +(sockets, bpf, tun/tap interfaces, native switches, pipes). +With suitably fast hardware (NICs, PCIe buses, CPUs), +packet I/O using +.Nm +on supported NICs +reaches 14.88 million packets per second (Mpps) +with much less than one core on 10 Gbit/s NICs; +35-40 Mpps on 40 Gbit/s NICs (limited by the hardware); +about 20 Mpps per core for VALE ports; +and over 100 Mpps for +.Nm netmap pipes . +NICs without native +.Nm +support can still use the API in emulated mode, +which uses unmodified device drivers and is 3-5 times faster than +.Xr bpf 4 +or raw sockets. +.Pp +Userspace clients can dynamically switch NICs into +.Nm +mode and send and receive raw packets through +memory mapped buffers. +Similarly, +.Nm VALE +switch instances and ports, +.Nm netmap pipes +and +.Nm netmap monitors +can be created dynamically, +providing high speed packet I/O between processes, +virtual machines, NICs and the host stack. +.Pp +.Nm +supports both non-blocking I/O through +.Xr ioctl 2 , +synchronization and blocking I/O through a file descriptor +and standard OS mechanisms such as +.Xr select 2 , +.Xr poll 2 , +.Xr kqueue 2 +and +.Xr epoll 7 . +All types of +.Nm netmap ports +and the +.Nm VALE switch +are implemented by a single kernel module, which also emulates the +.Nm +API over standard drivers. +For best performance, +.Nm +requires native support in device drivers. +A list of such devices is at the end of this document. +.Pp +In the rest of this (long) manual page we document +various aspects of the +.Nm +and +.Nm VALE +architecture, features and usage. +.Sh ARCHITECTURE +.Nm +supports raw packet I/O through a +.Em port , +which can be connected to a physical interface +.Em ( NIC ) , +to the host stack, +or to a +.Nm VALE +switch. +Ports use preallocated circular queues of buffers +.Em ( rings ) +residing in an mmapped region. +There is one ring for each transmit/receive queue of a +NIC or virtual port. +An additional ring pair connects to the host stack. +.Pp +After binding a file descriptor to a port, a +.Nm +client can send or receive packets in batches through +the rings, and possibly implement zero-copy forwarding +between ports. +.Pp +All NICs operating in +.Nm +mode use the same memory region, +accessible to all processes who own +.Pa /dev/netmap +file descriptors bound to NICs. +Independent +.Nm VALE +and +.Nm netmap pipe +ports +by default use separate memory regions, +but can be independently configured to share memory. +.Sh ENTERING AND EXITING NETMAP MODE +The following section describes the system calls to create +and control +.Nm netmap +ports (including +.Nm VALE +and +.Nm netmap pipe +ports). +Simpler, higher level functions are described in the +.Sx LIBRARIES +section. +.Pp +Ports and rings are created and controlled through a file descriptor, +created by opening a special device +.Dl fd = open("/dev/netmap"); +and then bound to a specific port with an +.Dl ioctl(fd, NIOCREGIF, (struct nmreq *)arg); +.Pp +.Nm +has multiple modes of operation controlled by the +.Vt struct nmreq +argument. +.Va arg.nr_name +specifies the netmap port name, as follows: +.Bl -tag -width XXXX +.It Dv OS network interface name (e.g., 'em0', 'eth1', ... ) +the data path of the NIC is disconnected from the host stack, +and the file descriptor is bound to the NIC (one or all queues), +or to the host stack; +.It Dv valeSSS:PPP +the file descriptor is bound to port PPP of VALE switch SSS. +Switch instances and ports are dynamically created if necessary. +.Pp +Both SSS and PPP have the form [0-9a-zA-Z_]+ , the string +cannot exceed IFNAMSIZ characters, and PPP cannot +be the name of any existing OS network interface. +.El +.Pp +On return, +.Va arg +indicates the size of the shared memory region, +and the number, size and location of all the +.Nm +data structures, which can be accessed by mmapping the memory +.Dl char *mem = mmap(0, arg.nr_memsize, fd); +.Pp +Non-blocking I/O is done with special +.Xr ioctl 2 +.Xr select 2 +and +.Xr poll 2 +on the file descriptor permit blocking I/O. +.Pp +While a NIC is in +.Nm +mode, the OS will still believe the interface is up and running. +OS-generated packets for that NIC end up into a +.Nm +ring, and another ring is used to send packets into the OS network stack. +A +.Xr close 2 +on the file descriptor removes the binding, +and returns the NIC to normal mode (reconnecting the data path +to the host stack), or destroys the virtual port. +.Sh DATA STRUCTURES +The data structures in the mmapped memory region are detailed in +.In sys/net/netmap.h , +which is the ultimate reference for the +.Nm +API. +The main structures and fields are indicated below: +.Bl -tag -width XXX +.It Dv struct netmap_if (one per interface ) +.Bd -literal +struct netmap_if { + ... + const uint32_t ni_flags; /* properties */ + ... + const uint32_t ni_tx_rings; /* NIC tx rings */ + const uint32_t ni_rx_rings; /* NIC rx rings */ + uint32_t ni_bufs_head; /* head of extra bufs list */ + ... +}; +.Ed +.Pp +Indicates the number of available rings +.Pa ( struct netmap_rings ) +and their position in the mmapped region. +The number of tx and rx rings +.Pa ( ni_tx_rings , ni_rx_rings ) +normally depends on the hardware. +NICs also have an extra tx/rx ring pair connected to the host stack. +.Em NIOCREGIF +can also request additional unbound buffers in the same memory space, +to be used as temporary storage for packets. +The number of extra +buffers is specified in the +.Va arg.nr_arg3 +field. +On success, the kernel writes back to +.Va arg.nr_arg3 +the number of extra buffers actually allocated (they may be less +than the amount requested if the memory space ran out of buffers). +.Pa ni_bufs_head +contains the index of the first of these extra buffers, +which are connected in a list (the first uint32_t of each +buffer being the index of the next buffer in the list). +A +.Dv 0 +indicates the end of the list. +The application is free to modify +this list and use the buffers (i.e., binding them to the slots of a +netmap ring). +When closing the netmap file descriptor, +the kernel frees the buffers contained in the list pointed by +.Pa ni_bufs_head +, irrespectively of the buffers originally provided by the kernel on +.Em NIOCREGIF . +.It Dv struct netmap_ring (one per ring ) +.Bd -literal +struct netmap_ring { + ... + const uint32_t num_slots; /* slots in each ring */ + const uint32_t nr_buf_size; /* size of each buffer */ + ... + uint32_t head; /* (u) first buf owned by user */ + uint32_t cur; /* (u) wakeup position */ + const uint32_t tail; /* (k) first buf owned by kernel */ + ... + uint32_t flags; + struct timeval ts; /* (k) time of last rxsync() */ + ... + struct netmap_slot slot[0]; /* array of slots */ +} +.Ed +.Pp +Implements transmit and receive rings, with read/write +pointers, metadata and an array of +.Em slots +describing the buffers. +.It Dv struct netmap_slot (one per buffer ) +.Bd -literal +struct netmap_slot { + uint32_t buf_idx; /* buffer index */ + uint16_t len; /* packet length */ + uint16_t flags; /* buf changed, etc. */ + uint64_t ptr; /* address for indirect buffers */ +}; +.Ed +.Pp +Describes a packet buffer, which normally is identified by +an index and resides in the mmapped region. +.It Dv packet buffers +Fixed size (normally 2 KB) packet buffers allocated by the kernel. +.El +.Pp +The offset of the +.Pa struct netmap_if +in the mmapped region is indicated by the +.Pa nr_offset +field in the structure returned by +.Dv NIOCREGIF . +From there, all other objects are reachable through +relative references (offsets or indexes). +Macros and functions in +.In net/netmap_user.h +help converting them into actual pointers: +.Pp +.Dl struct netmap_if *nifp = NETMAP_IF(mem, arg.nr_offset); +.Dl struct netmap_ring *txr = NETMAP_TXRING(nifp, ring_index); +.Dl struct netmap_ring *rxr = NETMAP_RXRING(nifp, ring_index); +.Pp +.Dl char *buf = NETMAP_BUF(ring, buffer_index); +.Sh RINGS, BUFFERS AND DATA I/O +.Va Rings +are circular queues of packets with three indexes/pointers +.Va ( head , cur , tail ) ; +one slot is always kept empty. +The ring size +.Va ( num_slots ) +should not be assumed to be a power of two. +.Pp +.Va head +is the first slot available to userspace; +.Pp +.Va cur +is the wakeup point: +select/poll will unblock when +.Va tail +passes +.Va cur ; +.Pp +.Va tail +is the first slot reserved to the kernel. +.Pp +Slot indexes +.Em must +only move forward; +for convenience, the function +.Dl nm_ring_next(ring, index) +returns the next index modulo the ring size. +.Pp +.Va head +and +.Va cur +are only modified by the user program; +.Va tail +is only modified by the kernel. +The kernel only reads/writes the +.Vt struct netmap_ring +slots and buffers +during the execution of a netmap-related system call. +The only exception are slots (and buffers) in the range +.Va tail\ . . . head-1 , +that are explicitly assigned to the kernel. +.Ss TRANSMIT RINGS +On transmit rings, after a +.Nm +system call, slots in the range +.Va head\ . . . tail-1 +are available for transmission. +User code should fill the slots sequentially +and advance +.Va head +and +.Va cur +past slots ready to transmit. +.Va cur +may be moved further ahead if the user code needs +more slots before further transmissions (see +.Sx SCATTER GATHER I/O ) . +.Pp +At the next NIOCTXSYNC/select()/poll(), +slots up to +.Va head-1 +are pushed to the port, and +.Va tail +may advance if further slots have become available. +Below is an example of the evolution of a TX ring: +.Bd -literal + after the syscall, slots between cur and tail are (a)vailable + head=cur tail + | | + v v + TX [.....aaaaaaaaaaa.............] + + user creates new packets to (T)ransmit + head=cur tail + | | + v v + TX [.....TTTTTaaaaaa.............] + + NIOCTXSYNC/poll()/select() sends packets and reports new slots + head=cur tail + | | + v v + TX [..........aaaaaaaaaaa........] +.Ed +.Pp +.Fn select +and +.Fn poll +will block if there is no space in the ring, i.e., +.Dl ring->cur == ring->tail +and return when new slots have become available. +.Pp +High speed applications may want to amortize the cost of system calls +by preparing as many packets as possible before issuing them. +.Pp +A transmit ring with pending transmissions has +.Dl ring->head != ring->tail + 1 (modulo the ring size). +The function +.Va int nm_tx_pending(ring) +implements this test. +.Ss RECEIVE RINGS +On receive rings, after a +.Nm +system call, the slots in the range +.Va head\& . . . tail-1 +contain received packets. +User code should process them and advance +.Va head +and +.Va cur +past slots it wants to return to the kernel. +.Va cur +may be moved further ahead if the user code wants to +wait for more packets +without returning all the previous slots to the kernel. +.Pp +At the next NIOCRXSYNC/select()/poll(), +slots up to +.Va head-1 +are returned to the kernel for further receives, and +.Va tail +may advance to report new incoming packets. +.Pp +Below is an example of the evolution of an RX ring: +.Bd -literal + after the syscall, there are some (h)eld and some (R)eceived slots + head cur tail + | | | + v v v + RX [..hhhhhhRRRRRRRR..........] + + user advances head and cur, releasing some slots and holding others + head cur tail + | | | + v v v + RX [..*****hhhRRRRRR...........] + + NICRXSYNC/poll()/select() recovers slots and reports new packets + head cur tail + | | | + v v v + RX [.......hhhRRRRRRRRRRRR....] +.Ed +.Sh SLOTS AND PACKET BUFFERS +Normally, packets should be stored in the netmap-allocated buffers +assigned to slots when ports are bound to a file descriptor. +One packet is fully contained in a single buffer. +.Pp +The following flags affect slot and buffer processing: +.Bl -tag -width XXX +.It NS_BUF_CHANGED +.Em must +be used when the +.Va buf_idx +in the slot is changed. +This can be used to implement +zero-copy forwarding, see +.Sx ZERO-COPY FORWARDING . +.It NS_REPORT +reports when this buffer has been transmitted. +Normally, +.Nm +notifies transmit completions in batches, hence signals +can be delayed indefinitely. +This flag helps detect +when packets have been sent and a file descriptor can be closed. +.It NS_FORWARD +When a ring is in 'transparent' mode, +packets marked with this flag by the user application are forwarded to the +other endpoint at the next system call, thus restoring (in a selective way) +the connection between a NIC and the host stack. +.It NS_NO_LEARN +tells the forwarding code that the source MAC address for this +packet must not be used in the learning bridge code. +.It NS_INDIRECT +indicates that the packet's payload is in a user-supplied buffer +whose user virtual address is in the 'ptr' field of the slot. +The size can reach 65535 bytes. +.Pp +This is only supported on the transmit ring of +.Nm VALE +ports, and it helps reducing data copies in the interconnection +of virtual machines. +.It NS_MOREFRAG +indicates that the packet continues with subsequent buffers; +the last buffer in a packet must have the flag clear. +.El +.Sh SCATTER GATHER I/O +Packets can span multiple slots if the +.Va NS_MOREFRAG +flag is set in all but the last slot. +The maximum length of a chain is 64 buffers. +This is normally used with +.Nm VALE +ports when connecting virtual machines, as they generate large +TSO segments that are not split unless they reach a physical device. +.Pp +NOTE: The length field always refers to the individual +fragment; there is no place with the total length of a packet. +.Pp +On receive rings the macro +.Va NS_RFRAGS(slot) +indicates the remaining number of slots for this packet, +including the current one. +Slots with a value greater than 1 also have NS_MOREFRAG set. +.Sh IOCTLS +.Nm +uses two ioctls (NIOCTXSYNC, NIOCRXSYNC) +for non-blocking I/O. +They take no argument. +Two more ioctls (NIOCGINFO, NIOCREGIF) are used +to query and configure ports, with the following argument: +.Bd -literal +struct nmreq { + char nr_name[IFNAMSIZ]; /* (i) port name */ + uint32_t nr_version; /* (i) API version */ + uint32_t nr_offset; /* (o) nifp offset in mmap region */ + uint32_t nr_memsize; /* (o) size of the mmap region */ + uint32_t nr_tx_slots; /* (i/o) slots in tx rings */ + uint32_t nr_rx_slots; /* (i/o) slots in rx rings */ + uint16_t nr_tx_rings; /* (i/o) number of tx rings */ + uint16_t nr_rx_rings; /* (i/o) number of rx rings */ + uint16_t nr_ringid; /* (i/o) ring(s) we care about */ + uint16_t nr_cmd; /* (i) special command */ + uint16_t nr_arg1; /* (i/o) extra arguments */ + uint16_t nr_arg2; /* (i/o) extra arguments */ + uint32_t nr_arg3; /* (i/o) extra arguments */ + uint32_t nr_flags /* (i/o) open mode */ + ... +}; +.Ed +.Pp +A file descriptor obtained through +.Pa /dev/netmap +also supports the ioctl supported by network devices, see +.Xr netintro 4 . +.Bl -tag -width XXXX +.It Dv NIOCGINFO +returns EINVAL if the named port does not support netmap. +Otherwise, it returns 0 and (advisory) information +about the port. +Note that all the information below can change before the +interface is actually put in netmap mode. +.Bl -tag -width XX +.It Pa nr_memsize +indicates the size of the +.Nm +memory region. +NICs in +.Nm +mode all share the same memory region, +whereas +.Nm VALE +ports have independent regions for each port. +.It Pa nr_tx_slots , nr_rx_slots +indicate the size of transmit and receive rings. +.It Pa nr_tx_rings , nr_rx_rings +indicate the number of transmit +and receive rings. +Both ring number and sizes may be configured at runtime +using interface-specific functions (e.g., +.Xr ethtool 8 +). +.El +.It Dv NIOCREGIF +binds the port named in +.Va nr_name +to the file descriptor. +For a physical device this also switches it into +.Nm +mode, disconnecting +it from the host stack. +Multiple file descriptors can be bound to the same port, +with proper synchronization left to the user. +.Pp +The recommended way to bind a file descriptor to a port is +to use function +.Va nm_open(..) +(see +.Sx LIBRARIES ) +which parses names to access specific port types and +enable features. +In the following we document the main features. +.Pp +.Dv NIOCREGIF can also bind a file descriptor to one endpoint of a +.Em netmap pipe , +consisting of two netmap ports with a crossover connection. +A netmap pipe share the same memory space of the parent port, +and is meant to enable configuration where a master process acts +as a dispatcher towards slave processes. +.Pp +To enable this function, the +.Pa nr_arg1 +field of the structure can be used as a hint to the kernel to +indicate how many pipes we expect to use, and reserve extra space +in the memory region. +.Pp +On return, it gives the same info as NIOCGINFO, +with +.Pa nr_ringid +and +.Pa nr_flags +indicating the identity of the rings controlled through the file +descriptor. +.Pp +.Va nr_flags +.Va nr_ringid +selects which rings are controlled through this file descriptor. +Possible values of +.Pa nr_flags +are indicated below, together with the naming schemes +that application libraries (such as the +.Nm nm_open +indicated below) can use to indicate the specific set of rings. +In the example below, "netmap:foo" is any valid netmap port name. +.Bl -tag -width XXXXX +.It NR_REG_ALL_NIC "netmap:foo" +(default) all hardware ring pairs +.It NR_REG_SW "netmap:foo^" +the ``host rings'', connecting to the host stack. +.It NR_REG_NIC_SW "netmap:foo*" +all hardware rings and the host rings +.It NR_REG_ONE_NIC "netmap:foo-i" +only the i-th hardware ring pair, where the number is in +.Pa nr_ringid ; +.It NR_REG_PIPE_MASTER "netmap:foo{i" +the master side of the netmap pipe whose identifier (i) is in +.Pa nr_ringid ; +.It NR_REG_PIPE_SLAVE "netmap:foo}i" +the slave side of the netmap pipe whose identifier (i) is in +.Pa nr_ringid . +.Pp +The identifier of a pipe must be thought as part of the pipe name, +and does not need to be sequential. +On return the pipe +will only have a single ring pair with index 0, +irrespective of the value of +.Va i . +.El +.Pp +By default, a +.Xr poll 2 +or +.Xr select 2 +call pushes out any pending packets on the transmit ring, even if +no write events are specified. +The feature can be disabled by or-ing +.Va NETMAP_NO_TX_POLL +to the value written to +.Va nr_ringid . +When this feature is used, +packets are transmitted only on +.Va ioctl(NIOCTXSYNC) +or +.Va select() / +.Va poll() +are called with a write event (POLLOUT/wfdset) or a full ring. +.Pp +When registering a virtual interface that is dynamically created to a +.Nm VALE +switch, we can specify the desired number of rings (1 by default, +and currently up to 16) on it using nr_tx_rings and nr_rx_rings fields. +.It Dv NIOCTXSYNC +tells the hardware of new packets to transmit, and updates the +number of slots available for transmission. +.It Dv NIOCRXSYNC +tells the hardware of consumed packets, and asks for newly available +packets. +.El +.Sh SELECT, POLL, EPOLL, KQUEUE +.Xr select 2 +and +.Xr poll 2 +on a +.Nm +file descriptor process rings as indicated in +.Sx TRANSMIT RINGS +and +.Sx RECEIVE RINGS , +respectively when write (POLLOUT) and read (POLLIN) events are requested. +Both block if no slots are available in the ring +.Va ( ring->cur == ring->tail ) . +Depending on the platform, +.Xr epoll 7 +and +.Xr kqueue 2 +are supported too. +.Pp +Packets in transmit rings are normally pushed out +(and buffers reclaimed) even without +requesting write events. +Passing the +.Dv NETMAP_NO_TX_POLL +flag to +.Em NIOCREGIF +disables this feature. +By default, receive rings are processed only if read +events are requested. +Passing the +.Dv NETMAP_DO_RX_POLL +flag to +.Em NIOCREGIF updates receive rings even without read events. +Note that on +.Xr epoll 7 +and +.Xr kqueue 2 , +.Dv NETMAP_NO_TX_POLL +and +.Dv NETMAP_DO_RX_POLL +only have an effect when some event is posted for the file descriptor. +.Sh LIBRARIES +The +.Nm +API is supposed to be used directly, both because of its simplicity and +for efficient integration with applications. +.Pp +For convenience, the +.In net/netmap_user.h +header provides a few macros and functions to ease creating +a file descriptor and doing I/O with a +.Nm +port. +These are loosely modeled after the +.Xr pcap 3 +API, to ease porting of libpcap-based applications to +.Nm . +To use these extra functions, programs should +.Dl #define NETMAP_WITH_LIBS +before +.Dl #include +.Pp +The following functions are available: +.Bl -tag -width XXXXX +.It Va struct nm_desc * nm_open(const char *ifname, const struct nmreq *req, uint64_t flags, const struct nm_desc *arg ) +similar to +.Xr pcap_open_live 3 , +binds a file descriptor to a port. +.Bl -tag -width XX +.It Va ifname +is a port name, in the form "netmap:PPP" for a NIC and "valeSSS:PPP" for a +.Nm VALE +port. +.It Va req +provides the initial values for the argument to the NIOCREGIF ioctl. +The nm_flags and nm_ringid values are overwritten by parsing +ifname and flags, and other fields can be overridden through +the other two arguments. +.It Va arg +points to a struct nm_desc containing arguments (e.g., from a previously +open file descriptor) that should override the defaults. +The fields are used as described below +.It Va flags +can be set to a combination of the following flags: +.Va NETMAP_NO_TX_POLL , +.Va NETMAP_DO_RX_POLL +(copied into nr_ringid); +.Va NM_OPEN_NO_MMAP +(if arg points to the same memory region, +avoids the mmap and uses the values from it); +.Va NM_OPEN_IFNAME +(ignores ifname and uses the values in arg); +.Va NM_OPEN_ARG1 , +.Va NM_OPEN_ARG2 , +.Va NM_OPEN_ARG3 +(uses the fields from arg); +.Va NM_OPEN_RING_CFG +(uses the ring number and sizes from arg). +.El +.It Va int nm_close(struct nm_desc *d ) +closes the file descriptor, unmaps memory, frees resources. +.It Va int nm_inject(struct nm_desc *d, const void *buf, size_t size ) +similar to +.Va pcap_inject() , +pushes a packet to a ring, returns the size +of the packet is successful, or 0 on error; +.It Va int nm_dispatch(struct nm_desc *d, int cnt, nm_cb_t cb, u_char *arg ) +similar to +.Va pcap_dispatch() , +applies a callback to incoming packets +.It Va u_char * nm_nextpkt(struct nm_desc *d, struct nm_pkthdr *hdr ) +similar to +.Va pcap_next() , +fetches the next packet +.El +.Sh SUPPORTED DEVICES +.Nm +natively supports the following devices: +.Pp +On +.Fx : +.Xr cxgbe 4 , +.Xr em 4 , +.Xr iflib 4 +.Pq providing Xr igb 4 and Xr em 4 , +.Xr ix 4 , +.Xr ixl 4 , +.Xr re 4 , +.Xr vtnet 4 . +.Pp +On Linux e1000, e1000e, i40e, igb, ixgbe, ixgbevf, r8169, virtio_net, vmxnet3. +.Pp +NICs without native support can still be used in +.Nm +mode through emulation. +Performance is inferior to native netmap +mode but still significantly higher than various raw socket types +(bpf, PF_PACKET, etc.). +Note that for slow devices (such as 1 Gbit/s and slower NICs, +or several 10 Gbit/s NICs whose hardware is unable to sustain line rate), +emulated and native mode will likely have similar or same throughput. +.Pp +When emulation is in use, packet sniffer programs such as tcpdump +could see received packets before they are diverted by netmap. +This behaviour is not intentional, being just an artifact of the implementation +of emulation. +Note that in case the netmap application subsequently moves packets received +from the emulated adapter onto the host RX ring, the sniffer will intercept +those packets again, since the packets are injected to the host stack as they +were received by the network interface. +.Pp +Emulation is also available for devices with native netmap support, +which can be used for testing or performance comparison. +The sysctl variable +.Va dev.netmap.admode +globally controls how netmap mode is implemented. +.Sh SYSCTL VARIABLES AND MODULE PARAMETERS +Some aspects of the operation of +.Nm +and +.Nm VALE +are controlled through sysctl variables on +.Fx +.Em ( dev.netmap.* ) +and module parameters on Linux +.Em ( /sys/module/netmap/parameters/* ) : +.Bl -tag -width indent +.It Va dev.netmap.admode: 0 +Controls the use of native or emulated adapter mode. +.Pp +0 uses the best available option; +.Pp +1 forces native mode and fails if not available; +.Pp +2 forces emulated hence never fails. +.It Va dev.netmap.generic_rings: 1 +Number of rings used for emulated netmap mode +.It Va dev.netmap.generic_ringsize: 1024 +Ring size used for emulated netmap mode +.It Va dev.netmap.generic_mit: 100000 +Controls interrupt moderation for emulated mode +.It Va dev.netmap.fwd: 0 +Forces NS_FORWARD mode +.It Va dev.netmap.txsync_retry: 2 +Number of txsync loops in the +.Nm VALE +flush function +.It Va dev.netmap.no_pendintr: 1 +Forces recovery of transmit buffers on system calls +.It Va dev.netmap.no_timestamp: 0 +Disables the update of the timestamp in the netmap ring +.It Va dev.netmap.verbose: 0 +Verbose kernel messages +.It Va dev.netmap.buf_num: 163840 +.It Va dev.netmap.buf_size: 2048 +.It Va dev.netmap.ring_num: 200 +.It Va dev.netmap.ring_size: 36864 +.It Va dev.netmap.if_num: 100 +.It Va dev.netmap.if_size: 1024 +Sizes and number of objects (netmap_if, netmap_ring, buffers) +for the global memory region. +The only parameter worth modifying is +.Va dev.netmap.buf_num +as it impacts the total amount of memory used by netmap. +.It Va dev.netmap.buf_curr_num: 0 +.It Va dev.netmap.buf_curr_size: 0 +.It Va dev.netmap.ring_curr_num: 0 +.It Va dev.netmap.ring_curr_size: 0 +.It Va dev.netmap.if_curr_num: 0 +.It Va dev.netmap.if_curr_size: 0 +Actual values in use. +.It Va dev.netmap.priv_buf_num: 4098 +.It Va dev.netmap.priv_buf_size: 2048 +.It Va dev.netmap.priv_ring_num: 4 +.It Va dev.netmap.priv_ring_size: 20480 +.It Va dev.netmap.priv_if_num: 2 +.It Va dev.netmap.priv_if_size: 1024 +Sizes and number of objects (netmap_if, netmap_ring, buffers) +for private memory regions. +A separate memory region is used for each +.Nm VALE +port and each pair of +.Nm netmap pipes . +.It Va dev.netmap.bridge_batch: 1024 +Batch size used when moving packets across a +.Nm VALE +switch. +Values above 64 generally guarantee good +performance. +.It Va dev.netmap.max_bridges: 8 +Max number of +.Nm VALE +switches that can be created. This tunable can be specified +at loader time. +.It Va dev.netmap.ptnet_vnet_hdr: 1 +Allow ptnet devices to use virtio-net headers +.It Va dev.netmap.port_numa_affinity: 0 +On +.Xr numa 4 +systems, allocate memory for netmap ports from the local NUMA domain when +possible. +This can improve performance by reducing the number of remote memory accesses. +However, when forwarding packets between ports attached to different NUMA +domains, this will prevent zero-copy forwarding optimizations and thus may hurt +performance. +Note that this setting must be specified as a loader tunable at boot time. +.El +.Sh SYSTEM CALLS +.Nm +uses +.Xr select 2 , +.Xr poll 2 , +.Xr epoll 7 +and +.Xr kqueue 2 +to wake up processes when significant events occur, and +.Xr mmap 2 +to map memory. +.Xr ioctl 2 +is used to configure ports and +.Nm VALE switches . +.Pp +Applications may need to create threads and bind them to +specific cores to improve performance, using standard +OS primitives, see +.Xr pthread 3 . +In particular, +.Xr pthread_setaffinity_np 3 +may be of use. +.Sh EXAMPLES +.Ss TEST PROGRAMS +.Nm +comes with a few programs that can be used for testing or +simple applications. +See the +.Pa examples/ +directory in +.Nm +distributions, or +.Pa tools/tools/netmap/ +directory in +.Fx +distributions. +.Pp +.Xr pkt-gen 8 +is a general purpose traffic source/sink. +.Pp +As an example +.Dl pkt-gen -i ix0 -f tx -l 60 +can generate an infinite stream of minimum size packets, and +.Dl pkt-gen -i ix0 -f rx +is a traffic sink. +Both print traffic statistics, to help monitor +how the system performs. +.Pp +.Xr pkt-gen 8 +has many options can be uses to set packet sizes, addresses, +rates, and use multiple send/receive threads and cores. +.Pp +.Xr bridge 4 +is another test program which interconnects two +.Nm +ports. +It can be used for transparent forwarding between +interfaces, as in +.Dl bridge -i netmap:ix0 -i netmap:ix1 +or even connect the NIC to the host stack using netmap +.Dl bridge -i netmap:ix0 +.Ss USING THE NATIVE API +The following code implements a traffic generator: +.Pp +.Bd -literal -compact +#include +\&... +void sender(void) +{ + struct netmap_if *nifp; + struct netmap_ring *ring; + struct nmreq nmr; + struct pollfd fds; + + fd = open("/dev/netmap", O_RDWR); + bzero(&nmr, sizeof(nmr)); + strcpy(nmr.nr_name, "ix0"); + nmr.nm_version = NETMAP_API; + ioctl(fd, NIOCREGIF, &nmr); + p = mmap(0, nmr.nr_memsize, fd); + nifp = NETMAP_IF(p, nmr.nr_offset); + ring = NETMAP_TXRING(nifp, 0); + fds.fd = fd; + fds.events = POLLOUT; + for (;;) { + poll(&fds, 1, -1); + while (!nm_ring_empty(ring)) { + i = ring->cur; + buf = NETMAP_BUF(ring, ring->slot[i].buf_index); + ... prepare packet in buf ... + ring->slot[i].len = ... packet length ... + ring->head = ring->cur = nm_ring_next(ring, i); + } + } +} +.Ed +.Ss HELPER FUNCTIONS +A simple receiver can be implemented using the helper functions: +.Pp +.Bd -literal -compact +#define NETMAP_WITH_LIBS +#include +\&... +void receiver(void) +{ + struct nm_desc *d; + struct pollfd fds; + u_char *buf; + struct nm_pkthdr h; + ... + d = nm_open("netmap:ix0", NULL, 0, 0); + fds.fd = NETMAP_FD(d); + fds.events = POLLIN; + for (;;) { + poll(&fds, 1, -1); + while ( (buf = nm_nextpkt(d, &h)) ) + consume_pkt(buf, h.len); + } + nm_close(d); +} +.Ed +.Ss ZERO-COPY FORWARDING +Since physical interfaces share the same memory region, +it is possible to do packet forwarding between ports +swapping buffers. +The buffer from the transmit ring is used +to replenish the receive ring: +.Pp +.Bd -literal -compact + uint32_t tmp; + struct netmap_slot *src, *dst; + ... + src = &src_ring->slot[rxr->cur]; + dst = &dst_ring->slot[txr->cur]; + tmp = dst->buf_idx; + dst->buf_idx = src->buf_idx; + dst->len = src->len; + dst->flags = NS_BUF_CHANGED; + src->buf_idx = tmp; + src->flags = NS_BUF_CHANGED; + rxr->head = rxr->cur = nm_ring_next(rxr, rxr->cur); + txr->head = txr->cur = nm_ring_next(txr, txr->cur); + ... +.Ed +.Ss ACCESSING THE HOST STACK +The host stack is for all practical purposes just a regular ring pair, +which you can access with the netmap API (e.g., with +.Dl nm_open("netmap:eth0^", ... ) ; +All packets that the host would send to an interface in +.Nm +mode end up into the RX ring, whereas all packets queued to the +TX ring are send up to the host stack. +.Ss VALE SWITCH +A simple way to test the performance of a +.Nm VALE +switch is to attach a sender and a receiver to it, +e.g., running the following in two different terminals: +.Dl pkt-gen -i vale1:a -f rx # receiver +.Dl pkt-gen -i vale1:b -f tx # sender +The same example can be used to test netmap pipes, by simply +changing port names, e.g., +.Dl pkt-gen -i vale2:x{3 -f rx # receiver on the master side +.Dl pkt-gen -i vale2:x}3 -f tx # sender on the slave side +.Pp +The following command attaches an interface and the host stack +to a switch: +.Dl valectl -h vale2:em0 +Other +.Nm +clients attached to the same switch can now communicate +with the network card or the host. +.Sh SEE ALSO +.Xr vale 4 , +.Xr bridge 8 , +.Xr lb 8 , +.Xr nmreplay 8 , +.Xr pkt-gen 8 , +.Xr valectl 8 +.Pp +.Pa http://info.iet.unipi.it/~luigi/netmap/ +.Pp +Luigi Rizzo, Revisiting network I/O APIs: the netmap framework, +Communications of the ACM, 55 (3), pp.45-51, March 2012 +.Pp +Luigi Rizzo, netmap: a novel framework for fast packet I/O, +Usenix ATC'12, June 2012, Boston +.Pp +Luigi Rizzo, Giuseppe Lettieri, +VALE, a switched ethernet for virtual machines, +ACM CoNEXT'12, December 2012, Nice +.Pp +Luigi Rizzo, Giuseppe Lettieri, Vincenzo Maffione, +Speeding up packet I/O in virtual machines, +ACM/IEEE ANCS'13, October 2013, San Jose +.Sh AUTHORS +.An -nosplit +The +.Nm +framework has been originally designed and implemented at the +Universita` di Pisa in 2011 by +.An Luigi Rizzo , +and further extended with help from +.An Matteo Landi , +.An Gaetano Catalli , +.An Giuseppe Lettieri , +and +.An Vincenzo Maffione . +.Pp +.Nm +and +.Nm VALE +have been funded by the European Commission within FP7 Projects +CHANGE (257422) and OPENLAB (287581). +.Sh CAVEATS +No matter how fast the CPU and OS are, +achieving line rate on 10G and faster interfaces +requires hardware with sufficient performance. +Several NICs are unable to sustain line rate with +small packet sizes. +Insufficient PCIe or memory bandwidth +can also cause reduced performance. +.Pp +Another frequent reason for low performance is the use +of flow control on the link: a slow receiver can limit +the transmit speed. +Be sure to disable flow control when running high +speed experiments. +.Ss SPECIAL NIC FEATURES +.Nm +is orthogonal to some NIC features such as +multiqueue, schedulers, packet filters. +.Pp +Multiple transmit and receive rings are supported natively +and can be configured with ordinary OS tools, +such as +.Xr ethtool 8 +or +device-specific sysctl variables. +The same goes for Receive Packet Steering (RPS) +and filtering of incoming traffic. +.Pp +.Nm +.Em does not use +features such as +.Em checksum offloading , TCP segmentation offloading , +.Em encryption , VLAN encapsulation/decapsulation , +etc. +When using netmap to exchange packets with the host stack, +make sure to disable these features. diff --git a/static/freebsd/man4/nfe.4 b/static/freebsd/man4/nfe.4 new file mode 100644 index 00000000..1194923f --- /dev/null +++ b/static/freebsd/man4/nfe.4 @@ -0,0 +1,198 @@ +.\" $OpenBSD: nfe.4,v 1.7 2006/02/28 08:13:47 jsg Exp $ +.\" +.\" Copyright (c) 2006 Jonathan Gray +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd January 15, 2011 +.Dt NFE 4 +.Os +.Sh NAME +.Nm nfe +.Nd "NVIDIA nForce MCP Ethernet driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device nfe" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_nfe_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports PCI Ethernet adapters based on the NVIDIA +nForce Media and Communications Processors (MCP), such as +the nForce, nForce 2, nForce 3, CK804, MCP04, MCP51, MCP55, +MCP61, MCP65, MCP67, MCP73, MCP77 and MCP79 Ethernet +controller chips. +.Pp +Supported features include (hardware support provided): +.Pp +.Bl -bullet -compact +.It +Receive/Transmit IP/TCP/UDP checksum offload +.It +Hardware VLAN tag insertion/stripping +.It +TCP segmentation offload (TSO) +.It +MSI/MSI-X +.It +Jumbo Frames +.El +.Pp +Support for Jumbo Frames is provided via the interface MTU setting. +Selecting an MTU larger than 1500 bytes with the +.Xr ifconfig 8 +utility configures the adapter to receive and transmit Jumbo Frames. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width "10baseT/UTP" +.It Cm autoselect +Enable autoselection of the media type and options. +.It Cm 10baseT/UTP +Set 10Mbps operation. +.It Cm 100baseTX +Set 100Mbps (Fast Ethernet) operation. +.It Cm 1000baseT +Set 1000Mbps (Gigabit Ethernet) operation (recent models only). +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width ".Cm 10baseT/UTP" +.It Cm half-duplex +Force half duplex operation. +.It Cm full-duplex +Force full duplex operation. +.El +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports the following NVIDIA MCP onboard adapters: +.Pp +.Bl -bullet -compact +.It +NVIDIA nForce MCP Networking Adapter +.It +NVIDIA nForce MCP04 Networking Adapter +.It +NVIDIA nForce 430 MCP12 Networking Adapter +.It +NVIDIA nForce 430 MCP13 Networking Adapter +.It +NVIDIA nForce MCP51 Networking Adapter +.It +NVIDIA nForce MCP55 Networking Adapter +.It +NVIDIA nForce MCP61 Networking Adapter +.It +NVIDIA nForce MCP65 Networking Adapter +.It +NVIDIA nForce MCP67 Networking Adapter +.It +NVIDIA nForce MCP73 Networking Adapter +.It +NVIDIA nForce MCP77 Networking Adapter +.It +NVIDIA nForce MCP79 Networking Adapter +.It +NVIDIA nForce2 MCP2 Networking Adapter +.It +NVIDIA nForce2 400 MCP4 Networking Adapter +.It +NVIDIA nForce2 400 MCP5 Networking Adapter +.It +NVIDIA nForce3 MCP3 Networking Adapter +.It +NVIDIA nForce3 250 MCP6 Networking Adapter +.It +NVIDIA nForce3 MCP7 Networking Adapter +.It +NVIDIA nForce4 CK804 MCP8 Networking Adapter +.It +NVIDIA nForce4 CK804 MCP9 Networking Adapter +.El +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width indent +.It Va hw.nfe.msi_disable +Whether or not MSI support is enabled in the driver. +The default value is 0. +.It Va hw.nfe.msix_disable +Whether or not MSI-X support is enabled in the driver. +The default value is 0. +.El +.Sh SYSCTL VARIABLES +The following +.Xr sysctl 8 +variables can be used to modify or monitor +.Nm +behavior. +.Bl -tag -width indent +.It Va dev.nfe.%d.process_limit +Maximum number of Rx events to be processed in the event loop +before rescheduling a taskqueue. +The accepted range is 50 to 255, the default value is 192. +The interface does not need to be brought down and up again +before a change takes effect. +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr intro 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr pci 4 , +.Xr polling 4 , +.Xr rgephy 4 , +.Xr ifconfig 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Ox 3.9 , +and then in +.Fx 7.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Jonathan Gray Aq Mt jsg@openbsd.org +and +.An Damien Bergamini Aq Mt damien@openbsd.org . +The +.Nm +driver was ported to +.Fx +by +.An Shigeaki Tagashira Aq Mt shigeaki@se.hiroshima-u.ac.jp . diff --git a/static/freebsd/man4/nfslockd.4 b/static/freebsd/man4/nfslockd.4 new file mode 100644 index 00000000..770d9b87 --- /dev/null +++ b/static/freebsd/man4/nfslockd.4 @@ -0,0 +1,45 @@ +.\"- +.\" Copyright (c) 2024 Dag-Erling Smørgrav +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd May 8, 2024 +.Dt NFSLOCKD 4 +.Os +.Sh NAME +.Nm nfslockd +.Nd NFS advisory locking +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in +your kernel configuration file: +.Bd -ragged -offset indent +.Cd "options NFSLOCKD" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the +following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +nfslockd_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides kernel support for NFSv3 advisory locking. +It works in tandem with +.Xr rpc.lockd 8 , +which will normally load it on startup if it is not already loaded or +compiled-in. +.Sh SEE ALSO +.Xr rpc.lockd 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 6.4 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Doug Rabson Aq Mt dfr@FreeBSD.org . diff --git a/static/freebsd/man4/nfsmb.4 b/static/freebsd/man4/nfsmb.4 new file mode 100644 index 00000000..d19ac4df --- /dev/null +++ b/static/freebsd/man4/nfsmb.4 @@ -0,0 +1,52 @@ +.\" Copyright (c) 2005 Christian Brueffer +.\" 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 December 31, 2005 +.Dt NFSMB 4 +.Os +.Sh NAME +.Nm nfsmb +.Nd "NVIDIA nForce2/3/4 SMBus 2.0 controller driver" +.Sh SYNOPSIS +.Cd "device smbus" +.Cd "device smb" +.Cd "device nfsmb" +.Sh DESCRIPTION +The +.Nm +driver provides access to NVIDIA nForce2/3/4 SMBus 2.0 controllers. +.Sh SEE ALSO +.Xr smb 4 , +.Xr smbus 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 6.2 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Ruslan Ermilov Aq Mt ru@FreeBSD.org . diff --git a/static/freebsd/man4/ng_UI.4 b/static/freebsd/man4/ng_UI.4 new file mode 100644 index 00000000..14ee8a43 --- /dev/null +++ b/static/freebsd/man4/ng_UI.4 @@ -0,0 +1,91 @@ +.\" Copyright (c) 1996-1999 Whistle Communications, Inc. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, use and +.\" redistribution of this software, in source or object code forms, with or +.\" without modifications are expressly permitted by Whistle Communications; +.\" provided, however, that: +.\" 1. Any and all reproductions of the source or object code must include the +.\" copyright notice above and the following disclaimer of warranties; and +.\" 2. No rights are granted, in any manner or form, to use Whistle +.\" Communications, Inc. trademarks, including the mark "WHISTLE +.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as +.\" such appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, +.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. +.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY +.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS +.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. +.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES +.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING +.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY +.\" OF SUCH DAMAGE. +.\" +.\" Author: Archie Cobbs +.\" $Whistle: ng_UI.8,v 1.4 1999/01/25 02:37:56 archie Exp $ +.\" +.Dd January 19, 1999 +.Dt NG_UI 4 +.Os +.Sh NAME +.Nm ng_UI +.Nd UI netgraph node type +.Sh SYNOPSIS +.In netgraph/ng_UI.h +.Sh DESCRIPTION +The +.Nm UI +node type has two hooks, +.Dv upstream +and +.Dv downstream . +Packets received on +.Dv downstream +must have 0x03 (indicating unnumbered information) as their first byte; +if not the packet is dropped. +This byte is then stripped and the +remainder of the packet sent out on +.Dv upstream . +.Pp +Conversely, packets received on +.Dv upstream +will have a 0x03 byte prepended to them before being forwarded out on the +.Dv downstream +hook. +.Sh HOOKS +This node type supports the following hooks: +.Bl -tag -width ".Va downstream" +.It Va downstream +Downstream connection. +Packets on this side of the node have a 0x03 as +their first byte. +.It Va upstream +Upstream connection. +Packets on this side of the node have the +initial 0x03 byte stripped off. +.El +.Sh CONTROL MESSAGES +This node type supports only the generic control messages. +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when both hooks have been disconnected. +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ngctl 8 +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 4.0 . +.Sh AUTHORS +.An Julian Elischer Aq Mt julian@FreeBSD.org diff --git a/static/freebsd/man4/ng_async.4 b/static/freebsd/man4/ng_async.4 new file mode 100644 index 00000000..f1ccadd9 --- /dev/null +++ b/static/freebsd/man4/ng_async.4 @@ -0,0 +1,170 @@ +.\" Copyright (c) 1996-1999 Whistle Communications, Inc. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, use and +.\" redistribution of this software, in source or object code forms, with or +.\" without modifications are expressly permitted by Whistle Communications; +.\" provided, however, that: +.\" 1. Any and all reproductions of the source or object code must include the +.\" copyright notice above and the following disclaimer of warranties; and +.\" 2. No rights are granted, in any manner or form, to use Whistle +.\" Communications, Inc. trademarks, including the mark "WHISTLE +.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as +.\" such appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, +.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. +.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY +.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS +.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. +.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES +.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING +.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY +.\" OF SUCH DAMAGE. +.\" +.\" Author: Archie Cobbs +.\" $Whistle: ng_async.8,v 1.6 1999/01/25 23:46:25 archie Exp $ +.\" +.Dd November 13, 2012 +.Dt NG_ASYNC 4 +.Os +.Sh NAME +.Nm ng_async +.Nd asynchronous framing netgraph node type +.Sh SYNOPSIS +.In sys/types.h +.In netgraph/ng_async.h +.Sh DESCRIPTION +The +.Nm async +node type performs conversion between synchronous frames and +asynchronous frames, as defined for the PPP protocol in RFC 1662. +Asynchronous framing uses flag bytes and octet-stuffing +to simulate a frame oriented connection over an octet-oriented +asynchronous serial line. +.Pp +The node transmits and receives asynchronous data on the +.Dv async +hook. +Mbuf boundaries of incoming data are ignored. +Once a complete packet has been received, it is decoded and +stripped of all framing bytes, and transmitted out the +.Dv sync +hook as a single frame. +.Pp +Synchronous frames are transmitted and received on the +.Dv sync +hook. +Packets received on this hook are encoded as asynchronous frames +and sent out on +.Dv async . +Received packets should start with the address and control fields, +or the PPP protocol field if address and control field compression +is employed, and contain no checksum field. +If the first four bytes are +.Dv "0xff 0x03 0xc0 0x21" +(an LCP protocol frame) then complete control character escaping +is enabled for that frame (in PPP, LCP packets are always sent with +no address and control field compression and all control characters +escaped). +.Pp +This node supports +.Dq flag sharing +for packets transmitted on +.Dv async . +This is an optimization where the trailing flag byte +of one frame is shared with the opening flag byte of the next. +Flag sharing between frames is disabled after one second of transmit +idle time. +.Sh HOOKS +This node type supports the following hooks: +.Bl -tag -width ".Va async" +.It Va async +Asynchronous connection. +Typically this hook would be connected to a +.Xr ng_tty 4 +node, which handles transmission of serial data over a tty device. +.It Va sync +Synchronous connection. +This hook sends and receives synchronous frames. +For PPP, these frames should contain address, control, and protocol fields, +but no checksum field. +Typically this hook would be connected to an individual link hook of a +.Xr ng_ppp 4 +type node. +.El +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_ASYNC_CMD_SET_CONFIG Pq Ic setconfig +Sets the node configuration, which is described by a +.Dv "struct ng_async_cfg" : +.Bd -literal -offset 4n +struct ng_async_cfg { + u_char enabled; /* Turn encoding on/off */ + uint16_t amru; /* Max receive async frame length */ + uint16_t smru; /* Max receive sync frame length */ + uint32_t accm; /* ACCM encoding */ +}; +.Ed +The +.Dv enabled +field enables or disables all encoding/decoding functions (default disabled). +When disabled, the node operates in simple +.Dq pass through +mode. +The +.Dv amru +and +.Dv smru +fields are the asynchronous and synchronous MRU (maximum receive unit) values, +respectively. +These both default to 1600; note that the async MRU +applies to the incoming frame length after asynchronous decoding. +The +.Dv accm +field is the asynchronous character control map, which controls the escaping +of characters 0x00 thorough 0x1f (default 0xffffffff). +.It Dv NGM_ASYNC_CMD_GET_CONFIG Pq Ic getconfig +This command returns the current configuration structure. +.It Dv NGM_ASYNC_CMD_GET_STATS Pq Ic getstats +This command returns a +.Dv "struct ng_async_stat" +containing node statistics for packet, octet, and error counts. +.It Dv NGM_ASYNC_CMD_CLR_STATS Pq Ic clrstats +Clears the node statistics. +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ng_ppp 4 , +.Xr ng_tty 4 , +.Xr ngctl 8 +.Rs +.%A W. Simpson +.%T "PPP in HDLC-link Framing" +.%O RFC 1662 +.Re +.Rs +.%A W. Simpson +.%T "The Point-to-Point Protocol (PPP)" +.%O RFC 1661 +.Re +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 4.0 . +.Sh AUTHORS +.An Archie Cobbs Aq Mt archie@FreeBSD.org diff --git a/static/freebsd/man4/ng_bluetooth.4 b/static/freebsd/man4/ng_bluetooth.4 new file mode 100644 index 00000000..d6d2f6f8 --- /dev/null +++ b/static/freebsd/man4/ng_bluetooth.4 @@ -0,0 +1,111 @@ +.\" Copyright (c) 2001-2002 Maksim Yevmenkin +.\" 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. +.\" +.\" $Id: ng_bluetooth.4,v 1.3 2003/05/21 19:37:35 max Exp $ +.\" +.Dd November 9, 2002 +.Dt NG_BLUETOOTH 4 +.Os +.Sh NAME +.Nm ng_bluetooth +.Nd placeholder for global Bluetooth variables +.Sh SYNOPSIS +.In sys/types.h +.In netgraph/bluetooth/include/ng_bluetooth.h +.Sh DESCRIPTION +The +.Nm +module is a placeholder for global Bluetooth variables. +All Bluetooth variables can be examined and changed via +.Xr sysctl 8 . +.Ss Bluetooth Variables +Below is the description of default variables. +Each Bluetooth module might add its own variables to the tree. +.Bl -tag -width foo +.It Va net.bluetooth.version +A read-only integer variable that shows the current version of the +Bluetooth stack. +.It Va net.bluetooth.hci.command_timeout +A read-write integer variable that controls the Host Controller Interface +(HCI) command timeout (in seconds), i.e., how long the HCI layer will wait +for the +.Dv Command_Complete +or +.Dv Command_Status +event from a Bluetooth device. +.It Va net.bluetooth.hci.connection_timeout +A read-write integer variable that controls the HCI connection timeout, i.e.\& +how long the HCI layer will wait for the +.Dv Connection_Complete +event. +Normally this should not be required as Bluetooth devices have +connection timeout of their own and will send event back. +This timeout +is required to ensure that no connection will stall in case when the HCI +transport layer is broken. +Be careful when changing this variable. +Make sure you understand what you are doing. +.It Va net.bluetooth.hci.max_neighbor_age +A read-write integer variable that controls time-to-live (in seconds) for +entries in the HCI neighbor cache. +Every time a Bluetooth device performs an +.Dv Inquiry +operation, the results will be put in cache. +Later when a Bluetooth device +establishes a baseband connection, it will try to find the matching entry in +the cache and use it. +This might speed up establishment of the baseband +connection. +.It Va net.bluetooth.l2cap.rtx_timeout +A read-write integer variable that controls the Link Layer Control and +Adaptation Protocol (L2CAP) Retransmission Timeout (RTX) (in seconds). +Every time the L2CAP layer submits a control command, the RTX timeout is set. +The value of the RTX timeout should be greater or equal to the value of +the HCI connection timeout. +Be careful when changing this variable. +Make sure you understand what you are doing. +.It Va net.bluetooth.l2cap.ertx_timeout +A read-write integer variable that controls the L2CAP Extended Retransmission +Timeout (ERTX) (in seconds). +In some cases remote peer may respond with +.Dv PENDING +status to the L2CAP control command. +In this case the L2CAP command timeout is reset to the ERTX timeout value. +The value of the ERTX timeout should be +greater or equal to the value of the RTX timeout. +Be careful when changing this variable. +Make sure you understand what you are doing. +.El +.Sh SEE ALSO +.Xr ng_btsocket 4 , +.Xr ng_hci 4 , +.Xr ng_l2cap 4 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +module was implemented in +.Fx 5.0 . +.Sh AUTHORS +.An Maksim Yevmenkin Aq Mt m_evmenkin@yahoo.com diff --git a/static/freebsd/man4/ng_bpf.4 b/static/freebsd/man4/ng_bpf.4 new file mode 100644 index 00000000..98b5cdf2 --- /dev/null +++ b/static/freebsd/man4/ng_bpf.4 @@ -0,0 +1,230 @@ +.\" Copyright (c) 1999 Whistle Communications, Inc. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, use and +.\" redistribution of this software, in source or object code forms, with or +.\" without modifications are expressly permitted by Whistle Communications; +.\" provided, however, that: +.\" 1. Any and all reproductions of the source or object code must include the +.\" copyright notice above and the following disclaimer of warranties; and +.\" 2. No rights are granted, in any manner or form, to use Whistle +.\" Communications, Inc. trademarks, including the mark "WHISTLE +.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as +.\" such appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, +.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. +.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY +.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS +.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. +.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES +.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING +.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY +.\" OF SUCH DAMAGE. +.\" +.\" Author: Archie Cobbs +.\" $Whistle: ng_bpf.8,v 1.2 1999/12/03 01:57:12 archie Exp $ +.\" +.Dd September 20, 2020 +.Dt NG_BPF 4 +.Os +.Sh NAME +.Nm ng_bpf +.Nd Berkeley packet filter netgraph node type +.Sh SYNOPSIS +.In sys/types.h +.In net/bpf.h +.In netgraph.h +.In netgraph/ng_bpf.h +.Sh DESCRIPTION +The +.Nm bpf +node type allows Berkeley Packet Filter (see +.Xr bpf 4 ) +filters to be applied to data travelling through a Netgraph network. +Each node allows an arbitrary number of connections to arbitrarily +named hooks. +With each hook is associated a +.Xr bpf 4 +filter program which is applied to incoming data only, a destination hook +for matching packets, a destination hook for non-matching packets, +and various statistics counters. +.Pp +A +.Xr bpf 4 +program returns an unsigned integer, which is normally interpreted as +the length of the prefix of the packet to return. +In the context of this +node type, returning zero is considered a non-match, in which case the +entire packet is delivered out the non-match destination hook. +Returning a value greater than zero causes the packet to be truncated +to that length and delivered out the match destination hook. +Either or both destination hooks may be the empty string, or may +not exist, in which case the packet is dropped. +.Pp +New hooks are initially configured to drop all packets. +A new filter program may be installed using the +.Dv NGM_BPF_SET_PROGRAM +control message. +.Sh HOOKS +This node type supports any number of hooks having arbitrary names. +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_BPF_SET_PROGRAM Pq Ic setprogram +This command sets the filter program that will be applied to incoming +data on a hook. +The following structure must be supplied as an argument: +.Bd -literal -offset 4n +struct ng_bpf_hookprog { + char thisHook[NG_HOOKSIZ]; /* name of hook */ + char ifMatch[NG_HOOKSIZ]; /* match dest hook */ + char ifNotMatch[NG_HOOKSIZ]; /* !match dest hook */ + int32_t bpf_prog_len; /* #insns in program */ + struct bpf_insn bpf_prog[]; /* bpf program */ +}; +.Ed +.Pp +The hook to be updated is specified in +.Dv thisHook . +The BPF program is the sequence of instructions in the +.Dv bpf_prog +array; there must be +.Dv bpf_prog_len +of them. +Matching and non-matching incoming packets are delivered out the hooks named +.Dv ifMatch +and +.Dv ifNotMatch , +respectively. +The program must be a valid +.Xr bpf 4 +program or else +.Er EINVAL +is returned. +.It Dv NGM_BPF_GET_PROGRAM Pq Ic getprogram +This command takes an ASCII +string argument, the hook name, and returns the +corresponding +.Dv "struct ng_bpf_hookprog" +as shown above. +.It Dv NGM_BPF_GET_STATS Pq Ic getstats +This command takes an ASCII +string argument, the hook name, and returns the +statistics associated with the hook as a +.Dv "struct ng_bpf_hookstat" . +.It Dv NGM_BPF_CLR_STATS Pq Ic clrstats +This command takes an ASCII +string argument, the hook name, and clears the +statistics associated with the hook. +.It Dv NGM_BPF_GETCLR_STATS Pq Ic getclrstats +This command is identical to +.Dv NGM_BPF_GET_STATS , +except that the statistics are also atomically cleared. +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +.Sh EXAMPLES +It is possible to configure a node from the command line, using +.Xr tcpdump 1 +to generate raw BPF instructions which are then transformed +into the ASCII form of a +.Dv NGM_BPF_SET_PROGRAM +control message, as demonstrated here: +.Bd -literal -offset 4n +#!/bin/sh + +PATTERN="tcp dst port 80" +NODEPATH="my_node:" +INHOOK="hook1" +MATCHHOOK="hook2" +NOTMATCHHOOK="hook3" + +BPFPROG=$( tcpdump -s 8192 -p -ddd ${PATTERN} | \\ + ( read len ; \\ + echo -n "bpf_prog_len=$len " ; \\ + echo -n "bpf_prog=[" ; \\ + while read code jt jf k ; do \\ + echo -n " { code=$code jt=$jt jf=$jf k=$k }" ; \\ + done ; \\ + echo " ]" ) ) + +ngctl msg ${NODEPATH} setprogram { thisHook=\\"${INHOOK}\\" \\ + ifMatch=\\"${MATCHHOOK}\\" \\ + ifNotMatch=\\"${NOTMATCHHOOK}\\" \\ + ${BPFPROG} } +.Ed +.Pp +Based on the previous example, it is possible to prevent a jail (or a VM) +from spoofing by allowing only traffic that has the expected ethernet and +IP addresses: +.Bd -literal -offset 4n +#!/bin/sh + +NODEPATH="my_node:" +JAIL_MAC="0a:00:de:ad:be:ef" +JAIL_IP="128.66.1.42" +JAIL_HOOK="jail" +HOST_HOOK="host" +DEBUG_HOOK="nomatch" + +bpf_prog() { + local PATTERN=$1 + + tcpdump -s 8192 -p -ddd ${PATTERN} | ( + read len + echo -n "bpf_prog_len=$len " + echo -n "bpf_prog=[" + while read code jt jf k ; do + echo -n " { code=$code jt=$jt jf=$jf k=$k }" + done + echo " ]" + ) +} + +# Prevent jail from spoofing (filter packets coming from jail) +ngctl msg ${NODEPATH} setprogram { \\ + thisHook=\\"${JAIL_HOOK}\\" \\ + ifMatch=\\"${HOST_HOOK}\\" \\ + ifNotMatch=\\"${DEBUG_HOOK}\\" \\ + $(bpf_prog "ether src ${JAIL_MAC} && src ${JAIL_IP}") \\ +} + +# Prevent jail from receiving spoofed packets (filter packets +# coming from host) +ngctl msg ${NODEPATH} setprogram { \\ + thisHook=\\"${HOST_HOOK}\\" \\ + ifMatch=\\"${JAIL_HOOK}\\" \\ + ifNotMatch=\\"${DEBUG_HOOK}\\" \\ + $(bpf_prog "ether dst ${JAIL_MAC} && dst ${JAIL_IP}") \\ +} +.Ed +.Sh SEE ALSO +.Xr bpf 4 , +.Xr netgraph 4 , +.Xr ngctl 8 +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 4.0 . +.Sh AUTHORS +.An Archie Cobbs Aq Mt archie@FreeBSD.org +.Sh BUGS +When built as a loadable kernel module, this module includes the file +.Pa net/bpf_filter.c . +Although loading the module should fail if +.Pa net/bpf_filter.c +already exists in the kernel, currently it does not, and the duplicate +copies of the file do not interfere. +However, this may change in the future. diff --git a/static/freebsd/man4/ng_bridge.4 b/static/freebsd/man4/ng_bridge.4 new file mode 100644 index 00000000..998c428c --- /dev/null +++ b/static/freebsd/man4/ng_bridge.4 @@ -0,0 +1,290 @@ +.\" Copyright (c) 2000 Whistle Communications, Inc. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, use and +.\" redistribution of this software, in source or object code forms, with or +.\" without modifications are expressly permitted by Whistle Communications; +.\" provided, however, that: +.\" 1. Any and all reproductions of the source or object code must include the +.\" copyright notice above and the following disclaimer of warranties; and +.\" 2. No rights are granted, in any manner or form, to use Whistle +.\" Communications, Inc. trademarks, including the mark "WHISTLE +.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as +.\" such appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, +.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. +.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY +.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS +.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. +.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES +.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING +.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY +.\" OF SUCH DAMAGE. +.\" +.\" Author: Archie Cobbs +.\" +.Dd April 8, 2024 +.Dt NG_BRIDGE 4 +.Os +.Sh NAME +.Nm ng_bridge +.Nd Ethernet bridging netgraph node type +.Sh SYNOPSIS +.In sys/types.h +.In netgraph/ng_bridge.h +.Sh DESCRIPTION +The +.Nm bridge +node type performs Ethernet bridging over one or more links. +Each link (represented by a connected hook) is used to transmit +and receive raw Ethernet frames. +As packets are received, the node learns which link each +host resides on. +Packets unicast to a known host are directed out the appropriate +link only, and other links are spared the traffic. +This behavior is in contrast to a hub, which always forwards +every received packet to every other link. +.Sh LOOP DETECTION +The +.Nm bridge +node incorporates a simple loop detection algorithm. +A loop is when two ports are connected to the same physical medium. +Loops are important to avoid because of packet storms, which severely +degrade performance. +A packet storm results when the same packet is sent and received +over and over again. +If a host is detected on link A, and is then detected on link B +within a certain time period after first being detected on link A, +then link B is considered to be a looped back link. +The time period is called the minimum stable time. +.Pp +A looped back link will be temporarily muted, i.e., all traffic +received on that link is ignored. +.Sh IPFW PROCESSING +Processing of IP packets via the +.Xr ipfirewall 4 +mechanism on a per-link basis is not yet implemented. +.Sh HOOKS +This node type supports an unlimited number of hooks. +Each connected hook represents a bridged link. +The hooks are named +.Ar link0 , +.Ar link1 , +etc. +Typically these hooks are connected to the +.Ar lower +hooks of one or more +.Xr ng_ether 4 +nodes. +To connect the host machine to a bridged network, simply connect the +.Ar upper +hook of an +.Xr ng_ether 4 +node to the bridge node. +.Pp +Instead of naming a hook +.Ar linkX +the hook might be also named +.Ar uplinkX . +The node does not learn MAC addresses on uplink hooks, which keeps +the internal address table small. +This way it is desirable to connect the +.Ar lower +hook of an +.Xr ng_ether 4 +node to an +.Ar uplink +hook of the bridge, and ignore the complexity of the outside world. +Frames with unknown MACs are always sent out to +.Ar uplink +hooks, so no functionality is lost. +The +.Ar uplink0 +hook is not allowed. +.Pp +The +.Ar linkX +and +.Ar uplinkX +hook numbers can be autoassigned. +If a new hook name was specified as +.Ar link +or +.Ar uplink +the node will append lowest available valid number to the name of the new hook. +.Pp +Frames with unknown destination MAC addresses are replicated to any +available hook, unless the first connected hook is an +.Ar uplink +hook. +In this case the node assumes, that all unknown MAC addresses are +located solely on the +.Ar uplink +hooks and only those hooks will be used to send out frames with +unknown destination MACs. +If the first connected hook is an +.Ar link +hook, the node will replicate such frames to all types of hooks, +even if +.Ar uplink +hooks are connected later. +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the +following: +.Bl -tag -width foo +.It Dv NGM_BRIDGE_SET_CONFIG Pq Ar setconfig +Set the node configuration. +This command takes a +.Vt "struct ng_bridge_config" +as an argument: +.Bd -literal -offset 0n +/* Node configuration structure */ +struct ng_bridge_config { + u_char debugLevel; /* debug level */ + uint32_t loopTimeout; /* link loopback mute time */ + uint32_t maxStaleness; /* max host age before nuking */ + uint32_t minStableAge; /* min time for a stable host */ +}; +.Ed +.Pp +The +.Va debugLevel +field sets the debug level on the node. +At level of 2 or greater, detected loops are logged. +The default level is 1. +.Pp +The +.Va loopTimeout +determines how long (in seconds) a looped link is muted. +The default is 60 seconds. +The +.Va maxStaleness +parameter determines how long a period of inactivity before +a host's entry is forgotten. +The default is 15 minutes. +The +.Va minStableAge +determines how quickly a host must jump from one link to another +before we declare a loopback condition. +The default is one second. +.It Dv NGM_BRIDGE_GET_CONFIG Pq Ar getconfig +Returns the current configuration as a +.Vt "struct ng_bridge_config" . +.It Dv NGM_BRIDGE_RESET Pq Ar reset +Causes the node to forget all hosts and unmute all links. +The node configuration is not changed. +.It Dv NGM_BRIDGE_GET_STATS Pq Ar getstats +This command takes a four byte link number as an argument and +returns a +.Vt "struct ng_bridge_link_stats" +containing statistics for the corresponding +.Ar link , +which must be currently connected: +.Bd -literal -offset 0n +/* Statistics structure (one for each link) */ +struct ng_bridge_link_stats { + uint64_t recvOctets; /* total octets rec'd on link */ + uint64_t recvPackets; /* total pkts rec'd on link */ + uint64_t recvMulticasts; /* multicast pkts rec'd on link */ + uint64_t recvBroadcasts; /* broadcast pkts rec'd on link */ + uint64_t recvUnknown; /* pkts rec'd with unknown dest addr */ + uint64_t recvRunts; /* pkts rec'd less than 14 bytes */ + uint64_t recvInvalid; /* pkts rec'd with bogus source addr */ + uint64_t xmitOctets; /* total octets xmit'd on link */ + uint64_t xmitPackets; /* total pkts xmit'd on link */ + uint64_t xmitMulticasts; /* multicast pkts xmit'd on link */ + uint64_t xmitBroadcasts; /* broadcast pkts xmit'd on link */ + uint64_t loopDrops; /* pkts dropped due to loopback */ + uint64_t loopDetects; /* number of loop detections */ + uint64_t memoryFailures; /* times couldn't get mem or mbuf */ +}; +.Ed +.Pp +Negative numbers refer to the +.Ar uplink +hooks. +So querying for -7 will get the statistics for hook +.Ar uplink7 . +.It Dv NGM_BRIDGE_CLR_STATS Pq Ar clrstats +This command takes a four byte link number as an argument and +clears the statistics for that link. +.It Dv NGM_BRIDGE_GETCLR_STATS Pq Ar getclrstats +Same as +.Dv NGM_BRIDGE_GET_STATS , +but also atomically clears the statistics as well. +.It Dv NGM_BRIDGE_GET_TABLE Pq Ar gettable +Returns the current host mapping table used to direct packets, in a +.Vt "struct ng_bridge_host_ary" . +.It Dv NGM_BRIDGE_SET_PERSISTENT Pq Ar setpersistent +This command sets the persistent flag on the node, and takes no arguments. +.It Dv NGM_BRIDGE_MOVE_HOST Pq Ar movehost +This command takes a +.Vt "struct ng_bridge_move_host" +as an argument. +It assigns the MAC +.Va addr +to the +.Va hook . +If the +.Va hook +is the empty string, the incoming hook of the control message is +used as fallback. +.Pp +If necessary, the MAC is removed from the currently assigned hook and +moved to the new one. +If the MAC is moved faster than +.Va minStableAge , +the hook is considered as a loop and will block traffic for +.Va loopTimeout +seconds. +.Bd -literal -offset 0n +struct ng_bridge_move_host { + u_char addr[ETHER_ADDR_LEN]; /* ethernet address */ + char hook[NG_HOOKSIZ]; /* link where addr can be found */ +}; +.Ed +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +Setting the persistent flag via a +.Dv NGM_BRIDGE_SET_PERSISTENT +control message disables automatic node shutdown when the last hook gets +disconnected. +.Sh FILES +.Bl -tag -width XXXXXXXX -compact +.It Pa /usr/share/examples/netgraph/ether.bridge +Example script showing how to set up a bridging network +.El +.Sh SEE ALSO +.Xr if_bridge 4 , +.Xr netgraph 4 , +.Xr ng_ether 4 , +.Xr ng_hub 4 , +.Xr ng_one2many 4 , +.Xr ngctl 8 +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 4.2 . +.Sh AUTHORS +.An Archie Cobbs Aq Mt archie@FreeBSD.org +.Sh BUGS +The +.Nm +node refuses to create the +.Ar uplink0 +hook to avoid later ambiguity with the +.Dv NGM_BRIDGE_GET_STATS +message. diff --git a/static/freebsd/man4/ng_btsocket.4 b/static/freebsd/man4/ng_btsocket.4 new file mode 100644 index 00000000..d16ccccb --- /dev/null +++ b/static/freebsd/man4/ng_btsocket.4 @@ -0,0 +1,353 @@ +.\" Copyright (c) 2001-2002 Maksim Yevmenkin +.\" 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. +.\" +.\" $Id: ng_btsocket.4,v 1.7 2003/05/21 19:37:35 max Exp $ +.\" +.Dd November 13, 2012 +.Dt NG_BTSOCKET 4 +.Os +.Sh NAME +.Nm ng_btsocket +.Nd Bluetooth sockets layer +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In sys/bitstring.h +.In netgraph/bluetooth/include/ng_hci.h +.In netgraph/bluetooth/include/ng_l2cap.h +.In netgraph/bluetooth/include/ng_btsocket.h +.Sh DESCRIPTION +The +.Nm +module implements three Netgraph node types. +Each type in its turn implements one protocol within +.Dv PF_BLUETOOTH +domain. +.Sh Dv BLUETOOTH_PROTO_HCI protocol +.Ss Dv SOCK_RAW HCI sockets +Implemented by +.Nm btsock_hci_raw +Netgraph type. +Raw HCI sockets allow sending of raw HCI command datagrams +only to correspondents named in +.Xr send 2 +calls. +Raw HCI datagrams (HCI commands, events and data) are generally received with +.Xr recvfrom 2 , +which returns the next datagram with its return address. +Raw HCI sockets can also be used to control HCI nodes. +.Pp +The Bluetooth raw HCI socket address is defined as follows: +.Bd -literal -offset indent +/* Bluetooth version of struct sockaddr for raw HCI sockets */ +struct sockaddr_hci { + u_char hci_len; /* total length */ + u_char hci_family; /* address family */ + char hci_node[32]; /* address (size == NG_NODESIZ ) */ +}; +.Ed +.Pp +Raw HCI sockets support a number of +.Xr ioctl 2 +requests such as: +.Bl -tag -width foo +.It Dv SIOC_HCI_RAW_NODE_GET_STATE +Returns current state for the HCI node. +.It Dv SIOC_HCI_RAW_NODE_INIT +Turn on +.Dq inited +bit for the HCI node. +.It Dv SIOC_HCI_RAW_NODE_GET_DEBUG +Returns current debug level for the HCI node. +.It Dv SIOC_HCI_RAW_NODE_SET_DEBUG +Sets current debug level for the HCI node. +.It Dv SIOC_HCI_RAW_NODE_GET_BUFFER +Returns current state of data buffers for the HCI node. +.It Dv SIOC_HCI_RAW_NODE_GET_BDADDR +Returns BD_ADDR for the HCI node. +.It Dv SIOC_HCI_RAW_NODE_GET_FEATURES +Returns the list of features supported by hardware for the HCI node. +.It Dv SIOC_HCI_RAW_NODE_GET_STAT +Returns various statistic counters for the HCI node. +.It Dv SIOC_HCI_RAW_NODE_RESET_STAT +Resets all statistic counters for the HCI node to zero. +.It Dv SIOC_HCI_RAW_NODE_FLUSH_NEIGHBOR_CACHE +Remove all neighbor cache entries for the HCI node. +.It Dv SIOC_HCI_RAW_NODE_GET_NEIGHBOR_CACHE +Returns content of the neighbor cache for the HCI node. +.It Dv SIOC_HCI_RAW_NODE_GET_CON_LIST +Returns list of active baseband connections (i.e., ACL and SCO links) for +the HCI node. +.It SIOC_HCI_RAW_NODE_GET_LINK_POLICY_MASK +Returns current link policy settings mask for the HCI node. +.It SIOC_HCI_RAW_NODE_SET_LINK_POLICY_MASK +Sets current link policy settings mask for the HCI node. +.It SIOC_HCI_RAW_NODE_GET_PACKET_MASK +Returns current packet mask for the HCI node. +.It SIOC_HCI_RAW_NODE_SET_PACKET_MASK +Sets current packet mask for the HCI node. +.It SIOC_HCI_RAW_NODE_GET_ROLE_SWITCH +Returns current value of the role switch parameter for the HCI node. +.It SIOC_HCI_RAW_NODE_SET_ROLE_SWITCH +Sets new value of the role switch parameter for the HCI node. +.El +.Pp +The +.Va net.bluetooth.hci.sockets.raw.ioctl_timeout +variable, that can be examined and set via +.Xr sysctl 8 , +controls the control request timeout (in seconds) for raw HCI sockets. +.Pp +Raw HCI sockets support filters. +The application can filter certain HCI datagram types. +For HCI event datagrams the application can set additional filter. +The raw HCI socket filter defined as follows: +.Bd -literal -offset indent +/* + * Raw HCI socket filter. + * + * For packet mask use (1 << (HCI packet indicator - 1)) + * For event mask use (1 << (Event - 1)) + */ + +struct ng_btsocket_hci_raw_filter { + bitstr_t bit_decl(packet_mask, 32); + bitstr_t bit_decl(event_mask, (NG_HCI_EVENT_MASK_SIZE * 8)); +}; +.Ed +.Pp +The +.Dv SO_HCI_RAW_FILTER +option defined at +.Dv SOL_HCI_RAW +level can be used to obtain via +.Xr getsockopt 2 +or change via +.Xr setsockopt 2 +raw HCI socket's filter. +.Sh Dv BLUETOOTH_PROTO_L2CAP protocol +The Bluetooth L2CAP socket address is defined as follows: +.Bd -literal -offset indent +/* Bluetooth version of struct sockaddr for L2CAP sockets */ +struct sockaddr_l2cap { + u_char l2cap_len; /* total length */ + u_char l2cap_family; /* address family */ + uint16_t l2cap_psm; /* Protocol/Service Multiplexor */ + bdaddr_t l2cap_bdaddr; /* address */ +}; +.Ed +.Ss Dv SOCK_RAW L2CAP sockets +Implemented by +.Nm btsock_l2c_raw +Netgraph type. +Raw L2CAP sockets do not provide access to raw L2CAP datagrams. +These +sockets used to control L2CAP nodes and to issue special L2CAP requests +such as +.Dv ECHO_REQUEST +and +.Dv GET_INFO +request. +.Pp +Raw L2CAP sockets support number of +.Xr ioctl 2 +requests such as: +.Bl -tag -width foo +.It Dv SIOC_L2CAP_NODE_GET_FLAGS +Returns current state for the L2CAP node. +.It Dv SIOC_L2CAP_NODE_GET_DEBUG +Returns current debug level for the L2CAP node. +.It Dv SIOC_L2CAP_NODE_SET_DEBUG +Sets current debug level for the L2CAP node. +.It Dv SIOC_L2CAP_NODE_GET_CON_LIST +Returns list of active baseband connections (i.e., ACL links) for the L2CAP +node. +.It Dv SIOC_L2CAP_NODE_GET_CHAN_LIST +Returns list of active channels for the L2CAP node. +.It Dv SIOC_L2CAP_NODE_GET_AUTO_DISCON_TIMO +Returns current value of the auto disconnect timeout for the L2CAP node. +.It Dv SIOC_L2CAP_NODE_SET_AUTO_DISCON_TIMO +Sets current value of the auto disconnect timeout for the L2CAP node. +.It Dv SIOC_L2CAP_L2CA_PING +Issues L2CAP +.Dv ECHO_REQUEST . +.It Dv SIOC_L2CAP_L2CA_GET_INFO +Issues L2CAP +.Dv GET_INFO +request. +.El +.Pp +The +.Va net.bluetooth.l2cap.sockets.raw.ioctl_timeout +variable, that can be examined and set via +.Xr sysctl 8 , +controls the control request timeout (in seconds) for raw L2CAP sockets. +.Ss Dv SOCK_SEQPACKET L2CAP sockets +Implemented by +.Nm btsock_l2c +Netgraph type. +L2CAP sockets are either +.Dq active +or +.Dq passive . +Active sockets initiate connections to passive sockets. +By default, L2CAP sockets are created active; to create a passive socket, the +.Xr listen 2 +system call must be used after binding the socket with the +.Xr bind 2 +system call. +Only passive sockets may use the +.Xr accept 2 +call to accept incoming connections. +Only active sockets may use the +.Xr connect 2 +call to initiate connections. +.Pp +L2CAP sockets support +.Dq "wildcard addressing" . +In this case, socket must be bound to +.Dv NG_HCI_BDADDR_ANY +address. +Note that PSM (Protocol/Service Multiplexor) field is always required. +Once a connection has been established, the socket's address is +fixed by the peer entity's location. +The address assigned to the socket is +the address associated with the Bluetooth device through which packets are +being transmitted and received, and PSM (Protocol/Service Multiplexor). +.Pp +L2CAP sockets support number of options defined at +.Dv SOL_L2CAP +level which can be set with +.Xr setsockopt 2 +and tested with +.Xr getsockopt 2 : +.Bl -tag -width foo +.It Dv SO_L2CAP_IMTU +Get (set) maximum payload size the local socket is capable of accepting. +.It Dv SO_L2CAP_OMTU +Get maximum payload size the remote socket is capable of accepting. +.It Dv SO_L2CAP_IFLOW +Get incoming flow specification for the socket. +.Bf -emphasis +Not implemented. +.Ef +.It Dv SO_L2CAP_OFLOW +Get (set) outgoing flow specification for the socket. +.Bf -emphasis +Not implemented. +.Ef +.It Dv SO_L2CAP_FLUSH +Get (set) value of the flush timeout. +.Bf -emphasis +Not implemented. +.Ef +.El +.Sh Dv BLUETOOTH_PROTO_RFCOMM protocol +The Bluetooth RFCOMM socket address is defined as follows: +.Bd -literal -offset indent +/* Bluetooth version of struct sockaddr for RFCOMM sockets */ +struct sockaddr_rfcomm { + u_char rfcomm_len; /* total length */ + u_char rfcomm_family; /* address family */ + bdaddr_t rfcomm_bdaddr; /* address */ + uint8_t rfcomm_channel; /* channel */ +}; +.Ed +.Ss Dv SOCK_STREAM RFCOMM sockets +Note that RFCOMM sockets do not have associated Netgraph node type. +RFCOMM sockets are implemented as additional layer on top of L2CAP sockets. +RFCOMM sockets are either +.Dq active +or +.Dq passive . +Active sockets initiate connections to passive sockets. +By default, RFCOMM sockets are created active; to create a passive socket, the +.Xr listen 2 +system call must be used after binding the socket with the +.Xr bind 2 +system call. +Only passive sockets may use the +.Xr accept 2 +call to accept incoming connections. +Only active sockets may use the +.Xr connect 2 +call to initiate connections. +.Pp +RFCOMM sockets support +.Dq "wildcard addressing" . +In this case, socket must be bound to +.Dv NG_HCI_BDADDR_ANY +address. +Note that RFCOMM channel field is always required. +Once a connection has been established, the socket's address is fixed by the +peer entity's location. +The address assigned to the socket is the address associated with the +Bluetooth device through which packets are being transmitted and received, +and RFCOMM channel. +.Pp +The following options, which can be tested with +.Xr getsockopt 2 +call, are defined at +.Dv SOL_RFCOMM +level for RFCOMM sockets: +.Bl -tag -width foo +.It Dv SO_RFCOMM_MTU +Returns the maximum transfer unit size (in bytes) for the underlying RFCOMM +channel. +Note that application still can write/read bigger chunks to/from the socket. +.It Dv SO_RFCOMM_FC_INFO +Return the flow control information for the underlying RFCOMM channel. +.El +.Pp +The +.Va net.bluetooth.rfcomm.sockets.stream.timeout +variable, that can be examined and set via +.Xr sysctl 8 , +controls the connection timeout (in seconds) for RFCOMM sockets. +.Sh HOOKS +These node types support hooks with arbitrary names (as long as they are +unique) and always accept hook connection requests. +.Sh NETGRAPH CONTROL MESSAGES +These node types support the generic control messages. +.Sh SHUTDOWN +These nodes are persistent and cannot be shut down. +.Sh SEE ALSO +.Xr btsockstat 1 , +.Xr socket 2 , +.Xr netgraph 4 , +.Xr ng_bluetooth 4 , +.Xr ng_hci 4 , +.Xr ng_l2cap 4 , +.Xr ngctl 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +module was implemented in +.Fx 5.0 . +.Sh AUTHORS +.An Maksim Yevmenkin Aq Mt m_evmenkin@yahoo.com +.Sh BUGS +Most likely. +Please report if found. diff --git a/static/freebsd/man4/ng_car.4 b/static/freebsd/man4/ng_car.4 new file mode 100644 index 00000000..e111a86b --- /dev/null +++ b/static/freebsd/man4/ng_car.4 @@ -0,0 +1,216 @@ +.\" Copyright (c) 2005 Nuno Antunes +.\" Copyright (c) 2007 Alexander Motin +.\" 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 January 27, 2021 +.Dt NG_CAR 4 +.Os +.Sh NAME +.Nm ng_car +.Nd Committed Access Rate netgraph node type +.Sh SYNOPSIS +.In netgraph/ng_car.h +.Sh DESCRIPTION +The +.Nm car +node type limits traffic flowing through it using: +.Pp +.Bl -bullet -compact +.It +Single rate three color marker as described in RFC 2697, +.It +Two rate three color marker as described in RFC 2698, +.It +RED-like rate limit algorithm used by Cisco, +.It +Traffic shaping with RED. +.El +.Sh HOOKS +This node type supports the following hooks: +.Bl -tag -width ".Va upper" +.It Va upper +Hook leading to upper layer protocols. +.It Va lower +Hook leading to lower layer protocols. +.El +.Pp +Traffic flowing from +.Va upper +to +.Va lower +is considered +.Sy downstream +traffic. +Traffic flowing from +.Va lower +to +.Va upper +is considered +.Sy upstream +traffic. +.Sh MODES OF OPERATION +Each hook can operate in one of the following modes: +.Bl -tag -width foo +.It Dv NG_CAR_SINGLE_RATE +Single rate three color marker as described in RFC 2697. +Committed burst packets are counted as green, extended burst packets are +counted as yellow and exceeding packets are counted as red. +Committed burst getting refilled with CIR (Committed Information Rate) speed. +When it is full, exceeded burst getting refilled. +.It Dv NG_CAR_DOUBLE_RATE +Two rate three color marker as described in RFC 2698. +Committed burst packets are counted as green, peak burst packets are counted +as yellow and exceeding packets are counted as red. +Committed burst getting refilled with CIR speed. +Peak burst getting refilled with PIR (Peak Information Rate) speed at the +same time. +.It Dv NG_CAR_RED +Similar to +.Dv NG_CAR_SINGLE_RATE , +but with different understanding of extended burst. +When normal burst exceeded and extended burst is used, packets are counted +red with probability equal to part of extended burst consumed. +Extended burst getting refilled first. +When it is full, committed burst getting refilled. +This behavior is similar to RED active queue management algorithm. +.Pp +This algorithm is more polite to the TCP traffic than NG_CAR_SINGLE_RATE. +.It Dv NG_CAR_SHAPE +Committed burst packets are counted as green, exceeding packets are delayed +by queue with RED management and counted as yellow. +Packets dropped by queue counted as red. +Queue parameters are hardcoded: length 99 packets, min_th 8 packets, max_p 100%. +.Pp +Traffic shaping is much more polite to the TCP traffic than rate limit on +links with bandwidth * delay product less than 6-8 TCP segments, but it +consumes additional system resources for queue processing. +.El +.Pp +By default, all information rates are measured in bits per second and bursts +are measured in bytes. +But when NG_CAR_COUNT_PACKETS option is enabled, +rates are measured in packets per second and bursts are in packets. +.Sh CONTROL MESSAGES +This node type supports the generic control messages and the following +specific messages. +.Bl -tag -width foo +.It Dv NGM_CAR_SET_CONF Pq Ic setconf +Set node configuration to the specified at +.Vt "struct ng_car_bulkconf" +.It Dv NGM_CAR_GET_CONF Pq Ic getconf +Return current node configuration as +.Vt "struct ng_car_bulkconf" +.Bd -literal +struct ng_car_hookconf { + uint64_t cbs; /* Committed burst size (bytes) */ + uint64_t ebs; /* Exceeded/Peak burst size (bytes) */ + uint64_t cir; /* Committed information rate (bits/s) */ + uint64_t pir; /* Peak information rate (bits/s) */ + uint8_t green_action; /* Action for green packets */ + uint8_t yellow_action; /* Action for yellow packets */ + uint8_t red_action; /* Action for red packets */ + uint8_t mode; /* single/double rate, ... */ + uint8_t opt; /* color-aware or color-blind */ +}; + +/* possible actions (..._action) */ +enum { + NG_CAR_ACTION_FORWARD = 1, + NG_CAR_ACTION_DROP, + NG_CAR_ACTION_MARK +}; + +/* operation modes (mode) */ +enum { + NG_CAR_SINGLE_RATE = 0, + NG_CAR_DOUBLE_RATE, + NG_CAR_RED, + NG_CAR_SHAPE +}; + +/* mode options (bits for opt) */ +#define NG_CAR_COLOR_AWARE 1 +#define NG_CAR_COUNT_PACKETS 2 + +struct ng_car_bulkconf { + struct ng_car_hookconf upstream; + struct ng_car_hookconf downstream; +}; +.Ed +.It Dv NGM_CAR_GET_STATS Pq Ic getstats +Return node statistics as +.Vt "struct ng_car_bulkstats" +.Bd -literal +struct ng_car_hookstats { + uint64_t passed_pkts; /* Counter for passed packets */ + uint64_t dropped_pkts; /* Counter for dropped packets */ + uint64_t green_pkts; /* Counter for green packets */ + uint64_t yellow_pkts; /* Counter for yellow packets */ + uint64_t red_pkts; /* Counter for red packets */ + uint64_t errors; /* Counter for operation errors */ +}; + +struct ng_car_bulkstats { + struct ng_car_hookstats upstream; + struct ng_car_hookstats downstream; +}; +.Ed +.It Dv NGM_CAR_CLR_STATS Pq Ic clrstats +Clear node statistics. +.It Dv NGM_CAR_GETCLR_STATS Pq Ic getclrstats +Atomically return and clear node statistics. +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +.Sh EXAMPLES +Limit outgoing data rate over fxp0 Ethernet interface to 20Mbit/s +and incoming packet rate to 5000pps. +.Bd -literal -offset indent +/usr/sbin/ngctl -f- <<-SEQ + mkpeer fxp0: car lower lower + name fxp0:lower fxp0_car + connect fxp0: fxp0_car: upper upper + msg fxp0_car: setconf { downstream={ cir=20000000 cbs=2500000 ebs=2500000 greenAction=1 yellowAction=1 redAction=2 mode=2 } upstream={ cir=5000 cbs=100 ebs=100 greenAction=1 yellowAction=1 redAction=2 mode=2 opt=2 } } +SEQ +.Ed +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ngctl 8 +.Rs +.%A J. Heinanen +.%T "A Single Rate Three Color Marker" +.%O RFC 2697 +.Re +.Rs +.%A J. Heinanen +.%T "A Two Rate Three Color Marker" +.%O RFC 2698 +.Re +.Sh AUTHORS +.An Nuno Antunes Aq Mt nuno.antunes@gmail.com +.An Alexander Motin Aq Mt mav@FreeBSD.org +.Sh BUGS +At this moment only DROP and FORWARD actions are implemented. diff --git a/static/freebsd/man4/ng_checksum.4 b/static/freebsd/man4/ng_checksum.4 new file mode 100644 index 00000000..d57f1b00 --- /dev/null +++ b/static/freebsd/man4/ng_checksum.4 @@ -0,0 +1,145 @@ +.\" Copyright (c) 2015 Dmitry Vagin +.\" 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 October 29, 2015 +.Dt NG_CHECKSUM 4 +.Os +.Sh NAME +.Nm ng_checksum +.Nd reconstructing IP checksums node type +.Sh SYNOPSIS +.In netgraph/ng_checksum.h +.Sh DESCRIPTION +The +.Nm checksum +node can calculate, or prepare for calculation in hardware, +IPv4 header, TCP and UDP checksums. +.Sh HOOKS +This node type has two hooks: +.Bl -tag -width ".Va out" +.It Va in +Packets received on this hook are processed according to settings specified +in config and then forwarded to the +.Ar out +hook, if it exists and is connected. +Otherwise they are reflected back to the +.Ar in +hook. +.It Va out +Packets received on this hook are forwarded to the +.Ar in +hook without any changes. +.El +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_CHECKSUM_SETDLT Pq Ic setdlt +Sets the data link type on the +.Va in +hook. +Currently, supported types are +.Cm DLT_RAW +(raw IP datagrams) and +.Cm DLT_EN10MB +(Ethernet). DLT_ definitions can be found in the +.In net/bpf.h +header. +Currently used values are +.Cm DLT_EN10MB += 1 and +.Cm DLT_RAW += 12. +.It Dv NGM_CHECKSUM_GETDLT Pq Ic getdlt +This control message obtains the data link type on the +.Va in +hook. +.It Dv NGM_CHECKSUM_SETCONFIG Pq Ic setconfig +Sets the node configuration. +The following +.Vt "struct ng_checksum_config" +must be supplied as an argument: +.Bd -literal -offset 4n +struct ng_checksum_config { + uint64_t csum_flags; + uint64_t csum_offload; +}; +.Ed +.Pp +The +.Va csum_flags +can be set to any combination of CSUM_IP, CSUM_TCP, CSUM_UDP, CSUM_TCP_IPV6 and CSUM_UDP_IPV6 +(other values are ignored) for instructing the node to calculate the corresponding checksum. +.Pp +The +.Va csum_offload +value can be set to any combination of CSUM_IP, CSUM_TCP, CSUM_UDP, CSUM_TCP_IPV6 and CSUM_UDP_IPV6 +(other values are ignored) for instructing the node what checksums should be requested from the hardware. +.Pp +The node also takes into account any combination of +CSUM_IP, CSUM_TCP, CSUM_UDP, CSUM_TCP_IPV6 and CSUM_UDP_IPV6 already +flagged on the mbuf. +.It Dv NGM_CHECKSUM_GETCONFIG Pq Ic getconfig +This control message obtains the current node configuration returned as a +.Vt "struct ng_checksum_config" . +.It Dv NGM_CHECKSUM_GET_STATS Pq Ic getstats +Returns node statistics as a +.Vt "struct ng_checksum_stats" . +.It Dv NGM_CHECKSUM_CLR_STATS Pq Ic clrstats +Clear the node statistics. +.It Dv NGM_CHECKSUM_GETCLR_STATS Pq Ic getclrstats +This command is identical to +.Dv NGM_CHECKSUM_GET_STATS , +except that the statistics are also atomically cleared. +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +.Sh EXAMPLES +.Xr ngctl 8 +script: +.Bd -literal -offset 4n +/usr/sbin/ngctl -f- <<-SEQ + msg checksum-1: setdlt 1 + msg checksum-1: setconfig { csum_flags=0 csum_offload=6 } +SEQ +.Ed +.Pp +Set the data link type to +.Cm DLT_EN10MB +(Ethernet), do not set additional checksum flags +and request that the hardware calculate CSUM_IP_UDP|CSUM_IP_TCP. +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ng_patch 4 , +.Xr ngctl 8 +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 10.2 +and first submitted in +.Fx 12.0 . +.Sh AUTHORS +.An "Dmitry Vagin" Aq daemon.hammer@ya.ru . diff --git a/static/freebsd/man4/ng_cisco.4 b/static/freebsd/man4/ng_cisco.4 new file mode 100644 index 00000000..f32b13f9 --- /dev/null +++ b/static/freebsd/man4/ng_cisco.4 @@ -0,0 +1,182 @@ +.\" Copyright (c) 1996-1999 Whistle Communications, Inc. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, use and +.\" redistribution of this software, in source or object code forms, with or +.\" without modifications are expressly permitted by Whistle Communications; +.\" provided, however, that: +.\" 1. Any and all reproductions of the source or object code must include the +.\" copyright notice above and the following disclaimer of warranties; and +.\" 2. No rights are granted, in any manner or form, to use Whistle +.\" Communications, Inc. trademarks, including the mark "WHISTLE +.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as +.\" such appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, +.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. +.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY +.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS +.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. +.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES +.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING +.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY +.\" OF SUCH DAMAGE. +.\" +.\" Author: Archie Cobbs +.\" $Whistle: ng_cisco.8,v 1.5 1999/01/25 23:46:26 archie Exp $ +.\" +.Dd January 19, 1999 +.Dt NG_CISCO 4 +.Os +.Sh NAME +.Nm ng_cisco +.Nd Cisco HDLC protocol netgraph node type +.Sh SYNOPSIS +.In sys/types.h +.In netinet/in.h +.In netgraph/ng_cisco.h +.Sh DESCRIPTION +The +.Nm cisco +node type performs encapsulation and de-encapsulation of packets +using the Cisco HDLC protocol. +This is a fairly simple +protocol for the transmission of packets across +high speed synchronous lines. +Each packet is prepended with +an Ethertype, indicating the protocol. +There is also a +.Dq keep alive +and an +.Dq inquire +capability. +.Pp +The +.Dv downstream +hook should connect to the synchronous line. +On the other side +of the node are the +.Dv inet , +.Dv inet6 , +.Dv atalk , +and +.Dv ipx +hooks, which transmit and receive raw IP, IPv6, AppleTalk, and IPX packets, +respectively. +Typically these hooks would connect to the corresponding +hooks on an +.Xr ng_iface 4 +type node. +.Sh IP Configuration +In order to function properly for IP traffic, the node must be informed +of the local IP address and netmask setting. +This is because the protocol +includes an +.Dq inquire +packet which we must be prepared to answer. +There are two ways to accomplish this, manually and automatically. +.Pp +Whenever such an inquire packet is received, the node sends a +.Dv NGM_CISCO_GET_IPADDR +control message to the peer node connected to the +.Dv inet +hook (if any). +If the peer responds, then that response is used. +This is the automatic method. +.Pp +If the peer does not respond, the node falls back on its cached value +for the IP address and netmask. +This cached value can be set at any time +with a +.Dv NGM_CISCO_SET_IPADDR +message, and this is the manual method. +.Pp +If the +.Dv inet +hook is connected to the +.Dv inet +hook of an +.Xr ng_iface 4 +node, as is usually the case, then configuration is automatic as the +.Xr ng_iface 4 +understands the +.Dv NGM_CISCO_GET_IPADDR +message. +.Sh HOOKS +This node type supports the following hooks: +.Bl -tag -width ".Va downstream" +.It Va downstream +The connection to the synchronous line. +.It Va inet +IP hook. +.It Va inet6 +IPv6 hook. +.It Va atalk +AppleTalk hook. +.It Va ipx +IPX hook. +.El +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_CISCO_SET_IPADDR Pq Ic setipaddr +This command takes an array of two +.Dv "struct in_addr" +arguments. +The first is the IP address of the corresponding interface +and the second is the netmask. +.It Dv NGM_CISCO_GET_IPADDR Pq Ic getipaddr +This command returns the IP configuration in the same format used by +.Dv NGM_CISCO_SET_IPADDR . +This command is also +.Em sent +by this node type to the +.Dv inet +peer whenever an IP address inquiry packet is received. +.It Dv NGM_CISCO_GET_STATUS Pq Ic getstats +Returns a +.Dv "struct ngciscostat" : +.Bd -literal -offset 4n +struct ngciscostat { + uint32_t seqRetries; /* # unack'd retries */ + uint32_t keepAlivePeriod; /* in seconds */ +}; +.Ed +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ng_iface 4 , +.Xr ngctl 8 +.Rs +.%A D. Perkins +.%T "Requirements for an Internet Standard Point-to-Point Protocol" +.%O RFC 1547 +.Re +.Sh LEGAL +.Tn Cisco +is a trademark of Cisco Systems, Inc. +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 4.0 . +.Sh AUTHORS +.An Julian Elischer Aq Mt julian@FreeBSD.org +.An Archie Cobbs Aq Mt archie@FreeBSD.org +.Sh BUGS +Not all of the functionality has been implemented. +For example, +the node does not support querying the remote end for its IP address +and netmask. diff --git a/static/freebsd/man4/ng_deflate.4 b/static/freebsd/man4/ng_deflate.4 new file mode 100644 index 00000000..397efe62 --- /dev/null +++ b/static/freebsd/man4/ng_deflate.4 @@ -0,0 +1,157 @@ +.\" +.\" Author: Alexander Motin +.\" +.\" Copyright (c) 2006, Alexander Motin +.\" 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 unmodified, 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 December 23, 2006 +.Dt NG_DEFLATE 4 +.Os +.Sh NAME +.Nm ng_deflate +.Nd Deflate PPP compression (RFC 1979) netgraph node type +.Sh SYNOPSIS +.In sys/types.h +.In netgraph/ng_deflate.h +.Sh DESCRIPTION +The +.Nm deflate +node type implements the Deflate sub-protocols of the Compression Control +Protocol (CCP). +.Pp +The node has two hooks, +.Va comp +for compression and +.Va decomp +for decompression. +Only one of them can be connected at the same time, specifying node's +operation mode. +Typically that hooks would be connected to the +.Xr ng_ppp 4 +node type hook of the same name. +Corresponding +.Xr ng_ppp 4 +node hook must be switched to +.Dv NG_PPP_DECOMPRESS_FULL +mode to permit sending uncompressed frames. +.Sh HOOKS +This node type supports the following hooks: +.Pp +.Bl -tag -compact -width ".Va decomp" +.It Va comp +Connection to +.Xr ng_ppp 4 +.Va comp +hook. +Incoming frames are compressed (if possible) and sent back out the same hook. +.It Va decomp +Connection to +.Xr ng_ppp 4 +.Va decomp +hook. +Incoming frames are decompressed (if they are compressed), and sent +back out the same hook. +.El +.Pp +Only one hook can be connected at the same time, specifying node's +operation mode. +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_DEFLATE_CONFIG Pq Ic config +This command resets and configures the node for a session +(i.e., for compression or decompression). +This command takes a +.Vt "struct ng_deflate_config" +as an argument: +.Bd -literal -offset 0n +struct ng_deflate_config { + u_char enable; /* node enabled */ + u_char windowBits; /* log2(Window size) */ +}; +.Ed +The +.Fa enabled +field enables traffic flow through the node. +The +.Fa windowBits +specify compression windows size as negotiated by the +Compression Control Protocol (CCP) in PPP. +.It Dv NGM_DEFLATE_RESETREQ Pq Ic resetreq +This message contains no arguments, and is bi-directional. +If an error is detected during decompression, this message is sent by the +node to the originator of the +.Dv NGM_DEFLATE_CONFIG +message that initiated the session. +The receiver should respond by sending a PPP CCP Reset-Request to the peer. +.Pp +This message may also be received by this node type when a CCP Reset-Request +or Reset-Ack is received by the local PPP entity. +The node will respond by flushing its compression state so the sides +can resynchronize. +.It Dv NGM_DEFLATE_GET_STATS Pq Ic getstats +This control message obtains statistics for a given hook. +The statistics are returned in +.Vt "struct ng_deflate_stats" : +.Bd -literal +struct ng_deflate_stats { + uint64_t FramesPlain; + uint64_t FramesComp; + uint64_t FramesUncomp; + uint64_t InOctets; + uint64_t OutOctets; + uint64_t Errors; +}; +.Ed +.It Dv NGM_DEFLATE_CLR_STATS Pq Ic clrstats +This control message clears statistics for a given hook. +.It Dv NGM_DEFLATE_GETCLR_STATS Pq Ic getclrstats +This control message obtains and clears statistics for a given hook. +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when hook have been disconnected. +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ng_ppp 4 , +.Xr ngctl 8 +.Rs +.%A J. Woods +.%T "PPP Deflate Protocol" +.%O RFC 1979 +.Re +.Rs +.%A W. Simpson +.%T "The Point-to-Point Protocol (PPP)" +.%O RFC 1661 +.Re +.Sh AUTHORS +.An Alexander Motin Aq Mt mav@alkar.net +.Sh BUGS +Due to nature of netgraph PPP implementation there are possible race conditions +between data packet and ResetAck CCP packet in case of packet loss. +As result, +packet loss can produce bigger performance degradation than supposed by protocol. diff --git a/static/freebsd/man4/ng_device.4 b/static/freebsd/man4/ng_device.4 new file mode 100644 index 00000000..003c9bc9 --- /dev/null +++ b/static/freebsd/man4/ng_device.4 @@ -0,0 +1,102 @@ +.\" Copyright (c) 2002 Mark Santcroos +.\" +.\" 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. 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 November 8, 2021 +.Dt NG_DEVICE 4 +.Os +.Sh NAME +.Nm ng_device +.Nd device netgraph node type +.Sh SYNOPSIS +.In netgraph/ng_device.h +.Sh DESCRIPTION +A +.Nm device +node is both a netgraph node and a system device interface. +When a +.Nm device +node is created, a new device entry appears which is accessible via the +regular file operators such as +.Xr open 2 , +.Xr close 2 , +.Xr read 2 , +.Xr write 2 , +etc. +.Pp +The first node is created as +.Pa /dev/ngd0 , +subsequent nodes are +.Pa /dev/ngd1 , /dev/ngd2 , +etc. +.Sh HOOKS +A +.Nm device +node has a single hook with an arbitrary name. +All data coming in over the hook will be presented to the device +for +.Xr read 2 . +All data coming in from the device entry by +.Xr write 2 +will be forwarded to the hook. +.Sh CONTROL MESSAGES +The +.Nm device +node supports the generic control messages, plus the following: +.Bl -tag -width 3n +.It Dv NGM_DEVICE_GET_DEVNAME +Returns the device name corresponding to the node. +.It Dv NGM_DEVICE_ETHERALIGN +Apply the system ETHER_ALIGN offset to mbufs sent out the node's hook, +if running on an architecture that requires strict alignment. +Use this option when the data being injected via the device node ultimately +ends up being fed into the protocol stack as ethernet packets (e.g., via +an +.Xr ng_eiface 4 +node). +.El +.\" Additionally, the node accepts +.\" .Xr ioctl 2 Ns s +.\" from the device entry. +.\" These will be encapsulated into +.\" .Xr netgraph 4 +.\" messages and send out to the hook. +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or upon hook disconnection. +The associated device entry is removed and becomes available +for use by future +.Nm device +nodes. +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ngctl 8 +.Sh HISTORY +The +.Nm device +node type was first implemented in +.Fx 5.0 . +.Sh AUTHORS +.An Mark Santcroos Aq Mt marks@ripe.net +.An Gleb Smirnoff Aq Mt glebius@FreeBSD.org diff --git a/static/freebsd/man4/ng_echo.4 b/static/freebsd/man4/ng_echo.4 new file mode 100644 index 00000000..2300b4d4 --- /dev/null +++ b/static/freebsd/man4/ng_echo.4 @@ -0,0 +1,71 @@ +.\" Copyright (c) 1996-1999 Whistle Communications, Inc. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, use and +.\" redistribution of this software, in source or object code forms, with or +.\" without modifications are expressly permitted by Whistle Communications; +.\" provided, however, that: +.\" 1. Any and all reproductions of the source or object code must include the +.\" copyright notice above and the following disclaimer of warranties; and +.\" 2. No rights are granted, in any manner or form, to use Whistle +.\" Communications, Inc. trademarks, including the mark "WHISTLE +.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as +.\" such appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, +.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. +.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY +.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS +.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. +.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES +.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING +.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY +.\" OF SUCH DAMAGE. +.\" +.\" Author: Archie Cobbs +.\" $Whistle: ng_echo.8,v 1.4 1999/01/25 23:46:26 archie Exp $ +.\" +.Dd January 19, 1999 +.Dt NG_ECHO 4 +.Os +.Sh NAME +.Nm ng_echo +.Nd netgraph echo node type +.Sh SYNOPSIS +.In netgraph/ng_echo.h +.Sh DESCRIPTION +The +.Nm echo +node type reflects all data and control messages back to the sender. +This node type is used for testing and debugging. +.Sh HOOKS +A +.Nm echo +node accepts any request to connect, regardless of the hook name, +as long as the name is unique. +.Sh CONTROL MESSAGES +This node type supports only the generic control messages. +Any other control messages are reflected back to the sender. +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ng_hole 4 , +.Xr ngctl 8 +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 4.0 . +.Sh AUTHORS +.An Julian Elischer Aq Mt julian@FreeBSD.org diff --git a/static/freebsd/man4/ng_eiface.4 b/static/freebsd/man4/ng_eiface.4 new file mode 100644 index 00000000..c2b64455 --- /dev/null +++ b/static/freebsd/man4/ng_eiface.4 @@ -0,0 +1,120 @@ +.\" Copyright (c) 2004 Gleb Smirnoff +.\" 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 May 14, 2019 +.Dt NG_EIFACE 4 +.Os +.Sh NAME +.Nm ng_eiface +.Nd "generic Ethernet interface netgraph node type" +.Sh SYNOPSIS +.In netgraph/ng_eiface.h +.Sh DESCRIPTION +The +.Vt eiface +netgraph node implements the generic Ethernet interface. +When an +.Vt eiface +node is created, a new interface appears which is accessible via +.Xr ifconfig 8 . +These interfaces are named +.Dq Li ngeth0 , +.Dq Li ngeth1 , +etc. +When a node is shut down, the corresponding interface is removed, +and the interface name becomes available for reuse by future +.Vt eiface +nodes. +New nodes always take the first unused interface. +.Sh HOOKS +An +.Vt eiface +node has a single hook named +.Va ether , +which should be connected to the +Ethernet downstream, for example, to the +.Xr ng_vlan 4 +node. +Packets transmitted via the interface flow out this hook. +Similarly, packets received on the hook go to the protocol stack as +packets received by any real Ethernet interface. +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_EIFACE_SET Pq Ic set +Set link-level address of the interface. +Requires +.Vt "struct ether_addr" +as an argument. +This message also has an +.Tn ASCII +version, called +.Dq Li set , +which requires as an argument an +.Tn ASCII +string consisting of 6 colon-separated hex digits. +.It Dv NGM_EIFACE_GET_IFNAME Pq Ic getifname +Return the name of the associated interface as a +.Dv NULL Ns -terminated +.Tn ASCII +string. +.It Dv NGM_EIFACE_GET_IFADDRS +Return the list of link-level addresses associated with the node. +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message. +The associated interface is removed and its name becomes +available for reuse by future +.Vt eiface +nodes. +.Pp +Unlike most other node types, an +.Vt eiface +node does +.Em not +go away when all hooks have been disconnected; rather, an explicit +.Dv NGM_SHUTDOWN +control message is required. +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ng_ether 4 , +.Xr ng_iface 4 , +.Xr ng_vlan 4 , +.Xr ifconfig 8 , +.Xr ngctl 8 +.Sh HISTORY +The +.Vt eiface +node type was implemented in +.Fx 4.6 . +.Sh AUTHORS +.An -nosplit +The +.Vt eiface +node type was written by +.An Vitaly V Belekhov . +This manual page was written by +.An Gleb Smirnoff . diff --git a/static/freebsd/man4/ng_etf.4 b/static/freebsd/man4/ng_etf.4 new file mode 100644 index 00000000..8aa4cdb8 --- /dev/null +++ b/static/freebsd/man4/ng_etf.4 @@ -0,0 +1,152 @@ +.\" +.\" Copyright (c) 2001, FreeBSD Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice unmodified, 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 November 13, 2012 +.Dt NG_ETF 4 +.Os +.Sh NAME +.Nm ng_etf +.Nd Ethertype filtering netgraph node type +.Sh SYNOPSIS +.In netgraph.h +.In netgraph/ng_etf.h +.Sh DESCRIPTION +The +.Nm etf +node type multiplexes and filters data between hooks on the basis +of the ethertype found in an Ethernet header, presumed to be in the +first 14 bytes of the data. +Incoming Ethernet frames are accepted on the +.Em downstream +hook and if the ethertype matches a value which the node has been configured +to filter, the packet is forwarded out the hook which was identified +at the time that value was configured. +If it does not match a configured +value, it is passed to the +.Em nomatch +hook. +If the +.Em nomatch +hook is not connected, the packet is dropped. +.Pp +Packets travelling in the other direction (towards the +.Em downstream +hook) are also examined and filtered. +If a packet has an ethertype that matches one of the values configured +into the node, it must have arrived in on the hook for which that value +was configured, otherwise it will be discarded. +Ethertypes of values other +than those configured by the control messages must have arrived via the +.Em nomatch +hook. +.Sh HOOKS +This node type supports the following hooks: +.Bl -tag -width ".Aq Em any legal name" +.It Em downstream +Typically this hook would be connected to a +.Xr ng_ether 4 +node, using the +.Em lower +hook. +.It Em nomatch +Typically this hook would also be connected to an +.Xr ng_ether 4 +type node using the +.Em upper +hook. +.It Aq Em "any legal name" +Any other hook name will be accepted and can be used as the match target +of an ethertype. +Typically this hook would be attached to +a protocol handling node that requires and generates packets +with a particular set of ethertypes. +.El +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width 4n +.It Dv NGM_ETF_GET_STATUS Pq Ic getstatus +This command returns a +.Vt "struct ng_etfstat" +containing node statistics for packet counts. +.It Dv NGM_ETF_SET_FILTER Pq Ic setfilter +Sets the a new ethertype filter into the node and specifies the hook to and +from which packets of that type should use. +The hook and ethertype +are specified in a structure of type +.Vt "struct ng_etffilter" : +.Bd -literal -offset 4n +struct ng_etffilter { + char matchhook[NG_HOOKSIZ]; /* hook name */ + uint16_t ethertype; /* this ethertype to this hook */ +}; +.Ed +.El +.Sh EXAMPLES +Using +.Xr ngctl 8 +it is possible to set a filter in place from the command line +as follows: +.Bd -literal -offset 4n +#!/bin/sh +ETHER_IF=fxp0 +MATCH1=0x834 +MATCH2=0x835 +cat </tmp/xwert +# Make a new ethertype filter and attach to the Ethernet lower hook. +# first remove left over bits from last time. +shutdown ${ETHER_IF}:lower +mkpeer ${ETHER_IF}: etf lower downstream +# Give it a name to easily refer to it. +name ${ETHER_IF}:lower etf +# Connect the nomatch hook to the upper part of the same interface. +# All unmatched packets will act as if the filter is not present. +connect ${ETHER_IF}: etf: upper nomatch +DONE +ngctl -f /tmp/xwert + +# something to set a hook to catch packets and show them. +echo "Unrecognised packets:" +nghook -a etf: newproto & +# Filter two random ethertypes to that hook. +ngctl 'msg etf: setfilter { matchhook="newproto" ethertype=${MATCH1} } +ngctl 'msg etf: setfilter { matchhook="newproto" ethertype=${MATCH2} } +.Ed +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ng_ether 4 , +.Xr ngctl 8 , +.Xr nghook 8 +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 5.0 . +.Sh AUTHORS +.An Julian Elischer Aq Mt julian@FreeBSD.org diff --git a/static/freebsd/man4/ng_ether.4 b/static/freebsd/man4/ng_ether.4 new file mode 100644 index 00000000..79c30ca7 --- /dev/null +++ b/static/freebsd/man4/ng_ether.4 @@ -0,0 +1,239 @@ +.\" Copyright (c) 2000 Whistle Communications, Inc. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, use and +.\" redistribution of this software, in source or object code forms, with or +.\" without modifications are expressly permitted by Whistle Communications; +.\" provided, however, that: +.\" 1. Any and all reproductions of the source or object code must include the +.\" copyright notice above and the following disclaimer of warranties; and +.\" 2. No rights are granted, in any manner or form, to use Whistle +.\" Communications, Inc. trademarks, including the mark "WHISTLE +.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as +.\" such appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, +.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. +.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY +.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS +.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. +.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES +.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING +.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY +.\" OF SUCH DAMAGE. +.\" +.\" Author: Archie Cobbs +.\" +.Dd June 23, 2011 +.Dt NG_ETHER 4 +.Os +.Sh NAME +.Nm ng_ether +.Nd Ethernet netgraph node type +.Sh SYNOPSIS +.In netgraph/ng_ether.h +.Sh DESCRIPTION +The +.Nm ether +netgraph node type allows Ethernet interfaces to interact with +the +.Xr netgraph 4 +networking subsystem. +Once the +.Nm +module is loaded into the kernel, a node is automatically created +for each Ethernet interface in the system. +Each node will attempt to name itself with the same name +as the associated interface. +.Pp +Three hooks are supported: +.Va lower , upper , +and +.Va orphans . +The hook name +.Va divert +may be used as an alias for +.Va lower , +and is provided for backward compatibility. +In reality, the two names represent the same hook. +.Pp +The +.Va lower +hook is a connection to the raw Ethernet device. +When connected, all incoming packets are forwarded to this hook, +instead of being passed to the kernel for upper layer processing. +Writing to this hook results in a raw Ethernet frame being transmitted +by the device. +Normal outgoing packets are not affected by +.Va lower +being connected. +.Pp +The +.Va upper +hook is a connection to the upper protocol layers. +When connected, all outgoing packets are forwarded to this hook, +instead of being transmitted by the device. +Writing to this hook results in a raw Ethernet frame being received by +the kernel just as if it had come in over the wire. +Normal incoming packets are not affected by +.Va upper +being connected. +.Pp +The +.Va orphans +hook is equivalent to +.Va lower , +except that only unrecognized packets (that would otherwise be discarded) +are written to the hook, while other normal incoming traffic is unaffected. +Unrecognized packets written to +.Va upper +will be forwarded back out to +.Va orphans +if connected. +.Pp +In all cases, frames are raw Ethernet frames with the standard +14 byte Ethernet header (but no checksum). +.Pp +When no hooks are connected, +.Va upper +and +.Va lower +are in effect connected together, +so that packets flow normally upwards and downwards. +.Sh HOOKS +This node type supports the following hooks: +.Bl -tag -width ".Va orphans" +.It Va lower +Connection to the lower device link layer. +.It Va upper +Connection to the upper protocol layers. +.It Va orphans +Like +.Va lower , +but only receives unrecognized packets. +.El +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_ETHER_GET_IFNAME Pq Ic getifname +Returns the name of the associated interface as a +.Dv NUL Ns -terminated +.Tn ASCII +string. +Normally this is the same as the name of the node. +.It Dv NGM_ETHER_GET_IFINDEX Pq Ic getifindex +Returns the global index of the associated interface as a 32 bit integer. +.It Dv NGM_ETHER_GET_ENADDR Pq Ic getenaddr +Returns the device's unique six byte Ethernet address. +.It Dv NGM_ETHER_SET_ENADDR Pq Ic setenaddr +Sets the device's unique six byte Ethernet address. +This control message is equivalent to using the +.Dv SIOCSIFLLADDR +.Xr ioctl 2 +system call. +.It Dv NGM_ETHER_SET_PROMISC Pq Ic setpromisc +Enable or disable promiscuous mode. +This message includes a single 32 bit integer flag that enables or +disables promiscuous mode on the interface. +Any non-zero value enables promiscuous mode. +.It Dv NGM_ETHER_GET_PROMISC Pq Ic getpromisc +Get the current value of the node's promiscuous flag. +The returned value is always either one or zero. +Note that this flag reflects the node's own promiscuous setting +and does not necessarily reflect the promiscuous state of the actual +interface, which can be affected by other means (e.g., +.Xr bpf 4 ) . +.It Dv NGM_ETHER_SET_AUTOSRC Pq Ic setautosrc +Sets the automatic source address override flag. +This message includes a single 32 bit integer flag that causes +all outgoing packets to have their source Ethernet +address field overwritten with the device's unique Ethernet address. +If this flag is set to zero, the source address in outgoing packets +is not modified. +The default setting for this flag is disabled. +.It Dv NGM_ETHER_GET_AUTOSRC Pq Ic getautosrc +Get the current value of the node's source address override flag. +The returned value is always either one or zero. +.It Dv NGM_ETHER_ADD_MULTI Pq Ic addmulti +Join Ethernet multicast group. +This control message is equivalent to using the +.Dv SIOCADDMULTI +.Xr ioctl 2 +system call. +.It Dv NGM_ETHER_DEL_MULTI Pq Ic delmulti +Leave Ethernet multicast group. +This control message is equivalent to using the +.Dv SIOCDELMULTI +.Xr ioctl 2 +system call. +.It Dv NGM_ETHER_DETACH Pq Ic detach +Detach from underlying Ethernet interface and shut down node. +.El +.Sh SHUTDOWN +Upon receipt of the +.Dv NGM_SHUTDOWN +control message, all hooks are disconnected, promiscuous mode is disabled, +but the node is not removed. +Node can be shut down only using +.Dv NGM_ETHER_DETACH +control message. +If the interface itself is detached (e.g., because of PC Card removal), the +node disappears as well. +.Sh EXAMPLES +This command dumps all unrecognized packets received by the +.Dq Li fxp0 +interface to standard output decoded in hex and +.Tn ASCII : +.Pp +.Dl "nghook -a fxp0: orphans" +.Pp +This command sends the contents of +.Pa sample.pkt +out the interface +.Dq Li fxp0 : +.Pp +.Dl "cat sample.pkt | nghook fxp0: orphans" +.Pp +These commands insert an +.Xr ng_tee 4 +node between the +.Va lower +and +.Va upper +protocol layers, which can be used for +tracing packet flow, statistics, etc.: +.Bd -literal -offset indent +ngctl mkpeer fxp0: tee lower right +ngctl connect fxp0: lower upper left +.Ed +.Sh SEE ALSO +.Xr arp 4 , +.Xr netgraph 4 , +.Xr netintro 4 , +.Xr ifconfig 8 , +.Xr ngctl 8 , +.Xr nghook 8 +.Sh AUTHORS +.An Julian Elischer Aq Mt julian@FreeBSD.org +.An Archie Cobbs Aq Mt archie@FreeBSD.org +.Sh BUGS +The automatic KLD module loading mechanism that works for most +other Netgraph node types does not work for the +.Nm ether +node type, +because +.Nm ether +nodes are not created on demand; instead, they are created when +Ethernet interfaces are attached or when the KLD is first loaded. +Therefore, if the KLD is not statically compiled into the kernel, +it is necessary to load the KLD manually in order to bring the +.Nm ether +nodes into existence. diff --git a/static/freebsd/man4/ng_ether_echo.4 b/static/freebsd/man4/ng_ether_echo.4 new file mode 100644 index 00000000..061c0ee8 --- /dev/null +++ b/static/freebsd/man4/ng_ether_echo.4 @@ -0,0 +1,75 @@ +.\" Copyright (c) 1996-1999 Whistle Communications, Inc. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, use and +.\" redistribution of this software, in source or object code forms, with or +.\" without modifications are expressly permitted by Whistle Communications; +.\" provided, however, that: +.\" 1. Any and all reproductions of the source or object code must include the +.\" copyright notice above and the following disclaimer of warranties; and +.\" 2. No rights are granted, in any manner or form, to use Whistle +.\" Communications, Inc. trademarks, including the mark "WHISTLE +.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as +.\" such appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, +.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. +.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY +.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS +.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. +.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES +.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING +.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY +.\" OF SUCH DAMAGE. +.\" +.\" Author: Archie Cobbs +.\" $Whistle: ng_echo.8,v 1.4 1999/01/25 23:46:26 archie Exp $ +.\" +.Dd December 24, 2008 +.Dt NG_ETHER_ECHO 4 +.Os +.Sh NAME +.Nm ng_ether_echo +.Nd netgraph ether_echo node type +.Sh SYNOPSIS +.In netgraph/ng_ether_echo.h +.Sh DESCRIPTION +The +.Nm ether_echo +node type reflects all data and control messages back to the sender. +It assumes (and does not check) that the packet is an ethernet frame, +and swaps the source and destination addresses before echoing it. +This node type is used for testing and debugging. +.Sh HOOKS +A +.Nm ether_echo +node accepts any request to connect, regardless of the hook name, +as long as the name is unique. +.Sh CONTROL MESSAGES +This node type supports only the generic control messages. +Any other control messages are reflected back to the sender. +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ng_echo 4 , +.Xr ng_ether 4 , +.Xr ng_hole 4 , +.Xr ngctl 8 +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 8.0 . +.Sh AUTHORS +.An Julian Elischer Aq Mt julian@FreeBSD.org diff --git a/static/freebsd/man4/ng_frame_relay.4 b/static/freebsd/man4/ng_frame_relay.4 new file mode 100644 index 00000000..91d9d4b5 --- /dev/null +++ b/static/freebsd/man4/ng_frame_relay.4 @@ -0,0 +1,97 @@ +.\" Copyright (c) 1996-1999 Whistle Communications, Inc. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, use and +.\" redistribution of this software, in source or object code forms, with or +.\" without modifications are expressly permitted by Whistle Communications; +.\" provided, however, that: +.\" 1. Any and all reproductions of the source or object code must include the +.\" copyright notice above and the following disclaimer of warranties; and +.\" 2. No rights are granted, in any manner or form, to use Whistle +.\" Communications, Inc. trademarks, including the mark "WHISTLE +.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as +.\" such appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, +.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. +.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY +.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS +.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. +.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES +.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING +.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY +.\" OF SUCH DAMAGE. +.\" +.\" Author: Archie Cobbs +.\" $Whistle: ng_frame_relay.8,v 1.4 1999/01/25 23:46:26 archie Exp $ +.\" +.Dd January 19, 1999 +.Dt NG_FRAME_RELAY 4 +.Os +.Sh NAME +.Nm ng_frame_relay +.Nd frame relay netgraph node type +.Sh SYNOPSIS +.In netgraph/ng_frame_relay.h +.Sh DESCRIPTION +The +.Nm frame_relay +node type performs encapsulation, de-encapsulation, and multiplexing +of packets using the frame relay protocol. +It supports up to 1024 DLCI's. +The LMI protocol is handled by a separate node type (see +.Xr ng_lmi 4 ) . +.Pp +The +.Dv downstream +hook should be connected to the synchronous line, i.e., the switch. +Then hooks +.Dv dlci0 , +.Dv dlci1 , +through +.Dv dlci1023 +are available to connect to each of the DLCI channels. +.Sh HOOKS +This node type supports the following hooks: +.Bl -tag -width ".Va downstream" +.It Va downstream +The connection to the synchronous line. +.It Va dlciX +Here X is a decimal number from 0 to 1023. +This hook corresponds +to the DLCI X frame relay virtual channel. +.El +.Sh CONTROL MESSAGES +This node type supports only the generic control messages. +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ng_lmi 4 , +.Xr ngctl 8 +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 4.0 . +.Sh AUTHORS +.An Julian Elischer Aq Mt julian@FreeBSD.org +.Sh BUGS +Technically, frames on DLCI X should not be transmitted to the switch +until the LMI protocol entity on both ends has configured DLCI X as active. +The +.Nm +node type ignores this restriction, and will always pass data received +on a DLCI hook to +.Dv downstream . +Instead, it should query the LMI node first. diff --git a/static/freebsd/man4/ng_gif.4 b/static/freebsd/man4/ng_gif.4 new file mode 100644 index 00000000..405f34a0 --- /dev/null +++ b/static/freebsd/man4/ng_gif.4 @@ -0,0 +1,124 @@ +.\" Copyright 2000 The Aerospace Corporation. 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. The name of The Aerospace Corporation may not be used to endorse or +.\" promote products derived from this software. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AEROSPACE CORPORATION "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 AEROSPACE CORPORATION 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. +.\" +.\" Author: Brooks Davis +.\" +.Dd September 18, 2001 +.Dt NG_GIF 4 +.Os +.Sh NAME +.Nm ng_gif +.Nd generic tunnel interface netgraph node type +.Sh SYNOPSIS +.In netgraph/ng_gif.h +.Sh DESCRIPTION +The +.Nm +netgraph node type allows +.Xr gif 4 +interfaces to interact with +the +.Xr netgraph 4 +networking subsystem. +Once the +.Nm +module is loaded in the kernel, a node is automatically created +for each +.Xr gif 4 +interface in the system. +Each node will attempt to name itself with the same name +as the associated interface. +All +.Nm +nodes are persistent for as long as the interface itself exists. +.Pp +Two hooks are supported: +.Dv lower +and +.Dv orphans . +The hook name +.Dv divert +may be used as an alias for +.Dv lower , +and is provided for compatibility with +.Xr ng_ether 4 . +In reality the two names represent the same hook. +.Pp +The +.Dv lower +hook is a connection to the raw +.Xr gif 4 +device. +When connected, all incoming packets are diverted out this hook. +Writing to this hook results in a raw encapsulated packet being transmitted +by the device. +Normal outgoing packets are not affected by +.Dv lower +being connected. +.Pp +The +.Dv orphans +hook is equivalent to +.Dv lower , +except that only unrecognized packets (that would otherwise be discarded) +are written to the hook, and normal incoming traffic is unaffected. +At most one of +.Dv orphans +and +.Dv lower +may be connected at any time. +.Pp +In all cases, frames are raw packets with the address family of the +packet attached to the front. +.Pp +When no hooks are connected, packets flow normally upwards and downwards. +.Sh HOOKS +This node type supports the following hooks: +.Bl -tag -width ".Va orphans" +.It Va lower +Connection to the lower device link layer. +.It Va orphans +Like +.Dv lower , +but only receives unrecognized packets. +.El +.Sh CONTROL MESSAGES +This node type supports only the generic control messages. +.Sh EXAMPLES +This command dumps all unrecognized packets received by the +.Li gif0 +interface to standard output decoded in hex and ASCII: +.Pp +.Dl "nghook -a gif0: orphans" +.Sh SEE ALSO +.Xr gif 4 , +.Xr netgraph 4 , +.Xr netintro 4 , +.Xr ifconfig 8 , +.Xr ngctl 8 , +.Xr nghook 8 +.Sh AUTHORS +.An Brooks Davis Aq Mt brooks@FreeBSD.org diff --git a/static/freebsd/man4/ng_gif_demux.4 b/static/freebsd/man4/ng_gif_demux.4 new file mode 100644 index 00000000..2855c256 --- /dev/null +++ b/static/freebsd/man4/ng_gif_demux.4 @@ -0,0 +1,105 @@ +.\" Copyright 2000 The Aerospace Corporation. 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. The name of The Aerospace Corporation may not be used to endorse or +.\" promote products derived from this software. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AEROSPACE CORPORATION "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 AEROSPACE CORPORATION 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. +.\" +.\" Author: Brooks Davis +.\" +.Dd September 18, 2001 +.Dt NG_GIF_DEMUX 4 +.Os +.Sh NAME +.Nm ng_gif_demux +.Nd demultiplexer for packets from +.Xr ng_gif 4 +nodes +.Sh SYNOPSIS +.In netgraph/ng_gif_demux.h +.Sh DESCRIPTION +The +.Nm +netgraph node type demultiplexes the output from +.Xr ng_gif 4 +nodes in the +.Xr netgraph 4 +networking subsystem. +.Pp +The +.Dv gif +hook is meant to be connected to the +.Dv lower +or +.Dv orphans +hook of an +.Xr ng_gif 4 +node. +The +.Dv inet , inet6 , atalk , ipx , atm , natm , +and +.Dv ns +hooks output frames of the given type when they are received on the +.Dv gif +hook. +When a frame is received on one of these hooks, it is encapsulated and +sent out the +.Dv gif +hook. +.Sh HOOKS +This node type supports the following hooks: +.Bl -tag -width ".Dv inet6" +.It Va gif +Connection to the +.Dv lower +or +.Dv orphans +hook of an +.Xr ng_gif 4 +node. +.It Va inet +Hook for input and output of IP frames. +.It Va inet6 +Hook for input and output of IPv6 frames. +.It Va atalk +Hook for input and output of AppleTalk frames. +.It Va ipx +Hook for input and output of IPX frames. +.It Va atm +Hook for input and output of ATM frames. +.It Va natm +Hook for input and output of NATM frames. +.It Va ns +Hook for input and output of NS frames. +.El +.Sh CONTROL MESSAGES +This node type supports only the generic control messages. +.Sh SEE ALSO +.Xr gif 4 , +.Xr netgraph 4 , +.Xr netintro 4 , +.Xr ng_gif 4 , +.Xr ifconfig 8 , +.Xr ngctl 8 , +.Xr nghook 8 +.Sh AUTHORS +.An Brooks Davis Aq Mt brooks@FreeBSD.org diff --git a/static/freebsd/man4/ng_hci.4 b/static/freebsd/man4/ng_hci.4 new file mode 100644 index 00000000..559d21cb --- /dev/null +++ b/static/freebsd/man4/ng_hci.4 @@ -0,0 +1,386 @@ +.\" Copyright (c) 2001-2002 Maksim Yevmenkin +.\" 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. +.\" +.\" $Id: ng_hci.4,v 1.3 2003/05/21 19:37:35 max Exp $ +.\" +.Dd June 25, 2002 +.Dt NG_HCI 4 +.Os +.Sh NAME +.Nm ng_hci +.Nd Netgraph node type that is also a Bluetooth Host Controller Interface +(HCI) layer +.Sh SYNOPSIS +.In sys/types.h +.In netgraph/bluetooth/include/ng_hci.h +.Sh DESCRIPTION +The +.Nm hci +node type is a Netgraph node type that implements Bluetooth Host Controller +Interface (HCI) layer as per chapter H1 of the Bluetooth Specification Book +v1.1. +.Sh INTRODUCTION TO BLUETOOTH +Bluetooth is a short-range radio link intended to replace the cable(s) +connecting portable and/or fixed electronic devices. +Bluetooth operates in the unlicensed ISM band at 2.4 GHz. +The Bluetooth protocol uses a +combination of circuit and packet switching. +Bluetooth can support an +asynchronous data channel, up to three simultaneous synchronous voice +channels, or a channel which simultaneously supports asynchronous data +and synchronous voice. +Each voice channel supports a 64 kb/s synchronous +(voice) channel in each direction. +The asynchronous channel can support +maximal 723.2 kb/s asymmetric (and still up to 57.6 kb/s in the return +direction), or 433.9 kb/s symmetric. +.Pp +The Bluetooth system provides a point-to-point connection (only two +Bluetooth units involved), or a point-to-multipoint connection. +In the point-to-multipoint connection, +the channel is shared among several Bluetooth units. +Two or more units sharing the same channel form a +.Dq piconet . +One Bluetooth unit acts as the master of the piconet, whereas the other +unit(s) acts as slave(s). +Up to seven slaves can be active in the piconet. +In addition, many more slaves can remain locked to the master in a so-called +parked state. +These parked slaves cannot be active on the channel, but remain +synchronized to the master. +Both for active and parked slaves, the channel +access is controlled by the master. +.Pp +Multiple piconets with overlapping coverage areas form a +.Dq scatternet . +Each piconet can only have a single master. +However, slaves can participate +in different piconets on a time-division multiplex basis. +In addition, a master in one piconet can be a slave in another piconet. +The piconets shall not be frequency-synchronized. +Each piconet has its own hopping channel. +.Ss Time Slots +The channel is divided into time slots, each 625 usec in length. +The time +slots are numbered according to the Bluetooth clock of the piconet master. +The slot numbering ranges from 0 to 2^27 -1 and is cyclic with a cycle length +of 2^27. +In the time slots, master and slave can transmit packets. +.Ss SCO Link +The SCO link is a symmetric, point-to-point link between the master and a +specific slave. +The SCO link reserves slots and can therefore be considered +as a circuit-switched connection between the master and the slave. +The SCO link typically supports time-bounded information like voice. +The master can +support up to three SCO links to the same slave or to different slaves. +A slave can support up to three SCO links from the same master, or two SCO +links if the links originate from different masters. +SCO packets are never retransmitted. +.Ss ACL Link +In the slots not reserved for SCO links, the master can exchange packets +with any slave on a per-slot basis. +The ACL link provides a packet-switched +connection between the master and all active slaves participating in the +piconet. +Both asynchronous and isochronous services are supported. +Between a master and a slave only a single ACL link can exist. +For most ACL packets, +packet retransmission is applied to assure data integrity. +.Sh HOST CONTROLLER INTERFACE (HCI) +The HCI provides a command interface to the baseband controller and link +manager, and access to hardware status and control registers. +This interface +provides a uniform method of accessing the Bluetooth baseband capabilities. +.Pp +The HCI layer on the Host exchanges data and commands with the HCI firmware +on the Bluetooth hardware. +The Host Controller Transport Layer (i.e., physical +bus) driver provides both HCI layers with the ability to exchange information +with each other. +.Pp +The Host will receive asynchronous notifications of HCI events independent +of which Host Controller Transport Layer is used. +HCI events are used for +notifying the Host when something occurs. +When the Host discovers that an +event has occurred it will then parse the received event packet to determine +which event occurred. +The next sections specify the HCI packet formats. +.Ss HCI Command Packet +.Bd -literal -offset indent +#define NG_HCI_CMD_PKT 0x01 +typedef struct { + uint8_t type; /* MUST be 0x1 */ + uint16_t opcode; /* OpCode */ + uint8_t length; /* parameter(s) length in bytes */ +} __attribute__ ((packed)) ng_hci_cmd_pkt_t; +.Ed +.Pp +The HCI command packet is used to send commands to the Host Controller +from the Host. +When the Host Controller completes most of the commands, +a Command Complete event is sent to the Host. +Some commands do not receive +a Command Complete event when they have been completed. +Instead, when the +Host Controller receives one of these commands the Host Controller sends +a Command Status event back to the Host when it has begun to execute the +command. +Later on, when the actions associated with the command have finished, +an event that is associated with the sent command will be sent by the Host +Controller to the Host. +.Ss HCI Event Packet +.Bd -literal -offset indent +#define NG_HCI_EVENT_PKT 0x04 +typedef struct { + uint8_t type; /* MUST be 0x4 */ + uint8_t event; /* event */ + uint8_t length; /* parameter(s) length in bytes */ +} __attribute__ ((packed)) ng_hci_event_pkt_t; +.Ed +.Pp +The HCI event packet is used by the Host Controller to notify the Host +when events occur. +.Ss HCI ACL Data Packet +.Bd -literal -offset indent +#define NG_HCI_ACL_DATA_PKT 0x02 +typedef struct { + uint8_t type; /* MUST be 0x2 */ + uint16_t con_handle; /* connection handle + PB + BC flags */ + uint16_t length; /* payload length in bytes */ +} __attribute__ ((packed)) ng_hci_acldata_pkt_t; +.Ed +.Pp +HCI ACL data packets are used to exchange ACL data between the Host and +Host Controller. +.Ss HCI SCO Data Packet +.Bd -literal -offset indent +#define NG_HCI_SCO_DATA_PKT 0x03 +typedef struct { + uint8_t type; /* MUST be 0x3 */ + uint16_t con_handle; /* connection handle + reserved bits */ + uint8_t length; /* payload length in bytes */ +} __attribute__ ((packed)) ng_hci_scodata_pkt_t; +.Ed +.Pp +HCI SCO data packets are used to exchange SCO data between the Host and +Host Controller. +.Sh HCI INITIALIZATION +On initialization, HCI control application must issue the following HCI +commands (in any order). +.Bl -tag -width foo +.It Dv Read_BD_ADDR +To obtain BD_ADDR of the Bluetooth unit. +.It Dv Read_Local_Supported_Features +To obtain the list of features supported by Bluetooth unit. +.It Dv Read_Buffer_Size +To determine the maximum size of HCI ACL and SCO HCI data packets (excluding +header) that can be sent from the Host to the Host Controller. +There are also +two additional return parameters that specify the total number of HCI ACL and +SCO data packets that the Host Controller can have waiting for transmission in +its buffers. +.El +.Pp +As soon as HCI initialization has been successfully performed, HCI control +application must turn on +.Dq inited +bit for the node. +Once HCI node has been initialized all upstream hooks +will receive a +.Dv NGM_HCI_NODE_UP +Netgraph message defined as follows. +.Bd -literal -offset indent +#define NGM_HCI_NODE_UP 112 /* HCI -> Upper */ +typedef struct { + uint16_t pkt_size; /* max. ACL/SCO packet size (w/o hdr) */ + uint16_t num_pkts; /* ACL/SCO packet queue size */ + uint16_t reserved; /* place holder */ + bdaddr_t bdaddr; /* bdaddr */ +} ng_hci_node_up_ep; +.Ed +.Sh HCI FLOW CONTROL +HCI layer performs flow control on baseband connection basis (i.e., ACL and +SCO link). +Each baseband connection has +.Dq "connection handle" +and queue of outgoing data packets. +Upper layers protocols are allowed to +send up to +.Dv ( num_pkts +\- +.Dv pending ) +packets at one time. +HCI layer will send +.Dv NGM_HCI_SYNC_CON_QUEUE +Netgraph messages to inform upper layers about current queue state for each +connection handle. +The +.Dv NGM_HCI_SYNC_CON_QUEUE +Netgraph message is defined as follows. +.Bd -literal -offset indent +#define NGM_HCI_SYNC_CON_QUEUE 113 /* HCI -> Upper */ +typedef struct { + uint16_t con_handle; /* connection handle */ + uint16_t completed; /* number of completed packets */ +} ng_hci_sync_con_queue_ep; +.Ed +.Sh HOOKS +This node type supports the following hooks: +.Bl -tag -width ".Va drv" +.It Va drv +Bluetooth Host Controller Transport Layer hook. +Single HCI packet contained in single +.Vt mbuf +structure. +.It Va acl +Upper layer protocol/node is connected to the hook. +Single HCI ACL data packet contained in single +.Vt mbuf +structure. +.It Va sco +Upper layer protocol/node is connected to the hook. +Single HCI SCO data packet contained in single +.Vt mbuf +structure. +.It Va raw +Raw hook. +Every HCI frame (including HCI command frame) that goes in +or out will be delivered to the hook. +Usually the Bluetooth raw HCI socket layer is connected to the hook. +Single HCI frame contained in single +.Vt mbuf +structure. +.El +.Sh BLUETOOTH UPPER LAYER PROTOCOLS INTERFACE (LP CONTROL MESSAGES) +.Bl -tag -width foo +.It Dv NGM_HCI_LP_CON_REQ +Requests the lower protocol to create a connection. +If a physical link +to the remote device does not exist, this message must be sent to the lower +protocol (baseband) to establish the physical connection. +.It Dv NGM_HCI_LP_DISCON_REQ +Requests the lower protocol (baseband) to terminate a connection. +.It Dv NGM_HCI_LP_CON_CFM +Confirms success or failure of the +.Dv NGM_HCI_LP_CON_REQ +request to establish a lower layer (baseband) connection. +This includes passing the authentication challenge if authentication is +required to establish the physical link. +.It Dv NGM_HCI_LP_CON_IND +Indicates the lower protocol (baseband) has successfully established +incoming connection. +.It Dv NGM_HCI_LP_CON_RSP +A response accepting or rejecting the previous connection indication request. +.It Dv NGM_HCI_LP_DISCON_IND +Indicates the lower protocol (baseband) has terminated connection. +This could be a response to +.Dv NGM_HCI_LP_DISCON_REQ +or a timeout event. +.It Dv NGM_HCI_LP_QOS_REQ +Requests the lower protocol (baseband) to accommodate a particular QoS +parameter set. +.It Dv NGM_HCI_LP_QOS_CFM +Confirms success or failure of the request for a given quality of service. +.It Dv NGM_HCI_LP_QOS_IND +Indicates the lower protocol (baseband) has detected a violation of the QoS +agreement. +.El +.Sh NETGRAPH CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_HCI_NODE_GET_STATE +Returns current state for the node. +.It Dv NGM_HCI_NODE_INIT +Turn on +.Dq inited +bit for the node. +.It Dv NGM_HCI_NODE_GET_DEBUG +Returns an integer containing the current debug level for the node. +.It Dv NGM_HCI_NODE_SET_DEBUG +This command takes an integer argument and sets current debug level +for the node. +.It Dv NGM_HCI_NODE_GET_BUFFER +Returns current state of data buffers. +.It Dv NGM_HCI_NODE_GET_BDADDR +Returns BD_ADDR as cached in the node. +.It Dv NGM_HCI_NODE_GET_FEATURES +Returns the list of features supported by hardware (as cached by the node). +.It Dv NGM_HCI_NODE_GET_NEIGHBOR_CACHE +Returns content of the neighbor cache. +.It Dv NGM_HCI_NODE_FLUSH_NEIGHBOR_CACHE +Remove all neighbor cache entries. +.It Dv NGM_HCI_NODE_GET_CON_LIST +Returns list of active baseband connections (i.e., ACL and SCO links). +.It Dv NGM_HCI_NODE_GET_STAT +Returns various statistic counters. +.It Dv NGM_HCI_NODE_RESET_STAT +Resets all statistic counters to zero. +.It NGM_HCI_NODE_SET_LINK_POLICY_SETTINGS_MASK +Sets current link policy settings mask. +After the new ACL connection is +created the HCI node will try set link policy for the ACL connection. +By default, every supported Link Manager (LM) mode will be enabled. +User can +override this by setting link policy settings mask which specifies LM +modes to be enabled. +.It NGM_HCI_NODE_GET_LINK_POLICY_SETTINGS_MASK +Returns current link policy settings mask. +.It NGM_HCI_NODE_SET_PACKET_MASK +Sets current packet mask. +When new baseband (ACL or SCO) connection is +created the HCI node will specify every packet type supported by the device. +User can override this by setting packet mask which specifies packet types +to be used for new baseband connections. +.It NGM_HCI_NODE_GET_PACKET_MASK +Returns current packet mask. +.It NGM_HCI_NODE_SET_ROLE_SWITCH +Sets the value of the role switch. +Role switch is enabled when this value is not zero. +This is the default state. +Note that actual role switch at Bluetooth link level will only be performed if +hardware supports role switch and it was enabled. +.It NGM_HCI_NODE_GET_ROLE_SWITCH +Returns the value of the role switch for the node. +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or +when all hooks have been disconnected. +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr hccontrol 8 , +.Xr ngctl 8 +.Sh HISTORY +The +.Nm hci +node type was implemented in +.Fx 5.0 . +.Sh AUTHORS +.An Maksim Yevmenkin Aq Mt m_evmenkin@yahoo.com +.Sh BUGS +Most likely. +Please report if found. diff --git a/static/freebsd/man4/ng_hole.4 b/static/freebsd/man4/ng_hole.4 new file mode 100644 index 00000000..22945fb0 --- /dev/null +++ b/static/freebsd/man4/ng_hole.4 @@ -0,0 +1,89 @@ +.\" Copyright (c) 1996-1999 Whistle Communications, Inc. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, use and +.\" redistribution of this software, in source or object code forms, with or +.\" without modifications are expressly permitted by Whistle Communications; +.\" provided, however, that: +.\" 1. Any and all reproductions of the source or object code must include the +.\" copyright notice above and the following disclaimer of warranties; and +.\" 2. No rights are granted, in any manner or form, to use Whistle +.\" Communications, Inc. trademarks, including the mark "WHISTLE +.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as +.\" such appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, +.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. +.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY +.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS +.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. +.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES +.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING +.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY +.\" OF SUCH DAMAGE. +.\" +.\" Author: Archie Cobbs +.\" $Whistle: ng_hole.8,v 1.4 1999/01/25 23:46:26 archie Exp $ +.\" +.Dd May 19, 2004 +.Dt NG_HOLE 4 +.Os +.Sh NAME +.Nm ng_hole +.Nd netgraph discard node type +.Sh SYNOPSIS +.In sys/types.h +.In netgraph/ng_hole.h +.Sh DESCRIPTION +The +.Nm hole +node type silently discards all data and control messages it receives. +This type is used for testing and debugging. +.Sh HOOKS +A +.Nm +node accepts any request to connect, regardless of the hook name, +as long as the name is unique. +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the +following: +.Bl -tag -width foo +.It Dv NGM_HOLE_GET_STATS Pq Ic getstats +This command takes an +.Tn ASCII +string argument, the hook name, and returns the statistics +associated with the hook as a +.Vt "struct ng_hole_hookstat" . +.It Dv NGM_HOLE_CLR_STATS Pq Ic clrstats +This command takes an +.Tn ASCII +string argument, the hook name, and clears the statistics +associated with the hook. +.It Dv NGM_HOLE_GETCLR_STATS Pq Ic getclrstats +This command is identical to +.Dv NGM_HOLE_GET_STATS , +except that the statistics are also atomically cleared. +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ng_echo 4 , +.Xr ngctl 8 +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 4.0 . +.Sh AUTHORS +.An Julian Elischer Aq Mt julian@FreeBSD.org diff --git a/static/freebsd/man4/ng_hub.4 b/static/freebsd/man4/ng_hub.4 new file mode 100644 index 00000000..9959cca9 --- /dev/null +++ b/static/freebsd/man4/ng_hub.4 @@ -0,0 +1,73 @@ +.\" Copyright (c) 2004 Ruslan Ermilov +.\" 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 May 5, 2010 +.Dt NG_HUB 4 +.Os +.Sh NAME +.Nm ng_hub +.Nd packet distribution netgraph node type +.Sh SYNOPSIS +.In netgraph/ng_hub.h +.Sh DESCRIPTION +The +.Nm hub +node type provides a simple mechanism for distributing packets over +several links. +Packets received on any of the hooks are forwarded out the other hooks. +Packets are not altered in any way. +.Sh HOOKS +A +.Nm hub +node accepts any request to connect, regardless of the hook name, +as long as the name is unique. +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the +following: +.Bl -tag -width foo +.It Dv NGM_HUB_SET_PERSISTENT Pq Ic setpersistent +This command sets the persistent flag on the node, and takes no arguments. +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +Setting the persistent flag via a +.Dv NGM_HUB_SET_PERSISTENT +control message disables automatic node shutdown when the last hook gets +disconnected. +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ng_bridge 4 , +.Xr ng_ether 4 , +.Xr ng_one2many 4 , +.Xr ngctl 8 , +.Xr nghook 8 +.Sh HISTORY +The +.Nm +node type appeared in +.Fx 5.3 . +.Sh AUTHORS +.An Ruslan Ermilov Aq Mt ru@FreeBSD.org diff --git a/static/freebsd/man4/ng_iface.4 b/static/freebsd/man4/ng_iface.4 new file mode 100644 index 00000000..e2dee22b --- /dev/null +++ b/static/freebsd/man4/ng_iface.4 @@ -0,0 +1,164 @@ +.\" Copyright (c) 1996-1999 Whistle Communications, Inc. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, use and +.\" redistribution of this software, in source or object code forms, with or +.\" without modifications are expressly permitted by Whistle Communications; +.\" provided, however, that: +.\" 1. Any and all reproductions of the source or object code must include the +.\" copyright notice above and the following disclaimer of warranties; and +.\" 2. No rights are granted, in any manner or form, to use Whistle +.\" Communications, Inc. trademarks, including the mark "WHISTLE +.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as +.\" such appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, +.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. +.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY +.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS +.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. +.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES +.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING +.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY +.\" OF SUCH DAMAGE. +.\" +.\" Author: Archie Cobbs +.\" $Whistle: ng_iface.8,v 1.5 1999/01/25 23:46:26 archie Exp $ +.\" +.Dd July 31, 2020 +.Dt NG_IFACE 4 +.Os +.Sh NAME +.Nm ng_iface +.Nd interface netgraph node type +.Sh SYNOPSIS +.In netgraph/ng_iface.h +.Sh DESCRIPTION +An +.Nm iface +node is both a netgraph node and a system networking interface. +When an +.Nm iface +node is created, a new interface appears which is accessible via +.Xr ifconfig 8 . +.Nm Iface +node interfaces are named +.Dv ng0 , +.Dv ng1 , +etc. +When a node is shutdown, the corresponding interface is removed +and the interface name becomes available for reuse by future +.Nm iface +nodes; new nodes always take the first unused interface. +The node itself is assigned the same name as its interface, unless the name +already exists, in which case the node remains unnamed. +.Pp +An +.Nm iface +node has a single hook corresponding to each supported protocol. +Packets transmitted via the interface flow out the corresponding +protocol-specific hook. +Similarly, packets received on a hook appear on the interface as +packets received into the corresponding protocol stack. +The currently supported protocols are IP and IPv6. +.Pp +An +.Nm iface +node can be configured as a point-to-point interface or a broadcast interface. +The configuration can only be changed when the interface is down. +The default mode is point-to-point. +.Pp +.Nm Iface +nodes support the Berkeley Packet Filter (BPF). +.Sh HOOKS +This node type supports the following hooks: +.Bl -tag -width ".Va inet6" +.It Va inet +Transmission and reception of IP packets. +.It Va inet6 +Transmission and reception of IPv6 packets. +.El +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_IFACE_GET_IFNAME Pq Ic getifname +Returns the name of the associated interface as a +.Dv NUL Ns -terminated +.Tn ASCII +string. +Normally this is the same as the name of the node. +.It Dv NGM_IFACE_GET_IFINDEX Pq Ic getifindex +Returns the global index of the associated interface as a 32 bit integer. +.It Dv NGM_IFACE_POINT2POINT Pq Ic point2point +Set the interface to point-to-point mode. +The interface must not currently be up. +.It Dv NGM_IFACE_BROADCAST Pq Ic broadcast +Set the interface to broadcast mode. +The interface must not currently be up. +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message. +The associated interface is removed and becomes available +for use by future +.Nm iface +nodes. +.Pp +Unlike most other node types, an +.Nm iface +node does +.Em not +go away when all hooks have been disconnected; rather, and explicit +.Dv NGM_SHUTDOWN +control message is required. +.Sh ALTQ Support +The +.Nm +interface supports ALTQ bandwidth management feature. +However, +.Nm +is a special case, since it is not a physical interface with limited bandwidth. +One should not turn ALTQ on +.Nm +if the latter corresponds to some tunneled connection, e.g.\& PPPoE or PPTP. +In this case, ALTQ should be configured on the interface that is used to +transmit the encapsulated packets. +In case when your graph ends up with some kind of serial line, either +synchronous or modem, the +.Nm +is the right place to turn ALTQ on. +.Sh Nesting +.Nm +supports nesting, a configuration when traffic of one +.Nm +interface flows through the other. +The default maximum allowed nesting level is 2. +It can be changed at runtime setting +.Xr sysctl 8 +variable +.Va net.graph.iface.max_nesting +to the desired level of nesting. +.Sh SEE ALSO +.Xr altq 4 , +.Xr bpf 4 , +.Xr netgraph 4 , +.Xr ng_cisco 4 , +.Xr ifconfig 8 , +.Xr ngctl 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm iface +node type was implemented in +.Fx 4.0 . +.Sh AUTHORS +.An Archie Cobbs Aq Mt archie@FreeBSD.org diff --git a/static/freebsd/man4/ng_ip_input.4 b/static/freebsd/man4/ng_ip_input.4 new file mode 100644 index 00000000..73893c3f --- /dev/null +++ b/static/freebsd/man4/ng_ip_input.4 @@ -0,0 +1,100 @@ +.\" Copyright 2001 The Aerospace Corporation. 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. The name of The Aerospace Corporation may not be used to endorse or +.\" promote products derived from this software. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AEROSPACE CORPORATION "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 AEROSPACE CORPORATION 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. +.\" +.\" Copyright (c) 1996-1999 Whistle Communications, Inc. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, use and +.\" redistribution of this software, in source or object code forms, with or +.\" without modifications are expressly permitted by Whistle Communications; +.\" provided, however, that: +.\" 1. Any and all reproductions of the source or object code must include the +.\" copyright notice above and the following disclaimer of warranties; and +.\" 2. No rights are granted, in any manner or form, to use Whistle +.\" Communications, Inc. trademarks, including the mark "WHISTLE +.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as +.\" such appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, +.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. +.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY +.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS +.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. +.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES +.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING +.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY +.\" OF SUCH DAMAGE. +.\" +.\" Author: Brooks Davis +.\" Derived from: ng_hole.4 +.\" +.Dd September 27, 2001 +.Dt NG_IP_INPUT 4 +.Os +.Sh NAME +.Nm ng_ip_input +.Nd netgraph IP input node type +.Sh SYNOPSIS +.In netgraph/ng_ip_input.h +.Sh DESCRIPTION +The +.Nm ip_input +node type takes all received packets and queues them into the IP in +input processing subsystem. +.Sh HOOKS +An +.Nm +node accepts any request to connect, regardless of the hook name, +as long as the name is unique. +.Sh CONTROL MESSAGES +This node type supports only the generic control messages. +Other control messages are silently discarded. +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ngctl 8 +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 5.0 . +.Sh AUTHORS +.An Brooks Davis Aq Mt brooks@FreeBSD.org +.Sh BUGS +The +.Nm +node type should probably keep some sort of statistics. diff --git a/static/freebsd/man4/ng_ipfw.4 b/static/freebsd/man4/ng_ipfw.4 new file mode 100644 index 00000000..eef30ffa --- /dev/null +++ b/static/freebsd/man4/ng_ipfw.4 @@ -0,0 +1,115 @@ +.\" Copyright (c) 2005 Gleb Smirnoff +.\" 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 March 2, 2010 +.Dt NG_IPFW 4 +.Os +.Sh NAME +.Nm ng_ipfw +.Nd interface between netgraph and IP firewall +.Sh SYNOPSIS +.In netinet/ip_var.h +.In netgraph/ng_ipfw.h +.Sh DESCRIPTION +The +.Nm ipfw +node implements interface between +.Xr ipfw 4 +and +.Xr netgraph 4 +subsystems. +.Sh HOOKS +The +.Nm ipfw +node supports an arbitrary number of hooks, +which must be named using only numeric characters. +.Sh OPERATION +Once the +.Nm +module is loaded into the kernel, a single node named +.Va ipfw +is automatically created. +No more +.Nm ipfw +nodes can be created. +Once destroyed, the only way to recreate the node is to reload the +.Nm +module. +.Pp +Packets can be injected into +.Xr netgraph 4 +using either the +.Cm netgraph +or +.Cm ngtee +commands of the +.Xr ipfw 8 +utility. +These commands require a numeric cookie to be supplied as an argument. +Packets are sent out of the hook whose name equals the cookie value. +If no hook matches, packets are discarded. +Packets injected via the +.Cm netgraph +command are tagged with +.Vt "struct ipfw_rule_ref" . +This tag contains information that helps the packet to re-enter +.Xr ipfw 4 +processing, should the packet come back from +.Xr netgraph 4 +to +.Xr ipfw 4 . +.Pp +Packets received by a node from +.Xr netgraph 4 +subsystem must be tagged with +.Vt "struct ipfw_rule_ref" +tag. +Packets re-enter IP firewall processing at the next rule. +If no tag is supplied, packets are discarded. +.Sh CONTROL MESSAGES +This node type supports only the generic control messages. +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message. +Do not do this, since the new +.Nm ipfw +node can only be created by reloading the +.Nm +module. +.Sh SEE ALSO +.Xr ipfw 4 , +.Xr netgraph 4 , +.Xr ipfw 8 , +.Xr mbuf_tags 9 +.Sh HISTORY +The +.Nm ipfw +node type was implemented in +.Fx 6.0 . +.Sh AUTHORS +The +.Nm ipfw +node was written by +.An Gleb Smirnoff Aq Mt glebius@FreeBSD.org . diff --git a/static/freebsd/man4/ng_ksocket.4 b/static/freebsd/man4/ng_ksocket.4 new file mode 100644 index 00000000..bb653c36 --- /dev/null +++ b/static/freebsd/man4/ng_ksocket.4 @@ -0,0 +1,247 @@ +.\" Copyright (c) 1999 Whistle Communications, Inc. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, use and +.\" redistribution of this software, in source or object code forms, with or +.\" without modifications are expressly permitted by Whistle Communications; +.\" provided, however, that: +.\" 1. Any and all reproductions of the source or object code must include the +.\" copyright notice above and the following disclaimer of warranties; and +.\" 2. No rights are granted, in any manner or form, to use Whistle +.\" Communications, Inc. trademarks, including the mark "WHISTLE +.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as +.\" such appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, +.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. +.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY +.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS +.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. +.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES +.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING +.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY +.\" OF SUCH DAMAGE. +.\" +.\" Author: Archie Cobbs +.\" +.Dd January 9, 2025 +.Dt NG_KSOCKET 4 +.Os +.Sh NAME +.Nm ng_ksocket +.Nd kernel socket netgraph node type +.Sh SYNOPSIS +.In sys/types.h +.In netgraph/ng_ksocket.h +.Sh DESCRIPTION +A +.Nm ksocket +node is both a netgraph node and a +.Bx +socket. +The +.Nm +node type allows one to open a socket inside the kernel and have +it appear as a Netgraph node. +The +.Nm +node type is the reverse of the socket node type (see +.Xr ng_socket 4 ) : +whereas the socket node type enables the user-level manipulation (via +a socket) of what is normally a kernel-level entity (the associated +Netgraph node), the +.Nm +node type enables the kernel-level manipulation (via a Netgraph node) of +what is normally a user-level entity (the associated socket). +.Pp +A +.Nm +node allows at most one hook connection. +Connecting to the node is +equivalent to opening the associated socket. +The name given to the hook +determines what kind of socket the node will open (see below). +When the hook is disconnected and/or the node is shutdown, the +associated socket is closed. +.Sh HOOKS +This node type supports a single hook connection at a time. +The name of the hook must be of the form +.Em // , +where the +.Em family , +.Em type , +and +.Em proto +are the decimal equivalent of the same arguments to +.Xr socket 2 . +Alternately, aliases for the commonly used values are accepted as +well. +For example +.Dv inet/dgram/udp +is a more readable but equivalent version of +.Dv 2/2/17 . +.Pp +Data received into socket is sent out via hook. +Data received on hook is sent out from socket, if the latter is +connected (an +.Dv NGM_KSOCKET_CONNECT +was sent to node before). +If socket is not connected, destination +.Vt "struct sockaddr" +must be supplied in an mbuf tag with cookie +.Dv NGM_KSOCKET_COOKIE +and type +.Dv NG_KSOCKET_TAG_SOCKADDR +attached to data. +Otherwise +.Nm +will return +.Er ENOTCONN +to sender. +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_KSOCKET_BIND Pq Ic bind +This functions exactly like the +.Xr bind 2 +system call. +The +.Vt "struct sockaddr" +socket address parameter should be supplied as an argument. +.It Dv NGM_KSOCKET_LISTEN Pq Ic listen +This functions exactly like the +.Xr listen 2 +system call. +The backlog parameter (a single 32 bit +.Dv int ) +should be supplied as an argument. +.It Dv NGM_KSOCKET_CONNECT Pq Ic connect +This functions exactly like the +.Xr connect 2 +system call. +The +.Vt "struct sockaddr" +destination address parameter should be supplied as an argument. +.It Dv NGM_KSOCKET_ACCEPT Pq Ic accept +Equivalent to the +.Xr accept 2 +system call on a non-blocking socket. +If there is a pending connection on the queue, +a new socket and a corresponding cloned node are created. +Returned are the cloned node's ID and a peer name (as +.Vt "struct sockaddr" ) . +If there are no pending connections, +this control message returns nothing, +and a connected node will receive the above message asynchronously, +when a connection is established. +.Pp +A cloned node supports a single hook with an arbitrary name. +If not connected, a node disappears when its parent node is destroyed. +Once connected, it becomes an independent node. +.It Dv NGM_KSOCKET_GETNAME Pq Ic getname +Equivalent to the +.Xr getsockname 2 +system call. +The name is returned as a +.Vt "struct sockaddr" +in the arguments field of the reply. +.It Dv NGM_KSOCKET_GETPEERNAME Pq Ic getpeername +Equivalent to the +.Xr getpeername 2 +system call. +The name is returned as a +.Vt "struct sockaddr" +in the arguments field of the reply. +.It Dv NGM_KSOCKET_SETOPT Pq Ic setopt +Equivalent to the +.Xr setsockopt 2 +system call, except that the option name, level, and value are passed in a +.Vt "struct ng_ksocket_sockopt" . +.It Dv NGM_KSOCKET_GETOPT Pq Ic getopt +Equivalent to the +.Xr getsockopt 2 +system call, except that the option is passed in a +.Vt "struct ng_ksocket_sockopt" . +When sending this command, the +.Dv value +field should be empty; upon return, it will contain the +retrieved value. +.El +.Sh ASCII FORM CONTROL MESSAGES +For control messages that pass a +.Vt "struct sockaddr" +in the argument field, the normal +.Tn ASCII +equivalent of the C structure +is an acceptable form. +For the +.Dv PF_INET , +.Dv PF_INET6 +and +.Dv PF_LOCAL +address families, a more convenient form is also used, which is +the protocol family name, followed by a slash, followed by the actual +address. +For +.Dv PF_INET , +the address is an IPv4 address followed by an optional colon and port number. +For +.Dv PF_INET6 , +the address is an IPv6 address enclosed in square brackets followed +by an optional colon and port number. +For +.Dv PF_LOCAL , +the address is the pathname as a doubly quoted string. +.Pp +Examples: +.Bl -tag -width "PF_LOCAL" +.It Dv PF_LOCAL +local/"/tmp/foo.socket" +.It Dv PF_INET +inet/192.168.1.1:1234 +.It Dv PF_INET6 +inet6/[2001::1]:1234 +.It Other +.Dv "\&{ family=16 len=16 data=[0x70 0x00 0x01 0x23] \&}" +.El +.Pp +For control messages that pass a +.Vt "struct ng_ksocket_sockopt" , +the normal +.Tn ASCII +form for that structure is used. +In the future, more +convenient encoding of the more common socket options may be supported. +.Pp +Setting socket options example: +.Bl -tag -width "PF_LOCAL" +.It Set FIB 2 for a socket (SOL_SOCKET, SO_SETFIB): +.Dv "setopt \&{ level=0xffff name=0x1014 data=[ 2 ] \&}" +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when the hook is disconnected. +Shutdown of the node closes the associated socket. +.Sh SEE ALSO +.Xr socket 2 , +.Xr netgraph 4 , +.Xr ng_socket 4 , +.Xr ngctl 8 , +.Xr mbuf_tags 9 , +.Xr socket 9 +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 4.0 . +.Sh AUTHORS +.An Archie Cobbs Aq Mt archie@FreeBSD.org diff --git a/static/freebsd/man4/ng_l2cap.4 b/static/freebsd/man4/ng_l2cap.4 new file mode 100644 index 00000000..0fa3901a --- /dev/null +++ b/static/freebsd/man4/ng_l2cap.4 @@ -0,0 +1,421 @@ +.\" Copyright (c) 2001-2002 Maksim Yevmenkin +.\" 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. +.\" +.\" $Id: ng_l2cap.4,v 1.4 2003/09/14 23:37:52 max Exp $ +.\" +.Dd July 4, 2002 +.Dt NG_L2CAP 4 +.Os +.Sh NAME +.Nm ng_l2cap +.Nd Netgraph node type that implements Bluetooth Logical Link Control and +Adaptation Protocol (L2CAP) +.Sh SYNOPSIS +.In sys/types.h +.In netgraph/bluetooth/include/ng_hci.h +.In netgraph/bluetooth/include/ng_l2cap.h +.Sh DESCRIPTION +The +.Nm l2cap +node type is a Netgraph node type that implements Bluetooth Logical Link +Control and Adaptation Protocol as per chapter D of the Bluetooth Specification +Book v1.1. +.Pp +L2CAP provides connection-oriented and connectionless data services to upper +layer protocols with protocol multiplexing capability, segmentation and +reassembly operation, and group abstractions. +L2CAP permits higher level +protocols and applications to transmit and receive L2CAP data packets up to +64 kilobytes in length. +.Ss L2CAP Assumptions +.Bl -enum -offset indent +.It +The ACL link between two units is set up. +The Baseband provides orderly +delivery of data packets, although there might be individual packet corruption +and duplicates. +No more than one ACL link exists between any two devices. +.It +The Baseband always provides the impression of full-duplex communication +channels. +This does not imply that all L2CAP communications are bi-directional. +Multicasts and unidirectional traffic (e.g., video) do not require duplex +channels. +.It +L2CAP provides a reliable channel using the mechanisms available at the +Baseband layer. +The Baseband always performs data integrity checks when +requested and resends data until it has been successfully acknowledged or +a timeout occurs. +As acknowledgements may be lost, timeouts may +occur even after the data has been successfully sent. +.El +.Sh L2CAP GENERAL OPERATION +The Logical Link Control and Adaptation Protocol (L2CAP) is based around the +concept of +.Dq channels . +Each channel is bound to a single protocol in a many-to-one fashion. +Multiple +channels can be bound to the same protocol, but a channel cannot be bound to +multiple protocols. +Each L2CAP packet received on a channel is directed to +the appropriate higher level protocol. +.Pp +Each one of the end-points of an L2CAP channel is referred to by a channel +identifier. +Channel identifiers (CIDs) are local names representing a logical +channel end-point on the device. +Identifiers from 0x0001 to 0x003F are reserved +for specific L2CAP functions. +The null identifier (0x0000) is defined as an +illegal identifier and must never be used as a destination end-point. +All L2CAP signalling commands are sent to CID 0x0001. +CID 0x0002 is reserved for group-oriented channel. +The same CID must not be reused as a local L2CAP +channel endpoint for multiple simultaneous L2CAP channels between a local +device and some remote device. +.Pp +CID assignment is relative to a particular device and a device can assign CIDs +independently from other devices. +Thus, even if the same CID value has been +assigned to (remote) channel endpoints by several remote devices connected +to a single local device, the local device can still uniquely associate each +remote CID with a different device. +.Ss Channel Operational States +.Bl -tag -width foo +.It Dv NG_L2CAP_CLOSED +In this state, there is no channel associated with this CID. +This is the only +state when a link level connection (Baseband) may not exist. +Link disconnection +forces all other states into the +.Dv NG_L2CAP_CLOSED +state. +.It Dv NG_L2CAP_W4_L2CAP_CON_RSP +In this state, the CID represents a local end-point and an L2CAP Connect +Request message has been sent referencing this endpoint and it is now waiting +for the corresponding L2CAP Connect Response message. +.It Dv NG_L2CAP_W4_L2CA_CON_RSP +In this state, the remote end-point exists and an L2CAP Connect Request has +been received by the local L2CAP entity. +An L2CA Connect Indication has been +sent to the upper layer and the part of the local L2CAP entity processing the +received L2CAP Connect Request waits for the corresponding response. +The response may require a security check to be performed. +.It Dv NG_L2CAP_CONFIG +In this state, the connection has been established but both sides are still +negotiating the channel parameters. +The Configuration state may also be +entered when the channel parameters are being renegotiated. +Prior to entering the +.Dv NG_L2CAP_CONFIG +state, all outgoing data traffic is suspended since +the traffic parameters of the data traffic are to be renegotiated. +Incoming +data traffic is accepted until the remote channel endpoint has entered +the +.Dv NG_L2CAP_CONFIG +state. +In the +.Dv NG_L2CAP_CONFIG +state, both sides will issue +L2CAP Configuration Request messages if only defaults are being used, a null +message will be sent. +If a large amount of parameters need to be negotiated, +multiple messages will be sent to avoid any MTU limitations and negotiate +incrementally. +Moving from the +.Dv NG_L2CAP_CONFIG +state to the +.Dv NG_L2CAP_OPEN +state requires both sides to be ready. +An L2CAP entity is ready when it has received +a positive response to its final request and it has positively responded to +the final request from the remote device. +.It Dv NG_L2CAP_OPEN +In this state, the connection has been established and configured, and data +flow may proceed. +.It Dv NG_L2CAP_W4_L2CAP_DISCON_RSP +In this state, the connection is shutting down and an L2CAP Disconnect Request +message has been sent. +This state is now waiting for the corresponding response. +.It Dv NG_L2CAP_W4_L2CA_DISCON_RSP +In this state, the connection on the remote endpoint is shutting down and an +L2CAP Disconnect Request message has been received. +An L2CA Disconnect +Indication has been sent to the upper layer to notify the owner of the CID +that the remote endpoint is being closed. +This state is now waiting for the +corresponding response from the upper layer before responding to the remote +endpoint. +.El +.Ss Protocol Multiplexing +L2CAP supports protocol multiplexing because the Baseband Protocol does not +support any +.Dq type +field identifying the higher layer protocol being multiplexed above it. +L2CAP is able to distinguish between upper layer protocols such as the Service +Discovery Protocol, RFCOMM and Telephony Control. +.Ss Segmentation and Reassembly +The data packets defined by the Baseband Protocol are limited in size. +Large +L2CAP packets must be segmented into multiple smaller Baseband packets prior +to their transmission over the air. +Similarly, multiple received Baseband +packets may be reassembled into a single larger L2CAP packet. +.Ss Quality of Service +The L2CAP connection establishment process allows the exchange of information +regarding the quality of service (QoS) expected between two Bluetooth units. +.Ss Groups +The Baseband Protocol supports the concept of a piconet, a group of devices +synchronously hopping together using the same clock. +The L2CAP group +abstraction permits implementations to efficiently map protocol groups on to +piconets. +.Pp +The following features are outside the scope of L2CAP responsibilities: +.Bl -dash -offset indent +.It +L2CAP does not transport audio designated for SCO links. +.It +L2CAP does not enforce a reliable channel or ensure data integrity, +that is, L2CAP performs no retransmissions or checksum calculations. +.It +L2CAP does not support a reliable multicast channel. +.It +L2CAP does not support the concept of a global group name. +.El +.Sh HOOKS +This node type supports the following hooks: +.Bl -tag -width ".Va hci" +.It Va hci +Bluetooth Host Controller Interface downstream hook. +.It Va l2c +Upper layer protocol upstream hook. +Usually the Bluetooth L2CAP socket layer is connected to the hook. +.It Va ctl +Control hook. +Usually the Bluetooth raw L2CAP sockets layer is connected to the hook. +.El +.Sh INTERFACE TO THE UPPER LAYER PROTOCOLS (L2CA CONTROL MESSAGES) +Bluetooth specification says that L2CA request must block until response +is ready. +L2CAP node uses +.Va token +field from Netgraph message header to match L2CA request and response. +The upper layer protocol must populate +.Va token . +L2CAP node will queue request and start processing. +Later, when response is +ready or timeout has occurred, L2CAP node will create new Netgraph message, set +.Va token +and +.Dv NFG_RESP +flag and send message to the upper layer. +Note that L2CA indication messages +will not populate +.Va token +and will not set +.Dv NGF_RESP +flag. +There is no reason for this, because they are just notifications and do +not require acknowledgment. +.Bl -tag -width foo +.It Dv NGM_L2CAP_L2CA_CON +Requests the creation of a channel representing a logical connection to a +physical address. +Input parameters are the target protocol (PSM) and remote +device's 48-bit address (BD_ADDR). +Output parameters are the local CID (LCID) +allocated by the local L2CAP entity, and Result of the request. +If Result +indicates a pending notification, the Status value may contain more information +of what processing is delaying the establishment of the connection. +.It Dv NGM_L2CAP_L2CA_CON_IND +This message includes the parameters for the address of the remote device that +issued the connection request, the local CID representing the channel being +requested, the Identifier contained in the request, and the PSM value the +request is targeting. +.It Dv NGM_L2CAP_L2CA_CON_RSP +Issues a response to a connection request event indication. +Input parameters +are the remote device's 48-bit address, Identifier sent in the request, local +CID, the Response code, and the Status attached to the Response code. +The output parameter is the Result of the service request. +This primitive must be +called no more than once after receiving the indication. +.It Dv NGM_L2CAP_L2CA_CFG +Requests the initial configuration (or reconfiguration) of a channel to a new +set of channel parameters. +Input parameters are the local CID endpoint, new +incoming receivable MTU (InMTU), new outgoing flow spec-ification, and flush +and link timeouts. +Output parameters are the Result, accepted incoming MTU +(InMTU), the remote side's flow requests, and flush and link timeouts. +.It Dv NGM_L2CAP_L2CA_CFG_IND +This message includes the parameters indicating the local CID of the channel +the request has been sent to, the outgoing MTU size (maximum packet that can +be sent across the channel) and the flowspec describing the characteristics of +the incoming data. +All other channel parameters are set to their default values +if not provided by the remote device. +.It Dv NGM_L2CAP_L2CA_CFG_RSP +Issues a response to a configuration request event indication. +Input parameters +include the local CID of the endpoint being configured, outgoing transmit MTU +(which may be equal or less to the OutMTU parameter in the configuration +indication event) and the accepted flowspec for incoming traffic. +The output parameter is the Result value. +.It Dv NGM_L2CAP_L2CA_QOS_IND +This message includes the parameter indicating the address of the remote +Bluetooth device where the QoS contract has been violated. +.It Dv NGM_L2CAP_L2CA_DISCON +Requests the disconnection of the channel. +Input parameter is the CID representing the local channel endpoint. +Output parameter is Result. +Result +is zero if an L2CAP Disconnect Response is received, otherwise a non-zero value +is returned. +Once disconnection has been requested, no process will be able to +successfully read or write from the CID. +.It Dv NGM_L2CAP_L2CA_DISCON_IND +This message includes the parameter indicating the local CID the request has +been sent to. +.It Dv NGM_L2CAP_L2CA_WRITE +Response to transfer of data request. +Actual data must be received from +appropriate upstream hook and must be prepended with header defined as follows. +.Bd -literal -offset indent +/* L2CA data packet header */ +typedef struct { + uint32_t token; /* token to use in L2CAP_L2CA_WRITE */ + uint16_t length; /* length of the data */ + uint16_t lcid; /* local channel ID */ +} __attribute__ ((packed)) ng_l2cap_l2ca_hdr_t; +.Ed +.Pp +The output parameters are Result and Length of data written. +.It Dv NGM_L2CAP_L2CA_GRP_CREATE +Requests the creation of a CID to represent a logical connection to multiple +devices. +Input parameter is the PSM value that the outgoing connectionless +traffic is labelled with, and the filter used for incoming traffic. +Output parameter is the CID representing the local endpoint. +On creation, the group +is empty but incoming traffic destined for the PSM value is readable. +.Bf -emphasis +This request has not been implemented. +.Ef +.It Dv NGM_L2CAP_L2CA_GRP_CLOSE +The use of this message closes down a Group. +.Bf -emphasis +This request has not been implemented. +.Ef +.It Dv NGM_L2CAP_L2CA_GRP_ADD_MEMBER +Requests the addition of a member to a group. +The input parameter includes the +CID representing the group and the BD_ADDR of the group member to be added. +The output parameter Result confirms the success or failure of the request. +.Bf -emphasis +This request has not been implemented. +.Ef +.It Dv NGM_L2CAP_L2CA_GRP_REM_MEMBER +Requests the removal of a member from a group. +The input parameters include +the CID representing the group and BD_ADDR of the group member to be removed. +The output parameter Result confirms the success or failure of the request. +.Bf -emphasis +This request has not been implemented. +.Ef +.It Dv NGM_L2CAP_L2CA_GRP_MEMBERSHIP +Requests a report of the members of a group. +The input parameter CID represents the group being queried. +The output parameter Result confirms the success or +failure of the operation. +If the Result is successful, BD_ADDR_Lst is a list +of the Bluetooth addresses of the N members of the group. +.Bf -emphasis +This request has not been implemented. +.Ef +.It Dv NGM_L2CAP_L2CA_PING +Initiates an L2CA Echo Request message and the reception of the corresponding +L2CAP Echo Response message. +The input parameters are remote Bluetooth device +BD_ADDR, Echo Data and Length of the echo data. +The output parameters are +Result, Echo Data and Length of the echo data. +.It Dv NGM_L2CAP_L2CA_GET_INFO +Initiates an L2CA Information Request message and the reception of the +corresponding L2CAP Info Response message. +The input parameters are remote Bluetooth device BD_ADDR and Information Type. +The output parameters are +Result, Information Data and Size of the information data. +.It Dv NGM_L2CAP_L2CA_ENABLE_CLT +Request to disable (enable) the reception of connectionless packets. +The input +parameter is the PSM value indicating service that should be blocked +(unblocked) and Enable flag. +.El +.Sh NETGRAPH CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_L2CAP_NODE_GET_FLAGS +Returns current state for the node. +.It Dv NGM_L2CAP_NODE_GET_DEBUG +Returns an integer containing the current debug level for the node. +.It Dv NGM_L2CAP_NODE_SET_DEBUG +This command takes an integer argument and sets current debug level +for the node. +.It Dv NGM_L2CAP_NODE_GET_CON_LIST +Returns list of active baseband connections (i.e., ACL links). +.It Dv NGM_L2CAP_NODE_GET_CHAN_LIST +Returns list of active L2CAP channels. +.It Dv NGM_L2CAP_NODE_GET_AUTO_DISCON_TIMO +Returns an integer containing the current value of the auto disconnect +timeout (in sec). +.It Dv NGM_L2CAP_NODE_SET_AUTO_DISCON_TIMO +This command accepts an integer and sets the value of the auto disconnect +timeout (in sec). +The special value of 0 (zero) disables auto disconnect timeout. +.El +.Sh SHUTDOWN +This node shuts down upon receipt of an +.Dv NGM_SHUTDOWN +control message, or +when all hooks have been disconnected. +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr l2control 8 , +.Xr l2ping 8 , +.Xr ngctl 8 +.Sh HISTORY +The +.Nm l2cap +node type was implemented in +.Fx 5.0 . +.Sh AUTHORS +.An Maksim Yevmenkin Aq Mt m_evmenkin@yahoo.com +.Sh BUGS +Most likely. +Please report if found. diff --git a/static/freebsd/man4/ng_l2tp.4 b/static/freebsd/man4/ng_l2tp.4 new file mode 100644 index 00000000..becde35e --- /dev/null +++ b/static/freebsd/man4/ng_l2tp.4 @@ -0,0 +1,327 @@ +.\" Copyright (c) 2001-2002 Packet Design, LLC. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, +.\" use and redistribution of this software, in source or object code +.\" forms, with or without modifications are expressly permitted by +.\" Packet Design; provided, however, that: +.\" +.\" (i) Any and all reproductions of the source or object code +.\" must include the copyright notice above and the following +.\" disclaimer of warranties; and +.\" (ii) No rights are granted, in any manner or form, to use +.\" Packet Design trademarks, including the mark "PACKET DESIGN" +.\" on advertising, endorsements, or otherwise except as such +.\" appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING +.\" THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED +.\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, +.\" OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE, +.\" OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS +.\" OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, +.\" RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE +.\" LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE +.\" OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT, +.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL +.\" DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF +.\" USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 PACKET DESIGN IS ADVISED OF +.\" THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Author: Archie Cobbs +.\" +.Dd November 13, 2012 +.Dt NG_L2TP 4 +.Os +.Sh NAME +.Nm ng_l2tp +.Nd L2TP protocol netgraph node type +.Sh SYNOPSIS +.In sys/types.h +.In netgraph/ng_l2tp.h +.Sh DESCRIPTION +The +.Nm l2tp +node type implements the encapsulation layer of the L2TP protocol +as described in RFC 2661. +This includes adding the L2TP packet header for outgoing packets +and verifying and removing it for incoming packets. +The node maintains the L2TP sequence number state and handles +control session packet acknowledgment and retransmission. +.Sh HOOKS +The +.Nm l2tp +node type supports the following hooks: +.Bl -tag -width ".Va session_hhhh" +.It Va lower +L2TP frames. +.It Va ctrl +Control packets. +.It Va session_hhhh +Session 0xhhhh data packets. +.El +.Pp +L2TP control and data packets are transmitted to, and received from, +the L2TP peer via the +.Dv lower +hook. +Typically this hook would be connected to the +.Dv "inet/dgram/udp" +hook of an +.Xr ng_ksocket 4 +node for L2TP over UDP. +.Pp +The +.Dv ctrl +hook connects to the local L2TP management entity. +L2TP control messages (without any L2TP headers) are transmitted +and received on this hook. +Messages written to this hook are guaranteed to be delivered to the +peer reliably, in order, and without duplicates. +.Pp +Packets written to the +.Dv ctrl +hook must contain a two byte session ID prepended to the frame +(in network order). +This session ID is copied to the outgoing L2TP header. +Similarly, packets read from the +.Dv ctrl +hook will have the received session ID prepended. +.Pp +Once an L2TP session has been created, the corresponding session +hook may be used to transmit and receive the session's data frames: +for the session with session ID +.Dv 0xabcd , +the hook is named +.Dv session_abcd . +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_L2TP_SET_CONFIG Pq Ic setconfig +This command updates the configuration of the node. +It takes a +.Vt "struct ng_l2tp_config" +as an argument: +.Bd -literal +/* Configuration for a node */ +struct ng_l2tp_config { + u_char enabled; /* enables traffic flow */ + u_char match_id; /* tunnel id must match 'tunnel_id' */ + uint16_t tunnel_id; /* local tunnel id */ + uint16_t peer_id; /* peer's tunnel id */ + uint16_t peer_win; /* peer's max recv window size */ + uint16_t rexmit_max; /* max retransmits before failure */ + uint16_t rexmit_max_to; /* max delay between retransmits */ +}; +.Ed +.Pp +The +.Va enabled +field enables packet processing. +Each time this field is changed back to zero the sequence +number state is reset. +In this way, reuse of a node is possible. +.Pp +The +.Va tunnel_id +field configures the local tunnel ID for the control connection. +The +.Va match_id +field determines how incoming L2TP packets with a tunnel ID +field different from +.Va tunnel_id +are handled. +If +.Va match_id +is non-zero, they will be dropped; otherwise, they will be dropped +only if the tunnel ID is non-zero. +Typically +.Va tunnel_id +is set to the local tunnel ID as soon as it is known and +.Va match_id +is set to non-zero after receipt of the SCCRP or SCCCN control message. +.Pp +The peer's tunnel ID should be set in +.Va peer_id +as soon as it is learned, typically after receipt of a SCCRQ or SCCRP +control message. +This value is copied into the L2TP header for outgoing packets. +.Pp +The +.Va peer_win +field should be set from the +.Dq "Receive Window Size" +AVP received from the peer. +The default value for this field is one; zero is an invalid value. +As long as +.Va enabled +is non-zero, this value may not be decreased. +.Pp +The +.Va rexmit_max +and +.Va rexmit_max_to +fields configure packet retransmission. +.Va rexmit_max_to +is the maximum retransmission delay between packets, in seconds. +The retransmit delay will start at a small value and increase +exponentially up to this limit. +The +.Va rexmit_max +sets the maximum number of times a packet will be retransmitted +without being acknowledged before a failure condition is declared. +Once a failure condition is declared, each additional retransmission +will cause the +.Nm l2tp +node to send a +.Dv NGM_L2TP_ACK_FAILURE Pq Ic ackfailure +control message back to the node that sent the last +.Dv NGM_L2TP_SET_CONFIG . +Appropriate action should then be taken to shutdown the control connection. +.It Dv NGM_L2TP_GET_CONFIG Pq Ic getconfig +Returns the current configuration as a +.Vt "struct ng_l2tp_config" . +.It Dv NGM_L2TP_SET_SESS_CONFIG Pq Ic setsessconfig +This control message configures a single data session. +The corresponding hook must already be connected before sending this command. +The argument is a +.Vt "struct ng_l2tp_sess_config" : +.Bd -literal +/* Configuration for a session hook */ +struct ng_l2tp_sess_config { + uint16_t session_id; /* local session id */ + uint16_t peer_id; /* peer's session id */ + u_char control_dseq; /* whether we control data sequencing */ + u_char enable_dseq; /* whether to enable data sequencing */ + u_char include_length; /* whether to include length field */ +}; +.Ed +.Pp +The +.Va session_id +and +.Va peer_id +fields configure the local and remote session IDs, respectively. +.Pp +The +.Va control_dseq +and +.Va enable_dseq +fields determine whether sequence numbers are used with L2TP data packets. +If +.Va enable_dseq +is zero, then no sequence numbers are sent and incoming sequence numbers +are ignored. +Otherwise, sequence numbers are included on outgoing packets and checked +on incoming packets. +.Pp +If +.Va control_dseq +is non-zero, then the setting of +.Va enable_dseq +will never change except by another +.Dv NGM_L2TP_SET_SESS_CONFIG +control message. +If +.Va control_dseq +is zero, then the peer controls whether sequence numbers are used: +if an incoming L2TP data packet contains sequence numbers, +.Va enable_dseq +is set to one, and conversely if an incoming L2TP data packet does not +contain sequence numbers, +.Va enable_dseq +is set to zero. +The current value of +.Va enable_dseq +is always accessible via the +.Dv NGM_L2TP_GET_SESS_CONFIG +control message (see below). +Typically an LNS would set +.Va control_dseq +to one while a LAC would set +.Va control_dseq +to zero (if the Sequencing Required AVP were not sent), thus giving +control of data packet sequencing to the LNS. +.Pp +The +.Va include_length +field determines whether the L2TP header length field is included +in outgoing L2TP data packets. +For incoming packets, the L2TP length field is always checked when present. +.It Dv NGM_L2TP_GET_SESS_CONFIG Pq Ic getsessconfig +This command takes a two byte session ID as an argument and returns +the current configuration for the corresponding data session as a +.Vt "struct ng_l2tp_sess_config" . +The corresponding session hook must be connected. +.It Dv NGM_L2TP_GET_STATS Pq Ic getstats +This command returns a +.Vt "struct ng_l2tp_stats" +containing statistics of the L2TP tunnel. +.It Dv NGM_L2TP_CLR_STATS Pq Ic clrstats +This command clears the statistics for the L2TP tunnel. +.It Dv NGM_L2TP_GETCLR_STATS Pq Ic getclrstats +Same as +.Dv NGM_L2TP_GET_STATS , +but also atomically clears the statistics as well. +.It Dv NGM_L2TP_GET_SESSION_STATS Pq Ic getsessstats +This command takes a two byte session ID as an argument and returns a +.Vt "struct ng_l2tp_session_stats" +containing statistics for the corresponding data session. +The corresponding session hook must be connected. +.It Dv NGM_L2TP_CLR_SESSION_STATS Pq Ic clrsessstats +This command takes a two byte session ID as an argument and +clears the statistics for that data session. +The corresponding session hook must be connected. +.It Dv NGM_L2TP_GETCLR_SESSION_STATS Pq Ic getclrsessstats +Same as +.Dv NGM_L2TP_GET_SESSION_STATS , +but also atomically clears the statistics as well. +.It Dv NGM_L2TP_SET_SEQ Pq Ic setsequence +This command sets the sequence numbers of a not yet enabled node. +It takes a +.Vt "struct ng_l2tp_seq_config" +as argument, where +.Va xack +and +.Va nr +respectively +.Va ns +and +.Va rack +must be the same. +This option is particularly useful if one receives and processes +the first packet entirely in userspace and wants to hand over further +processing to the node. +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ng_ksocket 4 , +.Xr ng_ppp 4 , +.Xr ng_pptpgre 4 , +.Xr ngctl 8 +.Rs +.%A W. Townsley +.%A A. Valencia +.%A A. Rubens +.%A G. Pall +.%A G. Zorn +.%A B. Palter +.%T "Layer Two Tunneling Protocol L2TP" +.%O RFC 2661 +.Re +.Sh HISTORY +The +.Nm l2tp +node type was developed at Packet Design, LLC, +.Pa http://www.packetdesign.com/ . +.Sh AUTHORS +.An Archie Cobbs Aq Mt archie@packetdesign.com diff --git a/static/freebsd/man4/ng_lmi.4 b/static/freebsd/man4/ng_lmi.4 new file mode 100644 index 00000000..691f00ad --- /dev/null +++ b/static/freebsd/man4/ng_lmi.4 @@ -0,0 +1,136 @@ +.\" Copyright (c) 1996-1999 Whistle Communications, Inc. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, use and +.\" redistribution of this software, in source or object code forms, with or +.\" without modifications are expressly permitted by Whistle Communications; +.\" provided, however, that: +.\" 1. Any and all reproductions of the source or object code must include the +.\" copyright notice above and the following disclaimer of warranties; and +.\" 2. No rights are granted, in any manner or form, to use Whistle +.\" Communications, Inc. trademarks, including the mark "WHISTLE +.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as +.\" such appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, +.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. +.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY +.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS +.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. +.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES +.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING +.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY +.\" OF SUCH DAMAGE. +.\" +.\" Author: Archie Cobbs +.\" $Whistle: ng_lmi.8,v 1.4 1999/01/25 23:46:27 archie Exp $ +.\" +.Dd November 13, 2012 +.Dt NG_LMI 4 +.Os +.Sh NAME +.Nm ng_lmi +.Nd frame relay LMI protocol netgraph node type +.Sh SYNOPSIS +.In sys/types.h +.In netgraph/ng_lmi.h +.Sh DESCRIPTION +The +.Nm lmi +node type performs the frame relay LMI protocol. +It supports +the ITU Annex A, ANSI Annex D, and Group-of-four LMI types. +It also supports auto-detection of the LMI type. +.Pp +To enable a specific LMI type, connect the corresponding hook +.Dv ( annexA , +.Dv annexD , +or +.Dv group4 ")" +to DLCI 0 or 1023 of a +.Xr ng_frame_relay 4 +node. +Typically, Annex A and Annex D live on DLCI 0 while Group-of-four +lives on DLCI 1023. +.Pp +To enable LMI type auto-detection, connect the +.Dv auto0 +hook to DLCI 0 and the +.Dv auto1023 +hook to DLCI 1023. +The node will attempt to automatically determine +which LMI type is running at the switch, and go into that mode. +.Pp +Only one fixed LMI type, or auto-detection, can be active at any given time. +.Pp +The +.Dv NGM_LMI_GET_STATUS +control message can be used at any time to query the current status +of the LMI protocol and each DLCI channel. +This node also supports the +.Dv NGM_TEXT_STATUS +control message. +.Sh HOOKS +This node type supports the following hooks: +.Bl -tag -width ".Va auto1023" +.It Va annexA +ITU Annex A LMI hook. +.It Va annexD +ANSI Annex D LMI hook. +.It Va group4 +Group-of-four LMI hook. +.It Va auto0 +Auto-detection hook for DLCI 0. +.It Va auto1023 +Auto-detection hook for DLCI 1023. +.El +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_LMI_GET_STATUS +This command returns status information in a +.Dv "struct nglmistat" : +.Bd -literal -offset 4n +#define NGM_LMI_STAT_ARYSIZE (1024/8) + +struct nglmistat { + u_char proto[12]; /* Active proto (same as hook name) */ + u_char hook[12]; /* Active hook */ + u_char fixed; /* If set to fixed LMI mode */ + u_char autod; /* If currently auto-detecting */ + u_char seen[NGM_LMI_STAT_ARYSIZE]; /* DLCIs ever seen */ + u_char up[NGM_LMI_STAT_ARYSIZE]; /* DLCIs currently up */ +}; +.Ed +.It Dv NGM_TEXT_STATUS +This generic message returns is a human-readable version of the node status. +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ng_frame_relay 4 , +.Xr ngctl 8 +.Rs +.%T "ANSI T1.617-1991 Annex D" +.Re +.Rs +.%T "ITU-T Q.933 Digital Subscriber Signaling System No. 1 - Signaling Specification for Frame Mode Basic Call Control, Annex A" +.Re +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 4.0 . +.Sh AUTHORS +.An Julian Elischer Aq Mt julian@FreeBSD.org diff --git a/static/freebsd/man4/ng_macfilter.4 b/static/freebsd/man4/ng_macfilter.4 new file mode 100644 index 00000000..904f194f --- /dev/null +++ b/static/freebsd/man4/ng_macfilter.4 @@ -0,0 +1,220 @@ +.\" Copyright (c) 2012-2017 Pekka Nikander +.\" Copyright (c) 2018 Retina b.v. +.\" 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" 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 December 10, 2018 +.Dt NG_MACFILTER 4 +.Os +.Sh NAME +.Nm ng_macfilter +.Nd packet filtering netgraph node using ethernet MAC addresses +.Sh SYNOPSIS +.In sys/types.h +.In netgraph/ng_macfilter.h +.Sh DESCRIPTION +The +.Nm macfilter +allows routing ethernet packets over different hooks based on the sender MAC +address. +.Pp +This processing is done when traffic flows from the +.Dq ether +hook through +.Nm macfilter +to one of the outgoing hooks. +Outbound hooks can be added to and remove from +.Nm macfilter +and arbitrarily named. +By default one hook called +.Dq default +is present and used for all packets which have no MAC address in the MAC table. +By adding MAC addresses to the MAC table traffic coming from this host can be +directed out other hooks. +.Nm macfilter +keeps track of packets and bytes from and to this MAC address in the MAC table. +.Pp +Packets are not altered in any way. +If hooks are not connected, packets are +dropped. +.Sh HOOKS +This node type by default has an +.Dv ether +hook, to be connected to the +.Dv lower +hook of the NIC, and a +.Dv default +hook where packets are sent if the MAC address is not found in the table. +.Nm macfilter +supports up to +.Dv NG_MACFILTER_UPPER_NUM +hooks to be connected to the NIC's upper hook. +Other nodes can be inserted to provide additional processing. +All outbound can be combined back into one by using +.Dv ng_one2many . +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the +following: +.Bl -tag -width foo +.It Dv NGM_MACFILTER_RESET Pq Ic reset +Resets the MAC table in the node. +.It Dv NGM_MACFILTER_DIRECT Pq Ic direct +Takes the following argument struct: +.Bd -literal -offset indent +struct ngm_macfilter_direct { + u_char ether[ETHER_ADDR_LEN]; /* MAC address */ + u_char hookname[NG_HOOKSIZ]; /* Upper hook name*/ +}; +.Ed +The given ethernet MAC address will be forwarded out the named hook. +.It Dv NGM_MACFILTER_DIRECT_HOOKID Pq Ic directi +Takes the following argument struct: +.Bd -literal -offset indent +struct ngm_macfilter_direct_hookid { + u_char ether[ETHER_ADDR_LEN]; /* MAC address */ + u_int16_t hookid; /* Upper hook hookid */ +}; +.Ed +The given ethernet MAC address will be forwarded out the hook at id +.Dv hookid . +.It Dv NGM_MACFILTER_GET_MACS Pq Ic getmacs +Returns the list of MAC addresses in the node in the following structure: +.Bd -literal -offset indent +struct ngm_macfilter_mac { + u_char ether[ETHER_ADDR_LEN]; /* MAC address */ + u_int16_t hookid; /* Upper hook hookid */ + u_int64_t packets_in; /* packets in from downstream */ + u_int64_t bytes_in; /* bytes in from upstream */ + u_int64_t packets_out; /* packets out towards downstream */ + u_int64_t bytes_out; /* bytes out towards downstream */ +}; +struct ngm_macfilter_macs { + u_int32_t n; /* Number of entries in macs */ + struct ngm_macfilter_mac macs[]; /* Macs table */ +}; +.Ed +.It Dv NGM_MACFILTER_GETCLR_MACS Pq Ic getclrmacs +Same as above, but will also atomically clear the +.Dv packets_in , +.Dv bytes_in , +.Dv packets_out , and +.Dv bytes_out +fields in the table. +.It Dv NGM_MACFILTER_CLR_STATS Pq Ic clrmacs +Will clear the per MAC address packet and byte counters. +.It Dv NGM_MACFILTER_GET_HOOKS Pq Ic gethooks +Will return a list of hooks and their hookids in an array of the following struct's: +.Bd -literal -offset indent +struct ngm_macfilter_hook { + u_char hookname[NG_HOOKSIZ]; /* Upper hook name*/ + u_int16_t hookid; /* Upper hook hookid */ + u_int32_t maccnt; /* Number of mac addresses associated with hook */ +}; +.Ed +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message or when all have been disconnected. +.Sh EXAMPLES +The following netgraph configuration will apply +.Xr ipfw 8 +tag 42 to each packet that is routed over the +.Dq accepted +hook. +The graph looks like the following: +.Bd -literal -offset indent + /-------[combiner]---------\\ + | + / \\ +[em0] | [tagger] + \\ / + | + \\-----[macfilter]------/ +.Ed +.Pp +Commands: +.Bd -literal -offset indent + ngctl mkpeer em0: macfilter lower ether + ngctl name em0:lower macfilter + + # Funnel both streams back into ether:upper + ngctl mkpeer em0: one2many upper one + ngctl name em0:upper recombiner + # Connect macfilter:default to recombiner:many0 + ngctl connect macfilter: recombiner: default many0 + # Connect macfilter:accepted to tagger:in + ngctl mkpeer macfilter: tag accepted in + ngctl name macfilter:accepted tagger + # Connect tagger:out to recombiner:many1 + ngctl connect tagger: recombiner: out many1 + + # Mark tag all traffic through tagger in -> out with an ipfw tag 42 + ngctl msg tagger: sethookin '{ thisHook="in" ifNotMatch="out" }' + ngctl msg tagger: sethookout '{ thisHook="out" tag_cookie=1148380143 tag_id=42 }' + + # Pass traffic from ether:upper / combiner:one via combiner:many0 on to + # macfilter:default and on to ether:lower. + ngctl msg recombiner: setconfig '{ xmitAlg=3 failAlg=1 enabledLinks=[ 1 1 ] }' +.Ed +.Pp +.Em Note : +The tag_cookie 1148380143 was retrieved from +.Dv MTAG_IPFW +in +.Pa /usr/include/netinet/ip_var.h . +.Pp +The following command can be used to add a MAC address to be output via +.Dv macfilter:accepted : +.Bd -literal -offset indent + ngctl msg macfilter: direct '{ hookname="known" ether=08:00:27:92:eb:aa }' +.Ed +.Pp +The following command can be used to retrieve the packet and byte counters : +.Bd -literal -offset indent + ngctl msg macfilter: getmacs +.Ed +.Pp +It will return the contents of the MAC table: +.Bd -literal -offset indent + Rec'd response "getmacs" (4) from "[54]:": + Args: { n=1 macs=[ { ether=08:00:27:92:eb:aa hookid=1 packets_in=3571 bytes_in=592631 packets_out=3437 bytes_out=777142 } ] } +.Ed +.Sh SEE ALSO +.Xr divert 4 , +.Xr ipfw 4 , +.Xr netgraph 4 , +.Xr ng_ether 4 , +.Xr ng_one2many 4 , +.Xr ng_tag 4 , +.Xr ngctl 8 +.Sh AUTHORS +.An -nosplit +The original version of this code was written by Pekka Nikander, and +subsequently modified heavily by +.An Nick Hibma Aq Mt n_hibma@FreeBSD.org . +.Sh BUGS +None known. diff --git a/static/freebsd/man4/ng_mppc.4 b/static/freebsd/man4/ng_mppc.4 new file mode 100644 index 00000000..fa000d87 --- /dev/null +++ b/static/freebsd/man4/ng_mppc.4 @@ -0,0 +1,185 @@ +.\" Copyright (c) 1996-2000 Whistle Communications, Inc. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, use and +.\" redistribution of this software, in source or object code forms, with or +.\" without modifications are expressly permitted by Whistle Communications; +.\" provided, however, that: +.\" 1. Any and all reproductions of the source or object code must include the +.\" copyright notice above and the following disclaimer of warranties; and +.\" 2. No rights are granted, in any manner or form, to use Whistle +.\" Communications, Inc. trademarks, including the mark "WHISTLE +.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as +.\" such appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, +.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. +.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY +.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS +.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. +.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES +.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING +.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY +.\" OF SUCH DAMAGE. +.\" +.\" Author: Archie Cobbs +.\" +.\" $Whistle: ng_mppc.8,v 1.1 1999/12/08 20:20:39 archie Exp $ +.\" +.Dd June 7, 2016 +.Dt NG_MPPC 4 +.Os +.Sh NAME +.Nm ng_mppc +.Nd Microsoft MPPC/MPPE compression and encryption netgraph node type +.Sh SYNOPSIS +.In sys/types.h +.In netgraph/ng_mppc.h +.Sh DESCRIPTION +The +.Nm mppc +node type implements the Microsoft Point-to-Point Compression (MPPC) +and Microsoft Point-to-Point Encryption (MPPE) sub-protocols of +the PPP protocol. +These protocols are often used in conjunction with the Point-to-Point +Tunneling Protocol (PPTP). +.Pp +The node has two hooks, +.Dv "comp" +for compression and +.Dv "decomp" +for decompression. +Typically one or both of these hooks would be connected to the +.Xr ng_ppp 4 +node type hook of the same name. +Each direction of traffic flow is independent of the other. +.Sh HOOKS +This node type supports the following hooks: +.Bl -tag -width ".Va decomp" +.It Va comp +Connection to +.Xr ng_ppp 4 +.Dv "comp" +hook. +Incoming frames are compressed and/or encrypted, and sent +back out the same hook. +.It Va decomp +Connection to +.Xr ng_ppp 4 +.Dv "decomp" +hook. +Incoming frames are decompressed and/or decrypted, and sent +back out the same hook. +.El +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_MPPC_CONFIG_COMP +This command resets and configures the node for a session in the +outgoing traffic direction (i.e., for compression and/or encryption). +This command takes a +.Dv "struct ng_mppc_config" +as an argument: +.Bd -literal -offset 0n +/* Length of MPPE key */ +#define MPPE_KEY_LEN 16 + +/* MPPC/MPPE PPP negotiation bits */ +#define MPPC_BIT 0x00000001 /* mppc compression bits */ +#define MPPE_40 0x00000020 /* use 40 bit key */ +#define MPPE_56 0x00000080 /* use 56 bit key */ +#define MPPE_128 0x00000040 /* use 128 bit key */ +#define MPPE_BITS 0x000000e0 /* mppe encryption bits */ +#define MPPE_STATELESS 0x01000000 /* use stateless mode */ +#define MPPC_VALID_BITS 0x010000e1 /* possibly valid bits */ + +/* Configuration for a session */ +struct ng_mppc_config { + u_char enable; /* enable */ + uint32_t bits; /* config bits */ + u_char startkey[MPPE_KEY_LEN]; /* start key */ +}; + +.Ed +The +.Dv enabled +field enables traffic flow through the node. +The +.Dv bits +field contains the bits as negotiated by the Compression Control Protocol +(CCP) in PPP. +The +.Dv startkey +is only necessary if MPPE was negotiated, and must be equal to the +session start key as defined for MPPE. +This key is based on the MS-CHAP credentials used at link authentication time. +.It Dv NGM_MPPC_CONFIG_DECOMP +This command resets and configures the node for a session in the +incoming traffic direction (i.e., for decompression and/or decryption). +This command takes a +.Dv "struct ng_mppc_config" +as an argument. +.It Dv NGM_MPPC_RESETREQ +This message contains no arguments, and is bi-directional. +If an error is detected during decompression, this message is sent by the +node to the originator of the +.Dv NGM_MPPC_CONFIG_DECOMP +message that initiated the session. +The receiver should respond by sending a PPP CCP Reset-Request to the peer. +.Pp +This message may also be received by this node type when a CCP Reset-Request +is received by the local PPP entity. +The node will respond by flushing its outgoing compression and encryption +state so the remote side can resynchronize. +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when both hooks have been disconnected. +.Sh COMPILATION +The kernel options +.Dv NETGRAPH_MPPC_COMPRESSION +and +.Dv NETGRAPH_MPPC_ENCRYPTION +are supplied to selectively compile in either or both capabilities. +At least one of these must be defined, or else this node type is useless. +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ng_ppp 4 , +.Xr ngctl 8 +.Rs +.%A G. Pall +.%T "Microsoft Point-To-Point Compression (MPPC) Protocol" +.%O RFC 2118 +.Re +.Rs +.%A G. S. Pall +.%A G. Zorn +.%T "Microsoft Point-To-Point Encryption (MPPE) Protocol" +.%O draft-ietf-pppext-mppe-04.txt +.Re +.Rs +.%A K. Hamzeh +.%A G. Pall +.%A W. Verthein +.%A J. Taarud +.%A W. Little +.%A G. Zorn +.%T "Point-to-Point Tunneling Protocol (PPTP)" +.%O RFC 2637 +.Re +.Sh AUTHORS +.An Archie Cobbs Aq Mt archie@FreeBSD.org +.Sh BUGS +In PPP, encryption should be handled by the Encryption Control Protocol (ECP) +rather than CCP. +However, Microsoft combined both compression and encryption into their +``compression'' algorithm, which is confusing. diff --git a/static/freebsd/man4/ng_nat.4 b/static/freebsd/man4/ng_nat.4 new file mode 100644 index 00000000..20042db7 --- /dev/null +++ b/static/freebsd/man4/ng_nat.4 @@ -0,0 +1,408 @@ +.\" Copyright (c) 2005 Gleb Smirnoff +.\" 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 December 6, 2024 +.Dt NG_NAT 4 +.Os +.Sh NAME +.Nm ng_nat +.Nd "NAT netgraph node type" +.Sh SYNOPSIS +.In netgraph/ng_nat.h +.Sh DESCRIPTION +An +.Nm +node performs network address translation (NAT) of IPv4 packets +passing through it. +A +.Nm nat +node uses +.Xr libalias 3 +engine for packet aliasing. +.Sh HOOKS +This node type has two hooks: +.Bl -tag -width ".Va out" +.It Va out +Packets received on this hook are considered outgoing and will be +masqueraded to a configured address. +.It Va in +Packets coming on this hook are considered incoming and will be +dealiased. +.El +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_NAT_SET_IPADDR Pq Ic setaliasaddr +Configure aliasing address for a node. +After both hooks have been connected and aliasing address was configured, +a node is ready for aliasing operation. +.It Dv NGM_NAT_SET_MODE Pq Ic setmode +Set node's operation mode using supplied +.Vt "struct ng_nat_mode" . +.Bd -literal +struct ng_nat_mode { + uint32_t flags; + uint32_t mask; +}; +/* Supported flags: */ +#define NG_NAT_LOG 0x01 +#define NG_NAT_DENY_INCOMING 0x02 +#define NG_NAT_SAME_PORTS 0x04 +#define NG_NAT_UNREGISTERED_ONLY 0x10 +#define NG_NAT_RESET_ON_ADDR_CHANGE 0x20 +#define NG_NAT_PROXY_ONLY 0x40 +#define NG_NAT_REVERSE 0x80 +#define NG_NAT_UNREGISTERED_CGN 0x100 +#define NG_NAT_UDP_EIM 0x200 +.Ed +.Pp +The corresponding libalias flags can be found by replacing the +.Vt "NG_NAT" +prefix with +.Vt "PKT_ALIAS" . +.It Dv NGM_NAT_SET_TARGET Pq Ic settarget +Configure target address for a node. +When an incoming packet not associated with any pre-existing aliasing +link arrives at the host machine, it will be sent to the specified address. +.It Dv NGM_NAT_REDIRECT_PORT Pq Ic redirectport +Redirect incoming connections arriving to given port(s) to +another host and port(s). +The following +.Vt "struct ng_nat_redirect_port" +must be supplied as argument. +.Bd -literal +#define NG_NAT_DESC_LENGTH 64 +struct ng_nat_redirect_port { + struct in_addr local_addr; + struct in_addr alias_addr; + struct in_addr remote_addr; + uint16_t local_port; + uint16_t alias_port; + uint16_t remote_port; + uint8_t proto; + char description[NG_NAT_DESC_LENGTH]; +}; +.Ed +.Pp +Redirection is assigned an unique ID which is returned as +response to this message, and +information about redirection added to +list of static redirects which later can be retrieved by +.Dv NGM_NAT_LIST_REDIRECTS +message. +.It Dv NGM_NAT_REDIRECT_ADDR Pq Ic redirectaddr +Redirect traffic for public IP address to a machine on the +local network. +This function is known as +.Em static NAT . +The following +.Vt "struct ng_nat_redirect_addr" +must be supplied as argument. +.Bd -literal +struct ng_nat_redirect_addr { + struct in_addr local_addr; + struct in_addr alias_addr; + char description[NG_NAT_DESC_LENGTH]; +}; +.Ed +.Pp +Unique ID for this redirection is returned as response to this message. +.It Dv NGM_NAT_REDIRECT_PROTO Pq Ic redirectproto +Redirect incoming IP packets of protocol +.Va proto +(see +.Xr protocols 5 ) +to a machine on the local network. +The following +.Vt "struct ng_nat_redirect_proto" +must be supplied as argument. +.Bd -literal +struct ng_nat_redirect_proto { + struct in_addr local_addr; + struct in_addr alias_addr; + struct in_addr remote_addr; + uint8_t proto; + char description[NG_NAT_DESC_LENGTH]; +}; +.Ed +.Pp +Unique ID for this redirection is returned as response to this message. +.It Dv NGM_NAT_REDIRECT_DYNAMIC Pq Ic redirectdynamic +Mark redirection with specified ID as dynamic, i.e., it will serve +for exactly one next connection and then will be automatically +deleted from internal links table. +Only fully specified links can be made dynamic. +The redirection with this ID is also immediately deleted from +user-visible list of static redirects (available through +.Dv NGM_NAT_LIST_REDIRECTS +message). +.It Dv NGM_NAT_REDIRECT_DELETE Pq Ic redirectdelete +Delete redirection with specified ID (currently active +connections are not affected). +.It Dv NGM_NAT_ADD_SERVER Pq Ic addserver +Add another server to a pool. +This is used to transparently offload network load on a single server +and distribute the load across a pool of servers, also known as +.Em LSNAT +(RFC 2391). +The following +.Vt "struct ng_nat_add_server" +must be supplied as argument. +.Bd -literal +struct ng_nat_add_server { + uint32_t id; + struct in_addr addr; + uint16_t port; +}; +.Ed +.Pp +First, the redirection is set up by +.Dv NGM_NAT_REDIRECT_PORT +or +.Dv NGM_NAT_REDIRECT_ADDR . +Then, ID of that redirection is used in multiple +.Dv NGM_NAT_ADD_SERVER +messages to add necessary number of servers. +For redirections created by +.Dv NGM_NAT_REDIRECT_ADDR , +the +.Va port +is ignored and could have any value. +Original redirection's parameters +.Va local_addr +and +.Va local_port +are also ignored after +.Dv NGM_NAT_ADD_SERVER +was used (they are effectively replaced by server pool). +.It Dv NGM_NAT_LIST_REDIRECTS Pq Ic listredirects +Return list of configured static redirects as +.Vt "struct ng_nat_list_redirects" . +.Bd -literal +struct ng_nat_listrdrs_entry { + uint32_t id; /* Anything except zero */ + struct in_addr local_addr; + struct in_addr alias_addr; + struct in_addr remote_addr; + uint16_t local_port; + uint16_t alias_port; + uint16_t remote_port; + uint16_t proto; /* Valid proto or NG_NAT_REDIRPROTO_ADDR */ + uint16_t lsnat; /* LSNAT servers count */ + char description[NG_NAT_DESC_LENGTH]; +}; +struct ng_nat_list_redirects { + uint32_t total_count; + struct ng_nat_listrdrs_entry redirects[]; +}; +#define NG_NAT_REDIRPROTO_ADDR (IPPROTO_MAX + 3) +.Ed +.Pp +Entries of the +.Va redirects +array returned in the unified format for all redirect types. +Ports are meaningful only if protocol is either TCP or UDP +and +.Em static NAT +redirection (created by +.Dv NGM_NAT_REDIRECT_ADDR ) +is indicated by +.Va proto +set to +.Dv NG_NAT_REDIRPROTO_ADDR . +If +.Va lsnat +servers counter is greater than zero, then +.Va local_addr +and +.Va local_port +are also meaningless. +.It Dv NGM_NAT_PROXY_RULE Pq Ic proxyrule +Specify a transparent proxying rule (string must be +supplied as argument). +See +.Xr libalias 3 +for details. +.It Dv NGM_NAT_LIBALIAS_INFO Pq Ic libaliasinfo +Return internal statistics of +.Xr libalias 3 +instance as +.Vt "struct ng_nat_libalias_info" . +.Bd -literal +struct ng_nat_libalias_info { + uint32_t icmpLinkCount; + uint32_t udpLinkCount; + uint32_t tcpLinkCount; + uint32_t sctpLinkCount; + uint32_t pptpLinkCount; + uint32_t protoLinkCount; + uint32_t fragmentIdLinkCount; + uint32_t fragmentPtrLinkCount; + uint32_t sockCount; +}; +.Ed +In case of +.Nm +failed to retrieve a certain counter +from its +.Xr libalias 3 +instance, the corresponding field is returned as +.Va UINT32_MAX . +.It Dv NGM_NAT_SET_DLT Pq Ic setdlt +Sets the data link type on the +.Va in +and +.Va out +hooks. +Currently, supported types are +.Cm DLT_RAW +(raw IP datagrams , no offset applied, the default) and +.Cm DLT_EN10MB +(Ethernet). DLT_ definitions can be found in +.In net/bpf.h . +If you want to work on the +.Xr ipfw 8 +level you must use no additional offset by specifying +.Cm DLT_RAW . +If, however, you attach +.Nm +to a network interface directly and +.Cm EN10MB +is specified, then the extra offset will be applied to take into account +link-level header. +In this mode the +.Nm +would also inspect appropriate type field in the Ethernet header and +pass-through any datagrams that are not IP packets. +.It Dv NGM_NAT_GET_DLT Pq Ic getdlt +This control message returns the current data link type of the +.Va in +and +.Va out +hooks. +.El +.Pp +In all redirection messages +.Va local_addr +and +.Va local_port +mean address and port of target machine in the internal network, +respectively. +If +.Va alias_addr +is zero, then default aliasing address (set by +.Dv NGM_NAT_SET_IPADDR ) +is used. +Connections can also be restricted to be accepted only +from specific external machines by using non-zero +.Va remote_addr +and/or +.Va remote_port . +Each redirection assigned an ID which can be later used for +redirection manipulation on individual basis (e.g., removal). +This ID guaranteed to be unique until the node shuts down +(it will not be reused after deletion), and is returned to +user after making each new redirection or can be found in +the stored list of all redirections. +The +.Va description +passed to and from node unchanged, together with ID providing +a way for several entities to concurrently manipulate +redirections in automated way. +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when both hooks are disconnected. +.Sh EXAMPLES +In the following example, the packets are injected into a +.Nm nat +node using the +.Xr ng_ipfw 4 +node. +.Bd -literal -offset indent +# Create NAT node +ngctl mkpeer ipfw: nat 60 out +ngctl name ipfw:60 nat +ngctl connect ipfw: nat: 61 in +ngctl msg nat: setaliasaddr x.y.35.8 + +# Divert traffic into NAT node +ipfw add 300 netgraph 61 all from any to any in via fxp0 +ipfw add 400 netgraph 60 all from any to any out via fxp0 + +# Let packets continue with after being (de)aliased +sysctl net.inet.ip.fw.one_pass=0 +.Ed +.Pp +The +.Nm +node can be inserted right after the +.Xr ng_iface 4 +node in the graph. +In the following example, we perform masquerading on a +serial line with HDLC encapsulation. +.Bd -literal -offset indent +/usr/sbin/ngctl -f- <<-SEQ + mkpeer cp0: cisco rawdata downstream + name cp0:rawdata hdlc + mkpeer hdlc: nat inet in + name hdlc:inet nat + mkpeer nat: iface out inet + msg nat: setaliasaddr x.y.8.35 +SEQ +ifconfig ng0 x.y.8.35 x.y.8.1 +.Ed +.Pp +The +.Nm +node can also be attached directly to the physical interface +via +.Xr ng_ether 4 +node in the graph. +In the following example, we perform masquerading on a +Ethernet interface connected to a public network. +.Bd -literal -offset indent +ifconfig igb0 inet x.y.8.35 netmask 0xfffff000 +route add default x.y.0.1 +/usr/sbin/ngctl -f- <<-SEQ + mkpeer igb0: nat lower in + name igb0:lower igb0_NAT + connect igb0: igb0_NAT: upper out + msg igb0_NAT: setdlt 1 + msg igb0_NAT: setaliasaddr x.y.8.35 +SEQ +.Ed +.Sh SEE ALSO +.Xr libalias 3 , +.Xr ng_ipfw 4 , +.Xr natd 8 , +.Xr ng_ether 8 , +.Xr ngctl 8 +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 6.0 . +.Sh AUTHORS +.An Gleb Smirnoff Aq Mt glebius@FreeBSD.org diff --git a/static/freebsd/man4/ng_netflow.4 b/static/freebsd/man4/ng_netflow.4 new file mode 100644 index 00000000..e313eb06 --- /dev/null +++ b/static/freebsd/man4/ng_netflow.4 @@ -0,0 +1,356 @@ +.\" Copyright (c) 2004-2005 Gleb Smirnoff +.\" 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 December 10, 2012 +.Dt NG_NETFLOW 4 +.Os +.Sh NAME +.Nm ng_netflow +.Nd Cisco's NetFlow implementation +.Sh SYNOPSIS +.In sys/types.h +.In netinet/in.h +.In netgraph/netflow/ng_netflow.h +.Sh DESCRIPTION +The +.Nm +node implements Cisco's NetFlow export protocol on a router running +.Fx . +The +.Nm +node listens for incoming traffic and identifies unique flows in it. +Flows are distinguished by endpoint IP addresses, TCP/UDP port numbers, +ToS and input interface. +Expired flows are exported out of the node in NetFlow version 5/9 UDP datagrams. +Expiration reason can be one of the following: +.Bl -dash +.It +RST or FIN TCP segment. +.It +Active timeout. +Flows cannot live more than the specified period of time. +The default is 1800 seconds (30 minutes). +.It +Inactive timeout. +A flow was inactive for the specified period of time. +The default is 15 seconds. +.El +.Pp +Node supports IPv6 accounting (NetFlow v9 only) and is aware of multiple fibs. +Different fibs are mapped to different domain_id in NetFlow V9 and different engine_id in NetFlow V5. +.Sh HOOKS +This node type supports up to +.Dv NG_NETFLOW_MAXIFACES +(default 65536) hooks named +.Va iface0 , iface1 , +etc., +and the same number of hooks named +.Va out0 , out1 , +etc., +plus two export hooks: +.Va export +(for NetFlow version 5) and +.Va export9 +(for NetFlow version 9). +Export can be done simultaneously for all supported export hooks. +By default (ingress NetFlow enabled) node does NetFlow accounting of data +received on +.Va iface* +hooks. +If corresponding +.Va out +hook is connected, unmodified data is bypassed to it, otherwise data is freed. +If data is received on +.Va out +hook, it is bypassed to corresponding +.Va iface +hook without any processing (egress NetFlow disabled by default). +When full export datagram for an export protocol is built it is sent to the +.Va export +or +.Va export9 +hook. +In normal operation, one (or more) export hook is connected to the +.Va inet/dgram/udp +hook of the +.Xr ng_ksocket 4 +node. +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_NETFLOW_INFO Pq Ic info +Returns some node statistics and the current timeout values in a +.Vt "struct ng_netflow_info" . +.It Dv NGM_NETFLOW_IFINFO Pq Ic ifinfo +Returns information about the +.Va iface Ns Ar N +hook. +The hook number is passed as an argument. +.It Dv NGM_NETFLOW_SETDLT Pq Ic setdlt +Sets data link type on the +.Va iface Ns Ar N +hook. +Currently, supported types are +.Cm DLT_RAW +(raw IP datagrams) and +.Cm DLT_EN10MB +(Ethernet). +DLT_ definitions can be found in +.In net/bpf.h +header. +Currently used values are 1 for +.Cm DLT_EN10MB +and 12 for +.Cm DLT_RAW . +This message type uses +.Vt "struct ng_netflow_setdlt" +as an argument: +.Bd -literal -offset 4n +struct ng_netflow_setdlt { + uint16_t iface; /* which iface dlt change */ + uint8_t dlt; /* DLT_XXX from bpf.h */ +}; +.Ed +.Pp +The requested +.Va iface Ns Ar N +hook must already be connected, otherwise message send operation will +return an error. +.It Dv NGM_NETFLOW_SETIFINDEX Pq Ic setifindex +In some cases, +.Nm +may be unable to determine the input interface index of a packet. +This can happen if traffic enters the +.Nm +node before it comes to the system interface's input queue. +An example of such a setup is capturing a traffic +.Em between +synchronous data line and +.Xr ng_iface 4 . +In this case, the input index should be associated with a given hook. +The interface's index can be determined via +.Xr if_nametoindex 3 +from userland. +This message requires +.Vt "struct ng_netflow_setifindex" +as an argument: +.Bd -literal -offset 4n +struct ng_netflow_setifindex { + uint16_t iface; /* which iface index change */ + uint16_t index; /* new index */ +}; +.Ed +.Pp +The requested +.Va iface Ns Ar N +hook must already be connected, otherwise the message +send operation will return an error. +.It Dv NGM_NETFLOW_SETTIMEOUTS Pq Ic settimeouts +Sets values in seconds for NetFlow active/inactive timeouts. +This message requires +.Vt "struct ng_netflow_settimeouts" +as an argument: +.Bd -literal -offset 4n +struct ng_netflow_settimeouts { + uint32_t inactive_timeout; /* flow inactive timeout */ + uint32_t active_timeout; /* flow active timeout */ +}; +.Ed +.It Dv NGM_NETFLOW_SETCONFIG Pq Ic setconfig +Sets configuration for the specified interface. +This message requires +.Vt "struct ng_netflow_setconfig" +as an argument: +.Bd -literal -offset 4n +struct ng_netflow_setconfig { + uint16_t iface; /* which iface config change */ + uint32_t conf; /* new config */ +#define NG_NETFLOW_CONF_INGRESS 1 +#define NG_NETFLOW_CONF_EGRESS 2 +#define NG_NETFLOW_CONF_ONCE 4 +#define NG_NETFLOW_CONF_THISONCE 8 +#define NG_NETFLOW_CONF_NOSRCLOOKUP 16 +#define NG_NETFLOW_CONF_NODSTLOOKUP 32 +}; +.Ed +.Pp +Configuration is a bitmask of several options. +Option NG_NETFLOW_CONF_INGRESS +enabled by default enables ingress NetFlow generation (for data coming from +ifaceX hook). +Option +.Va NG_NETFLOW_CONF_EGRESS +enables egress NetFlow (for data coming from outX hook). +Option +.Va NG_NETFLOW_CONF_ONCE +defines that packet should be accounted only once if it several times passes +via netflow node. +Option +.Va NG_NETFLOW_CONF_THISONCE +defines that packet should be accounted only once if it several times passes +via exactly this netflow node. +These two options are important to avoid duplicate accounting when both ingress +and egress NetFlow are enabled. +Option +.Va NG_NETFLOW_CONF_NOSRCLOOKUP +skips radix lookup on flow source address used to fill in network mask. +Option +.Va NG_NETFLOW_CONF_NODSTLOOKUP +skips radix lookup on destination (which fills egress interface id, destination +mask and gateway). +If one doesn't need data provided by lookups, he/she can disable them, to reduce +load on routers. +.It Dv NGM_NETFLOW_SETTEMPLATE Pq Ic settemplate +Sets various timeouts to announce data flow templates +(NetFlow v9-specific). This message requires +.Vt "struct ng_netflow_settemplate" +as an argument: +.Bd -literal -offset 4n +struct ng_netflow_settemplate { + uint16_t time; /* max time between announce */ + uint16_t packets; /* max packets between announce */ +}; +.Ed +.Pp +Value of time field represents time in seconds to re-announce data templates. +Value of packets field represents maximum packets count between +re-announcing data templates. +.It Dv NGM_NETFLOW_SETMTU Pq Ic setmtu +Sets export interface MTU to build packets of specified size (NetFlow v9-specific). +This message requires +.Vt "struct ng_netflow_setmtu" +as an argument: +.Bd -literal -offset 4n +struct ng_netflow_setemtu { + uint16_t mtu; /* MTU for packet */ +}; +.Ed +.Pp +Default is 1500 bytes. +.It Dv NGM_NETFLOW_SHOW +This control message asks a node to dump the entire contents of the flow cache. +It is called from +.Xr flowctl 8 , +not directly from +.Xr ngctl 8 . +.It Dv NGM_NETFLOW_V9INFO Pq Ic v9info +Returns some NetFlow v9 related values in a +.Bd -literal -offset 4n +struct ng_netflow_v9info { + uint16_t templ_packets; /* v9 template packets */ + uint16_t templ_time; /* v9 template time */ + uint16_t mtu; /* v9 MTU */ +}; +.Ed +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +.Sh EXAMPLES +The simplest possible configuration is one Ethernet interface, where +flow collecting is enabled. +.Bd -literal -offset indent +/usr/sbin/ngctl -f- <<-SEQ + mkpeer fxp0: netflow lower iface0 + name fxp0:lower netflow + connect fxp0: netflow: upper out0 + mkpeer netflow: ksocket export inet/dgram/udp + msg netflow:export connect inet/10.0.0.1:4444 +SEQ +.Ed +.Pp +This is a more complicated example of a router with 2 NetFlow-enabled +interfaces +.Li fxp0 +and +.Li ng0 . +Note that the +.Va ng0: +node in this example is connected to +.Xr ng_tee 4 . +The latter sends us a copy of IP packets, which we analyze and free. +On +.Va fxp0: +we do not use tee, but send packets back to either node. +.Bd -literal -offset indent +/usr/sbin/ngctl -f- <<-SEQ + # connect ng0's tee to iface0 hook + mkpeer ng0:inet netflow right2left iface0 + name ng0:inet.right2left netflow + # set DLT to raw mode + msg netflow: setdlt { iface=0 dlt=12 } + # set interface index (5 in this example) + msg netflow: setifindex { iface=0 index=5 } + + # Connect fxp0: to iface1 and out1 hook + connect fxp0: netflow: lower iface1 + connect fxp0: netflow: upper out1 + + # Create ksocket node on export hook, and configure it + # to send exports to proper destination + mkpeer netflow: ksocket export inet/dgram/udp + msg netflow:export connect inet/10.0.0.1:4444 +SEQ +.Ed +.Sh SEE ALSO +.Xr setfib 2 , +.Xr netgraph 4 , +.Xr ng_ether 4 , +.Xr ng_iface 4 , +.Xr ng_ksocket 4 , +.Xr ng_tee 4 , +.Xr flowctl 8 , +.Xr ngctl 8 +.Rs +.%A B. Claise, Ed +.%T "Cisco Systems NetFlow Services Export Version 9" +.%O RFC 3954 +.Re +.Pp +.Pa http://www.cisco.com/en/US/docs/ios/solutions_docs/netflow/nfwhite.html +.Sh AUTHORS +.An -nosplit +The +.Nm +node type was written by +.An Gleb Smirnoff Aq Mt glebius@FreeBSD.org , +.An Alexander Motin Aq Mt mav@FreeBSD.org , +.An Alexander Chernikov Aq Mt melifaro@ipfw.ru . +The initial code was based on +.Nm ng_ipacct +written by +.An Roman V. Palagin Aq Mt romanp@unshadow.net . +.Sh BUGS +Cache snapshot obtained via +.Dv NGM_NETFLOW_SHOW +command may lack some percentage of entries under severe load. +.Pp +The +.Nm +node type does not fill in AS numbers. +This is due to the lack of necessary information in the kernel routing table. +However, this information can be injected into the kernel from a routing daemon +such as GNU Zebra. +This functionality may become available in future releases. diff --git a/static/freebsd/man4/ng_one2many.4 b/static/freebsd/man4/ng_one2many.4 new file mode 100644 index 00000000..06bcbabe --- /dev/null +++ b/static/freebsd/man4/ng_one2many.4 @@ -0,0 +1,275 @@ +.\" Copyright (c) 2000 Whistle Communications, Inc. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, use and +.\" redistribution of this software, in source or object code forms, with or +.\" without modifications are expressly permitted by Whistle Communications; +.\" provided, however, that: +.\" 1. Any and all reproductions of the source or object code must include the +.\" copyright notice above and the following disclaimer of warranties; and +.\" 2. No rights are granted, in any manner or form, to use Whistle +.\" Communications, Inc. trademarks, including the mark "WHISTLE +.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as +.\" such appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, +.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. +.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY +.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS +.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. +.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES +.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING +.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY +.\" OF SUCH DAMAGE. +.\" +.\" Author: Archie Cobbs +.\" +.Dd November 13, 2012 +.Dt NG_ONE2MANY 4 +.Os +.Sh NAME +.Nm ng_one2many +.Nd packet multiplexing netgraph node type +.Sh SYNOPSIS +.In sys/types.h +.In netgraph/ng_one2many.h +.Sh DESCRIPTION +The +.Nm one2many +provides a simple mechanism for routing packets over several links +in a one-to-many (and in the reverse direction, many-to-one) fashion. +There is a single hook named +.Dv one , +and multiple hooks named +.Dv many0 , +.Dv many1 , +etc. +Packets received on any of the +.Dv many +hooks are forwarded out the +.Dv one +hook. +Packets received on the +.Dv one +hook are forwarded out one or more of the +.Dv many +hooks; which hook(s) is determined by the node's configured +transmit algorithm. +Packets are not altered in any way. +.Pp +Each of the connected many links may be considered to be up or down. +Packets are never delivered out a many hook that is down. +How a link is determined to be up or down depends on the node's +configured link failure detection algorithm. +.Pp +Before an interface or link can be plumbed into a group, its status +must be marked as being +.Dq up . +This is normally setup during the initial boot stages by +.Xr rc.conf 5 . +It is also possible to change an interface's status to +.Dq up +by using the +.Xr ifconfig 8 +utility. +.Sh TRANSMIT ALGORITHMS +.Bl -tag -width foo +.It Dv NG_ONE2MANY_XMIT_ROUNDROBIN +Packets are delivered out the many hooks in sequential order. +Each packet goes out on a different +.Dv many +hook. +.It Dv NG_ONE2MANY_XMIT_ALL +Packets are delivered out all the +.Dv many +hooks. +Each packet goes out each +.Dv many +hook. +.It Dv NG_ONE2MANY_XMIT_FAILOVER +Packets are delivered out the first active +.Dv many +hook. +.El +.Pp +In the future other algorithms may be added as well. +.Sh LINK FAILURE DETECTION +The node distinguishes between active and failed links. +Data is sent only to active links. +The following link failure detection algorithms are available: +.Bl -tag -width foo +.It Dv NG_ONE2MANY_FAIL_MANUAL +The node is explicitly told which of the links are up via the +.Dv NGM_ONE2MANY_SET_CONFIG +control message (see below). +Newly connected links are down until configured otherwise. +.It Dv NG_ONE2MANY_FAIL_NOTIFY +The node listens to flow control message from +.Va many +hooks, and considers link failed if +.Dv NGM_LINK_IS_DOWN +is received. +If the +.Dv NGM_LINK_IS_UP +message is received, node considers link active. +.El +.Pp +In the future other algorithms may be added as well. +.Pp +When all links are considered failed, node sends the +.Dv NGM_LINK_IS_DOWN +message towards the +.Va one +hook. +When at least one link comes up, node sends the +.Dv NGM_LINK_IS_UP +message towards the +.Va one +hook. +.Sh HOOKS +This node type supports up to +.Dv NG_ONE2MANY_MAX_LINKS +hooks named +.Dv many0 , +.Dv many1 , +etc., +plus a single hook named +.Dv one . +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the +following: +.Bl -tag -width foo +.It Dv NGM_ONE2MANY_SET_CONFIG Pq Ic setconfig +Sets the node configuration using a +.Dv "struct ng_one2many_link_config" +as the control message argument: +.Bd -literal +/* Node configuration structure */ +struct ng_one2many_config { + uint32_t xmitAlg; /* how to distribute packets */ + uint32_t failAlg; /* how to detect link failure */ + u_char enabledLinks[NG_ONE2MANY_MAX_LINKS]; +}; +.Ed +.Pp +Currently, the valid settings for the +.Dv xmitAlg +field are +.Dv NG_ONE2MANY_XMIT_ROUNDROBIN +(default) or +.Dv NG_ONE2MANY_XMIT_ALL . +The valid settings for +.Dv failAlg +are +.Dv NG_ONE2MANY_FAIL_MANUAL +(default) or +.Dv NG_ONE2MANY_FAIL_NOTIFY . +.It Dv NGM_ONE2MANY_GET_CONFIG Pq Ic getconfig +Returns the current node configuration in a +.Dv "struct ng_one2many_link_config" . +.It Dv NGM_ONE2MANY_GET_STATS Pq Ic getstats +This command takes a 32 bit link number as an argument and +returns a +.Dv "struct ng_one2many_link_stats" +containing statistics for the corresponding +.Dv many +link, which may or may not be currently connected: +.Bd -literal +/* Statistics structure (one for each link) */ +struct ng_one2many_link_stats { + uint64_t recvOctets; /* total octets rec'd on link */ + uint64_t recvPackets; /* total pkts rec'd on link */ + uint64_t xmitOctets; /* total octets xmit'd on link */ + uint64_t xmitPackets; /* total pkts xmit'd on link */ + uint64_t memoryFailures; /* times couldn't get mem or mbuf */ +}; +.Ed +.Pp +To access statistics for the +.Dv one +link, use the link number +.Dv -1 . +.It Dv NGM_ONE2MANY_CLR_STATS Pq Ic clrstats +This command takes a 32 bit link number as an argument and +clears the statistics for that link. +.It Dv NGM_ONE2MANY_GETCLR_STATS Pq Ic getclrstats +Same as +.Dv NGM_ONE2MANY_GET_STATS , +but also atomically clears the statistics for the link as well. +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +.Sh EXAMPLES +The following commands will set up Ethernet interfaces +.Dv fxp0 +to deliver packets alternating over the physical interfaces +corresponding to networking interfaces +.Dv fxp0 +through +.Dv fxp3 : +.Bd -literal + # Plumb nodes together + + ngctl mkpeer fxp0: one2many upper one + ngctl connect fxp0: fxp0:upper lower many0 + ngctl connect fxp1: fxp0:upper lower many1 + ngctl connect fxp2: fxp0:upper lower many2 + ngctl connect fxp3: fxp0:upper lower many3 + + # Allow fxp1 through fxp3 to xmit/recv fxp0 frames + + ngctl msg fxp1: setpromisc 1 + ngctl msg fxp2: setpromisc 1 + ngctl msg fxp3: setpromisc 1 + ngctl msg fxp1: setautosrc 0 + ngctl msg fxp2: setautosrc 0 + ngctl msg fxp3: setautosrc 0 + + # Configure all four links as up + + ngctl msg fxp0:upper \\ + setconfig "{ xmitAlg=1 failAlg=1 enabledLinks=[ 1 1 1 1 ] }" + + # Bring up interface + + ifconfig fxp0 192.168.1.1 netmask 0xfffffffc +.Ed +.Pp +With a similar setup on a peer machine (using the address +192.168.1.2), a point-to-point +Ethernet connection with four times normal bandwidth is +achieved. +.Sh SEE ALSO +.Xr lagg 4 , +.Xr netgraph 4 , +.Xr ng_bridge 4 , +.Xr ng_ether 4 , +.Xr ng_hub 4 , +.Xr ifconfig 8 , +.Xr ngctl 8 +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 4.2 . +.Sh AUTHORS +.An -nosplit +The +.Nm one2many +netgraph node (with round-robin algorithm) was written by +.An Archie Cobbs Aq Mt archie@FreeBSD.org . +The all algorithm was added by +.An Rogier R. Mulhuijzen Aq Mt drwilco@drwilco.net . +.Sh BUGS +More transmit and link failure algorithms should be supported. +A good candidate is Cisco's Etherchannel. diff --git a/static/freebsd/man4/ng_patch.4 b/static/freebsd/man4/ng_patch.4 new file mode 100644 index 00000000..9c0d7a8e --- /dev/null +++ b/static/freebsd/man4/ng_patch.4 @@ -0,0 +1,271 @@ +.\" Copyright (c) 2010 Maxim Ignatenko +.\" Copyright (c) 2010 Vadim Goncharov +.\" Copyright (c) 2015 Dmitry Vagin +.\" 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 November 17, 2015 +.Dt NG_PATCH 4 +.Os +.Sh NAME +.Nm ng_patch +.Nd "trivial mbuf data modifying netgraph node type" +.Sh SYNOPSIS +.In netgraph/ng_patch.h +.Sh DESCRIPTION +The +.Nm patch +node performs data modification of packets passing through it. +Modifications are restricted to a subset of C language operations +on unsigned integers of 8, 16, 32 or 64 bit size. +These are: set to new value (=), addition (+=), subtraction (-=), +multiplication (*=), division (/=), negation (= -), +bitwise AND (&=), bitwise OR (|=), bitwise eXclusive OR (^=), +shift left (<<=), shift right (>>=). +A negation operation is the one exception: integer is treated as signed +and second operand (the +.Va value ) +is not used. +If there is more than one modification operation, they are applied +to packets sequentially in the order they were specified by the user. +The data payload of a packet is viewed as an array of bytes, with a zero offset +corresponding to the very first byte of packet headers, and the +.Va length +bytes beginning from +.Va offset +as a single integer in network byte order. +An additional offset can be optionally +requested at configuration time to account for packet type. +.Sh HOOKS +This node type has two hooks: +.Bl -tag -width ".Va out" +.It Va in +Packets received on this hook are modified according to rules specified +in the configuration and then forwarded to the +.Ar out +hook, if it exists. +Otherwise they are reflected back to the +.Ar in +hook. +.It Va out +Packets received on this hook are forwarded to the +.Ar in +hook without any changes. +.El +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_PATCH_SETDLT Pq Ic setdlt +Sets the data link type on the +.Va in +hook (to help calculate relative offset). Currently, supported types are +.Cm DLT_RAW +(raw IP datagrams, no offset applied, the default) and +.Cm DLT_EN10MB +(Ethernet). DLT_ definitions can be found in +.In net/bpf.h . +If you want to work on the link layer header you must use no additional offset by specifying +.Cm DLT_RAW . +If +.Cm EN10MB +is specified, then the optional additional offset will take into account the Ethernet header and a QinQ header if present. +.It Dv NGM_PATCH_GETDLT Pq Ic getdlt +This control message returns the data link type of the +.Va in +hook. +.It Dv NGM_PATCH_SETCONFIG Pq Ic setconfig +This command sets the sequence of modify operations +that will be applied to incoming data on a hook. +The following +.Vt "struct ng_patch_config" +must be supplied as an argument: +.Bd -literal -offset 4n +struct ng_patch_op { + uint32_t offset; + uint16_t length; /* 1,2,4 or 8 bytes */ + uint16_t mode; + uint64_t value; +}; +/* Patching modes */ +#define NG_PATCH_MODE_SET 1 +#define NG_PATCH_MODE_ADD 2 +#define NG_PATCH_MODE_SUB 3 +#define NG_PATCH_MODE_MUL 4 +#define NG_PATCH_MODE_DIV 5 +#define NG_PATCH_MODE_NEG 6 +#define NG_PATCH_MODE_AND 7 +#define NG_PATCH_MODE_OR 8 +#define NG_PATCH_MODE_XOR 9 +#define NG_PATCH_MODE_SHL 10 +#define NG_PATCH_MODE_SHR 11 + +struct ng_patch_config { + uint32_t count; + uint32_t csum_flags; + uint32_t relative_offset; + struct ng_patch_op ops[]; +}; +.Ed +.Pp +The +.Va csum_flags +can be set to any combination of CSUM_IP, CSUM_TCP, CSUM_SCTP and CSUM_UDP +(other values are ignored) for instructing the IP stack to recalculate the +corresponding checksum before transmitting packet on output interface. +The +.Nm +node does not do any checksum correction by itself. +.Pp +The +.Va offset +value for the +.Vt ng_patch_op +structure is calculated from zero by default (the first byte of +packet headers). +If +.Va relative_offset +is enabled (set to 1) during configuration, the operation will have an +additional amount added to the offset based on the data link type. +.It Dv NGM_PATCH_GETCONFIG Pq Ic getconfig +This control message returns the current set of modify operations, +in the form of a +.Vt "struct ng_patch_config" . +.It Dv NGM_PATCH_GET_STATS Pq Ic getstats +Returns the node's statistics as a +.Vt "struct ng_patch_stats" . +.It Dv NGM_PATCH_CLR_STATS Pq Ic clrstats +Clears the node's statistics. +.It Dv NGM_PATCH_GETCLR_STATS Pq Ic getclrstats +This command is identical to +.Dv NGM_PATCH_GET_STATS , +except that the statistics are also atomically cleared. +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +.Sh EXAMPLES +This +.Nm +node was designed to modify TTL and TOS/DSCP fields in IP packets. +As an example, +suppose you have two adjacent simplex links to a remote network +(e.g.\& satellite), so that the packets expiring in between +will generate unwanted ICMP-replies which have to go forth, not back. +Thus you need to raise TTL of every packet entering link by 2 +to ensure the TTL will not reach zero there. +To achieve this you can set an +.Xr ipfw 8 +rule to use the +.Cm netgraph +action to inject packets which are going to the simplex link into the patch node, by using the +following +.Xr ngctl 8 +script: +.Bd -literal -offset 4n +/usr/sbin/ngctl -f- <<-SEQ + mkpeer ipfw: patch 200 in + name ipfw:200 ttl_add + msg ttl_add: setconfig { count=1 csum_flags=1 ops=[ \e + { mode=2 value=3 length=1 offset=8 } ] } +SEQ +/sbin/ipfw add 150 netgraph 200 ip from any to simplex.remote.net +.Ed +.Pp +Here the +.Dq Li ttl_add +node of type +.Nm +is configured to add (mode +.Dv NG_PATCH_MODE_ADD ) +a +.Va value +of 3 to a one-byte TTL field, which is 9th byte of IP packet header. +.Pp +Another example would be two consecutive modifications of packet TOS +field: say, you need to clear the +.Dv IPTOS_THROUGHPUT +bit and set the +.Dv IPTOS_MINCOST +bit. +So you do: +.Bd -literal -offset 4n +/usr/sbin/ngctl -f- <<-SEQ + mkpeer ipfw: patch 300 in + name ipfw:300 tos_chg + msg tos_chg: setconfig { count=2 csum_flags=1 ops=[ \e + { mode=7 value=0xf7 length=1 offset=1 } \e + { mode=8 value=0x02 length=1 offset=1 } ] } +SEQ +/sbin/ipfw add 160 netgraph 300 ip from any to any not dst-port 80 +.Ed +.Pp +This first does +.Dv NG_PATCH_MODE_AND +clearing the fourth bit and then +.Dv NG_PATCH_MODE_OR +setting the third bit. +.Pp +In both examples the +.Va csum_flags +field indicates that IP checksum (but not TCP or UDP checksum) should be +recalculated before transmit. +.Pp +Note: one should ensure that packets are returned to ipfw after processing +inside +.Xr netgraph 4 , +by setting appropriate +.Xr sysctl 8 +variable: +.Bd -literal -offset 4n +sysctl net.inet.ip.fw.one_pass=0 +.Ed +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ng_ipfw 4 , +.Xr ngctl 8 +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 8.1 . +.Sh AUTHORS +.An "Maxim Ignatenko" Aq gelraen.ua@gmail.com . +.Pp +Relative offset code by +.An "DMitry Vagin" +.Pp +This manual page was written by +.An "Vadim Goncharov" Aq vadimnuclight@tpu.ru . +.Sh BUGS +The node blindly tries to apply every patching operation to each packet +(except those which offset if greater than length of the packet), +so be sure that you supply only the right packets to it (e.g. changing +bytes in the ARP packets meant to be in IP header could corrupt +them and make your machine unreachable from the network). +.Pp +.Em !!! WARNING !!! +.Pp +The output path of the IP stack assumes correct fields and lengths in the +packets - changing them by to incorrect values can cause +unpredictable results including kernel panics. diff --git a/static/freebsd/man4/ng_pipe.4 b/static/freebsd/man4/ng_pipe.4 new file mode 100644 index 00000000..0262213e --- /dev/null +++ b/static/freebsd/man4/ng_pipe.4 @@ -0,0 +1,213 @@ +.\" Copyright (c) 2019 Lutz Donnerhacke +.\" Copyright (c) 2004-2008 University of Zagreb +.\" Copyright (c) 2007-2008 FreeBSD Foundation +.\" 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 October 17, 2019 +.Dt NG_PIPE 4 +.Os +.Sh NAME +.Nm ng_pipe +.Nd Traffic manipulating netgraph node type +.Sh SYNOPSIS +.In netgraph/ng_pipe.h +.Sh DESCRIPTION +The +.Nm pipe +node type manipulates traffic by emulating bandwidth and delay, as well as +random packet losses. +.Sh HOOKS +This node type supports the following hooks: +.Bl -tag -width ".Va upper" +.It Va upper +Hook leading to upper layer protocols. +.It Va lower +Hook leading to lower layer protocols. +.El +.Pp +Traffic flowing from +.Va upper +to +.Va lower +is considered +.Sy downstream +traffic. +Traffic flowing from +.Va lower +to +.Va upper +is considered +.Sy upstream +traffic. +.Sh MODE OF OPERATION +Data received on a hook - both in upstream and downstream direction - +is put into an inbound queue. +If inbound queue is full, discard one frame +depending on dropping policy (from the head or from the tail of the +queue). +.Pp +There are three mutually exclusive modes for the input queue: +.Bl -tag -width foo +.It Dv "First In First Out (FIFO)" +A single queue holds packets in chronological order. +.It Dv Weighted fair queuing (WFQ) +There are multiple queues for different traffic flows (based on IPv4 +IPs). +The longest queue is truncated if necessary. +This approach +assumes that the stalling flow is the flow with the most packets currently +on hold. +.It Dv Deficit Round Robin (DRR) +This mode is similar to WFQ, but packets are not taken out in +strict chronological order. +In principle oldest packets come first, +but not too many packets from the same flow. +.El +.Pp +It is possible to configure a duplication probability. +As the dice +decides, the currently active packet stays in the queue while a copy +of the packet is sent out. +Nothing prevents a packet from being +duplicated multiple times. +.Pp +Packets are dropped with an increasing probability depending on the +size of the packet, if a +.Va ber +(bit error rate) is configured. +.Pp +Surviving packets are delayed by the time the packet would need to +travel through a link of the configured bandwidth. +If this outbound +queue is full, the packet is dropped. +.Sh CONTROL MESSAGES +This node type supports the generic control messages and the following +specific messages. +.Bl -tag -width foo +.It Dv NGM_PIPE_SET_CFG Pq Ic setcfg +Set node configuration to the one specified in +.Vt "struct ng_pipe_cfg" +.Pp +Note: To set a value to zero, specify -1 instead. +This allows omitting configuration values, which should not be +modified. +.It Dv NGM_PIPE_GET_CFG Pq Ic getcfg +Return current node configuration as +.Vt "struct ng_pipe_cfg" +.Bd -literal +struct ng_pipe_cfg { + u_int64_t bandwidth; /* bits per second */ + u_int64_t delay; /* additional delay, usec */ + u_int32_t header_offset; /* offset of IP header in bytes */ + u_int32_t overhead; /* assumed L2 overhead in bytes */ + struct ng_pipe_hookcfg downstream; + struct ng_pipe_hookcfg upstream; +}; + +/* Config structure for one hook */ +struct ng_pipe_hookcfg { + u_int64_t bandwidth; /* bits per second */ + u_int64_t ber; /* avg. interval between bit errors (1 / BER) */ + u_int32_t qin_size_limit; /* number of queue items */ + u_int32_t qout_size_limit; /* number of queue items */ + u_int32_t duplicate; /* probability in % */ + u_int32_t fifo; /* 0 = off, 1 = on */ + u_int32_t drr; /* 0 = off, 1 = 2048 bytes, or x bytes */ + u_int32_t wfq; /* 0 = off, 1 = on */ + u_int32_t droptail; /* 0 = off, 1 = on */ + u_int32_t drophead; /* 0 = off, 1 = on */ +}; +.Ed +.It Dv NGM_PIPE_GET_STATS Pq Ic getstats +Return node statistics as +.Vt "struct ng_pipe_stats" +.Bd -literal +/* Statistics structure for one hook */ +struct ng_pipe_hookstat { + u_int64_t fwd_octets; + u_int64_t fwd_frames; + u_int64_t in_disc_octets; + u_int64_t in_disc_frames; + u_int64_t out_disc_octets; + u_int64_t out_disc_frames; +}; + +/* Statistics structure returned by NGM_PIPE_GET_STATS */ +struct ng_pipe_stats { + struct ng_pipe_hookstat downstream; + struct ng_pipe_hookstat upstream; +}; +.Ed +.It Dv NGM_PIPE_CLR_STATS Pq Ic clrstats +Clear node statistics. +.It Dv NGM_PIPE_GETCLR_STATS Pq Ic getclrstats +Atomically return and clear node statistics. +.It Dv NGM_PIPE_GET_RUN Pq Ic getrun +Return node statistics as +.Vt "struct ng_pipe_run" +.Bd -literal +/* Runtime structure for one hook */ +struct ng_pipe_hookrun { + u_int32_t fifo_queues; + u_int32_t qin_octets; + u_int32_t qin_frames; + u_int32_t qout_octets; + u_int32_t qout_frames; +}; + +/* Runtime structure returned by NGM_PIPE_GET_RUN */ +struct ng_pipe_run { + struct ng_pipe_hookrun downstream; + struct ng_pipe_hookrun upstream; +}; +.Ed +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +.Sh EXAMPLES +Limit outgoing data rate over fxp0 Ethernet interface to 20Mbps in +fifo mode and incoming to 50kbps in drr mode and 2% duplicate +probability. +.Bd -literal -offset indent +/usr/sbin/ngctl -f- <<-SEQ + mkpeer fxp0: pipe lower lower + name fxp0:lower fxp0_pipe + connect fxp0: fxp0_pipe: upper upper + msg fxp0_pipe: setcfg { downstream={ bandwidth=20000000 fifo=1 } } + msg fxp0_pipe: setcfg { upstream={ bandwidth=500000 drr=1 duplicate=2 } } +SEQ +.Ed +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ngctl 8 +.Sh AUTHORS +.An Lutz Donnerhacke Aq Mt lutz@donnerhacke.de +.Pq man page +.Sh BUGS +Error handling for memory issues is missing. +If kernel memory cannot be allocated immediately, a kernel panic will +be triggered. +Same happens if an mbuf is fragmented within the transport headers. diff --git a/static/freebsd/man4/ng_ppp.4 b/static/freebsd/man4/ng_ppp.4 new file mode 100644 index 00000000..c1b5b909 --- /dev/null +++ b/static/freebsd/man4/ng_ppp.4 @@ -0,0 +1,458 @@ +.\" Copyright (c) 1996-1999 Whistle Communications, Inc. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, use and +.\" redistribution of this software, in source or object code forms, with or +.\" without modifications are expressly permitted by Whistle Communications; +.\" provided, however, that: +.\" 1. Any and all reproductions of the source or object code must include the +.\" copyright notice above and the following disclaimer of warranties; and +.\" 2. No rights are granted, in any manner or form, to use Whistle +.\" Communications, Inc. trademarks, including the mark "WHISTLE +.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as +.\" such appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, +.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. +.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY +.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS +.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. +.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES +.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING +.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY +.\" OF SUCH DAMAGE. +.\" +.\" Author: Archie Cobbs +.\" $Whistle: ng_ppp.8,v 1.3 1999/01/25 23:46:27 archie Exp $ +.\" +.Dd November 13, 2012 +.Dt NG_PPP 4 +.Os +.Sh NAME +.Nm ng_ppp +.Nd PPP protocol netgraph node type +.Sh SYNOPSIS +.In sys/types.h +.In netgraph/ng_ppp.h +.Sh DESCRIPTION +The +.Nm ppp +node type performs multiplexing for the PPP protocol. +It handles only packets that contain data, and forwards protocol negotiation +and control packets to a separate controlling entity (e.g., a +user-land daemon). +This approach combines the fast dispatch of +kernel implementations with the configuration flexibility of a +user-land implementations. +The PPP node type directly supports +multi-link PPP, Van Jacobson compression, PPP compression, PPP +encryption, and the IP, IPX, and AppleTalk protocols. +A single PPP node corresponds to one PPP multi-link bundle. +.Pp +There is a separate hook for each PPP link in the bundle, plus +several hooks corresponding to the directly supported protocols. +For compression and encryption, separate attached nodes are required +to do the actual work. +The node type used will of course depend on the algorithm negotiated. +There is also a +.Dv bypass +hook which is used to handle any protocol not directly supported +by the node. +This includes all of the control protocols: LCP, IPCP, +CCP, etc. +Typically this node is connected to a user-land daemon via a +.Xr ng_socket 4 +type node. +.Sh ENABLING FUNCTIONALITY +In general, the PPP node enables a specific link or functionality when +(a) a +.Dv NGM_PPP_SET_CONFIG +message has been received which enables it, and +(b) the corresponding hook(s) are connected. +This allows the controlling entity to use either method (a) or (b) +(or both) to control the node's behavior. +When a link is connected but disabled, traffic can still flow on +the link via the +.Dv bypass +hook (see below). +.Sh LINK HOOKS +During normal operation, the individual PPP links are connected to hooks +.Dv link0 , +.Dv link1 , +etc. +Up to +.Dv NG_PPP_MAX_LINKS +links are supported. +These device-independent hooks transmit and receive full PPP +frames, which include the PPP protocol, address, control, and +information fields, but no checksum or other link-specific fields. +.Pp +On outgoing frames, when protocol compression +has been enabled and the protocol number is suitable for compression, +the protocol field will be compressed (i.e., sent as one byte +instead of two). +Either compressed or uncompressed protocol fields +are accepted on incoming frames. +Similarly, if address and control +field compression has been enabled for the link, the address and +control fields will be omitted (except for LCP frames as required +by the standards). +Incoming frames have the address and control fields +stripped automatically if present. +.Pp +Since all negotiation is handled outside the PPP node, the links +should not be connected and enabled until the corresponding link +has reached the network phase (i.e., LCP negotiation and authentication +have completed successfully) and the PPP node has been informed of +the link parameters via the +.Dv NGM_PPP_LINK_CONFIG +message. +.Pp +When a link is connected but disabled, all received frames are forwarded +directly out the +.Dv bypass +hook, and conversely, frames may be transmitted via the +.Dv bypass +hook as well. +This mode is appropriate for the link authentication phase. +As soon as the link is enabled, the PPP node will +begin processing frames received on the link. +.Sh COMPRESSION AND ENCRYPTION +Compression is supported via two hooks, +.Dv compress +and +.Dv decompress . +Compression and decompression can be enabled by toggling the +.Vt enableCompression +and +.Vt enableDecompression +fields of the node configuration structure. +(See below.) +If +.Vt enableCompression +is set to +.Dv NG_PPP_COMPRESS_SIMPLE , +then all outgoing frames are sent to the +.Dv compress +hook and all packets received on this hook are expected to be +compressed, so the COMPD tag is put on them unconditionally. +If +.Vt enableCompression +is set to +.Dv NG_PPP_COMPRESS_FULL , +then packets received on the +.Dv compress +hook are resent as is. +The compressor node should put the tag, if the packet was compressed. +If +.Vt enableDecompression +is set to +.Dv NG_PPP_DECOMPRESS_SIMPLE , +then the node will sent to the +.Dv decompress +hook only those frames, that are marked with the COMPD tag. +If +.Vt enableDecompression +is set to +.Dv NG_PPP_DECOMPRESS_FULL , +then the node will sent all incoming packets to the +.Dv decompress +hook. +Compression and decompression can be completely disabled by setting the +.Vt enableCompression +and +.Vt enableDecompression +fields to the +.Dv NG_PPP_COMPRESS_NONE +and +.Dv NG_PPP_DECOMPRESS_NONE , +respectively. +.Pp +Encryption works exactly analogously via the +.Dv encrypt +and +.Dv decrypt +nodes. +Data is always compressed before being encrypted, +and decrypted before being decompressed. +.Pp +Only bundle-level compression and encryption is directly supported; +link-level compression and encryption can be handled transparently +by downstream nodes. +.Sh VAN JACOBSON COMPRESSION +When all of the +.Dv vjc_ip , +.Dv vjc_vjcomp , +.Dv vjc_vjuncomp , +and +.Dv vjc_vjip +hooks are connected, and the corresponding configuration flag is +enabled, Van Jacobson compression and/or decompression will become active. +Normally these hooks connect to the corresponding hooks of a single +.Xr ng_vjc 4 +node. +The PPP node is compatible with the +.Dq pass through +modes of the +.Xr ng_vjc 4 +node type. +.Sh BYPASS HOOK +When a frame is received on a link with an unsupported protocol, +or a protocol which is disabled or for which the corresponding hook +is unconnected, the PPP node forwards the frame out the +.Dv bypass +hook, prepended with a four byte prefix. +This first two bytes of +the prefix indicate the link number on which the frame was received +(in network order). +For such frames received over the bundle (i.e., encapsulated in the +multi-link protocol), the special link number +.Dv NG_PPP_BUNDLE_LINKNUM +is used. +After the two byte link number is the two byte PPP protocol number +(also in network order). +The PPP protocol number is two bytes long even if the original frame +was protocol compressed. +.Pp +Conversely, any data written to the +.Dv bypass +hook is assumed to be in this same format. +The four byte header is +stripped off, the PPP protocol number is prepended (possibly compressed), +and the frame is delivered over the desired link. +If the link number is +.Dv NG_PPP_BUNDLE_LINKNUM +the frame will be delivered over the multi-link bundle; or, if multi-link +is disabled, over the (single) PPP link. +.Pp +Typically when the controlling entity receives an unexpected packet on the +.Dv bypass +hook it responds either by dropping the frame (if it is not ready for +the protocol) or with an LCP protocol reject (if it does not recognize +or expect the protocol). +.Sh MULTILINK OPERATION +To enable multi-link PPP, the corresponding configuration flag must be set +and at least one link connected. +The PPP node will not allow more than +one link to be connected if multi-link is not enabled, nor will it allow +certain multi-link settings to be changed while multi-link operation is +active (e.g., short sequence number header format). +.Pp +Since packets are sent as fragments across multiple individual links, +it is important that when a link goes down the PPP node is notified +immediately, either by disconnecting the corresponding hook or disabling +the link via the +.Dv NGM_PPP_SET_CONFIG +control message. +.Pp +Each link has configuration parameters for latency (specified in +milliseconds) and bandwidth (specified in tens of bytes per second). +The PPP node can be configured for +.Em round-robin +or +.Em optimized +packet delivery. +.Pp +When configured for round-robin delivery, the latency and bandwidth +values are ignored and the PPP node simply sends each frame as a +single fragment, alternating frames across all the links in the +bundle. +This scheme has the advantage that even if one link fails +silently, some packets will still get through. +It has the disadvantage +of sub-optimal overall bundle latency, which is important for +interactive response time, and sub-optimal overall bundle bandwidth +when links with different bandwidths exist in the same bundle. +.Pp +When configured for optimal delivery, the PPP node distributes the +packet across the links in a way that minimizes the time it takes +for the completed packet to be received by the far end. +This involves taking into account each link's latency, bandwidth, and +current queue length. +Therefore these numbers should be configured as accurately as possible. +The algorithm does require +some computation, so may not be appropriate for very slow machines +and/or very fast links. +.Pp +As a special case, if all links have identical latency and bandwidth, +then the above algorithm is disabled (because it is unnecessary) +and the PPP node simply fragments frames into equal sized portions +across all of the links. +.Sh HOOKS +This node type supports the following hooks: +.Bl -tag -width ".Va vjc_vjuncomp" +.It Va link +Individual PPP link number +.Dv +.It Va compress +Connection to compression engine +.It Va decompress +Connection to decompression engine +.It Va encrypt +Connection to encryption engine +.It Va decrypt +Connection to decryption engine +.It Va vjc_ip +Connection to +.Xr ng_vjc 4 +.Dv ip +hook +.It Va vjc_vjcomp +Connection to +.Xr ng_vjc 4 +.Dv vjcomp +hook +.It Va vjc_vjuncomp +Connection to +.Xr ng_vjc 4 +.Dv vjuncomp +hook +.It Va vjc_vjip +Connection to +.Xr ng_vjc 4 +.Dv vjip +hook +.It Va inet +IP packet data +.It Va ipv6 +IPv6 packet data +.It Va atalk +AppleTalk packet data +.It Va ipx +IPX packet data +.It Va bypass +Bypass hook; frames have a four byte header consisting of +a link number and a PPP protocol number. +.El +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_PPP_SET_CONFIG Pq Ic setconfig +This command configures all aspects of the node. +This includes enabling +multi-link PPP, encryption, compression, Van Jacobson compression, and IP, +IPv6, AppleTalk, and IPX packet delivery. +It includes per-link configuration, +including enabling the link, setting latency and bandwidth parameters, +and enabling protocol field compression. +Note that no link or functionality +is active until the corresponding hook is also connected. +This command takes a +.Dv "struct ng_ppp_node_conf" +as an argument: +.Bd -literal -offset 0n +/* Per-link config structure */ +struct ng_ppp_link_conf { + u_char enableLink; /* enable this link */ + u_char enableProtoComp;/* enable protocol field compression */ + u_char enableACFComp; /* enable addr/ctrl field compression */ + uint16_t mru; /* peer MRU */ + uint32_t latency; /* link latency (in milliseconds) */ + uint32_t bandwidth; /* link bandwidth (in bytes/sec/10) */ +}; + +/* Bundle config structure */ +struct ng_ppp_bund_conf { + uint16_t mrru; /* multilink peer MRRU */ + u_char enableMultilink; /* enable multilink */ + u_char recvShortSeq; /* recv multilink short seq # */ + u_char xmitShortSeq; /* xmit multilink short seq # */ + u_char enableRoundRobin; /* xmit whole packets */ + u_char enableIP; /* enable IP data flow */ + u_char enableIPv6; /* enable IPv6 data flow */ + u_char enableAtalk; /* enable AppleTalk data flow */ + u_char enableIPX; /* enable IPX data flow */ + u_char enableCompression; /* enable PPP compression */ + u_char enableDecompression; /* enable PPP decompression */ + u_char enableEncryption; /* enable PPP encryption */ + u_char enableDecryption; /* enable PPP decryption */ + u_char enableVJCompression; /* enable VJ compression */ + u_char enableVJDecompression; /* enable VJ decompression */ +}; + +struct ng_ppp_node_conf { + struct ng_ppp_bund_conf bund; + struct ng_ppp_link_conf links[NG_PPP_MAX_LINKS]; +}; +.Ed +.It Dv NGM_PPP_GET_CONFIG Pq Ic getconfig +Returns the current configuration as a +.Dv "struct ng_ppp_node_conf" . +.It Dv NGM_PPP_GET_LINK_STATS Pq Ic getstats +This command takes a two byte link number as an argument and returns a +.Dv "struct ng_ppp_link_stat" +containing statistics for the corresponding link. +Here +.Dv NG_PPP_BUNDLE_LINKNUM +is a valid link number corresponding to the multi-link bundle. +.It Dv NGM_PPP_GET_LINK_STATS64 Pq Ic getstats64 +Same as NGM_PPP_GET_LINK_STATS but returns +.Dv "struct ng_ppp_link_stat64" +containing 64bit counters. +.It Dv NGM_PPP_CLR_LINK_STATS Pq Ic clrstats +This command takes a two byte link number as an argument and +clears the statistics for that link. +.It Dv NGM_PPP_GETCLR_LINK_STATS Pq Ic getclrstats +Same as +.Dv NGM_PPP_GET_LINK_STATS , +but also atomically clears the statistics as well. +.It Dv NGM_PPP_GETCLR_LINK_STATS64 Pq Ic getclrstats64 +Same as NGM_PPP_GETCLR_LINK_STATS but returns +.Dv "struct ng_ppp_link_stat64" +containing 64bit counters. +.El +.Pp +This node type also accepts the control messages accepted by the +.Xr ng_vjc 4 +node type. +When received, these messages are simply forwarded to +the adjacent +.Xr ng_vjc 4 +node, if any. +This is particularly useful when the individual +PPP links are able to generate +.Dv NGM_VJC_RECV_ERROR +messages (see +.Xr ng_vjc 4 +for a description). +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ng_async 4 , +.Xr ng_iface 4 , +.Xr ng_mppc 4 , +.Xr ng_pppoe 4 , +.Xr ng_vjc 4 , +.Xr ngctl 8 +.Rs +.%A W. Simpson +.%T "The Point-to-Point Protocol (PPP)" +.%O RFC 1661 +.Re +.Rs +.%A K. Sklower +.%A B. Lloyd +.%A G. McGregor +.%A D. Carr +.%A T. Coradetti +.%T "The PPP Multilink Protocol (MP)" +.%O RFC 1990 +.Re +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 4.0 . +.Sh AUTHORS +.An Archie Cobbs Aq Mt archie@FreeBSD.org diff --git a/static/freebsd/man4/ng_pppoe.4 b/static/freebsd/man4/ng_pppoe.4 new file mode 100644 index 00000000..5b5f0dd6 --- /dev/null +++ b/static/freebsd/man4/ng_pppoe.4 @@ -0,0 +1,587 @@ +.\" Copyright (c) 1996-1999 Whistle Communications, Inc. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, use and +.\" redistribution of this software, in source or object code forms, with or +.\" without modifications are expressly permitted by Whistle Communications; +.\" provided, however, that: +.\" 1. Any and all reproductions of the source or object code must include the +.\" copyright notice above and the following disclaimer of warranties; and +.\" 2. No rights are granted, in any manner or form, to use Whistle +.\" Communications, Inc. trademarks, including the mark "WHISTLE +.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as +.\" such appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, +.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. +.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY +.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS +.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. +.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES +.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING +.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY +.\" OF SUCH DAMAGE. +.\" +.\" Author: Archie Cobbs +.\" $Whistle: ng_pppoe.8,v 1.1 1999/01/25 23:46:27 archie Exp $ +.\" +.Dd May 1, 2022 +.Dt NG_PPPOE 4 +.Os +.Sh NAME +.Nm ng_pppoe +.Nd RFC 2516 PPPoE protocol netgraph node type +.Sh SYNOPSIS +.In sys/types.h +.In net/ethernet.h +.In netgraph.h +.In netgraph/ng_pppoe.h +.Sh DESCRIPTION +The +.Nm pppoe +node type performs the PPPoE protocol. +It is used in conjunction with the +.Xr netgraph 4 +extensions to the Ethernet framework to divert and inject Ethernet packets +to and from a PPP agent (which is not specified). +.Pp +The +.Dv NGM_PPPOE_GET_STATUS +control message can be used at any time to query the current status +of the PPPoE module. +The only statistics presently available are the +total packet counts for input and output. +This node does not yet support +the +.Dv NGM_TEXT_STATUS +control message. +.Sh HOOKS +This node type supports the following hooks: +.Bl -tag -width ".Va [unspecified]" +.It Va ethernet +The hook that should normally be connected to an +.Xr ng_ether 4 +node. +Once connected, +.Nm +will send a message down this hook to determine Ethernet address of +the underlying node. +Obtained address will be stored and then used for outgoing datagrams. +.It Va debug +Presently no use. +.It Va [unspecified] +Any other name is assumed to be a session hook that will be connected to +a PPP client agent, or a PPP server agent. +.El +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width 3n +.It Dv NGM_PPPOE_GET_STATUS +This command returns status information in a +.Dv "struct ngpppoestat" : +.Bd -literal -offset 4n +struct ngpppoestat { + u_int packets_in; /* packets in from Ethernet */ + u_int packets_out; /* packets out towards Ethernet */ +}; +.Ed +.It Dv NGM_TEXT_STATUS +This generic message returns a human-readable version of the node status. +(not yet) +.It Dv NGM_PPPOE_CONNECT Pq Ic pppoe_connect +Tell a nominated newly created hook that its session should enter +the state machine as a client. +It must be newly created and a service name can be given as an argument. +It is legal to specify a zero-length service name, this is common +on some DSL setups. +It is possible to request a connection to a specific access concentrator, +and/or set a specific Host-Uniq tag, required by some Internet providers, +using the +.Qq Li [AC-Name\\][Host-Uniq|]Service-Name +syntax. +To set a binary Host-Uniq, it must be encoded as a hexadecimal lowercase +string and prefixed with +.Qq Li 0x , +for example +.Qq Li 0x6d792d746167 +is equivalent to +.Qq Li my-tag . +A session request packet will be broadcast on the Ethernet. +This command uses the +.Dv ngpppoe_init_data +structure shown below. +For example, this init data argument can be used to +connect to +.Qq Li my-isp +service with +.Qq Li my-host +uniq tag, accepting only +.Qq Li remote-ac +as access concentrator: +.Bd -literal -offset indent +"remote-ac\\my-host|my-isp" +.Ed +.It Dv NGM_PPPOE_LISTEN Pq Ic pppoe_listen +Tell a nominated newly created hook that its session should enter +the state machine as a server listener. +The argument +given is the name of the service to listen for. +A zero-length service name will match all requests for service. +A matching service request +packet will be passed unmodified back to the process responsible +for starting the service. +It can then examine it and pass it on to +the session that is started to answer the request. +This command uses the +.Dv ngpppoe_init_data +structure shown below. +.It Dv NGM_PPPOE_OFFER Pq Ic pppoe_offer +Tell a nominated newly created hook that its session should enter +the state machine as a server. +The argument given is the name of the service to offer. +A zero-length service +is legal. +The State machine will progress to a state where it will await +a request packet to be forwarded to it from the startup server, +which in turn probably received it from a LISTEN mode hook (see above). +This is so +that information that is required for the session that is embedded in +the original session request packet, is made available to the state machine +that eventually answers the request. +When the Session request packet is +received, the session negotiation will proceed. +This command uses the +.Dv ngpppoe_init_data +structure shown below. +.El +.Pp +The three commands above use a common data structure: +.Bd -literal -offset 4n +struct ngpppoe_init_data { + char hook[NG_HOOKSIZ]; /* hook to monitor on */ + uint16_t data_len; /* length of the service name */ + char data[0]; /* init data goes here */ +}; +.Ed +.Bl -tag -width 3n +.It Dv NGM_PPPOE_SUCCESS Pq Ic pppoe_success +This command is sent to the node that started this session with one of the +above messages, and reports a state change. +This message reports successful Session negotiation. +It uses the structure shown below, and +reports back the hook name corresponding to the successful session. +.It Dv NGM_PPPOE_FAIL Pq Ic pppoe_fail +This command is sent to the node that started this session with one of the +above messages, and reports a state change. +This message reports failed Session negotiation. +It uses the structure shown below, and +reports back the hook name corresponding to the failed session. +The hook will probably have been removed immediately after sending this +message. +.It Dv NGM_PPPOE_CLOSE Pq Ic pppoe_close +This command is sent to the node that started this session with one of the +above messages, and reports a state change. +This message reports a request to close a session. +It uses the structure shown below, and +reports back the hook name corresponding to the closed session. +The hook will probably have been removed immediately after sending this +message. +At present this message is not yet used and a +.Dv NGM_PPPOE_FAIL +message +will be received at closure instead. +.It Dv NGM_PPPOE_ACNAME +This command is sent to the node that started this session with one of the +above messages, and reports the Access Concentrator Name. +.El +.Pp +The four commands above use a common data structure: +.Bd -literal -offset 4n +struct ngpppoe_sts { + char hook[NG_HOOKSIZ]; +}; +.Ed +.Bl -tag -width 3n +.It Dv NGM_PPPOE_GETMODE Pq Ic pppoe_getmode +This command returns the current compatibility mode of the node +as a string. +.Tn ASCII +form of this message is +.Qq Li pppoe_getmode . +The following keywords can be returned: +.Bl -tag -width 3n +.It Qq standard +The node operates according to RFC 2516. +.It Qq 3Com +When +.Nm +is a PPPoE client, it initiates a session encapsulating packets into +incorrect 3Com ethertypes. +This compatibility option does not affect server mode. +In server mode +.Nm +supports both modes simultaneously, depending on the ethertype, the +client used when connecting. +.It Qq D-Link +When +.Nm +is a PPPoE server serving only specific Service-Name(s), it will respond +to a PADI requests with empty Service-Name tag, returning all available +Service-Name(s) on node. +This option is necessary for compatibility with D-Link DI-614+ and DI-624+ +SOHO routers as clients, when serving only specific Service-Name. +This compatibility option does not affect client mode. +.El +.It Dv NGM_PPPOE_SETMODE Pq Ic pppoe_setmode +Configure node to the specified mode. +The string argument is required. +This command understands the same keywords that are returned by the +.Dv NGM_PPPOE_GETMODE +command. +.Tn ASCII +form of this message is +.Qq Li pppoe_setmode . +For example, the following command will configure the node to initiate +the next session in the proprietary 3Com mode: +.Bd -literal -offset indent +ngctl msg fxp0:orphans pppoe_setmode '"3Com"' +.Ed +.It Dv NGM_PPPOE_SETENADDR Pq Ic setenaddr +Set the node Ethernet address for outgoing datagrams. +This message is important when a node has failed to obtain an Ethernet +address from its peer on the +.Dv ethernet +hook, or when user wants to override this address with another one. +.Tn ASCII +form of this message is +.Qq Li setenaddr . +.It Dv NGM_PPPOE_SETMAXP Pq Ic setmaxp +Set the node PPP-Max-Payload value as described in RFC 4638. +This message applies only to a client configuration. +.Tn ASCII +form of this message is +.Qq Li setmaxp . +.Pp +Data structure returned to client is: +.Bd -literal -offset 4n +struct ngpppoe_maxp { + char hook[NG_HOOKSIZ]; + uint16_t data; +}; +.Ed +.It Dv NGM_PPPOE_SEND_HURL Pq Ic send_hurl +Tell a nominated hook with an active session to send a PADM message with +a HURL tag. +The argument is the URL to be delivered to the client: +.Bd -literal -offset indent +ngctl msg fxp0:orphans send_hurl '{ hook="myHook" data="http://example.net/cpe" }' +.Ed +.It Dv NGM_PPPOE_SEND_MOTM Pq Ic send_motm +Tell a nominated hook with an active session to send a PADM message with +a MOTM tag. +The argument is the message to be delivered to the client: +.Bd -literal -offset indent +ngctl msg fxp0:orphans send_motm '{ hook="myHook" data="Welcome aboard" }' +.Ed +.El +.Pp +The two commands above use the same ngpppoe_init_data structure described +above. +.Bl -tag -width 3n +.It Dv NGM_PPPOE_HURL +This command is sent to the node that started this session when a PADM +message with a HURL tag is received, and contains a URL that the host can +pass to a web browser for presentation to the user. +.It Dv NGM_PPPOE_MOTM +This command is sent to the node that started this session when a PADM +message with a MOTM tag is received, and contains a Message Of The +Minute that the host can display to the user. +.El +.Pp +The two commands above use a common data structure: +.Bd -literal -offset 4n +struct ngpppoe_padm { + char msg[PPPOE_PADM_VALUE_SIZE]; +}; +.Ed +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, when all session have been disconnected or when the +.Dv ethernet +hook is disconnected. +.Sh SYSCTL VARIABLES +The node can mark transmitted LCP Ethernet packets (protocol 0xc021) +with 3-bit Priority Code Point (PCP) referring to IEEE 802.1p +class of service with following +.Xr sysctl 8 +variable. +.Bl -tag -width indent +.It Va net.graph.pppoe.lcp_pcp: 0..7 (default: 0) +Set it to non-zero value to be used by parent network interface driver +like +.Xr vlan 4 +.El +.Sh EXAMPLES +The following code uses +.Dv libnetgraph +to set up a +.Nm +node and connect it to both a socket node and an Ethernet node. +It can handle the case of when a +.Nm +node is already attached to the Ethernet. +It then starts a client session. +.Bd -literal +#include +#include +#include +#include +#include +#include +#include +#include + +#include +#include +#include +#include + +#include +#include +#include +#include +static int setup(char *ethername, char *service, char *sessname, + int *dfd, int *cfd); + +int +main() +{ + int fd1, fd2; + setup("xl0", NULL, "fred", &fd1, &fd2); + sleep (30); +} + +static int +setup(char *ethername, char *service, char *sessname, + int *dfd, int *cfd) +{ + struct ngm_connect ngc; /* connect */ + struct ngm_mkpeer mkp; /* mkpeer */ + /******** nodeinfo stuff **********/ + u_char rbuf[2 * 1024]; + struct ng_mesg *const resp = (struct ng_mesg *) rbuf; + struct hooklist *const hlist + = (struct hooklist *) resp->data; + struct nodeinfo *const ninfo = &hlist->nodeinfo; + int ch, no_hooks = 0; + struct linkinfo *link; + struct nodeinfo *peer; + /****message to connect PPPoE session*****/ + struct { + struct ngpppoe_init_data idata; + char service[100]; + } message; + /********tracking our little graph ********/ + char path[100]; + char source_ID[NG_NODESIZ]; + char pppoe_node_name[100]; + int k; + + /* + * Create the data and control sockets + */ + if (NgMkSockNode(NULL, cfd, dfd) < 0) { + return (errno); + } + /* + * find the ether node of the name requested by asking it for + * it's inquiry information. + */ + if (strlen(ethername) > 16) + return (EINVAL); + sprintf(path, "%s:", ethername); + if (NgSendMsg(*cfd, path, NGM_GENERIC_COOKIE, + NGM_LISTHOOKS, NULL, 0) < 0) { + return (errno); + } + /* + * the command was accepted so it exists. Await the reply (It's + * almost certainly already waiting). + */ + if (NgRecvMsg(*cfd, resp, sizeof(rbuf), NULL) < 0) { + return (errno); + } + /** + * The following is available about the node: + * ninfo->name (string) + * ninfo->type (string) + * ninfo->id (uint32_t) + * ninfo->hooks (uint32_t) (count of hooks) + * check it is the correct type. and get it's ID for use + * with mkpeer later. + */ + if (strncmp(ninfo->type, NG_ETHER_NODE_TYPE, + strlen(NG_ETHER_NODE_TYPE)) != 0) { + return (EPROTOTYPE); + } + sprintf(source_ID, "[%08x]:", ninfo->id); + + /* + * look for a hook already attached. + */ + for (k = 0; k < ninfo->hooks; k++) { + /** + * The following are available about each hook. + * link->ourhook (string) + * link->peerhook (string) + * peer->name (string) + * peer->type (string) + * peer->id (uint32_t) + * peer->hooks (uint32_t) + */ + link = &hlist->link[k]; + peer = &hlist->link[k].nodeinfo; + + /* Ignore debug hooks */ + if (strcmp("debug", link->ourhook) == 0) + continue; + + /* If the orphans hook is attached, use that */ + if (strcmp(NG_ETHER_HOOK_ORPHAN, + link->ourhook) == 0) { + break; + } + /* the other option is the 'divert' hook */ + if (strcmp("NG_ETHER_HOOK_DIVERT", + link->ourhook) == 0) { + break; + } + } + + /* + * See if we found a hook there. + */ + if (k < ninfo->hooks) { + if (strcmp(peer->type, NG_PPPOE_NODE_TYPE) == 0) { + /* + * If it's a type PPPoE, we skip making one + * ourself, but we continue, using + * the existing one. + */ + sprintf(pppoe_node_name, "[%08x]:", peer->id); + } else { + /* + * There is already someone hogging the data, + * return an error. Some day we'll try + * daisy-chaining.. + */ + return (EBUSY); + } + } else { + + /* + * Try make a node of type PPPoE against node "ID" + * On hook NG_ETHER_HOOK_ORPHAN. + */ + snprintf(mkp.type, sizeof(mkp.type), + "%s", NG_PPPOE_NODE_TYPE); + snprintf(mkp.ourhook, sizeof(mkp.ourhook), + "%s", NG_ETHER_HOOK_ORPHAN); + snprintf(mkp.peerhook, sizeof(mkp.peerhook), + "%s", NG_PPPOE_HOOK_ETHERNET); + /* Send message */ + if (NgSendMsg(*cfd, source_ID, NGM_GENERIC_COOKIE, + NGM_MKPEER, &mkp, sizeof(mkp)) < 0) { + return (errno); + } + /* + * Work out a name for the new node. + */ + sprintf(pppoe_node_name, "%s:%s", + source_ID, NG_ETHER_HOOK_ORPHAN); + } + /* + * We now have a PPPoE node attached to the Ethernet + * card. The Ethernet is addressed as ethername: The PPPoE + * node is addressed as pppoe_node_name: attach to it. + * Connect socket node to specified node Use the same hook + * name on both ends of the link. + */ + snprintf(ngc.path, sizeof(ngc.path), "%s", pppoe_node_name); + snprintf(ngc.ourhook, sizeof(ngc.ourhook), "%s", sessname); + snprintf(ngc.peerhook, sizeof(ngc.peerhook), "%s", sessname); + + if (NgSendMsg(*cfd, ".:", NGM_GENERIC_COOKIE, + NGM_CONNECT, &ngc, sizeof(ngc)) < 0) { + return (errno); + } + +#ifdef NONSTANDARD + /* + * In some cases we are speaking to 3Com hardware, so + * configure node to non-standard mode. + */ + if (NgSendMsg(*cfd, ngc.path, NGM_PPPOE_COOKIE, + NGM_PPPOE_SETMODE, NG_PPPOE_NONSTANDARD, + strlen(NG_PPPOE_NONSTANDARD) + 1) == -1) { + return (errno); + } +#endif + + /* + * Send it a message telling it to start up. + */ + bzero(&message, sizeof(message)); + snprintf(message.idata.hook, sizeof(message.idata.hook), + "%s", sessname); + if (service == NULL) { + message.idata.data_len = 0; + } else { + snprintf(message.idata.data, + sizeof(message.idata.data), "%s", service); + message.idata.data_len = strlen(service); + } + /* Tell session/hook to start up as a client */ + if (NgSendMsg(*cfd, ngc.path, + NGM_PPPOE_COOKIE, NGM_PPPOE_CONNECT, &message.idata, + sizeof(message.idata) + message.idata.data_len) < 0) { + return (errno); + } + return (0); +} +.Ed +.Sh SEE ALSO +.Xr netgraph 3 , +.Xr netgraph 4 , +.Xr ng_ether 4 , +.Xr ng_ppp 4 , +.Xr ng_socket 4 , +.Xr vlan 4 , +.Xr ngctl 8 , +.Xr ppp 8 +.Rs +.%A L. Mamakos +.%A K. Lidl +.%A J. Evarts +.%A D. Carrel +.%A D. Simone +.%A R. Wheeler +.%T "A Method for transmitting PPP over Ethernet (PPPoE)" +.%O RFC 2516 +.Re +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 4.0 . +.Sh AUTHORS +.An Julian Elischer Aq Mt julian@FreeBSD.org diff --git a/static/freebsd/man4/ng_pptpgre.4 b/static/freebsd/man4/ng_pptpgre.4 new file mode 100644 index 00000000..935b9ec9 --- /dev/null +++ b/static/freebsd/man4/ng_pptpgre.4 @@ -0,0 +1,198 @@ +.\" Copyright (c) 1996-1999 Whistle Communications, Inc. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, use and +.\" redistribution of this software, in source or object code forms, with or +.\" without modifications are expressly permitted by Whistle Communications; +.\" provided, however, that: +.\" 1. Any and all reproductions of the source or object code must include the +.\" copyright notice above and the following disclaimer of warranties; and +.\" 2. No rights are granted, in any manner or form, to use Whistle +.\" Communications, Inc. trademarks, including the mark "WHISTLE +.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as +.\" such appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, +.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. +.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY +.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS +.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. +.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES +.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING +.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY +.\" OF SUCH DAMAGE. +.\" +.\" Author: Archie Cobbs +.\" $Whistle: ng_pptpgre.8,v 1.2 1999/12/08 00:20:53 archie Exp $ +.\" +.Dd November 4, 2018 +.Dt NG_PPTPGRE 4 +.Os +.Sh NAME +.Nm ng_pptpgre +.Nd PPTP GRE protocol netgraph node type +.Sh SYNOPSIS +.In sys/types.h +.In netgraph/ng_pptpgre.h +.Sh DESCRIPTION +The +.Nm pptpgre +node type performs Generic Routing Encapsulation (GRE) over IP +for the PPTP protocol as specified by RFC 2637. +This involves packet +encapsulation, sequencing, acknowledgement, and an adaptive timeout +sliding window mechanism. +This node type does not handle any of +the TCP control protocol or call negotiation defined by PPTP. +.Pp +This node type expects to receive complete IP packets, +including the IP header, on the +.Dq Li lower +hook, but it transmits outgoing frames without any IP header. +The typical use for this node type would be to connect the +.Dq Li upper +hook to one of the link hooks of a +.Xr ng_ppp 4 +node, and the +.Dq Li lower +hook to the +.Dq Li "inet/raw/gre" +hook of a +.Xr ng_ksocket 4 +node. +.Sh HOOKS +This node type supports the following hooks: +.Bl -tag -width ".Va session_hhhh" +.It Va session_hhhh +Session 0xhhhh data packets to the upper protocol layers +.It Va upper +Same as session_hhhh, but for single session with configurable cid (legacy) +.It Va lower +Connection to the lower protocol layers +.El +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_PPTPGRE_SET_CONFIG Pq Ic setconfig +This command resets and configures hook for a session. +If corresponding +session_hhhh hook is not connected, upper hook will be configured. +This command takes a +.Vt "struct ng_pptpgre_conf" +as an argument: +.Bd -literal +/* Configuration for a session */ +struct ng_pptpgre_conf { + u_char enabled; /* enables traffic flow */ + u_char enableDelayedAck; /* enables delayed acks */ + u_char enableAlwaysAck; /* always include ack with data */ + u_char enableWindowing; /* enable windowing algorithm */ + uint16_t cid; /* my call id */ + uint16_t peerCid; /* peer call id */ + uint16_t recvWin; /* peer recv window size */ + uint16_t peerPpd; /* peer packet processing delay + (in 1/10 of a second) */ +}; +.Ed +.Pp +The +.Va enabled +field enables traffic flow through the node. +The +.Va enableDelayedAck +field enables delayed acknowledgement (maximum 250 milliseconds), which +is a useful optimization and should generally be turned on. +.Va enableAlwaysAck +field enables sending acknowledgements with every data packet, which +is probably helpful as well. +.Pp +.Va enableWindowing +enables the PPTP packet windowing mechanism specified by the protocol. +Disabling this will cause the node to violate the protocol, possibly +confusing other PPTP peers, but often results in better performance. +The windowing mechanism is a design error in the PPTP protocol; +L2TP, the successor to PPTP, removes it. +.Pp +The remaining fields are as supplied by the PPTP virtual call setup process. +.It Dv NGM_PPTPGRE_GET_CONFIG Pq Ic getconfig +Takes two byte argument as cid and returns the current configuration as a +.Vt "struct ng_pptpgre_conf" . +.It Dv NGM_PPTPGRE_GET_STATS Pq Ic getstats +This command returns a +.Vt "struct ng_pptpgre_stats" +containing various node statistics. +.It Dv NGM_PPTPGRE_CLR_STATS Pq Ic clrstats +This command resets the node statistics. +.It Dv NGM_PPTPGRE_GETCLR_STATS Pq Ic getclrstats +This command atomically gets and resets the node statistics, returning a +.Vt "struct ng_pptpgre_stats" . +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when both hooks have been disconnected. +.Sh SYSCTL VARIABLES +A set of +.Xr sysctl 8 +variables controls ability of this node to deal with some +amount of packet reorder that sometimes happens in transit. +Packet reorder results in packet drops (unless the order is restored) +as PPP protocol can not deliver reordered data. +These variables are shown below together +with their default value and meaning: +.Bl -tag -width indent +.It Va net.graph.pptpgre.reorder_max: 1 +Defines maximum length of node's private reorder queue +used to keep data waiting for late packets. +Zero value disables reordering. +Default value allows the node to restore the order for two packets swapped +in transit. +Greater values allow the node to deliver packets being late after more +packets in sequence at cost of increased kernel memory usage. +.It Va net.graph.pptpgre.reorder_timeout: 1 +Defines time value in milliseconds used to wait for late packets. +.El +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ng_ksocket 4 , +.Xr ng_ppp 4 , +.Xr ngctl 8 , +.Xr sysctl 8 +.Rs +.%A K. Hamzeh +.%A G. Pall +.%A W. Verthein +.%A J. Taarud +.%A W. Little +.%A G. Zorn +.%T "Point-to-Point Tunneling Protocol (PPTP)" +.%O RFC 2637 +.Re +.Rs +.%A S. Hanks +.%A T. \&Li +.%A D. Farinacci +.%A P. Traina +.%T "Generic Routing Encapsulation over IPv4 networks" +.%O RFC 1702 +.Re +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 4.0 . +.Sh AUTHORS +.An Archie Cobbs Aq Mt archie@FreeBSD.org +.Sh BUGS +The node should not expect incoming GRE packets to have an IP header. +This behavior is inherited from the (converse) behavior of raw IP sockets. +An intermediate node that strips IP headers in one direction +should be used instead. diff --git a/static/freebsd/man4/ng_pred1.4 b/static/freebsd/man4/ng_pred1.4 new file mode 100644 index 00000000..98634aea --- /dev/null +++ b/static/freebsd/man4/ng_pred1.4 @@ -0,0 +1,144 @@ +.\" +.\" Copyright (c) 2006, Alexander Motin +.\" 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 unmodified, 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 December 24, 2006 +.Dt NG_PRED1 4 +.Os +.Sh NAME +.Nm ng_pred1 +.Nd Predictor-1 PPP compression (RFC 1978) netgraph node type +.Sh SYNOPSIS +.In sys/types.h +.In netgraph/ng_pred1.h +.Sh DESCRIPTION +The +.Nm pred1 +node type implements the Predictor-1 sub-protocols of the Compression Control +Protocol (CCP). +.Pp +The node has two hooks, +.Va comp +for compression and +.Va decomp +for decompression. +Only one of them can be connected at the same time, specifying node's +operation mode. +Typically that hooks would be connected to the +.Xr ng_ppp 4 +node type hook of the same name. +.Sh HOOKS +This node type supports the following hooks: +.Pp +.Bl -tag -compact -width ".Va decomp" +.It Va comp +Connection to +.Xr ng_ppp 4 +.Va compress +hook. +Incoming frames are compressed and sent back out the same hook. +.It Va decomp +Connection to +.Xr ng_ppp 4 +.Va decompress +hook. +Incoming frames are decompressed and sent back out the same hook. +.El +.Pp +Only one hook can be connected at the same time, +specifying node's operation mode. +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_PRED1_CONFIG Pq Ic config +This command resets and configures the node for a session +(i.e., for compression or decompression). +This command takes a +.Vt "struct ng_pred1_config" +as an argument: +.Bd -literal -offset 0n +struct ng_pred1_config { + u_char enable; /* node enabled */ +}; +.Ed +The +.Ft enable +field enables traffic flow through the node. +.It Dv NGM_PRED1_RESETREQ Pq Ic resetreq +This message contains no arguments, and is bi-directional. +If an error is detected during decompression, this message is sent by the +node to the originator of the +.Dv NGM_PRED1_CONFIG +message that initiated the session. +The receiver should respond by sending a PPP CCP Reset-Request to the peer. +.Pp +This message may also be received by this node type when a CCP Reset-Request +or Reset-Ack is received by the local PPP entity. +The node will respond by flushing its compression state so the sides +can resynchronize. +.It Dv NGM_PRED1_GET_STATS Pq Ic getstats +This control message obtains statistics for a given hook. +The statistics are returned in +.Vt "struct ng_pred1_stats" : +.Bd -literal +struct ng_pred1_stats { + uint64_t FramesPlain; + uint64_t FramesComp; + uint64_t FramesUncomp; + uint64_t InOctets; + uint64_t OutOctets; + uint64_t Errors; +}; +.Ed +.It Dv NGM_PRED1_CLR_STATS Pq Ic clrstats +This control message clears statistics for a given hook. +.It Dv NGM_PRED1_GETCLR_STATS Pq Ic getclrstats +This control message obtains and clears statistics for a given hook. +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when hook have been disconnected. +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ng_ppp 4 , +.Xr ngctl 8 +.Rs +.%A D. Rand +.%T "PPP Predictor Compression Protocol" +.%O RFC 1978 +.Re +.Rs +.%A W. Simpson +.%T "The Point-to-Point Protocol (PPP)" +.%O RFC 1661 +.Re +.Sh AUTHORS +.An Alexander Motin Aq Mt mav@alkar.net +.Sh BUGS +Due to nature of netgraph PPP implementation there are possible race conditions +between data packet and ResetAck CCP packet in case of packet loss. +As result, +packet loss can produce bigger performance degradation than supposed by protocol. diff --git a/static/freebsd/man4/ng_rfc1490.4 b/static/freebsd/man4/ng_rfc1490.4 new file mode 100644 index 00000000..11660423 --- /dev/null +++ b/static/freebsd/man4/ng_rfc1490.4 @@ -0,0 +1,139 @@ +.\" Copyright (c) 1996-1999 Whistle Communications, Inc. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, use and +.\" redistribution of this software, in source or object code forms, with or +.\" without modifications are expressly permitted by Whistle Communications; +.\" provided, however, that: +.\" 1. Any and all reproductions of the source or object code must include the +.\" copyright notice above and the following disclaimer of warranties; and +.\" 2. No rights are granted, in any manner or form, to use Whistle +.\" Communications, Inc. trademarks, including the mark "WHISTLE +.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as +.\" such appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, +.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. +.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY +.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS +.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. +.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES +.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING +.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY +.\" OF SUCH DAMAGE. +.\" +.\" Author: Archie Cobbs +.\" $Whistle: ng_rfc1490.8,v 1.4 1999/01/25 23:46:27 archie Exp $ +.\" +.Dd January 19, 1999 +.Dt NG_RFC1490 4 +.Os +.Sh NAME +.Nm ng_rfc1490 +.Nd RFC 1490 netgraph node type +.Sh SYNOPSIS +.In netgraph/ng_rfc1490.h +.Sh DESCRIPTION +The +.Nm rfc1490 +node type performs protocol encapsulation, de-encapsulation, and +multiplexing according to RFC 1490 (which has since been updated by RFC 2427). +This particular type of encapsulation is often used on top of frame relay +DLCI channels. +.Pp +The +.Dv downstream +hook is used to transmit and receive encapsulated frames. +On the other side of the node, the +.Dv inet +and +.Dv ppp +hooks are used to transmit and receive raw IP frames and PPP frames, +respectively. +PPP frames are transmitted and received according to +RFC 1973; in particular, frames appearing on the +.Dv ppp +hook begin with the PPP protocol number. +The +.Dv ethernet +hook can be used to transmit and receive Ethernet frames (without a +checksum) in RFC 1490's bridging format. +.Pp +Typically the +.Dv inet +hook is connected to the +.Dv inet +hook of an +.Xr ng_iface 4 +node. +.Sh HOOKS +This node type supports the following hooks: +.Bl -tag -width ".Va downstream" +.It Va downstream +Connects to the RFC 1490 peer entity. +.It Va ethernet +Transmits and receives bridged raw Ethernet frames, without a checksum. +.It Va inet +Transmits and receives raw IP frames. +.It Va ppp +Transmits and receives PPP frames. +.El +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_RFC1490_SET_ENCAP Pq Ic setencap +This command sets encapsulation method for the node. +The desired method must be passed as a string message argument, +and must be one of the following supported encapsulation modes: +.Bl -tag -width ".Qq Li ietf-snap" +.It Qq Li ietf-ip +IP packets are sent using simple RFC1490/2427 encapsulation. +.It Qq Li ietf-snap +IP packets are sent inside SNAP frames. +Also conforms to RFC1490/2427. +.It Qq Li cisco +IP packets are sent and received using proprietary Cisco encapsulation +method. +.El +.It Dv NGM_RFC1490_GET_ENCAP Pq Ic getencap +This command returns current encapsulation method on the node. +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ng_frame_relay 4 , +.Xr ng_iface 4 , +.Xr ngctl 8 +.Rs +.%A C. Brown +.%A A. Malis +.%T "Multiprotocol Interconnect over Frame Relay" +.%O RFC 2427 +.Re +.Rs +.%A W. Simpson +.%T "PPP in Frame Relay" +.%O RFC 1973 +.Re +.Pp +.Pa http://www.cisco.com/warp/public/121/frf8modes.pdf +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 4.0 . +.Sh AUTHORS +.An Julian Elischer Aq Mt julian@FreeBSD.org +.Sh BUGS +Not all of RFC 1490 is implemented. diff --git a/static/freebsd/man4/ng_socket.4 b/static/freebsd/man4/ng_socket.4 new file mode 100644 index 00000000..b892498d --- /dev/null +++ b/static/freebsd/man4/ng_socket.4 @@ -0,0 +1,188 @@ +.\" Copyright (c) 1996-1999 Whistle Communications, Inc. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, use and +.\" redistribution of this software, in source or object code forms, with or +.\" without modifications are expressly permitted by Whistle Communications; +.\" provided, however, that: +.\" 1. Any and all reproductions of the source or object code must include the +.\" copyright notice above and the following disclaimer of warranties; and +.\" 2. No rights are granted, in any manner or form, to use Whistle +.\" Communications, Inc. trademarks, including the mark "WHISTLE +.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as +.\" such appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, +.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. +.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY +.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS +.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. +.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES +.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING +.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY +.\" OF SUCH DAMAGE. +.\" +.\" Author: Archie Cobbs +.\" $Whistle: ng_socket.8,v 1.5 1999/01/25 23:46:27 archie Exp $ +.\" +.Dd January 19, 1999 +.Dt NG_SOCKET 4 +.Os +.Sh NAME +.Nm ng_socket +.Nd netgraph socket node type +.Sh SYNOPSIS +.In sys/types.h +.In netgraph/ng_socket.h +.Sh DESCRIPTION +A +.Nm socket +node is both a +.Bx +socket and a netgraph node. +The +.Nm +node type allows user-mode processes to participate in the kernel +.Xr netgraph 4 +networking subsystem using the +.Bx +socket interface. +The process must have +root privileges to be able to create netgraph sockets however once created, +any process that has one may use it. +.Pp +A new +.Nm +node is created by creating a new socket of type +.Dv NG_CONTROL +in the protocol family +.Dv PF_NETGRAPH , +using the +.Xr socket 2 +system call. +Any control messages received by the node +and not having a cookie value of +.Dv NGM_SOCKET_COOKIE +are received by the process, using +.Xr recvfrom 2 ; +the socket address argument is a +.Dv "struct sockaddr_ng" +containing the sender's netgraph address. +Conversely, control messages can be sent to any node by calling +.Xr sendto 2 , +supplying the recipient's address in a +.Dv "struct sockaddr_ng" . +The +.Xr bind 2 +system call may be used to assign a global netgraph name to the node. +.Pp +To transmit and receive netgraph data packets, a +.Dv NG_DATA +socket must also be created using +.Xr socket 2 +and associated with a +.Nm +node. +.Dv NG_DATA +sockets do not automatically +have nodes associated with them; they are bound to a specific node via the +.Xr connect 2 +system call. +The address argument is the netgraph address of the +.Nm +node already created. +Once a data socket is associated with a node, +any data packets received by the node are read using +.Xr recvfrom 2 +and any packets to be sent out from the node are written using +.Xr sendto 2 . +In the case of data sockets, the +.Dv "struct sockaddr_ng" +contains the name of the +.Em hook +on which the data was received or should be sent. +.Pp +As a special case, to allow netgraph data sockets to be used as stdin or stdout +on naive programs, a +.Xr sendto 2 +with a NULL sockaddr pointer, a +.Xr send 2 +or a +.Xr write 2 +will succeed in the case where there is exactly ONE hook attached to +the socket node, (and thus the path is unambiguous). +.Pp +There is a user library that simplifies using netgraph sockets; see +.Xr netgraph 3 . +.Sh HOOKS +This node type supports hooks with arbitrary names (as long as +they are unique) and always accepts hook connection requests. +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_SOCK_CMD_NOLINGER +When the last hook is removed from this node, it will shut down as +if it had received a +.Dv NGM_SHUTDOWN +message. +Attempts to access the sockets associated will return +.Er ENOTCONN . +.It Dv NGM_SOCK_CMD_LINGER +This is the default mode. +When the last hook is removed, the node will +continue to exist, ready to accept new hooks until it +is explicitly shut down. +.El +.Pp +All other messages +with neither the +.Dv NGM_SOCKET_COOKIE +or +.Dv NGM_GENERIC_COOKIE +will be passed unaltered up the +.Dv NG_CONTROL +socket. +.Sh SHUTDOWN +This node type shuts down and disappears when both the associated +.Dv NG_CONTROL +and +.Dv NG_DATA +sockets have been closed, or a +.Dv NGM_SHUTDOWN +control message is received. +In the latter case, attempts to write +to the still-open sockets will return +.Er ENOTCONN . +If the +.Dv NGM_SOCK_CMD_NOLINGER +message has been received, closure of the last hook will also initiate +a shutdown of the node. +.Sh SEE ALSO +.Xr socket 2 , +.Xr netgraph 3 , +.Xr netgraph 4 , +.Xr ng_ksocket 4 , +.Xr ngctl 8 +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 4.0 . +.Sh AUTHORS +.An Julian Elischer Aq Mt julian@FreeBSD.org +.Sh BUGS +It is not possible to reject the connection of a hook, though any +data received on that hook can certainly be ignored. +.Pp +The controlling process is not notified of all events that an in-kernel node +would be notified of, e.g.\& a new hook, or hook removal. +Some node-initiated messages should be defined for this purpose (to be +sent up the control socket). diff --git a/static/freebsd/man4/ng_source.4 b/static/freebsd/man4/ng_source.4 new file mode 100644 index 00000000..38bf2d35 --- /dev/null +++ b/static/freebsd/man4/ng_source.4 @@ -0,0 +1,355 @@ +.\" Copyright 2002-2007 Sandvine Inc. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, use and +.\" redistribution of this software, in source or object code forms, with or +.\" without modifications are expressly permitted by Sandvine Inc.; provided, +.\" however, that: +.\" 1. Any and all reproductions of the source or object code must include the +.\" copyright notice above and the following disclaimer of warranties; and +.\" 2. No rights are granted, in any manner or form, to use Sandvine Inc. +.\" trademarks, including the mark "SANDVINE" on advertising, endorsements, +.\" or otherwise except as such appears in the above copyright notice or in +.\" the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY SANDVINE "AS IS", AND TO THE MAXIMUM +.\" EXTENT PERMITTED BY LAW, SANDVINE MAKES NO REPRESENTATIONS OR WARRANTIES, +.\" EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, +.\" ANY AND ALL IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR +.\" PURPOSE, OR NON-INFRINGEMENT. SANDVINE DOES NOT WARRANT, GUARANTEE, OR +.\" MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE +.\" USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY +.\" OR OTHERWISE. IN NO EVENT SHALL SANDVINE BE LIABLE FOR ANY DAMAGES +.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING +.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 SANDVINE IS ADVISED OF THE POSSIBILITY OF SUCH +.\" DAMAGE. +.\" +.\" Author: Dave Chapeskie +.\" +.Dd January 18, 2021 +.Dt NG_SOURCE 4 +.Os +.Sh NAME +.Nm ng_source +.Nd netgraph node for traffic generation +.Sh SYNOPSIS +.In sys/types.h +.In netgraph/ng_source.h +.Sh DESCRIPTION +The +.Nm source +node acts as a source of packets according to the parameters set up +using control messages and input packets. +The +.Nm +node type is used primarily for testing and benchmarking. +.Sh HOOKS +The +.Nm source +node has two hooks: +.Va input +and +.Va output . +The +.Va output +hook must remain connected, its disconnection will shutdown the node. +.Sh OPERATION +The operation of the node is as follows. +Packets received on the +.Va input +hook are queued internally. +When +.Va output +hook is connected, +.Nm +node assumes that its neighbour node is of +.Xr ng_ether 4 +node type. +The neighbour is queried for its interface name. +The +.Nm +node then uses queue of the interface for its evil purposes. +The +.Nm +node also disables +.Va autosrc +option on neighbour +.Xr ng_ether 4 +node. +If interface name cannot be obtained automatically, it should +be configured explicitly with the +.Dv NGM_SOURCE_SETIFACE +control message, and +.Va autosrc +should be turned off on +.Xr ng_ether 4 +node manually. +.Pp +If the node is connected to a netgraph network, which does not +terminate in a real +.Xr ng_ether 4 +interface, limit the packet injection rate explicitly with the +.Va NGM_SOURCE_SETPPS +control message. +.Pp +Upon receipt of a +.Dv NGM_SOURCE_START +control message the node starts sending +the previously queued packets out the +.Va output +hook on every clock tick as fast +as the connected interface will take them. +While active, on every clock tick the node checks the available space +in the interface queue and sends that many packets out its +.Va output +hook. +Once the number of packets indicated in the start message has been +sent, or upon receipt of a +.Dv NGM_SOURCE_STOP +message, the node stops sending data. +.Sh CONTROL MESSAGES +This node type supports the generic control messages as well as the following, +which must be sent with the +.Dv NGM_SOURCE_COOKIE +attached. +.Bl -tag -width foo +.It Dv NGM_SOURCE_GET_STATS Pq Ic getstats +Returns a structure containing the following fields: +.Bl -tag -width ".Va elapsedTime" +.It Va outOctets +The number of octets/bytes sent out the +.Va output +hook. +.It Va outFrames +The number of frames/packets sent out the +.Va output +hook. +.It Va queueOctets +The number of octets queued from the +.Va input +hook. +.It Va queueFrames +The number of frames queued from the +.Va input +hook. +.It Va startTime +The time the last start message was received. +.It Va endTime +The time the last end message was received or +the output packet count was reached. +.It Va elapsedTime +Either +.Va endTime Li \- Va startTime +or current time +\- +.Va startTime . +.El +.It Dv NGM_SOURCE_CLR_STATS Pq Ic clrstats +Clears and resets the statistics returned by +.Ic getstats +(except +.Va queueOctets +and +.Va queueFrames ) . +.It Dv NGM_SOURCE_GETCLR_STATS Pq Ic getclrstats +As +.Ic getstats +but clears the statistics at the same time. +.It Dv NGM_SOURCE_START Pq Ic start +This message requires a single +.Vt uint64_t +parameter which is the number of packets to +send before stopping. +Node starts sending the queued packets out the +.Va output +hook. +The +.Va output +hook must be connected and node must have +interface configured. +.It Dv NGM_SOURCE_STOP Pq Ic stop +Stops the node if it is active. +.It Dv NGM_SOURCE_CLR_DATA Pq Ic clrdata +Clears the packets queued from the +.Va input +hook. +.It Dv NGM_SOURCE_SETIFACE Pq Ic setiface +This message requires the name of the interface +to be configured as an argument. +.It Dv NGM_SOURCE_SETPPS Pq Ic setpps +This message requires a single +.Vt uint32_t +parameter which puts upper limit on the amount of packets +sent per second. +.It Dv NGM_SOURCE_SET_TIMESTAMP Pq Ic settimestamp +This message specifies that a timestamp (in the format of a +.Vt "struct timeval" ) +should be inserted in the transmitted packets. +This message requires a structure containing the following fields: +.Bl -tag -width ".Va offset" +.It Va offset +The offset from the beginning of the packet at which the timestamp is to be +inserted. +.It Va flags +Set to 1 to enable the timestamp. +.El +.It Dv NGM_SOURCE_GET_TIMESTAMP Pq Ic gettimestamp +Returns the current timestamp settings in the form of the structure described +above. +.It Dv NGM_SOURCE_SET_COUNTER Pq Ic setcounter +This message specifies that a counter should be embedded in transmitted +packets. +Up to four counters may be independently configured. +This message requires a structure containing the following fields: +.Bl -tag -width ".Va increment" +.It Va offset +The offset from the beginning of the packet at which the counter is to be +inserted. +.It Va flags +Set to 1 to enable the counter. +.It Va width +The byte width of the counter. +It may be 1, 2, or 4. +.It Va next_val +The value for the next insertion of the counter. +.It Va min_val +The minimum value to be used by the counter. +.It Va max_val +The maximum value to be used by the counter. +.It Va increment +The value to be added to the counter after each insertion. +It may be negative. +.It Va index +The counter to be configured, from 0 to 3. +.El +.It Dv NGM_SOURCE_GET_COUNTER Pq Ic getcounter +This message requires a single +.Vt uint8_t +parameter which specifies the counter to query. +Returns the current counter settings in the form of the structure described +above. +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, when all hooks have been disconnected, or when the +.Va output +hook has been disconnected. +.Sh EXAMPLES +Attach the node to an +.Xr ng_ether 4 +node for an interface. +If +.Nm ng_ether +is +not already loaded you will need to do so. +For example, these commands +load the +.Nm ng_ether +module and attach the +.Va output +hook of a new +.Nm source +node to +.Va orphans +hook of the +.Li bge0: +.Nm ng_ether +node. +.Bd -literal -offset indent +kldload ng_ether +ngctl mkpeer bge0: source orphans output +.Ed +.Pp +At this point the new node can be referred to as +.Dq Li bge0:orphans . +The +node can be given its own name like this: +.Pp +.Dl "ngctl name bge0:orphans src0" +.Pp +After which it can be referred to as +.Dq Li src0: . +.Pp +Once created, packets can be sent to the node as raw binary data. +Each packet must be delivered in a separate netgraph message. +.Pp +The following example uses a short Perl script to convert the hex +representation of an ICMP packet to binary and deliver it to the +.Nm source +node's +.Va input +hook via +.Xr nghook 8 : +.Bd -literal -offset indent +perl -pe 's/(..)[ \et\en]*/chr(hex($1))/ge' < +.\" +.Dd February 19, 2001 +.Dt NG_SPLIT 4 +.Os +.Sh NAME +.Nm ng_split +.Nd netgraph node to separate incoming and outgoing flows +.Sh SYNOPSIS +.In netgraph/ng_split.h +.Sh DESCRIPTION +The +.Nm split +node type is used to split a bidirectional stream of packets into +two separate unidirectional streams of packets. +.Sh HOOKS +This node type supports the following three hooks: +.Bl -tag -width ".Va mixed" +.It Va in +Packets received on +.Em in +are forwarded to +.Em mixed . +.It Va out +Packets received on +.Em out +will be discarded as illegal. +.It Va mixed +Packets received on +.Em mixed +are forwarded to +.Em out . +.El +.Sh CONTROL MESSAGES +This node type supports only the generic control messages. +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ngctl 8 +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 3.5 +but incorporated into +.Fx +in +.Fx 5.0 . +.Sh AUTHORS +.An Julian Elischer Aq Mt julian@FreeBSD.org +.An Vitaly V. Belekhov Aq Mt vitaly@riss-telecom.ru diff --git a/static/freebsd/man4/ng_tag.4 b/static/freebsd/man4/ng_tag.4 new file mode 100644 index 00000000..58e736c1 --- /dev/null +++ b/static/freebsd/man4/ng_tag.4 @@ -0,0 +1,328 @@ +.\" Copyright (c) 2006 Vadim Goncharov +.\" 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 June 10, 2006 +.Dt NG_TAG 4 +.Os +.Sh NAME +.Nm ng_tag +.Nd "mbuf tags manipulating netgraph node type" +.Sh SYNOPSIS +.In netgraph/ng_tag.h +.Sh DESCRIPTION +The +.Nm tag +node type allows mbuf packet tags (see +.Xr mbuf_tags 9 ) +to be examined, stripped or applied to data travelling through a +Netgraph network. +Mbuf tags are used in many parts of the +.Fx +kernel network subsystem, +including the storage of VLAN tags as described in +.Xr vlan 4 , +Mandatory Access Control (MAC) labels as described in +.Xr mac 9 , +IPsec policy information as described in +.Xr ipsec 4 , +and packet filter tags used by +.Xr pf 4 . +One should also consider useful setting or checking +.Xr ipfw 8 +tags, which are implemented as mbuf tags, too. +.Pp +Each node allows an arbitrary number of connections to arbitrarily +named hooks. +With each hook is associated a tag which will be searched in the list +of all tags attached to a packet incoming to this hook, a destination hook +for matching packets, a destination hook for non-matching packets, +a tag which will be appended to data leaving node through this hook, +and various statistics counters. +.Pp +The list of incoming packet's tags is traversed to find a tag with +specified +.Va type +and +.Va cookie +values. +Upon match, if specified +.Va tag_len +is non-zero, +.Va tag_data +of tag is checked to be identical to that specified in the hook structure. +Packets with matched tags are forwarded to +.Dq match +destination hook, or forwarded to +.Dq non-match +hook otherwise. +Either or both destination hooks can be an empty string, or may +not exist, in which case the packet is dropped. +.Pp +Tag list of packets leaving the node is extended with a new tag +specified in outgoing hook structure (it is possible to avoid appending +a new tag to pass packet completely unchanged by specifying zero +.Va type +and +.Va cookie +values in the structure of the corresponding outgoing hook). +Additionally, +a tag can be stripped from incoming packet after match if +.Va strip +flag is set. +This can be used for simple tag removal or tag replacement, if combined +with tag addition on outgoing matching hook. +Note that new tag is appended unconditionally, without checking if +such a tag is already present in the list (it is up to user to check +if this is a concern). +.Pp +New hooks are initially configured to drop all incoming packets +(as all hook names are empty strings; zero values can be specified +to forward all packets to non-matching hook), +and to forward all outgoing packets without any tag appending. +.Pp +Data payload of packets passing through the node is completely +unchanged, all operations can affect tag list only. +.Sh HOOKS +This node type supports any number of hooks having arbitrary names. +In order to allow internal optimizations, user should never try to +configure a hook with a structure pointing to hooks which do not exist yet. +The safe way is to create all hooks first, then begin to configure them. +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_TAG_SET_HOOKIN Pq Ic sethookin +This command sets tag values which will be searched in the tag list of +incoming packets on a hook. +The following structure must be supplied as an argument: +.Bd -literal -offset 4n +struct ng_tag_hookin { + char thisHook[NG_HOOKSIZ]; /* name of hook */ + char ifMatch[NG_HOOKSIZ]; /* match dest hook */ + char ifNotMatch[NG_HOOKSIZ]; /* !match dest hook */ + uint8_t strip; /* strip tag if found */ + uint32_t tag_cookie; /* ABI/Module ID */ + uint16_t tag_id; /* tag ID */ + uint16_t tag_len; /* length of data */ + uint8_t tag_data[0]; /* tag data */ +}; +.Ed +.Pp +The hook to be updated is specified in +.Va thisHook . +Data bytes of tag corresponding to specified +.Va tag_id +(type) and +.Va tag_cookie +are placed in the +.Va tag_data +array; there must be +.Va tag_len +of them. +Matching and non-matching incoming packets are delivered out the hooks named +.Va ifMatch +and +.Va ifNotMatch , +respectively. +If +.Va strip +flag is non-zero, then found tag is deleted from list of packet tags. +.It Dv NGM_TAG_GET_HOOKIN Pq Ic gethookin +This command takes an ASCII string argument, the hook name, and returns the +corresponding +.Vt "struct ng_tag_hookin" +as shown above. +.It Dv NGM_TAG_SET_HOOKOUT Pq Ic sethookout +This command sets tags values which will be applied to outgoing +packets. +The following structure must be supplied as an argument: +.Bd -literal -offset 4n +struct ng_tag_hookout { + char thisHook[NG_HOOKSIZ]; /* name of hook */ + uint32_t tag_cookie; /* ABI/Module ID */ + uint16_t tag_id; /* tag ID */ + uint16_t tag_len; /* length of data */ + uint8_t tag_data[0]; /* tag data */ +}; +.Ed +.Pp +The hook to be updated is specified in +.Va thisHook . +Other variables mean basically the same as in +.Vt "struct ng_tag_hookin" +shown above, except used for setting values in a new tag. +.It Dv NGM_TAG_GET_HOOKOUT Pq Ic gethookout +This command takes an ASCII string argument, the hook name, and returns the +corresponding +.Vt "struct ng_tag_hookout" +as shown above. +.It Dv NGM_TAG_GET_STATS Pq Ic getstats +This command takes an ASCII string argument, the hook name, and returns the +statistics associated with the hook as a +.Vt "struct ng_tag_hookstat" . +.It Dv NGM_TAG_CLR_STATS Pq Ic clrstats +This command takes an ASCII string argument, the hook name, and clears the +statistics associated with the hook. +.It Dv NGM_TAG_GETCLR_STATS Pq Ic getclrstats +This command is identical to +.Dv NGM_TAG_GET_STATS , +except that the statistics are also atomically cleared. +.El +.Pp +.Em Note : +statistics counters as well as three statistics messages above work +only if code was compiled with the +.Dv NG_TAG_DEBUG +option. +The reason for this is that statistics is rarely used in practice, +but still consumes CPU cycles for every packet. +Moreover, it is even not accurate on SMP systems due to lack of +synchronization between threads, as this is very expensive. +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +.Sh EXAMPLES +It is possible to do a simple L7 filtering by using +.Xr ipfw 8 +tags in conjunction with +.Xr ng_bpf 4 +traffic analyzer. +Example below explains how to filter DirectConnect P2P network data traffic, +which cannot be done by usual means as it uses random ports. +It is known that such data connection always contains a TCP packet with +6-byte payload string "$Send|". +So ipfw's +.Cm netgraph +action will be used to divert all TCP packets to an +.Xr ng_bpf 4 +node which will check for the specified string and return non-matching +packets to +.Xr ipfw 8 . +Matching packets are passed to +.Nm +node, which will set a tag and pass them back to +.Xr ng_bpf 4 +node on a hook programmed to accept all packets and pass them back to +.Xr ipfw 8 . +A script provided in +.Xr ng_bpf 4 +manual page will be used for programming node. +Note that packets diverted from +.Xr ipfw 8 +to Netgraph have no link-level header, so offsets in +.Xr tcpdump 1 +expressions must be altered accordingly. +Thus, there will be expression +.Dq Li "ether[40:2]=0x244c && ether[42:4]=0x6f636b20" +on incoming hook and empty expression to match all packets from +.Nm . +.Pp +So, this is +.Xr ngctl 8 +script for nodes creating and naming for easier access: +.Bd -literal -offset 4n +/usr/sbin/ngctl -f- <<-SEQ + mkpeer ipfw: bpf 41 ipfw + name ipfw:41 dcbpf + mkpeer dcbpf: tag matched th1 + name dcbpf:matched ngdc +SEQ +.Ed +.Pp +Now +.Dq Li ngdc +node (which is of type +.Nm ) +must be programmed to echo all packets received on the +.Dq Li th1 +hook back, with the +.Xr ipfw 8 +tag 412 attached. +.Dv MTAG_IPFW +value for +.Va tag_cookie +was taken from file +.In netinet/ip_fw.h +and value for +.Va tag_id +is tag number (412), with zero tag length: +.Bd -literal -offset 4n +ngctl msg ngdc: sethookin { thisHook=\e"th1\e" ifNotMatch=\e"th1\e" } +ngctl msg ngdc: sethookout { thisHook=\e"th1\e" \e + tag_cookie=1148380143 \e + tag_id=412 } +.Ed +.Pp +Do not forget to program +.Xr ng_bpf 4 +.Dq Li ipfw +hook with the above expression (see +.Xr ng_bpf 4 +for script doing this) and +.Dq Li matched +hook with an empty expression: +.Bd -literal -offset 4n +ngctl msg dcbpf: setprogram { thisHook=\e"matched\e" ifMatch=\e"ipfw\e" \e + bpf_prog_len=1 bpf_prog=[ { code=6 k=8192 } ] } +.Ed +.Pp +After finishing with +.Xr netgraph 4 +nodes, +.Xr ipfw 8 +rules must be added to enable packet flow: +.Bd -literal -offset 4n +ipfw add 100 netgraph 41 tcp from any to any iplen 46 +ipfw add 110 reset tcp from any to any tagged 412 +.Ed +.Pp +Note: one should ensure that packets are returned to ipfw after processing +inside +.Xr netgraph 4 , +by setting appropriate +.Xr sysctl 8 +variable: +.Bd -literal -offset 4n +sysctl net.inet.ip.fw.one_pass=0 +.Ed +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ng_bpf 4 , +.Xr ng_ipfw 4 , +.Xr ipfw 8 , +.Xr ngctl 8 , +.Xr mbuf_tags 9 +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 6.2 . +.Sh AUTHORS +.An Vadim Goncharov Aq Mt vadimnuclight@tpu.ru +.Sh BUGS +For manipulating any tags with data payload (that is, all tags with non-zero +.Va tag_len ) +one should care about non-portable machine-dependent representation of +tags on the low level as byte stream. +Perhaps this should be done by another program rather than manually. diff --git a/static/freebsd/man4/ng_tcpmss.4 b/static/freebsd/man4/ng_tcpmss.4 new file mode 100644 index 00000000..f2fc5038 --- /dev/null +++ b/static/freebsd/man4/ng_tcpmss.4 @@ -0,0 +1,123 @@ +.\" Copyright (c) 2005 Gleb Smirnoff +.\" 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 June 9, 2005 +.Dt NG_TCPMSS 4 +.Os +.Sh NAME +.Nm ng_tcpmss +.Nd "netgraph node to adjust TCP MSS option" +.Sh SYNOPSIS +.In netgraph.h +.In netgraph/ng_tcpmss.h +.Sh DESCRIPTION +The +.Nm tcpmss +node type is designed to alter the Maximum Segment Size option +of TCP packets. +This node accepts an arbitrary number of hooks. +Initially a new hook is considered unconfigured. +The +.Dv NG_TCPMSS_CONFIG +control message is used to configure a hook. +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following. +.Bl -tag -width foo +.It Dv NGM_TCPMSS_CONFIG Pq Ic config +This control message configures node to do given MSS adjusting on +a particular hook. +It requires the +.Vt "struct ng_tcpmss_config" +to be supplied as an argument: +.Bd -literal +struct ng_tcpmss_config { + char inHook[NG_HOOKSIZ]; + char outHook[NG_HOOKSIZ]; + uint16_t maxMSS; +} +.Ed +.Pp +This means: packets received on +.Va inHook +would be checked for TCP MSS option and the latter would be +reduced down to +.Va maxMSS +if it exceeds +.Va maxMSS . +After that, packets would be sent to hook +.Va outHook . +.It Dv NGM_TCPMSS_GET_STATS Pq Ic getstats +This control message obtains statistics for a given hook. +The statistics are returned in +.Vt "struct ng_tcpmss_hookstat" : +.Bd -literal +struct ng_tcpmss_hookstat { + uint64_t Octets; /* total bytes */ + uint64_t Packets; /* total packets */ + uint16_t maxMSS; /* maximum MSS */ + uint64_t SYNPkts; /* TCP SYN packets */ + uint64_t FixedPkts; /* changed packets */ +}; +.Ed +.It Dv NGM_TCPMSS_CLR_STATS Pq Ic clrstats +This control message clears statistics for a given hook. +.It Dv NGM_TCPMSS_GETCLR_STATS Pq Ic getclrstats +This control message obtains and clears statistics for a given hook. +.El +.Sh EXAMPLES +In the following example, packets are injected into the +.Nm tcpmss +node using the +.Xr ng_ipfw 4 +node. +.Bd -literal -offset indent +# Create tcpmss node and connect it to ng_ipfw node +ngctl mkpeer ipfw: tcpmss 100 qqq + +# Adjust MSS to 1452 +ngctl msg ipfw:100 config '{ inHook="qqq" outHook="qqq" maxMSS=1452 }' + +# Divert traffic into tcpmss node +ipfw add 300 netgraph 100 tcp from any to any tcpflags syn out via fxp0 + +# Let packets continue with ipfw after being hacked +sysctl net.inet.ip.fw.one_pass=0 +.Ed +.Sh SHUTDOWN +This node shuts down upon receipt of an +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ng_ipfw 4 +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 6.0 . +.Sh AUTHORS +.An Alexey Popov Aq Mt lollypop@flexuser.ru +.An Gleb Smirnoff Aq Mt glebius@FreeBSD.org +.Sh BUGS +When running on SMP, system statistics may be broken. diff --git a/static/freebsd/man4/ng_tee.4 b/static/freebsd/man4/ng_tee.4 new file mode 100644 index 00000000..5486201a --- /dev/null +++ b/static/freebsd/man4/ng_tee.4 @@ -0,0 +1,132 @@ +.\" Copyright (c) 1996-1999 Whistle Communications, Inc. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, use and +.\" redistribution of this software, in source or object code forms, with or +.\" without modifications are expressly permitted by Whistle Communications; +.\" provided, however, that: +.\" 1. Any and all reproductions of the source or object code must include the +.\" copyright notice above and the following disclaimer of warranties; and +.\" 2. No rights are granted, in any manner or form, to use Whistle +.\" Communications, Inc. trademarks, including the mark "WHISTLE +.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as +.\" such appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, +.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. +.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY +.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS +.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. +.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES +.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING +.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY +.\" OF SUCH DAMAGE. +.\" +.\" Author: Archie Cobbs +.\" $Whistle: ng_tee.8,v 1.4 1999/01/25 23:46:27 archie Exp $ +.\" +.Dd May 28, 2004 +.Dt NG_TEE 4 +.Os +.Sh NAME +.Nm ng_tee +.Nd netgraph ``tee'' node type +.Sh SYNOPSIS +.In sys/types.h +.In netgraph/ng_tee.h +.Sh DESCRIPTION +The +.Nm tee +node type has a purpose similar to the +.Xr tee 1 +command. +.Nm Tee +nodes are useful for debugging or +.Dq snooping +on a connection +between two netgraph nodes. +.Nm Tee +nodes have four hooks, +.Dv right , +.Dv left , +.Dv right2left , +and +.Dv left2right . +All data received on +.Dv right +is sent unmodified to +.Em both +hooks +.Dv left +and +.Dv right2left . +Similarly, all data received on +.Dv left +is sent unmodified to both +.Dv right +and +.Dv left2right . +.Pp +Packets may also be received on +.Dv right2left +and +.Dv left2right ; +if so, they are forwarded unchanged out hooks +.Dv right +and +.Dv left , +respectively. +.Sh HOOKS +This node type supports the following hooks: +.Bl -tag -width ".Va left2right" +.It Va right +The connection to the node on the right. +.It Va left +The connection to the node on the left. +.It Va right2left +Tap for right to left traffic. +.It Va left2right +Tap for left to right traffic. +.El +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following. +.Bl -tag -width foo +.It Dv NGM_TEE_GET_STATS Pq Ic getstats +Get statistics, returned as a +.Dv "struct ng_tee_stats" . +.It Dv NGM_TEE_CLR_STATS Pq Ic clrstats +Clear statistics. +.El +.Sh SHUTDOWN +This node shuts down upon receipt of an +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +If both +.Dv right +and +.Dv left +hooks are present, node removes itself from the chain gently, +connecting +.Dv right +and +.Dv left +together. +.Sh SEE ALSO +.Xr tee 1 , +.Xr netgraph 4 , +.Xr ngctl 8 +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 4.0 . +.Sh AUTHORS +.An Julian Elischer Aq Mt julian@FreeBSD.org diff --git a/static/freebsd/man4/ng_tty.4 b/static/freebsd/man4/ng_tty.4 new file mode 100644 index 00000000..85ab9843 --- /dev/null +++ b/static/freebsd/man4/ng_tty.4 @@ -0,0 +1,127 @@ +.\" Copyright (c) 1996-1999 Whistle Communications, Inc. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, use and +.\" redistribution of this software, in source or object code forms, with or +.\" without modifications are expressly permitted by Whistle Communications; +.\" provided, however, that: +.\" 1. Any and all reproductions of the source or object code must include the +.\" copyright notice above and the following disclaimer of warranties; and +.\" 2. No rights are granted, in any manner or form, to use Whistle +.\" Communications, Inc. trademarks, including the mark "WHISTLE +.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as +.\" such appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, +.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. +.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY +.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS +.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. +.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES +.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING +.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY +.\" OF SUCH DAMAGE. +.\" +.\" Author: Archie Cobbs +.\" $Whistle: ng_tty.8,v 1.5 1999/01/25 23:46:28 archie Exp $ +.\" +.Dd December 25, 2008 +.Dt NG_TTY 4 +.Os +.Sh NAME +.Nm ng_tty +.Nd netgraph node type that is also a TTY hook +.Sh SYNOPSIS +.In sys/types.h +.In sys/ttycom.h +.In netgraph/ng_tty.h +.Sh DESCRIPTION +The +.Nm tty +node type is both a netgraph node type and a TTY hook. +.Pp +The node has a single hook called +.Dv hook . +Incoming bytes received on the tty device are sent out on this hook, +and frames received on +.Dv hook +are transmitted out on the tty device. +No modification to the data is performed in either direction. +While the hook is installed on a tty, the normal read and write +operations are unavailable, returning +.Er EIO . +.Pp +Incoming data is delivered directly to ng_tty via the tty bypass hook as a +buffer pointer and length, this is converted to a mbuf and passed to the peer. +.Pp +The node supports an optional +.Dq hot character . +If the driver can not deliver data directly to the tty bypass hook then each +character is input one at a time. +If set to non-zero and bypass mode is unavailable, incoming +data from the tty device is queued until this character is seen. +This avoids sending lots of mbufs containing a small number of bytes, +but introduces potentially infinite latency. +The default hot character is 0x7e, consistent with +.Dv hook +being connected to a +.Xr ng_async 4 +type node. +The hot character has no effect on the transmission of data. +.Sh HOOKS +This node type supports the following hooks: +.Bl -tag -width ".Va hook" +.It Va hook +.Xr tty 4 +serial data contained in +.Dv mbuf +structures, with arbitrary inter-frame boundaries. +.El +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_TTY_SET_HOTCHAR +This command takes an integer argument and sets the hot character +from the lower 8 bits. +A hot character of zero disables queueing, +so that all received data is forwarded immediately. +.It Dv NGM_TTY_GET_HOTCHAR +Returns an integer containing the current hot character in the lower +eight bits. +.It Dv NGM_TTY_SET_TTY +This command takes integer process ID and file descriptor of open tty +and registers the tty hooks. +.El +.Sh SHUTDOWN +This node shuts down when the corresponding device is closed. +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr netgraph 4 , +.Xr ng_async 4 , +.Xr tty 4 , +.Xr ngctl 8 +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 4.0 . +.Sh AUTHORS +.An Archie Cobbs Aq Mt archie@FreeBSD.org +.An Andrew Thompson Aq Mt thompsa@FreeBSD.org +.Sh BUGS +The serial driver code also has a notion of a +.Dq hot character . +Unfortunately, this value is statically defined in terms of the +line discipline and cannot be changed. +Therefore, if a hot character other than 0x7e (the default) is set for the +.Nm +node, the node has no way to convey this information to the +serial driver, and sub-optimal performance may result. diff --git a/static/freebsd/man4/ng_ubt.4 b/static/freebsd/man4/ng_ubt.4 new file mode 100644 index 00000000..eff923aa --- /dev/null +++ b/static/freebsd/man4/ng_ubt.4 @@ -0,0 +1,124 @@ +.\" Copyright (c) 2001-2002 Maksim Yevmenkin +.\" 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. +.\" +.\" $Id: ng_ubt.4,v 1.3 2003/05/21 19:37:35 max Exp $ +.\" +.Dd December 26, 2012 +.Dt NG_UBT 4 +.Os +.Sh NAME +.Nm ng_ubt +.Nd Netgraph node type that is also a driver for Bluetooth USB devices +.Sh SYNOPSIS +.In sys/types.h +.In netgraph/bluetooth/include/ng_ubt.h +.Sh DESCRIPTION +The +.Nm ubt +node type is both a persistent Netgraph node type and a driver for +Bluetooth USB devices. +It implements a Bluetooth USB transport layer +as per chapter H2 of the Bluetooth Specification Book v1.1. +A new node is created when a supported USB device is plugged in. +.Pp +The node has a single hook called +.Dv hook . +Incoming bytes received on the device are re-assembled into HCI frames +(according to the length). +Full HCI frames are sent out on the hook. +The node will add a HCI frame indicator if the device did not send it. +HCI frames received on +.Dv hook +are transmitted out. +The node will drop the HCI frame indicator unless the device +requires it to be present. +.Sh HARDWARE +The +.Nm +driver supports all Bluetooth USB devices that conform with +the Bluetooth specification v1.1, including: +.Pp +.Bl -bullet -compact +.It +3Com 3CREB96 +.It +AIPTEK BR0R02 +.It +EPoX BT-DG02 +.It +Mitsumi Bluetooth USB adapter +.It +MSI MS-6967 +.It +TDK Bluetooth USB adapter +.It +Broadcom Bluetooth USB adapter +.El +.Sh HOOKS +This node type supports the following hooks: +.Bl -tag -width ".Va hook" +.It Va hook +single HCI frame contained in a single +.Vt mbuf +structure. +.El +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width indent +.It Dv NGM_UBT_NODE_GET_DEBUG Pq Ic get_debug +Returns an integer containing the current debug level for the node. +.It Dv NGM_UBT_NODE_SET_DEBUG Pq Ic set_debug +This command takes an integer argument and sets the current debug level +for the node. +.It Dv NGM_UBT_NODE_GET_QLEN Pq Ic get_qlen +This command takes a parameter that specifies the queue number and returns +the current maximal length of the queue for the node. +.It Dv NGM_UBT_NODE_SET_QLEN Pq Ic set_qlen +This command takes two parameters that specify the queue number and the maximum +length of the queue and sets the maximal length of the queue for the node. +.It Dv NGM_UBT_NODE_GET_STAT Pq Ic get_stat +Returns various statistic information for the node, such as: number of +bytes (frames) sent, number of bytes (frames) received and number of +input (output) errors. +.It Dv NGM_UBT_NODE_RESET_STAT Pq Ic reset_stat +Reset all statistic counters to zero. +.El +.Sh SHUTDOWN +This node shuts down when the corresponding USB device is un-plugged. +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ugen 4 , +.Xr usb 4 , +.Xr ngctl 8 +.Sh HISTORY +The +.Nm ubt +node type was implemented in +.Fx 5.0 . +.Sh AUTHORS +.An Maksim Yevmenkin Aq Mt m_evmenkin@yahoo.com +.Sh BUGS +Isochronous USB transfers are broken. +This means that the USB device will not be able to transfer SCO data (voice). +USB interrupt transfers are implemented as bulk-in transfers (not really a bug). diff --git a/static/freebsd/man4/ng_vjc.4 b/static/freebsd/man4/ng_vjc.4 new file mode 100644 index 00000000..bce09336 --- /dev/null +++ b/static/freebsd/man4/ng_vjc.4 @@ -0,0 +1,236 @@ +.\" Copyright (c) 1996-1999 Whistle Communications, Inc. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, use and +.\" redistribution of this software, in source or object code forms, with or +.\" without modifications are expressly permitted by Whistle Communications; +.\" provided, however, that: +.\" 1. Any and all reproductions of the source or object code must include the +.\" copyright notice above and the following disclaimer of warranties; and +.\" 2. No rights are granted, in any manner or form, to use Whistle +.\" Communications, Inc. trademarks, including the mark "WHISTLE +.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as +.\" such appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, +.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. +.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY +.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS +.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. +.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES +.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING +.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY +.\" OF SUCH DAMAGE. +.\" +.\" Author: Archie Cobbs +.\" $Whistle: ng_vjc.8,v 1.4 1999/01/25 23:46:28 archie Exp $ +.\" +.Dd January 19, 1999 +.Dt NG_VJC 4 +.Os +.Sh NAME +.Nm ng_vjc +.Nd Van Jacobson compression netgraph node type +.Sh SYNOPSIS +.In sys/types.h +.In netinet/in.h +.In netinet/in_systm.h +.In netinet/ip.h +.In net/slcompress.h +.In netgraph/ng_vjc.h +.Sh DESCRIPTION +The +.Nm vjc +node type performs Van Jacobson compression, which is used +over PPP, SLIP, and other point-to-point IP connections to +compress TCP packet headers. +The +.Dv ip +hook represents the uncompressed side of the node, while the +.Dv vjcomp , +.Dv vjuncomp , +and +.Dv vjip +hooks represent the compressed side of the node. +Packets received on the +.Dv ip +will be compressed or passed through as appropriate. +Packets received on the other three hooks will be uncompressed as appropriate. +This node also supports +.Dq always pass through +mode in either direction. +.Pp +Van Jacobson compression only applies to TCP packets. +Only +.Dq normal +(i.e., common case) TCP packets are actually compressed. +These are output on the +.Dv vjcomp +hook. +Other TCP packets are run through the state machine but not +compressed; these appear on the +.Dv vjuncomp +hook. +Other non-TCP IP packets are forwarded unchanged to +.Dv vjip . +.Pp +When connecting to a +.Xr ng_ppp 4 +node, the +.Dv ip , +.Dv vjuncomp , +.Dv vjcomp , +and +.Dv vjip +hooks should be connected to the +.Xr ng_ppp 4 +node's +.Dv vjc_ip , +.Dv vjc_vjcomp , +.Dv vjc_vjuncomp , +and +.Dv vjc_ip +hooks, respectively. +.Sh HOOKS +This node type supports the following hooks: +.Bl -tag -width ".Va vjuncomp" +.It Va ip +Upstream (uncompressed) IP packets. +.It Va vjcomp +Downstream compressed TCP packets. +.It Va vjuncomp +Downstream uncompressed TCP packets. +.It Va vjip +Downstream uncompressed IP packets. +.El +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_VJC_SET_CONFIG Pq Ic setconfig +This command resets the compression state and configures it according +to the supplied +.Dv "struct ngm_vjc_config" +argument. +This structure contains the following fields: +.Bd -literal -offset 4n +struct ngm_vjc_config { + u_char enableComp; /* Enable compression */ + u_char enableDecomp; /* Enable decompression */ + u_char maxChannel; /* Number of outgoing channels - 1 */ + u_char compressCID; /* OK to compress outgoing CID's */ +}; +.Ed +.Pp +When +.Dv enableComp +is set to zero, all packets received on the +.Dv ip +hook are forwarded unchanged out the +.Dv vjip +hook. +Similarly, when +.Dv enableDecomp +is set to zero, all packets received on the +.Dv vjip +hook are forwarded unchanged out the +.Dv ip +hook, and packets are not accepted on the +.Dv vjcomp +and +.Dv vjuncomp +hooks. +When a node is first created, +both compression and decompression are disabled and the node is +therefore operating in bi-directional +.Dq pass through +mode. +.Pp +When enabling compression, +.Dv maxChannel +should be set to the number of outgoing compression channels minus one, +and is a value between 3 and 15, inclusive. +The +.Dv compressCID +field indicates whether it is OK to compress the CID header field for +outgoing compressed TCP packets. +This value should be zero unless +either (a) it is not possible for an outgoing frame to be lost, or +(b) lost frames can be reliably detected and immediately +reported to the peer's decompression engine (see +.Dv NGM_VJC_RECV_ERROR +below). +.It Dv NGM_VJC_GET_STATE Pq Ic getstate +This command returns the node's current state described by the +.Dv "struct slcompress" +structure, which is defined in +.In net/slcompress.h . +.It Dv NGM_VJC_CLR_STATS Pq Ic clrstats +Clears the node statistics counters. +Statistics are also cleared whenever the +.Dv enableComp +or +.Dv enableDecomp +fields are changed from zero to one by a +.Dv NGM_VJC_SET_CONFIG +control message. +.It Dv NGM_VJC_RECV_ERROR Pq Ic recverror +When the peer has CID header field compression enabled, +this message must be sent to the local +.Nm vjc +node immediately +after detecting that a received frame has been lost, due to a bad +checksum or for any other reason. +Failing to do this can result in corrupted TCP stream data. +.El +.Sh SHUTDOWN +This node shuts down upon receipt of a +.Dv NGM_SHUTDOWN +control message, or when all hooks have been disconnected. +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ng_iface 4 , +.Xr ng_ppp 4 , +.Xr ngctl 8 +.Rs +.%A V. Jacobson +.%T "Compressing TCP/IP Headers" +.%O RFC 1144 +.Re +.Rs +.%A G. McGregor +.%T "The PPP Internet Control Protocol (IPCP)" +.%O RFC 1332 +.Re +.Sh HISTORY +The +.Nm +node type was implemented in +.Fx 4.0 . +.Sh AUTHORS +.An Archie Cobbs Aq Mt archie@FreeBSD.org +.Sh BUGS +As the initialization routine in the kernel implementation of +Van Jacobson compression initializes both compression and decompression +at once, this node does not allow compression and decompression to +be enabled in separate operations. +In order to enable one when +the other is already enabled, first both must be disabled, then +both enabled. +This of course resets the node state. +This restriction may be lifted in a later version. +.Pp +When built as a loadable kernel module, this module includes the file +.Pa net/slcompress.c . +Although loading the module should fail if +.Pa net/slcompress.c +already exists in the kernel, currently it does not, and the duplicate +copies of the file do not interfere. +However, this may change in the future. diff --git a/static/freebsd/man4/ng_vlan.4 b/static/freebsd/man4/ng_vlan.4 new file mode 100644 index 00000000..0356d5f7 --- /dev/null +++ b/static/freebsd/man4/ng_vlan.4 @@ -0,0 +1,143 @@ +.\" Copyright (c) 2003 Ruslan Ermilov +.\" 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 March 1, 2004 +.Dt NG_VLAN 4 +.Os +.Sh NAME +.Nm ng_vlan +.Nd IEEE 802.1Q VLAN tagging netgraph node type +.Sh SYNOPSIS +.In sys/types.h +.In netgraph.h +.In netgraph/ng_vlan.h +.Sh DESCRIPTION +The +.Nm vlan +node type multiplexes frames tagged according to +the IEEE 802.1Q standard between different hooks. +.Pp +Each node has two special hooks, +.Va downstream +and +.Va nomatch , +and an arbitrary number of +.Dq vlan +hooks, each associated with a particular VLAN tag. +.Pp +An +.Dv ETHERTYPE_VLAN +frame received on the +.Va downstream +hook with a tag that the node has been configured to filter +is sent out the corresponding +.Dq vlan +hook. +If it does not match any of the configured tags, or is not of a type +.Dv ETHERTYPE_VLAN , +it is sent out the +.Va nomatch +hook. +If the +.Va nomatch +hook is not connected, the packet is dropped. +.Pp +An Ethernet frame received on the +.Va nomatch +hook is passed unmodified to the +.Va downstream +hook. +.Pp +An Ethernet frame received on any of the +.Dq vlan +hooks is tagged accordingly and sent out the +.Va downstream +hook. +.Sh HOOKS +This node type supports the following hooks: +.Bl -tag -width "Aq Em any valid name" +.It Va downstream +Typically this hook would be connected to a +.Xr ng_ether 4 +node, using the +.Va lower +hook. +.It Va nomatch +Typically this hook would also be connected to an +.Xr ng_ether 4 +type node using the +.Va upper +hook. +.It Aq Em "any valid name" +Any other hook name will be accepted and should later be associated with +a particular tag. +Typically this hook would be attached to an +.Xr ng_eiface 4 +type node using the +.Va ether +hook. +.El +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_VLAN_ADD_FILTER Pq Ic addfilter +Associates a hook with the tag. +.It Dv NGM_VLAN_DEL_FILTER Pq Ic delfilter +Disassociates a hook from the tag. +.It Dv NGM_VLAN_GET_TABLE Pq Ic gettable +Returns a table of all hook/tag associations. +.El +.Sh EXAMPLES +.Bd -literal +#!/bin/sh + +ETHER_IF=rl0 + +ngctl -f- < +.\" +.Dd January 26, 2021 +.Dt NG_VLAN_ROTATE 4 +.Os +.Sh NAME +.Nm ng_vlan_rotate +.Nd IEEE 802.1ad VLAN manipulation netgraph node type +.Sh SYNOPSIS +.In sys/types.h +.In netgraph.h +.In netgraph/ng_vlan_rotate.h +.Sh DESCRIPTION +The +.Nm +node type manipulates the order of VLAN tags of frames tagged +according to the IEEE 802.1ad (an extension of IEEE 802.1Q) standard +between different hooks. +.Pp +Each node has four special hooks, +.Va original , +.Va ordered , +.Va excessive , +and +.Va incomplete . +.Pp +A frame tagged with an arbitrary number of +.Dv ETHERTYPE_VLAN , +.Dv ETHERTYPE_QINQ , +and +.Dv 0x9100 +tags received on the +.Va original +hook will be rearranged to a new order of those tags and is sent out +the +.Dq ordered +hook. +After successful processing the +.Va histogram +counter for the observed stack size increments. +.Pp +If it contains fewer VLANs in the stack than the configured +.Va min +limit, the frame is sent out to the +.Va incomplete +hook and the +.Va incomplete +counter increments. +.Pp +If there are more VLANs in the stack than the configured +.Va max +limit, the frame is sent out to the +.Va excessive +hook and the +.Va excessive +counter increments. +.Pp +If the destination hook is not connected, the frame is dropped and the +.Va drops +counter increments. +.Pp +For Ethernet frames received on the +.Va ordered +hook, the transformation is reversed and is passed to the +.Va original +hook. +Please note that this process is identical to the one described +above, besides the ordered/original hooks are swapped and the +transformation is reversed. +.Pp +An Ethernet frame received on the +.Va incomplete +or +.Va excessive +hook is forwarded to the +.Va original +hook without any modification. +.Pp +This node supports only one operation at the moment: Rotation of the +VLANs in the stack. +Setting the configuration parameter +.Va rot +to a positive value, the stack will roll up by this amount. +Negative values will roll down. +A typical scenario is setting the value to 1 in order to bring the +innermost VLAN tag to the outmost level. +Rotation includes the VLAN id, the ether type, and the QOS parameters +pcp and cfi. +Typical QOS handling refers to the outmost setting, so be careful to +keep your QOS intact. +.Sh HOOKS +This node type supports the following hooks: +.Bl -tag -width incomplete +.It Va original +Typically this hook would be connected to a +.Xr ng_ether 4 +node, using the +.Va lower +hook connected to a carrier network. +.It Va ordered +Typically this hook would be connected to a +.Xr ng_vlan 4 +type node using the +.Va downstream +hook in order to separate services. +.It Va excessive +see below. +.It Va incomplete +Typically those hooks would be attached to a +.Xr ng_eiface 4 +type node using the +.Va ether +hook for anomaly monitoring purposes. +.El +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width foo +.It Dv NGM_VLANROTATE_GET_CONF Pq Ic getconf +Read the current configuration. +.It Dv NGM_VLANROTATE_SET_CONF Pq Ic setconf +Set the current configuration. +.It Dv NGM_VLANROTATE_GET_STAT Pq Ic getstat +Read the current statistics. +.It Dv NGM_VLANROTATE_CLR_STAT Pq Ic clrstat +Zeroize the statistics. +.It Dv NGM_VLANROTATE_GETCLR_STAT Pq Ic getclrstat +Read the current statistics and zeroize it in one step. +.El +.Sh EXAMPLES +The first example demonstrates how to rotate double or triple tagged +frames so that the innermost C-VLAN can be used as service +discriminator. +The single or double tagged frames (C-VLAN removed) are sent out to an +interface pointing to different infrastructure. +.Bd -literal +#!/bin/sh + +BNG_IF=ixl3 +VOIP_IF=bge2 + +ngctl -f- < 00:01:02:03:04:05, + ethertype 802.1Q-9100 (0x9100), length 110: vlan 2, p 1, + ethertype 802.1Q-QinQ, vlan 101, p 0, + ethertype 802.1Q, vlan 123, p 7, + ethertype IPv4, (tos 0x0, ttl 64, id 15994, offset 0, flags [none], + proto ICMP (1), length 84) 192.168.140.101 > 192.168.140.1: + ICMP echo request, id 40234, seq 0, length 64 +.Ed +.Pp +The frame ejected on the +.Va ordered +hook will look like this: +.Bd -literal +00:00:00:00:01:01 > 00:01:02:03:04:05, + ethertype 802.1Q (0x8100), length 110: vlan 123, p 7, + ethertype 802.1Q-9100, vlan 2, p 1, + ethertype 802.1Q-QinQ, vlan 101, p 0, + ethertype IPv4, (tos 0x0, ttl 64, id 15994, offset 0, flags [none], + proto ICMP (1), length 84) 192.168.140.101 > 192.168.140.1: + ICMP echo request, id 40234, seq 0, length 64 +.Ed +.Pp +Hence, the frame pushed out to the +.Dv VOIP_IF +will have this form: +.Bd -literal +00:00:00:00:01:01 > 00:01:02:03:04:05, + ethertype 802.1Q-9100, vlan 2, p 1, + ethertype 802.1Q-QinQ, vlan 101, p 0, + ethertype IPv4, (tos 0x0, ttl 64, id 15994, offset 0, flags [none], + proto ICMP (1), length 84) 192.168.140.101 > 192.168.140.1: + ICMP echo request, id 40234, seq 0, length 64 +.Ed +.Pp +The second example distinguishes between double tagged and single +tagged frames. +.Bd -literal +#!/bin/sh + +IN_IF=bge1 + +ngctl -f- <. 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 Bill Paul. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Bill Paul 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 Bill Paul OR THE VOICES IN HIS HEAD +.\" 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 November 23, 2010 +.Dt NGE 4 +.Os +.Sh NAME +.Nm nge +.Nd "National Semiconductor PCI Gigabit Ethernet adapter driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device nge" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_nge_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for various NICs based on the National Semiconductor +DP83820 and DP83821 Gigabit Ethernet controller chips. +.Pp +The DP83820 supports TBI (ten bit interface) and GMII +transceivers, which means it can be used with either copper or 1000baseX +fiber applications. +The DP83820 supports TCP/IP checksum offload and +VLAN tagging/insertion as well as a 2048-bit multicast hash filter +and up to 4 pattern match buffers. +.Pp +Most cards also use the DP83861 10/100/1000 copper gigabit transceiver +chip, which supports autonegotiation of 10, 100 and 1000Mbps modes in +full or half duplex. +.Pp +The DP83820 and DP83821 also support jumbo frames, which can be +configured via the interface MTU setting. +Selecting an MTU larger than 1500 bytes with the +.Xr ifconfig 8 +utility configures the adapter to receive and transmit jumbo frames. +Using jumbo frames can greatly improve performance for certain tasks, +such as file transfers and data streaming. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width 10baseTXUTP +.It Cm autoselect +Enable autoselection of the media type and options. +The user can manually override +the autoselected mode by adding media options to +.Xr rc.conf 5 . +.It Cm 10baseT/UTP +Set 10Mbps operation. +The +.Xr ifconfig 8 +.Ic mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 100baseTX +Set 100Mbps (Fast Ethernet) operation. +The +.Xr ifconfig 8 +.Ic mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 1000baseTX +Set 1000baseTX operation over twisted pair. +.Cm full-duplex +and +.Cm half-duplex +modes are supported. +.It Cm 1000baseSX +Set 1000Mbps (Gigabit Ethernet) operation. +Both +.Cm full-duplex +and +.Cm half-duplex +modes are supported. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width full-duplex +.It Cm full-duplex +Force full duplex operation. +.It Cm half-duplex +Force half duplex operation. +.El +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports National Semiconductor DP83820 and DP83821 based +Gigabit Ethernet adapters including: +.Pp +.Bl -bullet -compact +.It +Addtron AEG320T +.It +Ark PC SOHO-GA2500T (32-bit PCI) and SOHO-GA2000T (64-bit PCI) +.It +Asante FriendlyNet GigaNIX 1000TA and 1000TPC +.It +D-Link DGE-500T +.It +Linksys EG1032, revision 1 +.It +Netgear GA621 +.It +Netgear GA622T +.It +SMC EZ Card 1000 (SMC9462TX) +.It +Surecom Technology EP-320G-TX +.It +Trendware TEG-PCITX (32-bit PCI) and TEG-PCITX2 (64-bit PCI) +.El +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width "xxxxxx" +.It Va dev.nge.%d.int_holdoff +Maximum amount of time to delay interrupt processing in units of +100us. +The accepted range is 0 to 255, the default is 1(100us). +Value 0 completely disables the interrupt moderation. +The interface has to be brought down and up again before a change +takes effect. +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "nge%d: couldn't map memory" +A fatal initialization error has occurred. +.It "nge%d: couldn't map ports" +A fatal initialization error has occurred. +.It "nge%d: couldn't map interrupt" +A fatal initialization error has occurred. +.It "nge%d: no memory for softc struct!" +The driver failed to allocate memory for per-device instance information +during initialization. +.It "nge%d: failed to enable memory mapping!" +The driver failed to initialize PCI shared memory mapping. +This might +happen if the card is not in a bus-master slot. +.It "nge%d: no memory for jumbo buffers!" +The driver failed to allocate memory for jumbo frames during +initialization. +.It "nge%d: watchdog timeout" +The device has stopped responding to the network, or there is a problem with +the network connection (cable). +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr polling 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Rs +.%T National Semiconductor DP83820 datasheet +.Re +.Rs +.%T National Semiconductor DP83861 datasheet +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 4.4 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Bill Paul Aq Mt wpaul@bsdi.com . diff --git a/static/freebsd/man4/nlsysevent.4 b/static/freebsd/man4/nlsysevent.4 new file mode 100644 index 00000000..3b46ab65 --- /dev/null +++ b/static/freebsd/man4/nlsysevent.4 @@ -0,0 +1,132 @@ +.\" +.\" Copyright (c) 2026 Baptiste Daroussin +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd April 9, 2026 +.Dt NLSYSEVENT 4 +.Os +.Sh NAME +.Nm nlsysevent +.Nd Netlink-based kernel event notification module +.Sh SYNOPSIS +To load the driver as a module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +nlsysevent_load="YES" +.Ed +.Pp +Alternatively, to load the module at runtime: +.Bd -literal -offset indent +kldload nlsysevent +.Ed +.Sh DESCRIPTION +The +.Nm +kernel module provides a +.Xr netlink 4 +Generic Netlink interface for receiving kernel device events. +It hooks into the +.Xr devctl 4 +notification system and re-publishes all kernel events as Generic Netlink +multicast messages under the +.Dv NETLINK_GENERIC +protocol family. +.Pp +This provides an alternative to reading events from +.Pa /dev/devctl +.Pq used by Xr devd 8 , +with the advantage that multiple consumers can subscribe to events +simultaneously, and consumers can selectively subscribe to specific +event groups. +.Ss Generic Netlink Family +The module registers a Generic Netlink family named +.Dq Li nlsysevent . +The dynamically-assigned family identifier can be resolved using the +standard +.Dv CTRL_CMD_GETFAMILY +request as described in +.Xr genetlink 4 . +.Ss Commands +The following command is defined: +.Bl -tag -width indent +.It Dv NLSE_CMD_NEWEVENT +Sent when a kernel event occurs. +This message is never solicited by userland; it is only delivered to +sockets that have subscribed to one or more multicast groups. +.El +.Ss Attributes +Each +.Dv NLSE_CMD_NEWEVENT +message contains the following TLV attributes: +.Bl -tag -width indent +.It Dv NLSE_ATTR_SYSTEM +(string) The system name that generated the event +.Pq e.g., Dq Li ACPI , Dq Li IFNET , Dq Li USB . +.It Dv NLSE_ATTR_SUBSYSTEM +(string) The subsystem name within the system. +.It Dv NLSE_ATTR_TYPE +(string) The type of the event. +.It Dv NLSE_ATTR_DATA +(string) Optional extra data associated with the event. +This attribute may be absent if no extra data was provided. +.El +.Ss Multicast Groups +The module creates one multicast group per system name. +The following groups are pre-registered when the module is loaded: +.Pp +.Bl -column "HYPERV_NIC_VF" -offset indent -compact +.It Li ACPI +.It Li AEON +.It Li CAM +.It Li CARP +.It Li coretemp +.It Li DEVFS +.It Li device +.It Li ETHERNET +.It Li GEOM +.It Li HYPERV_NIC_VF +.It Li IFNET +.It Li INFINIBAND +.It Li KERNEL +.It Li nvme +.It Li PMU +.It Li RCTL +.It Li USB +.It Li VFS +.It Li VT +.It Li ZFS +.El +.Pp +Additional groups are created dynamically as new system names appear in +kernel events, up to a maximum of 64 groups. +.Pp +The group identifier for a given system name can be resolved via +.Dv CTRL_CMD_GETFAMILY +and then subscribed to using the +.Dv NETLINK_ADD_MEMBERSHIP +socket option. +.Sh EXAMPLES +The +.Xr genl 1 +utility can be used to monitor events: +.Bd -literal -offset indent +genl monitor nlsysevent +.Ed +.Sh SEE ALSO +.Xr genl 1 , +.Xr snl 3 , +.Xr devctl 4 , +.Xr genetlink 4 , +.Xr netlink 4 , +.Xr devd 8 +.Sh HISTORY +The +.Nm +module first appeared in +.Fx 15.0 . +.Sh AUTHORS +The +.Nm +kernel module and this manual page were written by +.An Baptiste Daroussin Aq Mt bapt@FreeBSD.org . diff --git a/static/freebsd/man4/nmdm.4 b/static/freebsd/man4/nmdm.4 new file mode 100644 index 00000000..9ee610b2 --- /dev/null +++ b/static/freebsd/man4/nmdm.4 @@ -0,0 +1,96 @@ +.\" Copyright (c) 2001 +.\" The FreeBSD Project +.\" +.\" 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. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS 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 AUTHORS 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 11, 2020 +.Dt NMDM 4 +.Os +.Sh NAME +.Nm nmdm +.Nd nullmodem terminal driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device nmdm" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +nmdm_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides two +.Xr tty 4 +devices connected +by a virtual +.Dq "null modem" +cable. +.Pp +If either of the two tty devices have the +.Dv CDSR_OFLOW +bit +.Pq Dq Li "stty dsrflow" +set in their line discipline, the +.Nm +device will emulate the speed configured in the +.Xr termios 4 +settings. +The speed emulation works independently in the two directions, +controlled by the slower end's termios settings +.Va ( c_ispeed , c_ospeed , +.Dv CS5 ... CS8 , CSTOPB +and +.Dv PARENB ) . +.Sh FILES +.Bl -tag -width ".Pa /dev/nmdm Ns Ar N Ns Op Pa AB" -compact +.It Pa /dev/nmdm Ns Ar N Ns Op Pa AB +nullmodem device nodes. +Where the +.Pa A +node has a matching +.Pa B +node. +.El +.Pp +The +.Nm +driver implements +.Dq "on-demand device creation" +so simply accessing a given instance in +.Pa /dev +will create it. +.Sh DIAGNOSTICS +None. +.Sh SEE ALSO +.Xr stty 1 , +.Xr termios 4 , +.Xr tty 4 , +.Xr ttys 5 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 4.4 . diff --git a/static/freebsd/man4/ntb.4 b/static/freebsd/man4/ntb.4 new file mode 100644 index 00000000..fd796d6e --- /dev/null +++ b/static/freebsd/man4/ntb.4 @@ -0,0 +1,90 @@ +.\" +.\" Copyright (c) 2017 Alexander Motin +.\" 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 August 29, 2019 +.Dt NTB 4 +.Os +.Sh NAME +.Nm ntb +.Nd Non-Transparent Bridge subsystem +.Sh SYNOPSIS +To compile it into your kernel, +place the following lines in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ntb" +.Ed +.Pp +Or, to load it as a module at boot, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ntb_load="YES" +.Ed +.Pp +The following tunables are settable from the +.Xr loader 8 : +.Bl -ohang +.It Va hw.ntb.debug_level +Driver debug level. +The default value is 0, higher means more verbose. +.It Va hint.ntb_hw. Ns Ar X Ns Va .config +Configures a set of NTB functions, separated by commas, +and their resource allocation. +Each function can be configured as: "[][:[:[:]]]", where: +.Va name +is a name of the driver to attach (empty means any), +.Va mw +is a number of memory windows to allocate (empty means all available), +.Va spad +is a number of scratchpad registers to allocate (empty means all available), +.Va db +is a number of doorbells to allocate (empty means all available). +The default configuration is empty string, which means single function +with all available resources, allowing any driver to attach. +.El +.Sh DESCRIPTION +Non-Transparent Bridges connect two computer systems with PCIe +link(s), providing each of them limited access to others memory space, +scratchpad registers and interrupts. +The +.Nm +subsystem uses those resources provided in generic way by hardware drivers +and splits them between several functions, according to specified +configuration. +.Sh SEE ALSO +.Xr if_ntb 4 , +.Xr ntb_hw_amd 4 , +.Xr ntb_hw_intel 4 , +.Xr ntb_hw_plx 4 , +.Xr ntb_transport 4 +.Sh AUTHORS +.An -nosplit +The +.Nm +subsystem was developed by Intel and originally written by +.An Carl Delsey Aq Mt carl@FreeBSD.org . +Later improvements were done by +.An Conrad E. Meyer Aq Mt cem@FreeBSD.org +and +.An Alexander Motin Aq Mt mav@FreeBSD.org . diff --git a/static/freebsd/man4/ntb_hw_amd.4 b/static/freebsd/man4/ntb_hw_amd.4 new file mode 100644 index 00000000..56e0b3a7 --- /dev/null +++ b/static/freebsd/man4/ntb_hw_amd.4 @@ -0,0 +1,92 @@ +.\" +.\" Copyright (c) 2019 Rajesh Kumar +.\" 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 August 29, 2019 +.Dt NTB_HW_AMD 4 +.Os +.Sh NAME +.Nm ntb_hw_amd +.Nd AMD Non-Transparent Bridge driver +.Sh SYNOPSIS +To compile this driver into your kernel, +place the following lines in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ntb" +.Cd "device ntb_hw_amd" +.Ed +.Pp +Or, to load the driver as a module at boot, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ntb_hw_amd_load="YES" +.Ed +.Pp +The following sysctls are supported in this driver +.Bl -ohang +.It Va dev.ntb_hw.X.info +Reading this sysctl will give the basic details like the number of memory +windows, scratchpads and doorbells exposed by the NTB on the local host to +access the devices beyond the bridge. +It also provides details about the masked doorbells, translation address and +size limit of each exposed memory window and link status information. +.El +.Sh DESCRIPTION +The +.Nm ntb_hw_amd +driver provides support for the Non-Transparent Bridge (NTB) hardware in +AMD EPYC processor family. +The Non-Transparent Bridge does not look as a regular PCI bridge, but as PCI +endpoint device, hiding the devices behind it. +The driver hides details of hardware on the other side, but exposes memory windows, +scratchpads and doorbells to access the other side via hardware independent +KPI to +.Xr ntb 4 +subsystem. +.Pp +The hardware provides 2 (both 64-bit) or 3 (one 32-bit and two 64-bit) memory +windows to the other system's memory, up to 16 scratchpad registers and 16 +doorbells to communicate with and interrupt the other system respectively. +.Sh CONFIGURATION +The NTB configuration should be set by BIOS. +This includes enabling NTB, choosing topology (only NTB-to-Root Port +mode is supported now), role of the host in the topology. +This needs to be done on both systems. +.Pp +The BAR size for memory windows is configured to 1 MiB by default. +.Sh SEE ALSO +.Xr if_ntb 4 , +.Xr ntb 4 , +.Xr ntb_transport 4 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was developed by AMD and originally written by +.An Rajesh Kumar Aq Mt rajesh1.kumar@amd.com . +Reviewed by +.An Alexander Motin Aq Mt mav@FreeBSD.org , +.An Conrad E. Meyer Aq Mt cem@FreeBSD.org +and +.An Warner Losh Aq Mt imp@FreeBSD.org . diff --git a/static/freebsd/man4/ntb_hw_intel.4 b/static/freebsd/man4/ntb_hw_intel.4 new file mode 100644 index 00000000..cc22cd96 --- /dev/null +++ b/static/freebsd/man4/ntb_hw_intel.4 @@ -0,0 +1,98 @@ +.\" +.\" Copyright (c) 2016-2017 Alexander Motin +.\" 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 October 11, 2020 +.Dt NTB_HW_INTEL 4 +.Os +.Sh NAME +.Nm ntb_hw_intel +.Nd Intel(R) Non-Transparent Bridge driver +.Sh SYNOPSIS +To compile this driver into your kernel, +place the following lines in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ntb" +.Cd "device ntb_hw_intel" +.Ed +.Pp +Or, to load the driver as a module at boot, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ntb_hw_intel_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm ntb_hw_intel +driver provides support for the Non-Transparent Bridge (NTB) hardware in +Intel Xeon E3/E5 and S1200 processor families, which allow one of their PCIe +ports to be switched from transparent to non-transparent bridge mode. +In this mode the bridge looks not like a PCI bridge, but like a PCI endpoint +device. +The driver hides hardware details, exposing memory windows, scratchpads +and doorbells of the other side via a hardware independent KPI to the +.Xr ntb 4 +subsystem. +.Pp +The hardware provides 2 or 3 memory windows to the other system's memory, +16 scratchpad registers and 14, 31 or 34 doorbells to interrupt the other +system, depending on the platform. +On Xeon processors one of the memory windows is typically consumed by the driver +itself to work around multiple hardware errata. +.Sh CONFIGURATION +The NTB configuration should be set by BIOS. +It includes enabling NTB, choosing between NTB-to-NTB (back-to-back) or +NTB-to-Root Port mode, +enabling split BAR mode (one of two 64-bit BARs can be split into two 32-bit +ones) and configuring BAR sizes in bits (from 12 to 29/39) for both NTB sides. +.Pp +The recommended configuration is NTB-to-NTB mode, split bar enabled and +all BAR sizes set to 20 (1 MiB). +This needs to be done on both systems. +Note, on Xeon SkyLake and newer platforms, split bar mode is not available. +.Sh SEE ALSO +.Xr if_ntb 4 , +.Xr ntb 4 , +.Xr ntb_transport 4 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was developed by Intel and originally written by +.An Carl Delsey Aq Mt carl@FreeBSD.org . +Later improvements were done by +.An Conrad E. Meyer Aq Mt cem@FreeBSD.org +and +.An Alexander Motin Aq Mt mav@FreeBSD.org . +.Sh BUGS +NTB-to-Root Port mode is not yet supported, but it doesn't look very useful. +.Pp +On Xeon v2/v3/v4 processors split BAR mode should be enabled to allow +SB01BASE_LOCKUP errata workaround to be applied by the driver. +.Pp +There is no way to protect your system from malicious behavior on the other +system once the link is brought up. +Anyone with root or kernel access on the other system can read or write to +any location on your system. +In other words, only connect two systems that completely trust each other. diff --git a/static/freebsd/man4/ntb_hw_plx.4 b/static/freebsd/man4/ntb_hw_plx.4 new file mode 100644 index 00000000..cb3c1623 --- /dev/null +++ b/static/freebsd/man4/ntb_hw_plx.4 @@ -0,0 +1,121 @@ +.\" +.\" Copyright (c) 2017-2019 Alexander Motin +.\" 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 November 9, 2019 +.Dt NTB_HW_PLX 4 +.Os +.Sh NAME +.Nm ntb_hw_plx +.Nd PLX/Avago/Broadcom Non-Transparent Bridge driver +.Sh SYNOPSIS +To compile this driver into your kernel, +place the following lines in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ntb" +.Cd "device ntb_hw_plx" +.Ed +.Pp +Or, to load the driver as a module at boot, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ntb_hw_plx_load="YES" +.Ed +.Pp +The following tunables are settable from the +.Xr loader 8 : +.Bl -ohang +.It Va hint.ntb_hw. Ns Ar X Ns Va .b2b +Being set to 1 (default) tells the driver attached to Virtual Interface of the +NTB that it works in NTB-to-NTB (back-to-back) mode, 0 -- NTB-to-Root Port. +Driver attached to Link Interface (visible from Root Port side) switches to +NTB-to-Root Port mode automatically, but one attached to Virtual Interface +can't detect what is on the other side and require external knowledge. +.It Va hint.ntb_hw. Ns Ar X Ns Va .split +Being set above zero splits BAR2 into 2^x memory windows using Address +Lookup Table (A-LUT). +.El +.Sh DESCRIPTION +The +.Nm +driver provides support for the Non-Transparent Bridge (NTB) hardware in +PLX PCIe bridge chips, which allow up to two of their PCIe ports to be +switched from transparent to non-transparent bridge mode. +In this mode bridge looks not as a PCI bridge, but as PCI endpoint device. +The driver hides hardware details, exposing memory windows, scratchpads +and doorbells of the other side via hardware independent KPI to +.Xr ntb 4 +subsystem. +.Pp +Each PLX NTB provides up to 2 64-bit or 4 32-bit memory windows to the +other system's memory, 6 or 12 scratchpad registers and 16 doorbells to +interrupt the other system. +If Address Lookup Table (A-LUT) is enabled, BAR2 can be split into several +(up to 128) memory windows. +In NTB-to-NTB mode one of memory windows (or half of it, if bigger then 1MB) +is consumed by the driver itself to access scratchpad and doorbell registers +of the other side. +.Sh HARDWARE +The following PLX/Avago/Broadcom chips are supported by the +.Nm +driver: +.Pp +.Bl -bullet -compact +.It +PEX 8713 +.It +PEX 8717 +.It +PEX 8725 +.It +PEX 8733 +.It +PEX 8749 +.El +.Pp +, but it may also work with other compatible ones. +.Sh CONFIGURATION +The basic chip configuration should be done by serial EEPROM or via i2c. +It includes enabling NTB on one or both sides (choosing between NTB-to-NTB +(back-to-back) and NTB-to-Root Port modes) and configuring BARs sizes. +.Pp +The recommended mode is NTB-to-NTB mode, since while NTB-to-Root Port is +generally supported by the driver, it require PCI hotplug handling on the +Root Port, that may be difficult or cause different kinds of problems. +.Sh SEE ALSO +.Xr if_ntb 4 , +.Xr ntb 4 , +.Xr ntb_transport 4 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Alexander Motin Aq Mt mav@FreeBSD.org . +.Sh BUGS +There is no way to protect your system from malicious behavior on the other +system once the link is brought up. +Anyone with root or kernel access on the other system can read or write to +any location on your system. +In other words, only connect two systems that completely trust each other. diff --git a/static/freebsd/man4/ntb_transport.4 b/static/freebsd/man4/ntb_transport.4 new file mode 100644 index 00000000..460e3bc1 --- /dev/null +++ b/static/freebsd/man4/ntb_transport.4 @@ -0,0 +1,112 @@ +.\" +.\" Copyright (c) 2016-2019 Alexander Motin +.\" 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 November 9, 2019 +.Dt NTB_TRANSPORT 4 +.Os +.Sh NAME +.Nm ntb_transport +.Nd Packet-oriented transport for Non-Transparent Bridges +.Sh SYNOPSIS +To compile this driver into your kernel, +place the following lines in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ntb" +.Cd "device ntb_transport" +.Ed +.Pp +Or, to load the driver as a module at boot, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ntb_transport_load="YES" +.Ed +.Pp +The following tunables are settable from the +.Xr loader 8 : +.Bl -ohang +.It Va hw.ntb_transport.debug_level +Driver debug level. +The default value is 0, higher means more verbose. +.It Va hw.ntb_transport.max_mw_size +Limits maximum memory window usage. +Allocation of big physically contiguous memory buffer may be a problem, +while too big buffers makes no much sense for low latency network interface. +.It Va hint.ntb_transport. Ns Ar X Ns Va .config +Configures a set of the transport consumers, separated by commas. +Each consumer can be configured as: "[][:]", where: +.Va name +is a name of the driver to attach (empty means any), +.Va queues +is a number of queues to allocate (empty means automatic). +The default configuration is empty string, which means single consumer +with one queue per memory window, allowing any driver to attach. +.It Va hint.ntb_transport. Ns Ar X Ns Va .compact +Non-zero value enables compact version of scratchpad protocol, using half +as many registers. +Enabled automatically if there is not enough registers to negotiate all +available memory windows. +The compact version does not support memory windows of 4GB and above. +.El +.Sh DESCRIPTION +The +.Nm +driver attaches on top of the +.Nm ntb +driver to utilize its resources to create a set of bidirectional queues, +delivering packets between the systems. +The primary purpose of this driver is to be used by +.Nm if_ntb +network interface, but other consumers may also be developed using KPI. +.Pp +Each +.Nm +require from underlying +.Nm ntb +instance: +.Bl -bullet -compact +.It +1 or more memory windows; +.It +6 scratchpads, plus 2 more for each additional memory window, +or 3 plus 1 in case of compact protocol; +.It +1 doorbell for each memory window or configured queue. +.El +.Sh SEE ALSO +.Xr if_ntb 4 , +.Xr ntb 4 , +.Xr ntb_hw_amd 4 , +.Xr ntb_hw_intel 4 , +.Xr ntb_hw_plx 4 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was developed by Intel and originally written by +.An Carl Delsey Aq Mt carl@FreeBSD.org . +Later improvements were done by +.An Conrad E. Meyer Aq Mt cem@FreeBSD.org +and +.An Alexander Motin Aq Mt mav@FreeBSD.org . diff --git a/static/freebsd/man4/null.4 b/static/freebsd/man4/null.4 new file mode 100644 index 00000000..68c91a8d --- /dev/null +++ b/static/freebsd/man4/null.4 @@ -0,0 +1,54 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 August 30, 2019 +.Dt NULL 4 +.Os +.Sh NAME +.Nm null +.Nd the null device +.Sh DESCRIPTION +The +.Nm +device accepts and reads data as any ordinary (and willing) +file - +but throws it away. +The length of the +.Nm +device is always zero. +.Sh FILES +.Bl -tag -width /dev/null +.It Pa /dev/null +.El +.Sh SEE ALSO +.Xr full 4 , +.Xr zero 4 +.Sh HISTORY +A +.Nm +device appeared in +.At v4 . diff --git a/static/freebsd/man4/nullfs.4 b/static/freebsd/man4/nullfs.4 new file mode 100644 index 00000000..5aca0307 --- /dev/null +++ b/static/freebsd/man4/nullfs.4 @@ -0,0 +1,80 @@ +.\" +.\" Copyright (c) 2008 Daniel Gerzo +.\" 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 DOCUMENTATION 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 March 15, 2022 +.Dt NULLFS 4 +.Os +.Sh NAME +.Nm nullfs +.Nd "null file system" +.Sh SYNOPSIS +To enable support for this driver, +place the following line in the kernel configuration file: +.Bd -ragged -offset indent +.Cd "options NULLFS" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +nullfs_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver will permit the +.Fx +kernel to mount a loopback file system sub-tree. +.Sh EXAMPLES +To mount a +.Nm +file system: +.Pp +.Dl "mount_nullfs /usr/ports /home/devel/ports" +.Pp +It is also possible to define an entry in +.Xr fstab 5 +that looks similar to: +.Pp +.Bd -literal +/usr/ports /home/devel/ports nullfs rw 0 0 +.Ed +.Sh SEE ALSO +.Xr fstab 5 , +.Xr mount_nullfs 8 +.Sh HISTORY +The +.Nm +layer first appeared in +.Bx 4.4 . +.Sh AUTHORS +.An -nosplit +The +.Nm +kernel implementation was written by +.An John Heideman . +.Pp +This manual page was written by +.An Daniel Gerzo Aq Mt danger@FreeBSD.org . diff --git a/static/freebsd/man4/numa.4 b/static/freebsd/man4/numa.4 new file mode 100644 index 00000000..5a2108fb --- /dev/null +++ b/static/freebsd/man4/numa.4 @@ -0,0 +1,150 @@ +.\" Copyright (c) 2015 Adrian Chadd +.\" 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 AUTHORS 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 AUTHORS 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 October 22, 2018 +.Dt NUMA 4 +.Os +.Sh NAME +.Nm NUMA +.Nd Non-Uniform Memory Access +.Sh SYNOPSIS +.Cd options MAXMEMDOM +.Cd options NUMA +.Sh DESCRIPTION +Non-Uniform Memory Access is a computer architecture design which +involves unequal costs between processors, memory and IO devices +in a given system. +.Pp +In a +.Nm +architecture, the latency to access specific memory or IO devices +depends upon which processor the memory or device is attached to. +Accessing memory local to a processor is faster than accessing memory +that is connected to one of the other processors. +.Fx +implements NUMA-aware memory allocation policies. +By default it attempts to ensure that allocations are balanced across +each domain. +Users may override the default domain selection policy using +.Xr cpuset 1 . +.Pp +.Nm +support is enabled when the +.Cd NUMA +option is specified in the kernel configuration file. +Each platform defines the +.Cd MAXMEMDOM +constant, which specifies the maximum number of supported NUMA domains. +This constant may be specified in the kernel configuration file. +.Nm +support can be disabled at boot time by setting the +.Va vm.numa.disabled +tunable to 1. +Other values for this tunable are currently ignored. +.Pp +Thread and process +.Nm +policies are controlled with the +.Xr cpuset_getdomain 2 +and +.Xr cpuset_setdomain 2 +syscalls. +The +.Xr cpuset 1 +tool is available for starting processes with a non-default +policy, or to change the policy of an existing thread or process. +See +.Xr SMP 4 +for information about CPU to domain mapping. +.Pp +Systems with non-uniform access to I/O devices may mark those devices +with the local VM domain identifier. +Drivers can find out their local domain information by calling +.Xr bus_get_domain 9 . +.Ss MIB Variables +The operation of +.Nm +is controlled and exposes information with these +.Xr sysctl 8 +MIB variables: +.Pp +.Bl -tag -width indent -compact +.It Va vm.ndomains +The number of VM domains which have been detected. +.Pp +.It Va vm.phys_locality +A table indicating the relative cost of each VM domain to each other. +A value of 10 indicates equal cost. +A value of -1 means the locality map is not available or no +locality information is available. +.Pp +.It Va vm.phys_segs +The map of physical memory, grouped by VM domain. +.El +.Sh IMPLEMENTATION NOTES +The current +.Nm +implementation is VM-focused. +The hardware +.Nm +domains are mapped into a contiguous, non-sparse +VM domain space, starting from 0. +Thus, VM domain information (for example, the domain identifier) is not +necessarily the same as is found in the hardware specific information. +Policy information is available in both struct thread and struct proc. +.Sh SEE ALSO +.Xr cpuset 1 , +.Xr cpuset_getaffinity 2 , +.Xr cpuset_setaffinity 2 , +.Xr SMP 4 , +.Xr bus_get_domain 9 +.Sh HISTORY +.Nm +first appeared in +.Fx 9.0 +as a first-touch allocation policy with a fail-over to round-robin allocation +and was not configurable. +It was then modified in +.Fx 10.0 +to implement a round-robin allocation policy and was also not configurable. +.Pp +The +.Xr numa_getaffinity 2 +and +.Xr numa_setaffinity 2 +syscalls and the +.Xr numactl 1 +tool first appeared in +.Fx 11.0 +and were removed in +.Fx 12.0 . +The current implementation appeared in +.Fx 12.0 . +.Sh AUTHORS +This manual page written by +.An Adrian Chadd Aq Mt adrian@FreeBSD.org . +.Sh NOTES +No statistics are kept to indicate how often +.Nm +allocation policies succeed or fail. diff --git a/static/freebsd/man4/nvd.4 b/static/freebsd/man4/nvd.4 new file mode 100644 index 00000000..1861fabc --- /dev/null +++ b/static/freebsd/man4/nvd.4 @@ -0,0 +1,110 @@ +.\" +.\" Copyright (c) 2012-2016 Intel Corporation +.\" 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, +.\" without modification. +.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer +.\" substantially similar to the "NO WARRANTY" disclaimer below +.\" ("Disclaimer") and any redistribution must be conditioned upon +.\" including a substantially similar Disclaimer requirement for further +.\" binary redistribution. +.\" +.\" NO WARRANTY +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR 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 DAMAGES. +.\" +.\" nvd driver man page. +.\" +.\" Author: Jim Harris +.\" +.Dd October 2, 2025 +.Dt NVD 4 +.Os +.Sh NAME +.Nm nvd +.Nd NVM Express disk driver +.Sh SYNOPSIS +To compile this driver into your kernel, +place the following lines in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device nvme" +.Cd "device nvd" +.Ed +.Pp +Or, to load the driver as a module at boot, place the following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +nvme_load="YES" +nvd_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver exposes NVM Express (NVMe) namespaces as disks to the kernel disk +storage API. +It depends on the +.Xr nvme 4 +driver for notification of existing NVMe namespaces and submission of NVM +I/O commands. +.Pp +Device nodes from the +.Nm +driver will have the format /dev/nvdX and are +.Xr GEOM 4 +disks which can be partitioned by +.Xr geom 8 . +Note that device nodes from the +.Xr nvme 4 +driver are not +.Xr GEOM 4 +disks and cannot be partitioned. +.Sh HARDWARE +The +.Nm +driver supports NVMe storage devices using NVMe namespaces. +.Sh CONFIGURATION +The +.Nm +driver defines a system-wide maximum delete size for NVMe devices. +The default is 1GB. +To select a different value, set the following tunable in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hw.nvd.delete_max= +.Ed +.Sh SEE ALSO +.Xr GEOM 4 , +.Xr nda 4 , +.Xr nvme 4 , +.Xr geom 8 , +.Xr nvmecontrol 8 , +.Xr disk 9 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 9.2 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was developed by Intel and originally written by +.An Jim Harris Aq Mt jimharris@FreeBSD.org , +with contributions from Joe Golio at EMC. +.Pp +This man page was written by +.An Jim Harris Aq Mt jimharris@FreeBSD.org . diff --git a/static/freebsd/man4/nvdimm.4 b/static/freebsd/man4/nvdimm.4 new file mode 100644 index 00000000..2bec51b4 --- /dev/null +++ b/static/freebsd/man4/nvdimm.4 @@ -0,0 +1,132 @@ +.\" Copyright (c) 2019 The FreeBSD Foundation +.\" +.\" This documentation was written by +.\" Konstantin Belousov under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" 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 AUTHORS 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 AUTHORS 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 September 5, 2019 +.Dt NVDIMM 4 amd64 +.Os +.Sh NAME +.Nm nvdimm +.Nd ACPI NVDIMM driver +.Sh SYNOPSIS +To load the driver as a module at boot, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +nvdimm_load="YES" +.Ed +.Sh DESCRIPTION +.Bf -symbolic +Note: +The +.Nm +driver is under development and has some important limitations +described below. +.Ef +.Pp +The +.Nm +driver provides access to Non-Volatile DIMM (NVDIMM) persistent memory +devices, which are ACPI-enumerated under the root NVDIMM device +with a +.Va _HID +of +.Dv ACPI0012 +and in the +.Dv NFIT +table. +.Pp +For each System Physical Address (SPA) Range described by NFIT, a +device node +.Pa /dev/nvdimm_spaNNN +is created, where +.Dv NNN +is the SPA position in the table. +The node can be used to +.Xr read 2 , +.Xr write 2 , +or +.Xr mmap 2 +the device. +.Pp +Also, for each SPA, the geom provider +.Pa spaNNN +is created, which can be used to create a conventional filesystem (e.g., +by +.Xr newfs 8 ) +and +.Xr mount 8 +it as any storage volume. +Content accessible by +.Pa /dev/nvdimm_spaNNN +and +.Pa /dev/spaNNN +is coherent. +.Pp +The +.Nm +driver has support for reading NVDIMM namespaces (if supported by your +hardware and already configured by some other mechanism, e.g., a BIOS +configuration screen). +The driver will provide a +.Pa /dev/nvdimm_spaNNNnsMMM +device node and +.Pa spaNNNnsMMM +geom provider for each namespace in a SPA, which behave analogously to their +full-SPA cousins described above. +.Sh SEE ALSO +.Xr acpi 4 , +.Xr GEOM 4 , +.Xr geom 8 , +.Xr mount 8 , +.Xr newfs 8 , +.Xr disk 9 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 12.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was originally written by +.An Konstantin Belousov Aq Mt kib@FreeBSD.org , +and then updated by +.An D. Scott Phillips Aq Mt scottph@FreeBSD.org . +.Sh BUGS +The +.Nm +driver does not utilize the Block Window interface, so if a write to an +NVDIMM is interrupted due to a system crash or power outage, +the corresponding page might be left in a partially updated state. +.Pp +There is no support for Device-Specific Methods (DSM), used to report and +control device health and wearing. +.Pp +The driver depends on the +.Xr pmap_largemap 9 +pmap interface, which is currently only implemented on amd64. +The interface can be only reasonable implemented on 64bit architectures. diff --git a/static/freebsd/man4/nvme.4 b/static/freebsd/man4/nvme.4 new file mode 100644 index 00000000..76960a7e --- /dev/null +++ b/static/freebsd/man4/nvme.4 @@ -0,0 +1,294 @@ +.\" +.\" Copyright (c) 2012-2016 Intel Corporation +.\" 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, +.\" without modification. +.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer +.\" substantially similar to the "NO WARRANTY" disclaimer below +.\" ("Disclaimer") and any redistribution must be conditioned upon +.\" including a substantially similar Disclaimer requirement for further +.\" binary redistribution. +.\" +.\" NO WARRANTY +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR 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 DAMAGES. +.\" +.\" nvme driver man page. +.\" +.\" Author: Jim Harris +.\" +.Dd June 6, 2020 +.Dt NVME 4 +.Os +.Sh NAME +.Nm nvme +.Nd NVM Express core driver +.Sh SYNOPSIS +To compile this driver into your kernel, +place the following line in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device nvme" +.Ed +.Pp +Or, to load the driver as a module at boot, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +nvme_load="YES" +.Ed +.Pp +Most users will also want to enable +.Xr nvd 4 +or +.Xr nda 4 +to expose NVM Express namespaces as disk devices which can be +partitioned. +Note that in NVM Express terms, a namespace is roughly equivalent to a +SCSI LUN. +.Sh DESCRIPTION +The +.Nm +driver provides support for NVM Express (NVMe) controllers, such as: +.Bl -bullet +.It +Hardware initialization +.It +Per-CPU IO queue pairs +.It +API for registering NVMe namespace consumers such as +.Xr nvd 4 +or +.Xr nda 4 +.It +API for submitting NVM commands to namespaces +.It +Ioctls for controller and namespace configuration and management +.El +.Pp +The +.Nm +driver creates controller device nodes in the format +.Pa /dev/nvmeX +and namespace device nodes in +the format +.Pa /dev/nvmeXnsY . +Note that the NVM Express specification starts numbering namespaces at 1, +not 0, and this driver follows that convention. +.Sh CONFIGURATION +By default, +.Nm +will create an I/O queue pair for each CPU, provided enough MSI-X vectors +and NVMe queue pairs can be allocated. +If not enough vectors or queue +pairs are available, nvme(4) will use a smaller number of queue pairs and +assign multiple CPUs per queue pair. +.Pp +To force a single I/O queue pair shared by all CPUs, set the following +tunable value in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hw.nvme.per_cpu_io_queues=0 +.Ed +.Pp +To assign more than one CPU per I/O queue pair, thereby reducing the number +of MSI-X vectors consumed by the device, set the following tunable value in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hw.nvme.min_cpus_per_ioq=X +.Ed +.Pp +To force legacy interrupts for all +.Nm +driver instances, set the following tunable value in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hw.nvme.force_intx=1 +.Ed +.Pp +Note that use of INTx implies disabling of per-CPU I/O queue pairs. +.Pp +To control maximum amount of system RAM in bytes to use as Host Memory +Buffer for capable devices, set the following tunable: +.Bd -literal -offset indent +hw.nvme.hmb_max +.Ed +.Pp +The default value is 5% of physical memory size per device. +.Pp +To enable Autonomous Power State Transition (APST), set the following +tunable value in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hw.nvme.apst_enable=1 +.Ed +.Pp +The default vendor-provided settings, if any, will be applied. +To override this, set the following tunable: +.Bd -literal -offset indent +hw.nvme.apst_data +.Ed +.Pp +The string must contain up to 32 encoded integers, e.g. "0x6418 0 +0 0x3e820". +Each value corresponds to a specific available power state starting +from the lowest, and defines the target state (bits 3..7) to +transition to, as well as the idle time in milliseconds (bits 8..31) +to wait before that transition. +Bits 0..2 must be zero. +.Pp +The +.Xr nvd 4 +driver is used to provide a disk driver to the system by default. +The +.Xr nda 4 +driver can also be used instead. +The +.Xr nvd 4 +driver performs better with smaller transactions and few TRIM +commands. +It sends all commands directly to the drive immediately. +The +.Xr nda 4 +driver performs better with larger transactions and also collapses +TRIM commands giving better performance. +It can queue commands to the drive; combine +.Dv BIO_DELETE +commands into a single trip; and +use the CAM I/O scheduler to bias one type of operation over another. +To select the +.Xr nda 4 +driver, set the following tunable value in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hw.nvme.use_nvd=0 +.Ed +.Pp +This value may also be set in the kernel config file with +.Bd -literal -offset indent +.Cd options NVME_USE_NVD=0 +.Ed +.Pp +When there is an error, +.Nm +prints only the most relevant information about the command by default. +To enable dumping of all information about the command, set the following tunable +value in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hw.nvme.verbose_cmd_dump=1 +.Ed +.Pp +Prior versions of the driver reset the card twice on boot. +This proved to be unnecessary and inefficient, so the driver now resets drive +controller only once. +The old behavior may be restored in the kernel config file with +.Bd -literal -offset indent +.Cd options NVME_2X_RESET +.Ed +.Sh SYSCTL VARIABLES +The following controller-level sysctls are currently implemented: +.Bl -tag -width indent +.It Va dev.nvme.0.num_cpus_per_ioq +(R) Number of CPUs associated with each I/O queue pair. +.It Va dev.nvme.0.int_coal_time +(R/W) Interrupt coalescing timer period in microseconds. +Set to 0 to disable. +.It Va dev.nvme.0.int_coal_threshold +(R/W) Interrupt coalescing threshold in number of command completions. +Set to 0 to disable. +.El +.Pp +The following queue pair-level sysctls are currently implemented. +Admin queue sysctls take the format of dev.nvme.0.adminq and I/O queue sysctls +take the format of dev.nvme.0.ioq0. +.Bl -tag -width indent +.It Va dev.nvme.0.ioq0.num_entries +(R) Number of entries in this queue pair's command and completion queue. +.It Va dev.nvme.0.ioq0.num_tr +(R) Number of nvme_tracker structures currently allocated for this queue pair. +.It Va dev.nvme.0.ioq0.num_prp_list +(R) Number of nvme_prp_list structures currently allocated for this queue pair. +.It Va dev.nvme.0.ioq0.sq_head +(R) Current location of the submission queue head pointer as observed by +the driver. +The head pointer is incremented by the controller as it takes commands off +of the submission queue. +.It Va dev.nvme.0.ioq0.sq_tail +(R) Current location of the submission queue tail pointer as observed by +the driver. +The driver increments the tail pointer after writing a command +into the submission queue to signal that a new command is ready to be +processed. +.It Va dev.nvme.0.ioq0.cq_head +(R) Current location of the completion queue head pointer as observed by +the driver. +The driver increments the head pointer after finishing +with a completion entry that was posted by the controller. +.It Va dev.nvme.0.ioq0.num_cmds +(R) Number of commands that have been submitted on this queue pair. +.It Va dev.nvme.0.ioq0.dump_debug +(W) Writing 1 to this sysctl will dump the full contents of the submission +and completion queues to the console. +.El +.Pp +In addition to the typical pci attachment, the +.Nm +driver supports attaching to a +.Xr ahci 4 +device. +Intel's Rapid Storage Technology (RST) hides the nvme device +behind the AHCI device due to limitations in Windows. +However, this effectively hides it from the +.Fx +kernel. +To work around this limitation, +.Fx +detects that the AHCI device supports RST and when it is enabled. +See +.Xr ahci 4 +for more details. +.Sh DIAGNOSTICS +.Bl -diag +.It "nvme%d: System interrupt issues?" +The driver found a timed-out transaction had a pending completion record, +indicating an interrupt had not been delivered. +The system is either not configuring interrupts properly, or the system drops +them under load. +This message will appear at most once per boot per controller. +.El +.Sh SEE ALSO +.Xr nda 4 , +.Xr nvd 4 , +.Xr pci 4 , +.Xr nvmecontrol 8 , +.Xr disk 9 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 9.2 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was developed by Intel and originally written by +.An Jim Harris Aq Mt jimharris@FreeBSD.org , +with contributions from +.An Joe Golio +at EMC. +.Pp +This man page was written by +.An Jim Harris Aq Mt jimharris@FreeBSD.org . diff --git a/static/freebsd/man4/nvmf.4 b/static/freebsd/man4/nvmf.4 new file mode 100644 index 00000000..9ace6778 --- /dev/null +++ b/static/freebsd/man4/nvmf.4 @@ -0,0 +1,106 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2024 Chelsio Communications, Inc. +.\" +.Dd May 7, 2025 +.Dt NVMF 4 +.Os +.Sh NAME +.Nm nvmf +.Nd "NVM Express over Fabrics host driver" +.Sh SYNOPSIS +To compile the driver into the kernel, +place the following line in the +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device nvmf" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +nvmf_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides the kernel component of an NVM Express over Fabrics +host. +The NVMeoF host is the client which provides local access to +namespaces exported by a remote controller. +.Pp +Associations between the local host and remote controllers are managed +using +.Xr nvmecontrol 8 . +New associations are created via the +.Cm connect +command and destroyed via the +.Cm disconnect +command. +If an association's connection is interrupted, +the +.Cm reconnect +command creates a new association to replace the interrupted association. +.Pp +Similar to +.Xr nvme 4 , +.Nm +creates controller device nodes using the format +.Pa /dev/nvmeX +and namespace device nodes using the format +.Pa /dev/nvmeXnsY . +.Nm +also exports remote namespaces via the CAM +.Xr nda 4 +peripheral driver. +Unlike +.Xr nvme 4 , +.Nm +does not support the +.Xr nvd 4 +disk driver. +.Pp +Associations require a supported transport such as +.Xr nvmf_tcp 4 +for associations using TCP/IP. +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va kern.nvmf.fail_on_disconnection +Determines the behavior when an association's connection is interrupted. +By default, input/output operations are suspended while a host is disconnected. +This includes operations pending at the time the association's connection was +interrupted as well as new requests submitted while the host is disconnected. +Once a new association is established, suspended I/O requests are retried. +When set to 1, input/output operations fail with +.Er EIO +while a host is disconnected and +.Xr nda 4 +peripherals are destroyed after the first failed I/O request. +Note that any destroyed +.Xr nda 4 +peripherals will be recreated after a new association is established. +.El +.Sh SEE ALSO +.Xr nda 4 , +.Xr nvme 4 , +.Xr nvmf_tcp 4 , +.Xr nvmft 4 , +.Xr nvmecontrol 8 +.Sh HISTORY +The +.Nm +module first appeared in +.Fx 15.0 . +.Sh AUTHORS +The +.Nm +driver was developed by +.An John Baldwin Aq Mt jhb@FreeBSD.org +under sponsorship from Chelsio Communications, Inc. diff --git a/static/freebsd/man4/nvmf_che.4 b/static/freebsd/man4/nvmf_che.4 new file mode 100644 index 00000000..8960cda9 --- /dev/null +++ b/static/freebsd/man4/nvmf_che.4 @@ -0,0 +1,80 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 Chelsio Communications, Inc. +.\" +.Dd November 14, 2025 +.Dt NVMF_CHE 4 +.Os +.Sh NAME +.Nm nvmf_che +.Nd TCP transport for NVM Express over Fabrics on Chelsio NICs +.Sh SYNOPSIS +In +.Xr loader.conf 5 : +.Bd -literal -offset indent +nvmf_che_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +module implements the a TCP/IP transport for NVM Express over Fabrics +using PDU offload on Chelsio T7 adapters. +It can be used by either the in-kernel NVMeoF host driver or controller. +In order to use PDU offload, +the initial socket connection must be using the TCP offload engine (TOE) +on a supported network interface. +In addition, +controller connections must negotiate a suitable +.Dv MAXH2CDATA +limit to ensure that received PDUs do not exceeed the maximum size +supported by the adapter. +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va kern.nvmf.che.max_transmit_pdu +The maximum size of a transmitted PDU including all headers, payload, +and checksums. +This is an upper limit enforced when queues are created. +Individual adapters may empose a smaller limit. +The default size is 32 kilobytes. +.It Va kern.nvmf.che.max_receive_pdu +As above, but for received PDUs. +.It Va kern.nvmf.che.use_dsgl +Enable the use of a S/G list for large writes into adapter memory when +writing control structures for DDP (not used for PDU payload data). +S/G lists are enabled by default. +.It Va kern.nvmf.che.inline_threshold +Writes of control structures into adapter memory use a S/G list instead +of immediate data placed in work requests. +The default threshold is 256 bytes. +.It Va kern.nvmf.che.ddp_tags_per_qp +The number of STAGs reserved for use by DDP buffers for each queue pair. +Each command sent on a queue that requests data from the remote peer can +use DDP to place received data directly into the associated data buffer. +Each buffer requires a STAG to enable DDP. +If an STAG is not available when command requesting remote data is sent, +the data will be received in free list buffers and copied into the data +buffer by the driver instead. +The default size is 256 kilobytes. +.El +.Sh SEE ALSO +.Xr cxgbe 4 , +.Xr nvmf 4 , +.Xr nvmf_tcp 4 , +.Xr nvmft 4 +.Sh HISTORY +The +.Nm +module first appeared in +.Fx 16.0 . +.Sh AUTHORS +The +.Nm +module was developed by +.An John Baldwin Aq Mt jhb@FreeBSD.org +under sponsorship from Chelsio Communications, Inc. diff --git a/static/freebsd/man4/nvmf_tcp.4 b/static/freebsd/man4/nvmf_tcp.4 new file mode 100644 index 00000000..a781abaa --- /dev/null +++ b/static/freebsd/man4/nvmf_tcp.4 @@ -0,0 +1,64 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2024 Chelsio Communications, Inc. +.\" +.Dd July 25, 2024 +.Dt NVMF_TCP 4 +.Os +.Sh NAME +.Nm nvmf_tcp +.Nd TCP transport for NVM Express over Fabrics +.Sh SYNOPSIS +To compile the module into the kernel, +place the following line in the +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device nvmf_tcp" +.Ed +.Pp +Alternatively, to load the +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +nvmf_tcp_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +module implements the software TCP/IP transport for NVM Express over Fabrics. +It can be used by either the in-kernel NVMeoF host driver or controller. +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va kern.nvmf.tcp.max_transmit_data +The maximum data payload size of +.Va C2H_DATA +and +.Va H2C_DATA +PDUs. +A remote controller may enforce a lower limit on the size of +.Va H2C_DATA +PDUs via the +.Va MAXH2CDATA +parameter. +The default size is 256 kilobytes. +.El +.Sh SEE ALSO +.Xr nvmf 4 , +.Xr nvmft 4 +.Sh HISTORY +The +.Nm +module first appeared in +.Fx 15.0 . +.Sh AUTHORS +The +.Nm +module was developed by +.An John Baldwin Aq Mt jhb@FreeBSD.org +under sponsorship from Chelsio Communications, Inc. diff --git a/static/freebsd/man4/nvmft.4 b/static/freebsd/man4/nvmft.4 new file mode 100644 index 00000000..d121fb97 --- /dev/null +++ b/static/freebsd/man4/nvmft.4 @@ -0,0 +1,85 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2024 Chelsio Communications, Inc. +.\" +.Dd May 2, 2024 +.Dt NVMFT 4 +.Os +.Sh NAME +.Nm nvmft +.Nd "NVM Express over Fabrics CAM Target Layer frontend" +.Sh SYNOPSIS +To compile the subsystem into the kernel, +place the following lines in the +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device nvmft" +.Cd "device ctl" +.Ed +.Pp +Alternatively, to load the subsystem as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +nvmft_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides the kernel component of an NVM Express over Fabrics +controller. +The NVMeoF controller is the server exporting namespaces backed by +local files and volumes to remote hosts. +.Nm +follows the dynamic controller model and creates a new dynamic controller +for each association. +.Pp +.Nm +is implemented as a +.Xr ctl 4 +frontend and exports CAM Target Layer LUNs as namespaces to remote hosts. +LUNs can be configured via +.Xr ctladm 8 . +.Pp +Associations between the local controller and remote hosts are managed +using both the +.Xr nvmfd 8 +daemon and the +.Xr ctladm 8 +utility. +The +.Xr nvmfd 8 +daemon listens for new associations and handles transport-specific +negotiation before handing off connected queue pairs to +.Nm +which associates queue pairs with a suitable controller instance. +The +.Cm nvlist +.Xr ctladm 8 +command lists active controllers. +The +.Cm nvterminate +command terminates one or more associations between a local controller +and a remote host. +.Pp +Associations require a supported transport such as +.Xr nvmf_tcp 4 +for associations using TCP/IP. +.Sh SEE ALSO +.Xr ctl 4 , +.Xr nvmf 4 , +.Xr nvmf_tcp 4 , +.Xr ctladm 8 , +.Xr nvmfd 8 +.Sh HISTORY +The +.Nm +module first appeared in +.Fx 15.0 . +.Sh AUTHORS +The +.Nm +subsystem was developed by +.An John Baldwin Aq Mt jhb@FreeBSD.org +under sponsorship from Chelsio Communications, Inc. diff --git a/static/freebsd/man4/nvram.4 b/static/freebsd/man4/nvram.4 new file mode 100644 index 00000000..1ff2d078 --- /dev/null +++ b/static/freebsd/man4/nvram.4 @@ -0,0 +1,91 @@ +.\" +.\"Copyright (c) 2010 iXsystems, Inc. +.\"All rights reserved. +.\" written by: Xin LI +.\" +.\"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 February 8, 2010 +.Dt NVRAM 4 +.Os +.Sh NAME +.Nm nvram +.Nd "non-volatile RAM" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device nvram" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +nvram_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides access to BIOS configuration NVRAM on i386 and amd64 +systems. +.Pp +PC motherboard uses a small non-volatile memory to store BIOS settings +which is usually part of its clock chip and sometimes referred as +.Dq CMOS SRAM . +This driver exposes bytes 14 through 128 of the NVRAM, or a total of +114 bytes, at offset zero of the device file +.Pa /dev/nvram . +.Pp +This driver is useful for cloning machines that shares the same hardware +configuration and need same BIOS setting tweaks. +.Sh IMPLEMENTATION NOTES +The BIOS NVRAM's bytes 16 through 31 are checksummed at byte 32. +This driver +.Em does not +take care for these checksums. +.Sh EXAMPLES +Backup existing BIOS NVRAM to +.Pa nvram.bin : +.Pp +.Dl dd if=/dev/nvram of=nvram.bin +.Pp +Restore BIOS NVRAM from +.Pa nvram.bin : +.Pp +.Dl dd if=nvram.bin of=/dev/nvram +.Sh SEE ALSO +.Xr dd 1 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 6.4 . +.Sh AUTHORS +.An -nosplit +The +.Nm +device driver was written by +.An Peter Wemm . +This manual page was written by +.An Xin LI . diff --git a/static/freebsd/man4/oce.4 b/static/freebsd/man4/oce.4 new file mode 100644 index 00000000..a8cd9ae8 --- /dev/null +++ b/static/freebsd/man4/oce.4 @@ -0,0 +1,133 @@ +.\" Copyright (C) 2013 Emulex +.\" 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. Neither the name of the Emulex Corporation nor the names of its +.\" contributors may be used to endorse or promote products derived from +.\" this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 COPYRIGHT OWNER 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. +.\" +.\" Contact Information: +.\" freebsd-drivers@emulex.com +.\" +.\" Emulex +.\" 3333 Susan Street +.\" Costa Mesa, CA 92626 +.\" +.Dd January 27, 2025 +.Dt OCE 4 +.Os +.Sh NAME +.Nm oce +.Nd "Device driver for Emulex OneConnect 10Gb network adapters" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device pci" +.Cd "device oce" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_oce_load="YES" +.Ed +.Sh DESCRIPTION +Emulex OneConnect adapters come in various skews and with +different combinations of NIC, FCoE and iSCSI functions. +The +.Nm +driver claims the NIC functions in all these adapters. +.Pp +The +.Nm +driver supports VLAN Hardware offload, TCP checksum offload, +TCP segmentation offload (TSO), Large receive offload (LRO), +Bonding, Jumbo frames (from 1500 - 9000), Multiple TX queues, +Receive-Side Scaling (RSS) and MSI-X interrupts. +.Sh HARDWARE +The +.Nm +driver supports the following network adapters: +.Pp +.Bl -bullet -compact +.It +Emulex BladeEngine 2 +.It +Emulex BladeEngine 3 +.It +Emulex Lancer +.El +.Sh UPDATING FIRMWARE +Adapter firmware updates are persistent. +.Pp +Firmware can be updated by following the steps below: +.Bl -enum +.It +Copy the below code to a Makefile: +.Bd -literal -offset indent +KMOD=elxflash +FIRMWS=imagename.ufi:elxflash +\&.include +.Ed +.It +Replace imagename in above with UFI file name +.It +Copy Makefile and UFI file to a directory +.It +Execute make & copy generated elxflash.ko to +.Pa /lib/modules +.It +sysctl dev.oce..fw_upgrade=elxflash +.It +Reboot the machine +.El +.Pp +In case of issues with supplied UFI, flashing fails with one +of the following errors. +.Pp +.Bl -enum -compact +.It +.Qq Invalid BE3 firmware image +.It +.Qq "Invalid Cookie. Firmware image corrupted ?" +.It +.Qq cmd to write to flash rom failed. +.El +.Sh SUPPORT +For general information and support, +go to the Emulex website at: +.Pa http://www.Emulex.com/ +or E-Mail at +.Pa freebsd-drivers@emulex.com . +.Sh SEE ALSO +.Xr ifconfig 8 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An freebsd-drivers@emulex.com . diff --git a/static/freebsd/man4/ocs_fc.4 b/static/freebsd/man4/ocs_fc.4 new file mode 100644 index 00000000..714bb265 --- /dev/null +++ b/static/freebsd/man4/ocs_fc.4 @@ -0,0 +1,194 @@ +.\" Copyright (c) 2017 Broadcom. All rights reserved. +.\" The term "Broadcom" refers to Broadcom Limited and/or its subsidiaries. +.\" +.\" 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. Neither the name of the copyright holder nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 COPYRIGHT HOLDER 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 December 29, 2021 +.Dt OCS_FC 4 +.Os +.Sh NAME +.Nm ocs_fc +.Nd "Device driver for Emulex Fibre Channel Host Adapters" +.Sh SYNOPSIS +To compile this driver into the kernel, add this line to the +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ocs_fc" +.Ed +.Pp +To load the driver as a module at boot, add this line to +.Xr loader.conf 5 : +.Bd -literal -offset indent +ocs_fc_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides access to Fibre Channel SCSI devices. +.Pp +The +.Nm +driver supports initiator and target modes. +Support is available for Arbitrated loops, Point-to-Point, +and Fabric connections. +FC-Tape is highly recommended for connections to tape drives that support +it. +FC-Tape includes four elements from the T-10 FCP-4 specification: +.Bl -bullet -offset indent +.It +Precise Delivery of Commands +.It +Confirmed Completion of FCP I/O Operations +.It +Retransmission of Unsuccessfully Transmitted IUs +.It +Task Retry Identification +.El +.Pp +Together these features allow for link level error recovery with tape +devices. +Without link level error recovery, an initiator cannot, for instance, tell whether a tape write +command that has timed out resulted in all, part, or none of the data going to +the tape drive. +FC-Tape is automatically enabled when both the controller and target support it. +.Sh HARDWARE +The +.Nm +driver supports these Fibre Channel adapters: +.Bl -tag -width xxxxxx -offset indent +.It Emulex 16/8G FC GEN 5 HBAS +.Bd -literal -offset indent +LPe15004 FC Host Bus Adapters +LPe160XX FC Host Bus Adapters +.Ed +.It Emulex 32/16G FC GEN 6 HBAS +.Bd -literal -offset indent +LPe3100X FC Host Bus Adapters +LPe3200X FC Host Bus Adapters +.Ed +.It Emulex 64/32G FC GEN 7 HBAS +.Bd -literal -offset indent +LPe3500X FC Host Bus Adapters +.Ed +.El +.Sh UPDATING FIRMWARE +Adapter firmware updates are persistent. +.Pp +Firmware can be updated by following these steps: +.Bl -enum +.It +Copy this code to a +.Pa Makefile : +.Bd -literal -offset indent +KMOD=ocsflash +FIRMWS=imagename.grp:ocsflash +\&.include +.Ed +.It +Replace +.Pa imagename +with the name of the GRP file. +.It +Copy the +.Pa Makefile +and GRP file to a local directory +.It +Execute +.Cm make +and copy the generated +.Pa ocsflash.ko +file to +.Pa /lib/modules +.It +.Cm sysctl dev.ocs_fc..fw_upgrade=ocsflash +.It +Check kernel messages regarding status of the operation +.It +Reboot the machine +.El +.Sh BOOT OPTIONS +Options are controlled by setting values in +.Pa /boot/device.hints . +.Pp +They are: +.Bl -tag -width indent +.It Va hint.ocs_fc.N.initiator +Enable initiator functionality. +Default 1 (enabled), 0 to disable. +.It Va hint.ocs_fc.N.target +Enable target functionality. +Default 1 (enabled), 0 to disable. +.It Va hint.ocs_fc.N.topology +Topology: 0 for Auto, 1 for NPort only, 2 for Loop only. +.It Va hint.ocs_fc.N.speed +Link speed in megabits per second. +Possible values include: +0 Auto-speed negotiation (default), 4000 (4GFC), 8000 (8GFC), 16000 (16GFC). +.El +.Sh SYSCTL OPTIONS +.Bl -tag -width indent +.It Va dev.ocs_fc.N.port_state +Port state (read/write). +Valid values are +.Li online +and +.Li offline . +.It Va dev.ocs_fc.N.wwpn +World Wide Port Name (read/write). +.It Va dev.ocs_fc.N.wwnn +World Wide Node Name (read/write). +.It Va dev.ocs_fc.N.fwrev +Firmware revision (read-only). +.It Va dev.ocs_fc.N.sn +Adapter serial number (read-only). +.It Va dev.ocs_fc.N.configured_speed +Configured Port Speed (read/write). +Valid values are: +0 Auto-speed negotiation (default), 4000 (4GFC), 8000 (8GFC), 16000 (16GFC). +.It Va dev.ocs_fc.N.configured_topology +Configured Port Topology (read/write). +Valid values are: +0-Auto; 1-NPort; 2-Loop. +.It Va dev.ocs_fc.N.current_speed +Current Port Speed (read-only). +.It Va dev.ocs_fc.N.current_topology +Current Port Topology (read-only). +.El +.Sh SUPPORT +For general information and support, +go to the Broadcom website at: +.Pa http://www.broadcom.com/ +or E-Mail at +.Pa ocs-driver-team.pdl@broadcom.com . +.Sh SEE ALSO +.Xr ifconfig 8 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Broadcom . diff --git a/static/freebsd/man4/ohci.4 b/static/freebsd/man4/ohci.4 new file mode 100644 index 00000000..f8b7605f --- /dev/null +++ b/static/freebsd/man4/ohci.4 @@ -0,0 +1,86 @@ +.\" Copyright (c) 1999 +.\" Nick Hibma . 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 December 24, 2020 +.Dt OHCI 4 +.Os +.Sh NAME +.Nm ohci +.Nd OHCI USB Host Controller driver +.Sh SYNOPSIS +.Cd "device ohci" +.Sh DESCRIPTION +The +.Nm +driver provides support for OHCI-type PCI based USB controllers. +.Sh HARDWARE +The +.Nm +driver supports all OHCI v1.0 compliant controllers including: +.Pp +.Bl -bullet -compact +.It +AcerLabs M5237 (Aladdin-V) +.It +AMD-756 +.It +OPTi 82C861 (FireLink) +.It +NEC uPD 9210 +.It +CMD Tech 670 (USB0670) +.It +CMD Tech 673 (USB0673) +.It +NVIDIA nForce3 +.El +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va hw.usb.ohci.debug +Debug output level, where 0 is debugging disabled and larger values increase +debug message verbosity. +Default is 0. +.El +.Sh SEE ALSO +.Xr ehci 4 , +.Xr uhci 4 , +.Xr xhci 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 3.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Lennart Augustsson Aq Mt augustss@carlstedt.se +for the +.Nx +project. diff --git a/static/freebsd/man4/openfirm.4 b/static/freebsd/man4/openfirm.4 new file mode 100644 index 00000000..6c21c004 --- /dev/null +++ b/static/freebsd/man4/openfirm.4 @@ -0,0 +1,292 @@ +.\"- +.\" Copyright (c) 1992, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This software was developed by the Computer Systems Engineering group +.\" at Lawrence Berkeley Laboratory under DARPA contract BG 91-66 and +.\" contributed to Berkeley. +.\" +.\" 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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. +.\" from: OpenBSD: openprom.4,v 1.9 2004/03/22 22:07:21 miod Exp +.\" +.\"- +.\" Copyright (c) 2005 Marius Strobl +.\" 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 ``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 January 16, 2021 +.Dt OPENFIRM 4 +.Os +.Sh NAME +.Nm openfirm +.Nd "Open Firmware interface" +.Sh SYNOPSIS +.In sys/types.h +.In sys/ioctl.h +.In dev/ofw/openfirmio.h +.Sh DESCRIPTION +The +.Pa /dev/openfirm +device is an interface to the +.Tn Open Firmware +device tree. +This interface is highly stylized. +It uses +.Xr ioctl 2 +calls for all operations. +These calls refer to the nodes in the +.Tn Open Firmware +device tree. +The nodes are represented by package handles, +which are simply integer values describing data areas. +Occasionally a package handle of 0 may be used or returned instead, +as described below. +.Pp +The calls that only take and/or return the package handle of a node +use a pointer to a +.Vt phandle_t +for this purpose. +The others use a pointer to a +.Vt "struct ofiocdesc" +descriptor, +which has the following definition: +.Bd -literal +struct ofiocdesc { + phandle_t of_nodeid; + int of_namelen; + const char *of_name; + int of_buflen; + char *of_buf; +}; +.Ed +.Pp +The +.Va of_nodeid +member is the package handle of the node that is passed in or returned. +Strings are passed in via the +.Va of_name +member of +.Va of_namelen +length. +The maximum accepted length of +.Va of_name +is +.Dv OFIOCMAXNAME . +The +.Va of_buf +member is used to return strings except for the +.Dv OFIOCSET +call where it is also used to pass in a string. +In the latter case the maximum accepted length of +.Va of_buf +is +.Dv OFIOCMAXVALUE . +Generally, +.Va of_buf +works in a value-result fashion. +At entry to the +.Xr ioctl 2 +call, +.Va of_buflen +is expected to reflect the buffer size. +On return, +.Va of_buflen +is updated to reflect the buffer contents. +.Pp +The following +.Xr ioctl 2 +calls are supported: +.Bl -tag -width ".Dv OFIOCGETOPTNODE" +.It Dv OFIOCGETOPTNODE +Uses a +.Vt phandle_t . +Takes nothing and returns the package handle of the +.Pa /options +node. +.It Dv OFIOCGETNEXT +Uses a +.Vt phandle_t . +Takes the package handle of a node and returns the package handle of the next +node in the +.Tn Open Firmware +device tree. +The node following the last node has a package handle of 0. +The node following the node with the package handle of 0 is the first node. +.It Dv OFIOCGETCHILD +Uses a +.Vt phandle_t . +Takes the package handle of a node and returns the package handle of the first +child of that node. +This child may have siblings. +These can be determined by using +.Dv OFIOCGETNEXT . +If the node does not have a child, +a package handle of 0 is returned. +.It Dv OFIOCGET +Uses a +.Vt "struct ofiocdesc" . +Takes the package handle of a node and the name of a property. +Returns the property value and its length. +If no such property is associated with that node, +the length of the value is set to \-1. +If the named property exists but has no value, +the length of the value is set to 0. +.It Dv OFIOCGETPROPLEN +Uses a +.Vt "struct ofiocdesc" . +Takes the package handle of a node and the name of a property. +Returns the length of the property value. +This call is the same as +.Dv OFIOCGET +except that only the length of the property value is returned. +It can be used to determine whether a node has a particular property or whether +a property has a value without the need to provide memory for storing the value. +.It Dv OFIOCSET +Uses a +.Vt "struct ofiocdesc" . +Takes the package handle of a node, +the name of a property and a property value. +Returns the property value and the length that actually have been written. +The +.Tn Open Firmware +may choose to truncate the value if it is too long or write a valid value +instead if the given value is invalid for the particular property. +Therefore the returned value should be checked. +The +.Tn Open Firmware +may also completely refuse to write the given value to the property. +In this case +.Er EINVAL +is returned. +.It Dv OFIOCNEXTPROP +Uses a +.Vt "struct ofiocdesc" . +Takes the package handle of a node and the name of a property. +Returns the name and the length of the next property of the node. +If the property referenced by the given name is the last property of the node, +.Er ENOENT +is returned. +.It Dv OFIOCFINDDEVICE +Uses a +.Vt "struct ofiocdesc" . +Takes the name or alias name of a device node. +Returns package handle of the node. +If no matching node is found, +.Er ENOENT +is returned. +.El +.Sh FILES +.Bl -tag -width ".Pa /dev/openfirm" +.It Pa /dev/openfirm +Open Firmware interface node +.El +.Sh DIAGNOSTICS +The following may result in rejection of an operation: +.Bl -tag -width Er +.It Bq Er EBADF +The requested operation requires permissions not specified at the call to +.Fn open . +.It Bq Er EINVAL +The given package handle is not 0 and does not correspond to any valid node, +or the given package handle is 0 where 0 is not allowed. +.It Bq Er ENAMETOOLONG +The given name or value exceeds the maximum allowed length of +.Dv OFIOCMAXNAME +and +.Dv OFIOCMAXVALUE +bytes respectively. +.El +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr ofwdump 8 +.Rs +.%Q "IEEE Standards Organization" +.%B "IEEE Std 1275-1994:" +.%B "IEEE Standard for Boot Firmware (Initialization Configuration) Firmware:" +.%B Core Requirements and Practices" +.%O ISBN 1-55937-426-8 +.Re +.Sh HISTORY +The +.Nm +interface first appeared in +.Nx 1.6 . +The first +.Fx +version to include it was +.Fx 5.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +interface was ported to +.Fx +by +.An Thomas Moestl Aq Mt tmm@FreeBSD.org . +This manual page was written by +.An Marius Strobl Aq Mt marius@FreeBSD.org +based on the +.Ox +manual page for +.Xr openprom 4 . +.Sh CAVEATS +Due to limitations within +.Tn Open Firmware +itself, +these functions run at elevated priority and may adversely affect system +performance. +.Pp +For at least the +.Pa /options +node the property value passed in to the +.Dv OFIOCSET +call has to be null-terminated and the value length passed in has to include +the terminating +.Ql \e0 . +However, as with the +.Dv OFIOCGET +call, +the returned value length does not include the terminating +.Ql \e0 . diff --git a/static/freebsd/man4/orm.4 b/static/freebsd/man4/orm.4 new file mode 100644 index 00000000..e691c610 --- /dev/null +++ b/static/freebsd/man4/orm.4 @@ -0,0 +1,45 @@ +.\" Copyright (c) 2000 Nikolai Saoukh +.\" 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 December 15, 2000 +.Dt ORM 4 +.Os +.Sh NAME +.Nm orm +.Nd ISA I/O space option ROM(s) driver +.Sh SYNOPSIS +.Nm +is automatically included on all systems that have an ISA bus. +.Sh DESCRIPTION +The driver scans at boot time the ISA I/O memory space for option +ROM(s) and claims them. +Other drivers are thus precluded from using ISA I/O memory that is on +top of an option ROM. +.Sh AUTHORS +This +manual page was written by +.An Nikolai Saoukh Aq Mt nms@otdel-1.org . +.Sh BUGS +Due to the implementation of the resource manager, +other drivers cannot attach to the option ROM address range. diff --git a/static/freebsd/man4/ossl.4 b/static/freebsd/man4/ossl.4 new file mode 100644 index 00000000..ce080cf2 --- /dev/null +++ b/static/freebsd/man4/ossl.4 @@ -0,0 +1,115 @@ +.\" Copyright (c) 2020 Netflix, Inc +.\" +.\" 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, +.\" without modification. +.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer +.\" similar to the "NO WARRANTY" disclaimer below ("Disclaimer") and any +.\" redistribution must be conditioned upon including a substantially +.\" similar Disclaimer requirement for further binary redistribution. +.\" +.\" NO WARRANTY +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTIBILITY +.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL +.\" THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR 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 DAMAGES. +.\" +.Dd May 4, 2023 +.Dt OSSL 4 +.Os +.Sh NAME +.Nm ossl +.Nd "driver using OpenSSL assembly routines" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device crypto" +.Cd "device cryptodev" +.Cd "device ossl" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ossl_load="YES" +.Ed +.Sh DESCRIPTION +The OpenSSL distribution includes architecture-specific +implementations for some commonly used cryptographic algorithms. +This driver adds a wrapper around these routines permitting them to be +used by in-kernel cryptography consumers such as kernel TLS and IPsec. +.Pp +The +.Nm +driver includes architecture-specific implementations for the following +architectures: +.Pp +.Bl -bullet -compact +.It +arm64 +.It +amd64 +.It +i386 +.El +.Pp +The +.Nm +driver includes support for the following algorithms: +.Pp +.Bl -bullet -compact +.It +AES-CBC +.It +AES-GCM (amd64 only) +.It +ChaCha20 +.It +ChaCha20-Poly1305 (RFC 8439) +.It +Poly1305 +.It +SHA1 +.It +SHA1-HMAC +.It +SHA2-224 +.It +SHA2-224-HMAC +.It +SHA2-256 +.It +SHA2-256-HMAC +.It +SHA2-384 +.It +SHA2-384-HMAC +.It +SHA2-512 +.It +SHA2-512-HMAC +.El +.Sh SEE ALSO +.Xr crypto 4 , +.Xr intro 4 , +.Xr ipsec 4 , +.Xr crypto 7 , +.Xr crypto 9 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 13.0 . diff --git a/static/freebsd/man4/otus.4 b/static/freebsd/man4/otus.4 new file mode 100644 index 00000000..06f73bfe --- /dev/null +++ b/static/freebsd/man4/otus.4 @@ -0,0 +1,188 @@ +.\"- +.\" SPDX-License-Identifier: ISC +.\" +.\" Copyright (c) 2015 Adrian Chadd +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd November 10, 2024 +.Dt OTUS 4 +.Os +.Sh NAME +.Nm otus +.Nd Atheros AR9170 USB IEEE 802.11a/b/g/n wireless network driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ehci" +.Cd "device uhci" +.Cd "device ohci" +.Cd "device usb" +.Cd "device otus" +.Cd "device wlan" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, +place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_otus_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports USB 2.0 wireless network devices based on the Atheros +AR9170 chipset. +.Pp +The Atheros AR9170 is a draft-802.11n adapter that uses an external +radio to operate in either 2.4GHz only or 2.4GHz and 5GHz. +.Pp +The AR9101 radio supports 1T1R operation in 2GHz only. +.Pp +The AR9102 radio supports 2T2R operation in 2GHz only. +.Pp +The AR9104 radio supports 2T2R operation both 2GHz and 5GHz. +.Pp +These are the modes the +.Nm +driver can operate in: +.Bl -tag -width "IBSS-masterXX" +.It BSS mode +Also known as +.Em infrastructure +mode, this is used when associating with an access point, through +which all traffic passes. +This mode is the default. +.El +.Pp +The +.Nm +driver can be configured to use +Wired Equivalent Privacy (WEP) or +Wi-Fi Protected Access (WPA-PSK and WPA2-PSK). +WPA is the de facto encryption standard for wireless networks. +It is strongly recommended that WEP +not be used as the sole mechanism +to secure wireless communication, +due to serious weaknesses in it. +.Pp +The +.Nm +driver can be configured at runtime with +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver provides support for Atheros AR9170 USB IEEE 802.11b/g/n +wireless network adapters, including: +.Pp +.Bl -bullet -offset indent -compact +.It +3Com 3CRUSBN275 +.It +Arcadyan WN7512 +.\" .It AVM FRITZ!WLAN USB Stick N +.It +CACE AirPcap \&Nx +.It +D-Link DWA-130 rev \&D1 +.It +D-Link DWA-160 rev A1 +.It +D-Link DWA-160 rev A2 +.It +IO-Data WN-GDN/US2 +.It +NEC Aterm WL300NU-G +.It +Netgear WNDA3100 +.It +Netgear WN111 v2 +.It +Planex GW-US300 +.It +SMC Networks SMCWUSB-N2 +.It +TP-Link TL-WN821N v1, v2 +.It +Ubiquiti SR71 USB +.It +Unex DNUA-81 +.It +Z-Com UB81 +.It +Z-Com UB82 +.It +ZyXEL NWD-271N +.El +.Sh FILES +The driver needs at least version 1.0 of the following firmware files, +which is loaded when an interface is attached: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It Pa /boot/kernel/otusfw-init.ko +.It Pa /boot/kernel/otusfw-main.ko +.El +.Sh EXAMPLES +Join an existing BSS network (i.e., connect to an access point): +.Pp +.Dl ifconfig wlan create wlandev otus0 inet 192.0.2.20/24 +.Pp +Join a specific BSS network with network name +.Ar my_net : +.Pp +.Dl ifconfig wlan create wlandev otus0 ssid my_net up +.Pp +Join a specific BSS network with 64-bit WEP encryption: +.Bd -literal -offset indent +ifconfig wlan create wlandev otus0 ssid my_net \e + wepmode on wepkey 0x1234567890 weptxkey 1 up +.Ed +.Sh DIAGNOSTICS +.Bl -diag +.It "%s: failed load firmware of file otusfw-main" +For some reason, the driver was unable to read the microcode file from the +filesystem. +The file might be missing or corrupted. +.El +.Sh SEE ALSO +.Xr intro 1 , +.Xr netintro 4 , +.Xr otusfw 4 , +.Xr usb 4 , +.Xr wlan 4 , +.Xr arp 8 , +.Xr hostapd 8 , +.Xr ifconfig 8 , +.Xr wpa_supplicant 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Ox 4.6 +and +.Fx 11 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Damien Bergamini Aq Mt damien@openbsd.org +and ported by +.An Adrian Chadd Aq Mt adrian@freebsd.org . +.Sh CAVEATS +The +.Nm +driver only supports 802.11a/b/g operations. +802.11n operation is not supported at this time. diff --git a/static/freebsd/man4/otusfw.4 b/static/freebsd/man4/otusfw.4 new file mode 100644 index 00000000..8810673e --- /dev/null +++ b/static/freebsd/man4/otusfw.4 @@ -0,0 +1,44 @@ +.\" Copyright (c) 2015 Adrian Chadd +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd September 25, 2015 +.Dt OTUSFW 4 +.Os +.Sh NAME +.Nm otusfw +.Nd "Firmware Module for AR9170 driver" +.Sh SYNOPSIS +To compile this module into the kernel, place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device otusfw" +.Ed +.Pp +This will include the firmware image, AR9170, inside the kernel. +.Xr otus 4 +will load the image into the chip. +.Pp +Alternatively, to load the firmware images as a module at boot time, place +the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +otusfw_init_load="YES" +otusfw_main_load="YES" +.Ed +.Sh DESCRIPTION +This module provides the firmware for the Atheros AR9170 based +USB WiFi adapters. +.Sh SEE ALSO +.Xr otus 4 , +.Xr firmware 9 diff --git a/static/freebsd/man4/ovpn.4 b/static/freebsd/man4/ovpn.4 new file mode 100644 index 00000000..3481dd0d --- /dev/null +++ b/static/freebsd/man4/ovpn.4 @@ -0,0 +1,54 @@ +.\" Copyright (c) 2022 Rubicon Communications, LLC ("Netgate") +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 22, 2022 +.Dt OVPN 4 +.Os +.Sh NAME +.Nm ovpn +.Nd OpenVPN DCO driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ovpn" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_ovpn_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +device driver provides support for OpenVPN DCO. +DCO, or Data Channel Offload, moves the OpenVPN data path into the kernel. +This can improve performance. +.Pp +The +.Nm +interface is created automatically by the OpenVPN daemon. +It requires no configuration other than that done by OpenVPN. diff --git a/static/freebsd/man4/ow.4 b/static/freebsd/man4/ow.4 new file mode 100644 index 00000000..9b2f77d8 --- /dev/null +++ b/static/freebsd/man4/ow.4 @@ -0,0 +1,57 @@ +.\" +.\" Copyright (c) 2015 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. 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 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 20, 2015 +.Dt OW 4 +.Os +.Sh NAME +.Nm ow +.Nd Dallas Semiconductor 1-Wire bus +.Sh SYNOPSIS +.Cd device ow +.Sh DESCRIPTION +The +.Nm +module implements the Dallas Semiconductor 1-Wire bus. +It attaches to the +.Xr owc 4 +driver, which implements the low-level signaling of the +1-Wire bus. +.Sh SEE ALSO +.Xr ow_temp 4 , +.Xr owc 4 , +.Xr owll 9 , +.Xr own 9 +.Sh LEGAL +.Tn 1-Wire +is a registered trademark of Maxim Integrated Products, Inc. +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 11.0 . +.Sh AUTHORS +The +.Nm +device driver and this manual page were written by +.An Warner Losh . diff --git a/static/freebsd/man4/ow_temp.4 b/static/freebsd/man4/ow_temp.4 new file mode 100644 index 00000000..5afce6bd --- /dev/null +++ b/static/freebsd/man4/ow_temp.4 @@ -0,0 +1,149 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2015 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. 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 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 November 22, 2024 +.Dt OW_TEMP 4 +.Os +.Sh NAME +.Nm ow_temp +.Nd Dallas Semiconductor 1-Wire Temperature sensor +.Sh SYNOPSIS +.Cd device ow_temp +.Sh DESCRIPTION +The +.Nm +module supports many of the 1-Wire temperature sensors. +.Pp +The sensor is read periodically and the results returned via a +.Xr sysctl 3 +as described below. +.Sh HARDWARE +The +.Nm +driver supports the following temperature sensors: +.Pp +.Bl -column "DS18S20" "Econo 1-Wire Digital Thermometer" -compact +.It DS1820 Ta 1-Wire Digital Thermometer +.It DS18S20 Ta High-Precision 1-Wire Digital Thermometer +.It DS18B20 Ta Programmable Resolution 1-Wire Digital Thermometer +.It DS1822 Ta Econo 1-Wire Digital Thermometer +.It DS1825 Ta Programmable Resolution 1-Wire Digital Thermometer with 4-bit ID +.It MAX31820 Ta 1-Wire, Parasite-Power, Ambient Temperature Sensor +.El +.Pp +The driver supports Family codes 0x10, 0x22, 0x28, and 0x3b. +.Sh SYSCTL +The +.Nm +driver reports data via +.Xr sysctl 8 +entries in the device's node in the +.Xr sysctl 8 +tree: +.Bl -tag -width "reading_interval" +.It temperature +The last temperature read, in milli-Kelvin. +.It badcrc +The number of CRC errors in reading the temperature from the +device. +Some CRC errors are to be expected. +High rates of CRC errors, however, generally indicate a noisy +environment, cabling issues, or too many devices on the bus. +.It badread +The number of times a non-CRC error was encountered reading the temperature +from the card. +This type of error is very rare. +.It reading_interval +The time, in ticks, between successive reads of the sensor. +.It parasite +This item is non-zero when the device is connected using its parasitic +power mode. +It can also indicate a wiring error. +.El +.Pp +Temperatures are reported in milli-Kelvin, even though the absolute +accuracy is around 0.2 degrees for the good devices and around 1 +degree for cheaper devices. +The devices report in steps of 0.0625 degrees. +The driver preserves the precision of the device's measurements +in its +.Xr sysctl 8 +reports. +These devices often have a much higher relative accuracy and +repeatability than their absolute accuracy. +This makes them well suited for control loops that strive for +stability and become possible if the full precision is preserved. +.Sh SEE ALSO +.Xr ow 4 , +.Xr owc 4 , +.Xr sysctl 8 , +.Xr owll 9 , +.Xr own 9 +.Sh LEGAL +.Tn 1-Wire +is a registered trademark of Maxim Integrated Products, Inc. +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 11.0 . +.Sh AUTHORS +The +.Nm +device driver and this manual page were written by +.An Warner Losh . +.Sh BUGS +The parasitic mode of the devices does not work. +It requires support from the +.Xr owc 4 +driver that is unimplemented. +.Pp +The ID bits from the +.Em DS1825 +are not recognized or reported. +.Pp +The type of the device is not reported via +.Xr sysctl 8 . +.Pp +Alarm mode is not supported. +It is not possible to set the low and high alarm temperatures. +.Pp +There is no way to write to the EEPROM. +.Pp +.Dq Convert Temperature +requests are sent directly to the device. +There is no way to use the broadcast ability of the 1-Wire bus to do +all the conversions in parallel. +.Pp +It is not possible to set the precision on those devices that support +it. +.Pp +The time to convert is fixed at 1 second, even though some devices are +faster. +.Pp +There is no character device to supply a stream of readings to a +program. +Programs interested in the temperature must poll the sysctl to get the +temperature. diff --git a/static/freebsd/man4/owc.4 b/static/freebsd/man4/owc.4 new file mode 100644 index 00000000..95269f97 --- /dev/null +++ b/static/freebsd/man4/owc.4 @@ -0,0 +1,110 @@ +.\" +.\" Copyright (c) 2015 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. 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 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 June 26, 2019 +.Dt OWC 4 +.Os +.Sh NAME +.Nm owc +.Nd Dallas Semiconductor 1-Wire Controller +.Sh SYNOPSIS +.Cd device owc +.Sh DESCRIPTION +The +.Nm +module implements Dallas Semiconductor 1-Wire signaling. +It attaches the +.Xr ow 4 +driver 1-Wire bus protocol. +The +.Nm +device implements the Link Layer of the 1-Wire bus protocol stack. +.Pp +Bit banging a pin on a +.Xr gpiobus 4 +is the only supported controller. +Both standard and overdrive transfer timings are implemented. +Strong pull-up functionality needed to support parasitic mode is not +implemented. +.Pp +To enable 1-Wire for FDT systems requires modifying the DTS for your +board to add something like: +.Bd -literal +/ { + ... + onewire { + compatible = "w1-gpio"; + gpios = <&gpio 4 1>; + }; + ... +}; +.Ed +.Pp +The gpios property describes the GPIO pin the 1-Wire bus is connected +to. +For more details about the +.Va gpios +property, please consult +.Pa /usr/src/sys/dts/bindings-gpio.txt . +.Pp +On a +.Xr device.hints 5 +based system these values are required for the +.Nm : +.Bl -tag -width ".Va hint.owc.%d.atXXX" +.It Va hint.owc.%d.at +The +.Nm gpiobus +you are attaching to. +.It Va hint.owc.%d.pins +This is a bitmask that defines a pin on the +.Nm gpiobus +that is to be used for the 1-Wire bus. +For instance, to configure pin 10, use the bitmask of 0x400. +Please note that this mask should have only one bit set +(any other bits - i.e., pins - will be ignored). +.El +.Sh SEE ALSO +.Xr gpiobus 4 , +.Xr ow 4 , +.Xr ow_temp 4 , +.Xr owll 9 , +.Xr own 9 +.Sh LEGAL +.Tn 1-Wire +is a registered trademark of Maxim Integrated Products, Inc. +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 11.0 . +.Sh AUTHORS +The +.Nm +device driver and this manual page were written by +.An Warner Losh . +.Sh CAVEATS +The gpio driver implements timing by busy waiting, which can cause a +high load on slower systems. +.Sh BUGS +Overdrive mode has not actually been tested. diff --git a/static/freebsd/man4/p9fs.4 b/static/freebsd/man4/p9fs.4 new file mode 100644 index 00000000..a49053d4 --- /dev/null +++ b/static/freebsd/man4/p9fs.4 @@ -0,0 +1,127 @@ +.\" +.\" Copyright (c) 2022-present Doug Rabson +.\" 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 DOCUMENTATION 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 November 7, 2024 +.Dt P9FS 4 +.Os +.Sh NAME +.Nm p9fs +.Nd "9P file system" +.Sh SYNOPSIS +To use this filesystem, +either add the following to the kernel config: +.Bd -ragged -offset indent +.Cd "options P9FS" +.Cd "device virtio_p9fs" +.Ed +.Pp +Alternatively, load the driver as a kernel module, +either at boot time by adding the following to +.Xr loader.conf 5 : +.Bd -literal -offset indent +virtio_p9fs_load="YES" +.Ed +.Pp +or on system startup using the command: +.Pp +.Dl "# sysrc kld_list+=virtio_p9fs" +.Sh DESCRIPTION +The +.Nm +filesystem uses the 9P protocol to mount a host file system directory +into a +.Xr bhyve 8 +guest. +Multiple host directories can be accessed using the +.Xr bhyve 8 +virtio-9p virtual PCI device. +Each device is configured with a share name and a host directory path. +The share name can be used with +.Xr mount 8 +to mount the host directory in the guest: +.Pp +.Dl "# mount -t p9fs mysharename /mnt" +.Pp +Host directories can be mounted on system startup using +.Xr fstab 5 +like this: +.Pp +.Bd -literal -offset indent +mysharename /mnt p9fs rw 0 0 +.Ed +.Pp +Using +.Nm +as a root file system is supported by adding the following to +.Xr loader.conf 5 : +.Bd -literal -offset indent +vfs.root.mountfrom="p9fs:mysharename" +.Ed +.Sh LIMITATIONS +The 9P protocol relies on stateful file opens +which map protocol-level FIDs to host file descriptors. +The FreeBSD vnode interface doesn't support this and +.Nm +uses heuristics to guess the right FID to use for file operations. +.Pp +This can be confused by privilege lowering and +does not guarantee that the FID created for a +given file open is always used, +even if the calling process is using the file descriptor from +the original open call. +.Pp +In particular, accessing unlinked files using open file descriptor +may not work correctly. +If +.Nm +is the root filesystem, +it is recommended to use with +.Xr tmpfs 5 +to ensure that temporary files created in +.Pa /tmp +or +.Pa /var/tmp +have the expected semantics. +.Sh SEE ALSO +.Xr fstab 5 +.Sh HISTORY +The 9P protocol first appeared in the Plan 9 operating system. +More recently, the protocol has been widely used with virtual machines +to allow the use of host file resources inside a guest VM. +.Sh AUTHORS +This is derived from software released by Juniper Networks, Inc. +with many improvements and fixes from +.An Steve Wills . +.Pp +This manual page was written by +.An -nosplit +.An Doug Rabson Aq Mt dfr@FreeBSD.org . +.Sh BUGS +A better name for this filesystem would be +.Ar 9pfs +but for technical reasons, +the names of filesystems must be valid C identifiers. +As a compromise, +the filesystem is named +.Nm . diff --git a/static/freebsd/man4/padlock.4 b/static/freebsd/man4/padlock.4 new file mode 100644 index 00000000..cf362e58 --- /dev/null +++ b/static/freebsd/man4/padlock.4 @@ -0,0 +1,96 @@ +.\" Copyright (c) 2005 Christian Brueffer +.\" 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 29, 2020 +.Dt PADLOCK 4 +.Os +.Sh NAME +.Nm padlock +.Nd "driver for the cryptographic functions and RNG in VIA C3, C7 and Eden processors" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device crypto" +.Cd "device padlock" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +padlock_load="YES" +.Ed +.Sh DESCRIPTION +The C3 and Eden processor series from VIA include hardware acceleration for +AES. +The C7 series includes hardware acceleration for AES, SHA1, SHA256 and RSA. +All of the above processor series include a hardware random number generator. +.Pp +The +.Nm +driver registers itself to accelerate AES operations and, if available, HMAC/SHA1 +and HMAC/SHA256 for +.Xr crypto 4 . +It also registers itself to accelerate other HMAC algorithms, although +there is no hardware acceleration for those algorithms. +This is only needed so +.Nm +can work with +.Xr ipsec 4 . +.Pp +The hardware random number generator supplies data for the kernel +.Xr random 4 +subsystem. +.Sh SEE ALSO +.Xr crypt 3 , +.Xr crypto 4 , +.Xr intro 4 , +.Xr ipsec 4 , +.Xr random 4 , +.Xr crypto 7 , +.Xr crypto 9 +.Sh HISTORY +The +.Nm +driver first appeared in +.Ox . +The first +.Fx +release to include it was +.Fx 6.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver with AES encryption support was written by +.An Jason Wright Aq Mt jason@OpenBSD.org . +It was ported to +.Fx +and then extended to support SHA1 and SHA256 +by +.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . +This manual page was written by +.An Christian Brueffer Aq Mt brueffer@FreeBSD.org . diff --git a/static/freebsd/man4/pass.4 b/static/freebsd/man4/pass.4 new file mode 100644 index 00000000..0a5a58c2 --- /dev/null +++ b/static/freebsd/man4/pass.4 @@ -0,0 +1,240 @@ +.\" +.\" Copyright (c) 1998, 1999 Kenneth D. Merry. +.\" 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. 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 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 May 3, 2017 +.Dt PASS 4 +.Os +.Sh NAME +.Nm pass +.Nd CAM application passthrough driver +.Sh SYNOPSIS +.Cd device pass +.Sh DESCRIPTION +The +.Nm +driver provides a way for userland applications to issue CAM CCBs to the +kernel. +.Pp +Since the +.Nm +driver allows direct access to the CAM subsystem, system administrators +should exercise caution when granting access to this driver. +If used +improperly, this driver can allow userland applications to crash a machine +or cause data loss. +.Pp +The +.Nm +driver attaches to every +.Tn SCSI +and +.Tn ATA +device found in the system. +Since it attaches to every device, it provides a generic means of accessing +.Tn SCSI +and +.Tn ATA +devices, and allows the user to access devices which have no +"standard" peripheral driver associated with them. +.Sh KERNEL CONFIGURATION +It is only necessary to configure one +.Nm +device in the kernel; +.Nm +devices are automatically allocated as +.Tn SCSI +and +.Tn ATA +devices are found. +.Sh IOCTLS +.Bl -tag -width 5n +.It CAMIOCOMMAND union ccb * +This ioctl takes most kinds of CAM CCBs and passes them through to the CAM +transport layer for action. +Note that some CCB types are not allowed +through the passthrough device, and must be sent through the +.Xr xpt 4 +device instead. +Some examples of xpt-only CCBs are XPT_SCAN_BUS, +XPT_DEV_MATCH, XPT_RESET_BUS, XPT_SCAN_LUN, XPT_ENG_INQ, and XPT_ENG_EXEC. +These CCB types have various attributes that make it illogical or +impossible to service them through the passthrough interface. +.Pp +If the user would like the kernel to do error recovery, the +.Dv CAM_PASS_ERR_RECOVER +flag must be set on the CCB, and the retry_count field set to the number +of retries. +.It CAMGETPASSTHRU union ccb * +This ioctl takes an XPT_GDEVLIST CCB, and returns the passthrough device +corresponding to the device in question. +Although this ioctl is available through the +.Nm +driver, it is of limited use, since the caller must already know that +the device in question is a passthrough device if they are issuing this +ioctl. +It is probably more useful to issue this ioctl through the +.Xr xpt 4 +device. +.It CAMIOQUEUE union ccb * +Queue a CCB to the +.Nm +driver to be executed asynchronously. +The caller may use +.Xr select 2 , +.Xr poll 2 +or +.Xr kevent 2 +to receive notification when the CCB has completed. +.Pp +This ioctl takes most CAM CCBs, but some CCB types are not allowed through +the pass device, and must be sent through the +.Xr xpt 4 +device instead. +Some examples of xpt-only CCBs are XPT_SCAN_BUS, +XPT_DEV_MATCH, XPT_RESET_BUS, XPT_SCAN_LUN, XPT_ENG_INQ, and XPT_ENG_EXEC. +These CCB types have various attributes that make it illogical or +impossible to service them through the passthrough interface. +.Pp +Although the +.Dv CAMIOQUEUE +ioctl is not defined to take an argument, it does require a +pointer to a union ccb. +It is not defined to take an argument to avoid an extra malloc and copy +inside the generic +.Xr ioctl 2 +handler. +.Pp +The completed CCB will be returned via the +.Dv CAMIOGET +ioctl. +An error will only be returned from the +.Dv CAMIOQUEUE +ioctl if there is an error allocating memory for the request or copying +memory from userland. +All other errors will be reported as standard CAM CCB status errors. +Since the CCB is not copied back to the user process from the pass driver +in the +.Dv CAMIOQUEUE +ioctl, the user's passed-in CCB will not be modified. +This is the case even with immediate CCBs. +Instead, the completed CCB must be retrieved via the +.Dv CAMIOGET +ioctl and the status examined. +.Pp +Multiple CCBs may be queued via the +.Dv CAMIOQUEUE +ioctl at any given time, and they may complete in a different order than +the order that they were submitted. +The caller must take steps to identify CCBs that are queued and completed. +The +.Dv periph_priv +structure inside struct ccb_hdr is available for userland use with the +.Dv CAMIOQUEUE +and +.Dv CAMIOGET +ioctls, and will be preserved across calls. +Also, the periph_links linked list pointers inside struct ccb_hdr are +available for userland use with the +.Dv CAMIOQUEUE +and +.Dv CAMIOGET +ioctls and will be preserved across calls. +.Pp +If the user would like the kernel to do error recovery, the +.Dv CAM_PASS_ERR_RECOVER +flag must be set on the CCB, and the retry_count field set to the number +of retries. +.It CAMIOGET union ccb * +Retrieve completed CAM CCBs queued via the +.Dv CAMIOQUEUE +ioctl. +An error will only be returned from the +.Dv CAMIOGET +ioctl if the +.Nm +driver fails to copy data to the user process or if there are no completed +CCBs available to retrieve. +If no CCBs are available to retrieve, +errno will be set to +.Dv ENOENT . +.Pp +All other errors will be reported as standard CAM CCB status errors. +.Pp +Although the +.Dv CAMIOGET +ioctl is not defined to take an argument, it does require a +pointer to a union ccb. +It is not defined to take an argument to avoid an extra malloc and copy +inside the generic +.Xr ioctl 2 +handler. +.Pp +The pass driver will report via +.Xr select 2 , +.Xr poll 2 +or +.Xr kevent 2 +when a CCB has completed. +One CCB may be retrieved per +.Dv CAMIOGET +call. +CCBs may be returned in an order different than the order they were +submitted. +So the caller should use the +.Dv periph_priv +area inside the CCB header to store pointers to identifying information. +.El +.Sh FILES +.Bl -tag -width /dev/passn -compact +.It Pa /dev/pass Ns Ar n +Character device nodes for the +.Nm +driver. +There should be one of these for each device accessed through the +CAM subsystem. +.El +.Sh DIAGNOSTICS +None. +.Sh SEE ALSO +.Xr kqueue 2 , +.Xr poll 2 , +.Xr select 2 , +.Xr cam 3 , +.Xr cam_cdbparse 3 , +.Xr cam 4 , +.Xr cd 4 , +.Xr ctl 4 , +.Xr da 4 , +.Xr sa 4 , +.Xr xpt 4 , +.Xr camcontrol 8 , +.Xr camdd 8 +.Sh HISTORY +The CAM passthrough driver first appeared in +.Fx 3.0 . +.Sh AUTHORS +.An Kenneth Merry Aq Mt ken@FreeBSD.org diff --git a/static/freebsd/man4/pca954x.4 b/static/freebsd/man4/pca954x.4 new file mode 100644 index 00000000..69836234 --- /dev/null +++ b/static/freebsd/man4/pca954x.4 @@ -0,0 +1,117 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2020 Andriy Gapon +.\" +.\" 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 November 13, 2021 +.Dt PCA954X 4 +.Os +.Sh NAME +.Nm pca954x +.Nd driver for PCA9548A I2C switch +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device pca954x" +.Cd "device iicmux" +.Cd "device iicbus" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +pca954x_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports the PCA9548A I2C bus switch and compatible chips such as +TCA9548A. +It automatically connects an upstream I2C bus to one of several downstream +buses as needed when slave devices on the downstream buses initiate I/O. +More information on the automatic switching behavior is available in +.Xr iicmux 4 . +.Sh FDT CONFIGURATION +On an +.Xr FDT 4 +based system, an +.Nm +device node is defined as a child node of its upstream I2C bus. +The children of the +.Nm +node are additional I2C buses, which will have their own I2C slave +devices described in their child nodes. +.Pp +The +.Nm +driver attaches to nodes where the +.Va compatible +property is set to one of +.Bl -bullet +.It +.Qq nxp,pca9548 +.El +.Pp +The +.Nm +driver supports the following optional properties in addition to the standard +I2C mux properties: +.Bl -tag -width i2c-mux-idle-disconnect +.It Va i2c-mux-idle-disconnect +if defined, forces the switch to disconnect all children in idle state. +.El +.Sh HINTS CONFIGURATION +On a +.Xr device.hints 5 +based system, these values are configurable for +.Nm : +.Bl -tag -width hint.pca954x..chip_type +.It Va hint.pca954x..at +The upstream +.Xr iicbus 4 +the +.Nm +instance is attached to. +.It Va hint.pca954x..chip_type +The type of the chip. +At present, only +.Qq pca9548 +is supported. +.El +.Pp +When configured via hints, the driver automatically adds an +.Xr iicbus 4 +instance for every downstream bus supported by the chip. +There is currently no way to indicate used versus unused channels. +.Sh SEE ALSO +.Xr iicbus 4 , +.Xr iicmux 4 +.Sh HISTORY +The +.Nm +driver and this manual page was written by +.An Andriy Gapon Aq Mt avg@FreeBSD.org . diff --git a/static/freebsd/man4/pccbb.4 b/static/freebsd/man4/pccbb.4 new file mode 100644 index 00000000..1c6cb204 --- /dev/null +++ b/static/freebsd/man4/pccbb.4 @@ -0,0 +1,179 @@ +.\" +.\" Copyright (c) 2002-2003 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. 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 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 21, 2004 +.Dt PCCBB 4 +.Os +.Sh NAME +.Nm pccbb +.Nd cardbus bridge driver +.Sh SYNOPSIS +.Cd device cbb +.Cd device pccard +.Cd device cardbus +.Cd device exca +.Sh DESCRIPTION +The +.Nm +driver implements the Yenta specification for CardBus bridges. +.Pp +The following PCI cardbus and pcmcia bridges are supported: +.Pp +.Bl -item -compact +.It +Cirrus Logic PD6832 +.It +Cirrus Logic PD6833 +.It +Cirrus Logic PD6834 +.Pp +.It +O2micro OZ6812 +.It +O2micro OZ6832 +.It +O2micro OZ6833 +.It +O2micro OZ6836 +.It +O2micro OZ6860 +.It +O2micro OZ6872 +.It +O2micro OZ6912 +.It +O2micro OZ6922 +.It +O2micro OZ6933 +.It +O2micro OZ6972 +.It +O2Micro OZ711E1 +.It +O2Micro OZ711M1 +.El +.Bl -item -compact +.It +Ricoh RL4C475 +.It +Ricoh RL4C476 +.It +Ricoh RL4C477 +.It +Ricoh RL4C478 +.Pp +.It +TI PCI-1031 +.It +TI PCI-1130 +.It +TI PCI-1131 +.It +TI PCI-1210 +.It +TI PCI-1211 +.It +TI PCI-1220 +.It +TI PCI-1221 +.It +TI PCI-1225 +.It +TI PCI-1250 +.It +TI PCI-1251 +.It +TI PCI-1251B +.It +TI PCI-1260 +.It +TI PCI-1260B +.It +TI PCI-1410 +.It +TI PCI-1420 +.It +TI PCI-1450 +.It +TI PCI-1451 +.It +TI PCI-1510 +.It +TI PCI-1515 +.It +TI PCI-1520 +.It +TI PCI-1530 +.It +TI PCI-1620 +.It +TI PCI-4410 +.It +TI PCI-4450 +.It +TI PCI-4451 +.It +TI PCI-4510 +.It +TI PCI-4520 +.It +TI PCI-[67]x[12]1 +.It +TI PCI-[67]x20 +.It +ENE CB710 +.It +ENE CB720 +.It +ENE CB1211 +.It +ENE CB1255 +.It +ENE CB1410 +.It +ENE CB1420 +.Pp +.It +Toshiba ToPIC95 +.It +Toshiba ToPIC95B +.It +Toshiba ToPIC97 +.It +Toshiba ToPIC100 +.El +.Sh TUNABLES +The driver supports the following tunable parameters, which may be +added to +.Pa /boot/loader.conf +or set via the +.Xr sysctl 8 +command: +.Bl -tag -width ".Cm hw.cbb.debug" -compact +.It Cm hw.cbb.debug +Non-zero values cause more verbose information to be printed to aid in +debugging problems with the bridge chipset. +.El +.Sh SEE ALSO +.Xr cardbus 4 , +.Xr exca 4 diff --git a/static/freebsd/man4/pcf.4 b/static/freebsd/man4/pcf.4 new file mode 100644 index 00000000..f54e8c5d --- /dev/null +++ b/static/freebsd/man4/pcf.4 @@ -0,0 +1,70 @@ +.\" Copyright (c) 1998, Nicolas Souchu +.\" 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 August 6, 1998 +.Dt PCF 4 +.Os +.Sh NAME +.Nm pcf +.Nd Philips I2C bus controller +.Sh SYNOPSIS +.Cd "device pcf" +.Pp +In +.Pa /boot/device.hints : +.Cd hint.pcf.0.at="isa" +.Cd hint.pcf.0.port="0x320" +.Cd hint.pcf.0.irq="5" +.Pp +For one or more iicbus busses: +.Cd "device iicbus" +.Sh DESCRIPTION +The +.Em pcf +driver provides support to the Philips PCF8584 I2C controller for the +.Xr iicbus 4 +system. +.Pp +The PCF8584 is an integrated circuit designed in CMOS technology which serves +as an interface between most standard parallel-bus +microcontrollers/microprocessors and the serial I2C-bus. +The PCF8584 +provides both master and slave functions. +Communication with I2C-bus is +carried out on a byte-wise basis using interrupt or polled handshake. +It +controls all the I2C-bus specific sequences, protocol, arbitration and timing. +The PCF8584 allows parallel-bus systems to communicate bidirectionally with +the I2C-bus. +.Sh SEE ALSO +.Xr iicbus 4 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 3.0 . +.Sh AUTHORS +This +manual page was written by +.An Nicolas Souchu . diff --git a/static/freebsd/man4/pcf8574.4 b/static/freebsd/man4/pcf8574.4 new file mode 100644 index 00000000..900302a4 --- /dev/null +++ b/static/freebsd/man4/pcf8574.4 @@ -0,0 +1,96 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2020 Andriy Gapon +.\" +.\" 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 November 6, 2021 +.Dt PCF8574 4 +.Os +.Sh NAME +.Nm pcf8574 +.Nd driver for the PCF8574 8-bit I2C IO expander +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device pcf8574" +.Cd "device gpio" +.Cd "device iicbus" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +pcf8574_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides +.Xr gpiobus 4 +control over 8 GPIO pins. +The pins are quasi-bidirectional. +Only low output can be actively driven. +High output is equivalent to input. +.Pp +On an +.Xr FDT 4 +based system the following properties must be set: +.Bl -tag -width "compatible" +.It Va compatible +Must be set to "nxp,pcf8574". +.It Va reg +The I2C address of +.Nm . +.El +.Pp +The DTS part for a +.Nm +device usually looks like: +.Bd -literal +/ { + + ... + pcf8574@27 { + compatible = "nxp,pcf8574"; + reg = <0x27>; + }; +}; +.Ed +.Sh SEE ALSO +.Xr fdt 4 , +.Xr gpiobus 4 , +.Xr iicbus 4 +.Sh HISTORY +The +.Nm +driver and this manual page was written by +.An Andriy Gapon Aq Mt avg@FreeBSD.org . +.Sh BUGS +The +.Nm +driver does not support the input change interrupt +that the hardware provides. diff --git a/static/freebsd/man4/pcf8591.4 b/static/freebsd/man4/pcf8591.4 new file mode 100644 index 00000000..9acaf650 --- /dev/null +++ b/static/freebsd/man4/pcf8591.4 @@ -0,0 +1,120 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2020 Andriy Gapon +.\" +.\" 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 November 6, 2021 +.Dt PCF8591 4 +.Os +.Sh NAME +.Nm pcf8591 +.Nd driver for the PCF8591 8-bit A/D and D/A converter +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device pcf8591" +.Cd "device iicbus" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +pcf8591_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports reading four inputs and setting one output over I2C. +The hardware supports configuring the input lines as: +.Bl -bullet +.It +four single-ended inputs +.It +three differential inputs (one input line is shared between all three inputs) +.It +two single-ended inputs and one differential input +.It +two differential inputs. +.El +.Pp +The +.Nm +driver reports data via +.Xr sysctl 8 +entries in the device's node in the +.Xr sysctl 8 +tree: +.Bl -tag -width inputs.%d +.It Va inputs.%d +The input level of the corresponding input in steps between 0 and 255. +Absolute voltage depends on an actual reference voltage. +.El +.Pp +On an +.Xr FDT 4 +based system the following properties must be set: +.Bl -tag -width "compatible" +.It Va compatible +Must be set to "nxp,pcf8591". +.It Va reg +The I2C address of +.Nm . +It should be in the range from 0x40 to 0x4f (7-bit). +.El +.Pp +The DTS part for a +.Nm +device usually looks like: +.Bd -literal +/ { + + ... + pcf8591adc { + compatible = "nxp,pcf8591"; + reg = <0x48>; + }; +}; +.Ed +.Sh SEE ALSO +.Xr fdt 4 , +.Xr iicbus 4 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +driver and this manual page was written by +.An Andriy Gapon Aq Mt avg@FreeBSD.org . +.Sh BUGS +The +.Nm +driver does not support changing the input configuration. +All input lines are configured as single-ended inputs. +.Pp +The +.Nm +driver does not support setting the output. +It is always disabled (tri-state). diff --git a/static/freebsd/man4/pchtherm.4 b/static/freebsd/man4/pchtherm.4 new file mode 100644 index 00000000..2248ebd8 --- /dev/null +++ b/static/freebsd/man4/pchtherm.4 @@ -0,0 +1,114 @@ +.\" +.\" Copyright (c) 2020 Takanori Watanabe +.\" +.\" 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 ``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 March 15, 2020 +.Dt pchtherm 4 +.Os +.Sh NAME +.Nm pchtherm +.Nd Intel PCH thermal subsystem +.Sh SYNOPSIS +.Cd "device pci" +.Cd "device pchtherm" +.Sh DESCRIPTION +The +.Nm +driver provides access to sensor data and configuration +installed in Intel PCH chipset. +.Nm +configuration register. +.Pp +The access to +.Nm +data is made via the +.Xr sysctl 8 +interface: +.Bd -literal +dev.pchtherm.0.ctt: 115.0C +dev.pchtherm.0.temperature: 28.5C +dev.pchtherm.0.t2temp: 91.0C +dev.pchtherm.0.t1temp: 86.0C +dev.pchtherm.0.t0temp: 81.0C +dev.pchtherm.0.tahv: 83.0C +dev.pchtherm.0.talv: 30.0C +dev.pchtherm.0.pmtime: 32 +dev.pchtherm.0.pmtemp: 50.0C +dev.pchtherm.0.%parent: pci0 +dev.pchtherm.0.%pnpinfo: vendor=0x8086 device=0x9d31 subvendor=0x17aa subdevice=0x2256 class=0x118000 +dev.pchtherm.0.%location: slot=20 function=2 dbsf=pci0:0:20:2 +dev.pchtherm.0.%driver: pchtherm +dev.pchtherm.0.%desc: Skylake PCH Thermal Subsystem +dev.pchtherm.%parent: +.Ed +.Bl -tag -width ".Va dev.pchtherm.%d.pch_hot_level" +.It Va dev.pchtherm.%d.temperature +Is the read-only value of the current temperature read by the sensor. +.It Va dev.pchtherm.%d.ctt +When the system reaches this temperature, it will shut down. +This will not appear when this feature is disabled and locked down. +.It Va dev.pchtherm.%d.t0temp +When temperature is under this value, system will be in T0 state. +.It Va dev.pchtherm.%d.t1temp +When temperature is over +.Va t0temp +and under this value, system will be in T1 state. +.It Va dev.pchtherm.%d.t2temp +When temperature is over +.Va t1temp +and under this value, system will be in T2 state. +Over this value, system will be in T3 state. +.It Va dev.pchtherm.%d.talv +Lower alart value. +This will not appear when sensor enable bit is locked down and the value is zero(which will show -50.0C). +.It Va dev.pchtherm.%d.tahv +High alart value. +This will not appear when sensor enable bit is locked down and the value is zero(which will show -50.0C). +.It Va dev.pchtherm.%d.pmtemp +Sensor Power management temperature. +Under this temperature, sensor will idle during +.Va pmtime +second. +.It Va dev.pchtherm.%d.pmtime +Sensor idle duration when low temperature. +.It Va dev.pchtherm.%d.pch_hot_level +When temperature is higher than this value, PCHHOT# pin will assert. +This value is not appear when this feature is disabled and locked down. +.El +.Pp +Please check the PCH datasheets for more details. +.Sh CAVEATS +All values are read-only. +And it do not support event interrupt for now. +.Sh SEE ALSO +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver and this manual page were written by +.An Takanori Watanabe Aq Mt takawata@FreeBSD.org . diff --git a/static/freebsd/man4/pci.4 b/static/freebsd/man4/pci.4 new file mode 100644 index 00000000..38a427e6 --- /dev/null +++ b/static/freebsd/man4/pci.4 @@ -0,0 +1,764 @@ +.\" +.\" Copyright (c) 1999 Kenneth D. Merry. +.\" 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. 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 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 March 10, 2026 +.Dt PCI 4 +.Os +.Sh NAME +.Nm pci +.Nd generic PCI/PCIe bus driver +.Sh SYNOPSIS +To compile the PCI bus driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd device pci +.Ed +.Pp +To compile in support for Single Root I/O Virtualization +.Pq SR-IOV : +.Bd -ragged -offset indent +.Cd options PCI_IOV +.Ed +.Pp +To compile in support for native PCI-express HotPlug: +.Bd -ragged -offset indent +.Cd options PCI_HP +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for +.Tn PCI +and +.Tn PCIe +devices in the kernel and limited access to +.Tn PCI +devices for userland. +.Pp +The +.Nm +driver provides a +.Pa /dev/pci +character device that can be used by userland programs to read and write +.Tn PCI +configuration registers. +Programs can also use this device to get a list of all +.Tn PCI +devices, or all +.Tn PCI +devices that match various patterns. +.Pp +Since the +.Nm +driver provides a write interface for +.Tn PCI +configuration registers, system administrators should exercise caution when +granting access to the +.Nm +device. +If used improperly, this driver can allow userland applications to +crash a machine or cause data loss. +In particular, driver only allows operations on the opened +.Pa /dev/pci +to modify system state if the file descriptor was opened for writing. +For instance, the +.Dv PCIOCREAD +and +.Dv PCIOCBARMMAP +operations require a writeable descriptor, because reading a config register +or a BAR read access could have function-specific side-effects. +.Pp +The +.Nm +driver implements the +.Tn PCI +bus in the kernel. +It enumerates any devices on the +.Tn PCI +bus and gives +.Tn PCI +client drivers the chance to attach to them. +It assigns resources to children, when the BIOS does not. +It takes care of routing interrupts when necessary. +It reprobes the unattached +.Tn PCI +children when +.Tn PCI +client drivers are dynamically +loaded at runtime. +The +.Nm +driver also includes support for PCI-PCI bridges, +various platform-specific Host-PCI bridges, +and basic support for +.Tn PCI +VGA adapters. +.Sh IOCTLS +The following +.Xr ioctl 2 +calls are supported by the +.Nm +driver. +They are defined in the header file +.In sys/pciio.h . +.Bl -tag -width 012345678901234 +.It PCIOCGETCONF +This +.Xr ioctl 2 +takes a +.Va pci_conf_io +structure. +It allows the user to retrieve information on all +.Tn PCI +devices in the system, or on +.Tn PCI +devices matching patterns supplied by the user. +The call may set +.Va errno +to any value specified in either +.Xr copyin 9 +or +.Xr copyout 9 . +The +.Va pci_conf_io +structure consists of a number of fields: +.Bl -tag -width match_buf_len +.It pat_buf_len +The length, in bytes, of the buffer filled with user-supplied patterns. +.It num_patterns +The number of user-supplied patterns. +.It patterns +Pointer to a buffer filled with user-supplied patterns. +.Va patterns +is a pointer to +.Va num_patterns +.Va pci_match_conf +structures. +The +.Va pci_match_conf +structure consists of the following elements: +.Bl -tag -width pd_vendor +.It pc_sel +.Tn PCI +domain, bus, slot and function. +.It pd_name +.Tn PCI +device driver name. +.It pd_unit +.Tn PCI +device driver unit number. +.It pc_vendor +.Tn PCI +vendor ID. +.It pc_device +.Tn PCI +device ID. +.It pc_class +.Tn PCI +device class. +.It flags +The flags describe which of the fields the kernel should match against. +A device must match all specified fields in order to be returned. +The match flags are enumerated in the +.Va pci_getconf_flags +structure. +Hopefully the flag values are obvious enough that they do not need to +described in detail. +.El +.It match_buf_len +Length of the +.Va matches +buffer allocated by the user to hold the results of the +.Dv PCIOCGETCONF +query. +.It num_matches +Number of matches returned by the kernel. +.It matches +Buffer containing matching devices returned by the kernel. +The items in this buffer are of type +.Va pci_conf , +which consists of the following items: +.Bl -tag -width pc_subvendor +.It pc_sel +.Tn PCI +domain, bus, slot and function. +.It pc_hdr +.Tn PCI +header type. +.It pc_subvendor +.Tn PCI +subvendor ID. +.It pc_subdevice +.Tn PCI +subdevice ID. +.It pc_vendor +.Tn PCI +vendor ID. +.It pc_device +.Tn PCI +device ID. +.It pc_class +.Tn PCI +device class. +.It pc_subclass +.Tn PCI +device subclass. +.It pc_progif +.Tn PCI +device programming interface. +.It pc_revid +.Tn PCI +revision ID. +.It pd_name +Driver name. +.It pd_unit +Driver unit number. +.It pd_numa_domain +Device NUMA domain. +.It pc_reported_len +Length of the valid portion of the encompassing +.Vt pci_conf +structure. +This should always be equivalent to the offset of the +.Va pc_spare +member. +.It pc_secbus +Secondary PCI bus number. +.Pq Only valid for bridge devices +.It pc_subbus +Subordinate PCI bus number. +.Pq Only valid for bridge devices +.It pc_spare +Reserved for future use. +.El +.It offset +The offset is passed in by the user to tell the kernel where it should +start traversing the device list. +The value passed out by the kernel +points to the record immediately after the last one returned. +The user may +pass the value returned by the kernel in subsequent calls to the +.Dv PCIOCGETCONF +ioctl. +If the user does not intend to use the offset, it must be set to zero. +.It generation +.Tn PCI +configuration generation. +This value only needs to be set if the offset is set. +The kernel will compare the current generation number of its internal +device list to the generation passed in by the user to determine whether +its device list has changed since the user last called the +.Dv PCIOCGETCONF +ioctl. +If the device list has changed, a status of +.Va PCI_GETCONF_LIST_CHANGED +will be passed back. +.It status +The status tells the user the disposition of his request for a device list. +The possible status values are: +.Bl -ohang +.It PCI_GETCONF_LAST_DEVICE +This means that there are no more devices in the PCI device list matching +the specified criteria after the +ones returned in the +.Va matches +buffer. +.It PCI_GETCONF_LIST_CHANGED +This status tells the user that the +.Tn PCI +device list has changed since his last call to the +.Dv PCIOCGETCONF +ioctl and he must reset the +.Va offset +and +.Va generation +to zero to start over at the beginning of the list. +.It PCI_GETCONF_MORE_DEVS +This tells the user that his buffer was not large enough to hold all of the +remaining devices in the device list that match his criteria. +.It PCI_GETCONF_ERROR +This indicates a general error while servicing the user's request. +If the +.Va pat_buf_len +is not equal to +.Va num_patterns +times +.Fn sizeof "struct pci_match_conf" , +.Va errno +will be set to +.Er EINVAL . +.El +.El +.It PCIOCREAD +This +.Xr ioctl 2 +reads the +.Tn PCI +configuration registers specified by the passed-in +.Va pci_io +structure. +The +.Va pci_io +structure consists of the following fields: +.Bl -tag -width pi_width +.It pi_sel +A +.Va pcisel +structure which specifies the domain, bus, slot and function the user would +like to query. +If the specific bus is not found, errno will be set to ENODEV and -1 returned +from the ioctl. +.It pi_reg +The +.Tn PCI +configuration registers the user would like to access. +.It pi_width +The width, in bytes, of the data the user would like to read. +This value +may be either 1, 2, or 4. +3-byte reads and reads larger than 4 bytes are +not supported. +If an invalid width is passed, errno will be set to EINVAL. +.It pi_data +The data returned by the kernel. +.El +.It PCIOCWRITE +This +.Xr ioctl 2 +allows users to write to the +.Tn PCI +configuration registers specified in the passed-in +.Va pci_io +structure. +The +.Va pci_io +structure is described above. +The limitations on data width described for +reading registers, above, also apply to writing +.Tn PCI +configuration registers. +.It PCIOCATTACHED +This +.Xr ioctl 2 +allows users to query if a driver is attached to the +.Tn PCI +device specified in the passed-in +.Va pci_io +structure. +The +.Va pci_io +structure is described above, however, the +.Va pi_reg +and +.Va pi_width +fields are not used. +The status of the device is stored in the +.Va pi_data +field. +A value of 0 indicates no driver is attached, while a value larger than 0 +indicates that a driver is attached. +.It PCIOCBARMMAP +This +.Xr ioctl 2 +command allows userspace processes to +.Xr mmap 2 +the memory-mapped PCI BAR into its address space. +The input parameters and results are passed in the +.Va pci_bar_mmap +structure, which has the following fields: +.Bl -tag -width "uint64_t pbm_bar_length" +.It Vt void *pbm_map_base +Reports the established mapping base to the caller. +If +.Va PCIIO_BAR_MMAP_FIXED +flag was specified, then this field must be filled before the call +with the desired address for the mapping. +.It Vt size_t pbm_map_length +Reports the mapped length of the BAR, in bytes. +Its +.Vt size_t +value is always multiple of machine pages. +.It Vt uint64_t pbm_bar_length +Reports length of the bar as exposed by the device. +.It Vt int pbm_bar_off +Reports offset from the mapped base to the start of the +first register in the bar. +.It Vt struct pcisel pbm_sel +Should be filled before the call. +Describes the device to operate on. +.It Vt int pbm_reg +The BAR index to mmap. +.It Vt int pbm_flags +Flags which augments the operation. +See below. +.It Vt int pbm_memattr +The caching attribute for the mapping. +Typical values are +.Dv VM_MEMATTR_UNCACHEABLE +for control registers BARs, and +.Dv VM_MEMATTR_WRITE_COMBINING +for frame buffers. +Regular memory-like BAR should be mapped with +.Dv VM_MEMATTR_DEFAULT +attribute. +.El +.Pp +Currently defined flags are: +.Bl -tag -width PCIIO_BAR_MMAP_ACTIVATE +.It PCIIO_BAR_MMAP_FIXED +The resulted mappings should be established at the address +specified by the +.Va pbm_map_base +member, otherwise fail. +.It PCIIO_BAR_MMAP_EXCL +Must be used together with +.Dv PCIIO_BAR_MMAP_FIXED +If the specified base contains already established mappings, the +operation fails instead of implicitly unmapping them. +.It PCIIO_BAR_MMAP_RW +The requested mapping allows both reading and writing. +Without the flag, read-only mapping is established. +Note that it is common for the device registers to have side-effects +even on reads. +.It PCIIO_BAR_MMAP_ACTIVATE +(Unimplemented) If the BAR is not activated, activate it in the course +of mapping. +Currently attempt to mmap an inactive BAR results in error. +.El +.It PCIOCBARIO +This +.Xr ioctl 2 +command allows users to read from and write to BARs. +The I/O request parameters are passed in a +.Va struct pci_bar_ioreq +structure, which has the following fields: +.Bl -tag +.It Vt struct pcisel pbi_sel +Describes the device to operate on. +.It Vt int pbi_op +The operation to perform. +Currently supported values are +.Dv PCIBARIO_READ +and +.Dv PCIBARIO_WRITE . +.It Vt uint32_t pbi_bar +The index of the BAR on which to operate. +.It Vt uint32_t pbi_offset +The offset into the BAR at which to operate. +.It Vt uint32_t pbi_width +The size, in bytes, of the I/O operation. +1-byte, 2-byte, 4-byte and 8-byte perations are supported. +.It Vt uint32_t pbi_value +For reads, the value is returned in this field. +For writes, the caller specifies the value to be written in this field. +.Pp +Note that this operation maps and unmaps the corresponding resource and +so is relatively expensive for memory BARs. +The +.Va PCIOCBARMMAP +.Xr ioctl 2 +can be used to create a persistent userspace mapping for such BARs instead. +.El +.El +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel, or stored in +.Xr loader.conf 5 . +The current value of these tunables can be examined at runtime via +.Xr sysctl 8 +nodes of the same name. +Unless otherwise specified, +each of these tunables is a boolean that can be enabled by setting the +tunable to a non-zero value. +.Bl -tag -width indent +.It Va hw.pci.clear_bars Pq Defaults to 0 +Ignore any firmware-assigned memory and I/O port resources. +This forces the +.Tn PCI +bus driver to allocate resource ranges for memory and I/O port resources +from scratch. +.It Va hw.pci.clear_buses Pq Defaults to 0 +Ignore any firmware-assigned bus number registers in PCI-PCI bridges. +This forces the +.Tn PCI +bus driver and PCI-PCI bridge driver to allocate bus numbers for secondary +buses behind PCI-PCI bridges. +.It Va hw.pci.clear_pcib Pq Defaults to 0 +Ignore any firmware-assigned memory and I/O port resource windows in PCI-PCI +bridges. +This forces the PCI-PCI bridge driver to allocate memory and I/O port resources +for resource windows from scratch. +.Pp +By default the PCI-PCI bridge driver will allocate windows that +contain the firmware-assigned resources devices behind the bridge. +In addition, the PCI-PCI bridge driver will suballocate from existing window +regions when possible to satisfy a resource request. +As a result, +both +.Va hw.pci.clear_bars +and +.Va hw.pci.clear_pcib +must be enabled to fully ignore firmware-supplied resource assignments. +.It Va hw.pci.default_vgapci_unit Pq Defaults to -1 +By default, +the first +.Tn PCI +VGA adapter encountered by the system is assumed to be the boot display device. +This tunable can be set to choose a specific VGA adapter by specifying the +unit number of the associated +.Va vgapci Ns Ar X +device. +.It Va hw.pci.do_power_nodriver Pq Defaults to 0 +Place devices into a low power state +.Pq D3 +when a suitable device driver is not found. +Can be set to one of the following values: +.Bl -tag -width indent +.It 3 +Powers down all +.Tn PCI +devices without a device driver. +.It 2 +Powers down most devices without a device driver. +PCI devices with the display, memory, and base peripheral device classes +are not powered down. +.It 1 +Similar to a setting of 2 except that storage controllers are also not +powered down. +.It 0 +All devices are left fully powered. +.El +.Pp +A +.Tn PCI +device must support power management to be powered down. +Placing a device into a low power state may not reduce power consumption. +.It Va hw.pci.do_power_resume Pq Defaults to 1 +Place +.Tn PCI +devices into the fully powered state when resuming either the system or an +individual device. +Setting this to zero is discouraged as the system will not attempt to power +up non-powered PCI devices after a suspend. +.It Va hw.pci.do_power_suspend Pq Defaults to 1 +Place +.Tn PCI +devices into a low power state when suspending either the system or individual +devices. +Normally the D3 state is used as the low power state, +but firmware may override the desired power state during a system suspend. +.It Va hw.pci.enable_ari Pq Defaults to 1 +Enable support for PCI-express Alternative RID Interpretation. +This is often used in conjunction with SR-IOV. +.It Va hw.pci.enable_io_modes Pq Defaults to 1 +Enable memory or I/O port decoding in a PCI device's command register if it has +firmware-assigned memory or I/O port resources. +The firmware +.Pq BIOS +in some systems does not enable memory or I/O port decoding for some devices +even when it has assigned resources to the device. +This enables decoding for such resources during bus probe. +.It Va hw.pci.enable_msi Pq Defaults to 1 +Enable support for Message Signalled Interrupts +.Pq MSI . +MSI interrupts can be disabled by setting this tunable to 0. +.It Va hw.pci.enable_msix Pq Defaults to 1 +Enable support for extended Message Signalled Interrupts +.Pq MSI-X . +MSI-X interrupts can be disabled by setting this tunable to 0. +.It Va hw.pci.enable_pcie_ei Pq Defaults to 0 +Enable support for PCI-express Electromechanical Interlock. +.It Va hw.pci.enable_pcie_hp Pq Defaults to 1 +Enable support for native PCI-express HotPlug. +.It Va hw.pci.honor_msi_blacklist Pq Defaults to 1 +MSI and MSI-X interrupts are disabled for certain chipsets known to have +broken MSI and MSI-X implementations when this tunable is set. +It can be set to zero to permit use of MSI and MSI-X interrupts if the +chipset match is a false positive. +.It Va hw.pci.iov_max_config Pq Defaults to 1MB +The maximum amount of memory permitted for the configuration parameters +used when creating Virtual Functions via SR-IOV. +This tunable can also be changed at runtime via +.Xr sysctl 8 . +.It Va hw.pci.realloc_bars Pq Defaults to 0 +Attempt to allocate a new resource range during the initial device scan +for any memory or I/O port resources with firmware-assigned ranges that +conflict with another active resource. +.It Va hw.pci.usb_early_takeover Pq Defaults to 1 on Tn amd64 and Tn i386 +Disable legacy device emulation of USB devices during the initial device +scan. +Set this tunable to zero to use USB devices via legacy emulation when +using a custom kernel without USB controller drivers. +.It Va hw.pci...INT

.irq +These tunables can be used to override the interrupt routing for legacy +PCI INTx interrupts. +Unlike other tunables in this list, +these do not have corresponding sysctl nodes. +The tunable name includes the address of the PCI device as well as the +pin of the desired INTx IRQ to override: +.Bl -tag -width indent +.It +The domain +.Pq or segment +of the PCI device in decimal. +.It +The bus address of the PCI device in decimal. +.It +The slot of the PCI device in decimal. +.It

+The interrupt pin of the PCI slot to override. +One of +.Ql A , +.Ql B , +.Ql C , +or +.Ql D . +.El +.Pp +The value of the tunable is the raw IRQ value to use for the INTx interrupt +pin identified by the tunable name. +Mapping of IRQ values to platform interrupt sources is machine dependent. +.El +.Sh DEVICE WIRING +You can wire the device unit at a given location with +.Xr device.hints 5 . +.Ss BSF Based Wiring +Devices may be wired to a Bus / Slot / Function (BSF) address. +This is the form reported by +.Xr pciconf 8 +Entries of the form +.Va hints...at="pci::" +or +.Va hints...at="pci:::" +will force the driver +.Va name +to probe and attach at unit +.Va unit +for any PCI device found to match the specification, where: +.Bl -tag -width -indent +.It +The domain +.Pq or segment +of the PCI device in decimal. +Defaults to 0 if unspecified. +.It +The bus address of the PCI device in decimal. +.It +The slot of the PCI device in decimal. +.It +The function of the PCI device in decimal. +.El +.Pp +The code to do the matching requires an exact string match. +Do not specify the angle brackets +.Pq < > +in the hints file. +Wiring multiple devices to the same +.Va name +and +.Va unit +produces undefined results. +.Ss Examples +Given the following lines in +.Pa /boot/device.hints : +.Bd -literal +hint.nvme.3.at="pci6:0:0" +hint.igb.8.at="pci14:0:0" +.Ed +.Pp +If there is a device that supports +.Xr igb 4 +at PCI bus 14 slot 0 function 0, +then it will be assigned igb8 for probe and attach. +Likewise, if there is an +.Xr nvme 4 +device at PCI bus 6 slot 0 function 0, +then it will be assigned nvme3 for probe and attach. +If another type of card is in either of these locations, the name and +unit of that card will be the default names and will be unaffected by +these hints. +If other igb or nvme cards are located elsewhere, they will be +assigned their unit numbers sequentially, skipping the unit numbers +that have 'at' hints. +.Ss Location Based Wiring +While simple to locate where to place a device for BSF wiring, the +bus number of that is not invariant. +Any number of changes to the devices within the system can cause +this value to vary from boot to boot. +The UEFI Standard defines a device path that's based only on the invariant parts +of the address: The root complex (domain), the slot number and the function. +These paths are hard to construct by hand, please see +.Xr devctl 8 +.Sq Cm getpath +command with a +.Sq Ar UEFI +locator. +The above example could also be expressed as +.Bd -literal +hint.nvme.3.at="PciRoot(0x2)/Pci(0x1,0x3)/Pci(0x0,0x0)/Pci(0x0,0x0)/Pci(0x0,0x0)" +hint.nvme.8.at="PciRoot(0x1)/Pci(0x2,0x2)/Pci(0x0,0x0)/Pci(0x0,0x0)" +.Ed +.Pp +The advantage of this notation is that you can specify the exact location a +device will be at. +For deployments of multiple systems with the same configuration, this can be +helpful in managing the devices. +However, even slight variation in motherboards can cause the path to change +substantially. +It is also less natural to think of the UEFI Device Paths since little else +will report it. +.Sh FILES +.Bl -tag -width /dev/pci -compact +.It Pa /dev/pci +Character device for the +.Nm +driver. +.El +.Sh SEE ALSO +.Xr device.hints 5 +.Xr pciconf 8 +.Sh HISTORY +The +.Nm +driver (not the kernel's +.Tn PCI +support code) first appeared in +.Fx 2.2 , +and was written by Stefan Esser and Garrett Wollman. +Support for device listing and matching was re-implemented by +Kenneth Merry, and first appeared in +.Fx 3.0 . +.Sh AUTHORS +.An Kenneth Merry Aq Mt ken@FreeBSD.org +.Sh BUGS +It is not possible for users to specify an accurate offset into the device +list without calling the +.Dv PCIOCGETCONF +at least once, since they have no way of knowing the current generation +number otherwise. +This probably is not a serious problem, though, since +users can easily narrow their search by specifying a pattern or patterns +for the kernel to match against. diff --git a/static/freebsd/man4/pcib.4 b/static/freebsd/man4/pcib.4 new file mode 100644 index 00000000..b9a27a56 --- /dev/null +++ b/static/freebsd/man4/pcib.4 @@ -0,0 +1,46 @@ +.\" +.\" Copyright (c) 2008 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. 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 AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 18, 2008 +.Dt PCIB 4 +.Os +.Sh NAME +.Nm pcib +.Nd PCI bridge driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device pci" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides for host and +.Tn PCI +bridges in a +.Tn PCI +system. +.Sh BUGS +This man page is too short. diff --git a/static/freebsd/man4/pcm.4 b/static/freebsd/man4/pcm.4 new file mode 100644 index 00000000..518c37b5 --- /dev/null +++ b/static/freebsd/man4/pcm.4 @@ -0,0 +1,682 @@ +.\" +.\" Copyright (c) 2009-2011 Joel Dahl +.\" 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 February 15, 2025 +.Dt SOUND 4 +.Os +.Sh NAME +.Nm sound , +.Nm pcm , +.Nm snd +.Nd +.Fx +PCM audio device infrastructure +.Sh SYNOPSIS +To compile this driver into the kernel, place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device sound" +.Ed +.Sh DESCRIPTION +The +.Nm +driver is the main component of the +.Fx +sound system. +It works in conjunction with a bridge device driver on supported devices +and provides PCM audio record and playback once it attaches. +Each bridge device driver supports a specific set of audio chipsets and +needs to be enabled together with the +.Nm +driver. +PCI and ISA PnP audio devices identify themselves so users are usually not +required to add anything to +.Pa /boot/device.hints . +.Pp +Some of the main features of the +.Nm +driver are: multichannel audio, per-application +volume control, dynamic mixing through virtual sound channels, true full +duplex operation, bit perfect audio, rate conversion and low latency +modes. +.Pp +The +.Nm +driver is enabled by default, along with several bridge device drivers. +Those not enabled by default can be loaded during runtime with +.Xr kldload 8 +or during boot via +.Xr loader.conf 5 . +The following bridge device drivers are available: +.Pp +.Bl -bullet -compact +.It +.Xr snd_ai2s 4 (enabled by default on powerpc) +.It +.Xr snd_als4000 4 +.It +.Xr snd_atiixp 4 +.It +.Xr snd_cmi 4 (enabled by default on amd64, i386) +.It +.Xr snd_cs4281 4 +.It +.Xr snd_csa 4 (enabled by default on amd64, i386) +.It +.Xr snd_davbus 4 (enabled by default on powerpc) +.It +.Xr snd_emu10k1 4 +.It +.Xr snd_emu10kx 4 (enabled by default on amd64, i386) +.It +.Xr snd_envy24 4 +.It +.Xr snd_envy24ht 4 +.It +.Xr snd_es137x 4 (enabled by default on amd64, i386) +.It +.Xr snd_fm801 4 +.It +.Xr snd_hda 4 (enabled by default on amd64, i386) +.It +.Xr snd_hdsp 4 +.It +.Xr snd_hdspe 4 +.It +.Xr snd_ich 4 (enabled by default on amd64, i386) +.It +.Xr snd_maestro3 4 +.It +.Xr snd_neomagic 4 +.It +.Xr snd_solo 4 +.It +.Xr snd_spicds 4 +.It +.Xr snd_uaudio 4 (auto-loaded on device plug) +.It +.Xr snd_via8233 4 (enabled by default on amd64, i386) +.It +.Xr snd_via82c686 4 +.It +.Xr snd_vibes 4 +.El +.Pp +Refer to the manual page for each bridge device driver for driver specific +settings and information. +.Ss Boot Variables +In general, the module +.Pa snd_foo +corresponds to +.Cd "device snd_foo" +and can be +loaded by the boot +.Xr loader 8 +via +.Xr loader.conf 5 +or from the command line using the +.Xr kldload 8 +utility. +Options which can be specified in +.Pa /boot/loader.conf +include: +.Bl -tag -width ".Va snd_driver_load" -offset indent +.It Va snd_driver_load +.Pq Dq Li NO +If set to +.Dq Li YES , +this option loads all available drivers. +.It Va snd_hda_load +.Pq Dq Li NO +If set to +.Dq Li YES , +only the Intel High Definition Audio bridge device driver and dependent +modules will be loaded. +.It Va snd_foo_load +.Pq Dq Li NO +If set to +.Dq Li YES , +load driver for card/chipset foo. +.El +.Pp +To define default values for the different mixer channels, +set the channel to the preferred value using hints, e.g.: +.Va hint.pcm.0.line Ns = Ns Qq Li 0 . +This will mute the input channel per default. +.Ss Multichannel Audio +Multichannel audio, popularly referred to as +.Dq surround sound +is supported and enabled by default. +The +.Fx +multichannel matrix processor supports up to 18 interleaved channels, but the +limit is currently set to 8 channels (as commonly used for 7.1 surround sound). +The internal matrix mapping can handle reduction, expansion or +re-routing of channels. +This provides a base interface for related multichannel +.Fn ioctl +support. +Multichannel audio works both with and without VCHANs. +.Pp +Most bridge device drivers are still missing multichannel matrixing +support, but in most cases this should be trivial to implement. +Use the +.Va dev.pcm.%d.[play|rec].vchanformat +.Xr sysctl 8 +to adjust the number of channels used. +The current multichannel interleaved structure and arrangement was +implemented by inspecting various popular UNIX applications. +There were no single standard, so much care has been taken to try +to satisfy each possible scenario, despite the fact that each +application has its own conflicting standard. +.Ss EQ +The Parametric Software Equalizer (EQ) enables the use of +.Dq tone +controls (bass and treble). +Commonly used for ear-candy or frequency compensation due to the vast +difference in hardware quality. +EQ is disabled by default, but can be enabled with the +.Va hint.pcm.%d.eq +tunable. +.Ss VCHANs +Each device can optionally support more playback and recording channels +than physical hardware provides by using +.Dq virtual channels +or VCHANs. +VCHAN options can be configured via the +.Xr sysctl 8 +interface but can only be manipulated while the device is inactive. +.Ss VPC +.Fx +supports independent and individual volume controls for each active +application, without touching the master +.Nm +volume. +This is sometimes referred to as Volume Per Channel (VPC). +The VPC feature is enabled by default. +.Ss Loader Tunables +The following loader tunables are used to set driver configuration at the +.Xr loader 8 +prompt before booting the kernel, or they can be stored in +.Pa /boot/loader.conf +in order to automatically set them before booting the kernel. +It is also possible to use +.Xr kenv 1 +to change these tunables before loading the +.Nm +driver. +The following tunables can not be changed during runtime using +.Xr sysctl 8 . +.Bl -tag -width indent +.It Va hint.pcm.%d.eq +Set to 1 or 0 to explicitly enable (1) or disable (0) the equalizer. +Requires a driver reload if changed. +Enabling this will make bass and treble controls appear in mixer applications. +This tunable is undefined by default. +Equalizing is disabled by default. +.It Va hint.pcm.%d.vpc +Set to 1 or 0 to explicitly enable (1) or disable (0) the VPC feature. +This tunable is undefined by default. +VPC is however enabled by default. +.El +.Ss Runtime Configuration +There are a number of +.Xr sysctl 8 +variables available which can be modified during runtime. +These values can also be stored in +.Pa /etc/sysctl.conf +in order to automatically set them during the boot process. +.Va hw.snd.* +are global settings and +.Va dev.pcm.* +are device specific. +.Bl -tag -width indent +.It Va hw.snd.compat_linux_mmap +Linux +.Xr mmap 2 +compatibility. +The following values are supported (default is 0): +.Bl -tag -width 2n +.It -1 +Force disabling/denying PROT_EXEC +.Xr mmap 2 +requests. +.It 0 +Auto detect proc/ABI type, allow +.Xr mmap 2 +for Linux applications, and deny for everything else. +.It 1 +Always allow PROT_EXEC page mappings. +.El +.It Va hw.snd.default_auto +Automatically assign the default sound unit. +The following values are supported (default is 1): +.Bl -tag -width 2n +.It 0 +Do not assign the default sound unit automatically. +.It 1 +Use the best available sound device based on playing and recording +capabilities of the device. +.It 2 +Use the most recently attached device. +.El +.It Va hw.snd.default_unit +Default sound card for systems with multiple sound cards. +When using +.Xr devfs 4 , +the default device for +.Pa /dev/dsp . +Equivalent to a symlink from +.Pa /dev/dsp +to +.Pa /dev/dsp Ns Va ${hw.snd.default_unit} . +.It Va hw.snd.feeder_eq_exact_rate +Only certain rates are allowed for precise processing. +The default behavior is however to allow sloppy processing for all rates, +even the unsupported ones. +Enable to toggle this requirement and only allow processing for supported +rates. +.It Va hw.snd.feeder_rate_max +Maximum allowable sample rate. +.It Va hw.snd.feeder_rate_min +Minimum allowable sample rate. +.It Va hw.snd.feeder_rate_polyphase_max +Adjust to set the maximum number of allowed polyphase entries during the +process of building resampling filters. +Disabling polyphase resampling has the benefit of reducing memory usage, at +the expense of slower and lower quality conversion. +Only applicable when the SINC interpolator is used. +Default value is 183040. +Set to 0 to disable polyphase resampling. +.It Va hw.snd.feeder_rate_quality +Sample rate converter quality. +Default value is 1, linear interpolation. +Available options include: +.Bl -tag -width 2n +.It 0 +Zero Order Hold, ZOH. +Very fast, but with poor quality. +.It 1 +Linear interpolation. +Fast, quality is subject to personal preference. +Technically the quality is poor however, due to the lack of anti-aliasing +filtering. +.It 2 +Bandlimited SINC interpolator. +Implements polyphase banking to boost the conversion speed, at the cost of +memory usage, with multiple high quality polynomial interpolators to improve +the conversion accuracy. +100% fixed point, 64bit accumulator with 32bit coefficients and high precision +sample buffering. +Quality values are 100dB stopband, 8 taps and 85% bandwidth. +.It 3 +Continuation of the bandlimited SINC interpolator, with 100dB stopband, 36 +taps and 90% bandwidth as quality values. +.It 4 +Continuation of the bandlimited SINC interprolator, with 100dB stopband, 164 +taps and 97% bandwidth as quality values. +.El +.It Va hw.snd.feeder_rate_round +Sample rate rounding threshold, to avoid large prime division at the +cost of accuracy. +All requested sample rates will be rounded to the nearest threshold value. +Possible values range between 0 (disabled) and 500. +Default is 25. +.It Va hw.snd.latency +Configure the buffering latency. +Only affects applications that do not explicitly request +blocksize / fragments. +This tunable provides finer granularity than the +.Va hw.snd.latency_profile +tunable. +Possible values range between 0 (lowest latency) and 10 (highest latency). +.It Va hw.snd.latency_profile +Define sets of buffering latency conversion tables for the +.Va hw.snd.latency +tunable. +A value of 0 will use a low and aggressive latency profile which can result +in possible underruns if the application cannot keep up with a rapid irq +rate, especially during high workload. +The default value is 1, which is considered a moderate/safe latency profile. +.It Va hw.snd.vchans_enable +Global VCHAN setting to enable (1) or disable (0) VCHANs. +This setting can be overridden for an individual device by using the +.Va dev.pcm.%d.[play|rec].vchans +tunables. +Default is enabled. +.It Va hw.snd.report_soft_formats +Controls the internal format conversion if it is +available transparently to the application software. +When disabled or not available, the application will +only be able to select formats the device natively supports. +.It Va hw.snd.report_soft_matrix +Enable seamless channel matrixing even if the hardware does not support it. +Makes it possible to play multichannel streams even with a simple stereo +sound card. +.It Va hw.snd.verbose +Level of verbosity for the +.Pa /dev/sndstat +device. +Higher values include more output and the highest level, +four, should be used when reporting problems. +Other options include: +.Bl -tag -width 2n +.It 0 +Installed devices and their allocated bus resources. +.It 1 +The number of playback, record, virtual channels, and +flags per device. +.It 2 +Channel information per device including the channel's +current format, speed, and pseudo device statistics such as +buffer overruns and buffer underruns. +.It 3 +File names and versions of the currently loaded sound modules. +.It 4 +Various messages intended for debugging. +.El +.It Va hw.snd.vpc_0db +Default value for +.Nm +volume. +Increase to give more room for attenuation control. +Decrease for more amplification, with the possible cost of sound clipping. +.It Va hw.snd.vpc_autoreset +When a channel is closed the channel volume will be reset to 0db. +This means that any changes to the volume will be lost. +Enabling this will preserve the volume, at the cost of possible confusion +when applications tries to re-open the same device. +.It Va hw.snd.vpc_mixer_bypass +The recommended way to use the VPC feature is to teach applications to use the +correct +.Fn ioctl : +.Dv SNDCTL_DSP_GETPLAYVOL , SNDCTL_DSP_SETPLAYVOL , +.Dv SNDCTL_DSP_SETRECVOL , SNDCTL_DSP_SETRECVOL . +This is however not always possible. +Enable this to allow applications to use their own existing mixer logic +to control their own channel volume. +.It Va hw.snd.vpc_reset +Enable to restore all channel volumes back to the default value of 0db. +.It Va dev.pcm.%d.bitperfect +Enable or disable bitperfect mode. +When enabled, channels will skip all dsp processing, such as channel +matrixing, rate converting and equalizing. +The pure +.Nm +stream will be fed directly to the hardware. +If VCHANs are enabled, the bitperfect mode will use the VCHAN format/rate as +the definitive format/rate target. +The recommended way to use bitperfect mode is to disable VCHANs and enable this +sysctl. +Default is disabled. +.It Va dev.pcm.%d.[play|rec].vchans +Enable (1) or disable (0) VCHANs. +Default is enabled. +.It Va dev.pcm.%d.[play|rec].vchanformat +Format for VCHAN mixing. +All playback paths will be converted to this format before the mixing +process begins. +By default only 2 channels are enabled. +Available options include: +.Bl -tag -width 2n +.It s16le:1.0 +Mono. +.It s16le:2.0 +Stereo, 2 channels (left, right). +.It s16le:2.1 +3 channels (left, right, LFE). +.It s16le:3.0 +3 channels (left, right, rear center). +.It s16le:4.0 +Quadraphonic, 4 channels (front/rear left and right). +.It s16le:4.1 +5 channels (4.0 + LFE). +.It s16le:5.0 +5 channels (4.0 + center). +.It s16le:5.1 +6 channels (4.0 + center + LFE). +.It s16le:6.0 +6 channels (4.0 + front/rear center). +.It s16le:6.1 +7 channels (6.0 + LFE). +.It s16le:7.1 +8 channels (4.0 + center + LFE + left and right side). +.El +.It Va dev.pcm.%d.[play|rec].vchanmode +VCHAN format/rate selection. +Available options include: +.Bl -tag -width 2n +.It fixed +Channel mixing is done using fixed format/rate. +Advanced operations such as digital passthrough will not work. +Can be considered as a +.Dq legacy +mode. +This is the default mode for hardware channels which lack support for digital +formats. +.It passthrough +Channel mixing is done using fixed format/rate, but advanced operations such +as digital passthrough also work. +All channels will produce sound as usual until a digital format playback is +requested. +When this happens all other channels will be muted and the latest incoming +digital format will be allowed to pass through undisturbed. +Multiple concurrent digital streams are supported, but the latest stream will +take precedence and mute all other streams. +.It adaptive +Works like the +.Dq passthrough +mode, but is a bit smarter, especially for +multiple +.Nm +channels with different format/rate. +When a new channel is about to start, the entire list of virtual channels will +be scanned, and the channel with the best format/rate (usually the +highest/biggest) will be selected. +This ensures that mixing quality depends on the best channel. +The downside is that the hardware DMA mode needs to be restarted, which may +cause annoying pops or clicks. +.El +.It Va dev.pcm.%d.[play|rec].vchanrate +Sample rate speed for VCHAN mixing. +All playback paths will be converted to this sample rate before the mixing +process begins. +.It Va dev.pcm.%d.polling +Experimental polling mode support where the driver operates by querying the +device state on each tick using a +.Xr callout 9 +mechanism. +Disabled by default and currently only available for a few device drivers. +.El +.Ss Statistics +Channel statistics are only kept while the device is open. +So with situations involving overruns and underruns, consider the output +while the errant application is open and running. +.Ss IOCTL Support +The driver supports most of the OSS +.Fn ioctl +functions, and most applications work unmodified. +A few differences exist, while memory mapped playback is +supported natively and in Linux emulation, memory mapped recording is not due +to VM system design. +As a consequence, some applications may need to be recompiled +with a slightly modified audio module. +See +.In sys/soundcard.h +for a complete list of the supported +.Fn ioctl +functions. +.Sh FILES +The +.Nm +drivers may create the following device nodes: +.Pp +.Bl -tag -width ".Pa /dev/sndstat" -compact +.It Pa /dev/dsp%d +Audio device. +The number represents the unit number of the device. +.It Pa /dev/dsp +Alias of +.Pa /dev/dsp${hw.snd.default_unit} . +Available only if +.Pa hw.snd.basename_clone +is set. +.It Pa /dev/sndstat +Current +.Nm +status, including all channels and drivers. +.El +.Pp +All +.Nm +devices are listed +in +.Pa /dev/sndstat . +Additional messages are sometimes recorded when the +device is probed and attached, these messages can be viewed with the +.Xr dmesg 8 +utility. +.Sh EXAMPLES +Use the sound metadriver to load all +.Nm +bridge device drivers at once +(for example if it is unclear which the correct driver to use is): +.Pp +.Dl kldload snd_driver +.Pp +Load a specific bridge device driver, in this case the Intel +High Definition Audio driver: +.Pp +.Dl kldload snd_hda +.Pp +Check the status of all detected +.Nm +devices: +.Pp +.Dl cat /dev/sndstat +.Pp +Change the default sound device, in this case to the second device. +This is handy if there are multiple +.Nm +devices available: +.Pp +.Dl mixer -d pcm1 +.Sh DIAGNOSTICS +.Bl -diag +.It pcm%d:play:%d:dsp%d.p%d: play interrupt timeout, channel dead +The hardware does not generate interrupts to serve incoming (play) +or outgoing (record) data. +.It unsupported subdevice XX +A device node is not created properly. +.El +.Sh SEE ALSO +.Xr devfs 4 , +.Xr snd_ai2s 4 , +.Xr snd_als4000 4 , +.Xr snd_atiixp 4 , +.Xr snd_cmi 4 , +.Xr snd_cs4281 4 , +.Xr snd_csa 4 , +.Xr snd_davbus 4 , +.Xr snd_emu10k1 4 , +.Xr snd_emu10kx 4 , +.Xr snd_envy24 4 , +.Xr snd_envy24ht 4 , +.Xr snd_es137x 4 , +.Xr snd_fm801 4 , +.Xr snd_hda 4 , +.Xr snd_hdsp 4 , +.Xr snd_hdspe 4 , +.Xr snd_ich 4 , +.Xr snd_maestro3 4 , +.Xr snd_neomagic 4 , +.Xr snd_solo 4 , +.Xr snd_spicds 4 , +.Xr snd_t4dwave 4 , +.Xr snd_uaudio 4 , +.Xr snd_via8233 4 , +.Xr snd_via82c686 4 , +.Xr snd_vibes 4 , +.Xr device.hints 5 , +.Xr loader.conf 5 , +.Xr dmesg 8 , +.Xr kldload 8 , +.Xr mixer 8 , +.Xr sysctl 8 +.Rs +.%T "Cookbook formulae for audio EQ biquad filter coefficients (Audio-EQ-Cookbook.txt), by Robert Bristow-Johnson" +.%U "https://www.musicdsp.org/en/latest/Filters/197-rbj-audio-eq-cookbook.html" +.Re +.Rs +.%T "Julius O'Smith's Digital Audio Resampling" +.%U "http://ccrma.stanford.edu/~jos/resample/" +.Re +.Rs +.%T "Polynomial Interpolators for High-Quality Resampling of Oversampled Audio, by Olli Niemitalo" +.%U "http://yehar.com/blog/wp-content/uploads/2009/08/deip.pdf" +.Re +.Rs +.%T "The OSS API" +.%U "http://www.opensound.com/pguide/oss.pdf" +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 2.2.6 +as +.Nm pcm , +written by +.An Luigi Rizzo . +It was later +rewritten in +.Fx 4.0 +by +.An Cameron Grant . +The API evolved from the VOXWARE +standard which later became OSS standard. +.Sh AUTHORS +.An -nosplit +.An Luigi Rizzo Aq Mt luigi@iet.unipi.it +initially wrote the +.Nm pcm +device driver and this manual page. +.An Cameron Grant Aq Mt gandalf@vilnya.demon.co.uk +later revised the device driver for +.Fx 4.0 . +.An Seigo Tanimura Aq Mt tanimura@r.dl.itc.u-tokyo.ac.jp +revised this manual page. +It was then rewritten for +.Fx 5.2 . +.Sh BUGS +Some features of your sound card (e.g., global volume control) might not +be supported on all devices. +.Pp +Some audio devices might refuse to work properly unless the sample rate is +configured the same for both recording and playback, even if only simplex is +used. +See the +.Va dev.pcm.%d.[play|rec].vchanrate +sysctls. diff --git a/static/freebsd/man4/pf.4 b/static/freebsd/man4/pf.4 new file mode 100644 index 00000000..03a4ba2b --- /dev/null +++ b/static/freebsd/man4/pf.4 @@ -0,0 +1,1279 @@ +.\" $OpenBSD: pf.4,v 1.62 2008/09/10 14:57:37 jmc Exp $ +.\" +.\" Copyright (C) 2001, Kjell Wooding. 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. Neither the name of the project nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT 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 PROJECT 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 2, 2025 +.Dt PF 4 +.Os +.Sh NAME +.Nm pf +.Nd packet filter +.Sh SYNOPSIS +.Cd "device pf" +.Cd "options PF_DEFAULT_TO_DROP" +.Pp +In +.Xr rc.conf 5 : +.Cd pf_enable="YES" +.Pp +In +.Xr loader.conf 5 : +.Cd net.pf.states_hashsize +.Cd net.pf.source_nodes_hashsize +.Cd net.pf.rule_tag_hashsize +.Cd net.pf.udpendpoint_hashsize +.Cd net.pf.default_to_drop +.Pp +In +.Xr sysctl.conf 5 : +.Cd net.pf.request_maxcount +.Cd net.pf.filter_local +.Sh DESCRIPTION +Packet filtering takes place in the kernel. +A pseudo-device, +.Pa /dev/pf , +allows userland processes to control the +behavior of the packet filter through an +.Xr ioctl 2 +interface. +There are commands to enable and disable the filter, load rulesets, +add and remove individual rules or state table entries, +and retrieve statistics. +The most commonly used functions are covered by +.Xr pfctl 8 . +.Pp +Manipulations like loading a ruleset that involve more than a single +.Xr ioctl 2 +call require a so-called +.Em ticket , +which prevents the occurrence of +multiple concurrent manipulations. +.Pp +Fields of +.Xr ioctl 2 +parameter structures that refer to packet data (like +addresses and ports) are generally expected in network byte-order. +.Pp +Rules and address tables are contained in so-called +.Em anchors . +When servicing an +.Xr ioctl 2 +request, if the anchor field of the argument structure is empty, +the kernel will use the default anchor (i.e., the main ruleset) +in operations. +Anchors are specified by name and may be nested, with components +separated by +.Sq / +characters, similar to how file system hierarchies are laid out. +The final component of the anchor path is the anchor under which +operations will be performed. +.Sh SYSCTL VARIABLES +The following variables can be entered at the +.Xr loader 8 +prompt, set in +.Xr loader.conf 5 , +.Xr sysctl.conf 5 , +or changed at runtime with +.Xr sysctl 8 : +.Bl -tag -width indent +.It Va net.pf.filter_local +This tells +.Nm +to also filter on the loopback output hook. +This is typically used to allow redirect rules to adjust the source address. +.It Va net.pf.request_maxcount +The maximum number of items in a single ioctl call. +.El +.Sh LOADER TUNABLES +The following tunables can be entered at the +.Xr loader 8 +prompt, or set in +.Xr loader.conf 5 : +.Bl -tag -width indent +.It Va net.pf.states_hashsize +Size of hash table that stores states. +Should be power of 2. +Default value is 131072. +.It Va net.pf.source_nodes_hashsize +Size of hash table that stores source nodes. +Should be power of 2. +Default value is 32768. +.It Va net.pf.rule_tag_hashsize +Size of the hash table that stores tags. +.It Va net.pf.udpendpoint_hashsize +Size of hash table that store UDP endpoint mappings. +Should be power of 2. +Default value is 32768. +.It Va net.pf.default_to_drop +This value overrides +.Cd "options PF_DEFAULT_TO_DROP" +from kernel configuration file. +.It Va net.pf.filter_local +This tells +.Nm +to also filter on the loopback output hook. +This is typically used to allow redirect rules to adjust the source address. +.It Va net.pf.request_maxcount +The maximum number of items in a single ioctl call. +.El +.Pp +Read only +.Xr sysctl 8 +variables with matching names are provided to obtain current values +at runtime. +.Sh KERNEL OPTIONS +The following options in the kernel configuration file are related to +.Nm +operation: +.Pp +.Bl -tag -width ".Dv PF_DEFAULT_TO_DROP" -compact +.It Dv PF_DEFAULT_TO_DROP +Change default policy to drop by default +.El +.Sh IOCTL INTERFACE +.Nm +supports the following +.Xr ioctl 2 +commands, available through +.Aq Pa net/pfvar.h : +.Bl -tag -width xxxxxx +.It Dv DIOCSTART +Start the packet filter. +.It Dv DIOCSTOP +Stop the packet filter. +.It Dv DIOCSTARTALTQ +Start the ALTQ bandwidth control system (see +.Xr altq 9 ) . +.It Dv DIOCSTOPALTQ +Stop the ALTQ bandwidth control system. +.It Dv DIOCBEGINADDRS Fa "struct pfioc_pooladdr *pp" +.Bd -literal +struct pfioc_pooladdr { + u_int32_t action; + u_int32_t ticket; + u_int32_t nr; + u_int32_t r_num; + u_int8_t r_action; + u_int8_t r_last; + u_int8_t af; + char anchor[MAXPATHLEN]; + struct pf_pooladdr addr; +}; +.Ed +.Pp +Clear the buffer address pool and get a +.Va ticket +for subsequent +.Dv DIOCADDADDR , +.Dv DIOCADDRULE , +and +.Dv DIOCCHANGERULE +calls. +.It Dv DIOCADDADDR Fa "struct pfioc_pooladdr *pp" +.Pp +Add the pool address +.Va addr +to the buffer address pool to be used in the following +.Dv DIOCADDRULE +or +.Dv DIOCCHANGERULE +call. +All other members of the structure are ignored. +.It Dv DIOCADDRULE Fa "struct pfioc_rule *pr" +.Bd -literal +struct pfioc_rule { + u_int32_t action; + u_int32_t ticket; + u_int32_t pool_ticket; + u_int32_t nr; + char anchor[MAXPATHLEN]; + char anchor_call[MAXPATHLEN]; + struct pf_rule rule; +}; +.Ed +.Pp +Add +.Va rule +at the end of the inactive ruleset. +This call requires a +.Va ticket +obtained through a preceding +.Dv DIOCXBEGIN +call and a +.Va pool_ticket +obtained through a +.Dv DIOCBEGINADDRS +call. +.Dv DIOCADDADDR +must also be called if any pool addresses are required. +The optional +.Va anchor +name indicates the anchor in which to append the rule. +.Va nr +and +.Va action +are ignored. +.It Dv DIOCADDALTQ Fa "struct pfioc_altq *pa" +Add an ALTQ discipline or queue. +.Bd -literal +struct pfioc_altq { + u_int32_t action; + u_int32_t ticket; + u_int32_t nr; + struct pf_altq altq; +}; +.Ed +.It Dv DIOCGETRULES Fa "struct pfioc_rule *pr" +Get a +.Va ticket +for subsequent +.Dv DIOCGETRULE +calls and the number +.Va nr +of rules in the active ruleset. +.It Dv DIOCGETRULE Fa "struct pfioc_rule *pr" +Get a +.Va rule +by its number +.Va nr +using the +.Va ticket +obtained through a preceding +.Dv DIOCGETRULES +call. +If +.Va action +is set to +.Dv PF_GET_CLR_CNTR , +the per-rule statistics on the requested rule are cleared. +.It Dv DIOCGETADDRS Fa "struct pfioc_pooladdr *pp" +Get a +.Va ticket +for subsequent +.Dv DIOCGETADDR +calls and the number +.Va nr +of pool addresses in the rule specified with +.Va r_action , +.Va r_num , +and +.Va anchor . +.It Dv DIOCGETADDR Fa "struct pfioc_pooladdr *pp" +Get the pool address +.Va addr +by its number +.Va nr +from the rule specified with +.Va r_action , +.Va r_num , +and +.Va anchor +using the +.Va ticket +obtained through a preceding +.Dv DIOCGETADDRS +call. +.It Dv DIOCGETALTQS Fa "struct pfioc_altq *pa" +Get a +.Va ticket +for subsequent +.Dv DIOCGETALTQ +calls and the number +.Va nr +of queues in the active list. +.It Dv DIOCGETALTQ Fa "struct pfioc_altq *pa" +Get the queueing discipline +.Va altq +by its number +.Va nr +using the +.Va ticket +obtained through a preceding +.Dv DIOCGETALTQS +call. +.It Dv DIOCGETQSTATS Fa "struct pfioc_qstats *pq" +Get the statistics on a queue. +.Bd -literal +struct pfioc_qstats { + u_int32_t ticket; + u_int32_t nr; + void *buf; + int nbytes; + u_int8_t scheduler; +}; +.Ed +.Pp +This call fills in a pointer to the buffer of statistics +.Va buf , +of length +.Va nbytes , +for the queue specified by +.Va nr . +.It Dv DIOCGETRULESETS Fa "struct pfioc_ruleset *pr" +.Bd -literal +struct pfioc_ruleset { + u_int32_t nr; + char path[MAXPATHLEN]; + char name[PF_ANCHOR_NAME_SIZE]; +}; +.Ed +.Pp +Get the number +.Va nr +of rulesets (i.e., anchors) directly attached to the anchor named by +.Va path +for use in subsequent +.Dv DIOCGETRULESET +calls. +Nested anchors, since they are not directly attached to the given +anchor, will not be included. +This ioctl returns +.Er ENOENT +if the parent anchor given at +.Va path +does not exist. +.It Dv DIOCGETRULESET Fa "struct pfioc_ruleset *pr" +Get a ruleset (i.e., an anchor) +.Va name +by its number +.Va nr +from the given anchor +.Va path , +the maximum number of which can be obtained from a preceding +.Dv DIOCGETRULESETS +call. +This ioctl returns +.Er ENOENT +if the parent anchor given by +.Va path +does not exist or +.Er EBUSY +if the index passed in by +.Va nr +is greater than the number of anchors. +.It Dv DIOCADDSTATE Fa "struct pfioc_state *ps" +Add a state entry. +.Bd -literal +struct pfioc_state { + struct pfsync_state state; +}; +.Ed +.It Dv DIOCGETSTATENV Fa "struct pfioc_nv *nv" +Extract the entry identified by the +.Va id +and +.Va creatorid +fields of the +.Va state +nvlist from the state table. +.It Dv DIOCKILLSTATESNV Fa "struct pfioc_nv nv" +Remove matching entries from the state table. +This ioctl returns the number of killed states in +.Va "killed" . +.Bd -literal +nvlist pf_state_cmp { + number id; + number creatorid; + number direction; +}; + +nvlist pf_kill { + nvlist pf_state_cmp cmp; + number af; + number proto; + nvlist pf_rule_addr src; + nvlist pf_rule_addr dst; + string ifname[IFNAMSIZ]; + string label[PF_RULE_LABEL_SIZE]; +}; +.Ed +.It Dv DIOCCLRSTATESNV Fa "struct pfioc_nv nv" +Clear all states. +It works like +.Dv DIOCKILLSTATESNV , +but ignores the +.Va af , +.Va proto , +.Va src , +and +.Va dst +fields of the +.Vt pf_kill +nvlist. +.It Dv DIOCSETSTATUSIF Fa "struct pfioc_if *pi" +Specify the interface for which statistics are accumulated. +.Bd -literal +struct pfioc_if { + char ifname[IFNAMSIZ]; +}; +.Ed +.It Dv DIOCGETSTATUS Fa "struct pf_status *s" +Get the internal packet filter statistics. +.Bd -literal +struct pf_status { + u_int64_t counters[PFRES_MAX]; + u_int64_t lcounters[LCNT_MAX]; + u_int64_t fcounters[FCNT_MAX]; + u_int64_t scounters[SCNT_MAX]; + u_int64_t pcounters[2][2][3]; + u_int64_t bcounters[2][2]; + u_int32_t running; + u_int32_t states; + u_int32_t src_nodes; + u_int32_t since; + u_int32_t debug; + u_int32_t hostid; + char ifname[IFNAMSIZ]; + u_int8_t pf_chksum[MD5_DIGEST_LENGTH]; +}; +.Ed +.It Dv DIOCCLRSTATUS +Clear the internal packet filter statistics. +.It Dv DIOCNATLOOK Fa "struct pfioc_natlook *pnl" +Look up a state table entry by source and destination addresses and ports. +.Bd -literal +struct pfioc_natlook { + struct pf_addr saddr; + struct pf_addr daddr; + struct pf_addr rsaddr; + struct pf_addr rdaddr; + u_int16_t sport; + u_int16_t dport; + u_int16_t rsport; + u_int16_t rdport; + sa_family_t af; + u_int8_t proto; + u_int8_t direction; +}; +.Ed +.It Dv DIOCSETDEBUG Fa "u_int32_t *level" +Set the debug level. +.Bd -literal +enum { PF_DEBUG_NONE, PF_DEBUG_URGENT, PF_DEBUG_MISC, + PF_DEBUG_NOISY }; +.Ed +.It Dv DIOCGETSTATESV2 Fa "struct pfioc_states_v2 *ps" +Get state table entries. +.Bd -literal +struct pfioc_states_v2 { + int ps_len; + uint64_t ps_req_version; + union { + void *ps_buf; + struct pf_state_export *ps_states; + }; +}; + +struct pf_state_export { + uint64_t version; + uint64_t id; + char ifname[IFNAMSIZ]; + char orig_ifname[IFNAMSIZ]; + struct pf_state_key_export key[2]; + struct pf_state_peer_export src; + struct pf_state_peer_export dst; + struct pf_addr rt_addr; + uint32_t rule; + uint32_t anchor; + uint32_t nat_rule; + uint32_t creation; + uint32_t expire; + uint32_t spare0; + uint64_t packets[2]; + uint64_t bytes[2]; + uint32_t creatorid; + uint32_t spare1; + sa_family_t af; + uint8_t proto; + uint8_t direction; + uint8_t log; + uint8_t state_flags_compat; + uint8_t timeout; + uint8_t sync_flags; + uint8_t updates; + uint16_t state_flags; + uint16_t qid; + uint16_t pqid; + uint16_t dnpipe; + uint16_t dnrpipe; + int32_t rtableid; + uint8_t min_ttl; + uint8_t set_tos; + uint16_t max_mss; + uint8_t set_prio[2]; + uint8_t rt; + char rt_ifname[IFNAMSIZ]; + uint8_t spare[72]; +}; +.Ed +.It Dv DIOCCHANGERULE Fa "struct pfioc_rule *pcr" +Add or remove the +.Va rule +in the ruleset specified by +.Va rule.action . +.Pp +The type of operation to be performed is indicated by +.Va action , +which can be any of the following: +.Bd -literal +enum { PF_CHANGE_NONE, PF_CHANGE_ADD_HEAD, PF_CHANGE_ADD_TAIL, + PF_CHANGE_ADD_BEFORE, PF_CHANGE_ADD_AFTER, + PF_CHANGE_REMOVE, PF_CHANGE_GET_TICKET }; +.Ed +.Pp +.Va ticket +must be set to the value obtained with +.Dv PF_CHANGE_GET_TICKET +for all actions except +.Dv PF_CHANGE_GET_TICKET . +.Va pool_ticket +must be set to the value obtained with the +.Dv DIOCBEGINADDRS +call for all actions except +.Dv PF_CHANGE_REMOVE +and +.Dv PF_CHANGE_GET_TICKET . +.Va anchor +indicates to which anchor the operation applies. +.Va nr +indicates the rule number against which +.Dv PF_CHANGE_ADD_BEFORE , +.Dv PF_CHANGE_ADD_AFTER , +or +.Dv PF_CHANGE_REMOVE +actions are applied. +.\" It Dv DIOCCHANGEALTQ Fa "struct pfioc_altq *pcr" +.It Dv DIOCCHANGEADDR Fa "struct pfioc_pooladdr *pca" +Add or remove the pool address +.Va addr +from the rule specified by +.Va r_action , +.Va r_num , +and +.Va anchor . +.It Dv DIOCSETTIMEOUT Fa "struct pfioc_tm *pt" +.Bd -literal +struct pfioc_tm { + int timeout; + int seconds; +}; +.Ed +.Pp +Set the state timeout of +.Va timeout +to +.Va seconds . +The old value will be placed into +.Va seconds . +For possible values of +.Va timeout , +consult the +.Dv PFTM_* +values in +.Aq Pa net/pfvar.h . +.It Dv DIOCGETTIMEOUT Fa "struct pfioc_tm *pt" +Get the state timeout of +.Va timeout . +The value will be placed into the +.Va seconds +field. +.It Dv DIOCCLRRULECTRS +Clear per-rule statistics. +.It Dv DIOCSETLIMIT Fa "struct pfioc_limit *pl" +Set the hard limits on the memory pools used by the packet filter. +.Bd -literal +struct pfioc_limit { + int index; + unsigned limit; +}; + +enum { PF_LIMIT_STATES, PF_LIMIT_SRC_NODES, PF_LIMIT_FRAGS, + PF_LIMIT_TABLE_ENTRIES, PF_LIMIT_MAX }; +.Ed +.It Dv DIOCGETLIMIT Fa "struct pfioc_limit *pl" +Get the hard +.Va limit +for the memory pool indicated by +.Va index . +.It Dv DIOCRCLRTABLES Fa "struct pfioc_table *io" +Clear all tables. +All the ioctls that manipulate radix tables +use the same structure described below. +For +.Dv DIOCRCLRTABLES , +.Va pfrio_ndel +contains on exit the number of tables deleted. +.Bd -literal +struct pfioc_table { + struct pfr_table pfrio_table; + void *pfrio_buffer; + int pfrio_esize; + int pfrio_size; + int pfrio_size2; + int pfrio_nadd; + int pfrio_ndel; + int pfrio_nchange; + int pfrio_flags; + u_int32_t pfrio_ticket; +}; +#define pfrio_exists pfrio_nadd +#define pfrio_nzero pfrio_nadd +#define pfrio_nmatch pfrio_nadd +#define pfrio_naddr pfrio_size2 +#define pfrio_setflag pfrio_size2 +#define pfrio_clrflag pfrio_nadd +.Ed +.It Dv DIOCRADDTABLES Fa "struct pfioc_table *io" +Create one or more tables. +On entry, +.Va pfrio_buffer +must point to an array of +.Vt struct pfr_table +containing at least +.Vt pfrio_size +elements. +.Vt pfrio_esize +must be the size of +.Vt struct pfr_table . +On exit, +.Va pfrio_nadd +contains the number of tables effectively created. +.Bd -literal +struct pfr_table { + char pfrt_anchor[MAXPATHLEN]; + char pfrt_name[PF_TABLE_NAME_SIZE]; + u_int32_t pfrt_flags; + u_int8_t pfrt_fback; +}; +.Ed +.It Dv DIOCRDELTABLES Fa "struct pfioc_table *io" +Delete one or more tables. +On entry, +.Va pfrio_buffer +must point to an array of +.Vt struct pfr_table +containing at least +.Vt pfrio_size +elements. +.Vt pfrio_esize +must be the size of +.Vt struct pfr_table . +On exit, +.Va pfrio_ndel +contains the number of tables effectively deleted. +.It Dv DIOCRGETTABLES Fa "struct pfioc_table *io" +Get the list of all tables. +On entry, +.Va pfrio_buffer[pfrio_size] +contains a valid writeable buffer for +.Vt pfr_table +structures. +On exit, +.Va pfrio_size +contains the number of tables written into the buffer. +If the buffer is too small, the kernel does not store anything but just +returns the required buffer size, without error. +.It Dv DIOCRGETTSTATS Fa "struct pfioc_table *io" +This call is like +.Dv DIOCRGETTABLES +but is used to get an array of +.Vt pfr_tstats +structures. +.Bd -literal +struct pfr_tstats { + struct pfr_table pfrts_t; + u_int64_t pfrts_packets + [PFR_DIR_MAX][PFR_OP_TABLE_MAX]; + u_int64_t pfrts_bytes + [PFR_DIR_MAX][PFR_OP_TABLE_MAX]; + u_int64_t pfrts_match; + u_int64_t pfrts_nomatch; + time_t pfrts_tzero; + int pfrts_cnt; + int pfrts_refcnt[PFR_REFCNT_MAX]; +}; +#define pfrts_name pfrts_t.pfrt_name +#define pfrts_flags pfrts_t.pfrt_flags +.Ed +.It Dv DIOCRCLRTSTATS Fa "struct pfioc_table *io" +Clear the statistics of one or more tables. +On entry, +.Va pfrio_buffer +must point to an array of +.Vt struct pfr_table +containing at least +.Vt pfrio_size +elements. +.Vt pfrio_esize +must be the size of +.Vt struct pfr_table . +On exit, +.Va pfrio_nzero +contains the number of tables effectively cleared. +.It Dv DIOCRCLRADDRS Fa "struct pfioc_table *io" +Clear all addresses in a table. +On entry, +.Va pfrio_table +contains the table to clear. +On exit, +.Va pfrio_ndel +contains the number of addresses removed. +.It Dv DIOCRADDADDRS Fa "struct pfioc_table *io" +Add one or more addresses to a table. +On entry, +.Va pfrio_table +contains the table ID and +.Va pfrio_buffer +must point to an array of +.Vt struct pfr_addr +containing at least +.Vt pfrio_size +elements to add to the table. +.Vt pfrio_esize +must be the size of +.Vt struct pfr_addr . +On exit, +.Va pfrio_nadd +contains the number of addresses effectively added. +.Bd -literal +struct pfr_addr { + union { + struct in_addr _pfra_ip4addr; + struct in6_addr _pfra_ip6addr; + } pfra_u; + u_int8_t pfra_af; + u_int8_t pfra_net; + u_int8_t pfra_not; + u_int8_t pfra_fback; +}; +#define pfra_ip4addr pfra_u._pfra_ip4addr +#define pfra_ip6addr pfra_u._pfra_ip6addr +.Ed +.It Dv DIOCRDELADDRS Fa "struct pfioc_table *io" +Delete one or more addresses from a table. +On entry, +.Va pfrio_table +contains the table ID and +.Va pfrio_buffer +must point to an array of +.Vt struct pfr_addr +containing at least +.Vt pfrio_size +elements to delete from the table. +.Vt pfrio_esize +must be the size of +.Vt struct pfr_addr . +On exit, +.Va pfrio_ndel +contains the number of addresses effectively deleted. +.It Dv DIOCRSETADDRS Fa "struct pfioc_table *io" +Replace the content of a table by a new address list. +This is the most complicated command, which uses all the structure members. +.Pp +On entry, +.Va pfrio_table +contains the table ID and +.Va pfrio_buffer +must point to an array of +.Vt struct pfr_addr +containing at least +.Vt pfrio_size +elements which become the new contents of the table. +.Vt pfrio_esize +must be the size of +.Vt struct pfr_addr . +Additionally, if +.Va pfrio_size2 +is non-zero, +.Va pfrio_buffer[pfrio_size..pfrio_size2] +must be a writeable buffer, into which the kernel can copy the +addresses that have been deleted during the replace operation. +On exit, +.Va pfrio_ndel , +.Va pfrio_nadd , +and +.Va pfrio_nchange +contain the number of addresses deleted, added, and changed by the +kernel. +If +.Va pfrio_size2 +was set on entry, +.Va pfrio_size2 +will point to the size of the buffer used, exactly like +.Dv DIOCRGETADDRS . +.It Dv DIOCRGETADDRS Fa "struct pfioc_table *io" +Get all the addresses of a table. +On entry, +.Va pfrio_table +contains the table ID and +.Va pfrio_buffer[pfrio_size] +contains a valid writeable buffer for +.Vt pfr_addr +structures. +On exit, +.Va pfrio_size +contains the number of addresses written into the buffer. +If the buffer was too small, the kernel does not store anything but just +returns the required buffer size, without returning an error. +.It Dv DIOCRGETASTATS Fa "struct pfioc_table *io" +This call is like +.Dv DIOCRGETADDRS +but is used to get an array of +.Vt pfr_astats +structures. +.Bd -literal +struct pfr_astats { + struct pfr_addr pfras_a; + u_int64_t pfras_packets + [PFR_DIR_MAX][PFR_OP_ADDR_MAX]; + u_int64_t pfras_bytes + [PFR_DIR_MAX][PFR_OP_ADDR_MAX]; + time_t pfras_tzero; +}; +.Ed +.It Dv DIOCRCLRASTATS Fa "struct pfioc_table *io" +Clear the statistics of one or more addresses. +On entry, +.Va pfrio_table +contains the table ID and +.Va pfrio_buffer +must point to an array of +.Vt struct pfr_addr +containing at least +.Vt pfrio_size +elements to be cleared from the table. +.Vt pfrio_esize +must be the size of +.Vt struct pfr_addr . +On exit, +.Va pfrio_nzero +contains the number of addresses effectively cleared. +.It Dv DIOCRTSTADDRS Fa "struct pfioc_table *io" +Test if the given addresses match a table. +On entry, +.Va pfrio_table +contains the table ID and +.Va pfrio_buffer +must point to an array of +.Vt struct pfr_addr +containing at least +.Vt pfrio_size +elements, each of which will be tested for a match in the table. +.Vt pfrio_esize +must be the size of +.Vt struct pfr_addr . +On exit, the kernel updates the +.Vt pfr_addr +array by setting the +.Va pfra_fback +member appropriately. +.It Dv DIOCRSETTFLAGS Fa "struct pfioc_table *io" +Change the +.Dv PFR_TFLAG_CONST +or +.Dv PFR_TFLAG_PERSIST +flags of a table. +On entry, +.Va pfrio_buffer +must point to an array of +.Vt struct pfr_table +containing at least +.Vt pfrio_size +elements. +.Va pfrio_esize +must be the size of +.Vt struct pfr_table . +.Va pfrio_setflag +must contain the flags to add, while +.Va pfrio_clrflag +must contain the flags to remove. +On exit, +.Va pfrio_nchange +and +.Va pfrio_ndel +contain the number of tables altered or deleted by the kernel. +Yes, tables can be deleted if one removes the +.Dv PFR_TFLAG_PERSIST +flag of an unreferenced table. +.It Dv DIOCRINADEFINE Fa "struct pfioc_table *io" +Defines a table in the inactive set. +On entry, +.Va pfrio_table +contains the table ID and +.Va pfrio_buffer[pfrio_size] +contains an array of +.Vt pfr_addr +structures to put in the table. +A valid ticket must also be supplied to +.Va pfrio_ticket . +On exit, +.Va pfrio_nadd +contains 0 if the table was already defined in the inactive list +or 1 if a new table has been created. +.Va pfrio_naddr +contains the number of addresses effectively put in the table. +.It Dv DIOCXBEGIN Fa "struct pfioc_trans *io" +.Bd -literal +struct pfioc_trans { + int size; /* number of elements */ + int esize; /* size of each element in bytes */ + struct pfioc_trans_e { + int rs_num; + char anchor[MAXPATHLEN]; + u_int32_t ticket; + } *array; +}; +.Ed +.Pp +Clear all the inactive rulesets specified in the +.Vt pfioc_trans_e +array. +For each ruleset, a ticket is returned for subsequent "add rule" ioctls, +as well as for the +.Dv DIOCXCOMMIT +and +.Dv DIOCXROLLBACK +calls. +.Pp +Ruleset types, identified by +.Va rs_num , +include the following: +.Pp +.Bl -tag -width PF_RULESET_FILTER -offset ind -compact +.It Dv PF_RULESET_SCRUB +Scrub (packet normalization) rules. +.It Dv PF_RULESET_FILTER +Filter rules. +.It Dv PF_RULESET_NAT +NAT (Network Address Translation) rules. +.It Dv PF_RULESET_BINAT +Bidirectional NAT rules. +.It Dv PF_RULESET_RDR +Redirect rules. +.It Dv PF_RULESET_ALTQ +ALTQ disciplines. +.It Dv PF_RULESET_TABLE +Address tables. +.El +.It Dv DIOCXCOMMIT Fa "struct pfioc_trans *io" +Atomically switch a vector of inactive rulesets to the active rulesets. +This call is implemented as a standard two-phase commit, which will either +fail for all rulesets or completely succeed. +All tickets need to be valid. +This ioctl returns +.Er EBUSY +if another process is concurrently updating some of the same rulesets. +.It Dv DIOCXROLLBACK Fa "struct pfioc_trans *io" +Clean up the kernel by undoing all changes that have taken place on the +inactive rulesets since the last +.Dv DIOCXBEGIN . +.Dv DIOCXROLLBACK +will silently ignore rulesets for which the ticket is invalid. +.It Dv DIOCSETHOSTID Fa "u_int32_t *hostid" +Set the host ID, which is used by +.Xr pfsync 4 +to identify which host created state table entries. +.It Dv DIOCOSFPFLUSH +Flush the passive OS fingerprint table. +.It Dv DIOCOSFPADD Fa "struct pf_osfp_ioctl *io" +.Bd -literal +struct pf_osfp_ioctl { + struct pf_osfp_entry { + SLIST_ENTRY(pf_osfp_entry) fp_entry; + pf_osfp_t fp_os; + char fp_class_nm[PF_OSFP_LEN]; + char fp_version_nm[PF_OSFP_LEN]; + char fp_subtype_nm[PF_OSFP_LEN]; + } fp_os; + pf_tcpopts_t fp_tcpopts; + u_int16_t fp_wsize; + u_int16_t fp_psize; + u_int16_t fp_mss; + u_int16_t fp_flags; + u_int8_t fp_optcnt; + u_int8_t fp_wscale; + u_int8_t fp_ttl; + int fp_getnum; +}; +.Ed +.Pp +Add a passive OS fingerprint to the table. +Set +.Va fp_os.fp_os +to the packed fingerprint, +.Va fp_os.fp_class_nm +to the name of the class (Linux, Windows, etc), +.Va fp_os.fp_version_nm +to the name of the version (NT, 95, 98), and +.Va fp_os.fp_subtype_nm +to the name of the subtype or patchlevel. +The members +.Va fp_mss , +.Va fp_wsize , +.Va fp_psize , +.Va fp_ttl , +.Va fp_optcnt , +and +.Va fp_wscale +are set to the TCP MSS, the TCP window size, the IP length, the IP TTL, +the number of TCP options, and the TCP window scaling constant of the +TCP SYN packet, respectively. +.Pp +The +.Va fp_flags +member is filled according to the +.Aq Pa net/pfvar.h +include file +.Dv PF_OSFP_* +defines. +The +.Va fp_tcpopts +member contains packed TCP options. +Each option uses +.Dv PF_OSFP_TCPOPT_BITS +bits in the packed value. +Options include any of +.Dv PF_OSFP_TCPOPT_NOP , +.Dv PF_OSFP_TCPOPT_SACK , +.Dv PF_OSFP_TCPOPT_WSCALE , +.Dv PF_OSFP_TCPOPT_MSS , +or +.Dv PF_OSFP_TCPOPT_TS . +.Pp +The +.Va fp_getnum +member is not used with this ioctl. +.Pp +The structure's slack space must be zeroed for correct operation; +.Xr memset 3 +the whole structure to zero before filling and sending to the kernel. +.It Dv DIOCOSFPGET Fa "struct pf_osfp_ioctl *io" +Get the passive OS fingerprint number +.Va fp_getnum +from the kernel's fingerprint list. +The rest of the structure members will come back filled. +Get the whole list by repeatedly incrementing the +.Va fp_getnum +number until the ioctl returns +.Er EBUSY . +.It Dv DIOCGETSRCNODES Fa "struct pfioc_src_nodes *psn" +.Bd -literal +struct pfioc_src_nodes { + int psn_len; + union { + caddr_t psu_buf; + struct pf_src_node *psu_src_nodes; + } psn_u; +#define psn_buf psn_u.psu_buf +#define psn_src_nodes psn_u.psu_src_nodes +}; +.Ed +.Pp +Get the list of source nodes kept by sticky addresses and source +tracking. +The ioctl must be called once with +.Va psn_len +set to 0. +If the ioctl returns without error, +.Va psn_len +will be set to the size of the buffer required to hold all the +.Va pf_src_node +structures held in the table. +A buffer of this size should then be allocated, and a pointer to this buffer +placed in +.Va psn_buf . +The ioctl must then be called again to fill this buffer with the actual +source node data. +After that call, +.Va psn_len +will be set to the length of the buffer actually used. +.It Dv DIOCCLRSRCNODES +Clear the tree of source tracking nodes. +.It Dv DIOCIGETIFACES Fa "struct pfioc_iface *io" +Get the list of interfaces and interface groups known to +.Nm . +All the ioctls that manipulate interfaces +use the same structure described below: +.Bd -literal +struct pfioc_iface { + char pfiio_name[IFNAMSIZ]; + void *pfiio_buffer; + int pfiio_esize; + int pfiio_size; + int pfiio_nzero; + int pfiio_flags; +}; +.Ed +.Pp +If not empty, +.Va pfiio_name +can be used to restrict the search to a specific interface or group. +.Va pfiio_buffer[pfiio_size] +is the user-supplied buffer for returning the data. +On entry, +.Va pfiio_size +contains the number of +.Vt pfi_kif +entries that can fit into the buffer. +The kernel will replace this value by the real number of entries it wants +to return. +.Va pfiio_esize +should be set to +.Li sizeof(struct pfi_kif) . +.Pp +The data is returned in the +.Vt pfi_kif +structure described below: +.Bd -literal +struct pfi_kif { + char pfik_name[IFNAMSIZ]; + union { + RB_ENTRY(pfi_kif) pfik_tree; + LIST_ENTRY(pfi_kif) pfik_list; + }; + u_int64_t pfik_packets[2][2][2]; + u_int64_t pfik_bytes[2][2][2]; + u_int32_t pfik_tzero; + u_int pfik_flags; + struct ifnet *pfik_ifp; + struct ifg_group *pfik_group; + u_int pfik_rulerefs; + TAILQ_HEAD(, pfi_dynaddr) pfik_dynaddrs; +}; +.Ed +.It Dv DIOCSETIFFLAG Fa "struct pfioc_iface *io" +Set the user settable flags (described above) of the +.Nm +internal interface description. +The filtering process is the same as for +.Dv DIOCIGETIFACES . +.Bd -literal +#define PFI_IFLAG_SKIP 0x0100 /* skip filtering on interface */ +.Ed +.It Dv DIOCCLRIFFLAG Fa "struct pfioc_iface *io" +Works as +.Dv DIOCSETIFFLAG +above but clears the flags. +.It Dv DIOCKILLSRCNODES Fa "struct pfioc_iface *io" +Explicitly remove source tracking nodes. +.El +.Sh FILES +.Bl -tag -width /dev/pf -compact +.It Pa /dev/pf +packet filtering device. +.El +.Sh EXAMPLES +The following example demonstrates how to use the +.Dv DIOCNATLOOK +command to find the internal host/port of a NATed connection: +.Bd -literal +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +u_int32_t +read_address(const char *s) +{ + int a, b, c, d; + + sscanf(s, "%i.%i.%i.%i", &a, &b, &c, &d); + return htonl(a << 24 | b << 16 | c << 8 | d); +} + +void +print_address(u_int32_t a) +{ + a = ntohl(a); + printf("%d.%d.%d.%d", a >> 24 & 255, a >> 16 & 255, + a >> 8 & 255, a & 255); +} + +int +main(int argc, char *argv[]) +{ + struct pfioc_natlook nl; + int dev; + + if (argc != 5) { + printf("%s \\n", + argv[0]); + return 1; + } + + dev = open("/dev/pf", O_RDWR); + if (dev == -1) + err(1, "open(\\"/dev/pf\\") failed"); + + memset(&nl, 0, sizeof(struct pfioc_natlook)); + nl.saddr.v4.s_addr = read_address(argv[1]); + nl.sport = htons(atoi(argv[2])); + nl.daddr.v4.s_addr = read_address(argv[3]); + nl.dport = htons(atoi(argv[4])); + nl.af = AF_INET; + nl.proto = IPPROTO_TCP; + nl.direction = PF_IN; + + if (ioctl(dev, DIOCNATLOOK, &nl)) + err(1, "DIOCNATLOOK"); + + printf("internal host "); + print_address(nl.rsaddr.v4.s_addr); + printf(":%u\\n", ntohs(nl.rsport)); + return 0; +} +.Ed +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr altq 4 , +.Xr if_bridge 4 , +.Xr pflog 4 , +.Xr pfsync 4 , +.Xr pfctl 8 , +.Xr altq 9 +.Sh HISTORY +The +.Nm +packet filtering mechanism first appeared in +.Ox 3.0 +and then +.Fx 5.2 . +.Pp +This implementation is derived from +.Ox 4.5 . +A number of individual features, improvements, bug fixes and security fixes +have been ported from later versions of +.Ox . +It has been heavily modified to be capable of running in multithreaded +.Fx +kernel and scale its performance on multiple CPUs. diff --git a/static/freebsd/man4/pflog.4 b/static/freebsd/man4/pflog.4 new file mode 100644 index 00000000..c665268e --- /dev/null +++ b/static/freebsd/man4/pflog.4 @@ -0,0 +1,115 @@ +.\" $OpenBSD: pflog.4,v 1.10 2007/05/31 19:19:51 jmc Exp $ +.\" +.\" Copyright (c) 2001 Tobias Weingartner +.\" 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 ``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 October 29, 2021 +.Dt PFLOG 4 +.Os +.Sh NAME +.Nm pflog +.Nd packet filter logging interface +.Sh SYNOPSIS +.Cd "device pflog" +.Sh DESCRIPTION +The +.Nm pflog +interface is a device which makes visible all packets logged by +the packet filter, +.Xr pf 4 . +Logged packets can easily be monitored in real +time by invoking +.Xr tcpdump 1 +on the +.Nm +interface, or stored to disk using +.Xr pflogd 8 . +.Pp +The pflog0 interface is created when the +.Nm +module is loaded; +further instances can be created using +.Xr ifconfig 8 . +The +.Nm +module is loaded automatically if both +.Xr pf 4 +and +.Xr pflogd 8 +are enabled. +.Pp +Each packet retrieved on this interface has a header associated +with it of length +.Dv PFLOG_HDRLEN . +This header documents the address family, interface name, rule +number, reason, action, and direction of the packet that was logged. +This structure, defined in +.Aq Pa net/if_pflog.h +looks like +.Bd -literal -offset indent +struct pfloghdr { + u_int8_t length; + sa_family_t af; + u_int8_t action; + u_int8_t reason; + char ifname[IFNAMSIZ]; + char ruleset[PF_RULESET_NAME_SIZE]; + u_int32_t rulenr; + u_int32_t subrulenr; + uid_t uid; + pid_t pid; + uid_t rule_uid; + pid_t rule_pid; + u_int8_t dir; + u_int8_t pad[3]; + u_int32_t ridentifier; +}; +.Ed +.Sh EXAMPLES +Create a +.Nm +interface +and monitor all packets logged on it: +.Bd -literal -offset indent +# ifconfig pflog create +pflog1 +# ifconfig pflog1 up +# tcpdump -n -e -ttt -i pflog1 +.Ed +.Sh SEE ALSO +.Xr tcpdump 1 , +.Xr inet 4 , +.Xr inet6 4 , +.Xr netintro 4 , +.Xr pf 4 , +.Xr ifconfig 8 , +.Xr pflogd 8 +.Sh HISTORY +The +.Nm +device first appeared in +.Ox 3.0 . +.Sh BUGS +FreeBSD does not set a process id in the +.Fa pid +field in pfloghdr. diff --git a/static/freebsd/man4/pflow.4 b/static/freebsd/man4/pflow.4 new file mode 100644 index 00000000..320a7527 --- /dev/null +++ b/static/freebsd/man4/pflow.4 @@ -0,0 +1,123 @@ +.\" $OpenBSD: pflow.4,v 1.19 2014/03/29 11:26:03 florian Exp $ +.\" +.\" Copyright (c) 2008 Henning Brauer +.\" Copyright (c) 2008 Joerg Goltermann +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: January 08 2024 $ +.Dt PFLOW 4 +.Os +.Sh NAME +.Nm pflow +.Nd kernel interface for pflow data export +.Sh SYNOPSIS +.Cd "pseudo-device pflow" +.Sh DESCRIPTION +The +.Nm +subsystem exports +.Nm +accounting data from the kernel using +.Xr udp 4 +packets. +.Nm +is compatible with netflow version 5 and IPFIX (10). +The data is extracted from the +.Xr pf 4 +state table. +.Pp +Multiple +.Nm +interfaces can be created at runtime using the +.Ic pflowctl Ns Ar N Ic -c +command. +Each interface must be configured with a flow receiver IP address +and a flow receiver port number. +.Pp +Only states created by a rule marked with the +.Ar pflow +keyword are exported by +.Nm . +.Pp +.Nm +will attempt to export multiple +.Nm +records in one +UDP packet, but will not hold a record for longer than 30 seconds. +.Pp +Each packet seen on this interface has one header and a variable number of +flows. +The header indicates the version of the protocol, number of +flows in the packet, a unique sequence number, system time, and an engine +ID and type. +Header and flow structs are defined in +.In net/pflow.h . +.Pp +The +.Nm +source and destination addresses are controlled by +.Xr pflowctl 8 . +.Cm src +is the sender IP address of the UDP packet which can be used +to identify the source of the data on the +.Nm +collector. +.Cm dst +defines the collector IP address and the port. +The +.Cm dst +IP address and port must be defined to enable the export of flows. +.Pp +For example, the following command sets 10.0.0.1 as the source +and 10.0.0.2:1234 as destination: +.Bd -literal -offset indent +# pflowctl -s pflow0 src 10.0.0.1 dst 10.0.0.2:1234 +.Ed +.Pp +The protocol is set to IPFIX with the following command: +.Bd -literal -offset indent +# pflowctl -s pflow0 proto 10 +.Ed +.Sh SEE ALSO +.Xr netintro 4 , +.Xr pf 4 , +.Xr udp 4 , +.Xr pf.conf 5 , +.Xr pflowctl 8 , +.Xr tcpdump 8 +.Sh STANDARDS +.Rs +.%A B. Claise +.%D January 2008 +.%R RFC 5101 +.%T "Specification of the IP Flow Information Export (IPFIX) Protocol for the Exchange of IP Traffic Flow Information" +.Re +.Sh HISTORY +The +.Nm +device first appeared in +.Ox 4.5 +and was imported into +FreeBSD 15.0 . +.Sh BUGS +A state created by +.Xr pfsync 4 +can have a creation or expiration time before the machine came up. +In this case, +.Nm +pretends such flows were created or expired when the machine came up. +.Pp +The IPFIX implementation is incomplete: +The required transport protocol SCTP is not supported. +Transport over TCP and DTLS protected flow export is also not supported. diff --git a/static/freebsd/man4/pfsync.4 b/static/freebsd/man4/pfsync.4 new file mode 100644 index 00000000..c12bad74 --- /dev/null +++ b/static/freebsd/man4/pfsync.4 @@ -0,0 +1,296 @@ +.\" $OpenBSD: pfsync.4,v 1.28 2009/02/17 10:05:18 dlg Exp $ +.\" +.\" Copyright (c) 2002 Michael Shalayeff +.\" Copyright (c) 2003-2004 Ryan McBride +.\" 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 ``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 MIND, +.\" 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 November 08, 2023 +.Dt PFSYNC 4 +.Os +.Sh NAME +.Nm pfsync +.Nd packet filter state table synchronisation interface +.Sh SYNOPSIS +.Cd "device pfsync" +.Pp +In +.Xr loader.conf 5 : +.Cd net.pfsync.pfsync_buckets +.Pp +In +.Xr sysctl.conf 5 : +.Cd net.pfsync.carp_demotion_factor +.Sh DESCRIPTION +The +.Nm +interface is a pseudo-device which exposes certain changes to the state +table used by +.Xr pf 4 . +State changes can be viewed by invoking +.Xr tcpdump 1 +on the +.Nm +interface. +If configured with a physical synchronisation interface, +.Nm +will also send state changes out on that interface, +and insert state changes received on that interface from other systems +into the state table. +.Pp +By default, all local changes to the state table are exposed via +.Nm . +State changes from packets received by +.Nm +over the network are not rebroadcast. +Updates to states created by a rule marked with the +.Ar no-sync +keyword are ignored by the +.Nm +interface (see +.Xr pf.conf 5 +for details). +.Pp +The +.Nm +interface will attempt to collapse multiple state updates into a single +packet where possible. +The maximum number of times a single state can be updated before a +.Nm +packet will be sent out is controlled by the +.Ar maxupd +parameter to ifconfig +(see +.Xr ifconfig 8 +and the example below for more details). +The sending out of a +.Nm +packet will be delayed by a maximum of one second. +.Sh NETWORK SYNCHRONISATION +States can be synchronised between two or more firewalls using this +interface, by specifying a synchronisation interface using +.Xr ifconfig 8 . +For example, the following command sets fxp0 as the synchronisation +interface: +.Bd -literal -offset indent +# ifconfig pfsync0 syncdev fxp0 +.Ed +.Pp +By default, state change messages are sent out on the synchronisation +interface using IP multicast packets to the 224.0.0.240 group address. +An alternative destination address for +.Nm +packets can be specified using the +.Ic syncpeer +keyword. +This can be used in combination with +.Xr ipsec 4 +to protect the synchronisation traffic. +In such a configuration, the syncdev should be set to the +.Xr enc 4 +interface, as this is where the traffic arrives when it is decapsulated, +e.g.: +.Bd -literal -offset indent +# ifconfig pfsync0 syncpeer 10.0.0.2 syncdev enc0 +.Ed +.Pp +It is important that the pfsync traffic be well secured +as there is no authentication on the protocol and it would +be trivial to spoof packets which create states, bypassing the pf ruleset. +Either run the pfsync protocol on a trusted network \- ideally a network +dedicated to pfsync messages such as a crossover cable between two firewalls, +or specify a peer address and protect the traffic with +.Xr ipsec 4 . +.Pp +Support for +.Nm +transport over IPv6 was introduced in +.Fx 14.0 . +To set up +.Nm +using multicast with IPv6 link-local addresses, the +.Ic syncpeer +must be set to the +.Nm +multicast address and the +.Ic syncdev +to the interface where +.Nm +traffic is expected. +.Bd -literal -offset indent +# ifconfig pfsync0 syncpeer ff12::f0 syncdev vtnet0 +.Ed +.Pp +When new features are introduced to +.Xr pf 4 +the format of messages used by +.Nm +might change. +.Nm +will by default use the latest format. +If synchronization with a peer running an older version of FreeBSD is needed the +.Ar version +parameter can be used. +E.g.: +.Bd -literal -offset indent +# ifconfig pfsync0 version 1301 +.Ed +.Pp +Currently the following versions are supported: +.Bl -tag -width indent +.It Cm 1301 +FreeBSD releases 13.2 and older. +Compatibility with FreeBSD 13.1 has been verified. +.It Cm 1400 +FreeBSD release 14.0. +.It Cm 1500 +FreeBSD release 15.0. +.El +.Sh SYSCTL VARIABLES +The following variables can be entered at the +.Xr loader 8 +prompt, set in +.Xr loader.conf 5 , +or changed at runtime with +.Xr sysctl 8 : +.Bl -tag -width indent +.It Va net.pfsync.carp_demotion_factor +Value added to +.Va net.inet.carp.demotion +while +.Nm +tries to perform its bulk update. +See +.Xr carp 4 +for more information. +Default value is 240. +.El +.Sh LOADER TUNABLES +The following tunable may be set in +.Xr loader.conf 5 +or at the +.Xr loader 8 +prompt: +.Bl -tag -width indent +.It Va net.pfsync.pfsync_buckets +The number of +.Nm +buckets. +This affects the performance and memory tradeoff. +Defaults to twice the number of CPUs. +Change only if benchmarks show this helps on your workload. +.El +.Sh EXAMPLES +.Nm +and +.Xr carp 4 +can be used together to provide automatic failover of a pair of firewalls +configured in parallel. +One firewall will handle all traffic until it dies, is shut down, or is +manually demoted, at which point the second firewall will take over +automatically. +.Pp +Both firewalls in this example have three +.Xr sis 4 +interfaces. +sis0 is the external interface, on the 10.0.0.0/24 subnet; sis1 is the +internal interface, on the 192.168.0.0/24 subnet; and sis2 is the +.Nm +interface, using the 192.168.254.0/24 subnet. +A crossover cable connects the two firewalls via their sis2 interfaces. +On all three interfaces, firewall A uses the .254 address, while firewall B +uses .253. +The interfaces are configured as follows (firewall A unless otherwise +indicated): +.Pp +Interfaces configuration in +.Pa /etc/rc.conf : +.Bd -literal -offset indent +network_interfaces="lo0 sis0 sis1 sis2" +ifconfig_sis0="10.0.0.254/24" +ifconfig_sis0_alias0="inet 10.0.0.1/24 vhid 1 pass foo" +ifconfig_sis1="192.168.0.254/24" +ifconfig_sis1_alias0="inet 192.168.0.1/24 vhid 2 pass bar" +ifconfig_sis2="192.168.254.254/24" +pfsync_enable="YES" +pfsync_syncdev="sis2" +.Ed +.Pp +.Xr pf 4 +must also be configured to allow +.Nm +and +.Xr carp 4 +traffic through. +The following should be added to the top of +.Pa /etc/pf.conf : +.Bd -literal -offset indent +pass quick on { sis2 } proto pfsync keep state (no-sync) +pass on { sis0 sis1 } proto carp keep state (no-sync) +.Ed +.Pp +It is preferable that one firewall handle the forwarding of all the traffic, +therefore the +.Ar advskew +on the backup firewall's +.Xr carp 4 +vhids should be set to something higher than +the primary's. +For example, if firewall B is the backup, its +carp1 configuration would look like this: +.Bd -literal -offset indent +ifconfig_sis1_alias0="inet 192.168.0.1/24 vhid 2 pass bar advskew 100" +.Ed +.Pp +The following must also be added to +.Pa /etc/sysctl.conf : +.Bd -literal -offset indent +net.inet.carp.preempt=1 +.Ed +.Sh SEE ALSO +.Xr tcpdump 1 , +.Xr bpf 4 , +.Xr carp 4 , +.Xr enc 4 , +.Xr inet 4 , +.Xr inet6 4 , +.Xr ipsec 4 , +.Xr netintro 4 , +.Xr pf 4 , +.Xr pf.conf 5 , +.Xr protocols 5 , +.Xr rc.conf 5 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device first appeared in +.Ox 3.3 . +It was first imported to +.Fx 5.3 . +.Pp +The +.Nm +protocol and kernel implementation were significantly modified in +.Fx 9.0 . +The newer protocol is not compatible with older one and will not interoperate +with it. diff --git a/static/freebsd/man4/pim.4 b/static/freebsd/man4/pim.4 new file mode 100644 index 00000000..695468ba --- /dev/null +++ b/static/freebsd/man4/pim.4 @@ -0,0 +1,199 @@ +.\" Copyright (c) 2001-2003 International Computer Science Institute +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining a +.\" copy of this software and associated documentation files (the "Software"), +.\" to deal in the Software without restriction, including without limitation +.\" the rights to use, copy, modify, merge, publish, distribute, sublicense, +.\" and/or sell copies of the Software, and to permit persons to whom the +.\" Software is furnished to do so, subject to the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included in +.\" all copies or substantial portions of the Software. +.\" +.\" The names and trademarks of copyright holders may not be used in +.\" advertising or publicity pertaining to the software without specific +.\" prior permission. Title to copyright in this software and any associated +.\" documentation will at all times remain with the copyright holders. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +.\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +.\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +.\" AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +.\" LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +.\" FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +.\" DEALINGS IN THE SOFTWARE. +.\" +.Dd February 12, 2007 +.Dt PIM 4 +.Os +.\" +.Sh NAME +.Nm pim +.Nd Protocol Independent Multicast +.\" +.Sh SYNOPSIS +.Cd "options MROUTING" +.Pp +.In sys/types.h +.In sys/socket.h +.In netinet/in.h +.In netinet/ip_mroute.h +.In netinet/pim.h +.Ft int +.Fn getsockopt "int s" IPPROTO_IP MRT_PIM "void *optval" "socklen_t *optlen" +.Ft int +.Fn setsockopt "int s" IPPROTO_IP MRT_PIM "const void *optval" "socklen_t optlen" +.Ft int +.Fn getsockopt "int s" IPPROTO_IPV6 MRT6_PIM "void *optval" "socklen_t *optlen" +.Ft int +.Fn setsockopt "int s" IPPROTO_IPV6 MRT6_PIM "const void *optval" "socklen_t optlen" +.Sh DESCRIPTION +.Tn PIM +is the common name for two multicast routing protocols: +Protocol Independent Multicast - Sparse Mode (PIM-SM) and +Protocol Independent Multicast - Dense Mode (PIM-DM). +.Pp +PIM-SM is a multicast routing protocol that can use the underlying +unicast routing information base or a separate multicast-capable +routing information base. +It builds unidirectional shared trees rooted at a Rendezvous +Point (RP) per group, +and optionally creates shortest-path trees per source. +.Pp +PIM-DM is a multicast routing protocol that uses the underlying +unicast routing information base to flood multicast datagrams +to all multicast routers. +Prune messages are used to prevent future datagrams from propagating +to routers with no group membership information. +.Pp +Both PIM-SM and PIM-DM are fairly complex protocols, +though PIM-SM is much more complex. +To enable PIM-SM or PIM-DM multicast routing in a router, +the user must enable multicast routing and PIM processing in the kernel +(see +.Sx SYNOPSIS +about the kernel configuration options), +and must run a PIM-SM or PIM-DM capable user-level process. +From developer's point of view, +the programming guide described in the +.Sx "Programming Guide" +section should be used to control the PIM processing in the kernel. +.\" +.Ss Programming Guide +After a multicast routing socket is open and multicast forwarding +is enabled in the kernel +(see +.Xr multicast 4 ) , +one of the following socket options should be used to enable or disable +PIM processing in the kernel. +Note that those options require certain privilege +(i.e., root privilege): +.Bd -literal +/* IPv4 */ +int v = 1; /* 1 to enable, or 0 to disable */ +setsockopt(mrouter_s4, IPPROTO_IP, MRT_PIM, (void *)&v, sizeof(v)); +.Ed +.Bd -literal +/* IPv6 */ +int v = 1; /* 1 to enable, or 0 to disable */ +setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_PIM, (void *)&v, sizeof(v)); +.Ed +.Pp +After PIM processing is enabled, the multicast-capable interfaces +should be added +(see +.Xr multicast 4 ) . +In case of PIM-SM, the PIM-Register virtual interface must be added +as well. +This can be accomplished by using the following options: +.Bd -literal +/* IPv4 */ +struct vifctl vc; +memset(&vc, 0, sizeof(vc)); +/* Assign all vifctl fields as appropriate */ +\&... +if (is_pim_register_vif) + vc.vifc_flags |= VIFF_REGISTER; +setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_VIF, (void *)&vc, + sizeof(vc)); +.Ed +.Bd -literal +/* IPv6 */ +struct mif6ctl mc; +memset(&mc, 0, sizeof(mc)); +/* Assign all mif6ctl fields as appropriate */ +\&... +if (is_pim_register_vif) + mc.mif6c_flags |= MIFF_REGISTER; +setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_ADD_MIF, (void *)&mc, + sizeof(mc)); +.Ed +.Pp +Sending or receiving of PIM packets can be accomplished by +opening first a +.Dq raw socket +(see +.Xr socket 2 ) , +with protocol value of +.Dv IPPROTO_PIM : +.Bd -literal +/* IPv4 */ +int pim_s4; +pim_s4 = socket(AF_INET, SOCK_RAW, IPPROTO_PIM); +.Ed +.Bd -literal +/* IPv6 */ +int pim_s6; +pim_s6 = socket(AF_INET6, SOCK_RAW, IPPROTO_PIM); +.Ed +.Pp +Then, the following system calls can be used to send or receive PIM +packets: +.Xr sendto 2 , +.Xr sendmsg 2 , +.Xr recvfrom 2 , +.Xr recvmsg 2 . +.\" +.Sh SEE ALSO +.Xr getsockopt 2 , +.Xr recvfrom 2 , +.Xr recvmsg 2 , +.Xr sendmsg 2 , +.Xr sendto 2 , +.Xr setsockopt 2 , +.Xr socket 2 , +.Xr inet 4 , +.Xr intro 4 , +.Xr ip 4 , +.Xr multicast 4 +.\" +.Sh STANDARDS +.\" XXX the PIM-SM number must be updated after RFC 2362 is +.\" replaced by a new RFC by the end of year 2003 or so. +The PIM-SM protocol is specified in RFC 2362 (to be replaced by +.%T draft-ietf-pim-sm-v2-new-* ) . +The PIM-DM protocol is specified in +.%T draft-ietf-pim-dm-new-v2-* ) . +.\" +.Sh AUTHORS +.An -nosplit +The original IPv4 PIM kernel support for IRIX and SunOS-4.x was +implemented by +.An Ahmed Helmy +(USC and SGI). +Later the code was ported to various +.Bx +flavors and modified by +.An George Edmond Eddy +(Rusty) (ISI), +.An Hitoshi Asaeda +(WIDE Project), and +.An Pavlin Radoslavov +(USC/ISI and ICSI). +The IPv6 PIM kernel support was implemented by the KAME project +.Pq Pa https://www.kame.net , +and was based on the IPv4 PIM kernel support. +.Pp +This manual page was written by +.An Pavlin Radoslavov +(ICSI). diff --git a/static/freebsd/man4/pms.4 b/static/freebsd/man4/pms.4 new file mode 100644 index 00000000..bf5a3f45 --- /dev/null +++ b/static/freebsd/man4/pms.4 @@ -0,0 +1,124 @@ +.\" Copyright (c) 2015 Christian Brueffer +.\" 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 30, 2015 +.Dt PMS 4 +.Os +.Sh NAME +.Nm pms +.Nd "PMC-Sierra PM8001/8081/8088/8089/8074/8076/8077 SAS/SATA HBA Controller driver" +.Sh SYNOPSIS +To compile the driver into the kernel, +place the following line in the +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device pmspcv" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +pmspcv_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the PMC-Sierra PM8001/8081/8088/8089/8074/8076/8077 +range of SAS/SATA HBA controllers. +.Sh HARDWARE +The +.Nm +driver supports the following hardware: +.Pp +.Bl -bullet -compact +.It +Tachyon TS Fibre Channel Card +.It +Tachyon TL Fibre Channel Card +.It +Tachyon XL2 Fibre Channel Card +.It +Tachyon DX2 Fibre Channel Card +.It +Tachyon DX2+ Fibre Channel Card +.It +Tachyon DX4+ Fibre Channel Card +.It +Tachyon QX2 Fibre Channel Card +.It +Tachyon QX4 Fibre Channel Card +.It +Tachyon DE4 Fibre Channel Card +.It +Tachyon QE4 Fibre Channel Card +.It +Tachyon XL10 Fibre Channel Card +.It +PMC Sierra SPC SAS-SATA Card +.It +PMC Sierra SPC-V SAS-SATA Card +.It +PMC Sierra SPC-VE SAS-SATA Card +.It +PMC Sierra SPC-V 16 Port SAS-SATA Card +.It +PMC Sierra SPC-VE 16 Port SAS-SATA Card +.It +PMC Sierra SPC-V SAS-SATA Card 12Gig +.It +PMC Sierra SPC-VE SAS-SATA Card 12Gig +.It +PMC Sierra SPC-V 16 Port SAS-SATA Card 12Gig +.It +PMC Sierra SPC-VE 16 Port SAS-SATA Card 12Gig +.It +Adaptec Hialeah 4/8 Port SAS-SATA HBA Card 6Gig +.It +Adaptec Hialeah 4/8 Port SAS-SATA RAID Card 6Gig +.It +Adaptec Hialeah 8/16 Port SAS-SATA HBA Card 6Gig +.It +Adaptec Hialeah 8/16 Port SAS-SATA RAID Card 6Gig +.It +Adaptec Hialeah 8/16 Port SAS-SATA HBA Encryption Card 6Gig +.It +Adaptec Hialeah 8/16 Port SAS-SATA RAID Encryption Card 6Gig +.It +Adaptec Delray 8 Port SAS-SATA HBA Card 12Gig +.It +Adaptec Delray 8 Port SAS-SATA HBA Encryption Card 12Gig +.It +Adaptec Delray 16 Port SAS-SATA HBA Card 12Gig +.It +Adaptec Delray 16 Port SAS-SATA HBA Encryption Card 12Gig +.El +.Sh SEE ALSO +.Xr cam 4 , +.Xr camcontrol 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 10.2 . diff --git a/static/freebsd/man4/polling.4 b/static/freebsd/man4/polling.4 new file mode 100644 index 00000000..2556be2d --- /dev/null +++ b/static/freebsd/man4/polling.4 @@ -0,0 +1,218 @@ +.\" Copyright (c) 2002 Luigi Rizzo +.\" 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 December 26, 2020 +.Dt POLLING 4 +.Os +.Sh NAME +.Nm polling +.Nd device polling support +.Sh SYNOPSIS +.Cd "options DEVICE_POLLING" +.Sh DESCRIPTION +Device polling +.Nm ( +for brevity) refers to a technique that +lets the operating system periodically poll devices, instead of +relying on the devices to generate interrupts when they need attention. +This might seem inefficient and counterintuitive, but when done +properly, +.Nm +gives more control to the operating system on +when and how to handle devices, with a number of advantages in terms +of system responsiveness and performance. +.Pp +In particular, +.Nm +reduces the overhead for context +switches which is incurred when servicing interrupts, and +gives more control on the scheduling of the CPU between various +tasks (user processes, software interrupts, device handling) +which ultimately reduces the chances of livelock in the system. +.Ss Principles of Operation +In the normal, interrupt-based mode, devices generate an interrupt +whenever they need attention. +This in turn causes a +context switch and the execution of an interrupt handler +which performs whatever processing is needed by the device. +The duration of the interrupt handler is potentially unbounded +unless the device driver has been programmed with real-time +concerns in mind (which is generally not the case for +.Fx +drivers). +Furthermore, under heavy traffic load, the system might be +persistently processing interrupts without being able to +complete other work, either in the kernel or in userland. +.Pp +Device polling disables interrupts by polling devices at appropriate +times, i.e., on clock interrupts and within the idle loop. +This way, the context switch overhead is removed. +Furthermore, +the operating system can control accurately how much work to spend +in handling device events, and thus prevent livelock by reserving +some amount of CPU to other tasks. +.Pp +Enabling +.Nm +also changes the way software network interrupts +are scheduled, so there is never the risk of livelock because +packets are not processed to completion. +.Ss Enabling polling +Currently only network interface drivers support the +.Nm +feature. +It is turned on and off with help of +.Xr ifconfig 8 +command. +.Pp +The historic +.Va kern.polling.enable , +which enabled polling for all interfaces, can be replaced with the following +code: +.Bd -literal +for i in `ifconfig -l` ; + do ifconfig $i polling; # use -polling to disable +done +.Ed +.Ss MIB Variables +The operation of +.Nm +is controlled by the following +.Xr sysctl 8 +MIB variables: +.Pp +.Bl -tag -width indent -compact +.It Va kern.polling.user_frac +When +.Nm +is enabled, and provided that there is some work to do, +up to this percent of the CPU cycles is reserved to userland tasks, +the remaining fraction being available for +.Nm +processing. +Default is 50. +.Pp +.It Va kern.polling.burst +Maximum number of packets grabbed from each network interface in +each timer tick. +This number is dynamically adjusted by the kernel, +according to the programmed +.Va user_frac , burst_max , +CPU speed, and system load. +.Pp +.It Va kern.polling.each_burst +The burst above is split into smaller chunks of this number of +packets, going round-robin among all interfaces registered for +.Nm . +This prevents the case that a large burst from a single interface +can saturate the IP interrupt queue +.Pq Va net.inet.ip.intr_queue_maxlen . +Default is 5. +.Pp +.It Va kern.polling.burst_max +Upper bound for +.Va kern.polling.burst . +Note that when +.Nm +is enabled, each interface can receive at most +.Pq Va HZ No * Va burst_max +packets per second unless there are spare CPU cycles available for +.Nm +in the idle loop. +This number should be tuned to match the expected load +(which can be quite high with GigE cards). +Default is 150 which is adequate for 100Mbit network and HZ=1000. +.Pp +.It Va kern.polling.idle_poll +Controls if +.Nm +is enabled in the idle loop. +There are no reasons (other than power saving or bugs in the scheduler's +handling of idle priority kernel threads) to disable this. +.Pp +.It Va kern.polling.reg_frac +Controls how often (every +.Va reg_frac No / Va HZ +seconds) the status registers of the device are checked for error +conditions and the like. +Increasing this value reduces the load on the bus, but also delays +the error detection. +Default is 20. +.Pp +.It Va kern.polling.handlers +How many active devices have registered for +.Nm . +.Pp +.It Va kern.polling.short_ticks +.It Va kern.polling.lost_polls +.It Va kern.polling.pending_polls +.It Va kern.polling.residual_burst +.It Va kern.polling.phase +.It Va kern.polling.suspect +.It Va kern.polling.stalled +Debugging variables. +.El +.Sh SUPPORTED DEVICES +Device polling requires explicit modifications to the device drivers. +As of this writing, the +.Xr bge 4 , +.Xr dc 4 , +.Xr em 4 , +.Xr fwe 4 , +.Xr fwip 4 , +.Xr fxp 4 , +.Xr igb 4 , +.Xr nfe 4 , +.Xr nge 4 , +.Xr re 4 , +.Xr rl 4 , +.Xr sis 4 , +.Xr ste 4 , +.Xr stge 4 , +.Xr vge 4 , +.Xr vr 4 , +and +.Xr xl 4 +devices are supported, with others in the works. +The modifications are rather straightforward, consisting in +the extraction of the inner part of the interrupt service routine +and writing a callback function, +.Fn *_poll , +which is invoked +to probe the device for events and process them. +(See the +conditionally compiled sections of the devices mentioned above +for more details.) +.Pp +As in the worst case the devices are only polled on clock interrupts, +in order to reduce the latency in processing packets, it is not advisable +to decrease the frequency of the clock below 1000 Hz. +.Sh HISTORY +Device polling first appeared in +.Fx 4.6 +and +.Fx 5.0 . +.Sh AUTHORS +Device polling was written by +.An Luigi Rizzo Aq Mt luigi@iet.unipi.it . diff --git a/static/freebsd/man4/ppbus.4 b/static/freebsd/man4/ppbus.4 new file mode 100644 index 00000000..a52e8800 --- /dev/null +++ b/static/freebsd/man4/ppbus.4 @@ -0,0 +1,346 @@ +.\" Copyright (c) 1998, 1999 Nicolas Souchu +.\" 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 March 1, 1998 +.Dt PPBUS 4 +.Os +.Sh NAME +.Nm ppbus +.Nd Parallel Port Bus system +.Sh SYNOPSIS +.Cd "device ppbus" +.Pp +.Cd "device lpt" +.Cd "device plip" +.Cd "device ppi" +.Cd "device pps" +.Cd "device lpbb" +.Sh DESCRIPTION +The +.Em ppbus +system provides a uniform, modular and architecture-independent +system for the implementation of drivers to control various parallel devices, +and to utilize different parallel port chipsets. +.Sh DEVICE DRIVERS +In order to write new drivers or port existing drivers, the ppbus system +provides the following facilities: +.Bl -bullet -offset indent +.It +architecture-independent macros or functions to access parallel ports +.It +mechanism to allow various devices to share the same parallel port +.It +a user interface named +.Xr ppi 4 +that allows parallel port access from outside the kernel without conflicting +with kernel-in drivers. +.El +.Ss Developing new drivers +The ppbus system has been designed to support the development of standard +and non-standard software: +.Pp +.Bl -column "Driver" -compact +.It Em Driver Ta Em Description +.It Sy ppi Ta "Parallel port interface for general I/O" +.It Sy pps Ta "Pulse per second Timing Interface" +.It Sy lpbb Ta "Philips official parallel port I2C bit-banging interface" +.El +.Ss Porting existing drivers +Another approach to the ppbus system is to port existing drivers. +Various drivers have already been ported: +.Pp +.Bl -column "Driver" -compact +.It Em Driver Ta Em Description +.It Sy lpt Ta "lpt printer driver" +.It Sy plip Ta "lp parallel network interface driver" +.El +.Pp +ppbus should let you port any other software even from other operating systems +that provide similar services. +.Sh PARALLEL PORT CHIPSETS +Parallel port chipset support is provided by +.Xr ppc 4 . +.Pp +The ppbus system provides functions and macros to allocate a new +parallel port bus, then initialize it and upper peripheral device drivers. +.Pp +ppc makes chipset detection and initialization and then calls ppbus attach +functions to initialize the ppbus system. +.Sh PARALLEL PORT MODEL +The logical parallel port model chosen for the ppbus system is the PC's +parallel port model. +Consequently, for the i386 implementation of ppbus, +most of the services provided by ppc are macros for inb() +and outb() calls. +But, for another architecture, accesses to one of our logical +registers (data, status, control...) may require more than one I/O access. +.Ss Description +The parallel port may operate in the following modes: +.Bl -bullet -offset indent +.It +compatible mode, also called Centronics mode +.It +bidirectional 8/4-bits mode, also called NIBBLE mode +.It +byte mode, also called PS/2 mode +.It +Extended Capability Port mode, ECP +.It +Enhanced Parallel Port mode, EPP +.It +mixed ECP+EPP or ECP+PS/2 modes +.El +.Ss Compatible mode +This mode defines the protocol used by most PCs to transfer data to a printer. +In this mode, data is placed on the port's data lines, the printer status is +checked for no errors and that it is not busy, and then a data Strobe is +generated by the software to clock the data to the printer. +.Pp +Many I/O controllers have implemented a mode that uses a FIFO buffer to +transfer data with the Compatibility mode protocol. +This mode is referred to as +"Fast Centronics" or "Parallel Port FIFO mode". +.Ss Bidirectional mode +The NIBBLE mode is the most common way to get reverse channel data from a +printer or peripheral. +Combined with the standard host to printer mode, it +provides a complete bidirectional channel. +.Pp +In this mode, outputs are 8-bits long. +Inputs are accomplished by reading +4 of the 8 bits of the status register. +.Ss Byte mode +In this mode, the data register is used either for outputs and inputs. +Then, +any transfer is 8-bits long. +.Ss Extended Capability Port mode +The ECP protocol was proposed as an advanced mode for communication with +printer and scanner type peripherals. +Like the EPP protocol, ECP mode provides +for a high performance bidirectional communication path between the host +adapter and the peripheral. +.Pp +ECP protocol features include: +.Bl -item -offset indent +.It +Run_Length_Encoding (RLE) data compression for host adapters +.It +FIFOs for both the forward and reverse channels +.It +DMA as well as programmed I/O for the host register interface. +.El +.Ss Enhanced Parallel Port mode +The EPP protocol was originally developed as a means to provide a high +performance parallel port link that would still be compatible with the +standard parallel port. +.Pp +The EPP mode has two types of cycle: address and data. +What makes the +difference at hardware level is the strobe of the byte placed on the data +lines. +Data are strobed with nAutofeed, addresses are strobed with +nSelectin signals. +.Pp +A particularity of the ISA implementation of the EPP protocol is that an +EPP cycle fits in an ISA cycle. +In this fashion, parallel port peripherals can +operate at close to the same performance levels as an equivalent ISA plug-in +card. +.Pp +At software level, you may implement the protocol you wish, using data and +address cycles as you want. +This is for the IEEE1284 compatible part. +Then, +peripheral vendors may implement protocol handshake with the following +status lines: PError, nFault and Select. +Try to know how these lines toggle +with your peripheral, allowing the peripheral to request more data, stop the +transfer and so on. +.Pp +At any time, the peripheral may interrupt the host with the nAck signal without +disturbing the current transfer. +.Ss Mixed modes +Some manufacturers, like SMC, have implemented chipsets that support mixed +modes. +With such chipsets, mode switching is available at any time by +accessing the extended control register. +.Sh IEEE1284-1994 Standard +.Ss Background +This standard is also named "IEEE Standard Signaling Method for a +Bidirectional Parallel Peripheral Interface for Personal Computers". +It +defines a signaling method for asynchronous, fully interlocked, bidirectional +parallel communications between hosts and printers or other peripherals. +It +also specifies a format for a peripheral identification string and a method of +returning this string to the host outside of the bidirectional data stream. +.Pp +This standard is architecture independent and only specifies dialog handshake +at signal level. +One should refer to architecture specific documentation in +order to manipulate machine dependent registers, mapped memory or other +methods to control these signals. +.Pp +The IEEE1284 protocol is fully oriented with all supported parallel port +modes. +The computer acts as master and the peripheral as slave. +.Pp +Any transfer is defined as a finite state automaton. +It allows software to +properly manage the fully interlocked scheme of the signaling method. +The compatible mode is supported "as is" without any negotiation because it +is compatible. +Any other mode must be firstly negotiated by the host to check +it is supported by the peripheral, then to enter one of the forward idle +states. +.Pp +At any time, the slave may want to send data to the host. +This is only +possible from forward idle states (nibble, byte, ecp...). +So, the +host must have previously negotiated to permit the peripheral to +request transfer. +Interrupt lines may be dedicated to the requesting signals +to prevent time consuming polling methods. +.Pp +But peripheral requests are only a hint to the master host. +If the host +accepts the transfer, it must firstly negotiate the reverse mode and then +starts the transfer. +At any time during reverse transfer, the host may +terminate the transfer or the slave may drive wires to signal that no more +data is available. +.Ss Implementation +IEEE1284 Standard support has been implemented at the top of the ppbus system +as a set of procedures that perform high level functions like negotiation, +termination, transfer in any mode without bothering you with low level +characteristics of the standard. +.Pp +IEEE1284 interacts with the ppbus system as little as possible. +That means +you still have to request the ppbus when you want to access it, the negotiate +function does not do it for you. +And of course, release it later. +.Sh ARCHITECTURE +.Ss adapter, ppbus and device layers +First, there is the +.Em adapter +layer, the lowest of the ppbus system. +It provides +chipset abstraction throw a set of low level functions that maps the logical +model to the underlying hardware. +.Pp +Secondly, there is the +.Em ppbus +layer that provides functions to: +.Bl -enum -offset indent +.It +share the parallel port bus among the daisy-chain like connected devices +.It +manage devices linked to ppbus +.It +propose an arch-independent interface to access the hardware layer. +.El +.Pp +Finally, the +.Em device +layer gathers the parallel peripheral device drivers. +.Ss Parallel modes management +We have to differentiate operating modes at various ppbus system layers. +Actually, ppbus and adapter operating modes on one hands and for each +one, current and available modes are separated. +.Pp +With this level of abstraction a particular chipset may commute from any +native mode to any other mode emulated with extended modes without +disturbing upper layers. +For example, most chipsets support NIBBLE mode as +native and emulated with ECP and/or EPP. +.Pp +This architecture should support IEEE1284-1994 modes. +.Sh FEATURES +.Ss The boot process +The boot process starts with the probe stage of the +.Xr ppc 4 +driver during ISA bus (PC architecture) initialization. +During attachment of +the ppc driver, a new ppbus structure is allocated, then probe and attachment +for this new bus node are called. +.Pp +ppbus attachment tries to detect any PnP parallel peripheral (according to +.%T "Plug and Play Parallel Port Devices" +draft from (c)1993-4 Microsoft Corporation) +then probes and attaches known device drivers. +.Pp +During probe, device drivers are supposed to request the ppbus and try to +set their operating mode. +This mode will be saved in the context structure and +returned each time the driver requests the ppbus. +.Ss Bus allocation and interrupts +ppbus allocation is mandatory not to corrupt I/O of other devices. +Another +usage of ppbus allocation is to reserve the port and receive incoming +interrupts. +.Pp +High level interrupt handlers are connected to the ppbus system thanks to the +newbus +.Fn BUS_SETUP_INTR +and +.Fn BUS_TEARDOWN_INTR +functions. +But, in order to attach a handler, drivers must +own the bus. +Consequently, a ppbus request is mandatory in order to call the above +functions (see existing drivers for more info). +Note that the interrupt handler +is automatically released when the ppbus is released. +.Ss Microsequences +.Em Microsequences +is a general purpose mechanism to allow fast low-level +manipulation of the parallel port. +Microsequences may be used to do either +standard (in IEEE1284 modes) or non-standard transfers. +The philosophy of +microsequences is to avoid the overhead of the ppbus layer and do most of +the job at adapter level. +.Pp +A microsequence is an array of opcodes and parameters. +Each opcode codes an +operation (opcodes are described in +.Xr microseq 9 ) . +Standard I/O operations are implemented at ppbus level whereas basic I/O +operations and microseq language are coded at adapter level for efficiency. +.Sh SEE ALSO +.Xr lpt 4 , +.Xr plip 4 , +.Xr ppc 4 , +.Xr ppi 4 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 3.0 . +.Sh AUTHORS +This +manual page was written by +.An Nicolas Souchu . diff --git a/static/freebsd/man4/ppc.4 b/static/freebsd/man4/ppc.4 new file mode 100644 index 00000000..360ed538 --- /dev/null +++ b/static/freebsd/man4/ppc.4 @@ -0,0 +1,134 @@ +.\" Copyright (c) 1998, 1999, Nicolas Souchu +.\" 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 March 5, 1998 +.Dt PPC 4 +.Os +.Sh NAME +.Nm ppc +.Nd Parallel Port Chipset driver +.Sh SYNOPSIS +.Cd "device ppc" +.Pp +In +.Pa /boot/device.hints : +.Cd hint.ppc.0.at="isa" +.Cd hint.ppc.0.irq="7" +.Pp +For one or more PPBUS busses: +.Cd "device ppbus" +.Sh DESCRIPTION +The +.Nm +driver provides low level support to various parallel port chipsets for the +.Xr ppbus 4 +system. +.Pp +During the probe phase, +.Nm +detects parallel port chipsets and initializes +private data according to their operating mode: COMPATIBLE, +NIBBLE, PS/2, EPP, ECP and other mixed modes. +If a mode is provided at startup through the +.Va flags +variable of the boot +interface, the operating mode of the chipset is forced according to +.Va flags +and the hardware supported modes. +.Pp +During the attach phase, +.Nm +allocates a ppbus structure, initializes it and calls the ppbus +attach function. +.Ss Supported flags +.Bl -item -offset indent +.It +bits 0-3: chipset forced mode(s) +.Bd -literal +PPB_COMPATIBLE 0x0 /* Centronics compatible mode */ +PPB_NIBBLE 0x1 /* reverse 4 bit mode */ +PPB_PS2 0x2 /* PS/2 byte mode */ +PPB_EPP 0x4 /* EPP mode, 32 bit */ +PPB_ECP 0x8 /* ECP mode */ +.Ed +.Pp +And any mixed values. +.It +bit 4: EPP protocol (0 EPP 1.9, 1 EPP 1.7) +.It +bit 5: activate IRQ (1 IRQ disabled, 0 IRQ enabled) +.It +bit 6: disable chipset specific detection +.It +bit 7: disable FIFO detection +.El +.Ss Supported chipsets +Some parallel port chipsets are explicitly supported: +detection and initialisation code has been written according to +their datasheets. +.Bl -bullet -offset indent +.It +SMC FDC37C665GT and FDC37C666GT chipsets +.It +Natsemi PC873xx-family (PC87332 and PC87306) +.It +Winbond W83877xx-family (W83877F and W83877AF) +.It +SMC-like chipsets with mixed modes (see +.Xr ppbus 4 ) +.El +.Ss Adding support to a new chipset +You may want to add support for the newest chipset your motherboard was +sold with. +For the ISA bus, just retrieve the specs of the chipset and write the +corresponding +.Fn ppc_mychipset_detect "" +function. +Then add an entry to the general purpose +.Fn ppc_detect "" +function. +.Pp +Your +.Fn ppc_mychipset_detect "" +function should ensure that if the mode field of the +.Va flags +boot variable is not null, then the operating +mode is forced to the given mode and no other mode is available and +ppb->ppb_avm field contains the available modes of the chipset. +.Sh SEE ALSO +.Xr ppbus 4 , +.Xr ppi 4 , +.Xr device.hints 5 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 3.0 . +.Sh AUTHORS +This manual page was written by +.An Nicolas Souchu . +.Sh BUGS +The chipset detection process may corrupt your chipset configuration. +You may +disable chipset specific detection by using the above flags. diff --git a/static/freebsd/man4/ppi.4 b/static/freebsd/man4/ppi.4 new file mode 100644 index 00000000..f812a87c --- /dev/null +++ b/static/freebsd/man4/ppi.4 @@ -0,0 +1,105 @@ +.\" Copyright (c) 1997 +.\" Michael Smith +.\" +.\" 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 as +.\" the first lines of this file unmodified. +.\" 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 ``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 January 2, 1998 +.Dt PPI 4 +.Os +.Sh NAME +.Nm ppi +.Nd "user-space interface to ppbus parallel 'geek' port" +.Sh SYNOPSIS +.Cd "device ppi" +.Pp +Minor numbering: unit numbers correspond directly to ppbus numbers. +.Pp +.In dev/ppbus/ppi.h +.In dev/ppbus/ppbconf.h +.Sh DESCRIPTION +The +.Nm +driver provides a convenient means for user applications to manipulate the +state of the parallel port, enabling easy low-speed I/O operations without +the security problems inherent with the use of the +.Pa /dev/io +interface. +.Sh PROGRAMMING INTERFACE +All I/O on the +.Nm +interface is performed using +.Fn ioctl +calls. +Each command takes a single +.Ft uint8_t +argument, transferring one byte of data. +The following commands are available: +.Bl -tag -width indent +.It Dv PPIGDATA , PPISDATA +Get and set the contents of the data register. +.It Dv PPIGSTATUS , PPISSTATUS +Get and set the contents of the status register. +.It Dv PPIGCTRL , PPISCTRL +Get and set the contents of the control register. +The following defines correspond to bits in this register. +Setting a bit in the control register drives the corresponding output low. +.Bl -tag -width indent -compact +.It Dv STROBE +.It Dv AUTOFEED +.It Dv nINIT +.It Dv SELECTIN +.It Dv PCD +.El +.It Dv PPIGEPP , PPISEPP +Get and set the contents of the EPP control register. +.It Dv PPIGECR , PPISECR +Get and set the contents of the ECP control register. +.It Dv PPIGFIFO , PPISFIFO +Read and write the ECP FIFO (8-bit operations only). +.El +.Sh EXAMPLES +To present the value 0x5a to the data port, drive STROBE low and then high +again, the following code fragment can be used: +.Bd -literal -compact + + int fd; + uint8_t val; + + val = 0x5a; + ioctl(fd, PPISDATA, &val); + ioctl(fd, PPIGCTRL, &val); + val |= STROBE; + ioctl(fd, PPISCTRL, &val); + val &= ~STROBE; + ioctl(fd, PPISCTRL, &val); + +.Ed +.Sh BUGS +The inverse sense of signals is confusing. +.Pp +The +.Fn ioctl +interface is slow, and there is no way (yet) to chain multiple operations together. +.Pp +The headers required for user applications are not installed as part of the +standard system. diff --git a/static/freebsd/man4/procdesc.4 b/static/freebsd/man4/procdesc.4 new file mode 100644 index 00000000..f1f3757a --- /dev/null +++ b/static/freebsd/man4/procdesc.4 @@ -0,0 +1,83 @@ +.\" +.\" Copyright (c) 2013 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" This software was developed by SRI International and the University of +.\" Cambridge Computer Laboratory under DARPA/AFRL contract (FA8750-10-C-0237) +.\" ("CTSRD"), as part of the DARPA CRASH research programme. +.\" +.\" 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 May 15, 2020 +.Dt PROCDESC 4 +.Os +.Sh NAME +.Nm procdesc +.Nd process descriptor facility +.Sh DESCRIPTION +.Nm +is a file-descriptor-oriented interface to process signalling and control, +which supplements historic +.Ux +.Xr fork 2 +and +.Xr kill 2 , +primitives with +new system calls such as +.Xr pdfork 2 +and +.Xr pdkill 2 , +.Nm +is designed for use with +.Xr capsicum 4 , +replacing process identifiers with capability-oriented references. +However, it can also be used independently of +.Xr capsicum 4 , +displacing PIDs, which may otherwise suffer from race conditions. +Given a process descriptor, it is possible to query its conventional PID using +.Xr pdgetpid 2 . +.Sh SEE ALSO +.Xr fork 2 , +.Xr kill 2 , +.Xr kqueue 2 , +.Xr pdfork 2 , +.Xr pdgetpid 2 , +.Xr pdkill 2 , +.Xr wait4 2 , +.Xr capsicum 4 +.Sh HISTORY +.Nm +first appeared in +.Fx 9.0 , +and was developed at the University of Cambridge. +.Sh AUTHORS +.Nm +was developed by +.An -nosplit +.An Robert Watson Aq Mt rwatson@FreeBSD.org +and +.An Jonathan Anderson Aq Mt jonathan@FreeBSD.org +at the University of Cambridge, and +.An Ben Laurie Aq Mt benl@FreeBSD.org +and +.An Kris Kennaway Aq Mt kris@FreeBSD.org +at Google, Inc. diff --git a/static/freebsd/man4/procfs.4 b/static/freebsd/man4/procfs.4 new file mode 100644 index 00000000..5a588004 --- /dev/null +++ b/static/freebsd/man4/procfs.4 @@ -0,0 +1,308 @@ +.\" Written by Garrett Wollman +.\" This file is in the public domain. +.\" +.Dd June 23, 2024 +.Dt PROCFS 4 +.Os +.Sh NAME +.Nm procfs +.Nd process file system +.Sh SYNOPSIS +.Bd -literal +proc /proc procfs rw 0 0 +.Ed +.Sh DESCRIPTION +.Bf -symbolic +This functionality is deprecated. +Users are advised to use +.Xr libprocstat 3 +and +.Xr kvm 3 +instead. +.Ef +.Pp +The process file system, or +.Nm , +implements a view of the system process table inside the file system. +It is normally mounted on +.Pa /proc . +.Pp +The +.Nm +provides a two-level view of process space, unlike the previous +.Fx 1.1 +.Nm +implementation. +At the highest level, processes themselves are named, according to +their process ids in decimal, with no leading zeros. +There is also a +special node called +.Pa curproc +which always refers to the process making the lookup request. +.Pp +Each node is a directory which contains the following entries: +.Bl -tag -width status +.It Pa dbregs +The debug registers as defined by +.Dv "struct dbregs" +in +.In machine/reg.h . +.Pa dbregs +is currently only implemented on the i386 architecture. +.It Pa etype +The type of the executable referenced by the +.Pa file +entry. +.It Pa file +A symbolic link to the file from which the process text was read. +This can be used to gain access to the process' symbol table, +or to start another copy of the process. +If the file cannot be found, the link target is +.Ql unknown . +.It Pa fpregs +The floating point registers as defined by +.Dv "struct fpregs" +in +.In machine/reg.h . +.Pa fpregs +is only implemented on machines which have distinct general +purpose and floating point register sets. +.It Pa map +A collection of lines describing the memory regions of the process, +where each line contains the following fields: +.Bl -tag -compact -width private-resident +.It start-address +The starting address for the region (inclusive). +.It end-address +The ending address for the region (exclusive). +.It resident +The number of resident pages. +.It private-resident +The number of resident pages that were private to the process. +.It obj +The virtual address of the +.Vt struct vm_object +kernel data structure describing the memory region. +.It access +A three character string comprising the characters +.Sq r , +.Sq w +and +.Sq x , +denoting read, write, and execute permissions respectively. +The lack of a permission is represented by +.Sq - . +.It ref_count +The number of references to the region. +.It shadow_count +The number of VM objects that this region is a shadow for. +.It flags +The flags for the object, see the flags named +.Sy OBJ_* +in +.In vm/vm_object.h . +.It copy-on-write +Whether the region is copy-on-write. +One of: +.Bl -tag -compact -width NCOW +.It COW +A copy-on-write region. +.It NCOW +A non-copy-on-write region. +.El +.It needs-copy +Whether the region needs a copy. +One of: +.Bl -tag -compact -width NNC +.It NC +The region needs a copy. +.It NNC +The region does not need a copy. +.El +.It type +The type of the region. +One of: +.Bl -tag -compact -width unknown +.It dead +A region associated with a dead VM object. +.It device +A region backed by device memory. +.It none +A region not backed by anything. +.It phys +A region backed by physical memory. +.It swap +A region backed by swap. +.It unknown +A region of unknown type. +.It vnode +A region backed by a file. +.El +.It fullpath +The path to the file backing the memory region, or +.Sq - +if there is no such file. +.It cred +One of: +.Bl -tag -compact -width NCH +.It CH +The region is being charged to the user specified in the +.Sq charged-uid +field. +.It NCH +The region is not being charged to any user. +.El +.It charged-uid +The UID of the user being charged, or -1 if no user is being charged. +.El +.It Pa mem +The complete virtual memory image of the process. +Only those address which exist in the process can be accessed. +Reads and writes to this file modify the process. +Writes to the text segment remain private to the process. +.It Pa note +Used for sending signals to the process. +Not implemented. +.It Pa notepg +Used for sending signal to the process group. +Not implemented. +.It Pa osrel +Allows read and write of the kernel osrel value assigned to the process. +It affects the compatibility shims that are turned on and off +depending on the value. +Initial process value is read from the ABI note tag in the executed ELF image, +and is zero if the tag not supported by binary format or was not found. +.It Pa regs +Allows read and write access to the process' register set. +This file contains a binary data structure +.Dv "struct regs" +defined in +.In machine/reg.h . +.Pa regs +can only be written when the process is stopped. +.It Pa rlimit +This is a read-only file containing the process current and maximum +limits. +Each line is of the format +.Ar rlimit current max , +with -1 +indicating infinity. +.It Pa status +The process status. +This file is read-only and returns a single line containing +multiple space-separated fields as follows: +.Pp +.Bl -bullet -compact +.It +command name +.It +process id +.It +parent process id +.It +process group id +.It +session id +.It +device name +of the controlling terminal, or +a minus sign +.Pq Dq - +if there is no controlling terminal. +.It +a list of process flags: +.Dv ctty +if there is a controlling terminal, +.Dv sldr +if the process is a session leader, +.Dv noflags +if neither of the other two flags are set. +.It +the process start time in seconds and microseconds, +comma separated. +.It +the user time in seconds and microseconds, +comma separated. +.It +the system time in seconds and microseconds, +comma separated. +.It +the wait channel message +.It +the process effective UID +.It +the process real UID +.It +group list, starting with the effective GID, comma-separated +.It +the hostname of the jail in which the process runs, or +.Ql - +to indicate that the process is not running within a jail. +.El +.El +.Pp +Each node is owned by the process's user, and belongs to that user's +primary group. +.Sh FILES +.Bl -tag -width /proc/curproc/XXXXXXX -compact +.It Pa /proc +normal mount point for the +.Nm . +.It Pa /proc/pid +directory containing process information for process +.Pa pid . +.It Pa /proc/curproc +directory containing process information for the current process +.It Pa /proc/self +directory containing process information for the current process +.It Pa /proc/curproc/cmdline +the process executable name +.It Pa /proc/curproc/etype +executable type +.It Pa /proc/curproc/exe +executable image +.It Pa /proc/curproc/file +executable image +.It Pa /proc/curproc/fpregs +the process floating point register set +.It Pa /proc/curproc/map +virtual memory map of the process +.It Pa /proc/curproc/mem +the complete virtual address space of the process +.It Pa /proc/curproc/note +used for signaling the process +.It Pa /proc/curproc/notepg +used for signaling the process group +.It Pa /proc/curproc/osrel +the process osrel value +.It Pa /proc/curproc/regs +the process register set +.It Pa /proc/curproc/rlimit +the process current and maximum rlimit +.It Pa /proc/curproc/status +the process' current status +.El +.Sh EXAMPLES +To mount a +.Nm +file system on +.Pa /proc : +.Pp +.Dl "mount -t procfs proc /proc" +.Sh SEE ALSO +.Xr procstat 1 , +.Xr mount 2 , +.Xr sigaction 2 , +.Xr unmount 2 , +.Xr kvm 3 , +.Xr libprocstat 3 , +.Xr pseudofs 9 +.Sh AUTHORS +.An -nosplit +This manual page written by +.An Garrett Wollman , +based on the description +provided by +.An Jan-Simon Pendry , +and revamped later by +.An Mike Pritchard . diff --git a/static/freebsd/man4/proto.4 b/static/freebsd/man4/proto.4 new file mode 100644 index 00000000..889c07cd --- /dev/null +++ b/static/freebsd/man4/proto.4 @@ -0,0 +1,473 @@ +.\" +.\" Copyright (c) 2014, 2015 Marcel Moolenaar +.\" 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 ``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 August 7, 2015 +.Dt PROTO 4 +.Os +.\" +.Sh NAME +.Nm proto +.Nd Generic prototyping and diagnostics driver +.\" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device proto" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +proto_load="YES" +.Ed +.Pp +To have the driver attach to a device instead of its regular driver, +mention it in the list of devices assigned to the following loader variable: +.Bd -ragged -offset indent +hw.proto.attach="desc[,desc]" +.Ed +.\" +.Sh DESCRIPTION +The +.Nm +device driver attaches to PCI or ISA devices when no other device drivers +are present for those devices and it creates device special files for all +resources associated with the device. +The driver itself has no knowledge of the device it attaches to. +Programs can open these device special files and perform register-level +reads and writes. +As such, the +.Nm +device driver is nothing but a conduit or gateway between user space +programs and the hardware device. +.Pp +Examples for why this is useful include hardware diagnostics and prototyping. +In both these use cases, it is far more convenient to develop and run the +logic in user space. +Especially hardware diagnostics requires a somewhat user-friendly interface +and adequate reporting. +Neither is done easily as kernel code. +.Ss I/O port resources +Device special files created for I/O port resources allow +.Xr lseek 2 , +.Xr read 2 , +.Xr write 2 +and +.Xr ioctl 2 +operations to be performed on them. +The +.Xr read 2 +and +.Xr write 2 +system calls are used to perform input and output (resp.) on the port. +The amount of data that can be read or written at any single time is either +1, 2 or 4 bytes. +While the +.Nm +driver does not prevent reading or writing 8 bytes at a time for some +architectures, it should not be assumed that such actually produces +correct results. +The +.Xr lseek 2 +system call is used to select the port number, relative to the I/O port +region being represented by the device special file. +If, for example, the device special file corresponds to an I/O port region +from 0x3f8 to 0x3ff inclusive, then an offset of 4 given to lseek with a +whence value of SEEK_SET will target port 0x3fc on the next read or write +operation. +The +.Xr ioctl 2 +system call can be used for the +.Dv PROTO_IOC_REGION +request. +This ioctl request returns the extend of the resource covered by this +device special file. +The extend is returned in the following structure: +.Bd -literal +struct proto_ioc_region { + unsigned long address; + unsigned long size; +}; +.Ed +.Ss Memory mapped I/O resources +The device special files created for memory mapped I/O resources behave +in the same way as those created for I/O port resources. +Additionally, device special files for memory mapped I/O resources allow +the memory to be mapped into the process' address space using +.Xr mmap 2 . +Reads and writes to the memory address returned by +.Xr mmap 2 +go directly to the hardware. +As such the use of +.Xr read 2 +and +.Xr write 2 +can be avoided, reducing the access overhead significantly. +Alignment and access width constraints put forth by the underlying device +apply. +Also, make sure the compiler does not optimize memory accesses away or has +them coalesced into bigger accesses. +.Ss DMA pseudo resource +A device special file named +.Pa busdma +is created for the purpose of doing DMA. +It only supports +.Xr ioctl 2 +and only for the +.Dv PROTO_IOC_BUSDMA +request. +This device special file does not support +.Xr read 2 +nor +.Xr write 2 . +The +.Dv PROTO_IOC_BUSDMA +request has an argument that is both in and out and is defined as +follows: +.Bd -literal +struct proto_ioc_busdma { + unsigned int request; + unsigned long key; + union { + struct { + unsigned long align; + unsigned long bndry; + unsigned long maxaddr; + unsigned long maxsz; + unsigned long maxsegsz; + unsigned int nsegs; + unsigned int datarate; + unsigned int flags; + } tag; + struct { + unsigned long tag; + unsigned int flags; + unsigned long virt_addr; + unsigned long virt_size; + unsigned int phys_nsegs; + unsigned long phys_addr; + unsigned long bus_addr; + unsigned int bus_nsegs; + } md; + struct { + unsigned int op; + unsigned long base; + unsigned long size; + } sync; + } u; + unsigned long result; +}; +.Ed +The +.Va request +field is used to specify which DMA operation is to be performed. +The +.Va key +field is used to specify which object the operation applies to. +An object is either a tag or a memory descriptor (md). +The following DMA operations are defined: +.Bl -tag -width XXXX +.It PROTO_IOC_BUSDMA_TAG_CREATE +Create a root tag. +The +.Va result +field is set on output with the key of the DMA tag. +The tag is created with the constraints given by the +.Va tag +sub-structure. +These constraints correspond roughly to those that can be given to the +.Xr bus_dma_tag_create 9 +function. +.It PROTO_IOC_BUSDMA_TAG_DERIVE +Create a derived tag. +The +.Va key +field is used to identify the parent tag from which to derive the new tag. +The key of the derived tag is returned in the +.Va result +field. +The derived tag combines the constraints of the parent tag with those +given by the +.Va tag +sub-structure. +The combined constraints are written back to the +.Va tag +sub-structure on return. +.It PROTO_IOC_BUSDMA_TAG_DESTROY +Destroy a root or derived tag previously created. +The +.Va key +field specifies the tag to destroy. +A tag can only be destroyed when not referenced anymore. +This means that derived tags that have this tag as a parent and memory +descriptors created from this tag must be destroyed first. +.It PROTO_IOC_BUSDMA_MEM_ALLOC +Allocate memory that satisfies the constraints put forth by the tag +given in the +.Va tag +field of the +.Va md +sub-structure. +The key of the memory descriptor for this memory is returned in the +.Va result +field. +The +.Va md +sub-structure is filled on return with details of the allocation. +The kernel virtual address and the size of the allocated memory are returned +in the +.Va virt_addr +and +.Va virt_size +fields. +The number of contiguous physical memory segments and the address of the first +segment are returned in the +.Va phys_nsegs +and +.Va phys_addr +fields. +Allocated memory is automatically loaded and thus mapped into bus space. +The number of bus segments and the address of the first segment are returned +in the +.Va bus_nsegs +and +.Va bus_addr +fields. +The behaviour of this operation banks heavily on how +.Xr bus_dmamem_alloc 9 +is implemented, which means that memory is currently always allocated as a +single contiguous region of physical memory. +In practice this also tends to give a single contiguous region in bus space. +This may change over time. +.It PROTO_IOC_BUSDMA_MEM_FREE +Free previously allocated memory and destroy the memory descriptor. +The +.Nm +driver is not in a position to track whether the memory has been mapped in +the process' address space, so the application is responsible for unmapping +the memory before it is freed. +The +.Nm +driver also cannot protect against the hardware writing to or reading from +the memory, even after it has been freed. +When the memory is reused for other purposes it can be corrupted or cause +the hardware to behave in unpredictable ways when DMA has not stopped +completely before freeing. +.It PROTO_IOC_BUSDMA_MD_CREATE +Create an empty memory descriptor with the tag specified in the +.Va tag +field of the +.Va md +sub-structure. +The key of the memory descriptor is returned in the +.Va result +field. +.It PROTO_IOC_BUSDMA_MD_DESTROY +Destroy the previously created memory descriptor specified by the +.Va key +field. +When the memory descriptor is still loaded, it is unloaded first. +.It PROTO_IOC_BUSDMA_MD_LOAD +Load a contiguous region of memory in the memory descriptor specified by the +.Va key +field. +The size and address in the process' virtual address space are specified +by the +.Va virt_size +and +.Va virt_addr +fields. +On return, the +.Va md +sub-structure contains the result of the operation. +The number of physical segments and the address of the first segment is +returned in the +.Va phys_nsegs +and +.Va phys_addr +fields. +The number of bus space segments and the address of the first segment in +bus space is returned in the +.Va bus_nsegs +and +.Va bus_addr +fields. +.It PROTO_IOC_BUSDMA_MD_UNLOAD +Unload the memory descriptor specified by the +.Va key +field. +.It PROTO_IOC_BUSDMA_SYNC +Guarantee that all hardware components have a coherent view of the memory +tracked by the memory descriptor, specified by the +.Va key +field. +A sub-section of the memory can be targeted by specifying the relative +offset and size of the memory to make coherent. +The offset and size are given by the +.Va base +and +.Va size +fields of the +.Va sync +sub-structure. +The +.Va op +field holds the sync operation to be performed. +This is similar to the +.Xr bus_dmamap_sync 9 +function. +.El +.Ss PCI configuration space +Access to PCI configuration space is possible through the +.Pa pcicfg +device special file. +The device special file supports +.Xr lseek 2 , +.Xr read 2 +and +.Xr write 2 . +Usage is the asme as for I/O port resources. +.Sh FILES +All device special files corresponding to a PCI device are located under +.Pa /dev/proto/pci::: +with +.Pa pci::: +representing the location of the PCI device in the PCI hierarchy. +A PCI location includes: +.Pp +.Bl -tag -width XXXXXX -compact -offset indent +.It +The PCI domain number +.It +The PCI bus number +.It +The PCI slot or device number +.It +The PCI function number +.El +.Pp +Every PCI device has a device special file called +.Pa pcicfg . +This device special file gives access to the PCI configuration space. +A device special file called +.Pa busdma +is also created. +This device special file provides the interfaces needed for doing DMA. +For each valid base address register (BAR), a device special file is created +that contains the BAR offset and the resource type. +A resource type can be either +.Pa io +or +.Pa mem +representing I/O port or memory mapped I/O space (resp.) +.Pp +ISA devices do not have a location. +Instead, they are identified by the +first I/O port address or first memory mapped I/O address. +Consequently, all device special files corresponding to an ISA device are +located under +.Pa /dev/proto/isa: +with +.Pa addr +the address in hexadecimal notation. +For each I/O port or memory mapped I/O address, a device special file is +created that contains the resource identification used by the kernel and +the resource type. +The resource type can be either +.Pa io +or +.Pa mem +representing I/O port or memory mapped I/O space (resp.) +When the device has a DMA channel assigned to it, a device special file +with the name +.Pa busdma +is created as well. +This device special file provides the interfaces needed for doing DMA. +.Pp +If the ISA device is not a Plug-and-Play device nor present in the ACPI +device tree, it must have the appropriate hints so that the kernel can +reserve the resources for it. +.\" +.Sh EXAMPLES +A single function PCI device in domain 0, on bus 1, in slot 2 and having a +single memory mapped I/O region will have the following device special files: +.Pp +.Bl -tag -width XXXXXX -compact -offset indent +.It Pa /dev/proto/pci0:1:2:0/10.mem +.It Pa /dev/proto/pci0:1:2:0/pcicfg +.El +.Pp +A legacy floppy controller will have the following device files: +.Pp +.Bl -tag -width XXXXXX -compact -offset indent +.It Pa /dev/proto/isa:0x3f0/00.io +.It Pa /dev/proto/isa:0x3f0/01.io +.It Pa /dev/proto/isa:0x3f0/busdma +.El +.\" +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr lseek 2 , +.Xr mmap 2 , +.Xr read 2 , +.Xr write 2 , +.Xr bus_dma_tag_create 9 , +.Xr bus_dmamap_sync 9 , +.Xr bus_dmamem_alloc 9 +.\" +.Sh AUTHORS +The +.Nm +device driver and this manual page were written by +.An Marcel Moolenaar Aq Mt marcel@xcllnt.net . +.Sh SECURITY CONSIDERATIONS +Because programs have direct access to the hardware, the +.Nm +driver is inherently insecure. +It is not advisable to use this driver on a production machine. +.\" +.Sh MISSING FUNCTIONALITY +The +.Nm +driver does not fully support memory descriptors that need multiple +physical memory segments or multiple bus space segments. +At the very least, an operation is needed on the DMA pseudo resource +for the application to obtain all segments. +.Pp +The +.Nm +driver does not yet support interrupts. +Since interrupts cannot be handled by the driver itself, they must be +converted into signals and delivered to the program that has registered +for interrupts. +A satisfactory mechanism for keeping the interrupt masked during the +signal handling is still being worked out. +.Pp +DMA support for devices other than busmaster devices is not present yet. +The details of how a program is to interact with the DMA controller still +need to be fleshed out. diff --git a/static/freebsd/man4/ps4dshock.4 b/static/freebsd/man4/ps4dshock.4 new file mode 100644 index 00000000..f48e2c07 --- /dev/null +++ b/static/freebsd/man4/ps4dshock.4 @@ -0,0 +1,110 @@ +.\" Copyright (c) 2020 Vladimir Kondratyev +.\" +.\" 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 November 30, 2025 +.Dt PS4DSHOCK 4 +.Os +.Sh NAME +.Nm ps4dshock +.Nd Sony PlayStation 4 Dualshock 4 gamepad driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ps4dshock" +.Cd "device hid" +.Cd "device hidbus" +.Cd "device hidmap" +.Cd "device evdev" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ps4dshock_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for Sony PlayStation 4 Dualshock 4 gamepad driver. +.Pp +The +.Pa /dev/input/event* +device presents the game controller as a +.Ar evdev +type device. +It is accessible to members of the +.Em games +group. +.Sh SYSCTL VARIABLES +Next parameters are available as +.Xr sysctl 8 +variables. +Debug parameter is available as +.Xr loader 8 +tunable as well. +.Bl -tag -width indent +.It Va dev.p4dshock.*.led_state +LED state: 0 - off, 1 - on, 2 - blinking. +.It Va dev.p4dshock.*.led_color_r +LED color. +Red component. +.It Va dev.p4dshock.*.led_color_g +LED color. +Green component. +.It Va dev.p4dshock.*.led_color_b +LED color. +Blue component. +.It Va dev.p4dshock.*.led_delay_on +LED blink. +On delay, msecs. +.It Va dev.p4dshock.*.led_delay_off +LED blink. +Off delay, msecs. +.It Va hw.hid.ps4dshock.debug +Debug output level, where 0 is debugging disabled and larger values increase +debug message verbosity. +Default is 0. +.El +.Sh FILES +.Bl -tag -width /dev/input/event* -compact +.It Pa /dev/input/event* +input event device node. +.El +.Sh BUGS +The +.Nm +does not support force-feedback events. +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org . diff --git a/static/freebsd/man4/psm.4 b/static/freebsd/man4/psm.4 new file mode 100644 index 00000000..50bcf534 --- /dev/null +++ b/static/freebsd/man4/psm.4 @@ -0,0 +1,873 @@ +.\" +.\" Copyright (c) 1997 +.\" Kazutaka YOKOTA +.\" 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 as +.\" the first lines of this file unmodified. +.\" 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 ``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 June 2, 2020 +.Dt PSM 4 +.Os +.Sh NAME +.Nm psm +.Nd PS/2 mouse style pointing device driver +.Sh SYNOPSIS +.Cd "options KBD_RESETDELAY=N" +.Cd "options KBD_MAXWAIT=N" +.Cd "options PSM_DEBUG=N" +.Cd "options KBDIO_DEBUG=N" +.Cd "device psm" +.Pp +In +.Pa /boot/device.hints : +.Cd hint.psm.0.at="atkbdc" +.Cd hint.psm.0.irq="12" +.Sh DESCRIPTION +The +.Nm +driver provides support for the PS/2 mouse style pointing device. +Currently there can be only one +.Nm +device node in the system. +As the PS/2 mouse port is located +at the auxiliary port of the keyboard controller, +the keyboard controller driver, +.Nm atkbdc , +must also be configured in the kernel. +Note that there is currently no provision of changing the +.Em irq +number. +.Pp +Basic PS/2 style pointing device has two or three buttons. +Some devices may have a roller or a wheel and/or additional buttons. +.Ss Device Resolution +The PS/2 style pointing device usually has several grades of resolution, +that is, sensitivity of movement. +They are typically 25, 50, 100 and 200 +pulse per inch. +Some devices may have finer resolution. +The current resolution can be changed at runtime. +The +.Nm +driver allows the user to initially set the resolution +via the driver flag +(see +.Sx "DRIVER CONFIGURATION" ) +or change it later via the +.Xr ioctl 2 +command +.Dv MOUSE_SETMODE +(see +.Sx IOCTLS ) . +.Ss Report Rate +Frequency, or report rate, at which the device sends movement +and button state reports to the host system is also configurable. +The PS/2 style pointing device typically supports 10, 20, 40, 60, 80, 100 +and 200 reports per second. +60 or 100 appears to be the default value for many devices. +Note that when there is no movement and no button has changed its state, +the device will not send anything to the host system. +The report rate can be changed via an ioctl call. +.Ss Operation Levels +The +.Nm +driver has three levels of operation. +The current operation level can be set via an ioctl call. +.Pp +At the level zero the basic support is provided; the device driver will report +horizontal and vertical movement of the attached device +and state of up to three buttons. +The movement and status are encoded in a series of fixed-length data packets +(see +.Sx "Data Packet Format" ) . +This is the default level of operation and the driver is initially +at this level when opened by the user program. +.Pp +The operation level one, the `extended' level, supports a roller (or wheel), +if any, and up to 11 buttons. +The movement of the roller is reported as movement along the Z axis. +8 byte data packets are sent to the user program at this level. +.Pp +At the operation level two, data from the pointing device is passed to the +user program as is. +Conversely, command from the user program is passed +to the pointing device as is and the user program is responsible for +status validation and error recovery. +Modern PS/2 type pointing devices often use proprietary data format. +Therefore, the user program is expected to have +intimate knowledge about the format from a particular device when operating +the driver at this level. +This level is called `native' level. +.Ss Data Packet Format +Data packets read from the +.Nm +driver are formatted differently at each operation level. +.Pp +A data packet from the PS/2 mouse style pointing device +is three bytes long at the operation level zero: +.Pp +.Bl -tag -width Byte_1 -compact +.It Byte 1 +.Bl -tag -width bit_7 -compact +.It bit 7 +One indicates overflow in the vertical movement count. +.It bit 6 +One indicates overflow in the horizontal movement count. +.It bit 5 +Set if the vertical movement count is negative. +.It bit 4 +Set if the horizontal movement count is negative. +.It bit 3 +Always one. +.\" The ALPS GlidePoint clears this bit when the user `taps' the surface of +.\" the pad, otherwise the bit is set. +.\" Most, if not all, other devices always set this bit. +.It bit 2 +Middle button status; set if pressed. +For devices without the middle +button, this bit is always zero. +.It bit 1 +Right button status; set if pressed. +.It bit 0 +Left button status; set if pressed. +.El +.It Byte 2 +Horizontal movement count in two's complement; +-256 through 255. +Note that the sign bit is in the first byte. +.It Byte 3 +Vertical movement count in two's complement; +-256 through 255. +Note that the sign bit is in the first byte. +.El +.Pp +At the level one, a data packet is encoded +in the standard format +.Dv MOUSE_PROTO_SYSMOUSE +as defined in +.Xr mouse 4 . +.Pp +At the level two, native level, there is no standard on the size and format +of the data packet. +.Ss Acceleration +The +.Nm +driver can somewhat `accelerate' the movement of the pointing device. +The faster you move the device, the further the pointer +travels on the screen. +The driver has an internal variable which governs the effect of +the acceleration. +Its value can be modified via the driver flag +or via an ioctl call. +.Sh DRIVER CONFIGURATION +.Ss Kernel Configuration Options +There are following kernel configuration options to control the +.Nm +driver. +They may be set in the kernel configuration file +(see +.Xr config 8 ) . +.Bl -tag -width MOUSE +.It Em KBD_RESETDELAY=X , KBD_MAXWAIT=Y +The +.Nm +driver will attempt to reset the pointing device during the boot process. +It sometimes takes a long while before the device will respond after +reset. +These options control how long the driver should wait before +it eventually gives up waiting. +The driver will wait +.Fa X +* +.Fa Y +msecs at most. +If the driver seems unable to detect your pointing +device, you may want to increase these values. +The default values are +200 msec for +.Fa X +and 5 +for +.Fa Y . +.It Em PSM_DEBUG=N , KBDIO_DEBUG=N +Sets the debug level to +.Fa N . +The default debug level is zero. +See +.Sx DIAGNOSTICS +for debug logging. +.El +.Ss Driver Flags +The +.Nm +driver accepts the following driver flags. +Set them in +.Pa /boot/device.hints +(see +.Sx EXAMPLES +below). +.Bl -tag -width MOUSE +.It bit 0..3 RESOLUTION +This flag specifies the resolution of the pointing device. +It must be zero through four. +The greater the value +is, the finer resolution the device will select. +Actual resolution selected by this field varies according to the model +of the device. +Typical resolutions are: +.Pp +.Bl -tag -width 0_(medium_high)__ -compact +.It Em 1 (low) +25 pulse per inch (ppi) +.It Em 2 (medium low) +50 ppi +.It Em 3 (medium high) +100 ppi +.It Em 4 (high) +200 ppi +.El +.Pp +Leaving this flag zero will selects the default resolution for the +device (whatever it is). +.It bit 4..7 ACCELERATION +This flag controls the amount of acceleration effect. +The smaller the value of this flag is, more sensitive the movement becomes. +The minimum value allowed, thus the value for the most sensitive setting, +is one. +Setting this flag to zero will completely disables the +acceleration effect. +.It bit 8 NOCHECKSYNC +The +.Nm +driver tries to detect the first byte of the data packet by checking +the bit pattern of that byte. +Although this method should work with most +PS/2 pointing devices, it may interfere with some devices which are not +so compatible with known devices. +If you think your pointing device is not functioning as expected, +and the kernel frequently prints the following message to the console, +.Bd -literal -offset indent +psmintr: out of sync (xxxx != yyyy). +.Ed +.Pp +set this flag to disable synchronization check and see if it helps. +.It bit 9 NOIDPROBE +The +.Nm +driver will not try to identify the model of the pointing device and +will not carry out model-specific initialization. +The device should always act like a standard PS/2 mouse without such +initialization. +Extra features, such as wheels and additional buttons, will not be +recognized by the +.Nm +driver. +.It bit 10 NORESET +When this flag is set, the +.Nm +driver will not reset the pointing device when initializing the device. +If the +.Fx +kernel +is started after another OS has run, the pointing device will inherit +settings from the previous OS. +However, because there is no way for the +.Nm +driver to know the settings, the device and the driver may not +work correctly. +The flag should never be necessary under normal circumstances. +.It bit 11 FORCETAP +Some pad devices report as if the fourth button is pressed +when the user `taps' the surface of the device (see +.Sx CAVEATS ) . +This flag will make the +.Nm +driver assume that the device behaves this way. +Without the flag, the driver will assume this behavior +for ALPS GlidePoint models only. +.It bit 12 IGNOREPORTERROR +This flag makes +.Nm +driver ignore certain error conditions when probing the PS/2 mouse port. +It should never be necessary under normal circumstances. +.It bit 13 HOOKRESUME +The built-in PS/2 pointing device of some laptop computers is somehow +not operable immediately after the system `resumes' from +the power saving mode, +though it will eventually become available. +There are reports that +stimulating the device by performing I/O will help +waking up the device quickly. +This flag will enable a piece of code in the +.Nm +driver to hook +the `resume' event and exercise some harmless I/O operations on the +device. +.It bit 14 INITAFTERSUSPEND +This flag adds more drastic action for the above problem. +It will cause the +.Nm +driver to reset and re-initialize the pointing device +after the `resume' event. +.El +.Sh LOADER TUNABLES +Extended support for Synaptics touchpads can be enabled by setting +.Va hw.psm.synaptics_support +to +.Em 1 +at boot-time. +This will enable +.Nm +to handle packets from guest devices (sticks) and extra buttons. +Similarly, extended support for IBM/Lenovo TrackPoint and Elantech touchpads +can be enabled by setting +.Va hw.psm.trackpoint_support +or +.Va hw.psm.elantech_support , +respectively, to +.Em 1 +at boot-time. +.Pp +Tap and drag gestures can be disabled by setting +.Va hw.psm.tap_enabled +to +.Em 0 +at boot-time. +Currently, this is supported on Synaptics touchpads regardless of Extended +support state and on Elantech touchpads with Extended support enabled. +The behaviour may be changed after boot by setting +the sysctl with the same name and by restarting +.Xr moused 8 +using +.Pa /etc/rc.d/moused . +.Pp +Active multiplexing support can be disabled by setting +.Va hw.psm.mux_disabled +to +.Em 1 +at boot-time. +This will prevent +.Nm +from enabling active multiplexing mode needed for some Synaptics touchpads. +.Sh IOCTLS +There are a few +.Xr ioctl 2 +commands for mouse drivers. +These commands and related structures and constants are defined in +.In sys/mouse.h . +General description of the commands is given in +.Xr mouse 4 . +This section explains the features specific to the +.Nm +driver. +.Pp +.Bl -tag -width MOUSE -compact +.It Dv MOUSE_GETLEVEL Ar int *level +.It Dv MOUSE_SETLEVEL Ar int *level +These commands manipulate the operation level of the +.Nm +driver. +.Pp +.It Dv MOUSE_GETHWINFO Ar mousehw_t *hw +Returns the hardware information of the attached device in the following +structure. +.Bd -literal +typedef struct mousehw { + int buttons; /* number of buttons */ + int iftype; /* I/F type */ + int type; /* mouse/track ball/pad... */ + int model; /* I/F dependent model ID */ + int hwid; /* I/F dependent hardware ID */ +} mousehw_t; +.Ed +.Pp +The +.Dv buttons +field holds the number of buttons on the device. +The +.Nm +driver currently can detect the 3 button mouse from Logitech and report +accordingly. +The 3 button mouse from the other manufacturer may or may not be +reported correctly. +However, it will not affect the operation of +the driver. +.Pp +The +.Dv iftype +is always +.Dv MOUSE_IF_PS2 . +.Pp +The +.Dv type +tells the device type: +.Dv MOUSE_MOUSE , +.Dv MOUSE_TRACKBALL , +.Dv MOUSE_STICK , +.Dv MOUSE_PAD , +or +.Dv MOUSE_UNKNOWN . +The user should not heavily rely on this field, as the +driver may not always, in fact it is very rarely able to, identify +the device type. +.Pp +The +.Dv model +is always +.Dv MOUSE_MODEL_GENERIC +at the operation level 0. +It may be +.Dv MOUSE_MODEL_GENERIC +or one of +.Dv MOUSE_MODEL_XXX +constants at higher operation levels. +Again the +.Nm +driver may or may not set an appropriate value in this field. +.Pp +The +.Dv hwid +is the ID value returned by the device. +Known IDs include: +.Pp +.Bl -tag -width 0__ -compact +.It Em 0 +Mouse (Microsoft, Logitech and many other manufacturers) +.It Em 2 +Microsoft Ballpoint mouse +.It Em 3 +Microsoft IntelliMouse +.El +.Pp +.It Dv MOUSE_SYN_GETHWINFO Ar synapticshw_t *synhw +Retrieves extra information associated with Synaptics Touchpad. +Only available when a supported device has been detected. +.Bd -literal +typedef struct synapticshw { + int infoMajor; /* major hardware revision */ + int infoMinor; /* minor hardware revision */ + int infoRot180; /* touchpad is rotated */ + int infoPortrait; /* touchpad is a portrait */ + int infoSensor; /* sensor model */ + int infoHardware; /* hardware model */ + int infoNewAbs; /* supports the newabs format */ + int capPen; /* can detect a pen */ + int infoSimplC; /* supports simple commands */ + int infoGeometry; /* touchpad dimensions */ + int capExtended; /* supports extended packets */ + int capSleep; /* can be suspended/resumed */ + int capFourButtons; /* has four buttons */ + int capMultiFinger; /* can detect multiple fingers */ + int capPalmDetect; /* can detect a palm */ + int capPassthrough; /* can passthrough guest packets */ + int capMiddle; /* has a physical middle button */ + int nExtendedButtons; /* has N additional buttons */ + int nExtendedQueries; /* supports N extended queries */ +} synapticshw_t; +.Ed +.Pp +See the +.Em Synaptics TouchPad Interfacing Guide +for more information about the fields in this structure. +.Pp +.It Dv MOUSE_GETMODE Ar mousemode_t *mode +The command gets the current operation parameters of the mouse +driver. +.Bd -literal +typedef struct mousemode { + int protocol; /* MOUSE_PROTO_XXX */ + int rate; /* report rate (per sec), -1 if unknown */ + int resolution; /* MOUSE_RES_XXX, -1 if unknown */ + int accelfactor; /* acceleration factor */ + int level; /* driver operation level */ + int packetsize; /* the length of the data packet */ + unsigned char syncmask[2]; /* sync. bits */ +} mousemode_t; +.Ed +.Pp +The +.Dv protocol +is +.Dv MOUSE_PROTO_PS2 +at the operation level zero and two. +.Dv MOUSE_PROTO_SYSMOUSE +at the operation level one. +.Pp +The +.Dv rate +is the status report rate (reports/sec) at which the device will send +movement report to the host computer. +Typical supported values are 10, 20, 40, 60, 80, 100 and 200. +Some mice may accept other arbitrary values too. +.Pp +The +.Dv resolution +of the pointing device must be one of +.Dv MOUSE_RES_XXX +constants or a positive value. +The greater the value +is, the finer resolution the mouse will select. +Actual resolution selected by the +.Dv MOUSE_RES_XXX +constant varies according to the model of mouse. +Typical resolutions are: +.Pp +.Bl -tag -width MOUSE_RES_MEDIUMHIGH__ -compact +.It Dv MOUSE_RES_LOW +25 ppi +.It Dv MOUSE_RES_MEDIUMLOW +50 ppi +.It Dv MOUSE_RES_MEDIUMHIGH +100 ppi +.It Dv MOUSE_RES_HIGH +200 ppi +.El +.Pp +The +.Dv accelfactor +field holds a value to control acceleration feature +(see +.Sx Acceleration ) . +It must be zero or greater. +If it is zero, acceleration is disabled. +.Pp +The +.Dv packetsize +field specifies the length of the data packet. +It depends on the +operation level and the model of the pointing device. +.Pp +.Bl -tag -width level_0__ -compact +.It Em level 0 +3 bytes +.It Em level 1 +8 bytes +.It Em level 2 +Depends on the model of the device +.El +.Pp +The array +.Dv syncmask +holds a bit mask and pattern to detect the first byte of the +data packet. +.Dv syncmask[0] +is the bit mask to be ANDed with a byte. +If the result is equal to +.Dv syncmask[1] , +the byte is likely to be the first byte of the data packet. +Note that this detection method is not 100% reliable, +thus, should be taken only as an advisory measure. +.Pp +.It Dv MOUSE_SETMODE Ar mousemode_t *mode +The command changes the current operation parameters of the mouse driver +as specified in +.Ar mode . +Only +.Dv rate , +.Dv resolution , +.Dv level +and +.Dv accelfactor +may be modifiable. +Setting values in the other field does not generate +error and has no effect. +.Pp +If you do not want to change the current setting of a field, put -1 +there. +You may also put zero in +.Dv resolution +and +.Dv rate , +and the default value for the fields will be selected. +.Pp +.It Dv MOUSE_READDATA Ar mousedata_t *data +.\" The command reads the raw data from the device. +.\" .Bd -literal +.\" typedef struct mousedata { +.\" int len; /* # of data in the buffer */ +.\" int buf[16]; /* data buffer */ +.\" } mousedata_t; +.\" .Ed +.\" .Pp +.\" Upon returning to the user program, the driver will place the number +.\" of valid data bytes in the buffer in the +.\" .Dv len +.\" field. +.\" .Pp +.It Dv MOUSE_READSTATE Ar mousedata_t *state +.\" The command reads the hardware settings from the device. +.\" Upon returning to the user program, the driver will place the number +.\" of valid data bytes in the buffer in the +.\" .Dv len +.\" field. It is usually 3 bytes. +.\" The buffer is formatted as follows: +.\" .Pp +.\" .Bl -tag -width Byte_1 -compact +.\" .It Byte 1 +.\" .Bl -tag -width bit_6 -compact +.\" .It bit 7 +.\" Reserved. +.\" .It bit 6 +.\" 0 - stream mode, 1 - remote mode. +.\" In the stream mode, the pointing device sends the device status +.\" whenever its state changes. In the remote mode, the host computer +.\" must request the status to be sent. +.\" The +.\" .Nm +.\" driver puts the device in the stream mode. +.\" .It bit 5 +.\" Set if the pointing device is currently enabled. Otherwise zero. +.\" .It bit 4 +.\" 0 - 1:1 scaling, 1 - 2:1 scaling. +.\" 1:1 scaling is the default. +.\" .It bit 3 +.\" Reserved. +.\" .It bit 2 +.\" Left button status; set if pressed. +.\" .It bit 1 +.\" Middle button status; set if pressed. +.\" .It bit 0 +.\" Right button status; set if pressed. +.\" .El +.\" .It Byte 2 +.\" .Bl -tag -width bit_6_0 -compact +.\" .It bit 7 +.\" Reserved. +.\" .It bit 6..0 +.\" Resolution code: zero through three. Actual resolution for +.\" the resolution code varies from one device to another. +.\" .El +.\" .It Byte 3 +.\" The status report rate (reports/sec) at which the device will send +.\" movement report to the host computer. +.\" .El +These commands are not currently supported by the +.Nm +driver. +.Pp +.It Dv MOUSE_GETSTATUS Ar mousestatus_t *status +The command returns the current state of buttons and +movement counts as described in +.Xr mouse 4 . +.El +.Sh FILES +.Bl -tag -width /dev/npsm0 -compact +.It Pa /dev/psm0 +`non-blocking' device node +.It Pa /dev/bpsm0 +`blocking' device node +.El +.Sh EXAMPLES +In order to install the +.Nm +driver, you need to add +.Pp +.Dl "device atkbdc" +.Dl "device psm" +.Pp +to your kernel configuration file, and put the following lines to +.Pa /boot/device.hints . +.Pp +.Dl hint.atkbdc.0.at="isa" +.Dl hint.atkbdc.0.port="0x060" +.Dl hint.psm.0.at="atkbdc" +.Dl hint.psm.0.irq="12" +.Pp +If you add the following statement to +.Pa /boot/device.hints , +.Pp +.Dl hint.psm.0.flags="0x2000" +.Pp +you will add the optional code to stimulate the pointing device +after the `resume' event. +.Pp +.Dl hint.psm.0.flags="0x24" +.Pp +The above line will set the device resolution high (4) +and the acceleration factor to 2. +.Sh DIAGNOSTICS +At debug level 0, little information is logged except for the following +line during boot process: +.Bd -literal -offset indent +psm0: device ID X +.Ed +.Pp +where +.Fa X +the device ID code returned by the found pointing device. +See +.Dv MOUSE_GETINFO +for known IDs. +.Pp +At debug level 1 more information will be logged +while the driver probes the auxiliary port (mouse port). +Messages are logged with the LOG_KERN facility at the LOG_DEBUG level +(see +.Xr syslogd 8 ) . +.Bd -literal -offset indent +psm0: current command byte:xxxx +kbdio: TEST_AUX_PORT status:0000 +kbdio: RESET_AUX return code:00fa +kbdio: RESET_AUX status:00aa +kbdio: RESET_AUX ID:0000 +[...] +psm: status 00 02 64 +psm0 irq 12 on isa +psm0: model AAAA, device ID X, N buttons +psm0: config:00000www, flags:0000uuuu, packet size:M +psm0: syncmask:xx, syncbits:yy +.Ed +.Pp +The first line shows the command byte value of the keyboard +controller just before the auxiliary port is probed. +It usually is 40, 45, 47 or 65, depending on how the motherboard BIOS +initialized the keyboard controller upon power-up. +.Pp +The second line shows the result of the keyboard controller's +test on the auxiliary port interface, with zero indicating +no error; note that some controllers report no error even if +the port does not exist in the system, however. +.Pp +The third through fifth lines show the reset status of the pointing device. +The functioning device should return the sequence of FA AA . +The ID code is described above. +.Pp +The seventh line shows the current hardware settings. +.\" See +.\" .Dv MOUSE_READSTATE +.\" for definitions. +These bytes are formatted as follows: +.Pp +.Bl -tag -width Byte_1 -compact +.It Byte 1 +.Bl -tag -width bit_6 -compact +.It bit 7 +Reserved. +.It bit 6 +0 - stream mode, 1 - remote mode. +In the stream mode, the pointing device sends the device status +whenever its state changes. +In the remote mode, the host computer +must request the status to be sent. +The +.Nm +driver puts the device in the stream mode. +.It bit 5 +Set if the pointing device is currently enabled. +Otherwise zero. +.It bit 4 +0 - 1:1 scaling, 1 - 2:1 scaling. +1:1 scaling is the default. +.It bit 3 +Reserved. +.It bit 2 +Left button status; set if pressed. +.It bit 1 +Middle button status; set if pressed. +.It bit 0 +Right button status; set if pressed. +.El +.It Byte 2 +.Bl -tag -width bit_6_0 -compact +.It bit 7 +Reserved. +.It bit 6..0 +Resolution code: zero through three. +Actual resolution for +the resolution code varies from one device to another. +.El +.It Byte 3 +The status report rate (reports/sec) at which the device will send +movement report to the host computer. +.El +.Pp +Note that the pointing device will not be enabled until the +.Nm +driver is opened by the user program. +.Pp +The rest of the lines show the device ID code, the number of detected +buttons and internal variables. +.Pp +At debug level 2, much more detailed information is logged. +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr syslog 3 , +.Xr atkbdc 4 , +.Xr mouse 4 , +.Xr sysmouse 4 , +.Xr moused 8 , +.Xr syslogd 8 +.Rs +.%T Synaptics TouchPad Interfacing Guide +.%U http://www.synaptics.com/ +.Re +.\".Sh HISTORY +.Sh AUTHORS +.An -nosplit +The +.Nm +driver is based on the work done by quite a number of people, including +.An Eric Forsberg , +.An Sandi Donno , +.An Rick Macklem , +.An Andrew Herbert , +.An Charles Hannum , +.An Shoji Yuen +and +.An Kazutaka Yokota +to name the few. +.Pp +This manual page was written by +.An Kazutaka Yokota Aq Mt yokota@FreeBSD.org . +.Sh CAVEATS +Many pad devices behave as if the first (left) button were pressed if +the user `taps' the surface of the pad. +In contrast, some pad products, e.g.\& some versions of ALPS GlidePoint +and Interlink VersaPad, treat the tapping action +as fourth button events. +.Pp +It is reported that ALPS GlidePoint, Synaptics Touchpad, IBM/Lenovo +TrackPoint, and Interlink VersaPad require +.Em INITAFTERSUSPEND +flag in order to recover from suspended state. +This flag is automatically set when one of these devices is detected by the +.Nm +driver. +.Pp +Some PS/2 mouse models from MouseSystems require to be put in the +high resolution mode to work properly. +Use the driver flag to +set resolution. +.Pp +There is not a guaranteed way to re-synchronize with the first byte +of the packet once we are out of synchronization with the data +stream. +However, if you are using the \fIXFree86\fP server and experiencing +the problem, you may be able to make the X server synchronize with the mouse +by switching away to a virtual terminal and getting back to the X server, +unless the X server is accessing the mouse via +.Xr moused 8 . +Clicking any button without moving the mouse may also work. +.Sh BUGS +Enabling the extended support for Synaptics touchpads has been reported to +cause problems with responsivity on some (newer) models of Synaptics +hardware, particularly those with guest devices. diff --git a/static/freebsd/man4/pst.4 b/static/freebsd/man4/pst.4 new file mode 100644 index 00000000..0f23f145 --- /dev/null +++ b/static/freebsd/man4/pst.4 @@ -0,0 +1,73 @@ +.\" +.\" Copyright (c) 2001,2002 Søren Schmidt +.\" 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 December 14, 2004 +.Dt PST 4 +.Os +.Sh NAME +.Nm pst +.Nd device driver for Promise Supertrak SX6000 +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device pst" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +pst_load="YES" +.Ed +.Sh DESCRIPTION +This driver is for the Promise Supertrak SX6000 ATA hardware RAID controller. +It supports (in hardware) RAID levels 0, 1, 0+1, 3, 5 and JBOD on up to +6 ATA disk drives, including automatic rebuild and hotswap, and supports +signalling disk status on LEDs on Promise Superswap disk enclosures. +The Supertrak line of controllers does not support non-disk devices. +.Sh HARDWARE +The +.Nm +driver supports the Promise Supertrak SX6000 ATA hardware RAID +controller. +.Sh NOTES +The +.Nm +driver does not support manipulating the RAID from the OS, RAIDs need +to be set up from the onboard BIOS. +However, hot swap, hot spare, and +automatic rebuilds are supported without a reboot. +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 4.7 . +.Sh AUTHORS +The +.Nm +driver and man page was written by +.An S\(/oren Schmidt Aq Mt sos@FreeBSD.org . diff --git a/static/freebsd/man4/pt.4 b/static/freebsd/man4/pt.4 new file mode 100644 index 00000000..e56c1a61 --- /dev/null +++ b/static/freebsd/man4/pt.4 @@ -0,0 +1,89 @@ +.\" Copyright (c) 1995 +.\" Peter Dufault, 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 March 2, 1995 +.Dt PT 4 +.Os +.Sh NAME +.Nm pt +.Nd SCSI processor type driver +.Sh SYNOPSIS +.Cd device pt +.Sh DESCRIPTION +The +.Nm +driver provides support for a +.Tn SCSI +processor type device. +These are usually scanners and other devices using the +.Tn SCSI +link as a communication interface with device +specific commands embedded in the data stream. +.Pp +A +.Tn SCSI +adapter must be separately configured into the system +before this driver can be used. +.Pp +This device supports +.Xr read 2 +and +.Xr write 2 , +and the +.Xr ioctl 2 +calls described below. +.Sh IOCTLS +The following +.Xr ioctl 2 +calls are supported by the +.Nm +driver. +They are defined in the header file +.In sys/ptio.h . +.Bl -tag -width 012345678901234 +.It PTIOCGETTIMEOUT +This ioctl allows userland applications to fetch the current +.Nm +driver read and write timeout. +The value returned is in seconds. +.It PTIOCSETTIMEOUT +This ioctl allows userland applications to set the current +.Nm +driver read and write timeouts. +The value should be in seconds. +.El +.Sh FILES +.Bl -tag -width /dev/ptQQQ -compact +.It Pa /dev/pt Ns Ar N +the +.Ar N Ns th processor device. +.El +.Sh SEE ALSO +.Xr cam 4 +.Sh HISTORY +The +.Nm +driver appeared in +.Fx 2.1 . diff --git a/static/freebsd/man4/ptnet.4 b/static/freebsd/man4/ptnet.4 new file mode 100644 index 00000000..71efb3cd --- /dev/null +++ b/static/freebsd/man4/ptnet.4 @@ -0,0 +1,138 @@ +.\" Copyright (c) 2018 Vincenzo Maffione +.\" 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 December 11, 2018 +.Dt PTNET 4 +.Os +.Sh NAME +.Nm ptnet +.Nd Ethernet driver for passed-through netmap ports +.Sh SYNOPSIS +This network driver is included in +.Xr netmap 4 , +and it can be compiled into the kernel by adding the following +line in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device netmap" +.Ed +.Sh DESCRIPTION +The +.Nm +device driver provides direct access to host netmap ports, +from within a Virtual Machine (VM). +Applications running inside +the VM can access the TX/RX rings and buffers of a netmap port +that the hypervisor has passed-through to the VM. +Hypervisor support for +.Nm +is currently available for QEMU/KVM. +Any +.Xr netmap 4 +port can be passed-through, including physical NICs, +.Xr vale 4 +ports, netmap pipes, etc. +.Pp +The main use-case for netmap passthrough is Network Function +Virtualization (NFV), where middlebox applications running within +VMs may want to process very high packet rates (e.g., 1-10 millions +packets per second or more). +Note, however, that those applications +must use the device in netmap mode in order to achieve such rates. +In addition to the general advantages of netmap, the improved +performance of +.Nm +when compared to hypervisor device emulation or paravirtualization (e.g., +.Xr vtnet 4 , +.Xr vmx 4 ) +comes from the hypervisor being completely bypassed in the data-path. +For example, when using +.Xr vtnet 4 +the VM has to convert each +.Xr mbuf 9 +to a VirtIO-specific packet representation +and publish that to a VirtIO queue; on the hypervisor side, the +packet is extracted from the VirtIO queue and converted to a +hypervisor-specific packet representation. +The overhead of format conversions (and packet copies, in same cases) is not +incured by +.Nm +in netmap mode, because mbufs are not used at all, and the packet format +is the one defined by netmap (e.g., +.Ar struct netmap_slot ) +along the whole data-path. +No format conversions or copies happen. +.Pp +It is also possible to use a +.Nm +device like a regular network interface, which interacts with the +.Fx +network stack (i.e., not in netmap mode). +However, in that case it is necessary to pay the cost of data copies +between mbufs and netmap buffers, which generally results in lower +TCP/UDP performance than +.Xr vtnet 4 +or other paravirtualized network devices. +If the passed-through netmap port supports the VirtIO network header, +.Nm +is able to use it, and support TCP/UDP checksum offload (for both transmit +and receive), TCP segmentation offload (TSO) and TCP large receive offload +(LRO). +Currently, +.Xr vale 4 +ports support the header. +Note that the VirtIO network header is generally not used in NFV +use-cases, because middleboxes are not endpoints of TCP/UDP connections. +.Sh TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width "xxxxxx" +.It Va dev.netmap.ptnet_vnet_hdr +This tunable enables (1) or disables (0) the VirtIO network header. +If enabled, +.Nm +uses the same header used by +.Xr vtnet 4 +to exchange offload metadata with the hypervisor. +If disabled, no header is prepended to transmitted and received +packets. +The metadata is necessary to support TCP/UDP checksum offloads, +TSO, and LRO. +The default value is 1. +.El +.Sh SEE ALSO +.Xr netintro 4 , +.Xr netmap 4 , +.Xr vale 4 , +.Xr virtio 4 , +.Xr vmx 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +driver was written by +.An Vincenzo Maffione Aq Mt vmaffione@FreeBSD.org . +It first appeared in +.Fx 12.0 . diff --git a/static/freebsd/man4/pts.4 b/static/freebsd/man4/pts.4 new file mode 100644 index 00000000..de04ca6e --- /dev/null +++ b/static/freebsd/man4/pts.4 @@ -0,0 +1,158 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 August 20, 2008 +.Dt PTS 4 +.Os +.Sh NAME +.Nm pts +.Nd pseudo-terminal driver +.Sh DESCRIPTION +The +.Nm +driver provides support for a device-pair termed a +.Em pseudo-terminal . +A pseudo-terminal is a pair of character devices, a +.Em master +device and a +.Em slave +device. +The slave device provides to a process an interface identical +to that described in +.Xr tty 4 . +However, whereas all other devices which provide the +interface described in +.Xr tty 4 +have a hardware device of some sort behind them, the slave +device has, instead, another process manipulating +it through the master half of the pseudo-terminal. +That is, anything written on the master device is +given to the slave device as input and anything written +on the slave device is presented as input on the master +device. +.Pp +The following +.Xr ioctl 2 +calls apply only to pseudo-terminals: +.Bl -tag -width TIOCPTMASTER +.It Dv TIOCPKT +Enable/disable +.Em packet +mode. +Packet mode is enabled by specifying (by reference) +a nonzero parameter and disabled by specifying (by reference) +a zero parameter. +When applied to the master side of a pseudo-terminal, each subsequent +.Xr read 2 +from the terminal will return data written on the slave part of +the pseudo-terminal preceded by a zero byte (symbolically +defined as +.Dv TIOCPKT_DATA ) , +or a single byte reflecting control +status information. +In the latter case, the byte is an inclusive-or +of zero or more of the bits: +.Bl -tag -width TIOCPKT_FLUSHWRITE +.It Dv TIOCPKT_FLUSHREAD +whenever the read queue for the terminal is flushed. +.It Dv TIOCPKT_FLUSHWRITE +whenever the write queue for the terminal is flushed. +.It Dv TIOCPKT_STOP +whenever output to the terminal is stopped a la +.Ql ^S . +.It Dv TIOCPKT_START +whenever output to the terminal is restarted. +.It Dv TIOCPKT_DOSTOP +whenever +.Dv VSTOP +is +.Ql ^S +and +.Dv VSTART +is +.Ql ^Q . +.It Dv TIOCPKT_NOSTOP +whenever the start and stop characters are not +.Ql ^S/^Q . +.El +.Pp +While this mode is in use, the presence of control status information +to be read from the master side may be detected by a +.Xr select 2 +for exceptional conditions. +.Pp +This mode is used by +.Xr rlogin 1 +and +.Xr rlogind 8 +to implement a remote-echoed, locally +.Ql ^S/^Q +flow-controlled +remote login with proper back-flushing of output; it can be +used by other similar programs. +.It Dv TIOCGPTN +Obtain device unit number, which can be used to generate the filename of +the pseudo-terminal slave device. +This +.Xr ioctl 2 +should not be used directly. +Instead, the +.Xr ptsname 3 +function should be used. +.It Dv TIOCPTMASTER +Determine whether the file descriptor is pointing to a pseudo-terminal +master device. +This +.Xr ioctl 2 +should not be used directly. +It is used to implement routines like +.Xr grantpt 3 . +.El +.Sh FILES +The files used by this +pseudo-terminals implementation are: +.Bl -tag -width ".Pa /dev/pts/[num]" +.It Pa /dev/pts/[num] +Pseudo-terminal slave devices. +.El +.Sh DIAGNOSTICS +None. +.Sh SEE ALSO +.Xr posix_openpt 2 , +.Xr grantpt 3 , +.Xr ptsname 3 , +.Xr pty 4 , +.Xr tty 4 +.Sh HISTORY +A +pseudo-terminal driver appeared in +.Bx 4.2 . +In +.Fx 8.0 , +it was replaced with the +.Nm +driver. diff --git a/static/freebsd/man4/pty.4 b/static/freebsd/man4/pty.4 new file mode 100644 index 00000000..b9c5fce8 --- /dev/null +++ b/static/freebsd/man4/pty.4 @@ -0,0 +1,98 @@ +.\" Copyright (c) 2008 Ed Schouten +.\" All rights reserved. +.\" +.\" Portions of this software were developed under sponsorship from Snow +.\" B.V., the Netherlands. +.\" +.\" 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 October 28, 2019 +.Dt PTY 4 +.Os +.Sh NAME +.Nm pty +.Nd old-style compatibility pseudo-terminal driver +.Sh SYNOPSIS +.Cd "device pty" +.Sh DESCRIPTION +The +.Nm +driver provides support for the traditional BSD naming scheme that was +used for accessing pseudo-terminals before it was replaced by +.Xr pts 4 . +This traditional naming is still used in Linux. +When the device +.Pa /dev/ptyXX +is being opened, a new terminal shall be created with the +.Xr pts 4 +driver. +A device node for this terminal shall be created, which has the name +.Pa /dev/ttyXX . +.Pp +The +.Nm +driver also provides a cloning System V +.Pa /dev/ptmx +device. +.Pp +New code should not try to allocate pseudo-terminals using this +interface. +It is only provided for compatibility with older C libraries +that tried to open such devices when +.Xr posix_openpt 2 +was being called, +and for running Linux binaries. +.Sh FILES +The BSD-style compatibility pseudo-terminal driver uses the following +device names: +.Bl -tag -width ".Pa /dev/pty[l-sL-S][0-9a-v]" +.It Pa /dev/pty[l-sL-S][0-9a-v] +Pseudo-terminal master devices. +.It Pa /dev/tty[l-sL-S][0-9a-v] +Pseudo-terminal slave devices. +.It Pa /dev/ptmx +Control device, returns a file descriptor to a new master +pseudo-terminal when opened. +.El +.Sh DIAGNOSTICS +None. +.Sh SEE ALSO +.Xr posix_openpt 2 , +.Xr pts 4 , +.Xr tty 4 +.Sh HISTORY +A +pseudo-terminal driver appeared in +.Bx 4.2 . +.Sh BUGS +Unlike previous implementations, the master and slave device nodes are +destroyed when the PTY becomes unused. +A call to +.Xr stat 2 +on a nonexistent master device will already cause a new master device +node to be created. +The master device can only be destroyed by opening and closing it. +.Pp +The +.Nm +driver cannot be unloaded, because it cannot determine if it is being +used. diff --git a/static/freebsd/man4/puc.4 b/static/freebsd/man4/puc.4 new file mode 100644 index 00000000..624c2150 --- /dev/null +++ b/static/freebsd/man4/puc.4 @@ -0,0 +1,291 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2002 John Hay. +.\" 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 June 11, 2025 +.Dt PUC 4 +.Os +.Sh NAME +.Nm puc +.Nd PCI +.Dq Universal +Communications driver +.Sh SYNOPSIS +.Cd "device pci" +.Cd "device puc" +.Cd "device uart" +.Cd "device ppc" +.Sh DESCRIPTION +The +.Nm +driver acts as a shim to connect +PCI multi-port serial and parallel adapters to the +.Xr uart 4 +and +.Xr ppc 4 +driver. +.Sh HARDWARE +The +.Nm +driver supports the following +PCI/PCIe multi-port serial and parallel adapters: +.Pp +.Bl -bullet -compact +.It +Advantech 2-port PCI PCI-1602/1603 Rev A/B1 +.It +Applied Micro Circuits PCI 8 Port UART +.It +Avlab Technology PCI IO 2S +.It +Avlab Low Profile PCI 4 Serial +.It +Boca Research PCI Turbo Serial 658/654 +.It +Brainboxes: +.Bl -dash -compact +.It +Instashield PCIe IX-400, IX-200, IX-100 +.It +Instashield PCI IS-400, IS-200 +.It +PX Series PCIe RS232/RS422/RS485/LPT +.It +UC Series Universal PCI RS232/RS422/RS485/LPT +.It +UP Series PCI Dual RS232 +.El +.It +Comtrol RocketPort 550 PCI 16/8/4 port +.It +Decision Computer PCCOM PCI 8/4/2 port +.It +Digi Neo PCIe 4 and 8 Port (with and without RJ45) +.It +Digi Neo PCI 4 and 8 Port +.It +Dolphin Peripherals PCI 4035/4014 +.It +Exar: +.Bl -dash -compact +.It +XR17C/D152 +.It +XR17C154 +.It +XR17C158 +.It +XR17V258IV +.It +XR17V352 +.It +XR17V354 +.It +XR17V358 +.El +.It +Feasso PCI FPP-02 2S1P +.It +HP Diva Serial [GSP] Multiport UART: +.Bl -dash -compact +.It +Tosca Console +.It +Tosca Secondary +.It +Maestro SP2 +.It +Superdome Console +.It +Keystone SP2 +.It +Everest SP2 +.El +.It +I-O DATA RSA-PCI2/R +.It +IBM SurePOS 300 Series (481033H) serial ports +.It +IC Book Labs: +.Bl -dash -compact +.It +Dreadnought x16 Pro/Lite +.It +Ironclad x8 Pro +.It +Gunboat x4 Pro/Lite/Low Profile +.It +Gunboat x2 Low Profile +.El +.It +Kuroutoshikou SERIAL4P-LPPCI2 +.It +Lava Computers: +.Bl -dash -compact +.It +Dual Serial PCI +.It +Quattro-PCIe +.It +Quattro-PCI +.It +Octopus-550 PCI +.El +.It +Moxa Technologies: +.Bl -dash -compact +.It +Smartio CP-102E/PCIe +.It +Smartio CP-102EL/PCIe +.It +Smartio C104H/PCI +.It +Smartio CP-104UL/PCI +.It +Smartio CP-104JU/PCI +.It +Smartio CP-104EL/PCIe +.It +Smartio CP-104EL-A/PCIe +.It +CP-112UL PCI +.It +Industio CP-114 +.It +Smartio CP-114EL/PCIe +.It +Smartio CP-118EL-A/PCIe +.It +C168H/PCI +.It +C168U/PCI +.It +CP-168EL/PCIe +.It +Smartio CP-168EL-A/PCIe +.El +.It +NetMos NM9815 Dual 1284 Printer port PCI +.It +NetMos NM9835 2/1 port UART + 1284 Printer PCI +.It +NetMos NM9845 4/6 port UART + 1284 Printer PCI +.It +NetMos NM9865 4/3/2 port UART + 1/2 port 1284 Printer PCI +.It +Oxford Semiconductor based boards: +.Bl -dash -compact +.It +OX16PCI952 UART (with and without Parallel port) +.It +OX16PCI954 UART +.It +OX9160/OX16PCI954 UARTs +.It +OX16PCI958 UART +.El +.It +Perle Ultraport4 Express PCIe Serial +.It +Perle Speed8/Speed4/Speed2 LE PCI Serial +.It +Quatech: +.Bl -dash -compact +.It +DSC-300/200/100 PCI +.It +DSCLP-300/200/100 PCI +.It +ESC-100/100D/100M PCI +.It +QSC-300/200/100 PCI +.It +QSCLP-100 PCI +.El +.It +SIIG Cyber Series of UART and parallel port boards: +.Bl -dash -compact +.It +Cyber 2S and 2SP1 PCI 16550 +.It +Cyber 4 and 4S PCI 16C650 (10x family and 20x family) +.It +Cyber I/O PCI (10x family and 20x family) +.It +Cyber Parallel Dual PCI (10x family and 20x family) +.It +Cyber Serial Dual PCI (10x family and 20x family) +.It +Cyber 2S1P PCI (10x family and 20x family) +.It +PS8000 8S PCI 16C650 (20x family) +.It +Quartet Serial 850 PCI +.El +.It +Sun 1040 PCI Quad Serial +.It +Sunix MIO5xxxx 4/2/1 port UART and 1284 Printer +.It +Sunix SUN1889/1888 PCI dual port serial +.It +Sunix SER5xxxx 8/4/2 port serial +.It +Syba Tech Ltd PCI-4S2P-550-ECP +.It +Systembase SB16C1054/8 4/8 port serial +.It +Titan PCI-800H/PCI-200H +.It +VScom: +.Bl -dash -compact +.It +PCIex-800H +.It +PCI-200HV2 +.It +200Li uPCI +.It +PCI-800L, PCI-200L, and PCI-100L +.It +PCI-800, PCI-400, and PCI-200 +.El +.El +.Sh FILES +.Bl -tag -width "sys/dev/puc/pucdata.c" +.It Pa sys/dev/puc/pucdata.c +list of supported devices +.El +.Sh SEE ALSO +.Xr ppc 4 , +.Xr uart 4 +.Sh HISTORY +This driver took the idea from the +.Nx +.Nm +driver. +It uses a substantial amount of the same data. diff --git a/static/freebsd/man4/pvscsi.4 b/static/freebsd/man4/pvscsi.4 new file mode 100644 index 00000000..19ca6cc5 --- /dev/null +++ b/static/freebsd/man4/pvscsi.4 @@ -0,0 +1,72 @@ +.\" Copyright (c) 2018 VMware, Inc. +.\" +.\" SPDX-License-Identifier: (BSD-2-Clause OR GPL-2.0) +.Dd December 5, 2018 +.Dt PVSCSI 4 +.Os +.Sh NAME +.Nm pvscsi +.Nd VMware Paravirtual SCSI Controller +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device pci" +.Cd "device scbus" +.Cd "device pvscsi" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +pvscsi_load="YES" +.Ed +.Pp +The following tunables are settable from the +.Xr loader 8 : +.Bl -ohang +.It Va hw.pvscsi.request_ring_pages +controls how many pages are allocated for the device request ring. +A non-positive value will cause the driver to choose the value based on device +capabilities. +A non-zero value will use that many number of pages up to a maximum of 32. +The default setting is 0. +.It Va hw.pvscsi.max_queue_depth +controls the queue size for the adapter. +A non-positive value will cause the driver to choose the value based on number +of request ring pages. +A non-zero value will set the queue size up to a maximum allowed by the number +of request ring pages. +Default is 0. +.It Va hw.pvscsi.use_msg +setting to nonzero value enables the use of the PVSCSI message queue allowing +for disk hot-add and remove without manual rescan needed. +Default is 1. +.It Va hw.pvscsi.use_msi +setting to nonzero value enables the use of MSI interrupts. +Default is 1. +.It Va hw.pvscsi.use_msix +setting to nonzero value enables the use of MSI-X interrupts. +Default is 1. +.It Va hw.pvscsi.use_req_call_threshold +setting to nonzero value enables the request call threshold functionality. +TODO. +Default is 1. +.El +.Sh DESCRIPTION +The +.Nm +driver provides support for the VMware Paravirtual SCSI Controller (PVSCSI) in +virtual machines by VMware. +.Sh SEE ALSO +.Xr cam 4 , +.Xr da 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An Vishal Bhakta Aq Mt vbhakta@vmware.com . diff --git a/static/freebsd/man4/pwmc.4 b/static/freebsd/man4/pwmc.4 new file mode 100644 index 00000000..a3d6b1e9 --- /dev/null +++ b/static/freebsd/man4/pwmc.4 @@ -0,0 +1,209 @@ +.\" +.\" Copyright (c) 2019 Ian Lepore +.\" +.\" 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 ``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 June 17, 2019 +.Dt PWMC 4 +.Os +.Sh NAME +.Nm pwmc +.Nd PWM (Pulse Width Modulation) control device driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device pwmbus" +.Cd "device pwmc" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +pwmc_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides device-control access to a channel of PWM hardware. +Each instance of a +.Nm +device is associated with a single PWM output channel. +.Pp +Some PWM hardware is organized with multiple channels sharing a +common clock or other resources. +In such cases, a separate +.Nm +instance will exist for each channel, but changing the period or +duty cycle of any one channel may affect other channels within the +hardware which share the same resources. +Consult the documentation for the underlying PWM hardware device driver +for details on channels that share resources. +.Pp +An instance of +.Nm +creates a character device named +.Pa /dev/pwm/pwmcX.Y +where +.Va X +is a sequential number assigned to each PWM hardware controller +as it is discovered by the system, and +.Va Y +is the channel number within that hardware controller. +The driver can be configured to create aliases that point to the +.Pa pwmcX.Y +entries, in effect creating named channels. +.Pp +The +.Nm +driver provides control of a PWM channel with the following +.Xr ioctl 2 +calls and data structures, defined in +.In dev/pwm/pwmc.h : +.Bl -tag -width indent +.It Dv PWMGETSTATE Pq Vt "struct pwm_state" +Retrieve the current state of the channel. +.It Dv PWMSETSTATE Pq Vt "struct pwm_state" +Set the current state of the channel. +All parameters are updated on every call. +To change just one of the values, use +.Dv PWMGETSTATE +to get the current state and then submit the same data back with +just the appropriate value changed. +.El +.Pp +The +.Va pwm_state +structure is defined as follows: +.Bd -literal +struct pwm_state { + u_int period; + u_int duty; + uint32_t flags; + bool enable; +}; +.Ed +.Bl -tag -width period +.It Va period +The duration, in nanoseconds, of one complete on-off cycle. +.It Va duty +The duration, in nanoseconds, of the on portion of one cycle. +.It Va flags +Flags that affect the output signal can be bitwise-ORed together. +The following flags are currently defined: +.Pp +.Bl -tag -width PWM_POLARITY_INVERTED -compact +.It Dv PWM_POLARITY_INVERTED +Invert the signal polarity. +.El +.It Va enable +.Va +False to disable the output signal or true to enable it. +.El +.Sh HINTS CONFIGURATION +On a +.Xr device.hints 5 +based system, such as +.Li MIPS , +these values are configurable for +.Nm : +.Bl -tag -width indent +.It Va hint.pwmc.%d.at +The pwmbus instance the +.Nm +instance is attached to. +.It Va hint.pwmc.%d.channel +The hardware channel number the instance is attached to. +Channel numbers count up from zero. +.It Va hint.pwmc.%d.label +If this optional hint is set, the driver creates an alias in +.Pa /dev/pwm +with the given name, which points to the instance. +.El +.Sh FDT CONFIGURATION +On an +.Xr fdt 4 +based system, a +.Nm +device is described with a child node of the pwm hardware controller node. +When the hardware supports multiple channels within the controller, it is +not necessary to include a +.Nm +child node for every channel the hardware supports. +Define only the channels you need to control. +.Pp +The following properties are required for a +.Nm +device node: +.Bl -tag -width indent +.It Va compatible +Must be the string "freebsd,pwmc". +.It Va reg +The hardware channel number. +.El +.Pp +The following properties are optional for the +.Nm +device node: +.Bl -tag -width indent +.It Va label +A string containing only characters legal in a file name. +The driver creates an alias with the given name in +.Pa /dev/pwm +which points to the instance's +.Pa /dev/pwm/pwmcX.Y +device entry. +.El +.Pp +Example of a PWM hardware node containing one +.Nm +child node: +.Bd -literal +&ehrpwm0 { + status = "okay"; + pinctrl-names = "default"; + pinctrl-0 = <&ehrpwm0_AB_pins>; + + pwmcontrol@0 { + compatible = "freebsd,pwmc"; + reg = <0>; + label = "backlight"; + }; +}; +.Ed +.Sh FILES +.Bl -tag -width -compact +.It Pa /dev/pwm/pwmc* +.El +.Sh SEE ALSO +.Xr fdt 4 , +.Xr device.hints 5 , +.Xr pwm 8 , +.Xr pwm 9 +.Sh HISTORY +The +.Nm +driver +appeared in +.Fx 13.0 . diff --git a/static/freebsd/man4/qat.4 b/static/freebsd/man4/qat.4 new file mode 100644 index 00000000..613091df --- /dev/null +++ b/static/freebsd/man4/qat.4 @@ -0,0 +1,189 @@ +.\" SPDX-License-Identifier: BSD-3-Clause +.\" Copyright(c) 2007-2025 Intel Corporation +.Dd June 2, 2025 +.Dt QAT 4 +.Os +.Sh NAME +.Nm qat +.Nd Intel QuickAssist Technology driver +.Sh SYNOPSIS +To load the driver call: +.Pp +.Bl -item -compact +.It +kldload qat +.El +.Pp +In order to load the driver on boot add these lines to +.Xr loader.conf 5 selecting firmware(s) suitable for installed device(s) +.Pp +.Bl -item -compact +.It +qat_200xx_fw_load="YES" +.It +qat_c3xxx_fw_load="YES" +.It +qat_c4xxx_fw_load="YES" +.It +qat_c62x_fw_load="YES" +.It +qat_dh895xcc_fw_load="YES" +.It +qat_4xxx_fw_load="YES" +.It +qat_load="YES" +.El +.Sh DESCRIPTION +The +.Nm +driver supports cryptography and compression acceleration of the +Intel (R) QuickAssist Technology (QAT) devices. +.Pp +A complete API for offloading these operations is exposed in the kernel +and may be used by any other entity directly. +In addition to exposing a complete kernel API for +offloading cryptography and compression operations, the +.Nm +driver also integrates with +.Xr crypto 4 , +allowing offloading supported operations to Intel QuickAssist Technology +devices. +.Sh HARDWARE +The +.Nm +driver supports the following Intel QuickAssist Technology Engines: +.Pp +.Bl -bullet -compact +.It +Intel (R) C62x Chipset +.It +Intel (R) Atom C3000 processor product family +.It +Intel (R) QuickAssist Adapter 8960/Intel (R) QuickAssist Adapter 8970 +(formerly known as "Lewis Hill") +.It +Intel (R) Communications Chipset 8925 to 8955 Series +.It +Intel (R) Atom P5300 processor product family +.It +Intel (R) QAT 4xxx Series +.El +.Sh SYSCTL_VARIABLES +The following +.Xr sysctl 8 +variables may be used to reconfigure the +.Nm +device. +For configuration persistence those variables may be set before loading +the driver, either via +.Xr kenv 1 +or +.Xr loader.conf 5 . +.Pp +The specific device needs to be in the "down" state +before changing the configuration. +.Bl -tag -width indent +.It Va dev.qat.X.state +Show or set current state of the device. +Possible values: "down", "up". +.Pp +NOTE: If the symmetric services are used for device the +.Sy qat_ocf +driver needs to be disabled prior the device reconfiguration. +.It Va dev.qat_ocf.0.enable +Enable/disable the QAT cryptographic framework connectivity. +Enabled by default. +.It Va dev.qat.X.cfg_services +Override the device services enabled, may be one of: +symmetric, asymmetric, data compression. +Possible values: "sym", "asym", "dc", "sym;dc", "asym;dc", "sym;asym". +Default services configured +are "sym;asym" for even and "dc" for odd devices. +.It Va dev.qat.X.cfg_mode +Override the device mode configuration +for kernel space and user space instances. +Possible values: "ks", "us", "ks;us". +Default value "ks;us". +.It Va dev.qat.X.num_user_processes +Override the number of uio user space processes +that can connect to the QAT device. +Default: 2 +.It Va dev.qat.X.disable_safe_dc_mode +Override history buffer mitigation. +Disabled by default. +If enabled, decompression throughput increases but may result in a data leak if +.Va dev.qat.X.num_user_processes +is more than 1. +Enable this option only if your system is not prone to user data leaks. +.El +.Pp +The following +.Xr sysctl 8 +variables are read-only: +.Bl -tag -width indent +.It Va dev.qat.X.frequency +QAT device frequency value. +.It Va dev.qat.X.mmp_version +QAT MMP Library revision number. +.It Va dev.qat.X.hw_version +QAT hardware revision number. +.It Va dev.qat.X.fw_version +QAT firmware revision number. +.It Va dev.qat.X.dev_cfg +Summary of device specific configuration. +.It Va dev.qat.X.heartbeat +QAT device heartbeat status. +Value '1' indicates that the device is operational. +Value '0' means that the device is not responsive. +Device requires restart. +.It Va dev.qat.X.heartbeat_failed +Number of QAT heartbeat failures received. +.It Va dev.qat.X.heartbeat_sent +Number of QAT heartbeat requests sent. +.El +.Sh SEE ALSO +.Xr crypto 4 , +.Xr ipsec 4 , +.Xr pci 4 , +.Xr crypto 7 , +.Xr crypto 9 +.Pp +For details of usage and supported operations and algorithms refer to +the following documentation available from Intel Download Center +.Lk https://downloadcenter.intel.com : +.Pp +.Bl -bullet -compact +.It +.Rs +.%A Intel (R) +.%T QuickAssist Technology API Programmer's Guide +.Re +.It +.Rs +.%A Intel (R) +.%T QuickAssist Technology Cryptographic API Reference Manual +.Re +.It +.Rs +.%A Intel (R) +.%T QuickAssist Technology Data Compression API Reference Manual +.Re +.It +.Rs +.%A Intel (R) +.%T QuickAssist Technology Performance Optimization Guide +.Re +.El +.Sh HISTORY +A +.Nm +driver appeared in +.Fx 13.0 . +It was superseded in +.Fx 14.0 +by the upstream driver. +.Sh AUTHORS +The +.Nm +driver was written by +.An Intel (R) Corporation . diff --git a/static/freebsd/man4/qat_c2xxx.4 b/static/freebsd/man4/qat_c2xxx.4 new file mode 100644 index 00000000..aad0c043 --- /dev/null +++ b/static/freebsd/man4/qat_c2xxx.4 @@ -0,0 +1,100 @@ +.\"- +.\" Copyright (c) 2020 Rubicon Communications, LLC (Netgate) +.\" +.\" 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 21, 2022 +.Dt QAT_C2XXX 4 +.Os +.Sh NAME +.Nm qat_c2xxx +.Nd Intel QuickAssist Technology (QAT) driver for Atom C2000 chipsets +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device crypto" +.Cd "device cryptodev" +.Cd "device qat" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +qat_c2xxx_load="YES" +qat_c2xxxfw_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver implements +.Xr crypto 4 +support for some of the cryptographic acceleration functions of the Intel +QuickAssist (QAT) device found on Atom C2000 devices. +QAT devices are enumerated through PCIe and are thus visible in +.Xr pciconf 8 +output. +.Pp +The +.Nm +driver can accelerate AES in CBC, CTR, and GCM modes, +and can perform authenticated encryption combining the CBC, and CTR modes +with SHA1-HMAC and SHA2-HMAC. +The +.Nm +driver can also compute SHA1 and SHA2 digests. +The implementation of AES-GCM has a firmware-imposed constraint that the length +of any additional authenticated data (AAD) must not exceed 240 bytes. +The driver thus rejects +.Xr crypto 9 +requests that do not satisfy this constraint. +.Sh SEE ALSO +.Xr crypto 4 , +.Xr ipsec 4 , +.Xr pci 4 , +.Xr qat 4 , +.Xr random 4 , +.Xr crypto 7 , +.Xr crypto 9 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 13.0 . +.Sh AUTHORS +The +.Nm +driver was written for +.Nx +by +.An Hikaru Abe Aq Mt hikaru@iij.ad.jp . +.An Mark Johnston Aq Mt markj@FreeBSD.org +ported the driver to +.Fx . +.Sh BUGS +Some Atom C2000 QAT devices have two acceleration engines instead of one. +The +.Nm +driver currently misbehaves when both are enabled and thus does not enable +the second acceleration engine if one is present. diff --git a/static/freebsd/man4/qlnxe.4 b/static/freebsd/man4/qlnxe.4 new file mode 100644 index 00000000..70bad789 --- /dev/null +++ b/static/freebsd/man4/qlnxe.4 @@ -0,0 +1,90 @@ +.\"- +.\" Copyright (c) 2017 Cavium Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY 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 May 9, 2017 +.Dt QLNXE 4 amd64 +.Os +.Sh NAME +.Nm qlnxe +.Nd "Cavium 25/40/100 Gigabit Ethernet & CNA Adapter Driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device qlnxe" +.Ed +.Pp +To load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_qlnxe_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports IPv4 checksum offload, +TCP and UDP checksum offload for both IPv4 and IPv6, +Large Segment Offload for both IPv4 and IPv6, +Jumbo frames, VLAN Tag, Receive Side scaling, HW and Soft LRO. +For further hardware information, see +.Pa http://www.qlogic.com/ . +.Sh HARDWARE +The +.Nm +driver supports 25/40/100 Gigabit Ethernet & CNA Adapter based on the following +chipsets: +.Pp +.Bl -bullet -compact +.It +QLogic 45000 series +.It +QLogic 41000 series +.El +.Sh SUPPORT +For support questions please contact your Cavium approved reseller or +Cavium Technical Support at +.Pa http://support.qlogic.com , +or by E-mail at +.Aq Mt support@qlogic.com . +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 11.1 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An David C Somayajulu +at Cavium Inc. diff --git a/static/freebsd/man4/qlxgb.4 b/static/freebsd/man4/qlxgb.4 new file mode 100644 index 00000000..cc97cd06 --- /dev/null +++ b/static/freebsd/man4/qlxgb.4 @@ -0,0 +1,91 @@ +.\"- +.\" Copyright (c) 2011 "Bjoern A. Zeeb" +.\" 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 November 3, 2011 +.Dt QLXGB 4 amd64 +.Os +.Sh NAME +.Nm qlxgb +.Nd "QLogic 10 Gigabit Ethernet & CNA Adapter Driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device qlxgb" +.Ed +.Pp +To load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_qlxgb_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports IPv4 checksum offload, +TCP and UDP checksum offload for both IPv4 and IPv6, +Large Segment Offload for both IPv4 and IPv6, +Jumbo frames, VLAN Tag, and +Receive Side scaling. +For further hardware information, see +.Pa http://www.qlogic.com/ . +.Sh HARDWARE +The +.Nm +driver supports 10 Gigabit Ethernet & CNA Adapter based on the following +chipsets: +.Pp +.Bl -bullet -compact +.It +QLogic 3200 series +.It +QLogic 8200 series +.El +.Sh SUPPORT +For support questions please contact your QLogic approved reseller or +QLogic Technical Support at +.Pa http://support.qlogic.com , +or by E-mail at +.Aq Mt support@qlogic.com . +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 10.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An David C Somayajulu +at QLogic Corporation. diff --git a/static/freebsd/man4/qlxgbe.4 b/static/freebsd/man4/qlxgbe.4 new file mode 100644 index 00000000..465e4fc0 --- /dev/null +++ b/static/freebsd/man4/qlxgbe.4 @@ -0,0 +1,90 @@ +.\"- +.\" Copyright (c) 2013 Qlogic Corportaion +.\" 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 April 1, 2013 +.Dt QLXGBE 4 amd64 +.Os +.Sh NAME +.Nm qlxgbe +.Nd "QLogic 10 Gigabit Ethernet & CNA Adapter Driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device qlxgbe" +.Ed +.Pp +To load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_qlxgbe_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports IPv4 checksum offload, +TCP and UDP checksum offload for both IPv4 and IPv6, +Large Segment Offload for both IPv4 and IPv6, +Jumbo frames, VLAN Tag, and +Receive Side scaling, ability to select either HW or Software LRO, +when LRO is enabled (default HW LRO). +For further hardware information, see +.Pa http://www.qlogic.com/ . +.Sh HARDWARE +The +.Nm +driver supports 10 Gigabit Ethernet & CNA Adapter based on the following +chipsets: +.Pp +.Bl -bullet -compact +.It +QLogic 8300 series +.El +.Sh SUPPORT +For support questions please contact your QLogic approved reseller or +QLogic Technical Support at +.Pa http://support.qlogic.com , +or by E-mail at +.Aq Mt support@qlogic.com . +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 10.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An David C Somayajulu +at QLogic Corporation. diff --git a/static/freebsd/man4/qlxge.4 b/static/freebsd/man4/qlxge.4 new file mode 100644 index 00000000..14a1e128 --- /dev/null +++ b/static/freebsd/man4/qlxge.4 @@ -0,0 +1,89 @@ +.\"- +.\" Copyright (c) 2013-2014 Qlogic Corporation +.\" 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 June 21, 2013 +.Dt QLXGE 4 amd64 +.Os +.Sh NAME +.Nm qlxge +.Nd "QLogic 8100 Series 10 Gigabit Ethernet Adapter Driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device qlxge" +.Ed +.Pp +To load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_qlxge_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports IPv4 checksum offload, +TCP and UDP checksum offload for both IPv4 and IPv6, +Large Segment Offload for both IPv4 and IPv6, +Jumbo frames, VLAN Tag, and +Receive Side scaling. +For further hardware information, see +.Pa http://www.qlogic.com/ . +.Sh HARDWARE +The +.Nm +driver supports 10 Gigabit Ethernet & CNA Adapter based on the following +chipsets: +.Pp +.Bl -bullet -compact +.It +QLogic 8100 series +.El +.Sh SUPPORT +For support questions please contact your QLogic approved reseller or +QLogic Technical Support at +.Pa http://support.qlogic.com , +or by E-mail at +.Aq Mt support@qlogic.com . +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 10.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An David C Somayajulu +at QLogic Corporation. diff --git a/static/freebsd/man4/ral.4 b/static/freebsd/man4/ral.4 new file mode 100644 index 00000000..ad385e5f --- /dev/null +++ b/static/freebsd/man4/ral.4 @@ -0,0 +1,301 @@ +.\"- +.\" SPDX-License-Identifier: ISC +.\" +.\" Copyright (c) 2005-2010 Damien Bergamini +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd November 10, 2024 +.Dt RAL 4 +.Os +.Sh NAME +.Nm ral +.Nd Ralink Technology IEEE 802.11a/g/n wireless network driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ral" +.Cd "device ralfw" +.Cd "device wlan" +.Cd "device wlan_amrr" +.Cd "device firmware" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_ral_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports PCI/PCIe/CardBus wireless adapters based on the Ralink RT2500, +RT2501, RT2600, RT2700, RT2800, RT3090 and RT3900E chipsets. +.Pp +The RT2500 chipset is the first generation of 802.11b/g adapters from Ralink. +It consists of two integrated chips, an RT2560 MAC/BBP and an RT2525 radio +transceiver. +.Pp +The RT2501 chipset is the second generation of 802.11a/b/g adapters from +Ralink. +It consists of two integrated chips, an RT2561 MAC/BBP and an RT2527 radio +transceiver. +This chipset provides support for the IEEE 802.11e standard with multiple +hardware transmission queues and allows scatter/gather for efficient DMA +operations. +.Pp +The RT2600 chipset consists of two integrated chips, an RT2661 MAC/BBP and an +RT2529 radio transceiver. +This chipset uses the MIMO (multiple-input multiple-output) technology with +multiple radio transceivers to extend the operating range of the adapter and +to achieve higher throughput. +However, the RT2600 chipset does not support any of the 802.11n features. +.Pp +The RT2700 chipset is a low-cost version of the RT2800 chipset. +It supports a single transmit path and two receiver paths (1T2R). +It consists of two integrated chips, an RT2760 or RT2790 (PCIe) MAC/BBP and +an RT2720 (2.4GHz) or RT2750 (2.4GHz/5GHz) radio transceiver. +.Pp +The RT2800 chipset is the first generation of 802.11n adapters from Ralink. +It consists of two integrated chips, an RT2860 or RT2890 (PCIe) MAC/BBP and +an RT2820 (2.4GHz) or RT2850 (2.4GHz/5GHz) radio transceiver. +The RT2800 chipset supports two transmit paths and up to three receiver +paths (2T2R/2T3R). +It can achieve speeds up to 144Mbps (20MHz bandwidth) and 300Mbps (40MHz +bandwidth.) +.Pp +The RT3090 chipset is the first generation of single-chip 802.11n adapters +from Ralink. +.Nm +supports +.Cm station , +.Cm adhoc , +.Cm hostap , +.Cm mesh , +.Cm wds , +and +.Cm monitor +mode operation. +Only one +.Cm hostap +or +.Cm mesh +virtual interface may be configured at a time. +Any number of +.Cm wds +virtual interfaces may be configured together with a +.Cm hostap +interface. +Multiple +.Cm station +interfaces may be operated together with a +.Cm hostap +interface to construct a wireless repeater device. +.Pp +The RT3900E chipset is a single-chip 802.11n adapters from Ralink. +The MAC/Baseband Processor can be an RT5390 or RT5392. +The RT5390 chip operates in the 2GHz spectrum and supports 1 transmit path +and 1 receiver path (1T1R). +The RT5392 chip operates in the 2GHz spectrum and supports up to 2 transmit +paths and 2 receiver paths (2T2R). +.Pp +The transmit speed is user-selectable or can be adapted automatically by the +driver depending on the number of hardware transmission retries. +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports PCI/PCIe/CardBus wireless adapters based on Ralink Technology +chipsets, including: +.Pp +.Bl -column -offset indent -compact "Atlantis Land A02-PCM-W54" "RT2561S" "CardBus" +.It Em Card Ta Em MAC/BBP Ta Em Bus +.It "A-Link WL54H" Ta RT2560 Ta PCI +.It "A-Link WL54PC" Ta RT2560 Ta CardBus +.It "AirLink101 AWLC5025" Ta RT2661 Ta CardBus +.It "AirLink101 AWLH5025" Ta RT2661 Ta PCI +.It "Amigo AWI-914W" Ta RT2560 Ta CardBus +.It "Amigo AWI-922W" Ta RT2560 Ta mini-PCI +.It "Amigo AWI-926W" Ta RT2560 Ta PCI +.It "AMIT WL531C" Ta RT2560 Ta CardBus +.It "AMIT WL531P" Ta RT2560 Ta PCI +.It "AOpen AOI-831" Ta RT2560 Ta PCI +.It "ASUS WL-107G" Ta RT2560 Ta CardBus +.It "ASUS WL-130g" Ta RT2560 Ta PCI +.It "Atlantis Land A02-PCI-W54" Ta RT2560 Ta PCI +.It "Atlantis Land A02-PCM-W54" Ta RT2560 Ta CardBus +.It "Belkin F5D7000 v3" Ta RT2560 Ta PCI +.It "Belkin F5D7010 v2" Ta RT2560 Ta CardBus +.It "Billionton MIWLGRL" Ta RT2560 Ta mini-PCI +.It "Canyon CN-WF511" Ta RT2560 Ta PCI +.It "Canyon CN-WF513" Ta RT2560 Ta CardBus +.It "CC&C WL-2102" Ta RT2560 Ta CardBus +.It "CNet CWC-854" Ta RT2560 Ta CardBus +.It "CNet CWP-854" Ta RT2560 Ta PCI +.It "Compex WL54G" Ta RT2560 Ta CardBus +.It "Compex WLP54G" Ta RT2560 Ta PCI +.It "Conceptronic C54RC" Ta RT2560 Ta CardBus +.It "Conceptronic C54Ri" Ta RT2560 Ta PCI +.It "D-Link DWA-525 rev A2" Ta RT5392 Ta PCI +.It "Digitus DN-7001G-RA" Ta RT2560 Ta CardBus +.It "Digitus DN-7006G-RA" Ta RT2560 Ta PCI +.It "E-Tech WGPC02" Ta RT2560 Ta CardBus +.It "E-Tech WGPI02" Ta RT2560 Ta PCI +.It "Edimax EW-7108PCg" Ta RT2560 Ta CardBus +.It "Edimax EW-7128g" Ta RT2560 Ta PCI +.It "Eminent EM3036" Ta RT2560 Ta CardBus +.It "Eminent EM3037" Ta RT2560 Ta PCI +.It "Encore ENLWI-G-RLAM" Ta RT2560 Ta PCI +.It "Encore ENPWI-G-RLAM" Ta RT2560 Ta CardBus +.It "Fiberline WL-400P" Ta RT2560 Ta PCI +.It "Fibreline WL-400X" Ta RT2560 Ta CardBus +.It "Gigabyte GN-WI01GS" Ta RT2561S Ta mini-PCI +.It "Gigabyte GN-WIKG" Ta RT2560 Ta mini-PCI +.It "Gigabyte GN-WMKG" Ta RT2560 Ta CardBus +.It "Gigabyte GN-WP01GS" Ta RT2561S Ta PCI +.It "Gigabyte GN-WPKG" Ta RT2560 Ta PCI +.It "Hawking HWC54GR" Ta RT2560 Ta CardBus +.It "Hawking HWP54GR" Ta RT2560 Ta PCI +.It "iNexQ CR054g-009 (R03)" Ta RT2560 Ta PCI +.It "JAHT WN-4054P" Ta RT2560 Ta CardBus +.It "JAHT WN-4054PCI" Ta RT2560 Ta PCI +.It "LevelOne WNC-0301 v2" Ta RT2560 Ta PCI +.It "LevelOne WPC-0301 v2" Ta RT2560 Ta CardBus +.It "Linksys WMP54G v4" Ta RT2560 Ta PCI +.It "Micronet SP906GK" Ta RT2560 Ta PCI +.It "Micronet SP908GK V3" Ta RT2560 Ta CardBus +.It "Minitar MN54GCB-R" Ta RT2560 Ta CardBus +.It "Minitar MN54GPC-R" Ta RT2560 Ta PCI +.It "MSI CB54G2" Ta RT2560 Ta CardBus +.It "MSI MP54G2" Ta RT2560 Ta mini-PCI +.It "MSI PC54G2" Ta RT2560 Ta PCI +.It "OvisLink EVO-W54PCI" Ta RT2560 Ta PCI +.It "PheeNet HWL-PCIG/RA" Ta RT2560 Ta PCI +.It "Planex GW-NS300N" Ta RT2860 Ta CardBus +.It "Pro-Nets CB80211G" Ta RT2560 Ta CardBus +.It "Pro-Nets PC80211G" Ta RT2560 Ta PCI +.It "Repotec RP-WB7108" Ta RT2560 Ta CardBus +.It "Repotec RP-WP0854" Ta RT2560 Ta PCI +.It "SATech SN-54C" Ta RT2560 Ta CardBus +.It "SATech SN-54P" Ta RT2560 Ta PCI +.It "Sitecom WL-112" Ta RT2560 Ta CardBus +.It "Sitecom WL-115" Ta RT2560 Ta PCI +.It "SMC SMCWCB-GM" Ta RT2661 Ta CardBus +.It "SMC SMCWPCI-GM" Ta RT2661 Ta PCI +.It "SparkLAN WL-685R" Ta RT2560 Ta CardBus +.It "Surecom EP-9321-g" Ta RT2560 Ta PCI +.It "Surecom EP-9321-g1" Ta RT2560 Ta PCI +.It "Surecom EP-9428-g" Ta RT2560 Ta CardBus +.It "Sweex LC500050" Ta RT2560 Ta CardBus +.It "Sweex LC700030" Ta RT2560 Ta PCI +.It "TekComm NE-9321-g" Ta RT2560 Ta PCI +.It "TekComm NE-9428-g" Ta RT2560 Ta CardBus +.It "Unex CR054g-R02" Ta RT2560 Ta PCI +.It "Unex MR054g-R02" Ta RT2560 Ta CardBus +.It "Zinwell ZWX-G160" Ta RT2560 Ta CardBus +.It "Zinwell ZWX-G360" Ta RT2560 Ta mini-PCI +.It "Zinwell ZWX-G361" Ta RT2560 Ta PCI +.It "Zonet ZEW1500" Ta RT2560 Ta CardBus +.It "Zonet ZEW1600" Ta RT2560 Ta PCI +.El +.Sh EXAMPLES +Join an existing BSS network (i.e., connect to an access point): +.Pp +.Dl ifconfig wlan create wlandev ral0 inet 192.0.2.20/24 +.Pp +Join a specific BSS network with network name +.Ar my_net : +.Bd -literal -offset indent +ifconfig wlan create wlandev ral0 inet 192.0.2.20/24 \e + ssid my_net +.Ed +.Pp +Join a specific BSS network with 40-bit WEP encryption: +.Bd -literal -offset indent +ifconfig wlan create wlandev ral0 inet 192.0.2.20/24 \e + ssid my_net wepmode on wepkey 0x1234567890 weptxkey 1 +.Ed +.Pp +Join a specific BSS network with 104-bit WEP encryption: +.Bd -literal -offset indent +ifconfig wlan create wlandev ral0 inet 192.0.2.20/24 \e + ssid my_net \e + wepmode on wepkey 0x01020304050607080910111213 weptxkey 1 +.Ed +.Sh DIAGNOSTICS +.Bl -diag +.It "ral%d: could not load 8051 microcode" +An error occurred while attempting to upload the microcode to the onboard 8051 +microcontroller unit. +.It "ral%d: timeout waiting for MCU to initialize" +The onboard 8051 microcontroller unit failed to initialize in time. +.It "ral%d: device timeout" +A frame dispatched to the hardware for transmission did not complete in time. +The driver will reset the hardware. +This should not happen. +.El +.Sh SEE ALSO +.Xr cardbus 4 , +.Xr intro 4 , +.Xr wlan 4 , +.Xr wlan_ccmp 4 , +.Xr wlan_tkip 4 , +.Xr wlan_wep 4 , +.Xr wlan_xauth 4 , +.Xr networking 7 , +.Xr hostapd 8 , +.Xr ifconfig 8 , +.Xr wpa_supplicant 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Ox 3.7 . +Support for the RT2501 and RT2600 chipsets was added in +.Ox 3.9 . +Support for the RT2800 chipset was added in +.Ox 4.3 . +Support for the RT2700 chipset was added in +.Ox 4.4 . +Support for the RT3090 chipset was added in +.Ox 4.9 . +.Sh AUTHORS +The original +.Nm +driver was written by +.An Damien Bergamini Aq Mt damien@openbsd.org . +.Sh CAVEATS +The +.Nm +driver does not make use of the hardware cryptographic engine. +.Pp +The +.Nm +driver does not support any of the 802.11n capabilities offered by +the RT2700 and RT2800 chipsets. +Additional work is required in before those features can be supported. +.Pp +Host AP mode does not support power saving. +Clients attempting to use power saving mode may experience significant +packet loss (disabling power saving on the client will fix this). +.Pp +Some PCI +.Nm +adapters strictly require a system supporting PCI 2.2 or greater. +Check the board's PCI version before purchasing the card as it is likely these +adapters will not work in systems based on older revisions of the PCI +specification. diff --git a/static/freebsd/man4/random.4 b/static/freebsd/man4/random.4 new file mode 100644 index 00000000..457f49f3 --- /dev/null +++ b/static/freebsd/man4/random.4 @@ -0,0 +1,303 @@ +.\" Copyright (c) 2001-2015 Mark R V Murray. 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 August 28, 2025 +.Dt RANDOM 4 +.Os +.Sh NAME +.Nm random +.Nd the entropy device +.Sh SYNOPSIS +.Cd "options RANDOM_LOADABLE" +.Cd "options RANDOM_ENABLE_ETHER" +.Cd "options RANDOM_ENABLE_TPM" +.Cd "options RANDOM_ENABLE_UMA" +.Sh DESCRIPTION +The +.Nm +device returns an endless supply of random bytes when read. +.Pp +The generator will start in an +.Em unseeded +state, and will block reads until it is seeded for the first time. +.Pp +To provide prompt access to the random device at boot time, +.Fx +automatically saves some entropy data in +.Pa /boot/entropy +for the +.Xr loader 8 +to provide to the kernel. +Additional entropy is regularly saved in +.Pa /var/db/entropy . +This saved entropy is sufficient to unblock the random device on devices with +writeable media. +.Pp +Embedded applications without writable media must determine their own scheme +for re-seeding the random device on boot, or accept that the device +will remain unseeded and block reads indefinitely. +See +.Sx SECURITY CONSIDERATIONS +for more detail. +.Pp +In addition to +.Xr read 2 , +the direct output of the abstract kernel entropy device can be read with +.Xr getrandom 2 , +.Xr getentropy 3 , +or the +.Xr sysctl 8 +pseudo-variable +.Va kern.arandom . +.Pp +To see the current settings of the software +.Nm +device, use the command line: +.Pp +.Dl "sysctl kern.random" +.Pp +which results in something like: +.Bd -literal -offset indent +kern.random.block_seeded_status: 0 +kern.random.fortuna.minpoolsize: 64 +kern.random.harvest.mask_symbolic: ENABLEDSOURCE,[DISABLEDSOURCE],...,CACHED +kern.random.harvest.mask_bin: 00000010000000111011111 +kern.random.harvest.mask: 66015 +kern.random.use_chacha20_cipher: 0 +kern.random.random_sources: 'Intel Secure Key RNG' +kern.random.initial_seeding.bypass_before_seeding: 1 +kern.random.initial_seeding.read_random_bypassed_before_seeding: 0 +kern.random.initial_seeding.arc4random_bypassed_before_seeding: 0 +kern.random.initial_seeding.disable_bypass_warnings: 0 +.Ed +.Pp +Other than +.Va kern.random.block_seeded_status , +.Va kern.random.fortuna.minpoolsize , +and +.Va kern.random.harvest.mask , +all settings are read-only via +.Xr sysctl 8 . +.Pp +The +.Pa kern.random.fortuna.minpoolsize +sysctl is used +to set the seed threshold. +A smaller number gives a faster seed, +but a less secure one. +In practice, +values between 64 and 256 +are acceptable. +.Pp +The +.Va kern.random.harvest.mask +bitmask is used to select +the possible entropy sources. +A 0 (zero) value means +the corresponding source +is not considered +as an entropy source. +Set the bit to 1 (one) +if you wish to use +that source. +The +.Va kern.random.harvest.mask_bin +and +.Va kern.random.harvest.mask_symbolic +sysctls +can be used to confirm +settings in a human readable form. +Disabled items +in the latter +are listed in square brackets. +See +.Xr random_harvest 9 +for more on the harvesting of entropy. +.Pp +The +.Va kern.random.nist_healthtest_enabled +tunable can be used to enable the entropy source health tests outlined +in section 4 of NIST Special Publication 800-90B. +When enabled, all entropy sources will be subject to the repetition +count and adaptive proportion tests described in that document. +If one of the tests fails, the source will be disabled, i.e., all +subsequent entropy samples from that source will be discarded. +The implementation performs startup testing, during which entropy +sources are discarded. +.Sh FILES +.Bl -tag -width ".Pa /dev/urandom" +.It Pa /dev/random +.It Pa /dev/urandom +.El +.Sh DIAGNOSTICS +The following tunables are related to initial seeding of the +.Nm +device: +.Bl -tag -width 4 +.It Va kern.random.initial_seeding.bypass_before_seeding +Defaults to 1 (on). +When set, the system will bypass the +.Nm +device prior to initial seeding. +On is +.Em unsafe , +but provides availability on many systems that lack early sources +of entropy, or cannot load +.Pa /boot/entropy +sufficiently early in boot for +.Nm +consumers. +When unset (0), the system will block +.Xr read_random 9 +and +.Xr arc4random 9 +requests if and until the +.Nm +device is initially seeded. +.It Va kern.random.initial_seeding.disable_bypass_warnings +Defaults to 0 (off). +When set non-zero, disables warnings in dmesg when the +.Nm +device is bypassed. +.El +.Pp +The following read-only +.Xr sysctl 8 +variables allow programmatic diagnostic of whether +.Nm +device bypass occurred during boot. +If they are set (non-zero), the specific functional unit bypassed the strong +.Nm +device output and either produced no output +.Xr ( read_random 9 ) +or seeded itself with minimal, non-cryptographic entropy +.Xr ( arc4random 9 ) . +.Bl -bullet +.It +.Va kern.random.initial_seeding.read_random_bypassed_before_seeding +.It +.Va kern.random.initial_seeding.arc4random_bypassed_before_seeding +.El +.Sh SEE ALSO +.Xr getrandom 2 , +.Xr arc4random 3 , +.Xr getentropy 3 , +.Xr random 3 , +.Xr sysctl 8 , +.Xr random 9 +.Rs +.%A Ferguson +.%A Schneier +.%A Kohno +.%B Cryptography Engineering +.%I Wiley +.%O ISBN 978-0-470-47424-2 +.Re +.Sh HISTORY +A +.Nm +device appeared in +.Fx 2.2 . +The implementation was changed to the +.Em Yarrow algorithm in +.Fx 5.0 . +In +.Fx 11.0 , +the Fortuna algorithm was introduced as the default. +In +.Fx 12.0 , +Yarrow was removed entirely. +.Sh AUTHORS +.An -nosplit +The current +.Nm +code was authored by +.An Mark R V Murray , +with significant contributions from many people. +.Pp +The +.Em Fortuna +algorithm was designed by +.An Niels Ferguson , +.An Bruce Schneier , +and +.An Tadayoshi Kohno . +.Sh CAVEATS +When +.Cd "options RANDOM_LOADABLE" +is enabled, +the +.Pa /dev/random +device is not created +until an "algorithm module" +is loaded. +The only module built by default is +.Em random_fortuna . +Loadable random modules +are less efficient +than their compiled-in equivalents. +This is because some functions +must be locked against +load and unload events, +and also must be indirect calls +to allow for removal. +.Pp +When +.Cd "options RANDOM_ENABLE_UMA" +is enabled, +the +.Pa /dev/random +device will obtain entropy +from the zone allocator. +This is a very high rate source with significant performance impact. +Therefore, it is disabled by default. +.Pp +When +.Cd "options RANDOM_ENABLE_ETHER" +is enabled, the +.Nm +device will obtain entropy from +.Vt mbuf +structures passing through the network stack. +This source is both extremely expensive and a poor source of entropy, so it is +disabled by default. +.Sh SECURITY CONSIDERATIONS +The initial seeding +of random number generators +is a bootstrapping problem +that needs very careful attention. +When writable media is available, the +.Em Fortuna +paper describes a robust system for rapidly reseeding the device. +.Pp +In some embedded cases, it may be difficult to find enough randomness to seed a +random number generator until a system is fully operational. +In these cases, is the responsibility of the system architect to ensure that +blocking is acceptable, or that the random device is seeded. +(This advice does not apply to typical consumer systems.) +.Pp +To emulate embedded systems, developers may set the +.Va kern.random.block_seeded_status +tunable to 1 to verify boot does not require early availability of the +.Nm +device. diff --git a/static/freebsd/man4/rccgpio.4 b/static/freebsd/man4/rccgpio.4 new file mode 100644 index 00000000..f790b003 --- /dev/null +++ b/static/freebsd/man4/rccgpio.4 @@ -0,0 +1,61 @@ +.\" Copyright (c) 2015, Rubicon Communications, LLC (Netgate) +.\" 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 August 18, 2015 +.Dt RCCGPIO 4 +.Os +.Sh NAME +.Nm rccgpio +.Nd ADI Engineering RCC-VE and RCC-DFF/DFFv2 GPIO controller +.Sh SYNOPSIS +.Cd "device rccgpio" +.Cd "device gpio" +.Cd "device gpioled" +.Sh DESCRIPTION +The +.Nm +provides a simple interface to read the reset switch state and control the +status LEDs. +.Pp +The software controlled reset switch is known to be available on boards from +Netgate. +Most people get a button that is a hardware reset. +.Pp +All the GPIO pins are locked in their intended setup to disallow any harmful +settings (the ones that can cause short circuits). +.Sh SEE ALSO +.Xr gpio 3 , +.Xr gpio 4 , +.Xr gpioled 4 , +.Xr gpioctl 8 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 11.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Luiz Otavio O Souza Aq Mt loos@FreeBSD.org . diff --git a/static/freebsd/man4/rctl.4 b/static/freebsd/man4/rctl.4 new file mode 100644 index 00000000..12f0a837 --- /dev/null +++ b/static/freebsd/man4/rctl.4 @@ -0,0 +1,71 @@ +.\" Copyright (c) 2017 Edward Tomasz Napierala +.\" +.\" 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 May 28, 2017 +.Dt RCTL 4 +.Os +.Sh NAME +.Nm rctl +.Nd resource limits +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in the +kernel configuration file: +.Bd -ragged -offset indent +.Cd "options RACCT" +.Cd "options RCTL" +.Ed +.Sh DESCRIPTION +The +.Nm +subsystem provides a flexible resource limits mechanism, +controlled by a set of rules that can be added or removed at runtime +using the +.Xr rctl 8 +management utility. +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt, or +.Xr loader.conf 5 . +.Bl -tag -width indent +.It Va kern.racct.enable: No 1 +Enable +.Nm . +This defaults to 1, unless +.Cd "options RACCT_DEFAULT_TO_DISABLED" +is set in the kernel configuration file. +.El +.Sh SEE ALSO +.Xr rctl.conf 5 , +.Xr rctl 8 +.Sh HISTORY +The +.Nm +subsystem first appeared in +.Fx 9.0 . +.Sh AUTHORS +The +.Nm +subsystem was developed by +.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org +under sponsorship from the FreeBSD Foundation. diff --git a/static/freebsd/man4/re.4 b/static/freebsd/man4/re.4 new file mode 100644 index 00000000..1a255ccf --- /dev/null +++ b/static/freebsd/man4/re.4 @@ -0,0 +1,293 @@ +.\" Copyright (c) 2003 +.\" Bill Paul . 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 Bill Paul. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Bill Paul 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 Bill Paul OR THE VOICES IN HIS HEAD +.\" 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 November 7, 2022 +.Dt RE 4 +.Os +.Sh NAME +.Nm re +.Nd "Realtek 8139C+/8169/816xS/811xS/8168/810xE/8111 PCI/PCIe Ethernet adapter driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device re" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_re_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for various NICs based on the Realtek RTL8139C+, +RTL8169, RTL816xS, RTL811xS, RTL8168, RTL810xE and RTL8111 PCI and +PCIe Ethernet controllers. +.Pp +NICs based on the 8139C+ and 810xE are capable of 10 and 100Mbps speeds +over CAT5 cable. +NICs based on the 8169, 816xS, 811xS, 8168 and 8111 are capable of 10, 100 +and 1000Mbps operation. +.Pp +All NICs supported by the +.Nm +driver have TCP/IP checksum offload and hardware VLAN tagging/insertion +features, and use a descriptor-based DMA mechanism. +They are also +capable of TCP large send (TCP segmentation offload). +.Pp +The 8139C+ is a single-chip solution combining both a 10/100 MAC and PHY. +The 8169 is a 10/100/1000 MAC only, requiring a GMII or TBI external PHY. +The 816xS, 811xS, 8168 and 8111 are single-chip devices containing both a +10/100/1000 MAC and 10/100/1000 copper PHY. +Standalone 10/100/1000 cards are available +in both 32-bit PCI and 64-bit PCI models. +The 8110S is designed for +embedded LAN-on-motherboard applications. +.Pp +The 8169, 8169S and 8110S also support jumbo frames, which can be configured +via the interface MTU setting. +The MTU is limited to 7422, since the chip cannot transmit larger frames. +Selecting an MTU larger than 1500 bytes with the +.Xr ifconfig 8 +utility configures the adapter to receive and transmit jumbo frames. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width ".Cm 10baseT/UTP" +.It Cm autoselect +Enable autoselection of the media type and options. +The user can manually override +the autoselected mode by adding media options to +.Xr rc.conf 5 . +.It Cm 10baseT/UTP +Set 10Mbps operation. +The +.Xr ifconfig 8 +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 100baseTX +Set 100Mbps (Fast Ethernet) operation. +The +.Xr ifconfig 8 +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 1000baseTX +Set 1000baseTX operation over twisted pair. +The Realtek gigE chips support 1000Mbps in +.Cm full-duplex +mode only. +.\" .It Cm 1000baseSX +.\" Set 1000Mbps (Gigabit Ethernet) operation. +.\" Both +.\" .Cm full-duplex +.\" and +.\" .Cm half-duplex +.\" modes are supported. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width ".Cm full-duplex" +.It Cm full-duplex +Force full duplex operation. +.It Cm half-duplex +Force half duplex operation. +.El +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports Realtek RTL8139C+, RTL8169, RTL816xS, RTL811xS, RTL8168, +RTL810xE and RTL8111 based Fast Ethernet and Gigabit Ethernet adapters including: +.Pp +.Bl -bullet -compact +.It +Alloy Computer Products EtherGOLD 1439E 10/100 (8139C+) +.It +Compaq Evo N1015v Integrated Ethernet (8139C+) +.It +Corega CG-LAPCIGT Gigabit Ethernet (8169S) +.It +D-Link DGE-528(T) Gigabit Ethernet (8169S) +.It +D-Link DGE-530(T) Gigabit Ethernet (8169S) +.It +Killer E2600 Gigabit Ethernet (8168) +.It +Gigabyte 7N400 Pro2 Integrated Gigabit Ethernet (8110S) +.It +LevelOne GNC-0105T (8169S) +.It +LinkSys EG1032 (32-bit PCI) +.It +PLANEX COMMUNICATIONS Inc.\& GN-1200TC (8169S) +.It +TP-Link TG-3468 v2 Gigabit Ethernet (8168) +.It +USRobotics USR997902 Gigabit Ethernet (8169S) +.It +Xterasys XN-152 10/100/1000 NIC (8169) +.El +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width "xxxxxx" +.It Va hw.re.intr_filter +This tunable makes driver use interrupt filter handler on +controllers that support MSI/MSI-X capability. +If MSI/MSI-X is disabled by administrator this tunable has no +effect and driver will use interrupt filter handler. +The default value is 0 to use interrupt thread handler. +.It Va hw.re.msi_disable +This tunable disables MSI support on the Ethernet hardware. +The default value is 0. +.It Va hw.re.msix_disable +This tunable disables MSI-X support on the Ethernet hardware. +The default value is 0. +.It Va hw.re.prefer_iomap +This tunable controls which register mapping should be used on the +specified device. +A non-zero value enables I/O space register mapping. +The default value is 0 to use memory space register mapping. +.El +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width "xxxxxx" +.It Va dev.re.%d.int_rx_mod +Maximum amount of time to delay receive interrupt processing in +units of 1us. +The accepted range is 0 to 65, the default is 65(65us). +Value 0 completely disables the interrupt moderation. +The interface need to be brought down and up again before a change +takes effect. +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "re%d: couldn't map memory" +A fatal initialization error has occurred. +.It "re%d: couldn't map ports" +A fatal initialization error has occurred. +.It "re%d: couldn't map interrupt" +A fatal initialization error has occurred. +.It "re%d: no memory for softc struct!" +The driver failed to allocate memory for per-device instance information +during initialization. +.It "re%d: failed to enable memory mapping!" +The driver failed to initialize PCI shared memory mapping. +This might +happen if the card is not in a bus-master slot. +.It "re%d: no memory for jumbo buffers!" +The driver failed to allocate memory for jumbo frames during +initialization. +.It "re%d: watchdog timeout" +The device has stopped responding to the network, or there is a problem with +the network connection (cable). +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr polling 4 , +.Xr rge 4 , +.Xr rgephy 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Rs +.%T Realtek Semiconductor RTL8139C+, RTL8169, RTL8169S and RTL8110S datasheets +.%U https://www.realtek.com +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 5.2 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Bill Paul Aq Mt wpaul@windriver.com . +.Sh BUGS +The Xterasys XN-152 32-bit PCI NIC, which uses the RTL8169 MAC and +Marvell 88E1000 PHY, has a defect that causes DMA corruption +if the board is plugged into a 64-bit PCI slot. +The defect +lies in the board design, not the chip itself: the PCI REQ64# and ACK64# +lines should be pulled high, but they are not. +The result is that the +8169 chip is tricked into performing 64-bit DMA transfers even though +a 64-bit data path between the NIC and the bus does not actually exist. +.Pp +Unfortunately, it is not possible to correct this problem in software, +however it is possible to detect it. +When the +.Nm +driver is loaded, it will run a diagnostic routine designed to +validate DMA operation by placing the chip in digital loopback mode +and initiating a packet transmission. +If the card functions properly, +the transmitted data will +be echoed back unmodified. +If the echoed data is corrupt, the driver +will print an error message on the console and abort the device attach. +The +user should ensure the NIC is installed in a 32-bit PCI slot to +avoid this problem. +.Pp +The Realtek 8169, 8169S and 8110S chips appear to only be capable of +transmitting jumbo frames up to 7.5K in size. +.Pp +If this driver is causing problems then an updated driver from +the vendor can be found in ports under net/realtek-re-kmod. diff --git a/static/freebsd/man4/rge.4 b/static/freebsd/man4/rge.4 new file mode 100644 index 00000000..24c42f91 --- /dev/null +++ b/static/freebsd/man4/rge.4 @@ -0,0 +1,195 @@ +.\" +.\" Copyright (c) 2025 Adrian Chadd +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd April 5, 2026 +.Dt RGE 4 +.Os +.Sh NAME +.Nm rge +.Nd RealTek RTL8125/RTL8126/RTL8127/Killer E3000 PCIe Ethernet adapter driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device rge" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_rge_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for various NICs based on the RealTek RTL8125, +RTL8126 and RTL8127 PCIe Ethernet controllers. +.Pp +All of the NICs supported by this driver support 10, 100 and 1000Mbit +over CAT5 cable. +NICs based on the RTL8125 additionally support 2.5Gbit over CAT6 cable. +NICs based on the RTL8126 additionally support 2.5Gbit and 5Gbit over CAT6 +cable. +NICs based on the RTL8127 additionally support 2.5Gbit, 5Gbit and 10Gbit +over CAT6 cable. +.Pp +All NICs supported by the +.Nm +driver have TCP/IP checksum offload, hardware VLAN tagging/insertion +features, Wake On Lan (WOL), and use a descriptor-based DMA mechanism. +They are also +capable of TCP large send (TCP segmentation offload). +.Pp +The RTL8125, RTL8126 and RTL8127 devices are single-chip solutions combining +both a MAC and PHY. +The +.Nm +driver manages the PHY directly rather than using the +.Xr miibus 4 +interface. +Standalone cards are available in 1x PCIe models. +.Pp +The RTL8125, RTL8126 and RTL8127 also support jumbo frames, which can be +configured via the interface MTU setting. +The MTU is limited to 9126. +Selecting an MTU larger than 1500 bytes with the +.Xr ifconfig 8 +utility configures the adapter to receive and transmit jumbo frames. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width "10baseT/UTP" +.It Cm autoselect +Enable autoselection of the media type and options. +The user can manually override +the autoselected mode by adding media options to +.Xr rc.conf 5 . +.It Cm 10baseT/UTP +Set 10Mbps operation. +The +.Xr ifconfig 8 +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 100baseTX +Set 100Mbps (Fast Ethernet) operation. +The +.Xr ifconfig 8 +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 1000baseT +Set 1000baseT operation over twisted pair. +The RealTek gigE chips support 1000Mbps in +.Cm full-duplex +mode only. +.It Cm 2500Base-T +Set 2500Base-T operation over twisted pair. +The RealTek devices support 2.5Gbit in +.Cm full-duplex +mode only. +.It Cm 5000Base-T +Set 5000Base-T operation over twisted pair. +The RealTek devices support 5Gbit in +.Cm full-duplex +mode only. +.It Cm 10Gbase-T +Set 10Gbase-T operation over twisted pair. +The RealTek devices support 10Gbit in +.Cm full-duplex +mode only. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width "full-duplex" +.It Cm full-duplex +Force full duplex operation. +.It Cm half-duplex +Force half duplex operation. +.El +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports the following PCIe Ethernet adapters: +.Pp +.Bl -bullet -compact +.It +RealTek RTL8125 (up to 2.5 Gbps) +.It +RealTek RTL8126 (up to 5 Gbps) +.It +RealTek RTL8127 (up to 10 Gbps) +.It +Killer E3000 (up to 2.5 Gbps) +.El +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width "xxxxxx" +.It Va dev.rge.%d.debug +Configure runtime debug output. This is a 32 bit bitmask. +.It Va dev.rge.%d.rx_process_limit +Maximum number of RX packets to process per interrupt. +The default value is 16. +Increasing this value may improve throughput on high-speed links at the +cost of increased interrupt latency. +.It Va dev.rge.%d.disable_aspm +Disable PCIe Active State Power Management (ASPM) and Extended +Configuration Power Management (ECPM). +The default value is 0 (leave ASPM enabled). +Setting this to 1 reduces latency at the cost of increased power +consumption. +This tunable can only be set in +.Xr loader.conf 5 +and requires a reboot to take effect. +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "rge%d: watchdog timeout" +The device has stopped responding to the network, or there is a problem with +the network connection (cable). +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr polling 4 , +.Xr re 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Rs +.%U https://www.realtek.com/ +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 16.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Kevin Lo Aq Mt kevlo@openbsd.org +and ported to FreeBSD by +.An Adrian Chadd Aq Mt adrian@freebsd.org . diff --git a/static/freebsd/man4/rgephy.4 b/static/freebsd/man4/rgephy.4 new file mode 100644 index 00000000..2e3048a3 --- /dev/null +++ b/static/freebsd/man4/rgephy.4 @@ -0,0 +1,93 @@ +.\" +.\" Copyright (c) 2011 Marius Strobl +.\" 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 January 16, 2011 +.Dt RGEPHY 4 +.Os +.Sh NAME +.Nm rgephy +.Nd Realtek RTL8168/8169/8110/8211 series 10/100/1000 Gigabit Ethernet PHY driver +.Sh SYNOPSIS +To compile all available PHY drivers into the kernel, +place the following line in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Ed +.Pp +Alternatively, to selectively compile this driver into the kernel, +place the following lines in your kernel configuration file instead: +.Bd -ragged -offset indent +.Cd "device mii" +.Cd "device rgephy" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports the Realtek RTL8168, RTL8169, RTL8110 and RTL8211 series +integrated 10/100/1000 Gigabit Ethernet PHYs. +.Pp +In order to get a list of media types and options supported by a specific +instance of the +.Nm +driver, run +.Li ifconfig -m +on the instance of its parent MAC driver. +.Pp +Additionally, +the +.Nm +driver supports the following special media option: +.Bl -tag -width ".Cm flag0" +.It Cm flag0 +When manually setting media type and options via +.Xr ifconfig 8 , +the +.Nm +driver by default also triggers an autonegotiation advertising the selected +media. +This is done in order to work around hardware issues in certain scenarios. +It is believed that this behavior does not cause harm in general but in fact +can have an adverse effect in edge cases. +In order to manually set the media type and options without also triggering +an autonegotiation, +the +.Nm +driver allows to turn this behavior off via the +.Cm flag0 +media option. +.El +.Pp +Note that this special media option will not show up in the output of +.Xr ifconfig 8 , +even when set. +.Sh EXAMPLES +Manually set 100BASE-TX full-duplex without also triggering an +autonegotiation: +.Pp +.Dl "ifconfig re0 media 100baseTX mediaopt full-duplex,flag0" +.Sh SEE ALSO +.Xr intro 4 , +.Xr miibus 4 , +.Xr ifconfig 8 diff --git a/static/freebsd/man4/rights.4 b/static/freebsd/man4/rights.4 new file mode 100644 index 00000000..396222a8 --- /dev/null +++ b/static/freebsd/man4/rights.4 @@ -0,0 +1,751 @@ +.\" +.\" Copyright (c) 2008-2010 Robert N. M. Watson +.\" Copyright (c) 2012-2013 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" This software was developed at the University of Cambridge Computer +.\" Laboratory with support from a grant from Google, Inc. +.\" +.\" Portions of this documentation were written by Pawel Jakub Dawidek +.\" under sponsorship from the FreeBSD Foundation. +.\" +.\" 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 May 22, 2025 +.Dt RIGHTS 4 +.Os +.Sh NAME +.Nm Capability rights +.Nd Capsicum capability rights for file descriptors +.Sh DESCRIPTION +When a file descriptor is created by a function such as +.Xr fhopen 2 , +.Xr kqueue 2 , +.Xr mq_open 2 , +.Xr open 2 , +.Xr pdfork 2 , +.Xr pipe 2 , +.Xr shm_open 2 , +.Xr socket 2 +or +.Xr socketpair 2 , +it is assigned all capability rights; for +.Xr accept 2 , +.Xr accept4 2 +or +.Xr openat 2 , +it inherits capability rights from the "parent" file descriptor. +Those rights can be reduced (but never expanded) by using the +.Xr cap_rights_limit 2 , +.Xr cap_fcntls_limit 2 and +.Xr cap_ioctls_limit 2 +system calls. +Once capability rights are reduced, operations on the file descriptor will be +limited to those permitted by rights. +.Pp +The complete list of capability rights is provided below. +The +.Vt cap_rights_t +type is used to store list of capability rights. +The +.Xr cap_rights_init 3 +family of functions should be used to manage the structure. +.Sh RIGHTS +Note that rights are not simple bitmasks (and cannot be bitwise-ORed together). +See +.Xr cap_rights_init 3 +for details. +.Pp +The following rights are available: +.Bl -tag -width CAP_RENAMEAT_SOURCE +.It Dv CAP_ACCEPT +Permit +.Xr accept 2 +and +.Xr accept4 2 . +.It Dv CAP_ACL_CHECK +Permit +.Xr acl_valid_fd_np 3 . +.It Dv CAP_ACL_DELETE +Permit +.Xr acl_delete_fd_np 3 . +.It Dv CAP_ACL_GET +Permit +.Xr acl_get_fd 3 +and +.Xr acl_get_fd_np 3 . +.It Dv CAP_ACL_SET +Permit +.Xr acl_set_fd 3 +and +.Xr acl_set_fd_np 3 . +.It Dv CAP_BIND +When not in capabilities mode, permit +.Xr bind 2 +and +.Xr bindat 2 +with special value +.Dv AT_FDCWD +in the +.Fa fd +parameter. +Note that sockets can also become bound implicitly as a result of +.Xr connect 2 +or +.Xr send 2 , +and that socket options set with +.Xr setsockopt 2 +may also affect binding behavior. +.It Dv CAP_BINDAT +Permit +.Xr bindat 2 . +This right has to be present on the directory descriptor. +This right includes the +.Dv CAP_LOOKUP +right. +.It Dv CAP_CHFLAGSAT +An alias to +.Dv CAP_FCHFLAGS +and +.Dv CAP_LOOKUP . +.It Dv CAP_CONNECT +When not in capabilities mode, permit +.Xr connect 2 +and +.Xr connectat 2 +with special value +.Dv AT_FDCWD +in the +.Fa fd +parameter. +This right is also required for +.Xr sendto 2 +with a non-NULL destination address. +.It Dv CAP_CONNECTAT +Permit +.Xr connectat 2 . +This right has to be present on the directory descriptor. +This right includes the +.Dv CAP_LOOKUP +right. +.It Dv CAP_CREATE +Permit +.Xr openat 2 +with the +.Dv O_CREAT +flag. +.It Dv CAP_EVENT +Permit +.Xr select 2 , +.Xr poll 2 , +and +.Xr kevent 2 +to be used in monitoring the file descriptor for events. +.It Dv CAP_EXTATTR_DELETE +Permit +.Xr extattr_delete_fd 2 . +.It Dv CAP_EXTATTR_GET +Permit +.Xr extattr_get_fd 2 . +.It Dv CAP_EXTATTR_LIST +Permit +.Xr extattr_list_fd 2 . +.It Dv CAP_EXTATTR_SET +Permit +.Xr extattr_set_fd 2 . +.It Dv CAP_FCHDIR +Permit +.Xr fchdir 2 . +.It Dv CAP_FCHFLAGS +Permit +.Xr fchflags 2 +and +.Xr chflagsat 2 +if the +.Dv CAP_LOOKUP +right is also present. +.It Dv CAP_FCHMOD +Permit +.Xr fchmod 2 +and +.Xr fchmodat 2 +if the +.Dv CAP_LOOKUP +right is also present. +.It Dv CAP_FCHMODAT +An alias to +.Dv CAP_FCHMOD +and +.Dv CAP_LOOKUP . +.It Dv CAP_FCHOWN +Permit +.Xr fchown 2 +and +.Xr fchownat 2 +if the +.Dv CAP_LOOKUP +right is also present. +.It Dv CAP_FCHOWNAT +An alias to +.Dv CAP_FCHOWN +and +.Dv CAP_LOOKUP . +.It Dv CAP_FCHROOT +Permit +.Xr fchroot 2 . +.It Dv CAP_FCNTL +Permit +.Xr fcntl 2 . +Note that only the +.Dv F_GETFL , +.Dv F_SETFL , +.Dv F_GETOWN +and +.Dv F_SETOWN +commands require this capability right. +Also note that the list of permitted commands can be further limited with the +.Xr cap_fcntls_limit 2 +system call. +.It Dv CAP_FEXECVE +Permit +.Xr fexecve 2 +and +.Xr openat 2 +with the +.Dv O_EXEC +flag; +.Dv CAP_READ +is also required. +.It Dv CAP_FLOCK +Permit +.Xr flock 2 , +.Xr fcntl 2 +(with +.Dv F_GETLK , +.Dv F_SETLK , +.Dv F_SETLKW +or +.Dv F_SETLK_REMOTE +flag) and +.Xr openat 2 +(with +.Dv O_EXLOCK +or +.Dv O_SHLOCK +flag). +.It Dv CAP_FPATHCONF +Permit +.Xr fpathconf 2 . +.It Dv CAP_FSCK +Permit UFS background-fsck operations on the descriptor. +.It Dv CAP_FSTAT +Permit +.Xr fstat 2 +and +.Xr fstatat 2 +if the +.Dv CAP_LOOKUP +right is also present. +.It Dv CAP_FSTATAT +An alias to +.Dv CAP_FSTAT +and +.Dv CAP_LOOKUP . +.It Dv CAP_FSTATFS +Permit +.Xr fstatfs 2 . +.It Dv CAP_FSYNC +Permit +.Xr aio_fsync 2 , +.Xr fdatasync 2 , +.Xr fsync 2 +and +.Xr openat 2 +with +.Dv O_DSYNC , +.Dv O_FSYNC , +or +.Dv O_SYNC +flag. +.It Dv CAP_FTRUNCATE +Permit +.Xr ftruncate 2 +and +.Xr openat 2 +with the +.Dv O_TRUNC +flag. +.It Dv CAP_FUTIMES +Permit +.Xr futimens 2 +and +.Xr futimes 2 , +and permit +.Xr futimesat 2 +and +.Xr utimensat 2 +if the +.Dv CAP_LOOKUP +right is also present. +.It Dv CAP_FUTIMESAT +An alias to +.Dv CAP_FUTIMES +and +.Dv CAP_LOOKUP . +.It Dv CAP_GETPEERNAME +Permit +.Xr getpeername 2 . +.It Dv CAP_GETSOCKNAME +Permit +.Xr getsockname 2 . +.It Dv CAP_GETSOCKOPT +Permit +.Xr getsockopt 2 . +.It Dv CAP_INOTIFY_ADD +Permit +.Xr inotify_add_watch 2 +and +.Xr inotify_add_watch_at 2 . +.It Dv CAP_INOTIFY_RM +Permit +.Xr inotify_rm_watch 2 . +.It Dv CAP_IOCTL +Permit +.Xr ioctl 2 . +Be aware that this system call has enormous scope, including potentially +global scope for some objects. +The list of permitted ioctl commands can be further limited with the +.Xr cap_ioctls_limit 2 +system call. +.It Dv CAP_KQUEUE +An alias to +.Dv CAP_KQUEUE_CHANGE +and +.Dv CAP_KQUEUE_EVENT . +.It Dv CAP_KQUEUE_CHANGE +Permit +.Xr kevent 2 +on a +.Xr kqueue 2 +descriptor that modifies list of monitored events (the +.Fa changelist +argument is non-NULL). +.It Dv CAP_KQUEUE_EVENT +Permit +.Xr kevent 2 +on a +.Xr kqueue 2 +descriptor that monitors events (the +.Fa eventlist +argument is non-NULL). +.Dv CAP_EVENT +is also required on file descriptors that will be monitored using +.Xr kevent 2 . +.It Dv CAP_LINKAT_SOURCE +Permit +.Xr linkat 2 +on the source directory descriptor. +This right includes the +.Dv CAP_LOOKUP +right. +.Pp +Warning: +.Dv CAP_LINKAT_SOURCE +makes it possible to link files in a directory for which file +descriptors exist that have additional rights. +For example, +a file stored in a directory that does not allow +.Dv CAP_READ +may be linked in another directory that does allow +.Dv CAP_READ , +thereby granting read access to a file that is otherwise unreadable. +.It Dv CAP_LINKAT_TARGET +Permit +.Xr linkat 2 +on the target directory descriptor. +This right includes the +.Dv CAP_LOOKUP +right. +.It Dv CAP_LISTEN +Permit +.Xr listen 2 ; +not much use (generally) without +.Dv CAP_BIND . +.It Dv CAP_LOOKUP +Permit the file descriptor to be used as a starting directory for calls such as +.Xr linkat 2 , +.Xr openat 2 , +and +.Xr unlinkat 2 . +.It Dv CAP_MAC_GET +Permit +.Xr mac_get_fd 3 . +.It Dv CAP_MAC_SET +Permit +.Xr mac_set_fd 3 . +.It Dv CAP_MKDIRAT +Permit +.Xr mkdirat 2 . +This right includes the +.Dv CAP_LOOKUP +right. +.It Dv CAP_MKFIFOAT +Permit +.Xr mkfifoat 2 . +This right includes the +.Dv CAP_LOOKUP +right. +.It Dv CAP_MKNODAT +Permit +.Xr mknodat 2 . +This right includes the +.Dv CAP_LOOKUP +right. +.It Dv CAP_MMAP +Permit +.Xr mmap 2 +with the +.Dv PROT_NONE +protection. +.It Dv CAP_MMAP_R +Permit +.Xr mmap 2 +with the +.Dv PROT_READ +protection. +This right includes the +.Dv CAP_READ +and +.Dv CAP_SEEK +rights. +.It Dv CAP_MMAP_RW +An alias to +.Dv CAP_MMAP_R +and +.Dv CAP_MMAP_W . +.It Dv CAP_MMAP_RWX +An alias to +.Dv CAP_MMAP_R , +.Dv CAP_MMAP_W +and +.Dv CAP_MMAP_X . +.It Dv CAP_MMAP_RX +An alias to +.Dv CAP_MMAP_R +and +.Dv CAP_MMAP_X . +.It Dv CAP_MMAP_W +Permit +.Xr mmap 2 +with the +.Dv PROT_WRITE +protection. +This right includes the +.Dv CAP_WRITE +and +.Dv CAP_SEEK +rights. +.It Dv CAP_MMAP_WX +An alias to +.Dv CAP_MMAP_W +and +.Dv CAP_MMAP_X . +.It Dv CAP_MMAP_X +Permit +.Xr mmap 2 +with the +.Dv PROT_EXEC +protection. +This right includes the +.Dv CAP_SEEK +right. +.It Dv CAP_PDGETPID +Permit +.Xr pdgetpid 2 . +.It Dv CAP_PDKILL +Permit +.Xr pdkill 2 . +.It Dv CAP_PDWAIT +Permit +.Xr pdwait 2 . +.It Dv CAP_PEELOFF +Permit +.Xr sctp_peeloff 2 . +.It Dv CAP_PREAD +An alias to +.Dv CAP_READ +and +.Dv CAP_SEEK . +.It Dv CAP_PWRITE +An alias to +.Dv CAP_SEEK +and +.Dv CAP_WRITE . +.It Dv CAP_READ +Permit +.Xr aio_read 2 +.Dv ( CAP_SEEK +is also required), +.Xr openat 2 +with the +.Dv O_RDONLY flag, +.Xr read 2 , +.Xr readv 2 , +.Xr recv 2 , +.Xr recvfrom 2 , +.Xr recvmsg 2 , +.Xr pread 2 +.Dv ( CAP_SEEK +is also required), +.Xr preadv 2 +.Dv ( CAP_SEEK +is also required), +.Xr getdents 2 , +.Xr getdirentries 2 , +and related system calls. +.It Dv CAP_RECV +An alias to +.Dv CAP_READ . +.It Dv CAP_RENAMEAT_SOURCE +Permit +.Xr renameat 2 +on the source directory descriptor. +This right includes the +.Dv CAP_LOOKUP +right. +.Pp +Warning: +.Dv CAP_RENAMEAT_SOURCE +makes it possible to move files to a directory for which file +descriptors exist that have additional rights. +For example, +a file stored in a directory that does not allow +.Dv CAP_READ +may be moved to another directory that does allow +.Dv CAP_READ , +thereby granting read access to a file that is otherwise unreadable. +.It Dv CAP_RENAMEAT_TARGET +Permit +.Xr renameat 2 +on the target directory descriptor. +This right includes the +.Dv CAP_LOOKUP +right. +.It Dv CAP_SEEK +Permit operations that seek on the file descriptor, such as +.Xr lseek 2 , +but also required for I/O system calls that can read or write at any position +in the file, such as +.Xr pread 2 +and +.Xr pwrite 2 . +.It Dv CAP_SEM_GETVALUE +Permit +.Xr sem_getvalue 3 . +.It Dv CAP_SEM_POST +Permit +.Xr sem_post 3 . +.It Dv CAP_SEM_WAIT +Permit +.Xr sem_wait 3 +and +.Xr sem_trywait 3 . +.It Dv CAP_SEND +An alias to +.Dv CAP_WRITE . +.It Dv CAP_SETSOCKOPT +Permit +.Xr setsockopt 2 ; +this controls various aspects of socket behavior and may affect binding, +connecting, and other behaviors with global scope. +.It Dv CAP_SHUTDOWN +Permit explicit +.Xr shutdown 2 ; +closing the socket will also generally shut down any connections on it. +.It Dv CAP_SYMLINKAT +Permit +.Xr symlinkat 2 . +This right includes the +.Dv CAP_LOOKUP +right. +.It Dv CAP_TTYHOOK +Allow configuration of TTY hooks, such as +.Xr snp 4 , +on the file descriptor. +.It Dv CAP_UNLINKAT +Permit +.Xr unlinkat 2 +and +.Xr renameat 2 . +This right is only required for +.Xr renameat 2 +on the destination directory descriptor if the destination object already +exists and will be removed by the rename. +This right includes the +.Dv CAP_LOOKUP +right. +.It Dv CAP_WRITE +Allow +.Xr aio_write 2 , +.Xr openat 2 +with +.Dv O_WRONLY +and +.Dv O_APPEND +flags set, +.Xr send 2 , +.Xr sendmsg 2 , +.Xr sendto 2 , +.Xr write 2 , +.Xr writev 2 , +.Xr pwrite 2 , +.Xr pwritev 2 +and related system calls. +For +.Xr sendto 2 +with a non-NULL connection address, +.Dv CAP_CONNECT +is also required. +For +.Xr openat 2 +with the +.Dv O_WRONLY +flag, but without the +.Dv O_APPEND +or +.Dv O_TRUNC +flag, +.Dv CAP_SEEK +is also required. +For +.Xr aio_write 2 , +.Xr pwrite 2 +and +.Xr pwritev 2 +.Dv CAP_SEEK +is also required. +.El +.Sh SEE ALSO +.Xr accept 2 , +.Xr accept4 2 , +.Xr aio_fsync 2 , +.Xr aio_read 2 , +.Xr aio_write 2 , +.Xr bind 2 , +.Xr bindat 2 , +.Xr cap_enter 2 , +.Xr cap_fcntls_limit 2 , +.Xr cap_ioctls_limit 2 , +.Xr cap_rights_limit 2 , +.Xr chflagsat 2 , +.Xr connect 2 , +.Xr connectat 2 , +.Xr extattr_delete_fd 2 , +.Xr extattr_get_fd 2 , +.Xr extattr_list_fd 2 , +.Xr extattr_set_fd 2 , +.Xr fchflags 2 , +.Xr fchmod 2 , +.Xr fchmodat 2 , +.Xr fchown 2 , +.Xr fchownat 2 , +.Xr fcntl 2 , +.Xr fexecve 2 , +.Xr fhopen 2 , +.Xr flock 2 , +.Xr fpathconf 2 , +.Xr fstat 2 , +.Xr fstatat 2 , +.Xr fstatfs 2 , +.Xr fsync 2 , +.Xr ftruncate 2 , +.Xr futimes 2 , +.Xr getdents 2 , +.Xr getdirentries 2 , +.Xr getpeername 2 , +.Xr getsockname 2 , +.Xr getsockopt 2 , +.Xr ioctl 2 , +.Xr kevent 2 , +.Xr kqueue 2 , +.Xr linkat 2 , +.Xr listen 2 , +.Xr mmap 2 , +.Xr mq_open 2 , +.Xr open 2 , +.Xr openat 2 , +.Xr pdfork 2 , +.Xr pdgetpid 2 , +.Xr pdkill 2 , +.Xr pdwait4 2 , +.Xr pipe 2 , +.Xr poll 2 , +.Xr pread 2 , +.Xr preadv 2 , +.Xr pwrite 2 , +.Xr pwritev 2 , +.Xr read 2 , +.Xr readv 2 , +.Xr recv 2 , +.Xr recvfrom 2 , +.Xr recvmsg 2 , +.Xr renameat 2 , +.Xr sctp_peeloff 2 , +.Xr select 2 , +.Xr send 2 , +.Xr sendmsg 2 , +.Xr sendto 2 , +.Xr setsockopt 2 , +.Xr shm_open 2 , +.Xr shutdown 2 , +.Xr socket 2 , +.Xr socketpair 2 , +.Xr symlinkat 2 , +.Xr unlinkat 2 , +.Xr write 2 , +.Xr writev 2 , +.Xr acl_delete_fd_np 3 , +.Xr acl_get_fd 3 , +.Xr acl_get_fd_np 3 , +.Xr acl_set_fd 3 , +.Xr acl_set_fd_np 3 , +.Xr acl_valid_fd_np 3 , +.Xr mac_get_fd 3 , +.Xr mac_set_fd 3 , +.Xr sem_getvalue 3 , +.Xr sem_post 3 , +.Xr sem_trywait 3 , +.Xr sem_wait 3 , +.Xr capsicum 4 , +.Xr snp 4 +.Sh HISTORY +Support for capabilities and capabilities mode was developed as part of the +.Tn TrustedBSD +Project. +.Sh AUTHORS +.An -nosplit +This manual page was created by +.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net +under sponsorship from the FreeBSD Foundation based on the +.Xr cap_new 2 +manual page by +.An Robert Watson Aq Mt rwatson@FreeBSD.org . diff --git a/static/freebsd/man4/rl.4 b/static/freebsd/man4/rl.4 new file mode 100644 index 00000000..ba93b282 --- /dev/null +++ b/static/freebsd/man4/rl.4 @@ -0,0 +1,310 @@ +.\" Copyright (c) 1997, 1998 +.\" Bill Paul . 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 Bill Paul. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Bill Paul 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 Bill Paul OR THE VOICES IN HIS HEAD +.\" 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 16, 2013 +.Dt RL 4 +.Os +.Sh NAME +.Nm rl +.Nd "Realtek 8129/8139 Fast Ethernet device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device rl" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_rl_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for PCI Ethernet adapters and embedded +controllers based on the Realtek 8129 and 8139 Fast Ethernet controller +chips. +.Pp +The Realtek 8129/8139 series controllers use bus master DMA but do not use a +descriptor-based data transfer mechanism. +The receiver uses a +single fixed size ring buffer from which packets must be copied +into mbufs. +For transmission, there are only four outbound packet +address registers which require all outgoing packets to be stored +as contiguous buffers. +Furthermore, outbound packet buffers must +be longword aligned or else transmission will fail. +.Pp +The 8129 differs from the 8139 in that the 8139 has an internal +PHY which is controlled through special direct access registers +whereas the 8129 uses an external PHY via an MII bus. +The 8139 +supports both 10 and 100Mbps speeds in either full or half duplex. +The 8129 can support the same speeds and modes given an appropriate +PHY chip. +.Pp +Note: support for the 8139C+ chip is provided by the +.Xr re 4 +driver. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width xxxxxxxxxxxxxxxxxxxx +.It autoselect +Enable autoselection of the media type and options. +This is only +supported if the PHY chip attached to the Realtek controller +supports NWAY autonegotiation. +The user can manually override +the autoselected mode by adding media options to the +.Pa /etc/rc.conf +file. +.It 10baseT/UTP +Set 10Mbps operation. +The +.Ar mediaopt +option can also be used to select either +.Ar full-duplex +or +.Ar half-duplex +modes. +.It 100baseTX +Set 100Mbps (Fast Ethernet) operation. +The +.Ar mediaopt +option can also be used to select either +.Ar full-duplex +or +.Ar half-duplex +modes. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width xxxxxxxxxxxxxxxxxxxx +.It full-duplex +Force full duplex operation. +.It half-duplex +Force half duplex operation. +.El +.Pp +Note that the 100baseTX media type is only available if supported +by the adapter. +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +Adapters supported by the +.Nm +driver include: +.Pp +.Bl -bullet -compact +.It +Accton +.Dq Cheetah +EN1207D (MPX 5030/5038; Realtek 8139 clone) +.It +Allied Telesyn AT2550 +.It +Allied Telesyn AT2500TX +.It +Belkin F5D5000 +.It +BUFFALO (Melco INC.) LPC-CB-CLX (CardBus) +.It +Compaq HNE-300 +.It +CompUSA no-name 10/100 PCI Ethernet NIC +.It +Corega FEther CB-TXD +.It +Corega FEtherII CB-TXD +.It +D-Link DFE-520TX (rev. C1) +.It +D-Link DFE-528TX +.It +D-Link DFE-530TX+ +.It +D-Link DFE-538TX +.It +D-Link DFE-690TXD +.It +Edimax EP-4103DL CardBus +.It +Encore ENL832-TX 10/100 M PCI +.It +Farallon NetLINE 10/100 PCI +.It +Genius GF100TXR +.It +GigaFast Ethernet EE100-AXP +.It +KTX-9130TX 10/100 Fast Ethernet +.It +LevelOne FPC-0106TX +.It +Longshine LCS-8038TX-R +.It +NDC Communications NE100TX-E +.It +Netronix Inc.\& EA-1210 NetEther 10/100 +.It +Nortel Networks 10/100BaseTX +.It +OvisLink LEF-8129TX +.It +OvisLink LEF-8139TX +.It +Peppercon AG ROL-F +.It +Planex FNW-3603-TX +.It +Planex FNW-3800-TX +.It +SMC EZ Card 10/100 PCI 1211-TX +.It +SOHO (PRAGMATIC) UE-1211C +.El +.Sh LOADER TUNABLES +.Bl -tag -width indent +.It Va dev.rl.%unit.prefer_iomap +This tunable controls which register mapping should be used on the +specified device. +A non-zero value enables I/O space register mapping. +For controllers that have no I/O space register mapping this tunable +should be set to 0 to use memory space register mapping. +The default value is 1 to use I/O space register mapping. +.It Va dev.rl.%unit.twister_enable +Non-zero value enables the long cable tuning on the specified device. +Disabled by default. +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "rl%d: couldn't map memory" +A fatal initialization error has occurred. +.It "rl%d: couldn't map interrupt" +A fatal initialization error has occurred. +.It "rl%d: watchdog timeout" +The device has stopped responding to the network, or there is a problem with +the network connection (cable). +.It "rl%d: no memory for rx list" +The driver failed to allocate an mbuf for the receiver ring. +.It "rl%d: no memory for tx list" +The driver failed to allocate an mbuf for the transmitter ring when +allocating a pad buffer or collapsing an mbuf chain into a cluster. +.It "rl%d: chip is in D3 power state -- setting to D0" +This message applies only to adapters which support power +management. +Some operating systems place the controller in low power +mode when shutting down, and some PCI BIOSes fail to bring the chip +out of this state before configuring it. +The controller loses all of +its PCI configuration in the D3 state, so if the BIOS does not set +it back to full power mode in time, it will not be able to configure it +correctly. +The driver tries to detect this condition and bring +the adapter back to the D0 (full power) state, but this may not be +enough to return the driver to a fully operational condition. +If +you see this message at boot time and the driver fails to attach +the device as a network interface, you will have to perform second +warm boot to have the device properly configured. +.Pp +Note that this condition only occurs when warm booting from another +operating system. +If you power down your system prior to booting +.Fx , +the card should be configured correctly. +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr polling 4 , +.Xr ifconfig 8 +.Rs +.%B The Realtek 8129, 8139 and 8139C+ datasheets +.%U https://www.realtek.com +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 3.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Bill Paul Aq Mt wpaul@ctr.columbia.edu . +.Sh BUGS +Since outbound packets must be longword aligned, the transmit +routine has to copy an unaligned packet into an mbuf cluster buffer +before transmission. +The driver abuses the fact that the cluster buffer +pool is allocated at system startup time in a contiguous region starting +at a page boundary. +Since cluster buffers are 2048 bytes, they are +longword aligned by definition. +The driver probably should not be +depending on this characteristic. +.Pp +The Realtek data sheets are of especially poor quality, +and there is a lot of information missing +particularly concerning the receiver operation. +One particularly +important fact that the data sheets fail to mention relates to the +way in which the chip fills in the receive buffer. +When an interrupt +is posted to signal that a frame has been received, it is possible that +another frame might be in the process of being copied into the receive +buffer while the driver is busy handling the first one. +If the driver +manages to finish processing the first frame before the chip is done +DMAing the rest of the next frame, the driver may attempt to process +the next frame in the buffer before the chip has had a chance to finish +DMAing all of it. +.Pp +The driver can check for an incomplete frame by inspecting the frame +length in the header preceding the actual packet data: an incomplete +frame will have the magic length of 0xFFF0. +When the driver encounters +this value, it knows that it has finished processing all currently +available packets. +Neither this magic value nor its significance are +documented anywhere in the Realtek data sheets. diff --git a/static/freebsd/man4/rndtest.4 b/static/freebsd/man4/rndtest.4 new file mode 100644 index 00000000..c7330206 --- /dev/null +++ b/static/freebsd/man4/rndtest.4 @@ -0,0 +1,68 @@ +.\"- +.\" Copyright (c) 2003 Sam Leffler, Errno Consulting +.\" 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 May 11, 2020 +.Dt RNDTEST 4 +.Os +.Sh NAME +.Nm rndtest +.Nd FIPS 140-2 random number generator test monitor +.Sh SYNOPSIS +.Cd "device rndtest" +.Sh DESCRIPTION +The +.Nm +driver +.Dq "hooks up" +to hardware crypto devices to monitor the +entropy data passed to the +.Xr random 4 +subsystem. +This data is periodically tested for FIPS 140-2 compliance and +statistics are collected. +If the harvested entropy fails any of the FIPS test suite, then +it is discarded and testing is continuously applied until +.Dq "good data" +is received from the device. +Failures are optionally reported on the console. +.Sh SEE ALSO +.Xr crypto 4 , +.Xr random 4 , +.Xr safe 4 , +.Xr crypto 9 +.Sh HISTORY +The idea for this and the original code came from +.An "Jason L. Wright" . +The +.Nm +device driver first appeared in +.Fx 5.0 . +.Sh BUGS +Crypto device drivers must be compiled specially to make use of this driver; +this should not be necessary. +This feature might better be integrated into the +.Xr random 4 +subsystem where it can be applied to devices that claim to supply +.Dq "pure entropy" . diff --git a/static/freebsd/man4/route.4 b/static/freebsd/man4/route.4 new file mode 100644 index 00000000..5096c278 --- /dev/null +++ b/static/freebsd/man4/route.4 @@ -0,0 +1,326 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 November 4, 2004 +.Dt ROUTE 4 +.Os +.Sh NAME +.Nm route +.Nd kernel packet forwarding database +.Sh SYNOPSIS +.In sys/types.h +.In sys/time.h +.In sys/socket.h +.In net/if.h +.In net/route.h +.Ft int +.Fn socket PF_ROUTE SOCK_RAW "int family" +.Sh DESCRIPTION +.Fx +provides some packet routing facilities. +The kernel maintains a routing information database, which +is used in selecting the appropriate network interface when +transmitting packets. +.Pp +A user process (or possibly multiple co-operating processes) +maintains this database by sending messages over a special kind +of socket. +This supplants fixed size +.Xr ioctl 2 Ns 's +used in earlier releases. +Routing table changes may only be carried out by the super user. +.Pp +The operating system may spontaneously emit routing messages in response +to external events, such as receipt of a re-direct, or failure to +locate a suitable route for a request. +The message types are described in greater detail below. +.Pp +Routing database entries come in two flavors: for a specific +host, or for all hosts on a generic subnetwork (as specified +by a bit mask and value under the mask. +The effect of wildcard or default route may be achieved by using +a mask of all zeros, and there may be hierarchical routes. +.Pp +When the system is booted and addresses are assigned +to the network interfaces, each protocol family +installs a routing table entry for each interface when it is ready for traffic. +Normally the protocol specifies the route +through each interface as a +.Dq direct +connection to the destination host +or network. +If the route is direct, the transport layer of +a protocol family usually requests the packet be sent to the +same host specified in the packet. +Otherwise, the interface +is requested to address the packet to the gateway listed in the routing entry +(i.e., the packet is forwarded). +.Pp +When routing a packet, +the kernel will attempt to find +the most specific route matching the destination. +(If there are two different mask and value-under-the-mask pairs +that match, the more specific is the one with more bits in the mask. +A route to a host is regarded as being supplied with a mask of +as many ones as there are bits in the destination). +If no entry is found, the destination is declared to be unreachable, +and a routing-miss message is generated if there are any +listeners on the routing control socket described below. +.Pp +A wildcard routing entry is specified with a zero +destination address value, and a mask of all zeroes. +Wildcard routes will be used +when the system fails to find other routes matching the +destination. +The combination of wildcard +routes and routing redirects can provide an economical +mechanism for routing traffic. +.Pp +One opens the channel for passing routing control messages +by using the socket call shown in the synopsis above: +.Pp +The +.Fa family +parameter may be +.Dv AF_UNSPEC +which will provide +routing information for all address families, or can be restricted +to a specific address family by specifying which one is desired. +There can be more than one routing socket open per system. +.Pp +Messages are formed by a header followed by a small +number of sockaddrs (now variable length particularly +in the +.Tn ISO +case), interpreted by position, and delimited +by the new length entry in the sockaddr. +An example of a message with four addresses might be an +.Tn ISO +redirect: +Destination, Netmask, Gateway, and Author of the redirect. +The interpretation of which address are present is given by a +bit mask within the header, and the sequence is least significant +to most significant bit within the vector. +.Pp +Any messages sent to the kernel are returned, and copies are sent +to all interested listeners. +The kernel will provide the process +ID for the sender, and the sender may use an additional sequence +field to distinguish between outstanding messages. +However, message replies may be lost when kernel buffers are exhausted. +.Pp +The kernel may reject certain messages, and will indicate this +by filling in the +.Ar rtm_errno +field. +The routing code returns +.Er EEXIST +if +requested to duplicate an existing entry, +.Er ESRCH +if +requested to delete a non-existent entry, +or +.Er ENOBUFS +if insufficient resources were available +to install a new route. +In the current implementation, all routing processes run locally, +and the values for +.Ar rtm_errno +are available through the normal +.Em errno +mechanism, even if the routing reply message is lost. +.Pp +A process may avoid the expense of reading replies to +its own messages by issuing a +.Xr setsockopt 2 +call indicating that the +.Dv SO_USELOOPBACK +option +at the +.Dv SOL_SOCKET +level is to be turned off. +A process may ignore all messages from the routing socket +by doing a +.Xr shutdown 2 +system call for further input. +.Pp +If a route is in use when it is deleted, +the routing entry will be marked down and removed from the routing table, +but the resources associated with it will not +be reclaimed until all references to it are released. +User processes can obtain information about the routing +entry to a specific destination by using a +.Dv RTM_GET +message, or by calling +.Xr sysctl 3 . +.Pp +Messages include: +.Bd -literal +#define RTM_ADD 0x1 /* Add Route */ +#define RTM_DELETE 0x2 /* Delete Route */ +#define RTM_CHANGE 0x3 /* Change Metrics, Flags, or Gateway */ +#define RTM_GET 0x4 /* Report Information */ +#define RTM_LOSING 0x5 /* Kernel Suspects Partitioning */ +#define RTM_REDIRECT 0x6 /* Told to use different route */ +#define RTM_MISS 0x7 /* Lookup failed on this address */ +#define RTM_LOCK 0x8 /* fix specified metrics */ +#define RTM_RESOLVE 0xb /* request to resolve dst to LL addr - unused */ +#define RTM_NEWADDR 0xc /* address being added to iface */ +#define RTM_DELADDR 0xd /* address being removed from iface */ +#define RTM_IFINFO 0xe /* iface going up/down etc. */ +#define RTM_NEWMADDR 0xf /* mcast group membership being added to if */ +#define RTM_DELMADDR 0x10 /* mcast group membership being deleted */ +#define RTM_IFANNOUNCE 0x11 /* iface arrival/departure */ +#define RTM_IEEE80211 0x12 /* IEEE80211 wireless event */ +.Ed +.Pp +A message header consists of one of the following: +.Bd -literal +struct rt_msghdr { + u_short rtm_msglen; /* to skip over non-understood messages */ + u_char rtm_version; /* future binary compatibility */ + u_char rtm_type; /* message type */ + u_short rtm_index; /* index for associated ifp */ + int rtm_flags; /* flags, incl. kern & message, e.g. DONE */ + int rtm_addrs; /* bitmask identifying sockaddrs in msg */ + pid_t rtm_pid; /* identify sender */ + int rtm_seq; /* for sender to identify action */ + int rtm_errno; /* why failed */ + int rtm_fmask; /* bitmask used in RTM_CHANGE message */ + u_long rtm_inits; /* which metrics we are initializing */ + struct rt_metrics rtm_rmx; /* metrics themselves */ +}; + +struct if_msghdr { + u_short ifm_msglen; /* to skip over non-understood messages */ + u_char ifm_version; /* future binary compatibility */ + u_char ifm_type; /* message type */ + int ifm_addrs; /* like rtm_addrs */ + int ifm_flags; /* value of if_flags */ + u_short ifm_index; /* index for associated ifp */ + struct if_data ifm_data; /* statistics and other data about if */ +}; + +struct ifa_msghdr { + u_short ifam_msglen; /* to skip over non-understood messages */ + u_char ifam_version; /* future binary compatibility */ + u_char ifam_type; /* message type */ + int ifam_addrs; /* like rtm_addrs */ + int ifam_flags; /* value of ifa_flags */ + u_short ifam_index; /* index for associated ifp */ + int ifam_metric; /* value of ifa_metric */ +}; + +struct ifma_msghdr { + u_short ifmam_msglen; /* to skip over non-understood messages */ + u_char ifmam_version; /* future binary compatibility */ + u_char ifmam_type; /* message type */ + int ifmam_addrs; /* like rtm_addrs */ + int ifmam_flags; /* value of ifa_flags */ + u_short ifmam_index; /* index for associated ifp */ +}; + +struct if_announcemsghdr { + u_short ifan_msglen; /* to skip over non-understood messages */ + u_char ifan_version; /* future binary compatibility */ + u_char ifan_type; /* message type */ + u_short ifan_index; /* index for associated ifp */ + char ifan_name[IFNAMSIZ]; /* if name, e.g. "en0" */ + u_short ifan_what; /* what type of announcement */ +}; +.Ed +.Pp +The +.Dv RTM_IFINFO +message uses a +.Ar if_msghdr +header, the +.Dv RTM_NEWADDR +and +.Dv RTM_DELADDR +messages use a +.Ar ifa_msghdr +header, the +.Dv RTM_NEWMADDR +and +.Dv RTM_DELMADDR +messages use a +.Vt ifma_msghdr +header, the +.Dv RTM_IFANNOUNCE +message uses a +.Vt if_announcemsghdr +header, +and all other messages use the +.Ar rt_msghdr +header. +.Pp +The +.Dq Li "struct rt_metrics" +and the flag bits are as defined in +.Xr rtentry 9 . +.Pp +Specifiers for metric values in rmx_locks and rtm_inits are: +.Bd -literal +#define RTV_MTU 0x1 /* init or lock _mtu */ +#define RTV_HOPCOUNT 0x2 /* init or lock _hopcount */ +#define RTV_EXPIRE 0x4 /* init or lock _expire */ +#define RTV_RPIPE 0x8 /* init or lock _recvpipe */ +#define RTV_SPIPE 0x10 /* init or lock _sendpipe */ +#define RTV_SSTHRESH 0x20 /* init or lock _ssthresh */ +#define RTV_RTT 0x40 /* init or lock _rtt */ +#define RTV_RTTVAR 0x80 /* init or lock _rttvar */ +#define RTV_WEIGHT 0x100 /* init or lock _weight */ +.Ed +.Pp +Specifiers for which addresses are present in the messages are: +.Bd -literal +#define RTA_DST 0x1 /* destination sockaddr present */ +#define RTA_GATEWAY 0x2 /* gateway sockaddr present */ +#define RTA_NETMASK 0x4 /* netmask sockaddr present */ +#define RTA_GENMASK 0x8 /* cloning mask sockaddr present - unused */ +#define RTA_IFP 0x10 /* interface name sockaddr present */ +#define RTA_IFA 0x20 /* interface addr sockaddr present */ +#define RTA_AUTHOR 0x40 /* sockaddr for author of redirect */ +#define RTA_BRD 0x80 /* for NEWADDR, broadcast or p-p dest addr */ +.Ed +.Sh SEE ALSO +.Xr sysctl 3 , +.Xr route 8 , +.Xr rtentry 9 +.Pp +The constants for the +.Va rtm_flags +field are documented in the manual page for the +.Xr route 8 +utility. +.Sh HISTORY +A +.Dv PF_ROUTE +protocol family first appeared in +.Bx 4.3 reno . diff --git a/static/freebsd/man4/rsu.4 b/static/freebsd/man4/rsu.4 new file mode 100644 index 00000000..1c4f9774 --- /dev/null +++ b/static/freebsd/man4/rsu.4 @@ -0,0 +1,215 @@ +.\"- +.\" SPDX-License-Identifier: ISC +.\" +.\" $OpenBSD: rsu.4,v 1.11 2013/02/14 07:40:42 jmc Exp $ +.\" +.\" Copyright (c) 2010 Damien Bergamini +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd April 1, 2025 +.Dt RSU 4 +.Os +.Sh NAME +.Nm rsu +.Nd Realtek RTL8188SU/RTL8192SU USB IEEE 802.11b/g/n wireless network driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ehci" +.Cd "device uhci" +.Cd "device ohci" +.Cd "device usb" +.Cd "device rsu" +.Cd "device rsufw" +.Cd "device wlan" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, +place the following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_rsu_load="YES" +rsu-rtl8712fw_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports USB 2.0 wireless network devices based on Realtek +RTL8188SU, RTL8191SU and RTL8192SU chipsets. +.Pp +The RTL8188SU is a highly integrated 802.11n adapter that combines +a MAC, a 1T1R capable baseband and an RF in a single chip. +It operates in the 2GHz spectrum only. +.Pp +The RTL8191SU is a highly integrated multiple-in, single-out (MISO) +802.11n adapter that combines a MAC, a 1T2R capable baseband and an +RF in a single chip. +It operates in the 2GHz spectrum only. +.Pp +The RTL8192SU is a highly integrated multiple-in, multiple-out (MIMO) +802.11n adapter that combines a MAC, a 2T2R capable baseband and an +RF in a single chip. +It operates in the 2GHz spectrum only. +.Pp +These are the modes the +.Nm +driver can operate in: +.Bl -tag -width "IBSS-masterXX" +.It BSS mode +Also known as +.Em infrastructure +mode, this is used when associating with an access point, through +which all traffic passes. +This mode is the default. +.It monitor mode +In this mode the driver is able to receive packets without +associating with an access point. +This disables the internal receive filter and enables the card to +capture packets from networks which it wouldn't normally have access to, +or to scan for access points. +.El +.Pp +The +.Nm +driver can be configured to use +Wired Equivalent Privacy (WEP) or +Wi-Fi Protected Access (WPA-PSK and WPA2-PSK). +WPA is the de facto encryption standard for wireless networks. +It is strongly recommended that WEP +not be used as the sole mechanism +to secure wireless communication, +due to serious weaknesses in it. +.Pp +The +.Nm +driver can be configured at runtime with +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver provides support for Realtek RTL8188SU/RTL8192SU USB IEEE 802.11b/g/n +wireless network adapters, including: +.Pp +.Bl -bullet -offset indent -compact +.It +ASUS USB-N10 +.It +ASUS WL-167G V3 +.It +Belkin F7D1101 v1 +.It +D-Link DWA-131 A1 +.It +EDUP EP-MS150N(W) +.It +Edimax EW-7622UMN +.It +Hercules HWGUn-54 +.It +Hercules HWNUm-300 +.It +Planex GW-USNano +.It +Sitecom WL-349 v1 +.It +Sitecom WL-353 +.It +Sitecom WLA-1100 v1001 +.It +Sweex LW154 +.It +TRENDnet TEW-646UBH +.It +TRENDnet TEW-648UB +.It +TRENDnet TEW-649UB +.El +.Sh FILES +.Bl -tag -width "/usr/share/doc/legal/realtek.LICENSE" -compact +.It Pa /usr/share/doc/legal/realtek.LICENSE +.Nm +firmware license +.El +.Pp +The driver needs at least version 1.2 of the following firmware file, +which is loaded when an interface is attached: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It Pa /boot/kernel/rsu-rtl8712fw.ko +.El +.Sh EXAMPLES +Join an existing BSS network (i.e., connect to an access point): +.Pp +.Dl ifconfig wlan create wlandev rsu0 inet 192.0.2.20/24 +.Pp +Join a specific BSS network with network name +.Ar my_net : +.Pp +.Dl ifconfig wlan create wlandev rsu0 ssid my_net up +.Pp +Join a specific BSS network with 64-bit WEP encryption: +.Bd -literal -offset indent +ifconfig wlan create wlandev rsu0 ssid my_net \e + wepmode on wepkey 0x1234567890 weptxkey 1 up +.Ed +.Sh DIAGNOSTICS +.Bl -diag +.It "%s: failed load firmware of file rsu-rtl8712fw" +For some reason, the driver was unable to read the microcode file from the +filesystem. +The file might be missing or corrupted. +.It "device timeout" +A frame dispatched to the hardware for transmission did not complete in time. +The driver will reset the hardware. +This should not happen. +.El +.Sh SEE ALSO +.Xr intro 1 , +.Xr netintro 4 , +.Xr rsufw 4 , +.Xr usb 4 , +.Xr wlan 4 , +.Xr networking 7 , +.Xr arp 8 , +.Xr hostapd 8 , +.Xr ifconfig 8 , +.Xr wpa_supplicant 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Ox 4.9 and +.Fx 10.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Damien Bergamini Aq Mt damien@openbsd.org +and ported by +.An Rui Paulo Aq Mt rpaulo@freebsd.org . +The 802.11n support was added by +.An Adrian Chadd Aq Mt adrian@freebsd.org . +.Sh CAVEATS +The +.Nm +driver currently does not support 802.11n transmit aggregation, +either A-MSDU or A-MPDU. +.Pp +The +.Nm +driver does not capture management frames in non-monitor modes; +without this limitation some firmware functions (e.g., 'join bss') +will not work properly. diff --git a/static/freebsd/man4/rsufw.4 b/static/freebsd/man4/rsufw.4 new file mode 100644 index 00000000..f80891ea --- /dev/null +++ b/static/freebsd/man4/rsufw.4 @@ -0,0 +1,45 @@ +.\" Copyright (c) 2013 Idwer Vollering +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd April 4, 2018 +.Dt RSUFW 4 +.Os +.Sh NAME +.Nm rsufw +.Nd "Firmware Module for Realtek driver" +.Sh SYNOPSIS +To compile this module into the kernel, place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device rsufw" +.Ed +.Pp +This will include the firmware image, RTL8712, inside the kernel. +.Xr rsu 4 +will load the image into the chip. +.Pp +Alternatively, to load the firmware images as a module at boot time, place +the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +rsu-rtl8712fw_load="YES" +.Ed +.Sh DESCRIPTION +This module provides the firmware for the Realtek RTL8188SU and +RTL8192SU chip based USB WiFi adapters. +Please read Realtek's license, +.Pa /usr/share/doc/legal/realtek.LICENSE . +.Sh SEE ALSO +.Xr rsu 4 , +.Xr firmware 9 diff --git a/static/freebsd/man4/rtnetlink.4 b/static/freebsd/man4/rtnetlink.4 new file mode 100644 index 00000000..f15e2690 --- /dev/null +++ b/static/freebsd/man4/rtnetlink.4 @@ -0,0 +1,542 @@ +.\" +.\" Copyright (C) 2022 Alexander Chernikov . +.\" +.\" 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 November 1, 2022 +.Dt RTNETLINK 4 +.Os +.Sh NAME +.Nm RTNetlink +.Nd Network configuration-specific Netlink family +.Sh SYNOPSIS +.In netlink/netlink.h +.In netlink/netlink_route.h +.Ft int +.Fn socket AF_NETLINK SOCK_RAW NETLINK_ROUTE +.Sh DESCRIPTION +The +.Dv NETLINK_ROUTE +family aims to be the primary configuration mechanism for all +network-related tasks. +Currently it supports configuring interfaces, interface addresses, routes, +nexthops and arp/ndp neighbors. +.Sh ROUTES +All route configuration messages share the common header: +.Bd -literal +struct rtmsg { + unsigned char rtm_family; /* address family */ + unsigned char rtm_dst_len; /* Prefix length */ + unsigned char rtm_src_len; /* Deprecated, set to 0 */ + unsigned char rtm_tos; /* Type of service (not used) */ + unsigned char rtm_table; /* deprecated, set to 0 */ + unsigned char rtm_protocol; /* Routing protocol id (RTPROT_) */ + unsigned char rtm_scope; /* Route distance (RT_SCOPE_) */ + unsigned char rtm_type; /* Route type (RTN_) */ + unsigned rtm_flags; /* Route flags (not supported) */ +}; +.Ed +.Pp +The +.Va rtm_family +specifies the route family to be operated on. +Currently, +.Dv AF_INET6 +and +.Dv AF_INET +are the only supported families. +The route prefix length is stored in +.Va rtm_dst_len +. +The caller should set the originator identity (one of the +.Dv RTPROT_ +values) in +.Va rtm_protocol +. +It is useful for users and for the application itself, allowing for easy +identification of self-originated routes. +The route scope has to be set via +.Va rtm_scope +field. +The supported values are: +.Bd -literal -offset indent -compact +RT_SCOPE_UNIVERSE Global scope +RT_SCOPE_LINK Link scope +.Ed +.Pp +Route type needs to be set. +The defined values are: +.Bd -literal -offset indent -compact +RTN_UNICAST Unicast route +RTN_MULTICAST Multicast route +RTN_BLACKHOLE Drops traffic towards destination +RTN_PROHIBIT Drops traffic and sends reject +.Ed +.Pp +The following messages are supported: +.Ss RTM_NEWROUTE +Adds a new route. +All NL flags are supported. +Extending a multipath route requires NLM_F_APPEND flag. +.Ss RTM_DELROUTE +Tries to delete a route. +The route is specified using a combination of +.Dv RTA_DST +TLV and +.Va rtm_dst_len . +.Ss RTM_GETROUTE +Fetches a single route or all routes in the current VNET, depending on the +.Dv NLM_F_DUMP +flag. +Each route is reported as +.Dv RTM_NEWROUTE +message. +The following filters are recognised by the kernel: +.Pp +.Bd -literal -offset indent -compact +rtm_family required family or AF_UNSPEC +RTA_TABLE fib number or RT_TABLE_UNSPEC to return all fibs +.Ed +.Ss TLVs +.Bl -tag -width indent +.It Dv RTA_DST +(binary) IPv4/IPv6 address, depending on the +.Va rtm_family . +.It Dv RTA_OIF +(uint32_t) transmit interface index. +.It Dv RTA_GATEWAY +(binary) IPv4/IPv6 gateway address, depending on the +.Va rtm_family . +.It Dv RTA_METRICS +(nested) Container attribute, listing route properties. +The only supported sub-attribute is +.Dv RTAX_MTU , +which stores path MTU as uint32_t. +.It Dv RTA_MULTIPATH +This attribute contains multipath route nexthops with their weights. +These nexthops are represented as a sequence of +.Va rtnexthop +structures, each followed by +.Dv RTA_GATEWAY +or +.Dv RTA_VIA +attributes. +.Bd -literal +struct rtnexthop { + unsigned short rtnh_len; + unsigned char rtnh_flags; + unsigned char rtnh_hops; /* nexthop weight */ + int rtnh_ifindex; +}; +.Ed +.Pp +The +.Va rtnh_len +field specifies the total nexthop info length, including both +.Va struct rtnexthop +and the following TLVs. +The +.Va rtnh_hops +field stores relative nexthop weight, used for load balancing between group +members. +The +.Va rtnh_ifindex +field contains the index of the transmit interface. +.Pp +The following TLVs can follow the structure: +.Bd -literal -offset indent -compact +RTA_GATEWAY IPv4/IPv6 nexthop address of the gateway +RTA_VIA IPv6 nexthop address for IPv4 route +RTA_KNH_ID Kernel-specific index of the nexthop +.Ed +.It Dv RTA_KNH_ID +(uint32_t) (FreeBSD-specific) Auto-allocated kernel index of the nexthop. +.It Dv RTA_RTFLAGS +(uint32_t) (FreeBSD-specific) rtsock route flags. +.It Dv RTA_TABLE +(uint32_t) Fib number of the route. +Default route table is +.Dv RT_TABLE_MAIN . +To explicitly specify "all tables" one needs to set the value to +.Dv RT_TABLE_UNSPEC . +.It Dv RTA_EXPIRES +(uint32_t) seconds till path expiration. +.It Dv RTA_NH_ID +(uint32_t) useland nexthop or nexthop group index. +.El +.Ss Groups +The following groups are defined: +.Bd -literal -offset indent -compact +RTNLGRP_IPV4_ROUTE Notifies on IPv4 route arrival/removal/change +RTNLGRP_IPV6_ROUTE Notifies on IPv6 route arrival/removal/change +.Ed +.Sh NEXTHOPS +All nexthop/nexthop group configuration messages share the common header: +.Bd -literal +struct nhmsg { + unsigned char nh_family; /* transport family */ + unsigned char nh_scope; /* ignored on RX, filled by kernel */ + unsigned char nh_protocol; /* Routing protocol that installed nh */ + unsigned char resvd; + unsigned int nh_flags; /* RTNH_F_* flags from route.h */ +}; +.Ed +The +.Va nh_family +specifies the gateway address family. +It can be different from route address family for IPv4 routes with IPv6 +nexthops. +The +.Va nh_protocol +is similar to +.Va rtm_protocol +field, which designates originator application identity. +.Pp +The following messages are supported: +.Ss RTM_NEWNEXTHOP +Creates a new nexthop or nexthop group. +.Ss RTM_DELNEXTHOP +Deletes nexthop or nexthhop group. +The required object is specified by the +.Dv RTA_NH_ID +attribute. +.Ss RTM_GETNEXTHOP +Fetches a single nexthop or all nexthops/nexthop groups, depending on the +.Dv NLM_F_DUMP +flag. +The following filters are recognised by the kernel: +.Pp +.Bd -literal -offset indent -compact +RTA_NH_ID nexthop or nexthtop group id +NHA_GROUPS match only nexthtop groups +.Ed +.Ss TLVs +.Bl -tag -width indent +.It Dv RTA_NH_ID +(uint32_t) Nexthhop index used to identify particular nexthop or nexthop group. +Should be provided by userland at the nexthtop creation time. +.It Dv NHA_GROUP +This attribute designates the nexthtop group and contains all of its nexthtops +and their relative weights. +The attribute consists of a list of +.Va nexthop_grp +structures: +.Bd -literal +struct nexthop_grp { + uint32_t id; /* nexhop userland index */ + uint8_t weight; /* weight of this nexthop */ + uint8_t resvd1; + uint16_t resvd2; +}; +.Ed +.It Dv NHA_GROUP_TYPE +(uint16_t) Nexthtop group type, set to one of the following types: +.Bd -literal -offset indent -compact +NEXTHOP_GRP_TYPE_MPATH default multipath group +.Ed +.It Dv NHA_BLACKHOLE +(flag) Marks the nexthtop as blackhole. +.It Dv NHA_OIF +(uint32_t) Transmit interface index of the nexthtop. +.It Dv NHA_GATEWAY +(binary) IPv4/IPv6 gateway address +.It Dv NHA_GROUPS +(flag) Matches nexthtop groups during dump. +.El +.Ss Groups +The following groups are defined: +.Bd -literal -offset indent -compact +RTNLGRP_NEXTHOP Notifies on nexthop/groups arrival/removal/change +.Ed +.Sh INTERFACES +All interface configuration messages share the common header: +.Bd -literal +struct ifinfomsg { + unsigned char ifi_family; /* not used, set to 0 */ + unsigned char __ifi_pad; + unsigned short ifi_type; /* ARPHRD_* */ + int ifi_index; /* Interface index */ + unsigned ifi_flags; /* IFF_* flags */ + unsigned ifi_change; /* IFF_* change mask */ +}; +.Ed +.Ss RTM_NEWLINK +Creates a new interface. +The only mandatory TLV is +.Dv IFLA_IFNAME . +The following attributes are returned inside the nested +.Dv NLMSGERR_ATTR_COOKIE : +.Pp +.Bd -literal -offset indent -compact +IFLA_NEW_IFINDEX (uint32) created interface index +IFLA_IFNAME (string) created interface name +.Ed +.Ss RTM_DELLINK +Deletes the interface specified by +.Dv IFLA_IFNAME . +.Ss RTM_GETLINK +Fetches a single interface or all interfaces in the current VNET, +depending on the +.Dv NLM_F_DUMP +flag. +Each interface is reported as a +.Dv RTM_NEWLINK +message. +The following filters are recognised by the kernel: +.Pp +.Bd -literal -offset indent -compact +ifi_index interface index +IFLA_IFNAME interface name +IFLA_ALT_IFNAME interface name +.Ed +.Ss TLVs +.Bl -tag -width indent +.It Dv IFLA_ADDRESS +(binary) Llink-level interface address (MAC). +.It Dv IFLA_BROADCAST +(binary) (readonly) Link-level broadcast address. +.It Dv IFLA_IFNAME +(string) New interface name. +.It Dv IFLA_IFALIAS +(string) Interface description. +.It Dv IFLA_LINK +(uint32_t) (readonly) Interface index. +.It Dv IFLA_MASTER +(uint32_t) Parent interface index. +.It Dv IFLA_LINKINFO +(nested) Interface type-specific attributes: +.Bd -literal -offset indent -compact +IFLA_INFO_KIND (string) interface type ("vlan") +IFLA_INFO_DATA (nested) custom attributes +.Ed +The following types and attributes are supported: +.Bl -tag -width indent +.It Dv vlan +.Bd -literal -offset indent -compact +IFLA_VLAN_ID (uint16_t) 802.1Q vlan id +IFLA_VLAN_PROTOCOL (uint16_t) Protocol: ETHERTYPE_VLAN or ETHERTYPE_QINQ +.Ed +.El +.It Dv IFLA_OPERSTATE +(uint8_t) Interface operational state per RFC 2863. +Can be one of the following: +.Bd -literal -offset indent -compact +IF_OPER_UNKNOWN status can not be determined +IF_OPER_NOTPRESENT some (hardware) component not present +IF_OPER_DOWN down +IF_OPER_LOWERLAYERDOWN some lower-level interface is down +IF_OPER_TESTING in some test mode +IF_OPER_DORMANT "up" but waiting for some condition (802.1X) +IF_OPER_UP ready to pass packets +.Ed +.It Dv IFLA_STATS64 +(readonly) Consists of the following 64-bit counters structure: +.Bd -literal +struct rtnl_link_stats64 { + uint64_t rx_packets; /* total RX packets (IFCOUNTER_IPACKETS) */ + uint64_t tx_packets; /* total TX packets (IFCOUNTER_OPACKETS) */ + uint64_t rx_bytes; /* total RX bytes (IFCOUNTER_IBYTES) */ + uint64_t tx_bytes; /* total TX bytes (IFCOUNTER_OBYTES) */ + uint64_t rx_errors; /* RX errors (IFCOUNTER_IERRORS) */ + uint64_t tx_errors; /* RX errors (IFCOUNTER_OERRORS) */ + uint64_t rx_dropped; /* RX drop (no space in ring/no bufs) (IFCOUNTER_IQDROPS) */ + uint64_t tx_dropped; /* TX drop (IFCOUNTER_OQDROPS) */ + uint64_t multicast; /* RX multicast packets (IFCOUNTER_IMCASTS) */ + uint64_t collisions; /* not supported */ + uint64_t rx_length_errors; /* not supported */ + uint64_t rx_over_errors; /* not supported */ + uint64_t rx_crc_errors; /* not supported */ + uint64_t rx_frame_errors; /* not supported */ + uint64_t rx_fifo_errors; /* not supported */ + uint64_t rx_missed_errors; /* not supported */ + uint64_t tx_aborted_errors; /* not supported */ + uint64_t tx_carrier_errors; /* not supported */ + uint64_t tx_fifo_errors; /* not supported */ + uint64_t tx_heartbeat_errors; /* not supported */ + uint64_t tx_window_errors; /* not supported */ + uint64_t rx_compressed; /* not supported */ + uint64_t tx_compressed; /* not supported */ + uint64_t rx_nohandler; /* dropped due to no proto handler (IFCOUNTER_NOPROTO) */ +}; +.Ed +.El +.Ss Groups +The following groups are defined: +.Bd -literal -offset indent -compact +RTNLGRP_LINK Notifies on interface arrival/removal/change +.Ed +.Sh INTERFACE ADDRESSES +All interface address configuration messages share the common header: +.Bd -literal +struct ifaddrmsg { + uint8_t ifa_family; /* Address family */ + uint8_t ifa_prefixlen; /* Prefix length */ + uint8_t ifa_flags; /* Address-specific flags */ + uint8_t ifa_scope; /* Address scope */ + uint32_t ifa_index; /* Link ifindex */ +}; +.Ed +.Pp +The +.Va ifa_family +specifies the address family of the interface address. +The +.Va ifa_prefixlen +specifies the prefix length if applicable for the address family. +The +.Va ifa_index +specifies the interface index of the target interface. +.Ss RTM_NEWADDR +Not supported +.Ss RTM_DELADDR +Not supported +.Ss RTM_GETADDR +Fetches interface addresses in the current VNET matching conditions. +Each address is reported as a +.Dv RTM_NEWADDR +message. +The following filters are recognised by the kernel: +.Pp +.Bd -literal -offset indent -compact +ifa_family required family or AF_UNSPEC +ifa_index matching interface index or 0 +.Ed +.Ss TLVs +.Bl -tag -width indent +.It Dv IFA_ADDRESS +(binary) masked interface address or destination address for p2p interfaces. +.It Dv IFA_LOCAL +(binary) local interface address. +Set for IPv4 and p2p addresses. +.It Dv IFA_LABEL +(string) interface name. +.It Dv IFA_BROADCAST +(binary) broadcast interface address. +.El +.Ss Groups +The following groups are defined: +.Bd -literal -offset indent -compact +RTNLGRP_IPV4_IFADDR Notifies on IPv4 ifaddr arrival/removal/change +RTNLGRP_IPV6_IFADDR Notifies on IPv6 ifaddr arrival/removal/change +.Ed +.Sh NEIGHBORS +All neighbor configuration messages share the common header: +.Bd -literal +struct ndmsg { + uint8_t ndm_family; + uint8_t ndm_pad1; + uint16_t ndm_pad2; + int32_t ndm_ifindex; + uint16_t ndm_state; + uint8_t ndm_flags; + uint8_t ndm_type; +}; +.Ed +.Pp +The +.Va ndm_family +field specifies the address family (IPv4 or IPv6) of the neighbor. +The +.Va ndm_ifindex +specifies the interface to operate on. +The +.Va ndm_state +represents the entry state according to the neighbor model. +The state can be one of the following: +.Bd -literal -offset indent -compact +NUD_INCOMPLETE No lladdr, address resolution in progress +NUD_REACHABLE reachable & recently resolved +NUD_STALE has lladdr but it's stale +NUD_DELAY has lladdr, is stale, probes delayed +NUD_PROBE has lladdr, is stale, probes sent +NUD_FAILED unused +.Ed +.Pp +The +.Va ndm_flags +field stores the options specific to this entry. +Available flags: +.Bd -literal -offset indent -compact +NTF_SELF local station (LLE_IFADDR) +NTF_PROXY proxy entry (LLE_PUB) +NTF_STICKY permanent entry (LLE_STATIC) +NTF_ROUTER dst indicated itself as a router +.Ed +.Ss RTM_NEWNEIGH +Creates new neighbor entry. +The mandatory options are +.Dv NDA_DST , +.Dv NDA_LLADDR +and +.Dv NDA_IFINDEX . +.Ss RTM_DELNEIGH +Deletes the neighbor entry. +The entry is specified by the combination of +.Dv NDA_DST +and +.Dv NDA_IFINDEX . +.Ss RTM_GETNEIGH +Fetches a single neighbor or all neighbors in the current VNET, depending on the +.Dv NLM_F_DUMP +flag. +Each entry is reported as +.Dv RTM_NEWNEIGH +message. +The following filters are recognised by the kernel: +.Pp +.Bd -literal -offset indent -compact +ndm_family required family or AF_UNSPEC +ndm_ifindex target ifindex +NDA_IFINDEX target ifindex +.Ed +.Ss TLVs +.Bl -tag -width indent +.It Dv NDA_DST +(binary) neighbor IPv4/IPv6 address. +.It Dv NDA_LLADDR +(binary) neighbor link-level address. +.It Dv NDA_IFINDEX +(uint32_t) interface index. +.It Dv NDA_FLAGS_EXT +(uint32_t) extended version of +.Va ndm_flags . +.El +.Ss Groups +The following groups are defined: +.Bd -literal -offset indent -compact +RTNLGRP_NEIGH Notifies on ARP/NDP neighbor arrival/removal/change +.Ed +.Sh SEE ALSO +.Xr snl 3 , +.Xr netlink 4 , +.Xr route 4 +.Sh HISTORY +The +.Dv NETLINK_ROUTE +protocol family appeared in +.Fx 13.2 . +.Sh AUTHORS +The netlink was implemented by +.An -nosplit +.An Alexander Chernikov Aq Mt melifaro@FreeBSD.org . +It was derived from the Google Summer of Code 2021 project by +.An Ng Peng Nam Sean . diff --git a/static/freebsd/man4/rtsx.4 b/static/freebsd/man4/rtsx.4 new file mode 100644 index 00000000..69de84c6 --- /dev/null +++ b/static/freebsd/man4/rtsx.4 @@ -0,0 +1,141 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2020 Henri Hennebert +.\" 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. 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 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 May 26, 2025 +.Dt RTSX 4 +.Os +.Sh NAME +.Nm rtsx +.Nd Realtek SD card reader +.Sh SYNOPSIS +To compile this driver into the kernel, place the following +lines in the kernel configuration file: +.Bd -ragged -offset indent +.Cd device mmc +.Cd device mmcsd +.Cd device rtsx +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, +place the following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +.Cd mmc_load="YES" +.Cd mmcsd_load="YES" +.Cd rtsx_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for Realtek SD card reader. +Driver attaches mmc bus on card insertion and detaches it on card removing. +.Sh HARDWARE +The +.Nm +driver supports the following Realtek SD card readers: +.Pp +.Bl -bullet -compact +.It +RTS5209 +.It +RTS5227 +.It +RTS5229 +.It +RTS522A +.It +RTS525A +.It +RTS5260 +.It +RTL8411B +.It +RTS5249 (unverified) +.It +RTL8402 (unverified) +.It +RTL8411 (unverified) +.El +.Sh SEE ALSO +.Xr mmc 4 , +.Xr mmcsd 4 +.Rs +.%T "SD Specifications, Part 2, SD Host Controller, Simplified Specification" +.%T "SanDisk Secure Digital Card" +.Re +.Sh HISTORY +The +.Nm +driver appeared in +.Fx 13.0 +and was ported from +.Ox +with modifications found in Linux and +.Nx . +.Sh AUTHORS +.An Henri Hennebert Aq Mt hlh@restart.be +.An Gary Jennejohn Aq Mt gj@freebsd.org +.An Jesper Schmitz Mouridsen Aq Mt jsm@FreeBSD.org +.Sh CONTRIBUTORS +.An Lutz Bichler Aq Mt Lutz.Bichler@gmail.com +.Sh DEBUGGING INFORMATION +.Em dev.rtsx.0.debug_mask +can be set with the following masks: +.Bl -bullet +.It +0x01 - to show the basic flow of the driver, +.It +0x02 - to trace the SD commands, +.It +0x04 - to trace the tuning phase. +.El +.Sh BUGS +.Bl -bullet +.It +RTS522A on Lenovo T470p, card detection and read-only switch are reversed. +This is solved by adding in +.Em loader.conf(5) : +.Bd -ragged +.Cd dev.rtsx.0.inversion=1 +.Ed +.Pp +The driver tries to automate those exceptions. +If this automation is wrong, it can be avoided by adding in +.Em loader.conf(5) : +.Bd -ragged +.Cd dev.rtsx.0.inversion=0 +.Ed +.It +Mounting a filesystem with write access on a card write protected may involve a kernel crash. +.It +Suspend/Resume do not work under MMCCAM. +.It +For some chips (e.g. RTS5260) after +.Cd devctl disable/enable +or +.Cd kldunload/kldload +the driver can't detect a card correctly. +.El diff --git a/static/freebsd/man4/rtw88.4 b/static/freebsd/man4/rtw88.4 new file mode 100644 index 00000000..e01f508e --- /dev/null +++ b/static/freebsd/man4/rtw88.4 @@ -0,0 +1,110 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2022-2026 Bjoern A. Zeeb +.\" +.Dd February 10, 2026 +.Dt RTW88 4 +.Os +.Sh NAME +.Nm rtw88 +.Nd Realtek IEEE 802.11n/ac wireless network driver +.Sh SYNOPSIS +The driver will auto-load without any user interaction using +.Xr devmatch 8 +if enabled in +.Xr rc.conf 5 . +.Pp +Only if auto-loading is explicitly disabled, place the following +lines in +.Xr rc.conf 5 +to manually load the driver as a module at boot time: +.Bd -literal -offset indent +kld_list="${kld_list} if_rtw88" +.Ed +.Pp +It is not possible to load the driver from +.Xr loader 8 . +.Sh DESCRIPTION +The +.Nm +driver is derived from Realtek's Linux rtw88 driver. +.Pp +This driver requires firmware to be loaded before it will work. +The package +.Pa wifi-firmware-rtw88-kmod +from the +.Pa ports/net/wifi-firmware-rtw88-kmod +port needs to be installed before the driver is loaded. +Otherwise no +.Xr wlan 4 +interface can be created using +.Xr ifconfig 8 . +One can use +.Xr fwget 8 +to install the correct firmware package. +.Pp +The driver uses the +.\" No LinuxKPI man pages so no .Xr here. +.Sy linuxkpi_wlan +and +.Sy linuxkpi +compat framework to bridge between the Linux and +native +.Fx +driver code as well as to the native +.Xr net80211 4 +wireless stack. +.Sh HARDWARE +The +.Nm +driver supports PCIe devices with the following chipsets: +.Pp +.Bl -bullet -offset indent -compact +.It +Realtek 802.11n wireless 8723de (RTL8723DE) +.It +Realtek 802.11ac wireless 8821ce (RTL8821CE) +.It +Realtek 802.11ac wireless 8822be (RTL8822BE) +.It +Realtek 802.11ac wireless 8822ce (RTL8822CE) +.El +.Sh LOADER TUNABLES +.Bl -tag -width indent +.It Va compat.linuxkpi.skb.mem_limit +If you are running a 64bit system with more than 4GB of main memory +you need to set this tunable to +.Sy 1 +in +.Xr loader.conf 5 +and reboot once to make it effective. +This tunable will work around a problem with DMA and limit allocations +for network buffer memory to the lower 32bit of physical memory and +make the driver work. +.El +.Sh SEE ALSO +.Xr wlan 4 , +.Xr networking 7 , +.Xr fwget 8 , +.Xr ifconfig 8 , +.Xr wpa_supplicant 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 13.2 . +.Sh BUGS +Certainly. +.Pp +Does not seem to work (reliably) on machines with more than 4GB of +main memory. +See in the +.Sx LOADER TUNABLES +section above. +.Pp +While +.Nm +supports 802.11a/b/g/n/ac modes, +the compatibility code currently only supports 802.11a/b/g modes. +Support for 802.11n/ac is yet to come. diff --git a/static/freebsd/man4/rtw89.4 b/static/freebsd/man4/rtw89.4 new file mode 100644 index 00000000..8c713267 --- /dev/null +++ b/static/freebsd/man4/rtw89.4 @@ -0,0 +1,112 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2023-2025 Bjoern A. Zeeb +.\" +.Dd June 13, 2025 +.Dt RTW89 4 +.Os +.Sh NAME +.Nm rtw89 +.Nd Realtek IEEE 802.11ax wireless network driver +.Sh SYNOPSIS +The driver will auto-load without any user interaction using +.Xr devmatch 8 +if enabled in +.Xr rc.conf 5 . +.Pp +Only if auto-loading is explicitly disabled, place the following +lines in +.Xr rc.conf 5 +to manually load the driver as a module at boot time: +.Bd -literal -offset indent +kld_list="${kld_list} if_rtw89" +.Ed +.Pp +It is not possible to load the driver from +.Xr loader 8 . +.Sh DESCRIPTION +The +.Nm +driver is derived from Realtek's Linux rtw89 driver. +.Pp +This driver requires firmware to be loaded before it will work. +The package +.Pa wifi-firmware-rtw89-kmod +from the +.Pa ports/net/wifi-firmware-rtw89-kmod +port needs to be installed before the driver is loaded. +Otherwise no +.Xr wlan 4 +interface can be created using +.Xr ifconfig 8 . +One should use +.Xr fwget 8 +to install the correct firmware package. +.Pp +The driver uses the +.\" No LinuxKPI man pages so no .Xr here. +.Sy linuxkpi_wlan +and +.Sy linuxkpi +compat framework to bridge between the Linux and +native +.Fx +driver code as well as to the native +.Xr net80211 4 +wireless stack. +.Sh HARDWARE +The +.Nm +driver supports PCIe devices with the following chipsets: +.Pp +.Bl -bullet -offset indent -compact +.It +Realtek 8851BE Wi-Fi 6 (RTL8851BE) +.It +Realtek 8852AE Wi-Fi 6 (RTL8852AE) +.It +Realtek 8852BE Wi-Fi 6 (RTL8852BE) +.It +Realtek 8852CE Wi-Fi 6E (RTL8852CE) +.It +Realtek 8922AE Wi-Fi 7 (RTL8922AE) +.El +.Sh LOADER TUNABLES +.Bl -tag -width indent +.It Va compat.linuxkpi.skb.mem_limit +If you are running a 64bit system with more than 4GB of main memory +you need to set this tunable to +.Sy 1 +in +.Xr loader.conf 5 +and reboot once to make it effective. +This tunable will work around a problem with DMA and limit allocations +for network buffer memory to the lower 32bit of physical memory and +make the driver work. +.El +.Sh SEE ALSO +.Xr wlan 4 , +.Xr networking 7 , +.Xr fwget 8 , +.Xr ifconfig 8 , +.Xr wpa_supplicant 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 14.2 . +.Sh BUGS +Certainly. +.Pp +Does not seem to work (reliably) on machines with more than 4GB of +main memory. +See in the +.Sx LOADER TUNABLES +section above. +.Pp +While +.Nm +supports 802.11a/b/g/n/ac/ax modes, +the compatibility code currently only supports 802.11a/b/g modes. +Support for 802.11n/ac/ax is yet to come. diff --git a/static/freebsd/man4/rtwn.4 b/static/freebsd/man4/rtwn.4 new file mode 100644 index 00000000..06761fdc --- /dev/null +++ b/static/freebsd/man4/rtwn.4 @@ -0,0 +1,268 @@ +.\"- +.\" SPDX-License-Identifier: ISC +.\" +.\" $OpenBSD: rtwn.4,v 1.2 2015/07/09 11:28:53 stsp Exp $ +.\" +.\" Copyright (c) 2010 Damien Bergamini +.\" Copyright (c) 2015 Stefan Sperling +.\" Copyright (c) 2016 Andriy Voskoboinyk +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd November 10, 2024 +.Dt RTWN 4 +.Os +.Sh NAME +.Nm rtwn +.Nd Realtek IEEE 802.11n/ac wireless network driver +.Sh SYNOPSIS +.Cd "options RTWN_DEBUG" +.Cd "options RTWN_WITHOUT_UCODE" +.Pp +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device rtwn" +.Cd "device rtwnfw" +.Cd "device rtwn_usb" +.Cd "device rtwn_pci" +.Cd "device wlan" +.Cd "device firmware" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_rtwn_pci_load="YES" +if_rtwn_usb_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for 802.11n/ac wireless network PHYs supplied by +.Xr rtwn_pci 4 +and +.Xr rtwn_usb 4 . +.Pp +The +.Nm +driver supports +.Cm station , +.Cm adhoc , +.Cm hostap +and +.Cm monitor +mode operation. +There are no limitations for number of +.Cm monitor +mode +virtual interfaces; in addition to any other virtual interface +one +.Cm station +interface can be added (Note: RTL8821AU supports two non-monitor +mode interfaces at the same time). +.Pp +All chips have hardware support for WEP, AES-CCM and TKIP encryption. +.Pp +The +.Nm +driver can be configured at runtime with +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports USB and PCI devices with the following chipsets: +.Pp +.Bl -bullet -offset indent -compact +.It +Realtek 802.11n wireless 8188e (RTL8188E) +.It +Realtek 802.11n wireless 8192c (RTL8192C) +.It +Realtek 802.11n wireless 8192e (RTL8192E) +.It +Realtek 802.11ac wireless 8812a (RTL8812A) +.It +Realtek 802.11ac wireless 8821a (RTL8821A) +.El +.Pp +For specific devices, see +.Xr rtwn_pci 4 +and +.Xr rtwn_usb 4 . +.Sh FILES +.Bl -tag -width "/usr/share/doc/legal/realtek.LICENSE" -compact +.It Pa /usr/share/doc/legal/realtek.LICENSE +.Nm +firmware license +.El +.Pp +The driver +.Pq if not compiled with Cd options RTWN_WITHOUT_UCODE +may use following firmware files, +which are loaded when an interface is brought up: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It Pa /boot/kernel/rtwn-rtl8188eefw.ko +.It Pa /boot/kernel/rtwn-rtl8188eufw.ko +.It Pa /boot/kernel/rtwn-rtl8192cfwE_B.ko +.It Pa /boot/kernel/rtwn-rtl8192cfwE.ko +.It Pa /boot/kernel/rtwn-rtl8192cfwT.ko +.It Pa /boot/kernel/rtwn-rtl8192cfwU.ko +.It Pa /boot/kernel/rtwn-rtl8192eufw.ko +.It Pa /boot/kernel/rtwn-rtl8812aufw.ko +.It Pa /boot/kernel/rtwn-rtl8821aufw.ko +.El +.Sh EXAMPLES +Join an existing BSS network (i.e., connect to an access point): +.Pp +.Dl ifconfig wlan create wlandev rtwn0 inet 192.0.2.20/24 +.Pp +Join a specific BSS network with network name +.Ar my_net : +.Pp +.Dl ifconfig wlan create wlandev rtwn0 ssid my_net up +.Pp +Join a specific BSS network with 64-bit WEP encryption: +.Bd -literal -offset indent +ifconfig wlan create wlandev rtwn0 ssid my_net \e + wepmode on wepkey 0x1234567890 weptxkey 1 up +.Ed +.Pp +Create an IBSS network with 128-bit WEP encryption on the channel 4: +.Bd -literal -offset indent +ifconfig wlan create wlandev rtwn0 wlanmode adhoc ssid my_net \e + wepmode on wepkey 0x01020304050607080910111213 weptxkey 1 \e + channel 4 +.Ed +.Pp +Join/create an 802.11b IBSS network with network name +.Ar my_net : +.Bd -literal -offset indent +ifconfig wlan0 create wlandev rtwn0 wlanmode adhoc +ifconfig wlan0 inet 192.0.2.20/24 ssid my_net mode 11b +.Ed +.Pp +Create a host-based access point: +.Bd -literal -offset indent +ifconfig wlan0 create wlandev rtwn0 wlanmode hostap +ifconfig wlan0 inet 192.0.2.20/24 ssid my_ap +.Ed +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width indent +.It Va dev.rtwn.%d.hwcrypto +This tunable controls how key slots are assigned: +.Pp +0 - disable h/w crypto support. +Features that require access to frame contents (e.g., TCP/UDP/IP Rx +checksum validation) will not work; +.Pp +1 - use h/w crypto support for pairwise keys only; +.Pp +2 - use h/w crypto support for all keys; may not work for +multi-vap configurations. +.Pp +By default it is set to 1. +.It Va dev.rtwn.%d.ratectl +This tunable switches between rate control implementations: +.Pp +0 - no rate control; +.Pp +1 - driver sends 'tx complete' reports to net80211; algorithm +is controlled via net80211; +.Pp +2 - firmware-based rate control. +.Pp +By default it is set to 1; however driver may choose another +algorithm in case if it is not implemented +.Pp +Currently selected algorithm is reported via +.Va dev.rtwn.%d.ratectl_selected +read-only OID. +.It Va dev.rtwn.%d.rx_buf_size +(USB only) Controls size of temporary Rx buffer; smaller buffer size +may increase number of interrupts. +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "rtwn%d: could not read efuse byte at address 0x%x" +.It "rtwn%d: %s: cannot read rom, error %d" +There was an error while reading ROM; device attach will be aborted. +This should not happen. +.It "rtwn%d: failed loadfirmware of file %s" +For some reason, the driver was unable to read the microcode file from the +filesystem. +The file might be missing or corrupted. +The driver will disable firmware-dependent features. +.It "rtwn%d: wrong firmware size (%zu)" +.It "rtwn%d: %s: failed to upload firmware %s (error %d)" +.It "rtwn%d: timeout waiting for firmware readiness" +Firmware upload failed; the file might be corrupted. +The driver will disable firmware-dependent features. +This should not happen. +.It "rtwn%d: device timeout" +A frame dispatched to the hardware for transmission did not complete in time. +The driver will reset the hardware. +This should not happen. +.El +.Sh SEE ALSO +.Xr intro 4 , +.Xr netintro 4 , +.Xr rtwn_pci 4 , +.Xr rtwn_usb 4 , +.Xr rtwnfw 4 , +.Xr wlan 4 , +.Xr wlan_amrr 4 , +.Xr wlan_ccmp 4 , +.Xr wlan_tkip 4 , +.Xr wlan_wep 4 , +.Xr wlan_xauth 4 , +.Xr networking 7 , +.Xr hostapd 8 , +.Xr ifconfig 8 , +.Xr wpa_supplicant 8 +.Sh HISTORY +The +.Cm urtwn +driver first appeared in +.Ox 4.9 +and +.Fx 10.0 ; +the +.Nm +driver first appeared in +.Ox 5.8 +and +.Fx 11.0 . +.Sh AUTHORS +The +.Nm +driver was initially written by +.An -nosplit +.An Stefan Sperling Aq Mt stsp@openbsd.org +and ported by +.An Kevin Lo Aq Mt kevlo@freebsd.org . +It was based on the +.Cm urtwn +driver written by +.An Damien Bergamini Aq Mt damien.bergamini@free.fr . +.Sh BUGS +The +.Nm +driver currently does not implement firmware-based rate control. diff --git a/static/freebsd/man4/rtwn_pci.4 b/static/freebsd/man4/rtwn_pci.4 new file mode 100644 index 00000000..e604007d --- /dev/null +++ b/static/freebsd/man4/rtwn_pci.4 @@ -0,0 +1,73 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2011 Adrian Chadd, Xenion Pty Ltd +.\" Copyright (c) 2016 Andriy Voskoboinyk +.\" 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, +.\" without modification. +.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer +.\" similar to the "NO WARRANTY" disclaimer below ("Disclaimer") and any +.\" redistribution must be conditioned upon including a substantially +.\" similar Disclaimer requirement for further binary redistribution. +.\" +.\" NO WARRANTY +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTIBILITY +.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL +.\" THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR 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 DAMAGES. +.\" +.Dd November 10, 2024 +.Dt RTWN_PCI 4 +.Os +.Sh NAME +.Nm rtwn_pci +.Nd Realtek wireless rtwn network driver PCI/PCIe support +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device rtwn" +.Cd "device rtwn_pci" +.Cd "device pci" +.Cd "device wlan" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for PCIe wireless network devices to the +.Xr rtwn 4 +driver. +.Pp +Both RTL8188CE and RTL8188EE are highly integrated 802.11n adapters +that combines a MAC, a 1T1R capable baseband and an RF in a single chip. +They are operate in the 2GHz spectrum only. +.Sh HARDWARE +The +.Nm +driver supports the following PCIe Wi-Fi devices: +.Pp +.Bl -bullet -offset indent -compact +.It +Realtek 802.11n wireless 8188 (RTL8188EE) +.It +Realtek 802.11n wireless 8192 (RTL8192CE) +.El +.Sh SEE ALSO +.Xr pci 4 , +.Xr rtwn 4 , +.Xr rtwn_usb 4 , +.Xr rtwnfw 4 diff --git a/static/freebsd/man4/rtwn_usb.4 b/static/freebsd/man4/rtwn_usb.4 new file mode 100644 index 00000000..3a584d18 --- /dev/null +++ b/static/freebsd/man4/rtwn_usb.4 @@ -0,0 +1,134 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2011 Adrian Chadd, Xenion Pty Ltd +.\" Copyright (c) 2016 Andriy Voskoboinyk +.\" 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, +.\" without modification. +.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer +.\" similar to the "NO WARRANTY" disclaimer below ("Disclaimer") and any +.\" redistribution must be conditioned upon including a substantially +.\" similar Disclaimer requirement for further binary redistribution. +.\" +.\" NO WARRANTY +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF NONINFRINGEMENT, MERCHANTIBILITY +.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL +.\" THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR 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 DAMAGES. +.\" +.Dd November 10, 2024 +.Dt RTWN_USB 4 +.Os +.Sh NAME +.Nm rtwn_usb +.Nd Realtek wireless rtwn network driver USB support +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device xhci" +.Cd "device ehci" +.Cd "device uhci" +.Cd "device ohci" +.Cd "device usb" +.Cd "device rtwn" +.Cd "device rtwn_usb" +.Cd "device wlan" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for USB wireless network devices to the +.Xr rtwn 4 +driver. +.Sh HARDWARE +The +.Nm +driver supports USB wireless network adapters based on certain +Realtek RTL 8188/8192/8812 and 8821 chipsets, including: +.Pp +.Bl -column -compact "Belkin F7D1102 Surf Wireless Micro" "RTL8188CUS" "USB 2.0" +.It Em Card Ta Em Chip Ta Em Bus +.It "Alfa AWUS036NHR v2" Ta RTL8188RU Ta USB 2.0 +.It "ASUS USB-AC56" Ta RTL8812AU Ta USB 3.0 +.It "ASUS USB-N10 NANO" Ta RTL8188CUS Ta USB 2.0 +.It "ASUS USB-N10 NANO rev B1" Ta RTL8188EUS Ta USB 2.0 +.It "Asus USB-N13, rev. B1" Ta RTL8192CU Ta USB 2.0 +.It "Belkin F7D1102 Surf Wireless Micro" Ta RTL8188CUS Ta USB 2.0 +.It "Buffalo WI-U2-433DHP" Ta RTL8821AU Ta USB 2.0 +.It "Buffalo WI-U2-433DM" Ta RTL8821AU Ta USB 2.0 +.It "Buffalo WI-U3-866D" Ta RTL8812AU Ta USB 3.0 +.It "D-Link DWA-121 rev C1A (N150 Nano)" Ta RTL8188EU Ta USB 2.0 +.It "D-Link DWA-123 rev D1" Ta RTL8188EU Ta USB 2.0 +.It "D-Link DWA-125 rev D1" Ta RTL8188EU Ta USB 2.0 +.It "D-Link DWA-131" Ta RTL8192CU Ta USB 2.0 +.It "D-Link DWA-131 rev E1" Ta RTL8192EU Ta USB 2.0 +.It "D-Link DWA-171 rev A1" Ta RTL8821AU Ta USB 2.0 +.It "D-Link DWA-172 rev A1" Ta RTL8821AU Ta USB 2.0 +.It "D-Link DWA-180 rev A1" Ta RTL8812AU Ta USB 2.0 +.It "D-Link DWA-182 rev C1" Ta RTL8812AU Ta USB 3.0 +.It "Edimax EW-7811Un" Ta RTL8188CUS Ta USB 2.0 +.It "Edimax EW-7811UTC" Ta RTL8821AU Ta USB 2.0 +.It "Edimax EW-7822UAC" Ta RTL8812AU Ta USB 3.0 +.It "EDUP EP-AC1620" Ta RTL8821AU Ta USB 2.0 +.It "Elecom WDC-150SU2M" Ta RTL8188EU Ta USB 2.0 +.It "EnGenius EUB1200AC" Ta RTL8812AU Ta USB 3.0 +.It "Foxconn WFUR6" Ta RTL8812AU Ta USB 2.0 +.It "Hawking HD65U" Ta RTL8821AU Ta USB 2.0 +.It "Hercules Wireless N USB Pico" Ta RTL8188CUS Ta USB 2.0 +.It "I-O Data WN-AC867U" Ta RTL8812AU Ta USB 3.0 +.It "Linksys WUSB6300" Ta RTL8812AU Ta USB 3.0 +.It "NEC AtermWL900U PA-WL900U" Ta RTL8812AU Ta USB 3.0 +.It "Netgear A6100" Ta RTL8821AU Ta USB 2.0 +.It "Netgear WNA1000M" Ta RTL8188CUS Ta USB 2.0 +.It "Mercusys MW150US" Ta RTL8188EU Ta USB 2.0 +.It "Planex GW-900D" Ta RTL8812AU Ta USB 3.0 +.It "Realtek RTL8192CU" Ta RTL8192CU Ta USB 2.0 +.It "Realtek RTL8188CUS" Ta RTL8188CUS Ta USB 2.0 +.It "Sitecom WLA-7100" Ta RTL8812AU Ta USB 3.0 +.It "TP-Link Archer T2U Nano" Ta RTL8821AU Ta USB 2.0 +.It "TP-Link Archer T2U Plus" Ta RTL8821AU Ta USB 2.0 +.It "TP-Link Archer T2U v3" Ta RTL8821AU Ta USB 2.0 +.It "TP-Link Archer T4U" Ta RTL8812AU Ta USB 3.0 +.It "TP-Link Archer T4U v2" Ta RTL8812AU Ta USB 3.0 +.It "TP-Link Archer T4UH v1" Ta RTL8812AU Ta USB 3.0 +.It "TP-Link Archer T4UH v2" Ta RTL8812AU Ta USB 3.0 +.It "TP-Link TL-WN722N v2" Ta RTL8188EU Ta USB 2.0 +.It "TP-LINK TL-WN723N v3" Ta RTL8188EU Ta USB 2.0 +.It "TP-LINK TL-WN725N v2" Ta RTL8188EU Ta USB 2.0 +.It "TP-LINK TL-WN727N v5" Ta RTL8188EU Ta USB 2.0 +.It "TP-LINK TL-WN821N v4" Ta RTL8192CU Ta USB 2.0 +.It "TP-LINK TL-WN821N v5" Ta RTL8192EU Ta USB 2.0 +.It "TP-LINK TL-WN822N v4" Ta RTL8192EU Ta USB 2.0 +.It "TP-LINK TL-WN823N v1" Ta RTL8192CU Ta USB 2.0 +.It "TP-LINK TL-WN823N v2" Ta RTL8192EU Ta USB 2.0 +.It "TRENDnet TEW-805UB" Ta RTL8812AU Ta USB 3.0 +.It "ZyXEL NWD6605" Ta RTL8812AU Ta USB 3.0 +.El +.Sh SEE ALSO +.Xr rtwn 4 , +.Xr rtwn_pci 4 , +.Xr rtwnfw 4 , +.Xr usb 4 +.Sh BUGS +The +.Nm +driver does not support any of the 802.11ac capabilities offered by the +adapters. +Additional work is required in +.Xr ieee80211 9 +before those features can be supported. diff --git a/static/freebsd/man4/rtwnfw.4 b/static/freebsd/man4/rtwnfw.4 new file mode 100644 index 00000000..98e3ef0c --- /dev/null +++ b/static/freebsd/man4/rtwnfw.4 @@ -0,0 +1,92 @@ +.\" Copyright (c) 2015 Kevin Lo +.\" Copyright (c) 2016 Andriy Voskoboinyk +.\" 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. 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 January 3, 2019 +.Dt RTWNFW 4 +.Os +.Sh NAME +.Nm rtwnfw +.Nd "Firmware Module for Realtek Wireless driver" +.Sh SYNOPSIS +To compile this module into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device rtwnfw" +.Ed +.Pp +This will include all firmware images inside the kernel. +If you want to pick only the firmware image for your network adapter choose one +of the following: +.Bd -ragged -offset indent +.Cd "device rtwn-rtl8188eefw" +.Cd "device rtwn-rtl8188eufw" +.Cd "device rtwn-rtl8192cfwE_B" +.Cd "device rtwn-rtl8192cfwE" +.Cd "device rtwn-rtl8192cfwT" +.Cd "device rtwn-rtl8192cfwU" +.Cd "device rtwn-rtl8192eufw" +.Cd "device rtwn-rtl8812aufw" +.Cd "device rtwn-rtl8821aufw" +.Ed +.Pp +Alternatively, to load all firmware images as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +rtwn-rtl8188eefw_load="YES" +rtwn-rtl8188eufw_load="YES" +rtwn-rtl8192cfwE_B_load="YES" +rtwn-rtl8192cfwE_load="YES" +rtwn-rtl8192cfwT_load="YES" +rtwn-rtl8192cfwU_load="YES" +rtwn-rtl8192eufw_load="YES" +rtwn-rtl8812aufw_load="YES" +rtwn-rtl8821aufw_load="YES" +.Ed +.Sh DESCRIPTION +rtwn-rtl8192cfwE and rtl8192cfwE_B modules provide access +to firmware sets for the Realtek RTL8188CE chip based PCIe adapters. +rtwn-rtl8188ee module provides access to firmware sets for the +Realtek RTL8188EE chip based PCIe adapters. +Other modules provide access to firmware sets for the Realtek RTL8188CUS, +RTL8188CE-VAU, RTL8188EUS, RTL8188RU, RTL8192CU, RTL8192EU, RTL8812AU and +RTL8821AU chip based USB WiFi adapters. +They may be +statically linked into the kernel, or loaded as a modules. +.Pp +For the loaded firmware to be enabled for use the license at +.Pa /usr/share/doc/legal/realtek.LICENSE +must be agreed to by adding the following line to +.Xr loader.conf 5 : +.Pp +.Dl "legal.realtek.license_ack=1" +.Sh FILES +.Bl -tag -width ".Pa /usr/share/doc/legal/realtek.LICENSE" -compact +.It Pa /usr/share/doc/legal/realtek.LICENSE +.Nm +firmware license +.El +.Sh SEE ALSO +.Xr rtwn 4 , +.Xr firmware 9 diff --git a/static/freebsd/man4/rue.4 b/static/freebsd/man4/rue.4 new file mode 100644 index 00000000..b26acd57 --- /dev/null +++ b/static/freebsd/man4/rue.4 @@ -0,0 +1,153 @@ +.\" +.\" Copyright (c) 2001-2003, Shunsuke Akiyama . +.\" 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 November 24, 2015 +.Dt RUE 4 +.Os +.Sh NAME +.Nm rue +.Nd "Realtek RTL8150 USB to Fast Ethernet controller driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device uhci" +.Cd "device ohci" +.Cd "device usb" +.Cd "device miibus" +.Cd "device uether" +.Cd "device rue" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_rue_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for USB Ethernet adapters based on the Realtek +RTL8150 USB to Fast Ethernet controller chip. +.Pp +The RTL8150 contains an integrated Fast Ethernet MAC, which supports +both 10 and 100Mbps speeds in either full or half duplex. +Although designed to interface with +100Mbps peripheral, the existing USB standard specifies a maximum +transfer speed of 12Mbps. +Users should therefore not expect to actually +achieve 100Mbps speeds with this device. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width ".Cm 10baseT/UTP" +.It Cm autoselect +Enable auto selection of the media type and options. +The user can manually override +the auto selected mode by adding media options to the +.Pa /etc/rc.conf +file. +.It Cm 10baseT/UTP +Set 10Mbps operation. +The +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 100baseTX +Set 100Mbps (Fast Ethernet) operation. +The +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width ".Cm 10baseT/UTP" +.It Cm full-duplex +Force full duplex operation. +.It Cm half-duplex +Force half duplex operation. +.El +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports Realtek RTL8150 based USB Ethernet +adapters including: +.Pp +.Bl -bullet -compact +.It +Buffalo (Melco Inc.) LUA-KTX +.It +Green House GH-USB100B +.It +LinkSys USB100M +.It +Billionton 10/100 FastEthernet USBKR2 +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "rue%d: watchdog timeout" +A packet was queued for transmission and a transmit command was +issued, however the device failed to acknowledge the transmission +before a timeout expired. +.It "rue%d: rx list init failed" +The driver failed to allocate an mbuf for the transmitter ring. +.It "rue%d: no memory for rx list" +The driver failed to allocate an mbuf for the receiver ring. +.El +.Sh SEE ALSO +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr ifconfig 8 +.Rs +.%T "Realtek RTL8150 data sheet" +.%U http://pdf.seekdatasheet.com/2008714/200807142333305235.pdf +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 5.1 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Shunsuke Akiyama Aq Mt akiyama@FreeBSD.org . diff --git a/static/freebsd/man4/rum.4 b/static/freebsd/man4/rum.4 new file mode 100644 index 00000000..8e77839b --- /dev/null +++ b/static/freebsd/man4/rum.4 @@ -0,0 +1,185 @@ +.\"- +.\" SPDX-License-Identifier: ISC +.\" +.\" Copyright (c) 2005-2007 +.\" Damien Bergamini +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd November 10, 2024 +.Dt RUM 4 +.Os +.Sh NAME +.Nm rum +.Nd Ralink Technology USB IEEE 802.11a/b/g wireless network driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ehci" +.Cd "device uhci" +.Cd "device ohci" +.Cd "device usb" +.Cd "device rum" +.Cd "device wlan" +.Cd "device wlan_amrr" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_rum_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports USB 2.0 and PCI Express Mini Card wireless adapters +based on the Ralink RT2501USB and RT2601USB chipsets. +.Pp +Ralink PCI Express Mini Card adapters show up as normal USB 2.0 +devices and are thus handled by the +.Nm +driver. +.Pp +The RT2501USB chipset is the second generation of 802.11a/b/g adapters from +Ralink. +It consists of two integrated chips, an RT2571W MAC/BBP and an RT2528 or +RT5226 radio transceiver. +.Pp +The RT2601USB chipset consists of two integrated chips, an RT2671 +MAC/BBP and an RT2527 or RT5225 radio transceiver. +This chipset uses the MIMO (multiple-input multiple-output) technology +with multiple antennas to extend the operating range of the adapter +and to achieve higher throughput. +.Pp +All chips have hardware support for WEP, AES-CCM, TKIP, and Michael +cryptographic operations. +.Pp +.Nm +supports +.Cm station , +.Cm adhoc , +.Cm adhoc-demo , +.Cm hostap , +and +.Cm monitor +mode operation. +Only one virtual interface may be configured at any time. +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports USB 2.0 wireless +adapters based on the Ralink RT2501USB and RT2601USB chipsets, +including: +.Pp +.Bl -column -compact "Atlantis Land A02-PCM-W54" "Bus" +.It Em Card Ta Em Bus +.It "3Com Aolynk WUB320g" Ta USB +.It "Abocom WUG2700 Ta" Ta USB +.It "Airlink101 AWLL5025" Ta USB +.It "ASUS WL-167g ver 2" Ta USB +.It "Belkin F5D7050 ver 3" Ta USB +.It "Belkin F5D9050 ver 3" Ta USB +.It "Buffalo WLI-U2-SG54HP" Ta USB +.It "Buffalo WLI-U2-SG54HG" Ta USB +.It "Buffalo WLI-U2-G54HP" Ta USB +.It "Buffalo WLI-UC-G" Ta USB +.It "CNet CWD-854 ver F" Ta USB +.It "Conceptronic C54RU ver 2" Ta USB +.It "Corega CG-WLUSB2GO" Ta USB +.It "D-Link DWA-110" Ta USB +.It "D-Link DWA-111" Ta USB +.It "D-Link DWL-G122 rev C1" Ta USB +.It "D-Link WUA-1340" Ta USB +.It "Digitus DN-7003GR" Ta USB +.It "Edimax EW-7318USG" Ta USB +.It "Gigabyte GN-WB01GS" Ta USB +.It "Gigabyte GN-WI05GS" Ta USB +.It "Hawking HWUG1" Ta USB +.It "Hawking HWU54DM" Ta USB +.It "Hercules HWGUSB2-54-LB" Ta USB +.It "Hercules HWGUSB2-54V2-AP" Ta USB +.It "LevelOne WNC-0301USB v3" Ta USB +.It "Linksys WUSB54G rev C" Ta USB +.It "Linksys WUSB54GR" Ta USB +.It "Planex GW-US54HP" Ta USB +.It "Planex GW-US54Mini2" Ta USB +.It "Planex GW-USMM" Ta USB +.It "Senao NUB-3701" Ta USB +.It "Sitecom WL-113 ver 2" Ta USB +.It "Sitecom WL-172" Ta USB +.It "Sweex LW053" Ta USB +.It "TP-LINK TL-WN321G v1/v2/v3" Ta USB +.El +.Sh EXAMPLES +Join an existing BSS network (i.e., connect to an access point): +.Pp +.Dl ifconfig wlan create wlandev rum0 inet 192.0.2.20/24 +.Pp +Join a specific BSS network with network name +.Ar my_net : +.Pp +.Dl ifconfig wlan create wlandev rum0 ssid my_net up +.Pp +Join a specific BSS network with 64-bit WEP encryption: +.Bd -literal -offset indent +ifconfig wlan create wlandev rum0 ssid my_net \e + wepmode on wepkey 0x1234567890 weptxkey 1 up +.Ed +.Pp +Join a specific BSS network with 128-bit WEP encryption: +.Bd -literal -offset indent +ifconfig wlan create wlandev rum0 wlanmode adhoc ssid my_net \e + wepmode on wepkey 0x01020304050607080910111213 weptxkey 1 +.Ed +.Sh DIAGNOSTICS +.Bl -diag +.It "rum%d: could not load 8051 microcode" +An error occurred while attempting to upload the microcode to the onboard 8051 +microcontroller unit. +The driver will reset the hardware. +This should not happen. +.El +.Sh SEE ALSO +.Xr intro 4 , +.Xr netintro 4 , +.Xr usb 4 , +.Xr wlan 4 , +.Xr wlan_amrr 4 , +.Xr wlan_ccmp 4 , +.Xr wlan_tkip 4 , +.Xr wlan_wep 4 , +.Xr wlan_xauth 4 , +.Xr networking 7 , +.Xr hostapd 8 , +.Xr ifconfig 8 , +.Xr wpa_supplicant 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Ox 4.0 +and +.Fx 7.0 . +.Sh AUTHORS +.An -nosplit +The original +.Nm +driver was written by +.An Niall O'Higgins Aq Mt niallo@openbsd.org +and +.An Damien Bergamini Aq Mt damien@openbsd.org . diff --git a/static/freebsd/man4/run.4 b/static/freebsd/man4/run.4 new file mode 100644 index 00000000..c3d9d75f --- /dev/null +++ b/static/freebsd/man4/run.4 @@ -0,0 +1,319 @@ +.\"- +.\" SPDX-License-Identifier: ISC +.\" +.\" $OpenBSD: run.4,v 1.22 2009/11/23 06:16:32 jmc Exp $ +.\" +.\" Copyright (c) 2008 Damien Bergamini +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd April 1, 2025 +.Dt RUN 4 +.Os +.Sh NAME +.Nm run +.Nd Ralink Technology USB IEEE 802.11a/g/n wireless network driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ehci" +.Cd "device uhci" +.Cd "device ohci" +.Cd "device usb" +.Cd "device run" +.Cd "device wlan" +.Cd "device wlan_amrr" +.Ed +.Pp +Firmware is also needed, and provided by: +.Bd -ragged -offset indent +.Cd "device runfw" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_run_load="YES" +runfw_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports USB 2.0 wireless adapters based on the Ralink RT2700U, +RT2800U, RT3000U and RT3900E chipsets. +.Pp +The RT2700U chipset consists of two integrated chips, an RT2770 MAC/BBP and +an RT2720 (1T2R) or RT2750 (dual-band 1T2R) radio transceiver. +.Pp +The RT2800U chipset consists of two integrated chips, an RT2870 MAC/BBP and +an RT2820 (2T3R) or RT2850 (dual-band 2T3R) radio transceiver. +.Pp +The RT3000U is a single-chip solution based on an RT3070 MAC/BBP and +an RT3020 (1T1R), RT3021 (1T2R) or RT3022 (2T2R) single-band radio +transceiver. +.Pp +The RT3900E is a single-chip USB 2.0 802.11n solution. +The MAC/Baseband Processor can be an RT3593, RT5390, RT5392 or an RT5592. +The radio can be an RT3053, RT5370, RT5372 or an RT5572. +The RT3053 chip operates in the 2GHz and 5GHz spectra and supports up to +3 transmit paths and 3 receiver paths (3T3R). +The RT5370 chip operates in the 2GHz spectrum and supports 1 transmit path +and 1 receiver path (1T1R). +The RT5372 chip operates in the 2GHz spectrum and supports up to 2 transmit +paths and 2 receiver paths (2T2R). +The RT5572 chip operates in the 2GHz and 5GHz spectra and supports up to +2 transmit paths and 2 receiver paths (2T2R). +.Pp +These are the modes the +.Nm +driver can operate in: +.Bl -tag -width "IBSS-masterXX" +.It BSS mode +Also known as +.Em infrastructure +mode, this is used when associating with an access point, through +which all traffic passes. +This mode is the default. +.It Host AP mode +In this mode the driver acts as an access point (base station) +for other cards. +.It monitor mode +In this mode the driver is able to receive packets without +associating with an access point. +This disables the internal receive filter and enables the card to +capture packets from networks which it wouldn't normally have access to, +or to scan for access points. +.El +.Pp +The +.Nm +driver can be configured to use +Wired Equivalent Privacy (WEP) or +Wi-Fi Protected Access (WPA-PSK and WPA2-PSK). +WPA is the de facto encryption standard for wireless networks. +It is strongly recommended that WEP +not be used as the sole mechanism +to secure wireless communication, +due to serious weaknesses in it. +The +.Nm +driver offloads both encryption and decryption of data frames to the +hardware for the WEP40, WEP104, TKIP(+MIC) and CCMP ciphers. +.Pp +The +.Nm +driver can be configured at runtime with +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports the following wireless adapters: +.Pp +.Bl -bullet -offset indent -compact +.It +Airlink101 AWLL6090 +.It +ASUS USB-N11 +.It +ASUS USB-N13 ver. A1 +.It +ASUS USB-N14 +.It +ASUS USB-N66 +.It +ASUS WL-160N +.It +Belkin F5D8051 ver 3000 +.It +Belkin F5D8053 +.It +Belkin F5D8055 +.It +Belkin F6D4050 ver 1 +.It +Belkin F9L1103 +.It +Buffalo WLI-UC-AG300N +.It +Buffalo WLI-UC-G300HP +.It +Buffalo WLI-UC-G300N +.It +Buffalo WLI-UC-G301N +.It +Buffalo WLI-UC-GN +.It +Buffalo WLI-UC-GNM +.It +Buffalo WLI-UC-GNM2 +.It +Corega CG-WLUSB2GNL +.It +Corega CG-WLUSB2GNR +.It +Corega CG-WLUSB300AGN +.It +Corega CG-WLUSB300GNM +.It +D-Link DWA-130 rev B1 +.It +D-Link DWA-130 rev F1 +.It +D-Link DWA-140 rev B1, B2, B3, \&D1 +.It +D-Link DWA-160 rev B2 +.It +D-Link DWA-162 +.It +DrayTek Vigor N61 +.It +Edimax EW-7711UAn +.It +Edimax EW-7711UTn +.It +Edimax EW-7717Un +.It +Edimax EW-7718Un +.It +Edimax EW-7733UnD +.It +Gigabyte GN-WB30N +.It +Gigabyte GN-WB31N +.It +Gigabyte GN-WB32L +.It +Hawking HWDN1 +.It +Hawking HWUN1 +.It +Hawking HWUN2 +.It +Hercules HWNU-300 +.It +Linksys WUSB54GC v3 +.It +Linksys WUSB600N +.It +Logitec LAN-W150N/U2 +.It +Mvix Nubbin MS-811N +.It +Panda Wireless PAU06 +.It +Planex GW-USMicroN +.It +Planex GW-US300MiniS +.It +Sitecom WL-182 +.It +Sitecom WL-188 +.It +Sitecom WL-301 +.It +Sitecom WL-302 +.It +Sitecom WL-315 +.It +Sitecom WL-364 +.It +SMC SMCWUSBS-N2 +.It +Sweex LW303 +.It +Sweex LW313 +.It +TP-LINK TL-WDN3200 +.It +TP-LINK TL-WN321G v4 +.It +TP-LINK TL-WN727N v3 +.It +Unex DNUR-81 +.It +Unex DNUR-82 +.It +ZyXEL NWD2705 +.It +ZyXEL NWD210N +.It +ZyXEL NWD270N +.El +.Sh EXAMPLES +Join an existing BSS network (i.e., connect to an access point): +.Pp +.Dl ifconfig wlan create wlandev run0 inet 192.0.2.20/24 +.Pp +Join a specific BSS network with network name +.Ar my_net : +.Pp +.Dl ifconfig wlan create wlandev run0 ssid my_net up +.Pp +Join a specific BSS network with 64-bit WEP encryption: +.Bd -literal -offset indent +ifconfig wlan create wlandev run0 ssid my_net \e + wepmode on wepkey 0x1234567890 weptxkey 1 up +.Ed +.Pp +Join a specific BSS network with 128-bit WEP encryption: +.Bd -literal -offset indent +ifconfig wlan create wlandev run0 wlanmode adhoc ssid my_net \e + wepmode on wepkey 0x01020304050607080910111213 weptxkey 1 +.Ed +.Sh DIAGNOSTICS +.Bl -diag +.It "run%d: failed load firmware of file runfw" +For some reason, the driver was unable to read the microcode file from the +filesystem. +The file might be missing or corrupted. +.It "run%d: could not load 8051 microcode" +An error occurred while attempting to upload the microcode to the onboard 8051 +microcontroller unit. +.It "run%d: device timeout" +A frame dispatched to the hardware for transmission did not complete in time. +The driver will reset the hardware. +This should not happen. +.El +.Sh SEE ALSO +.Xr intro 4 , +.Xr netintro 4 , +.Xr runfw 4 , +.Xr usb 4 , +.Xr wlan 4 , +.Xr wlan_amrr 4 , +.Xr wlan_ccmp 4 , +.Xr wlan_tkip 4 , +.Xr wlan_wep 4 , +.Xr wlan_xauth 4 , +.Xr networking 7 , +.Xr hostapd 8 , +.Xr ifconfig 8 , +.Xr wpa_supplicant 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Ox 4.5 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Damien Bergamini Aq Mt damien@openbsd.org . +.Sh CAVEATS +The +.Nm +driver supports some of the 11n capabilities found in the +RT2800, RT3000 and RT3900 chipsets. diff --git a/static/freebsd/man4/runfw.4 b/static/freebsd/man4/runfw.4 new file mode 100644 index 00000000..55942908 --- /dev/null +++ b/static/freebsd/man4/runfw.4 @@ -0,0 +1,48 @@ +.\" Copyright (c) 2010 Akinori Furukoshi +.\" Copyright (c) 2010 Warren Block +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" 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 November 11, 2013 +.Dt RUNFW 4 +.Os +.Sh NAME +.Nm runfw +.Nd "Firmware Module for Ralink driver" +.Sh SYNOPSIS +To compile this module into the kernel, place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device runfw" +.Ed +.Pp +This will include two firmware images, RT2870 and RT3071, inside the kernel. +.Xr run 4 +will load the appropriate image into the chip. +.Pp +Alternatively, to load the firmware images as a module at boot time, place +the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +runfw_load="YES" +.Ed +.Sh DESCRIPTION +This module provides firmware sets for the Ralink RT2700U, +RT2800U, RT3000U and RT3900E chip based USB WiFi adapters. +Please read Ralink's license, src/sys/contrib/dev/run/LICENSE. +.Sh SEE ALSO +.Xr run 4 , +.Xr firmware 9 diff --git a/static/freebsd/man4/sa.4 b/static/freebsd/man4/sa.4 new file mode 100644 index 00000000..6c948a0f --- /dev/null +++ b/static/freebsd/man4/sa.4 @@ -0,0 +1,500 @@ +.\" Copyright (c) 1996 +.\" Julian Elischer . 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 January 18, 2022 +.Dt SA 4 +.Os +.Sh NAME +.Nm sa +.Nd SCSI Sequential Access device driver +.Sh SYNOPSIS +.Cd device sa +.Sh DESCRIPTION +The +.Nm +driver provides support for all +.Tn SCSI +devices of the sequential access class that are attached to the system +through a supported +.Tn SCSI +Host Adapter. +The sequential access class includes tape and other linear access devices. +.Pp +A +.Tn SCSI +Host +adapter must also be separately configured into the system +before a +.Tn SCSI +sequential access device can be configured. +.Sh MOUNT SESSIONS +The +.Nm +driver is based around the concept of a +.Dq Em mount session , +which is defined as the period between the time that a tape is +mounted, and the time when it is unmounted. +Any parameters set during +a mount session remain in effect for the remainder of the session or +until replaced. +The tape can be unmounted, bringing the session to a +close in several ways. +These include: +.Bl -enum +.It +Closing a `rewind device', +referred to as sub-mode 00 below. +An example is +.Pa /dev/sa0 . +.It +Using the MTOFFL +.Xr ioctl 2 +command, reachable through the +.Sq Cm offline +command of +.Xr mt 1 . +.El +.Pp +It should be noted that tape devices are exclusive open devices, except in +the case where a control mode device is opened. +In the latter case, exclusive +access is only sought when needed (e.g., to set parameters). +.Sh SUB-MODES +The sub-modes differ in the action taken when the device is closed: +.Bl -tag -width XXXX +.It Pa /dev/sa* +A close will rewind the device; if the tape has been +written, then a file mark will be written before the rewind is requested. +The device is unmounted. +.It Pa /dev/nsa* +A close will leave the tape mounted. +If the tape was written to, a file mark will be written. +No other head positioning takes place. +Any further reads or writes will occur directly after the +last read, or the written file mark. +.It Pa /dev/esa* +A close will rewind the device. +If the tape has been +written, then a file mark will be written before the rewind is requested. +On completion of the rewind an unload command will be issued. +The device is unmounted. +.El +.Sh BLOCKING MODES +.Tn SCSI +tapes may run in either +.Sq Em variable +or +.Sq Em fixed +block-size modes. +Most +.Tn QIC Ns -type +devices run in fixed block-size mode, where most nine-track tapes and +many new cartridge formats allow variable block-size. +The difference between the two is as follows: +.Bl -inset +.It Variable block-size: +Each write made to the device results in a single logical record +written to the tape. +One can never read or write +.Em part +of a record from tape (though you may request a larger block and read +a smaller record); nor can one read multiple blocks. +Data from a single write is therefore read by a single read. +The block size used +may be any value supported by the device, the +.Tn SCSI +adapter and the system (usually between 1 byte and 64 Kbytes, +sometimes more). +.Pp +When reading a variable record/block from the tape, the head is +logically considered to be immediately after the last item read, +and before the next item after that. +If the next item is a file mark, +but it was never read, then the next +process to read will immediately hit the file mark and receive an end-of-file notification. +.It Fixed block-size: +Data written by the user is passed to the tape as a succession of +fixed size blocks. +It may be contiguous in memory, but it is +considered to be a series of independent blocks. +One may never write +an amount of data that is not an exact multiple of the blocksize. +One may read and write the same data as a different set of records. +In other words, blocks that were written together may be read separately, +and vice-versa. +.Pp +If one requests more blocks than remain in the file, the drive will +encounter the file mark. +As there is some data to return (unless +there were no records before the file mark), the read will succeed, +returning that data. +The next read will return immediately with a value +of 0. +(As above, if the file mark is never read, it remains for the next +process to read if in no-rewind mode.) +.El +.Sh BLOCK SIZES +By default, the driver will NOT accept reads or writes to a tape device that +are larger than may be written to or read from the mounted tape using a single +write or read request. +Because of this, the application author may have confidence that his wishes +are respected in terms of the block size written to tape. +For example, if the user tries to write a 256KB block to the tape, but the +controller can handle no more than 128KB, the write will fail. +The previous +.Fx +behavior, prior to +.Fx +10.0, +was to break up large reads or writes into smaller blocks when going to the +tape. +The problem with that behavior, though, is that it hides the actual on-tape +block size from the application writer, at least in variable block mode. +.Pp +If the user would like his large reads and writes broken up into separate +pieces, he may set the following loader tunables. +Note that these tunables WILL GO AWAY in +.Fx 11.0 . +They are provided for transition purposes only. +.Bl -tag -width 12 +.It kern.cam.sa.allow_io_split +.Pp +This variable, when set to 1, will configure all +.Nm +devices to split large buffers into smaller pieces when needed. +.It kern.cam.sa.%d.allow_io_split +.Pp +This variable, when set to 1, will configure the given +.Nm +unit to split large buffers into multiple pieces. +This will override the global setting, if it exists. +.El +.Pp +There are several +.Xr sysctl 8 +variables available to view block handling parameters: +.Bl -tag -width 12 +.It kern.cam.sa.%d.allow_io_split +.Pp +This variable allows the user to see, but not modify, the current I/O split +setting. +The user is not permitted to modify this setting so that there is no chance +of behavior changing for the application while a tape is mounted. +.It kern.cam.sa.%d.maxio +.Pp +This variable shows the maximum I/O size in bytes that is allowed by the +combination of kernel tuning parameters (MAXPHYS, DFLTPHYS) and the +capabilities of the controller that is attached to the tape drive. +Applications may look at this value for a guide on how large an I/O may be +permitted, but should keep in mind that the actual maximum may be +restricted further by the tape drive via the +.Tn SCSI +READ BLOCK LIMITS command. +.It kern.cam.sa.%d.cpi_maxio +.Pp +This variable shows the maximum I/O size supported by the controller, in +bytes, that is reported via the CAM Path Inquiry CCB (XPT_PATH_INQ). +If this is 0, that means that the controller has not reported a maximum I/O +size. +.El +.Sh FILE MARK HANDLING +The handling of file marks on write is automatic. +If the user has +written to the tape, and has not done a read since the last write, +then a file mark will be written to the tape when the device is +closed. +If a rewind is requested after a write, then the driver +assumes that the last file on the tape has been written, and ensures +that there are two file marks written to the tape. +The exception to +this is that there seems to be a standard (which we follow, but do not +understand why) that certain types of tape do not actually write two +file marks to tape, but when read, report a `phantom' file mark when the +last file is read. +These devices include the QIC family of devices. +(It might be that this set of devices is the same set as that of fixed +block devices. +This has not been determined yet, and they are treated +as separate behaviors by the driver at this time.) +.Sh PARAMETERS +The +.Nm +driver supports a number of parameters. +The user can query parameters using +.Dq mt param -l +(which uses the +.Dv MTIOCPARAMGET +ioctl) and the user can set parameters using +.Dq mt param -s +(which uses the +.Dv MTIOCPARAMSET +ioctl). +See +.Xr mt 1 +and +.Xr mtio 4 +for more details on the interface. +.Pp +Supported parameters: +.Bl -tag -width 5n +.It sili +The default is 0. +When set to 1, it sets the Suppress Incorrect Length Indicator (SILI) bit +on tape reads. +Tape drives normally return sense data (which contains the residual) when the +application reads a block that is not the same length as the amount of data +requested. +The SILI bit suppresses that notification in most cases. +See the SSC-5 spec (available at t10.org), specifically the section on the +READ(6) command, for more information. +.It eot_warn +The default is 0. +By default, the +.Nm +driver reports entering Programmable Early Warning, Early Warning and End +of Media conditions by returning a write with 0 bytes written, and +.Dv errno +set to 0. +If +.Va eot_warn +is set to 1, the +.Nm +driver will set +.Dv errno +to +.Dv ENOSPC +when it enters any of the out of space conditions. +.It protection.protection_supported +This is a read-only parameter, and is set to 1 if the tape drive supports +protection information. +.It protection.prot_method +If protection is supported, set this to the desired protection method +supported by the tape drive. +As of SSC-5r03 (available at t10.org), the protection method values are: +.Bl -tag -width 3n +.It 0 +No protection. +.It 1 +Reed-Solomon CRC, 4 bytes in length. +.It 2 +CRC32C, 4 bytes in length. +.El +.It protection.pi_length +Length of the protection information, see above for lengths. +.It protection.lbp_w +If set to 1, enable logical block protection on writes. +The CRC must be appended to the end of the block written to the tape driver. +The tape drive will verify the CRC when it receives the block. +.It protection.lbp_r +If set to 1, enable logical block protection on reads. +The CRC will be appended to the end of the block read from the tape driver. +The application should verify the CRC when it receives the block. +.It protection.rdbp +If set to 1, enable logical block protection on the RECOVER BUFFERED DATA +command. +The +.Nm +driver does not currently use the +RECOVER BUFFERED DATA command. +.El +.Sh TIMEOUTS +The +.Nm +driver has a set of default timeouts for SCSI commands (READ, WRITE, TEST UNIT +READY, etc.) that will likely work in most cases for many tape drives. +.Pp +For newer tape drives that claim to support the SPC-4 +standard (SCSI Primary Commands 4) or later standards, the +.Nm +driver will attempt to use the REPORT SUPPORTED OPERATION CODES command to +fetch timeout descriptors from the drive. +If the drive does report timeout descriptors, the +.Nm +driver will use the drive's recommended timeouts for commands. +.Pp +The timeouts in use are reported in units of +.Sy thousandths +of a second via the +.Va kern.cam.sa.%d.timeout.* +.Xr sysctl 8 +variables. +.Pp +To override either the default timeouts, or the timeouts recommended by the +drive, you can set one of two sets of loader tunable values. +If you have a drive that supports the REPORT SUPPORTED OPERATION CODES +timeout descriptors (see the +.Xr camcontrol 8 +.Va opcodes +subcommand) it is generally best to use those values. +The global +.Va kern.cam.sa.timeout.* +values will override the timeouts for all +.Nm +driver instances. +If there are 5 tape drives in the system, they'll all get the same timeouts. +The +.Va kern.cam.sa.%d.timeout.* +values (where %d is the numeric +.Nm +instance number) will override the global timeouts as well as either the +default timeouts or the timeouts recommended by the drive. +.Pp +To set timeouts after boot, the per-instance timeout values, for example: +.Va kern.cam.sa.0.timeout.read , +are available as sysctl variables. +.Pp +If a tape drive arrives after boot, the global tunables or per-instance +tunables that apply to the newly arrived drive will be used. +.Pp +Loader tunables: +.Pp +.Bl -tag -compact +.It kern.cam.sa.timeout.erase +.It kern.cam.sa.timeout.locate +.It kern.cam.sa.timeout.mode_select +.It kern.cam.sa.timeout.mode_sense +.It kern.cam.sa.timeout.prevent +.It kern.cam.sa.timeout.read +.It kern.cam.sa.timeout.read_position +.It kern.cam.sa.timeout.read_block_limits +.It kern.cam.sa.timeout.report_density +.It kern.cam.sa.timeout.reserve +.It kern.cam.sa.timeout.rewind +.It kern.cam.sa.timeout.space +.It kern.cam.sa.timeout.tur +.It kern.cam.sa.timeout.write +.It kern.cam.sa.timeout.write_filemarks +.El +.Pp +Loader tunable values and +.Xr sysctl 8 +values: +.Pp +.Bl -tag -compact +.It kern.cam.sa.%d.timeout.erase +.It kern.cam.sa.%d.timeout.locate +.It kern.cam.sa.%d.timeout.mode_select +.It kern.cam.sa.%d.timeout.mode_sense +.It kern.cam.sa.%d.timeout.prevent +.It kern.cam.sa.%d.timeout.read +.It kern.cam.sa.%d.timeout.read_position +.It kern.cam.sa.%d.timeout.read_block_limits +.It kern.cam.sa.%d.timeout.report_density +.It kern.cam.sa.%d.timeout.reserve +.It kern.cam.sa.%d.timeout.rewind +.It kern.cam.sa.%d.timeout.space +.It kern.cam.sa.%d.timeout.tur +.It kern.cam.sa.%d.timeout.write +.It kern.cam.sa.%d.timeout.write_filemarks +.El +.Pp +As mentioned above, the timeouts are set and reported in +.Sy thousandths +of a second, so be sure to account for that when setting them. +.Sh IOCTLS +The +.Nm +driver supports all of the ioctls of +.Xr mtio 4 . +.Sh FILES +.Bl -tag -width /dev/[n][e]sa[0-9] -compact +.It Pa /dev/[n][e]sa[0-9] +general form: +.It Pa /dev/sa0 +Rewind on close +.It Pa /dev/nsa0 +No rewind on close +.It Pa /dev/esa0 +Eject on close (if capable) +.It Pa /dev/sa0.ctl +Control mode device (to examine state while another program is +accessing the device, e.g.). +.El +.Sh DIAGNOSTICS +The +.Nm +driver supports injecting End Of Media (EOM) notification to aid +application development and testing. +EOM is indicated to the application by returning the read or write with 0 +bytes written. +In addition, when EOM is injected, the tape position status will be updated +to temporarily show Beyond of the Programmable Early Warning (BPEW) status. +To see BPEW status, use the +.Dv MTIOCEXTGET +ioctl, which is used by the +.Dq mt status +command. +To inject an EOM notification, set the +.Pp +.Va kern.cam.sa.%d.inject_eom +.Pp +sysctl variable to 1. +One EOM notification will be sent, BPEW status will be set for one position +query, and then the driver state will be reset to normal. +.Sh SEE ALSO +.Xr mt 1 , +.Xr cam 4 , +.Xr mtio 4 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written for the +.Tn CAM +.Tn SCSI +subsystem by +.An Justin T. Gibbs +and +.An Kenneth Merry . +Many ideas were gleaned from the +.Nm st +device driver written and ported from +.Tn Mach +2.5 +by +.An Julian Elischer . +.Pp +The owner of record for many years was +.An Matthew Jacob . +The current maintainer is +.An Kenneth Merry +.Sh BUGS +This driver lacks many of the hacks required to deal with older devices. +Many older +.Tn SCSI-1 +devices may not work properly with this driver yet. +.Pp +Additionally, certain +tapes (QIC tapes mostly) that were written under +.Fx +2.X +are not automatically read correctly with this driver: you may need to +explicitly set variable block mode or set to the blocksize that works best +for your device in order to read tapes written under +.Fx +2.X. +.Pp +Partitions are only supported for status information and location. +It would be nice to add support for creating and editing tape partitions. diff --git a/static/freebsd/man4/safe.4 b/static/freebsd/man4/safe.4 new file mode 100644 index 00000000..914b2dd0 --- /dev/null +++ b/static/freebsd/man4/safe.4 @@ -0,0 +1,146 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2003 Sam Leffler, Errno Consulting +.\" 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 October 31, 2025 +.Dt SAFE 4 +.Os +.Sh NAME +.Nm safe +.Nd SafeNet SafeXcel 1141/1741 crypto accelerator +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device crypto" +.Cd "device cryptodev" +.Cd "device safe" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +safe_load="YES" +.Ed +.Pp +In +.Xr sysctl.conf 5 : +.Bd -ragged -offset indent +.Cd hw.safe.debug +.Cd hw.safe.dump +.Cd hw.safe.rnginterval +.Cd hw.safe.rngbufsize +.Cd hw.safe.rngmaxalarm +.Ed +.Sh DEPRECATION NOTICE +The +.Nm +driver is deprecated and is scheduled for removal in +.Fx 16.0 . +.Sh DESCRIPTION +The +.Nm +driver supports cards containing SafeNet crypto accelerator chips. +.Pp +The +.Nm +driver registers itself to accelerate AES, +SHA1-HMAC, and NULL operations for +.Xr ipsec 4 +and +.Xr crypto 4 . +.Pp +On all models, the driver registers itself to provide random data to the +.Xr random 4 +subsystem. +Periodically the driver will poll the hardware RNG and retrieve +data for use by the system. +If the driver detects that the hardware RNG is resonating with any local +signal, it will reset the oscillators that generate random data. +Three +.Xr sysctl 8 +settings control this procedure: +.Va hw.safe.rnginterval +specifies the time, in seconds, between polling operations, +.Va hw.safe.rngbufsize +specifies the number of 32-bit words to retrieve on each poll, +and +.Va hw.safe.rngmaxalarm +specifies the threshold for resetting the oscillators. +.Pp +When the driver is compiled with +.Dv SAFE_DEBUG +defined, two +.Xr sysctl 8 +variables are provided for debugging purposes: +.Va hw.safe.debug +can be set to a non-zero value to enable debugging messages to be sent +to the console for each cryptographic operation, +.Va hw.safe.dump +is a write-only variable that can be used to force driver state to be sent +to the console. +Set this variable to +.Dq Li ring +to dump the current state of the descriptor ring, +to +.Dq Li dma +to dump the hardware DMA registers, +or +to +.Dq Li int +to dump the hardware interrupt registers. +.Sh HARDWARE +The +.Nm +driver supports the following SafeXcel chips: +.Bl -column "SafeNet 1141" "The original chipset. Supports" -offset indent +.It SafeNet 1141 Ta The original chipset. +Supports DES, Triple-DES, AES, MD5, and SHA-1 +symmetric crypto operations, RNG, public key operations, and full IPsec +packet processing. +.It SafeNet 1741 Ta A faster version of the 1141. +.El +.Sh SEE ALSO +.Xr crypt 3 , +.Xr crypto 4 , +.Xr intro 4 , +.Xr ipsec 4 , +.Xr random 4 , +.Xr crypto 7 , +.Xr crypto 9 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 5.2 . +It is deprecated in +.Fx 15.0 +and removed in +.Fx 16.0 . +.Sh BUGS +Public key support is not implemented. diff --git a/static/freebsd/man4/safexcel.4 b/static/freebsd/man4/safexcel.4 new file mode 100644 index 00000000..e14eebe4 --- /dev/null +++ b/static/freebsd/man4/safexcel.4 @@ -0,0 +1,90 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2020 Rubicon Communications, LLC (Netgate) +.\" +.\" 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 November 22, 2024 +.Dt SAFEXCEL 4 +.Os +.Sh NAME +.Nm safexcel +.Nd Inside Secure SafeXcel-IP-97 cryptographic offload engine +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device crypto" +.Cd "device cryptodev" +.Cd "device safexcel" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +safexcel_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver implements +.Xr crypto 4 +support for the cryptographic acceleration functions of the EIP-97 device +found on some Marvell systems-on-chip. +The driver can accelerate the following AES modes: +.Pp +.Bl -bullet -compact +.It +AES-CBC +.It +AES-CTR +.It +AES-XTS +.It +AES-GCM +.It +AES-CCM +.El +.Pp +.Nm +also implements SHA1 and SHA2 transforms, and can combine AES-CBC and AES-CTR +with SHA1-HMAC and SHA2-HMAC for encrypt-then-authenticate operations. +.Sh HARDWARE +The +.Nm +driver supports the cryptographic acceleration functions of the +Inside Secure EIP-97 device found on some Marvell systems-on-chip. +.Sh SEE ALSO +.Xr crypto 4 , +.Xr ipsec 4 , +.Xr random 4 , +.Xr crypto 7 , +.Xr geli 8 , +.Xr crypto 9 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 13.0 . diff --git a/static/freebsd/man4/sbp.4 b/static/freebsd/man4/sbp.4 new file mode 100644 index 00000000..1daffd10 --- /dev/null +++ b/static/freebsd/man4/sbp.4 @@ -0,0 +1,106 @@ +.\" +.\" SPDX-License-Identifier: BSD-4-Clause +.\" +.\" Copyright (c) 1998-2002 Katsushi Kobayashi and Hidetoshi Shimokawa +.\" 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 acknowledgement as bellow: +.\" +.\" This product includes software developed by K. Kobayashi +.\" +.\" 4. 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 November 11, 2025 +.Dt SBP 4 +.Os +.Sh NAME +.Nm sbp +.Nd Serial Bus Protocol 2 (SBP-2) Mass Storage Devices driver +.Sh SYNOPSIS +.Cd "kldload firewire" +.Cd "kldload cam" +.Cd "kldload sbp" +.Pp +or +.Pp +.Cd "device sbp" +.Cd "device firewire" +.Cd "device scbus" +.Cd "device da" +.Cd "device cd" +.Cd "device pass" +.Sh DESCRIPTION +The +.Nm +driver provides support for SBP-2 devices that attach to the FireWire +(IEEE 1394) port. +It should work with SBP-2 devices which the CAM layer supports, for example, +HDDs, CDROM drives and DVD drives. +.Pp +Some users familiar with +.Xr umass 4 +might wonder why the device is not detached at the CAM layer when the device +is unplugged. +It is detached only if the device has not been plugged again +during several bus resets. +This is for preventing to detach an active file system even when the +device cannot be probed correctly for some reason after a bus reset +or when the device is temporary disconnected because the user changes the bus +topology. +If you want to force to detach the device, run +.Ql fwcontrol -r +several times or set +.Va hw.firewire.hold_count=0 +by +.Xr sysctl 8 . +.Pp +Some (broken) HDDs do not work well with tagged queuing. +If you have problems with such drives, try +.Ql camcontrol [device id] tags -N 1 +to disable tagged queuing. +.Sh HARDWARE +The +.Nm +driver supports FireWire Serial Bus Protocol 2 +.Pq SBP-2 +storage devices. +.Sh SEE ALSO +.Xr cam 4 , +.Xr firewire 4 , +.Xr camcontrol 8 , +.Xr fwcontrol 8 , +.Xr kldload 8 , +.Xr sysctl 8 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Katsushi Kobayashi +and +.An Hidetoshi Shimokawa . +.Pp +This manual page was written by +.An Katsushi Kobayashi . diff --git a/static/freebsd/man4/sbp_targ.4 b/static/freebsd/man4/sbp_targ.4 new file mode 100644 index 00000000..fe6451b6 --- /dev/null +++ b/static/freebsd/man4/sbp_targ.4 @@ -0,0 +1,96 @@ +.\" Copyright (c) 2003 Hidetoshi Shimokawa +.\" 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 acknowledgement as bellow: +.\" +.\" This product includes software developed by H. Shimokawa +.\" +.\" 4. 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 November 7, 2003 +.Dt SBP_TARG 4 +.Os +.Sh NAME +.Nm sbp_targ +.Nd Serial Bus Protocol 2 (SBP-2) Target Mode devices driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device sbp_targ" +.Cd "device firewire" +.Cd "device scbus" +.Cd "device targ" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +firewire_load="YES" +cam_load="YES" +sbp_targ_load"YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for SBP-2 target mode. +This driver is supposed to work with +.Xr cam 4 , +.Xr targ 4 +and +.Xr firewire 4 . +You also need to use +.Xr scsi_target 8 , +which can be found in +.Pa /usr/share/examples/scsi_target , +to provide actual devices. +.Sh EXAMPLES +.Bd -literal -offset indent +# mdconfig -a -t malloc -s 10m +md0 +# scsi_target 0:0:0 /dev/md0 +(Assuming sbp_targ0 on scbus0) +.Ed +.Sh SEE ALSO +.Xr cam 4 , +.Xr firewire 4 , +.Xr targ 4 , +.Xr camcontrol 8 , +.Xr fwcontrol 8 , +.Xr kldload 8 , +.Xr scsi_target 8 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Hidetoshi Shimokawa . +.Sh BUGS +This driver is +.Ud +It does not work correctly in multi-initiator environments +or after the bus topology has been changed. diff --git a/static/freebsd/man4/scc.4 b/static/freebsd/man4/scc.4 new file mode 100644 index 00000000..db0c6dea --- /dev/null +++ b/static/freebsd/man4/scc.4 @@ -0,0 +1,75 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2006 Marcel Moolenaar +.\" 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 ``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 May 26, 2025 +.Dt SCC 4 +.Os +.\" +.Sh NAME +.Nm scc +.Nd Serial Communications Controller driver +.\" +.Sh SYNOPSIS +.Cd "device scc" +.Cd "device uart" +.\" +.Sh DESCRIPTION +The +.Nm +device driver provides support for various classes of SCCs. +It is an umbrella driver that delegates control of each independent +communication channel to subordinate drivers. +These subordinate drivers, like +.Xr uart 4 , +take care of the details of the communication itself. +.\" +.Sh HARDWARE +The +.Nm +driver supports the following classes of Serial Communications Controllers: +.Pp +.Bl -bullet -compact +.It +QUICC: Freescale/NXP QUad Integrated Communications Controllers. +.It +Z8530: Zilog 8530 based serial communications controllers. +.El +.\" +.Sh SEE ALSO +.Xr puc 4 , +.Xr uart 4 +.\" +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 7.0 . +.Sh AUTHORS +The +.Nm +driver and this manual page were written by +.An Marcel Moolenaar Aq Mt marcel@xcllnt.net . diff --git a/static/freebsd/man4/sched_4bsd.4 b/static/freebsd/man4/sched_4bsd.4 new file mode 100644 index 00000000..c8b3938f --- /dev/null +++ b/static/freebsd/man4/sched_4bsd.4 @@ -0,0 +1,72 @@ +.\" Copyright (c) 2005 Robert N. M. Watson +.\" 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 AUTHORS 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 AUTHORS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 21, 2008 +.Dt SCHED_4BSD 4 +.Os +.Sh NAME +.Nm sched_4bsd +.Nd "4.4BSD scheduler" +.Sh SYNOPSIS +.Cd "options SCHED_4BSD" +.Sh DESCRIPTION +The +.Nm +scheduler +is the traditional system scheduler, providing both high throughput and solid +interactive response in the presence of load. +.Pp +The following sysctls are relevant to the operation of +.Nm : +.Bl -tag -width indent +.It Va kern.sched.name +This read-only sysctl reports the name of the active scheduler. +.It Va kern.sched.quantum +This read-write sysctl reports or sets the length of the quantum (in +micro-seconds) granted to a thread. +.It Va kern.sched.ipiwakeup.enabled +This read-write sysctl sets whether or not the scheduler will generate an +inter-processor interrupt (IPI) to an idle CPU when a thread is woken up. +Otherwise, idle CPUs will wait until the next clock tick before looking for +new work. +.It Va kern.sched.preemption +This read-only sysctl reports whether or not the kernel is configured to +support preemption, which reduces the latency to run lower priority threads +on wakeup. +.El +.Pp +Some sysctls will be available only on systems supporting SMP. +.Sh SEE ALSO +.Xr sched_ule 4 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +scheduler has been present, in various forms, since the inception of +.Bx . +.Sh BUGS +While a highly robust and time-tested scheduler, +.Nm +lacks specific knowledge of how to schedule advantageously in non-symmetric +processor configurations, such as hyper-threading. diff --git a/static/freebsd/man4/sched_ule.4 b/static/freebsd/man4/sched_ule.4 new file mode 100644 index 00000000..764ff394 --- /dev/null +++ b/static/freebsd/man4/sched_ule.4 @@ -0,0 +1,73 @@ +.\" Copyright (c) 2005 Robert N. M. Watson +.\" 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 AUTHORS 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 AUTHORS 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 August 10, 2012 +.Dt SCHED_ULE 4 +.Os +.Sh NAME +.Nm sched_ule +.Nd ULE scheduler +.Sh SYNOPSIS +.Cd "options SCHED_ULE" +.Sh DESCRIPTION +The +.Nm +scheduler +provides a number of advanced scheduler +features not present in +.Xr sched_4bsd 4 , +the traditional system scheduler. +These features address SMP and interactivity and include: +.Pp +.Bl -bullet -compact -offset indent +.It +Thread CPU affinity. +.It +CPU topology awareness, including for hyper-threading. +.It +Per-CPU run queues. +.It +Interactivity heuristics that detect interactive applications and schedules +them preferentially under high load. +.El +.Pp +The following sysctls are relevant to the operation of +.Nm : +.Bl -tag -width indent +.It Va kern.sched.name +This read-only sysctl reports the name of the active scheduler. +.It Va kern.sched.quantum +This read-write sysctl reports or sets the length of the quantum (in +micro-seconds) granted to a thread. +.El +.Sh SEE ALSO +.Xr sched_4bsd 4 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +scheduler first appeared in +.Fx 5.1 . +.Sh AUTHORS +.An Jeff Roberson Aq Mt jeff@FreeBSD.org diff --git a/static/freebsd/man4/screen.4 b/static/freebsd/man4/screen.4 new file mode 100644 index 00000000..109aa2fe --- /dev/null +++ b/static/freebsd/man4/screen.4 @@ -0,0 +1,239 @@ +.\" +.Dd October 6, 2000 +.Dt SCREEN 4 +.Os +.Sh NAME +.Nm screen +.Nd pc display interface +.Sh DESCRIPTION +Access to the +.Em virtual consoles +are obtained through the device files +.Pa /dev/ttyv0 +- +.Pa /dev/ttyvb . +Each of these files correspond to a separate +virtual console. +All virtual console devices can be open at once, but only one is +active at a time. +The active virtual console "owns" the keyboard and +display screen. +.Pp +Output to a virtual console that not currently is on the display is +saved in a buffer that holds a "screenfull" (normally 25) lines. +Any output written to +.Pa /dev/console +(the original console device) is echoed to +.Pa /dev/ttyv0 . +.Pp +To switch between the virtual consoles one uses the sequence +.Em ALT+Fn , +which means hold down ALT and press one of the function keys. +The +virtual console with the same number as the function key is then +selected as the current virtual console, and given exclusive use of +the keyboard and display. +This switch sequence can be changed via +the keyboard mapping ioctl call (see +.Xr keyboard 4 ) . +.Pp +The console allows entering values that are not physically +present on the keyboard via a special keysequence. +To use this facility press and hold down ALT, +then enter a decimal number from 0-255 via the numerical keypad, then +release ALT. +The entered value is then used as the ASCII value for one +character. +This way it is possible to enter any ASCII value. +The console driver also includes a history function. +It is activated by +pressing the scroll-lock key. +This holds the display, and enables the cursor +arrows for scrolling up and down through the last scrolled out lines. +.Pp +The console understands a subset of the ANSI x3.64 character +sequences. +For compatibility with the old pccons, the PC3 character +sequences are also supported. +.Bd -literal +ANSI Seq Function Termcap entry +======= ======= ===================================== ============== + +-- E7 Save cursor position sc + +-- E8 Restore saved cursor position rc + +-- Ec Reset rs + +-- EM move cursor up 1 line, -- + scroll if at top + +CUU E[nA move cursor up n lines up/UP (ku) + +CUD E[nB move cursor down n lines do/DO (kd) + +CUF E[nC move cursor right n characters nd/RI (kr) + +CUB E[nD move cursor left n characters --/LE (kl) + +HPA E[n` move cursor to character position n ch + +HPR E[na move cursor right n characters -- + +VPA E[nd move cursor to line n cv + +VPR E[ne move cursor down n lines -- + +CPL E[nF move cursor to start of line, -- (@7) + n lines up + +CNL E[nE move cursor to start of line, nw + n lines down + +CUP E[y;xH Move cursor to x, y cm + +HVP E[y;xf Move cursor to x, y -- + +CBT E[nZ Move cursor back n tab stops bt (kB) + +IL E[nL Insert n blank lines al/AL + +ICH E[n@ Insert n blank characters ic/IC + +DL E[nM Delete n lines dl/DL + +DCH E[nP Delete n characters dc/DC + +ED E[nJ Erase part or all of display: cd + n=0 from cursor to end of display, + n=1 from begin of display to cursor, + n=2 entire display. + +EL E[nK Erase part or all of line: ce + n=0 from cursor to end of line, + n=1 from begin of line to cursor, + n=2 entire line. + +ECH E[nX Erase n characters ec + +SU E[nS Scroll display n lines up (forward) sf/SF + +SD E[nT Scroll display n lines down (reverse) sr/SR + + +SGR E[nm Set character attributes: -- + n= 0 normal attribute (all off) + n= 1 bold (highlight) + n= 4 underscore (if supported by HW) + n= 5 blink (if supported by HW) + n= 7 reverse + n= 22 remove bold + n= 24 remove underscore + n= 25 remove blink + n= 27 remove reverse + n= 3X set ANSI foreground color + (see table) + n= 4X set ANSI background color + (see table) + + X=0 black X=1 red + X=2 green X=3 brown + X=4 blue X=5 magenta + X=6 cyan X=7 light grey + X=9 reset to the normal color + +-- E[s Save cursor position sc + +-- E[u Restore saved cursor position rc + +-- E[x Reset normal colors and attributes -- + to their default values + +-- E[nz Switch to virtual console n -- + +-- E[1;nx Set normal ANSI background color -- + to n (see table) + +-- E[2;nx Set normal ANSI foreground color -- + to n (see table) + +-- E[3;nx Set normal video attribute directly -- + to n (n from 0 to 255) + +-- E[5;nx Set normal ANSI reverse background -- + color to n (see table) + +-- E[6;nx Set normal ANSI reverse foreground -- + color to n (see table) + + n= 0 black n= 8 dark grey + n= 1 red n= 9 light red + n= 2 green n=10 light green + n= 3 brown n=11 yellow + n= 4 blue n=12 light blue + n= 5 magenta n=13 light magenta + n= 6 cyan n=14 light cyan + n= 7 light grey n=15 white + +-- E[7;nx Set normal reverse video attribute -- + directly to n (n from 0 to 255) + +-- E[=p;dB Set bell pitch (p) and duration (d), -- + pitch is in units of 840 nS, + duration is units of 0,1 S. + +-- E[=tC Set global cursor type (see table) -- + + t=0 normal non-blinking + t=1 normal blinking + t=2 custom non-blinking + t=3 custom blinking + t=4 reset cursor (resets custom + cursor shape and sets current + cursor type to 0) + t=5 hide cursor + +-- E[=s;eC Set custom cursor shape, where -- + s is the starting and e is the ending + scanlines of the cursor. + +-- E[=s;e;dC -- + Same as above, except d specifies the + direction. If 0, scanlines are counted + from the top to the bottom. If 1, from + the bottom to the top. + +-- E[=tS Set local cursor type (see table) -- + + t=0 normal (global) ve + t=1 invisible vi + t=2 very visible vs + +-- E[=nA Set the border color to n -- + (see table) (if supported by HW) + +-- E[=nF Set normal foreground color to n -- + (see table) + +-- E[=nG Set normal background color to n -- + (see table) + +-- E[=nH Set normal reverse foreground color -- + to n (see table) + +-- E[=nI Set normal reverse background color -- + to n (see table) + + n= 0 black n= 8 dark grey + n= 1 blue n= 9 light blue + n= 2 green n=10 light green + n= 3 cyan n=11 light cyan + n= 4 red n=12 light red + n= 5 magenta n=13 light magenta + n= 6 brown n=14 yellow + n= 7 light grey n=15 white + +note: the first E in the sequences stands for ESC (0x1b) +.Ed +.Sh AUTHORS +.An S\(/oren Schmidt Aq Mt sos@FreeBSD.org diff --git a/static/freebsd/man4/scsi.4 b/static/freebsd/man4/scsi.4 new file mode 100644 index 00000000..e66fccf5 --- /dev/null +++ b/static/freebsd/man4/scsi.4 @@ -0,0 +1,562 @@ +.\" Copyright (c) 1996 +.\" Julian Elischer . 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 December 11, 2025 +.Dt CAM 4 +.Os +.Sh NAME +.Nm CAM +.Nd Common Access Method Storage subsystem +.Sh SYNOPSIS +.Cd "device scbus" +.Cd "device ada" +.Cd "device cd" +.Cd "device ch" +.Cd "device da" +.Cd "device pass" +.Cd "device pt" +.Cd "device sa" +.Cd "options CAMDEBUG" +.Cd "options CAM_DEBUG_BUS=-1" +.Cd "options CAM_DEBUG_TARGET=-1" +.Cd "options CAM_DEBUG_LUN=-1" +.Cd "options CAM_DEBUG_COMPILE=CAM_DEBUG_INFO|CAM_DEBUG_CDB|CAM_DEBUG_PROBE" +.Cd "options CAM_DEBUG_FLAGS=CAM_DEBUG_INFO|CAM_DEBUG_CDB" +.Cd "options CAM_MAX_HIGHPOWER=4" +.Cd "options SCSI_NO_SENSE_STRINGS" +.Cd "options SCSI_NO_OP_STRINGS" +.Cd "options SCSI_DELAY=8000" +.Sh DESCRIPTION +The +.Nm +subsystem provides a uniform and modular system for the implementation +of drivers to control various +.Tn SCSI , +.Tn ATA , +.Tn NVMe , +and +.Tn MMC / SD +devices, and to utilize different +.Tn SCSI , +.Tn ATA , +.Tn NVMe , +and +.Tn MMC / SD +host adapters through host adapter drivers. +When the system probes buses, it attaches any devices it finds to the +appropriate drivers. +The +.Xr pass 4 +driver, if it is configured in the kernel, will attach to all devices. +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width 12 +.It Va kern.cam.cam_srch_hi +Search above LUN 7 for SCSI3 and greater devices. +.It Va kern.cam.tur_timeout +Timeout, in ms, for the initial TESTUNITREADY command we send to the devices +during their initial probing. +Defaults to 1s. +.Fx 15 +and earlier set this to 60s. +.It Va kern.cam.inquiry_timeout +Timeout, in ms, for the initial INQUIRY command we send to the devices +during their initial probing. +Defaults to 1s. +.Fx 15 +and earlier set this to 60s. +.It Va kern.cam.reportluns_timeout +Timeout, in ms, for the initial REPORTLUNS command we send to the devices +during their initial probing. +Defaults to 50s. +.It Va kern.cam.max_high_power +The maximum number high power commands, like START UNIT, to issue at the same +time. +Defaults to 4. +.It Va kern.cam.modesense_timeout +Timeout, in ms, for the initial MODESENSE command we send to the devices +during their initial probing. +Defaults to 1s. +.Fx 15 +and earlier set this to 60s. +.El +.Sh KERNEL CONFIGURATION +There are a number of generic kernel configuration options for the +.Nm +subsystem: +.Bl -tag -width SCSI_NO_SENSE_STRINGS +.It Dv CAM_BOOT_DELAY +Additional time to wait after the static parts of the kernel have run to allow +for discovery of additional devices which may take time to connect, +such as USB attached storage. +.It Dv CAM_IOSCHED_DYNAMIC +Enable dynamic decisions in the I/O scheduler based on hints and the current +performance of the storage devices. +.It Dv CAM_IO_STATS +Enable collection of statistics for periph devices. +.It Dv CAM_TEST_FAILURE +Enable ability to simulate I/O failures. +.It Dv CAMDEBUG +This option compiles in all the +.Nm +debugging printf code. +This will not actually +cause any debugging information to be printed out when included by itself. +See below for details. +.It Dv "CAM_MAX_HIGHPOWER=4" +This sets the maximum allowable number of concurrent "high power" commands. +A "high power" command is a command that takes more electrical power than +most to complete. +An example of this is the +.Tn SCSI +START UNIT command. +Starting a disk often takes significantly more electrical power than normal +operation. +This option allows the +user to specify how many concurrent high power commands may be outstanding +without overloading the power supply on his computer. +.It Dv SCSI_NO_SENSE_STRINGS +This eliminates text descriptions of each +.Tn SCSI +Additional Sense Code and Additional Sense Code Qualifier pair. +Since this +is a fairly large text database, eliminating it reduces the size of the +kernel somewhat. +This is primarily necessary for boot floppies and other +low disk space or low memory space environments. +In most cases, though, +this should be enabled, since it speeds the interpretation of +.Tn SCSI +error messages. +Do not let the "kernel bloat" zealots get to you -- leave +the sense descriptions in your kernel! +.It Dv SCSI_NO_OP_STRINGS +This disables text descriptions of each +.Tn SCSI +opcode. +This option, like the sense string option above, is primarily +useful for environments like a boot floppy where kernel size is critical. +Enabling this option for normal use is not recommended, since it slows +debugging of +.Tn SCSI +problems. +.It Dv SCSI_DELAY=8000 +This is the +.Tn SCSI +"bus settle delay." +In +.Nm , +it is specified in +.Em milliseconds , +not seconds like the old +.Tn SCSI +layer used to do. +When the kernel boots, it sends a bus reset to each +.Tn SCSI +bus to tell each device to reset itself to a default set of transfer +negotiations and other settings. +Most +.Tn SCSI +devices need some amount of time to recover from a bus reset. +Newer disks +may need as little as 100ms, while old, slow devices may need much longer. +If the +.Dv SCSI_DELAY +is not specified, it defaults to 2 seconds. +The minimum allowable value for +.Dv SCSI_DELAY +is "100", or 100ms. +One special case is that if the +.Dv SCSI_DELAY +is set to 0, that will be taken to mean the "lowest possible value." +In that case, the +.Dv SCSI_DELAY +will be reset to 100ms. +.El +.Pp +All devices and buses support dynamic allocation so that +an upper number of devices and controllers does not need to be configured; +.Cd "device da" +will suffice for any number of disk drivers. +.Pp +The devices are either +.Em wired +so they appear as a particular device unit or +.Em counted +so that they appear as the next available unused unit. +.Pp +Units are wired down by setting kernel environment hints. +This is usually done either interactively from the +.Xr loader 8 , +or automatically via the +.Pa /boot/device.hints +file. +The basic syntax is: +.Bd -literal -offset indent +hint.device.unit.property="value" +.Ed +.Pp +Individual +.Nm +bus numbers can be wired down to specific controllers with +a config line similar to the following: +.Bd -literal -offset indent +hint.scbus.0.at="mpr1" +.Ed +.Pp +This assigns +.Nm +bus number 0 to the +.Em mpr1 +driver instance. +For controllers supporting more than one bus, a particular bus can be assigned +as follows: +.Bd -literal -offset indent +hint.scbus.0.at="ahci1" +hint.scbus.0.bus="1" +.Ed +.Pp +This assigns +.Nm +bus 0 to the bus 1 instance on +.Em ahci1 . +Peripheral drivers can be wired to a specific bus, target, and lun as so: +.Bd -literal -offset indent +hint.da.0.at="scbus0" +hint.da.0.target="0" +hint.da.0.lun="0" +.Ed +.Pp +This assigns +.Em da0 +to target 0, unit (lun) 0 of scbus 0. +Omitting the target or unit hints will instruct +.Nm +to treat them as wildcards +and use the first respective counted instances. +These examples can be combined together to allow a peripheral device to be +wired to any particular controller, bus, target, and/or unit instance. +.Pp +This also works with +.Xr nvme 4 +drives. +.Bd -literal -offset indent +hint.nvme.4.at="pci7:0:0" +hint.scbus.10.at="nvme4" +hint.nda.10.at="scbus10" +hint.nda.10.target="1" +hint.nda.10.lun="12" +hint.nda.11.at="scbus10" +hint.nda.11.target="1" +hint.nda.11.lun="2" +.Ed +.Pp +This assigns the NVMe card at PCI bus 7 slot 0 function 1 to scbus 10. +The target for +.Xr nda 4 +devices is always 1. +The unit is the namespace identifier from the drive. +The namespace id 1 is exported as +.Em nda10 +and namespace id 2 is exported as +.Em nda11 . +.Pp +For devices that provide a serial number, units may be wired to that serial +number without regard where the drive is attached: +.Bd -literal -offset indent +hint.nda.3.sn="CY0AN07101120B12P" +hint.da.44.sn="143282400011" +hint.ada.2.sn="A065D591" +.Ed +wires +.Em nda3 , +.Em da44 , +and +.Em ada2 +to drives with the specified serial numbers. +One need not specify an +.Em at +line when serial numbers are used. +.Sh ADAPTERS +The system allows common device drivers to work through many different +types of adapters. +The adapters take requests from the upper layers and do +all IO between the +.Tn SCSI , +.Tn ATA , +.Tn NVMe , +or +.Tn MMC / SD +bus and the system. +The maximum size of a transfer is governed by the +adapter. +Most adapters can transfer 1MB in a single operation, however +many can transfer larger amounts. +.Sh TARGET MODE +Some adapters support +.Em target mode +in which the system is capable of operating as a device, responding to +operations initiated by another system. +Target mode is supported for +some adapters, but is not yet complete for this version of the +.Nm +.Tn SCSI +subsystem. +.Sh ARCHITECTURE +The +.Nm +subsystem glues together the upper layers of the system to the storage devices. +PERIPH devices accept storage requests from GEOM and other upper layers of the +system and translates them into protocol requests. +XPT (transport) dispatches these protocol requests to a SIM driver. +A SIM driver takes protocol requests and translates them into hardware commands +the host adapter understands to transfer the protocol requests, and data (if +any) to the storage device. +The CCB transports these requests around as messages. +.Ss CAM +The Common Access Method was a standard defined in the 1990s to talk to disk +drives. +.Fx +is one of the few operating systems to fully implement this model. +The interface between different parts of CAM is the CCB (or CAM Control Block). +Each CCB has a standard header, which contains the type of request and dispatch +information, and a command specific portion. +A CAM Periph generates requests. +The XPT layer dispatches these requests to the appropriate SIM. +Some CCBs are sent directly to the SIM for immediate processing, while others +are queued and complete when the I/O has finished. +A SIM takes CCBs and translates them into hardware specific commands to push the +SCSI CDB or other protocol control block to the peripheral, along with setting +up the DMA for the associated data. +.Ss Periph Devices +A periph driver knows how to translate standard requests into protocol messages +that a SIM can deliver to hardware. +These requests can come from any upper layer source, but primarily come in via +GEOM as a bio request. +They can also come in directly from character device requests for tapes and pass +through commands. +.Pp +Disk devices, or direct access (da) in CAM, are one type of peripheral. +These devices present themselves to the kernel a device ending in +.Dq da . +Each protocol has a unique device name: +.Bl -tag -width 4 +.It Xr da 4 +SCSI or SAS device, or devices that accept SCSI CDBs for I/O. +.It Xr ada 4 +ATA or SATA device +.It Xr nda 4 +NVME device +.It Xr sdda 4 +An SD or MMC block storage device. +.El +.Pp +Tape devices are called serial access +.Po +.Xr sa 4 +.Pc +in CAM. +They interface to the system via a character device and provide +.Xr ioctl 2 +control for tape drives. +.Pp +The +.Xr pass 4 +device will pass through CCB requests from userland to the SIM directly. +The device is used to send commands other than read, write, trim or flush to a +device. +The +.Xr camcontrol 8 +command uses this device. +.Ss XPT drivers +The transport driver connects the periph to the SIM. +It is not configured separately. +It is also responsible for device discovery for those SIM drivers that do not +enumerate themselves. +.Ss SIM driver +SIM used to stand for SCSI Interface Module. +Now it is just SIM because it understands protocols other than SCSI. +There are two types of SIM drivers: virtual and physical. +Physical SIMs are typically called host bus adapters (HBA), but not universally. +Virtual SIM drivers are for communicating with network or virtual machine hosts. +.Sh FILES +see other +.Nm +device entries. +.Sh DIAGNOSTICS +An XPT_DEBUG CCB can be used to enable various amounts of tracing information +on any specific bus/device from the list of options compiled into the kernel. +There are currently seven debugging flags that may be compiled in and used: +.Bl -tag -width CAM_DEBUG_SUBTRACE +.It Dv CAM_DEBUG_INFO +This flag enables general informational printfs for the device +or devices in question. +.It Dv CAM_DEBUG_TRACE +This flag enables function-level command flow tracing i.e., +kernel printfs will happen at the entrance and exit of various functions. +.It Dv CAM_DEBUG_SUBTRACE +This flag enables debugging output internal to various functions. +.It Dv CAM_DEBUG_CDB +This flag will cause the kernel to print out all +.Tn ATA +and +.Tn SCSI +commands sent to a particular device or devices. +.It Dv CAM_DEBUG_XPT +This flag will enable command scheduler tracing. +.It Dv CAM_DEBUG_PERIPH +This flag will enable peripheral drivers messages. +.It Dv CAM_DEBUG_PROBE +This flag will enable devices probe process tracing. +.El +.Pp +Some of these flags, most notably +.Dv CAM_DEBUG_TRACE +and +.Dv CAM_DEBUG_SUBTRACE , +will produce kernel printfs in EXTREME numbers. +.Pp +Users can enable debugging from their kernel config file, by using +the following kernel config options: +.Bl -tag -width CAM_DEBUG_COMPILE +.It Dv CAMDEBUG +This builds into the kernel all possible +.Nm +debugging. +.It Dv CAM_DEBUG_COMPILE +This specifies support for which debugging flags described above +should be built into the kernel. +Flags may be ORed together if the user wishes to +see printfs for multiple debugging levels. +.It Dv CAM_DEBUG_FLAGS +This sets the various debugging flags from a kernel config file. +.It Dv CAM_DEBUG_BUS +Specify a bus to debug. +To debug all buses, set this to -1. +.It Dv CAM_DEBUG_TARGET +Specify a target to debug. +To debug all targets, set this to -1. +.It Dv CAM_DEBUG_LUN +Specify a lun to debug. +To debug all luns, set this to -1. +.El +.Pp +Users may also enable debugging on the fly by using the +.Xr camcontrol 8 +utility, if wanted options built into the kernel. +See +.Xr camcontrol 8 +for details. +.Sh SEE ALSO +.Bl -tag -width 20 +.It Sy Commands: +.Xr camcontrol 8 , +.Xr camdd 8 +.It Sy Libraries: +.Xr cam 3 +.It Sy Periph Drivers: +.Xr ada 4 , +.Xr da 4 , +.Xr nda 4 , +.\" .Xr sdda 4 , +.Xr pass 4 , +.Xr sa 4 +.It Sy SIM Devices: +.Xr aac 4 , +.Xr aacraid 4 , +.Xr ahc 4 , +.Xr ahci 4 , +.Xr ata 4 , +.Xr aw_mmc 4 , +.Xr ciss 4 , +.Xr hv_storvsc 4 , +.Xr isci 4 , +.Xr iscsi 4 , +.Xr isp 4 , +.\" .Xr mmcnull 4 , +.Xr mpr 4 , +.Xr mps 4 , +.Xr mpt 4 , +.Xr mrsas 4 , +.Xr mvs 4 , +.Xr nvme 4 , +.Xr pms 4 , +.Xr pvscsi 4 , +.Xr sdhci 4 , +.Xr smartpqi 4 , +.Xr sym 4 , +.Xr tws 4 , +.Xr umass 4 , +.Xr virtio_scsi 4 +.It Sy Deprecated or Poorly Supported SIM Devices: +.Xr ahd 4 , +.Xr amr 4 , +.Xr arcmsr 4 , +.Xr esp 4 , +.\" .Xr fslsata 4 , +.Xr hpt27xx 4 , +.Xr hptiop 4 , +.Xr hptmv 4 , +.Xr hptnr 4 , +.\" .Xr htprr 4 , +.Xr iir 4 +.Xr mfi 4 , +.\" .Xr osc 4 , +.\" .Xr ps3cdrom 4 , +.Xr sbp 4 , +.Xr twa 4 +.El +.Sh HISTORY +The +.Nm +.Tn SCSI +subsystem first appeared in +.Fx 3.0 . +The +.Nm +ATA support was added in +.Fx 8.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +.Tn SCSI +subsystem was written by +.An Justin Gibbs +and +.An Kenneth Merry . +The +.Nm +.Tn ATA +support was added by +.An Alexander Motin Aq Mt mav@FreeBSD.org . +The +.Nm +.Tn NVMe +support was added by +.An Warner Losh Aq Mt imp@FreeBSD.org . diff --git a/static/freebsd/man4/sctp.4 b/static/freebsd/man4/sctp.4 new file mode 100644 index 00000000..287e16f3 --- /dev/null +++ b/static/freebsd/man4/sctp.4 @@ -0,0 +1,624 @@ +.\" Copyright (c) 2006, Randall Stewart. +.\" +.\" 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 June 21, 2023 +.Dt SCTP 4 +.Os +.Sh NAME +.Nm sctp +.Nd Internet Stream Control Transmission Protocol +.Sh SYNOPSIS +.Cd "options SCTP" +.Cd "options SCTP_SUPPORT" +.Pp +.In sys/types.h +.In sys/socket.h +.In netinet/sctp.h +.Ft int +.Fn socket AF_INET SOCK_STREAM IPPROTO_SCTP +.Ft int +.Fn socket AF_INET SOCK_SEQPACKET IPPROTO_SCTP +.Sh DESCRIPTION +The +.Tn SCTP +protocol provides reliable, flow-controlled, two-way +transmission of data. +It is a message oriented protocol and can +support the +.Dv SOCK_STREAM +and +.Dv SOCK_SEQPACKET +abstractions. +.Tn SCTP +uses the standard +Internet address format and, in addition, provides a per-host +collection of +.Dq "port addresses" . +Thus, each address is composed of an Internet address specifying +the host and network, with a specific +.Tn SCTP +port on the host identifying the peer entity. +.Pp +There are two models of programming in SCTP. +The first uses the +.Dv SOCK_STREAM +abstraction. +In this abstraction sockets utilizing the +.Tn SCTP +protocol are either +.Dq active +or +.Dq passive . +Active sockets initiate connections to passive +sockets. +By default, +.Tn SCTP +sockets are created active; to create a +passive socket, the +.Xr listen 2 +system call must be used after binding the socket with the +.Xr bind 2 +or +.Xr sctp_bindx 3 +system calls. +Only passive sockets may use the +.Xr accept 2 +call to accept incoming connections. +Only active sockets may use the +.Xr connect 2 +call to initiate connections. +.Pp +The other abstraction +.Dv SOCK_SEQPACKET +provides a +.Dq connectionless +mode of operation in that the user may send to an address +(using any of the valid send calls that carry a +socket address) and an association will be setup +implicitly by the underlying +.Tn SCTP +transport stack. +This abstraction is the only one capable of sending data on the +third leg of the four-way handshake. +A user must still call +.Xr listen 2 +to allow the socket to accept connections. +Calling +.Xr listen 2 +however does not restrict the user from still initiating +implicit connections to other peers. +.Pp +The +.Tn SCTP +protocol directly supports multi-homing. +So when binding a socket with the +.Dq wildcard +address +.Dv INADDR_ANY , +the +.Tn SCTP +stack will inform the peer about all of the local addresses +that are deemed in scope of the peer. +The peer will then possibly have multiple paths to reach the local host. +.Pp +The +.Tn SCTP +transport protocol is also multi-streamed. +Multi-streaming refers to the ability to send sub-ordered flows of +messages. +A user performs this by specifying a specific stream in one of the +extended send calls such as the +.Xr sctp_send 3 +function call. +Sending messages on different streams will allow parallel delivery +of data i.e., a message loss in stream 1 will not block the delivery +of messages sent in stream 2. +.Pp +The +.Tn SCTP +transport protocol also provides a unordered service as well. +The unordered service allows a message to be sent and delivered +with no regard to the ordering of any other message. +.Pp +The +.Tn SCTP +kernel implementation may either be compiled into the kernel, or loaded +dynamically as a module. +To support dynamic loading of the stack, the kernel must be compiled +with +.Cd "options SCTP_SUPPORT" . +.Ss Extensions +The +.Fx +implementation of +.Tn SCTP +also supports the following extensions: +.Bl -tag -width "sctp partial reliability" +.It "sctp partial reliability" +This extension allows one to have message be skipped and +not delivered based on some user specified parameters. +.It "sctp dynamic addressing" +This extension allows addresses to be added and deleted +dynamically from an existing association. +.It "sctp authentication" +This extension allows the user to authenticate specific +peer chunks (including data) to validate that the peer +who sent the message is in fact the peer who setup the +association. +A shared key option is also provided for +so that two stacks can pre-share keys. +.It "packet drop" +Some routers support a special satellite protocol that +will report losses due to corruption. +This allows retransmissions without subsequent loss in bandwidth +utilization. +.It "stream reset" +This extension allows a user on either side to reset the +stream sequence numbers used by any or all streams. +.El +.Ss Socket Options +.Tn SCTP +supports a number of socket options which can be set with +.Xr setsockopt 2 +and tested with +.Xr getsockopt 2 +or +.Xr sctp_opt_info 3 : +.Bl -tag -width indent +.It Dv SCTP_NODELAY +Under most circumstances, +.Tn SCTP +sends data when it is presented; when outstanding data has not +yet been acknowledged, it gathers small amounts of output to be +sent in a single packet once an acknowledgement is received. +For some clients, such as window systems that send a stream of +mouse events which receive no replies, this packetization may +cause significant delays. +The boolean option +.Dv SCTP_NODELAY +defeats this algorithm. +.It Dv SCTP_RTOINFO +This option returns specific information about an associations +.Dq "Retransmission Time Out" . +It can also be used to change the default values. +.It Dv SCTP_ASSOCINFO +This option returns specific information about the requested +association. +.It Dv SCTP_INITMSG +This option allows you to get or set the default sending +parameters when an association is implicitly setup. +It allows you to change such things as the maximum number of +streams allowed inbound and the number of streams requested +of the peer. +.It Dv SCTP_AUTOCLOSE +For the one-to-many model +.Dv ( SOCK_SEQPACKET ) +associations are setup implicitly. +This option allows the user to specify a default number of idle +seconds to allow the association be maintained. +After the idle timer (where no user message have been sent or have +been received from the peer) the association will be gracefully +closed. +The default for this value is 0, or unlimited (i.e., no automatic +close). +.It Dv SCTP_SET_PEER_PRIMARY_ADDR +The dynamic address extension allows a peer to also request a +particular address of its be made into the primary address. +This option allows the caller to make such a request to a peer. +Note that if the peer does not also support the dynamic address +extension, this call will fail. +Note the caller must provide a valid local address that the peer has +been told about during association setup or dynamically. +.It Dv SCTP_PRIMARY_ADDR +This option allows the setting of the primary address +that the caller wishes to send to. +The caller provides the address of a peer that is to be made primary. +.It Dv SCTP_ADAPTATION_LAYER +The dynamic address extension also allows a user to +pass a 32 bit opaque value upon association setup. +This option allows a user to set or get this value. +.It Dv SCTP_DISABLE_FRAGMENTS +By default +.Tn SCTP +will fragment user messages into multiple pieces that +will fit on the network and then later, upon reception, reassemble +the pieces into a single user message. +If this option is enabled instead, any send that exceeds the path +maximum transfer unit (P-MTU) will fail and the message will NOT be +sent. +.It Dv SCTP_PEER_ADDR_PARAMS +This option will allow a user to set or get specific +peer address parameters. +.It Dv SCTP_DEFAULT_SEND_PARAM +When a user does not use one of the extended send +calls (e.g., +.Xr sctp_sendmsg 3 ) +a set of default values apply to each send. +These values include things like the stream number to send +to as well as the per-protocol id. +This option lets a caller both get and set these values. +If the user changes these default values, then these new values will +be used as the default whenever no information is provided by the +sender (i.e., the non-extended API is used). +.It Dv SCTP_EVENTS +.Tn SCTP +has non-data events that it can communicate +to its application. +By default these are all disabled since they arrive in the data path +with a special flag +.Dv MSG_NOTIFICATION +set upon the received message. +This option lets a caller +both get what events are current being received +as well as set different events that they may be interested +in receiving. +.It Dv SCTP_I_WANT_MAPPED_V4_ADDR +.Tn SCTP +supports both IPV4 and IPV6. +An association may span both IPV4 and IPV6 addresses since +.Tn SCTP +is multi-homed. +By default, when opening an IPV6 socket, when +data arrives on the socket from a peer's +V4 address the V4 address will be presented with an address family +of AF_INET. +If this is undesirable, then this option +can be enabled which will then convert all V4 addresses +into mapped V6 representations. +.It Dv SCTP_MAXSEG +By default +.Tn SCTP +chooses its message fragmentation point +based upon the smallest P-MTU of the peer. +This option lets the caller set it to a smaller value. +Note that while the user can change this value, if the P-MTU +is smaller than the value set by the user, then the P-MTU +value will override any user setting. +.It Dv SCTP_DELAYED_SACK +This option lets the user both set and get the +delayed ack time (in milliseconds) and the ack frequency that +.Tn SCTP +is using. +The default delayed ack time is 200 milliseconds and the default +ack frequency is 2. +.It Dv SCTP_PARTIAL_DELIVERY_POINT +.Tn SCTP +at times may need to start delivery of a +very large message before the entire message has +arrived. +By default SCTP waits until the incoming +message is larger than one fourth of the receive +buffer. +This option allows the stacks value +to be overridden with a smaller value. +.It Dv SCTP_FRAGMENT_INTERLEAVE +.Tn SCTP +at times will start partial delivery (as mentioned above). +In the normal case successive reads will continue to return +the rest of the message, blocking if needed, until all of +that message is read. +However this means other messages may have arrived and be ready +for delivery and be blocked behind the message being partially +delivered. +If this option is enabled, when a partial delivery +message has no more data to be received, then a subsequent +read may return a different message that is ready for delivery. +By default this option is off since the user must be using the +extended API's to be able to tell the difference between +messages (via the stream and stream sequence number). +.It Dv SCTP_AUTH_CHUNK +By default only the dynamic addressing chunks are +authenticated. +This option lets a user request an +additional chunk be authenticated as well. +Note that successive calls to this option will work and continue +to add more chunks that require authentication. +Note that this option only effects future associations and +not existing ones. +.It Dv SCTP_AUTH_KEY +This option allows a user to specify a shared +key that can be later used to authenticate +a peer. +.It Dv SCTP_HMAC_IDENT +This option will let you get or set the list of +HMAC algorithms used to authenticate peers. +Note that the HMAC values are in priority order where +the first HMAC identifier is the most preferred +and the last is the least preferred. +.It Dv SCTP_AUTH_ACTIVE_KEY +This option allows you to make a key active for +the generation of authentication information. +Note that the peer must have the same key or else the +data will be discarded. +.It Dv SCTP_AUTH_DELETE_KEY +This option allows you to delete an old key. +.It Dv SCTP_USE_EXT_RECVINFO +The sockets api document allows an extended +send/receive information structure to be used. +The extended structure includes additional fields +related to the next message to be received (after the +current receive completes) if such information is known. +By default the system will not pass this information. +This option allows the user to request this information. +.It Dv SCTP_AUTO_ASCONF +By default when bound to all address and the system administrator has +enables automatic dynamic addresses, the +.Tn SCTP +stack will automatically generate address changes into add and +delete requests to any peers by setting this option to +true. +This option allows an endpoint to disable that behavior. +.It Dv SCTP_MAXBURST +By default +.Tn SCTP +implements micro-burst control so that as the congestion window +opens up no large burst of packets can be generated. +The default burst limit is four. +This option lets the user change this value. +.It Dv SCTP_CONTEXT +Many sctp extended calls have a context field. +The context field is a 32 bit opaque value that will be returned in +send failures. +This option lets the caller set the default +context value to use when none is provided by the user. +.It Dv SCTP_EXPLICIT_EOR +By default, a single send is a complete message. +.Tn SCTP +generates an implied record boundary. +If this option is enabled, then all sends are part of the same message +until the user indicates an end of record with the +special flag +.Dv SCTP_EOR +passed in the sctp_sndrcvinfo flags field. +This effectively makes all sends part of the same message +until the user specifies differently. +This means that a caller must NOT change the stream number until +after the +.Dv SCTP_EOR +is passed to +.Tn SCTP +else an error will be returned. +.It Dv SCTP_STATUS +This option is a read-only option that returns +various status information about the specified association. +.It Dv SCTP_GET_PEER_ADDR_INFO +This read-only option returns information about a peer +address. +.It Dv SCTP_PEER_AUTH_CHUNKS +This read-only option returns a list of the chunks +the peer requires to be authenticated. +.It Dv SCTP_LOCAL_AUTH_CHUNKS +This read-only option returns a list of the locally +required chunks that must be authenticated. +.It Dv SCTP_RESET_STREAMS +This socket option is used to cause a stream sequence +number or all stream sequence numbers to be reset. +Note that the peer +.Tn SCTP +endpoint must also support the stream reset extension +as well. +.El +.Ss MIB Variables +The +.Tn SCTP +protocol implements a number of variables in the +.Va net.inet.sctp +branch of the +.Xr sysctl 3 +MIB. +.Bl -ohang +.It Sy Congestion Control +.Bl -tag -width indent +.It Va default_cc_module +Default congestion control module. +Default value is 0. +The minimum is 0, and the maximum is 3. +A value of 0 enables the default congestion control algorithm. +A value of 1 enables the High Speed congestion control algorithm. +A value of 2 enables the HTCP congestion control algorithm. +A value of 3 enables the data center congestion control (DCCC) algorithm. +.It Va initial_cwnd +Defines the initial congestion window size in MTUs. +.It Va cwnd_maxburst +Use congestion control instead of 'blind' logic to limit maximum burst when sending. +Default value is 1. May be set to 0 or 1. +.It Va ecn_enable +Enable Explicit Congestion Notification (ECN). +Default value is 1. May be set to 0 or 1. +.It Va rttvar_steady_step +Number of identical bandwidth measurements DCCC takes to try step down the congestion window. +Default value is 20. +The minimum is 0, and the maximum is 65535. +.It Va rttvar_eqret +Whether DCCC reduces the congestion window size when round-trip time and bandwidth remain unchanged. +Default value is 0. +May be set to 0 or 1. +.It Va rttvar_bw +Shift amount DCCC uses for bandwidth smoothing on round-trip-time calculation. +Default value is 4. +The minimum is 0, and the maximum is 32. +.It Va rttvar_rtt +Shift amount DCCC uses for round-trip-time smoothing on round-trip-time calculation. +Default value is 5. +The minimum is 0, and the maximum is 32. +.It Va use_dcccecn +Enable ECN when using DCCC. +Default value is 1. +May be set to 0 or 1. +.El +.It Sy Misc +.Bl -tag -width indent +.It Va getcred +Get the ucred of a SCTP connection. +.It Va assoclist +List of active SCTP associations. +.It Va stats +SCTP statistics (struct sctp_stat). +.It Va diag_info_code +Diagnostic information error cause code. +.It Va blackhole +Enable SCTP blackholing. +See +.Xr blackhole 4 +for more details. +.It Va sendall_limit +Maximum message size (in bytes) that can be transmitted with SCTP_SENDALL flags set. +.It Va buffer_splitting +Enable send/receive buffer splitting. +.It Va vtag_time_wait +Vtag wait time in seconds, 0 to disable. +.It Va nat_friendly_init +Enable sending of the NAT-friendly SCTP option on INITs. +.It Va enable_sack_immediately +Enable sending of the SACK-IMMEDIATELY bit. +.It Va udp_tunneling_port +Set the SCTP/UDP tunneling port. +.It Va mobility_fasthandoff +Enable SCTP fast handoff. +.It Va mobility_base +Enable SCTP base mobility +.It Va default_frag_interleave +Default fragment interleave level. +.It Va default_ss_module +Default stream scheduling module. +.It Va log_level +Ltrace/KTR trace logging level. +.It Va max_retran_chunk +Number of retransmissions of a DATA chunk before an association is aborted. +.It Va min_residual +Minimum residual data chunk in second part of split. +.It Va strict_data_order +Enforce strict data ordering, abort if control inside data. +.It Va abort_at_limit +Abort when one-to-one hits qlimit. +.It Va hb_max_burst +Confirmation heartbeat max burst. +.It Va do_sctp_drain +Flush chunks in receive queues with TSN higher than the cumulative TSN if the +system is low on mbufs. +.It Va max_chained_mbufs +Default max number of small mbufs on a chain. +.It Va abc_l_var +SCTP ABC max increase per SACK (L). +.It Va nat_friendly +SCTP NAT friendly operation. +.It Va cmt_use_dac +CMT DAC on/off flag. +.It Va cmt_on_off +CMT settings. +.It Va outgoing_streams +Default number of outgoing streams. +.It Va incoming_streams +Default number of incoming streams. +.It Va add_more_on_output +When space-wise is it worthwhile to try to add more to a socket send buffer. +.It Va path_pf_threshold +Default potentially failed threshold. +.It Va path_rtx_max +Default maximum of retransmissions per path. +.It Va assoc_rtx_max +Default maximum number of retransmissions per association. +.It Va init_rtx_max +Default maximum number of retransmissions for INIT chunks. +.It Va valid_cookie_life +Default cookie lifetime in seconds. +.It Va init_rto_max +Default maximum retransmission timeout during association setup in ms. +.It Va rto_initial +Default initial retransmission timeout in ms. +.It Va rto_min +Default minimum retransmission timeout in ms. +.It Va rto_max +Default maximum retransmission timeout in ms. +.It Va secret_lifetime +Default secret lifetime in seconds. +.It Va shutdown_guard_time +Shutdown guard timer in seconds (0 means 5 times RTO.Max). +.It Va pmtu_raise_time +Default PMTU raise timer in seconds. +.It Va heartbeat_interval +Default heartbeat interval in ms. +.It Va asoc_resource +Max number of cached resources in an association. +.It Va sys_resource +Max number of cached resources in the system. +.It Va sack_freq +Default SACK frequency. +.It Va delayed_sack_time +Default delayed SACK timer in ms. +.It Va chunkscale +Tunable for scaling of number of chunks and messages. +.It Va min_split_point +Minimum size when splitting a chunk. +.It Va pcbhashsize +Tunable for PCB hash table sizes. +.It Va tcbhashsize +Tunable for TCB hash table sizes. +.It Va maxchunks +Default max chunks on queue per association. +.It Va fr_maxburst +Default max burst for SCTP endpoints when fast retransmitting. +.It Va maxburst +Default max burst for SCTP endpoints. +.It Va peer_chkoh +Amount to debit peers rwnd per chunk sent. +.It Va strict_sacks +Enable SCTP Strict SACK checking. +.It Va pktdrop_enable +Enable SCTP PKTDROP. +.It Va nrsack_enable +Enable SCTP NR-SACK. +.It Va reconfig_enable +Enable SCTP RE-CONFIG. +.It Va asconf_enable +Enable SCTP ASCONF. +.It Va auth_enable +Enable SCTP AUTH. +.It Va pr_enable +Enable PR-SCTP. +.It Va auto_asconf +Enable SCTP Auto-ASCONF. +.It Va recvspace +Maximum incoming SCTP buffer size. +.It Va sendspace +Maximum outgoing SCTP buffer size. +.El +.El +.Sh SEE ALSO +.Xr accept 2 , +.Xr bind 2 , +.Xr connect 2 , +.Xr listen 2 , +.Xr sctp_bindx 3 , +.Xr sctp_connectx 3 , +.Xr sctp_opt_info 3 , +.Xr sctp_recvmsg 3 , +.Xr sctp_sendmsg 3 , +.Xr blackhole 4 +.Sh BUGS +The +.Nm +kernel module cannot be unloaded. diff --git a/static/freebsd/man4/sdhci.4 b/static/freebsd/man4/sdhci.4 new file mode 100644 index 00000000..1608d9c2 --- /dev/null +++ b/static/freebsd/man4/sdhci.4 @@ -0,0 +1,90 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2008 Alexander Motin +.\" 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. 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 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 October 3, 2025 +.Dt SDHCI 4 +.Os +.Sh NAME +.Nm sdhci +.Nd PCI SD Host Controller bridge driver +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device mmc" +.Cd "device mmcsd" +.Cd "device sdhci" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the +following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +mmc_load="YES" +mmcsd_load="YES" +sdhci_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports PCI devices with class 8 and subclass 5 according to +SD Host Controller Specification. +Driver supports up to six high speed 4bit MMC/SD slots per controller. +Driver attaches mmc bus to the respective slot on card insertion and +detaches it on card removing. +.Sh HARDWARE +The +.Nm +driver supports the SD Host Controller Specification. +When attaching via the PCI bus, +the controller is automatically configured. +Many SoC chips provide a SDHCI controller directly mapped to I/O memory. +For those, the controller may be configured using +.Xr fdt 4 +or +.Xr acpi 4 +methods, supplied by your board's vendor. +.Pp +Unlike most other drivers that support a generic standard, +.Nm +requires a large number of quirks to cope with hardware bugs, +proprietary registers and poorly specified power management. +While many chipsets from +Intel, Xilinx, Rockchip, Frescale, Ricoh, and TI have these entries, +suboptimal performance may result when using some controllers. +Quirks and custom configuration are most often required +when the device is configured via +.Xr fdt 4 +or +.Xr acpi 4 . +.Sh SEE ALSO +.Xr mmc 4 , +.Xr mmcsd 4 +.Rs +.%T "SD Specifications, Part 2, SD Host Controller, Simplified Specification" +.Re +.Sh AUTHORS +.An Alexander Motin Aq Mt mav@FreeBSD.org diff --git a/static/freebsd/man4/sem.4 b/static/freebsd/man4/sem.4 new file mode 100644 index 00000000..f2331738 --- /dev/null +++ b/static/freebsd/man4/sem.4 @@ -0,0 +1,79 @@ +.\" Copyright (c) 2002 Tim J. Robbins +.\" 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 February 7, 2014 +.Dt SEM 4 +.Os +.Sh NAME +.Nm sem +.Nd POSIX semaphores +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "options P1003_1B_SEMAPHORES" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +sem_load="YES" +.Ed +.Pp +To load the driver as a module at run-time, run the following +command as root: +.Bd -ragged -offset indent +kldload sem +.Ed +.Sh DESCRIPTION +The +.Nm +facility provides system calls used by the standard C library +.Pq Pa libc +to implement +.Tn POSIX +semaphores. +This facility offers support for such functions as +.Fn sem_init +and +.Fn sem_wait . +It is available both as a kernel option for static inclusion and as a +dynamic kernel module. +.Sh SEE ALSO +.Xr sem_destroy 3 , +.Xr sem_getvalue 3 , +.Xr sem_init 3 , +.Xr sem_open 3 , +.Xr sem_post 3 , +.Xr sem_wait 3 , +.Xr config 8 , +.Xr kldload 8 , +.Xr kldunload 8 +.Sh HISTORY +The +.Nm +facility appeared in +.Fx 5.0 . diff --git a/static/freebsd/man4/send.4 b/static/freebsd/man4/send.4 new file mode 100644 index 00000000..06e04f3c --- /dev/null +++ b/static/freebsd/man4/send.4 @@ -0,0 +1,212 @@ +.\"- +.\" Copyright (c) 2010 Ana Kukec +.\" 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 September 19, 2010 +.Dt SEND 4 +.Os +.Sh NAME +.Nm send +.Nd "Kernel side support for Secure Neighbor Discovery (SeND)" +.Sh SYNOPSIS +.In sys/socket.h +.In netinet/in.h +.In netinet6/send.h +.Ft int +.Fn socket PF_INET6 SOCK_RAW IPPROTO_SEND +.Pp +To load the driver as a module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +send_load="YES" +.Ed +.Sh DESCRIPTION +IPv6 nodes use the Neighbor Discovery Protocol (NDP) to discover other nodes +on the link, to determine their link-layer addresses to find routers, and +to maintain reachability information about the paths to active members. +NDP is vulnerable to various attacks [RFC3756]. +Secure Neighbor Discovery is a set of extensions to NDP that counter threats +to NDP [RFC3971]. +.Pp +Kernel side support for SeND consists of a kernel module with hooks that +divert relevant packets (Neighbor Solicitations, Neighbor Advertisements, +Router Solicitations, Router Advertisements and Redirects) from the NDP stack, +send them to user space on a dedicated socket and reinject them back for +further processing. +Hooks are triggered only if the +.Nm +module is loaded. +.Pp +The native SeND socket is similar to a raw IP socket, but with its own, +internal pseudo-protocol (IPPROTO_SEND). +Struct sockaddr_send is defined in +.In netinet6/send.h . +It defines the total length of the structure, the address family, packet's +incoming or outgoing direction from the interface's point of view, and the +interface index. +.Bd -literal +struct sockaddr_send { + unsigned char send_len; /* total length */ + sa_family_t send_family; /* address family */ + int send_direction; + int send_ifidx; + char send_zero[8]; +}; +.Ed +.Pp +The address family is always +.Va AF_INET6 . +The +.Va send_direction +variable denotes the direction of the packet from the interface's +point of view and has either the value +.Dv SND_IN +or +.Dv SND_OUT . +The +.Va send_ifidx +variable is the interface index of the receiving or sending interface. +The +.Va send_zero +variable is padding and must always be zero. +.Pp +In case that no user space application is connected to the send socket, +processing continues normally as if the module was not loaded. +.Sh INPUT HOOK +The input hook is named after the input path of the incoming or outgoing +NDP packets, on the way from the wire, through the nd6 stack, to user +space. +Relevant packets are identified by adding an mbuf_tag +(see +.Xr mbuf_tags 9 ) +to the +.Xr mbuf 9 , +if the +.Nm +module is loaded. +It is then passed on to the kernel-userland interface +for either cryptographic protection or validation by the SeND application. +The hook takes an argument that describes the direction of the packet, both +in case of incoming and outgoing packets. +.Dv SND_IN +is the direction of the incoming packets that are usually protected +by the SeND options and then sent to user space for cryptographic validation. +.Dv SND_OUT +is the outgoing direction. +It describes both reply and locally +originated outgoing packets that are sent to user space for the addition +of SeND options. +.Sh INCOMING PACKETS +The incoming ND packet from the wire: +.Bd -literal + kernelspace ( userspace + ) + incoming SeND/ND packet ( + | ) + v ( SND_IN ) ( + icmp6_input() -> send_input_hook ---> send socket ----+ + : ) | + : # # ( | + normal : # # ) v + processing : # send.ko # ( SeND application + path : # # ) | + : # # ( | + v ) | + icmp6/nd6_??_input() <- protocol switch <--- send socket <---+ + | structure (IPPPROTO_SEND) ) + | ( SND_IN ) ( + v ) + continue normal ND processing ( +.Ed +.Sh OUTGOING PACKETS +Outgoing ND packet (reply or locally triggered): +.Bd -literal + kernelspace ( userspace + ) + nd6_na_input() ( + +PACKET_TAG_ND_OUTGOING ) + | ) + | outgoing packet ( + | | ) + | v ( + | icmp6_redirect_output() ) + | nd6_ns_output() ( + | nd6_na_output() ) + | +PACKET_TAG_ND_OUTGOING ( + | | ) + | +-----------<- rip6_output() <----------)----- rtsol/rtadvd/.. + | | +PACKET_TAG_ND_OUTGOING ( + | v ) + | ip6_output() ( + | | ) + +-------->-+ ( + | ) + v ( SND_OUT ) ( + nd6_output_lle() -> send_input_hook ---> send socket ----+ + -PACKET_TAG_ND_OUTGOING ) | + : # # ( | + normal : # # ) v + processing : # send.ko # ( SeND application + path : # # ) | + : # # ( | + v ) | + (*ifp->if_output)() <- protocol switch <--- send socket <---+ + | structure (IPPPROTO_SEND) ) + | ( SND_OUT ) ( + v ) + continue with normal packet output ( +.Ed +.Sh ERRORS +A socket operation may fail with one of the following errors returned: +.Bl -tag -width Er +.It Bq Er EEXIST +Another user space SeND application is bound to the socket. +.It Bq Er ENOBUFS +Shortage of space to receive the incoming (SeND-protected) or outgoing +(SeND-validated) packet from the SeND application. +.It Bq Er ENOSYS +A packet received from user space and passed to the NDP stack for further +processing is neither Neighbor Solicitation, Neighbor Advertisement, +Router Solicitation, Router Advertisement nor Redirect. +.It Bq Er ENOENT +Occurs if interface output routines fail to send the packet out of the +interface. +.El +.Sh SEE ALSO +.Xr recvfrom 2 , +.Xr sendto 2 , +.Xr socket 2 , +.Xr loader.conf 5 +.Sh HISTORY +The +.Nm +module first appeared in +.Fx 9.0 . +.Sh AUTHORS +.An Ana Kukec Aq Mt anchie@FreeBSD.org , +University of Zagreb +.Sh BUGS +Due to the lack of NDP locking, it is currently not possible to unload the +.Nm +module. diff --git a/static/freebsd/man4/ses.4 b/static/freebsd/man4/ses.4 new file mode 100644 index 00000000..8de664c8 --- /dev/null +++ b/static/freebsd/man4/ses.4 @@ -0,0 +1,151 @@ +.\" Copyright (c) 2000 +.\" Matthew Jacob . 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 November 12, 2019 +.Dt SES 4 +.Os +.Sh NAME +.Nm ses +.Nd SCSI Environmental Services driver +.Sh SYNOPSIS +.Cd device ses +.Sh DESCRIPTION +The +.Nm +driver provides support for all +.Tn SCSI +devices of the environmental services class that are attached to the system +through a supported +.Tn SCSI +Host Adapter, as well as emulated support for SAF-TE (SCSI Accessible +Fault Tolerant Enclosures). +The environmental services class generally are enclosure devices that +provide environmental information such as number of power supplies (and +state), temperature, device slots, and so on. +.Pp +A +.Tn SCSI +Host +adapter must also be separately configured into the system +before a +.Tn SCSI +Environmental Services device can be configured. +.Sh KERNEL CONFIGURATION +It is only necessary to explicitly configure one +.Nm +device; data structures are dynamically allocated as devices are found +on the +.Tn SCSI +bus. +.Pp +A separate option, +.Va SES_ENABLE_PASSTHROUGH , +may be specified to allow the +.Nm +driver to perform functions on devices of other classes that claim to +also support +.Nm +functionality. +.Sh IOCTLS +The following +.Xr ioctl 2 +calls apply to +.Nm +devices. +They are defined in the header file +.In cam/scsi/scsi_enc.h +(\fIq.v.\fR). +.Bl -tag -width ENCIOC_GETENCSTAT +.It Dv ENCIOC_GETNELM +Used to find out how many +.Nm +elements are driven by this particular device instance. +.It Dv ENCIOC_GETELMMAP +Read, from the kernel, an array of SES elements which contains +the element identifier, which subenclosure it is in, and the +.Nm +type of the element. +.It Dv ENCIOC_GETENCSTAT +Get the overall enclosure status. +.It Dv ENCIOC_SETENCSTAT +Set the overall enclosure status. +.It Dv ENCIOC_GETELMSTAT +Get the status of a particular element. +.It Dv ENCIOC_SETELMSTAT +Set the status of a particular element. +.It Dv ENCIOC_GETTEXT +Get the associated help text for an element (not yet implemented). +.Nm +devices often have descriptive text for an element which can tell +you things like location (e.g., "left power supply"). +.It Dv ENCIOC_INIT +Initialize the enclosure. +.It Dv ENCIOC_GETELMDESC +Get the element's descriptor string. +.It Dv ENCIOC_GETELMDEVNAMES +Get the device names, if any, associated with this element. +.It Dv ENCIOC_GETSTRING +Used to read the SES String In Diagnostic Page. +The contents of this page are device-specific. +.It Dv ENCIOC_SETSTRING +Used to set the SES String Out Diagnostic Page. +The contents of this page are device-specific. +.It Dv ENCIOC_GETENCNAME +Used to get the name of the enclosure. +.It Dv ENCIOC_GETENCID +Used to get the Enclosure Logical Identifier. +.El +.Sh EXAMPLE USAGE +The files contained in +.In /usr/share/examples/ses +show simple mechanisms for how to use these interfaces, as well as a +very stupid simple monitoring daemon. +.Sh FILES +.Bl -tag -width /dev/rsdXXXXX -compact +.It Pa /dev/ses Ns Ar N +The +.Em Nth +.Nm SES +device. +.El +.Sh DIAGNOSTICS +When the kernel is configured with +.Tn DEBUG +enabled, the first open to an SES device will spit out overall enclosure +parameters to the console. +.Sh SEE ALSO +.Xr sesutil 8 +.Sh HISTORY +The +.Nm +driver was originally written for the +.Tn CAM +.Tn SCSI +subsystem by Matthew Jacob and first released in +.Fx 4.3 . +It was a functional equivalent of a similar +driver available in Solaris, Release 7. +It was largely rewritten by Alexander Motin, Justin Gibbs, and Will Andrews for +.Fx 9.2 . diff --git a/static/freebsd/man4/sfxge.4 b/static/freebsd/man4/sfxge.4 new file mode 100644 index 00000000..ea35cf3e --- /dev/null +++ b/static/freebsd/man4/sfxge.4 @@ -0,0 +1,187 @@ +.\" Copyright (c) 2011-2016 Solarflare Communications Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright notice, +.\" this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright notice, +.\" this list of conditions and the following disclaimer in the documentation +.\" and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 COPYRIGHT OWNER 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. +.\" +.\" The views and conclusions contained in the software and documentation are +.\" those of the authors and should not be interpreted as representing official +.\" policies, either expressed or implied, of the FreeBSD Project. +.\" +.Dd February 22, 2015 +.Dt SFXGE 4 amd64 +.Os +.Sh NAME +.Nm sfxge +.Nd "Solarflare 10Gb Ethernet adapter driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device sfxge" +.Ed +.Pp +To load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +sfxge_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for 10Gb Ethernet adapters based on +Solarflare SFC9000 and XtremeScale X2 family controllers. +The driver supports jumbo +frames, transmit/receive checksum offload, TCP Segmentation Offload +(TSO), Large Receive Offload (LRO), VLAN checksum offload, VLAN TSO, +and Receive Side Scaling (RSS) using MSI-X interrupts. +.Pp +The driver allocates 1 receive queue, transmit queue, event queue and +IRQ per CPU up to a maximum of 64. +IRQ affinities should be spread out using +.Xr cpuset 1 . +Interrupt moderation may be controlled through the sysctl +.Va dev.sfxge.%d.int_mod +(units are microseconds). +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Pp +A large number of MAC, PHY and data path statistics are available +under the sysctl +.Va dev.sfxge.%d.stats . +The adapter's VPD +fields including its serial number are available under the sysctl +.Va dev.sfxge.%d.vpd . +.Sh HARDWARE +The +.Nm +driver supports all 10Gb Ethernet adapters based on Solarflare SFC9000 +family controllers. +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +Actual values can be obtained using +.Xr sysctl 8 . +.Bl -tag -width indent +.It Va hw.sfxge.rx_ring +The maximum number of descriptors in a receive queue ring. +Supported values are: 512, 1024, 2048 and 4096. +.It Va hw.sfxge.tx_ring +The maximum number of descriptors in a transmit queue ring. +Supported values are: 512, 1024, 2048 and 4096. +.It Va hw.sfxge.tx_dpl_get_max +The maximum length of the deferred packet +.Dq get-list +for queued transmit packets (TCP and non-TCP), used only if the transmit +queue lock can be acquired. +If a packet is dropped, the +.Va tx_get_overflow +counter is incremented and the local sender receives ENOBUFS. +The value must be greater than 0. +.It Va hw.sfxge.tx_dpl_get_non_tcp_max +The maximum number of non-TCP packets in the deferred packet +.Dq get-list +, used only if the transmit queue lock can be acquired. +If a packet is dropped, the +.Va tx_get_non_tcp_overflow +counter is incremented and the local sender receives ENOBUFS. +The value must be greater than 0. +.It Va hw.sfxge.tx_dpl_put_max +The maximum length of the deferred packet +.Dq put-list +for queued transmit +packets, used if the transmit queue lock cannot be acquired. +If a packet is dropped, the +.Va tx_put_overflow +counter is incremented and the local sender receives ENOBUFS. +The value must be greater than or equal to 0. +.It Va hw.sfxge.tso_fw_assisted +Bitmask to enable/disable usage of FW-assisted TSO version if supported +by NIC firmware. +FATSOv1 (bit 0) and FATSOv2 (bit 1) are supported. +All enabled by default. +.It Va hw.sfxge.N.max_rss_channels +The maximum number of allocated RSS channels for the Nth adapter. +If set to 0 or unset, the number of channels is determined by the number +of CPU cores. +.It Va hw.sfxge.lro.table_size +Size of the LRO hash table. +Must be a power of 2. +A larger table means we can accelerate a larger number of streams. +.It Va hw.sfxge.lro.chain_max +The maximum length of a hash chain. +If chains get too long then the lookup time increases and may exceed +the benefit of LRO. +.It Va hw.sfxge.lro.idle_ticks +The maximum time (in ticks) that a connection can be idle before it's LRO +state is discarded. +.It Va hw.sfxge.lro.slow_start_packets +Number of packets with payload that must arrive in-order before a connection +is eligible for LRO. +The idea is we should avoid coalescing segments when the sender is in +slow-start because reducing the ACK rate can damage performance. +.It Va hw.sfxge.lro.loss_packets +Number of packets with payload that must arrive in-order following loss +before a connection is eligible for LRO. +The idea is we should avoid coalescing segments when the sender is recovering +from loss, because reducing the ACK rate can damage performance. +.It Va hw.sfxge.mcdi_logging +Enable logging of MCDI protocol messages (only available if enabled at compile-time). +.It Va hw.sfxge.N.mcdi_logging +Enable or disable logging of MCDI protocol messages on a per-port basis. +The default for each port will be the value of +.Va hw.sfxge.mcdi_logging. +The logging may also be enabled or disabled after the driver is loaded using the sysctl +.Va dev.sfxge.%d.mcdi_logging. +.It Va hw.sfxge.stats_update_period_ms +Period in milliseconds to refresh interface statistics from hardware. +The accepted range is 0 to 65535, the default is 1000 (1 second). +Use zero value to disable periodic statistics update. +Supported on SFN8xxx series adapters with firmware v6.2.1.1033 and later and +SFN5xxx, SFN6xxx and XtremeScale X2xxx series adapters. +SFN7xxx series adapters and sfN8xxx series with earlier firmware use a +fixed 1000 milliseconds statistics update period. +The period may also be changed after the driver is loaded using the sysctl +.Va dev.sfxge.%d.stats_update_period_ms . +.El +.Sh SUPPORT +For general information and support, +go to the Solarflare support website at: +.Pa https://support.solarflare.com . +.Sh SEE ALSO +.Xr cpuset 1 , +.Xr arp 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh AUTHORS +The +.Nm +driver was written by +.An Philip Paeps +and +.An Solarflare Communications, Inc. diff --git a/static/freebsd/man4/sg.4 b/static/freebsd/man4/sg.4 new file mode 100644 index 00000000..ac549452 --- /dev/null +++ b/static/freebsd/man4/sg.4 @@ -0,0 +1,63 @@ +.\" +.\" Copyright (c) 2024 Netflix, Inc. +.\" +.\" SPDX-License-Expression: BSD-2-Clause +.\" +.Dd May 6, 2024 +.Dt SG 4 +.Os +.Sh NAME +.Nm sg +.Nd Linux ioctl-compatible SCSI passthru device +.Sh SYNOPSIS +.Cd device sg +.Cd device scbus +.Sh DESCRIPTION +The +.Nm +driver provides a Linux compatible scsi passthru device. +This driver attaches to all +.Xr cam 4 +peripheral devices. +It is similar to the +.Xr pass 4 +device, but uses the Linux interfaces, rather than the FreeBSD CAM interfaces. +.Sh IOCTL +The following subset of the Linux sg ioctl interfaces are implemented: +.Bl -tag -width 12 +.It Va SG_SET_TIMEOUT +.Fa u_int to +Set the timeout in milliseconds. +.It Va SG_GET_TIMEOUT +Get the timeout in milliseconds +.It Va SG_GET_RESERVED_SIZE +.Fa u_int +Returns the size of the I/O one can do this device. +.It Va SG_GET_SCSI_ID +.Fa struct sg_scsi_id +Returns the bus number, channel, scsi bus ID number, lun and other information +about the SCSI device. +.It Va SG_GET_SG_TABLESIZE +.Fa u_int +Returns the table size, though hard wired to 0. +.It Va SG_GET_VERSION_NUM +.Fa u_int +Return the version number that is implemented. +.It Va SG_IO +.Fa struct sg_io_hdr +.El +All other ioctl interfaces return +.Va ENODEV . +.Sh FILES +.Bl -tag -width ".Pa /dev/sg*" -compact +.It Pa /dev/sg* +Passthru devices. +.El +.Sh SEE ALSO +.Xr cam 4 , +.Xr pass 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 7.0 . diff --git a/static/freebsd/man4/sge.4 b/static/freebsd/man4/sge.4 new file mode 100644 index 00000000..cdcedc81 --- /dev/null +++ b/static/freebsd/man4/sge.4 @@ -0,0 +1,117 @@ +.\" Copyright (c) 2010 Pyun YongHyeon +.\" 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 January 16, 2011 +.Dt SGE 4 +.Os +.Sh NAME +.Nm sge +.Nd Silicon Integrated Systems SiS190/191 Fast/Gigabit Ethernet driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device sge" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_sge_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +device driver provides support for SiS190 Fast Ethernet +controllers and SiS191 Fast/Gigabit Ethernet controllers. +.Pp +All LOMs supported by the +.Nm +driver have TCP/UDP/IP checksum offload for transmit and receive, +TCP segmentation offload (TSO), hardware VLAN tag stripping/insertion +features. +Due to lack of documentation Wake On Lan (WOL), Jumbo frame and an +interrupt moderation mechanism are not supported yet. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width ".Cm 10baseT/UTP" +.It Cm autoselect +Enable autoselection of the media type and options. +The user can manually override +the autoselected mode by adding media options to +.Xr rc.conf 5 . +.It Cm 10baseT/UTP +Set 10Mbps operation. +.It Cm 100baseTX +Set 100Mbps (Fast Ethernet) operation. +.It Cm 1000baseTX +Set 1000baseTX operation over twisted pair. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width ".Cm full-duplex" +.It Cm full-duplex +Force full duplex operation. +.It Cm half-duplex +Force half duplex operation. +.El +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +device driver provides support for the following Ethernet controllers: +.Pp +.Bl -bullet -compact +.It +SiS190 Fast Ethernet controller +.It +SiS191 Fast/Gigabit Ethernet controller +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr rgephy 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +driver was written by +.An Alexander Pohoyda Aq Mt alexander.pohoyda@gmx.net . +And enhanced by +.An Nikolay Denev Aq Mt ndenev@gmail.com . +It first appeared in +.Fx 8.1 . diff --git a/static/freebsd/man4/siba.4 b/static/freebsd/man4/siba.4 new file mode 100644 index 00000000..4191971d --- /dev/null +++ b/static/freebsd/man4/siba.4 @@ -0,0 +1,91 @@ +.\" Copyright (c) 2010 Weongyo Jeong +.\" 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 September 13, 2017 +.Dt SIBA 4 +.Os +.Sh NAME +.Nm siba +.Nd Sonic Inc. Silicon Backplane driver +.Sh SYNOPSIS +To compile this driver into the kernel, add the following lines to the +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device bhnd" +.Cd "device siba" +.Ed +.Pp +To load the driver as a module at boot, add this line to +.Xr loader.conf 5 : +.Bd -literal -offset indent +siba_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides +.Xr bhnd 4 +support for devices based on the Sonic Inc. Silicon Backplane, an +interblock communications architecture found in earlier Broadcom Home +Networking Division wireless chipsets and embedded systems. +.Pp +A common interconnect connects all of the Silicon Backplane's functional +blocks. +These functional blocks, known as cores, use the Open Core Protocol +(OCP) interface to communicate with agents attached to the Silicon +Backplane. +.Pp +Each core can have an initiator agent that passes read and write +requests onto the system backplane and a target agent that returns +responses to those requests. +Not all cores contain both an initiator and a target agent. +Initiator agents are present in cores that contain +host interfaces (PCI, PCMCIA), embedded processors (MIPS), +or DMA processors associated with communications cores. +.Sh SEE ALSO +.Xr bcma 4 , +.Xr bhnd 4 , +.Xr intro 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 8.0 . +The driver was rewritten for +.Fx 11.0 +to support the common Broadcom +.Xr bhnd 4 +bus interface. +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was originally written by +.An Bruce M. Simpson Aq Mt bms@FreeBSD.org +and +.An Weongyo Jeong Aq Mt weongyo@FreeBSD.org . +The driver was rewritten for +.Fx 11.0 +by +.An Landon Fuller Aq Mt landonf@FreeBSD.org . diff --git a/static/freebsd/man4/siftr.4 b/static/freebsd/man4/siftr.4 new file mode 100644 index 00000000..719ba0e3 --- /dev/null +++ b/static/freebsd/man4/siftr.4 @@ -0,0 +1,744 @@ +.\" +.\" Copyright (c) 2010 The FreeBSD Foundation +.\" +.\" Portions of this software were developed at the Centre for Advanced +.\" Internet Architectures, Swinburne University of Technology, Melbourne, +.\" Australia by Lawrence Stewart under sponsorship from the FreeBSD +.\" Foundation. +.\" +.\" 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, +.\" without modification, immediately at the beginning of the file. +.\" 2. 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 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 May 29, 2023 +.Dt SIFTR 4 +.Os +.Sh NAME +.Nm SIFTR +.Nd Statistical Information For TCP Research +.Sh SYNOPSIS +To load +the driver +as a module at run-time, run the following command as root: +.Bd -literal -offset indent +kldload siftr +.Ed +.Pp +Alternatively, to load +the driver +as a module at boot time, add the following line into the +.Xr loader.conf 5 +file: +.Bd -literal -offset indent +siftr_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +.Po +.Em S Ns tatistical +.Em I Ns nformation +.Em F Ns or +.Em T Ns CP +.Em R Ns esearch +.Pc +kernel module logs a range of statistics on active TCP connections to +a log file. +It provides the ability to make highly granular measurements of TCP connection +state, aimed at system administrators, developers and researchers. +.Ss Compile-time Configuration +The default operation of +.Nm +is to capture IPv4 TCP/IP packets. +.Nm +can be configured to support IPv4 and IPv6 by uncommenting: +.Bd -literal -offset indent +CFLAGS+=-DSIFTR_IPV6 +.Ed +.Pp +in +.Aq sys/modules/siftr/Makefile +and recompiling. +.Pp +In the IPv4-only (default) mode, standard dotted decimal notation (e.g. +"136.186.229.95") is used to format IPv4 addresses for logging. +In IPv6 mode, standard dotted decimal notation is used to format IPv4 addresses, +and standard colon-separated hex notation (see RFC 4291) is used to format IPv6 +addresses (e.g. "fd00::2") for logging. +.Ss Run-time Configuration +.Nm +utilises the +.Xr sysctl 8 +interface to export its configuration variables to user-space. +The following variables are available: +.Bl -tag -offset indent -width Va +.It Va net.inet.siftr.enabled +controls whether the module performs its +measurements or not. +By default, the value is set to 0, which means the module +will not be taking any measurements. +Having the module loaded with +.Va net.inet.siftr.enabled +set to 0 will have no impact on the performance of the network stack, as the +packet filtering hooks are only inserted when +.Va net.inet.siftr.enabled +is set to 1. +.El +.Bl -tag -offset indent -width Va +.It Va net.inet.siftr.ppl +controls how many inbound/outbound packets for a given TCP connection will cause +a log message to be generated for the connection. +By default, the value is set to 1, which means the module will log a message for +every packet of every TCP connection. +The value can be set to any integer in the range [1,2^32], and can be changed at +any time, even while the module is enabled. +.El +.Bl -tag -offset indent -width Va +.It Va net.inet.siftr.logfile +controls the path to the file that the module writes its log messages to. +By default, the file /var/log/siftr.log is used. +The path can be changed at any time, even while the module is enabled. +.El +.Bl -tag -offset indent -width Va +.It Va net.inet.siftr.port_filter +controls on which source or destination port +.Nm +should capture. +By default, the value is set to 0, which means all ports are eligible for logging. +Set to any other value, only packets where either the source or destination +port is equal to this number are logged. +.El +.Ss Log Format +A typical +.Nm +log file will contain 3 different types of log message. +All messages are written in plain ASCII text. +.Pp +Note: The +.Qq \e +present in the example log messages in this section indicates a +line continuation and is not part of the actual log message. +.Pp +The first type of log message is written to the file when the module is +enabled and starts collecting data from the running kernel. +The text below shows an example module enable log. +The fields are tab delimited key-value +pairs which describe some basic information about the system. +.Bd -literal -offset indent +enable_time_secs=1685191807 enable_time_usecs=160752 \\ +siftrver=1.3.0 sysname=FreeBSD sysver=1400089 ipmode=4 +.Ed +.Pp +Field descriptions are as follows: +.Bl -tag -offset indent -width Va +.It Va enable_time_secs +time at which the module was enabled, in seconds since the UNIX epoch. +.El +.Bl -tag -offset indent -width Va +.It Va enable_time_usecs +time at which the module was enabled, in microseconds since enable_time_secs. +.El +.Bl -tag -offset indent -width Va +.It Va siftrver +version of +.Nm . +.El +.Bl -tag -offset indent -width Va +.It Va sysname +operating system name. +.El +.Bl -tag -offset indent -width Va +.It Va sysver +operating system version. +.El +.Bl -tag -offset indent -width Va +.It Va ipmode +IP mode as defined at compile time. +An ipmode of "4" means IPv6 is not supported and IP addresses are logged in +regular dotted quad format. +An ipmode of "6" means IPv6 is supported, and IP addresses are logged in dotted +quad or hex format, as described in the +.Qq Compile-time Configuration +subsection. +.El +.Pp +The second type of log message is written to the file when a data log message +is generated. +The text below shows an example data log triggered by an IPv4 +TCP/IP packet. +The data is CSV formatted. +.Bd -literal -offset indent +o,1685191814.185109,10.1.1.2,32291,10.1.1.3,5001,1073725440, \\ +14480,2,65160,65700,7,9,4,1460,1000,1,16778209,230000,33580,0, \\ +65700,0,0,0,86707916,130 +.Ed +.Pp +Field descriptions are as follows: +.Bl -tag -offset indent -width Va +.It Va 1 +Direction of packet that triggered the log message. +Either +.Qq i +for in, or +.Qq o +for out. +.El +.Bl -tag -offset indent -width Va +.It Va 2 +Time at which the packet that triggered the log message was processed by +the +.Xr pfil 9 +hook function, in seconds and microseconds since the UNIX epoch. +.El +.Bl -tag -offset indent -width Va +.It Va 3 +The IPv4 or IPv6 address of the local host, in dotted quad (IPv4 packet) +or colon-separated hex (IPv6 packet) notation. +.El +.Bl -tag -offset indent -width Va +.It Va 4 +The TCP port that the local host is communicating via. +.El +.Bl -tag -offset indent -width Va +.It Va 5 +The IPv4 or IPv6 address of the foreign host, in dotted quad (IPv4 packet) +or colon-separated hex (IPv6 packet) notation. +.El +.Bl -tag -offset indent -width Va +.It Va 6 +The TCP port that the foreign host is communicating via. +.El +.Bl -tag -offset indent -width Va +.It Va 7 +The slow start threshold for the flow, in bytes. +.El +.Bl -tag -offset indent -width Va +.It Va 8 +The current congestion window for the flow, in bytes. +.El +.Bl -tag -offset indent -width Va +.It Va 9 +The current state of the t_flags2 field for the flow. +.El +.Bl -tag -offset indent -width Va +.It Va 10 +The current sending window for the flow, in bytes. +The post scaled value is reported. +.El +.Bl -tag -offset indent -width Va +.It Va 11 +The current receive window for the flow, in bytes. +The post scaled value is always reported. +.El +.Bl -tag -offset indent -width Va +.It Va 12 +The current window scaling factor for the sending window. +.El +.Bl -tag -offset indent -width Va +.It Va 13 +The current window scaling factor for the receiving window. +.El +.Bl -tag -offset indent -width Va +.It Va 14 +The current state of the TCP finite state machine, as defined +in +.Aq Pa netinet/tcp_fsm.h . +.El +.Bl -tag -offset indent -width Va +.It Va 15 +The maximum segment size for the flow, in bytes. +.El +.Bl -tag -offset indent -width Va +.It Va 16 +The current smoothed RTT estimate for the flow, in units of microsecond. +.El +.Bl -tag -offset indent -width Va +.It Va 17 +SACK enabled indicator. 1 if SACK enabled, 0 otherwise. +.El +.Bl -tag -offset indent -width Va +.It Va 18 +The current state of the TCP flags for the flow. +See +.Aq Pa netinet/tcp_var.h +for information about the various flags. +.El +.Bl -tag -offset indent -width Va +.It Va 19 +The current retransmission timeout length for the flow, in units microsecond. +.El +.Bl -tag -offset indent -width Va +.It Va 20 +The current size of the socket send buffer in bytes. +.El +.Bl -tag -offset indent -width Va +.It Va 21 +The current number of bytes in the socket send buffer. +.El +.Bl -tag -offset indent -width Va +.It Va 22 +The current size of the socket receive buffer in bytes. +.El +.Bl -tag -offset indent -width Va +.It Va 23 +The current number of bytes in the socket receive buffer. +.El +.Bl -tag -offset indent -width Va +.It Va 24 +The current number of unacknowledged bytes in-flight. +Bytes acknowledged via SACK are not excluded from this count. +.El +.Bl -tag -offset indent -width Va +.It Va 25 +The current number of segments in the reassembly queue. +.El +.Bl -tag -offset indent -width Va +.It Va 26 +Flowid for the connection. +A caveat: Zero '0' either represents a valid flowid or a default value when it's +not being set. +There is no easy way to differentiate without looking at actual +network interface card and drivers being used. +.El +.Bl -tag -offset indent -width Va +.It Va 27 +Flow type for the connection. +Flowtype defines which protocol fields are hashed to produce the flowid. +A complete listing is available in +.Pa sys/mbuf.h +under +.Dv M_HASHTYPE_* . +.El +.Pp +The third type of log message is written to the file when the module is disabled +and ceases collecting data from the running kernel. +The text below shows an example module disable log. +The fields are tab delimited key-value pairs which provide statistics about +operations since the module was most recently enabled. +.Bd -literal -offset indent +disable_time_secs=1685191816 disable_time_usecs=629397 \\ +num_inbound_tcp_pkts=10 num_outbound_tcp_pkts=10 \\ +total_tcp_pkts=20 num_inbound_skipped_pkts_malloc=0 \\ +num_outbound_skipped_pkts_malloc=0 num_inbound_skipped_pkts_tcpcb=2 \\ +num_outbound_skipped_pkts_tcpcb=2 num_inbound_skipped_pkts_inpcb=0 \\ +num_outbound_skipped_pkts_inpcb=0 total_skipped_tcp_pkts=4 \\ +flow_list=10.1.1.2;32291-10.1.1.3;5001,10.1.1.2;58544-10.1.1.3;5001, +.Ed +.Pp +Field descriptions are as follows: +.Bl -tag -offset indent -width Va +.It Va disable_time_secs +Time at which the module was disabled, in seconds since the UNIX epoch. +.El +.Bl -tag -offset indent -width Va +.It Va disable_time_usecs +Time at which the module was disabled, in microseconds since disable_time_secs. +.El +.Bl -tag -offset indent -width Va +.It Va num_inbound_tcp_pkts +Number of TCP packets that traversed up the network stack. +This only includes inbound TCP packets during the periods when +.Nm +was enabled. +.El +.Bl -tag -offset indent -width Va +.It Va num_outbound_tcp_pkts +Number of TCP packets that traversed down the network stack. +This only includes outbound TCP packets during the periods when +.Nm +was enabled. +.El +.Bl -tag -offset indent -width Va +.It Va total_tcp_pkts +The summation of num_inbound_tcp_pkts and num_outbound_tcp_pkts. +.El +.Bl -tag -offset indent -width Va +.It Va num_inbound_skipped_pkts_malloc +Number of inbound packets that were not processed because of failed +.Fn malloc +calls. +.El +.Bl -tag -offset indent -width Va +.It Va num_outbound_skipped_pkts_malloc +Number of outbound packets that were not processed because of failed +.Fn malloc +calls. +.El +.Bl -tag -offset indent -width Va +.It Va num_inbound_skipped_pkts_tcpcb +Number of inbound packets that were not processed because of failure to find the +TCP control block associated with the packet. +.El +.Bl -tag -offset indent -width Va +.It Va num_outbound_skipped_pkts_tcpcb +Number of outbound packets that were not processed because of failure to find +the TCP control block associated with the packet. +.El +.Bl -tag -offset indent -width Va +.It Va num_inbound_skipped_pkts_inpcb +Number of inbound packets that were not processed because of failure to find the +IP control block associated with the packet. +.El +.Bl -tag -offset indent -width Va +.It Va num_outbound_skipped_pkts_inpcb +Number of outbound packets that were not processed because of failure to find +the IP control block associated with the packet. +.El +.Bl -tag -offset indent -width Va +.It Va total_skipped_tcp_pkts +The summation of all skipped packet counters. +.El +.Bl -tag -offset indent -width Va +.It Va flow_list +A CSV list of TCP flows that triggered data log messages to be generated since +the module was loaded. +Each flow entry in the CSV list is +formatted as +.Qq local_ip;local_port-foreign_ip;foreign_port . +If there are no entries in the list (i.e., no data log messages were generated), +the value will be blank. +If there is at least one entry in the list, a trailing comma will always be +present. +.El +.Pp +The total number of data log messages found in the log file for a module +enable/disable cycle should equate to total_tcp_pkts - total_skipped_tcp_pkts. +.Sh IMPLEMENTATION NOTES +.Nm +hooks into the network stack using the +.Xr pfil 9 +interface. +In its current incarnation, it hooks into the AF_INET/AF_INET6 (IPv4/IPv6) +.Xr pfil 9 +filtering points, which means it sees packets at the IP layer of the network +stack. +This means that TCP packets inbound to the stack are intercepted before +they have been processed by the TCP layer. +Packets outbound from the stack are intercepted after they have been processed +by the TCP layer. +.Pp +The diagram below illustrates how +.Nm +inserts itself into the stack. +.Bd -literal -offset indent +---------------------------------- + Upper Layers +---------------------------------- + ^ | + | | + | | + | v + TCP in TCP out +---------------------------------- + ^ | + |________ _________| + | | + | v + --------- + | SIFTR | + --------- + ^ | + ________| |__________ + | | + | v +IPv{4/6} in IPv{4/6} out +---------------------------------- + ^ | + | | + | v +Layer 2 in Layer 2 out +---------------------------------- + Physical Layer +---------------------------------- +.Ed +.Pp +.Nm +uses the +.Xr alq 9 +interface to manage writing data to disk. +.Pp +At first glance, you might mistakenly think that +.Nm +extracts information from +individual TCP packets. +This is not the case. +.Nm +uses TCP packet events (inbound and outbound) for each TCP flow originating from +the system to trigger a dump of the state of the TCP control block for that +flow. +With the PPL set to 1, we are in effect sampling each TCP flow's control block +state as frequently as flow packets enter/leave the system. +For example, setting PPL to 2 halves the sampling rate i.e., every second flow +packet (inbound OR outbound) causes a dump of the control block state. +.Pp +The distinction between interrogating individual packets versus interrogating the +control block is important, because +.Nm +does not remove the need for packet capturing tools like +.Xr tcpdump 1 . +.Nm +allows you to correlate and observe the cause-and-affect relationship between +what you see on the wire (captured using a tool like +.Xr tcpdump 1 Ns ) +and changes in the TCP control block corresponding to the flow of interest. +It is therefore useful to use +.Nm +and a tool like +.Xr tcpdump 1 +to gather the necessary data to piece together the complete picture. +Use of either tool on its own will not be able to provide all of the necessary +data. +.Pp +As a result of needing to interrogate the TCP control block, certain packets +during the lifecycle of a connection are unable to trigger a +.Nm +log message. +The initial handshake takes place without the existence of a control block or +the complete initialization of the control block, and the final ACK is +exchanged when the connection is in the TIMEWAIT state. +.Pp +.Nm +was designed to minimise the delay introduced to packets traversing the network +stack. +This design called for a highly optimised and minimal hook function that +extracted the minimal details necessary whilst holding the packet up, and +passing these details to another thread for actual processing and logging. +.Pp +This multithreaded design does introduce some contention issues when accessing +the data structure shared between the threads of operation. +When the hook function tries to place details in the structure, it must first +acquire an exclusive lock. +Likewise, when the processing thread tries to read details from the structure, +it must also acquire an exclusive lock to do so. +If one thread holds the lock, the other must wait before it can obtain it. +This does introduce some additional bounded delay into the kernel's packet +processing code path. +.Pp +In some cases (e.g., low memory, connection termination), TCP packets that enter +the +.Nm +.Xr pfil 9 +hook function will not trigger a log message to be generated. +.Nm +refers to this outcome as a +.Qq skipped packet . +Note that +.Nm +always ensures that packets are allowed to continue through the stack, even if +they could not successfully trigger a data log message. +.Nm +will therefore not introduce any packet loss for TCP/IP packets traversing the +network stack. +.Ss Important Behaviours +The behaviour of a log file path change whilst the module is enabled is as +follows: +.Bl -enum +.It +Attempt to open the new file path for writing. +If this fails, the path change will fail and the existing path will continue to +be used. +.It +Assuming the new path is valid and opened successfully: +.Bl -dash +.It +Flush all pending log messages to the old file path. +.It +Close the old file path. +.It +Switch the active log file pointer to point at the new file path. +.It +Commence logging to the new file. +.El +.El +.Pp +During the time between the flush of pending log messages to the old file and +commencing logging to the new file, new log messages will still be generated and +buffered. +As soon as the new file path is ready for writing, the accumulated log messages +will be written out to the file. +.Sh EXAMPLES +To enable the module's operations, run the following command as root: +sysctl net.inet.siftr.enabled=1 +.Pp +To change the granularity of log messages such that 1 log message is +generated for every 10 TCP packets per connection, run the following +command as root: +sysctl net.inet.siftr.ppl=10 +.Pp +To change the log file location to /tmp/siftr.log, run the following +command as root: +sysctl net.inet.siftr.logfile=/tmp/siftr.log +.Sh SEE ALSO +.Xr tcpdump 1 , +.Xr tcp 4 , +.Xr sysctl 8 , +.Xr alq 9 , +.Xr pfil 9 +.Sh ACKNOWLEDGEMENTS +Development of this software was made possible in part by grants from the +Cisco University Research Program Fund at Community Foundation Silicon Valley, +and the FreeBSD Foundation. +.Sh HISTORY +.Nm +first appeared in +.Fx 7.4 +and +.Fx 8.2 . +.Pp +.Nm +was first released in 2007 by Lawrence Stewart and James Healy whilst working on +the NewTCP research project at Swinburne University of Technology's Centre for +Advanced Internet Architectures, Melbourne, Australia, which was made possible +in part by a grant from the Cisco University Research Program Fund at Community +Foundation Silicon Valley. +More details are available at: +.Pp +http://caia.swin.edu.au/urp/newtcp/ +.Pp +Work on +.Nm +v1.2.x was sponsored by the FreeBSD Foundation as part of +the +.Qq Enhancing the FreeBSD TCP Implementation +project 2008-2009. +More details are available at: +.Pp +https://www.freebsdfoundation.org/ +.Pp +http://caia.swin.edu.au/freebsd/etcp09/ +.Sh AUTHORS +.An -nosplit +.Nm +was written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org +and +.An James Healy Aq Mt jimmy@deefa.com . +.Pp +This manual page was written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org . +.Sh BUGS +Current known limitations and any relevant workarounds are outlined below: +.Bl -dash +.It +The internal queue used to pass information between the threads of operation is +currently unbounded. +This allows +.Nm +to cope with bursty network traffic, but sustained high packet-per-second +traffic can cause exhaustion of kernel memory if the processing thread cannot +keep up with the packet rate. +.It +If using +.Nm +on a machine that is also running other modules utilising the +.Xr pfil 9 +framework e.g. +.Xr dummynet 4 , +.Xr ipfw 8 , +.Xr pf 4 Ns , +the order in which you load the modules is important. +You should kldload the other modules first, as this will ensure TCP packets +undergo any necessary manipulations before +.Nm +.Qq sees +and processes them. +.It +There is a known, harmless lock order reversal warning between the +.Xr pfil 9 +mutex and tcbinfo TCP lock reported by +.Xr witness 4 +when +.Nm +is enabled in a kernel compiled with +.Xr witness 4 +support. +.It +There is no way to filter which TCP flows you wish to capture data for. +Post processing is required to separate out data belonging to particular flows +of interest. +.It +The module does not detect deletion of the log file path. +New log messages will simply be lost if the log file being used by +.Nm +is deleted whilst the module is set to use the file. +Switching to a new log file using the +.Em net.inet.siftr.logfile +variable will create the new file and allow log messages to begin being written +to disk again. +The new log file path must differ from the path to the deleted file. +.It +The hash table used within the code is sized to hold 65536 flows. +This is not a +hard limit, because chaining is used to handle collisions within the hash table +structure. +However, we suspect (based on analogies with other hash table performance data) +that the hash table look up performance (and therefore the module's packet +processing performance) will degrade in an exponential manner as the number of +unique flows handled in a module enable/disable cycle approaches and surpasses +65536. +.It +There is no garbage collection performed on the flow hash table. +The only way currently to flush it is to disable +.Nm . +.It +The PPL variable applies to packets that make it into the processing thread, +not total packets received in the hook function. +Packets are skipped before the PPL variable is applied, which means there may be +a slight discrepancy in the triggering of log messages. +For example, if PPL was set to 10, and the 8th packet since the last log message +is skipped, the 11th packet will actually trigger the log message to be +generated. +This is discussed in greater depth in CAIA technical report 070824A. +.It +At the time of writing, there was no simple way to hook into the TCP layer +to intercept packets. +.Nm Ap s +use of IP layer hook points means all IP +traffic will be processed by the +.Nm +.Xr pfil 9 +hook function, which introduces minor, but nonetheless unnecessary packet delay +and processing overhead on the system for non-TCP packets as well. +Hooking in at the IP layer is also not ideal from the data gathering point of +view. +Packets traversing up the stack will be intercepted and cause a log message +generation BEFORE they have been processed by the TCP layer, which means we +cannot observe the cause-and-affect relationship between inbound events and the +corresponding TCP control block as precisely as could be. +Ideally, +.Nm +should intercept packets after they have been processed by the TCP layer i.e. +intercept packets coming up the stack after they have been processed by +.Fn tcp_input , +and intercept packets coming down the stack after they have been +processed by +.Fn tcp_output . +The current code still gives satisfactory granularity though, as inbound events +tend to trigger outbound events, allowing the cause-and-effect to be observed +indirectly by capturing the state on outbound events as well. +.It +The +.Qq inflight bytes +value logged by +.Nm +does not take into account bytes that have been +.No SACK Ap ed +by the receiving host. +.El diff --git a/static/freebsd/man4/siis.4 b/static/freebsd/man4/siis.4 new file mode 100644 index 00000000..3ba7cd1b --- /dev/null +++ b/static/freebsd/man4/siis.4 @@ -0,0 +1,133 @@ +.\" Copyright (c) 2009 Alexander Motin +.\" 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 March 23, 2015 +.Dt SIIS 4 +.Os +.Sh NAME +.Nm siis +.Nd SiliconImage Serial ATA Host Controller driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device pci" +.Cd "device scbus" +.Cd "device siis" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +siis_load="YES" +.Ed +.Pp +The following tunables are settable from the +.Xr loader 8 : +.Bl -ohang +.It Va hint.siis. Ns Ar X Ns Va .msi +controls Message Signaled Interrupts (MSI) usage by the specified controller. +.It Va hint.siisch. Ns Ar X Ns Va .pm_level +controls SATA interface Power Management for the specified channel, +allowing some power to be saved at the cost of additional command +latency. +Possible values: +.Bl -tag -width 2n -offset indent +.It 0 +interface Power Management is disabled (default); +.It 1 +device is allowed to initiate PM state change, host is passive. +.El +.Pp +Note that interface Power Management is not compatible with +device presence detection. +A manual bus reset is needed on device hot-plug. +.It Va hint.siisch. Ns Ar X Ns Va .sata_rev +setting to nonzero value limits maximum SATA revision (speed). +Values 1, 2 and 3 are respectively 1.5, 3 and 6Gbps. +.El +.Sh DESCRIPTION +This driver provides the +.Xr CAM 4 +subsystem with native access to the +.Tn SATA +ports of controller. +Each SATA port is represented to CAM as a separate bus with 16 targets. +Most of the bus-management details are handled by the SATA-specific +transport of CAM. +Connected ATA disks are handled by the ATA protocol disk peripheral driver +.Xr ada 4 . +ATAPI devices are handled by the SCSI protocol peripheral drivers +.Xr cd 4 , +.Xr da 4 , +.Xr sa 4 , +etc. +.Pp +Driver features include support for Serial ATA and ATAPI devices, +Port Multipliers (including FIS-based switching), hardware command queues +(31 command per port), Native Command Queuing, SATA interface Power Management, +device hot-plug and Message Signaled Interrupts. +.Pp +The activity LEDs of the adapters supported by the +.Nm +driver can be controlled via the +.Xr led 4 +API for localization or status reporting purposes. +.Sh HARDWARE +The +.Nm +driver supports the following controller chips: +.Pp +.Bl -bullet -compact +.It +SiI3124 (PCI-X 133MHz/64bit, 4 ports) +.It +SiI3131 (PCIe 1.0 x1, 1 port) +.It +SiI3132 (PCIe 1.0 x1, 2 ports) +.It +SiI3531 (PCIe 1.0 x1, 1 port) +.El +.Sh FILES +.Bl -tag -width /dev/led/siisch* +.It Pa /dev/led/siisch* +identification LED device nodes +.El +.Sh SEE ALSO +.Xr ada 4 , +.Xr ata 4 , +.Xr cam 4 , +.Xr cd 4 , +.Xr da 4 , +.Xr led 4 , +.Xr sa 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 8.0 . +.Sh AUTHORS +.An Alexander Motin Aq Mt mav@FreeBSD.org diff --git a/static/freebsd/man4/simplebus.4 b/static/freebsd/man4/simplebus.4 new file mode 100644 index 00000000..78cb8d77 --- /dev/null +++ b/static/freebsd/man4/simplebus.4 @@ -0,0 +1,81 @@ +.\" +.\" Copyright (c) 2010 The FreeBSD Foundation +.\" +.\" This software was developed by Semihalf under sponsorship from +.\" the FreeBSD Foundation. +.\" +.\" 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 12, 2010 +.Dt SIMPLEBUS 4 +.Os +.Sh NAME +.Nm simplebus +.Nd ePAPR simple-bus driver +.Sh SYNOPSIS +.Cd "options FDT" +.Sh DESCRIPTION +This bus driver is dedicated for the +.Pa simple-bus +node of a flattened device tree compliant with the +.Pa ePAPR +specification. +.Pp +The +.Nm +entity does not represent any physical element by itself, it is rather an +umbrella node grouping integrated on-chip peripherals like interrupt +controller, connectivity controllers, accelerating engines and so on. +.Pp +The driver is generic and common for all flattened device tree nodes claiming +.Pa simple-bus +compatibility. +It iterates over direct descendants of the +.Pa simple-bus +node, instantiates newbus children and assigns resources to them, based on the +configuration data retrieved from the nodes properties in +.Xr fdt 4 . +.Pp +Note the +.Nm +does not manage device resources and passes through any requests to the +.Xr fdtbus 4 +layer. +.Sh SEE ALSO +.Xr fdt 4 , +.Xr fdtbus 4 , +.Xr openfirm 4 +.Sh STANDARDS +Power.org Standard for Embedded Power Architecture Platform Requirements +.Pq Vt ePAPR . +.Sh HISTORY +The +.Nm +support first appeared in +.Fx 9.0 . +.Sh AUTHORS +The +.Nm +support was developed by Semihalf under sponsorship from the FreeBSD +Foundation. +This manual page was written by +.An Rafal Jaworowski . diff --git a/static/freebsd/man4/sis.4 b/static/freebsd/man4/sis.4 new file mode 100644 index 00000000..87c8e059 --- /dev/null +++ b/static/freebsd/man4/sis.4 @@ -0,0 +1,223 @@ +.\" Copyright (c) 1997, 1998, 1999 +.\" Bill Paul . 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 Bill Paul. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Bill Paul 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 Bill Paul OR THE VOICES IN HIS HEAD +.\" 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 September 2, 2010 +.Dt SIS 4 +.Os +.Sh NAME +.Nm sis +.Nd "SiS 900, SiS 7016 and NS DP83815/DP83816 Fast Ethernet device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device sis" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_sis_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for PCI Ethernet adapters and embedded +controllers based on the Silicon Integrated Systems SiS 900 +and SiS 7016 Fast Ethernet controller chips. +.Pp +This driver also supports +adapters based on the National Semiconductor DP83815 (MacPhyter) and DP83816 +PCI Ethernet controller chip. +.Pp +The SiS 900 is a 100Mbps Ethernet MAC and MII-compliant transceiver +in a single package. +It uses a bus master DMA and a scatter/gather +descriptor scheme. +The SiS 7016 is similar to the SiS 900 except +that it has no internal PHY, requiring instead an external transceiver +to be attached to its MII interface. +The SiS 900 and SiS 7016 both have a 128-bit multicast hash filter +and a single perfect filter entry for the station address. +.Pp +The NS DP83815 is also a 100Mbps Ethernet MAC with integrated PHY. +The NatSemi chip and the SiS 900 share many of the same features and +a fairly similar programming interface, hence both chips are supported +by the same driver. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width 10baseTXUTP +.It autoselect +Enable autoselection of the media type and options. +The user can manually override +the autoselected mode by adding media options to +.Xr rc.conf 5 . +.It 10baseT/UTP +Set 10Mbps operation. +The +.Xr ifconfig 8 +.Cm mediaopt +option can also be used to select either +.Sq full-duplex +or +.Sq half-duplex +modes. +.It 100baseTX +Set 100Mbps (Fast Ethernet) operation. +The +.Xr ifconfig 8 +.Cm mediaopt +option can also be used to select either +.Sq full-duplex +or +.Sq half-duplex +modes. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width full-duplex +.It full-duplex +Force full duplex operation. +.It half-duplex +Force half duplex operation. +.El +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports Silicon Integrated Systems SiS 900 and SiS 7016 based +Fast Ethernet adapters and embedded controllers, as well as Fast Ethernet +adapters based on the National Semiconductor DP83815 (MacPhyter) and DP83816 +chips. +Supported adapters include: +.Pp +.Bl -bullet -compact +.It +@Nifty FNECHARD IFC USUP-TX +.It +MELCO LGY-PCI-TXC +.It +Netgear FA311-TX (DP83815) +.It +Netgear FA312-TX (DP83815) +.It +SiS 630, 635, and 735 motherboard chipsets +.It +Soekris Engineering net45xx, net48xx, lan1621, and lan1641 +.El +.Sh SYSCTL VARIABLES +The following variable is available as both +.Xr sysctl 8 +variable and +.Xr loader 8 +tunable: +.Bl -tag -width indent +.It Va dev.sis.%unit.manual_pad +This variable controls how to pad short frames for DP83815/DP83816 +controllers on the specified device. +DP83815/DP83816 controllers are known to pad 0xFF for short frames +which is violation of RFC 1042. +Set this variable to a non-zero value to let driver manually pad +each short frame with zeros at the cost of extra CPU cycles. +The default value is 0 to let hardware perform automatic padding. +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "sis%d: couldn't map ports/memory" +A fatal initialization error has occurred. +.It "sis%d: couldn't map interrupt" +A fatal initialization error has occurred. +.It "sis%d: watchdog timeout" +The device has stopped responding to the network, or there is a problem with +the network connection (e.g.\& a cable fault). +.It "sis%d: no memory for rx list" +The driver failed to allocate an mbuf for the receiver ring. +.It "sis%d: no memory for tx list" +The driver failed to allocate an mbuf for the transmitter ring when +allocating a pad buffer or collapsing an mbuf chain into a cluster. +.It "sis%d: chip is in D3 power state -- setting to D0" +This message applies only to adapters which support power +management. +Some operating systems place the controller in low power +mode when shutting down, and some PCI BIOSes fail to bring the chip +out of this state before configuring it. +The controller loses all of +its PCI configuration in the D3 state, so if the BIOS does not set +it back to full power mode in time, it will not be able to configure it +correctly. +The driver tries to detect this condition and bring +the adapter back to the D0 (full power) state, but this may not be +enough to return the driver to a fully operational condition. +If +you see this message at boot time and the driver fails to attach +the device as a network interface, you will have to perform a +warm boot to have the device properly configured. +.Pp +Note that this condition only occurs when warm booting from another +operating system. +If you power down your system prior to booting +.Fx , +the card should be configured correctly. +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr polling 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Rs +.%T SiS 900 and SiS 7016 datasheets +.%U https://www.sis.com.tw +.Re +.Rs +.%T NatSemi DP83815 datasheet +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 3.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Bill Paul Aq Mt wpaul@ee.columbia.edu . diff --git a/static/freebsd/man4/sk.4 b/static/freebsd/man4/sk.4 new file mode 100644 index 00000000..17ca8beb --- /dev/null +++ b/static/freebsd/man4/sk.4 @@ -0,0 +1,239 @@ +.\" Copyright (c) 1997, 1998, 1999 +.\" Bill Paul . 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 Bill Paul. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Bill Paul 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 Bill Paul OR THE VOICES IN HIS HEAD +.\" 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 August 29, 2012 +.Dt SK 4 +.Os +.Sh NAME +.Nm sk +.Nd "SysKonnect SK-984x and SK-982x PCI Gigabit Ethernet adapter driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device sk" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_sk_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the SysKonnect SK-984x and SK-982x series PCI +Gigabit Ethernet adapters. +.Pp +The SysKonnect adapters consist of two main components: the XaQti Corp. +XMAC II gigabit MAC and the SysKonnect GEnesis controller ASIC. +The +XMAC provides the gigabit MAC and PHY support while the GEnesis +provides an interface to the PCI bus, DMA support, packet buffering +and arbitration. +The GEnesis can control up to two XMACs simultaneously, +allowing dual-port NIC configurations. +.Pp +The SK-982x 1000baseT adapters also include a Broadcom BCM5400 1000baseTX +PHY which is used in place of the XMAC's internal PHY. +The Broadcom PHY is connected to the XMAC via its GMII port. +.Pp +The +.Nm +driver configures dual port SysKonnect adapters such that each XMAC +is treated as a separate logical network interface. +Both ports can +operate independently of each other and can be connected to separate +networks. +The SysKonnect driver software currently only uses the +second port on dual port adapters for failover purposes: if the link +on the primary port fails, the SysKonnect driver will automatically +switch traffic onto the second port. +.Pp +Also supported is the Marvell Semiconductor 88E100* gigabit PHY. +.Pp +The XaQti XMAC II supports full and half duplex operation with +autonegotiation. +The XMAC also supports unlimited frame sizes. +Support for jumbo frames is provided via the interface MTU setting. +Selecting an MTU larger than 1500 bytes with the +.Xr ifconfig 8 +utility configures the adapter to receive and transmit jumbo frames. +Using jumbo frames can greatly improve performance for certain tasks, +such as file transfers and data streaming. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width xxxxxxxxxxxxxxxxxxxx +.It autoselect +Enable autoselection of the media type and options. +The user can manually override +the autoselected mode by adding media options to the +.Pa /etc/rc.conf +file. +.It 1000baseTX +Set 1000baseTX operation over twisted pair. +This is only available +for SK-982x series adapters with 1000baseT ports. +Both +.Ar full-duplex +and +.Ar half-duplex +modes are supported. +.It 1000baseSX +Set 1000Mbps (Gigabit Ethernet) operation. +Both +.Ar full-duplex +and +.Ar half-duplex +modes are supported. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width xxxxxxxxxxxxxxxxxxxx +.It full-duplex +Force full duplex operation. +.It half-duplex +Force half duplex operation. +.El +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +Adapters supported by the +.Nm +driver include: +.Pp +.Bl -bullet -compact +.It +3Com 3C940 single port, 1000baseT adapter +.It +3Com 3C2000-T single port, 1000baseT adapter +.It +Belkin F5D5005 single port, 1000baseT adapter +.It +D-Link DGE-530T single port, 1000baseT adapter +.It +Linksys (revision 2) single port, 1000baseT adapter +.It +SK-9521 SK-NET GE-T single port, 1000baseT adapter +.It +SK-9821 SK-NET GE-T single port, 1000baseT adapter +.It +SK-9822 SK-NET GE-T dual port, 1000baseT adapter +.It +SK-9841 SK-NET GE-LX single port, single mode fiber adapter +.It +SK-9842 SK-NET GE-LX dual port, single mode fiber adapter +.It +SK-9843 SK-NET GE-SX single port, multimode fiber adapter +.It +SK-9844 SK-NET GE-SX dual port, multimode fiber adapter +.It +SMC 9452TX single port, 1000baseT adapter +.El +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width xxxxxx +.It Va hw.skc.jumbo_disable +Disable jumbo frame support. +Systems with less memory can set it to a non-zero value to save memory. +The default value is 0. +.El +.Sh SYSCTL VARIABLES +The following variable is available as both +.Xr sysctl 8 +variable and +.Xr loader 8 +tunable: +.Bl -tag -width xxxxxx +.It Va dev.skc.%d.int_mod +This variable controls interrupt moderation. +The accepted range is 10 to 10000. +The default value is 100 microseconds. +The interface has to be brought down and up again before a change takes effect. +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "sk%d: couldn't map memory" +A fatal initialization error has occurred. +.It "sk%d: couldn't map ports" +A fatal initialization error has occurred. +.It "sk%d: couldn't map interrupt" +A fatal initialization error has occurred. +.It "sk%d: no memory for softc struct!" +The driver failed to allocate memory for per-device instance information +during initialization. +.It "sk%d: failed to enable memory mapping!" +The driver failed to initialize PCI shared memory mapping. +This might +happen if the card is not in a bus-master slot. +.It "sk%d: no memory for jumbo buffers!" +The driver failed to allocate memory for jumbo frames during +initialization. +.It "sk%d: watchdog timeout" +The device has stopped responding to the network, or there is a problem with +the network connection (cable). +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Rs +.%T XaQti XMAC II datasheet +.%U https://people.freebsd.org/~wpaul/SysKonnect/xmacii_datasheet_rev_c_9-29.pdf +.Re +.Rs +.%T SysKonnect GEnesis programming manual +.%U http://www.syskonnect.com +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 3.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Bill Paul Aq Mt wpaul@ctr.columbia.edu . diff --git a/static/freebsd/man4/smartpqi.4 b/static/freebsd/man4/smartpqi.4 new file mode 100644 index 00000000..ef5f903f --- /dev/null +++ b/static/freebsd/man4/smartpqi.4 @@ -0,0 +1,175 @@ +.\" Copyright (C) 2019-2025, Microchip Technology Inc. and its subsidiaries +.\" Copyright (C) 2016-2018, Microsemi Corporation +.\" Copyright (C) 2016, PMC-Sierra, Inc. +.\" Written by John Hall +.\" +.\" 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 August 28, 2025 +.Dt SMARTPQI 4 amd64 +.Os +.Sh NAME +.Nm smartpqi +.Nd "Microchip Smart Storage SCSI driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place these lines in the kernel +configuration file: +.Bd -ragged -offset indent +.Cd device pci +.Cd device scbus +.Cd device smartpqi +.Ed +.Pp +The driver can be loaded as a module at boot time by placing this line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +smartpqi_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for Microchip Technology Inc. / Adaptec SmartRaid and +SmartHBA SATA/SAS/NVMe PCIe controllers +.Sh HARDWARE +Controllers supported by the +.Nm +driver include, but not limited to: +.Pp +.Bl -bullet -compact +.It +HPE Gen10 Smart Array Controller Family +.It +Adaptec SmartRaid and SmartHBA Controllers +.It +OEM Controllers based on the Microchip Technology Inc. SmartROC +and SmartIOC Chipsets +.El +.Sh DEBUGGING +Driver diagnostic printing is controlled in +.Xr loader.conf 5 +by using the global +.Va hw.smartpqi.debug_level +tunable. +.Pp +The +.Va debug_level +variable is set with an integer value. +The default value is 0x0060 (warn && error). +.Pp +The following levels are available: +.Bl -column "FlagXX" "NameXXXX" "Description" -offset indent +.It Em Flag Ta Em Name Ta Em Description +.It 0x0001 Ta init Ta System initialization operations +.It 0x0002 Ta info Ta Basic information +.It 0x0004 Ta function Ta Used to show function entry and exit +.It 0x0008 Ta io Ta Logging data from controller +.It 0x0010 Ta discovery Ta Device discovery +.It 0x0020 Ta warning Ta Operational warnings +.It 0x0040 Ta error Ta Parameter errors and programming bugs +.It 0x0080 Ta note Ta More detailed information +.El +.Sh DEVICE HINTS +The following tunable values can be set in +.Pa /boot/device.hints +to control the behavior of the +.Nm +driver. +These hints are specified as: +.Bd -literal -offset indent +hint.smartpqi..= +.Ed +.Pp +The supported variables are: +.Bl -tag -width ".Va aio_raid1_write_disable" +.It Va stream_disable +If set to 0, disables Stream Detection. +.Pp +Default is (enabled). +.It Va sata_unique_wwn_disable +If set to 0, disables SATA Unique World Wide Number. +.Pp +Default is (enabled). +.It Va aio_raid1_write_disable +If set to 0, disables acceleration of RAID1 writes +.Pp +Default is (enabled). +.It Va aio_raid5_write_disable +If set to 0, disables acceleration of RAID5 writes +.Pp +Default is (enabled). +.It Va aio_raid6_write_disable +If set to 0, disables acceleration of RAID6 writes +.Pp +Default is (enabled). +.It Va queue_depth +Sets queue depth for the controller. If the queue depth value +is greater than the maximum supported queue size of the driver or +controller, it will be set to the lowest size. If the queue +depth value is lower than the minimum queue depth then this will +be set to the minimum queue depth. +.Pp +Default is driver-determined. +.It Va sg_count +Sets the scatter gather (sg) count. If this sg count is greater +than maximum sg count it will be set to the maximum sg count. +If this sg count is less than minimum sg count it will be set to +the minimum sg count. +.Pp +Default is driver-determined. +.El +.Pp +For example, to disable Stream Detection on the first controller, add +the following line to +.Pa /boot/device.hints : +.Bd -literal -offset indent +hint.smartpqi.0.stream_disable="0" +.Ed +.Sh FILES +.Bl -tag -width /boot/kernel/smartpqi.ko -compact +.It Pa /dev/smartpqi? +smartpqi management interface +.El +.Sh NOTES +.Ss Configuration +To configure a Microchip Smart Storage controller, +refer to the User Guide for the controller, +which can be found by searching for the specific controller at +https://www.microchip.com/design-centers/storage +.Sh SEE ALSO +.Xr kld 4 , +.Xr linux 4 , +.Xr pass 4 , +.Xr scsi 4 , +.Xr xpt 4 , +.Xr loader.conf 5 , +.Xr camcontrol 8 , +.Xr kldload 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 11.1 . +.Sh AUTHORS +.An John Hall +.Aq john.hall@microchip.com +.Sh BUGS +The controller is not actually paused on suspend/resume. diff --git a/static/freebsd/man4/smb.4 b/static/freebsd/man4/smb.4 new file mode 100644 index 00000000..44dff0f7 --- /dev/null +++ b/static/freebsd/man4/smb.4 @@ -0,0 +1,201 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 1998, Nicolas Souchu +.\" Copyright (c) 2004, Joerg Wunsch +.\" Copyright (c) 2015, Michael Gmelin +.\" 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 April 25, 2015 +.Dt SMB 4 +.Os +.Sh NAME +.Nm smb +.Nd System Management Bus (SMBus) generic I/O device driver +.Sh SYNOPSIS +.Cd "device smb" +.Sh DESCRIPTION +The +.Em smb +character device driver provides generic I/O to any +.Xr smbus 4 +instance. +To control SMB devices, use +.Pa /dev/smb? +with the ioctls described below. +Any of these ioctl commands takes a pointer to +.Vt struct smbcmd +as its argument. +.Bd -literal +#include + +struct smbcmd { + u_char cmd; + u_char reserved; + u_short op; + union { + char byte; + char buf[2]; + short word; + } wdata; + union { + char byte; + char buf[2]; + short word; + } rdata; + int slave; + char *wbuf; /* use wdata if NULL */ + int wcount; + char *rbuf; /* use rdata if NULL */ + int rcount; +}; +.Ed +.Pp +The +.Fa slave +field is always used, and provides the address of the +SMBus slave device. +The slave address is specified in the seven most significant bits +.Pq i.e., Dq "left-justified" . +The least significant bit of the slave address must be zero. +.Pp +.Bl -column ".Dv SMB_QUICK_WRITE" -compact +.It Em Ioctl Ta Em Description +.Pp +.It Dv SMB_QUICK_WRITE Ta +.Em QuickWrite +does not transfer any data. +It just issues the device address with write intent to the bus. +.It Dv SMB_QUICK_READ Ta +.Em QuickRead +does not transfer any data. +It just issues the device address with read intent to the bus. +.It Dv SMB_SENDB Ta +.Em SendByte +sends the byte provided in +.Fa cmd +to the device. +.It Dv SMB_RECVB Ta +.Em ReceiveByte +reads a single byte from the device which is returned in +.Fa cmd . +.It Dv SMB_WRITEB Ta +.Em WriteByte +first sends the byte from +.Fa cmd +to the device, followed by the byte given in +.Fa wdata.byte . +.It Dv SMB_WRITEW Ta +.Em WriteWord +first sends the byte from +.Fa cmd +to the device, followed by the word given in +.Fa wdata.word . +Note that the SMBus byte-order is little-endian by definition. +.It Dv SMB_READB Ta +.Em ReadByte +first sends the byte from +.Fa cmd +to the device, then reads one byte of data from +the device. +Returned data is stored in +.Fa rdata.byte . +.It Dv SMB_READW Ta +.Em ReadWord +first sends the byte from +.Fa cmd +to the device, then reads one word of data from +the device. +Returned data is stored in +.Fa rdata.word . +.It Dv SMB_PCALL Ta +.Em ProcedureCall +first sends the byte from +.Fa cmd +to the device, followed by the word provided in +.Fa wdata.word . +It then reads one word of data from the device and returns it +in +.Fa rdata.word . +.It Dv SMB_BWRITE Ta +.Em BlockWrite +first sends the byte from +.Fa cmd +to the device, then the byte from +.Fa wcount +followed by +.Fa wcount +bytes of data that are taken from the buffer pointed to by +.Fa wbuf . +The SMBus specification mandates that no more than 32 bytes of +data can be transferred in a single block read or write command. +This value can be read from the constant +.Dv SMB_MAXBLOCKSIZE . +.It Dv SMB_BREAD Ta +.Em BlockRead +first sends the byte from +.Fa cmd +to the device, then reads a count of data bytes that the device +is going to provide and then reads that many bytes. +The count is returned in +.Fa rcount . +The data is returned in the buffer pointed to by +.Fa rbuf . +.El +.Pp +The +.Xr read 2 +and +.Xr write 2 +system calls are not implemented by this driver. +.Sh ERRORS +The +.Xr ioctl 2 +commands can cause the following driver-specific errors: +.Bl -tag -width Er +.It Bq Er ENXIO +Device did not respond to selection. +.It Bq Er EBUSY +Device still in use. +.It Bq Er ENODEV +Operation not supported by device (not supposed to happen). +.It Bq Er EINVAL +General argument error. +.It Bq Er EWOULDBLOCK +SMBus transaction timed out. +.El +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr smbus 4 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 3.0 . +.Sh AUTHORS +This +manual page was written by +.An Nicolas Souchu +and extended by +.An Michael Gmelin Aq freebsd@grem.de . diff --git a/static/freebsd/man4/smbfs.4 b/static/freebsd/man4/smbfs.4 new file mode 100644 index 00000000..df64bdc3 --- /dev/null +++ b/static/freebsd/man4/smbfs.4 @@ -0,0 +1,99 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2020 Gordon Bergling +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 6, 2022 +.Dt SMBFS 4 +.Os +.Sh NAME +.Nm smbfs +.Nd server message block (SMB1/CIFS) file system +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "option NETSMB" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +smbfs_load="YES" +.Ed +.Sh DESCRIPTION +The SMB driver is an implementation of the CIFS (Common Internet Filesystem) +network protocol. +.Pp +.Bf -symbolic +The +.Nm +filesystem driver supports only the obsolete SMBv1 protocol. +.Nm +has known bugs and likely has security vulnerabilities. +.Nm +and userspace counterparts +.Xr smbutil 1 +and +.Xr mount_smbfs 8 +may be removed from a future version of +.Fx . +Users are advised to evaluate the +.Pa filesystems/smbnetfs +port instead. +.Ef +.Sh SEE ALSO +.Xr smbutil 1 , +.Xr mount_smbfs 8 +.Sh STANDARDS +.Rs +.%U https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-cifs/ +.%T Common Internet File System (CIFS) Protocol +.%R MS-CIFS +.%D December 2018 +.Re +.Pp +.Rs +.%U https://tools.ietf.org/html/draft-heizer-cifs-v1-spec-00 +.%T Common Internet File System Protocol (CIFS/1.0) +.%D June 13, 1996 +.%A I. Heizer +.%A P. Leach +.%A D. Perry +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 4.4 . +.Sh AUTHORS +.An -nosplit +The +.Nm +device driver was written by +.An Boris Popov Aq Mt bp@FreeBSD.org . +The manual page was contributed by +.An Gordon Bergling Aq Mt gbe@FreeBSD.org . diff --git a/static/freebsd/man4/smbios.4 b/static/freebsd/man4/smbios.4 new file mode 100644 index 00000000..0b710190 --- /dev/null +++ b/static/freebsd/man4/smbios.4 @@ -0,0 +1,63 @@ +.\" Copyright (c) 2020 Gordon Bergling +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 22, 2020 +.Dt SMBIOS 4 +.Os +.Sh NAME +.Nm smbios +.Nd "System Management BIOS" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device smbios" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +smbios_load="YES" +.Ed +.Sh DESCRIPTION +The System Management BIOS (SMBIOS) describes hardware components. +.Sh SEE ALSO +.Xr efi 8 +.Rs +.%T System Management BIOS (SMBIOS) Reference Specification +.%N DMTF DSP0134 +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 4.8 . +.Sh AUTHORS +The +.Nm +device driver was written by +.An Matthew N. Dodd Aq Mt winter@jurai.net . +This manual page was written by +.An Gordon Bergling Aq Mt gbe@FreeBSD.org . diff --git a/static/freebsd/man4/smbus.4 b/static/freebsd/man4/smbus.4 new file mode 100644 index 00000000..c02cb4b3 --- /dev/null +++ b/static/freebsd/man4/smbus.4 @@ -0,0 +1,77 @@ +.\" Copyright (c) 1998, Nicolas Souchu +.\" 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 March 7, 2021 +.Dt SMBUS 4 +.Os +.Sh NAME +.Nm smbus +.Nd System Management Bus +.Sh SYNOPSIS +.Cd "device smbus" +.Pp +.Cd "device iicsmb" +.Sh DESCRIPTION +The +.Em smbus +system provides a uniform, modular and architecture-independent +system for the implementation of drivers to control various SMB devices +and to utilize different SMB controllers (I2C, PIIX4, vm86...). +.Sh System Management Bus +The +.Em System Management Bus +is a two-wire interface through which simple power-related chips can communicate +with rest of the system. +It uses I2C as its backbone (see +.Xr iicbus 4 ) . +.Pp +A system using SMB passes messages to and from devices instead of tripping +individual control lines. +.Pp +With the SMBus, a device can provide manufacturer information, tell the +system what its model/part number is, save its state for a suspend event, +report different types of errors, accept control parameters, and return its +status. +.Pp +The SMBus may share the same host device and physical bus as ACCESS bus +components provided that an appropriate electrical bridge is provided +between the internal SMB devices and external ACCESS bus devices. +.Sh SEE ALSO +.Xr iicbus 4 , +.Xr iicsmb 4 , +.Xr smb 4 , +.Xr smbmsg 8 +.Rs +.%T The SMBus specification +.%U http://www.smbus.org/specs/ +.Re +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 3.0 . +.Sh AUTHORS +This +manual page was written by +.An Nicolas Souchu . diff --git a/static/freebsd/man4/smp.4 b/static/freebsd/man4/smp.4 new file mode 100644 index 00000000..a02d69b0 --- /dev/null +++ b/static/freebsd/man4/smp.4 @@ -0,0 +1,188 @@ +.\" Copyright (c) 1997 +.\" Steve Passe . 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. The name of the developer 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 AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 4, 2019 +.Dt SMP 4 +.Os +.Sh NAME +.Nm SMP +.Nd description of the FreeBSD Symmetric Multi-Processor kernel +.Sh SYNOPSIS +.Cd options SMP +.Sh DESCRIPTION +The +.Nm +kernel implements symmetric multi-processor support. +.Pp +.Nm +support can be disabled by setting the loader tunable +.Va kern.smp.disabled +to 1. +.Pp +The number of CPUs detected by the system is available in +the read-only sysctl variable +.Va hw.ncpu . +.Pp +The number of online threads per CPU core is available in the read-only sysctl +variable +.Va kern.smp.threads_per_core . +The number of physical CPU cores detected by the system is available in the +read-only sysctl variable +.Va kern.smp.cores . +.Pp +.Fx +allows specific CPUs on a multi-processor system to be disabled. +This can be done using the +.Va hint.lapic.X.disabled +tunable, where X is the APIC ID of a CPU. +Setting this tunable to 1 will result in the corresponding CPU being +disabled. +.Pp +.Fx +supports simultaneous multithreading on x86 and powerpc platforms. +On x86, the logical CPUs can be disabled by setting the +.Va machdep.hyperthreading_allowed +tunable to zero. +.Pp +The +.Xr sched_ule 4 +scheduler implements CPU topology detection and adjusts the scheduling +algorithms to make better use of modern multi-core CPUs. +The sysctl variable +.Va kern.sched.topology_spec +reflects the detected CPU hardware in a parsable XML format. +The top level XML tag is , which encloses one or more tags +containing data about individual CPU groups. +A CPU group contains CPUs that are detected to be "close" together, usually +by being cores in a single multi-core processor. +Attributes available in a tag are "level", corresponding to the +nesting level of the CPU group and "cache-level", corresponding to the +level of CPU caches shared by the CPUs in the group. +The tag contains the and tags. +The tag describes CPUs in the group. +Its attributes are "count", corresponding to the number of CPUs in the +group and "mask", corresponding to the integer binary mask in which +each bit position set to 1 signifies a CPU belonging to the group. +The contents (CDATA) of the tag is the comma-delimited list +of CPU indexes (derived from the "mask" attribute). +The tag contains special tags (if any) describing the relation +of the CPUs in the group. +The possible flags are currently "HTT" and "SMT", corresponding to +the various implementations of hardware multithreading. +An example topology_spec output for a system consisting of +two quad-core processors is: +.Bd -literal + + + 0, 1, 2, 3, 4, 5, 6, 7 + + + + 0, 1, 2, 3 + + + + 4, 5, 6, 7 + + + + + +.Ed +.Pp +This information is used internally by the kernel to schedule related +tasks on CPUs that are closely grouped together. +.Sh COMPATIBILITY +Support for multi-processor systems is present for all Tier-1 and Tier-2 +architectures on +.Fx . +Currently, this includes x86, powerpc, mips, arm and arm64. +Support is enabled using +.Cd options SMP . +It is permissible to use the SMP kernel configuration on non-SMP hardware. +.Sh I386 NOTES +For i386 systems, the +.Nm +kernel supports motherboards that follow the Intel MP specification, +version 1.4. +In addition to +.Cd options SMP , +i386 also requires +.Cd device apic . +The +.Xr mptable 1 +command may be used to view the status of multi-processor support. +.Sh SEE ALSO +.Xr cpuset 1 , +.Xr mptable 1 , +.Xr sched_4bsd 4 , +.Xr sched_ule 4 , +.Xr loader 8 , +.Xr sysctl 8 , +.Xr condvar 9 , +.Xr msleep 9 , +.Xr mtx_pool 9 , +.Xr mutex 9 , +.Xr rwlock 9 , +.Xr sema 9 , +.Xr sx 9 +.Sh HISTORY +The +.Nm +kernel's early history is not (properly) recorded. +It was developed +in a separate CVS branch until April 26, 1997, at which point it was +merged into 3.0-current. +By this date 3.0-current had already been +merged with Lite2 kernel code. +.Pp +.Fx 5.0 +introduced support for a host of new synchronization primitives, and +a move towards fine-grained kernel locking rather than reliance on +a Giant kernel lock. +The SMPng Project relied heavily on the support of BSDi, who provided +reference source code from the fine-grained SMP implementation found +in +.Bsx . +.Pp +.Fx 5.0 +also introduced support for SMP on the sparc64 architecture. +.Sh AUTHORS +.An Steve Passe Aq Mt fsmp@FreeBSD.org +.Sh CAVEATS +The +.Va kern.smp.threads_per_core +and +.Va kern.smp.cores +sysctl variables are provided as a best-effort guess. +If an architecture or platform adds SMT and +.Fx +has not yet implemented detection, the reported values may be inaccurate. +In this case, +.Va kern.smp.threads_per_core +will report +.Dv 1 +and +.Va kern.smp.cores +will report the same value as +.Va hw.ncpu . diff --git a/static/freebsd/man4/smsc.4 b/static/freebsd/man4/smsc.4 new file mode 100644 index 00000000..61b12c7d --- /dev/null +++ b/static/freebsd/man4/smsc.4 @@ -0,0 +1,90 @@ +.\" Copyright (c) 2014 Gavin Atkinson +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" - Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" - 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 COPYRIGHT HOLDERS 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 +.\" COPYRIGHT HOLDERS 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 May 7, 2024 +.Dt SMSC 4 +.Os +.Sh NAME +.Nm smsc +.Nd "USB Microchip LAN9xxx Fast Ethernet driver" +.Sh SYNOPSIS +To load the driver as a module at boot time, place the +following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_smsc_load="YES" +.Ed +.Pp +Alternatively, to compile this driver into the kernel, place the +following lines in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device uhci" +.Cd "device ohci" +.Cd "device usb" +.Cd "device miibus" +.Cd "device uether" +.Cd "device smsc" +.Ed +.Sh DESCRIPTION +The +.Nm +device driver provides support for USB Fast Ethernet adapters based +on the Microchip (formerly SMSC) LAN9xxx chipsets. +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The following devices are supported by the +.Nm +driver: +.Pp +.Bl -bullet -compact +.It +LAN9500, LAN9500A, LAN9505 and LAN9505A based Ethernet adapters +.It +LAN89530, LAN9530 and LAN9730 based Ethernet adapters +.It +LAN951x Ethernet adapters with integrated USB hub +.El +.Sh SEE ALSO +.Xr arp 4 , +.Xr intro 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr usb 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 10.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Ben Gray Aq Mt bgray@FreeBSD.org . diff --git a/static/freebsd/man4/snd_als4000.4 b/static/freebsd/man4/snd_als4000.4 new file mode 100644 index 00000000..7df6868c --- /dev/null +++ b/static/freebsd/man4/snd_als4000.4 @@ -0,0 +1,68 @@ +.\" Copyright (c) 2004 Atte Peltomaki +.\" 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 December 15, 2005 +.Dt SND_ALS4000 4 +.Os +.Sh NAME +.Nm snd_als4000 +.Nd "Avance Logic ALS4000 PCI bridge device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device sound" +.Cd "device snd_als4000" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the +following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +snd_als4000_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +bridge driver allows the generic audio driver +.Xr sound 4 +to attach to the ALS4000 sound card. +.Sh HARDWARE +The +.Nm +driver supports the following sound cards: +.Pp +.Bl -bullet -compact +.It +Avance Logic ALS4000 +.El +.Sh SEE ALSO +.Xr sound 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 4.4 . +.Sh AUTHORS +.An Orion Hodson Aq Mt oho@acm.org diff --git a/static/freebsd/man4/snd_atiixp.4 b/static/freebsd/man4/snd_atiixp.4 new file mode 100644 index 00000000..1b83a969 --- /dev/null +++ b/static/freebsd/man4/snd_atiixp.4 @@ -0,0 +1,98 @@ +.\" Copyright (c) 2005 Joel Dahl +.\" 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 November 29, 2006 +.Dt SND_ATIIXP 4 +.Os +.Sh NAME +.Nm snd_atiixp +.Nd "ATI IXP bridge device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device sound" +.Cd "device snd_atiixp" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the +following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +snd_atiixp_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +bridge driver allows the generic audio driver, +.Xr sound 4 , +to attach to ATI IXP audio devices. +This driver supports 16bit playback and recording, and 32bit native playback +and recording. +.Ss Runtime Configuration +The following +.Xr sysctl 8 +variables are available in addition to those available to all +.Xr sound 4 +devices: +.Bl -tag -width ".Va dev.pcm.%d.polling" -offset indent +.It Va dev.pcm.%d.polling +Experimental polling mode, where the driver operates by querying the device +state on each tick using +.Xr callout 9 . +Polling is disabled by default. +Do not enable it unless you are facing weird interrupt problems or if the +device cannot generate interrupts at all. +.El +.Sh HARDWARE +The +.Nm +driver supports the following audio chipsets: +.Pp +.Bl -bullet -compact +.It +ATI IXP 200 +.It +ATI IXP 300 +.It +ATI IXP 400 +.El +.Sh SEE ALSO +.Xr sound 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 6.1 . +.Sh AUTHORS +This manual page was written by +.An Joel Dahl Aq Mt joel@FreeBSD.org . +.Sh BUGS +The +.Nm +driver +does not support S/PDIF, but implementing it should be fairly easy if the +right hardware is available. +.Pp +32bit native recording is broken on some hardware. diff --git a/static/freebsd/man4/snd_cmi.4 b/static/freebsd/man4/snd_cmi.4 new file mode 100644 index 00000000..5f233ec9 --- /dev/null +++ b/static/freebsd/man4/snd_cmi.4 @@ -0,0 +1,74 @@ +.\" Copyright (c) 2004 Atte Peltomaki +.\" 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 December 15, 2005 +.Dt SND_CMI 4 +.Os +.Sh NAME +.Nm snd_cmi +.Nd "CMedia CMI8338/CMI8738 PCI bridge device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device sound" +.Cd "device snd_cmi" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the +following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +snd_cmi_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +bridge driver allows the generic audio driver +.Xr sound 4 +to attach to the CMedia CMI8338/CMI8738 audio cards. +.Sh HARDWARE +The +.Nm +driver supports the following sound cards: +.Pp +.Bl -bullet -compact +.It +CMedia CMI8338A +.It +CMedia CMI8338B +.It +CMedia CMI8738 +.It +CMedia CMI8738B +.El +.Sh SEE ALSO +.Xr sound 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 4.3 . +.Sh AUTHORS +.An Orion Hodson Aq Mt O.Hodson@cs.ucl.ac.uk diff --git a/static/freebsd/man4/snd_cs4281.4 b/static/freebsd/man4/snd_cs4281.4 new file mode 100644 index 00000000..a05ac399 --- /dev/null +++ b/static/freebsd/man4/snd_cs4281.4 @@ -0,0 +1,68 @@ +.\" Copyright (c) 2004 Atte Peltomaki +.\" 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 December 15, 2005 +.Dt SND_CS4281 4 +.Os +.Sh NAME +.Nm snd_cs4281 +.Nd "Crystal Semiconductor CS4281 PCI bridge device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device sound" +.Cd "device snd_cs4281" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the +following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +snd_cs4281_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +bridge driver allows the generic audio driver +.Xr sound 4 +to attach to the CS4281 sound card. +.Sh HARDWARE +The +.Nm +driver supports the following sound cards: +.Pp +.Bl -bullet -compact +.It +Crystal Semiconductor CS4281 +.El +.Sh SEE ALSO +.Xr sound 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 4.3 . +.Sh AUTHORS +.An Orion Hodson Aq Mt O.Hodson@cs.ucl.ac.uk diff --git a/static/freebsd/man4/snd_csa.4 b/static/freebsd/man4/snd_csa.4 new file mode 100644 index 00000000..8422387c --- /dev/null +++ b/static/freebsd/man4/snd_csa.4 @@ -0,0 +1,96 @@ +.\" +.\" Copyright (c) 1999 Seigo Tanimura +.\" 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 December 15, 2005 +.Dt SND_CSA 4 +.Os +.Sh NAME +.Nm snd_csa +.Nd Crystal Semiconductor CS461x/462x/4280 PCI bridge device driver +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device sound" +.Cd "device snd_csa" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the +following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +snd_csa_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +bridge driver allows the generic audio driver +.Xr sound 4 +to attach to Crystal Semiconductor CS461x/462x/4280 based sound cards. +.Sh HARDWARE +The +.Nm +driver supports the following sound cards: +.Pp +.Bl -bullet -compact +.It +Crystal Semiconductor CS4280 +.It +Crystal Semiconductor CS4610 +.It +Crystal Semiconductor CS4611 +.It +Crystal Semiconductor CS4614 +.It +Crystal Semiconductor CS4615 +.It +Crystal Semiconductor CS4622 +.It +Crystal Semiconductor CS4624 +.It +Crystal Semiconductor CS4630 +.It +Genius Soundmaker 128 Value +.It +Hercules Game Theatre XP +.It +Turtle Beach Santa Cruz +.El +.Pp +Some onboard CS4610 chips are accompanied by the CS423x ISA codec +instead of the CS4297 AC97 codec. +Such configurations are not +supported by the +.Nm +driver yet. +.Sh SEE ALSO +.Xr sound 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 4.0 . +.Sh AUTHORS +.An Seigo Tanimura Aq Mt tanimura@r.dl.itc.u-tokyo.ac.jp diff --git a/static/freebsd/man4/snd_dummy.4 b/static/freebsd/man4/snd_dummy.4 new file mode 100644 index 00000000..5e9d8aa5 --- /dev/null +++ b/static/freebsd/man4/snd_dummy.4 @@ -0,0 +1,80 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2024 The FreeBSD Foundation +.\" +.\" Portions of this software were developed by Christos Margiolis +.\" under sponsorship from the FreeBSD Foundation. +.\" +.\" 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 October 22, 2025 +.Dt SND_DUMMY 4 +.Os +.Sh NAME +.Nm snd_dummy +.Nd Dummy audio driver +.Sh SYNOPSIS +To load the driver at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +snd_dummy_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver implements a virtual testing device, meaning it does not correspond to a +physical sound card. +It is intended for testing, so that test programs do not need to rely on +hardware being present in the machine in order to run. +.Pp +The driver attaches as a regular +.Xr sound 4 +device, with two channels (one playback and one recording), as well as a mixer. +.Pp +Playback works by discarding all input, and recording by returning silence +(zeros). +.Sh FILES +.Bl -tag -width "/dev/dsp.dummy" -compact +.It Pa /dev/dsp.dummy +Alias to the device's +.Pa /dev/dsp%d +file created by +.Xr sound 4 . +This makes it easy for tests to open the dummy device when there are more +devices present in the system. +.El +.Sh SEE ALSO +.Xr sound 4 , +.Xr loader.conf 5 , +.Xr loader 8 +.Sh AUTHORS +The +.Nm +driver was implemented by +.An Christos Margiolis Aq Mt christos@FreeBSD.org +under sponsorship from the +.Fx +Foundation. +.Sh CAVEATS +Because the driver automatically attaches once the module is loaded, it can +only be attached once. diff --git a/static/freebsd/man4/snd_emu10k1.4 b/static/freebsd/man4/snd_emu10k1.4 new file mode 100644 index 00000000..5ced043c --- /dev/null +++ b/static/freebsd/man4/snd_emu10k1.4 @@ -0,0 +1,80 @@ +.\" Copyright (c) 2004 Atte Peltomaki +.\" 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 December 15, 2005 +.Dt SND_EMU10K1 4 +.Os +.Sh NAME +.Nm snd_emu10k1 +.Nd "SoundBlaster Live! and Audigy PCI bridge device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device sound" +.Cd "device snd_emu10k1" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the +following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +snd_emu10k1_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +bridge driver allows the generic audio driver +.Xr sound 4 +to attach to the SoundBlaster Live!\& and Audigy audio cards. +.Pp +Digital output is supported by default. +.Sh HARDWARE +The +.Nm +driver supports the following sound cards: +.Pp +.Bl -bullet -compact +.It +Creative SoundBlaster Live!\& (EMU10K1 Chipset) +.It +Creative SoundBlaster Audigy (EMU10K2 Chipset) +.It +Creative SoundBlaster Audigy 2 (EMU10K2 Chipset) +.It +Creative SoundBlaster Audigy 2 (EMU10K3 Chipset) +.El +.Sh SEE ALSO +.Xr sound 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 4.1 . +.Sh AUTHORS +.An David O'Brien Aq Mt obrien@FreeBSD.org +.An Orlando Bassotto Aq Mt orlando.bassotto@ieo-research.it +.An Cameron Grant Aq Mt cg@FreeBSD.org +.Sh BUGS +Fancy features like DD5.1 output are not supported. diff --git a/static/freebsd/man4/snd_emu10kx.4 b/static/freebsd/man4/snd_emu10kx.4 new file mode 100644 index 00000000..cdfe3f03 --- /dev/null +++ b/static/freebsd/man4/snd_emu10kx.4 @@ -0,0 +1,294 @@ +.\" +.\" Copyright (c) 2003-2007 Yuriy Tsibizov +.\" 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 May 28, 2008 +.Dt SND_EMU10KX 4 +.Os +.Sh NAME +.Nm snd_emu10kx +.Nd Creative SoundBlaster Live! and Audigy sound cards device driver +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device sound" +.Cd "device snd_emu10kx" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the +following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +snd_emu10kx_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +bridge driver allows the generic audio driver +.Xr sound 4 +to attach to Creative sound cards based on the EMU10K1, CA0100, CA0101, CA0102 +and CA0108 DSPs. +.Pp +The +.Nm +sound cards have a PCM part, which is accessible through one to five +.Xr pcm 4 +devices (see +.Sx MULTICHANNEL PLAYBACK +for details), and MPU401-compatible MIDI I/O controller, which is accessible +through the midi device. +Wave table synthesizer support is not available. +.Sh HARDWARE +The +.Nm +driver supports the following sound cards: +.Pp +.Bl -bullet -compact +.It +Creative Sound Blaster Live!\& (EMU10K1 Chipset). +Both PCM and MIDI interfaces are available. +.It +Creative Sound Blaster Audigy (CA0100 and CA0101 Chipset). +PCM and two MIDI interfaces available. +.It +Creative Sound Blaster Audigy 2 and Creative Sound Blaster Audigy 4 (CA0102 +Chipset). +PCM support is limited to 48kHz/16 bit stereo (192kHz/24 bit part +of this chipset is not supported). +.It +Creative Sound Blaster Audigy 2 Value (CA0108 Chipset). +PCM support is limited +to 48kHz/16 bit stereo (192kHz/24 bit part of this chipset is not supported). +There is no MIDI support for this card. +.El +.Pp +The +.Nm +driver does +.Em not +support the following sound cards (although they have names +similar to some supported ones): +.Pp +.Bl -bullet -compact +.It +Creative Sound Blaster Live!\& 24-Bit, identified by +.Fx +as +.Qq Li "emu10k1x Soundblaster Live! 5.1" . +.It +Creative Sound Blaster Audigy LS / ES, identified by +.Fx +as +.Qq Li "CA0106-DAT Audigy LS" . +.It +All other Creative sound cards with -DAT chipsets. +.It +All Creative X-Fi series sound cards. +.El +.Sh MULTICHANNEL PLAYBACK +By default the +.Nm +driver is loaded with multichannel playback capabilities enabled. +If you do not set the +.Dv hint.emu10kx.0.multichannel_disabled +option in your +.Xr loader.conf 5 +configuration file you will get up to five DSP devices, one for each +sound card output. +You can use additional software (like +.Em audio/pulseaudio +from +.Em The Ports Collection ) +to do sound stream demultiplexing. +Only +.Dq FRONT +output can play and record sound from external +sources (like line or S/PDIF inputs). +.Sh MULTICHANNEL RECORDING +By default multichannel recording capabilities are not enabled when you load +the +.Nm +driver. +If you enable the +.Dv hint.emu10kx.0.multichannel_recording +option in +.Xr loader.conf 5 +you will get one more DSP device that is rate-locked to 48kHz/16bit/mono. +This is actually 48kHz/16bit/32 channels on SB Live! cards and +48kHz/16bit/64channels on Audigy cards, but the current implementation of +the sound subsystem does not support such an amount of PCM channels. +This device can not be opened for read, thus confusing many applications. +.Pp +Within a multichannel stream, the first half (0-15 or 0-31) is a copy of all DSP +outputs, the second half (15-30 or 32-63) is a copy of some DSP inputs. +On Live! cards the last substream (31) is used as a sync stream and is always +set to 0xc0de. +Audigy cards do not need such sync data, because a stream always starts with +substream 0. +.Ss SB Live! substream map (in byte offsets, each substream is 2 bytes LE) +.Bl -tag -width ".Dv +0x00..+0x1E" +.It Dv Offset +Substream +.It +0x00..+0x1E +PCM streams 0..15 +.It +0x20, +0x22 +Empty +.It +0x24..+0x2A +PCM inputs: front left, front right, rear left, rear right, center, sub +.It +0x2C..+0x3C +DSP inputs 0..8: +.It +0x3E +sync substream (0xc0de) +.El +.Ss Audigy substream map (in byte offsets, each substream is 2 bytes LE) +.Bl -tag -width ".Dv +0x00..+0x3E" +.It Dv Offset +Substream +.It +0x00..+0x3E +PCM streams 0..31 +.It +0x40..+0x5E +PCM inputs: front LR, rear LR, center, sub, ... +.It +0x60..+0x7E +DSP inputs 0..16 +.El +.Sh OSS MIXER CONTROLS +These are the controls available through the standard OSS programming interface. +You can use +.Xr mixer 8 +to change them. +.Pp +On EMU10K1-based cards the OSS mixer directly controls the AC97 codec. +On newer cards the OSS mixer controls some parameters of the AC97 codec and +some DSP-based mixer controls. +.Bl -inset +.It Qq vol +mixer control for the overall sound volume. +.It Qq pcm +mixer control for the PCM playback volume. +It controls only front output +volume in multichannel mode and all output volume in single channel mode. +.It Qq rec +mixer control acts very differently on EMU10K1 and other cards. +On EMU10K1 cards it controls the AC97 codec recording level. +On non-EMU10K1 cards it controls the amount of AC97 +.Dq stereo mix + entering the DSP. +AC97 recording level and AC97 recording source are fixed on CA0100, CA0101, +CA0102 and CA0108 cards. +The AC97 recording levels are always set to maximum and recording source is always +.Dq Li "stereo mix" . +.It Qq dig1 +is a CD S/PDIF (on-card) volume control +.It Qq dig2 +is an AudigyDrive S/PDIF (Audigy series) or TOSLink (SB Live! series) volume +control +.It Qq dig3 +is an on-card S/PDIF volume control +.It Qq line2 +is AudigyDrive "Line In 2" volume control +.It Qq line3 +is AudigyDrive "AUX In 2" volume control +.El +.Pp +Other OSS mixer controls control the inputs of the AC97 codec. +.Sh PRIVATE DEVICE CONTROLS +You can control some of EMU10Kx's operation and configuration parameters through +.Va dev.emu10kx. Ns Aq Ar X +sysctls. +These +.Xr sysctl 8 +values are temporary and should not be relied upon. +.Sh DRIVER CONFIGURATION +Loader tunables are used to set driver configuration. +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or they can be stored in +.Pa /boot/loader.conf . +These tunables cannot be changed from a machine +.Xr sysctl 8 +entry after boot, but you can change them using +.Xr kenv 1 +before loading the +.Nm +driver. +.Bl -tag -width indent +.It Va hint.emu10kx. Ns Ao Ar X Ac Ns Va .disabled +Disables loading a driver instance. +.It Va hint.emu10kx. Ns Ao Ar X Ac Ns Va .multichannel_disabled +Disables multichannel playback support, when one card is represented as +several PCM devices. +.It Va hint.emu10kx. Ns Ao Ar X Ac Ns Va .multichannel_recording +Enables experimental multichannel recording support. +.It Va hint.emu10kx. Ns Ao Ar X Ac Ns Va .debug +Set debug output level. +.Bl -tag -width 2n +.It 0 +No additional debug options enabled +.It 1 +Enables all DSP outputs to be connected, even those +that are known to be unused on a particular card. +.It 2 +Additional debug messages about in-driver events will be printed. +.It 2 +Additional debug messages will be printed when memory allocation fails. +.El +.El +.Sh FILES +.Bl -tag -width ".Pa /dev/emu10kx?" -compact +.It Pa /dev/emu10kx? +.Nm +management interface +.El +.Sh SEE ALSO +.Xr sound 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 7.0 . +.Sh AUTHORS +.An -nosplit +The PCM part of the driver is based on the +.Xr snd_emu10k1 4 +SB Live!\& driver by +.An Cameron Grant Aq Mt cg@FreeBSD.org . +The MIDI interface is based on the +.Xr snd_emu10k1 4 +MIDI interface code by +.An Mathew Kanner Aq Mt matk@FreeBSD.org . +The +.Nm +device driver and this manual page were written by +.An Yuriy Tsibizov . +.Sh BUGS +The driver does not detect lost S/PDIF signals and produces noise when +S/PDIF is not connected and S/PDIF volume is not zero. +.Pp +The PCM driver cannot detect the presence of Live!Drive or AudigyDrive +breakout boxes and tries to use them (and list their connectors in the +mixer). +.Pp +The MIDI driver cannot detect the presence of Live!Drive or AudigyDrive +breakout boxes and tries to enable the IR receiver on them anyway. diff --git a/static/freebsd/man4/snd_envy24.4 b/static/freebsd/man4/snd_envy24.4 new file mode 100644 index 00000000..fe65004a --- /dev/null +++ b/static/freebsd/man4/snd_envy24.4 @@ -0,0 +1,82 @@ +.\" Copyright (c) 2006 Alexander Leidinger +.\" 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 June 1, 2014 +.Dt SND_ENVY24 4 +.Os +.Sh NAME +.Nm snd_envy24 +.Nd "VIA Envy24 and compatible bridge device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device sound" +.Cd "device snd_envy24" +.Cd "device snd_spicds" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the +following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +snd_envy24_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +bridge driver allows the generic audio driver +.Xr sound 4 +to attach to VIA Envy24 (ICE1724 or VT1724 chipset) and compatible audio +devices. +.Sh HARDWARE +The +.Nm +driver supports the following audio devices: +.Pp +.Bl -bullet -compact +.It +M-Audio Audiophile 2496 +.It +M-Audio Delta Dio 2496 +.It +Terratec DMX 6fire +.El +Only analog playback is supported. +Recording and other features of these cards are not supported. +.Sh SEE ALSO +.Xr sound 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 6.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Katsurajima Naoto . +This manual page was written by +.An Alexander Leidinger Aq Mt netchild@FreeBSD.org . diff --git a/static/freebsd/man4/snd_envy24ht.4 b/static/freebsd/man4/snd_envy24ht.4 new file mode 100644 index 00000000..f909afc7 --- /dev/null +++ b/static/freebsd/man4/snd_envy24ht.4 @@ -0,0 +1,107 @@ +.\" Copyright (c) 2006 Alexander Leidinger +.\" 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 August 11, 2018 +.Dt SND_ENVY24HT 4 +.Os +.Sh NAME +.Nm snd_envy24ht +.Nd "VIA Envy24HT and compatible bridge device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device sound" +.Cd "device snd_envy24ht" +.Cd "device snd_spicds" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the +following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +snd_envy24ht_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +bridge driver allows the generic audio driver +.Xr sound 4 +to attach to VIA Envy24HT (ICE1724 or VT1724 chipset) and compatible audio +devices. +.Sh HARDWARE +The +.Nm +driver supports the following audio devices: +.Pp +.Bl -bullet -compact +.It +Audiotrak Prodigy 7.1 +.It +Audiotrak Prodigy 7.1 LT +.It +Audiotrak Prodigy 7.1 XT +.It +Audiotrak Prodigy HD2 +.It +ESI Juli@ +.It +ESI Juli@ XTe +.It +M-Audio Audiophile 192 +.It +M-Audio Revolution 5.1 +.It +M-Audio Revolution 7.1 +.It +Terratec Aureon 5.1 Sky +.It +Terratec Aureon 7.1 Space +.It +Terratec Aureon 7.1 Universe +.It +Terratec PHASE 22 +.It +Terratec PHASE 28 +.El +Only analog playback is supported. +Recording and other features of these cards are not supported. +.Sh SEE ALSO +.Xr sound 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 6.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Konstantin Dimitrov +based upon the +.Xr snd_envy24 4 +driver. +This manual page was written by +.An Alexander Leidinger Aq Mt netchild@FreeBSD.org . diff --git a/static/freebsd/man4/snd_es137x.4 b/static/freebsd/man4/snd_es137x.4 new file mode 100644 index 00000000..e503df44 --- /dev/null +++ b/static/freebsd/man4/snd_es137x.4 @@ -0,0 +1,115 @@ +.\" Copyright (c) 2004 Atte Peltomaki +.\" 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 November 29, 2006 +.Dt SND_ES137X 4 +.Os +.Sh NAME +.Nm snd_es137x +.Nd "Ensoniq AudioPCI ES137x bridge device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device sound" +.Cd "device snd_es137x" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the +following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +snd_es137x_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +bridge driver allows the generic audio driver +.Xr sound 4 +to attach to the Ensoniq 137x audio cards. +.Ss Runtime Configuration +The following +.Xr sysctl 8 +variables are available in addition to those available to all +.Xr sound 4 +devices: +.Bl -tag -width ".Va hw.snd.pcm%d.latency_timer" -offset indent +.It Va hw.snd.pcm%d.latency_timer +Controls the PCI latency timer setting. +Increasing this value will solve most popping and crackling issues +(especially on VIA motherboards). +.It Va hw.snd.pcm%d.spdif_enabled +Enables S/PDIF output on the primary playback channel. +This +.Xr sysctl 8 +variable is available only if the device is known to support S/PDIF output. +.It Va dev.pcm.%d.polling +Experimental polling mode, where the driver operates by querying the device +state on each tick using +.Xr callout 9 . +Polling is disabled by default. +Do not enable it unless you are facing weird interrupt problems or if the +device cannot generate interrupts at all. +.El +.Sh HARDWARE +The +.Nm +driver supports the following sound cards: +.Pp +.Bl -bullet -compact +.It +Creative CT5880-A +.It +Creative CT5880-C +.It +Creative CT5880-D +.It +Creative CT5880-E +.It +Creative SB AudioPCI CT4730 +.It +Ensoniq AudioPCI ES1370 +.It +Ensoniq AudioPCI ES1371-A +.It +Ensoniq AudioPCI ES1371-B +.It +Ensoniq AudioPCI ES1373-A +.It +Ensoniq AudioPCI ES1373-B +.It +Ensoniq AudioPCI ES1373-8 +.El +.Sh SEE ALSO +.Xr sound 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 4.0 . +.Sh AUTHORS +.An Russell Cattelan Aq Mt cattelan@thebarn.com +.An Cameron Grant Aq Mt cg@FreeBSD.org +.An Joachim Kuebart +.An Jonathan Noack Aq Mt noackjr@alumni.rice.edu diff --git a/static/freebsd/man4/snd_fm801.4 b/static/freebsd/man4/snd_fm801.4 new file mode 100644 index 00000000..e72c07b2 --- /dev/null +++ b/static/freebsd/man4/snd_fm801.4 @@ -0,0 +1,76 @@ +.\" Copyright (c) 2005 Joel Dahl +.\" 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 December 1, 2005 +.Dt SND_FM801 4 +.Os +.Sh NAME +.Nm snd_fm801 +.Nd "Forte Media FM801 bridge device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device sound" +.Cd "device snd_fm801" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the +following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +snd_fm801_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +bridge driver allows the generic audio driver, +.Xr sound 4 , +to attach audio devices based on the Forte Media FM801 chipset. +This is a common chipset found in various parts used by OEM manufacturers. +.Sh HARDWARE +The +.Nm +driver supports audio devices based on the following chipset: +.Pp +.Bl -bullet -compact +.It +Forte Media FM801 +.El +.Sh SEE ALSO +.Xr sound 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 4.2 . +.Sh AUTHORS +This manual page was written by +.An Joel Dahl Aq Mt joel@FreeBSD.org . +.Sh BUGS +The Forte Media FM801 chipset is a sort of PCI bridge, not an actual +sound controller, making it possible to have soundless support. +One problem is that both chipsets, with and without sound support, use the +same PCI ID. +This makes it impossible to determine which one is installed. diff --git a/static/freebsd/man4/snd_hda.4 b/static/freebsd/man4/snd_hda.4 new file mode 100644 index 00000000..93bac0e5 --- /dev/null +++ b/static/freebsd/man4/snd_hda.4 @@ -0,0 +1,641 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2006-2008 Joel Dahl +.\" Copyright (c) 2008 Alexander Motin +.\" 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 January 20, 2025 +.Dt SND_HDA 4 +.Os +.Sh NAME +.Nm snd_hda +.Nd "Intel High Definition Audio bridge device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device sound" +.Cd "device snd_hda" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the +following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +snd_hda_load="YES" +.Ed +.Sh DESCRIPTION +The High Definition (HD) Audio specification was developed by Intel as the +logical successor of the old AC'97 specification and has several advantages, +such as higher bandwidth which allows more channels and more detailed formats, +support for several logical audio devices, and general purpose DMA channels. +.Pp +The +.Nm +driver includes HDA bus controller driver (hdac), HDA codec driver (hdacc) +and HDA codecs audio functions bridge driver (hdaa) that allows +the generic audio driver, +.Xr sound 4 , +to be used with this hardware. +Only audio functions are supported by +.Nm . +Modem and other possible functions are not implemented. +.Pp +The +.Nm +driver supports hardware that conforms with revision 1.0 of the Intel High +Definition Audio specification and tries to behave much like the Microsoft +Universal Audio Architecture (UAA) draft (revision 0.7b) for handling audio +devices. +.Pp +According to HDA and UAA specifications, depending on the number of HDA buses +and codecs present in system, their audio capabilities and BIOS provided +configuration, the +.Nm +driver often provides several PCM audio devices. +For example, one device for main rear 7.1 output and inputs, one device +for independent headset connectors at front and one device for SPDIF or +HDMI audio input/output. +The assignment of audio inputs and outputs may be tuned with +.Xr device.hints 5 +or +.Xr sysctl 8 . +The driver's verbose boot messages provide a lot of information about +the operation of the driver and present audio setup. +.Pp +The default audio device may be tuned by setting the +.Ar hw.snd.default_unit +sysctl, as described in +.Xr sound 4 , +or explicitly specified in application settings. +.Ss Boot-time Configuration +The following variables are available at boot-time through the +.Xr device.hints 5 +file: +.Bl -tag -width ".Va hint.hdac.%d.config"-offset indent +.It Va hint.hdac.%d.config +Configures a range of possible controller options. +Possible values are: +.Dq Li 64bit , +.Dq Li dmapos , +.Dq Li msi . +An option prefixed with +.Dq Li no , +such as +.Dq Li nomsi , +will do the opposite and takes precedence. +Options can be separated by whitespace and commas. +.It Va hint.hdac.%d.msi +Controls MSI (Message Signaled Interrupts) support. +.It Va hint.hdac.%d.cad%d.nid%d.config +Same as +.Va hint.hdaa.%d.nid%d.config +.It Va hint.hdaa.%d.config +Configures a range of possible audio function options. +Possible values are: +.Dq Li eapdinv , +.Dq Li ivref , +.Dq Li ivref50 , +.Dq Li ivref80 , +.Dq Li ivref100 , +.Dq Li fixedrate , +.Dq Li forcestereo , +.Dq Li ovref , +.Dq Li ovref50 , +.Dq Li ovref80 , +.Dq Li ovref100 , +.Dq Li senseinv , +.Dq Li softpcmvol , +and +.Dq Li vref . +An option prefixed with +.Dq Li no , +such as +.Dq Li nofixedrate , +will do the opposite and takes precedence. +Options can be separated by whitespace and commas. +.Pp +The +.Dq Li eapdinv +option inverts External Amplifier Power Down signal. +The +.Dq Li fixedrate +denies all sampling rates except 48KHz. +The +.Dq Li forcestereo +denies mono playback/recording. +The +.Dq Li senseinv +option inverts jack sensing logic. +The +.Dq Li ivref Ns Ar X +and +.Dq Li ovref Ns Ar X +options control the voltage used to power external microphones. +.It Va dev.hdaa.%d.init_clear +Zero out the pin widget config setup by the system. +Some systems seem to have unusable audio devices if the pin widget +configuration is cleared. +Set this value to 0 to accept the default configuration values setup by the +BIOS. +.It Va hint.hdaa.%d.gpio_config +Overrides audio function GPIO pins configuration set by BIOS. +May be specified as a set of space-separated +.Dq Ar num Ns = Ns Ar value +pairs, where +.Ar num +is GPIO line number, and +.Ar value +is one of: +.Dq Li keep , +.Dq Li set , +.Dq Li clear , +.Dq Li disable +and +.Dq Li input . +.Pp +.Dq Li GPIO Ns s +are a codec's General Purpose I/O pins which system integrators sometimes +use to control external muters, amplifiers and so on. +If you have no sound, or sound volume is not adequate, you may have to +experiment a bit with the GPIO setup to find the optimal setup for your +system. +.It Va hint.hdaa.%d.nid%d.config +Overrides audio function pin configuration set by BIOS. +May be specified as a 32-bit hexadecimal value with a leading +.Dq 0x , +or as a set of space-separated +.Dq Ar option Ns = Ns Ar value +pairs. +.It Va hint.pcm.%d.rec.autosrc +Controls automatic recording source feature: +.Bl -tag -width 2n -compact +.It 0 +disabled, +.It 1 +once on attach, +.It 2 +enabled. +.El +When enabled, driver will automatically set recording source of the mixer to +connected input using jack presence detection statuses. +.El +.Pp +Pin configuration is the UAA driver's main source of information about codec +usage. +This information is usually provided by the codec manufacturer and tuned +by system integrators for specific system requirements. +The +.Nm +driver allows users to override it to fix integrator mistakes or to use the +available codec in alternative ways (for example to get stereo output and 2 +inputs instead of a single 5.1 output). +.Pp +The following options are supported: +.Bl -tag -width ".Va device=" -offset indent +.It Va as +Association number. +Associations are used to group individual pins to form a complex multi-pin +device. +For example, to group 4 connectors for 7.1 input/output, or to treat several +input connectors as sources for the same input device. +Association numbers can be specified as numeric values from 0 to 15. +A value of 0 means disabled pin. +A value of 15 is a set of independent unassociated pins. +Each association includes only pins of the same direction (in/out) and is +detected atomically (all pins or none). +A separate PCM audio device is created for every pair of input and +output associations. +.It Va seq +Sequence number. +A unique, per-association number used to order pins inside the +particular association. +Sequence numbers can be specified as numeric values from 0 to 15. +.Pp +The sequence number 15 has a special meaning for output associations. +Output pins with this number and device type +.Dq Ar Headphones +will duplicate (with automatic mute if jack detection is supported) the +first pin in that association. +.Pp +The sequence numbers 14 and 15 has a special meaning for input associations. +Their presence in association defines it as multiplexed or mixed respectively. +If none of them are present and there are more than one pin in association, +the association will provide multichannel input. +.Pp +For multichannel input/output associations sequence numbers encode +channel pairs positions: +0 - Front, 1 - Center/LFE, 2 - Back, 3 - Front Wide Center, 4 - Side. +Standard combinations are: (0) - Stereo; (0, 2), (0, 4) - Quadro; +(0, 1, 2), (0, 1, 4) - 5.1; (0, 1, 2, 4) - 7.1. +.It Va device +Device type. +Can be specified as a number from 0 to 15 or as a name: +.Dq Li Line-out , +.Dq Li Speaker , +.Dq Li Headphones, +.Dq Li CD , +.Dq Li SPDIF-out , +.Dq Li Digital-out , +.Dq Li Modem-line , +.Dq Li Modem-handset , +.Dq Li Line-in , +.Dq Li AUX , +.Dq Li Mic , +.Dq Li Telephony , +.Dq Li SPDIF-in , +.Dq Li Digital-in , +.Dq Li Res.E , +or +.Dq Li Other . +The device type also describes the pin direction (in/out). +For example, +.Dq Li CD +always means an input pin, while +.Dq Li Headphones +always means an output. +.It Va conn +Connection type. +Can be specified as a number from 0 to 3. +The connection type can also be specified as one of the special names +.Dq Li Jack , +.Dq Li None , +.Dq Li Fixed , +or +.Dq Li Both . +Pins with a connection type of +.Dq Li None +are disabled. +.It Va ctype +Connector physical type. +Can be specified as a number from 0 to 15. +This is a reference only value. +It is ignored by the +.Nm +driver. +.It Va color +Connector color. +Can be specified as a number from 0 to 15 or as one of the names +.Dq Li Unknown , +.Dq Li Black , +.Dq Li Grey , +.Dq Li Blue , +.Dq Li Green , +.Dq Li Red , +.Dq Li Orange , +.Dq Li Yellow , +.Dq Li Purple , +.Dq Li Pink , +.Dq Li Res.A , +.Dq Li Res.B , +.Dq Li Res.C , +.Dq Li Res.D , +.Dq Li White , +or +.Dq Li Other . +This is a reference only value. +It is ignored by the +.Nm +driver. +.It Va loc +Connector physical location. +Can be specified as a number from 0 to 63. +This is a reference only value. +It is ignored by the +.Nm +driver. +.It Va misc +Misc bits. +Can be specified as a number from 0 to 15. +Bit 0 has a special meaning. +When set it means that jack detection is not implemented in hardware. +.El +.Ss Runtime Configuration +The following +.Xr sysctl 8 +variables are available in addition to those available to all +.Xr sound 4 +devices: +.Bl -tag -width ".Va dev.hdaa.%d.nid%d_original" -offset indent +.It Va dev.hdac.%d.pindump +Setting this to a non-zero value dumps the current pin configuration, main +capabilities and jack sense status of all audio functions on the controller +to console and syslog. +.It Va dev.hdac.%d.polling +Enables polling mode. +In this mode the driver operates by querying the device state on timer +ticks using +.Xr callout 9 +instead of interrupts. +Polling is disabled by default. +Do not enable it unless you are facing weird interrupt problems or if the +device cannot generate interrupts at all. +.It Va dev.hdaa.%d.config +Run-time equivalent of the +.Va hint.hdaa.%d.config +tunable. +.It Va dev.hdaa.%d.gpi_state +Current state of GPI lines. +.It Va dev.hdaa.%d.gpio_state +Current state of GPIO lines. +.It Va dev.hdaa.%d.gpio_config +Run-time equivalent of the +.Va hint.hdaa.%d.gpio.config +tunable. +.It Va dev.hdaa.%d.gpo_state +Current state of GPO lines. +.It Va dev.hdaa.%d.nid%d_config +Run-time equivalent of the +.Va hint.hdaa.%d.nid%d.config +tunable. +.It Va dev.hdaa.%d.nid%d_original +Original pin configuration written by BIOS. +.It Va dev.hdaa.%d.reconfig +Setting this to a non-zero value makes driver to destroy existing pcm devices +and process new pins configuration set via +.Va dev.hdaa.%d.nid%d_config . +.It Va dev.pcm.%d.play.32bit , dev.pcm.%d.rec.32bit +HDA controller uses 32bit representation for all samples of more then 16 bits. +These variables allow to specify how many bits of these 32 should be +used by CODEC. +Depending on codec capabilities, possible values are 20, 24 and 32 bit. +The default value is 24. +.It Va dev.pcm.%d.rec.autosrc +Run-time equivalent of the +.Va hint.pcm.%d.rec.autosrc +tunable. +.El +.Sh HARDWARE +The +.Nm +driver supports PCI class 04h +.Pq multimedia , +subclass 03h +.Pq HDA +audio controllers and codecs compatible with the +Intel High Definition Audio 1.0 specification. +.Sh EXAMPLES +Taking HP Compaq DX2300 with Realtek ALC888 HDA codec for example. +This system has two audio connectors on a front side, three audio connectors +on a rear side and one internal speaker. +According to verbose driver output and the codec datasheet, +this codec has five stereo DACs and two stereo ADCs, all of them are routable to +any codec pin (external connector). +All codec pins are reversible (could be configured either as input or output). +.Pp +So high codec uniformity and flexibility allow driver to configure it in many +different ways, depending on requested pins usage described by pins configuration. +The driver reports such default pin configuration when verbose messages enabled: +.Bd -literal +hdaa0: nid 0x as seq device conn jack loc color misc +hdaa0: 20 01014020 2 0 Line-out Jack 1/8 Rear Green 0 +hdaa0: 21 99130110 1 0 Speaker Fixed ATAPI Onboard Unknown 1 +hdaa0: 22 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA +hdaa0: 23 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA +hdaa0: 24 01a19830 3 0 Mic Jack 1/8 Rear Pink 8 +hdaa0: 25 02a1983f 3 15 Mic Jack 1/8 Front Pink 8 +hdaa0: 26 01813031 3 1 Line-in Jack 1/8 Rear Blue 0 +hdaa0: 27 0221401f 1 15 Headphones Jack 1/8 Front Green 0 +hdaa0: 28 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA +hdaa0: 30 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA +hdaa0: 31 411111f0 15 0 Speaker None 1/8 Rear Black 1 DISA +.Ed +.Pp +Here we can see, that the nodes with ID (nid) 25 and 27 are front panel +connectors (Jack, Front), nids 20, 24 and 26 are rear panel connectors +(Jack, Rear) and nid 21 is a built-in speaker (Fixed, Onboard). +Pins with nids 22, 23, 28, 30 and 31 will be disabled by driver due to "None" +connectivity. +So the pin count and description matches to connectors that we have. +.Pp +Using association (as) and sequence (seq) fields values pins are grouped into +3 associations: +.Bd -literal +hdaa0: Association 0 (1) out: +hdaa0: Pin nid=21 seq=0 +hdaa0: Pin nid=27 seq=15 +hdaa0: Association 1 (2) out: +hdaa0: Pin nid=20 seq=0 +hdaa0: Association 2 (3) in: +hdaa0: Pin nid=24 seq=0 +hdaa0: Pin nid=26 seq=1 +hdaa0: Pin nid=25 seq=15 +.Ed +.Pp +Each +.Xr pcm 4 +device uses two associations: one for playback and one for recording. +Associations processed and assigned to +.Xr pcm 4 +devices in increasing numerical order. +In this case association #0 (1) will become +.Li pcm0 +device playback, using the internal speakers and +.Ar Headphones +jack with speaker automute on the headphones jack connection. +Association #1 (2) will become +.Li pcm1 +playback, using the +.Ar Line-out +jack. +Association #2 (3) will become +.Li pcm0 +recording, using the external microphones and the +.Ar Line-in +jack. +.Pp +The +.Nm +driver provides extensive verbose messages to diagnose its operation +logic and describe its current codec configuration. +.Pp +Using +.Xr device.hints 5 +it is possible to modify the configuration of the existing pins, +allowing a broad range of different audio setups. +Here are a few examples of some setups possible for this particular +hardware: +.Ss Example 1 +Setting the +.Xr device.hints 5 +options +.Bd -literal +hint.hdac.0.cad0.nid20.config="as=1" +hint.hdac.0.cad0.nid21.config="as=2" +.Ed +.Pp +will swap line-out and speaker functions. +So the +.Li pcm0 +device will play to the line-out and headphones jacks. +Line-out will be muted on the headphones jack connection. +Recording on +.Li pcm0 +will go from two external microphones and line-in jacks. +.Li pcm1 +playback will go to the internal speaker. +.Ss Example 2 +Setting the +.Xr device.hints 5 +options +.Bd -literal +hint.hdac.0.cad0.nid20.config="as=1 seq=15 device=Headphones" +hint.hdac.0.cad0.nid27.config="as=2 seq=0" +hint.hdac.0.cad0.nid25.config="as=4 seq=0" +.Ed +.Pp +will split the headphones and one of the microphones to a separate device. +The +.Li pcm0 +device will play to the internal speaker and to the line-out jack, with +speaker automute on the line-out jack connection. +Recording on +.Li pcm0 +will use input from one external microphone and the line-in jacks. +The +.Li pcm1 +device will be completely dedicated to a headset (headphones and mic) +connected to the front connectors. +.Ss Example 3 +Setting the +.Xr device.hints 5 +options +.Bd -literal +hint.hdac.0.cad0.nid20.config="as=1 seq=0" +hint.hdac.0.cad0.nid26.config="as=2 seq=0" +hint.hdac.0.cad0.nid27.config="as=3 seq=0" +hint.hdac.0.cad0.nid25.config="as=4 seq=0" +hint.hdac.0.cad0.nid24.config="as=5 seq=0 device=Line-out" +hint.hdac.0.cad0.nid21.config="as=6 seq=0" +.Ed +.Pp +will give 4 independent devices: +.Li pcm0 +.Pq line-out and line-in , +.Li pcm1 +.Pq headphones and mic , +.Li pcm2 +.Pq additional line-out via retasked rear mic jack , +and +.Li pcm3 +.Pq internal speaker . +.Ss Example 4 +Setting the +.Xr device.hints 5 +options +.Bd -literal +hint.hdac.0.cad0.nid20.config="as=1 seq=0" +hint.hdac.0.cad0.nid24.config="as=1 seq=1 device=Line-out" +hint.hdac.0.cad0.nid26.config="as=1 seq=2 device=Line-out" +hint.hdac.0.cad0.nid21.config="as=2 seq=0" +.Ed +.Pp +will give 2 devices: +.Li pcm0 +for 5.1 playback via 3 rear connectors (line-out and retasked +mic and line-in) and headset (headphones and mic) at front connectors. +.Li pcm1 +for internal speaker playback. +On headphones connection rear connectors will be muted. +.Sh MIXER CONTROLS +Depending on codec configuration, these controls and signal sources could be +reported to +.Xr sound 4 : +.Bl -tag -width ".Va speaker" -offset indent +.It Va vol +overall output level (volume) +.It Va rec +overall recording level +.It Va igain +input-to-output monitoring loopback level +.It Va ogain +external amplifier control +.It Va pcm +PCM playback +.It Va mix +input mix +.It Va mic +first external or second internal microphone input +.It Va monitor +first internal or second external microphone input +.It Va line , Va line1 , Va line2 , Va line3 +analog (line) inputs +.It Va dig1 , Va dig2 , Va dig3 +digital (S/PDIF, HDMI or DisplayPort) inputs +.It Va cd +CD input +.It Va speaker +PC speaker input +.It Va phin , Va phout , Va radio , Va video +other random inputs +.El +.Pp +Controls have different precision. +Some could be just an on/off triggers. +Most of controls use logarithmic scale. +.Sh SEE ALSO +.Xr snd_ich 4 , +.Xr sound 4 , +.Xr device.hints 5 , +.Xr loader.conf 5 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 6.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Stephane E. Potvin Aq Mt sepotvin@videotron.ca , +.An Ariff Abdullah Aq Mt ariff@FreeBSD.org +and +.An Alexander Motin Aq Mt mav@FreeBSD.org . +This manual page was written by +.An Joel Dahl Aq Mt joel@FreeBSD.org , +.An Alexander Motin Aq Mt mav@FreeBSD.org +and +.An Giorgos Keramidas Aq Mt keramida@FreeBSD.org . +.Sh BUGS +Some Hardware/OEM vendors tend to screw up BIOS settings or use custom +unusual CODEC wiring that create problems to the driver. +This may result in missing pcm devices, or a state where the +.Nm +driver seems to attach and work, but no sound is played. +Some cases can be solved by tuning +.Pa loader.conf +variables. +But before trying to fix problem that way, make sure that there really is +a problem and that the PCM audio device in use really corresponds to the +expected audio connector. +.Pp +Some vendors use non-standardized General Purpose I/O (GPIO) pins of the codec +to control external amplifiers. +In some cases setting a combination of GPIO bits may be needed to make +sound work on a specific device. +.Pp +HDMI and DisplayPort audio may also require support from video driver. diff --git a/static/freebsd/man4/snd_hdsp.4 b/static/freebsd/man4/snd_hdsp.4 new file mode 100644 index 00000000..ca24bcf2 --- /dev/null +++ b/static/freebsd/man4/snd_hdsp.4 @@ -0,0 +1,176 @@ +.\" Copyright (c) 2012 Ruslan Bukin +.\" Copyright (c) 2024 Florian Walpen +.\" 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 October 28, 2024 +.Dt SND_HDSP 4 +.Os +.Sh NAME +.Nm snd_hdsp +.Nd "RME HDSP bridge device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device sound" +.Cd "device snd_hdsp" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the +following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +snd_hdsp_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +bridge driver allows the generic audio driver +.Xr sound 4 +to attach to RME HDSP audio devices. +.Sh HARDWARE +The +.Nm +driver supports the following audio devices: +.Pp +.Bl -bullet -compact +.It +RME HDSP 9632 (optional AO4S-192 and AIS-192 extension boards) +.It +RME HDSP 9652 +.El +.Pp +By default, each +.Xr pcm 4 +device corresponds to a physical port on the sound card. +For ADAT ports, 8 channel, 4 channel and 2 channel formats are supported. +The effective number of ADAT channels is 8 channels at single speed +(32kHz-48kHz) and 4 channels at double speed (64kHz-96kHz). +Only the HDSP 9632 can operate at quad speed (128kHz-192kHz), ADAT is +disabled in this mode. +Depending on sample rate and channel format selected, not all pcm channels can +be mapped to ADAT channels and vice versa. +.Sh LOADER TUNABLES +These settings can be entered at the +.Xr loader 8 +prompt or in +.Xr loader.conf 5 . +.Bl -tag -width indent +.It Va hw.hdsp.unified_pcm +If set to 1, all physical ports are combined into one unified pcm device. +When opened in multi-channel audio software, this makes all ports available +at the same time, and fully synchronized. +For resulting channel numbers consult the following table: +.El +.Bl -column "Sound Card" "Single Speed" "Double Speed" "Quad Speed" +.Sy "Sound Card" Ta Sy "Single Speed" Ta Sy "Double Speed" Ta Sy "Quad Speed" +.It "" Ta "Play | Rec" Ta "Play | Rec" Ta "Play | Rec" +.It HDSP 9632 Ta " 16 | 16" Ta " 12 | 12" Ta " 8 | 8" +.It HDSP 9652 Ta " 26 | 26" Ta " 14 | 14" Ta " - | -" +.El +.Sh SYSCTL TUNABLES +These settings and informational values can be accessed at runtime with the +.Xr sysctl 8 +command. +If multiple RME HDSP sound cards are installed, each device has a separate +configuration. +To adjust the following sysctl identifiers for a specific sound card, insert +the respective device number in place of +.Ql 0 . +.Bl -tag -width indent +.It Va dev.hdsp.0.sample_rate +Set a fixed sample rate from 32000, 44100, 48000, up to 192000. +This is usually required for digital connections (AES, S/PDIF, ADAT). +The default value of 0 adjusts the sample rate according to pcm device settings. +.It Va dev.hdsp.0.period +The number of samples processed per interrupt, from 32, 64, 128, up to 4096. +Setting a lower value here results in less latency, but increases system load +due to frequent interrupt processing. +Extreme values may cause audio gaps and glitches. +.It Va dev.hdsp.0.clock_list +Lists possible clock sources to sync with, depending on the hardware model. +This includes internal and external master clocks as well as incoming digital +audio signals like AES, S/PDIF and ADAT. +.It Va dev.hdsp.0.clock_preference +Select a preferred clock source from the clock list. +HDSP cards will sync to this clock source when available, but fall back to +auto-sync with any other digital clock signal they receive. +Set this to +.Ql internal +if the HDSP card should act as master clock. +.It Va dev.hdsp.0.clock_source +Shows the actual clock source in use (read only). +This differs from what is set as clock preference when in auto-sync mode. +.It Va dev.hdsp.0.sync_status +Display the current sync status of all external clock sources. +Status indications are +.Ql none +for no signal at all, +.Ql lock +for when a valid signal is present, and +.Ql sync +for accurately synchronized signals (required for recording digital +audio). +.El +.Pp +The following tunables are applicable to HDSP 9632 devices only: +.Bl -tag -width indent +.It Va dev.hdsp.0.input_level +Select the sensitivity of the analog line input. +Available reference levels for the input signal are +.Ql LowGain , +.Ql +4dBu +and +.Ql -10dBV . +.It Va dev.hdsp.0.output_level +Select the gain level of the analog line output. +Available reference levels for the output signal are +.Ql HighGain , +.Ql +4dBu +and +.Ql -10dBV . +.It Va dev.hdsp.0.phones_level +Adjust the gain level of the phones output, separately from the analog line +output. +The signal can be lowered by 6 or 12 dB. +.El +.Pp +Where appropriate these sysctl values are modeled after official RME software on +other platforms, and adopt their terminology. +Consult the RME user manuals for additional information. +.Sh SEE ALSO +.Xr sound 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 15.0 . +.Sh AUTHORS +.An -nosplit +Based on +.Xr snd_hdspe 4 +originally written by +.An Ruslan Bukin . +All adaptation to HDSP cards by +.An Florian Walpen . diff --git a/static/freebsd/man4/snd_hdspe.4 b/static/freebsd/man4/snd_hdspe.4 new file mode 100644 index 00000000..35dea518 --- /dev/null +++ b/static/freebsd/man4/snd_hdspe.4 @@ -0,0 +1,178 @@ +.\" Copyright (c) 2012 Ruslan Bukin +.\" 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 November 2, 2024 +.Dt SND_HDSPE 4 +.Os +.Sh NAME +.Nm snd_hdspe +.Nd "RME HDSPe bridge device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device sound" +.Cd "device snd_hdspe" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the +following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +snd_hdspe_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +bridge driver allows the generic audio driver +.Xr sound 4 +to attach to RME HDSPe audio devices. +.Sh HARDWARE +The +.Nm +driver supports the following audio devices: +.Pp +.Bl -bullet -compact +.It +RME HDSPe AIO (optional AO4S-192 and AI4S-192 extension boards) +.It +RME HDSPe RayDAT +.El +.Pp +By default, each +.Xr pcm 4 +device corresponds to a physical port on the sound card. +For ADAT ports, 8 channel, 4 channel and 2 channel formats are supported. +The effective number of ADAT channels is 8 channels at single speed +(32kHz-48kHz), 4 channels at double speed (64kHz-96kHz), and 2 channels at +quad speed (128kHz-192kHz). +Depending on sample rate and channel format selected, not all pcm channels can +be mapped to ADAT channels and vice versa. +.Sh LOADER TUNABLES +These settings can be entered at the +.Xr loader 8 +prompt or in +.Xr loader.conf 5 . +.Bl -tag -width indent +.It Va hw.hdspe.unified_pcm +If set to 1, all physical ports are combined into one unified pcm device. +When opened in multi-channel audio software, this makes all ports available +at the same time, and fully synchronized. +For resulting channel numbers consult the following table: +.El +.Bl -column "HDSPe RayDAT" "Single Speed" "Double Speed" "Quad Speed" +.Sy "Sound Card" Ta Sy "Single Speed" Ta Sy "Double Speed" Ta Sy "Quad Speed" +.It "" Ta "Play | Rec" Ta "Play | Rec" Ta "Play | Rec" +.It HDSPe AIO Ta " 20 | 18" Ta " 16 | 14" Ta " 14 | 12" +.It HDSPe RayDAT Ta " 36 | 36" Ta " 20 | 20" Ta " 12 | 12" +.El +.Sh SYSCTL TUNABLES +These settings and informational values can be accessed at runtime with the +.Xr sysctl 8 +command. +If multiple RME HDSPe sound cards are installed, each device has a separate +configuration. +To adjust the following sysctl identifiers for a specific sound card, insert +the respective device number in place of +.Ql 0 . +.Bl -tag -width indent +.It Va dev.hdspe.0.sample_rate +Set a fixed sample rate from 32000, 44100, 48000, up to 192000. +This is usually required for digital connections (AES, S/PDIF, ADAT). +The default value of 0 adjusts the sample rate according to pcm device settings. +.It Va dev.hdspe.0.period +The number of samples processed per interrupt, from 32, 64, 128, up to 4096. +Setting a lower value here results in less latency, but increases system load +due to frequent interrupt processing. +Extreme values may cause audio gaps and glitches. +.It Va dev.hdspe.0.clock_list +Lists possible clock sources to sync with, depending on the hardware model. +This includes internal and external master clocks as well as incoming digital +audio signals like AES, S/PDIF and ADAT. +.It Va dev.hdspe.0.clock_preference +Select a preferred clock source from the clock list. +HDSPe cards will sync to this clock source when available, but fall back to +auto-sync with any other digital clock signal they receive. +Set this to +.Ql internal +if the HDSPe card should act as master clock. +.It Va dev.hdspe.0.clock_source +Shows the actual clock source in use (read only). +This differs from what is set as clock preference when in auto-sync mode. +.It Va dev.hdspe.0.sync_status +Display the current sync status of all external clock sources. +Status indications are +.Ql none +for no signal at all, +.Ql lock +for when a valid signal is present, and +.Ql sync +for accurately synchronized signals (required for recording digital +audio). +.El +.Pp +The following tunables are applicable to HDSPe AIO devices only: +.Bl -tag -width indent +.It Va dev.hdspe.0.input_level +Select the sensitivity of the analog line input. +Available reference levels for the input signal are +.Ql LowGain , +.Ql +4dBu +and +.Ql -10dBV . +.It Va dev.hdspe.0.output_level +Select the gain level of the analog line output. +Available reference levels for the output signal are +.Ql HighGain , +.Ql +4dBu +and +.Ql -10dBV . +.It Va dev.hdspe.0.phones_level +Adjust the gain level of the phones output, separately from the analog line +output. +Available reference levels for the output signal are +.Ql HighGain , +.Ql +4dBu +and +.Ql -10dBV . +.El +.Pp +Where appropriate these sysctl values are modeled after official RME software on +other platforms, and adopt their terminology. +Consult the RME user manuals for additional information. +.Sh SEE ALSO +.Xr sound 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 10.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Ruslan Bukin . +.An Florian Walpen +contributed clock source settings and restructured the pcm device mapping. diff --git a/static/freebsd/man4/snd_ich.4 b/static/freebsd/man4/snd_ich.4 new file mode 100644 index 00000000..77e425f5 --- /dev/null +++ b/static/freebsd/man4/snd_ich.4 @@ -0,0 +1,109 @@ +.\" Copyright (c) 2004 Jorge Mario G. Mazo +.\" 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 January 6, 2009 +.Dt SND_ICH 4 +.Os +.Sh NAME +.Nm snd_ich +.Nd "Intel ICH AC'97 and compatible bridge device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device sound" +.Cd "device snd_ich" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the +following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +snd_ich_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +bridge driver allows the generic audio driver +.Xr sound 4 +to attach to Intel ICH AC'97 and compatible audio devices. +.Pp +Some later chips, like ICH6/ICH7, depending on wiring can instead implement +newer Intel HD Audio specification, which is supported by +.Xr snd_hda 4 +driver. +.Sh HARDWARE +The +.Nm +driver supports the following audio devices: +.Pp +.Bl -bullet -compact +.It +AMD 768 +.It +AMD 8111 +.It +Intel 443MX +.It +Intel ICH +.It +Intel ICH revision 1 +.It +Intel ICH2 +.It +Intel ICH3 +.It +Intel ICH4 +.It +Intel ICH5 +.It +Intel ICH6 +.It +Intel ICH7 +.It +NVIDIA nForce +.It +NVIDIA nForce2 +.It +NVIDIA nForce2 400 +.It +NVIDIA nForce3 +.It +NVIDIA nForce3 250 +.It +NVIDIA nForce4 +.It +SiS 7012 +.El +.Sh SEE ALSO +.Xr snd_hda 4 , +.Xr sound 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 4.2 . +.Sh AUTHORS +This manual page was written by +.An Jorge Mario G. Mazo Aq Mt jgutie11@eafit.edu.co . diff --git a/static/freebsd/man4/snd_maestro3.4 b/static/freebsd/man4/snd_maestro3.4 new file mode 100644 index 00000000..3637f740 --- /dev/null +++ b/static/freebsd/man4/snd_maestro3.4 @@ -0,0 +1,92 @@ +.\" Copyright (c) 2001 Scott Long +.\" 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 December 15, 2005 +.Dt SND_MAESTRO3 4 +.Os +.Sh NAME +.Nm snd_maestro3 +.Nd "ESS Maestro3/Allegro-1 bridge device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device sound" +.Cd "device snd_maestro3" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the +following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +snd_maestro3_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the ESS Maestro3 and Allegro-1 sound chips +under the PCM framework. +These chips are mostly found in laptop computers and feature an AC97 mixer, +a multi-channel sample rate converter that can mix up to four digital audio +streams in hardware, recording support, and external volume control buttons. +.Pp +The firmware for the sound processor is licensed under the GNU Public +License, and thus this driver is not included in the default +.Pa GENERIC +kernel. +.Sh HARDWARE +The +.Nm +driver supports the following audio devices: +.Pp +.Bl -bullet -compact +.It +ESS Technology Allegro-1 +.It +ESS Technology Maestro3 +.El +.Sh DIAGNOSTICS +The hardware volume control buttons can be connected to two different pin +sets (GPIO or GD) on the chip, depending on the manufacturer. +The driver has no way of determining this configuration, so a hint may be +used to override the default guess. +The default setting for hardware volume control assumes that GD pins +are wired to control the hardware volume. +For systems that have the GPIO pins wired to the hardware volume control +buttons, add the line +.Dq Li hint.pcm.0.hwvol_config="0" +to the file +.Pa /boot/device.hints +to override the default setting. +.Sh SEE ALSO +.Xr sound 4 , +.Xr loader.conf 5 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 4.3 . +.Sh AUTHORS +.An Scott Long Aq Mt scottl@FreeBSD.org +.An Darrel Anderson Aq Mt anderson@cs.duke.edu diff --git a/static/freebsd/man4/snd_neomagic.4 b/static/freebsd/man4/snd_neomagic.4 new file mode 100644 index 00000000..5a42e9e3 --- /dev/null +++ b/static/freebsd/man4/snd_neomagic.4 @@ -0,0 +1,72 @@ +.\" Copyright (c) 2005 Joel Dahl +.\" 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 December 1, 2005 +.Dt SND_NEOMAGIC 4 +.Os +.Sh NAME +.Nm snd_neomagic +.Nd "NeoMagic 256AV/ZX bridge device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device sound" +.Cd "device snd_neomagic" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the +following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +snd_neomagic_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +bridge driver allows the generic audio driver, +.Xr sound 4 , +to attach to the NeoMagic 256AV/ZX audio devices. +These chips are mostly found in laptop computers. +.Sh HARDWARE +The +.Nm +driver supports the following audio devices: +.Pp +.Bl -bullet -compact +.It +NeoMagic 256AV +.It +NeoMagic 256ZX +.El +.Sh SEE ALSO +.Xr sound 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 4.0 . +.Sh AUTHORS +This manual page was written by +.An Joel Dahl Aq Mt joel@FreeBSD.org . diff --git a/static/freebsd/man4/snd_solo.4 b/static/freebsd/man4/snd_solo.4 new file mode 100644 index 00000000..eed773ed --- /dev/null +++ b/static/freebsd/man4/snd_solo.4 @@ -0,0 +1,59 @@ +.\" Copyright (c) 2004 Atte Peltomaki +.\" 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 November 28, 2005 +.Dt SND_SOLO 4 +.Os +.Sh NAME +.Nm snd_solo +.Nd "ESS Solo-1/1E PCI bridge device driver" +.Sh SYNOPSIS +.Cd "device sound" +.Cd "device snd_solo" +.Sh DESCRIPTION +The +.Nm +bridge driver allows the generic audio driver +.Xr sound 4 +to attach to the ESS Solo-1x PCI cards. +.Sh HARDWARE +The +.Nm +driver supports the following sound cards: +.Pp +.Bl -bullet -compact +.It +ESS Solo-1 (ES1938 Chipset) +.It +ESS Solo-1E (ES1946 Chipset) +.El +.Sh SEE ALSO +.Xr sound 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 4.1 . +.Sh AUTHORS +.An Cameron Grant Aq Mt cg@FreeBSD.org diff --git a/static/freebsd/man4/snd_spicds.4 b/static/freebsd/man4/snd_spicds.4 new file mode 100644 index 00000000..15abc8f5 --- /dev/null +++ b/static/freebsd/man4/snd_spicds.4 @@ -0,0 +1,87 @@ +.\" Copyright (c) 2006 Alexander Leidinger +.\" 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 May 28, 2007 +.Dt SND_SPICDS 4 +.Os +.Sh NAME +.Nm snd_spicds +.Nd "I2S SPI audio codec driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device snd_spicds" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the +following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +snd_spicds_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +I2S codec driver is used by several sound drivers for soundcards which use +the supported codec chips. +.Sh HARDWARE +The +.Nm +driver supports the following codecs: +.Pp +.Bl -bullet -compact +.It +AK4358 +.It +AK4381 +.It +AK4396 +.It +AK4524 +.It +AK4528 +.It +WM8770 +.El +.Sh SEE ALSO +.Xr snd_envy24 4 , +.Xr snd_envy24ht 4 , +.Xr sound 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 6.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Konstantin Dimitrov +based upon the +.Xr snd_envy24 4 +driver. +This manual page was written by +.An Alexander Leidinger Aq Mt netchild@FreeBSD.org . diff --git a/static/freebsd/man4/snd_t4dwave.4 b/static/freebsd/man4/snd_t4dwave.4 new file mode 100644 index 00000000..ccf9dc02 --- /dev/null +++ b/static/freebsd/man4/snd_t4dwave.4 @@ -0,0 +1,75 @@ +.\" Copyright (c) 2005 Joel Dahl +.\" 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 December 1, 2005 +.Dt SND_T4DWAVE 4 +.Os +.Sh NAME +.Nm snd_t4dwave +.Nd "Trident 4DWave bridge device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device sound" +.Cd "device snd_t4dwave" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the +following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +snd_t4dwave_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +bridge driver allows the generic audio driver, +.Xr sound 4 , +to attach to Trident 4DWave audio devices. +.Sh HARDWARE +The +.Nm +driver supports the following audio devices: +.Pp +.Bl -bullet -compact +.It +Acer Labs M5451 +.It +SIS 7018 +.It +Trident 4DWave DX +.It +Trident 4DWave NX +.El +.Sh SEE ALSO +.Xr sound 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 4.0 . +.Sh AUTHORS +This manual page was written by +.An Joel Dahl Aq Mt joel@FreeBSD.org . diff --git a/static/freebsd/man4/snd_uaudio.4 b/static/freebsd/man4/snd_uaudio.4 new file mode 100644 index 00000000..7193c85f --- /dev/null +++ b/static/freebsd/man4/snd_uaudio.4 @@ -0,0 +1,170 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" $NetBSD: uaudio.4,v 1.15 2002/02/12 19:53:57 jdolecek Exp $ +.\" +.\" Copyright (c) 1999 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Lennart Augustsson. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 17, 2025 +.Dt SND_UAUDIO 4 +.Os +.Sh NAME +.Nm snd_uaudio +.Nd USB audio and MIDI device driver +.Sh SYNOPSIS +.Cd "device sound" +.Cd "device usb" +.Cd "device snd_uaudio" +.Pp +In +.Xr rc.conf 5 : +.Cd kld_list="snd_uaudio" +.Pp +In +.Xr sysctl.conf 5 : +.Cd hw.usb.uaudio.buffer_ms +.Cd hw.usb.uaudio.default_bits +.Cd hw.usb.uaudio.default_channels +.Cd hw.usb.uaudio.default_rate +.Cd hw.usb.uaudio.handle_hid +.Cd hw.usb.uaudio.debug +.Sh DESCRIPTION +A USB audio device consists of a number of components: input terminals (e.g.\& +USB digital input), output terminals (e.g.\& speakers), and a number of units +in between (e.g.\& volume control). +.Pp +If the device supports multiple configurations, and there have been no +user-supplied values specified through the +.Xr sysctl 8 +interface, the driver will select the best matching configuration supported by +the device during attach. +"Best" means the configuration with the most channels and highest quality in +sample rate and sample size. +.Pp +Refer to the +.Ql USB Audio Class Specification +for more information. +.Sh HARDWARE +The +.Nm +driver provides support for USB audio class devices and +USB MIDI class devices. +.Sh SYSCTL VARIABLES +The following settings can be entered at the +.Xr loader 8 +prompt or in +.Xr loader.conf 5 +and can also be changed at runtime with the +.Xr sysctl 8 +command. +For a change to take effect during runtime, the device has to be re-attached. +.Bl -tag -width indent +.It Va hw.usb.uaudio.buffer_ms +Period of audio data processed at once, in milliseconds, from 1 to 8 (default +is 4). +Lower values mean less latency, but this can result in audible gaps due to +frequent CPU wakeups. +.It Va hw.usb.uaudio.default_bits +Preferred sample size in bits, from 0 to 32 (default is 0). +A value of 0 sets the sample size to the maximum supported sample size. +.Pp +Set this to select a smaller sample size if the device supports multiple sample +sizes. +.It Va hw.usb.uaudio.default_channels +Preferred number of sample channels, from 0 to 64 (default is 0). +USB 1.1 devices are limited to 4 channels due to bandwidth constraints, unless +a higher value is explicitly requested. +A value of 0 sets the sample channels to the maximum supported channel number. +.Pp +Set this to select a smaller channel number if the device supports multiple +channel configurations. +.It Va hw.usb.uaudio.default_rate +Preferred sample rate in Hz (default is 0). +If set to 0, the device's highest supported sample rate will be used. +.Pp +Note that if VCHANs are enabled, the sample rate will be overridden by +.Pa dev.pcm.%d.[play|rec].vchanrate +(see +.Xr sound 4 ) , +which can also be used to adjust the sample rate during runtime. +.Pp +If +.Pa hw.usb.uaudio.default_rate +is non-zero, +.Pa dev.pcm.%d.[play|rec].vchanrate +will use it as its maximum allowed value. +.It Va hw.usb.uaudio.handle_hid +Let +.Nm +handle HID volume keys, if any (default is 1). +.Bl -tag -width 2n +.It 0 +Disabled. +.It 1 +Enabled. +.El +.El +.Pp +If +.Xr usb 4 +has been compiled with +.Va USB_DEBUG +on, the following setting is also available: +.Bl -tag -width indent +.It Va hw.usb.uaudio.debug +Debug output level (default is 0). +.El +.Sh SEE ALSO +.Xr sound 4 , +.Xr usb 4 , +.Xr loader.conf 5 , +.Xr loader 8 , +.Xr sysctl 8 +.Rs +.%T "USB Audio Class Specifications" +.%U http://www.usb.org/developers/docs/devclass_docs/ +.Re +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 4.7 . +.Sh AUTHORS +This manual page was adopted from +.Nx 1.6 +and modified for +.Fx +by +.An Hiten Pandya Aq Mt hmp@FreeBSD.org . +.Sh BUGS +The PCM framework in +.Fx +currently does not support the full set of USB audio mixer controls. +Some mixer controls are only available as +.Va dev.pcm.%d.mixer +sysctls. diff --git a/static/freebsd/man4/snd_via8233.4 b/static/freebsd/man4/snd_via8233.4 new file mode 100644 index 00000000..5495854a --- /dev/null +++ b/static/freebsd/man4/snd_via8233.4 @@ -0,0 +1,103 @@ +.\" Copyright (c) 2005 Joel Dahl +.\" 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 November 29, 2006 +.Dt SND_VIA8233 4 +.Os +.Sh NAME +.Nm snd_via8233 +.Nd "VIA Technologies VT8233 bridge device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device sound" +.Cd "device snd_via8233" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the +following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +snd_via8233_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +bridge driver allows the generic audio driver, +.Xr sound 4 , +to attach to the VIA VT8233 audio devices. +These audio chipsets are integrated in the southbridge on many VIA based +motherboards. +.Ss Runtime Configuration +The following +.Xr sysctl 8 +variables are available in addition to those available to all +.Xr sound 4 +devices: +.Bl -tag -width ".Va dev.pcm.%d.polling" -offset indent +.It Va dev.pcm.%d.polling +Experimental polling mode, where the driver operates by querying the device +state on each tick using +.Xr callout 9 . +Polling is disabled by default. +Do not enable it unless you are facing weird interrupt problems or if the +device cannot generate interrupts at all. +.El +.Sh HARDWARE +The +.Nm +driver supports the following audio chipsets: +.Pp +.Bl -bullet -compact +.It +VIA VT8233 +.It +VIA VT8233A +.It +VIA VT8233C +.It +VIA VT8235 +.It +VIA VT8237 +.It +VIA VT8251 +.El +.Sh SEE ALSO +.Xr sound 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 4.7 . +.Sh AUTHORS +This manual page was written by +.An Joel Dahl Aq Mt joel@FreeBSD.org . +.Sh BUGS +The +.Nm +driver +does not support S/PDIF. +There is partial support in the code, so implementing it should be fairly +easy if the right hardware is available. diff --git a/static/freebsd/man4/snd_via82c686.4 b/static/freebsd/man4/snd_via82c686.4 new file mode 100644 index 00000000..4aa79121 --- /dev/null +++ b/static/freebsd/man4/snd_via82c686.4 @@ -0,0 +1,69 @@ +.\" Copyright (c) 2005 Joel Dahl +.\" 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 December 1, 2005 +.Dt SND_VIA82C686 4 +.Os +.Sh NAME +.Nm snd_via82c686 +.Nd "VIA Technologies 82C686A bridge device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device sound" +.Cd "device snd_via82c686" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the +following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +snd_via82c686_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +bridge driver allows the generic audio driver, +.Xr sound 4 , +to attach audio devices based on the VIA 82C686A chipset. +.Sh HARDWARE +The +.Nm +driver supports audio devices based on the following chipset: +.Pp +.Bl -bullet -compact +.It +VIA 82C686A +.El +.Sh SEE ALSO +.Xr sound 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 4.2 . +.Sh AUTHORS +This manual page was written by +.An Joel Dahl Aq Mt joel@FreeBSD.org . diff --git a/static/freebsd/man4/snd_vibes.4 b/static/freebsd/man4/snd_vibes.4 new file mode 100644 index 00000000..df6e3b75 --- /dev/null +++ b/static/freebsd/man4/snd_vibes.4 @@ -0,0 +1,69 @@ +.\" Copyright (c) 2005 Joel Dahl +.\" 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 December 1, 2005 +.Dt SND_VIBES 4 +.Os +.Sh NAME +.Nm snd_vibes +.Nd "S3 SonicVibes bridge device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device sound" +.Cd "device snd_vibes" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the +following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +snd_vibes_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +bridge driver allows the generic audio driver, +.Xr sound 4 , +to attach audio devices based on the S3 SonicVibes chipset. +.Sh HARDWARE +The +.Nm +driver supports audio devices based on the following chipset: +.Pp +.Bl -bullet -compact +.It +S3 SonicVibes +.El +.Sh SEE ALSO +.Xr sound 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 4.4 . +.Sh AUTHORS +This manual page was written by +.An Joel Dahl Aq Mt joel@FreeBSD.org . diff --git a/static/freebsd/man4/sndstat.4 b/static/freebsd/man4/sndstat.4 new file mode 100644 index 00000000..5927e03a --- /dev/null +++ b/static/freebsd/man4/sndstat.4 @@ -0,0 +1,400 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" This software was developed by Ka Ho Ng +.\" under sponsorship from the FreeBSD Foundation. +.\" +.\" Copyright (c) 2020 The FreeBSD Foundation +.\" +.\" 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. +.\" +.\" Note: The date here should be updated whenever a non-trivial +.\" change is made to the manual page. +.Dd July 26, 2024 +.Dt SNDSTAT 4 +.Os +.Sh NAME +.Nm sndstat +.Nd "nvlist-based PCM audio device enumeration interface" +.Sh SYNOPSIS +To compile the driver into the kernel, +place the following lines in the +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device sound" +.Ed +.Sh DESCRIPTION +The ioctl interface provided by +.Pa /dev/sndstat +device allows callers to enumerate PCM audio devices available for use. +In other words, it provides means to get the list of all audio devices +available to the system. +.Sh IOCTLS +For ioctl calls that take an argument, the following structure is used: +.Bd -literal -offset indent +struct sndstioc_nv_arg { + size_t nbytes; + void *buf; +}; +.Ed +.Pp +Here is an example of an nvlist object with explanations of the common fields: +.Bd -literal -offset indent +dsps (NVLIST ARRAY): 1 + from_user (BOOL): FALSE + nameunit (STRING): [pcm0] + devnode (STRING): [dsp0] + desc (STRING): [Generic (0x8086) (Analog Line-out)] + pchan (NUMBER): 1 + rchan (NUMBER): 0 + info_play (NVLIST): + min_rate (NUMBER): 48000 + max_rate (NUMBER): 48000 + formats (NUMBER): 16 + min_chn (NUMBER): 2 + max_chn (NUMBER): 2 + provider_info (NVLIST): + unit (NUMBER): 0 + status (STRING): on hdaa0 + bitperfect (BOOL): FALSE + pvchan (BOOL): TRUE + pvchanrate (NUMBER): 48000 + pvchanformat (NUMBER): 0x00000010 + rvchan (BOOL): TRUE + rvchanrate (NUMBER): 48000 + rvchanformat (NUMBER): 0x00000010 + channel_info (NVLIST_ARRAY): 1 + name (STRING): dsp0.virtual_play.0 + parentchan (STRING): dsp0.play.0 + unit (NUMBER): 1 + caps (NUMBER): 0x073200 + latency (NUMBER): 2 + rate (NUMBER): 48000 + format (NUMBER): 0x201000 + pid (NUMBER): 1234 + comm (STRING): mpv + interrupts (NUMBER): 0 + feedcount (NUMBER): 0 + xruns (NUMBER): 0 + left_volume (NUMBER): 45 + right_volume (NUMBER): 45 + hwbuf_fmt (NUMBER): 0x200010 + hwbuf_rate (NUMBER): 48000 + hwbuf_size (NUMBER): 0 + hwbuf_blksz (NUMBER): 0 + hwbuf_blkcnt (NUMBER): 0 + hwbuf_free (NUMBER): 0 + hwbuf_ready (NUMBER): 0 + swbuf_fmt (NUMBER): 0x201000 + swbuf_rate (NUMBER): 48000 + swbuf_size (NUMBER): 16384 + swbuf_blksz (NUMBER): 2048 + swbuf_blkcnt (NUMBER): 8 + swbuf_free (NUMBER): 16384 + swbuf_ready (NUMBER): 0 + feederchain (STRING): + [userland -> + feeder_root(0x00201000) -> + feeder_format(0x00201000 -> 0x00200010) -> + feeder_volume(0x00200010) -> hardware] + provider (STRING): [sound(4)] +.Ed +.Bl -tag -width ".Dv provider_info" +.It Dv from_user +Whether the PCM audio device node is created by in-kernel audio subsystem or +userspace providers. +.It Dv nameunit +The device identification in the form of subsystem plus a unit number. +.It Dv devnode +The PCM audio device node relative path in devfs. +.It Dv desc +The description of the PCM audio device. +.It Dv pchan +The number of playback channels supported by hardware. +This can be 0 if this PCM audio device does not support playback at all. +.It Dv rchan +The number of recording channels supported by hardware. +This can be 0 if this PCM audio device does not support recording at all. +.It Dv info_play +Supported configurations in playback direction. +This exists only if this PCM audio device supports playback. +There are a number of name/value pairs inside this field: +.Bl -tag -width ".Dv min_rate" +.It Dv min_rate +Minimum supported sampling rate. +.It Dv max_rate +Maximum supported sampling rate. +.It Dv formats +Supported sample formats. +.It Dv min_chn +Minimum supported number of channels in channel layout +.It Dv max_chn +Maximum supported number of channels in channel layout +.El +.It Dv info_rec +Supported configurations in recording direction. +This exists only if this PCM audio device supports recording. +There are a number of name/value pairs inside this field: +.Bl -tag -width ".Dv min_rate" +.It Dv min_rate +Minimum supported sampling rate. +.It Dv max_rate +Maximum supported sampling rate. +.It Dv formats +Supported sample formats. +.It Dv min_chn +Minimum supported number of channels in channel layout +.It Dv max_chn +Maximum supported number of channels in channel layout +.El +.It Dv provider_info +Provider-specific fields. +This field may not exist if the PCM audio device is not provided by in-kernel +interface. +This field will not exist if the provider field is an empty string. +For the +.Xr sound 4 +provider, there are a number of name/value pairs inside this field: +.Bl -tag -width ".Dv channel_info" +.It Dv unit +Sound card unit. +.It Dv status +Status string. +Usually reports the driver the device is attached on. +.It Dv bitperfect +Whether the sound card has bit-perfect mode enabled. +.It Dv pvchan +Playback virtual channels enabled. +.It Dv pvchanrate +Playback virtual channel sample rate. +.It Dv pvchanformat +Playback virtual channel format. +.It Dv rvchan +Recording virtual channels enabled. +.It Dv rvchanrate +Recording virtual channel sample rate. +.It Dv rvchanformat +Recording virtual channel format. +.It Dv channel_info +Channel information. +There are a number of name/value pairs inside this field: +.Bl -tag -width ".Dv hwbuf_blkcnt" +.It Dv name +Channel name. +.It Dv parentchan +Parent channel name (e.g., in the case of virtual channels). +.It Dv unit +Channel unit. +.It Dv caps +OSS capabilities. +.It Dv latency +Latency. +.It Dv rate +Sampling rate. +.It Dv format +Sampling format. +.It Dv pid +PID of the process consuming the channel. +.It Dv comm +Name of the process consuming the channel. +.It Dv interrupts +Number of interrupts since the channel has been opened. +.It Dv xruns +Number of overruns/underruns, depending on channel direction. +.It Dv feedcount +Number of read/written bytes since the channel has been opened. +.It Dv left_volume +Left volume. +.It Dv right_volume +Right volume. +.It Dv hwbuf_format +Hardware buffer format. +.It Dv hwbuf_rate +Hardware buffer sample rate; +.It Dv hwbuf_size +Hardware buffer size. +.It Dv hwbuf_blksz +Hardware buffer block size. +.It Dv hwbuf_blkcnt +Hardware buffer block count. +.It Dv hwbuf_free +Free space in hardware buffer (in bytes). +.It Dv hwbuf_ready +Number of bytes ready to be read/written from hardware buffer. +.It Dv swbuf_format +Software buffer format. +.It Dv swbuf_rate +Software buffer sample rate; +.It Dv swbuf_size +Software buffer size. +.It Dv swbuf_blksz +Software buffer block size. +.It Dv swbuf_blkcnt +Software buffer block count. +.It Dv swbuf_free +Free space in software buffer (in bytes). +.It Dv swbuf_ready +Number of bytes ready to be read/written from software buffer. +.It Dv feederchain +Channel feeder chain. +.El +.El +.It Dv provider +A string specifying the provider of the PCm audio device. +.El +.Pp +The following ioctls are provided for use: +.Bl -tag -width ".Dv SNDSTIOC_FLUSH_USER_DEVS" +.It Dv SNDSTIOC_REFRESH_DEVS +Drop any previously fetched PCM audio devices list snapshots. +This ioctl takes no arguments. +.It Dv SNDSTIOC_GET_DEVS +Generate and/or return PCM audio devices list snapshots to callers. +This ioctl takes a pointer to +.Fa struct sndstioc_nv_arg +as the first and the only argument. +Callers need to provide a sufficiently large buffer to hold a serialized +nvlist. +If there is no existing PCM audio device list snapshot available in the +internal structure of the opened sndstat. +.Fa fd , +a new PCM audio device list snapshot will be automatically generated. +Callers have to set +.Fa nbytes +to either 0 or the size of buffer provided. +In case +.Fa nbytes +is 0, the buffer size required to hold a serialized nvlist +stream of current snapshot will be returned in +.Fa nbytes , +and +.Fa buf +will be ignored. +Otherwise, if the buffer is not sufficiently large, +the ioctl returns success, and +.Fa nbytes +will be set to 0. +If the buffer provided is sufficiently large, +.Fa nbytes +will be set to the size of the serialized nvlist written to the provided buffer. +Once a PCM audio device list snapshot is returned to user-space successfully, +the snapshot stored in the subsystem's internal structure of the given +.Fa fd +will be freed. +.It Dv SNDSTIOC_ADD_USER_DEVS +Add a list of PCM audio devices provided by callers to +.Pa /dev/sndstat +device. +This ioctl takes a pointer to +.Fa struct sndstioc_nv_arg +as the first and the only argument. +Callers have to provide a buffer holding a serialized nvlist. +.Fa nbytes +should be set to the length in bytes of the serialized nvlist. +.Fa buf +should be pointed to a buffer storing the serialized nvlist. +Userspace-backed PCM audio device nodes should be listed inside the serialized +nvlist. +.It Dv SNDSTIOC_FLUSH_USER_DEVS +Flush any PCM audio devices previously added by callers. +This ioctl takes no arguments. +.El +.Sh FILES +.Bl -tag -width ".Pa /dev/sndstat" -compact +.It Pa /dev/sndstat +.El +.Sh EXAMPLES +The following code enumerates all available PCM audio devices: +.Bd -literal -offset indent +#include +#include +#include +#include +#include +#include +#include +#include +#include + +int +main() +{ + int fd; + struct sndstioc_nv_arg arg; + const nvlist_t * const *di; + size_t i, nitems; + nvlist_t *nvl; + + /* Open sndstat node in read-only first */ + fd = open("/dev/sndstat", O_RDONLY); + + if (ioctl(fd, SNDSTIOC_REFRESH_DEVS, NULL)) + err(1, "ioctl(fd, SNDSTIOC_REFRESH_DEVS, NULL)"); + + /* Get the size of snapshot, when nbytes = 0 */ + arg.nbytes = 0; + arg.buf = NULL; + if (ioctl(fd, SNDSTIOC_GET_DEVS, &arg)) + err(1, "ioctl(fd, SNDSTIOC_GET_DEVS, &arg)"); + + /* Get snapshot data */ + arg.buf = malloc(arg.nbytes); + if (arg.buf == NULL) + err(EX_OSERR, "malloc"); + if (ioctl(fd, SNDSTIOC_GET_DEVS, &arg)) + err(1, "ioctl(fd, SNDSTIOC_GET_DEVS, &arg)"); + + /* Deserialize the nvlist stream */ + nvl = nvlist_unpack(arg.buf, arg.nbytes, 0); + free(arg.buf); + + /* Get DSPs array */ + di = nvlist_get_nvlist_array(nvl, SNDST_DSPS, &nitems); + for (i = 0; i < nitems; i++) { + const char *nameunit, *devnode, *desc; + + /* + * Examine each device nvlist item + */ + + nameunit = nvlist_get_string(di[i], SNDST_DSPS_NAMEUNIT); + devnode = nvlist_get_string(di[i], SNDST_DSPS_DEVNODE); + desc = nvlist_get_string(di[i], SNDST_DSPS_DESC); + printf("Name unit: `%s`, Device node: `%s`, Description: `%s`\n", + nameunit, devnode, desc); + } + + nvlist_destroy(nvl); + return (0); +} +.Ed +.Sh SEE ALSO +.Xr sound 4 , +.Xr nv 9 +.Sh HISTORY +The nvlist-based ioctls support for +.Nm +device first appeared in +.Fx 13.0 . +.Sh AUTHORS +This manual page was written by +.An Ka Ho Ng Aq Mt khng@FreeBSD.org . diff --git a/static/freebsd/man4/snp.4 b/static/freebsd/man4/snp.4 new file mode 100644 index 00000000..3a42b933 --- /dev/null +++ b/static/freebsd/man4/snp.4 @@ -0,0 +1,87 @@ +.\" +.Dd September 24, 2022 +.Dt SNP 4 +.Os +.Sh NAME +.Nm snp +.Nd tty snoop interface +.Sh SYNOPSIS +.In sys/snoop.h +.Ft int +.Fn ioctl fd SNPSTTY &dev +.Ft int +.Fn ioctl fd SNPGTTY &dev +.Ft int +.Fn ioctl fd FIONREAD &result +.Sh DESCRIPTION +.Pa /dev/snp +is a snoop device which allows users to attach to any tty +and watch activities on it. +The kernel must be compiled with +.Cd "device snp" , +or the +.Nm +module must be loaded, +for these devices to be available. +.Pp +To associate a given +.Nm +device with a tty to be observed, open the +.Nm +device and a tty device, and then issue the +.Dv SNPSTTY +ioctl on +.Nm +device. +The argument passed to the +.Xr ioctl 2 +is the address of a variable of type +.Vt int , +holding the file descriptor of a tty device. +To detach the +.Nm +device from a tty use a pointer to a value of +\-1. +.Pp +The +.Dv SNPGTTY +ioctl returns information about the current tty attached to +the open +.Nm +device. +.Pp +The +.Dv FIONREAD +ioctl returns a positive value equal to the number of characters +in a read buffer. +Special values defined are: +.Bl -tag -width ".Dv SNP_TTYCLOSE" +.It Dv SNP_TTYCLOSE +tty not attached. +.It Dv SNP_DETACH +.Nm +device has been detached by user or tty device has been closed +and detached. +.El +.Sh SEE ALSO +.Xr pty 4 , +.Xr kldload 8 , +.Xr watch 8 +.Sh HISTORY +The +.Nm +device first appeared in +.Fx 2.1 . +In +.Fx 8.0 +the +.Nm +driver was rewritten to work with the replaced TTY subsystem. +.Sh AUTHORS +.An -nosplit +The author of the current implementation is +.An \&Ed Schouten Aq Mt ed@FreeBSD.org . +Previous versions of +.Nm +were based on code written by +.An Ugen J.S. Antsilevich Aq Mt ugen@NetVision.net.il . diff --git a/static/freebsd/man4/spigen.4 b/static/freebsd/man4/spigen.4 new file mode 100644 index 00000000..5ca5ef6b --- /dev/null +++ b/static/freebsd/man4/spigen.4 @@ -0,0 +1,205 @@ +.\" +.\" Copyright (c) 2018 Ian Lepore +.\" 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 ``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 August 21, 2020 +.Dt SPIGEN 4 +.Os +.Sh NAME +.Nm spigen +.Nd SPI generic I/O device driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device spi" +.Cd "device spibus" +.Cd "device spigen" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +spigen_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides direct access to a slave device on the SPI bus. +Each instance of a +.Nm +device is associated with a single chip-select +line on the bus, and all I/O performed through that instance is done +with that chip-select line asserted. +.Pp +SPI data transfers are inherently bi-directional; there are no separate +read and write operations. +When commands and data are sent to a device, data also comes back from +the device, although in some cases the data may not be useful (or even +documented or predictable for some devices). +Likewise on a read operation, whatever data is in the buffer at the start +of the operation is sent to (and typically ignored by) the device, with each +outgoing byte then replaced in the buffer by the corresponding incoming byte. +Thus, all buffers passed to the transfer functions are both input and +output buffers. +.Pp +The +.Nm +driver provides access to the SPI slave device with the following +.Xr ioctl 2 +calls, defined in +.In sys/spigenio.h : +.Bl -tag -width indent +.It Dv SPIGENIOC_TRANSFER Pq Vt "struct spigen_transfer" +Transfer a command and optional associated data to/from the device, +using the buffers described by the st_command and st_data fields in the +.Vt spigen_transfer . +Set +.Vt st_data.iov_len +to zero if there is no data associated with the command. +.Bd -literal +struct spigen_transfer { + struct iovec st_command; + struct iovec st_data; +}; +.Ed +.It Dv SPIGENIOC_TRANSFER_MMAPPED Pq Vt "spigen_transfer_mmapped" +Transfer a command and optional associated data to/from the device. +The buffers for the transfer are a previously-mmap'd region. +The length of the command and data within that region are described by the +.Vt stm_command_length +and +.Vt stm_data_length +fields of +.Vt spigen_transfer_mmapped . +If +.Vt stm_data_length +is non-zero, the data appears in the memory region immediately +following the command (that is, at offset +.Vt stm_command_length +from the start of the mapped region). +.Bd -literal +struct spigen_transfer_mmapped { + size_t stm_command_length; + size_t stm_data_length; +}; +.Ed +.It Dv SPIGENIOC_GET_CLOCK_SPEED Pq Vt uint32_t +Get the maximum clock speed (bus frequency in Hertz) to be used +when communicating with this slave device. +.It Dv SPIGENIOC_SET_CLOCK_SPEED Pq Vt uint32_t +Set the maximum clock speed (bus frequency in Hertz) to be used +when communicating with this slave device. +The setting remains in effect for subsequent transfers; it +is not necessary to reset this before each transfer. +The actual bus frequency may be lower due to hardware limitations +of the SPI bus controller device. +.It Dv SPIGENIOC_GET_SPI_MODE Pq Vt uint32_t +Get the SPI mode (clock polarity and phase) to be used +when communicating with this device. +.It Dv SPIGENIOC_SET_SPI_MODE Pq Vt uint32_t +Set the SPI mode (clock polarity and phase) to be used +when communicating with this device. +The setting remains in effect for subsequent transfers; it +is not necessary to reset this before each transfer. +.El +.Sh HINTS CONFIGURATION +On a +.Xr device.hints 5 +based system, such as +.Li MIPS , +these values are configurable for +.Nm : +.Bl -tag -width indent +.It Va hint.spigen.%d.at +The spibus the +.Nm +instance is attached to. +.It Va hint.spigen.%d.clock +The maximum bus frequency to use when communicating with this device. +Actual bus speed may be lower, depending on the capabilities of the SPI +bus controller hardware. +.It Va hint.spigen.%d.cs +The chip-select number to assert when performing I/O for this device. +Set the high bit (1 << 31) to invert the logic level of the chip select line. +.It Va hint.spigen.%d.mode +The SPI mode (0-3) to use when communicating with this device. +.El +.Sh FDT CONFIGURATION +On an +.Xr fdt 4 +based system, the spigen device is defined as a slave device subnode +of the SPI bus controller node. +All properties documented in the +.Va spibus.txt +bindings document can be used with the +.Nm +device. +The most commonly-used ones are documented below. +.Pp +The following properties are required in the +.Nm +device subnode: +.Bl -tag -width indent +.It Va compatible +Must be the string "freebsd,spigen". +.It Va reg +Chip select address of device. +.It Va spi-max-frequency +The maximum bus frequency to use when communicating with this slave device. +Actual bus speed may be lower, depending on the capabilities of the SPI +bus controller hardware. +.El +.Pp +The following properties are optional for the +.Nm +device subnode: +.Bl -tag -width indent +.It Va spi-cpha +Empty property indicating the slave device requires shifted clock +phase (CPHA) mode. +.It Va spi-cpol +Empty property indicating the slave device requires inverse clock +polarity (CPOL) mode. +.It Va spi-cs-high +Empty property indicating the slave device requires chip select active high. +.El +.Sh FILES +.Bl -tag -width -compact +.It Pa /dev/spigen* +.El +.Sh SEE ALSO +.Xr fdt 4 , +.Xr device.hints 5 , +.Xr spi 8 +.Sh HISTORY +The +.Nm +driver +appeared in +.Fx 11.0 . +FDT support appeared in +.Fx 11.2 . diff --git a/static/freebsd/man4/spkr.4 b/static/freebsd/man4/spkr.4 new file mode 100644 index 00000000..64dfee27 --- /dev/null +++ b/static/freebsd/man4/spkr.4 @@ -0,0 +1,247 @@ +.\" +.Dd November 10, 2005 +.Dt SPKR 4 +.Os +.Sh NAME +.Nm speaker , +.Nm spkr +.Nd console speaker device driver +.Sh SYNOPSIS +.Cd device speaker +.In dev/speaker/speaker.h +.Sh DESCRIPTION +The speaker device driver allows applications to control the PC console +speaker on an +.Tn IBM-PC Ns --compatible +machine running +.Fx . +.Pp +Only one process may have this device open at any given time; +.Xr open 2 +and +.Xr close 2 +are used to lock and relinquish it. +An attempt to open when +another process has the device locked will return -1 with an +.Er EBUSY +error +indication. +Writes to the device are interpreted as `play strings' in a +simple ASCII melody notation. +An +.Xr ioctl 2 +request +for tone generation at arbitrary +frequencies is also supported. +.Pp +Sound-generation does not monopolize the processor; in fact, the driver +spends most of its time sleeping while the PC hardware is emitting +tones. +Other processes may emit beeps while the driver is running. +.Pp +Applications may call +.Xr ioctl 2 +on a speaker file descriptor to control the +speaker driver directly; definitions for the +.Xr ioctl 2 +interface are in +.In dev/speaker/speaker.h . +The +.Li tone_t +structure used in these calls has two fields, +specifying a frequency (in Hz) and a duration (in 1/100ths of a second). +A frequency of zero is interpreted as a rest. +.Pp +At present there are two such +.Xr ioctl 2 +calls. +.Dv SPKRTONE +accepts a pointer to a +single tone structure as third argument and plays it. +.Dv SPKRTUNE +accepts a +pointer to the first of an array of tone structures and plays them in +continuous sequence; this array must be terminated by a final member with +a zero duration. +.Pp +The play-string language is modeled on the PLAY statement conventions of +.Tn IBM +Advanced BASIC 2.0. +The +.Li MB , +.Li MF , +and +.Li X +primitives of PLAY are not +useful in a timesharing environment and are omitted. +The `octave-tracking' +feature and the slur mark are new. +.Pp +There are 84 accessible notes numbered 1-84 in 7 octaves, each running from +C to B, numbered 0-6; the scale is equal-tempered A440 and octave 3 starts +with middle C. +By default, the play function emits half-second notes with the +last 1/16th second being `rest time'. +.Pp +Play strings are interpreted left to right as a series of play command groups; +letter case is ignored. +Play command groups are as follows: +.Bl -tag -width CDEFGABxx +.It Li CDEFGAB +Letters A through G cause the corresponding note to be played in the +current octave. +A note letter may optionally be followed by an +.Dq Em "accidental sign" , +one of # + or -; the first two of these cause it to be sharped one +half-tone, the last causes it to be flatted one half-tone. +It may +also be followed by a time value number and by sustain dots (see +below). +Time values are interpreted as for the L command below. +.It Ns Li O Sy n +If +.Sy n +is numeric, this sets the current octave. +.Sy n +may also be one of +.Li L +or +.Li N +to enable or disable octave-tracking (it is disabled by default). +When octave-tracking is on, interpretation of a pair of letter notes +will change octaves if necessary in order to make the smallest +possible jump between notes. +Thus ``olbc'' will be played as +``olb>c'', and ``olcb'' as ``olc, < and O[0123456]. +(The octave-locking +feature is not supported in +.Tn IBM +BASIC.) +.It Li > +Bump the current octave up one. +.It Li < +Drop the current octave down one. +.It Ns Li N Sy n +Play note +.Sy n , +.Sy n +being 1 to 84 or 0 for a rest of current time value. +May be followed by sustain dots. +.It Ns Li L Sy n +Sets the current time value for notes. +The default is +.Li L4 , +quarter or crotchet notes. +The lowest possible value is 1; values up +to 64 are accepted. +.Li L1 +sets whole notes, +.Li L2 +sets half notes, +.Li L4 +sets quarter notes, etc. +.It Ns Li P Sy n +Pause (rest), with +.Sy n +interpreted as for +.Li L Sy n . +May be followed by +sustain dots. +May also be written +.Li ~ . +.It Ns Li T Sy n +Sets the number of quarter notes per minute; default is 120. +Musical +names for common tempi are: +.Bd -literal -offset indent + Tempo Beats Per Minute +very slow Larghissimo + Largo 40-60 + Larghetto 60-66 + Grave + Lento + Adagio 66-76 +slow Adagietto + Andante 76-108 +medium Andantino + Moderato 108-120 +fast Allegretto + Allegro 120-168 + Vivace + Veloce + Presto 168-208 +very fast Prestissimo +.Ed +.It Li M[LNS] +Set articulation. +.Li MN +.Li ( N +for normal) is the default; the last 1/8th of +the note's value is rest time. +You can set +.Li ML +for legato (no rest space) or +.Li MS +for staccato (1/4 rest space). +.El +.Pp +Notes (that is, +.Li CDEFGAB +or +.Li N +command character groups) may be followed by +sustain dots. +Each dot causes the note's value to be lengthened by one-half +for each one. +Thus, a note dotted once is held for 3/2 of its undotted value; +dotted twice, it is held 9/4, and three times would give 27/8. +.Pp +A note and its sustain dots may also be followed by a slur mark (underscore). +This causes the normal micro-rest after the note to be filled in, slurring it +to the next one. +(The slur feature is not supported in +.Tn IBM +BASIC.) +.Pp +Whitespace in play strings is simply skipped and may be used to separate +melody sections. +.Sh FILES +.Bl -tag -width /dev/speakerxx +.It Pa /dev/speaker +speaker device file +.El +.Sh SEE ALSO +.Xr spkrtest 8 +.Sh HISTORY +The +.Nm +device appeared in +.Fx 1.0 . +.Sh AUTHORS +.An Eric S. Raymond Aq Mt esr@snark.thyrsus.com , +June 1990 +.Sh PORTED BY +.An Andrew A. Chernov Aq Mt ache@astral.msk.su +.Sh BUGS +Due to roundoff in the pitch tables and slop in the tone-generation and timer +hardware (neither of which was designed for precision), neither pitch accuracy +nor timings will be mathematically exact. +There is no volume control. +.Pp +The action of two or more sustain dots does not reflect standard musical +notation, in which each dot adds half the value of the previous dot +modifier, not half the value of the note as modified. +Thus, a note dotted +once is held for 3/2 of its undotted value; dotted twice, it is held 7/4, +and three times would give 15/8. +The multiply-by-3/2 interpretation, +however, is specified in the +.Tn IBM +BASIC manual and has been retained for +compatibility. +.Pp +In play strings which are very long (longer than your system's physical I/O +blocks) note suffixes or numbers may occasionally be parsed incorrectly due +to crossing a block boundary. diff --git a/static/freebsd/man4/splash.4 b/static/freebsd/man4/splash.4 new file mode 100644 index 00000000..0985385f --- /dev/null +++ b/static/freebsd/man4/splash.4 @@ -0,0 +1,329 @@ +.\" +.\" Copyright (c) 1999 +.\" Kazutaka YOKOTA +.\" 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 as +.\" the first lines of this file unmodified. +.\" 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 ``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 03, 2026 +.Dt SPLASH 4 +.Os +.Sh NAME +.Nm splash +.Nd splash screen / screen saver interface +.Sh SYNOPSIS +.Cd device splash +.Sh DESCRIPTION +The +.Nm +pseudo device driver adds support for the splash screen and screen +savers to the kernel. +This driver is required if the splash bitmap image is to be loaded or +any screen saver is to be used. +.Ss Splash screen +You can load and display an arbitrary bitmap image file as a welcome banner +on the screen when the system is about to start. +This image will remain on the screen +during kernel initialization process +until the login prompt appears on the screen +or until a screen saver is loaded and initialized. +The image will also disappear if you hit any key, +although this may not work immediately +if the kernel is still probing devices. +.Pp +If you specify the +.Fl c +or +.Fl v +boot option when loading the kernel, the splash image will not appear. +However, it +is still loaded and can be used as a screen saver later: see below. +.Pp +In order to display the bitmap, the bitmap file itself and the +matching splash image decoder module must be loaded by the boot loader. +Currently the following decoder modules are available: +.Pp +.Bl -tag -width splash_decoder -compact +.It Pa splash_bmp.ko +Windows BMP file decoder. +While the BMP file format allows images of various color depths, this +decoder currently only handles 256 color bitmaps. +Bitmaps of other color depths will not be displayed. +.It Pa splash_pcx.ko +ZSoft PCX decoder. +This decoder currently only supports version 5 8-bpp single-plane +images. +.It Pa splash_txt.ko +TheDraw binary ASCII drawing file decoder. +Displays a text-mode 80x25 ASCII drawing, such as that produced by +the Binary save format in TheDraw. +This format consists of a sequence +of two byte pairs representing the 80x25 display, where the first byte +is the ASCII character to draw and the second byte indicates the +colors/attributes to use when drawing the character. +.El +.Pp +The +.Sx EXAMPLES +section illustrates how to set up the splash screen. +.Pp +If the standard VGA video mode is used, +the size of the bitmap must be 320x200 or less. +If you enable the VESA mode support in the kernel, +either by statically linking the VESA module or by loading the VESA module +(see +.Xr vga 4 ) , +you can load bitmaps up to a resolution of 1024x768, depending on the VESA +BIOS and the amount of video memory on the video card. +.Ss Screen saver +The screen saver will activate when the system is considered idle: i.e.\& +when the user has not typed a key or moved the mouse for a specified period +of time. +As the screen saver is an optional module, +it must be explicitly loaded into memory. +Currently the following screen saver modules are available: +.Pp +.Bl -tag -width splash_module.ko -compact +.It Pa blank_saver.ko +This screen saver simply blanks the screen. +.It Pa beastie_saver.ko +Animated graphical +.Bx +Daemon. +.It Pa daemon_saver.ko +Animated +.Bx +Daemon screen saver. +.It Pa dragon_saver.ko +Draws a random dragon curve. +.It Pa fade_saver.ko +The screen will gradually fade away. +.It Pa fire_saver.ko +A fire which becomes higher as load increases. +.It Pa green_saver.ko +The screen will be blanked, similar to +.Pa blank_saver.ko . +If the monitor and the video card's BIOS support it +the screen will also be powered off. +.It Pa logo_saver.ko +Animated graphical +.Fx +logo. +.It Pa plasma_saver.ko +Draws an animated interference pattern. +.It Pa rain_saver.ko +Draws a shower on the screen. +.It Pa snake_saver.ko +Draws a snake of string. +.It Pa star_saver.ko +Twinkling stars. +.It Pa warp_saver.ko +Streaking stars. +.El +.Pp +Screen saver modules can be loaded using +.Xr kldload 8 : +.Pp +.Dl kldload logo_saver +.Pp +The timeout value in seconds can be specified as follows: +.Pp +.Dl vidcontrol -t N +.Pp +Alternatively, you can set the +.Ar saver +variable in the +.Pa /etc/rc.conf +to the screen saver of your choice and +the timeout value to the +.Ar blanktime +variable so that the screen saver is automatically loaded +and the timeout value is set when the system starts. +.Pp +The screen saver may be instantly activated by hitting the +.Ar saver +key: the defaults are +.Em Shift-Pause +on the AT enhanced keyboard and +.Em Shift-Ctrl-NumLock/Pause +on the AT 84 keyboard. +You can change the +.Ar saver +key by modifying the keymap +(see +.Xr kbdcontrol 1 , +.Xr keymap 5 ) , +and assign the +.Ar saver +function to a key of your preference. +.Pp +The screen saver will not run if the screen is not in text mode. +.Ss Splash screen as a screen saver +If you load a splash image but do not load a screen saver, +you can continue using the splash module as a screen saver. +The screen blanking interval can be specified as described in the +.Sx Screen saver +section above. +.\".Sh DRIVER CONFIGURATION +.Sh FILES +.Bl -tag -width /boot/kernel/splash_xxxx.ko -compact +.It Pa /boot/defaults/loader.conf +boot loader configuration defaults +.It Pa /etc/rc.conf +system configuration information +.It Pa /boot/kernel/splash_*.ko +splash image decoder modules +.It Pa /boot/kernel/*_saver.ko +screen saver modules +.It Pa /boot/kernel/vesa.ko +the VESA support module +.El +.Sh EXAMPLES +In order to load the splash screen or the screen saver, you must +have the following line in the kernel configuration file. +.Pp +.Dl device splash +.Pp +Next for +.Xr syscons 4 , +edit +.Pa /boot/loader.conf +(see +.Xr loader.conf 5 ) +and include the following lines: +.Bd -literal -offset indent +splash_bmp_load="YES" +bitmap_load="YES" +bitmap_name="/boot/chuck.bmp" +.Ed +.Pp +In the above example, the file +.Pa /boot/chuck.bmp +is loaded. +In the following example, the VESA module +is loaded so that a bitmap file which cannot be displayed in standard +VGA modes may be shown using one of the VESA video modes. +.Bd -literal -offset indent +splash_pcx_load="YES" +vesa_load="YES" +bitmap_load="YES" +bitmap_name="/boot/chuck.pcx" +.Ed +.Pp +If the VESA support is statically linked to the kernel, it is not +necessary to load the VESA module. +Just load the bitmap file and the splash decoder module as in the +first example above. +.Pp +To load a binary ASCII drawing and display this while booting, include the +following into your +.Pa /boot/loader.conf : +.Bd -literal -offset indent +splash_txt_load="YES" +bitmap_load="YES" +bitmap_name="/boot/splash.bin" +.Ed +.Pp +For +.Xr vt 4 , +edit +.Pa /boot/loader.conf +(see +.Xr loader.conf 5 ) +and include the following lines: +.Bd -literal -offset indent +splash="/boot/images/freebsd-logo-rev.png" +boot_mute="YES" +.Ed +.Pp +A splash screen to be displayed at shutdown time can be specified with: +.Bd -literal -offset indent +shutdown_splash="/boot/images/freebsd-logo-rev.png" +boot_mute="YES" +.Ed +.\".Sh DIAGNOSTICS +.Sh SEE ALSO +.Xr vidcontrol 1 , +.Xr syscons 4 , +.Xr vga 4 , +.Xr loader.conf 5 , +.Xr rc.conf 5 , +.Xr kldload 8 , +.Xr kldunload 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 3.1 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver and this manual page were written by +.An Kazutaka Yokota Aq Mt yokota@FreeBSD.org . +The +.Pa splash_bmp +module was written by +.An Michael Smith Aq Mt msmith@FreeBSD.org +and +.An Kazutaka Yokota . +The +.Pa splash_pcx +module was written by +.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org +based on the +.Pa splash_bmp +code. +The +.Pa splash_txt +module was written by +.An Antony Mawer Aq Mt antony@mawer.org +based on the +.Pa splash_bmp +code, with some additional inspiration from the +.Pa daemon_saver +code. +The +.Pa logo_saver , +.Pa plasma_saver , +.Pa rain_saver +and +.Pa warp_saver +modules were written by +.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . +.Pa splash +png support for +.Xr vt 4 +was written by +.An Emmanuel Vadot Aq Mt manu@FreeBSD.org +and extended for shutdown by +.An Quentin Thébault Aq Mt quentin.thebault@defenso.fr . +.Sh CAVEATS +The screen saver works with +.Xr syscons 4 +only. +.Pp +For vt splash screen, only RGBA png are supported. +.Sh BUGS +If you load a screen saver while another screen saver has already +been loaded, the first screen saver will not be automatically unloaded +and will remain in memory, wasting kernel memory space. diff --git a/static/freebsd/man4/ste.4 b/static/freebsd/man4/ste.4 new file mode 100644 index 00000000..ba82e22e --- /dev/null +++ b/static/freebsd/man4/ste.4 @@ -0,0 +1,201 @@ +.\" Copyright (c) 1997, 1998, 1999 +.\" Bill Paul . 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 Bill Paul. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Bill Paul 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 Bill Paul OR THE VOICES IN HIS HEAD +.\" 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 24, 2009 +.Dt STE 4 +.Os +.Sh NAME +.Nm ste +.Nd "Sundance Technologies ST201 Fast Ethernet device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device ste" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_ste_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for PCI Ethernet adapters and embedded +controllers based on the Sundance Technologies ST201 PCI Fast +Ethernet controller chip. +.Pp +The Sundance ST201 uses bus master DMA and is designed to be a +3Com Etherlink XL workalike. +It uses the same DMA descriptor +structure and is very similar in operation, however its register +layout is different. +The ST201 has a 64-bit multicast hash filter +and a single perfect filter entry for the station address. +It supports both 10 and 100Mbps speeds in either full or half duplex +using an MII transceiver. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width xxxxxxxxxxxxxxxxxxxx +.It autoselect +Enable autoselection of the media type and options. +The user can manually override +the autoselected mode by adding media options to the +.Pa /etc/rc.conf +file. +.It 10baseT/UTP +Set 10Mbps operation. +The +.Ar mediaopt +option can also be used to select either +.Ar full-duplex +or +.Ar half-duplex +modes. +.It 100baseTX +Set 100Mbps (Fast Ethernet) operation. +The +.Ar mediaopt +option can also be used to select either +.Ar full-duplex +or +.Ar half-duplex +modes. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width xxxxxxxxxxxxxxxxxxxx +.It full-duplex +Force full duplex operation. +.It half-duplex +Force half duplex operation. +.El +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports Sundance Technologies ST201 based Fast Ethernet +adapters and embedded controllers including: +.Pp +.Bl -bullet -compact +.It +D-Link DFE-530TXS +.It +D-Link DFE-550TX +.It +D-Link DFE-580TX +.El +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width "xxxxxx" +.It Va dev.ste.%d.int_rx_mod +Maximum number of time to delay RX interrupts. +The valid range is 0 to 209712 in units of 1us, the default is +150 (150us). +The value 0 effectively disables the RX interrupt moderation. +The resolution of timer is about 3.2us so finer tuning than +3.2us wouldn't be available. +The interface does not need to be brought down and up again before +a change takes effect. +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "ste%d: couldn't map ports/memory" +A fatal initialization error has occurred. +.It "ste%d: couldn't map interrupt" +A fatal initialization error has occurred. +.It "ste%d: watchdog timeout" +The device has stopped responding to the network, or there is a problem with +the network connection (cable). +.It "ste%d: no memory for rx list" +The driver failed to allocate an mbuf for the receiver ring. +.It "ste%d: no memory for tx list" +The driver failed to allocate an mbuf for the transmitter ring when +allocating a pad buffer or collapsing an mbuf chain into a cluster. +.It "ste%d: chip is in D3 power state -- setting to D0" +This message applies only to adapters which support power +management. +Some operating systems place the controller in low power +mode when shutting down, and some PCI BIOSes fail to bring the chip +out of this state before configuring it. +The controller loses all of +its PCI configuration in the D3 state, so if the BIOS does not set +it back to full power mode in time, it will not be able to configure it +correctly. +The driver tries to detect this condition and bring +the adapter back to the D0 (full power) state, but this may not be +enough to return the driver to a fully operational condition. +If +you see this message at boot time and the driver fails to attach +the device as a network interface, you will have to perform a second +warm boot to have the device properly configured. +.Pp +Note that this condition only occurs when warm booting from another +operating system. +If you power down your system prior to booting +.Fx , +the card should be configured correctly. +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr polling 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Rs +.%T Sundance ST201 data sheet +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 3.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Bill Paul Aq Mt wpaul@ee.columbia.edu . diff --git a/static/freebsd/man4/stf.4 b/static/freebsd/man4/stf.4 new file mode 100644 index 00000000..c93600c1 --- /dev/null +++ b/static/freebsd/man4/stf.4 @@ -0,0 +1,339 @@ +.\" $KAME: stf.4,v 1.35 2001/05/02 06:24:49 itojun Exp $ +.\" +.\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. +.\" 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. Neither the name of the project nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT 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 PROJECT 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 November 16, 2021 +.Dt STF 4 +.Os +.Sh NAME +.Nm stf +.Nd +.Tn 6to4 +tunnel interface +.Sh SYNOPSIS +.Cd "device stf" +.Sh DESCRIPTION +The +.Nm +interface supports +.Dq 6to4 +and +.Dq 6rd +IPv6 in IPv4 encapsulation. +It can tunnel IPv6 traffic over IPv4, as specified in +.Li RFC3056 +or +.Li RFC5969 . +.Pp +For ordinary nodes in a 6to4 or 6RD site, you do not need +.Nm +interface. +The +.Nm +interface is necessary for site border routers +(called +.Dq 6to4 routers +or +.Dq 6rd Customer Edge (CE) +in the specification). +.Pp +Each +.Nm +interface is created at runtime using interface cloning. +This is +most easily done with the +.Xr ifconfig 8 +.Cm create +command or using the +.Va cloned_interfaces +variable in +.Xr rc.conf 5 . +.Sh 6to4 +Due to the way 6to4 protocol is specified, +.Nm +interface requires certain configuration to work properly. +Single +(no more than 1) +valid 6to4 address needs to be configured to the interface. +.Dq A valid 6to4 address +is an address which has the following properties. +If any of the following properties are not satisfied, +.Nm +raises runtime error on packet transmission. +Read the specification for more details. +.Bl -bullet +.It +matches +.Li 2002:xxyy:zzuu::/48 +where +.Li xxyy:zzuu +is a hexadecimal notation of an IPv4 address for the node. +IPv4 address can be taken from any of interfaces your node has. +Since the specification forbids the use of IPv4 private address, +the address needs to be a global IPv4 address. +.It +Subnet identifier portion +(48th to 63rd bit) +and interface identifier portion +(lower 64 bits) +are properly filled to avoid address collisions. +.El +.Pp +If you would like the node to behave as a relay router, +the prefix length for the IPv6 interface address needs to be 16 so that +the node would consider any 6to4 destination as +.Dq on-link . +If you would like to restrict 6to4 peers to be inside certain IPv4 prefix, +you may want to configure IPv6 prefix length as +.Dq 16 + IPv4 prefix length . +.Nm +interface will check the IPv4 source address on packets, +if the IPv6 prefix length is larger than 16. +.Pp +.Nm +can be configured to be ECN friendly. +This can be configured by +.Dv IFF_LINK1 . +See +.Xr gif 4 +for details. +.Pp +Please note that 6to4 specification is written as +.Dq accept tunnelled packet from everyone +tunnelling device. +By enabling +.Nm +device, you are making it much easier for malicious parties to inject +fabricated IPv6 packet to your node. +Also, malicious party can inject an IPv6 packet with fabricated source address +to make your node generate improper tunnelled packet. +Administrators must take caution when enabling the interface. +To prevent possible attacks, +.Nm +interface filters out the following packets. +Note that the checks are no way complete: +.Bl -bullet +.It +Packets with IPv4 unspecified address as outer IPv4 source/destination +.Pq Li 0.0.0.0/8 +.It +Packets with loopback address as outer IPv4 source/destination +.Pq Li 127.0.0.0/8 +.It +Packets with IPv4 multicast address as outer IPv4 source/destination +.Pq Li 224.0.0.0/4 +.It +Packets with limited broadcast address as outer IPv4 source/destination +.Pq Li 255.0.0.0/8 +.It +Packets with private address as outer IPv4 source/destination +.Pq Li 10.0.0.0/8 , 172.16.0.0/12 , 192.168.0.0/16 +.It +Packets with subnet broadcast address as outer IPv4 source/destination. +The check is made against subnet broadcast addresses for +all of the directly connected subnets. +.It +Packets that does not pass ingress filtering. +Outer IPv4 source address must meet the IPv4 topology on the routing table. +Ingress filter can be turned off by +.Dv IFF_LINK2 +bit. +.It +The same set of rules are applied against the IPv4 address embedded into +inner IPv6 address, if the IPv6 address matches 6to4 prefix. +.El +.Pp +It is recommended to filter/audit +incoming IPv4 packet with IP protocol number 41, as necessary. +It is also recommended to filter/audit encapsulated IPv6 packets as well. +You may also want to run normal ingress filter against inner IPv6 address +to avoid spoofing. +.Pp +By setting the +.Dv IFF_LINK0 +flag on the +.Nm +interface, it is possible to disable the input path, +making the direct attacks from the outside impossible. +Note, however, there are other security risks exist. +If you wish to use the configuration, +you must not advertise your 6to4 address to others. +.\" +.Sh 6rd +Like +.Dq 6to4 +.Dq 6rd +also requires configuration before it can be used. +The required configuration parameters are: +.Bl -bullet +.It +The IPv6 address and prefix length. +.It +The border router IPv4 address. +.It +The IPv4 WAN address. +.It +The prefix length of the IPv4 WAN address. +.El +.Pp +These parameters are all configured through +.Xr ifconfig 8 . +.Pp +The IPv6 address and prefix length can be configured like any other IPv6 address. +Note that the prefix length is the IPv6 prefix length excluding the embedded +IPv4 address bits. +The prefix length of the delegated network is the sum of the IPv6 prefix length +and the IPv4 prefix length. +.Pp +The border router IPv4 address is configured with the +.Xr ifconfig 8 +.Cm stfv4br +command. +.Pp +The IPv4 WAN address and IPv4 prefix length are configured using the +.Xr ifconfig 8 +.Cm stfv4net +command. +.Sh SYSCTL VARIABLES +The following +.Xr sysctl 8 +variables can be used to control the behavior of the +.Nm stf . +The default value is shown next to each variable. +.Bl -tag -width indent +.It Va net.link.stf.permit_rfc1918 : No 0 +The RFC3056 requires the use of globally unique 32-bit IPv4 +addresses. +This sysctl variable controls the behaviour of this requirement. +When it set to not 0, +.Nm stf +allows the use of private IPv4 addresses described in the RFC1918. +This may be useful for an Intranet environment or when some mechanisms +of network address translation (NAT) are used. +.El +.Sh EXAMPLES +Note that +.Li 8504:0506 +is equal to +.Li 133.4.5.6 , +written in hexadecimals. +.Bd -literal +# ifconfig ne0 inet 133.4.5.6 netmask 0xffffff00 +# ifconfig stf0 inet6 2002:8504:0506:0000:a00:5aff:fe38:6f86 \\ + prefixlen 16 alias +.Ed +.Pp +The following configuration accepts packets from IPv4 source +.Li 9.1.0.0/16 +only. +It emits 6to4 packet only for IPv6 destination 2002:0901::/32 +(IPv4 destination will match +.Li 9.1.0.0/16 ) . +.Bd -literal +# ifconfig ne0 inet 9.1.2.3 netmask 0xffff0000 +# ifconfig stf0 inet6 2002:0901:0203:0000:a00:5aff:fe38:6f86 \\ + prefixlen 32 alias +.Ed +.Pp +The following configuration uses the +.Nm +interface as an output-only device. +You need to have alternative IPv6 connectivity +(other than 6to4) +to use this configuration. +For outbound traffic, you can reach other 6to4 networks efficiently via +.Nm stf . +For inbound traffic, you will not receive any 6to4-tunneled packets +(less security drawbacks). +Be careful not to advertise your 6to4 prefix to others +.Pq Li 2002:8504:0506::/48 , +and not to use your 6to4 prefix as a source. +.Bd -literal +# ifconfig ne0 inet 133.4.5.6 netmask 0xffffff00 +# ifconfig stf0 inet6 2002:8504:0506:0000:a00:5aff:fe38:6f86 \\ + prefixlen 16 alias deprecated link0 +# route add -inet6 2002:: -prefixlen 16 ::1 +# route change -inet6 2002:: -prefixlen 16 ::1 -ifp stf0 +.Ed +.Pp +The following example configures a +.Dq 6rd +tunnel on a +.Dq 6rd CE +where the ISP's +.Dq 6rd +IPv6 prefix is 2001:db8::/32. +The border router is 192.0.2.1. +The +.Dq 6rd CE +has a WAN address of 192.0.2.2 and the full IPv4 address is embedded in the +.Dq 6rd IPv6 address: +.Bd -literal +# ifconfig stf0 inet6 2001:db8:c000:0202:: prefixlen 32 up +# ifconfig stf0 stfv4br 192.0.2.1 +# ifconfig stf0 stfv4net 192.0.2.2/32 +.Ed +.\" +.Sh SEE ALSO +.Xr gif 4 , +.Xr inet 4 , +.Xr inet6 4 +.Rs +.%A Brian Carpenter +.%A Keith Moore +.%T "Connection of IPv6 Domains via IPv4 Clouds" +.%D February 2001 +.%R RFC +.%N 3056 +.Re +.Rs +.%A Jun-ichiro itojun Hagino +.%T "Possible abuse against IPv6 transition technologies" +.%D July 2000 +.%N draft-itojun-ipv6-transition-abuse-01.txt +.%O work in progress +.Re +.\" +.Sh HISTORY +The +.Nm +device first appeared in WIDE/KAME IPv6 stack. +.\" +.Sh BUGS +No more than one +.Nm +interface is allowed for a node, +and no more than one IPv6 interface address is allowed for an +.Nm +interface. +It is to avoid source address selection conflicts +between IPv6 layer and IPv4 layer, +and to cope with ingress filtering rule on the other side. +This is a feature to make +.Nm +work right for all occasions. diff --git a/static/freebsd/man4/stge.4 b/static/freebsd/man4/stge.4 new file mode 100644 index 00000000..2dbaf70b --- /dev/null +++ b/static/freebsd/man4/stge.4 @@ -0,0 +1,198 @@ +.\" $NetBSD: stge.4,v 1.7 2003/02/14 15:20:20 grant Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 November 23, 2010 +.Dt STGE 4 +.Os +.Sh NAME +.Nm stge +.Nd Sundance/Tamarack TC9021 Gigabit Ethernet adapter driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device stge" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_stge_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +device driver provides support for various NICs based on the +Sundance/Tamarack TC9021 Gigabit Ethernet controller chip. +.Pp +The Sundance/Tamarack TC9021 is found on the D-Link DGE-550T +and the Antares Microsystems Gigabit Ethernet board. +It uses an external PHY or an external 10-bit interface. +.Pp +All NICs supported by the +.Nm +driver have TCP/UDP/IP checksum offload for both receive and +transmit, hardware VLAN tag stripping/insertion features, and +receive interrupt moderation mechanism as well as a 64-bit +multicast hash filter. +The Sundance/Tamarack TC9021 supports TBI (ten bit interface) +and GMII transceivers, which means it can be used with either +copper or 1000baseX fiber applications. +.Pp +The Sundance/Tamarack TC9021 also supports jumbo frames, which can be +configured via the interface MTU setting. +Selecting an MTU larger than 1500 bytes with the +.Xr ifconfig 8 +utility configures the adapter to receive and transmit jumbo frames. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width ".Cm 10baseT/UTP" +.It Cm autoselect +Enable autoselection of the media type and options. +The user can manually override +the autoselected mode by adding media options to +.Xr rc.conf 5 . +.It Cm 10baseT/UTP +Set 10Mbps operation. +The +.Xr ifconfig 8 +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 100baseTX +Set 100Mbps (Fast Ethernet) operation. +The +.Xr ifconfig 8 +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 1000baseTX +Set 1000baseTX operation over twisted pair. +The Sundance/Tamarack supports 1000Mbps in +.Cm autoselect +mode only. +.\" .It Cm 1000baseSX +.\" Set 1000Mbps (Gigabit Ethernet) operation. +.\" Both +.\" .Cm full-duplex +.\" and +.\" .Cm half-duplex +.\" modes are supported. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width ".Cm full-duplex" +.It Cm full-duplex +Force full duplex operation. +.It Cm half-duplex +Force half duplex operation. +.El +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver provides support for various NICs based on the Sundance/Tamarack +TC9021 based Gigabit Ethernet controller chips, including: +.Pp +.Bl -bullet -compact +.It +Antares Microsystems Gigabit Ethernet +.It +ASUS NX1101 Gigabit Ethernet +.It +D-Link DL-4000 Gigabit Ethernet +.It +IC Plus IP1000A Gigabit Ethernet +.It +Sundance ST-2021 Gigabit Ethernet +.It +Sundance ST-2023 Gigabit Ethernet +.It +Sundance TC9021 Gigabit Ethernet +.It +Tamarack TC9021 Gigabit Ethernet +.El +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va dev.stge.%d.rxint_nframe +Number of frames between RxDMAComplete interrupts. +The accepted range is 1 to 255, default value is 8 frames. +The interface has to be brought down and up again before a change takes effect. +.It Va dev.stge.%d.rxint_dmawait +Maximum amount of time to wait in 1us increments before issuing +an Rx interrupt if the number of frames received is less than +.Va rxint_nframe . +The accepted range is 0 to 4194, default value is 30 microseconds. +The interface has to be brought down and up again before a change takes effect. +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr polling 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +driver was ported from +.Nx +and first appeared in +.Fx 6.2 . +The +.Nx +version was written by +.An Jason R. Thorpe Aq Mt thorpej@NetBSD.org . +.Sh AUTHORS +The +.Nm +driver was ported by +.An Pyun YongHyeon Aq Mt yongari@FreeBSD.org . diff --git a/static/freebsd/man4/sume.4 b/static/freebsd/man4/sume.4 new file mode 100644 index 00000000..b36f9248 --- /dev/null +++ b/static/freebsd/man4/sume.4 @@ -0,0 +1,96 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2020 Denis Salopek +.\" +.\" 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 COPYRIGHT HOLDERS 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 COPYRIGHT OWNER 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 August 30, 2020 +.Dt SUME 4 amd64 +.Os +.Sh NAME +.Nm sume +.Nd "NetFPGA SUME 4x10Gb Ethernet driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines +in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device sume" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place +the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_sume_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for NetFPGA SUME Virtex-7 FPGA Development Board +with the reference NIC bitstream loaded onto it. +The HDL design for the reference NIC project uses the RIFFA based DMA +engine to communicate with the host machine over PCIe. +Every packet is transmitted to / from the board via a single DMA +transaction, taking up to two or three interrupts per one transaction +which yields low performance. +.Pp +There is no support for Jumbo frames as the hardware is capable of +dealing only with frames with maximum size of 1514 bytes. +The hardware does not support multicast filtering, provides no checksums, +and offers no other offloading. +.Sh SEE ALSO +.Xr arp 4 , +.Xr netgraph 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh AUTHORS +The Linux +.Nm +driver was originally written by +.An -nosplit +.An Bjoern A. Zeeb . +The +.Fx version and this manual page were written by +.An Denis Salopek +as a GSoC project. +More information about the project can be found here: +.Pa https://wiki.freebsd.org/SummerOfCode2020Projects/NetFPGA_SUME_Driver +.Sh BUGS +The reference NIC hardware design provides no mechanism for quiescing +inbound traffic from interfaces configured as DOWN. +All packets from administratively disabled interfaces are transferred to +main memory, leaving the driver with the task of dropping such packets, +thus consuming PCI bandwidth, interrupts and CPU cycles in vain. +.Pp +Pre-built FPGA bitstream from the NetFPGA project may not work correctly. +At higher RX packet rates, the newly incoming packets can overwrite the +ones in an internal FIFO so the packets would arrive in main memory +corrupted, until a physical reset of the board. +.Pp +Occasionally, the driver can get stuck in a non-IDLE TX state due to +a missed interrupt. +The driver includes a watchdog function which monitors for such a +condition and resets the board automatically. +For more details, visit the NetFPGA SUME project site. diff --git a/static/freebsd/man4/superio.4 b/static/freebsd/man4/superio.4 new file mode 100644 index 00000000..cee5e164 --- /dev/null +++ b/static/freebsd/man4/superio.4 @@ -0,0 +1,149 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2019 Andriy Gapon +.\" +.\" 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 October 11, 2019 +.Dt SUPERIO 4 +.Os +.Sh NAME +.Nm superio +.Nd Super I/O controller and bus driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device superio" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +superio_load="YES" +.Ed +.Sh DESCRIPTION +Super I/O is an I/O controller that combines various low-bandwidth devices +that can be functionally unrelated otherwise. +A typical Super I/O can contain devices such as +.Pp +.Bl -bullet -compact +.It +a floppy disk controller +.It +a parallel port +.It +a serial port +.It +a PS/2 mouse and keyboard controller +.It +a hardware monitoring controller +.It +a watchdog timer +.It +a controller for general purpose input-output +.El +.Pp +The +.Nm +driver provides support for devices residing in the Super I/O controller +that can only be accessed or discovered using the controller's interface. +Some of the Super I/O devices have standardized interfaces. +Such devices either use well-known legacy resources or they are advertised +via ACPI or both. +They can be configured either using ISA bus hints or they are auto-configured by +.Xr acpi 4 . +The +.Nm +driver is not designed to interact with that kind of devices. +They can be handled by their respective drivers without any knowledge of the +Super I/O specifics. +For instance, +.Xr fdc 4 +provides access to the floppy disk controller. +.Pp +There are other Super I/O devices that do not have any standardized interface. +Drivers for those devices can be written using facilities of the +.Nm +driver. +.Pp +The driver itself attaches to the ISA bus as all supported controllers are +accessed via LPC I/O ports. +.Pp +The +.Nm +driver is unusual as it is both a controller driver for a variety of Super I/O +controllers and a bus driver for supported devices in those controllers. +.Sh HARDWARE +The +.Nm +driver supports a multitude of Super I/O controllers produced by Nuvoton, +formerly known as Winbond, and ITE, namely: +.Pp +.Bl -bullet -compact +.It +Fintek F81803 +.It +Fintek F81865 +.It +Nuvoton NCT5104D/NCT6102D/NCT6106D rev. A and B+ +.It +Nuvoton NCT5585D +.It +Nuvoton NCT6116D +.It +Nuvoton NCT6775 +.It +Nuvoton NCT6776 +.It +Nuvoton NCT6779 +.It +Nuvoton NCT6791 +.It +Nuvoton NCT6792 +.It +Nuvoton NCT6793 +.It +Nuvoton NCT6795 +.It +Nuvoton NCT6796D-E +.It +Winbond 83627HF/F/HG/G/S/THF/EHF/DHG/UHG/DHG-P +.It +Winbond 83637HF +.It +Winbond 83667HG/HG-B +.It +Winbond 83687THF +.It +Winbond 83697HF/UG +.El +.Sh SEE ALSO +.Xr superio 9 +.Sh HISTORY +The +.Nm +driver was written by +.An Andriy Gapon Aq Mt avg@FreeBSD.org . diff --git a/static/freebsd/man4/sym.4 b/static/freebsd/man4/sym.4 new file mode 100644 index 00000000..14eb1624 --- /dev/null +++ b/static/freebsd/man4/sym.4 @@ -0,0 +1,325 @@ +.\" +.\" Device driver optimized for the Symbios/LSI 53C896/53C895A/53C1010 +.\" PCI SCSI controllers. +.\" +.\" Copyright (C) 1999-2000 Gerard Roudier +.\" +.\" This driver also supports the following Symbios/LSI PCI SCSI chips: +.\" 53C810A, 53C825A, 53C860, 53C875, 53C876, 53C885, 53C895, +.\" 53C810, 53C815, 53C825 and the 53C1510D is 53C8XX mode. +.\" +.\" +.\" This driver for FreeBSD-CAM is derived from the Linux sym53c8xx driver. +.\" Copyright (C) 1998-1999 Gerard Roudier +.\" +.\" The sym53c8xx driver is derived from the ncr53c8xx driver that had been +.\" a port of the FreeBSD ncr driver to Linux-1.2.13. +.\" +.\" The original ncr driver has been written for 386bsd and FreeBSD by +.\" Wolfgang Stanglmeier +.\" Stefan Esser +.\" Copyright (C) 1994 Wolfgang Stanglmeier +.\" +.\" The initialization code, and part of the code that addresses +.\" FreeBSD-CAM services is based on the aic7xxx driver for FreeBSD-CAM +.\" written by Justin T. Gibbs. +.\" +.\" Other major contributions: +.\" +.\" NVRAM detection and reading. +.\" Copyright (C) 1997 Richard Waltham +.\" +.\" ---------------------------------------------------------------------------- +.\" +.\" 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. 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 AUTHORS 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 December 26, 2020 +.Dt SYM 4 +.Os +.Sh NAME +.Nm sym +.Nd NCR/Symbios/LSI Logic 53C8XX PCI SCSI host adapter driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device pci" +.Cd "device scbus" +.Cd "device sym" +.Ed +.Pp +To disable PCI parity checking (needed for broken bridges): +.Cd "options SYM_SETUP_PCI_PARITY=" +.Pp +To control driver probing against HVD buses: +.Cd "options SYM_SETUP_SCSI_DIFF=" +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +sym_load="YES" +.Ed +.Sh DESCRIPTION +This driver provides support for the Symbios/LSI Logic 53C8XX +PCI SCSI controllers. +.Pp +Driver features include support for wide SCSI busses and fast10, fast20, +fast40 and fast80-dt synchronous data transfers depending on controller +capabilities. +It also provides generic SCSI features such as tagged command +queueing and auto-request sense. +This driver is configured by default +for a maximum of 446 outstanding commands per bus, 8 LUNs per target +and 64 tagged tasks per LUN. +These numbers are not so much limited by design +as they are considered reasonable values for current SCSI technology. +These values can be increased by changing appropriate +constants in driver header files (not recommended). +.Pp +This driver supports the entire Symbios 53C8XX family of PCI SCSI +controllers. +It also offers the advantage of architectural improvements available +only with newer chips. +.Pp +.Nm +notably handles phase mismatch from SCRIPTS for the 53C896, 53C895A, +and 53C1010 cores. +As a result, it guarantees that no more than 1 interrupt +per IO completion is delivered to the CPU, and that the SCRIPTS processor +is never stalled waiting for CPU attention in normal situations. +.Pp +.Nm +also uses LOAD/STORE SCRIPTS instructions for chips that support it. +Only the early 810, 815 and 825 NCR chips do not support LOAD/STORE. +Use of LOAD/STORE instead of MEMORY MOVE allows SCRIPTS to access IO +registers internal to the chip (no external PCI cycles). +As a result, the driver guarantees that no PCI self-mastering will occur +for chips that support LOAD/STORE. +.Pp +LOAD/STORE instructions are also faster than MEMORY MOVE because +they do not involve the chip DMA FIFO and are coded on 2 DWORDs +instead of 3. +.Pp +For the early NCR 810, 815 and 825 chips, the driver uses a separate +SCRIPTS set that uses MEMORY MOVE instructions for data movements. +This is because LOAD/STORE are not supported by these chips. +.Pp +HVD/LVD capable controllers (895, 895A, 896, and 897) report +the actual bus mode in the STEST4 chip IO registers. +This feature +allows the driver to safely probe against bus mode and to set up the chip +accordingly. +By default the driver only supports HVD for these chips. +For other chips that can support HVD but not LVD, the driver has to probe +implementation dependent registers (GPIO) in order to detect HVD bus mode. +Only HVD implementations that conform with Symbios Logic recommendations can +be detected by the driver. +When the +.Ar SYM_SETUP_SCSI_DIFF +kernel option is assigned +a value of 1, the driver will also probe against HVD for 825a, 875, 876 and +885 chips, assuming Symbios Logic compatible implementation of HVD. +.Pp +When the +.Ar SYM_SETUP_PCI_PARITY +is assigned a value of 0, the +driver will not enable PCI parity checking for 53C8XX devices. +PCI parity +checking should not be an option for PCI SCSI controllers, but some +systems have been reported to fail using 53C8XX chips, due to spurious or +permanent PCI parity errors detected. +This option is supplied for +convenience but it is neither recommended nor supported. +.Pp +This driver offers other options +that are not currently exported to the user. +They are defined and documented in the +.Pa sym_conf.h +driver file. +Changing these options is not recommended unless absolutely necessary. +Some of these +options are planned to be exported through +.Xr sysctl 3 +or an equivalent mechanism +in a future driver releases and therefore, +no compatibility is guaranteed. +.Pp +At initialization, the driver tries to detect and read user settings from +controller NVRAM. +The Symbios/Logic NVRAM layout and the Tekram NVRAM +layout are currently supported. +If the reading of the NVRAM succeeds, the +following settings are taken into account and reported to CAM: +.Bl -column "SCSI parity checking" "Symbios" +.It Em "Host settings Symbios Tekram" +.It "SCSI parity checking Y N" +.It "Host SCSI ident Y Y" +.It "Verbose messages Y N" +.It "Scan targets hi-lo Y N" +.It "Avoid SCSI bus reset Y N" +.El +.Bl -column "Synchronous period" "Symbios" +.It Em "Device settings Symbios Tekram" +.It "Synchronous period Y Y" +.It "SCSI bus width Y Y" +.It "Queue tag enable Y Y" +.It "Number of tags NA Y" +.It "Disconnect enable Y Y" +.It "Scan at boot time Y N" +.It "Scan LUN Y N" +.El +.Pp +Devices that are configured as disabled for 'scan' in the NVRAM are not +reported to CAM at system start-up. +They can be discovered later using +the +.Ql camcontrol rescan +command. +.Pp +The table below summarizes the main features and capabilities of the +NCR/Symbios/LSI Logic 53C8XX family of PCI SCSI controllers. +.Bl -column sym53c1510d "80MHz" "Width" "SRAM" "PCI64" +.It Em "Chip Sync Width SRAM PCI64 Supported" +.It "sym53c810 10MHz 8Bit N N Y" +.It "sym53c810a 10MHz 8Bit N N Y" +.It "sym53c815 10MHz 8Bit N N Y" +.It "sym53c825 10MHz 16Bit N N Y" +.It "sym53c825a 10MHz 16Bit 4KB N Y" +.It "sym53c860 20MHz 8Bit N N Y" +.It "sym53c875 20MHz 16Bit 4KB N Y" +.It "sym53c876 20MHz 16Bit 4KB N Y" +.It "sym53c885 20MHz 16Bit 4KB N Y" +.It "sym53c895 40MHz 16Bit 4KB N Y" +.It "sym53c895A 40MHz 16Bit 8KB N Y" +.It "sym53c896 40MHz 16Bit 8KB Y Y" +.It "sym53c897 40MHz 16Bit 8KB Y Y" +.It "sym53c1510D 40MHz 16Bit 4KB Y Y" +.It "sym53c1010 80MHz 16Bit 8KB Y Y" +.El +.Sh HARDWARE +The +.Nm +driver provides support for the following Symbios/LSI Logic PCI SCSI +controllers: +.Pp +.Bl -bullet -compact +.It +.Tn 53C810 +.It +.Tn 53C810A +.It +.Tn 53C815 +.It +.Tn 53C825 +.It +.Tn 53C825A +.It +.Tn 53C860 +.It +.Tn 53C875 +.It +.Tn 53C876 +.It +.Tn 53C895 +.It +.Tn 53C895A +.It +.Tn 53C896 +.It +.Tn 53C897 +.It +.Tn 53C1000 +.It +.Tn 53C1000R +.It +.Tn 53C1010-33 +.It +.Tn 53C1010-66 +.It +.Tn 53C1510D +.El +.Pp +The SCSI controllers supported by +.Nm +can be either embedded on a motherboard, or on +one of the following add-on boards: +.Pp +.Bl -bullet -compact +.It +ASUS SC-200, SC-896 +.It +Data Technology DTC3130 (all variants) +.It +DawiControl DC2976UW +.It +Diamond FirePort (all) +.It +NCR cards (all) +.It +Symbios cards (all) +.It +Tekram DC390W, 390U, 390F, 390U2B, 390U2W, 390U3D, and 390U3W +.It +Tyan S1365 +.El +.Sh MISC +The DEC KZPCA-AA is a rebadged SYM8952U. +.Sh SEE ALSO +.Xr cd 4 , +.Xr da 4 , +.Xr sa 4 , +.Xr scsi 4 , +.Xr camcontrol 8 +.Sh HISTORY +The +.Nm +driver appeared in +.Fx 4.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Gerard Roudier +and is derived from the +Linux sym53c8xx driver from the same author. +The sym53c8xx driver is derived from the ncr53c8xx driver, +which was ported from the +.Fx +.Xr ncr 4 +driver to Linux-1.2.13. +The original +.Xr ncr 4 +driver was written for +.Bx 386 +and +.Fx +by +.An Wolfgang Stanglmeier +and +.An Stefan Esser . +.Sh BUGS +No known bugs. diff --git a/static/freebsd/man4/syncache.4 b/static/freebsd/man4/syncache.4 new file mode 100644 index 00000000..f83e9b08 --- /dev/null +++ b/static/freebsd/man4/syncache.4 @@ -0,0 +1,263 @@ +.\" +.\" syncache - TCP SYN caching to handle SYN flood DoS. +.\" +.\" 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. +.\" +.Dd August 30, 2025 +.Dt SYNCACHE 4 +.Os +.Sh NAME +.Nm syncache , syncookies +.Nd +.Xr sysctl 8 +MIBs for controlling TCP SYN caching +.Sh SYNOPSIS +.Bl -item -compact +.It +.Nm sysctl Cm net.inet.tcp.syncookies +.It +.Nm sysctl Cm net.inet.tcp.syncookies_only +.El +.Pp +.Bl -item -compact +.It +.Nm sysctl Cm net.inet.tcp.syncache.hashsize +.It +.Nm sysctl Cm net.inet.tcp.syncache.bucketlimit +.It +.Nm sysctl Cm net.inet.tcp.syncache.cachelimit +.It +.Nm sysctl Cm net.inet.tcp.syncache.rexmtlimit +.It +.Nm sysctl Cm net.inet.tcp.syncache.count +.It +.Nm sysctl Cm net.inet.tcp.syncache.see_other +.It +.Nm sysctl Cm net.inet.tcp.syncache.rst_on_sock_fail +.El +.Sh DESCRIPTION +The +.Nm +.Xr sysctl 8 +MIB is used to control the TCP SYN caching in the system, which +is intended to handle SYN flood Denial of Service attacks. +.Pp +When a TCP SYN segment is received on a port corresponding to a listen +socket, an entry is made in the +.Nm , +and a SYN,ACK segment is +returned to the peer. +The +.Nm +entry holds the TCP options from the initial SYN, +enough state to perform a SYN,ACK retransmission, and takes up less +space than a TCP control block endpoint. +An incoming segment which contains an ACK for the SYN,ACK +and matches a +.Nm +entry will cause the system to create a TCP control block +with the options stored in the +.Nm +entry, which is then released. +.Pp +The +.Nm +protects the system from SYN flood DoS attacks by minimizing +the amount of state kept on the server, and by limiting the overall size +of the +.Nm . +.Pp +.Nm Syncookies +provides a way to virtually expand the size of the +.Nm +by keeping state regarding the initial SYN in the network. +Enabling +.Nm syncookies +sends a cryptographic value in the SYN,ACK reply to +the client machine, which is then returned in the client's ACK. +If the corresponding entry is not found in the +.Nm , +but the value +passes specific security checks, the connection will be accepted. +This is only used if the +.Nm +is unable to handle the volume of +incoming connections, and a prior entry has been evicted from the cache. +.Pp +.Nm Syncookies +have a certain number of disadvantages that a paranoid +administrator may wish to take note of. +Since the TCP options from the initial SYN are not saved, they are not +applied to the connection, precluding use of features like window scale, +timestamps, or exact MSS sizing. +As the returning ACK establishes the connection, it may be possible for +an attacker to ACK flood a machine in an attempt to create a connection. +While steps have been taken to mitigate this risk, this may provide a way +to bypass firewalls which filter incoming segments with the SYN bit set. +.Pp +To disable the +.Nm syncache +and run only with +.Nm syncookies , +set +.Va net.inet.tcp.syncookies_only +to 1. +To use +.Nm syncookies +to handle bucket overflows in the +.Nm syncache +set +.Va net.inet.tcp.syncookies +to 1. +The default value for +.Va net.inet.tcp.syncookies_only +is 0 and the default value for +.Va net.inet.tcp.syncookies +is 1. +.Pp +The +.Nm +implements a number of variables in +the +.Va net.inet.tcp.syncache +branch of the +.Xr sysctl 3 +MIB. +Several of these may be tuned by setting the corresponding +variable in the +.Xr loader 8 . +.Bl -tag -width ".Va bucketlimit" +.It Va hashsize +Size of the +.Nm +hash table, must be a power of 2. +Read-only, tunable via +.Xr loader 8 . +.It Va bucketlimit +Limit on the number of entries permitted in each bucket of the hash table. +This should be left at a low value to minimize search time. +Read-only, tunable via +.Xr loader 8 . +.It Va cachelimit +Limit on the total number of entries in the +.Nm . +Defaults to +.Va ( hashsize No \(mu Va bucketlimit ) , +may be set lower to minimize memory +consumption. +Read-only, tunable via +.Xr loader 8 . +.It Va rexmtlimit +Maximum number of times a SYN,ACK is retransmitted before being discarded. +The default of 3 retransmits corresponds to a 45 second timeout, this value +may be increased depending on the RTT to client machines. +Tunable via +.Xr sysctl 3 . +.It Va count +Number of entries present in the +.Nm +(read-only). +.It Va see_other +If set to true value, all +.Nm +entries will be visible via +.Va net.inet.tcp.pcblist +sysctl, or via +.Xr netstat 1 , +ignoring all of +.Xr security 7 +UID/GID, +.Xr jail 2 +and +.Xr mac 4 +checks. +If turned off, the visibility checks are enforced. +However, extra +.Xr ucred 9 +referencing is required on every incoming SYN packet processed. +The default is off. +.It Va rst_on_sock_fail +Send a TCP RST segment if the socket allocation fails. +The default is on. +.El +.Pp +Statistics on the performance of the +.Nm +may be obtained via +.Xr netstat 1 , +which provides the following counts: +.Bl -tag -width ".Li cookies received" +.It Li "syncache entries added" +Entries successfully inserted in the +.Nm . +.It Li retransmitted +SYN,ACK retransmissions due to a timeout expiring. +.It Li dupsyn +Incoming SYN segment matching an existing entry. +.It Li dropped +SYNs dropped because SYN,ACK could not be sent. +.It Li completed +Successfully completed connections. +.It Li "bucket overflow" +Entries dropped for exceeding per-bucket size. +.It Li "cache overflow" +Entries dropped for exceeding overall cache size. +.It Li reset +RST segment received. +.It Li stale +Entries dropped due to maximum retransmissions or listen socket disappearance. +.It Li aborted +New socket allocation failures. +.It Li badack +Entries dropped due to bad ACK reply. +.It Li unreach +Entries dropped due to ICMP unreachable messages. +.It Li "zone failures" +Failures to allocate new +.Nm +entry. +.It Li "cookies sent" +SYN cookies sent in SYN ACK segments. +.It Li "cookies received" +ACK segments with valid syncookies which resulted in TCP connection +establishment. +.It Li "spurious cookies rejected" +Received ACKs, for which the syncache lookup failed and also no syncookie was +recently sent. +.It Li "failed cookies rejected" +Received ACKs for which the syncookie validation failed. +.El +.Sh SEE ALSO +.Xr netstat 1 , +.Xr jail 2 , +.Xr mac 4 , +.Xr tcp 4 , +.Xr security 7 , +.Xr loader 8 , +.Xr sysctl 8 , +.Xr ucred 9 +.Sh HISTORY +The existing +.Nm +implementation +first appeared in +.Fx 4.5 . +The original concept of a +.Nm +originally appeared in +.Bsx , +and was later modified by +.Nx , +then further extended here. +.Sh AUTHORS +The +.Nm +code and manual page were written by +.An Jonathan Lemon Aq Mt jlemon@FreeBSD.org . diff --git a/static/freebsd/man4/syncer.4 b/static/freebsd/man4/syncer.4 new file mode 100644 index 00000000..326f14ed --- /dev/null +++ b/static/freebsd/man4/syncer.4 @@ -0,0 +1,90 @@ +.\" Copyright (c) 2000 Sheldon Hearn +.\" 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 REGENTS 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 REGENTS 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 14, 2000 +.Dt SYNCER 4 +.Os +.Sh NAME +.Nm syncer +.Nd file system synchronizer kernel process +.Sh SYNOPSIS +.Nm +.Sh DESCRIPTION +The +.Nm +kernel process helps protect the integrity of disk volumes +by flushing volatile cached file system data to disk. +.Pp +The kernel places all +.Xr vnode 9 Ns 's +in a number of queues. +The +.Nm +process works through the queues +in a round-robin fashion, +usually processing one queue per second. +For each +.Xr vnode 9 +on that queue, +the +.Nm +process forces a write out to disk of its dirty buffers. +.Pp +The usual delay between the time buffers are dirtied +and the time they are synced +is controlled by the following +.Xr sysctl 8 +tunable variables: +.Bl -column "filedelayXXXX" "DefaultXX" "DescriptionXX" +.It Em Variable Ta Em Default Ta Em Description +.It Va kern.filedelay Ta 30 Ta "time to delay syncing files" +.It Va kern.dirdelay Ta 29 Ta "time to delay syncing directories" +.It Va kern.metadelay Ta 28 Ta "time to delay syncing metadata" +.El +.Sh SEE ALSO +.Xr sync 2 , +.Xr fsck 8 , +.Xr sync 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +process is a descendant of the +.Sq update +command, which appeared in +.At v6 , +and was usually started by +.Pa /etc/rc +when the system went multi-user. +A kernel initiated +.Sq update +process first appeared in +.Fx 2.0 . +.Sh BUGS +It is possible on some systems that a +.Xr sync 2 +occurring simultaneously with a crash may cause +file system damage. +See +.Xr fsck 8 . diff --git a/static/freebsd/man4/syscons.4 b/static/freebsd/man4/syscons.4 new file mode 100644 index 00000000..7e31680c --- /dev/null +++ b/static/freebsd/man4/syscons.4 @@ -0,0 +1,647 @@ +.\" +.\" Copyright (c) 1999 +.\" Kazutaka YOKOTA +.\" 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 as +.\" the first lines of this file unmodified. +.\" 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 ``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 November 2, 2024 +.Dt SYSCONS 4 +.Os +.Sh NAME +.Nm syscons , +.Nm sc +.Nd the legacy console driver +.Sh SYNOPSIS +.Cd "options MAXCONS=N" +.Cd "options SC_ALT_MOUSE_IMAGE" +.Cd "options SC_CUT_SEPCHARS=_characters_" +.Cd "options SC_CUT_SPACES2TABS" +.Cd "options SC_DFLT_TERM" +.Cd "options SC_DISABLE_KDBKEY" +.Cd "options SC_DISABLE_REBOOT" +.Cd "options SC_HISTORY_SIZE=N" +.Cd "options SC_MOUSE_CHAR=C" +.Cd "options SC_NO_CUTPASTE" +.Cd "options SC_NO_FONT_LOADING" +.Cd "options SC_NO_HISTORY" +.Cd "options SC_NO_PALETTE_LOADING" +.Cd "options SC_NO_SUSPEND_VTYSWITCH" +.Cd "options SC_NO_SYSMOUSE" +.Cd "options SC_NO_TERM_DUMB" +.Cd "options SC_NO_TERM_SC" +.Cd "options SC_NO_TERM_SCTEKEN" +.Cd "options SC_PIXEL_MODE" +.Cd "options SC_TWOBUTTON_MOUSE" +.Cd "options SC_NORM_ATTR=_attribute_" +.Cd "options SC_NORM_REV_ATTR=_attribute_" +.Cd "options SC_KERNEL_CONS_ATTR=_attribute_" +.Cd "options SC_KERNEL_CONS_ATTRS=_attributes_" +.Cd "options SC_KERNEL_CONS_REV_ATTR=_attribute_" +.Cd "options SC_DFLT_FONT" +.Cd "makeoptions SC_DFLT_FONT=_font_name_" +.Cd "device sc" +.Pp +In +.Pa /boot/device.hints : +.Cd hint.sc.0.at="isa" +.Cd hint.sc.0.vesa_mode=0x103 +.Pp +In +.Pa /boot/loader.conf : +.Cd kern.vty=sc +.Sh DEPRECATION NOTICE +The +.Nm +console is deprecated, and will be removed in a future version of +.Fx . +Users are advised to migrate to the +.Xr vt 4 +console instead. +.Sh DESCRIPTION +The +.Nm +driver provides multiple virtual terminals. +It resembles the SCO color console driver. +.Pp +Note that the +.Nm +driver is not compatible with systems booted via +.Xr UEFI 8 . +Forcing use of +.Nm +on such systems will result in no usable console. +.Pp +The +.Nm +driver is implemented on top of the keyboard driver +.Pq Xr atkbd 4 +and the video card driver +.Pq Xr vga 4 +and so requires both of them to be configured in the system. +.Pp +There can be only one +.Nm +device defined in the system. +.Ss Virtual Terminals +The +.Nm +driver provides multiple virtual terminals which appear as if they were +separate terminals. +One virtual terminal is considered current and exclusively +occupies the screen and the keyboard; the other virtual terminals +are placed in the background. +.Pp +In order to use virtual terminals, they must be individually +marked ``on'' in +.Pa /etc/ttys +so that +.Xr getty 8 +will recognize them to be active and run +.Xr login 1 +to let the user log in to the system. +By default, only the first eight virtual terminals are activated in +.Pa /etc/ttys . +.Pp +You press the +.Dv Alt +key and a switch key to switch between +virtual terminals. +The following table summarizes the correspondence between the switch +key and the virtual terminal. +.Bd -literal -offset indent +Alt-F1 ttyv0 Alt-F7 ttyv6 Shift-Alt-F1 ttyva +Alt-F2 ttyv1 Alt-F8 ttyv7 Shift-Alt-F2 ttyvb +Alt-F3 ttyv2 Alt-F9 ttyv8 Shift-Alt-F3 ttyvc +Alt-F4 ttyv3 Alt-F10 ttyv9 Shift-Alt-F4 ttyvd +Alt-F5 ttyv4 Alt-F11 ttyva Shift-Alt-F5 ttyve +Alt-F6 ttyv5 Alt-F12 ttyvb Shift-Alt-F6 ttyvf +.Ed +.Pp +You can also use the ``nscr'' key (usually the +.Dv PrintScreen +key on the AT Enhanced keyboard) to cycle available virtual terminals. +.Pp +The default number of available virtual terminals is 16. +This can be changed with the kernel configuration option +.Dv MAXCONS +(see below). +.Pp +Note that the X server usually requires a virtual terminal for display +purposes, so at least one terminal must be left unused by +.Xr getty 8 +so that it can be used by the X server. +.Ss Key Definitions and Function Key Strings +The +.Nm +driver, in conjunction with the keyboard driver, allows the user +to change key definitions and function key strings. +The +.Xr kbdcontrol 1 +command will load a key definition file (known as ``keymap'' file), +dump the current keymap, and assign a string to a function key. +See +.Xr keyboard 4 +and +.Xr kbdmap 5 +for the keymap file. +.Pp +You may want to set the +.Ar keymap +variable in +.Pa /etc/rc.conf.local +to the desired keymap file so that it will be automatically loaded +when the system starts up. +.Ss Software Font +For most modern video cards, e.g., VGA, the +.Nm +driver and the video card driver allow the user to change +the font used on the screen. +The +.Xr vidcontrol 1 +command can be used to load a font file from +.Pa /usr/share/syscons/fonts . +.Pp +The font comes in various sizes: 8x8, 8x14 and 8x16. +The 8x16 font is typically used for the VGA card in the +80-column-by-25-line mode. +Other video modes may require different font sizes. +It is better to always load all three sizes of the same font. +.Pp +You may set +.Ar font8x8 , +.Ar font8x14 +and +.Ar font8x16 +variables in +.Pa /etc/rc.conf +to the desired font files so that they will be automatically loaded +when the system starts up. +.Pp +Optionally you can specify a particular font file as the default. +See the +.Dv SC_DFLT_FONT +option below. +.Ss Screen Map +If your video card does not support software fonts, you may still be able +to achieve a similar effect by re-mapping the font built into your video card. +Use +.Xr vidcontrol 1 +to load a screen map file which defines the mapping between character codes. +.Ss Mouse Support and Copy-and-Paste +You can use your mouse to copy text on the screen and paste it as if +it was typed by hand. +You must be running the mouse daemon +.Xr moused 8 +and enable the mouse cursor in the virtual terminal via +.Xr vidcontrol 1 . +.Pp +Pressing mouse button 1 (usually the left button) will start selection. +Releasing button 1 will end the selection process. +The selected text will be marked by inverting foreground and +background colors. +You can press button 3 (usually the right button) to extend +the selected region. +The selected text is placed in the copy buffer and can be pasted +at the cursor position by pressing button 2 (usually the +middle button) as many times as you like. +.Pp +If your mouse has only two buttons, you may want to use the +.Dv SC_TWOBUTTON_MOUSE +option below to make the right button to paste the text. +Alternatively you can make the mouse daemon +emulate the middle button. +See the man page for +.Xr moused 8 +for more details. +.Ss Back Scrolling +The +.Nm +driver allows the user to browse the output which has ``scrolled off'' +the top of the screen. +.Pp +Press the ``slock'' key (usually +.Dv ScrllLock +/ +.Dv Scroll Lock +or +.Dv Pause +on many keyboards) and the terminal is +in the ``scrollback'' mode. +It is indicated by the +.Dv Scroll Lock +LED. +Use the arrow keys, the +.Dv Page Up/Down +keys and the +.Dv Home/End +keys to scroll buffered terminal output. +Press the ``slock'' key again to get back to the normal terminal mode. +.Pp +The size of the scrollback buffer can be set by the +.Dv SC_HISTORY_SIZE +option described below. +.Ss Screen Saver +The +.Nm +driver can be made to put up the screen saver if the current +virtual terminal is idle, that is, the user is not typing +on the keyboard nor moving the mouse. +See +.Xr splash 4 +and +.Xr vidcontrol 1 +for more details. +.Sh DRIVER CONFIGURATION +.Ss Kernel Configuration Options +The following kernel configuration options control the +.Nm +driver. +.Bl -tag -width MOUSE +.It Dv MAXCONS=N +This option sets the number of virtual terminals to +.Fa N . +The default value is 16. +.It Dv SC_ALT_MOUSE_IMAGE +This option selects the alternative way of displaying the mouse cursor +in the virtual terminal. +It may be expensive for some video cards to draw the arrow-shaped +cursor, and you may want to try this option. +However, the appearance of the alternative mouse cursor may not be +very appealing. +Note that if you use the +.Dv SC_NO_FONT_LOADING +option then you must also use this option if you wish to be able to use +the mouse. +.It Dv SC_CUT_SEPCHARS=_characters_ +This options specifies characters that will be looked for when the +driver searches for words boundaries when doing cut operation. +By default, its value is +.Qq Li \ex20 +\(em a space character. +.It Dv SC_CUT_SPACES2TABS +This options instructs the driver to convert leading spaces into tabs +when copying data into cut buffer. +This might be useful to preserve +indentation when copying tab-indented text. +.It Dv SC_DFLT_TERM=_name_ +This option specifies the name of the preferred terminal emulator. +.It Dv SC_DISABLE_KDBKEY +This option disables the ``debug'' key combination (by default, it is +.Dv Alt-Esc , +or +.Dv Ctl-PrintScreen ) . +It will prevent users from +entering the kernel debugger (KDB) by pressing the key combination. +KDB will still be invoked when the kernel panics or hits a break point +if it is included in the kernel. +If this option is not defined, this behavior may be controlled at runtime +by the +.Xr sysctl 8 +variable +.Va hw.syscons.kbd_debug . +.It Dv SC_DISABLE_REBOOT +This option disables the ``reboot'' key (by default, it is +.Dv Ctl-Alt-Del ) , +so that the casual user may not accidentally reboot the system. +If this option is not defined, this behavior may be controlled at runtime +by the +.Xr sysctl 8 +variable +.Va hw.syscons.kbd_reboot . +.It Dv SC_HISTORY_SIZE=N +Sets the size of back scroll buffer to +.Fa N +lines. +The default value is 100. +.It Dv SC_MOUSE_CHAR=C +Unless the +.Dv SC_ALT_MOUSE_IMAGE +option above is specified, the +.Nm +driver reserves four consecutive character codes in order to display the +mouse cursor in the virtual terminals in some systems. +This option specifies the first character code to +.Fa C +to be used for this purpose. +The default value is 0xd0. +A good candidate is 0x03. +.It Dv SC_PIXEL_MODE +Adds support for pixel (raster) mode console. +This mode is useful on some laptop computers, but less so on +most other systems, and it adds substantial amount of code to syscons. +If this option is NOT defined, you can reduce the kernel size a lot. +See the +.Dv VESAMODE +flag below. +.It Dv SC_TWOBUTTON_MOUSE +If you have a two button mouse, you may want to add this option +to use the right button of the mouse to paste text. +See +.Sx Mouse Support and Copy-and-Paste +above. +.It Dv SC_NORM_ATTR=_attribute_ +.It Dv SC_NORM_REV_ATTR=_attribute_ +.It Dv SC_KERNEL_CONS_ATTR=_attribute_ +.It Dv SC_KERNEL_CONS_ATTRS=_attributes_ +.It Dv SC_KERNEL_CONS_REV_ATTR=_attribute_ +These options will set the default colors. +Available colors are defined in +.In machine/pc/display.h . +See +.Sx EXAMPLES +below. +.Dv SC_KERNEL_CONS_ATTRS +is a character string giving a sequence of attributes in binary format. +The sequence will be repeated up to the number of CPUs. +Beware that the string must not be null, +since the kernel divides by its length. +.It Dv SC_DFLT_FONT +This option will specify the default font. +Available fonts are: iso, iso2, koi8-r, koi8-u, cp437, cp850, cp865, +cp866 and cp866u. +16-line, 14-line and 8-line font data will be compiled in. +Without this option, the +.Nm +driver will use whatever font is already loaded in the video card, +unless you explicitly load a software font at startup. +See +.Sx EXAMPLES +below. +.It Dv SC_NO_SUSPEND_VTYSWITCH +This option, which is also available as +.Xr loader 8 +tunable and +.Xr sysctl 8 +variable +.Va hw.syscons.sc_no_suspend_vtswitch , +disables switching between virtual terminals (graphics <-> text) during +suspend/resume (ACPI and APM). +Use this option if your system is freezing +when you are running X and trying to suspend. +.El +.Pp +The following options will remove some features from the +.Nm +driver and save kernel memory. +.Bl -tag -width MOUSE +.It Dv SC_NO_CUTPASTE +This option disables ``copy and paste'' operation in virtual +terminals. +.It Dv SC_NO_FONT_LOADING +The +.Nm +driver can load software fonts on some video cards. +This option removes this feature. +Note that if you still wish to use +the mouse with this option then you must also use the +.Dv SC_ALT_MOUSE_IMAGE +option. +.It Dv SC_NO_HISTORY +This option disables back-scrolling in virtual terminals. +.\".It Dv SC_NO_PALETTE_LOADING +.It Dv SC_NO_SYSMOUSE +This option removes mouse support in the +.Nm +driver. +The mouse daemon +.Xr moused 8 +will fail if this option is defined. +This option implies the +.Dv SC_NO_CUTPASTE +option too. +.It Dv SC_NO_TERM_DUMB +.It Dv SC_NO_TERM_SC +.It Dv SC_NO_TERM_SCTEKEN +These options remove the +.Qq dumb , +.Qq sc , +and +.Qq scteken +terminal emulators, respectively. +.El +.Ss Driver Flags +The following driver flags can be used to control the +.Nm +driver. +Driver flags can be set with the +.Cd hint.sc.0.flags +tunable, either in +.Pa /boot/device.hints , +or else at the loader prompt (see +.Xr loader 8 ) . +.Bl -tag -width bit_0 +.\".It bit 0 (VISUAL_BELL) +.\"Uses the ``visual'' bell. +.\"The screen will blink instead of generating audible sound. +.\".It bit 1,2 (CURSOR_TYPE) +.\"This option specifies the cursor appearance. +.\"Possible values are: +.\".Bl -tag -width TYPE -compact +.\".It Dv 0 +.\"normal block cursor +.\".It Dv 2 +.\"blinking block cursor +.\".It Dv 4 +.\"underline cursor +.\".It Dv 6 +.\"blinking underline (aka destructive) cursor +.\".El +.\".It bit 6 (QUIET_BELL) +.\"This option suppresses the bell, whether audible or visual, +.\"if it is rung in a background virtual terminal. +.It 0x0080 (VESAMODE) +This option puts the video card in the VESA mode specified by +.Pa /boot/device.hints +variable +.Va vesa_mode +during kernel initialization. +Note that in order for this flag to work, the kernel must be +compiled with the +.Dv SC_PIXEL_MODE +option explained above. +A list of the available mode can be obtained via +.Xr vidcontrol 1 . +.\"Note also that the ``copy-and-paste'' function is not currently supported +.\"in this mode and the mouse pointer will not be displayed. +.It 0x0100 (AUTODETECT_KBD) +This option instructs the syscons driver to periodically scan +for a keyboard device if it is not currently attached to one. +Otherwise, the driver only probes for a keyboard once during bootup. +.El +.Ss Loader Tunables +These settings can be entered at the +.Xr loader 8 +prompt or in +.Xr loader.conf 5 . +.Bl -tag -width indent +.It Va kern.vty +When both +.Nm +and +.Xr vt 4 +have been compiled into the kernel, the one to use for the system console can +be selected by setting this variable to +.Ql sc +or +.Ql vt . +The +.Pa GENERIC +kernel uses +.Xr vt 4 +when this value is not set. +.El +.Sh FILES +.Bl -tag -width /usr/share/syscons/xxxxyyyyzzz -compact +.It Pa /dev/console +.It Pa /dev/consolectl +.It Pa /dev/ttyv? +virtual terminals +.It Pa /etc/ttys +terminal initialization information +.It Pa /usr/share/syscons/fonts/* +font files +.It Pa /usr/share/syscons/keymaps/* +key map files +.It Pa /usr/share/syscons/scrmaps/* +screen map files +.El +.Sh EXAMPLES +As the +.Nm +driver requires the keyboard driver and the video card driver, +the kernel configuration file should contain the following lines. +.Bd -literal -offset indent +device atkbdc +device atkbd +device vga +device sc +device splash +.Ed +.Pp +You also need the following lines in +.Pa /boot/device.hints +for these drivers. +.Bd -literal -offset indent +hint.atkbdc.0.at="isa" +hint.atkbdc.0.port="0x060" +hint.atkbd.0.at="atkbdc" +hint.atkbd.0.irq="1" +hint.vga.0.at="isa" +hint.sc.0.at="isa" +.Ed +.Pp +If you do not intend to load the splash image or use the screen saver, +the last line is not necessary, and can be omitted. +.Pp +Note that the keyboard controller driver +.Nm atkbdc +is required by the keyboard driver +.Nm atkbd . +.Pp +The following lines will set the default colors. +The normal text will be green on black background. +The reversed text will be yellow on green background. +Note that you cannot put any white space inside the quoted string, +because of the current implementation of +.Xr config 8 . +.Pp +.Dl "options SC_NORM_ATTR=(FG_GREEN|BG_BLACK)" +.Dl "options SC_NORM_REV_ATTR=(FG_YELLOW|BG_GREEN)" +.Pp +The following lines will set the default colors of the kernel message. +The kernel message will be printed bright red on black background. +The reversed message will be black on red background. +.Pp +.Dl "options SC_KERNEL_CONS_ATTR=(FG_LIGHTRED|BG_BLACK)" +.Dl "options SC_KERNEL_CONS_REV_ATTR=(FG_BLACK|BG_RED)" +.Pp +Provided +.Dv SC_KERNEL_CONS_ATTR +is not set, or is set to its default of bright white on black, +the following line will set 4 red-ish colors +for printing kernel messages in colors depending on the CPU. +.Pp +.Dl options SC_KERNEL_CONS_ATTRS=\e"\ex0c\ex04\ex40\ex0e\e" +.Pp +The default scheme is probably better for up to 8 CPUs. +Use a long string to get unique colors for more than 8 CPUs. +.Pp +To turn off all per-CPU coloring of kernel messages, +set SC_KERNEL_CONS_ATTR to a non-default value, +or use the default in a pattern of length 1. +.Pp +.Dl options SC_KERNEL_CONS_ATTRS=\e"\ex0f\e" +.Pp +The following example adds the font files +.Pa cp850-8x16.fnt , +.Pa cp850-8x14.font +and +.Pa cp850-8x8.font +to the kernel. +.Pp +.Dl "options SC_DFLT_FONT" +.Dl "makeoptions SC_DFLT_FONT=cp850" +.Dl "device sc" +.\".Sh DIAGNOSTICS +.Sh SEE ALSO +.Xr kbdcontrol 1 , +.Xr login 1 , +.Xr vidcontrol 1 , +.Xr atkbd 4 , +.Xr atkbdc 4 , +.Xr keyboard 4 , +.Xr screen 4 , +.Xr splash 4 , +.Xr ukbd 4 , +.Xr vga 4 , +.Xr vt 4 , +.Xr kbdmap 5 , +.Xr rc.conf 5 , +.Xr ttys 5 , +.Xr config 8 , +.Xr getty 8 , +.Xr kldload 8 , +.Xr moused 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 1.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An S\(/oren Schmidt Aq Mt sos@FreeBSD.org . +This manual page was written by +.An Kazutaka Yokota Aq Mt yokota@FreeBSD.org . +.Sh CAVEATS +The amount of data that is possible to insert from the cut buffer is limited +by the +.Brq Dv MAX_INPUT , +a system limit on the number of bytes that may be stored in the terminal +input queue - usually 1024 bytes +(see +.Xr termios 4 ) . +.Sh BUGS +This manual page is incomplete and urgently needs revision. diff --git a/static/freebsd/man4/sysmouse.4 b/static/freebsd/man4/sysmouse.4 new file mode 100644 index 00000000..2955fbbf --- /dev/null +++ b/static/freebsd/man4/sysmouse.4 @@ -0,0 +1,463 @@ +.\" Copyright 1997 John-Mark Gurney. 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 John-Mark Gurney 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 March 25, 2014 +.Dt SYSMOUSE 4 +.Os +.Sh NAME +.Nm sysmouse +.\" .Nd supplies mouse data from syscons for other applications +.Nd virtualized mouse driver +.Sh SYNOPSIS +.In sys/mouse.h +.In sys/consio.h +.Sh DESCRIPTION +The console driver, in conjunction with the mouse daemon +.Xr moused 8 , +supplies mouse data to the user process in the standardized way via the +.Nm +driver. +This arrangement makes it possible for the console and the user process +(such as the +.Tn X\ Window System ) +to share the mouse. +.Pp +The user process which wants to utilize mouse operation simply opens +.Pa /dev/sysmouse +with a +.Xr open 2 +call and reads +mouse data from the device via +.Xr read 2 . +Make sure that +.Xr moused 8 +is running, otherwise the user process will not see any data coming from +the mouse. +.Ss Operation Levels +The +.Nm +driver has two levels of operation. +The current operation level can be referred to and changed via ioctl calls. +.Pp +The level zero, the basic level, is the lowest level at which the driver +offers the basic service to user programs. +The +.Nm +driver +provides horizontal and vertical movement of the mouse +and state of up to three buttons in the +.Tn MouseSystems +format as follows. +.Pp +.Bl -tag -width Byte_1 -compact +.It Byte 1 +.Bl -tag -width bit_7 -compact +.It bit 7 +Always one. +.It bit 6..3 +Always zero. +.It bit 2 +Left button status; cleared if pressed, otherwise set. +.It bit 1 +Middle button status; cleared if pressed, otherwise set. +Always one, +if the device does not have the middle button. +.It bit 0 +Right button status; cleared if pressed, otherwise set. +.El +.It Byte 2 +The first half of horizontal movement count in two's complement; +\-128 through 127. +.It Byte 3 +The first half of vertical movement count in two's complement; +\-128 through 127. +.It Byte 4 +The second half of the horizontal movement count in two's complement; +\-128 through 127. +To obtain the full horizontal movement count, add +the byte 2 and 4. +.It Byte 5 +The second half of the vertical movement count in two's complement; +\-128 through 127. +To obtain the full vertical movement count, add +the byte 3 and 5. +.El +.Pp +At the level one, the extended level, mouse data is encoded +in the standard format +.Dv MOUSE_PROTO_SYSMOUSE +as defined in +.Xr mouse 4 . +.\" .Ss Acceleration +.\" The +.\" .Nm +.\" driver can somewhat `accelerate' the movement of the pointing device. +.\" The faster you move the device, the further the pointer +.\" travels on the screen. +.\" The driver has an internal variable which governs the effect of +.\" the acceleration. Its value can be modified via the driver flag +.\" or via an ioctl call. +.Sh IOCTLS +This section describes two classes of +.Xr ioctl 2 +commands: +commands for the +.Nm +driver itself, and commands for the console and the console control drivers. +.Ss Sysmouse Ioctls +There are a few commands for mouse drivers. +General description of the commands is given in +.Xr mouse 4 . +Following are the features specific to the +.Nm +driver. +.Pp +.Bl -tag -width MOUSE -compact +.It Dv MOUSE_GETLEVEL Ar int *level +.It Dv MOUSE_SETLEVEL Ar int *level +These commands manipulate the operation level of the mouse driver. +.Pp +.It Dv MOUSE_GETHWINFO Ar mousehw_t *hw +Returns the hardware information of the attached device in the following +structure. +Only the +.Va iftype +field is guaranteed to be filled with the correct value in the current +version of the +.Nm +driver. +.Bd -literal +typedef struct mousehw { + int buttons; /* number of buttons */ + int iftype; /* I/F type */ + int type; /* mouse/track ball/pad... */ + int model; /* I/F dependent model ID */ + int hwid; /* I/F dependent hardware ID */ +} mousehw_t; +.Ed +.Pp +The +.Va buttons +field holds the number of buttons detected by the driver. +.Pp +The +.Va iftype +is always +.Dv MOUSE_IF_SYSMOUSE . +.Pp +The +.Va type +tells the device type: +.Dv MOUSE_MOUSE , +.Dv MOUSE_TRACKBALL , +.Dv MOUSE_STICK , +.Dv MOUSE_PAD , +or +.Dv MOUSE_UNKNOWN . +.Pp +The +.Va model +is always +.Dv MOUSE_MODEL_GENERIC +at the operation level 0. +It may be +.Dv MOUSE_MODEL_GENERIC +or one of +.Dv MOUSE_MODEL_XXX +constants at higher operation levels. +.Pp +The +.Va hwid +is always zero. +.Pp +.It Dv MOUSE_GETMODE Ar mousemode_t *mode +The command gets the current operation parameters of the mouse +driver. +.Bd -literal +typedef struct mousemode { + int protocol; /* MOUSE_PROTO_XXX */ + int rate; /* report rate (per sec) */ + int resolution; /* MOUSE_RES_XXX, -1 if unknown */ + int accelfactor; /* acceleration factor */ + int level; /* driver operation level */ + int packetsize; /* the length of the data packet */ + unsigned char syncmask[2]; /* sync. bits */ +} mousemode_t; +.Ed +.Pp +The +.Va protocol +field tells the format in which the device status is returned +when the mouse data is read by the user program. +It is +.Dv MOUSE_PROTO_MSC +at the operation level zero. +.Dv MOUSE_PROTO_SYSMOUSE +at the operation level one. +.Pp +The +.Va rate +is always set to \-1. +.Pp +The +.Va resolution +is always set to \-1. +.Pp +The +.Va accelfactor +is always 0. +.Pp +The +.Va packetsize +field specifies the length of the data packet. +It depends on the +operation level. +.Pp +.Bl -tag -width level_0__ -compact +.It Em level 0 +5 bytes +.It Em level 1 +8 bytes +.El +.Pp +The array +.Va syncmask +holds a bit mask and pattern to detect the first byte of the +data packet. +.Va syncmask[0] +is the bit mask to be ANDed with a byte. +If the result is equal to +.Va syncmask[1] , +the byte is likely to be the first byte of the data packet. +Note that this method of detecting the first byte is not 100% reliable; +thus, it should be taken only as an advisory measure. +.Pp +.It Dv MOUSE_SETMODE Ar mousemode_t *mode +The command changes the current operation parameters of the mouse driver +as specified in +.Ar mode . +Only +.Va level +may be modifiable. +Setting values in the other field does not generate +error and has no effect. +.Pp +.It Dv MOUSE_READDATA Ar mousedata_t *data +.It Dv MOUSE_READSTATE Ar mousedata_t *state +These commands are not supported by the +.Nm +driver. +.Pp +.It Dv MOUSE_GETSTATUS Ar mousestatus_t *status +The command returns the current state of buttons and +movement counts in the structure as defined in +.Xr mouse 4 . +.El +.Ss Console and Consolectl Ioctls +The user process issues console +.Fn ioctl +calls to the current virtual console in order to control +the mouse pointer. +The console +.Fn ioctl +also provides a method for the user process to receive a +.Xr signal 3 +when a button is pressed. +.Pp +The mouse daemon +.Xr moused 8 +uses +.Fn ioctl +calls to the console control device +.Pa /dev/consolectl +to inform the console of mouse actions including mouse movement +and button status. +.Pp +Both classes of +.Fn ioctl +commands are defined as +.Dv CONS_MOUSECTL +which takes the following argument. +.Bd -literal +struct mouse_info { + int operation; + union { + struct mouse_data data; + struct mouse_mode mode; + struct mouse_event event; + } u; +}; +.Ed +.Pp +.Bl -tag -width operation -compact +.It Va operation +This can be one of +.Pp +.Bl -tag -width MOUSE_MOVEABS -compact +.It Dv MOUSE_SHOW +Enables and displays mouse cursor. +.It Dv MOUSE_HIDE +Disables and hides mouse cursor. +.It Dv MOUSE_MOVEABS +Moves mouse cursor to position supplied in +.Va u.data . +.It Dv MOUSE_MOVEREL +Adds position supplied in +.Va u.data +to current position. +.It Dv MOUSE_GETINFO +Returns current mouse position in the current virtual console +and button status in +.Va u.data . +.It Dv MOUSE_MODE +This sets the +.Xr signal 3 +to be delivered to the current process when a button is pressed. +The signal to be delivered is set in +.Va u.mode . +.El +.Pp +The above operations are for virtual consoles. +The operations defined +below are for the console control device and are used by +.Xr moused 8 +to pass mouse data to the console driver. +.Pp +.Bl -tag -width MOUSE_MOVEABS -compact +.It Dv MOUSE_ACTION +.It Dv MOUSE_MOTION_EVENT +These operations take the information in +.Va u.data +and act upon it. +Mouse data will be sent to the +.Nm +driver if it is open. +.Dv MOUSE_ACTION +also processes button press actions and sends signal to the process if +requested or performs cut and paste operations +if the current console is a text interface. +.It Dv MOUSE_BUTTON_EVENT +.Va u.data +specifies a button and its click count. +The console driver will +use this information for signal delivery if requested or +for cut and paste operations if the console is in text mode. +.El +.Pp +.Dv MOUSE_MOTION_EVENT +and +.Dv MOUSE_BUTTON_EVENT +are newer interface and are designed to be used together. +They are intended to replace functions performed by +.Dv MOUSE_ACTION +alone. +.Pp +.It Va u +This union is one of +.Pp +.Bl -tag -width data -compact +.It Va data +.Bd -literal +struct mouse_data { + int x; + int y; + int z; + int buttons; +}; +.Ed +.Pp +.Va x , y +and +.Va z +represent movement of the mouse along respective directions. +.Va buttons +tells the state of buttons. +It encodes up to 31 buttons in the bit 0 though +the bit 30. +If a button is held down, the corresponding bit is set. +.Pp +.It Va mode +.Bd -literal +struct mouse_mode { + int mode; + int signal; +}; +.Ed +.Pp +The +.Va signal +field specifies the signal to be delivered to the process. +It must be +one of the values defined in +.In signal.h . +The +.Va mode +field is currently unused. +.Pp +.It Va event +.Bd -literal +struct mouse_event { + int id; + int value; +}; +.Ed +.Pp +The +.Va id +field specifies a button number as in +.Va u.data.buttons . +Only one bit/button is set. +The +.Va value +field +holds the click count: the number of times the user has clicked the button +successively. +.El +.El +.Sh FILES +.Bl -tag -width /dev/consolectl -compact +.It Pa /dev/consolectl +device to control the console +.It Pa /dev/sysmouse +virtualized mouse driver +.It Pa /dev/ttyv%d +virtual consoles +.El +.Sh SEE ALSO +.Xr vidcontrol 1 , +.Xr ioctl 2 , +.Xr signal 3 , +.Xr mouse 4 , +.Xr moused 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 2.2 . +.Sh AUTHORS +.An -nosplit +This +manual page was written by +.An John-Mark Gurney Aq Mt jmg@FreeBSD.org +and +.An Kazutaka Yokota Aq Mt yokota@FreeBSD.org . diff --git a/static/freebsd/man4/tap.4 b/static/freebsd/man4/tap.4 new file mode 100644 index 00000000..a4fe98cd --- /dev/null +++ b/static/freebsd/man4/tap.4 @@ -0,0 +1,333 @@ +.\" Based on PR#2411 +.\" +.Dd January 13, 2020 +.Dt TAP 4 +.Os +.Sh NAME +.Nm tap , +.Nm vmnet +.Nd Ethernet tunnel software network interface +.Sh SYNOPSIS +.Cd device tuntap +.Sh DESCRIPTION +The +.Nm +interface is a software loopback mechanism that can be loosely +described as the network interface analog of the +.Xr pty 4 , +that is, +.Nm +does for network interfaces what the +.Xr pty 4 +driver does for terminals. +.Pp +The +.Nm +driver, like the +.Xr pty 4 +driver, provides two interfaces: an interface like the usual facility +it is simulating +(an Ethernet network interface in the case of +.Nm , +or a terminal for +.Xr pty 4 ) , +and a character-special device +.Dq control +interface. +A client program transfers Ethernet frames to or from the +.Nm +.Dq control +interface. +The +.Xr tun 4 +interface provides similar functionality at the network layer: +a client will transfer IP (by default) packets to or from a +.Xr tun 4 +.Dq control +interface. +.Pp +The network interfaces are named +.Dq Li tap0 , +.Dq Li tap1 , +etc., one for each control device that has been opened. +These Ethernet network interfaces persist until +.Pa if_tuntap.ko +module is unloaded, or until removed with "ifconfig destroy" (see below). +.Pp +.Nm +devices are created using interface cloning. +This is done using the +.Dq ifconfig tap Ns Sy N No create +command. +This is the preferred method of creating +.Nm +devices. +The same method allows removal of interfaces. +For this, use the +.Dq ifconfig tap Ns Sy N No destroy +command. +.Pp +If the +.Xr sysctl 8 +variable +.Va net.link.tap.devfs_cloning +is non-zero, the +.Nm +interface +permits opens on the special control device +.Pa /dev/tap . +When this device is opened, +.Nm +will return a handle for the lowest unused +.Nm +device (use +.Xr devname 3 +to determine which). +.Pp +.Bf Em +Disabling the legacy devfs cloning functionality may break existing +applications which use +.Nm , +such as +.Tn VMware +and +.Xr ssh 1 . +It therefore defaults to being enabled until further notice. +.Ef +.Pp +Control devices (once successfully opened) persist until +.Pa if_tuntap.ko +is unloaded or the interface is destroyed. +.Pp +Each interface supports the usual Ethernet network interface +.Xr ioctl 2 Ns s +and thus can be used with +.Xr ifconfig 8 +like any other Ethernet interface. +When the system chooses to transmit +an Ethernet frame on the network interface, the frame can be read from +the control device +(it appears as +.Dq input +there); +writing an Ethernet frame to the control device generates an input frame on +the network interface, as if the +(non-existent) +hardware had just received it. +.Pp +The Ethernet tunnel device, normally +.Pa /dev/tap Ns Sy N , +is exclusive-open +(it cannot be opened if it is already open) +and is restricted to the super-user, unless the +.Xr sysctl 8 +variable +.Va net.link.tap.user_open +is non-zero. +If the +.Xr sysctl 8 +variable +.Va net.link.tap.up_on_open +is non-zero, the tunnel device will be marked +.Dq up +when the control device is opened. +A +.Fn read +call will return an error +.Pq Er EHOSTDOWN +if the interface is not +.Dq ready . +Once the interface is ready, +.Fn read +will return an Ethernet frame if one is available; if not, it will +either block until one is or return +.Er EWOULDBLOCK , +depending on whether non-blocking I/O has been enabled. +If the frame +is longer than is allowed for in the buffer passed to +.Fn read , +the extra data will be silently dropped. +.Pp +A +.Xr write 2 +call passes an Ethernet frame in to be +.Dq received +on the pseudo-interface. +Each +.Fn write +call supplies exactly one frame; the frame length is taken from the +amount of data provided to +.Fn write . +Writes will not block; if the frame cannot be accepted +for a transient reason +(e.g., no buffer space available), +it is silently dropped; if the reason is not transient +(e.g., frame too large), +an error is returned. +The following +.Xr ioctl 2 +calls are supported +(defined in +.In net/if_tap.h ) : +.Bl -tag -width VMIO_SIOCSETMACADDR +.It Dv TAPSIFINFO +Set network interface information (line speed and MTU). +The type must be the same as returned by +.Dv TAPGIFINFO +or set to +.Dv IFT_ETHER +else the +.Xr ioctl 2 +call will fail. +The argument should be a pointer to a +.Va struct tapinfo . +.It Dv TAPGIFINFO +Retrieve network interface information (line speed, MTU and type). +The argument should be a pointer to a +.Va struct tapinfo . +.It Dv TAPSDEBUG +The argument should be a pointer to an +.Va int ; +this sets the internal debugging variable to that value. +What, if +anything, this variable controls is not documented here; see the source +code. +.It Dv TAPGDEBUG +The argument should be a pointer to an +.Va int ; +this stores the internal debugging variable's value into it. +.It Dv TAPGIFNAME +Retrieve network interface name. +The argument should be a pointer to a +.Va struct ifreq . +The interface name will be returned in the +.Va ifr_name +field. +.It Dv TAPSTRANSIENT +The argument should be a pointer to an +.Va int ; +this sets the transient flag on +the +.Nm +device. +A transient +.Nm +will be destroyed upon last close. +.It Dv TAPGTRANSIENT +The argument should be a pointer to an +.Va int ; +this stores the current state (enabled or disabled) of the transient flag into +it. +.It Dv FIONBIO +Turn non-blocking I/O for reads off or on, according as the argument +.Va int Ns 's +value is or is not zero +(Writes are always nonblocking). +.It Dv FIOASYNC +Turn asynchronous I/O for reads +(i.e., generation of +.Dv SIGIO +when data is available to be read) +off or on, according as the argument +.Va int Ns 's +value is or is not zero. +.It Dv FIONREAD +If any frames are queued to be read, store the size of the first one into the argument +.Va int ; +otherwise, store zero. +.It Dv TIOCSPGRP +Set the process group to receive +.Dv SIGIO +signals, when asynchronous I/O is enabled, to the argument +.Va int +value. +.It Dv TIOCGPGRP +Retrieve the process group value for +.Dv SIGIO +signals into the argument +.Va int +value. +.It Dv SIOCGIFADDR +Retrieve the Media Access Control +.Pq Dv MAC +address of the +.Dq remote +side. +This command is used by the VMware port and expected to be executed on +descriptor, associated with control device +(usually +.Pa /dev/vmnet Ns Sy N +or +.Pa /dev/tap Ns Sy N ) . +The +.Va buffer , +which is passed as the argument, is expected to have enough space to store +the +.Dv MAC +address. +At the open time both +.Dq local +and +.Dq remote +.Dv MAC +addresses are the same, so this command could be used to retrieve the +.Dq local +.Dv MAC +address. +.It Dv SIOCSIFADDR +Set the Media Access Control +.Pq Dv MAC +address of the +.Dq remote +side. +This command is used by VMware port and expected to be executed on +a descriptor, associated with control device +(usually +.Pa /dev/vmnet Ns Sy N ) . +.El +.Pp +The control device also supports +.Xr select 2 +for read; selecting for write is pointless, and always succeeds, since +writes are always non-blocking. +.Pp +On the last close of the data device, the interface is +brought down +(as if with +.Dq ifconfig tap Ns Sy N No down ) +and has all of its configured addresses deleted +unless the device is a +.Em VMnet +device, or has +.Dv IFF_LINK0 +flag set. +All queued frames are thrown away. +If the interface is up when the data +device is not open, output frames are thrown away rather than +letting them pile up. +.Pp +The +.Nm +device can also be used with the VMware port as a replacement +for the old +.Em VMnet +device driver. +.Em VMnet +devices do not +.Xr ifconfig 8 +themselves down when the +control device is closed. +Everything else is the same. +.Pp +In addition to the above mentioned +.Xr ioctl 2 +calls, there is an additional one for the VMware port. +.Bl -tag -width VMIO_SIOCSETMACADDR +.It Dv VMIO_SIOCSIFFLAGS +VMware +.Dv SIOCSIFFLAGS . +.El +.Sh SEE ALSO +.Xr inet 4 , +.Xr intro 4 , +.Xr tun 4 diff --git a/static/freebsd/man4/tarfs.4 b/static/freebsd/man4/tarfs.4 new file mode 100644 index 00000000..1a2944de --- /dev/null +++ b/static/freebsd/man4/tarfs.4 @@ -0,0 +1,126 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2022 Klara, Inc. +.\" +.\" 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 February 14, 2023 +.Dt TARFS 4 +.Os +.Sh NAME +.Nm tarfs +.Nd tarball filesystem +.Sh SYNOPSIS +To compile this driver into the kernel, place the following line in +your kernel configuration file: +.Bd -ragged -offset indent +.Cd "options TARFS" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the +following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +tarfs_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver implements a read-only filesystem backed by a +.Xr tar 5 +file. +Currently, only POSIX archives, optionally compressed with +.Xr zstd 1 , +are supported. +.Pp +The preferred I/O size for +.Nm +filesystems can be adjusted using the +.Va vfs.tarfs.ioshift +sysctl setting and tunable. +Setting it to 0 will reset it to its default value. +Note that changes to this setting only apply to filesystems mounted +after the change. +.Pp +When the backing tar file is compressed with +.Xr zstd 1 , +I/O performance can be improved by ensuring that compressed data is +broken up into multiple frames. +This helps minimize unnecessary decompression work. +When using +.Xr bsdtar 1 +to create the tar file, this can be achieved using the +.Cm zstd:max-frame-size +and +.Cm zstd:frame-per-file +options. +Sensible frame sizes are powers of 2 between the system's base page size +(see +.Xr arch 7 ) +and the value of the +.Sy kern.maxphys +sysctl. +Smaller frames will generally yield a worse compression ratio and require extra +kernel memory to maintain an index, and larger frames will on average require +more CPU time to access data when performing random I/O. +.Sh DIAGNOSTICS +If enabled by the +.Dv TARFS_DEBUG +kernel option, the +.Va vfs.tarfs.debug +sysctl setting can be used to control debugging output from the +.Nm +driver. +Debugging output for individual sections of the driver can be enabled +by adding together the relevant values from the table below. +.Bl -column Value Description +.It 0x01 Ta Memory allocations +.It 0x02 Ta Checksum calculations +.It 0x04 Ta Filesystem operations (vfsops) +.It 0x08 Ta Path lookups +.It 0x10 Ta File operations (vnops) +.It 0x20 Ta General I/O +.It 0x40 Ta Decompression +.It 0x80 Ta Decompression index +.It 0x100 Ta Sparse file mapping +.It 0x200 Ta Bounce buffer usage +.El +.Sh SEE ALSO +.Xr tar 1 , +.Xr zstd 1 , +.Xr fstab 5 , +.Xr tar 5 , +.Xr mount 8 , +.Xr sysctl 8 +.Sh HISTORY +.An -nosplit +The +.Nm +driver was developed by +.An Stephen J. Kiernan Aq Mt stevek@FreeBSD.org +and +.An Dag-Erling Smørgrav Aq Mt des@FreeBSD.org +for Juniper Networks and Klara Systems. +This manual page was written by +.An Dag-Erling Smørgrav Aq Mt des@FreeBSD.org +for Juniper Networks and Klara Systems. diff --git a/static/freebsd/man4/targ.4 b/static/freebsd/man4/targ.4 new file mode 100644 index 00000000..543597c8 --- /dev/null +++ b/static/freebsd/man4/targ.4 @@ -0,0 +1,150 @@ +.\" Copyright (c) 2002 +.\" Nate Lawson. 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. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Nate Lawson 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 December 13, 2011 +.Dt TARG 4 +.Os +.Sh NAME +.Nm targ +.Nd SCSI target emulator driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device targ" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides an interface for usermode programs to emulate SCSI target +devices. +A sample program that emulates a disk drive (similar to +.Xr da 4 ) +can be found in +.Pa /usr/share/examples/scsi_target . +.Pp +The +.Nm +driver supplies the control device +.Pa /dev/targ . +After opening the device, the file descriptor must be bound to a +specific bus/target/LUN and enabled to process CCBs using the +.Dv TARGIOCENABLE +ioctl. +The process then uses +.Xr write 2 +to send CCBs to the SIM and +.Xr poll 2 +or +.Xr kqueue 2 +to see if responses are ready. +Pointers to completed CCBs are returned via +.Xr read 2 . +Any data transfers requested by the user CCBs are done via zero-copy IO. +.Sh IOCTLS +The following +.Xr ioctl 2 +calls are defined in the header file +.In cam/scsi/scsi_targetio.h . +.Bl -tag -width ".Dv TARGIOCDISABLE" +.It Dv TARGIOCENABLE +.Pq Vt "struct ioc_enable_lun" +Enable target mode on the LUN specified by the following structure: +.Bd -literal -offset indent +struct ioc_enable_lun { + path_id_t path_id; + target_id_t target_id; + lun_id_t lun_id; + int grp6_len; + int grp7_len; +}; +.Ed +.Pp +The selected path (bus), target, and LUN must not already be in use or +.Er EADDRINUSE +is returned. +If +.Va grp6_len +or +.Va grp7_len +are non-zero, reception of vendor-specific commands +is enabled. +.It Dv TARGIOCDISABLE +Disable target mode and abort all pending CCBs. +The CCBs may optionally be read as they complete. +.Dv TARGIOCENABLE +can then be called to activate a different LUN. +Multiple disable calls have no effect. +The +.Xr close 2 +system call automatically disables target mode if enabled. +.It Dv TARGIOCDEBUG +.Pq Vt int +Enables +.Dv CAM_PERIPH +debugging if the argument is non-zero, otherwise disables +it. +.El +.Sh FILES +.Bl -tag -width ".Pa /sys/cam/scsi/scsi_target.c" -compact +.It In cam/scsi/scsi_targetio.h +describes the usermode interface. +.It Pa /sys/cam/scsi/scsi_target.c +is the driver source file. +.It Pa /dev/targ +is the control device. +.El +.Sh SEE ALSO +.Pa /usr/share/examples/scsi_target , +.Xr ahc 4 , +.Xr isp 4 , +.Xr scsi 4 +.Rs +.%T "FreeBSD Target Information" +.%U http://www.root.org/~nate/freebsd/ +.Re +.Sh AUTHORS +.An -nosplit +The +.Nm +driver first appeared in +.Fx 3.0 +and was written by +.An Justin T. Gibbs . +It was rewritten +for +.Fx 5.0 +by +.An Nate Lawson Aq Mt nate@root.org . +.Sh BUGS +Currently, only the +.Xr ahc 4 +and +.Xr isp 4 +drivers fully support target mode. +.Pp +The +.Xr ahc 4 +driver does not support tagged queuing in target mode. diff --git a/static/freebsd/man4/tcp.4 b/static/freebsd/man4/tcp.4 new file mode 100644 index 00000000..3c9f4ff8 --- /dev/null +++ b/static/freebsd/man4/tcp.4 @@ -0,0 +1,1160 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. +.\" Copyright (c) 2010-2011 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" Portions of this documentation were written at the Centre for Advanced +.\" Internet Architectures, Swinburne University of Technology, Melbourne, +.\" Australia by David Hayes under sponsorship from the FreeBSD Foundation. +.\" +.\" 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 September 5, 2025 +.Dt TCP 4 +.Os +.Sh NAME +.Nm tcp +.Nd Internet Transmission Control Protocol +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netinet/in.h +.In netinet/tcp.h +.Ft int +.Fn socket AF_INET SOCK_STREAM 0 +.Sh DESCRIPTION +The +.Tn TCP +protocol provides reliable, flow-controlled, two-way +transmission of data. +It is a byte-stream protocol used to +support the +.Dv SOCK_STREAM +abstraction. +.Tn TCP +uses the standard +Internet address format and, in addition, provides a per-host +collection of +.Dq "port addresses" . +Thus, each address is composed +of an Internet address specifying the host and network, +with a specific +.Tn TCP +port on the host identifying the peer entity. +.Pp +Sockets utilizing the +.Tn TCP +protocol are either +.Dq active +or +.Dq passive . +Active sockets initiate connections to passive +sockets. +By default, +.Tn TCP +sockets are created active; to create a +passive socket, the +.Xr listen 2 +system call must be used +after binding the socket with the +.Xr bind 2 +system call. +Only passive sockets may use the +.Xr accept 2 +call to accept incoming connections. +Only active sockets may use the +.Xr connect 2 +call to initiate connections. +.Pp +Passive sockets may +.Dq underspecify +their location to match +incoming connection requests from multiple networks. +This technique, termed +.Dq "wildcard addressing" , +allows a single +server to provide service to clients on multiple networks. +To create a socket which listens on all networks, the Internet +address +.Dv INADDR_ANY +must be bound. +The +.Tn TCP +port may still be specified +at this time; if the port is not specified, the system will assign one. +Once a connection has been established, the socket's address is +fixed by the peer entity's location. +The address assigned to the +socket is the address associated with the network interface +through which packets are being transmitted and received. +Normally, this address corresponds to the peer entity's network. +.Pp +.Tn TCP +supports a number of socket options which can be set with +.Xr setsockopt 2 +and tested with +.Xr getsockopt 2 : +.Bl -tag -width ".Dv TCP_FUNCTION_BLK" +.It Dv TCP_INFO +Information about a socket's underlying TCP session may be retrieved +by passing the read-only option +.Dv TCP_INFO +to +.Xr getsockopt 2 . +It accepts a single argument: a pointer to an instance of +.Vt "struct tcp_info" . +.Pp +This API is subject to change; consult the source to determine +which fields are currently filled out by this option. +.Fx +specific additions include +send window size, +receive window size, +and +bandwidth-controlled window space. +.It Dv TCP_CCALGOOPT +Set or query congestion control algorithm specific parameters. +See +.Xr mod_cc 4 +for details. +.It Dv TCP_CONGESTION +Select or query the congestion control algorithm that TCP will use for the +connection. +See +.Xr mod_cc 4 +for details. +.It Dv TCP_FASTOPEN +Enable or disable TCP Fast Open (TFO). +To use this option, the kernel must be built with the +.Dv TCP_RFC7413 +option. +.Pp +This option can be set on the socket either before or after the +.Xr listen 2 +is invoked. +Clearing this option on a listen socket after it has been set has no effect on +existing TFO connections or TFO connections in progress; it only prevents new +TFO connections from being established. +.Pp +For passively-created sockets, the +.Dv TCP_FASTOPEN +socket option can be queried to determine whether the connection was established +using TFO. +Note that connections that are established via a TFO +.Tn SYN , +but that fall back to using a non-TFO +.Tn SYN|ACK +will have the +.Dv TCP_FASTOPEN +socket option set. +.Pp +In addition to the facilities defined in RFC7413, this implementation supports a +pre-shared key (PSK) mode of operation in which the TFO server requires the +client to be in possession of a shared secret in order for the client to be able +to successfully open TFO connections with the server. +This is useful, for example, in environments where TFO servers are exposed to +both internal and external clients and only wish to allow TFO connections from +internal clients. +.Pp +In the PSK mode of operation, the server generates and sends TFO cookies to +requesting clients as usual. +However, when validating cookies received in TFO SYNs from clients, the server +requires the client-supplied cookie to equal +.Bd -literal -offset left +SipHash24(key=\fI16-byte-psk\fP, msg=\fIcookie-sent-to-client\fP) +.Ed +.Pp +Multiple concurrent valid pre-shared keys are supported so that time-based +rolling PSK invalidation policies can be implemented in the system. +The default number of concurrent pre-shared keys is 2. +.Pp +This can be adjusted with the +.Dv TCP_RFC7413_MAX_PSKS +kernel option. +.It Dv TCP_FUNCTION_BLK +Select or query the set of functions that TCP will use for this connection. +This allows a user to select an alternate TCP stack. +The alternate TCP stack must already be loaded in the kernel. +To list the available TCP stacks, see +.Va functions_available +in the +.Sx FIB support +TCP sockets are FIB-aware. +They inherit the FIB of the process which created the socket, or that of the +listening socket for sockets created by +.Xr accept 2 . +In particular, the FIB is not inherited from that of the interface where the +initiating SYN packet was received. +When an incoming connection request arrives to a listening socket, the initial +handshake also occurs in the FIB of the listening socket, not that of the +received packet. +.Pp +By default, a TCP listening socket can accept connections originating from any +FIB. +If the +.Va net.inet.tcp.bind_all_fibs +tunable is set to 0, a listening socket will only accept connections +originating +from the FIB's listening socket. +Connection requests from other FIBs will be treated as though there is no +listening socket for the destination address and port. +In this mode, multiple listening sockets owned by the same user can listen on +the same address and port so long as they belong to different FIBs, similar to +the behavior of the +.Dv SO_REUSEPORT +socket option. +If the tunable is set to 0, all sockets added to a load-balancing group created +with the +.Dv SO_REUSEPORT_LB +socket option must belong to the same FIB. +.Sx MIB (sysctl) Variables +section further down. +To list the default TCP stack, see +.Va functions_default +in the +.Sx MIB (sysctl) Variables +section. +.It Dv TCP_KEEPINIT +This +.Xr setsockopt 2 +option accepts a per-socket timeout argument of +.Vt "u_int" +in seconds, for new, non-established +.Tn TCP +connections. +For the global default in milliseconds see +.Va keepinit +in the +.Sx MIB (sysctl) Variables +section further down. +.It Dv TCP_KEEPIDLE +This +.Xr setsockopt 2 +option accepts an argument of +.Vt "u_int" +for the amount of time, in seconds, that the connection must be idle +before keepalive probes (if enabled) are sent for the connection of this +socket. +If set on a listening socket, the value is inherited by the newly created +socket upon +.Xr accept 2 . +For the global default in milliseconds see +.Va keepidle +in the +.Sx MIB (sysctl) Variables +section further down. +.It Dv TCP_KEEPINTVL +This +.Xr setsockopt 2 +option accepts an argument of +.Vt "u_int" +to set the per-socket interval, in seconds, between keepalive probes sent +to a peer. +If set on a listening socket, the value is inherited by the newly created +socket upon +.Xr accept 2 . +For the global default in milliseconds see +.Va keepintvl +in the +.Sx MIB (sysctl) Variables +section further down. +.It Dv TCP_KEEPCNT +This +.Xr setsockopt 2 +option accepts an argument of +.Vt "u_int" +and allows a per-socket tuning of the number of probes sent, with no response, +before the connection will be dropped. +If set on a listening socket, the value is inherited by the newly created +socket upon +.Xr accept 2 . +For the global default see the +.Va keepcnt +in the +.Sx MIB (sysctl) Variables +section further down. +.It Dv TCP_NODELAY +Under most circumstances, +.Tn TCP +sends data when it is presented; +when outstanding data has not yet been acknowledged, it gathers +small amounts of output to be sent in a single packet once +an acknowledgement is received. +For a small number of clients, such as window systems +that send a stream of mouse events which receive no replies, +this packetization may cause significant delays. +The boolean option +.Dv TCP_NODELAY +defeats this algorithm. + +.It Dv TCP_MAXSEG +By default, a sender- and +.No receiver- Ns Tn TCP +will negotiate among themselves to determine the maximum segment size +to be used for each connection. +The +.Dv TCP_MAXSEG +option allows the user to determine the result of this negotiation, +and to reduce it if desired. +.It Dv TCP_MAXUNACKTIME +This +.Xr setsockopt 2 +option accepts an argument of +.Vt "u_int" +to set the per-socket interval, in seconds, in which the connection must +make progress. Progress is defined by at least 1 byte being acknowledged within +the set time period. If a connection fails to make progress, then the +.Tn TCP +stack will terminate the connection with a reset. Note that the default +value for this is zero which indicates no progress checks should be made. +.It Dv TCP_NOOPT +.Tn TCP +usually sends a number of options in each packet, corresponding to +various +.Tn TCP +extensions which are provided in this implementation. +The boolean option +.Dv TCP_NOOPT +is provided to disable +.Tn TCP +option use on a per-connection basis. +.It Dv TCP_NOPUSH +By convention, the +.No sender- Ns Tn TCP +will set the +.Dq push +bit, and begin transmission immediately (if permitted) at the end of +every user call to +.Xr write 2 +or +.Xr writev 2 . +When this option is set to a non-zero value, +.Tn TCP +will delay sending any data at all until either the socket is closed, +or the internal send buffer is filled. +.It Dv TCP_MD5SIG +This option enables the use of MD5 digests (also known as TCP-MD5) +on writes to the specified socket. +Outgoing traffic is digested; +digests on incoming traffic are verified. +When this option is enabled on a socket, all inbound and outgoing +TCP segments must be signed with MD5 digests. +.Pp +One common use for this in a +.Fx +router deployment is to enable +based routers to interwork with Cisco equipment at peering points. +Support for this feature conforms to RFC 2385. +.Pp +In order for this option to function correctly, it is necessary for the +administrator to add a tcp-md5 key entry to the system's security +associations database (SADB) using the +.Xr setkey 8 +utility. +This entry can only be specified on a per-host basis at this time. +.Pp +If an SADB entry cannot be found for the destination, +the system does not send any outgoing segments and drops any inbound segments. +However, during connection negotiation, a non-signed segment will be accepted if +an SADB entry does not exist between hosts. +When a non-signed segment is accepted, the established connection is not +protected with MD5 digests. +.It Dv TCP_STATS +Manage collection of connection level statistics using the +.Xr stats 3 +framework. +.Pp +Each dropped segment is taken into account in the TCP protocol statistics. +.It Dv TCP_TXTLS_ENABLE +Enable in-kernel Transport Layer Security (TLS) for data written to this +socket. +See +.Xr ktls 4 +for more details. +.It Dv TCP_TXTLS_MODE +The integer argument can be used to get or set the current TLS transmit mode +of a socket. +See +.Xr ktls 4 +for more details. +.It Dv TCP_RXTLS_ENABLE +Enable in-kernel TLS for data read from this socket. +See +.Xr ktls 4 +for more details. +.It Dv TCP_REUSPORT_LB_NUMA +Changes NUMA affinity filtering for an established TCP listen +socket. +This option takes a single integer argument which specifies +the NUMA domain to filter on for this listen socket. +The argument can also have the following special values: +.Bl -tag -width "Dv TCP_REUSPORT_LB_NUMA" +.It Dv TCP_REUSPORT_LB_NUMA_NODOM +Remove NUMA filtering for this listen socket. +.It Dv TCP_REUSPORT_LB_NUMA_CURDOM +Filter traffic associated with the domain where the calling thread is +currently executing. +This is typically used after a process or thread inherits a listen +socket from its parent, and sets its CPU affinity to a particular core. +.El +.It Dv TCP_REMOTE_UDP_ENCAPS_PORT +Set and get the remote UDP encapsulation port. +It can only be set on a closed TCP socket. +.El +.Pp +The option level for the +.Xr setsockopt 2 +call is the protocol number for +.Tn TCP , +available from +.Xr getprotobyname 3 , +or +.Dv IPPROTO_TCP . +All options are declared in +.In netinet/tcp.h . +.Pp +Options at the +.Tn IP +transport level may be used with +.Tn TCP ; +see +.Xr ip 4 . +Incoming connection requests that are source-routed are noted, +and the reverse source route is used in responding. +.Pp +The default congestion control algorithm for +.Tn TCP +is +.Xr cc_cubic 4 . +Other congestion control algorithms can be made available using the +.Xr mod_cc 4 +framework. +.Ss MIB (sysctl) Variables +The +.Tn TCP +protocol implements a number of variables in the +.Va net.inet.tcp +branch of the +.Xr sysctl 3 +MIB, which can also be read or modified with +.Xr sysctl 8 . +.Bl -tag -width ".Va v6pmtud_blackhole_mss" +.It Va ack_war_timewindow , ack_war_cnt +The challenge ACK throttling algorithm defined in RFC 5961 limits +the number of challenge ACKs sent per TCP connection to +.Va ack_war_cnt +during the time interval specified in milliseconds by +.Va ack_war_timewindow . +Setting +.Va ack_war_timewindow +or +.Va ack_war_cnt +to zero disables challenge ACK throttling. +.It Va always_keepalive +Assume that +.Dv SO_KEEPALIVE +is set on all +.Tn TCP +connections, the kernel will +periodically send a packet to the remote host to verify the connection +is still up. +.It Va blackhole +If enabled, disable sending of RST when a connection is attempted +to a port where there is no socket accepting connections. +See +.Xr blackhole 4 . +.It Va blackhole_local +See +.Xr blackhole 4 . +.It Va cc +A number of variables for congestion control are under the +.Va net.inet.tcp.cc +node. +See +.Xr mod_cc 4 . +.It Va cc.newreno +Variables for NewReno congestion control are under the +.Va net.inet.tcp.cc.newreno +node. +See +.Xr cc_newreno 4 . +.It Va delacktime +Maximum amount of time, in milliseconds, before a delayed ACK is sent. +.It Va delayed_ack +Delay ACK to try and piggyback it onto a data packet or another ACK. +.It Va do_prr +Perform SACK loss recovery using the Proportional Rate Reduction (PRR) algorithm +described in RFC6937. +This improves the effectiveness of retransmissions particular in environments +with ACK thinning or burst loss events, as chances to run out of the ACK clock +are reduced, preventing lengthy and performance reducing RTO based loss recovery +(default is true). +.It Va do_tcpdrain +Flush packets in the +.Tn TCP +reassembly queue if the system is low on mbufs. +.It Va drop_synfin +Drop TCP packets with both SYN and FIN set. +.It Va ecn.enable +Enable support for TCP Explicit Congestion Notification (ECN). +ECN allows a TCP sender to reduce the transmission rate in order to +avoid packet drops. +.Bl -tag -compact +.It 0 +Disable ECN. +.It 1 +Allow incoming connections to request ECN. +Outgoing connections will request ECN. +.It 2 +Allow incoming connections to request ECN. +Outgoing connections will not request ECN. +(default) +.It 3 +Negotiate on incoming connection for Accurate ECN, ECN, or no ECN. +Outgoing connections will request Accurate ECN and fall back to +ECN depending on the capabilities of the server. +.It 4 +Negotiate on incoming connection for Accurate ECN, ECN, or no ECN. +Outgoing connections will not request ECN. +.El +.It Va ecn.maxretries +Number of retries (SYN or SYN/ACK retransmits) before disabling ECN on a +specific connection. +This is needed to help with connection establishment +when a broken firewall is in the network path. +.It Va fast_finwait2_recycle +Recycle +.Tn TCP +.Dv FIN_WAIT_2 +connections faster when the socket is marked as +.Dv SBS_CANTRCVMORE +(no user process has the socket open, data received on +the socket cannot be read). +The timeout used here is +.Va finwait2_timeout . +.It Va fastopen.acceptany +When non-zero, all client-supplied TFO cookies will be considered to be valid. +The default is 0. +.It Va fastopen.autokey +When this and +.Va net.inet.tcp.fastopen.server_enable +are non-zero, a new key will be automatically generated after this specified +seconds. +The default is 120. +.It Va fastopen.ccache_bucket_limit +The maximum number of entries in a client cookie cache bucket. +The default value can be tuned with the +.Dv TCP_FASTOPEN_CCACHE_BUCKET_LIMIT_DEFAULT +kernel option or by setting +.Va net.inet.tcp.fastopen_ccache_bucket_limit +in the +.Xr loader 8 . +.It Va fastopen.ccache_buckets +The number of client cookie cache buckets. +Read-only. +The value can be tuned with the +.Dv TCP_FASTOPEN_CCACHE_BUCKETS_DEFAULT +kernel option or by setting +.Va fastopen.ccache_buckets +in the +.Xr loader 8 . +.It Va fastopen.ccache_list +Print the client cookie cache. +Read-only. +.It Va fastopen.client_enable +When zero, no new active (i.e., client) TFO connections can be created. +On the transition from enabled to disabled, the client cookie cache is cleared +and disabled. +The transition from enabled to disabled does not affect any active TFO +connections in progress; it only prevents new ones from being established. +The default is 0. +.It Va fastopen.keylen +The key length in bytes. +Read-only. +.It Va fastopen.maxkeys +The maximum number of keys supported. +Read-only, +.It Va fastopen.maxpsks +The maximum number of pre-shared keys supported. +Read-only. +.It Va fastopen.numkeys +The current number of keys installed. +Read-only. +.It Va fastopen.numpsks +The current number of pre-shared keys installed. +Read-only. +.It Va fastopen.path_disable_time +When a failure occurs while trying to create a new active (i.e., client) TFO +connection, new active connections on the same path, as determined by the tuple +.Brq client_ip, server_ip, server_port , +will be forced to be non-TFO for this many seconds. +Note that the path disable mechanism relies on state stored in client cookie +cache entries, so it is possible for the disable time for a given path to be +reduced if the corresponding client cookie cache entry is reused due to resource +pressure before the disable period has elapsed. +The default is +.Dv TCP_FASTOPEN_PATH_DISABLE_TIME_DEFAULT . +.It Va fastopen.psk_enable +When non-zero, pre-shared key (PSK) mode is enabled for all TFO servers. +On the transition from enabled to disabled, all installed pre-shared keys are +removed. +The default is 0. +.It Va fastopen.server_enable +When zero, no new passive (i.e., server) TFO connections can be created. +On the transition from enabled to disabled, all installed keys and pre-shared +keys are removed. +On the transition from disabled to enabled, if +.Va fastopen.autokey +is non-zero and there are no keys installed, a new key will be generated +immediately. +The transition from enabled to disabled does not affect any passive TFO +connections in progress; it only prevents new ones from being established. +The default is 0. +.It Va fastopen.setkey +Install a new key by writing +.Va net.inet.tcp.fastopen.keylen +bytes to this sysctl. +.It Va fastopen.setpsk +Install a new pre-shared key by writing +.Va net.inet.tcp.fastopen.keylen +bytes to this sysctl. +.It Va finwait2_timeout +Timeout to use for fast recycling of +.Tn TCP +.Dv FIN_WAIT_2 +connections +.Pq Va fast_finwait2_recycle . +Defaults to 60 seconds. +.It Va functions_available +List of available TCP function blocks (TCP stacks). +.It Va functions_default +The default TCP function block (TCP stack). +.It Va hostcache +The TCP host cache is used to cache connection details and metrics to +improve future performance of connections between the same hosts. +At the completion of a TCP connection, a host will cache information +for the connection for some defined period of time. +There are a number of +.Va hostcache +variables under this node. +See +.Va hostcache.enable . +.It Va hostcache.bucketlimit +The maximum number of entries for the same hash. +Defaults to 30. +.It Va hostcache.cachelimit +Overall entry limit for hostcache. +Defaults to +.Va hashsize +* +.Va bucketlimit . +.It Va hostcache.count +The current number of entries in the host cache. +.It Va hostcache.enable +Enable/disable the host cache: +.Bl -tag -compact +.It 0 +Disable the host cache. +.It 1 +Enable the host cache. (default) +.El +.It Va hostcache.expire +Time in seconds, how long a entry should be kept in the +host cache since last accessed. +Defaults to 3600 (1 hour). +.It Va hostcache.hashsize +Size of TCP hostcache hashtable. +This number has to be a power of two, or will be rejected. +Defaults to 512. +.It Va hostcache.histo +Provide a Histogram of the hostcache hash utilization. +.It Va hostcache.list +Provide a complete list of all current entries in the host +cache. +.It Va hostcache.prune +Time in seconds between pruning expired host cache entries. +Defaults to 300 (5 minutes). +.It Va hostcache.purge +Expire all entries on next pruning of host cache entries. +Any non-zero setting will be reset to zero, once the purge +is running. +.Bl -tag -compact +.It 0 +Do not purge all entries when pruning the host cache (default). +.It 1 +Purge all entries when doing the next pruning. +.It 2 +Purge all entries and also reseed the hash salt. +.El +.It Va hostcache.purgenow +Immediately purge all entries once set to any value. +Setting this to 2 will also reseed the hash salt. +.It Va icmp_may_rst +Certain +.Tn ICMP +unreachable messages may abort connections in +.Tn SYN-SENT +state. +.It Va initcwnd_segments +Enable the ability to specify initial congestion window in number of segments. +The default value is 10 as suggested by RFC 6928. +Changing the value on the fly would not affect connections +using congestion window from the hostcache. +Caution: +This regulates the burst of packets allowed to be sent in the first RTT. +The value should be relative to the link capacity. +Start with small values for lower-capacity links. +Large bursts can cause buffer overruns and packet drops if routers have small +buffers or the link is experiencing congestion. +.It Va insecure_rst +Use criteria defined in RFC793 instead of RFC5961 for accepting RST segments. +Default is false. +.It Va insecure_syn +Use criteria defined in RFC793 instead of RFC5961 for accepting SYN segments. +Default is false. +.It Va insecure_ack +Use criteria defined in RFC793 for validating SEG.ACK. +Default is false. +.It Va isn_reseed_interval +The interval (in seconds) specifying how often the secret data used in +RFC 1948 initial sequence number calculations should be reseeded. +By default, this variable is set to zero, indicating that +no reseeding will occur. +Reseeding should not be necessary, and will break +.Dv TIME_WAIT +recycling for a few minutes. +.It Va keepcnt +Number of keepalive probes sent, with no response, before a connection +is dropped. +The default is 8 packets. +.It Va keepidle +Amount of time, in milliseconds, that the connection must be idle +before sending keepalive probes (if enabled). +The default is 7200000 msec (7.2M msec, 2 hours). +.It Va keepinit +Timeout, in milliseconds, for new, non-established +.Tn TCP +connections. +The default is 75000 msec (75K msec, 75 sec). +.It Va keepintvl +The interval, in milliseconds, between keepalive probes sent to remote +machines, when no response is received on a +.Va keepidle +probe. +The default is 75000 msec (75K msec, 75 sec). +.It Va log_in_vain +Log any connection attempts to ports where there is no socket +accepting connections. +The value of 1 limits the logging to +.Tn SYN +(connection establishment) packets only. +A value of 2 results in any +.Tn TCP +packets to closed ports being logged. +Any value not listed above disables the logging +(default is 0, i.e., the logging is disabled). +.It Va minmss +Minimum TCP Maximum Segment Size; used to prevent a denial of service attack +from an unreasonably low MSS. +.It Va msl +The Maximum Segment Lifetime, in milliseconds, for a packet. +.It Va msl_local +The Maximum Segment Lifetime, in milliseconds, for a packet when both endpoints +are local. +.Va msl_local +is only used if +.Va nolocaltimewait , +which is deprecated, is zero. +.It Va mssdflt +The default value used for the TCP Maximum Segment Size +.Pq Dq MSS +for IPv4 when no advice to the contrary is received from MSS negotiation. +.It Va newcwv +Enable the New Congestion Window Validation mechanism as described in RFC 7661. +This gently reduces the congestion window during periods, where TCP is +application limited and the network bandwidth is not utilized completely. +That prevents self-inflicted packet losses once the application starts to +transmit data at a higher speed. +.It Va nolocaltimewait +Suppress the creation of TCP +.Dv TIME_WAIT +states for connections in +which both endpoints are local. +The default is 0. +.Va nolocaltimewait +is deprecated and will be removed in +.Fx 16 . +.Va msl_local +can be used instead. +.It Va path_mtu_discovery +Enable Path MTU Discovery. +.It Va pcbcount +Number of active protocol control blocks +(read-only). +.It Va perconn_stats_enable +Controls the default collection of statistics for all connections using the +.Xr stats 3 +framework. +0 disables, 1 enables, 2 enables random sampling across log id connection +groups with all connections in a group receiving the same setting. +.It Va perconn_stats_sample_rates +A CSV list of template_spec=percent key-value pairs which controls the per +template sampling rates when +.Xr stats 3 +sampling is enabled. +.It Va persmax +Maximum persistence interval, msec. +.It Va persmin +Minimum persistence interval, msec. +.It Va pmtud_blackhole_detection +Enable automatic path MTU blackhole detection. +In case of retransmits of MSS sized segments, +the OS will lower the MSS to check if it's an MTU problem. +If the current MSS is greater than the configured value to try +.Po Va net.inet.tcp.pmtud_blackhole_mss +and +.Va net.inet.tcp.v6pmtud_blackhole_mss +.Pc , +it will be set to this value, otherwise, +the MSS will be set to the default values +.Po Va net.inet.tcp.mssdflt +and +.Va net.inet.tcp.v6mssdflt +.Pc . +Settings: +.Bl -tag -compact +.It 0 +Disable path MTU blackhole detection. +.It 1 +Enable path MTU blackhole detection for IPv4 and IPv6. +.It 2 +Enable path MTU blackhole detection only for IPv4. +.It 3 +Enable path MTU blackhole detection only for IPv6. +.El +.It Va pmtud_blackhole_mss +MSS to try for IPv4 if PMTU blackhole detection is turned on. +.It Va reass.cursegments +The current total number of segments present in all reassembly queues. +.It Va reass.maxqueuelen +The maximum number of segments allowed in each reassembly queue. +By default, the system chooses a limit based on each TCP connection's +receive buffer size and maximum segment size (MSS). +The actual limit applied to a session's reassembly queue will be the lower of +the system-calculated automatic limit and the user-specified +.Va reass.maxqueuelen +limit. +.It Va reass.maxsegments +The maximum limit on the total number of segments across all reassembly +queues. +The limit can be adjusted as a tunable. +.It Va recvbuf_auto +Enable automatic receive buffer sizing as a connection progresses. +.It Va recvbuf_max +Maximum size of automatic receive buffer. +.It Va recvspace +Initial +.Tn TCP +receive window (buffer size). +.It Va retries +Maximum number of consecutive timer based retransmits sent after a data +segment is lost (default and maximum is 12). +.It Va rexmit_drop_options +Drop TCP options from third and later retransmitted SYN segments +of a connection. +.It Va rexmit_initial , rexmit_min , rexmit_slop , rexmit_max +Adjust the retransmit timer calculation for +.Tn TCP . +A new connection starts with timer set to +.Va rexmit_initial . +The +.Va rexmit_slop +typically added to the raw calculation to take into account +occasional variances that the +.Tn SRTT +(smoothed round-trip time) +is unable to accommodate, while the minimum specifies an +absolute minimum. +While a number of +.Tn TCP +RFCs suggest a 1 +second minimum, these RFCs tend to focus on streaming behavior, +and fail to deal with the fact that a 1 second minimum has severe +detrimental effects over lossy interactive connections, such +as a 802.11b wireless link, and over very fast but lossy +connections for those cases not covered by the fast retransmit +code. +For this reason, we use 200ms of slop and a near-0 +minimum, which gives us an effective minimum of 200ms (similar to +.Tn Linux ) . +The initial value is used before an RTT measurement has been performed. +The +.Va rexmit_min +and +.Va rexmit_max +set minimum and maximum timer values that a connection may have. +.It Va rfc1323 +Implement the window scaling and timestamp options of RFC 1323/RFC 7323 +(default is 1). +Settings: +.Bl -tag -compact +.It 0 +Disable window scaling and timestamp option. +.It 1 +Enable window scaling and timestamp option. +.It 2 +Enable only window scaling. +.It 3 +Enable only timestamp option. +.El +.It Va rfc3042 +Enable the Limited Transmit algorithm as described in RFC 3042. +It helps avoid timeouts on lossy links and also when the congestion window +is small, as happens on short transfers. +.It Va rfc3390 +Enable support for RFC 3390, which allows for a variable-sized +starting congestion window on new connections, depending on the +maximum segment size. +This helps throughput in general, but +particularly affects short transfers and high-bandwidth large +propagation-delay connections. +.It Va sack.enable +Enable support for RFC 2018, TCP Selective Acknowledgment option, +which allows the receiver to inform the sender about all successfully +arrived segments, allowing the sender to retransmit the missing segments +only. +.It Va sack.globalholes +Global number of TCP SACK holes currently allocated. +.It Va sack.globalmaxholes +Maximum number of SACK holes per system, across all connections. +Defaults to 65536. +.It Va sack.lrd +Enable Lost Retransmission Detection for SACK-enabled sessions, enabled by +default. +Under severe congestion, a retransmission can be lost which then leads to a +mandatory Retransmission Timeout (RTO), followed by slow-start. +LRD will try to resend the repeatedly lost packet, preventing the time-consuming +RTO and performance reducing slow-start or purge of the SACK scoreboard. +.It Va sack.maxholes +Maximum number of SACK holes per connection. +Defaults to 128. +.It Va sack.revised +Enables three updated mechanisms from RFC6675 (default is true). +Calculate the bytes in flight using the algorithm described in RFC 6675, and +is also an improvement when Proportional Rate Reduction is enabled. +Next, Rescue Retransmission helps timely loss recovery, when the trailing segments +of a transmission are lost, while no additional data is ready to be sent. +In case a partial ACK without a SACK block is received during SACK loss +recovery, the trailing segment is immediately resent, rather than waiting +for a Retransmission timeout. +Finally, SACK loss recovery is also engaged, once two segments plus one byte are +SACKed - even if no traditional duplicate ACKs were observed. +.Va sack.revised +is deprecated and will be removed in +.Fx 16 . +.Va sack.enable +will always follow RFC6675. +.It Va sendbuf_auto +Enable automatic send buffer sizing. +.It Va sendbuf_auto_lowat +Modify threshold for auto send buffer growth to account for +.Dv SO_SNDLOWAT . +.It Va sendbuf_inc +Incrementor step size of automatic send buffer. +.It Va sendbuf_max +Maximum size of automatic send buffer. +.It Va sendspace +Initial +.Tn TCP +send window (buffer size). +.It Va syncache +Variables under the +.Va net.inet.tcp.syncache +node are documented in +.Xr syncache 4 . +.It Va syncookies +Determines whether or not +.Tn SYN +cookies should be generated for outbound +.Tn SYN-ACK +packets. +.Tn SYN +cookies are a great help during +.Tn SYN +flood attacks, and are enabled by default. +(See +.Xr syncookies 4 . ) +.It Va syncookies_only +See +.Xr syncookies 4 . +.It Va tcbhashsize +Size of the +.Tn TCP +control-block hash table +(read-only). +This is tuned using the kernel option +.Dv TCBHASHSIZE +or by setting +.Va net.inet.tcp.tcbhashsize +in the +.Xr loader 8 . +.It Va tolerate_missing_ts +Tolerate the missing of timestamps (RFC 1323/RFC 7323) for +.Tn TCP +segments belonging to +.Tn TCP +connections for which support of +.Tn TCP +timestamps has been negotiated. +As of June 2021, several TCP stacks are known to violate RFC 7323, including +modern widely deployed ones. +Therefore the default is 1, i.e., the missing of timestamps is tolerated. +.It Va ts_offset_per_conn +When initializing the TCP timestamps, use a per connection offset instead of a +per host pair offset. +Default is to use per connection offsets as recommended in RFC 7323. +.It Va tso +Enable TCP Segmentation Offload. +.It Va udp_tunneling_overhead +The overhead taken into account when using UDP encapsulation. +Since MSS clamping by middleboxes will most likely not work, values larger than +8 (the size of the UDP header) are also supported. +Supported values are between 8 and 1024. +The default is 8. +.It Va udp_tunneling_port +The local UDP encapsulation port. +A value of 0 indicates that UDP encapsulation is disabled. +The default is 0. +.It Va v6mssdflt +The default value used for the TCP Maximum Segment Size +.Pq Dq MSS +for IPv6 when no advice to the contrary is received from MSS negotiation. +.It Va v6pmtud_blackhole_mss +MSS to try for IPv6 if PMTU blackhole detection is turned on. +See +.Va pmtud_blackhole_detection . +.El +.Sh ERRORS +A socket operation may fail with one of the following errors returned: +.Bl -tag -width Er +.It Bq Er EISCONN +when trying to establish a connection on a socket which +already has one; +.It Bo Er ENOBUFS Bc or Bo Er ENOMEM Bc +when the system runs out of memory for +an internal data structure; +.It Bq Er ETIMEDOUT +when a connection was dropped +due to excessive retransmissions; +.It Bq Er ECONNRESET +when the remote peer +forces the connection to be closed; +.It Bq Er ECONNREFUSED +when the remote +peer actively refuses connection establishment (usually because +no process is listening to the port); +.It Bq Er EADDRINUSE +when an attempt +is made to create a socket with a port which has already been +allocated; +.It Bq Er EADDRNOTAVAIL +when an attempt is made to create a +socket with a network address for which no network interface +exists; +.It Bq Er EAFNOSUPPORT +when an attempt is made to bind or connect a socket to a multicast +address. +.It Bq Er EINVAL +when trying to change TCP function blocks at an invalid point in the session; +.It Bq Er ENOENT +when trying to use a TCP function block that is not available; +.El +.Sh SEE ALSO +.Xr getsockopt 2 , +.Xr setfib 2 , +.Xr socket 2 , +.Xr stats 3 , +.Xr sysctl 3 , +.Xr blackhole 4 , +.Xr inet 4 , +.Xr intro 4 , +.Xr ip 4 , +.Xr ktls 4 , +.Xr mod_cc 4 , +.Xr siftr 4 , +.Xr syncache 4 , +.Xr tcp_bbr 4 , +.Xr tcp_rack 4 , +.Xr setkey 8 , +.Xr sysctl 8 , +.Xr tcp_functions 9 +.Rs +.%A "V. Jacobson" +.%A "B. Braden" +.%A "D. Borman" +.%T "TCP Extensions for High Performance" +.%O "RFC 1323" +.Re +.Rs +.%A "D. Borman" +.%A "B. Braden" +.%A "V. Jacobson" +.%A "R. Scheffenegger" +.%T "TCP Extensions for High Performance" +.%O "RFC 7323" +.Re +.Rs +.%A "A. Heffernan" +.%T "Protection of BGP Sessions via the TCP MD5 Signature Option" +.%O "RFC 2385" +.Re +.Rs +.%A "K. Ramakrishnan" +.%A "S. Floyd" +.%A "D. Black" +.%T "The Addition of Explicit Congestion Notification (ECN) to IP" +.%O "RFC 3168" +.Re +.Rs +.%A "A. Ramaiah" +.%A "R. Stewart" +.%A "M. Dalal" +.%T "Improving TCP's Robustness to Blind In-Window Attacks" +.%O "RFC 5961" +.Re +.Sh HISTORY +The +.Tn TCP +protocol appeared in +.Bx 4.2 . +The RFC 1323 extensions for window scaling and timestamps were added +in +.Bx 4.4 . +The +.Dv TCP_INFO +option was introduced in +.Tn Linux 2.6 +and is +.Em subject to change . diff --git a/static/freebsd/man4/tcp_bbr.4 b/static/freebsd/man4/tcp_bbr.4 new file mode 100644 index 00000000..fb1023dc --- /dev/null +++ b/static/freebsd/man4/tcp_bbr.4 @@ -0,0 +1,161 @@ +.\" +.\" Copyright (c) 2020, Gordon Bergling +.\" +.\" 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 December 17, 2023 +.Dt TCP_BBR 4 +.Os +.Sh NAME +.Nm tcp_bbr +.Nd TCP Bottleneck Bandwidth and Round-Trip Time Algorithm +.Sh SYNOPSIS +To load the driver as a module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +tcp_bbr_load="YES" +.Ed +.Pp +To enable the TCP stack you must place the following line in the +.Xr sysctl.conf 5 : +.Bd -literal -offset indent +net.inet.tcp.functions_default=bbr +.Ed +.Sh DESCRIPTION +Bottleneck bandwidth and round-trip time (BBR) is a congestion control algorithm which +seeks high throughput with a small queue by probing BW and RTT. +It is a round-up redesign of congestion control, which is not loss-based, delay-based, +ECN-based or AIMD-based. +.Pp +The core design of BBR is about creating a model graph of the network path by +estimating the maximum BW and minimum RTT on each ACK. +.Sh MIB Variables +The algorithm exposes the following scopes in the +.Va net.inet.tcp.bbr +branch of the +.Xr sysctl 3 +MIB: +.Bl -tag -width ".Va exp_backoff_scale" +.It Va cwnd +Cwnd controls, for example "target cwnd rtt measurement" and "BBR initial window". +.It Va measure +Measurement controls. +.It Va pacing +Connection pacing controls. +.It Va policer +Policer controls, for example "false detection threshold" and "loss threshold". +.It Va probertt +Probe RTT controls. +.It Va startup +Startup controls. +.It Va states +State controls. +.It Va timeout +Time out controls. +.El +.Pp +Besides the variables within the above scopes the following +variables are also exposed in the +.Va net.inet.tcp.bbr +branch: +.Bl -tag -width ".Va exp_backoff_scale" +.It Va clrlost +Clear lost counters. +.It Va software_pacing +Total number of software paced flows. +.It Va hdwr_pacing +Total number of hardware paced flows. +.It Va enob_no_hdwr_pacing +Total number of enobufs for non-hardware paced flows. +.It Va enob_hdwr_pacing +Total number of enobufs for hardware paced flows. +.It Va rtt_tlp_thresh +What divisor for TLP rtt/retran will be added (1=rtt, 2=1/2 rtt etc). +.It Va reorder_fade +Does reorder detection fade, if so how many ms (0 means never). +.It Va reorder_thresh +What factor for rack will be added when seeing reordering (shift right). +.It Va bb_verbose +Should BBR black box logging be verbose. +.It Va sblklimit +When do we start ignoring small sack blocks. +.It Va resend_use_tso +Can resends use TSO? +.It Va data_after_close +Do we hold off sending a RST until all pending data is ack'd. +.It Va kill_paceout +When we hit this many errors in a row, kill the session? +.It Va error_paceout +When we hit an error what is the min to pace out in usec's? +.It Va cheat_rxt +Do we burst 1ms between sends on retransmissions (like rack)? +.It Va minrto +Minimum RTO in ms. +.El +.Sh SEE ALSO +.Xr cc_chd 4 , +.Xr cc_cubic 4 , +.Xr cc_hd 4 , +.Xr cc_htcp 4 , +.Xr cc_newreno 4 , +.Xr cc_vegas 4 , +.Xr h_ertt 4 , +.Xr mod_cc 4 , +.Xr tcp 4 , +.Xr tcp_rack 4 , +.Xr mod_cc 9 +.Rs +.%A "Neal Cardwell" +.%A "Yuchung Cheng" +.%A "Stephen Gunn" +.%A "Soheil Hassas Yeganeh" +.%A "Van Jacobson" +.%T "BBR: Congestion-Based Congestion Control" +.%J "ACM Queue, Vol. 14" +.%D "September / October 2016" +.Re +.Rs +.%A "Dominik Scholz" +.%A "Benedikt Jaeger" +.%A "Lukas Schwaighofer" +.%A "Daniel Raumer" +.%A "Fabien Geyer" +.%A "Georg Carle" +.%T "Towards a Deeper Understanding of TCP BBR Congestion Control" +.%J "IFIP Networking 2018" +.%D "May 2018" +.%U "http://www.net.in.tum.de/fileadmin/bibtex/publications/papers/IFIP-Networking-2018-TCP-BBR.pdf" +.Re +.Sh HISTORY +The +.Nm +congestion control module first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +congestion control module was written by +.An Randall Stewart Aq Mt rrs@FreeBSD.org +and sponsored by Netflix, Inc. +This manual page was written by +.An Gordon Bergling Aq Mt gbe@FreeBSD.org . diff --git a/static/freebsd/man4/tcp_rack.4 b/static/freebsd/man4/tcp_rack.4 new file mode 100644 index 00000000..73995d93 --- /dev/null +++ b/static/freebsd/man4/tcp_rack.4 @@ -0,0 +1,162 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2022, Gordon Bergling +.\" +.\" 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 March 18, 2024 +.Dt TCP_RACK 4 +.Os +.Sh NAME +.Nm tcp_rack +.Nd TCP RACK-TLP Loss Detection Algorithm for TCP +.Sh SYNOPSIS +To load the TCP stack as a module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +tcp_rack_load="YES" +.Ed +.Pp +To enable the TCP stack, place the following line in the +.Xr sysctl.conf 5 : +.Bd -literal -offset indent +net.inet.tcp.functions_default=rack +.Ed +.Sh DESCRIPTION +RACK-TLP uses per-segment transmit timestamps and selective +acknowledgments (SACKs) and has two parts. +Recent Acknowledgment (RACK) starts fast recovery quickly +using time-based inferences derived from acknowledgment (ACK) +feedback, and Tail Loss Probe (TLP) leverages RACK +and sends a probe packet to trigger ACK feedback to avoid +retransmission timeout (RTO) events. +.Pp +Compared to the widely used duplicate acknowledgment (DupAck) +threshold approach, RACK-TLP detects losses more efficiently +when there are application-limited flights of data, lost +retransmissions, or data packet reordering events. +.Pp +It is intended to be an alternative to the +DupAck threshold approach. +.Sh MIB Variables +The algorithm exposes the following scopes in the +.Va net.inet.tcp.rack +branch of the +.Xr sysctl 3 +MIB: +.Bl -tag -width indent +.It Va net.inet.tcp.rack.misc +Misc related controls +.It Va net.inet.tcp.rack.features +Feature controls +.It Va net.inet.tcp.rack.measure +Measure related controls +.It Va net.inet.tcp.rack.timers +Timer related controls +.It Va net.inet.tcp.rack.tlp +TLP and Rack related Controls +.It Va net.inet.tcp.rack.timely +Rack Timely RTT Controls +.It Va net.inet.tcp.rack.hdwr_pacing +Pacing related Controls +.It Va net.inet.tcp.rack.pacing +Pacing related Controls +.It Va net.inet.tcp.rack.tp +Rack tracepoint facility +.It Va net.inet.tcp.rack.probertt +ProbeRTT related Controls +.It Va net.inet.tcp.rack.stats +Rack Counters +.It Va net.inet.tcp.rack.sack_attack +Rack Sack Attack Counters and Controls +.El +.Pp +Besides the variables within the above scopes the following +variables are also exposed in the +.Va net.inet.tcp.rack +branch: +.Bl -tag -width indent +.It Va net.inet.tcp.rack.clear +Clear counters +.It Va net.inet.tcp.rack.opts +RACK Option Stats +.It Va net.inet.tcp.rack.outsize +MSS send sizes +.It Va net.inet.tcp.rack.req_measure_cnt +If doing dynamic pacing, how many measurements +must be in before we start pacing? +.It Va net.inet.tcp.rack.use_pacing +If set we use pacing, if clear we use only the original burst mitigation +.It Va net.inet.tcp.rack.rate_sample_method +What method should we use for rate sampling 0=high, 1=low +.El +.Sh SEE ALSO +.Xr cc_chd 4 , +.Xr cc_cubic 4 , +.Xr cc_hd 4 , +.Xr cc_htcp 4 , +.Xr cc_newreno 4 , +.Xr cc_vegas 4 , +.Xr h_ertt 4 , +.Xr mod_cc 4 , +.Xr tcp 4 , +.Xr tcp_bbr 4 , +.Xr mod_cc 9 +.Rs +.%A "Neal Cardwell" +.%A "Yuchung Cheng" +.%A "Nandita Dukkipati" +.%A "Priyaranjan Jha" +.%T "The RACK-TLP Loss Detection Algorithm for TCP" +.%O "RFC 8985" +.%D "February 2021" +.Re +.Rs +.%A "M. Allman" +.%A "V. Paxson" +.%A "E. Blanton" +.%T "TCP Congestion Control" +.%O "RFC 5681" +.%D "September 2009" +.Re +.Rs +.%A "M. Mathis" +.%A "Nandita Dukkipati" +.%A "Yuchung Cheng" +.%T "Proportional Rate Reduction for TCP" +.%O "RFC 6937" +.%D "May 2013" +.Re +.Sh HISTORY +The +.Nm +congestion control module first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +congestion control module was written by +.An Randall Stewart Aq Mt rrs@FreeBSD.org +and sponsored by Netflix, Inc. +This manual page was written by +.An Gordon Bergling Aq Mt gbe@FreeBSD.org . diff --git a/static/freebsd/man4/tdfx.4 b/static/freebsd/man4/tdfx.4 new file mode 100644 index 00000000..663cd582 --- /dev/null +++ b/static/freebsd/man4/tdfx.4 @@ -0,0 +1,96 @@ +.\" +.Dd February 19, 2001 +.Dt TDFX 4 +.Os +.Sh NAME +.Nm tdfx +.Nd Voodoo Graphics and VoodooII Memory Access GLIDE device driver +.Sh SYNOPSIS +.Cd device tdfx +.Sh DESCRIPTION +This driver creates an entry in +.Pa /dev +that allows programs (mostly +.Em GLIDE-based software ) +to access the device memory of the Voodoo Graphics and +VoodooII 3D accelerators created by +.Em 3Dfx, Inc . +This provides an interface +for applications based on the +.Em GLIDE API +or that simply use the API +provided by the linux +.Pa /dev/3dfx +device to use the video device. +.Pp +Supports all cards based on the following chipsets: +.Pp +.Bl -item -offset indent -compact +.It +.Em 3Dfx Voodoo Graphics +.It +.Em 3Dfx Voodoo II +.El +.Pp +Specifically, the following cards should work: +.Pp +.Bl -item -offset indent -compact +.It +.Em Diamond Multimedia Monster 3D +.It +.Em Diamond Multimedia Monster 3D II +.El +.Pp +Note that this driver does not currently have support for the Voodoo +Banshee, Voodoo3, Voodoo5, or Voodoo6 based cards. +It also does not currently support the Voodoo Rush. +It also does not yet handle the SLI feature of the Voodoo II boards. +You can only use each of them separately. +.Pp +By loading the +.Nm tdfx_linux.ko +and +.Nm linux.ko +modules, you can enable the linux ioctl code for this driver, where the only supported +applications currently reside. +.Sh FILES +.Bl -tag -width /dev/voodoo* -compact +.It Pa /dev/3dfx +Symlinked to default +.Em 3dfx +board +.It Pa /dev/3dfx* +.Em Character Device +programming interface +.Pp +.It Pa /dev/voodoo +Mirrors of above interfaces +.It Pa /dev/voodoo* +(Some apps use +.Pa /dev/voodoo ) +.El +.Sh SEE ALSO +.Xr kld 4 , +.Xr linux 4 , +.Xr kldload 8 +.Sh HISTORY +The +.Nm +driver appeared in +.Fx 5.0 , +and was originally developed for Linux kernel 2.0.x, later written for +2.2.x and 2.4.x. +.Sh AUTHORS +.An -nosplit +The driver was developed by +.An Coleman Kane Aq Mt cokane@micro.ti.com +after the linux version of this driver by +.An Darryll Straus , +.An John Taylor , +.An Jens Axboe , +.An Carlo Wood Aq Mt carlo@alinoe.com +and +.An Joseph Kain Aq Mt joseph@3dfx.com +to be directly compatible with it and support the many GLIDE based games +available for Linux and +.Ux . diff --git a/static/freebsd/man4/termios.4 b/static/freebsd/man4/termios.4 new file mode 100644 index 00000000..62a5d041 --- /dev/null +++ b/static/freebsd/man4/termios.4 @@ -0,0 +1,1610 @@ +.\" Copyright (c) 1991, 1992, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 14, 2026 +.Dt TERMIOS 4 +.Os +.Sh NAME +.Nm termios +.Nd general terminal line discipline +.Sh SYNOPSIS +.In termios.h +.Sh DESCRIPTION +This describes a general terminal line discipline that is +supported on tty asynchronous communication ports. +.Ss Opening a Terminal Device File +When a terminal file is opened, it normally causes the process to wait +until a connection is established. +For most hardware, the presence +of a connection is indicated by the assertion of the hardware +.Dv CARRIER +line. +If the termios structure associated with the terminal file has the +.Dv CLOCAL +flag set in the cflag, or if the +.Dv O_NONBLOCK +flag is set +in the +.Xr open 2 +call, then the open will succeed even without +a connection being present. +In practice, applications +seldom open these files; they are opened by special programs, such +as +.Xr getty 8 , +and become +an application's standard input, output, and error files. +.Ss Job Control in a Nutshell +Every process is associated with a particular process group and session. +The grouping is hierarchical: every member of a particular process group is a +member of the same session. +This structuring is used in managing groups +of related processes for purposes of +.\" .Gw "job control" ; +.Em "job control" ; +that is, the +ability from the keyboard (or from program control) to simultaneously +stop or restart +a complex command (a command composed of one or more related +processes). +The grouping into process groups allows delivering +of signals that stop or start the group as a whole, along with +arbitrating which process group has access to the single controlling +terminal. +The grouping at a higher layer into sessions is to restrict +the job control related signals and system calls to within processes +resulting from a particular instance of a +.Dq login . +Typically, a session +is created when a user logs in, and the login terminal is setup +to be the controlling terminal; all processes spawned from that +login shell are in the same session, and inherit the controlling +terminal. +.Pp +A job control shell +operating interactively (that is, reading commands from a terminal) +normally groups related processes together by placing them into the +same process group. +A set of processes in the same process group +is collectively referred to as a +.Dq job . +When the foreground process +group of the terminal is the same as the process group of a particular +job, that job is said to be in the +.Dq foreground . +When the process group of the terminal is different from the process group of +a job (but is still the controlling terminal), that job is said +to be in the +.Dq background . +Normally the +shell reads a command and starts the job that implements that +command. +If the command is to be started in the foreground (typical), it +sets the process group of the terminal to the process group +of the started job, waits for the job to complete, and then +sets the process group of the terminal back to its own process +group (it puts itself into the foreground). +If the job is to +be started in the background (as denoted by the shell operator "&"), +it never changes the process group of the terminal and does not +wait for the job to complete (that is, it immediately attempts to read the next +command). +If the job is started in the foreground, the user may +type a key (usually +.Ql \&^Z ) +which generates the terminal stop signal +.Pq Dv SIGTSTP +and has the effect of stopping the entire job. +The shell will notice that the job stopped, and will resume running after +placing itself in the foreground. +The shell also has commands for placing stopped jobs in the background, +and for placing stopped or background jobs into the foreground. +.Ss Orphaned Process Groups +An orphaned process group is a process group that has no process +whose parent is in a different process group, yet is in the same +session. +Conceptually it means a process group that does not have +a parent that could do anything if it were to be stopped. +For example, +the initial login shell is typically in an orphaned process group. +Orphaned process groups are immune to keyboard generated stop +signals and job control signals resulting from reads or writes to the +controlling terminal. +.Ss The Controlling Terminal +A terminal may belong to a process as its controlling terminal. +Each +process of a session that has a controlling terminal has the same +controlling terminal. +A terminal may be the controlling terminal for at +most one session. +The controlling terminal for a session is allocated by +the session leader by issuing the +.Dv TIOCSCTTY +ioctl. +A controlling terminal +is never acquired by merely opening a terminal device file. +When a controlling terminal becomes +associated with a session, its foreground process group is set to +the process group of the session leader. +.Pp +The controlling terminal is inherited by a child process during a +.Xr fork 2 +function call. +A process relinquishes its controlling terminal when it +creates a new session with the +.Xr setsid 2 +function; other processes +remaining in the old session that had this terminal as their controlling +terminal continue to have it. +A process does not relinquish its +controlling terminal simply by closing all of its file descriptors +associated with the controlling terminal if other processes continue to +have it open. +.Pp +When a controlling process terminates, the controlling terminal is +disassociated from the current session, allowing it to be acquired by a +new session leader. +Subsequent access to the terminal by other processes +in the earlier session will be denied, with attempts to access the +terminal treated as if modem disconnect had been sensed. +.Ss Terminal Access Control +If a process is in the foreground process group of its controlling +terminal, read operations are allowed. +Any attempts by a process +in a background process group to read from its controlling terminal +causes a +.Dv SIGTTIN +signal to be sent to +the process's group +unless one of the +following special cases apply: if the reading process is ignoring or +blocking the +.Dv SIGTTIN +signal, or if the process group of the reading +process is orphaned, the +.Xr read 2 +returns -1 with +.Va errno +set to +.Er EIO +and no +signal is sent. +The default action of the +.Dv SIGTTIN +signal is to stop the +process to which it is sent. +.Pp +If a process is in the foreground process group of its controlling +terminal, write operations are allowed. +Attempts by a process in a background process group to write to its +controlling terminal will cause the process group to be sent a +.Dv SIGTTOU +signal unless one of the following special cases apply: if +.Dv TOSTOP +is not +set, or if +.Dv TOSTOP +is set and the process is ignoring or blocking the +.Dv SIGTTOU +signal, the process is allowed to write to the terminal and the +.Dv SIGTTOU +signal is not sent. +If +.Dv TOSTOP +is set, and the process group of +the writing process is orphaned, and the writing process is not ignoring +or blocking +.Dv SIGTTOU , +the +.Xr write 2 +returns -1 with +errno set to +.Er EIO +and no signal is sent. +.Pp +Certain calls that set terminal parameters are treated in the same +fashion as write, except that +.Dv TOSTOP +is ignored; that is, the effect is +identical to that of terminal writes when +.Dv TOSTOP +is set. +.Ss Input Processing and Reading Data +A terminal device associated with a terminal device file may operate in +full-duplex mode, so that data may arrive even while output is occurring. +Each terminal device file has associated with it an input queue, into +which incoming data is stored by the system before being read by a +process. +The system imposes a limit, +.Pf \&{ Dv MAX_INPUT Ns \&} , +on the number of +bytes that may be stored in the input queue. +The behavior of the system +when this limit is exceeded depends on the setting of the +.Dv IMAXBEL +flag in the termios +.Fa c_iflag . +If this flag is set, the terminal +is sent an +.Tn ASCII +.Dv BEL +character each time a character is received +while the input queue is full. +Otherwise, the input queue is flushed upon receiving the character. +.Pp +Two general kinds of input processing are available, determined by +whether the terminal device file is in canonical mode or noncanonical +mode. +Additionally, +input characters are processed according to the +.Fa c_iflag +and +.Fa c_lflag +fields. +Such processing can include echoing, which +in general means transmitting input characters immediately back to the +terminal when they are received from the terminal. +This is useful for terminals that can operate in full-duplex mode. +.Pp +The manner in which data is provided to a process reading from a terminal +device file is dependent on whether the terminal device file is in +canonical or noncanonical mode. +.Pp +Another dependency is whether the +.Dv O_NONBLOCK +flag is set by +.Xr open 2 +or +.Xr fcntl 2 . +If the +.Dv O_NONBLOCK +flag is clear, then the read request is +blocked until data is available or a signal has been received. +If the +.Dv O_NONBLOCK +flag is set, then the read request is completed, without +blocking, in one of three ways: +.Bl -enum -offset indent +.It +If there is enough data available to satisfy the entire request, +and the read completes successfully the number of +bytes read is returned. +.It +If there is not enough data available to satisfy the entire +request, and the read completes successfully, having read as +much data as possible, the number of bytes read is returned. +.It +If there is no data available, the read returns -1, with +errno set to +.Er EAGAIN . +.El +.Pp +When data is available depends on whether the input processing mode is +canonical or noncanonical. +.Ss Canonical Mode Input Processing +In canonical mode input processing, terminal input is processed in units +of lines. +A line is delimited by a newline +.Ql \&\en +character, an end-of-file +.Pq Dv EOF +character, or an end-of-line +.Pq Dv EOL +character. +See the +.Sx "Special Characters" +section for +more information on +.Dv EOF +and +.Dv EOL . +This means that a read request will +not return until an entire line has been typed, or a signal has been +received. +Also, no matter how many bytes are requested in the read call, +at most one line is returned. +It is not, however, necessary to +read a whole line at once; any number of bytes, even one, may be +requested in a read without losing information. +.Pp +.Pf \&{ Dv MAX_CANON Ns \&} +is a limit on the +number of bytes in a line. +The behavior of the system when this limit is +exceeded is the same as when the input queue limit +.Pf \&{ Dv MAX_INPUT Ns \&} , +is exceeded. +.Pp +Erase and kill processing occur when either of two special characters, +the +.Dv ERASE +and +.Dv KILL +characters (see the +.Sx "Special Characters" +section), is received. +This processing affects data in the input queue that has not yet been +delimited by a newline +.Dv NL , +.Dv EOF , +or +.Dv EOL +character. +This un-delimited +data makes up the current line. +The +.Dv ERASE +character deletes the last +character in the current line, if there is any. +The +.Dv KILL +character +deletes all data in the current line, if there is any. +The +.Dv ERASE +and +.Dv KILL +characters have no effect if there is no data in the current line. +The +.Dv ERASE +and +.Dv KILL +characters themselves are not placed in the input +queue. +.Ss Noncanonical Mode Input Processing +In noncanonical mode input processing, input bytes are not assembled into +lines, and erase and kill processing does not occur. +The values of the +.Dv VMIN +and +.Dv VTIME +members of the +.Fa c_cc +array are used to determine how to +process the bytes received. +.Pp +.Dv MIN +represents the minimum number of bytes that should be received when +the +.Xr read 2 +function successfully returns. +.Dv TIME +is a timer of 0.1 second +granularity that is used to time out bursty and short term data +transmissions. +If +.Dv MIN +is greater than +.Dv \&{ Dv MAX_INPUT Ns \&} , +the response to the +request is undefined. +The four possible values for +.Dv MIN +and +.Dv TIME +and +their interactions are described below. +.Ss "Case A: MIN > 0, TIME > 0" +In this case +.Dv TIME +serves as an inter-byte timer and is activated after +the first byte is received. +Since it is an inter-byte timer, it is reset +after a byte is received. +The interaction between +.Dv MIN +and +.Dv TIME +is as +follows: as soon as one byte is received, the inter-byte timer is +started. +If +.Dv MIN +bytes are received before the inter-byte timer expires +(remember that the timer is reset upon receipt of each byte), the read is +satisfied. +If the timer expires before +.Dv MIN +bytes are received, the +characters received to that point are returned to the user. +Note that if +.Dv TIME +expires at least one byte is returned because the timer would +not have been enabled unless a byte was received. +In this case +.Pf \&( Dv MIN +> 0, +.Dv TIME +> 0) the read blocks until the +.Dv MIN +and +.Dv TIME +mechanisms are +activated by the receipt of the first byte, or a signal is received. +If data is in the buffer at the time of the +.Fn read , +the result is as +if data had been received immediately after the +.Fn read . +.Ss "Case B: MIN > 0, TIME = 0" +In this case, since the value of +.Dv TIME +is zero, the timer plays no role +and only +.Dv MIN +is significant. +A pending read is not satisfied until +.Dv MIN +bytes are received (i.e., the pending read blocks until +.Dv MIN +bytes +are received), or a signal is received. +A program that uses this case to read record-based terminal +.Dv I/O +may block indefinitely in the read +operation. +.Ss "Case C: MIN = 0, TIME > 0" +In this case, since +.Dv MIN += 0, +.Dv TIME +no longer represents an inter-byte +timer. +It now serves as a read timer that is activated as soon as the +read function is processed. +A read is satisfied as soon as a single +byte is received or the read timer expires. +Note that in this case if the timer expires, no bytes are returned. +If the timer does not +expire, the only way the read can be satisfied is if a byte is received. +In this case the read will not block indefinitely waiting for a byte; if +no byte is received within +.Dv TIME Ns *0.1 +seconds after the read is initiated, +the read returns a value of zero, having read no data. +If data is +in the buffer at the time of the read, the timer is started as if +data had been received immediately after the read. +.Ss Case D: MIN = 0, TIME = 0 +The minimum of either the number of bytes requested or the number of +bytes currently available is returned without waiting for more +bytes to be input. +If no characters are available, read returns a +value of zero, having read no data. +.Ss Writing Data and Output Processing +When a process writes one or more bytes to a terminal device file, they +are processed according to the +.Fa c_oflag +field (see the +.Sx "Output Modes" +section). +The +implementation may provide a buffering mechanism; as such, when a call to +.Fn write +completes, all of the bytes written have been scheduled for +transmission to the device, but the transmission will not necessarily +have been completed. +.\" See also .Sx "6.4.2" for the effects of +.\" .Dv O_NONBLOCK +.\" on write. +.Ss Special Characters +Certain characters have special functions on input or output or both. +These functions are summarized as follows: +.Bl -tag -width indent +.It Dv INTR +Special character on input and is recognized if the +.Dv ISIG +flag (see the +.Sx "Local Modes" +section) is enabled. +Generates a +.Dv SIGINT +signal which is sent to all processes in the foreground +process group for which the terminal is the controlling +terminal. +If +.Dv ISIG +is set, the +.Dv INTR +character is +discarded when processed. +.It Dv QUIT +Special character on input and is recognized if the +.Dv ISIG +flag is enabled. +Generates a +.Dv SIGQUIT +signal which is +sent to all processes in the foreground process group +for which the terminal is the controlling terminal. +If +.Dv ISIG +is set, the +.Dv QUIT +character is discarded when +processed. +.It Dv ERASE +Special character on input and is recognized if the +.Dv ICANON +flag is set. +Erases the last character in the +current line; see +.Sx "Canonical Mode Input Processing" . +It does not erase beyond +the start of a line, as delimited by an +.Dv NL , +.Dv EOF , +or +.Dv EOL +character. +If +.Dv ICANON +is set, the +.Dv ERASE +character is +discarded when processed. +.It Dv KILL +Special character on input and is recognized if the +.Dv ICANON +flag is set. +Deletes the entire line, as +delimited by a +.Dv NL , +.Dv EOF , +or +.Dv EOL +character. +If +.Dv ICANON +is set, the +.Dv KILL +character is discarded when processed. +.It Dv EOF +Special character on input and is recognized if the +.Dv ICANON +flag is set. +When received, all the bytes +waiting to be read are immediately passed to the +process, without waiting for a newline, and the +.Dv EOF +is discarded. +Thus, if there are no bytes waiting (that is, the +.Dv EOF +occurred at the beginning of a line), a byte +count of zero is returned from the +.Fn read , +representing an end-of-file indication. +If +.Dv ICANON +is +set, the +.Dv EOF +character is discarded when processed. +.It Dv NL +Special character on input and is recognized if the +.Dv ICANON +flag is set. +It is the line delimiter +.Ql \&\en . +.It Dv EOL +Special character on input and is recognized if the +.Dv ICANON +flag is set. +Is an additional line delimiter, like +.Dv NL . +.It Dv SUSP +If the +.Dv ISIG +flag is enabled, receipt of the +.Dv SUSP +character causes a +.Dv SIGTSTP +signal to be sent to all processes in the +foreground process group for which the terminal is the +controlling terminal, and the +.Dv SUSP +character is +discarded when processed. +.It Dv STOP +Special character on both input and output and is +recognized if the +.Dv IXON +(output control) or +.Dv IXOFF +(input +control) flag is set. +Can be used to temporarily suspend output. +It is useful with fast terminals to +prevent output from disappearing before it can be read. +If +.Dv IXON +is set, the +.Dv STOP +character is discarded when +processed. +.It Dv START +Special character on both input and output and is +recognized if the +.Dv IXON +(output control) or +.Dv IXOFF +(input +control) flag is set. +Can be used to resume output that has been suspended by a +.Dv STOP +character. +If +.Dv IXON +is set, the +.Dv START +character is discarded when processed. +.It Dv CR +Special character on input and is recognized if the +.Dv ICANON +flag is set; it is the +.Ql \&\er , +as denoted in the +.Tn \&C +Standard {2}. +When +.Dv ICANON +and +.Dv ICRNL +are set and +.Dv IGNCR +is not set, this character is translated into a +.Dv NL , +and +has the same effect as a +.Dv NL +character. +.El +.Pp +The following special characters are extensions defined by this +system and are not a part of +.St -p1003.1 +termios. +.Bl -tag -width indent +.It Dv EOL2 +Secondary +.Dv EOL +character. +Same function as +.Dv EOL . +.It Dv WERASE +Special character on input and is recognized if the +.Dv ICANON +flag is set. +Erases the last word in the current line according to one of two algorithms. +If the +.Dv ALTWERASE +flag is not set, first any preceding whitespace is +erased, and then the maximal sequence of non-whitespace +characters. +If +.Dv ALTWERASE +is set, first any preceding +whitespace is erased, and then the maximal sequence +of alphabetic/underscores or non alphabetic/underscores. +As a special case in this second algorithm, the first previous +non-whitespace character is skipped in determining +whether the preceding word is a sequence of +alphabetic/underscores. +This sounds confusing but turns out to be quite practical. +.It Dv REPRINT +Special character on input and is recognized if the +.Dv ICANON +flag is set. +Causes the current input edit line to be retyped. +.It Dv DSUSP +Has similar actions to the +.Dv SUSP +character, except that +the +.Dv SIGTSTP +signal is delivered when one of the processes +in the foreground process group issues a +.Fn read +to the +controlling terminal. +.It Dv LNEXT +Special character on input and is recognized if the +.Dv IEXTEN +flag is set. +Receipt of this character causes the next character to be taken literally. +.It Dv DISCARD +Special character on input and is recognized if the +.Dv IEXTEN +flag is set. +Receipt of this character toggles the flushing of terminal output. +.It Dv STATUS +Special character on input and is recognized if the +.Dv ICANON +flag is set. +Receipt of this character causes a +.Dv SIGINFO +signal to be sent to the foreground process group of the +terminal. +Also, if the +.Dv NOKERNINFO +flag is not set, it +causes the kernel to write a status message to the terminal +that displays the current load average, the name of the +command in the foreground, its process ID, the symbolic +wait channel, the number of user and system seconds used, +the percentage of cpu the process is getting, and the resident +set size of the process. +.Pp +In case the kernel has +.Xr stack 9 +support configured and the +.Xr sysctl 8 +variable +.Va kern.tty_info_kstacks +is set to a non-zero value, the running thread's kernel stack is +written to the terminal (e.g., for debugging purposes). +.El +.Pp +The +.Dv NL +and +.Dv CR +characters cannot be changed. +The values for all the remaining characters can be set and are +described later in the document under +Special Control Characters. +.Pp +Special +character functions associated with changeable special control characters +can be disabled individually by setting their value to +.Dv {_POSIX_VDISABLE} ; +see +.Sx "Special Control Characters" . +.Pp +If two or more special characters have the same value, the function +performed when that character is received is undefined. +.Ss Modem Disconnect +If a modem disconnect is detected by the terminal interface for a +controlling terminal, and if +.Dv CLOCAL +is not set in the +.Fa c_cflag +field for +the terminal, the +.Dv SIGHUP +signal is sent to the controlling +process associated with the terminal. +Unless other arrangements have +been made, this causes the controlling process to terminate. +Any subsequent call to the +.Fn read +function returns the value zero, +indicating end of file. +Thus, processes that read a terminal +file and test for end-of-file can terminate appropriately after a +disconnect. +.\" If the +.\" .Er EIO +.\" condition specified in 6.1.1.4 that applies +.\" when the implementation supports job control also exists, it is +.\" unspecified whether the +.\" .Dv EOF +.\" condition or the +.\" .Pf [ Dv EIO +.\" ] is returned. +Any +subsequent +.Fn write +to the terminal device returns -1, with +.Va errno +set to +.Er EIO , +until the device is closed. +.Sh General Terminal Interface +.Ss Closing a Terminal Device File +The last process to close a terminal device file causes any output +to be sent to the device and any input to be discarded. +Then, if +.Dv HUPCL +is set in the control modes, and the communications port supports a +disconnect function, the terminal device performs a disconnect. +.Ss Parameters That Can Be Set +Routines that need to control certain terminal +.Tn I/O +characteristics +do so by using the termios structure as defined in the header +.In termios.h . +This structure contains minimally four scalar elements of bit flags +and one array of special characters. +The scalar flag elements are named: +.Fa c_iflag , +.Fa c_oflag , +.Fa c_cflag , +and +.Fa c_lflag . +The character array is named +.Fa c_cc , +and its maximum index is +.Dv NCCS . +.Ss Input Modes +Values of the +.Fa c_iflag +field describe the basic +terminal input control, and are composed of +following masks: +.Pp +.Bl -tag -width IMAXBEL -offset indent -compact +.It Dv IGNBRK +/* ignore BREAK condition */ +.It Dv BRKINT +/* map BREAK to SIGINTR */ +.It Dv IGNPAR +/* ignore (discard) parity errors */ +.It Dv PARMRK +/* mark parity and framing errors */ +.It Dv INPCK +/* enable checking of parity errors */ +.It Dv ISTRIP +/* strip 8th bit off chars */ +.It Dv INLCR +/* map NL into CR */ +.It Dv IGNCR +/* ignore CR */ +.It Dv ICRNL +/* map CR to NL (ala CRMOD) */ +.It Dv IXON +/* enable output flow control */ +.It Dv IXOFF +/* enable input flow control */ +.It Dv IXANY +/* any char will restart after stop */ +.It Dv IMAXBEL +/* ring bell on input queue full */ +.It Dv IUTF8 +/* assume input is UTF-8 encoded */ +.El +.Pp +In the context of asynchronous serial data transmission, a break +condition is defined as a sequence of zero-valued bits that continues for +more than the time to send one byte. +The entire sequence of zero-valued +bits is interpreted as a single break condition, even if it continues for +a time equivalent to more than one byte. +In contexts other than +asynchronous serial data transmission the definition of a break condition +is implementation defined. +.Pp +If +.Dv IGNBRK +is set, a break condition detected on input is ignored, that +is, not put on the input queue and therefore not read by any process. +If +.Dv IGNBRK +is not set and +.Dv BRKINT +is set, the break condition flushes the +input and output queues and if the terminal is the controlling terminal +of a foreground process group, the break condition generates a +single +.Dv SIGINT +signal to that foreground process group. +If neither +.Dv IGNBRK +nor +.Dv BRKINT +is set, a break condition is read as a single +.Ql \&\e0 , +or if +.Dv PARMRK +is set, as +.Ql \&\e377 , +.Ql \&\e0 , +.Ql \&\e0 . +.Pp +If +.Dv IGNPAR +is set, a byte with a framing or parity error (other than +break) is ignored. +.Pp +If +.Dv PARMRK +is set, and +.Dv IGNPAR +is not set, a byte with a framing or parity +error (other than break) is given to the application as the +three-character sequence +.Ql \&\e377 , +.Ql \&\e0 , +X, where +.Ql \&\e377 , +.Ql \&\e0 +is a two-character +flag preceding each sequence and X is the data of the character received +in error. +To avoid ambiguity in this case, if +.Dv ISTRIP +is not set, a valid +character of +.Ql \&\e377 +is given to the application as +.Ql \&\e377 , +.Ql \&\e377 . +If +neither +.Dv PARMRK +nor +.Dv IGNPAR +is set, a framing or parity error (other than +break) is given to the application as a single character +.Ql \&\e0 . +.Pp +If +.Dv INPCK +is set, input parity checking is enabled. +If +.Dv INPCK +is not set, +input parity checking is disabled, allowing output parity generation +without input parity errors. +Note that whether input parity checking is +enabled or disabled is independent of whether parity detection is enabled +or disabled (see +.Sx "Control Modes" ) . +If parity detection is enabled but input +parity checking is disabled, the hardware to which the terminal is +connected recognizes the parity bit, but the terminal special file +does not check whether this bit is set correctly or not. +.Pp +If +.Dv ISTRIP +is set, valid input bytes are first stripped to seven bits, +otherwise all eight bits are processed. +.Pp +If +.Dv INLCR +is set, a received +.Dv NL +character is translated into a +.Dv CR +character. +If +.Dv IGNCR +is set, a received +.Dv CR +character is ignored (not +read). +If +.Dv IGNCR +is not set and +.Dv ICRNL +is set, a received +.Dv CR +character is +translated into a +.Dv NL +character. +.Pp +If +.Dv IXON +is set, start/stop output control is enabled. +A received +.Dv STOP +character suspends output and a received +.Dv START +character +restarts output. +If +.Dv IXANY +is also set, then any character may +restart output. +When +.Dv IXON +is set, +.Dv START +and +.Dv STOP +characters are not +read, but merely perform flow control functions. +When +.Dv IXON +is not set, +the +.Dv START +and +.Dv STOP +characters are read. +.Pp +If +.Dv IXOFF +is set, start/stop input control is enabled. +The system shall transmit one or more +.Dv STOP +characters, which are intended to cause the +terminal device to stop transmitting data, as needed to prevent the input +queue from overflowing and causing the undefined behavior described in +.Sx "Input Processing and Reading Data" , +and shall transmit one or more +.Dv START +characters, which are +intended to cause the terminal device to resume transmitting data, as +soon as the device can continue transmitting data without risk of +overflowing the input queue. +The precise conditions under which +.Dv STOP +and +.Dv START +characters are transmitted are implementation defined. +.Pp +If +.Dv IMAXBEL +is set and the input queue is full, subsequent input shall cause an +.Tn ASCII +.Dv BEL +character to be transmitted to +the output queue. +.Pp +The initial input control value after +.Fn open +is implementation defined. +.Ss Output Modes +Values of the +.Fa c_oflag +field describe the basic terminal output control, +and are composed of the following masks: +.Pp +.Bl -tag -width ONOEOT -offset indent -compact +.It Dv OPOST +/* enable following output processing */ +.It Dv ONLCR +/* map NL to CR-NL (ala +.Dv CRMOD ) +*/ +.It Dv OCRNL +/* map CR to NL */ +.It Dv TABDLY +/* tab delay mask */ +.It Dv TAB0 +/* no tab delay and expansion */ +.It Dv TAB3 +/* expand tabs to spaces */ +.It Dv ONOEOT +/* discard +.Dv EOT Ns 's +.Ql \&^D +on output) */ +.It Dv ONOCR +/* do not transmit CRs on column 0 */ +.It Dv ONLRET +/* on the terminal NL performs the CR function */ +.El +.Pp +If +.Dv OPOST +is set, the remaining flag masks are interpreted as follows; +otherwise characters are transmitted without change. +.Pp +If +.Dv ONLCR +is set, newlines are translated to carriage return, linefeeds. +.Pp +If +.Dv OCRNL +is set, carriage returns are translated to newlines. +.Pp +The +.Dv TABDLY +bits specify the tab delay. +The +.Fa c_oflag +is masked with +.Dv TABDLY +and compared with the +values +.Dv TAB0 +or +.Dv TAB3 . +If +.Dv TAB3 +is set, tabs are expanded to the appropriate number of +spaces (assuming 8 column tab stops). +.Pp +If +.Dv ONOEOT +is set, +.Tn ASCII +.Dv EOT Ns 's +are discarded on output. +.Pp +If +.Dv ONOCR +is set, no CR character is transmitted when at column 0 (first position). +.Pp +If +.Dv ONLRET +is set, the NL character is assumed to do the carriage-return function; +the column pointer will be set to 0. +.Ss Control Modes +Values of the +.Fa c_cflag +field describe the basic +terminal hardware control, and are composed of the +following masks. +Not all values +specified are supported by all hardware. +.Pp +.Bl -tag -width CRTSXIFLOW -offset indent -compact +.It Dv CSIZE +/* character size mask */ +.It Dv CS5 +/* 5 bits (pseudo) */ +.It Dv CS6 +/* 6 bits */ +.It Dv CS7 +/* 7 bits */ +.It Dv CS8 +/* 8 bits */ +.It Dv CSTOPB +/* send 2 stop bits */ +.It Dv CREAD +/* enable receiver */ +.It Dv PARENB +/* parity enable */ +.It Dv PARODD +/* odd parity, else even */ +.It Dv HUPCL +/* hang up on last close */ +.It Dv CLOCAL +/* ignore modem status lines */ +.It Dv CCTS_OFLOW +/* +.Dv CTS +flow control of output */ +.It Dv CRTSCTS +/* same as +.Dv CCTS_OFLOW +*/ +.It Dv CRTS_IFLOW +/* RTS flow control of input */ +.It Dv MDMBUF +/* flow control output via Carrier */ +.It Dv CNO_RTSDTR +/* Do not assert RTS or DTR automatically */ +.El +.Pp +The +.Dv CSIZE +bits specify the byte size in bits for both transmission and +reception. +The +.Fa c_cflag +is masked with +.Dv CSIZE +and compared with the +values +.Dv CS5 , +.Dv CS6 , +.Dv CS7 , +or +.Dv CS8 . +This size does not include the parity bit, if any. +If +.Dv CSTOPB +is set, two stop bits are used, otherwise one stop bit. +For example, at 110 baud, two stop bits are normally used. +.Pp +If +.Dv CREAD +is set, the receiver is enabled. +Otherwise, no character is received. +Not all hardware supports this bit. +In fact, this flag is pretty silly and if it were not part of the +.Nm +specification +it would be omitted. +.Pp +If +.Dv PARENB +is set, parity generation and detection are enabled and a parity +bit is added to each character. +If parity is enabled, +.Dv PARODD +specifies +odd parity if set, otherwise even parity is used. +.Pp +If +.Dv HUPCL +is set, the modem control lines for the port are lowered +when the last process with the port open closes the port or the process +terminates. +The modem connection is broken. +.Pp +If +.Dv CLOCAL +is set, a connection does not depend on the state of the modem +status lines. +If +.Dv CLOCAL +is clear, the modem status lines are +monitored. +.Pp +Under normal circumstances, a call to the +.Fn open +function waits for +the modem connection to complete. +However, if the +.Dv O_NONBLOCK +flag is set +or if +.Dv CLOCAL +has been set, the +.Fn open +function returns +immediately without waiting for the connection. +.Pp +The +.Dv CCTS_OFLOW +.Pf ( Dv CRTSCTS ) +flag is currently unused. +.Pp +If +.Dv MDMBUF +is set then output flow control is controlled by the state +of Carrier Detect. +.Pp +If +.Dv CNO_RTSDTR +is set then the RTS and DTR lines will not be asserted when the device +is opened. +As a result, this flag is only useful on initial-state devices. +.Pp +If the object for which the control modes are set is not an asynchronous +serial connection, some of the modes may be ignored; for example, if an +attempt is made to set the baud rate on a network connection to a +terminal on another host, the baud rate may or may not be set on the +connection between that terminal and the machine it is directly connected +to. +.Ss Local Modes +Values of the +.Fa c_lflag +field describe the control of +various functions, and are composed of the following +masks. +.Pp +.Bl -tag -width NOKERNINFO -offset indent -compact +.It Dv ECHOKE +/* visual erase for line kill */ +.It Dv ECHOE +/* visually erase chars */ +.It Dv ECHO +/* enable echoing */ +.It Dv ECHONL +/* echo +.Dv NL +even if +.Dv ECHO +is off */ +.It Dv ECHOPRT +/* visual erase mode for hardcopy */ +.It Dv ECHOCTL +/* echo control chars as ^(Char) */ +.It Dv ISIG +/* enable signals +.Dv INTR , +.Dv QUIT , +.Dv [D]SUSP +*/ +.It Dv ICANON +/* canonicalize input lines */ +.It Dv ALTWERASE +/* use alternate +.Dv WERASE +algorithm */ +.It Dv IEXTEN +/* enable +.Dv DISCARD +and +.Dv LNEXT +*/ +.It Dv EXTPROC +/* external processing */ +.It Dv TOSTOP +/* stop background jobs from output */ +.It Dv FLUSHO +/* output being flushed (state) */ +.It Dv NOKERNINFO +/* no kernel output from +.Dv VSTATUS +*/ +.It Dv PENDIN +/* XXX retype pending input (state) */ +.It Dv NOFLSH +/* don't flush after interrupt */ +.El +.Pp +If +.Dv ECHO +is set, input characters are echoed back to the terminal. +If +.Dv ECHO +is not set, input characters are not echoed. +.Pp +If +.Dv ECHOE +and +.Dv ICANON +are set, the +.Dv ERASE +character causes the terminal +to erase the last character in the current line from the display, if +possible. +If there is no character to erase, an implementation may echo +an indication that this was the case or do nothing. +.Pp +If +.Dv ECHOK +and +.Dv ICANON +are set, the +.Dv KILL +character causes +the current line to be discarded and the system echoes the +.Ql \&\en +character after the +.Dv KILL +character. +.Pp +If +.Dv ECHOKE +and +.Dv ICANON +are set, the +.Dv KILL +character causes +the current line to be discarded and the system causes +the terminal +to erase the line from the display. +.Pp +If +.Dv ECHOPRT +and +.Dv ICANON +are set, the system assumes +that the display is a printing device and prints a +backslash and the erased characters when processing +.Dv ERASE +characters, followed by a forward slash. +.Pp +If +.Dv ECHOCTL +is set, the system echoes control characters +in a visible fashion using a caret followed by the control character. +.Pp +If +.Dv ALTWERASE +is set, the system uses an alternative algorithm +for determining what constitutes a word when processing +.Dv WERASE +characters (see +.Dv WERASE ) . +.Pp +If +.Dv ECHONL +and +.Dv ICANON +are set, the +.Ql \&\en +character echoes even if +.Dv ECHO +is not set. +.Pp +If +.Dv ICANON +is set, canonical processing is enabled. +This enables the +erase and kill edit functions, and the assembly of input characters into +lines delimited by +.Dv NL , +.Dv EOF , +and +.Dv EOL , +as described in +.Sx "Canonical Mode Input Processing" . +.Pp +If +.Dv ICANON +is not set, read requests are satisfied directly from the input +queue. +A read is not satisfied until at least +.Dv MIN +bytes have been +received or the timeout value +.Dv TIME +expired between bytes. +The time value +represents tenths of seconds. +See +.Sx "Noncanonical Mode Input Processing" +for more details. +.Pp +If +.Dv ISIG +is set, each input character is checked against the special +control characters +.Dv INTR , +.Dv QUIT , +and +.Dv SUSP +(job control only). +If an input +character matches one of these control characters, the function +associated with that character is performed. +If +.Dv ISIG +is not set, no +checking is done. +Thus these special input functions are possible only +if +.Dv ISIG +is set. +.Pp +If +.Dv IEXTEN +is set, implementation-defined functions are recognized +from the input data. +How +.Dv IEXTEN +being set +interacts with +.Dv ICANON , +.Dv ISIG , +.Dv IXON , +or +.Dv IXOFF +is implementation defined. +If +.Dv IEXTEN +is not set, then +implementation-defined functions are not recognized, and the +corresponding input characters are not processed as described for +.Dv ICANON , +.Dv ISIG , +.Dv IXON , +and +.Dv IXOFF . +.Pp +If +.Dv NOFLSH +is set, the normal flush of the input and output queues +associated with the +.Dv INTR , +.Dv QUIT , +and +.Dv SUSP +characters +are not be done. +.Pp +If +.Dv TOSTOP +is set, the signal +.Dv SIGTTOU +is sent to the process group of a process that tries to write to +its controlling terminal if it is not in the foreground process group for +that terminal. +This signal, by default, stops the members of the process group. +Otherwise, the output generated by that process is output to the +current output stream. +Processes that are blocking or ignoring +.Dv SIGTTOU +signals are excepted and allowed to produce output and the +.Dv SIGTTOU +signal +is not sent. +.Pp +If +.Dv NOKERNINFO +is set, the kernel does not produce a status message +when processing +.Dv STATUS +characters (see +.Dv STATUS ) . +.Ss Special Control Characters +The special control characters values are defined by the array +.Fa c_cc . +This table lists the array index, the corresponding special character, +and the system default value. +For an accurate list of +the system defaults, consult the header file +.In sys/ttydefaults.h . +.Pp +.Bl -column "Index Name" "Special Character" -offset indent -compact +.It Em "Index Name Special Character Default Value" +.It Dv VEOF Ta EOF Ta \&^D +.It Dv VEOL Ta EOL Ta _POSIX_VDISABLE +.It Dv VEOL2 Ta EOL2 Ta _POSIX_VDISABLE +.It Dv VERASE Ta ERASE Ta \&^? Ql \&\e177 +.It Dv VWERASE Ta WERASE Ta \&^W +.It Dv VKILL Ta KILL Ta \&^U +.It Dv VREPRINT Ta REPRINT Ta \&^R +.It Dv VINTR Ta INTR Ta \&^C +.It Dv VQUIT Ta QUIT Ta \&^\e\e Ql \&\e34 +.It Dv VSUSP Ta SUSP Ta \&^Z +.It Dv VDSUSP Ta DSUSP Ta \&^Y +.It Dv VSTART Ta START Ta \&^Q +.It Dv VSTOP Ta STOP Ta \&^S +.It Dv VLNEXT Ta LNEXT Ta \&^V +.It Dv VDISCARD Ta DISCARD Ta \&^O +.It Dv VMIN Ta --- Ta \&1 +.It Dv VTIME Ta --- Ta \&0 +.It Dv VSTATUS Ta STATUS Ta \&^T +.El +.Pp +If the +value of one of the changeable special control characters (see +.Sx "Special Characters" ) +is +.Dv {_POSIX_VDISABLE} , +that function is disabled; that is, no input +data is recognized as the disabled special character. +If +.Dv ICANON +is +not set, the value of +.Dv {_POSIX_VDISABLE} +has no special meaning for the +.Dv VMIN +and +.Dv VTIME +entries of the +.Fa c_cc +array. +.Pp +The initial values of the flags and control characters +after +.Fn open +is set according to +the values in the header +.In sys/ttydefaults.h . +.Sh SEE ALSO +.Xr stty 1 , +.Xr tcgetsid 3 , +.Xr tcgetwinsize 3 , +.Xr tcsendbreak 3 , +.Xr tcsetattr 3 , +.Xr tcsetsid 3 , +.Xr tty 4 , +.Xr uart 4 , +.Xr stack 9 +.Sh BUGS +Before the Internet, serial ports were primarily used for inbound +connections from terminals, either directly or through modems, these +days serial ports are primarily used for outbound connections to +devices, an evolution which unfortunately has spread the relevant +documentation over three different manual pages: +.Xr termios 4 , +.Xr uart 4 and +.Xr tty 4 . + diff --git a/static/freebsd/man4/textdump.4 b/static/freebsd/man4/textdump.4 new file mode 100644 index 00000000..bd479d6a --- /dev/null +++ b/static/freebsd/man4/textdump.4 @@ -0,0 +1,194 @@ +.\" +.\" Copyright (c) 2007 Robert N. M. Watson +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 October 18, 2019 +.Dt TEXTDUMP 4 +.Os +.Sh NAME +.Nm textdump +.Nd textdump kernel dumping facility +.Sh SYNOPSIS +.Cd options DDB +.Cd options KDB +.Pp +.Cd options TEXTDUMP_PREFERRED +.Cd options TEXTDUMP_VERBOSE +.Sh DESCRIPTION +The +.Nm +facility allows the capture of kernel debugging information to disk in a +human-readable rather than the machine-readable form normally used with +kernel memory dumps and minidumps. +This representation, while less complete in that it does not capture full +kernel state, can provide debugging information in a more compact, portable, +and persistent form than a traditional dump. +By combining +.Nm +with other +.Xr ddb 4 +facilities, such as scripting and output capture, detailed bug information +can be captured in a fully automated manner. +.Sh FORMAT +.Nm +data is stored in a dump partition in the same style as a regular memory +dump, and will be automatically extracted by +.Xr savecore 8 +if present on boot. +.Pp +.Nm +files are stored in the +.Xr tar 5 +format, and consist of one or more text files, each storing a particular type +of debugging output. +The following parts may be present: +.Bl -tag -width version.txt +.It Pa ddb.txt +Captured +.Xr ddb 4 +output, if the capture facility has been used. +May be disabled by clearing the +.Va debug.ddb.textdump.do_ddb +sysctl. +.It Pa config.txt +Kernel configuration, if +.Cd options INCLUDE_CONFIG_FILE +has been compiled into the kernel. +May be disabled by clearing the +.Va debug.ddb.textdump.do_config +sysctl. +.It Pa msgbuf.txt +Kernel message buffer, including recent console output if the capture +facility has been used. +May be disabled by clearing the +.Va debug.ddb.textdump.do_msgbuf +sysctl. +.It Pa panic.txt +Kernel panic string, if the kernel panicked before the dump was generated. +May be disabled by clearing the +.Va debug.ddb.textdump.do_panic +sysctl. +.It Pa version.txt +Kernel version string. +My be disabled by clearing the +.Va debug.ddb.textdump.do_version +sysctl. +.El +.Pp +Kernel textdumps may be extracted using +.Xr tar 1 . +.Sh CONFIGURATION +The +.Nm +facility is enabled as part of the kernel debugger using +.Cd options KDB +and +.Cd options DDB . +By default, kernel dumps generated on panic or via explicit requests for a +dump will be regular memory dumps; however, by using the +.Ic textdump set +command in +.Xr ddb 4 , +or by setting the +.Va debug.ddb.textdump.pending +sysctl to 1 using +.Xr sysctl 8 , +it is possible to request that the next dump be a textdump. +One may also directly trigger a textdump in +.Xr ddb 4 +by running the command +.Ic textdump dump . +.Pp +If at the +.Xr ddb 4 +command line, the commands +.Ic textdump set , +.Ic textdump status , +and +.Ic textdump unset +may be used to set, query, and clear the textdump pending flag. +.Pp +As with regular kernel dumps, a dump partition must be automatically or +manually configured using +.Xr dumpon 8 . +.Pp +Additional kernel +.Xr config 8 +options: +.Bl -tag -width TEXTDUMP_PREFERRED +.It Cd TEXTDUMP_PREFERRED +sets textdumps to be the default manner of doing dumps. +This means there will be no need to +.Xr sysctl 8 +or use the +.Ic textdump set +.Xr ddb 8 +commands. +.It Cd TEXTDUMP_VERBOSE +will have the textdump facility be more verbose about each file it is emitting +as well as other diagnostics useful to debug the textdump facility itself. +.El +.Sh EXAMPLES +In the following example, the script +.Va kdb.enter.panic +will run when the kernel debugger is entered as a result of a panic, enable +output capture, dump several useful pieces of debugging information, and then +invoke panic in order to force a kernel dump to be written out followed by a +reboot: +.Bd -literal -offset indent +script kdb.enter.panic=textdump set; capture on; show allpcpu; bt; + ps; alltrace; show alllocks; textdump dump; reset +.Ed +.Pp +In the following example, the script +.Va kdb.enter.witness +will run when the kernel debugger is entered as a result of a witness +violation, printing lock-related information for the user: +.Bd -literal -offset indent +script kdb.enter.witness=show locks +.Ed +.Pp +These scripts may also be configured using the +.Xr ddb 8 +utility. +.Sh SEE ALSO +.Xr tar 1 , +.Xr ddb 4 , +.Xr tar 5 , +.Xr ddb 8 , +.Xr dumpon 8 , +.Xr savecore 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +facility first appeared in +.Fx 7.1 . +.Sh AUTHORS +The +.Nm +facility was created by +.An Robert N. M. Watson . diff --git a/static/freebsd/man4/thunderbolt.4 b/static/freebsd/man4/thunderbolt.4 new file mode 100644 index 00000000..fd7cb1f3 --- /dev/null +++ b/static/freebsd/man4/thunderbolt.4 @@ -0,0 +1,22 @@ +.\" +.\" Copyright (c) 2025 Alexander Ziaee +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd October 2, 2025 +.Dt THUNDERBOLT 4 +.Os +.Sh NAME +.Nm thunderbolt +.Nd USB4 controller driver +.Sh SYNOPSIS +.Cd device thunderbolt +.Sh HARDWARE +The +.Nm +driver supports Thunderbolt 3 and USB4 controllers. +.Sh HISTORY +The +.Nm +driver appeared in +.Fx 15.0 . diff --git a/static/freebsd/man4/ti.4 b/static/freebsd/man4/ti.4 new file mode 100644 index 00000000..bc229633 --- /dev/null +++ b/static/freebsd/man4/ti.4 @@ -0,0 +1,423 @@ +.\" Copyright (c) 1997, 1998, 1999 +.\" Bill Paul . 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 Bill Paul. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Bill Paul 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 Bill Paul OR THE VOICES IN HIS HEAD +.\" 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 November 14, 2011 +.Dt TI 4 +.Os +.Sh NAME +.Nm ti +.Nd "Alteon Networks Tigon I and Tigon II Gigabit Ethernet driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ti" +.Cd "options TI_SF_BUF_JUMBO" +.Cd "options TI_JUMBO_HDRSPLIT" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_ti_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for PCI Gigabit Ethernet adapters based on +the Alteon Networks Tigon Gigabit Ethernet controller chip. +The Tigon +contains an embedded R4000 CPU, gigabit MAC, dual DMA channels and +a PCI interface unit. +The Tigon II contains two R4000 CPUs and other +refinements. +Either chip can be used in either a 32-bit or 64-bit PCI +slot. +Communication with the chip is achieved via PCI shared memory +and bus master DMA. +The Tigon I and II support hardware multicast +address filtering, VLAN tag extraction and insertion, and jumbo +Ethernet frames sizes up to 9000 bytes. +Note that the Tigon I chipset +is no longer in active production: all new adapters should come equipped +with Tigon II chipsets. +.Pp +While the Tigon chipset supports 10, 100 and 1000Mbps speeds, support for +10 and 100Mbps speeds is only available on boards with the proper +transceivers. +Most adapters are only designed to work at 1000Mbps, +however the driver should support those NICs that work at lower speeds +as well. +.Pp +Support for jumbo frames is provided via the interface MTU setting. +Selecting an MTU larger than 1500 bytes with the +.Xr ifconfig 8 +utility configures the adapter to receive and transmit jumbo frames. +Using jumbo frames can greatly improve performance for certain tasks, +such as file transfers and data streaming. +.Pp +Header splitting support for Tigon 2 boards (this option has no effect for +the Tigon 1) can be turned on with the +.Dv TI_JUMBO_HDRSPLIT +option. +See +.Xr zero_copy 9 +for more discussion on zero copy receive and header splitting. +.Pp +The +.Nm +driver uses UMA backed jumbo receive buffers, but can be configured +to use +.Xr sendfile 2 +buffer allocator. +To turn on +.Xr sendfile 2 +buffer allocator, use the +.Dv TI_SF_BUF_JUMBO +option. +.Pp +Support for vlans is also available using the +.Xr vlan 4 +mechanism. +See the +.Xr vlan 4 +man page for more details. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width xxxxxxxxxxxxxxxxxxxx +.It autoselect +Enable autoselection of the media type and options. +The user can manually override +the autoselected mode by adding media options to the +.Pa /etc/rc.conf +file. +.It 10baseT/UTP +Set 10Mbps operation. +The +.Ar mediaopt +option can also be used to select either +.Ar full-duplex +or +.Ar half-duplex +modes. +.It 100baseTX +Set 100Mbps (Fast Ethernet) operation. +The +.Ar mediaopt +option can also be used to select either +.Ar full-duplex +or +.Ar half-duplex +modes. +.It 1000baseSX +Set 1000Mbps (Gigabit Ethernet) operation. +Only +.Ar full-duplex +mode is supported at this speed. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width xxxxxxxxxxxxxxxxxxxx +.It full-duplex +Force full-duplex operation. +.It half-duplex +Force half duplex operation. +.El +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports Gigabit Ethernet adapters based on the +Alteon Tigon I and II chips. +The +.Nm +driver has been tested with the following adapters: +.Pp +.Bl -bullet -compact +.It +3Com 3c985-SX Gigabit Ethernet adapter (Tigon 1) +.It +3Com 3c985B-SX Gigabit Ethernet adapter (Tigon 2) +.It +Alteon AceNIC V Gigabit Ethernet adapter (1000baseSX) +.It +Alteon AceNIC V Gigabit Ethernet adapter (1000baseT) +.It +Digital EtherWORKS 1000SX PCI Gigabit adapter +.It +Netgear GA620 Gigabit Ethernet adapter (1000baseSX) +.It +Netgear GA620T Gigabit Ethernet adapter (1000baseT) +.El +.Pp +The following adapters should also be supported but have +not yet been tested: +.Pp +.Bl -bullet -compact +.It +Asante GigaNIX1000T Gigabit Ethernet adapter +.It +Asante PCI 1000BASE-SX Gigabit Ethernet adapter +.It +Farallon PN9000SX Gigabit Ethernet adapter +.It +NEC Gigabit Ethernet +.It +Silicon Graphics PCI Gigabit Ethernet adapter +.El +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width "xxxxxx" +.It Va hw.ti.%d.dac +If this tunable is set to 0 it will disable DAC (Dual Address Cycle). +The default value is 1 which means driver will use full 64bit +DMA addressing. +.El +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables. +The interface has to be brought down and up again before a +change takes effect when any of the following tunables are +changed. +The one microsecond clock tick referenced below is a nominal +time and the actual hardware may not provide granularity to +this level. +For example, on Tigon 2 (revision 6) cards with release 12.0 +the clock granularity is 5 microseconds. +.Bl -tag -width "xxxxxx" +.It Va dev.ti.%d.rx_coal_ticks +This value, receive coalesced ticks, controls the number of clock +ticks (of 1 microseconds each) that must elapse before the NIC DMAs +the receive return producer pointer to the Host and generates an +interrupt. +This parameter works in conjunction with the rx_max_coal_bds, +receive max coalesced BDs, tunable parameter. +The NIC will return the receive return producer pointer to the Host +when either of the thresholds is exceeded. +A value of 0 means that this parameter is ignored and receive BDs +will only be returned when the receive max coalesced BDs value is +reached. +The default value is 170. +.It Va dev.ti.%d.rx_max_coal_bds +This value, receive max coalesced BDs, controls the number of +receive buffer descriptors that will be coalesced before the NIC +updates the receive return ring producer index. +If this value is set to 0 it will disable receive buffer descriptor +coalescing. +The default value is 64. +.It Va dev.ti.%d.ti_tx_coal_ticks +This value, send coalesced ticks, controls the number of clock +ticks (of 1 microseconds each) that must elapse before the NIC DMAs +the send consumer pointer to the Host and generates an interrupt. +This parameter works in conjunction with the tx_max_coal_bds, +send max coalesced BDs, tunable parameter. +The NIC will return the send consumer pointer to the Host when +either of the thresholds is exceeded. +A value of 0 means that this parameter is ignored and send BDs will +only be returned when the send max coalesced BDs value is reached. +The default value is 2000. +.It Va dev.ti.%d.tx_max_coal_bds +This value, send max coalesced BDs, controls the number of send +buffer descriptors that will be coalesced before the NIC updates +the send consumer index. +If this value is set to 0 it will disable send buffer descriptor +coalescing. +The default value is 32. +.It Va dev.ti.%d.tx_buf_ratio +This value controls the ratio of the remaining memory in the NIC +that should be devoted to transmit buffer vs. receive buffer. +The lower 7 bits are used to indicate the ratio in 1/64th increments. +For example, setting this value to 16 will set the transmit buffer +to 1/4 of the remaining buffer space. +In no cases will the transmit or receive buffer be reduced below +68 KB. +For a 1 MB NIC the approximate total space for data buffers is +800 KB. +For a 512 KB NIC that number is 300 KB. +The default value is 21. +.It Va dev.ti.%d.stat_ticks +The value, stat ticks, controls the number of clock ticks +(of 1 microseconds each) that must elapse before the NIC DMAs +the statistics block to the Host and generates a STATS_UPDATED +event. +If set to zero then statistics are never DMAed to the Host. +It is recommended that this value be set to a high enough +frequency to not mislead someone reading statistics refreshes. +Several times a second is enough. +The default value is 2000000 (2 seconds). +.El +.Sh IOCTLS +In addition to the standard +.Xr socket 2 +.Xr ioctl 2 +calls implemented by most network drivers, the +.Nm +driver also includes a character device interface that can be used for +additional diagnostics, configuration and debugging. +With this character +device interface, and a specially patched version of +.Xr gdb 1 Pq Pa ports/devel/gdb , +the user can +debug firmware running on the Tigon board. +.Pp +These ioctls and their arguments are defined in the +.In sys/tiio.h +header file. +.Bl -tag -width ".Dv ALT_WRITE_TG_MEM" +.It Dv TIIOCGETSTATS +Return card statistics DMAed from the card into kernel memory approximately +every 2 seconds. +(That time interval can be changed via the +.Dv TIIOCSETPARAMS +ioctl.) +The argument is +.Vt "struct ti_stats" . +.It Dv TIIOCGETPARAMS +Get various performance-related firmware parameters that largely affect how +interrupts are coalesced. +The argument is +.Vt "struct ti_params" . +.It Dv TIIOCSETPARAMS +Set various performance-related firmware parameters that largely affect how +interrupts are coalesced. +The argument is +.Vt "struct ti_params" . +.It Dv TIIOCSETTRACE +Tell the NIC to trace the requested types of information. +The argument is +.Vt ti_trace_type . +.It Dv TIIOCGETTRACE +Dump the trace buffer from the card. +The argument is +.Vt "struct ti_trace_buf" . +.It Dv ALT_ATTACH +This ioctl is used for compatibility with Alteon's Solaris driver. +They apparently only have one character interface for debugging, so they have +to tell it which Tigon instance they want to debug. +This ioctl is a noop for +.Fx . +.It Dv ALT_READ_TG_MEM +Read the requested memory region from the Tigon board. +The argument is +.Vt "struct tg_mem" . +.It Dv ALT_WRITE_TG_MEM +Write to the requested memory region on the Tigon board. +The argument is +.Vt "struct tg_mem" . +.It Dv ALT_READ_TG_REG +Read the requested register from the Tigon board. +The argument is +.Vt "struct tg_reg" . +.It Dv ALT_WRITE_TG_REG +Write to the requested register on the Tigon board. +The argument is +.Vt "struct tg_reg" . +.El +.Sh FILES +.Bl -tag -width ".Pa /dev/ti[0-255]" -compact +.It Pa /dev/ti[0-255] +Tigon driver character interface. +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "ti%d: couldn't map memory" +A fatal initialization error has occurred. +.It "ti%d: couldn't map interrupt" +A fatal initialization error has occurred. +.It "ti%d: no memory for softc struct!" +The driver failed to allocate memory for per-device instance information +during initialization. +.It "ti%d: failed to enable memory mapping!" +The driver failed to initialize PCI shared memory mapping. +This might +happen if the card is not in a bus-master slot. +.It "ti%d: no memory for jumbo buffers!" +The driver failed to allocate memory for jumbo frames during +initialization. +.It "ti%d: bios thinks we're in a 64 bit slot, but we aren't" +The BIOS has programmed the NIC as though it had been installed in +a 64-bit PCI slot, but in fact the NIC is in a 32-bit slot. +This happens +as a result of a bug in some BIOSes. +This can be worked around on the +Tigon II, but on the Tigon I initialization will fail. +.It "ti%d: board self-diagnostics failed!" +The ROMFAIL bit in the CPU state register was set after system +startup, indicating that the on-board NIC diagnostics failed. +.It "ti%d: unknown hwrev" +The driver detected a board with an unsupported hardware revision. +The +.Nm +driver supports revision 4 (Tigon 1) and revision 6 (Tigon 2) chips +and has firmware only for those devices. +.It "ti%d: watchdog timeout" +The device has stopped responding to the network, or there is a problem with +the network connection (cable). +.El +.Sh SEE ALSO +.Xr sendfile 2 , +.Xr altq 4 , +.Xr arp 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr vlan 4 , +.Xr ifconfig 8 , +.Xr zero_copy 9 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 3.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Bill Paul Aq Mt wpaul@bsdi.com . +The header splitting firmware modifications, character +.Xr ioctl 2 +interface and debugging support were written by +.An Kenneth Merry Aq Mt ken@FreeBSD.org . +Initial zero copy support was written by +.An Andrew Gallatin Aq Mt gallatin@FreeBSD.org . diff --git a/static/freebsd/man4/timecounters.4 b/static/freebsd/man4/timecounters.4 new file mode 100644 index 00000000..998bb95d --- /dev/null +++ b/static/freebsd/man4/timecounters.4 @@ -0,0 +1,111 @@ +.\" Copyright (c) 2011 Alexander Motin +.\" 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 August 12, 2015 +.Dt TIMECOUNTERS 4 +.Os +.Sh NAME +.Nm timecounters +.Nd kernel time counters subsystem +.Sh SYNOPSIS +The kernel uses several types of time-related devices, such as: real time clocks, +time counters and event timers. +Real time clocks are responsible for tracking real world time, mostly when the system +is down. +Time counters are responsible for tracking purposes, when the system is running. +Event timers are responsible for generating interrupts at a specified time or +periodically, to run different time-based events. +This page is about the second. +.Sh DESCRIPTION +Time counters are the lowest level of time tracking in the kernel. +They provide monotonically increasing timestamps with known width and +update frequency. +They can overflow, drift, etc and so in raw form can be used only in very limited +performance-critical places like the process scheduler. +.Pp +More usable time is created by scaling the values read from the selected +time counter and combining it with some offset, regularly updated by +.Fn tc_windup +on +.Fn hardclock +invocation. +.Pp +Different platforms provide different kinds of timer hardware. +The goal of the time counters subsystem is to provide a unified way to access +that hardware. +.Pp +Each driver implementing time counters registers them with the subsystem. +It is possible to see the list of present time counters, via the +.Va kern.timecounter +.Xr sysctl 8 +variable: +.Bd -literal +kern.timecounter.choice: TSC-low(-100) HPET(950) i8254(0) ACPI-fast(900) dummy(-1000000) +kern.timecounter.tc.ACPI-fast.mask: 16777215 +kern.timecounter.tc.ACPI-fast.counter: 13467909 +kern.timecounter.tc.ACPI-fast.frequency: 3579545 +kern.timecounter.tc.ACPI-fast.quality: 900 +kern.timecounter.tc.i8254.mask: 65535 +kern.timecounter.tc.i8254.counter: 62692 +kern.timecounter.tc.i8254.frequency: 1193182 +kern.timecounter.tc.i8254.quality: 0 +kern.timecounter.tc.HPET.mask: 4294967295 +kern.timecounter.tc.HPET.counter: 3013495652 +kern.timecounter.tc.HPET.frequency: 14318180 +kern.timecounter.tc.HPET.quality: 950 +kern.timecounter.tc.TSC-low.mask: 4294967295 +kern.timecounter.tc.TSC-low.counter: 4067509463 +kern.timecounter.tc.TSC-low.frequency: 11458556 +kern.timecounter.tc.TSC-low.quality: -100 +.Ed +.Pp +The output nodes are defined as follows: +.Bl -inset +.It Va kern.timecounter.tc. Ns Ar X Ns Va .mask +is a bitmask, defining valid counter bits, +.It Va kern.timecounter.tc. Ns Ar X Ns Va .counter +is a present counter value, +.It Va kern.timecounter.tc. Ns Ar X Ns Va .frequency +is a counter update frequency, +.It Va kern.timecounter.tc. Ns Ar X Ns Va .quality +is an integral value, defining the quality of this time counter +compared to others. +A negative value means this time counter is broken and should not be used. +.El +.Pp +The time management code of the kernel automatically switches to a +higher-quality time counter when it registers, unless the +.Va kern.timecounter.hardware +sysctl has been used to choose a specific device. +.Pp +There is no way to unregister a time counter once it has registered +with the kernel. +If a dynamically loaded module contains a time counter you will not +be able to unload that module, even if the time counter it contains +is not the one currently in use. +.Sh SEE ALSO +.Xr attimer 4 , +.Xr eventtimers 4 , +.Xr ffclock 4 , +.Xr hpet 4 diff --git a/static/freebsd/man4/tmpfs.4 b/static/freebsd/man4/tmpfs.4 new file mode 100644 index 00000000..7d24f7db --- /dev/null +++ b/static/freebsd/man4/tmpfs.4 @@ -0,0 +1,229 @@ +.\"- +.\" Copyright (c) 2007 Xin LI +.\" Copyright (c) 2017 The FreeBSD Foundation +.\" +.\" Part of this documentation was written by +.\" Konstantin Belousov under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" 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 DOCUMENTATION 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. +.\" +.\"- +.\" Copyright (c) 2005, 2006 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 FOUNDATION 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 September 18, 2023 +.Dt TMPFS 4 +.Os +.Sh NAME +.Nm tmpfs +.Nd "in-memory file system" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "options TMPFS" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +tmpfs_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver implements an in-memory, or +.Nm +file system. +The filesystem stores both file metadata and data in main memory. +This allows very fast and low latency accesses to the data. +The data is volatile. +An umount or system reboot invalidates it. +These properties make the filesystem's mounts suitable for fast +scratch storage, like +.Pa /tmp . +.Pp +If the system becomes low on memory and swap is configured +.Po see +.Xr swapon 8 Pc , +the system can transfer file data to swap space, freeing memory +for other needs. +Metadata, including the directory content, is never swapped out by the +current implementation. +Keep this in mind when planning the mount limits, especially when expecting +to place many small files on a tmpfs mount. +.Pp +When +.Xr mmap 2 +is used on a file from a tmpfs mount, the swap VM object managing the +file pages is used to implement mapping and avoid double-copying of +the file data. +This quirk causes process inspection tools, like +.Xr procstat 1 , +to report anonymous memory mappings instead of file mappings. +.Sh OPTIONS +The following options are available when +mounting +.Nm +file systems: +.Bl -tag -width "maxfilesize" +.It Cm easize +Set the maximum memory size used by extended attributes in bytes. +The default is 16 megabytes. +.It Cm export +Accept the +.Cm export +option for compatibility with +.Xr nfsv4 4 . +This option does nothing. +.It Cm gid +Set the group ID of the root inode of the file system. +The default is the mount point's GID. +.It Cm inodes +Set the maximum number of nodes available to the file system. +If not specified, the file system chooses a reasonable maximum based on +the file system size, which can be limited with the +.Cm size +option. +.It Cm maxfilesize +Set the maximum file size in bytes. +The default is the maximum possible value. +.It Cm mode +Set the mode (in octal notation) of the root inode of the file system. +The default is the mount point's mode. +.It Cm nomtime +Disable the tracking of mtime updates caused by writes to the +shared mapped areas backed by +.Nm +files. +This option removes periodic scans, +which downgrade read-write-mapped pages to read-only to note the writes. +.It Cm nonc +Do not use namecache to resolve names to files for the created mount. +This saves memory, but currently might impair scalability for highly +used mounts on large machines. +.It Cm nosymfollow +Do not follow +.Xr symlink 7 Ap s +on the mounted file system. +.It Cm pgread +Enable pgcache read for the mount. +.It Cm size +Set the total file system size in bytes, unless suffixed +with one of k, m, g, t, or p, which denote byte, kilobyte, +megabyte, gigabyte, terabyte and petabyte respectively. +If zero (the default) or a value larger than SIZE_MAX - PAGE_SIZE +is given, the available amount of memory (including +main memory and swap space) will be used. +.It Cm uid +Set the user ID of the root inode of the file system. +The default is the mount point's UID. +.It Cm union +Refer to +.Xr mount 8 . +.El +.Sh SYSCTL VARIABLES +The following +.Xr sysctl 8 +variables are available: +.Bl -tag -width indent +.It Va vfs.tmpfs.memory_percent +The percentage of memory plus swap space available at kernel file system +initialization that can be used by a file system with a size of 0. +When this amount of space in use is reached, new files cannot be created +and files cannot be extended. +The default is 95%. +Changing this value also changes +.Va vfs.tmpfs.memory_reserved . +.It Va vfs.tmpfs.memory_reserved +The currently-reserved amount of memory plus swap space +based on the memory percentage. +The minimum is compiled into the system, and defaults to 4 MB. +.El +.Sh EXAMPLES +Mount a +.Nm +memory file system: +.Pp +.Dl "mount -t tmpfs tmpfs /tmp" +.Pp +Configure a +.Nm +mount via +.Xr fstab 5 : +.Bd -literal -offset indent +tmpfs /tmp tmpfs rw 0 0 +.Ed +.Sh SEE ALSO +.Xr procstat 1 , +.Xr mmap 2 , +.Xr nmount 2 , +.Xr unmount 2 , +.Xr fstab 5 , +.Xr mdmfs 8 , +.Xr mount 8 , +.Xr swapinfo 8 , +.Xr swapon 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 7.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +kernel implementation was written by +.An Julio M. Merino Vidal Aq Mt jmmv@NetBSD.org +as a Google Summer of Code project. +.Pp +.An Rohit Jalan +and others ported it from +.Nx +to +.Fx . +.Pp +This manual page was written by +.An Xin LI Aq Mt delphij@FreeBSD.org . diff --git a/static/freebsd/man4/tpm.4 b/static/freebsd/man4/tpm.4 new file mode 100644 index 00000000..8736d24d --- /dev/null +++ b/static/freebsd/man4/tpm.4 @@ -0,0 +1,122 @@ +.\" +.\" Copyright (c) 2010 Hans-Joerg Hoexer +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd October 31, 2018 +.Dt TPM 4 +.Os +.Sh NAME +.Nm tpm +.Nd Trusted Platform Module +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device tpm" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +tpm_load="YES" +.Ed +.Pp +In +.Pa /boot/device.hints : +.Cd hint.tpm.0.at="isa" +.Cd hint.tpm.0.maddr="0xfed40000" +.Cd hint.tpm.0.msize="0x5000" +.Cd hint.tpm.1.at="isa" +.Cd hint.tpm.1.maddr="0xfed40000" +.Cd hint.tpm.1.msize="0x1000" +.Sh DESCRIPTION +The +.Nm +driver provides support for various trusted platform modules (TPM) that can +store cryptographic keys. +.Pp +Supported modules: +.Pp +.Bl -bullet -compact -offset indent +.It +Atmel 97SC3203 +.It +Broadcom BCM0102 +.It +Infineon IFX SLD 9630 TT 1.1 and IFX SLB 9635 TT 1.2 +.It +Intel INTC0102 +.It +Sinosun SNS SSX35 +.It +STM ST19WP18 +.It +Winbond WEC WPCT200 +.El +.Pp +The driver can be configured to use an IRQ by providing a free ISA +interrupt vector in +.Pa /boot/device.hints . +.Sh SEE ALSO +.Xr intro 4 , +.Xr device.hints 5 , +.Xr config 8 +.Pp +The homepage of the BSSSD project, which developed the original +.Nm +driver: +.Lk "http://bsssd.sourceforge.net/" . +.Pp +TPM main specification can be found at: +.Lk "https://trustedcomputinggroup.org/resource/tpm-main-specification/" . +.Sh STANDARDS +TPM Main Specification Level 2 Version 1.2: +.Bl -dash +.It +.Rs +.%A ISO/IEC +.%T 11889-1:2009, Information technology -- Trusted Platform Module -- Part 1: Overview +.%U "https://www.iso.org/standard/50970.html" +.Re +.It +.Rs +.%A ISO/IEC +.%T 11889-2:2009, Information technology -- Trusted Platform Module -- Part 2: Design principles +.%U "https://www.iso.org/standard/50971.html" +.Re +.It +.Rs +.%A ISO/IEC +.%T 11889-3:2009, Information technology -- Trusted Platform Module -- Part 3: Structures +.%U "https://www.iso.org/standard/50972.html" +.Re +.El +.Sh HISTORY +The +.Nm +driver +first appeared in +.Fx 8.2 +and was later added to +.Ox 6.1 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Michael Shalayeff +and +.An Hans-Joerg Hoexer . diff --git a/static/freebsd/man4/tslog.4 b/static/freebsd/man4/tslog.4 new file mode 100644 index 00000000..e7f69a8d --- /dev/null +++ b/static/freebsd/man4/tslog.4 @@ -0,0 +1,137 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2022 Mateusz Piotrowski <0mp@FreeBSD.org> +.\" +.\" 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 June 1, 2022 +.Dt TSLOG 4 +.Os +.Sh NAME +.Nm tslog +.Nd Boot-time event tracing facility +.Sh SYNOPSIS +To compile this boot-time event tracing facility into the kernel, +place the following line in the kernel configuration file: +.Bd -ragged -offset indent +.Cd "option TSLOG" +.Ed +.Sh DESCRIPTION +.Nm +is a boot-time event tracing facility. +It is suitable for tracing recursive events +based on function entries and exits. +Its purpose is to ease pinpointing and reducing the overall +.Fx +boot time by generating detailed timing information. +.Pp +.Nm +is able to trace the boot loader, kernel initialization, and userland processes. +.Pp +In userland, it records the following details for each process ID: +.Bl -dash +.It +The timestamp of the +.Xr fork 2 +which creates the given process ID and the parent process ID. +.It +The path passed to +.Xr execve 2 , +if any. +.It +The first path resolved by +.Xr namei 9 , +if any. +.It +The timestamp of the +.Xr exit 3 +which terminates the process. +.El +.Sh SYSCTL VARIABLES +The following +.Xr sysctl 8 +variables are available: +.Bl -tag -width indent +.It Va debug.tslog +Dump the +.Nm +buffer of recorded loader and kernel event timestamps. +.It Va debug.tslog_user +Dump the +.Nm +buffer +of recorded userland event timestamps. +.El +.Sh FLAMEGRAPHS +The +.Nm +buffer dumps +can be used to generate flamegraphs of the +.Fx +boot process for visual analysis. +See +.Lk https://github.com/cperciva/freebsd-boot-profiling +for more information. +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr boottrace 4 , +.Xr ktr 4 +.Sh HISTORY +.Nm +first appeared in +.Fx 12.0 . +Support for tracing boot loaders and userland process +was added in +.Fx 13.2 . +.Ss TSLOG vs. Boottrace +.Nm +is oriented towards system developers while +.Xr boottrace 4 +is meant to be easy to use by system administrators. +Both facilities provide an overview of timing and resource usage of the boot +process. +.Ss TSLOG vs. DTrace +.Xr dtrace 1 +is not always the right tool for profiling early kernel initialization. +The reason is it requires some kernel subroutines +which are not yet available early in the boot process, e.g.: +traps, memory allocation, or thread scheduling. +.Nm +depends on fewer kernel subroutines than +.Xr dtrace 1 +and because of that can trace early kernel initialization. +.Ss TSLOG vs. KTR +.Xr ktr 4 +has a couple of limitations which prevent it from +being able to run at the start of the boot process. +In contrast, +.Nm +is designed for logging timestamped events for boot +profiling. +.Sh AUTHORS +.An -nosplit +.Nm +was written by +.An Colin Percival Aq Mt cperciva@FreeBSD.org . +.Pp +This manual page was written by +.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . diff --git a/static/freebsd/man4/tty.4 b/static/freebsd/man4/tty.4 new file mode 100644 index 00000000..ec93ff44 --- /dev/null +++ b/static/freebsd/man4/tty.4 @@ -0,0 +1,395 @@ +.\" Copyright (c) 1991, 1992, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 3, 2022 +.Dt TTY 4 +.Os +.Sh NAME +.Nm tty +.Nd general terminal interface +.Sh SYNOPSIS +.In sys/ioctl.h +.Sh DESCRIPTION +This section describes the interface to the terminal drivers +in the system. +.Ss Terminal Special Files +Each hardware terminal port on the system has several terminal special device +files associated with it in the directory ``/dev/'' (for +example, ``/dev/tty03'' and ``/dev/cua03''). +When a user logs into +the system on one of these hardware terminal ports, the system has already +opened the associated device and prepared the line for normal interactive +use (see +.Xr getty 8 . ) +There is also a special case of a terminal file that connects not to +a hardware terminal port, but to another program on the other side. +These special terminal devices are called +.Em ptys +and provide the mechanism necessary to give users the same interface to the +system when logging in over a network (using +.Xr telnet 1 +for example). +Even in these cases the details of how the terminal +file was opened and set up is already handled by special software +in the system. +Thus, users do not normally need to worry about the details of +how these lines are opened or used. +Also, these lines are often used +for dialing out of a system (through an out-calling modem), but again +the system provides programs that hide the details of accessing +these terminal special files (see +.Xr tip 1 ) . +.Pp +When an interactive user logs in, the system prepares the line to +behave in a certain way (called a +.Em "line discipline" ) , +the particular details of which is described in +.Xr stty 1 +at the command level, and in +.Xr termios 4 +at the programming level. +A user may be concerned with changing +settings associated with his particular login terminal and should refer +to the preceding man pages for the common cases. +The remainder of this man page is concerned +with describing details of using and controlling terminal devices +at a low level, such as that possibly required by a program wishing +to provide features similar to those provided by the system. +.Ss Terminal File Operations +All of the following operations are invoked using the +.Xr ioctl 2 +system call. +Refer to that man page for a description of the +.Em request +and +.Em argp +parameters. +In addition to the ioctl +.Em requests +defined here, the specific line discipline +in effect will define other +.Em requests +specific to it (actually +.Xr termios 4 +defines them as function calls, not ioctl +.Em requests . ) +The following section lists the available ioctl requests. +The name of the request, a description of its purpose, and the typed +.Em argp +parameter (if any) +are listed. +For example, the first entry says +.Pp +.D1 Em "TIOCSPGRP int *tpgrp" +.Pp +and would be called on the terminal associated with +file descriptor zero by the following code fragment: +.Bd -literal + int pgrp; + + pgrp = getpgrp(); + ioctl(0, TIOCSPGRP, &pgrp); +.Ed +.Ss Terminal File Request Descriptions +.Bl -tag -width TIOCGWINSZ +.It Dv TIOCSETD Fa int *ldisc +This call is obsolete but left for compatibility. +Before +.Fx 8.0 , +it would change to the new line discipline pointed to by +.Fa ldisc . +.It Dv TIOCGETD Fa int *ldisc +Return the current line discipline in the integer pointed to by +.Fa ldisc . +.It Dv TIOCSBRK Fa void +Set the terminal hardware into BREAK condition. +.It Dv TIOCCBRK Fa void +Clear the terminal hardware BREAK condition. +.It Dv TIOCSDTR Fa void +Assert data terminal ready (DTR). +.It Dv TIOCCDTR Fa void +Clear data terminal ready (DTR). +.It Dv TIOCGPGRP Fa int *tpgrp +Return the current process group with which the terminal is associated +in the integer pointed to by +.Fa tpgrp . +This is the underlying call that implements the +.Xr termios 4 +.Fn tcgetattr +call. +.It Dv TIOCSPGRP Fa int *tpgrp +Associate the terminal with the process group (as an integer) pointed to by +.Fa tpgrp . +This is the underlying call that implements the +.Xr termios 4 +.Fn tcsetattr +call. +.It Dv TIOCGETA Fa struct termios *term +Place the current value of the termios state associated with the +device in the termios structure pointed to by +.Fa term . +This is the underlying call that implements the +.Xr termios 4 +.Fn tcgetattr +call. +.It Dv TIOCSETA Fa struct termios *term +Set the termios state associated with the device immediately. +This is the underlying call that implements the +.Xr termios 4 +.Fn tcsetattr +call with the +.Dv TCSANOW +option. +.It Dv TIOCSETAW Fa struct termios *term +First wait for any output to complete, then set the termios state +associated with the device. +This is the underlying call that implements the +.Xr termios 4 +.Fn tcsetattr +call with the +.Dv TCSADRAIN +option. +.It Dv TIOCSETAF Fa struct termios *term +First wait for any output to complete, clear any pending input, +then set the termios state associated with the device. +This is the underlying call that implements the +.Xr termios 4 +.Fn tcsetattr +call with the +.Dv TCSAFLUSH +option. +.It Dv TIOCOUTQ Fa int *num +Place the current number of characters in the output queue in the +integer pointed to by +.Fa num . +.It Dv TIOCSTI Fa char *cp +Simulate typed input. +Pretend as if the terminal received the character pointed to by +.Fa cp . +.It Dv TIOCNOTTY Fa void +In the past, when a process that did not have a controlling terminal (see +.Em The Controlling Terminal +in +.Xr termios 4 ) +first opened a terminal device, it acquired that terminal as its +controlling terminal. +For some programs this was a hazard as they +did not want a controlling terminal in the first place, and this +provides a mechanism to disassociate the controlling terminal from +the calling process. +It +.Em must +be called by opening the file +.Pa /dev/tty +and calling +.Dv TIOCNOTTY +on that file descriptor. +.Pp +The current system does not allocate a controlling terminal to +a process on an +.Fn open +call: there is a specific ioctl called +.Dv TIOCSCTTY +to make a terminal the controlling +terminal. +In addition, a program can +.Fn fork +and call the +.Fn setsid +system call which will place the process into its own session - which +has the effect of disassociating it from the controlling terminal. +This is the new and preferred method for programs to lose their controlling +terminal. +.Pp +However, environmental restrictions may prohibit the process from being able to +.Fn fork +and call the +.Fn setsid +system call to disassociate it from the controlling terminal. +In this case, it must use +.Dv TIOCNOTTY . +.It Dv TIOCSTOP Fa void +Stop output on the terminal (like typing ^S at the keyboard). +.It Dv TIOCSTART Fa void +Start output on the terminal (like typing ^Q at the keyboard). +.It Dv TIOCSCTTY Fa void +Make the terminal the controlling terminal for the process (the process +must not currently have a controlling terminal). +.It Dv TIOCDRAIN Fa void +Wait until all output is drained, or until the drain wait timeout expires. +.It Dv TIOCGDRAINWAIT Fa int *timeout +Return the current drain wait timeout in seconds. +.It Dv TIOCSDRAINWAIT Fa int *timeout +Set the drain wait timeout in seconds. +A value of zero disables timeouts. +The default drain wait timeout is controlled by the tunable +.Xr sysctl 8 +OID +.Va kern.tty_drainwait . +.It Dv TIOCEXCL Fa void +Set exclusive use on the terminal. +No further opens are permitted except by root. +Of course, this means that programs that are run by +root (or setuid) will not obey the exclusive setting - which limits +the usefulness of this feature. +.It Dv TIOCNXCL Fa void +Clear exclusive use of the terminal. +Further opens are permitted. +.It Dv TIOCFLUSH Fa int *what +If the value of the int pointed to by +.Fa what +contains the +.Dv FREAD +bit as defined in +.In sys/file.h , +then all characters in the input queue are cleared. +If it contains the +.Dv FWRITE +bit, then all characters in the output queue are cleared. +If the value of the integer is zero, then it behaves as if both the +.Dv FREAD +and +.Dv FWRITE +bits were set (i.e., clears both queues). +.It Dv TIOCGWINSZ Fa struct winsize *ws +Put the window size information associated with the terminal in the +.Va winsize +structure pointed to by +.Fa ws . +The window size structure contains the number of rows and columns (and pixels +if appropriate) of the devices attached to the terminal. +It is set by user software +and is the means by which most full\&-screen oriented programs determine the +screen size. +The +.Va winsize +structure is provided by +.In sys/ioctl.h . +.It Dv TIOCSWINSZ Fa struct winsize *ws +Set the window size associated with the terminal to be the value in +the +.Va winsize +structure pointed to by +.Fa ws +(see above). +.It Dv TIOCCONS Fa int *on +If +.Fa on +points to a non-zero integer, redirect kernel console output (kernel printf's) +to this terminal. +If +.Fa on +points to a zero integer, redirect kernel console output back to the normal +console. +This is usually used on workstations to redirect kernel messages +to a particular window. +.It Dv TIOCMSET Fa int *state +The integer pointed to by +.Fa state +contains bits that correspond to modem state. +Following is a list of defined variables and the modem state they represent: +.Pp +.Bl -tag -width TIOCMXCTS -compact +.It TIOCM_LE +Line Enable. +.It TIOCM_DTR +Data Terminal Ready. +.It TIOCM_RTS +Request To Send. +.It TIOCM_ST +Secondary Transmit. +.It TIOCM_SR +Secondary Receive. +.It TIOCM_CTS +Clear To Send. +.It TIOCM_CAR +Carrier Detect. +.It TIOCM_CD +Carrier Detect (synonym). +.It TIOCM_RNG +Ring Indication. +.It TIOCM_RI +Ring Indication (synonym). +.It TIOCM_DSR +Data Set Ready. +.El +.Pp +This call sets the terminal modem state to that represented by +.Fa state . +Not all terminals may support this. +.It Dv TIOCMGET Fa int *state +Return the current state of the terminal modem lines as represented +above in the integer pointed to by +.Fa state . +.It Dv TIOCMBIS Fa int *state +The bits in the integer pointed to by +.Fa state +represent modem state as described above, however the state is OR-ed +in with the current state. +.It Dv TIOCMBIC Fa int *state +The bits in the integer pointed to by +.Fa state +represent modem state as described above, however each bit which is on +in +.Fa state +is cleared in the terminal. +.El +.Sh IMPLEMENTATION NOTES +The total number of input and output bytes +through all terminal devices +are available via the +.Va kern.tty_nin +and +.Va kern.tty_nout +read-only +.Xr sysctl 8 +variables. +.Sh SEE ALSO +.Xr stty 1 , +.Xr ioctl 2 , +.Xr ng_tty 4 , +.Xr pts 4 , +.Xr pty 4 , +.Xr termios 4 , +.Xr uart 4 , +.Xr getty 8 +.Sh HISTORY +A console typewriter device +.Pa /dev/tty +and asynchronous communication interfaces +.Pa /dev/tty[0-5] +first appeared in +.At v1 . +.Sh BUGS +Before the Internet, serial ports were primarily used for inbound +connections from terminals, either directly or through modems, these +days serial ports are primarily used for outbound connections to +devices, an evolution which unfortunately has spread the relevant +documentation over three different manual pages: +.Xr termios 4 , +.Xr uart 4 and +.Xr tty 4 . diff --git a/static/freebsd/man4/tun.4 b/static/freebsd/man4/tun.4 new file mode 100644 index 00000000..1c5bd35f --- /dev/null +++ b/static/freebsd/man4/tun.4 @@ -0,0 +1,358 @@ +.\" $NetBSD: tun.4,v 1.1 1996/06/25 22:17:37 pk Exp $ +.\" Based on PR#2411 +.\" +.Dd March 17, 2020 +.Dt TUN 4 +.Os +.Sh NAME +.Nm tun +.Nd tunnel software network interface +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device tuntap" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_tuntap_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +interface is a software loopback mechanism that can be loosely +described as the network interface analog of the +.Xr pty 4 , +that is, +.Nm +does for network interfaces what the +.Xr pty 4 +driver does for terminals. +.Pp +The +.Nm +driver, like the +.Xr pty 4 +driver, provides two interfaces: an interface like the usual facility +it is simulating +(a network interface in the case of +.Nm , +or a terminal for +.Xr pty 4 ) , +and a character-special device +.Dq control +interface. +A client program transfers IP (by default) packets to or from the +.Nm +.Dq control +interface. +The +.Xr tap 4 +interface provides similar functionality at the Ethernet layer: +a client will transfer Ethernet frames to or from a +.Xr tap 4 +.Dq control +interface. +.Pp +The network interfaces are named +.Dq Li tun0 , +.Dq Li tun1 , +etc., one for each control device that has been opened. +These network interfaces persist until the +.Pa if_tuntap.ko +module is unloaded, or until removed with the +.Xr ifconfig 8 +command. +.Pp +.Nm +devices are created using interface cloning. +This is done using the +.Dq ifconfig tun Ns Sy N No create +command. +This is the preferred method of creating +.Nm +devices. +The same method allows removal of interfaces. +For this, use the +.Dq ifconfig tun Ns Sy N No destroy +command. +.Pp +If the +.Xr sysctl 8 +variable +.Va net.link.tun.devfs_cloning +is non-zero, the +.Nm +interface +permits opens on the special control device +.Pa /dev/tun . +When this device is opened, +.Nm +will return a handle for the lowest unused +.Nm +device (use +.Xr devname 3 +to determine which). +.Pp +.Bf Em +Disabling the legacy devfs cloning functionality may break existing +applications which use +.Nm , +such as +.Xr ppp 8 +and +.Xr ssh 1 . +It therefore defaults to being enabled until further notice. +.Ef +.Pp +Control devices (once successfully opened) persist until +.Pa if_tuntap.ko +is unloaded in the same way that network interfaces persist (see above). +.Pp +Each interface supports the usual network-interface +.Xr ioctl 2 Ns s , +such as +.Dv SIOCAIFADDR +and thus can be used with +.Xr ifconfig 8 +like any other interface. +At boot time, they are +.Dv POINTOPOINT +interfaces, but this can be changed; see the description of the control +device, below. +When the system chooses to transmit a packet on the +network interface, the packet can be read from the control device +(it appears as +.Dq input +there); +writing a packet to the control device generates an input +packet on the network interface, as if the (non-existent) +hardware had just received it. +.Pp +The tunnel device +.Pq Pa /dev/tun Ns Ar N +is exclusive-open +(it cannot be opened if it is already open). +A +.Xr read 2 +call will return an error +.Pq Er EHOSTDOWN +if the interface is not +.Dq ready +(which means that the control device is open and the interface's +address has been set). +.Pp +Once the interface is ready, +.Xr read 2 +will return a packet if one is available; if not, it will either block +until one is or return +.Er EWOULDBLOCK , +depending on whether non-blocking I/O has been enabled. +If the packet is longer than is allowed for in the buffer passed to +.Xr read 2 , +the extra data will be silently dropped. +.Pp +If the +.Dv TUNSLMODE +ioctl has been set, packets read from the control device will be prepended +with the destination address as presented to the network interface output +routine, +.Fn tunoutput . +The destination address is in +.Vt struct sockaddr +format. +The actual length of the prepended address is in the member +.Va sa_len . +If the +.Dv TUNSIFHEAD +ioctl has been set, packets will be prepended with a four byte address +family in network byte order. +.Dv TUNSLMODE +and +.Dv TUNSIFHEAD +are mutually exclusive. +In any case, the packet data follows immediately. +.Pp +A +.Xr write 2 +call passes a packet in to be +.Dq received +on the pseudo-interface. +If the +.Dv TUNSIFHEAD +ioctl has been set, the address family must be prepended, otherwise the +packet is assumed to be of type +.Dv AF_INET . +Each +.Xr write 2 +call supplies exactly one packet; the packet length is taken from the +amount of data provided to +.Xr write 2 +(minus any supplied address family). +Writes will not block; if the packet cannot be accepted for a +transient reason +(e.g., no buffer space available), +it is silently dropped; if the reason is not transient +(e.g., packet too large), +an error is returned. +.Pp +The following +.Xr ioctl 2 +calls are supported +(defined in +.In net/if_tun.h ) : +.Bl -tag -width ".Dv TUNSIFMODE" +.It Dv TUNSDEBUG +The argument should be a pointer to an +.Vt int ; +this sets the internal debugging variable to that value. +What, if anything, this variable controls is not documented here; see +the source code. +.It Dv TUNGDEBUG +The argument should be a pointer to an +.Vt int ; +this stores the internal debugging variable's value into it. +.It Dv TUNSIFINFO +The argument should be a pointer to an +.Vt struct tuninfo +and allows setting the MTU and the baudrate of the tunnel +device. +The type must be the same as returned by +.Dv TUNGIFINFO +or set to +.Dv IFT_PPP +else the +.Xr ioctl 2 +call will fail. +The +.Vt struct tuninfo +is declared in +.In net/if_tun.h . +.Pp +The use of this ioctl is restricted to the super-user. +.It Dv TUNGIFINFO +The argument should be a pointer to an +.Vt struct tuninfo , +where the current MTU, type, and baudrate will be stored. +.It Dv TUNSIFMODE +The argument should be a pointer to an +.Vt int ; +its value must be either +.Dv IFF_POINTOPOINT +or +.Dv IFF_BROADCAST +and should have +.Dv IFF_MULTICAST +OR'd into the value if multicast support is required. +The type of the corresponding +.Dq Li tun Ns Ar N +interface is set to the supplied type. +If the value is outside the above range, an +.Er EINVAL +error is returned. +The interface must be down at the time; if it is up, an +.Er EBUSY +error is returned. +.It Dv TUNSLMODE +The argument should be a pointer to an +.Vt int ; +a non-zero value turns off +.Dq multi-af +mode and turns on +.Dq link-layer +mode, causing packets read from the tunnel device to be prepended with +the network destination address (see above). +.It Dv TUNSIFPID +Will set the pid owning the tunnel device to the current process's pid. +.It Dv TUNSIFHEAD +The argument should be a pointer to an +.Vt int ; +a non-zero value turns off +.Dq link-layer +mode, and enables +.Dq multi-af +mode, where every packet is preceded with a four byte address family. +.It Dv TUNGIFHEAD +The argument should be a pointer to an +.Vt int ; +the ioctl sets the value to one if the device is in +.Dq multi-af +mode, and zero otherwise. +.It Dv TUNSTRANSIENT +The argument should be a pointer to an +.Va int ; +this sets the transient flag on +the +.Nm +device. +A transient +.Nm +will be destroyed upon last close. +.It Dv TUNGTRANSIENT +The argument should be a pointer to an +.Va int ; +this stores the current state (enabled or disabled) of the transient flag into +it. +.It Dv FIONBIO +Turn non-blocking I/O for reads off or on, according as the argument +.Vt int Ns 's +value is or is not zero. +(Writes are always non-blocking.) +.It Dv FIOASYNC +Turn asynchronous I/O for reads +(i.e., generation of +.Dv SIGIO +when data is available to be read) +off or on, according as the argument +.Vt int Ns 's +value is or is not zero. +.It Dv FIONREAD +If any packets are queued to be read, store the size of the first one +into the argument +.Vt int ; +otherwise, store zero. +.It Dv TIOCSPGRP +Set the process group to receive +.Dv SIGIO +signals, when asynchronous I/O is enabled, to the argument +.Vt int +value. +.It Dv TIOCGPGRP +Retrieve the process group value for +.Dv SIGIO +signals into the argument +.Vt int +value. +.El +.Pp +The control device also supports +.Xr select 2 +for read; selecting for write is pointless, and always succeeds, since +writes are always non-blocking. +.Pp +On the last close of the data device, by default, the interface is +brought down +(as if with +.Nm ifconfig Ar tunN Cm down ) . +All queued packets are thrown away. +If the interface is up when the data device is not open +output packets are always thrown away rather than letting +them pile up. +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr read 2 , +.Xr select 2 , +.Xr write 2 , +.Xr devname 3 , +.Xr inet 4 , +.Xr intro 4 , +.Xr pty 4 , +.Xr tap 4 , +.Xr ifconfig 8 +.Sh AUTHORS +This manual page was originally obtained from +.Nx . diff --git a/static/freebsd/man4/tws.4 b/static/freebsd/man4/tws.4 new file mode 100644 index 00000000..35ac3091 --- /dev/null +++ b/static/freebsd/man4/tws.4 @@ -0,0 +1,116 @@ +.\" +.\"Copyright (c) 2010, 2011 iXsystems, Inc. +.\"All rights reserved. +.\" written by: Xin LI +.\" +.\"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 October 4, 2011 +.Dt TWS 4 +.Os +.Sh NAME +.Nm tws +.Nd 3ware 9750 SATA+SAS 6Gb/s RAID controller card driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device scbus" +.Cd "device tws" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +tws_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for LSI's 3ware 9750 SATA+SAS 6Gb/s RAID controller cards. +.Pp +These controllers feature the LSISAS2108 6Gb/s SAS RAID-on-Chip (ROC) +and are available in 4- and 8-port configurations, supports RAID levels +0, 1, 5, 6, 10, 50 and single disk, with 96 SATA and/or SAS hard drives and SSDs. +.Pp +For further hardware information, see +.Pa http://www.lsi.com/. +.Sh HARDWARE +The +.Nm +driver supports the following SATA/SAS RAID controller: +.Pp +.Bl -bullet -compact +.It +LSI's 3ware SAS 9750 series +.El +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width "hw.tws.use_32bit_sgls" +.It Va hw.tws.cam_depth +The maximum queued CAM SIM requests for one controller. +The default value is 256. +.It Va hw.tws.enable_msi +This tunable enables MSI support on the controller if set to a non-zero value. +The default value is 0. +.It Va hw.tws.queue_depth +The maximum queued requests for one controller. +.It Va hw.tws.use_32bit_sgls +Limit the driver to use only 32-bit SG elements regardless whether the operating +system is running in 64-bit mode. +The default value is 0. +.El +.Sh FILES +.Bl -tag -width ".Pa /dev/tws?" -compact +.It Pa /dev/da? +array/logical disk interface +.It Pa /dev/tws? +management interface +.El +.Sh DIAGNOSTICS +Whenever the driver encounters a command failure, it prints out an error code in +the format: +.Qq Li "ERROR: (: ):" , +followed by a text description of the error. +There are other error messages and warnings that the +driver prints out, depending on the kinds of errors that it encounters. +If the driver is compiled with +.Dv TWS_DEBUG +defined, it prints out a whole bunch of debug +messages. +.Sh SEE ALSO +.Xr da 4 , +.Xr scsi 4 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Manjunath Ranganathaiah +for LSI and this manual page was written by +.An Xin LI Aq Mt delphij@FreeBSD.org +for iXsystems, Inc. diff --git a/static/freebsd/man4/u2f.4 b/static/freebsd/man4/u2f.4 new file mode 100644 index 00000000..4c51e140 --- /dev/null +++ b/static/freebsd/man4/u2f.4 @@ -0,0 +1,96 @@ +.\" +.\" SPDX-License-Identifier: ISC +.\" +.\" $OpenBSD: fido.4,v 1.4 2020/08/21 19:02:46 mglocker Exp $ +.\" +.\" Copyright (c) 2019 Reyk Floeter +.\" Copyright (c) 2023 Vladimir Kondratyev +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd August 21, 2023 +.Dt U2F 4 +.Os +.Sh NAME +.Nm u2f +.Nd FIDO/U2F USB security keys +.Sh SYNOPSIS +.Cd "device u2f" +.Pp +In +.Xr loader.conf 5 : +.Cd u2f_load="YES" +.Pp +In +.Xr sysctl.conf 5 : +.Cd hw.hid.u2f.debug +.Sh DESCRIPTION +The +.Nm +driver provides support for FIDO/U2F-compatible USB security keys. +They are Human Interface Devices (HID) which can be accessed via the +.Pa /dev/u2f/N +interface. +.Pp +The driver is compatible with the +.Xr read 2 , +.Xr write 2 , +and +.Xr ioctl 2 +operations of the generic +.Xr uhid 4 +device but only accepts the optional HID +.Xr ioctl 2 +calls from u2f group users. +.Sh HARDWARE +The +.Nm +driver supports FIDO/U2F-compatible USB security keys. +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va hw.hid.u2f.debug +Debug output level, where 0 is debugging disabled and larger values increase +debug message verbosity. +Default is 0. +.El +.Sh FILES +.Bl -tag -width /dev/u2f/* -compact +.It Pa /dev/u2f/* +.El +.Sh SEE ALSO +.Xr uhid 4 , +.Xr usbhid 4 , +.Xr usb 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 15.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org . +.Pp +This manual page was written by +.An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org +based on the +.Ox +.Xr fido 4 +manual page. diff --git a/static/freebsd/man4/u3g.4 b/static/freebsd/man4/u3g.4 new file mode 100644 index 00000000..c7bf1f98 --- /dev/null +++ b/static/freebsd/man4/u3g.4 @@ -0,0 +1,175 @@ +.\"- +.\" SPDX-License-Identifier: ISC +.\" +.\" Copyright (c) 2008 AnyWi Technologies +.\" All rights reserved. +.\" +.\" This code is derived from uark.c +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd December 5, 2024 +.Dt U3G 4 +.Os +.Sh NAME +.Nm u3g +.Nd USB support for 3G and 4G cellular modems +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device usb" +.Cd "device ucom" +.Cd "device u3g" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +u3g_load="YES" +.Ed +.Pp +If neither of the above is done, the driver will be +automatically loaded by devd(8) when the device is connected. +.Sh DESCRIPTION +The +.Nm +driver provides support for USB-to-serial interfaces +exposed by many 3G and 4G modems. +The supported adapters provide the necessary modem port for +.Xr ppp 8 , +or +.Pa net/mpd5 +connections. +Depending on the specific device, extra ports provide other functions +such as an additional command port, diagnostic port, +GPS receiver port, or SIM toolkit port. +.Pp +The device is accessed through the +.Xr ucom 4 +driver which makes it behave like a +.Xr tty 4 . +.Pp +In some adapters a mass storage device supported by the +.Xr umass 4 +driver is present which contains Windows and Mac OS X drivers. +The device starts up in disk mode (TruInstall, ZeroCD, etc.) +and requires additional commands to switch it to modem mode. +If your device is not switching automatically, please try to add quirks. +See +.Xr usbconfig 8 +and +.Xr usb_quirk 4 . +.Sh HARDWARE +The +.Nm +driver supports the following cellular modems: +.Pp +.Bl -bullet -compact +.It +Option GT 3G Fusion, GT Fusion Quad, etc. +.Pq 3G only, not WLAN +.It +Option GT 3G, GT 3G Quad, etc. +.It +Vodafone Mobile Connect Card 3G +.It +Vodafone Mobile Broadband K3772-Z +.It +Qualcomm Inc. CDMA MSM +.It +Qualcomm Inc. GOBI 1000, 2000 and 3000 devices with MDM1000 or MDM2000 chipsets +.It +QUECTEL BGX, ECX, EGX, EMX, EPX, RGX series +.It +Quectel EM160R, EM060K +.Pq see Sx CAVEATS +.It +Huawei B190, E180v, E220, E3372, E3372v153, E5573Cs322, ('') +.It +Novatel U740, MC950D, X950D, etc. +.It +Sierra MC875U, MC8775U, EM7590, etc. +.It +Panasonic CF-F9 GOBI +.El +.Pp +Many more are supported, see +.Pa /sys/dev/usb/serial/u3g.c +for the complete list. +.Sh FILES +.Bl -tag -width "/dev/ttyU*.*.init" -compact +.It Pa /dev/ttyU*.* +for callin ports +.It Pa /dev/ttyU*.*.init +.It Pa /dev/ttyU*.*.lock +corresponding callin initial-state and lock-state devices +.Pp +.It Pa /dev/cuaU*.* +for callout ports +.It Pa /dev/cuaU*.*.init +.It Pa /dev/cuaU*.*.lock +corresponding callout initial-state and lock-state devices +.El +.Sh EXAMPLES +Connect to the Internet using the default configuration: +.Bd -literal -offset indent +ppp -background u3g +.Ed +.Sh SEE ALSO +.Xr tty 4 , +.Xr ucom 4 , +.Xr usb 4 , +.Xr usb_quirk 4 , +.Xr devd 8 , +.Xr ppp 8 , +.Xr usbconfig 8 +.Sh HISTORY +The +.Nm +driver appeared in +.Fx 7.2 , +is based on the +.Xr uark 4 +driver, and written by +.An Andrea Guzzo Aq Mt aguzzo@anywi.com +in September 2008. +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Andrea Guzzo Aq Mt aguzzo@anywi.com +and +.An Nick Hibma Aq Mt n_hibma@FreeBSD.org . +Hardware for testing was provided by AnyWi Technologies, Leiden, NL. +.Sh CAVEATS +The Quectel EM160R is not officially supported in PPP mode. +In order to use it in PPP mode, the ctsrts option needs to be turned off, +for example, by adding: +.Pp +.Dl set ctsrts off +.Pp +to +.Pa /etc/ppp/ppp.conf +in the correct section. +.Sh BUGS +The automatic mode switch from disk mode to modem mode does not work unless +the driver is either built into the kernel or loaded before the device is +connected. +.Pp +The GOBI-based devices require the gobi loader available from the +.Pa sysutils/gobi_loader +port. diff --git a/static/freebsd/man4/uark.4 b/static/freebsd/man4/uark.4 new file mode 100644 index 00000000..7c16921e --- /dev/null +++ b/static/freebsd/man4/uark.4 @@ -0,0 +1,96 @@ +.\" $OpenBSD: uark.4,v 1.3 2006/10/26 19:42:36 jmc Exp $ +.\" +.\" Copyright (c) 2006 Jonathan Gray +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd April 26, 2017 +.Dt UARK 4 +.Os +.Sh NAME +.Nm uark +.Nd Arkmicro Technologies ARK3116 based USB serial adapter +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device usb" +.Cd "device ucom" +.Cd "device uark" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +uark_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports Arkmicro Technologies ARK3116 based serial adapters. +.Sh HARDWARE +The +.Nm +driver supports the following adapters: +.Pp +.Bl -bullet -compact +.It +HL USB-RS232 +.It +HugePine USB-UART +.It +KQ-U8A Data Cable +.It +Skymaster USB to RS232 +.El +.Sh FILES +.Bl -tag -width "/dev/ttyU*.init" -compact +.It Pa /dev/ttyU* +for callin ports +.It Pa /dev/ttyU*.init +.It Pa /dev/ttyU*.lock +corresponding callin initial-state and lock-state devices +.Pp +.It Pa /dev/cuaU* +for callout ports +.It Pa /dev/cuaU*.init +.It Pa /dev/cuaU*.lock +corresponding callout initial-state and lock-state devices +.El +.Sh SEE ALSO +.Xr tty 4 , +.Xr ucom 4 , +.Xr usb 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Ox 4.0 . +The first +.Fx +release to include it was +.Fx 7.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Jonathan Gray Aq Mt jsg@openbsd.org . +.Sh CAVEATS +Setting hardware flow control is not currently supported. +It is not yet known how to ask the hardware to send a break. +.Pp +Arkmicro Technologies do not reply to requests of documentation +for their products. diff --git a/static/freebsd/man4/uart.4 b/static/freebsd/man4/uart.4 new file mode 100644 index 00000000..f0b6b23b --- /dev/null +++ b/static/freebsd/man4/uart.4 @@ -0,0 +1,403 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2003 Marcel Moolenaar +.\" 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 ``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 December 5, 2024 +.Dt UART 4 +.Os +.Sh NAME +.Nm uart +.Nd Universal Asynchronous Receiver/Transmitter serial driver +.Sh SYNOPSIS +.Cd "device uart" +.Pp +.Cd "device puc" +.Cd "device uart" +.Pp +.Cd "device scc" +.Cd "device uart" +.Pp +In +.Pa /boot/device.hints : +.Cd hint.uart.0.disabled="1" +.Cd hint.uart.0.baud="38400" +.Cd hint.uart.0.port="0x3f8" +.Cd hint.uart.0.flags="0x10" +.Pp +With +.Ar flags +encoded as: +.Bl -tag -compact -width 0x000000 +.It 0x00010 +device is potential system console +.It 0x00080 +use this port for remote kernel debugging +.It 0x00100 +set RX FIFO trigger level to ``low'' (NS8250 only) +.It 0x00200 +set RX FIFO trigger level to ``medium low'' (NS8250 only) +.It 0x00400 +set RX FIFO trigger level to ``medium high'' (default, NS8250 only) +.It 0x00800 +set RX FIFO trigger level to ``high'' (NS8250 only) +.El +.\" +.Sh DESCRIPTION +The +.Nm +device driver provides support for various classes of UARTs implementing the +EIA RS-232C (CCITT V.24) serial communications interface. +Each such interface is controlled by a separate and independent instance of +the +.Nm +driver. +The primary support for devices that contain multiple serial interfaces or +that contain other functionality besides one or more serial interfaces is +provided by the +.Xr puc 4 , +or +.Xr scc 4 +device drivers. +However, the serial interfaces of those devices that are managed by the +.Xr puc 4 , +or +.Xr scc 4 +driver are each independently controlled by the +.Nm +driver. +As such, the +.Xr puc 4 , +or +.Xr scc 4 +driver provides umbrella functionality for the +.Nm +driver and hides the complexities that are inherent when elementary components +are packaged together. +.Pp +The +.Nm +driver has a modular design to allow it to be used on differing hardware and +for various purposes. +In the following sections the components are discussed in detail. +Options are described in the section that covers the component to which each +option applies. +.\" +.Ss CORE COMPONENT +At the heart of the +.Nm +driver is the core component. +It contains the bus attachments and the low-level interrupt handler. +.\" +.Ss HARDWARE DRIVERS +The core component and the kernel interfaces talk to the hardware through the +hardware interface. +This interface serves as an abstraction of the hardware and allows varying +UARTs to be used for serial communications. +.\" +.Ss SYSTEM DEVICES +System devices are UARTs that have a special purpose by way of hardware +design or software setup. +For example, Sun UltraSparc machines use UARTs as their keyboard interface. +Such an UART cannot be used for general purpose communications. +Likewise, when the kernel is configured for a serial console, the +corresponding UART will in turn be a system device so that the kernel can +output boot messages early on in the boot process. +.\" +.Ss KERNEL INTERFACES +The last but not least of the components is the kernel interface. +This component ultimately determines how the UART is made visible to the +kernel in particular and to users in general. +The default kernel interface is the TTY interface. +This allows the UART to be used for terminals, modems and serial line IP +applications. +System devices, with the notable exception of serial consoles, generally +have specialized kernel interfaces. +.\" +.Sh HARDWARE +The +.Nm +driver supports the following classes of UARTs: +.Pp +.Bl -bullet -compact +.It +NS8250: standard hardware based on the 8250, 16450, 16550, 16650, 16750 or +the 16950 UARTs. +.It +SCC: serial communications controllers supported by the +.Xr scc 4 +device driver. +.El +.\" +.Sh Pulse Per Second (PPS) Timing Interface +The +.Nm +driver can capture PPS timing information as defined in RFC 2783. +The API, accessed via +.Xr ioctl 2 , +is available on the tty device. +To use the PPS capture feature with +.Xr ntpd 8 , +symlink the tty callout device +.Va /dev/cuau? +to +.Va /dev/pps0. +.Pp +The +.Va hw.uart.pps_mode +tunable configures the PPS capture mode for all uart devices; +it can be set in +.Xr loader.conf 5 . +The +.Va dev.uart.0.pps_mode +sysctl configures the PPS capture mode for a specific uart device; +it can be set in +.Xr loader.conf 5 +or +.Xr sysctl.conf 5 . +.Pp +The following capture modes are available: +.Bl -tag -compact -offset "mmmm" -width "mmmm" +.It 0x00 +Capture disabled. +.It 0x01 +Capture pulses on the CTS line. +.It 0x02 +Capture pulses on the DCD line. +.El +.Pp +The following values may be ORed with the capture mode to configure +capture processing options: +.Bl -tag -compact -offset "mmmm" -width "mmmm" +.It 0x10 +Invert the pulse (RS-232 logic low = ASSERT, high = CLEAR). +.It 0x20 +Attempt to capture narrow pulses. +.El +.Pp +Add the narrow pulse option when the incoming PPS pulse width is small +enough to prevent reliable capture in normal mode. +In narrow mode the driver uses the hardware's ability to latch a line +state change; not all hardware has this capability. +The hardware latch provides a reliable indication that a pulse occurred, +but prevents distinguishing between the CLEAR and ASSERT edges of the pulse. +For each detected pulse, the driver synthesizes both an ASSERT and a CLEAR +event, using the same timestamp for each. +To prevent spurious events when the hardware is intermittently able to +see both edges of a pulse, the driver will not generate a new pair of +events within a half second of the prior pair. +Both normal and narrow pulse modes work with +.Xr ntpd 8 . +.Pp +Add the invert option when the connection to the uart device uses TTL +level signals, or when the PPS source emits inverted pulses. +RFC 2783 defines an ASSERT event as a higher-voltage line level, and a CLEAR +event as a lower-voltage line level, in the context of the RS-232 protocol. +The modem control signals on a TTL-level connection are typically +inverted from the RS-232 levels. +For example, carrier presence is indicated by a high signal on an RS-232 +DCD line, and by a low signal on a TTL DCD line. +This is due to the use of inverting line driver buffers to convert between +TTL and RS-232 line levels in most hardware designs. +Generally speaking, a connection to a DB-9 style connector is an RS-232 +level signal at up to 12 volts. +A connection to header pins or an edge-connector on an embedded board +is typically a TTL signal at 3.3 or 5 volts. +.Sh Special Devices +The +.Nm +driver also supports an initial-state and a lock-state control +device for each of the callin and the callout "data" devices. +The termios settings of a data device are copied +from those of the corresponding initial-state device +on first opens and are not inherited from previous opens. +Use +.Xr stty 1 +in the normal way on the initial-state devices to program +initial termios states suitable for your setup. +.Pp +The lock termios state acts as flags to disable changing +the termios state. +E.g., to lock a flag variable such as CRTSCTS, use +.Em stty crtscts +on the lock-state device. +Speeds and special characters +may be locked by setting the corresponding value in the lock-state +device to any nonzero value. +E.g., to lock a speed to 115200, use +.Dq Li stty 115200 +on the initial-state device and +.Dq Li stty 1 +on the lock-state device. +.Pp +Correct programs talking to correctly wired external devices +work with almost arbitrary initial states and almost no locking, +but other setups may benefit from changing some of the default +initial state and locking the state. +In particular, the initial states for non (POSIX) standard flags +should be set to suit the devices attached and may need to be +locked to prevent buggy programs from changing them. +E.g., CRTSCTS should be locked on for devices that support +RTS/CTS handshaking at all times and off for devices that do not +support it at all. +CLOCAL should be locked on for devices that do not support carrier. +HUPCL may be locked off if you do not +want to hang up for some reason. +In general, very bad things happen +if something is locked to the wrong state, and things should not +be locked for devices that support more than one setting. +The CLOCAL flag on callin ports should be locked off for logins +to avoid certain security holes, but this needs to be done by +getty if the callin port is used for anything else. +.Sh Console Tuneable +The +.Nm +driver can be designated as a system console. +.Bl -tag -width indent +.It Va hw.uart.console +Contains a number of +.Pa /etc/remote +like tag:value pairs, separated by commas. +.Bl -tag -width indent +.It Cm \&bd +Busy Detect. +Enable the so-called +.Dq Busy Detect +quirk for the device. +For NS 16550-compatible devices, this will use heuristics to ensure that the +UART is no longer busy before manipulating line control. +DesignWare-based UARTs need this due to a design flaw in the UART. +.It Cm \&br +Baudrate. +The data rate (bits per second) used for communications on the serial port. +When the device clock rate (see below) is set to 0, then the baud rate will be +used with the divisor to compute the device clock rate the first time the device +is initialized. +Only the traditional baud rates are allowed. +Rates larger than 19200 must be a multiple of 19200. +Baud rates between 1200 and 19200 must be a multiple of 1200. +Otherwise the baud rate must be a multiple of 75. +A value of '0' instructs the +.Nm +driver to not program the baud rate divisor and use the hardware as-is. +.It Cm \&ch +Channel. +Defaults to 0. +Has no effect on UARTs with only one channel. +.It Cm \&db +Data bits. +Defaults to 8. +.It Cm \&dt +Device type. +Specify the uart class to use for this device. +.Bl -tag -width indent +.It ns8250 +Traditional PC UART National Semiconductor 16550 and compatible devices. +.It pl011 +Common ARM UART, based on ARM Limited designs. +.El +.It Cm \&io +I/O port address. +Specifies the address of a UART in an Intel processor's I/O space. +Mutually exclusive with +.Sq mm . +.It Cm \&mm +Memory mapped I/O address. +Specifies the physical address of a memory-mapped UART. +Mutually exclusive with +.Sq io . +.It Cm \&pa +Parity. +The type of parity to use when sending data +to the host. +This may be one of ``even'', +``odd'', ``none'', ``zero'' (always set bit 8 to zero), +``one'' (always set bit 8 to 1). +The default is even parity. +.It Cm \&rs +Register shift. +Number of bits to shift left the base register offset. +.It Cm \&rw +Register width. +Size of operations to read and write the registers of the device. +.It Cm \&sb +Stopbits. +Defaults to 1. +.It Cm \&xo +Device clock (xtal oscillator). +Base frequency of the oscillator to use for the device. +When set to 0, and the baud rate is also set, the UART's initialization +code will compute this the first time and use that after. +Automatically computed values can be as large as 5% when the base +frequency is a poor match to the traditional baud rates. +.El +.El +.Sh FILES +.Bl -tag -width "/dev/ttyu?.init" -compact +.It Pa /dev/ttyu? +for callin ports +.It Pa /dev/ttyu?.init +.It Pa /dev/ttyu?.lock +corresponding callin initial-state and lock-state devices +.Pp +.It Pa /dev/cuau? +for callout ports +.It Pa /dev/cuau?.init +.It Pa /dev/cuau?.lock +corresponding callout initial-state and lock-state devices +.El +.Sh EXAMPLES +.Dl hw.uart.console="io:0x2f8,br=115200" +.Pp +When the kernel is using a serial console port, it should use +COM2 instead of COM1 and set the baud rate to 115200. +.Sh SEE ALSO +.Xr cu 1 , +.Xr puc 4 , +.Xr scc 4 , +.Xr termios 4 , +.Xr tty 4 , +.Xr ttys 5 +.\" +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 5.2 . +.Sh AUTHORS +The +.Nm +device driver and this manual page were written by +.An Marcel Moolenaar Aq Mt marcel@xcllnt.net . +.Sh BUGS +Before the Internet, serial ports were primarily used for inbound +connections from terminals, either directly or through modems, these +days serial ports are primarily used for outbound connections to +devices, an evolution which unfortunately has spread the relevant +documentation over three different manual pages: +.Xr termios 4 , +.Xr uart 4 and +.Xr tty 4 . + diff --git a/static/freebsd/man4/uath.4 b/static/freebsd/man4/uath.4 new file mode 100644 index 00000000..865f04b8 --- /dev/null +++ b/static/freebsd/man4/uath.4 @@ -0,0 +1,184 @@ +.\" +.\" SPDX-License-Identifier: ISC +.\" +.\" Copyright (c) 2006 +.\" Damien Bergamini +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd April 7, 2009 +.Dt UATH 4 +.Os +.Sh NAME +.Nm uath +.Nd Atheros USB IEEE 802.11a/b/g wireless network driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ehci" +.Cd "device uhci" +.Cd "device ohci" +.Cd "device usb" +.Cd "device uath" +.Cd "device wlan" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_uath_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports USB 2.0 wireless network devices based on Atheros +Communications fifth generation AR5005UG and AR5005UX chipsets. +.Pp +The AR5005UG chipset is made of an AR5523 multiprotocol MAC/baseband processor +and an AR2112 Radio-on-a-Chip that can operate between 2300 and 2500 MHz +(802.11b/g). +.Pp +The AR5005UX chipset is made of an AR5523 multiprotocol MAC/baseband processor +and an AR5112 dual band Radio-on-a-Chip that can operate between 2300 and +2500 MHz (802.11b/g) or 4900 and 5850 MHz (802.11a). +.Pp +The AR5005UG and AR5005UX chipsets both have an integrated 32-bit MIPS +R4000-class processor that runs a firmware and manages, among other things, +the automatic control of the transmit rate and the calibration of the radio. +.Pp +.Nm +supports +.Cm station , +and +.Cm monitor +mode operation. +Only one virtual interface may be configured at any time. +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh FIRMWARE +.Nm +requires firmware that is downloaded to the device. +This is normally done by the +.Xr uathload 8 +utility that is launched by +.Xr devd 8 +when the device is inserted. +.Xr uathload 8 +includes the firmware in the binary program. +This firmware is licensed for general use and is included in the base system. +.Sh HARDWARE +The +.Nm +driver should work with the following adapters: +.Bl -column "TRENDware International TEW-444UB" "AR5005UX" +.It Em "Adapter" Ta Em "Chipset" +.\".It Belkin F6D3050 AR5005UX +.It Li "Compex WLU108AG" Ta AR5005UX +.It Li "Compex WLU108G" Ta AR5005UG +.\".It Li "D-Link DWL-AG132" Ta AR5005UX +.It Li "D-Link DWL-G132" Ta AR5005UG +.\".It Li "Edimax EW-7315Ug" Ta AR5005UG (AR2414???) +.\".It Li "Lancom USB-54ag" Ta AR5005UX +.\".It Li "NEC WL54TU" Ta AR5005UX +.It Li "IODATA WN-G54/US" Ta AR5005UG +.It Li "MELCO WLI-U2-KAMG54" Ta AR5005UX +.It Li "Netgear WG111T" Ta AR5005UG +.It Li "Netgear WG111U" Ta AR5005UX +.It Li "Netgear WPN111" Ta AR5005UG +.It Li "Olitec 000544" Ta AR5005UG +.It Li "PLANET WDL-U357" Ta AR5005UX +.\".It Li "Senao WUB-8004" Ta AR5005UX +.It Li "Siemens Gigaset 108" Ta AR5005UG +.It Li "SMC SMCWUSBT-G" Ta AR5005UG +.It Li "SMC SMCWUSBT-G2" Ta AR5005UG +.\".It Li "SparkLAN WL-685GS" Ta AR5005UG +.It Li "SparkLAN WL-785A" Ta AR5005UX +.It Li "TP-Link TL-WN620G" Ta AR5005UG +.It Li "TRENDware International TEW-444UB" Ta AR5005UG +.It Li "TRENDware International TEW-504UB" Ta AR5005UX +.It Li "Unex Technology UR054ag" Ta AR5005UX +.\".It Li "Wistron NeWeb DCUA-81" Ta AR5005UX +.\".It Li "Wistron NeWeb DRUA-81" Ta AR5005UG +.\".It Li "Wistron NeWeb DRUA-82" Ta AR5005UX +.\".It Li "ZyXEL G-200 v2" Ta AR5005UG +.It Li "ZyXEL XtremeMIMO M-202" Ta AR5005UX +.El +.Sh EXAMPLES +Join an existing BSS network (i.e., connect to an access point): +.Bd -literal -offset indent +ifconfig wlan create wlandev uath0 inet 192.168.0.20 \e + netmask 0xffffff00 +.Ed +.Pp +Join a specific BSS network with network name +.Dq Li my_net : +.Pp +.Dl "ifconfig wlan create wlandev uath0 ssid my_net up" +.Pp +Join a specific BSS network with 64-bit WEP encryption: +.Bd -literal -offset indent +ifconfig wlan create wlandev uath0 ssid my_net \e + wepmode on wepkey 0x1234567890 weptxkey 1 up +.Ed +.Pp +Join a specific BSS network with 128-bit WEP encryption: +.Bd -literal -offset indent +ifconfig wlan create wlandev uath0 wlanmode adhoc ssid my_net \e + wepmode on wepkey 0x01020304050607080910111213 weptxkey 1 +.Ed +.Sh DIAGNOSTICS +.Bl -diag +.It "uath%d: could not send command (error=%s)" +An attempt to send a command to the firmware failed. +.It "uath%d: timeout waiting for command reply" +A read command was sent to the firmware but the firmware failed to reply in +time. +.It "uath%d: device timeout" +A frame dispatched to the hardware for transmission did not complete in time. +The driver will reset the hardware. +This should not happen. +.El +.Sh SEE ALSO +.Xr netintro 4 , +.Xr usb 4 , +.Xr wlan 4 , +.Xr wlan_ccmp 4 , +.Xr wlan_tkip 4 , +.Xr wlan_wep 4 , +.Xr devd 8 , +.Xr ifconfig 8 , +.Xr uathload 8 , +.Xr wpa_supplicant 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Ox 4.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Weongyo Jeong Aq Mt weongyo@FreeBSD.org +and +.An Sam Leffler Aq Mt sam@FreeBSD.org . +It is distantly related to a driver written by +.An Damien Bergamini Aq Mt damien@openbsd.org . +.Sh CAVEATS +Atheros proprietary 108 Mbps mode (aka Super AG mode) is not supported. +.Pp +Dual-band adapters are presently not working; +to workaround, restriction operation to 2.4GHz channels. diff --git a/static/freebsd/man4/ubsa.4 b/static/freebsd/man4/ubsa.4 new file mode 100644 index 00000000..094f3ad1 --- /dev/null +++ b/static/freebsd/man4/ubsa.4 @@ -0,0 +1,121 @@ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Lennart Augustsson. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 26, 2017 +.Dt UBSA 4 +.Os +.Sh NAME +.Nm ubsa +.Nd USB support for Belkin serial adapters +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device usb" +.Cd "device ucom" +.Cd "device ubsa" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ubsa_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the USB-to-RS232 Bridge chip used by a variety of +serial adapters from Belkin and other vendors. +.Pp +The device is accessed through the +.Xr ucom 4 +driver which makes it behave like a +.Xr tty 4 . +.Sh HARDWARE +The +.Nm +driver supports the following adapters: +.Pp +.Bl -bullet -compact +.It +AnyData ADU-500A EV-DO modem +.It +AnyData ADU-E100A (no EV-DO mode support) +.It +Belkin F5U103 +.It +Belkin F5U120 +.It +e-Tek Labs Kwik232 +.It +GoHubs GoCOM232 +.It +Peracom single port serial adapter +.El +.Sh FILES +.Bl -tag -width "/dev/ttyU*.init" -compact +.It Pa /dev/ttyU* +for callin ports +.It Pa /dev/ttyU*.init +.It Pa /dev/ttyU*.lock +corresponding callin initial-state and lock-state devices +.Pp +.It Pa /dev/cuaU* +for callout ports +.It Pa /dev/cuaU*.init +.It Pa /dev/cuaU*.lock +corresponding callout initial-state and lock-state devices +.El +.Sh SEE ALSO +.Xr tty 4 , +.Xr ucom 4 , +.Xr usb 4 +.Sh HISTORY +The +.Nm +driver +appeared in +.Fx 5.0 . +The +.Xr uplcom 4 +manual page was adopted from +.Nx +by +.An Tom Rhodes Aq Mt trhodes@FreeBSD.org +in April 2002 and modified for the +.Nm +driver by +.An Alexander Kabaev Aq Mt kan@FreeBSD.org +in October 2002. +.Sh AUTHORS +The +.Nm +driver was written by +.An Alexander Kabaev Aq Mt kan@FreeBSD.org . diff --git a/static/freebsd/man4/ubser.4 b/static/freebsd/man4/ubser.4 new file mode 100644 index 00000000..58a24c3e --- /dev/null +++ b/static/freebsd/man4/ubser.4 @@ -0,0 +1,78 @@ +.\" Copyright (c) 2004 Bernd Walter +.\" +.\" $URL: https://devel.bwct.de/svn/projects/ubser/ubser.4 $ +.\" $Date: 2004-02-29 21:54:17 +0100 (Sun, 29 Feb 2004) $ +.\" $Author: ticso $ +.\" $Rev: 1130 $ +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 26, 2017 +.Dt UBSER 4 +.Os +.Sh NAME +.Nm ubser +.Nd USB support for BWCT console serial adapters +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device usb" +.Cd "device ucom" +.Cd "device ubser" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ubser_load="YES" +.Ed +.Sh HARDWARE +The +.Nm +driver provides support for the BWCT console management serial adapters. +.Sh FILES +.Bl -tag -width "/dev/ttyU*.*.init" -compact +.It Pa /dev/ttyU*.* +for callin ports +.It Pa /dev/ttyU*.*.init +.It Pa /dev/ttyU*.*.lock +corresponding callin initial-state and lock-state devices +.Pp +.It Pa /dev/cuaU*.* +for callout ports +.It Pa /dev/cuaU*.*.init +.It Pa /dev/cuaU*.*.lock +corresponding callout initial-state and lock-state devices +.El +.Sh SEE ALSO +.Xr tty 4 , +.Xr ucom 4 , +.Xr usb 4 +.Sh HISTORY +The +.Nm +driver +appeared in +.Fx 5.2 . diff --git a/static/freebsd/man4/ubtbcmfw.4 b/static/freebsd/man4/ubtbcmfw.4 new file mode 100644 index 00000000..ec1ee6cf --- /dev/null +++ b/static/freebsd/man4/ubtbcmfw.4 @@ -0,0 +1,107 @@ +.\" Copyright (c) 2003 Maksim Yevmenkin +.\" 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. +.\" +.\" $Id: ubtbcmfw.4,v 1.3 2003/05/21 19:37:35 max Exp $ +.\" +.Dd November 22, 2006 +.Dt UBTBCMFW 4 +.Os +.Sh NAME +.Nm ubtbcmfw +.Nd Firmware driver for Broadcom BCM2033 chip based Bluetooth USB devices +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ubtbcmfw" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ubtbcmfw_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +is a firmware driver for Broadcom BCM2033 chip based Bluetooth USB devices. +It provides minimal access to the parts of the device required to download +firmware. +.Pp +The +.Nm +driver creates three fixed endpoint device nodes. +.Pp +The control transfers can only happen on the control endpoint which +is always endpoint 0. +Control requests are issued by +.Xr ioctl 2 +calls. +.Pp +Only incoming transfers are supported on an interrupt endpoint. +To perform I/O on an interrupt endpoint, +.Xr read 2 +should be used. +All I/O operations on an interrupt endpoint are unbuffered. +Interrupt endpoint is always endpoint 1. +.Pp +Only outgoing bulk transfers are supported on a bulk endpoint. +To perform I/O on a bulk endpoint, +.Xr write 2 +should be used. +All I/O operations on a bulk endpoint are unbuffered. +Outgoing bulk endpoint is always endpoint 2. +.Pp +The control endpoint (endpoint 0) handles the following +.Xr ioctl 2 +calls: +.Bl -tag -width indent +.It Dv USB_GET_DEVICE_DESC Pq Vt usb_device_descriptor_t +Return the device descriptor. +.El +.Sh FILES +.Bl -tag -width ".Pa /dev/ubtbcmfw Ns Ar N Ns Pa \&. Ns Ar EE" -compact +.It Pa /dev/ubtbcmfw Ns Ar N Ns Pa \&. Ns Ar EE +Endpoint +.Ar EE +of device +.Ar N . +.El +.Sh SEE ALSO +.Xr ng_ubt 4 , +.Xr ugen 4 , +.Xr usb 4 , +.Xr bcmfw 8 +.Sh HISTORY +The +.Nm +driver was implemented in +.Fx 5.0 . +.Sh AUTHORS +.An Maksim Yevmenkin Aq Mt m_evmenkin@yahoo.com +.Sh BUGS +Most likely. +Please report if found. diff --git a/static/freebsd/man4/uchcom.4 b/static/freebsd/man4/uchcom.4 new file mode 100644 index 00000000..6cee3d82 --- /dev/null +++ b/static/freebsd/man4/uchcom.4 @@ -0,0 +1,127 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" $NetBSD: uchcom.4,v 1.2 2008/04/30 13:10:54 martin Exp $ +.\" +.\" Copyright (c) 2007 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Takuya SHIOZAKI (tshiozak@netbsd.org). +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 June 25, 2025 +.Dt UCHCOM 4 +.Os +.Sh NAME +.Nm uchcom +.Nd WinChipHead CH9102/CH343/CH341/CH340 USB to serial UART driver +.Sh SYNOPSIS +.Cd "device usb" +.Cd "device ucom" +.Cd "device uchcom" +.Pp +In +.Xr rc.conf 5 : +.Cd kld_list="uchcom" +.Pp +In +.Xr sysctl.conf 5 : +.Cd hw.usb.uchcom.debug=1 +.Sh DESCRIPTION +The +.Nm +driver provides support for the WinChipHead USB to serial UART adapters. +If the appropriate hardware is detected, +the driver will be loaded automatically by +.Xr devmatch 8 . +To load the driver manually, add it to the +.Ic kld_list +in +.Xr rc.conf 5 , +or use +.Xr kldload 8 +at runtime. +The device is accessed through the +.Xr ucom 4 +driver, which makes it behave like a +.Xr tty 4 . +.Pp +Call out through this interface with applications like +.Xr cu 1 +or +.Xr tip 1 . +.Sh HARDWARE +The +.Nm +driver supports the following USB to serial UART controllers: +.Pp +.Bl -bullet -compact +.It +WinChipHead CH9102 (max 6Mbps) +.It +WinChipHead CH343 (max 6Mbps) +.It +WinChipHead CH341 (max 2Mbps) +.It +WinChipHead CH340 (max 2Mbps) +.El +.Sh SYSCTL VARIABLES +These settings can be entered in the +.Xr loader 8 +prompt, set in +.Xr loader.conf 5 , +.Xr sysctl.conf 5 , +or changed at runtime with +.Xr sysctl 8 : +.Bl -tag -width "hw.usb.uchcom.debug" +.It Va hw.usb.uchcom.debug +Enable debugging messages, default +.Ql 0 +.El +.Sh FILES +.Bl -tag -width "/dev/ttyU*.init" -compact +.It Pa /dev/ttyU* +for callin ports +.It Pa /dev/ttyU*.init +.It Pa /dev/ttyU*.lock +corresponding callin initial-state and lock-state devices +.Pp +.It Pa /dev/cuaU* +for callout ports +.It Pa /dev/cuaU*.init +.It Pa /dev/cuaU*.lock +corresponding callout initial-state and lock-state devices +.El +.Sh SEE ALSO +.Xr cu 1 , +.Xr tty 4 , +.Xr ucom 4 , +.Xr usb 4 +.Sh HISTORY +The +.Nm +driver appeared in +.Fx 8.0 +from +.Nx 5.0 . diff --git a/static/freebsd/man4/ucom.4 b/static/freebsd/man4/ucom.4 new file mode 100644 index 00000000..b9f40777 --- /dev/null +++ b/static/freebsd/man4/ucom.4 @@ -0,0 +1,166 @@ +.\" $NetBSD: ucom.4,v 1.9 2002/03/22 00:39:40 augustss Exp $ +.\" +.\" Copyright (c) 1999 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Lennart Augustsson. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 11, 2020 +.Dt UCOM 4 +.Os +.Sh NAME +.Nm ucom +.Nd USB tty support +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ucom" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ucom_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver attaches to USB modems, serial ports, and other devices that need +to look like a tty. +The +.Nm +driver shows a behavior like a +.Xr tty 4 . +This means that normal programs such as +.Xr tip 1 +or +.Xr ppp 8 +can be used to access the device. +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va hw.usb.ucom.debug +Debug output level, where 0 is debugging disabled and larger values increase +debug message verbosity. +Default is 0. +.It Va hw.usb.ucom.device_mode_console +When set to 1, the +.Nm +driver will mark terminals as console devices when operating in device mode. +Default is 1. +.It Va hw.usb.ucom.pps_mode +Enables and configure PPS capture mode as described below. +.El +.Sh Pulse Per Second (PPS) Timing Interface +The +.Nm +driver can capture PPS timing information as defined in RFC 2783. +The API, accessed via +.Xr ioctl 2 , +is available on the tty device. +To use the PPS capture feature with +.Xr ntpd 8 , +symlink the tty device to +.Va /dev/pps0. +.Pp +The +.Va hw.usb.ucom.pps_mode +sysctl configures the PPS capture mode. +It can be set in +.Xr loader.conf 5 +or +.Xr sysctl.conf 5 . +The following capture modes are available: +.Bl -tag -compact -offset "mmmm" -width "mmmm" +.It 0 +Capture disabled (default). +.It 1 +Capture pulses on the CTS line. +.It 2 +Capture pulses on the DCD line. +.El +.Sh FILES +.Bl -tag -width "/dev/ttyU*.init" -compact +.It Pa /dev/ttyU* +for callin ports +.It Pa /dev/ttyU*.init +.It Pa /dev/ttyU*.lock +corresponding callin initial-state and lock-state devices +.Pp +.It Pa /dev/cuaU* +for callout ports +.It Pa /dev/cuaU*.init +.It Pa /dev/cuaU*.lock +corresponding callout initial-state and lock-state devices +.El +.Sh SEE ALSO +.Xr cu 1 , +.Xr tty 4 , +.Xr uark 4 , +.Xr ubsa 4 , +.Xr ubser 4 , +.Xr uchcom 4 , +.Xr ucycom 4 , +.Xr ufoma 4 , +.Xr uftdi 4 , +.Xr uhso 4 , +.\".Xr ugensa 4 , +.Xr uipaq 4 , +.Xr umcs 4 , +.Xr umct 4 , +.Xr umodem 4 , +.Xr umoscom 4 , +.Xr uplcom 4 , +.Xr usb 4 , +.Xr uslcom 4 , +.Xr uvisor 4 , +.Xr uvscom 4 , +.Xr ttys 5 +.Sh HISTORY +The +.Nm +driver was adopted from +.Nx +in March of 2002. +This manual page was adopted from +.Nx +by +.An Tom Rhodes Aq Mt trhodes@FreeBSD.org +in April 2002. +.Sh BUGS +Prior to +.Fx 6.0 +.Nm +created +.Pa /dev/ucom? +rather than the uniform device names created today. +Old scripts must be adjusted accordingly. diff --git a/static/freebsd/man4/ucycom.4 b/static/freebsd/man4/ucycom.4 new file mode 100644 index 00000000..4f4790f5 --- /dev/null +++ b/static/freebsd/man4/ucycom.4 @@ -0,0 +1,101 @@ +.\"- +.\" Copyright (c) 2004 Dag-Erling Smørgrav +.\" 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. 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 AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 26, 2017 +.Dt UCYCOM 4 +.Os +.Sh NAME +.Nm ucycom +.Nd device driver for Cypress CY7C63743 and CY7C64013 USB to RS232 bridges +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device usb" +.Cd "device hid" +.Cd "device ucom" +.Cd "device ucycom" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ucycom_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the Cypress CY7C63743 and CY7C64013 bridge +chips. +These chips were designed to provide a low-cost transition path to USB +for existing RS232 devices, and have fairly limited capabilities. +.Pp +The +.Nm +driver behaves like a +.Xr tty 4 . +.Sh HARDWARE +The +.Nm +driver currently supports the following devices which incorporate +Cypress USB to RS232 bridge chips: +.Pp +.Bl -bullet -compact +.It +DeLorme Earthmate USB GPS receiver +.El +.Sh FILES +.Bl -tag -width "/dev/ttyU*.init" -compact +.It Pa /dev/ttyU* +for callin ports +.It Pa /dev/ttyU*.init +.It Pa /dev/ttyU*.lock +corresponding callin initial-state and lock-state devices +.Pp +.It Pa /dev/cuaU* +for callout ports +.It Pa /dev/cuaU*.init +.It Pa /dev/cuaU*.lock +corresponding callout initial-state and lock-state devices +.El +.Sh SEE ALSO +.Xr tty 4 , +.Xr ucom 4 , +.Xr usb 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 5.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver and this manual page were written by +.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . diff --git a/static/freebsd/man4/udav.4 b/static/freebsd/man4/udav.4 new file mode 100644 index 00000000..f85c8849 --- /dev/null +++ b/static/freebsd/man4/udav.4 @@ -0,0 +1,100 @@ +.\" $NetBSD$ +.\" +.\" Copyright (c) 2003 +.\" Shingo WATANABE . 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 Shingo WATANABE. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" 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 Bill Paul OR THE VOICES IN HIS HEAD +.\" 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 November 24, 2015 +.Dt UDAV 4 +.Os +.Sh NAME +.Nm udav +.Nd "Davicom DM9601 USB Ethernet driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ehci" +.Cd "device uhci" +.Cd "device ohci" +.Cd "device usb" +.Cd "device miibus" +.Cd "device uether" +.Cd "device udav" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_udav_load="YES" +.Ed +.Sh HARDWARE +The +.Nm +driver supports the following adapters: +.Pp +.Bl -bullet -compact +.It +Corega FEther USB-TXC +.It +ShanTou ST268 USB NIC +.El +.Sh DESCRIPTION +The +.Nm +driver provides support for USB +.Tn Ethernet +adapters based on the Davicom DM9601 chipset. +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr usb 4 , +.Xr ifconfig 8 +.Rs +.%T "Davicom DM9601 data sheet" +.%U http://ptm2.cc.utu.fi/ftp/network/cards/DM9601/From_NET/DM9601-DS-P01-930914.pdf +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Nx 2.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Shingo WATANABE Aq Mt nabe@nabechan.org . diff --git a/static/freebsd/man4/udbc.4 b/static/freebsd/man4/udbc.4 new file mode 100644 index 00000000..c8fa02ec --- /dev/null +++ b/static/freebsd/man4/udbc.4 @@ -0,0 +1,132 @@ +.\" +.\" Copyright (c) 2025 The FreeBSD Foundation +.\" +.\" This documentation was written by Tom Jones under +.\" sponsorship from the FreeBSD Foundation. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" +.Dd September 3, 2025 +.Dt UDBC 4 +.Os +.Sh NAME +.Nm udbc +.Nd USB Debug Class device driver +.Sh SYNOPSIS +.Cd "device usb" +.Cd "device ucom" +.Cd "device udbc" +.Pp +In +.Xr rc.conf 5 : +.Cd kld_list="udbc" +.Sh DESCRIPTION +The +.Nm +driver provides support for USB Debug Class devices whose +interface class is Diagnostic Class and the subclass is DbC.GP. +.Pp +The USB Debug Class is defined in the USB 3.1 Device Class +Specification for Debug Devices. +This is designed to provide a general-purpose communication channel +for debugging. +It has also been widely implemented in USB xHCs +.Pq USB eXtensible Host Controllers , +which can be found on many commodity computers, +as an optional feature. +Once this feature is enabled on a USB xHC, one of the USB ports will +behave as a USB Debug Class device, +not a host port, +when a USB debug cable is connected. +The supported class in USB xHCs is typically DbC.GP, +while the specification defines several types of Debug Class devices. +The DbC.GP uses IN and OUT endpoint pairs and realizes a single +bidirectional serial communication channel. +On most systems, +including +.Fx , +the DbC.GP is seen as a simple serial device. +.Pp +Most systems with USB xHC can be configured to provide DbC.GP access. +The +.Nm +is a driver that connects to DbC.GP-supported devices, +offering +.Xr tty 4 +devices to connect to them via the +.Xr ucom 4 +device driver. +.Sh HARDWARE CONFIGURATION +A native DbC.GP device can be attached using the +.Nm +driver in a straightforward way. +.Pp +A USB xHC DbC.GP device on a target system needs a special hardware +configuration because all of the ports are supposed to be a USB Host. +There is one method to expose DbC.GP is to use a USB 3.1 A-to-A cable +.Pq section 5.5.2 in USB 3.1 Legacy Cable and Connector Specification . +When this cable is connected to a USB 3.1 port on the target system, +the DbC-enabled USB xHC automatically switches the port as a USB Device. +The +.Nm +driver can find a DbC.GP device on that port. +.Pp +Note that a USB xHC with USB 3.2 support +.Pq USB Type-C connectors +is not compatible with the USB 3.1 A-to-A cable. +Connecting a USB 3.2 C-to-C cable or A-to-C cable does not automatically work, +either, +because it needs role configuration of the port, which is not supported on +.Fx +yet. +.Sh FILES +.Bl -tag -width "/dev/ttyU*.*.init" -compact +.It Pa /dev/ttyU*.* +for callin ports +.It Pa /dev/ttyU*.*.init +.It Pa /dev/ttyU*.*.lock +corresponding callin initial-state and lock-state devices +.Pp +.It Pa /dev/cuaU*.* +for callout ports +.It Pa /dev/cuaU*.*.init +.It Pa /dev/cuaU*.*.lock +corresponding callout initial-state and lock-state devices +.El +.Sh SEE ALSO +.Xr tty 4 , +.Xr ucom 4 , +.Xr usb 4 , +.Xr xhci 4 +.Sh STANDARDS +.Rs +.%T eXtensible Host Controller Interface for Universal Serial Bus (XHCI) +.%U https://www.intel.com/content/dam/www/public/us/en/documents/technical-specifications/extensible-host-controler-interface-usb-xhci.pdf +.Re +.Rs +.%T USB 3.1 Device Class Specification for Debug Devices +.%U https://www.usb.org/sites/default/files/documents/usb_debug_class_rev_1_0_final_0.pdf +.Re +.Rs +.%T USB 3.1 Legacy Cable and Connector Specification +.%U https://www.usb.org/document-library/usb-31-legacy-cable-and-connector-revision-10 +.Re +.Sh HISTORY +The +.Nm +driver first appeared +.Fx +15.0. +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Hiroki Sato Aq Mt hrs@FreeBSD.org . +.Sh BUGS +According to the XHCI specification the host side of USB Debug should work with +any USB 3.0 port, +whether connected directly to a controller or with a hub in between. +Testing on some controllers has encountered issues when using a hub rather than +a directly connected port on the controller. diff --git a/static/freebsd/man4/udbp.4 b/static/freebsd/man4/udbp.4 new file mode 100644 index 00000000..f6ec43ae --- /dev/null +++ b/static/freebsd/man4/udbp.4 @@ -0,0 +1,163 @@ +.\" Copyright (c) 1999 +.\" Nick Hibma . 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 October 20, 2017 +.Dt UDBP 4 +.Os +.Sh NAME +.Nm udbp +.Nd USB Double Bulk Pipe driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device udbp" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +udbp_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for host-to-host cables +that contain at least two bulk pipes (one for each direction). +This typically includes cables branded for use with +.Sy Windows USB Easy Transfer , +and many cables based on the Prolific PL2xx1 series of USB bridge chips. +A useful (but non-comprehensive) list of compatible USB host cables +is listed in the +.Sx SEE ALSO +section below. +.Pp +.\" XXX The description of how to add netgraph to the kernel +.\" is out of place here. It should be limited to the +.\" netgraph(4) manpage only. However, that page does +.\" not yet give instructions for kldload(8) for the +.\" clueless. Working on it -- sheldonh +It requires +.Xr netgraph 4 +to be available. +This can be done either by adding +.Cd "options NETGRAPH" +to your kernel configuration file, or alternatively loading +.Xr netgraph 4 +as a module, either from +.Pa /boot/loader.conf +or from the command line, before the +.Nm +module. +.Sh EXAMPLES +.Dl options NETGRAPH +.Dl device udbp +.Pp +Add the +.Nm +driver to the kernel. +.Pp +.Dl kldload netgraph +.Dl kldload udbp +.Pp +Load the +.Xr netgraph 4 +module and then the +.Nm +driver. +.Pp +.Dl ngctl mkpeer udbp0: eiface data ether +.Dl ifconfig ngeth0 ether aa:dd:xx:xx:xx +.Dl ifconfig ngeth0 inet 169.254.x.x/16 +.Pp +Create a new Ethernet network interface node +and connect its ether hook to the data hook of the +.Nm +driver. +.Pp +This enables FreeBSD to communicate with a Linux peer (e.g. using the +.Sy plusb +driver). +The Linux node should be configured to prefer link-local IPv4 addresses +(e.g. using Network Manager in Debian and Red Hat derived distributions). +.Pp +Whilst both FreeBSD and Linux are able to interoperate by +loosely following CDC EEM 1.0 in their behaviour, neither implementation +has been expressly designed to follow its specification. +.Sh SEE ALSO +.Xr netgraph 4 , +.Xr ng_eiface 4 , +.Xr ohci 4 , +.Xr uhci 4 , +.Xr usb 4 , +.Xr ngctl 8 +.\" +.Rs +.%B Universal Serial Bus: Communications Class Subclass Specification for Ethernet Emulation Model Devices +.%N Revision 1.0 +.%D February 2, 2005 +.%I USB Implementers Forum, Inc. +.%U http://www.usb.org/developers/docs/devclass_docs/CDC_EEM10.pdf +.Re +.\" +.Rs +.%B Total Commander: Supported cables for USB cable connection +.%I Ghisler Software GmbH. +.%U https://www.ghisler.com/cables/index.htm +.Re +.Sh CAVEATS +The point-to-point nature and additional latency of USB host-host links +makes them unsuitable as a "drop-in" replacement for an Ethernet LAN; +for a USB 3.0 SuperSpeed cable, latency is comparable to 100BaseTX Ethernet +(but often worse), with throughput comparable to 2.5GBASE-T. +.Pp +However, their energy efficiency makes them attractive for embedded applications. +A Plugable PL27A1 cable claims 24mA of USB3 bus power, +as compared to 150mA for a typical USB 3.0 to Gigabit Ethernet interface. +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 5.0 . +.Sh BUGS +The +.Nm +driver does not support the special packets described in section 5.1 +of the CDC EEM specification. +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Doug Ambrisko Aq Mt ambrisko@whistle.com , +.An Julian Elischer Aq Mt julian@FreeBSD.org +and +.An Nick Hibma Aq Mt n_hibma@FreeBSD.org . +.Pp +This manual page was written by +.An Nick Hibma Aq Mt n_hibma@FreeBSD.org +and updated by +.An Bruce Simpson Aq Mt bms@FreeBSD.org . diff --git a/static/freebsd/man4/udl.4 b/static/freebsd/man4/udl.4 new file mode 100644 index 00000000..eab17302 --- /dev/null +++ b/static/freebsd/man4/udl.4 @@ -0,0 +1,95 @@ +.\" +.\" SPDX-License-Identifier: ISC +.\" +.\" $OpenBSD: udl.4,v 1.20 2012/09/18 17:11:41 jasper Exp $ +.\" +.\" Copyright (c) 2009 Marcus Glocker +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd December 23, 2025 +.Dt UDL 4 +.Os +.Sh NAME +.Nm udl +.Nd DisplayLink DL-120 / DL-160 USB display device driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device udl" +.Cd "device videomode" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +udl_load="YES" +.Ed +.Sh HARDWARE +The +.Nm +driver supports USB display devices +based on the DisplayLink DL-120 and DL-160 graphic chips, including: +.Pp +.Bl -bullet -compact +.It +Century Corp. Japan Plus One LCD-8000U +.It +Century Corp. Japan Plus One LCD-4300U +.It +DisplayLink USB to DVI +.It +ForwardVideo EasyCAP008 USB to DVI +.It +HP USB 2.0 Docking Station (FQ834) +.It +HP USB Graphics Adapter (NL571) +.It +IOGEAR USB 2.0 External DVI (GUC2020) +.It +Koenig CMP-USBVGA10 and CMP-USBVGA11 +.It +Lenovo 45K5296 USB to DVI +.It +Lenovo ThinkVision LT1421 +.It +Lilliput UM-70 +.It +Nanovision MiMo UM-710 and UM-740 +.It +Rextron VCUD60 USB to DVI +.It +Samsung LD220 +.It +StarTech CONV-USB2DVI +.It +Sunweit USB to DVI +.It +Unitek Y-2240 USB to DVI +.It +VideoHome NBdock1920 +.It +i-tec USB 2.0 Docking Station (USBDVIDOCK) +.El +.Sh SEE ALSO +.Xr usb 4 +.Sh HISTORY +The +.Nm +driver appeared in +.Ox 4.6 +and +.Fx 11.0 . diff --git a/static/freebsd/man4/udp.4 b/static/freebsd/man4/udp.4 new file mode 100644 index 00000000..b1dbff56 --- /dev/null +++ b/static/freebsd/man4/udp.4 @@ -0,0 +1,186 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 20, 2025 +.Dt UDP 4 +.Os +.Sh NAME +.Nm udp +.Nd Internet User Datagram Protocol +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netinet/in.h +.Ft int +.Fn socket AF_INET SOCK_DGRAM 0 +.Sh DESCRIPTION +.Tn UDP +is a simple, unreliable datagram protocol which is used +to support the +.Dv SOCK_DGRAM +abstraction for the Internet +protocol family. +.Tn UDP +sockets are connectionless, and are +normally used with the +.Xr sendto 2 +and +.Xr recvfrom 2 +calls, though the +.Xr connect 2 +call may also be used to fix the destination for future +packets (in which case the +.Xr recv 2 +or +.Xr read 2 +and +.Xr send 2 +or +.Xr write 2 +system calls may be used). +.Pp +.Tn UDP +address formats are identical to those used by +.Tn TCP . +In particular +.Tn UDP +provides a port identifier in addition +to the normal Internet address format. +Note that the +.Tn UDP +port +space is separate from the +.Tn TCP +port space (i.e., a +.Tn UDP +port +may not be +.Dq connected +to a +.Tn TCP +port). +In addition broadcast +packets may be sent (assuming the underlying network supports +this) by using a reserved +.Dq broadcast address ; +this address +is network interface dependent. +.Pp +Options at the +.Tn IP +transport level may be used with +.Tn UDP ; +see +.Xr ip 4 . +.Tn UDP_ENCAP +socket option may be used at the +.Tn IPPROTO_UDP +level to encapsulate +.Tn ESP +packets in +.Tn UDP . +Only one value is supported for this option: +.Tn UDP_ENCAP_ESPINUDP +from RFC 3948, defined in +.In netinet/udp.h . +.Sh FIB support +UDP sockets are FIB-aware. +They inherit the FIB of the process which created the socket. +By default, a UDP socket bound to an address can receive datagrams originating +from any FIB. +If the +.Va net.inet.udp.bind_all_fibs +tunable is set to 0, all UDP sockets will receive only datagrams originating +from the same FIB as the socket. +In this mode, multiple sockets can be bound to the same address, so long as +each socket belongs to a different FIB, similar to the behavior of the +.Dv SO_REUSEPORT +option. +.Sh MIB (sysctl) Variables +The +.Nm +protocol implements a number of variables in the +.Va net.inet.udp +branch of the +.Xr sysctl 3 +MIB, which can be also read or modified with +.Xr sysctl 8 : +.Bl -tag -width ".Va log_in_vain" +.It Va blackhole +When a datagram is received on a port where there is no socket +listening, do not return an ICMP port unreachable message. +(Disabled by default. +See +.Xr blackhole 4 . ) +.It Va checksum +Enable UDP checksums (enabled by default). +.It Va log_in_vain +For all UDP datagrams, to ports on which there is no socket +listening, log the connection attempt (disabled by default). +.It Va maxdgram +Maximum outgoing UDP datagram size +.It Va recvspace +Maximum space for incoming UDP datagrams +.El +.Sh ERRORS +A socket operation may fail with one of the following errors returned: +.Bl -tag -width Er +.It Bq Er EISCONN +when trying to establish a connection on a socket which +already has one, or when trying to send a datagram with the destination +address specified and the socket is already connected; +.It Bq Er ENOTCONN +when trying to send a datagram, but +no destination address is specified, and the socket has not been +connected; +.It Bq Er ENOBUFS +when the system runs out of memory for +an internal data structure; +.It Bq Er EADDRINUSE +when an attempt +is made to create a socket with a port which has already been +allocated; +.It Bq Er EADDRNOTAVAIL +when an attempt is made to create a +socket with a network address for which no network interface +exists. +.El +.Sh SEE ALSO +.Xr getsockopt 2 , +.Xr recv 2 , +.Xr send 2 , +.Xr socket 2 , +.Xr blackhole 4 , +.Xr inet 4 , +.Xr intro 4 , +.Xr ip 4 , +.Xr udplite 4 +.Sh HISTORY +The +.Nm +protocol appeared in +.Bx 4.2 . diff --git a/static/freebsd/man4/udplite.4 b/static/freebsd/man4/udplite.4 new file mode 100644 index 00000000..38c0691a --- /dev/null +++ b/static/freebsd/man4/udplite.4 @@ -0,0 +1,94 @@ +.\" Copyright (c) 2014, Kevin Lo. +.\" 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 REGENTS 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 REGENTS 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 October 1, 2014 +.Dt UDPLITE 4 +.Os +.Sh NAME +.Nm udplite +.Nd Lightweight User Datagram Protocol +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netinet/udplite.h +.Ft int +.Fn socket AF_INET SOCK_DGRAM IPPROTO_UDPLITE +.Sh DESCRIPTION +The +.Tn UDP-Lite +protocol provides a partial checksum which allows +corrupted packets to be transmitted to the receiving +application. +This has advantages for some types of multimedia +transport that may be able to make use of slightly +damaged datagrams, rather than having them discarded +by lower-layer protocols. +.Pp +.Tn UDP-Lite +supports a number of socket options which can be set with +.Xr setsockopt 2 +and tested with +.Xr getsockopt 2 : +.Bl -tag -width ".Dv UDPLITE_SEND_CSCOV" +.It Dv UDPLITE_SEND_CSCOV +This option sets the sender checksum coverage. +A value of zero indicates that all sent packets will have +full checksum coverage. +A value of 8 to 65535 limits the checksum coverage of all sent packets +to the value given. +.It Dv UDPLITE_RECV_CSCOV +This option is the receiver-side analogue. +A value of zero instructs the kernel to drop all received packets +not having full checksum coverage. +A value of 8 to 65535 instructs the kernel to drop all received +packets with a partial checksum coverage smaller than the value specified. +.El +.Sh ERRORS +A socket operation may fail with one of the following errors returned: +.Bl -tag -width Er +.It Bq Er EISCONN +when trying to establish a connection on a socket which +already has one, or when trying to send a datagram with the destination +address specified and the socket is already connected; +.It Bq Er ENOTCONN +when trying to send a datagram, but +no destination address is specified, and the socket has not been +connected; +.It Bq Er ENOBUFS +when the system runs out of memory for +an internal data structure; +.It Bq Er EADDRINUSE +when an attempt +is made to create a socket with a port which has already been +allocated; +.It Bq Er EADDRNOTAVAIL +when an attempt is made to create a +socket with a network address for which no network interface +exists. +.El +.Sh SEE ALSO +.Xr getsockopt 2 , +.Xr recv 2 , +.Xr send 2 , +.Xr socket 2 diff --git a/static/freebsd/man4/uep.4 b/static/freebsd/man4/uep.4 new file mode 100644 index 00000000..321d2f1e --- /dev/null +++ b/static/freebsd/man4/uep.4 @@ -0,0 +1,97 @@ +.\" Copyright (c) 2010 Gleb Smirnoff +.\" 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 August 5, 2018 +.Dt UEP 4 +.Os +.Sh NAME +.Nm uep +.Nd eGalax touchscreen driver +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines into +your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device uep" +.Cd "device usb" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +uep_load="YES" +.Ed +.Pp +To compile this driver with evdev support enabled, place the +following lines into the kernel configuration file: +.Bd -ragged -offset indent +.Cd "options EVDEV_SUPPORT" +.Cd "device evdev" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the eGalax onscreen touch panels. +.Pp +The driver is a stub. +It just probes and attaches to USB device, creates a device entry +and feeds reassembled packets from the hardware to it. +Depending on compile-time kernel options it supports either native +or evdev operation modes. +.Pp +To get the mouse working in +.Xr X 7 Pq Pa ports/x11/xorg-docs +in native mode, install +.Pa ports/x11-drivers/xf86-input-egalax . +.Pp +To get the mouse working in +.Xr X 7 Pq Pa ports/x11/xorg-docs +in evdev mode, install +.Pa ports/x11-drivers/xf86-input-evdev . +.Sh FILES +.Nm +creates a blocking pseudo-device file, +.Pa /dev/uep0 +in native mode or +.Pa /dev/input/eventN +in evdev mode. +.Sh SEE ALSO +.Xr usb 4 , +.Xr loader.conf 5 , +.Xr xorg.conf 5 Pq Pa ports/x11/xorg , +.Xr egalax 4 Pq Pa ports/x11-drivers/xf86-input-egalax , +.Xr evdev 4 Pq Pa ports/x11-drivers/xf86-input-evdev . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Gleb Smirnoff Aq Mt glebius@FreeBSD.org . +.Sh BUGS +.Nm +cannot act like +.Xr sysmouse 4 , +as +.Xr sysmouse 4 +does not support absolute motion events. diff --git a/static/freebsd/man4/ufintek.4 b/static/freebsd/man4/ufintek.4 new file mode 100644 index 00000000..89e3d7b6 --- /dev/null +++ b/static/freebsd/man4/ufintek.4 @@ -0,0 +1,118 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 Diane Bruce +.\" 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 November, 2025 +.Dt UFINTEK 4 +.Os +.Sh NAME +.Nm ufintek +.Nd Fintek F81232 USB to serial UART driver +.Sh SYNOPSIS +.Cd "device usb" +.Cd "device ucom" +.Cd "device ufintek" +.Pp +In +.Xr rc.conf 5 : +.Cd kld_list="ufintek" +.Pp +In +.Xr sysctl.conf 5 : +.Cd hw.usb.ufintek.debug=1 +.Sh DESCRIPTION +The +.Nm +driver provides support for the F81232 serial adapter from FINTEK. +If the appropriate hardware is detected, +the driver will be loaded automatically by +.Xr devmatch 8 . +To load the driver manually, add it to the +.Ic kld_list +in +.Xr rc.conf 5 , +or use +.Xr kldload 8 +at runtime. +The device is accessed through the +.Xr ucom 4 +driver which makes it behave like a +.Xr tty 4 . +.Pp +Call out through this interface with applications like +.Xr cu 1 +or +.Xr tip 1 . +.Sh HARDWARE +The +.Nm +driver supports the following USB to serial UART controllers: +.Pp +.Bl -bullet -compact +.It +FT82332 +.El +.Sh SYSCTL VARIABLES +These settings can be entered in the +.Xr loader 8 +prompt, set in +.Xr loader.conf 5 , +.Xr sysctl.conf 5 , +or changed at runtime with +.Xr sysctl 8 : +.Bl -tag -width "hw.usb.uftdi.debug" +.It Va hw.usb.uftdi.debug +Enable debugging messages, default +.Ql 0 +.Ql 1 +.El +.Sh FILES +.Bl -tag -width "/dev/ttyU*.init" -compact +.It Pa /dev/ttyU* +for callin ports +.It Pa /dev/ttyU*.init +.It Pa /dev/ttyU*.lock +corresponding callin initial-state and lock-state devices +.Pp +.It Pa /dev/cuaU* +for callout ports +.It Pa /dev/cuaU*.init +.It Pa /dev/cuaU*.lock +corresponding callout initial-state and lock-state devices +.El +.Sh SEE ALSO +.Xr cu 1 , +.Xr tty 4 , +.Xr ucom 4 , +.Xr usb 4 +.Sh HISTORY +The +.Nm +driver appeared in +.Fx 16.0 +.Sh BUGS +This driver is limited to 9600 baud. + diff --git a/static/freebsd/man4/ufoma.4 b/static/freebsd/man4/ufoma.4 new file mode 100644 index 00000000..609a9b1f --- /dev/null +++ b/static/freebsd/man4/ufoma.4 @@ -0,0 +1,139 @@ +.\" Copyright (c) 2006 Takanori Watanabe. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Lennart Augustsson. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 November 20, 2011 +.Dt UFOMA 4 +.Os +.Sh NAME +.Nm ufoma +.Nd USB mobile phone support +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device usb" +.Cd "device ucom" +.Cd "device ufoma" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ufoma_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for USB mobile phone terminals in the subset of +the Mobile Computing Promotion Consortium USB Implementation Guideline, +which is adopted by FOMA, the NTT DoCoMo 3G system, terminal. +These are partly like CDC ACM model based modems, which are supported +by +.Xr umodem 4 , +but the +.Nm +driver recognizes a specific USB descriptor that describes its role and +interface structure, and it will negotiate its role when the device is open. +They support a regular AT command set and +the commands can either be multiplexed with the data stream +or handled through separate pipes. +In the latter case the AT +commands have to be given on a device separate from the data device. +.Pp +The device is accessed through the +.Xr ucom 4 +driver which makes it behave like a +.Xr tty 4 . +.Sh SYSCTLS +These devices often have a few interface sets and these interfaces +have their role, sometimes multiplexed. +These roles are identified with the following sysctl MIBs: +.Bl -tag -width indent +.It Va dev.ucom.%d.supportmode +The modes which are supported by the interface. +.It Va dev.ucom.%d.currentmode +Current mode of the interface. +.It Va dev.ucom.%d.openmode +Mode to transit when the device is open next. +.El +The modes are as follows: +.Bl -tag -width indent +.It Li modem +Accepts AT commands and go and pass packet communication data. +.It Li handsfree +Accepts AT commands but it does not pass data. +.It Li obex +Accepts OBEX frame which is used to exchange telephone book, etc. +.It Li vendor1 , vendor2 +Vendor specific data may be passed. +.It Li deactivated +When an interface is recognized by the system but not used, the interface +will be set to this mode. +.It Li unlinked +When an interface is not yet negotiated, the interface is in this mode. +.El +.Sh HARDWARE +Devices supported by the +.Nm +driver include: +.Pp +.Bl -bullet -compact +.It +SHARP FOMA SH902i +.It +KYOCERA PHS AH-K3001V (a.k.a Kyopon) +.It +SANYO Vodafone3G V801SA +.El +.Sh SEE ALSO +Specification can be found at: +.Pp +.Bl -item -compact +.It +.Pa http://www.nttdocomo.co.jp/corporate/technology/document/foma/index.html +.It +.Pa http://www.mcpc-jp.org/doclist.htm +.El +.Pp +.Xr tty 4 , +.Xr ucom 4 , +.Xr umodem 4 , +.Xr usb 4 +.Sh HISTORY +The +.Nm +driver +appeared in +.Fx 7.0 , +partly derived from the +.Xr umodem 4 +code. +.Sh BUGS +Interfaces with multiplexed commands and data and interfaces with +commands only are supported. diff --git a/static/freebsd/man4/ufshci.4 b/static/freebsd/man4/ufshci.4 new file mode 100644 index 00000000..f9de9b39 --- /dev/null +++ b/static/freebsd/man4/ufshci.4 @@ -0,0 +1,213 @@ +.\" +.\" Copyright (c) 2025, Samsung Electronics Co., Ltd. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" ufshci driver man page. +.\" +.\" Author: Jaeyoon Choi +.\" +.Dd July 17, 2025 +.Dt UFSHCI 4 +.Os +.Sh NAME +.Nm ufshci +.Nd Universal Flash Storage Host Controller Interface driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in the kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ufshci" +.Ed +.Pp +Or, to load the driver as a module at boot, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ufshci_load="YES" +.Ed +.Sh DESCRIPTION +Universal Flash Storage (UFS) is a low-power, high-performance storage +standard composed of a host controller and a single target device. +.Pp +The driver currently provides: +.Bl -bullet +.It +Initialization of the host controller and the target device +.It +Handling of UFS Interconnect (UIC) commands +.It +Support for UTP Transfer Requests (UTR) and UTP Task Management Requests (UTMR) +.It +Support for the SCSI command set +.It +Operation in the legacy single-doorbell queue mode +.It +Support for the PCI Express bus +.El +.Pp +After initialization, the controller is registered with the +.Xr cam 4 +subsystem and its logical unit appears as the device node +.Pa /dev/daX . +.Pp +The driver is under active development; upcoming work includes full +UFS 4.1 feature coverage, additional power-management modes, and +ACPI/FDT-based attach support. +.Sh HARDWARE +The +.Nm +driver supports both host controllers and devices implementing the +Universal Flash Storage Host Controller Interface 4.1 and earlier. +.Sh CONFIGURATION +The +.Nm +driver currently operates with a single doorbell (one I/O-queue), so any +tunables that change the queue count are ignored. +When Multi-Circular Queue (MCQ) support is added and multiple queues +become available, the following queue count tunable values will take effect: +.Pp +To force a single I/O queue pair shared by all CPUs, set the following +tunable value in loader.conf(5): +.Bd -literal -offset indent +hw.ufshci.per_cpu_io_queues=0 +.Ed +.Pp +To assign more than one CPU per I/O queue pair, thereby reducing the +number of MSI-X vectors consumed by the device, set the following tunable +value in loader.conf(5): +.Bd -literal -offset indent +hw.ufshci.min_cpus_per_ioq=X +.Ed +.Pp +To change the I/O command timeout value (in seconds), set the following tunable +value in loader.conf(5): +.Bd -literal -offset indent +hw.ufshci.timeout_period=X +.Ed +.Pp +To change the I/O command retry count, set the following tunable value in +loader.conf(5): +.Bd -literal -offset indent +hw.ufshci.retry_count=X +.Ed +.Pp +To force the driver to use legacy INTx interrupts, set the following tunable +value in loader.conf(5): +.br +(Note: until MCQ support is available the driver always uses legacy INTx, so +this value effectively remains 1) +.Bd -literal -offset indent +hw.ufshci.force_intx=1 +.Ed +.Sh SYSCTL VARIABLES +The following controller-level +.Xr sysctl 8 +nodes are currently implemented: +.Bl -tag -width indent +.It Va dev.ufshci.0.num_failures +(R) Number of command failures for the entire controller. +.It Va dev.ufshci.0.num_retries +(R) Number of command retries for the entire controller. +.It Va dev.ufshci.0.num_intr_handler_calls +(R) Number of times the interrupt handler has been called. +.It Va dev.ufshci.0.num_cmds +(R) Total number of commands issued by the controller. +.It Va dev.ufshci.0.timeout_period +(RW) Configured timeout period (in seconds). +.It Va dev.ufshci.0.cap +(R) Host controller capabilities register value. +.It Va dev.ufshci.0.num_io_queues +(R) Number of I/O-queue pairs. +.It Va dev.ufshci.0.io_queue_mode +(R) Indicates single doorbell mode or multi circular queue mode. +.It Va dev.ufshci.0.minor_version +(R) Host controller minor version. +.It Va dev.ufshci.0.major_version +(R) Host controller major version. +.It Va dev.ufshci.0.wb_enabled +(R) WriteBooster enable/disable. +.It Va dev.ufshci.0.wb_flush_enabled +(R) WriteBooster flush enable/disable. +.It Va dev.ufshci.0.wb_buffer_type +(R) WriteBooster type. +.It Va dev.ufshci.0.wb_buffer_size_mb +(R) WriteBooster buffer size in MB. +.It Va dev.ufshci.0.wb_user_space_config_option +(R) WriteBooster preserve user space mode. +.It Va dev.ufshci.0.auto_hibernation_supported +(R) Device auto hibernation support. +.It Va dev.ufshci.0.auto_hibernate_idle_timer_value +(R) Auto-Hibernate Idle Timer Value (in microseconds). +.It Va dev.ufshci.0.power_mode_supported +(R) Device power mode support. +.It Va dev.ufshci.0.power_mode +(R) Current device power mode. +.It Va dev.ufshci.0.tx_rx_power_mode +(R) Current TX/RX PA_PWRMode value. +.It Va dev.ufshci.0.max_tx_lanes +(R) Maximum available TX data lanes. +.It Va dev.ufshci.0.max_rx_lanes +(R) Maximum available RX data lanes. +.It Va dev.ufshci.0.tx_lanes +(R) Active TX data lanes. +.It Va dev.ufshci.0.rx_lanes +(R) Active RX data lanes. +.It Va dev.ufshci.0.max_rx_hs_gear +(R) Maximum available RX HS gear. +.It Va dev.ufshci.0.hs_gear +(R) Active HS gear. +.It Va dev.ufshci.0.utmrq.num_failures +(R) Number of failed UTP task-management requests. +.It Va dev.ufshci.0.utmrq.num_retries +(R) Number of retried UTP task-management requests. +.It Va dev.ufshci.0.utmrq.num_intr_handler_calls +(R) Number of interrupt handler calls caused by UTP task-management requests. +.It Va dev.ufshci.0.utmrq.num_cmds +(R) Number of UTP task-management requests issued. +.It Va dev.ufshci.0.utmrq.cq_head +(R) Current location of the UTP task-management completion queue head. +.It Va dev.ufshci.0.utmrq.sq_tail +(R) Current location of the UTP task-management submission queue tail. +.It Va dev.ufshci.0.utmrq.sq_head +(R) Current location of the UTP task-management submission queue head. +.It Va dev.ufshci.0.utmrq.num_trackers +(R) Number of trackers in the UTP task-management queue. +.It Va dev.ufshci.0.utmrq.num_entries +(R) Number of entries in the UTP task-management queue. +.It Va dev.ufshci.0.ioq.0.num_failures +(R) Number of failed UTP transfer requests. +.It Va dev.ufshci.0.ioq.0.num_retries +(R) Number of retried UTP transfer requests. +.It Va dev.ufshci.0.ioq.0.num_intr_handler_calls +(R) Number of interrupt-handler calls caused by UTP transfer requests. +.It Va dev.ufshci.0.ioq.0.num_cmds +(R) Number of UTP transfer requests issued. +.It Va dev.ufshci.0.ioq.0.cq_head +(R) Current location of the UTP transfer completion queue head. +.It Va dev.ufshci.0.ioq.0.sq_tail +(R) Current location of the UTP transfer submission queue tail. +.It Va dev.ufshci.0.ioq.0.sq_head +(R) Current location of the UTP transfer submission queue head. +.It Va dev.ufshci.0.ioq.0.num_trackers +(R) Number of trackers in the UTP transfer queue. +.It Va dev.ufshci.0.ioq.0.num_entries +(R) Number of entries in the UTP transfer queue. +.El +.Sh SEE ALSO +.Xr cam 4 , +.Xr pci 4 , +.Xr disk 9 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 15.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was developed by Samsung Electronics and originally written by +.An Jaeyoon Choi Aq Mt j_yoon.choi@samsung.com . +.Pp +This manual page was written by +.An Jaeyoon Choi Aq Mt j_yoon.choi@samsung.com . diff --git a/static/freebsd/man4/uftdi.4 b/static/freebsd/man4/uftdi.4 new file mode 100644 index 00000000..b526143e --- /dev/null +++ b/static/freebsd/man4/uftdi.4 @@ -0,0 +1,279 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" $NetBSD: uftdi.4,v 1.5 2002/02/07 03:15:08 ross Exp $ +.\" +.\" Copyright (c) 2000 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Lennart Augustsson. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 June 25, 2025 +.Dt UFTDI 4 +.Os +.Sh NAME +.Nm uftdi +.Nd Future Technology Devices International USB to serial UART driver +.Sh SYNOPSIS +.Cd "device usb" +.Cd "device ucom" +.Cd "device uftdi" +.Pp +In +.Xr rc.conf 5 : +.Cd kld_list="uftdi" +.Pp +In +.Xr sysctl.conf 5 : +.Cd hw.usb.uftdi.debug=1 +.Cd hw.usb.uftdi.skip_jtag_interfaces=0 +.Sh DESCRIPTION +The +.Nm +driver supports FTDI USB to serial UART devices. +If the appropriate hardware is detected, +the driver will be loaded automatically by +.Xr devmatch 8 . +To load the driver manually, add it to the +.Ic kld_list +in +.Xr rc.conf 5 , +or use +.Xr kldload 8 +at runtime. +The device is accessed through the +.Xr ucom 4 +driver which makes it behave like a +.Xr tty 4 . +.Pp +Call out through this interface with applications like +.Xr cu 1 +or +.Xr tip 1 . +.Sh HARDWARE +The +.Nm +driver supports the following USB to serial UART controllers: +.Pp +.Bl -bullet -compact +.It +FTDI FT4232H +.It +FTDI FT232R +.It +FTDI FT230X +.It +FTDI FT2232H +.It +FTDI FT2232D +.It +FTDI FT2232C +.It +FTDI FT8U232BM +.It +FTDI FT8U232AM +.It +FTDI FT8U100AX +.El +.Sh SYSCTL VARIABLES +These settings can be entered in the +.Xr loader 8 +prompt, set in +.Xr loader.conf 5 , +.Xr sysctl.conf 5 , +or changed at runtime with +.Xr sysctl 8 : +.Bl -tag -width "hw.usb.uftdi.skip_jtag_interfaces" +.It Va hw.usb.uftdi.debug +Enable debugging messages, default +.Ql 0 +.It Va hw.usb.uftdi.skip_jtag_interfaces +Ignore JTAG interfaces, default +.Ql 1 +.El +.Sh IOCTLS +Many of the supported chips provide additional functionality +such as bitbang mode and the MPSSE engine for serial bus emulation. +The +.Nm +driver provides access to that functionality with the following +.Xr ioctl 2 +calls, defined in +.In dev/usb/uftdiio.h : +.Bl -tag -width indent +.It Dv UFTDIIOC_RESET_IO Pq Vt int +Reset the channel to its default configuration, flush RX and TX FIFOs. +.It Dv UFTDIIOC_RESET_RX Pq Vt int +Flush the RX FIFO. +.It Dv UFTDIIOC_RESET_TX Pq Vt int +Flush the TX FIFO. +.It Dv UFTDIIOC_SET_BITMODE Pq Vt "struct uftdi_bitmode" +Put the channel into the operating mode specified in +.Va mode , +and set the pins indicated by ones in +.Va iomask +to output mode. +The +.Va mode +must be one of the +.Va uftdi_bitmodes +values. +Setting +.Va mode +to +.Dv UFTDI_BITMODE_NONE +returns the channel to standard UART mode. +.Bd -literal +enum uftdi_bitmodes +{ + UFTDI_BITMODE_ASYNC = 0, + UFTDI_BITMODE_MPSSE = 1, + UFTDI_BITMODE_SYNC = 2, + UFTDI_BITMODE_CPU_EMUL = 3, + UFTDI_BITMODE_FAST_SERIAL = 4, + UFTDI_BITMODE_CBUS = 5, + UFTDI_BITMODE_NONE = 0xff, +}; + +struct uftdi_bitmode +{ + uint8_t mode; + uint8_t iomask; +}; +.Ed +.Pp +Manuals and application notes published by FTDI describe these +modes in detail. +To use most of these modes, you first put the channel into +the desired mode, then you +.Xr read 2 +and +.Xr write 2 +data which either reflects pin state or is interpreted +as MPSSE commands and parameters, depending on the mode. +.It Dv UFTDIIOC_GET_BITMODE Pq Vt "struct uftdi_bitmode" +Return the current bitbang mode in the +.Va mode +member, and the state of the DBUS0..DBUS7 pins at the time +of the call in the +.Va iomask +member. +The pin state can be read while the chip is in any mode, including +.Dv UFTDI_BITMODE_NONE +(UART) mode. +.It Dv UFTDIIOC_SET_ERROR_CHAR Pq Vt int +Set the character which is inserted into the buffer to mark +the point of an error such as FIFO overflow. +.It Dv UFTDIIOC_SET_EVENT_CHAR Pq Vt int +Set the character which causes a partial FIFO full of data +to be returned immediately even if the FIFO is not full. +.It Dv UFTDIIOC_SET_LATENCY Pq Vt int +Set the amount of time to wait for a full FIFO, +in milliseconds. +If more than this much time elapses without receiving a new +character, any characters in the FIFO are returned. +.It Dv UFTDIIOC_GET_LATENCY Pq Vt int +Get the current value of the latency timer. +.It Dv UFTDIIOC_GET_HWREV Pq Vt int +Get the hardware revision number. +This is the +.Va bcdDevice +value from the +.Va usb_device_descriptor . +.It Dv UFTDIIOC_READ_EEPROM Pq Vt "struct uftdi_eeio" +Read one or more words from the configuration eeprom. +The FTDI chip performs eeprom I/O in 16-bit words. +Set +.Va offset +and +.Va length +to values evenly divisible by two before the call, and the +.Va data +array will contain the requested values from eeprom after the call. +.Bd -literal +struct uftdi_eeio +{ + uint16_t offset; + uint16_t length; + uint16_t data[64]; +}; +.Ed +.Pp +The FT232R chip has an internal eeprom. +An external serial eeprom is optional on other FTDI chips. +The eeprom may contain 64, 128, or 256 words, +depending on the part used. +Multiple calls may be needed to read or write the larger parts. +When no eeprom is present, all words in the returned data are 0xffff. +An erased eeprom also reads as all 0xffff. +.It Dv UFTDIIOC_WRITE_EEPROM Pq Vt "struct uftdi_eeio" +Write one or more words to the configuration eeprom. +The +.Va uftdi_eeio +values are as described for +.Dv UFTDIIOC_READ_EEPROM . +.Pp +The FTDI chip does a blind write to the eeprom, and it will appear +to succeed even when no eeprom is present. +To ensure a good write you must read back and verify the data. +It is +.Em not +necessary to erase before writing. +Any position within the eeprom can be overwritten at any time. +.It Dv UFTDIIOC_ERASE_EEPROM Pq Vt int +Erase the entire eeprom. +This is useful primarily for test and debugging, as there is no +need to erase before writing. +To help prevent accidental erasure caused by calling the wrong +ioctl, you must pass the special value +.Dv UFTDI_CONFIRM_ERASE +as the argument to this ioctl. +.El +.Sh FILES +.Bl -tag -width "/dev/ttyU*.init" -compact +.It Pa /dev/ttyU* +for callin ports +.It Pa /dev/ttyU*.init +.It Pa /dev/ttyU*.lock +corresponding callin initial-state and lock-state devices +.Pp +.It Pa /dev/cuaU* +for callout ports +.It Pa /dev/cuaU*.init +.It Pa /dev/cuaU*.lock +corresponding callout initial-state and lock-state devices +.El +.Sh SEE ALSO +.Xr cu 1 , +.Xr tty 4 , +.Xr ucom 4 , +.Xr usb 4 +.Sh HISTORY +The +.Nm +driver appeared in +.Fx 4.8 +from +.Nx 1.5 . diff --git a/static/freebsd/man4/ugen.4 b/static/freebsd/man4/ugen.4 new file mode 100644 index 00000000..bd387b0e --- /dev/null +++ b/static/freebsd/man4/ugen.4 @@ -0,0 +1,326 @@ +.\" $NetBSD: ugen.4,v 1.13 2001/09/11 22:52:54 wiz Exp $ +.\" +.\" Copyright (c) 1999 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Lennart Augustsson. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 May 14, 2021 +.Dt UGEN 4 +.Os +.Sh NAME +.Nm ugen +.Nd USB generic device support +.Sh SYNOPSIS +.Nm +is integrated into the +.Xr usb 4 +kernel module. +.Sh DESCRIPTION +The +.Nm +driver provides support for all USB devices that do not have +a special driver. +It supports access to all parts of the device, +but not in a way that is as convenient as a special purpose driver. +.Pp +There can be up to 127 USB devices connected to a USB bus. +Each USB device can have up to 16 endpoints. +Each of these endpoints +will communicate in one of four different modes: control, isochronous, +bulk, or interrupt. +Each of the endpoints will have a different +device node. +The four least significant bits in the minor device +number determine which endpoint the device accesses, and the rest +of the bits determine which USB device. +.Pp +If an endpoint address is used both for input and output, the device +can be opened for both read or write. +.Pp +To find out which endpoints exist, there are a series of +.Xr ioctl 2 +operations on the control endpoint that return the USB descriptors +of the device, configurations, interfaces, and endpoints. +.Pp +The control transfer mode can only happen on the control endpoint +which is always endpoint 0. +The control endpoint accepts a request +and may respond with an answer to such a request. +Control requests +are issued by +.Xr ioctl 2 +calls. +.\" .Pp +.\" The isochronous transfer mode can be in or out depending on the +.\" endpoint. +.\" To perform I/O on an isochronous endpoint +.\" .Xr read 2 +.\" and +.\" .Xr write 2 +.\" should be used. +.\" Before any I/O operations can take place the transfer rate in +.\" bytes/second has to be set. +.\" This is done with +.\" .Xr ioctl 2 +.\" .Dv USB_SET_ISO_RATE . +.\" Performing this call sets up a buffer corresponding to +.\" about 1 second of data. +.Pp +The bulk transfer mode can be in or out depending on the +endpoint. +To perform I/O on a bulk endpoint +.Xr read 2 +and +.Xr write 2 +should be used. +All I/O operations on a bulk endpoint are unbuffered. +.Pp +The interrupt transfer mode can be in or out depending on the +endpoint. +To perform I/O on an interrupt endpoint +.Xr read 2 +and +.Xr write 2 +should be used. +A moderate amount of buffering is done +by the driver. +.Pp +All endpoints handle the following +.Xr ioctl 2 +calls: +.Bl -tag -width indent +.It Dv USB_SET_SHORT_XFER Pq Vt int +Allow short read transfer. +Normally a transfer from the device +which is shorter than the request specified is reported as an +error. +.It Dv USB_SET_TIMEOUT Pq Vt int +Set the timeout on the device operations +The time is specified in milliseconds. +The value 0 is used to indicate that there is +no timeout. +.El +.Pp +The control endpoint (endpoint 0) handles the following +.Xr ioctl 2 +calls: +.Bl -tag -width indent +.It Dv USB_GET_CONFIG Pq Vt int +Get the device configuration number. +.It Dv USB_SET_CONFIG Pq Vt int +Set the device into the given configuration number. +.Pp +This operation can only be performed when the control endpoint +is the sole open endpoint. +.It Dv USB_GET_ALTINTERFACE Pq Vt "struct usb_alt_interface" +Get the alternative setting number for the interface with the given +index. +The +.Va uai_config_index +is ignored in this call. +.Bd -literal +struct usb_alt_interface { + int uai_config_index; + int uai_interface_index; + int uai_alt_no; +}; +.Ed +.It Dv USB_SET_ALTINTERFACE Pq Vt "struct usb_alt_interface" +Set the alternative setting to the given number in the interface with the +given index. +The +.Va uai_config_index +is ignored in this call. +.Pp +This operation can only be performed when no endpoints for the interface +are open. +.It Dv USB_GET_NO_ALT Pq Vt "struct usb_alt_interface" +Return the number of different alternate settings in the +.Va uai_alt_no +field. +.It Dv USB_GET_DEVICE_DESC Pq Vt usb_device_descriptor_t +Return the device descriptor. +.It Dv USB_GET_CONFIG_DESC Pq Vt "struct usb_config_desc" +Return the descriptor for the configuration with the given index. +For convenience, the current configuration can be specified by +.Dv USB_CURRENT_CONFIG_INDEX . +.Bd -literal +struct usb_config_desc { + int ucd_config_index; + usb_config_descriptor_t ucd_desc; +}; +.Ed +.It Dv USB_GET_INTERFACE_DESC Pq Vt "struct usb_interface_desc" +Return the interface descriptor for an interface specified by its +configuration index, interface index, and alternative index. +For convenience, the current alternative can be specified by +.Dv USB_CURRENT_ALT_INDEX . +.Bd -literal +struct usb_interface_desc { + int uid_config_index; + int uid_interface_index; + int uid_alt_index; + usb_interface_descriptor_t uid_desc; +}; +.Ed +.It Dv USB_GET_ENDPOINT_DESC Pq Vt "struct usb_endpoint_desc" +Return the endpoint descriptor for the endpoint specified by its +configuration index, interface index, alternative index, and +endpoint index. +.Bd -literal +struct usb_endpoint_desc { + int ued_config_index; + int ued_interface_index; + int ued_alt_index; + int ued_endpoint_index; + usb_endpoint_descriptor_t ued_desc; +}; +.Ed +.It Dv USB_GET_FULL_DESC Pq Vt "struct usb_full_desc" +Return all the descriptors for the given configuration. +.Bd -literal +struct usb_full_desc { + int ufd_config_index; + u_int ufd_size; + u_char *ufd_data; +}; +.Ed +The +.Va ufd_data +field should point to a memory area of the size given in the +.Va ufd_size +field. +The proper size can be determined by first issuing a +.Dv USB_GET_CONFIG_DESC +and inspecting the +.Va wTotalLength +field. +.It Dv USB_GET_STRING_DESC Pq Vt "struct usb_string_desc" +Get a string descriptor for the given language ID and +string index. +.Bd -literal +struct usb_string_desc { + int usd_string_index; + int usd_language_id; + usb_string_descriptor_t usd_desc; +}; +.Ed +.It Dv USB_DO_REQUEST Pq Vt "struct usb_ctl_request" +Send a USB request to the device on the control endpoint. +Any data sent to/from the device is located at +.Va ucr_data . +The size of the transferred data is determined from the +.Va ucr_request . +The +.Va ucr_addr +field is ignored in this call. +The +.Va ucr_flags +field can be used to flag that the request is allowed to +be shorter than the requested size, and +.Va ucr_actlen +will contain the actual size on completion. +.Bd -literal +struct usb_ctl_request { + int ucr_addr; + usb_device_request_t ucr_request; + void *ucr_data; + int ucr_flags; +#define USBD_SHORT_XFER_OK 0x04 /* allow short reads */ + int ucr_actlen; /* actual length transferred */ +}; +.Ed +This is a dangerous operation in that it can perform arbitrary operations +on the device. +Some of the most dangerous (e.g., changing the device +address) are not allowed. +.It Dv USB_GET_DEVICEINFO Pq Vt "struct usb_device_info" +Get an information summary for the device. +This call will not issue any USB transactions. +.El +.Pp +Note that there are two different ways of addressing configurations, +interfaces, alternatives, and endpoints: by index or by number. +The index is the ordinal number (starting from 0) of the descriptor +as presented by the device. +The number is the respective number of +the entity as found in its descriptor. +Enumeration of descriptors +uses the index, getting and setting typically uses numbers. +.Pp +Example: +all endpoints (except the control endpoint) for the current configuration +can be found by iterating the +.Va interface_index +from 0 to +.Va config_desc->bNumInterface Ns \-1 +and for each of these, iterating the +.Va endpoint_index +from 0 to +.Va interface_desc->bNumEndpoints . +The +.Va config_index +should be set to +.Dv USB_CURRENT_CONFIG_INDEX +and +.Va alt_index +should be set to +.Dv USB_CURRENT_ALT_INDEX . +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va hw.usb.ugen.debug +Debug output level, where 0 is debugging disabled and larger values increase +debug message verbosity. +Default is 0. +.El +.Sh FILES +.Bl -tag -width "/dev/usb/B.D.E" -compact +.It Pa /dev/usb/B.D.E +Endpoint +.Ar E +of device +.Ar D +at bus +.Ar B . +.It Pa /dev/ugenB.D +Control endpoint, 0, of device +.Ar D +at bus +.Ar B . +.El +.Sh SEE ALSO +.Xr usb 4 +.Sh HISTORY +The +.Nm +driver +appeared in +.Nx 1.4 . diff --git a/static/freebsd/man4/ugold.4 b/static/freebsd/man4/ugold.4 new file mode 100644 index 00000000..d8b2f456 --- /dev/null +++ b/static/freebsd/man4/ugold.4 @@ -0,0 +1,59 @@ +.\" $OpenBSD: ugold.4,v 1.1 2013/09/06 08:39:39 mpi Exp $ +.\" +.\" Copyright (c) 2013 Takayoshi SASANO +.\" Copyright (c) 2013 Martin Pieuchot +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd June 11, 2015 +.Dt UGOLD 4 +.Os +.Sh NAME +.Nm ugold +.Nd TEMPer gold HID thermometer +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines into +your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device usb" +.Cd "device hid" +.Cd "device ugold" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, +place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ugold_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for pcsensors TEMPer gold devices. +.Pp +The driver possesses a collection of sensor values which are +made available through the +.Xr sysctl 8 +interface. +.Sh HARDWARE +The following devices are supported by the +.Nm +driver: +.Pp +.Bl -bullet -compact +.It +RDing TEMPer1V1.2 +.El +.Sh SEE ALSO +.Xr usb 4 , +.Xr sysctl 8 diff --git a/static/freebsd/man4/uhci.4 b/static/freebsd/man4/uhci.4 new file mode 100644 index 00000000..689dc4b8 --- /dev/null +++ b/static/freebsd/man4/uhci.4 @@ -0,0 +1,78 @@ +.\" Copyright (c) 1999 +.\" Nick Hibma . 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 April 24, 2018 +.Dt UHCI 4 +.Os +.Sh NAME +.Nm uhci +.Nd UHCI USB Host Controller driver +.Sh SYNOPSIS +.Cd "device uhci" +.Sh DESCRIPTION +The +.Nm +driver provides support for UHCI-type PCI based USB controllers. +.Sh HARDWARE +The +.Nm +driver supports all UHCI v1.1 compliant controllers including: +.Pp +.Bl -bullet -compact +.It +Intel 82371AB/EB (PIIX4) +.It +Intel 82371SB (PIIX3) +.It +VIA 83C572 +.El +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va hw.usb.uhci.debug +Debug output level, where 0 is debugging disabled and larger values increase +debug message verbosity. +Default is 0. +.El +.Sh SEE ALSO +.Xr ehci 4 , +.Xr ohci 4 , +.Xr xhci 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 3.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Lennart Augustsson Aq Mt augustss@carlstedt.se +for the +.Nx +project. diff --git a/static/freebsd/man4/uhid.4 b/static/freebsd/man4/uhid.4 new file mode 100644 index 00000000..f7c8a22a --- /dev/null +++ b/static/freebsd/man4/uhid.4 @@ -0,0 +1,181 @@ +.\" $NetBSD: uhid.4,v 1.13 2001/12/29 14:41:59 augustss Exp $ +.\" +.\" Copyright (c) 1999, 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Lennart Augustsson. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 Oct 31, 2020 +.Dt UHID 4 +.Os +.Sh NAME +.Nm uhid +.Nd USB generic HID support +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device uhid" +.Cd "device hid" +.Cd "device usb" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +uhid_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for all HID (Human Interface Device) interfaces +in USB devices that do not have a special driver. +.Pp +The device handles the following +.Xr ioctl 2 +calls: +.Bl -tag -width indent +.It Dv USB_GET_REPORT_ID Pq Vt int +Get the report identifier used by this HID report. +.It Dv USB_GET_REPORT_DESC Pq Vt "struct usb_gen_descriptor" +Get the HID report descriptor. +Copies a maximum of +.Va ugd_maxlen +bytes of the report descriptor data into the memory +specified by +.Va ugd_data . +Upon return +.Va ugd_actlen +is set to the number of bytes copied. +Using +this descriptor the exact layout and meaning of data to/from +the device can be found. +The report descriptor is delivered +without any processing. +.Bd -literal +struct usb_gen_descriptor { + void *ugd_data; + uint16_t ugd_maxlen; + uint16_t ugd_actlen; + uint8_t ugd_report_type; + ... +}; +.Ed +.It Dv USB_SET_IMMED Pq Vt int +Sets the device in a mode where each +.Xr read 2 +will return the current value of the input report. +Normally +a +.Xr read 2 +will only return the data that the device reports on its +interrupt pipe. +This call may fail if the device does not support +this feature. +.It Dv USB_GET_REPORT Pq Vt "struct usb_gen_descriptor" +Get a report from the device without waiting for data on +the interrupt pipe. +Copies a maximum of +.Va ugd_maxlen +bytes of the report data into the memory specified by +.Va ugd_data . +Upon return +.Va ugd_actlen +is set to the number of bytes copied. +The +.Va ugd_report_type +field indicates which report is requested. +It should be +.Dv UHID_INPUT_REPORT , +.Dv UHID_OUTPUT_REPORT , +or +.Dv UHID_FEATURE_REPORT . +This call may fail if the device does not support this feature. +.It Dv USB_SET_REPORT Pq Vt "struct usb_gen_descriptor" +Set a report in the device. +The +.Va ugd_report_type +field indicates which report is to be set. +It should be +.Dv UHID_INPUT_REPORT , +.Dv UHID_OUTPUT_REPORT , +or +.Dv UHID_FEATURE_REPORT . +The value of the report is specified by the +.Va ugd_data +and the +.Va ugd_maxlen +fields. +This call may fail if the device does not support this feature. +.It Dv USB_GET_DEVICEINFO Pq Vt "struct usb_device_info" +Returns information about the device, like USB vendor ID and USB product ID. +This call will not issue any USB transactions. +Also refer to +.Xr ugen 4 . +.El +.Pp +Use +.Xr read 2 +to get data from the device. +Data should be read in chunks of the +size prescribed by the report descriptor. +.Pp +Use +.Xr write 2 +to send data to the device. +Data should be written in chunks of the +size prescribed by the report descriptor. +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va hw.usb.uhid.debug +Debug output level, where 0 is debugging disabled and larger values increase +debug message verbosity. +Default is 0. +.El +.Sh FILES +.Bl -tag -width ".Pa /dev/uhid?" +.It Pa /dev/uhid? +.El +.Sh SEE ALSO +.Xr usbhidctl 1 , +.Xr usb 4 +.Sh HISTORY +The +.Nm +driver +appeared in +.Nx 1.4 . +This manual page was adopted from +.Nx +by +.An Tom Rhodes Aq Mt trhodes@FreeBSD.org +in April 2002. diff --git a/static/freebsd/man4/uhso.4 b/static/freebsd/man4/uhso.4 new file mode 100644 index 00000000..d88c9252 --- /dev/null +++ b/static/freebsd/man4/uhso.4 @@ -0,0 +1,140 @@ +.\" Copyright (c) 2009 Fredrik Lindberg +.\" 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 ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 20, 2010 +.Dt UHSO 4 +.Os +.Sh NAME +.Nm uhso +.Nd support for several HSxPA devices from Option N.V. +.Sh SYNOPSIS +The module can be loaded at boot time by placing the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +uhso_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for several HSxPA devices from Option N.V. that are +based on their packet interface. +Each device has a set of serial ports and a raw IP packet interface. +The serial ports of the device are accessed through the +.Xr ucom 4 +driver which makes them behave like +.Xr tty 4 +devices. +The packet interface is exposed as a network interface. +.Pp +Establishing a connection on the packet interface is achieved by using the +proprietary AT commands +.Dq Li AT_OWANCALL +and +.Dq Li AT_OWANDATA +on any of the available serial ports. +.Pp +The network interface must be configured manually using the data obtain from +these calls. +.Pp +Each device usually have at least two or more serial ports, their individual purpose +can be identified through +.Xr sysctl 8 . +Ports identified as +.Dq Modem +features a normal modem interface that can be used with PPP. +Ports identified as +.Dq Diagnostic +uses a proprietary binary interface used for firmware upgrades, this port does not +have a AT command interface and can not be used to control the device. +Other ports features an AT command interface that can be used for normal device control. +.Sh HARDWARE +The +.Nm +driver should work with most devices from Option. +The following devices have been verified to work +.Pp +.Bl -bullet -compact +.It +Option GlobeSurfer iCON 7.2 (new firmware) +.It +Option GlobeTrotter Max 7.2 (new firmware) +.It +Option iCON 225 +.It +Option iCON 452 +.It +Option iCON 505 +.El +.Pp +The device features a mass storage device referred to as +.Dq Zero-CD +which contains drivers for Microsoft Windows; this is the default +mode for the device. +The +.Nm +driver automatically switches the device from +.Dq Zero-CD +mode to modem mode. +This behavior can be disabled by setting +.Va hw.usb.uhso.auto_switch +to 0 using +.Xr sysctl 8 . +.Sh FILES +.Bl -tag -width "XXXXXX" +.It Pa /dev/cuaU?.? +.El +.Sh EXAMPLES +Establishing a packet interface connection using the AT command interface available +at one of the serial ports +.Bd -literal -offset indent +AT+CGDCONT=1,,"apn.provider" +AT_OWANCALL=1,1,1 +OK +_OWANCALL=1,1 + +AT_OWANDATA=1 +_OWANDATA: 1, 10.11.12.13, 0.0.0.0, 10.2.3.4, 10.2.3.5, \e + 0.0.0.0, 0.0.0.0, 72000 +.Ed +.Pp +Configuring the interface +.Bd -literal -offset indent +ifconfig uhso0 10.11.12.13 up +route add default -interface uhso0 +echo "nameserver 10.2.3.4" > /etc/resolv.conf +echo "nameserver 10.2.3.5" >> /etc/resolv.conf +.Ed +.Pp +The connection can be terminated with +.Bd -literal -offset indent +AT_OWANCALL=1,0,1 +.Ed +.Sh SEE ALSO +.Xr uhsoctl 1 , +.Xr ucom 4 , +.Xr usb 4 +.Sh AUTHORS +The +.Nm +driver was written by +.An Fredrik Lindberg Aq Mt fli@shapeshifter.se . diff --git a/static/freebsd/man4/uipaq.4 b/static/freebsd/man4/uipaq.4 new file mode 100644 index 00000000..b4934495 --- /dev/null +++ b/static/freebsd/man4/uipaq.4 @@ -0,0 +1,119 @@ +.\" $OpenBSD: uipaq.4,v 1.1 2005/06/17 23:50:35 deraadt Exp $ +.\" $NetBSD: uipaq.4,v 1.3 2008/04/30 13:10:54 martin Exp $ +.\" +.\" Copyright (c) 2001-2005 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Lennart Augustsson. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 14, 2025 +.Dt UIPAQ 4 +.Os +.Sh NAME +.Nm uipaq +.Nd USB support for iPAQ units +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device usb" +.Cd "device ucom" +.Cd "device uipaq" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +uipaq_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the USB serial emulation provided +by the iPAQ devices. +.Pp +The device is accessed through the +.Xr ucom 4 +driver which makes it behave like a +.Xr tty 4 . +.Sh HARDWARE +The +.Nm +driver supports the following iPAQ devices: +.Pp +.Bl -bullet -compact +.It +ASUS P535 PDA +.It +Casio BE300 PDA +.It +Compaq IPaq PocketPC +.It +HP Jornada 568 +.It +HP iPAQ 22xx/Jornada 548 +.It +HTC PPC6700 Modem +.It +HTC Smart Phone +.It +HTC Winmobile +.It +Sharp W-ZERO3 ES Spart Phone +.It +Most Windows CE based phones +.El +.Sh FILES +.Bl -tag -width "/dev/ttyU*.init" -compact +.It Pa /dev/ttyU* +for callin ports +.It Pa /dev/ttyU*.init +.It Pa /dev/ttyU*.lock +corresponding callin initial-state and lock-state devices +.Pp +.It Pa /dev/cuaU* +for callout ports +.It Pa /dev/cuaU*.init +.It Pa /dev/cuaU*.lock +corresponding callout initial-state and lock-state devices +.El +.Sh SEE ALSO +.Xr tty 4 , +.Xr ucom 4 , +.Xr usb 4 +.Sh HISTORY +The +.Fx +support was imported from +.Nx +for +.Fx 7.0 . +.Nx +added support in +.Nx 4.0 +and it was imported from +.Ox 3.8 . diff --git a/static/freebsd/man4/ukbd.4 b/static/freebsd/man4/ukbd.4 new file mode 100644 index 00000000..003600aa --- /dev/null +++ b/static/freebsd/man4/ukbd.4 @@ -0,0 +1,207 @@ +.\" Copyright (c) 1997, 1998 +.\" Nick Hibma . 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 April 23, 2026 +.Dt UKBD 4 +.Os +.Sh NAME +.Nm ukbd +.Nd USB keyboard driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ukbd" +.Cd "device hid" +.Cd "device usb" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ukbd_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for keyboards that attach to the USB port. +.Xr usb 4 +and one of +.Xr uhci 4 +or +.Xr ohci 4 +must be configured in the kernel as well. +.Sh CONFIGURATION +By default, the keyboard subsystem does not create the appropriate devices yet. +Make sure you reconfigure your kernel with the following option in the kernel +config file: +.Pp +.Dl "options KBD_INSTALL_CDEV" +.Pp +If both an AT keyboard USB keyboards are used at the same time, the +AT keyboard will appear as +.Pa kbd0 +in +.Pa /dev . +The USB keyboards will be +.Pa kbd1 , kbd2 , +etc. +You can see some information about the keyboard with the following command: +.Pp +.Dl "kbdcontrol -i < /dev/kbd1" +.Pp +or load a keymap with +.Pp +.Dl "kbdcontrol -l keymaps/pt.iso < /dev/kbd1" +.Pp +See +.Xr kbdcontrol 1 +for more possible options. +.Pp +You can swap console keyboards by using the command +.Pp +.Dl "kbdcontrol -k /dev/kbd1" +.Pp +From this point on, the first USB keyboard will be the keyboard +to be used by the console. +.Pp +If you want to use a USB keyboard as your default and not use an AT keyboard at +all, you will have to remove the +.Cd "device atkbd" +line from the kernel configuration file. +Because of the device initialization order, +the USB keyboard will be detected +.Em after +the console driver +initializes itself and you have to explicitly tell the console +driver to use the existence of the USB keyboard. +This can be done in +one of the following two ways. +.Pp +Run the following command as a part of system initialization: +.Pp +.Dl "kbdcontrol -k /dev/kbd0 < /dev/ttyv0 > /dev/null" +.Pp +(Note that as the USB keyboard is the only keyboard, it is accessed as +.Pa /dev/kbd0 ) +or otherwise tell the console driver to periodically look for a +keyboard by setting a flag in the kernel configuration file: +.Pp +.Dl "device sc0 at isa? flags 0x100" +.Pp +With the above flag, the console driver will try to detect any +keyboard in the system if it did not detect one while it was +initialized at boot time. +.Sh DRIVER CONFIGURATION +.D1 Cd "options KBD_INSTALL_CDEV" +.Pp +Make the keyboards available through a character device in +.Pa /dev . +.Pp +.D1 Cd options UKBD_DFLT_KEYMAP +.D1 Cd makeoptions UKBD_DFLT_KEYMAP=fr.iso +.Pp +The above lines will put the French ISO keymap in the ukbd driver. +You can specify any keymap in +.Pa /usr/share/syscons/keymaps +or +.Pa /usr/share/vt/keymaps +(depending on the console driver being used) with this option. +.Pp +.D1 Cd "options KBD_DISABLE_KEYMAP_LOADING" +.Pp +Do not allow the user to change the keymap. +.Pp +.D1 Cd "options KBD_DELAY1=200" +.Pp +Set the keyboard initial key repeat delay. +.Pp +.D1 Cd "options KBD_DELAY2=15" +.Pp +Set the keyboard key repeat delay. +.Pp +Note that these options also affect the AT keyboard driver, +.Xr atkbd 4 . +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va hw.usb.ukbd.debug +Debug output level, where 0 is debugging disabled and larger values increase +debug message verbosity. +Default is 0. +.It Va hw.usb.ukbd.apple_swap_cmd_opt +Swap the Command & Option keys on Apple keyboards if set to 1. +Default is 0. +.It Va hw.usb.ukbd.apple_swap_cmd_ctl +Swap the Command & Control keys on Apple keyboards if set to 1. +Default is 0. +.It Va hw.usb.ukbd.apple_fn_mode +Direct access to media keys without holding Fn if set to 1. +Default is 0. +.It Va hw.usb.ukbd.no_leds +Disables setting of keyboard LEDs if set to 1. +Default is 0. +.El +.Sh FILES +.Bl -tag -width ".Pa /dev/kbd*" -compact +.It Pa /dev/kbd* +blocking device nodes +.El +.Sh EXAMPLES +.D1 Cd "device ukbd" +.Pp +Add the +.Nm +driver to the kernel. +.Sh SEE ALSO +.Xr kbdcontrol 1 , +.Xr ohci 4 , +.Xr syscons 4 , +.Xr uhci 4 , +.Xr usb 4 , +.Xr vt 4 , +.Xr config 8 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Lennart Augustsson Aq Mt augustss@cs.chalmers.se +for +.Nx +and was substantially rewritten for +.Fx +by +.An Kazutaka YOKOTA Aq Mt yokota@zodiac.mech.utsunomiya-u.ac.jp . +.Pp +This manual page was written by +.An Nick Hibma Aq Mt n_hibma@FreeBSD.org +with a large amount of input from +.An Kazutaka YOKOTA Aq Mt yokota@zodiac.mech.utsunomiya-u.ac.jp . diff --git a/static/freebsd/man4/uled.4 b/static/freebsd/man4/uled.4 new file mode 100644 index 00000000..99deb90b --- /dev/null +++ b/static/freebsd/man4/uled.4 @@ -0,0 +1,93 @@ +.\" +.\" Copyright (c) 2014 Kevin Lo +.\" 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 March 31, 2017 +.Dt ULED 4 +.Os +.Sh NAME +.Nm uled +.Nd USB LED driver +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines into +your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device uled" +.Cd "device usb" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, +place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +uled_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for Dream Cheeky WebMail Notifier and +ThingM blink(1) notification LED. +.Pp +Subsequently, the +.Pa /dev/uled0 +device can be used by userland applications. +.Sh IOCTLS +The following +.Xr ioctl 2 +commands can be performed on +.Pa /dev/uled0 , +which are defined in +.In dev/usb/uled_ioctl.h : +.Bl -tag -width indent +.It Dv ULED_GET_COLOR +The command returns LED colors with values for RGB. +This +.Xr ioctl 2 +takes the following structure: +.Bd -literal +struct uled_color { + uint8_t red; + uint8_t green; + uint8_t blue; +}; +.Ed +.It Dv ULED_SET_COLOR +The command sets LED colors with values for RGB. +It uses the same structure as above. +.El +.Sh FILES +.Bl -tag -width ".Pa /dev/uled0" -compact +.It Pa /dev/uled0 +blocking device node +.El +.Sh SEE ALSO +.Xr ohci 4 , +.Xr uhci 4 , +.Xr usb 4 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Kevin Lo Aq Mt kevlo@FreeBSD.org . diff --git a/static/freebsd/man4/ulpt.4 b/static/freebsd/man4/ulpt.4 new file mode 100644 index 00000000..4dbe3494 --- /dev/null +++ b/static/freebsd/man4/ulpt.4 @@ -0,0 +1,108 @@ +.\" $NetBSD: ulpt.4,v 1.6 2002/02/05 00:37:48 augustss Exp $ +.\" +.\" Copyright (c) 1999 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Lennart Augustsson. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 November 22, 2006 +.Dt ULPT 4 +.Os +.Sh NAME +.Nm ulpt +.Nd USB printer support +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ulpt" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ulpt_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for USB printers that follow the printer +bi- or uni-directional protocol. +The bits in the minor number select various features of the driver. +.Bl -column "Minor Bit" "Functionxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -offset indent +.It Em "Minor Bit" Ta Em "Function" +.It "64" Ta "Do not initialize (reset) the device on the port." +.El +.Pp +Some printers cannot handle the reset on open; in case of problems try the +.Pa unlpt +device. +.Sh HARDWARE +The +.Nm +driver provides support for USB printers and parallel printer +conversion cables, including the following: +.Pp +.Bl -bullet -compact +.It +ATen parallel printer adapter +.It +Belkin F5U002 parallel printer adapter +.It +Canon BJ F850, S600 +.It +Canon LBP-1310, 350 +.It +Entrega USB-to-parallel printer adapter +.It +Hewlett-Packard HP Deskjet 3420 (P/N: C8947A #ABJ) +.It +Oki Data MICROLINE ML660PS +.It +Seiko Epson PM-900C, 880C, 820C, 730C +.El +.Sh FILES +.Bl -tag -width ".Pa /dev/unlpt?" -compact +.It Pa /dev/ulpt? +device with reset +.It Pa /dev/unlpt? +device without reset +.El +.Sh SEE ALSO +.Xr lpt 4 , +.Xr usb 4 +.Sh HISTORY +The +.Nm +driver +appeared in +.Nx 1.4 . +This manual page was adopted from +.Nx +by +.An Tom Rhodes Aq Mt trhodes@FreeBSD.org +in April 2002. diff --git a/static/freebsd/man4/umass.4 b/static/freebsd/man4/umass.4 new file mode 100644 index 00000000..306dc4e8 --- /dev/null +++ b/static/freebsd/man4/umass.4 @@ -0,0 +1,147 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 1999 +.\" Nick Hibma . 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 November 28, 2025 +.Dt UMASS 4 +.Os +.Sh NAME +.Nm umass +.Nd USB Mass Storage Devices driver +.Sh SYNOPSIS +.Cd "device da" +.Cd "device scbus" +.Cd "device pass" +.Cd "device usb" +.Cd "device umass" +.Pp +In +.Xr loader.conf 5 : +.Cd umass_load +.Sh DESCRIPTION +The +.Nm +driver provides support for Mass Storage devices that attach to the USB +interface. +.Pp +If the appropriate hardware is detected, +the driver will be loaded automatically by +.Xr devmatch 8 . +To load the driver manually at boot time, use the +.Cm umass_load +command at the +.Xr loader 8 +prompt, or add it to +.Xr loader.conf 5 . +.Pp +To use the driver in a custom kernel, +.Xr usb 4 +and at least one of +.Xr uhci 4 , +.Xr ohci 4 , +.Xr ehci 4 , +or +.Xr xhci 4 +must be configured in the kernel. +Additionally, since +.Nm +uses the SCSI subsystem and sometimes acts as a SCSI device, it +requires +.Xr da 4 +and +.Xr scbus 4 +to be included in the kernel. +.Sh HARDWARE +The +.Nm +driver supports USB Mass Storage devices such as: +.Pp +.Bl -bullet -compact +.It +USB thumb drives +.It +USB hard disk drives +.It +USB floppy drives +.El +.Pp +The +.Nm +driver tries its best to avoid issues with the drives, not all issues +can be handled automatically, so quirks may be necessary. +See the +.Em USB Mass Sotrage quirks +section of +.Xr usb_quirk 4 +for quirks for the drives. +The +.Cd add_dev_quirk_vplh +and +.Cd add_quirk +commands of +.Xr usbconfig 8 +can manage these dynamically. +Quirks can be specified via tuables, as described in +.Xr usb_quirk 4 . +.Sh EXAMPLES +Rescan all slots on a multi-slot flash reader, +where the slots map to separate LUNs on a single SCSI ID: +.Bd -literal -offset indent +camcontrol rescan 0:0:0 +camcontrol rescan 0:0:1 +camcontrol rescan 0:0:2 +camcontrol rescan 0:0:3 +.Ed +.Pp +Typically only the first slot will be enabled at boot time. +This assumes that +the flash reader is the first SCSI bus in the system and has 4 slots. +.Sh SEE ALSO +.Xr cfumass 4 , +.Xr ehci 4 , +.Xr ohci 4 , +.Xr uhci 4 , +.Xr usb 4 , +.Xr usb_quirk 4 , +.Xr xhci 4 , +.Xr camcontrol 8 , +.Xr usbconfig 8 . +.Sh HISTORY +The +.Nm +driver appeared in +.Fx 4.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An MAEKAWA Masahide Aq Mt bishop@rr.iij4u.or.jp +and +.An Nick Hibma Aq Mt n_hibma@FreeBSD.org . +.Pp +This manual page was written by +.An Nick Hibma Aq Mt n_hibma@FreeBSD.org . diff --git a/static/freebsd/man4/umb.4 b/static/freebsd/man4/umb.4 new file mode 100644 index 00000000..37c86b30 --- /dev/null +++ b/static/freebsd/man4/umb.4 @@ -0,0 +1,118 @@ +.\"- +.\" SPDX-License-Identifier: 0BSD +.\" +.\" Copyright (c) 2016 genua mbH +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $NetBSD: umb.4,v 1.4 2019/08/30 09:22:17 wiz Exp $ +.\" +.Dd September 3, 2025 +.Dt UMB 4 +.Os +.Sh NAME +.Nm umb +.Nd USB Mobile Broadband Interface Model (MBIM) cellular modem driver +.Sh SYNOPSIS +.Cd "device usb" +.Cd "device umb" +.Pp +In +.Xr loader.conf 5 : +.Cd umb_load="YES" +.Sh DESCRIPTION +The +.Nm +driver provides support for USB MBIM devices. +If the appropriate hardware is detected, +the driver will be loaded automatically by +.Xr devmatch 8 . +To load the driver manually, +.Cm load +it in +.Xr loader.conf 5 +or at the +.Xr loader 8 +prompt. +.Pp +MBIM devices establish connections via cellular networks such as +GPRS, UMTS, and LTE. +They appear as a regular point-to-point network interface, +transporting raw IP frames. +.Pp +Required configuration parameters like PIN and APN have to be set +with +.Xr umbctl 8 . +Once the SIM card has been unlocked with the correct PIN, it +will remain in this state until the MBIM device is power-cycled. +In case the device is connected to an "always-on" USB port, +it may be possible to connect to a provider without entering the +PIN again even if the system was rebooted. +.Sh HARDWARE +The +.Nm +driver should support any USB device implementing MBIM, including +the following cellular modems: +.Pp +.Bl -bullet -compact +.It +Ericsson H5321gw and N5321gw +.It +Fibocom L831-EAU +.It +Medion Mobile S4222 (MediaTek OEM) +.It +Sierra Wireless EM7345 +.It +Sierra Wireless EM7455 +.It +Sierra Wireless EM8805 +.It +Sierra Wireless MC8305 +.El +.Sh SEE ALSO +.Xr intro 4 , +.Xr netintro 4 , +.Xr usb 4 , +.Xr ifconfig 8 , +.Xr umbctl 8 +.Rs +.%T "Universal Serial Bus Communications Class Subclass Specification for Mobile Broadband Interface Model" +.%U http://www.usb.org/developers/docs/devclass_docs/MBIM10Errata1_073013.zip +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Ox 6.0 , +.Nx 9.0 , +and +.Fx 15.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Gerhard Roth Aq Mt gerhard@openbsd.org +and ported from +.Ox +by +.An Pierre Pronchery Aq Mt khorben@defora.org . +.Sh CAVEATS +The +.Nm +driver does not support IPv6. +.Pp +Devices which fail to provide a conforming MBIM implementation will +probably be attached as some other driver, such as +.Xr u3g 4 . diff --git a/static/freebsd/man4/umcs.4 b/static/freebsd/man4/umcs.4 new file mode 100644 index 00000000..0ed77806 --- /dev/null +++ b/static/freebsd/man4/umcs.4 @@ -0,0 +1,112 @@ +.\" +.\" Copyright (c) 2010 Lev Serebryakov . +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Lennart Augustsson. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 26, 2017 +.Dt UMCS 4 +.Os +.Sh NAME +.Nm umcs +.Nd USB support for serial adapters based on the MCS7820 and MCS7840 chips +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device usb" +.Cd "device ucom" +.Cd "device umcs" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +umcs_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for various multiport serial adapters based on the MosCom +MCS7820 and MCS7840 chips. +They are 2- or 4-port adapters with full-featured +16550-compatible UARTs and very flexible baud generators. +Also, these chips +support RS422/RS485 and IrDA operations. +.Pp +The device is accessed through the +.Xr ucom 4 +driver which makes it behave like a +.Xr tty 4 . +.Pp +Different ports on device are presented as sub-units, like +.Pa /dev/ttyU0.1 +and +.Pa /dev/ttyU0.2 . +.Sh HARDWARE +The +.Nm +driver was tested on the following adapters: +.Pp +.Bl -bullet -compact +.It +ST Lab U-360 two-port serial USB adapter +.It +ST Lab U-400 four-port serial USB adapter +.El +.Sh FILES +.Bl -tag -width "/dev/ttyU*.*.init" -compact +.It Pa /dev/ttyU*.* +for callin ports +.It Pa /dev/ttyU*.*.init +.It Pa /dev/ttyU*.*.lock +corresponding callin initial-state and lock-state devices +.Pp +.It Pa /dev/cuaU*.* +for callout ports +.It Pa /dev/cuaU*.*.init +.It Pa /dev/cuaU*.*.lock +corresponding callout initial-state and lock-state devices +.El +.Sh SEE ALSO +.Xr tty 4 , +.Xr ucom 4 , +.Xr usb 4 +.Sh HISTORY +The +.Nm +driver +appeared in ports since December of 2010. +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Lev Serebryakov Aq Mt lev@FreeBSD.org . +.Sh BUGS +This driver doesn't support access to any fine tunes of +chip, like RS522/RS485 mode, non-standard baudrates, etc. diff --git a/static/freebsd/man4/umct.4 b/static/freebsd/man4/umct.4 new file mode 100644 index 00000000..53e9a455 --- /dev/null +++ b/static/freebsd/man4/umct.4 @@ -0,0 +1,113 @@ +.\" +.\" Copyright (c) 2004 Scott Long +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 26, 2017 +.Dt UMCT 4 +.Os +.Sh NAME +.Nm umct +.Nd Magic Control Technology USB-RS232 converter driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device usb" +.Cd "device ucom" +.Cd "device umct" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +umct_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for USB to RS-232 converters based on the Magic +Control Technology USB-232 design. +These devices support most of the +standard RS-232 features including baud rates ranging from 300 to 115200 +bits per second. +However, neither hardware nor software flow control +seems to be supported. +.Pp +Access to devices under this driver is via the +.Xr ucom 4 +framework and device nodes. +.Sh HARDWARE +The +.Nm +driver supports the following adapters: +.Pp +.Bl -bullet -compact +.It +Belkin F5U109 +.It +Belkin F5U409 +.It +D-Link DU-H3SP USB BAY Hub +.It +Magic Control Technology USB-232 +.It +Sitecom USB-232 +.El +.Sh FILES +.Bl -tag -width "/dev/ttyU*.init" -compact +.It Pa /dev/ttyU* +for callin ports +.It Pa /dev/ttyU*.init +.It Pa /dev/ttyU*.lock +corresponding callin initial-state and lock-state devices +.Pp +.It Pa /dev/cuaU* +for callout ports +.It Pa /dev/cuaU*.init +.It Pa /dev/cuaU*.lock +corresponding callout initial-state and lock-state devices +.El +.Sh SEE ALSO +.Xr tty 4 , +.Xr ucom 4 , +.Xr usb 4 +.Sh HISTORY +The +.Nm +driver +appeared in +.Fx 5.2 . +It is loosely based on the +.Xr ubsa 4 +driver by +.An Alexander Kabaev Aq Mt kan@FreeBSD.org +with documentation from +.An Wolfgang Grandeggar Aq Mt wolfgang@cec.ch . +.Sh AUTHORS +The +.Nm +driver was written by +.An Scott Long Aq Mt scottl@FreeBSD.org . diff --git a/static/freebsd/man4/umodem.4 b/static/freebsd/man4/umodem.4 new file mode 100644 index 00000000..793f820f --- /dev/null +++ b/static/freebsd/man4/umodem.4 @@ -0,0 +1,128 @@ +.\" $NetBSD: umodem.4,v 1.6 2001/09/11 23:18:55 wiz Exp $ +.\" +.\" Copyright (c) 1999 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Lennart Augustsson. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 26, 2017 +.Dt UMODEM 4 +.Os +.Sh NAME +.Nm umodem +.Nd USB Communication Device Class serial (CDC ACM) driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device usb" +.Cd "device ucom" +.Cd "device umodem" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +umodem_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for USB modems and serial devices that +implement the Communication Device Class Abstract Control Model (CDC ACM). +It also provides device-side CDC ACM support. +Supported modems are basically standard serial line modems, but they are +accessed via USB instead. +They support a regular AT command set. +The commands can either be multiplexed with the data stream +or handled through separate pipes. +In the latter case the AT +commands have to be given on a device separate from the data device. +.Pp +The device is accessed through the +.Xr ucom 4 +driver which makes it behave like a +.Xr tty 4 . +.Sh HARDWARE +Devices supported by the +.Nm +driver include: +.Pp +.Bl -bullet -compact +.It +3Com 5605 +.It +Curitel PC5740 Wireless Modem +.It +Kyocera AH-K3001V Mobile Phone(WILLCOM) +.It +Kyocera WX320K Mobile Phone(WILLCOM) +.It +Metricom Ricochet GS USB wireless modem +.It +Sierra MC5720 Wireless Modem +.It +Yamaha Broadband Wireless Router RTW65b +.It +ELSA MicroLink 56k USB modem +.It +Sony Ericsson W810i phone +.It +Sonim XP5300 Force +.El +.Sh FILES +.Bl -tag -width "/dev/ttyU*.init" -compact +.It Pa /dev/ttyU* +for callin ports +.It Pa /dev/ttyU*.init +.It Pa /dev/ttyU*.lock +corresponding callin initial-state and lock-state devices +.Pp +.It Pa /dev/cuaU* +for callout ports +.It Pa /dev/cuaU*.init +.It Pa /dev/cuaU*.lock +corresponding callout initial-state and lock-state devices +.El +.Sh SEE ALSO +.Xr tty 4 , +.Xr ucom 4 , +.Xr usb 4 +.Sh HISTORY +The +.Nm +driver +appeared in +.Nx 1.5 . +This manual page was adopted from +.Nx +by +.An Tom Rhodes Aq Mt trhodes@FreeBSD.org +in April 2002. +.Sh BUGS +Only modems with multiplexed commands and data are supported +at the moment. diff --git a/static/freebsd/man4/umoscom.4 b/static/freebsd/man4/umoscom.4 new file mode 100644 index 00000000..faad33bf --- /dev/null +++ b/static/freebsd/man4/umoscom.4 @@ -0,0 +1,81 @@ +.\" +.\" Copyright (c) 2014 Hans Petter Selasky +.\" 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 April 26, 2017 +.Dt UMOSCOM 4 +.Os +.Sh NAME +.Nm umoscom +.Nd USB support for serial adapters based on chips made by MOSCHIP +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device usb" +.Cd "device ucom" +.Cd "device umoscom" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +umoscom_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for various serial adapters based on chips from MOSCHIP. +.Pp +The device is accessed through the +.Xr ucom 4 +driver which makes it behave like a +.Xr tty 4 . +.Sh FILES +.Bl -tag -width "/dev/ttyU*.init" -compact +.It Pa /dev/ttyU* +for callin ports +.It Pa /dev/ttyU*.init +.It Pa /dev/ttyU*.lock +corresponding callin initial-state and lock-state devices +.Pp +.It Pa /dev/cuaU* +for callout ports +.It Pa /dev/cuaU*.init +.It Pa /dev/cuaU*.lock +corresponding callout initial-state and lock-state devices +.El +.Sh SEE ALSO +.Xr tty 4 , +.Xr ucom 4 , +.Xr usb 4 +.Sh HISTORY +The +.Nm +driver appeared in +.Ox +and was ported to +.Fx . diff --git a/static/freebsd/man4/ums.4 b/static/freebsd/man4/ums.4 new file mode 100644 index 00000000..4e5ead6b --- /dev/null +++ b/static/freebsd/man4/ums.4 @@ -0,0 +1,124 @@ +.\" Copyright (c) 1999 +.\" Nick Hibma . 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 April 24, 2018 +.Dt UMS 4 +.Os +.Sh NAME +.Nm ums +.Nd USB mouse driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ums" +.Cd "device hid" +.Cd "device uhci" +.Cd "device ohci" +.Cd "device usb" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ums_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for mice that attach to the USB port. +Supported are +mice with any number of buttons and mice with a wheel. +.Pp +The +.Pa /dev/ums0 +device presents the mouse as a +.Ar sysmouse +or +.Ar mousesystems +type device. +See +.Xr moused 8 +for an explanation of these mouse types. +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va hw.usb.ums.debug +Debug output level, where 0 is debugging disabled and larger values increase +debug message verbosity. +Default is 0. +.El +.Sh FILES +.Bl -tag -width /dev/ums0 -compact +.It Pa /dev/ums0 +blocking device node +.El +.Sh EXAMPLES +Use the first +USB mouse on the system as your console mouse: +.Pp +.Dl moused -p /dev/ums0 -t auto +.Pp +To be able to use the USB mouse under X, change the "Pointer" section in +.Nm xorg.conf +to the following: +.Pp +.Dl Device "/dev/ums0" +.Dl Protocol "Auto" +.Pp +If you want to be able to use the mouse in both virtual consoles as well +as in X change it to: +.Pp +.Dl Device "/dev/sysmouse" +.Dl Protocol "Auto" +.Sh SEE ALSO +.Xr ohci 4 , +.Xr sysmouse 4 , +.Xr uhci 4 , +.Xr usb 4 , +.Xr xorg.conf 5 Pq Pa ports/x11/xorg , +.Xr moused 8 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Lennart Augustsson Aq Mt augustss@cs.chalmers.se +for +.Nx +and was adopted for +.Fx +by +.An MAEKAWA Masahide Aq Mt bishop@rr.iij4u.or.jp . +.Pp +This manual page was written by +.An Nick Hibma Aq Mt n_hibma@FreeBSD.org +with input from +.An Kazutaka YOKOTA Aq Mt yokota@zodiac.mech.utsunomiya-u.ac.jp . diff --git a/static/freebsd/man4/unionfs.4 b/static/freebsd/man4/unionfs.4 new file mode 100644 index 00000000..85714331 --- /dev/null +++ b/static/freebsd/man4/unionfs.4 @@ -0,0 +1,89 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2020 Gordon Bergling +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 27, 2020 +.Dt UNIONFS 4 +.Os +.Sh NAME +.Nm unionfs +.Nd union mount file system +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "option UNIONFS" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +unionfs_load="YES" +.Ed +.Sh DESCRIPTION +The UNIONFS driver is an implementation of a stackable unification filesystem. +.Sh SEE ALSO +.Xr mount_unionfs 8 +.Sh STANDARDS +.Rs +.%T Union mounts in 4.4BSD-Lite +.%A J. S. Pendry +.%A M. K. McKusick +.%R Proceedings of the USENIX Technical Conference on UNIX and Advanced Computing Systems +.%D December 1995 +.Re +.Pp +.Rs +.%T Jails: Confining the omnipotent root +.%A P. H. Kamp +.%A R. N. M. Watson +.%R Proceedings of the Second International System Administration and Networking Conference (SANE2000) +.%D May 2000 +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 5.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +device driver was written by Jan-Simon Pendry for +.Bx 4.4 +and +.An Masanori OZAWA Aq Mt ozawa@ongs.co.jp +reimplemented the handling of the locking for +.Fx 7.0 . +The manual page was written by +.An Gordon Bergling Aq Mt gbe@FreeBSD.org . +.Sh BUGS +Please see the +.Xr mount_unionfs 8 +manual page for a list of bugs regarding the +.Nm +filesystem. diff --git a/static/freebsd/man4/unix.4 b/static/freebsd/man4/unix.4 new file mode 100644 index 00000000..2fdfde22 --- /dev/null +++ b/static/freebsd/man4/unix.4 @@ -0,0 +1,473 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 October 31, 2024 +.Dt UNIX 4 +.Os +.Sh NAME +.Nm unix +.Nd UNIX-domain protocol family +.Sh SYNOPSIS +.In sys/types.h +.In sys/un.h +.Sh DESCRIPTION +The +.Ux Ns -domain +protocol family is a collection of protocols +that provides local (on-machine) interprocess +communication through the normal +.Xr socket 2 +mechanisms. +The +.Ux Ns -domain +family supports the +.Dv SOCK_STREAM , +.Dv SOCK_SEQPACKET , +and +.Dv SOCK_DGRAM +socket types and uses +file system pathnames for addressing. +.Sh ADDRESSING +.Ux Ns -domain +addresses are variable-length file system pathnames of +at most 104 characters. +The include file +.In sys/un.h +defines this address: +.Bd -literal -offset indent +struct sockaddr_un { + u_char sun_len; + u_char sun_family; + char sun_path[104]; +}; +.Ed +.Pp +Binding a name to a +.Ux Ns -domain +socket with +.Xr bind 2 +causes a socket file to be created in the file system. +This file is +.Em not +removed when the socket is closed \(em +.Xr unlink 2 +must be used to remove the file. +.Pp +Prior to binding a socket, +.Xr fchmod 2 +can be used to set the permissions of the socket file. +This avoids the race that would otherwise occur between creation of the file +and a subsequent call to +.Xr chmod 2 . +Once the socket is bound to a file name, the permissions of the file can not be +changed this way. +.Pp +The length of +.Ux Ns -domain +address, required by +.Xr bind 2 +and +.Xr connect 2 , +can be calculated by the macro +.Fn SUN_LEN +defined in +.In sys/un.h . +The +.Va sun_path +field must be terminated by a +.Dv NUL +character to be used with +.Fn SUN_LEN , +but the terminating +.Dv NUL +is +.Em not +part of the address. +.Pp +The +.Ux Ns -domain +protocol family does not support broadcast addressing or any form +of +.Dq wildcard +matching on incoming messages. +All addresses are absolute- or relative-pathnames +of other +.Ux Ns -domain +sockets. +Normal file system access-control mechanisms are also +applied when referencing pathnames; e.g., the destination +of a +.Xr connect 2 +or +.Xr sendto 2 +must be writable. +.Sh CONTROL MESSAGES +The +.Ux Ns -domain +sockets support the communication of +.Ux +file descriptors and process credentials through the use of the +.Va msg_control +field in the +.Fa msg +argument to +.Xr sendmsg 2 +and +.Xr recvmsg 2 . +The items to be passed are described using a +.Vt "struct cmsghdr" +that is defined in the include file +.In sys/socket.h . +.Pp +To send file descriptors, the type of the message is +.Dv SCM_RIGHTS , +and the data portion of the messages is an array of integers +representing the file descriptors to be passed. +The number of descriptors being passed is defined +by the length field of the message; +the length field is the sum of the size of the header +plus the size of the array of file descriptors. +.Pp +The received descriptor is a +.Em duplicate +of the sender's descriptor, as if it were created via +.Li dup(fd) +or +.Li fcntl(fd, F_DUPFD_CLOEXEC, 0) +depending on whether +.Dv MSG_CMSG_CLOEXEC +is passed in the +.Xr recvmsg 2 +call. +Descriptors that are awaiting delivery, or that are +purposely not received, are automatically closed by the system +when the destination socket is closed. +.Pp +Credentials of the sending process can be transmitted explicitly using a +control message of type +.Dv SCM_CREDS +with a data portion of type +.Vt "struct cmsgcred" , +defined in +.In sys/socket.h +as follows: +.Bd -literal +struct cmsgcred { + pid_t cmcred_pid; /* PID of sending process */ + uid_t cmcred_uid; /* real UID of sending process */ + uid_t cmcred_euid; /* effective UID of sending process */ + gid_t cmcred_gid; /* real GID of sending process */ + short cmcred_ngroups; /* number of groups */ + gid_t cmcred_groups[CMGROUP_MAX]; /* groups */ +}; +.Ed +.Pp +The sender should pass a zeroed buffer which will be filled in by the system. +.Pp +The group list is truncated to at most +.Dv CMGROUP_MAX +GIDs. +.Pp +The process ID +.Fa cmcred_pid +should not be looked up (such as via the +.Dv KERN_PROC_PID +sysctl) for making security decisions. +The sending process could have exited and its process ID already been +reused for a new process. +.Sh SOCKET OPTIONS +.Tn UNIX +domain sockets support a number of socket options for the options level +.Dv SOL_LOCAL , +which can be set with +.Xr setsockopt 2 +and tested with +.Xr getsockopt 2 : +.Bl -tag -width ".Dv LOCAL_CREDS_PERSISTENT" +.It Dv LOCAL_CREDS +This option may be enabled on +.Dv SOCK_DGRAM , +.Dv SOCK_SEQPACKET , +or a +.Dv SOCK_STREAM +socket. +This option provides a mechanism for the receiver to +receive the credentials of the process calling +.Xr write 2 , +.Xr send 2 , +.Xr sendto 2 +or +.Xr sendmsg 2 +as a +.Xr recvmsg 2 +control message. +The +.Va msg_control +field in the +.Vt msghdr +structure points to a buffer that contains a +.Vt cmsghdr +structure followed by a variable length +.Vt sockcred +structure, defined in +.In sys/socket.h +as follows: +.Bd -literal +struct sockcred { + uid_t sc_uid; /* real user id */ + uid_t sc_euid; /* effective user id */ + gid_t sc_gid; /* real group id */ + gid_t sc_egid; /* effective group id */ + int sc_ngroups; /* number of supplemental groups */ + gid_t sc_groups[1]; /* variable length */ +}; +.Ed +.Pp +The current implementation truncates the group list to at most +.Dv CMGROUP_MAX +groups. +.Pp +The +.Fn SOCKCREDSIZE +macro computes the size of the +.Vt sockcred +structure for a specified number +of groups. +The +.Vt cmsghdr +fields have the following values: +.Bd -literal +cmsg_len = CMSG_LEN(SOCKCREDSIZE(ngroups)) +cmsg_level = SOL_SOCKET +cmsg_type = SCM_CREDS +.Ed +.Pp +On +.Dv SOCK_STREAM +and +.Dv SOCK_SEQPACKET +sockets credentials are passed only on the first read from a socket, +then the system clears the option on the socket. +.Pp +This option and the above explicit +.Vt "struct cmsgcred" +both use the same value +.Dv SCM_CREDS +but incompatible control messages. +If this option is enabled and the sender attached a +.Dv SCM_CREDS +control message with a +.Vt "struct cmsgcred" , +it will be discarded and a +.Vt "struct sockcred" +will be included. +.Pp +Many setuid programs will +.Xr write 2 +data at least partially controlled by the invoker, +such as error messages. +Therefore, a message accompanied by a particular +.Fa sc_euid +value should not be trusted as being from that user. +.It Dv LOCAL_CREDS_PERSISTENT +This option is similar to +.Dv LOCAL_CREDS , +except that socket credentials are passed on every read from a +.Dv SOCK_STREAM +or +.Dv SOCK_SEQPACKET +socket, instead of just the first read. +Additionally, the +.Va msg_control +field in the +.Vt msghdr +structure points to a buffer that contains a +.Vt cmsghdr +structure followed by a variable length +.Vt sockcred2 +structure, defined in +.In sys/socket.h +as follows: +.Bd -literal +struct sockcred2 { + int sc_version; /* version of this structure */ + pid_t sc_pid; /* PID of sending process */ + uid_t sc_uid; /* real user id */ + uid_t sc_euid; /* effective user id */ + gid_t sc_gid; /* real group id */ + gid_t sc_egid; /* effective group id */ + int sc_ngroups; /* number of supplemental groups */ + gid_t sc_groups[1]; /* variable length */ +}; +.Ed +.Pp +The current version is zero. +.Pp +The +.Vt cmsghdr +fields have the following values: +.Bd -literal +cmsg_len = CMSG_LEN(SOCKCRED2SIZE(ngroups)) +cmsg_level = SOL_SOCKET +cmsg_type = SCM_CREDS2 +.Ed +.Pp +The +.Dv LOCAL_CREDS +and +.Dv LOCAL_CREDS_PERSISTENT +options are mutually exclusive. +.It Dv LOCAL_PEERCRED +Requested via +.Xr getsockopt 2 +on a +.Dv SOCK_STREAM +or +.Dv SOCK_SEQPACKET +socket returns credentials of the remote side. +These will arrive in the form of a filled in +.Vt xucred +structure, defined in +.In sys/ucred.h +as follows: +.Bd -literal +struct xucred { + u_int cr_version; /* structure layout version */ + uid_t cr_uid; /* effective user id */ + short cr_ngroups; /* number of groups */ + gid_t cr_groups[XU_NGROUPS]; /* groups */ + pid_t cr_pid; /* process id of the sending process */ +}; +.Ed +The +.Vt cr_version +fields should be checked against +.Dv XUCRED_VERSION +define. +.Pp +The credentials presented to the server (the +.Xr listen 2 +caller) are those of the client when it called +.Xr connect 2 ; +the credentials presented to the client (the +.Xr connect 2 +caller) are those of the server when it called +.Xr listen 2 . +This mechanism is reliable; there is no way for either party to influence +the credentials presented to its peer except by calling the appropriate +system call (e.g., +.Xr connect 2 +or +.Xr listen 2 ) +under different effective credentials. +.Pp +To reliably obtain peer credentials on a +.Dv SOCK_DGRAM +socket refer to the +.Dv LOCAL_CREDS +socket option. +.El +.Sh BUFFERING +Due to the local nature of the +.Ux Ns -domain +sockets, they do not implement send buffers. +The +.Xr send 2 +and +.Xr write 2 +families of system calls attempt to write data to the receive buffer of the +destination socket. +.Pp +The default buffer sizes for +.Dv SOCK_STREAM +and +.Dv SOCK_SEQPACKET +.Ux Ns -domain +sockets can be configured with +.Va net.local.stream +and +.Va net.local.seqpacket +branches of +.Xr sysctl 3 +MIB respectively. +Note that setting the send buffer size (sendspace) affects only the maximum +write size. +.Pp +The +.Ux Ns -domain +sockets of type +.Dv SOCK_DGRAM +are unreliable and always non-blocking for write operations. +The default receive buffer can be configured with +.Va net.local.dgram.recvspace . +The maximum allowed datagram size is limited by +.Va net.local.dgram.maxdgram . +A +.Dv SOCK_DGRAM +socket that has been bound with +.Xr bind 2 +can have multiple peers connected +at the same time. +The modern +.Fx +implementation will allocate +.Va net.local.dgram.recvspace +sized private buffers in the receive buffer of the bound socket for every +connected socket, preventing a situation when a single writer can exhaust +all of buffer space. +Messages coming from unconnected sends using +.Xr sendto 2 +land on the shared buffer of the receiving socket, which has the same +size limit. +A side effect of the implementation is that it doesn't guarantee +that writes from different senders will arrive at the receiver in the same +chronological order they were sent. +The order is preserved for writes coming through a particular connection. +.Sh SEE ALSO +.Xr connect 2 , +.Xr dup 2 , +.Xr fchmod 2 , +.Xr fcntl 2 , +.Xr getsockopt 2 , +.Xr listen 2 , +.Xr recvmsg 2 , +.Xr sendto 2 , +.Xr setsockopt 2 , +.Xr socket 2 , +.Xr CMSG_DATA 3 , +.Xr intro 4 , +.Xr sysctl 8 +.Rs +.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial" +.%B PS1 +.%N 7 +.Re +.Rs +.%T "An Advanced 4.3 BSD Interprocess Communication Tutorial" +.%B PS1 +.%N 8 +.Re diff --git a/static/freebsd/man4/upgt.4 b/static/freebsd/man4/upgt.4 new file mode 100644 index 00000000..cc5775d2 --- /dev/null +++ b/static/freebsd/man4/upgt.4 @@ -0,0 +1,228 @@ +.\" $OpenBSD: upgt.4,v 1.6 2008/04/17 14:01:22 jmc Exp $ +.\" +.\" Copyright (c) 2007 Marcus Glocker +.\" Copyright (c) 2005-2007 +.\" Damien Bergamini +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" +.\" +.\" Copyright (c) 2006 Theo de Raadt. +.\" Copyright (c) 2006 The DragonFly Project. 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. Neither the name of The DragonFly Project nor the names of its +.\" contributors may be used to endorse or promote products derived +.\" from this software without specific, prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 +.\" COPYRIGHT HOLDERS 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 October 24, 2025 +.Dt UPGT 4 +.Os +.Sh NAME +.Nm upgt +.Nd Conexant/Intersil PrismGT SoftMAC USB IEEE 802.11b/g wireless network +driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ehci" +.Cd "device uhci" +.Cd "device ohci" +.Cd "device usb" +.Cd "device upgt" +.Cd "device wlan" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_upgt_load="YES" +.Ed +.Sh DEPRECATION NOTICE +The +.Nm +driver is slated to be removed in +.Fx 16.0 . +.Sh DESCRIPTION +The +.Nm +driver supports the USB 2.0 Conexant/Intersil PrismGT series wireless +adapters based on the GW3887 chipset. +.Pp +These are the modes the +.Nm +driver can operate in: +.Bl -tag -width "IBSS-masterXX" +.It BSS mode +Also known as +.Em infrastructure +mode, this is used when associating with an access point, through +which all traffic passes. +This mode is the default. +.\" .It IBSS mode +.\" Also known as +.\" .Em IEEE ad-hoc +.\" mode or +.\" .Em peer-to-peer +.\" mode. +.\" This is the standardized method of operating without an access point. +.\" Stations associate with a service set. +.\" However, actual connections between stations are peer-to-peer. +.\" .It Host AP +.\" In this mode the driver acts as an access point (base station) +.\" for other cards. +.It monitor mode +In this mode the driver is able to receive packets without +associating with an access point. +This disables the internal receive filter and enables the card to +capture packets from networks which it wouldn't normally have access to, +or to scan for access points. +.El +.Pp +.Nm +supports software WEP. +Wired Equivalent Privacy (WEP) is the de facto encryption standard +for wireless networks. +It can be typically configured in one of three modes: +no encryption; 40-bit encryption; or 104-bit encryption. +Unfortunately, due to serious weaknesses in WEP protocol +it is strongly recommended that it not be used as the +sole mechanism to secure wireless communication. +WEP is not enabled by default. +.\".Pp +.\"The transmit speed is user-selectable or can be adapted automatically by the +.\"driver depending on the received signal strength and on the number of hardware +.\"transmission retries. +.Pp +The +.Nm +driver can be configured at runtime with +.Xr ifconfig 8 . +.Sh FILES +.\".Pp +.\"These firmware files are not free because Conexant/Intersil refuses +.\"to grant distribution rights. +.\"As a result, even though +.\".Ox +.\"includes the driver, the firmware files cannot be included and +.\"users have to download these files on their own. +This driver requires the +.Nm upgtfw +firmware to be installed before it will work. +The firmware files are not publicly available. +A package of the firmware which can be installed via +.Xr pkg_add 1 +is available: +.Bd -literal -offset indent +http://weongyo.org/project/upgt/upgt-firmware-2.13.1.0.tar.gz +.Ed +.Sh HARDWARE +The +.Nm +driver supports USB 2.0 Conexant/Intersil PrismGT series wireless +adapters based on the GW3887 chipset, among them: +.Pp +.Bl -bullet -compact +.It +Belkin F5D7050 (version 1000) +.It +Cohiba Proto Board +.It +D-Link DWL-G120 Cohiba +.It +FSC Connect2Air E-5400 USB D1700 +.It +Gigaset USB Adapter 54 +.It +Inventel UR045G +.It +Netgear WG111v1 (rev2) +.It +SMC EZ ConnectG SMC2862W-G +.It +Sagem XG703A +.It +Spinnaker DUT +.It +Spinnaker Proto Board +.El +.Sh EXAMPLES +Join an existing BSS network (i.e., connect to an access point): +.Bd -literal -offset indent +ifconfig wlan create wlandev upgt0 inet 192.168.0.20 \e + netmask 0xffffff00 +.Ed +.Pp +Join a specific BSS network with network name +.Dq Li my_net : +.Pp +.Dl "ifconfig wlan create wlandev upgt0 ssid my_net up" +.Pp +Join a specific BSS network with 64-bit WEP encryption: +.Bd -literal -offset indent +ifconfig wlan create wlandev upgt0 ssid my_net \e + wepmode on wepkey 0x1234567890 weptxkey 1 up +.Ed +.Sh SEE ALSO +.Xr arp 4 , +.Xr netintro 4 , +.Xr usb 4 , +.Xr wlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Ox 4.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Marcus Glocker Aq Mt mglocker@openbsd.org . +.Pp +The hardware specification was reverse engineered by the people at +.Pa http://www.prism54.org . +.Sh CAVEATS +The +.Nm +driver just supports the USB 2.0 devices (GW3887 chipset) but not the +USB 1.0 devices containing the NET2280, ISL3880, and ISL3886 chipsets. +Some further efforts would be necessary to add USB 1.0 support to the +driver. diff --git a/static/freebsd/man4/uplcom.4 b/static/freebsd/man4/uplcom.4 new file mode 100644 index 00000000..49c6fb42 --- /dev/null +++ b/static/freebsd/man4/uplcom.4 @@ -0,0 +1,227 @@ +.\" $NetBSD: uplcom.4,v 1.9 2002/02/07 03:15:09 ross Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Lennart Augustsson. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 7, 2021 +.Dt UPLCOM 4 +.Os +.Sh NAME +.Nm uplcom +.Nd USB support for Prolific PL-2303/2303X/2303HX serial adapters driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device usb" +.Cd "device ucom" +.Cd "device uplcom" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +uplcom_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for various serial adapters based on the Prolific +PL-2303, PL-2303X and PL-2303HX USB-to-RS232 Bridge chips. +.Pp +The device is accessed through the +.Xr ucom 4 +driver which makes it behave like a +.Xr tty 4 . +.Sh HARDWARE +The +.Nm +driver supports the following devices and adapters: +.Pp +.Bl -bullet -compact +.It +ADLINK ND-6530 USB-Serial Adapter +.It +Alcatel One Touch 535/735 Phone +.It +Alcor AU9720 USB-RS232 Serial Adapter +.It +AlDiga AL-11U Modem +.It +Alltronix ACM003U00 Modem +.It +Anchor Serial adapter +.It +ATEN UC-232A +.It +ATEN UC-232B +.It +BAFO BF-800 and BF-810 +.It +Belkin F5U257 +.It +BenQ S81 Phone +.It +Corega CG-USBRS232R Serial Adapter +.It +Cressi Edy (Seiko) Diving Computer +.It +ELECOM UC-SGT Serial Adapter +.It +HAL Corporation Crossam2+USB IR commander +.It +Hama USB RS-232 Serial Adapter +.It +Hamlet exaggerate XURS232 +.It +HP LD220 Point-Of-Sale (POS) Display +.It +IOGEAR UC-232A +.It +I/O DATA USB-RSAQ, USB-RSAQ2, USB-RSAQ3 and USB-RSAQ5 +.It +iTegno WM1080A GSM/GFPRS Modem +.It +iTegno WM2080A CDMA Modem +.It +Leadtek 9531 GPS +.It +Micromax 610U Modem +.It +Microsoft Palm 700WX +.It +Mobile Action MA-620 Infrared Adapter +.It +Motorola Cables +.It +Nokia CA-42 Cable +.It +OTI DKU-5 cable +.It +Panasonic TY-TP50P6-S flat screen +.It +PLX CA-42 Phone Cable +.It +PLANEX USB-RS232 URS-03 +.It +Prolific Generic USB-Serial Adapters +.It +Prolific Generic USB-Serial Adapters (HXN) +.It +Prolific Pharos USB-Serial Adapter +.It +Prolific USB-Serial Controller D +.It +RATOC REX-USB60 +.It +Radio Shack USB Serial Cable +.It +Sagem USB-Serial Adapter +.It +Samsung I330 Phone Cradle +.It +Sandberg USB to Serial Link (model number 133-08) +.It +Sanwa KB-USB2 Multimeter cable +.It +Siemens/BenQ EF81, SX1, X65 and X75 Mobile Phones +.It +Sitecom USB-Serial Adapter +.It +SMART Technologies USB-Serial Adapter +.It +Sony QN3 Phone Cable +.It +Sony Ericsson Datapilot +.It +Sony Ericsson DCU-10 and DCU-11 (Susteen) USB Cables +.It +SOURCENEXT KeikaiDenwa 8 (with and without charger) +.It +Speed Dragon USB-Serial Cable +.It +Syntech CPT-8001C Barcode Scanner +.It +TDK UHA6400 and UPA9664 USB-PHS Adapters +.It +TRENDnet USB to Serial Converter (TU-S9) +.It +Tripp-Lite U209-000-R USB-Serial Adapter +.It +UIC HCR331 Magnetic Stripe Card Reader +.It +UIC MSR206 Magnetic Stripe Card Reader +.It +Willcom W-SIM DD PHS terminal.(WS002IN) +.It +YC-Cable USB-Serial Adapter +.It +Zeagle N2iTion3 Diving Computer +.El +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va hw.usb.uplcom.debug +Debug output level, where 0 is debugging disabled and larger values increase +debug message verbosity. +Default is 0. +.El +.Sh FILES +.Bl -tag -width "/dev/ttyU*.init" -compact +.It Pa /dev/ttyU* +for callin ports +.It Pa /dev/ttyU*.init +.It Pa /dev/ttyU*.lock +corresponding callin initial-state and lock-state devices +.Pp +.It Pa /dev/cuaU* +for callout ports +.It Pa /dev/cuaU*.init +.It Pa /dev/cuaU*.lock +corresponding callout initial-state and lock-state devices +.El +.Sh SEE ALSO +.Xr tty 4 , +.Xr ucom 4 , +.Xr usb 4 +.Sh HISTORY +The +.Nm +driver +appeared in +.Nx 1.6 . +This manual page was adopted from +.Nx +by +.An Tom Rhodes Aq Mt trhodes@FreeBSD.org +in April 2002. diff --git a/static/freebsd/man4/ural.4 b/static/freebsd/man4/ural.4 new file mode 100644 index 00000000..53ac1b5d --- /dev/null +++ b/static/freebsd/man4/ural.4 @@ -0,0 +1,163 @@ +.\"- +.\" SPDX-License-Identifier: ISC +.\" +.\" Copyright (c) 2005, 2006 +.\" Damien Bergamini +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd November 10, 2024 +.Dt URAL 4 +.Os +.Sh NAME +.Nm ural +.Nd Ralink RT2500USB IEEE 802.11a/b/g wireless network driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ehci" +.Cd "device uhci" +.Cd "device ohci" +.Cd "device usb" +.Cd "device ural" +.Cd "device wlan" +.Cd "device wlan_amrr" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_ural_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports USB 2.0 wireless adapters based on the RT2500USB chipset. +.Pp +The RT2500USB chipset consists of two integrated chips, a RT2570 MAC/BBP +and a radio transceiver (the model of which depends on the card revision). +.Pp +The RT2522, RT2523, RT2524, RT2525, RT2525e and RT2526 radio transceivers +operate in the 2.4GHz band (802.11b/g) whereas the RT5222 is a dual-band radio +transceiver that can operate in the 2.4GHz and 5.2GHz bands (802.11a). +.Pp +.Nm +supports +.Cm station , +.Cm adhoc , +.Cm hostap , +and +.Cm monitor +mode operation. +Only one virtual interface may be configured at any time. +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports USB 2.0 wireless adapters based on the Ralink Technology +RT2500USB chipset, including: +.Pp +.Bl -column -compact "Atlantis Land A02-PCM-W54" "Bus" +.It Em Card Ta Em Bus +.It "AMIT WL532U" Ta USB +.It "ASUS WL-167g" Ta USB +.It "Belkin F5D7050 v2000" Ta USB +.It "Buffalo WLI-U2-KG54-AI" Ta USB +.It "CNet CWD-854" Ta USB +.It "Compex WLU54G 2A1100" Ta USB +.It "Conceptronic C54RU" Ta USB +.It "D-Link DWL-G122 b1" Ta USB +.It "Dynalink WLG25USB" Ta USB +.It "E-Tech WGUS02" Ta USB +.It "Gigabyte GN-WBKG" Ta USB +.It "Hercules HWGUSB2-54" Ta USB +.It "KCORP LifeStyle KLS-685" Ta USB +.It "Linksys WUSB54G v4" Ta USB +.It "Linksys WUSB54GP v4" Ta USB +.It "MSI MS-6861" Ta USB +.It "MSI MS-6865" Ta USB +.It "MSI MS-6869" Ta USB +.It "NovaTech NV-902" Ta USB +.It "OvisLink Evo-W54USB" Ta USB +.It "SerComm UB801R" Ta USB +.It "SparkLAN WL-685R" Ta USB +.It "Surecom EP-9001-g" Ta USB +.It "Sweex LC100060" Ta USB +.It "Tonze UW-6200C" Ta USB +.It "Zinwell ZWX-G261" Ta USB +.It "Zonet ZEW2500P" Ta USB +.El +.Pp +An up to date list can be found at +.Pa http://ralink.rapla.net/ . +.Sh EXAMPLES +Join an existing BSS network (i.e., connect to an access point): +.Pp +.Dl ifconfig wlan create wlandev ural0 inet 192.0.2.20/24 +.Pp +Join a specific BSS network with network name +.Ar my_net : +.Pp +.Dl ifconfig wlan create wlandev ural0 ssid my_net up +.Pp +Join a specific BSS network with 64-bit WEP encryption: +.Bd -literal -offset indent +ifconfig wlan create wlandev ural0 ssid my_net \e + wepmode on wepkey 0x1234567890 weptxkey 1 up +.Ed +.Pp +Join a specific BSS network with 128-bit WEP encryption: +.Bd -literal -offset indent +ifconfig wlan create wlandev ural0 wlanmode adhoc ssid my_net \e + wepmode on wepkey 0x01020304050607080910111213 weptxkey 1 +.Ed +.Sh DIAGNOSTICS +.Bl -diag +.It "ural%d: device timeout" +The driver will reset the hardware. +This should not happen. +.El +.Sh SEE ALSO +.Xr intro 4 , +.Xr netintro 4 , +.Xr usb 4 , +.Xr wlan 4 , +.Xr wlan_amrr 4 , +.Xr wlan_ccmp 4 , +.Xr wlan_tkip 4 , +.Xr wlan_wep 4 , +.Xr wlan_xauth 4 , +.Xr networking 7 , +.Xr hostapd 8 , +.Xr ifconfig 8 , +.Xr wpa_supplicant 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Ox 3.7 +and +.Fx 6.0 . +.Sh AUTHORS +The original +.Nm +driver was written by +.An Damien Bergamini Aq Mt damien.bergamini@free.fr . +.Sh BUGS +Host AP mode doesn't support client power save. +Clients using power save mode will experience packet loss +.Pq disabling power saving on the client will fix this . diff --git a/static/freebsd/man4/ure.4 b/static/freebsd/man4/ure.4 new file mode 100644 index 00000000..0d14a20f --- /dev/null +++ b/static/freebsd/man4/ure.4 @@ -0,0 +1,138 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2015-2016 Kevin Lo +.\" 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 April 8, 2025 +.Dt URE 4 +.Os +.Sh NAME +.Nm ure +.Nd Realtek RTL8152/RTL8153/RTL8156 USB Ethernet driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device uhci" +.Cd "device ohci" +.Cd "device usb" +.Cd "device miibus" +.Cd "device uether" +.Cd "device ure" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_ure_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports the Realtek USB Ethernet Controller family. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width "10baseT/UTP" +.It Cm autoselect +Enable auto selection of the media type and options. +The user can manually override +the auto selected mode by adding media options to the +.Pa /etc/rc.conf +file. +.It Cm 10baseT/UTP +Set 10Mbps operation. +The +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 100baseTX +Set 100Mbps (Fast Ethernet) operation. +The +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 1000baseTX +Set 1000baseTX (Gigabit Ethernet) operation over twisted pair. +The Realtek gigE chips support 1000Mbps in +.Cm full-duplex +mode only. +.It Cm 2500base-T +Set 2500Base-T operation over twisted pair. +The Realtek 8156/8156B chips support 2500Mbps in +.Cm full-duplex +mode only. +.El +.Pp +The +.Nm +driver supports the following media options for 10/100 operation: +.Bl -tag -width "full-duplex" +.It Cm full-duplex +Force full-duplex operation. +.It Cm half-duplex +Force half-duplex operation. +.El +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports the following USB Ethernet controllers: +.Bl -column "Realtek RTL8168/8169/8110/8211 via rgephy(4)" "10, 100, 1000, and 2500" +.It Model: Ta Speed (Mbps): +.It Realtek RTL8156/RTL8156B/RTL8156BG Ta 10, 100, 1000, and 2500 +.It Realtek RTL8153/RTL8153B Ta 10, 100, and 1000 +.It Realtek RTL8152 Ta 10 and 100 +.It Realtek RTL8168/8169/8110/8211 via rgephy(4) Ta 10, 100, and 1000 +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "ure%d: watchdog timeout" +A packet was queued for transmission and a transmit command was +issued, however the device failed to acknowledge the transmission +before a timeout expired. +.El +.Sh SEE ALSO +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr ifconfig 8 +.Sh AUTHORS +The +.Nm +driver was written by +.An Kevin Lo Aq Mt kevlo@FreeBSD.org . diff --git a/static/freebsd/man4/urio.4 b/static/freebsd/man4/urio.4 new file mode 100644 index 00000000..b7ad71e8 --- /dev/null +++ b/static/freebsd/man4/urio.4 @@ -0,0 +1,128 @@ +.\" Copyright (c) 2000 Dirk-Willem van Gulik +.\" 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 November 22, 2006 +.Dt URIO 4 +.Os +.Sh NAME +.Nm urio +.Nd "USB driver for the Rio MP3 players" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device urio" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +urio_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for Rio MP3 players from Diamond MultiMedia +which attaches to the USB port. +The +.Nm +device must be configured in the kernel, along with +.Em usb +and one of the +.Em uhci +or +.Em ohci +controllers. +.Pp +Subsequently, the +.Pa /dev/urio0 +device can be used by the Rio userland applications. +.Sh HARDWARE +The following devices are supported by the +.Nm +driver: +.Pp +.Bl -bullet -compact +.It +Diamond MultiMedia Rio 500 +.It +Diamond MultiMedia Rio 600 +.It +Diamond MultiMedia Rio 800 +.El +.Sh FILES +.Bl -tag -width /dev/ums0 -compact +.It Pa /dev/urio0 +blocking device node +.El +.Sh EXAMPLES +The following line in the kernel configuration file adds the +.Nm +driver to the kernel: +.Dl device urio +.Pp +To download a song over the +.Tn USB +connection into the Rio using the +.Xr rio_add_song 1 +utility (see the +.Sx SEE ALSO +section): +.Dl rio_add_song /usr/local/MP3/TracyChapman/02-Fast-Car.mp3 +.Sh SEE ALSO +.Xr ohci 4 , +.Xr uhci 4 , +.Xr usb 4 +.Rs +.%T The Rio 500 SourceForge Project Web Page +.%U http://rio500.sourceforge.net/ +.Re +.Pp +The Rio500 tools from SourceForge +are the actual userland tools used to download, +format or rename songs on players. +When compiling these tools, +the following pre-build configuration command will ensure that +.Pa rio_usb.h +is available in the include path +and that the device used is +.Pa /dev/urio0 : +.Bd -literal -offset indent +CFLAGS="-I/usr/include/dev/usb" ./configure \\ + --with-devicepath='/dev' --with-deviceentry='urio0' +.Ed +.\".Sh HISTORY +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Iwasa Kazmi Aq Mt kzmi@ca2.so-net.ne.jp +for +.Fx . +.Pp +This manual page was written by +.An Dirk-Willem van Gulik Aq Mt dirkx@webweaving.org . diff --git a/static/freebsd/man4/urndis.4 b/static/freebsd/man4/urndis.4 new file mode 100644 index 00000000..88e312d6 --- /dev/null +++ b/static/freebsd/man4/urndis.4 @@ -0,0 +1,106 @@ +.\" Copyright (c) 2010 Michael Knudsen +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" - Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" - 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 COPYRIGHT HOLDERS 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 +.\" COPYRIGHT HOLDERS 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. +.\" +.\" $OpenBSD: urndis.4,v 1.15 2013/07/16 16:05:49 schwarze Exp $ +.\" +.Dd November 24, 2015 +.Dt URNDIS 4 +.Os +.Sh NAME +.Nm urndis +.Nd USB Remote NDIS Ethernet device +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ehci" +.Cd "device uhci" +.Cd "device ohci" +.Cd "device xhci" +.Cd "device usb" +.Cd "device miibus" +.Cd "device uether" +.Cd "device urndis" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_urndis_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides Ethernet access over Remote NDIS (RNDIS), +allowing mobile devices such as phones and tablets to provide network access. +It is often referred to as USB tethering, +and in most cases must be explicitly enabled on the device. +.Pp +.Nm +should work with any USB RNDIS devices, +such as those commonly found on Android devices. +It does not support different media types or options. +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports the +.Qq tethering +functionality of many Android devices. +.Sh SEE ALSO +.Xr arp 4 , +.Xr cdce 4 , +.Xr cdceem 4 , +.Xr ipheth 4 , +.Xr netintro 4 , +.Xr usb 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Ox 4.7 . +The first +.Fx +release to include it was +.Fx 9.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Jonathan Armani Aq Mt armani@openbsd.org , +.An Michael Knudsen Aq Mt mk@openbsd.org , +and +.An Fabien Romano Aq Mt fabien@openbsd.org . +It was ported to +.Fx +by +.An Hans Petter Selasky Aq Mt hselasky@FreeBSD.org . diff --git a/static/freebsd/man4/urtw.4 b/static/freebsd/man4/urtw.4 new file mode 100644 index 00000000..7252b8ac --- /dev/null +++ b/static/freebsd/man4/urtw.4 @@ -0,0 +1,125 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2008 Weongyo Jeong +.\" 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 November 10, 2024 +.Dt URTW 4 +.Os +.Sh NAME +.Nm urtw +.Nd Realtek RTL8187B/L USB IEEE 802.11b/g wireless network driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ehci" +.Cd "device uhci" +.Cd "device ohci" +.Cd "device usb" +.Cd "device urtw" +.Cd "device wlan" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, +place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_urtw_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports USB 802.11b/g wireless adapters based on the +Realtek RTL8187B/L. +.Pp +.Nm +supports +.Cm station +and +.Cm monitor +mode operation. +Only one virtual interface may be configured at any time. +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports Realtek RTL8187B/L based wireless network devices, including: +.Pp +.Bl -column -offset indent "Shuttle XPC Accessory PN20" "RTL8225" "USB" -compact +.It Em Card Ta Em Radio Ta Em Bus +.It Belkin F5D7050E Ta RTL8225 Ta USB +.It Linksys WUSB54GCv2 Ta RTL8225 Ta USB +.It Netgear WG111v2 Ta RTL8225 Ta USB +.It Netgear WG111v3 Ta RTL8225 Ta USB +.It Safehome WLG-1500SMA5 Ta RTL8225 Ta USB +.It Shuttle XPC Accessory PN20 Ta RTL8225 Ta USB +.It Sitecom WL168v1 Ta RTL8225 Ta USB +.It Sitecom WL168v4 Ta RTL8225 Ta USB +.It SureCom EP-9001-g(2A) Ta RTL8225 Ta USB +.It TRENDnet TEW-424UB V3.xR Ta RTL8225 Ta USB +.El +.Sh EXAMPLES +Join an existing BSS network (i.e., connect to an access point): +.Pp +.Dl ifconfig wlan create wlandev urtw0 inet 192.0.2.20/24 +.Pp +Join a specific BSS network with network name +.Ar my_net : +.Pp +.Dl ifconfig wlan create wlandev urtw0 ssid my_net up +.Pp +Join a specific BSS network with 64-bit WEP encryption: +.Bd -literal -offset indent +ifconfig wlan create wlandev urtw0 ssid my_net \e + wepmode on wepkey 0x1234567890 weptxkey 1 up +.Ed +.Sh SEE ALSO +.Xr intro 4 , +.Xr netintro 4 , +.Xr usb 4 , +.Xr wlan 4 , +.Xr wlan_ccmp 4 , +.Xr wlan_tkip 4 , +.Xr wlan_wep 4 , +.Xr ifconfig 8 , +.Xr wpa_supplicant 8 +.Rs +.%T Realtek +.%U https://www.realtek.com +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 8.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Weongyo Jeong Aq Mt weongyo@FreeBSD.org . diff --git a/static/freebsd/man4/usb.4 b/static/freebsd/man4/usb.4 new file mode 100644 index 00000000..40cb8675 --- /dev/null +++ b/static/freebsd/man4/usb.4 @@ -0,0 +1,178 @@ +.\" Copyright (c) 1997, 1998 Nick Hibma +.\" Copyright (c) 2008 Hans Petter Selasky. 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 September 7, 2020 +.Dt USB 4 +.Os +.Sh NAME +.Nm usb +.Nd Universal Serial Bus +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device usb" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +usb_load="YES" +.Ed +.Sh USERLAND PROGRAMMING +USB functions can be accessed from userland through the libusb library. +See +.Xr libusb 3 +for more information. +.Sh DESCRIPTION +.Fx +provides machine-independent bus support and drivers for +USB devices in host and device side mode. +.Pp +The +.Nm +driver has three layers: +.Bl -tag -width 6n -offset indent +.It USB Controller (Bus) +.It USB Device +.It USB Driver +.El +.Pp +The controller attaches to a physical bus +like +.Xr pci 4 . +The USB bus attaches to the controller, and the root hub attaches +to the controller. +Any devices attached to the bus will attach to the root hub +or another hub attached to the USB bus. +.Pp +The +.Nm uhub +device will always be present as it is needed for the root hub. +.Sh INTRODUCTION TO USB +The USB is a system where external devices can be connected to a PC. +The most common USB speeds are: +.Bl -tag -width 6n -offset indent +.It Low Speed (1.5 MBit/sec) +.It Full Speed (12 MBit/sec) +.It High Speed (480 MBit/sec) +.It SuperSpeed (5 GBit/sec) +.El +.Pp +Each USB has a USB controller that is the master of the bus. +The physical communication is simplex which means the host controller only +communicates with one USB device at a time. +.Pp +There can be up to 127 devices connected to an USB HUB tree. +The addresses are assigned dynamically by the host when each device is +attached to the bus. +.Pp +Within each device there can be up to 16 endpoints. +Each endpoint is individually addressed and the addresses are static. +Each of these endpoints will communicate in one of four different modes: +.Em control , isochronous , bulk , +or +.Em interrupt . +A device always has at least one endpoint. +This endpoint has address 0 and is a control endpoint and is used to give +commands to and extract basic data, such as descriptors, from the device. +Each endpoint, except the control endpoint, is unidirectional. +.Pp +The endpoints in a device are grouped into interfaces. +An interface is a logical unit within a device, e.g., a compound device with +both a keyboard and a trackball, would present one interface for each. +An interface can sometimes be set into different modes, called alternate +settings, which affects how it operates. +Different alternate settings can have different endpoints within it. +.Pp +A device may operate in different configurations. +Depending on the configuration, the device may present different sets of +endpoints and interfaces. +.Pp +The bus enumeration of the USB bus proceeds in several steps: +.Bl -enum +.It +Any interface specific driver can attach to the device. +.It +If none is found, generic interface class drivers can attach. +.El +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va hw.usb.debug +Debug output level, where 0 is debugging disabled and larger values increase +debug message verbosity. +Default is 0. +.El +.Sh SEE ALSO +The USB specifications can be found at: +.Pp +.D1 Pa https://www.usb.org/documents +.Pp +.Xr libusb 3 , +.Xr aue 4 , +.Xr axe 4 , +.Xr axge 4 , +.Xr cue 4 , +.Xr ehci 4 , +.Xr kue 4 , +.Xr mos 4 , +.Xr ohci 4 , +.Xr pci 4 , +.Xr rue 4 , +.Xr ucom 4 , +.Xr udav 4 , +.Xr uhci 4 , +.Xr uhid 4 , +.Xr ukbd 4 , +.Xr ulpt 4 , +.Xr umass 4 , +.Xr ums 4 , +.Xr uplcom 4 , +.Xr urio 4 , +.Xr uvscom 4 , +.Xr xhci 4 +.Xr usbconfig 8 , +.Xr usbdi 9 +.Sh STANDARDS +The +.Nm +module complies with the USB 3.0 standard. +.Sh HISTORY +The +.Nm +module has been inspired by the +.Nx +USB stack initially written by +.An Lennart Augustsson . +The +.Nm +module was written by +.An Hans Petter Selasky Aq Mt hselasky@FreeBSD.org . diff --git a/static/freebsd/man4/usb_quirk.4 b/static/freebsd/man4/usb_quirk.4 new file mode 100644 index 00000000..15f5a971 --- /dev/null +++ b/static/freebsd/man4/usb_quirk.4 @@ -0,0 +1,267 @@ +.\" +.\" Copyright (c) 2010 AnyWi Technologies +.\" All rights reserved. +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd August 19, 2017 +.Dt USB_QUIRK 4 +.Os +.Sh NAME +.Nm usb_quirk +.Nd USB quirks module +.Sh SYNOPSIS +To compile this module into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device usb" +.Ed +.Pp +Alternatively, to load the module at boot +time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +usb_quirk_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +module provides support for dynamically adding and removing quirks for +USB devices with +.Xr usbconfig 8 . +.Sh General quirks: +.Bl -tag -width Ds +.It UQ_AUDIO_SWAP_LR +swap left and right channels +.It UQ_AU_INP_ASYNC +input is async despite claim of adaptive +.It UQ_AU_NO_FRAC +do not adjust for fractional samples +.It UQ_AU_NO_XU +audio device has broken extension unit +.It UQ_AU_VENDOR_CLASS +audio device uses vendor class to identify itself +.It UQ_AU_SET_SPDIF_CM6206 +audio device needs special programming to enable S/PDIF audio output +.It UQ_BAD_ADC +bad audio spec version number +.It UQ_BAD_AUDIO +device claims audio class, but is not +.It UQ_BROKEN_BIDIR +printer has broken bidir mode +.It UQ_BUS_POWERED +device is bus powered, despite claim +.It UQ_HID_IGNORE +device should be ignored by hid class +.It UQ_KBD_IGNORE +device should be ignored by kbd class +.It UQ_KBD_BOOTPROTO +device should set the boot protocol +.It UQ_UMS_IGNORE +device should be ignored by ums class +.It UQ_MS_BAD_CLASS +does not identify properly +.It UQ_MS_LEADING_BYTE +mouse sends an unknown leading byte +.It UQ_MS_REVZ +mouse has Z-axis reversed +.It UQ_MS_VENDOR_BTN +mouse has buttons in vendor usage page +.It UQ_NO_STRINGS +string descriptors are broken +.It UQ_POWER_CLAIM +hub lies about power status +.It UQ_SPUR_BUT_UP +spurious mouse button up events +.It UQ_SWAP_UNICODE +has some Unicode strings swapped +.It UQ_CFG_INDEX_1 +select configuration index 1 by default +.It UQ_CFG_INDEX_2 +select configuration index 2 by default +.It UQ_CFG_INDEX_3 +select configuration index 3 by default +.It UQ_CFG_INDEX_4 +select configuration index 4 by default +.It UQ_CFG_INDEX_0 +select configuration index 0 by default +.It UQ_ASSUME_CM_OVER_DATA +assume cm over data feature +.It UQ_IGNORE_CDC_CM +ignore cm descriptor +.It UQ_WMT_IGNORE +device should be ignored by wmt driver +.El +.Sh USB Mass Storage quirks: +.Bl -tag -width Ds +.It UQ_MSC_NO_TEST_UNIT_READY +send start/stop instead of TUR +.It UQ_MSC_NO_RS_CLEAR_UA +does not reset Unit Att. +.It UQ_MSC_NO_START_STOP +does not support start/stop +.It UQ_MSC_NO_GETMAXLUN +does not support get max LUN +.It UQ_MSC_NO_INQUIRY +fake generic inq response +.It UQ_MSC_NO_INQUIRY_EVPD +does not support inq EVPD +.It UQ_MSC_NO_SYNC_CACHE +does not support sync cache +.It UQ_MSC_SHUTTLE_INIT +requires Shuttle init sequence +.It UQ_MSC_ALT_IFACE_1 +switch to alternate interface 1 +.It UQ_MSC_FLOPPY_SPEED +does floppy speeds (20kb/s) +.It UQ_MSC_IGNORE_RESIDUE +gets residue wrong +.It UQ_MSC_WRONG_CSWSIG +uses wrong CSW signature +.It UQ_MSC_RBC_PAD_TO_12 +pad RBC requests to 12 bytes +.It UQ_MSC_READ_CAP_OFFBY1 +reports sector count, not max sec. +.It UQ_MSC_FORCE_SHORT_INQ +does not support full inq. +.It UQ_MSC_FORCE_WIRE_BBB +force BBB wire protocol +.It UQ_MSC_FORCE_WIRE_CBI +force CBI wire protocol +.It UQ_MSC_FORCE_WIRE_CBI_I +force CBI with int. wire protocol +.It UQ_MSC_FORCE_PROTO_SCSI +force SCSI command protocol +.It UQ_MSC_FORCE_PROTO_ATAPI +force ATAPI command protocol +.It UQ_MSC_FORCE_PROTO_UFI +force UFI command protocol +.It UQ_MSC_FORCE_PROTO_RBC +force RBC command protocol +.El +.Sh 3G Datacard (u3g) quirks: +.Bl -tag -width Ds +.It UQ_MSC_EJECT_HUAWEI +ejects after Huawei USB command +.It UQ_MSC_EJECT_SIERRA +ejects after Sierra USB command +.It UQ_MSC_EJECT_SCSIEJECT +ejects after SCSI eject command +.Dv 0x1b0000000200 +.It UQ_MSC_EJECT_REZERO +ejects after SCSI rezero command +.Dv 0x010000000000 +.It UQ_MSC_EJECT_ZTESTOR +ejects after ZTE SCSI command +.Dv 0x850101011801010101010000 +.It UQ_MSC_EJECT_CMOTECH +ejects after C-motech SCSI command +.Dv 0xff52444556434847 +.It UQ_MSC_EJECT_WAIT +wait for the device to eject +.It UQ_MSC_EJECT_SAEL_M460 +ejects after Sael USB commands +.It UQ_MSC_EJECT_HUAWEISCSI +ejects after Huawei SCSI command +.Dv 0x11060000000000000000000000000000 +.It UQ_MSC_EJECT_TCT +ejects after TCT SCSI command +.Dv 0x06f504025270 +.It UQ_MSC_DYMO_EJECT +ejects after HID command +.Dv 0x1b5a01 +.El +.Pp +See +.Pa /sys/dev/usb/quirk/usb_quirk.h +or run "usbconfig dump_quirk_names" for the complete list of supported quirks. +.Sh LOADER TUNABLE +The following tunable can be set at the +.Xr loader 8 +prompt before booting the kernel, or stored in +.Xr loader.conf 5 . +.Bl -tag -width indent +.It Va hw.usb.quirk.%d +The value is a string whose format is: +.Bd -literal -offset indent +.Qo VendorId ProductId LowRevision HighRevision UQ_QUIRK,... Qc +.Ed +.Pp +Installs the quirks +.Ic UQ_QUIRK,... +for all USB devices matching +.Ic VendorId +and +.Ic ProductId +which have a hardware revision between and including +.Ic LowRevision +and +.Ic HighRevision . +.Pp +.Ic VendorId , +.Ic ProductId , +.Ic LowRevision +and +.Ic HighRevision +are all 16 bits numbers which can be decimal or hexadecimal based. +.Pp +A maximum of 100 variables +.Ic hw.usb.quirk.0, .1, ..., .99 +can be defined. +.Pp +If a matching entry is found in the kernel's internal quirks table, it +is replaced by the new definition. +.Pp +Else a new entry is created given that the quirk table is not full. +.Pp +The kernel iterates over the +.Ic hw.usb.quirk.N +variables starting at +.Ic N = 0 +and stops at +.Ic N = 99 +or the first non-existing one. +.El +.Sh EXAMPLES +After attaching a +.Nm u3g +device which appears as a USB device on +.Pa ugen0.3 : +.Bd -literal -offset indent +usbconfig -d ugen0.3 add_quirk UQ_MSC_EJECT_WAIT +.Ed +.Pp +Enable a Holtec/Keep Out F85 gaming keyboard on +.Pa ugen1.4 : +.Bd -literal -offset indent +usbconfig -d ugen1.4 add_quirk UQ_KBD_BOOTPROTO +.Ed +.Pp +To install a quirk at boot time, place one or several lines like the +following in +.Xr loader.conf 5 : +.Bd -literal -offset indent +hw.usb.quirk.0="0x04d9 0xfa50 0 0xffff UQ_KBD_IGNORE" +.Ed +.Sh SEE ALSO +.Xr usbconfig 8 +.Sh HISTORY +The +.Nm +module appeared in +.Fx 8.0 , +and was written by +.An Hans Petter Selasky Aq Mt hselasky@FreeBSD.org . +This manual page was written by +.An Nick Hibma Aq Mt n_hibma@FreeBSD.org . diff --git a/static/freebsd/man4/usb_template.4 b/static/freebsd/man4/usb_template.4 new file mode 100644 index 00000000..9e87ccb2 --- /dev/null +++ b/static/freebsd/man4/usb_template.4 @@ -0,0 +1,134 @@ +.\" +.\" Copyright (c) 2008 Hans Petter Selasky. 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 August 7, 2019 +.Dt USB_TEMPLATE 4 +.Os +. +.Sh NAME +. +. +.Nm usb_template +. +.Nd "USB device side templates" +. +. +.Sh SYNOPSIS +To compile this module into the kernel, place the following line in +your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device usb_template" +.Ed +.Pp +To load the module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +usb_template_load="YES" +.Ed +. +.Sh DESCRIPTION +The +.Nm +module implements various USB templates that are needed when +programming an USB device side driver. +. +A USB template consists of an USB device descriptor, one or more USB +configuration descriptors, one or more USB interface descriptors, one +or more USB endpoint descriptors, USB strings and additional USB +descriptors. +. +USB templates are selected using the +.Va hw.usb.template +sysctl and tunable, +or by using the +.Xr usbconfig 8 +.Cm set_template +subcommand. +Changing the +.Va hw.usb.template +sysctl triggers reenumeration by the USB host; changes to other sysctls +may not be visible to the host until reenumeration is performed. +.Pp +Available templates are: +.Bl -column -offset 3n "Value" +.It Em Value Ta Em Description +.It Dv 0 Ta USB Mass Storage, see +.Xr cfumass 4 +.It Dv 1 Ta CDC Ethernet, see +.Xr cdce 4 +.It Dv 2 Ta Media Transfer Protocol (MTP) +.It Dv 3 Ta USB serial port, see +.Xr umodem 4 +.It Dv 4 Ta USB audio +.It Dv 5 Ta USB keyboard +.It Dv 6 Ta USB mouse +.It Dv 7 Ta USB phone +.It Dv 8 Ta CDC Ethernet and serial port +.It Dv 9 Ta USB MIDI +.It Dv 10 Ta CDC Ethernet, serial port, and storage +.It Dv 11 Ta CDC Ethernet Emulation Model, see +.Xr cdceem 4 +.El +. +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va hw.usb.template +Currently selected template. +Set to -1 to make the device disappear from the USB host point of view. +.It Va hw.usb.template_power +USB bus power consumption in mA at 5V. +Must be between 0 and 500. +Setting to 0 marks the device as self-powered. +Defaults to 500mA. +.It Va hw.usb.templates.N +Configuration for template number +.Va N . +.It Va hw.usb.templates.N.vendor_id +16-bit vendor identifier (VID), usually assigned by USB-IF. +.It Va hw.usb.templates.N.product_id +16-bit product identifier (PID). +.It Va hw.usb.templates.N.manufacturer +String containing human-readable manufacturer name. +.It Va hw.usb.templates.N.product +String containing human-readable product name. +.El +.Sh SEE ALSO +.Xr cfumass 4 , +.Xr usb 4 , +.Xr usfs 4 , +.Xr usbconfig 8 +.Sh STANDARDS +The +.Nm +module complies to the USB 1.0, 2.0 and 3.0 standard. +.Sh HISTORY +The +.Nm +module was written by +.An Hans Petter Selasky Aq Mt hselasky@FreeBSD.org . diff --git a/static/freebsd/man4/usbhid.4 b/static/freebsd/man4/usbhid.4 new file mode 100644 index 00000000..0b2e7230 --- /dev/null +++ b/static/freebsd/man4/usbhid.4 @@ -0,0 +1,94 @@ +.\" Copyright (c) 2020 Vladimir Kondratyev +.\" +.\" 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 October 2, 2025 +.Dt USBHID 4 +.Os +.Sh NAME +.Nm usbhid +.Nd USB HID transport driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device usbhid" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +usbhid_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides a interface to USB Human Interface Devices (HIDs). +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va hw.usb.usbhid.enable +Enable +.Nm +and make its priority greater than other USB HID drivers, such as +.Xr ukbd 4 , +.Xr ums 4 , +and +.Xr uhid 4 . +Default is 1. +.El +.Bl -tag -width indent +.It Va hw.usb.usbhid.debug +Debug output level, where 0 is debugging disabled and larger values increase +debug message verbosity. +Default is 0. +Debug messages are printed on the system console and can be viewed using +.Xr dmesg 8 . +.El +.Sh SEE ALSO +.Xr ehci 4 , +.Xr hkbd 4 , +.Xr hms 4 , +.Xr ohci 4 , +.Xr uhci 4 , +.Xr usb 4 , +.Xr xhci 4 , +.Xr usbconfig 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 13.0 . +It was enabled by default in +.Fx 15.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org . diff --git a/static/freebsd/man4/usfs.4 b/static/freebsd/man4/usfs.4 new file mode 100644 index 00000000..98465fc9 --- /dev/null +++ b/static/freebsd/man4/usfs.4 @@ -0,0 +1,74 @@ +.\" +.\" Copyright (c) 2014 Hans Petter Selasky +.\" 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 May 17, 2018 +.Dt USFS 4 +.Os +.Sh NAME +.Nm usfs +.Nd USB device side support for bulk only transport mass storage +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device usb" +.Cd "device usfs" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +usfs_load="YES" +.Ed +.Sh DESCRIPTION +.Bf -symbolic +This driver is obsolete. +Users are advised to use +.Xr cfumass 4 +instead. +.Ef +.Pp +The +.Nm +driver provides support for emulating an USB mass storage device when +the USB stack is activated in USB device side mode (the +.Xr usb_template 4 +module is loaded and the +.Va hw.usb.template +sysctl is set to 0). +.Pp +Upon attach the driver creates a RAM disk which can be read and written. +.Sh SEE ALSO +.Xr cfumass 4 , +.Xr umass 4 , +.Xr usb 4 , +.Xr usb_template 4 +.Sh HISTORY +The +.Nm +driver appeared in +.Fx 8.0 . diff --git a/static/freebsd/man4/uslcom.4 b/static/freebsd/man4/uslcom.4 new file mode 100644 index 00000000..3805cdb4 --- /dev/null +++ b/static/freebsd/man4/uslcom.4 @@ -0,0 +1,229 @@ +.\" $OpenBSD: uslcom.4,v 1.6 2007/10/08 03:10:42 jcs Exp $ +.\" +.\" Copyright (c) 2006 Jonathan Gray +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd December 9, 2019 +.Dt USLCOM 4 +.Os +.Sh NAME +.Nm uslcom +.Nd Silicon Laboratories CP2101/CP2102/CP2103/CP2104/CP2105 based USB serial adapter +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device usb" +.Cd "device ucom" +.Cd "device uslcom" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +uslcom_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver supports Silicon Laboratories CP2101/CP2102/CP2103/CP2104/CP2105 +based USB serial adapters. +.Pp +The datasheets for the CP2101/CP2102/CP2103 list the maximum +supported baud rate as 921,600. +Empirical testing has shown that the rates 1,228,800 and 1,843,200 also work, +at least on some hardware, so the driver allows setting those rates. +.Sh HARDWARE +The following devices should work with the +.Nm +driver: +.Pp +.Bl -bullet -compact +.It +AC-Services CAN, CIS-IBUS, IBUS and OBD interfaces +.It +Aerocomm Radio +.It +AKTACOM ACE-1001 cable +.It +AMBER Wireless AMB2560 +.It +Arkham DS-101 Adapter +.It +Argussoft ISP +.It +Arygon Technologies Mifare RFID Reader +.It +AVIT Research USB-TTL interface +.It +B&G H3000 Data Cable +.It +Balluff RFID reader +.It +Baltech card reader +.It +BEI USB VCP Sensor +.It +Burnside Telecom Desktop Mobile +.It +chip45.com Crumb128 module +.It +Clipsal 5000CT2, 5500PACA, 5500PCU, 560884, 5800PC, C5000CT2 +and L51xx C-Bus Home Automation products +.It +Commander 2 EDGE(GSM) Modem +.It +Cygnal Fasttrax GPS and Debug adapter +.It +DataApex MultiCOM USB to RS232 converter +.It +Degree Controls USB adapter +.It +DekTec DTA Plus VHF/UHF Booster +.It +Dell DW700 GPS Receiver +.It +Digianswer ZigBee/802.15.4 MAC +.It +Dynastream ANT Development kits +.It +Elan USBcount50, USBscope50, USBpulse100 and USBwave12 +.It +ELV USB-I2C interface +.It +EMS C1007 HF RFID controller +.It +Festo CPX-USB and CMSP interfaces +.It +Gemalto Prox-PU/CU contactless card reader +.It +Helicomm IP-Link 1220-DVM +.It +IMS USB-RS422 adapter +.It +Infinity GPS-MIC-1 Radio Monophone +.It +INSYS Modem +.It +IRZ SG-10 and MC35pu GSM/GPRS Modems +.It +Jablotron PC-60B +.It +Kamstrup M-Bus Master MultiPort 250D +and Optical Eye/3 wire utility meter interfaces +.It +Kyocera GPS +.It +Link Instruments MS-019 and MS-028 +Oscilloscope/Logic Analyzer/Pattern Generators +.It +Lipowsky Baby-JTAG, Baby-LIN and HARP-1 +.It +MEI CashFlow SC and Series 2000 cash acceptors +.It +MJS USB-TOSLINK Adapter +.It +MobiData GPRS USB Modems +.It +MSD DashHawk +.It +Multiplex RC adapter +.It +Optris MSpro LT Thermometer +.It +Owen AC4 USB-RS485 converter +.It +Pirelli DP-L10 SIP phone +.It +PLX CA-42 Phone cable +.It +Pololu USB to Serial +.It +Procyon AVS Mind Machine +.It +Renesas RX-Stick for RX610 +.It +Siemens MC60 Cable +.It +Silicon Laboratories generic CP2101/CP2102/CP2103/CP2104/CP2105 chips +.It +Software Bisque Paramount ME +.It +SPORTident BSM7-D USB +.It +Suunto Sports Instrument +.It +Syntech CipherLab USB Barcode Scanner +.It +T-Com TC 300 SIP phone +.It +Tams Master Easy Control +.It +Telegesis ETRX2USB +.It +Timewave HamLinkUSB +.It +Tracient RFID Reader +.It +Track Systems Traqmate +.It +Vaisala USB Instrument cable +.It +VStabi Controller +.It +WAGO 750-923 USB Service Cable +.It +WaveSense Jazz Blood Glucose Meter +.It +WIENER Plein & Baus CML Data Logger, RCM Remote, +and PL512 and MPOD PSUs +.It +WMR RIGblaster Plug&Play and RIGtalk RT1 +.It +Zephyr Bioharness +.El +.Sh FILES +.Bl -tag -width "/dev/ttyU*.init" -compact +.It Pa /dev/ttyU* +for callin ports +.It Pa /dev/ttyU*.init +.It Pa /dev/ttyU*.lock +corresponding callin initial-state and lock-state devices +.Pp +.It Pa /dev/cuaU* +for callout ports +.It Pa /dev/cuaU*.init +.It Pa /dev/cuaU*.lock +corresponding callout initial-state and lock-state devices +.El +.Sh SEE ALSO +.Xr tty 4 , +.Xr ucom 4 , +.Xr usb 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Ox 4.0 . +The first +.Fx +release to include it was +.Fx 7.1 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Jonathan Gray Aq Mt jsg@openbsd.org . diff --git a/static/freebsd/man4/uvisor.4 b/static/freebsd/man4/uvisor.4 new file mode 100644 index 00000000..21170d88 --- /dev/null +++ b/static/freebsd/man4/uvisor.4 @@ -0,0 +1,154 @@ +.\" $NetBSD: uvisor.4,v 1.3 2001/01/23 21:31:10 augustss Exp $ +.\" +.\" Copyright (c) 2000 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Lennart Augustsson. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 26, 2017 +.Dt UVISOR 4 +.Os +.Sh NAME +.Nm uvisor +.Nd "USB support for the PalmOS based PDAs" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device usb" +.Cd "device ucom" +.Cd "device uvisor" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +uvisor_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for USB based PalmOS PDAs, like Handspring +Visor, Palm Mxxx series, and Sony Clie. +.Pp +The device is accessed through the +.Xr ucom 4 +driver which makes it behave like a +.Xr tty 4 . +The device has several ports for different purposes, each of them gets its +own +.Xr ucom 4 +device. +The attach message describes the purpose of each port. +.Pp +The usual Pilot tools can be used to access the attached device on the +HotSync port. +.Sh HARDWARE +The +.Nm +driver supports the following devices: +.Pp +.Bl -bullet -compact +.It +Aceeca Mez1000 RDA +.It +Handspring Treo +.It +Handspring Treo 600 +.It +Handspring Visor +.It +Palm I705 +.It +Palm M125 +.It +Palm M130 +.It +Palm M500 +.It +Palm M505 +.It +Palm M515 +.It +Palm Tungsten T +.It +Palm Tungsten Z +.It +Palm Zire +.It +Palm Zire 31 +.It +Sony Clie 4.0 +.It +Sony Clie 4.1 +.It +Sony Clie 5.0 +.It +Sony Clie PEG-S500C +.It +Sony Clie NX60 +.It +Sony Clie S360 +.It +Sony Clie TJ37 +.El +.Sh FILES +.Bl -tag -width "/dev/ttyU*.init" -compact +.It Pa /dev/ttyU* +for callin ports +.It Pa /dev/ttyU*.init +.It Pa /dev/ttyU*.lock +corresponding callin initial-state and lock-state devices +.Pp +.It Pa /dev/cuaU* +for callout ports +.It Pa /dev/cuaU*.init +.It Pa /dev/cuaU*.lock +corresponding callout initial-state and lock-state devices +.El +.Sh SEE ALSO +.Xr tty 4 , +.Xr ucom 4 , +.Xr usb 4 +.Sh HISTORY +The +.Nm +driver was adopted from +.Nx 1.5 +in August 2002. +This manual page was adopted from +.Nx +by +.An Tom Rhodes Aq Mt trhodes@FreeBSD.org +at that time. +.Sh BUGS +The code to provide multiple +.Xr ucom 4 +instances has not yet been ported from +.Nx . +It is unclear whether this driver works in its +current state. diff --git a/static/freebsd/man4/uvscom.4 b/static/freebsd/man4/uvscom.4 new file mode 100644 index 00000000..cabad068 --- /dev/null +++ b/static/freebsd/man4/uvscom.4 @@ -0,0 +1,107 @@ +.\" $NetBSD: uvscom.4,v 1.1 2002/03/19 15:17:49 augustss Exp $ +.\" +.\" Copyright (c) 2002 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Lennart Augustsson. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 26, 2017 +.Dt UVSCOM 4 +.Os +.Sh NAME +.Nm uvscom +.Nd USB support for SUNTAC Slipper U VS-10U serial adapters driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device usb" +.Cd "device ucom" +.Cd "device uvscom" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +uvscom_load="YES" +.Ed +.Sh HARDWARE +The +.Nm +driver supports the following adapters: +.Pp +.Bl -bullet -compact +.It +DDI Pocket Air H" C@rd +.It +DDI Pocket Air H" C@rd 64 +.It +NTT P-in +.It +NTT P-in m@ster +.El +.Sh DESCRIPTION +The +.Nm +driver provides support for the SUNTAC Slipper U VS-10U chip. +Slipper U is a PC Card to USB converter for data communication card +adapters. +.Pp +The device is accessed through the +.Xr ucom 4 +driver which makes it behave like a +.Xr tty 4 . +.Sh FILES +.Bl -tag -width "/dev/ttyU*.init" -compact +.It Pa /dev/ttyU* +for callin ports +.It Pa /dev/ttyU*.init +.It Pa /dev/ttyU*.lock +corresponding callin initial-state and lock-state devices +.Pp +.It Pa /dev/cuaU* +for callout ports +.It Pa /dev/cuaU*.init +.It Pa /dev/cuaU*.lock +corresponding callout initial-state and lock-state devices +.El +.Sh SEE ALSO +.Xr tty 4 , +.Xr ucom 4 , +.Xr usb 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx +and later in +.Nx 1.6 . +This manual page was adopted from +.Nx +by +.An Tom Rhodes Aq Mt trhodes@FreeBSD.org +in April 2002. diff --git a/static/freebsd/man4/vale.4 b/static/freebsd/man4/vale.4 new file mode 100644 index 00000000..a9f172e1 --- /dev/null +++ b/static/freebsd/man4/vale.4 @@ -0,0 +1,120 @@ +.\" Copyright (c) 2012 Luigi Rizzo, Universita` di Pisa +.\" 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. +.\" +.\" This document is derived in part from the enet man page (enet.4) +.\" distributed with 4.3BSD Unix. +.\" $Id: $ +.\" +.Dd August 30, 2024 +.Dt VALE 4 +.Os +.Sh NAME +.Nm vale +.Nd a very fast Virtual Local Ethernet using the netmap API +.Sh SYNOPSIS +.Cd device netmap +.Sh DESCRIPTION +.Nm +is a feature of the +.Xr netmap 4 +module that implements multiple Virtual switches that can +be used to interconnect netmap clients, including traffic +sources and sinks, packet forwarders, userspace firewalls, +and so on. +.Pp +.Nm +is implemented completely in software, and is extremely fast. +On a modern machine it can move almost 20 Million packets per +second (Mpps) per core with small frames, and about 70 Gbit/s +with 1500 byte frames. +.Sh OPERATION +.Nm +dynamically creates switches and ports as clients connect +to it using the +.Xr netmap 4 +API. +.Pp +.Nm +ports are named +.Pa valeSSS:PPP +where +.Pa vale +is the prefix indicating a VALE switch rather than a standard interface, +.Pa SSS +indicates a specific switch (the colon is a separator), +and +.Pa PPP +indicates a port within the switch. +Both SSS and PPP have the form [0-9a-zA-Z_]+ , the string cannot +exceed IFNAMSIZ characters, and PPP cannot be the name of any +existing OS network interface. +.Pp +See +.Xr netmap 4 +for details on the API. +.Ss LIMITS +.Nm +currently supports up to 254 ports per switch. The maximum +number of switches is provided by the max_bridges sysctl variable. +.Sh SYSCTL VARIABLES +See +.Xr netmap 4 +for a list of sysctl variables that affect +.Nm +bridges. +.Sh EXAMPLES +Create one switch, with a traffic generator connected to one +port, and a netmap-enabled tcpdump instance on another port: +.Bd -literal -offset indent +tcpdump -ni valea:1 & +pkt-gen -i valea:0 -f tx & +.Ed +.Pp +Create two switches, +each connected to two qemu machines on different ports. +.Bd -literal -offset indent +qemu -net nic -net netmap,ifname=vale1:a ... & +qemu -net nic -net netmap,ifname=vale1:b ... & +qemu -net nic -net netmap,ifname=vale2:c ... & +qemu -net nic -net netmap,ifname=vale2:d ... & +.Ed +.Sh SEE ALSO +.Xr netmap 4 , +.Xr valectl 8 +.Pp +Luigi Rizzo, Giuseppe Lettieri: VALE, a switched ethernet for virtual machines, +June 2012, http://info.iet.unipi.it/~luigi/vale/ +.Sh AUTHORS +.An -nosplit +The +.Nm +switch was designed and implemented in 2012 by +.An Luigi Rizzo +and +.An Giuseppe Lettieri +at the Universita` di Pisa. +.Pp +.Nm +was funded by the European Commission within FP7 Projects +CHANGE (257422) and OPENLAB (287581). diff --git a/static/freebsd/man4/veriexec.4 b/static/freebsd/man4/veriexec.4 new file mode 100644 index 00000000..14e4aeae --- /dev/null +++ b/static/freebsd/man4/veriexec.4 @@ -0,0 +1,96 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2024, Juniper Networks, Inc. +.\" +.\" 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 COPYRIGHT HOLDERS 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 COPYRIGHT +.\" OWNER 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 August 1, 2024 +.Dt VERIEXEC 4 +.Os +.Sh NAME +.Nm veriexec +.Nd the veriexec device +.Sh SYNOPSIS +.In dev/veriexec/veriexec_ioctl.h +.Sh DESCRIPTION +The +.Nm +device is used by +.Xr veriexec 8 +to query and modify the state of +.Xr mac_veriexec 4 . +.Pp +Once +.Xr mac_veriexec 4 +is active, only a process which is marked as +.Ql trusted +(normally only +.Xr veriexec 8 ) +is able to more than the +.Dv VERIEXEC_GETSTATE +ioctl. +.Sh IOCTLS +The supported ioctls are described below. +.Bl -tag +.It Dv VERIEXEC_SIGNED_LOAD Vt struct verified_exec_params +Pass file information to +.Xr mac_veriexec 4 . +.Bd -literal +struct verified_exec_params { + unsigned char flags; + char fp_type[VERIEXEC_FPTYPELEN]; /* type of fingerprint */ + char file[MAXPATHLEN]; + unsigned char fingerprint[MAXFINGERPRINTLEN]; +}; +.Ed +.It Dv VERIEXEC_LABEL_LOAD Vt struct verified_exec_label_params +Pass file information and a label to +.Xr mac_veriexec 4 . +.Bd -literal +struct verified_exec_label_params { + struct verified_exec_params params; + char label[MAXLABELLEN]; +}; +.Ed +.It Dv VERIEXEC_ACTIVE +.It Dv VERIEXEC_DEBUG_OFF +.It Dv VERIEXEC_DEBUG_ON Vt int level +.It Dv VERIEXEC_ENFORCE +.It Dv VERIEXEC_GETSTATE +.It Dv VERIEXEC_GETVERSION +.It Dv VERIEXEC_LOCK +.It Dv VERIEXEC_VERIFIED_FILE Vt int fd +Rarely needed. +Tells +.Xr mac_veriexec 4 +that the file associated with +.Va fd +is verified. +.El +.Sh HISTORY +A +.Nm +device first appeared in +.Nx . +It was added to +.Fx 13.1 . diff --git a/static/freebsd/man4/vga.4 b/static/freebsd/man4/vga.4 new file mode 100644 index 00000000..1cfe3414 --- /dev/null +++ b/static/freebsd/man4/vga.4 @@ -0,0 +1,183 @@ +.\" +.\" Copyright (c) 1999 +.\" Kazutaka YOKOTA +.\" 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 as +.\" the first lines of this file unmodified. +.\" 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 ``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 June 30, 1999 +.Dt VGA 4 +.Os +.Sh NAME +.Nm vga +.Nd generic video card interface +.Sh SYNOPSIS +.Cd "options VESA" +.Cd "options VESA_DEBUG=N" +.Cd "options VGA_ALT_SEQACCESS" +.Cd "options VGA_NO_FONT_LOADING" +.Cd "options VGA_NO_MODE_CHANGE" +.Cd "options VGA_SLOW_IOACCESS" +.Cd "options VGA_WIDTH90" +.Cd "device vga" +.Pp +In +.Pa /boot/device.hints : +.Cd hint.vga.0.at="isa" +.Sh DESCRIPTION +The +.Nm +driver is a generic video card driver which provides access to +video cards. +This driver is required for the console driver +.Xr syscons 4 . +The console driver will call the +.Nm +driver to manipulate video hardware (changing video modes, loading font, etc). +.Pp +The +.Nm +driver supports the standard video cards: MDA, CGA, EGA and VGA. +In +addition, the driver can utilize VESA BIOS extensions if the video card +supports them. +VESA support can either be statically included in the kernel +or can be loaded as a separate module. +.Pp +In order to statically link the VESA support to the kernel, the +.Dv VESA +option (see below) must be defined in the kernel configuration file. +.Pp +The +.Nm vesa +module can be dynamically loaded into the kernel using +.Xr kldload 8 . +.Sh DRIVER CONFIGURATION +.Ss Kernel Configuration Options +The following kernel configuration options +(see +.Xr config 8 ) +can be used to control the +.Nm +driver. +These options provide compatibility with certain VGA cards. +.Bl -tag -width MOUSE +.It Dv VGA_ALT_SEQACCESS +You may want to try this option if the mouse pointer is not drawn correctly +or the font does not seem to be loaded properly on the VGA card. +However, it may cause flicker on some systems. +.It Dv VGA_SLOW_IOACCESS +Older VGA cards may require this option for proper operation. +It makes the driver perform byte-wide I/O to VGA registers and +slow down a little. +.It Dv VGA_WIDTH90 +This option enables 90 column modes: 90x25, 90x30, 90x43, 90x50, 90x60. +These modes are not always supported by the video card and the display. +It is highly likely that LCD display cannot work with these modes. +.El +.Pp +The following options add optional features to the driver. +.Bl -tag -width MOUSE +.It Dv VESA +Add VESA BIOS support to the driver. +If the VGA card has the VESA BIOS extension 1.2 or later, +this option will utilize the VESA BIOS service to switch to high +resolution modes. +.It Dv VESA_DEBUG=N +Set the VESA support debug level to +.Fa N . +The default value is zero, which suppresses all debugging output. +.El +.Pp +The following options will remove some features from the +.Nm +driver and save kernel memory. +.Bl -tag -width MOUSE +.It Dv VGA_NO_FONT_LOADING +The +.Nm +driver can load software font to EGA and VGA cards. +This option removes this feature. +Note that if you use this option and +still wish to use the mouse on the console then you must also use the +.Dv SC_ALT_MOUSE_IMAGE +option. +See +.Xr syscons 4 . +.It Dv VGA_NO_MODE_CHANGE +This option prevents the driver from changing video modes. +.El +.\".Sh FILES +.Sh EXAMPLES +Your kernel configuration should normally have: +.Pp +.Dl "device vga" +.Pp +And you need the following line in +.Pa /boot/device.hints . +.Pp +.Dl hint.vga.0.at="isa" +.Pp +The following lines should be included in the kernel configuration file +in order to enable the VESA BIOS Extension support. +.Pp +.Dl "options VESA" +.Dl "device vga" +.Pp +If you do not want VESA support included in the kernel, but +want to use occasionally, do not add the +.Dv VESA +option. +And load the +.Nm vesa +module as desired: +.Pp +.Dl kldload vesa +.\".Sh DIAGNOSTICS +.\".Sh CAVEATS +.\".Sh BUGS +.Sh SEE ALSO +.Xr vgl 3 , +.Xr syscons 4 , +.Xr config 8 , +.Xr kldload 8 , +.Xr kldunload 8 +.Sh STANDARDS +.Rs +.%T "VESA BIOS Extension (VBE)" +.%A Video Electronics Standards Association +.Re +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 3.1 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An S\(/oren Schmidt Aq Mt sos@FreeBSD.org +and +.An Kazutaka Yokota Aq Mt yokota@FreeBSD.org . +This manual page was written by +.An Kazutaka Yokota . diff --git a/static/freebsd/man4/vge.4 b/static/freebsd/man4/vge.4 new file mode 100644 index 00000000..9c0a89a1 --- /dev/null +++ b/static/freebsd/man4/vge.4 @@ -0,0 +1,223 @@ +.\" Copyright (c) 2004 +.\" Bill Paul . 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 Bill Paul. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Bill Paul 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 Bill Paul OR THE VOICES IN HIS HEAD +.\" 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 May 29, 2011 +.Dt VGE 4 +.Os +.Sh NAME +.Nm vge +.Nd "VIA Networking Technologies Velocity Gigabit Ethernet adapter driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device vge" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_vge_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for various NICs and embedded Ethernet interfaces +based on the VIA Technologies VT6120, VT6122, VT6130 and VT6132 Velocity +Family Gigabit Ethernet controller chips. +.Pp +The VT6120/VT6122 is a 33/66MHz 64-bit PCI device which combines a tri-speed +MAC with an integrated 10/100/1000 copper PHY. +(Some older cards use an external PHY.) +The VT6130/VT6132 is the PCI express version of Velocity family. +The MAC supports TCP/IP hardware +checksums (IPv4 only), TCP large send, VLAN tag insertion and stripping, +as well as VLAN filtering, a 64-entry CAM filter and a 64-entry VLAN filter, +64-bit multicast hash filter, 4 separate transmit DMA queues, flow control +and jumbo frames (not on VT6130/VT6132) up to 16K in size. +The Velocity family controllers have a 16K receive FIFO and 48K transmit FIFO. +.Pp +The +.Nm +driver takes advantage of the controller's checksum offload and VLAN +tagging features, as well as the jumbo frame (except VT6130/VT6132) and CAM +filter support. +The CAM filter is used for multicast address filtering to provide +64 perfect multicast address filter support. +If it is necessary for the interface to join more than 64 multicast +groups, the driver will switch over to using the hash filter. +.Pp +The jumbo frame support can be enabled by setting the interface MTU +to any value larger than the default of 1500 bytes, up to a maximum +of 9000 bytes. +Jumbo frames are disabled on the VT6130/VT6132 controllers because the TX +MAC will hang when trying to send a frame that is larger than 4K. +The receive and transmit checksum offload support +can be toggled on and off using the +.Xr ifconfig 8 +utility. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width ".Cm 10baseT/UTP" +.It Cm autoselect +Enable autoselection of the media type and options. +The user can manually override +the autoselected mode by adding media options to +.Xr rc.conf 5 . +.It Cm 10baseT/UTP +Set 10Mbps operation. +The +.Xr ifconfig 8 +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 100baseTX +Set 100Mbps (Fast Ethernet) operation. +The +.Xr ifconfig 8 +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.It Cm 1000baseTX +Set 1000baseTX operation over twisted pair. +The +.Xr ifconfig 8 +.Cm mediaopt +option can also be used to select either +.Cm full-duplex +or +.Cm half-duplex +modes. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width ".Cm full-duplex" +.It Cm full-duplex +Force full duplex operation. +.It Cm half-duplex +Force half duplex operation. +.El +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports VIA Networking VT6120, VT6122, VT6130 and VT6132 based +Gigabit Ethernet adapters including: +.Pp +.Bl -bullet -compact +.It +VIA Networking LAN-on-motherboard Gigabit Ethernet +.It +ZyXEL GN650-T 64-bit PCI Gigabit Ethernet NIC (ZX1701) +.It +ZyXEL GN670-T 32-bit PCI Gigabit Ethernet NIC (ZX1702) +.El +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width "xxxxxx" +.It Va hw.vge.msi_disable +This tunable disables MSI support on the Ethernet hardware. +The default value is 0. +.El +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width "xxxxxx" +.It Va dev.vge.%d.int_holdoff +Maximum number of time to delay interrupts. +The valid range is 0 to 5100 in units of 1us, the default is +150 (150us). +The resolution of timer is about 20us so finer tuning than +20us wouldn't be available. +The interface should be brought down and up again before a change +takes effect. +.It Va dev.vge.%d.rx_coal_pkt +Maximum number of packets to fire Rx completion interrupt. +The valid range is 1 to 255, the default is 64. +.It Va dev.vge.%d.tx_coal_pkt +Maximum number of packets to fire Tx completion interrupt. +The valid range is 1 to 255, the default is 128. +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "vge%d: couldn't map memory" +A fatal initialization error has occurred. +.It "vge%d: couldn't map ports" +A fatal initialization error has occurred. +.It "vge%d: couldn't map interrupt" +A fatal initialization error has occurred. +.It "vge%d: failed to enable memory mapping!" +The driver failed to initialize PCI shared memory mapping. +This might +happen if the card is not in a bus-master slot. +.It "vge%d: watchdog timeout" +The device has stopped responding to the network, or there is a problem with +the network connection (cable). +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr polling 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 5.3 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Bill Paul Aq Mt wpaul@windriver.com . diff --git a/static/freebsd/man4/viapm.4 b/static/freebsd/man4/viapm.4 new file mode 100644 index 00000000..becb4f6a --- /dev/null +++ b/static/freebsd/man4/viapm.4 @@ -0,0 +1,70 @@ +.\" Copyright (c) 2002 Nicolas Souchu +.\" 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 April 20, 2002 +.Dt VIAPM 4 +.Os +.Sh NAME +.Nm viapm +.Nd VIA chipsets Power Management controller driver +.Sh SYNOPSIS +.Cd device iicbb +.Cd device iicbus +.Cd device iicsmb +.Cd device smbus +.Cd device smb +.Cd device viapm +.Sh DESCRIPTION +This driver provides access to the +.Tn "VIA chipset Power Management Unit" +family. +They are +VT82C586B, VT82C596A, VT82C596B, VT82C686A and VT8233. +.Pp +The embedded controller of the VIA chipset may give you access +to the monitoring facilities of your mainboard. +.Pp +The 586B support is made by software whereas other controllers support +the SMBus protocol by hardware. +See +.Xr smb 4 +for writing user code to fetch voltages, temperature and so on from the +monitoring chip of your mainboard. +.Sh SEE ALSO +.Xr iicbb 4 , +.Xr iicbus 4 , +.Xr iicsmb 4 , +.Xr smb 4 , +.Xr smbus 4 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 4.5 . +.Sh AUTHORS +This +manual page was written by +.An Nicolas Souchu Aq Mt nsouch@FreeBSD.org . +.Sh BUGS +Only polling mode is supported. diff --git a/static/freebsd/man4/viawd.4 b/static/freebsd/man4/viawd.4 new file mode 100644 index 00000000..730c8afd --- /dev/null +++ b/static/freebsd/man4/viawd.4 @@ -0,0 +1,77 @@ +.\"- +.\" Copyright (c) 2011 Fabien Thomas +.\" 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 December 7, 2011 +.Dt VIAWD 4 +.Os +.Sh NAME +.Nm viawd +.Nd device driver for VIA south bridge watchdog timer +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device viawd" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +viawd_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides +.Xr watchdog 4 +support for the watchdog interrupt timer present on +VIA south bridge chipset (VT8251, CX700, VX800, VX855, VX900). +.Pp +The VIA south bridge have a built-in watchdog timer, +which can be enabled and disabled by user's program and set between +1 to 1023 seconds. +.Pp +The +.Nm +driver when unloaded with running watchdog will reschedule the watchdog +to 5 minutes. +.Sh SEE ALSO +.Xr watchdog 4 , +.Xr watchdog 8 , +.Xr watchdogd 8 , +.Xr watchdog 9 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 10.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver and this manual page were written by +.An Fabien Thomas Aq Mt fabient@FreeBSD.org . diff --git a/static/freebsd/man4/virtio.4 b/static/freebsd/man4/virtio.4 new file mode 100644 index 00000000..6af6300b --- /dev/null +++ b/static/freebsd/man4/virtio.4 @@ -0,0 +1,134 @@ +.\" Copyright (c) 2011 Bryan Venteicher +.\" 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 April 4, 2026 +.Dt VIRTIO 4 +.Os +.Sh NAME +.Nm virtio +.Nd VirtIO Device Support +.Sh SYNOPSIS +To compile VirtIO device support into the kernel, place the following lines +in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device virtio" +.Cd "device virtio_pci" +.Ed +.Pp +Alternatively, to load VirtIO support as modules at boot time, place the +following lines in +.Xr loader.conf 5 : +.Bd -literal -offset indent +virtio_load="YES" +virtio_pci_load="YES" +.Ed +.Sh DESCRIPTION +VirtIO is a specification for para-virtualized I/O in a virtual machine (VM). +Traditionally, the hypervisor emulated real devices such as an Ethernet +interface or disk controller to provide the VM with I/O. +This emulation is often inefficient. +.Pp +VirtIO defines an interface for efficient I/O between the hypervisor and VM. +The +.Nm +module provides a shared memory transport called a virtqueue. +The +.Sy virtio_pci +device driver represents an emulated PCI device that the hypervisor makes +available to the VM. +This device provides the probing, configuration, and +interrupt notifications needed to interact with the hypervisor. +.Fx +supports the following VirtIO devices: +.Bl -hang -offset indent -width xxxxxxxx +.It Sy Ethernet +An emulated Ethernet device is provided by the +.Xr vtnet 4 +device driver. +.It Sy Block +An emulated disk controller is provided by the +.Xr virtio_blk 4 +device driver. +.It Sy Console +Provided by the +.Xr virtio_console 4 +driver. +.It Sy Entropy +Provided by the +.Xr virtio_random 4 +driver. +.It Sy Balloon +A pseudo-device to allow the VM to release memory back to the hypervisor is +provided by the +.Xr virtio_balloon 4 +device driver. +.It Sy GPU +Graphics support is provided by the +.Xr virtio_gpu 4 +device driver. +.It Sy SCSI +An emulated SCSI HBA is provided by the +.Xr virtio_scsi 4 +device driver. +.El +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width "hw.virtio.pci.transitional" +.It Va hw.virtio.pci.disable_msix +If set to 1, disables MSI-X. +The default value is 0. +.It Va hw.virtio.pci.transitional +For a transitional +.Nm +device, this tunable specifies whether to negotiate +modern mode and use the modern +.Nm +driver +.Pq 1 +or to negotiate legacy mode and +use the legacy +.Nm +driver +.Pq 0 . +The default value is 1. +.El +.Sh SEE ALSO +.Xr virtio_balloon 4 , +.Xr virtio_blk 4 , +.Xr virtio_console 4 , +.Xr virtio_gpu 4 , +.Xr virtio_random 4 , +.Xr virtio_scsi 4 , +.Xr vtnet 4 +.Sh HISTORY +Support for VirtIO first appeared in +.Fx 9.0 . +.Sh AUTHORS +.An -nosplit +.Fx +support for VirtIO was first added by +.An Bryan Venteicher Aq Mt bryanv@FreeBSD.org . diff --git a/static/freebsd/man4/virtio_balloon.4 b/static/freebsd/man4/virtio_balloon.4 new file mode 100644 index 00000000..1d680435 --- /dev/null +++ b/static/freebsd/man4/virtio_balloon.4 @@ -0,0 +1,62 @@ +.\" Copyright (c) 2011 Bryan Venteicher +.\" 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 January 22, 2012 +.Dt VIRTIO_BALLOON 4 +.Os +.Sh NAME +.Nm virtio_balloon +.Nd VirtIO Memory Balloon driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device virtio_balloon" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +virtio_balloon_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +device driver provides support for VirtIO memory balloon devices. +.Pp +The memory balloon allows the guest to, at the request of the +hypervisor, return memory allocated to the hypervisor so it can +be made available to other guests. +The hypervisor can later signal the balloon to return the memory. +.Sh SEE ALSO +.Xr virtio 4 +.Sh HISTORY +The +.Nm +driver was written by +.An Bryan Venteicher Aq Mt bryanv@FreeBSD.org . +It first appeared in +.Fx 9.0 . diff --git a/static/freebsd/man4/virtio_blk.4 b/static/freebsd/man4/virtio_blk.4 new file mode 100644 index 00000000..64be2164 --- /dev/null +++ b/static/freebsd/man4/virtio_blk.4 @@ -0,0 +1,90 @@ +.\" Copyright (c) 2011 Bryan Venteicher +.\" 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 2, 2013 +.Dt VIRTIO_BLK 4 +.Os +.Sh NAME +.Nm virtio_blk +.Nd VirtIO Block driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device virtio_blk" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +virtio_blk_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +device driver provides support for VirtIO block devices. +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width indent +.It Va hw.vtblk.no_ident +.It Va hw.vtblk. Ns Ar X Ns Va .no_ident +.Pp +These tunables disable retrieving the device identification string +from the hypervisor either globally or per-device. +The default value is 0. +.It Va hw.vtblk.writecache_mode +.It Va hw.vtblk. Ns Ar X Ns Va .writecache_mode +.Pp +These tunables determine the write cache mode globally or per-device. +The mode can changed only if the ConfigWCE feature is negotiated. +Set to 0 for writethrough mode, 1 for writeback mode, and -1 to leave +it as-is. +The default value is to leave as-is. +.El +.Sh SYSCTL VARIABLES +The following variables are available as +.Xr sysctl 8 +variables. +.Bl -tag -width indent +.It Va dev.vtblk. Ns Ar X Ns Va .writecache_mode +.Pp +The write cache mode of the device can be either writethrough (0) or +writeback (1). +If the ConfigWCE feature is negotiated, the write cache mode can +be toggled between writethrough and writeback. +.El +.Sh SEE ALSO +.Xr virtio 4 +.Sh HISTORY +The +.Nm +driver was written by +.An Bryan Venteicher Aq Mt bryanv@FreeBSD.org . +It first appeared in +.Fx 9.0 . diff --git a/static/freebsd/man4/virtio_console.4 b/static/freebsd/man4/virtio_console.4 new file mode 100644 index 00000000..901c8bfc --- /dev/null +++ b/static/freebsd/man4/virtio_console.4 @@ -0,0 +1,65 @@ +.\" Copyright (c) 2014 Bryan Venteicher +.\" 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 October 22, 2014 +.Dt VIRTIO_CONSOLE 4 +.Os +.Sh NAME +.Nm virtio_console +.Nd VirtIO Console driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device virtio_console" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +virtio_console_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +device driver provides support for VirtIO console devices. +.Pp +The console device may have one or more ports. +Each port is similar to a simple serial interface, and +each port is accessible through +.Xr tty 4 . +.Sh FILES +.Bl -tag -width ".Pa /dev/ttyV?.??" -compact +.It Pa /dev/ttyV?.?? +.El +.Sh SEE ALSO +.Xr tty 4 , +.Xr virtio 4 +.Sh HISTORY +The +.Nm +driver was written by +.An Bryan Venteicher Aq bryanv@FreeBSD.org . diff --git a/static/freebsd/man4/virtio_gpu.4 b/static/freebsd/man4/virtio_gpu.4 new file mode 100644 index 00000000..f8d48faa --- /dev/null +++ b/static/freebsd/man4/virtio_gpu.4 @@ -0,0 +1,54 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2014 Bryan Venteicher +.\" All rights reserved. +.\" Copyright (c) 2023 Arm Ltd +.\" +.\" 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 August 14, 2023 +.Dt VIRTIO_GPU 4 +.Os +.Sh NAME +.Nm virtio_gpu +.Nd VirtIO GPU driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device virtio_gpu" +.Ed +.Sh DESCRIPTION +The +.Nm +device driver provides support for VirtIO gpu devices to create a +.Xr vt 4 +console. +.Sh SEE ALSO +.Xr virtio 4 , +.Xr vt 4 +.Sh HISTORY +The +.Nm +driver first appeared in FreeBSD 14.0. diff --git a/static/freebsd/man4/virtio_random.4 b/static/freebsd/man4/virtio_random.4 new file mode 100644 index 00000000..74852c27 --- /dev/null +++ b/static/freebsd/man4/virtio_random.4 @@ -0,0 +1,59 @@ +.\" Copyright (c) 2013 Bryan Venteicher +.\" 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 December 28, 2013 +.Dt VIRTIO_RANDOM 4 +.Os +.Sh NAME +.Nm virtio_random +.Nd VirtIO Entropy driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device virtio_random" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +virtio_random_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +device driver provides support for VirtIO entropy devices. +.Pp +The entropy device supplies high-quality randomness from the +hypervisor to the guest. +.Sh SEE ALSO +.Xr random 4 , +.Xr virtio 4 +.Sh HISTORY +The +.Nm +driver was written by +.An Bryan Venteicher Aq Mt bryanv@FreeBSD.org . diff --git a/static/freebsd/man4/virtio_scsi.4 b/static/freebsd/man4/virtio_scsi.4 new file mode 100644 index 00000000..0e62cd8f --- /dev/null +++ b/static/freebsd/man4/virtio_scsi.4 @@ -0,0 +1,91 @@ +.\" Copyright (c) 2012 Bryan Venteicher +.\" 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 June 24, 2012 +.Dt VIRTIO_SCSI 4 +.Os +.Sh NAME +.Nm virtio_scsi +.Nd VirtIO SCSI driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device virtio_scsi" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +virtio_scsi_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +device driver provides support for VirtIO SCSI devices. +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width "xxxxxx" +.It Va hw.vtscsi.bus_reset_disable +In the initial QEMU release with VirtIO SCSI support, in-flight +operations were not aborted when stopping the device, rendering +bus reset ineffective. +This tunable disables attempts to issue reset bus commands. +The default value is 1. +.El +.Sh DEBUGGING +To enable debugging prints from the +.Nm +driver, set the +.Bd -literal -offset indent +hw.vtscsi.X.debug_level +.Ed +.Pp +variable, where X is the adapter number, either in +.Xr loader.conf 5 +or via +.Xr sysctl 8 . +The following bits have the described effects: +.Bl -tag -width 6n -offset indent +.It 0x01 +Enable informational prints. +.It 0x02 +Enable prints for driver errors. +.It 0x04 +Enable tracing prints. +.El +.Sh SEE ALSO +.Xr virtio 4 +.Sh HISTORY +The +.Nm +driver was written by +.An Bryan Venteicher Aq Mt bryanv@FreeBSD.org . +It first appeared in +.Fx 10.0 . diff --git a/static/freebsd/man4/vkbd.4 b/static/freebsd/man4/vkbd.4 new file mode 100644 index 00000000..b6487ee5 --- /dev/null +++ b/static/freebsd/man4/vkbd.4 @@ -0,0 +1,153 @@ +.\" $Id: vkbd.4,v 1.4 2004/11/16 16:49:39 max Exp $ +.\" +.Dd August 12, 2004 +.Dt VKBD 4 +.Os +.Sh NAME +.Nm vkbd +.Nd the virtual AT keyboard interface +.Sh SYNOPSIS +.Cd "device vkbd" +.Sh DESCRIPTION +The +.Nm +interface is a software loopback mechanism that can be loosely +described as the virtual AT keyboard analog of the +.Xr pty 4 , +that is, +.Nm +does for virtual AT keyboards what the +.Xr pty 4 +driver does for terminals. +.Pp +The +.Nm +driver, like the +.Xr pty 4 +driver, provides two interfaces: a keyboard interface like the usual +facility it is simulating (a virtual AT keyboard in the case of +.Nm , +or a terminal for +.Xr pty 4 ) , +and a character-special device +.Dq control +interface. +.Pp +The virtual AT keyboards are named +.Pa vkbd0 , vkbd1 , +etc., one for each control device that has been opened. +.Pp +The +.Nm +interface permits opens on the special control device +.Pa /dev/vkbdctl . +When this device is opened, +.Nm +will return a handle for the lowest unused +.Pa vkbdctl +device (use +.Xr devname 3 +to determine which). +.Pp +Each virtual AT keyboard supports the usual keyboard interface +.Xr ioctl 2 Ns s , +and thus can be used with +.Xr kbdcontrol 1 +like any other keyboard. +The control device supports exactly the same +.Xr ioctl 2 Ns s +as the virtual AT keyboard device. +Writing AT scan codes to the control device generates an input on +the virtual AT keyboard, as if the +(non-existent) +hardware had just received it. +.Pp +The virtual AT keyboard control device, normally +.Pa /dev/vkbdctl Ns Aq Ar N , +is exclusive-open +(it cannot be opened if it is already open) +and is restricted to the super-user. +A +.Xr read 2 +call will return the virtual AT keyboard status structure +(defined in +.In dev/vkbd/vkbd_var.h ) +if one is available; +if not, it will either block until one is or return +.Er EWOULDBLOCK , +depending on whether non-blocking I/O has been enabled. +.Pp +A +.Xr write 2 +call passes AT scan codes to be +.Dq received +from the virtual AT keyboard. +Each AT scan code must be passed as +.Vt "unsigned int" . +Although AT scan codes must be passes as +.Vt "unsigned int" Ns s , +the size of the buffer passed to +.Xr write 2 +still should be in bytes, i.e., +.Bd -literal -offset indent +static unsigned int codes[] = +{ +/* Make Break */ + 0x1e, 0x9e +}; + +int +main(void) +{ + int fd, len; + + fd = open("/dev/vkbdctl0", O_RDWR); + if (fd < 0) + err(1, "open"); + + /* Note sizeof(codes) - not 2! */ + len = write(fd, codes, sizeof(codes)); + if (len < 0) + err(1, "write"); + + close(fd); + + return (0); +} +.Ed +.Pp +Write will block if there is not enough space in the input queue. +.Pp +The control device also supports +.Xr select 2 +for read and write. +.Pp +On the last close of the control device, the virtual AT keyboard is removed. +All queued scan codes are thrown away. +.Sh SEE ALSO +.Xr kbdcontrol 1 , +.Xr atkbdc 4 , +.Xr psm 4 , +.Xr syscons 4 , +.Xr vt 4 +.Sh HISTORY +The +.Nm +module was implemented in +.Fx 6.0 . +.Sh AUTHORS +.An Maksim Yevmenkin Aq Mt m_evmenkin@yahoo.com +.Sh CAVEATS +The +.Nm +interface is a software loopback mechanism, and, thus +.Xr ddb 4 +will not work with it. +Current implementation of the +.Xr syscons 4 +driver can accept input from only one keyboard, even if it is virtual. +Thus it is not possible to have both wired and virtual keyboard to be active +at the same time. +It is, however, in principal possible to obtain AT scan +codes from the different sources and write them into the same virtual keyboard. +The virtual keyboard state synchronization is the user's responsibility. diff --git a/static/freebsd/man4/vlan.4 b/static/freebsd/man4/vlan.4 new file mode 100644 index 00000000..25405172 --- /dev/null +++ b/static/freebsd/man4/vlan.4 @@ -0,0 +1,197 @@ +.\" +.\" Copyright (c) 2001 Yar Tikhiy +.\" 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 December 26, 2020 +.Dt VLAN 4 +.Os +.Sh NAME +.Nm vlan +.Nd "IEEE 802.1Q VLAN network interface" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device vlan" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_vlan_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver demultiplexes frames tagged according to +the IEEE 802.1Q standard into logical +.Nm +network interfaces, which allows routing/bridging between +multiple VLANs through a single switch trunk port. +.Pp +Each +.Nm +interface is created at runtime using interface cloning. +This is +most easily done with the +.Xr ifconfig 8 +.Cm create +command or using the +.Va cloned_interfaces +variable in +.Xr rc.conf 5 . +.Pp +To function, a +.Nm +interface must be assigned a parent interface and +numeric VLAN tag using +.Xr ifconfig 8 . +A single parent can be assigned to multiple +.Nm +interfaces provided they have different tags. +The parent interface is likely to be an Ethernet card connected +to a properly configured switch port. +The VLAN tag should match one of those set up in the switched +network. +.Pp +.Nm +initially assumes the same minimum length for tagged and untagged frames. +This mode is selected by setting the +.Xr sysctl 8 +variable +.Va net.link.vlan.soft_pad +to 0 +.Pq default . +However, there are network devices that fail to adjust frame length +when it falls below the allowed minimum due to untagging. +Such devices should be able to interoperate with +.Nm +after changing the value of +.Va net.link.vlan.soft_pad +to 1. +In the latter mode, +.Nm +will pad short frames before tagging them +so that their length is not less than the minimum value +after untagging by the non-compliant devices. +.Sh HARDWARE +The +.Nm +driver supports efficient operation over parent interfaces that can provide +help in processing VLANs. +Such interfaces are automatically recognized by their capabilities. +Depending on the level of sophistication found in a physical +interface, it may do full VLAN processing or just be able to +receive and transmit long frames (up to 1522 bytes including an Ethernet +header and FCS). +The capabilities may be user-controlled by the respective parameters to +.Xr ifconfig 8 , +.Cm vlanhwtag , +and +.Cm vlanmtu . +However, a physical interface is not obliged to react to them: +It may have either capability enabled permanently without +a way to turn it off. +The whole issue is very specific to a particular device and its driver. +.Pp +At present, these devices are capable of full VLAN processing +in hardware: +.Xr ae 4 , +.Xr age 4 , +.Xr alc 4 , +.Xr ale 4 , +.Xr bce 4 , +.Xr bge 4 , +.Xr bxe 4 , +.Xr cxgb 4 , +.Xr cxgbe 4 , +.Xr em 4 , +.Xr igb 4 , +.Xr ix 4 , +.Xr jme 4 , +.Xr liquidio 4 , +.Xr msk 4 , +.Xr mxge 4 , +.Xr nge 4 , +.Xr re 4 , +.Xr sge 4 , +.Xr stge 4 , +.Xr ti 4 , +and +.Xr vge 4 . +.Pp +Other Ethernet interfaces can run VLANs using software emulation in the +.Nm +driver. +However, some lack the capability +of transmitting and receiving long frames. +Assigning such an interface as the parent to +.Nm +will result in a reduced MTU on the corresponding +.Nm +interfaces. +In the modern Internet, this is likely to cause +.Xr tcp 4 +connectivity problems due to massive, inadequate +.Xr icmp 4 +filtering that breaks the Path MTU Discovery mechanism. +.Pp +These interfaces natively support long frames for +.Nm : +.Xr axe 4 , +.Xr bfe 4 , +.Xr cas 4 , +.Xr dc 4 , +.Xr et 4 , +.Xr fwe 4 , +.Xr fxp 4 , +.Xr gem 4 , +.Xr le 4 , +.Xr nfe 4 , +.Xr rl 4 , +.Xr sis 4 , +.Xr sk 4 , +.Xr ste 4 , +.Xr vr 4 , +.Xr vte 4 , +and +.Xr xl 4 . +.Pp +The +.Nm +driver automatically recognizes devices that natively support long frames +for +.Nm +use and calculates the appropriate frame MTU based on the +capabilities of the parent interface. +Some other interfaces not listed above may handle long frames, +but they do not advertise this ability. +The MTU setting on +.Nm +can be corrected manually if used in conjunction with such a parent interface. +.Sh SEE ALSO +.Xr ifconfig 8 , +.Xr sysctl 8 diff --git a/static/freebsd/man4/vmci.4 b/static/freebsd/man4/vmci.4 new file mode 100644 index 00000000..8feea98a --- /dev/null +++ b/static/freebsd/man4/vmci.4 @@ -0,0 +1,70 @@ +.\" Copyright (c) 2018 VMware, Inc. +.\" +.\" SPDX-License-Identifier: (BSD-2-Clause OR GPL-2.0) +.Dd February 10, 2018 +.Dt VMCI 4 +.Os +.Sh NAME +.Nm vmci +.Nd VMware Virtual Machine Communication Interface +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device vmci" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_vmci_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the VMware Virtual Machine Communication Interface +(VMCI) in virtual machines by VMware. +.Pp +VMCI allows virtual machines to communicate with host kernel modules and the +VMware hypervisors. +User level applications in a virtual machine can use VMCI through vSockets +(also known as VMCI Sockets and not included in this kernel module), a socket +address family designed to be compatible with UDP and TCP at the interface +level. +Today, VMCI and vSockets are used by various VMware Tools components inside +the guest for zero-config, network-less access to VMware host services. +In addition to this, VMware's users are using vSockets for various +applications, where network access of the virtual machine is restricted +or non-existent. +Examples of this are VMs communicating with device proxies for proprietary +hardware running as host applications and automated testing of applications +running within virtual machines. +.Pp +In a virtual machine, VMCI is exposed as a regular PCI device. +The primary communication mechanisms supported are a point-to-point +bidirectional transport based on a pair of memory-mapped queues, and +asynchronous notifications in the form of datagrams and doorbells. +These features are available to kernel level components such as vSockets +through the VMCI kernel API. +In addition to this, the VMCI kernel API provides support for receiving +events related to the state of the VMCI communication channels, and the +virtual machine itself. +.Sh SEE ALSO +.Xr socket 2 , +.Xr pci 9 +.Rs +.%T "VMware vSockets Documentation" +.%U https://www.vmware.com/support/developer/vmci-sdk/ +.Re +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 12.0 . +.Sh AUTHORS +The +.Nm +driver and man page were written by +.An Vishnu Dasa Aq Mt vdasahar@gmail.com . diff --git a/static/freebsd/man4/vmd.4 b/static/freebsd/man4/vmd.4 new file mode 100644 index 00000000..590a368f --- /dev/null +++ b/static/freebsd/man4/vmd.4 @@ -0,0 +1,83 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2021 Alexander Motin +.\" Copyright 2019 Cisco Systems, Inc. +.\" +.\" 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 October 6, 2022 +.Dt VMD 4 +.Os +.Sh NAME +.Nm vmd +.Nd Intel Volume Management Device driver +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device vmd" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the following +line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +vmd_load="YES" +.Ed +.Sh DESCRIPTION +This driver attaches to Intel VMD devices, representing them as PCI-to-PCI +bridges and providing access to children PCI devices via new PCI domains. +Intel VMD is used by Intel's VROC (Virtual RAID on chip) to manage NVMe +drives. +.Sh LOADER TUNABLES +The following tunables are settable via +.Xr loader 8 +or +.Xr sysctl 8 : +.Bl -tag -width indent +.It Va hw.vmd.bypass_msi +By default all VMD devices remap children MSI/MSI-X interrupts into their +own. It creates additional isolation, but also complicates things due to +sharing, etc. Fortunately some VMD devices can bypass the remapping. +Defaults to 1. +.It Va hw.vmd.max_msi +Limits number of Message Signaled Interrupt (MSI) vectors allowed to each +child device. +VMD can't distinguish MSI vectors of the same device, so there are no +benefits to have more than one, unless it is required by specific device +driver. +Defaults to 1. +.It Va hw.vmd.max_msix +Limits number of Extended Message Signaled Interrupt (MSI-X) vectors +allowed to each child device. +VMD has limited number of interrupt vectors to map children interrupts into, +so to avoid/reduce sharing children devices/drivers need to be constrained. +Defaults to 3. +.El +.Sh SEE ALSO +.Xr graid 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 13.0 . diff --git a/static/freebsd/man4/vmgenc.4 b/static/freebsd/man4/vmgenc.4 new file mode 100644 index 00000000..1938e7f7 --- /dev/null +++ b/static/freebsd/man4/vmgenc.4 @@ -0,0 +1,62 @@ +.\" +.\" Copyright (c) 2026 Christos Longros +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd March 21, 2026 +.Dt VMGENC 4 +.Os +.Sh NAME +.Nm vmgenc +.Nd ACPI virtual machine generation ID counter +.Sh SYNOPSIS +.Cd device vmgenc +.Pp +In +.Xr loader.conf 5 : +.Cd vmgenc_load="YES" +.Sh DESCRIPTION +The +.Nm +driver provides support for the Virtual Machine Generation ID, +a 128-bit unique identifier exposed by the hypervisor via ACPI. +The hypervisor changes this identifier whenever the virtual machine +is cloned, restored from a snapshot, or otherwise duplicated. +.Pp +When a generation ID change is detected, the +.Nm +driver feeds the new identifier into the kernel entropy pool via +.Xr random 4 , +ensuring that duplicated virtual machines do not share +cryptographic state. +The driver also sends a +.Xr devctl 4 +event and an internal kernel notification so that other subsystems +can respond to the duplication. +.Pp +The Virtual Machine Generation ID specification is supported by +QEMU, VMware ESXi, Microsoft Hyper-V, and Xen. +.Sh SYSCTL VARIABLES +The following variable is available: +.Bl -tag -width indent +.It Va dev.vmgenc.%d.guid +The current cached VM generation counter as a 128-bit value. +This value is updated each time the hypervisor signals a +generation change. +.El +.Sh SEE ALSO +.Xr acpi 4 , +.Xr random 4 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 13.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Conrad Meyer Aq Mt cem@FreeBSD.org . +.Pp +This manual page was written by +.An Christos Longros Aq Mt chris.longros@gmail.com . diff --git a/static/freebsd/man4/vmm.4 b/static/freebsd/man4/vmm.4 new file mode 100644 index 00000000..6e121cb8 --- /dev/null +++ b/static/freebsd/man4/vmm.4 @@ -0,0 +1,196 @@ +.\" Copyright (c) 2013 Peter Grehan +.\" 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 AUTHORS 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 AUTHORS 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 December 30, 2024 +.Dt VMM 4 +.Os +.Sh NAME +.Nm vmm.ko +.Nd "bhyve virtual machine monitor" +.Sh SYNOPSIS +To load the driver as a module at boot, add this line to +.Xr loader.conf 5 : +.Bd -literal -offset indent +.Cd vmm_load="YES" +.Ed +.Pp +The module can also be loaded manually with +.Xr kldload 8 : +.Bd -literal -offset indent +kldload vmm +.Ed +.Sh DESCRIPTION +.Nm +provides the kernel portion of the +.Xr bhyve 4 +hypervisor. +The following platforms are supported: +.Bl -bullet -compat +.It +amd64: An Intel CPU with VT-x/EPT or AMD CPU with SVM support is required. +.It +arm64: The boot CPU must start in EL2 and the system must have a GICv3 interrupt +controller. +VHE support will be used if available. +.It +riscv: The CPUs must implement the H (hypervisor) RISC-V ISA extension. +.El +.Pp +PCI device passthrough to a virtual machine requires +hardware with VT-d support and is available only on amd64. +.Sh ACCESS CONTROL +Only the super-user and processes with write access to the +.Pa /dev/vmmctl +device file may create and destroy virtual machines. +By default, members of the +.Va vmm +group have such access. +Once created, a virtual machine may be destroyed only by that user or +the super-user. +.Pp +Unprivileged users must use +.Dq monitor mode +to run the virtual machine; in this mode, the virtual machine is automatically +destroyed when its device file is closed. +When running +.Xr bhyve 8 , +this mode can be selected by specifying the +.Fl M +flag. +.Pp +Virtual machines can be created in a jail if the jail has the +.Va allow.vmm +flag set. +.Sh PCI PASSTHROUGH +On amd64 where the hardware supports VT-d, +PCI devices can be reserved for use by the hypervisor. +Entries consisting of the PCI +.Ar bus Ns / Ns Ar slot Ns / Ns Ar function +are added to the +.Va pptdevs +.Xr loader.conf 5 +variable. +Additional entries are separated by spaces. +Host PCI devices that match an entry will be assigned to the hypervisor +and will not be probed by +.Fx +device drivers. +See the +.Sx EXAMPLES +section below for sample usage. +.Pp +Note that +.Nm vmm +must be given first the right of refusal to all +.Xr pci 4 +devices it may need to claim. +As a result, the +.Nm vmm +kernel module almost certainly needs to be loaded from +.Xr loader.conf 5 +rather than by adding it to +.Va kld_list in +.Xr rc.conf 5 . +.Pp +A large number of PCI device entries may require a string longer than the +128-character limit of +.Xr loader.conf 5 +variables. +The +.Va pptdevs2 +and +.Va pptdevs3 +variables can be used for additional entries. +.Pp +In general, PCI passthrough cannot be used when running +.Xr bhyve 8 +as an unprivileged user or in a jail, as this feature requires write +access to +.Pa /dev/pci . +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width indent +.It Va hw.vmm.maxcpu +Maximum number of virtual CPUs. +The default is the number of physical CPUs in the system. +.El +.Sh FILES +.Bl -tag -width /dev/vmm.io/* -compact +.It Pa /dev/vmmctl +control interface for creating and destroying virtual machines. +.It Pa /dev/vmm/* +device interface for individual virtual machines. +.It Pa /dev/vmm.io/* +device interface for device memory mapped into virtual machines. +.Sh EXAMPLES +Reserve three PCI devices for use by the hypervisor: bus 10 slot 0 function 0, +bus 6 slot 5 function 0, and bus 6 slot 5 function 1. +.Bd -literal -offset indent +pptdevs="10/0/0 6/5/0 6/5/1" +.Ed +.Pp +It is possible to detach +.Va ppt +from a PCI device without rebooting the host machine and then attach a host +driver, using the +.Xr devctl 8 +utility. +Suppose +.Va ppt +is currently attached to +.Va pci0:0:1:0 +and we want the host's +.Xr xhci 4 +driver to be attached instead: +.Bd -literal -offset indent +# devctl set driver -f pci0:0:1:0 xhci +.Ed +.Pp +The same can be applied to attach +.Va ppt +back: +.Bd -literal -offset indent +# devctl set driver -f pci0:0:1:0 ppt +.Ed +.Sh SEE ALSO +.Xr bhyve 4 , +.Xr loader.conf 5 , +.Xr bhyve 8 , +.Xr bhyvectl 8 , +.Xr bhyveload 8 , +.Xr devctl 8 , +.Xr jail 8 , +.Xr kldload 8 +.Sh HISTORY +.Nm vmm.ko +first appeared in +.Fx 10.0 . +arm64 and riscv support first appeared in +.Fx 15.0 . +.Sh AUTHORS +.An Neel Natu Aq neel@freebsd.org +.An Peter Grehan Aq grehan@freebsd.org diff --git a/static/freebsd/man4/vmx.4 b/static/freebsd/man4/vmx.4 new file mode 100644 index 00000000..339c7d90 --- /dev/null +++ b/static/freebsd/man4/vmx.4 @@ -0,0 +1,155 @@ +.\" +.\" Copyright (c) 2006,2013 Reyk Floeter +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $OpenBSD: src/share/man/man4/vmx.4,v 1.1 2013/05/31 20:18:44 reyk Exp $ +.\" +.Dd December 26, 2020 +.Dt VMX 4 +.Os +.Sh NAME +.Nm vmx +.Nd VMware VMXNET3 Virtual Interface Controller device +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device iflib" +.Cd "device vmx" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_vmx_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the VMXNET3 virtual NIC available in virtual +machines by VMware. +It appears as a simple Ethernet device but is actually a virtual network +interface to the underlying host operating system. +.Pp +This driver supports the +.Ic VMXNET3 +driver protocol, as an alternative to the emulated +.Xr le 4 , +.Xr em 4 +interfaces also available in the VMware environment. +The +.Nm +driver is optimized for the virtual machine, it can provide advanced +capabilities depending on the underlying host operating system and +the physical network interface controller of the host. +The +.Nm +driver supports features like multiqueue support, IPv6 +checksum offloading, MSI/MSI-X support and hardware VLAN tagging in +VMware's VLAN Guest Tagging (VGT) mode. +.Pp +The +.Nm +driver supports VMXNET3 VMware virtual NICs provided by the virtual +machine hardware version 7 or newer, as provided by the following +products: +.Pp +.Bl -bullet -compact -offset indent +.It +VMware ESX/ESXi 4.0 and newer +.It +VMware Server 2.0 and newer +.It +VMware Workstation 6.5 and newer +.It +VMware Fusion 2.0 and newer +.El +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh MULTIPLE QUEUES +The +.Nm +driver supports multiple transmit and receive queues. +Multiple queues are only supported by certain VMware products, such as ESXi. +The number of queues allocated depends on the presence of MSI-X, +the number of configured CPUs, +and the tunables listed below. +.Fx +does not enable MSI-X support on VMware by default. +The +.Va hw.pci.honor_msi_blacklist +tunable must be disabled to enable MSI-X support. +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width indent +.It Va hw.vmx.txnqueue +.It Va hw.vmx. Ns Ar X Ns Va .txnqueue +Maximum number of transmit queues allocated by default by the driver. +The default value is 8. +The maximum supported by the VMXNET3 virtual NIC is 8. +.It Va hw.vmx.rxnqueue +.It Va hw.vmx. Ns Ar X Ns Va .rxnqueue +Maximum number of receive queues allocated by default by the driver. +The default value is 8. +The maximum supported by the VMXNET3 virtual NIC is 16. +.It Va hw.vmx.txndesc +.It Va hw.vmx. Ns Ar X Ns Va .txndesc +.Pp +Number of transmit descriptors allocated by the driver. +The default value is 512. +The value must be a multiple of 32, and the maximum is 4096. +.It Va hw.vmx.rxndesc +.It Va hw.vmx. Ns Ar X Ns Va .rxndesc +.Pp +Number of receive descriptors per ring allocated by the driver. +The default value is 256. +The value must be a multiple of 32, and the maximum is 2048. +There are two rings so the actual usage is doubled. +.El +.Sh EXAMPLES +The following entry must be added to the VMware configuration file +to provide the +.Nm +device: +.Bd -literal -offset indent +ethernet0.virtualDev = "vmxnet3" +.Ed +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr em 4 , +.Xr iflib 4 , +.Xr le 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was ported from +.Ox +and significantly rewritten by +.An Bryan Venteicher Aq Mt bryanv@freebsd.org . +The +.Ox +driver was written by +.An Tsubai Masanari . diff --git a/static/freebsd/man4/vr.4 b/static/freebsd/man4/vr.4 new file mode 100644 index 00000000..c18133b5 --- /dev/null +++ b/static/freebsd/man4/vr.4 @@ -0,0 +1,215 @@ +.\" Copyright (c) 1997, 1998 +.\" Bill Paul . 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 Bill Paul. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Bill Paul 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 Bill Paul OR THE VOICES IN HIS HEAD +.\" 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 February 25, 2012 +.Dt VR 4 +.Os +.Sh NAME +.Nm vr +.Nd "VIA Technologies Rhine I/II/III Ethernet device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device vr" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_vr_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for PCI Ethernet adapters and embedded +controllers based on the VIA Technologies VT3043 Rhine I, +VT86C100A Rhine II, and VT6105/VT6105M Rhine III Fast Ethernet +controller chips. +.Pp +The VIA Rhine chips use bus master DMA and have a descriptor layout +designed to resemble that of the DEC 21x4x +.Dq tulip +chips. +The register +layout is different however and the receive filter in the Rhine chips +is much simpler and is programmed through registers rather than by +downloading a special setup frame through the transmit DMA engine. +Transmit and receive DMA buffers must be longword +aligned. +The Rhine chips are meant to be interfaced with external +physical layer devices via an MII bus. +They support both +10 and 100Mbps speeds in either full or half duplex. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width xxxxxxxxxxxxxxxxxxxx +.It autoselect +Enable autoselection of the media type and options. +The user can manually override +the autoselected mode by adding media options to the +.Pa /etc/rc.conf +file. +.It 10baseT/UTP +Set 10Mbps operation. +The +.Ar mediaopt +option can also be used to select either +.Ar full-duplex +or +.Ar half-duplex +modes. +.It 100baseTX +Set 100Mbps (Fast Ethernet) operation. +The +.Ar mediaopt +option can also be used to select either +.Ar full-duplex +or +.Ar half-duplex +modes. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width xxxxxxxxxxxxxxxxxxxx +.It full-duplex +Force full duplex operation. +.It half-duplex +Force half duplex operation. +.El +.Pp +Note that the 100baseTX media type is only available if supported +by the adapter. +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports VIA Technologies Rhine I, Rhine II, and Rhine III based +Fast Ethernet adapters including: +.Pp +.Bl -bullet -compact +.It +AOpen/Acer ALN-320 +.It +D-Link DFE520-TX +.It +D-Link DFE530-TX +.It +Hawking Technologies PN102TX +.It +Soekris Engineering net5501 +.El +.Sh SYSCTL VARIABLES +The following variables are available as +.Xr sysctl 8 +variables: +.Bl -tag -width indent +.It Va dev.vr.%d.stats +Display lots of useful MAC counters maintained in the driver. +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "vr%d: couldn't map memory" +A fatal initialization error has occurred. +.It "vr%d: couldn't map interrupt" +A fatal initialization error has occurred. +.It "vr%d: watchdog timeout" +The device has stopped responding to the network, or there is a problem with +the network connection (cable). +.It "vr%d: no memory for rx list" +The driver failed to allocate an mbuf for the receiver ring. +.It "vr%d: no memory for tx list" +The driver failed to allocate an mbuf for the transmitter ring when +allocating a pad buffer or collapsing an mbuf chain into a cluster. +.It "vr%d: chip is in D3 power state -- setting to D0" +This message applies only to adapters which support power +management. +Some operating systems place the controller in low power +mode when shutting down, and some PCI BIOSes fail to bring the chip +out of this state before configuring it. +The controller loses all of +its PCI configuration in the D3 state, so if the BIOS does not set +it back to full power mode in time, it will not be able to configure it +correctly. +The driver tries to detect this condition and bring +the adapter back to the D0 (full power) state, but this may not be +enough to return the driver to a fully operational condition. +If +you see this message at boot time and the driver fails to attach +the device as a network interface, you will have to perform second +warm boot to have the device properly configured. +.Pp +Note that this condition only occurs when warm booting from another +operating system. +If you power down your system prior to booting +.Fx , +the card should be configured correctly. +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr polling 4 , +.Xr ifconfig 8 +.Rs +.%T The VIA Technologies VT86C100A data sheet +.%U http://www.via.com.tw +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 3.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Bill Paul Aq Mt wpaul@ctr.columbia.edu . +.Sh BUGS +The +.Nm +driver always copies transmit mbuf chains into longword-aligned +buffers prior to transmission in order to pacify the Rhine chips. +If buffers are not aligned correctly, the chip will round the +supplied buffer address and begin DMAing from the wrong location. +This buffer copying impairs transmit performance on slower systems but cannot +be avoided. +On faster machines (e.g.\& a Pentium II), the performance +impact is much less noticeable. diff --git a/static/freebsd/man4/vt.4 b/static/freebsd/man4/vt.4 new file mode 100644 index 00000000..5454fe0a --- /dev/null +++ b/static/freebsd/man4/vt.4 @@ -0,0 +1,456 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2014 Warren Block +.\" 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 AUTHORS 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 AUTHORS 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 November 21, 2025 +.Dt VT 4 +.Os +.Sh NAME +.Nm vt +.Nd virtual terminal system video console driver +.Sh SYNOPSIS +.Cd options TERMINAL_KERN_ATTR= Ns Ao Ar attribute Ac +.Cd options TERMINAL_NORM_ATTR= Ns Ao Ar attribute Ac +.Cd options VT_MAXWINDOWS= Ns Ao Ar N Ac +.Cd options VT_ALT_TO_ESC_HACK= Ns Ar 1 +.Cd options VT_TWOBUTTON_MOUSE +.Cd options VT_FB_MAX_WIDTH= Ns Ao Ar X Ac +.Cd options VT_FB_MAX_HEIGHT= Ns Ao Ar Y Ac +.Cd options SC_NO_CUTPASTE +.Cd device vt +.Pp +In +.Xr loader.conf 5 : +.Cd hw.vga.textmode= Ns Ar 1 +.Cd hw.vga.acpi_ignore_no_vga= Ns Ar 1 +.Cd kern.vty= Ns Ar vt +.Cd kern.vt.color. Ns Ao Ar colornum Ac Ns .rgb= Ns Ao Ar colorspec Ac +.Cd kern.vt.fb.default_mode= Ns Ao Ar X Ac Ns x Ns Ao Ar Y Ac +.Cd kern.vt.fb.modes. Ns Ao Ar connector Ac Ns = Ns Ao Ar X Ac Ns x Ns Ao Ar Y Ac +.Cd kern.vt.slow_down= Ns Ao Ar delay Ac +.Cd screen.font= Ns Ao Ar X Ac Ns x Ns Ao Ar Y Ac +.Pp +In +.Xr loader.conf 5 or +.Xr sysctl.conf 5 : +.Cd kern.consmute= Ns Ar 1 +.Cd kern.vt.kbd_halt= Ns Ar 1 +.Cd kern.vt.kbd_poweroff= Ns Ar 1 +.Cd kern.vt.kbd_reboot= Ns Ar 1 +.Cd kern.vt.kbd_debug= Ns Ar 1 +.Cd kern.vt.kbd_panic= Ns Ar 0 +.Cd kern.vt.enable_altgr= Ns Ar 0 +.Cd kern.vt.enable_bell= Ns Ar 1 +.Sh DESCRIPTION +The +.Nm +device provides multiple virtual terminals with an extensive feature +set: +.Bl -item -offset indent +.It +Unicode UTF-8 text with double-width characters. +.It +Large font maps in graphics mode, including support for Asian +character sets. +.It +Graphics-mode consoles. +.It +Integration with +KMS +.Pq Kernel Mode Setting +video drivers for switching between the +.Em X Window System +and virtual terminals. +.El +.Ss Virtual Terminals +Multiple virtual terminals are provided on a single computer. +Up to sixteen virtual terminals can be defined. +A single virtual terminal is connected to the screen and keyboard +at a time. +Key combinations are used to select a virtual terminal. +Alt-F1 through Alt-F12 correspond to the first twelve virtual terminals. +If more than twelve virtual terminals are created, Shift-Alt-F1 through +Shift-Alt-F4 are used to switch to the additional terminals. +.Ss Copying and Pasting Text with a Mouse +Copying and pasting text from the screen with a mouse is supported. +Press and hold down mouse button 1, usually the left button, while +moving the mouse to select text. +Selected text is highlighted with reversed foreground and background +colors. +To select more text after releasing mouse button 1, press mouse button +3, usually the right button. +To paste text that has been selected, press mouse button 2, usually the +middle button. +The text is entered as if it were typed at the keyboard. +The +.Dv VT_TWOBUTTON_MOUSE +kernel option can be used with mice that only have two buttons. +Setting this option makes the second mouse button into the +paste button. +See +.Xr moused 8 +for more information. +.Ss Scrolling Back +Output that has scrolled off the screen can be reviewed by pressing the +Scroll Lock key, then scrolling up and down with the arrow keys. +The Page Up and Page Down keys scroll up or down a full screen at a +time. +The Home and End keys jump to the beginning or end of the scrollback +buffer. +When finished reviewing, press the Scroll Lock key again to return to +normal use. +Some laptop keyboards lack a Scroll Lock key, and use a special function key +sequence (such as Fn + K) to access Scroll Lock. +.Sh DRIVER CONFIGURATION +.Ss Kernel Configuration Options +These kernel options control the +.Nm +driver. +.Bl -tag -width MAXCONS +.It Dv TERMINAL_NORM_ATTR= Ns Ao Ar attribute Ac +.It Dv TERMINAL_KERN_ATTR= Ns Ao Ar attribute Ac +These options change the default colors used for normal and kernel +text. +Available colors are defined in +.In sys/terminal.h . +See +.Sx EXAMPLES +below. +.It Dv VT_MAXWINDOWS= Ns Ao Ar N Ac +Set the number of virtual terminals to be created to +.Fa N . +The value defaults to 12. +.It Dv VT_ALT_TO_ESC_HACK= Ns Ar 1 +When the Alt key is held down while pressing another key, send an ESC +sequence instead of the Alt key. +.It Dv VT_TWOBUTTON_MOUSE +If defined, swap the functions of mouse buttons 2 and 3. +In effect, this makes the right-hand mouse button perform a paste. +These options are checked in the order shown. +.It Dv SC_NO_CUTPASTE +Disable mouse support. +.It VT_FB_MAX_WIDTH= Ns Ao Ar X Ac +Set the maximum width to +.Fa X . +.It VT_FB_MAX_HEIGHT= Ns Ao Ar Y Ac +Set the maximum height to +.Fa Y . +.El +.Sh BACKWARDS COMPATIBILITY +Several options are provided for compatibility with the previous +console device, +.Xr sc 4 . +These options will be removed in a future +.Fx +version. +.Bl -column -offset indent "TERMINAL_KERN_ATTR" "SC_KERNEL_CONS_ATTR" +.It Sy vt Option Name Ta Sy sc Option Name +.It Dv TERMINAL_KERN_ATTR Ta Dv SC_KERNEL_CONS_ATTR +.It Dv TERMINAL_NORM_ATTR Ta Dv SC_NORM_ATTR +.It Dv VT_TWOBUTTON_MOUSE Ta Dv SC_TWOBUTTON_MOUSE +.It Dv VT_MAXWINDOWS Ta Dv MAXCONS +.It none Ta Dv SC_NO_CUTPASTE +.El +.Sh START-UP OPERATION WITH X86 BIOS SYSTEMS +The computer BIOS starts in text mode, and +the +.Fx +.Xr loader 8 +runs, loading the kernel. +If +.Va hw.vga.textmode +is set, the system remains in text mode. +Otherwise, +.Nm +switches to 640x480x16 VGA mode using +.Cm vt_vga . +If a KMS +.Pq Kernel Mode Setting +video driver is available, the display is switched to high resolution +and the KMS driver takes over. +When a KMS driver is not available, +.Cm vt_vga +remains active. +.Sh LOADER TUNABLES +These settings can be entered at the +.Xr loader 8 +prompt or in +.Xr loader.conf 5 . +.Bl -tag -width indent +.It Va hw.vga.textmode +Set to 1 to use virtual terminals in text mode instead of graphics mode on +BIOS boot. +Features that require graphics mode, like loadable fonts, will be +disabled. +.Pp +If a KMS driver is loaded the console will switch to, and remain in, +graphics mode. +Moreover this tunable has no effect with +.Xr UEFI 8 +boot because it does not use VGA mode. +.It Va hw.vga.acpi_ignore_no_vga +Set to 1 to force the usage of the VGA driver regardless of whether +ACPI IAPC_BOOT_ARCH signals no VGA support. +Can be used to workaround firmware bugs in the ACPI tables. +Note no VGA support is only acknowledged when running virtualized. +There is too many broken firmware that wrongly reports no VGA support on +physical hardware. +.It Va kern.vty +Set this value to +.Ql vt +or +.Ql sc +to choose a specific system console, overriding the default. +The +.Pa GENERIC +kernel uses +.Nm +when this value is not set. +Note that +.Ql sc +is not compatible with +.Xr UEFI 8 +boot. +.It Va kern.vt.color . Ns Ar colornum . Ns Va rgb +Set this value to override default palette entry for color +.Ar colornum +which should be in a range from 0 to 15 inclusive. +The value should be either a comma-separated triplet of +red, green, and blue values in a range from 0 to 255 or +HTML-like hex triplet. +See +.Sx EXAMPLES +below. +.Pp +Note: The +.Nm +VGA hardware driver does not support palette configuration. +.It Va kern.vt.fb.default_mode +Set this value to a graphic mode to override the default picked by the +.Nm +backend. +The mode is applied to all output connectors. +This is currently only supported by the +.Cm vt_fb +backend when it is paired with a KMS video driver. +.It Va kern.vt.fb.modes . Ns Ao Ar connector_name Ac +Set this value to a graphic mode to override the default picked by the +.Nm +backend. +This mode is applied to the output connector +.Pa connector_name +only. +It has precedence over +.Va kern.vt.fb.default_mode . +The names of available connector names can be found in +.Xr dmesg 8 +after loading the KMS driver. +It will contain a list of connectors and their associated tunables. +This is currently only supported by the +.Cm vt_fb +backend when it is paired with a KMS video driver. +.It Va kern.vt.slow_down +When debugging the kernel on modern laptops, the screen is often +the only available console, and relevant information will scroll +out of view before it can be captured by eye or camera. +.Pp +Setting +.Va kern.vt.slow_down +to a non-zero number will make console output synchronous (ie: +not dependent on timers and interrupts) and slow it down in proportion +to the number. +.It Va screen.font +Set this value to the base name of the desired font file located in +.Pa /boot/fonts . +The font must be specified in the +.Pa INDEX.fonts +file located there. +Fonts can be converted for use with +.Xr vtfontcvt 8 . +.El +.Sh KEYBOARD SYSCTL TUNABLES +These settings control whether certain special key combinations are enabled or +ignored. +The specific key combinations can be configured by using a +.Xr keymap 5 +file. +.Pp +These settings can be entered at the +.Xr loader 8 +prompt or in +.Xr loader.conf 5 +and can also be changed at runtime with the +.Xr sysctl 8 +command. +.Bl -tag -width indent +.It Va kern.vt.enable_altgr +Enable AltGr key (do not assume right Alt key as Alt). +.It Va kern.vt.kbd_halt +Enable halt keyboard combination. +.It Va kern.vt.kbd_poweroff +Enable power off key combination. +.It Va kern.vt.kbd_reboot +Enable reboot key combination, usually Ctrl+Alt+Del. +.It Va kern.vt.kbd_debug +Enable debug request key combination, usually Ctrl+Alt+Esc. +.It Va kern.vt.kbd_panic +Enable panic key combination. +.El +.Sh OTHER SYSCTL TUNABLES +These settings can be entered at the +.Xr loader 8 +prompt, set in +.Xr loader.conf 5 , +or changed at runtime with +.Xr sysctl 8 . +.Bl -tag -width indent +.It Va kern.consmute +Disable printing kernel messages to the system console. +.It Va kern.vt.enable_bell +Enable the terminal bell. +.El +.Sh FILES +.Bl -tag -width "/usr/share/vt/keymaps/*.kbd" -compact +.It Pa /dev/console +.It Pa /dev/consolectl +.It Pa /dev/ttyv* +virtual terminals +.It Pa /etc/ttys +terminal initialization information +.It Pa /usr/share/vt/fonts/*.fnt +console fonts +.It Pa /usr/share/vt/keymaps/*.kbd +keyboard layouts +.El +.Sh DEVCTL MESSAGES +.Bl -column "System" "Subsystem" "Type" "Description" +.Sy "System" Ta Sy "Subsystem" Ta Sy "Type" Ta Sy "Description" +.It Li VT Ta BELL Ta RING Ta +Notification that the console bell has rung. +.El +.Bl -column "duration_ms" "Meaning" +.Sy "Variable" Ta Sy "Meaning" +.It Li duration_ms Ta Length of time the bell was requested to ring in milliseconds. +.It Li enabled Ta true or false indicating whether or not the bell was administratively enabled when rung. +.It Li hushed Ta true or false indicating whether or not the bell was quieted by the user when rung. +.It Li hz Ta Tone that was requested in Hz. +.El +.Sh EXAMPLES +To increase the scrollback buffer size to 22500 lines, +add the following line to +.Pa /etc/rc.conf : +.Pp +.Dl allscreens_flags="-h 22500" +.Pp +This example changes the default color of normal text to green on a +black background, or black on a green background when reversed. +Note that white space cannot be used inside the attribute string +because of the current implementation of +.Xr config 8 . +.Pp +.Dl "options TERMINAL_NORM_ATTR=(FG_GREEN|BG_BLACK)" +.Pp +This line changes the default color of kernel messages to be bright red +on a black background, or black on a bright red background when reversed. +.Pp +.Dl "options TERMINAL_KERN_ATTR=(FG_LIGHTRED|BG_BLACK)" +.Pp +To set a 1024x768 mode on all output connectors, put the following line in +.Pa /boot/loader.conf : +.Pp +.Dl kern.vt.fb.default_mode="1024x768" +.Pp +To set a 800x600 only on a laptop builtin screen, +use the following line instead: +.Pp +.Dl kern.vt.fb.modes.LVDS-1="800x600" +.Pp +The connector name was found in +.Xr dmesg 8 : +.Pp +.Dl info: [drm] Connector LVDS-1: get mode from tunables: +.Dl info: [drm] - kern.vt.fb.modes.LVDS-1 +.Dl info: [drm] - kern.vt.fb.default_mode +.Pp +To set black and white colors of console palette +.Pp +.Dl kern.vt.color.0.rgb="10,10,10" +.Dl kern.vt.color.15.rgb="#f0f0f0" +.Pp +Load the 8x16 font in +.Xr loader.conf 5 +from +.Pa /boot/fonts/*.fnt[.gz] +at boot: +.Pp +.Dl screen.font="8x16" +.Sh SEE ALSO +.Xr kbdcontrol 1 , +.Xr login 1 , +.Xr vidcontrol 1 , +.Xr atkbd 4 , +.Xr atkbdc 4 , +.Xr kbdmux 4 , +.Xr keyboard 4 , +.Xr screen 4 , +.Xr splash 4 , +.Xr syscons 4 , +.Xr ukbd 4 , +.Xr kbdmap 5 , +.Xr loader.conf 5 , +.Xr rc.conf 5 , +.Xr ttys 5 , +.Xr config 8 , +.Xr getty 8 , +.Xr kldload 8 , +.Xr moused 8 , +.Xr vtfontcvt 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 9.3 . +.Sh AUTHORS +.An -nosplit +The +.Nm +device driver was developed by +.An \&Ed Schouten Aq Mt ed@FreeBSD.org , +.An \&Ed Maste Aq Mt emaste@FreeBSD.org , +and +.An Aleksandr Rybalko Aq Mt ray@FreeBSD.org , +with sponsorship provided by the +.Fx +Foundation. +This manual page was written by +.An Warren Block Aq Mt wblock@FreeBSD.org . +.Sh CAVEATS +Paste buffer size is limited by the system value +.Brq Dv MAX_INPUT , +the number of bytes that can be stored in the terminal +input queue, usually 1024 bytes +(see +.Xr termios 4 ) . diff --git a/static/freebsd/man4/vte.4 b/static/freebsd/man4/vte.4 new file mode 100644 index 00000000..293c2cbb --- /dev/null +++ b/static/freebsd/man4/vte.4 @@ -0,0 +1,149 @@ +.\" Copyright (c) 2010 Pyun YongHyeon +.\" 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 December 30, 2010 +.Dt VTE 4 +.Os +.Sh NAME +.Nm vte +.Nd Vortex86 RDC R6040 Fast Ethernet driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device vte" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_vte_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +device driver provides support for RDC R6040 Fast Ethernet controller +which is commonly found on Vortex86 System On a Chip (SoC). +.Pp +The RDC R6040 has integrated 10/100 PHY for 10/100Mbps support in full +or half-duplex. +The controller supports interrupt moderation mechanism, a 64-bit multicast +hash filter, VLAN over-size frame and four station addresses. +The +.Nm +device driver uses three station addresses out of four as perfect +multicast filter. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width ".Cm 10baseT/UTP" +.It Cm autoselect +Enable autoselection of the media type and options. +The user can manually override +the autoselected mode by adding media options to +.Xr rc.conf 5 . +.It Cm 10baseT/UTP +Set 10Mbps operation. +.It Cm 100baseTX +Set 100Mbps (Fast Ethernet) operation. +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width ".Cm full-duplex" +.It Cm full-duplex +Force full duplex operation. +.It Cm half-duplex +Force half duplex operation. +.El +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +device driver provides support for the following Ethernet controllers: +.Pp +.Bl -bullet -compact +.It +DM&P Vortex86 RDC R6040 Fast Ethernet controller +.El +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width "xxxxxx" +.It Va hw.vte.tx_deep_copy +The RDC R6040 controller has no auto-padding support for short +frames and the controller's DMA engine does not have capability to +handle multiple buffers for a TX frame such that driver has to +create a single contiguous TX buffer. +This hardware limitation leads to poor TX performance since most of +CPU cycles are wasted on both de-fragmenting mbuf chains and padding. +This tunable enables deep copy operation for TX frames such that +driver will spend less CPU cycles in de-fragmentation with the +cost of extra TX buffer memory. +The default value is 1 to use deep copy. +.El +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width "xxxxxx" +.It Va dev.vte.%d.rx_mod +Maximum number of packets to fire RX completion interrupt. +The accepted range is 0 to 15, the default is 15. +.It Va dev.vte.%d.tx_mod +Maximum number of packets to fire TX completion interrupt. +The accepted range is 0 to 15, the default is 15. +.It Va dev.vte.%d.stats +Show hardware MAC statistics maintained in driver. +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Rs +.%T "DM&P Electronics Inc. Vortex86" +.%U http://www.dmp.com.tw +.Re +.Sh HISTORY +The +.Nm +driver was written by +.An Pyun YongHyeon Aq Mt yongari@FreeBSD.org . +It first appeared in +.Fx 8.3 . diff --git a/static/freebsd/man4/vtnet.4 b/static/freebsd/man4/vtnet.4 new file mode 100644 index 00000000..926f504d --- /dev/null +++ b/static/freebsd/man4/vtnet.4 @@ -0,0 +1,298 @@ +.\" Copyright (c) 2011 Bryan Venteicher +.\" 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 December 19, 2025 +.Dt VTNET 4 +.Os +.Sh NAME +.Nm vtnet +.Nd VirtIO Ethernet driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device vtnet" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_vtnet_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +device driver provides support for VirtIO Ethernet devices. +.Pp +If the hypervisor advertises the appropriate features, the +.Nm +driver supports TCP/UDP checksum offload for both transmit and receive, +TCP segmentation offload (TSO), TCP large receive offload (LRO), +hardware VLAN tag stripping/insertion features, a multicast hash filter, +as well as Jumbo Frames (up to 9216 bytes), which can be +configured via the interface MTU setting. +.Pp +Two flavors of TCP LRO are supported: +Hardware TCP LRO, which is performed by the host providing TCP segments larger +than the MTU to the guest, and Software TCP LRO, which is performed by the +network stack of the guest processing TCP segments in an optimized way. +Only one flavour of TCP LRO should be used. +Since hardware TCP LRO can have bad interactions with IP forwarding and +software TCP LRO mitigates several drawbacks of hardware TCP LRO, the default +setting is to disable hardware TCP LRO. +See the loader tunable +.Va hw.vtnet. Ns Ar X Ns Va .lro_disable . +.Pp +TCP/UDP receive checksum offload cannot be configured independently for IPv4 +and IPv6. +Selecting an MTU larger than 1500 bytes with the +.Xr ifconfig 8 +utility configures the adapter to receive and transmit Jumbo Frames. +.Pp +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh LOADER TUNABLES +Tunables can be set at the +.Xr loader 8 +prompt before booting the kernel or stored in +.Xr loader.conf 5 . +.Bl -tag -width "xxxxxx" +.It Va hw.vtnet.csum_disable +.It Va hw.vtnet. Ns Ar X Ns Va .csum_disable +This tunable disables receive and transmit checksum offloading for TCP and +UDP. +This also implies that TCP segmentation offloading and large receive offload +are disabled. +The default value is 0. +.It Va hw.vtnet.fixup_needs_csum +.It Va hw.vtnet. Ns Ar X Ns Va .fixup_needs_csum +This tunable enforces the calculation of a valid TCP or UDP checksum for +packets received with +.Dv VIRTIO_NET_HDR_F_NEEDS_CSUM +being set in the +.Va flags +field of the structure +.Vt struct virtio_net_hdr . +It also marks the checksum as being correct in the mbuf packet header. +The default value is 0. +This tunable is deprecated and will be removed in +.Fx 16 . +.It Va hw.vtnet.tso_disable +.It Va hw.vtnet. Ns Ar X Ns Va .tso_disable +This tunable disables TCP segmentation offloading. +The default value is 0. +.It Va hw.vtnet.lro_disable +.It Va hw.vtnet. Ns Ar X Ns Va .lro_disable +This tunable disables hardware TCP LRO. +The default value is 1. +.It Va hw.vtnet.mq_disable +.It Va hw.vtnet. Ns Ar X Ns Va .mq_disable +This tunable disables multiqueue. +The default value is 0. +.It Va hw.vtnet.mq_max_pairs +.It Va hw.vtnet. Ns Ar X Ns Va .mq_max_pairs +This tunable sets the maximum number of transmit and receive queue pairs. +Multiple queues are only supported when the Multiqueue feature is negotiated. +This driver supports a maximum of 8 queue pairs. +The number of queue pairs used is the lesser of the maximum supported by the +driver and the hypervisor, the number of CPUs present in the guest, and this +tunable if not zero. +The default value is 0. +.It Va hw.vtnet.tso_maxlen +.It Va hw.vtnet. Ns Ar X Ns Va .tso_maxlen +This tunable sets the TSO burst limit. +The default value is 65535. +.It Va hw.vtnet.rx_process_limit +.It Va hw.vtnet. Ns Ar X Ns Va .rx_process_limit +This tunable sets the number of RX segments processed in one pass. +The default value is 1024. +.It Va hw.vtnet.lro_entry_count +.It Va hw.vtnet. Ns Ar X Ns Va .lro_entry_count +This tunable sets the software TCP LRO entry count. +The default value is 128, the minimum value is 8. +.It Va hw.vtnet.lro_mbufq_depth +.It Va hw.vtnet. Ns Ar X Ns Va .lro_mbufq_depth +This tunable sets the depth of the software TCP LRO mbuf queue. +The default value is 0. +.It Va hw.vtnet.altq_disable +This tunable disables ALTQ support, allowing the use of multiqueue instead. +This option applies to all interfaces. +The default value is 0. +.El +.Sh TRANSMIT QUEUE STATISTICS +For each transmit queue of each interface the following read-only statistics +are provided: +.Bl -tag -width "xxxxxx" +.It Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .rescheduled +The number of times the transmit interrupt handler was rescheduled. +.It Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .tso +The number of times TCP segment offloading was performed. +.It Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .csum +The number of times transmit checksum offloading for UDP or TCP was +performed. +.It Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .omcasts +The number of multicast packets that were transmitted. +.It Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .obytes +The number of bytes that were transmitted (based on Ethernet frames). +.It Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .opackets +The number of packets that were transmitted (Ethernet frames). +.El +.Sh RECEIVE QUEUE STATISTICS +For each receive queue of each interface the following read-only statistics +are provided: +.Bl -tag -width "xxxxxx" +.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .rescheduled +The number of times the receive interrupt handler was rescheduled. +.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .host_lro +The number of times TCP large receive offload was performed. +.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .csum_failed +The number of times a packet with a request for receive or transmit checksum +offloading was received and this request failed. +The different reasons for the failure are counted by +.Va dev.vtnet. Ns Ar X Ns Va .rx_csum_inaccessible_ipproto , +.Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_ipproto , +.Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_ethtype , +and +.Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_offset . +.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .csum +The number of times receive checksum offloading for UDP or TCP was performed. +.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .ierrors +The number of times an error occurred during input processing. +.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .iqdrops +The number of times a packet was dropped during input processing. +.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .ibytes +The number of bytes that were received (based on Ethernet frames). +.It Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .ipackets +The number of packets that were received (Ethernet frames). +.El +.Sh INTERFACE TRANSMIT STATISTICS +For each interface the following read-only transmit statistics are provided: +.Bl -tag -width "xxxxxx" +.It Va dev.vtnet. Ns Ar X Ns Va .tx_task_rescheduled +The sum of +.Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .rescheduled +over all transmit queues of the interface. +.It Va dev.vtnet. Ns Ar X Ns Va .tx_tso_offloaded +The sum of +.Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .tso +over all transmit queues of the interface. +.It Va dev.vtnet. Ns Ar X Ns Va .tx_csum_offloaded +The sum of +.Va dev.vtnet. Ns Ar X Ns Va .txq Ns Ar Y Ns Va .csum +over all transmit queues of the interface. +.It Va dev.vtnet. Ns Ar X Ns Va .tx_defrag_failed +The number of times an attempt to defragment an mbuf chain failed during a +transmit operation. +.It Va dev.vtnet. Ns Ar X Ns Va .tx_defragged +The number of times an mbuf chain was defragmented during a transmit operation. +.It Va dev.vtnet. Ns Ar X Ns Va .tx_tso_without_csum +The number of times TCP segment offloading was attempted without transmit +checksum offloading. +.It Va dev.vtnet. Ns Ar X Ns Va .tx_tso_not_tcp +The number of times TCP segment offloading was attempted for a non-TCP packet. +.It Va dev.vtnet. Ns Ar X Ns Va .tx_csum_proto_mismatch +The number of times the IP protocol version of the transmit checksum +offloading request did not match the IP protocol version of the packet. +.It Va dev.vtnet. Ns Ar X Ns Va .tx_csum_unknown_ethtype +The number of times a transmit offload operation was requested for an +ethernet frame for which the EtherType was neither IPv4 nor IPv6 +(considering simple VLAN tagging). +.El +.Sh INTERFACE RECEIVE STATISTICS +For each interface the following read-only receive statistics are provided: +.Bl -tag -width "xxxxxx" +.It Va dev.vtnet. Ns Ar X Ns Va .rx_task_rescheduled +The sum of +.Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .rescheduled +over all receive queues of the interface. +.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_offloaded +The sum of +.Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .csum +over all receive queues of the interface. +.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_failed +The sum of +.Va dev.vtnet. Ns Ar X Ns Va .rxq Ns Ar Y Ns Va .csum_failed +over all receive queues of the interface. +.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_inaccessible_ipproto +The number of times a packet with a request for receive or transmit checksum +offloading was received where the IP protocol was not accessible. +.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_offset +The number of times fixing the checksum required by +.Va hw.vtnet.fixup_needs_csum +or +.Va hw.vtnet. Ns Ar X Ns Va .fixup_needs_csum +was attempted for a packet where the csum is not located in the first mbuf. +.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_ipproto +The number of times a packet with a request for receive or transmit checksum +offloading was received where the IP protocol was neither TCP nor UDP. +.It Va dev.vtnet. Ns Ar X Ns Va .rx_csum_bad_ethtype +The number of times a packet with a request for receive or transmit checksum +offloading was received where the EtherType was neither IPv4 nor IPv6. +.It Va dev.vtnet. Ns Ar X Ns Va .rx_mergeable_failed +The number of times receiving a mergable buffer failed. +.It Va dev.vtnet. Ns Ar X Ns Va .rx_enq_replacement_failed +The number of times the enqueuing the replacement receive mbuf chain failed. +.It Va dev.vtnet. Ns Ar X Ns Va .rx_frame_too_large +The number of times the frame was loger than the mbuf chain during large +receive offload without mergeable buffers. +.It Va dev.vtnet. Ns Ar X Ns Va .mbuf_alloc_failed +The number of times an mbuf cluster allocation for the receive buffer failed. +.El +.Sh INTERFACE CONFIGURATION PARAMETER +For each interface the following read-only configuration parameters are +provided: +.Bl -tag -width "xxxxxx" +.It Va dev.vtnet. Ns Ar X Ns Va .act_vq_pairs +The number of active virtqueue pairs. +.It Va dev.vtnet. Ns Ar X Ns Va .req_vq_pairs +The number of requested virtqueue pairs. +.It Va dev.vtnet. Ns Ar X Ns Va .max_vq_pairs +The maximum number of supported virtqueue pairs. +.It Va dev.vtnet. Ns Ar X Ns Va .flags +The flags of the interface. +Mostly for debugging purposes. +.It Va dev.vtnet. Ns Ar X Ns Va .features +The features of the interface as defined by the virtio specification. +.El +.Sh SEE ALSO +.Xr arp 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr virtio 4 , +.Xr vlan 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +driver was written by +.An Bryan Venteicher Aq Mt bryanv@FreeBSD.org . +It first appeared in +.Fx 9.0 . +.Sh CAVEATS +The +.Nm +driver only supports LRO when the hypervisor advertises the +mergeable buffer feature. diff --git a/static/freebsd/man4/vxlan.4 b/static/freebsd/man4/vxlan.4 new file mode 100644 index 00000000..5f2bd469 --- /dev/null +++ b/static/freebsd/man4/vxlan.4 @@ -0,0 +1,292 @@ +.\" Copyright (c) 2014 Bryan Venteicher +.\" 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 March 30, 2021 +.Dt VXLAN 4 +.Os +.Sh NAME +.Nm vxlan +.Nd "Virtual eXtensible LAN interface" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device vxlan" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_vxlan_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver creates a virtual tunnel endpoint in a +.Nm +segment. +A +.Nm +segment is a virtual Layer 2 (Ethernet) network that is overlaid +in a Layer 3 (IP/UDP) network. +.Nm +is analogous to +.Xr vlan 4 +but is designed to be better suited for large, multiple tenant +data center environments. +.Pp +Each +.Nm +interface is created at runtime using interface cloning. +This is most easily done with the +.Xr ifconfig 8 +.Cm create +command or using the +.Va cloned_interfaces +variable in +.Xr rc.conf 5 . +The interface may be removed with the +.Xr ifconfig 8 +.Cm destroy +command. +.Pp +The +.Nm +driver creates a pseudo Ethernet network interface +that supports the usual network +.Xr ioctl 2 Ns s +and thus can be used with +.Xr ifconfig 8 +like any other Ethernet interface. +The +.Nm +interface encapsulates the Ethernet frame +by prepending IP/UDP and +.Nm +headers. +Thus, the encapsulated (inner) frame is able to be transmitted +over a routed, Layer 3 network to the remote host. +.Pp +The +.Nm +interface may be configured in either unicast or multicast mode. +When in unicast mode, +the interface creates a tunnel to a single remote host, +and all traffic is transmitted to that host. +When in multicast mode, +the interface joins an IP multicast group, +and receives packets sent to the group address, +and transmits packets to either the multicast group address, +or directly to the remote host if there is an appropriate +forwarding table entry. +.Pp +When the +.Nm +interface is brought up, a +.Xr udp 4 +.Xr socket 9 +is created based on the configuration, +such as the local address for unicast mode or +the group address for multicast mode, +and the listening (local) port number. +Since multiple +.Nm +interfaces may be created that either +use the same local address +or join the same group address, +and use the same port, +the driver may share a socket among multiple interfaces. +However, each interface within a socket must belong to +a unique +.Nm +segment. +The analogous +.Xr vlan 4 +configuration would be a physical interface configured as +the parent device for multiple VLAN interfaces, each with +a unique VLAN tag. +Each +.Nm +segment is identified by a 24-bit value in the +.Nm +header called the +.Dq VXLAN Network Identifier , +or VNI. +.Pp +When configured with the +.Xr ifconfig 8 +.Cm vxlanlearn +parameter, the interface dynamically creates forwarding table entries +from received packets. +An entry in the forwarding table maps the inner source MAC address +to the outer remote IP address. +During transmit, the interface attempts to lookup an entry for +the encapsulated destination MAC address. +If an entry is found, the IP address in the entry is used to directly +transmit the encapsulated frame to the destination. +Otherwise, when configured in multicast mode, +the interface must flood the frame to all hosts in the group. +The maximum number of entries in the table is configurable with the +.Xr ifconfig 8 +.Cm vxlanmaxaddr +command. +Stale entries in the table are periodically pruned. +The timeout is configurable with the +.Xr ifconfig 8 +.Cm vxlantimeout +command. +The table may be viewed with the +.Xr sysctl 8 +.Cm net.link.vxlan.N.ftable.dump +command. +.Sh MTU +Since the +.Nm +interface encapsulates the Ethernet frame with an IP, UDP, and +.Nm +header, the resulting frame may be larger than the MTU of the +physical network. +The +.Nm +specification recommends the physical network MTU be configured +to use jumbo frames to accommodate the encapsulated frame size. +.Pp +By default, the +.Nm +driver sets its MTU to usual ethernet MTU of 1500 bytes, reduced by +the size of vxlan headers prepended to the encapsulated packets. +.Pp +Alternatively, the +.Xr ifconfig 8 +.Cm mtu +command may be used to set the fixed MTU size on the +.Nm +interface to allow the encapsulated frame to fit in the +current MTU of the physical network. +If the +.Cm mtu +command was used, system no longer adjust the +.Nm +interface MTU on routing or address changes. +.Sh HARDWARE +The +.Nm +driver supports hardware checksum offload (receive and transmit) and TSO on the +encapsulated traffic over physical interfaces that support these features. +The +.Nm +interface examines the +.Cm vxlandev +interface, if one is specified, or the interface hosting the +.Cm vxlanlocal +address, and configures its capabilities based on the hardware offload +capabilities of that physical interface. +If multiple physical interfaces will transmit or receive traffic for the +.Nm +then they all must have the same hardware capabilities. +The transmit routine of a +.Nm +interface may fail with +.Er ENXIO +if an outbound physical interface does not support +an offload that the +.Nm +interface is requesting. +This can happen if there are multiple physical interfaces involved, with +different hardware capabilities, or an interface capability was disabled after +the +.Nm +interface had already started. +.Pp +At present, these devices are capable of generating checksums and performing TSO +on the inner frames in hardware: +.Xr cxgbe 4 . +.Sh EXAMPLES +Create a +.Nm +interface in unicast mode +with the +.Cm vxlanlocal +tunnel address of 192.168.100.1, +and the +.Cm vxlanremote +tunnel address of 192.168.100.2. +.Bd -literal -offset indent +ifconfig vxlan create vxlanid 108 vxlanlocal 192.168.100.1 vxlanremote 192.168.100.2 +.Ed +.Pp +Create a +.Nm +interface in multicast mode, +with the +.Cm local +address of 192.168.10.95, +and the +.Cm group +address of 224.0.2.6. +The em0 interface will be used to transmit multicast packets. +.Bd -literal -offset indent +ifconfig vxlan create vxlanid 42 vxlanlocal 192.168.10.95 vxlangroup 224.0.2.6 vxlandev em0 +.Ed +.Pp +Once created, the +.Nm +interface can be configured with +.Xr ifconfig 8 . +.Pp +The following when placed in the file +.Pa /etc/rc.conf +will cause a vxlan interface called +.Dq Li vxlan0 +to be created, and will configure the interface in unicast mode. +.Bd -literal -offset indent +cloned_interfaces="vxlan0" +create_args_vxlan0="vxlanid 108 vxlanlocal 192.168.100.1 vxlanremote 192.168.100.2" +.Ed +.Sh SEE ALSO +.Xr inet 4 , +.Xr inet6 4 , +.Xr vlan 4 , +.Xr rc.conf 5 , +.Xr ifconfig 8 , +.Xr sysctl 8 +.Rs +.%A "M. Mahalingam" +.%A "et al" +.%T "Virtual eXtensible Local Area Network (VXLAN): A Framework for Overlaying Virtualized Layer 2 Networks over Layer 3 Networks" +.%D August 2014 +.%O "RFC 7348" +.Re +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Bryan Venteicher Aq bryanv@freebsd.org . +Support for stateless hardware offloads was added by +.An Navdeep Parhar Aq np@freebsd.org +in +.Fx 13.0 . diff --git a/static/freebsd/man4/watchdog.4 b/static/freebsd/man4/watchdog.4 new file mode 100644 index 00000000..fc2d6003 --- /dev/null +++ b/static/freebsd/man4/watchdog.4 @@ -0,0 +1,218 @@ +.\" Copyright (c) 2004 Poul-Henning Kamp +.\" Copyright (c) 2003, 2004 Sean M. Kelly +.\" 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 REGENTS 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 REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 2, 2018 +.Dt WATCHDOG 4 +.Os +.Sh NAME +.Nm watchdog +.Nd "hardware and software watchdog" +.Sh SYNOPSIS +.In sys/watchdog.h +.Sh DESCRIPTION +The +.Nm +facility is used for controlling hardware and software watchdogs. +.Pp +The device +.Pa /dev/fido +supports several optional +.Xr ioctl 2 +calls for configuration, and +responds to a set of operational +.Xr ioctl 2 +calls: +.Bl -tag -width "WDIOC_CONTROL int " +.It Dv WDIOCPATPAT +Pat the watchdog. +.It Dv WDIOC_CONTROL +Enable, disable, or reset the watchdog. +.El +.Pp +The +.Dv WDIOCPATPAT +.Xr ioctl 2 +call takes a single argument which represents a timeout value specified as a +.Vt sbintime_t +of the timeout period for the watchdog. +.Pp +The +.Dv WDIOCPATPAT +.Xr ioctl 2 +call will return success if just one of the available +.Xr watchdog 9 +implementations supports setting the timeout to the specified timeout. +This +means that at least one watchdog is armed. +By default, this will be a hardware watchdog if one is present, but if +no hardware watchdog is able to process the request, a default software +watchdog is enabled. +If the call fails, for instance if +none of +.Xr watchdog 9 +implementations support the timeout length, all watchdogs are disabled and must +be explicitly re-enabled. +.Pp +To disable the watchdogs use the +.Dv WDIOC_CONTROL +.Xr ioctl 2 +call with the +.Dv WD_CTRL_DISABLE +flag. +If disarming the watchdog(s) failed an error is returned. +The watchdog might +still be armed! +To reenable the watchdogs use the +.Dv WDIOC_CONTROL +.Xr ioctl 2 +call with the +.Dv WD_CTRL_ENABLE +flag. +Another way to pat the watchdog is with the +.Dv WDIOC_CONTROL +.Xr ioctl 2 +call passing the +.Dv WDIOC_CTRL_RESET +flag. +.Pp +The optional configuration +.Xr ioctl 2 +commands are listed here, along with the type of the parameter used. +Examples of their use can be found in +.Xr watchdogd 8 . +.Bl -tag -width "WDIOC_GETPRETTIMEOUT sbintime_t" +.It Dv WDIOC_SETTIMEOUT Fa sbintime_t +set/reset the timer +.It Dv WDIOC_GETTIMEOUT Fa sbintime_t +get total timeout +.It Dv WDIOC_GETTIMELEFT Fa sbintime_t +get time left +.It Dv WDIOC_GETPRETIMEOUT Fa sbintime_t +get the pre-timeout +.It Dv WDIOC_SETPRETIMEOUT Fa sbintime_t +set the pre-timeout +.It Dv WDIOC_SETPRETIMEOUTACT Fa int +Set the action when a pre-timeout occurs (see +.Li WD_SOFT_* +below). +.It Dv WDIOC_SETSOFT Fa int +Use an internal software watchdog instead of hardware. +There is also an external software watchdog, which is used by default +if no hardware watchdog was attached. +.It Dv WDIOC_SETSOFTTIMEOUTACT Fa int +Set the action when a soft timeout occurs. +.El +.Pp +The actions that may be specified for the pre-timeout or the internal software +watchdog are listed here. +Multiple actions can be specified by ORing values together. +.Bl -tag -width WD_SOFT_PRINT +.It Dv WD_SOFT_PANIC +panic +.It Dv WD_SOFT_DDB +enter debugger +.It Dv WD_SOFT_LOG +log(9) +.It Dv WD_SOFT_PRINT +printf(9) +.El +.Sh RETURN VALUES +The +.Dv WDIOCPATPAT +.Xr ioctl 2 +returns zero on success and non-zero on failure. +.Bl -tag -width Er +.It Bq Er EOPNOTSUPP +No watchdog present in the kernel or +none of the watchdogs supports the requested timeout value +(timeout value other than 0). +.It Bq Er EOPNOTSUPP +Watchdog could not be disabled (timeout value of 0). +.It Bq Er EINVAL +Invalid flag combination passed. +.El +.Pp +The configuration +.Xr ioctl 2 +operations return zero on success and non-zero on failure. +.Sh EXAMPLES +.Bd -literal -offset indent +#include +#include + +#define WDPATH "/dev/" _PATH_WATCHDOG +int wdfd = -1; + +static void +wd_init(void) +{ + wdfd = open(WDPATH, O_RDWR); + if (wdfd == -1) + err(1, WDPATH); +} +static void +wd_reset(u_int timeout) +{ + if (ioctl(wdfd, WDIOCPATPAT, &timeout) == -1) + err(1, "WDIOCPATPAT"); +} + +/* in main() */ +wd_init(); +wd_reset(WD_ACTIVE|WD_TO_8SEC); +/* potential freeze point */ +wd_reset(WD_TO_NEVER); +.Ed +.Pp +Enables a watchdog to recover from a potentially freezing piece of code. +.Pp +.Dl "options SW_WATCHDOG" +.Pp +in your kernel config forces a software watchdog in the kernel +to be configured even if a hardware watchdog is configured, +dropping to KDB or panicking when firing, depending +on the KDB and KDB_UNATTENDED kernel configuration options. +.Sh SEE ALSO +.Xr watchdogd 8 , +.Xr watchdog 9 +.Sh HISTORY +The +.Nm +code first appeared in +.Fx 5.1 . +.Sh AUTHORS +.An -nosplit +The +.Nm +facility was written by +.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org . +The software watchdog code and this manual page were written by +.An Sean Kelly Aq Mt smkelly@FreeBSD.org . +Some contributions were made by +.An Jeff Roberson Aq Mt jeff@FreeBSD.org . +.Sh BUGS +The +.Dv WD_PASSIVE +option has not yet been implemented. diff --git a/static/freebsd/man4/wbwd.4 b/static/freebsd/man4/wbwd.4 new file mode 100644 index 00000000..30800b4a --- /dev/null +++ b/static/freebsd/man4/wbwd.4 @@ -0,0 +1,142 @@ +.\"- +.\" Copyright (c) 2012 Bjoern A. Zeeb +.\" 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 October 16, 2019 +.Dt WBWD 4 +.Os +.Sh NAME +.Nm wbwd +.Nd device driver for Winbond/Nuvoton Super I/O chips watchdog timer +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device superio" +.Cd "device wbwd" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, place the following +line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +wbwd_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides +.Xr watchdog 4 +support for the watchdog interrupt timer present on at least the following +Super I/O chips: +.Bl -bullet -compact +.It +Winbond 83627HF/F/HG/G +.It +Winbond 83627S +.It +Winbond 83697HF +.It +Winbond 83697UG +.It +Winbond 83637HF +.It +Winbond 83627THF +.It +Winbond 83687THF +.It +Winbond 83627EHF +.It +Winbond 83627DHG +.It +Winbond 83627UHG +.It +Winbond 83667HG +.It +Winbond 83627DHG-P +.It +Winbond 83667HG-B +.It +Nuvoton NCT6775 +.It +Nuvoton NCT6776 +.It +Nuvoton NCT6102 +.It +Nuvoton NCT6779 +.It +Nuvoton NCT6791 +.It +Nuvoton NCT6792 +.El +.Sh SYSCTL VARIABLES +The +.Nm +driver provides the following options as +.Xr sysctl 8 +variables. +.Bl -tag -width "xxxxxx" +.It Va dev.wbwd.0.timeout_override +This variable allows to program the timer to a value independent on the one +provided by the +.Xr watchdog 4 +framework while still relying on the regular updates from e.g. +.Xr watchdogd 8 . +This is particularly useful if your system provides multiple watchdogs and +you want them to fire in a special sequence to trigger an NMI after a shorter +period than the reset timeout for example. +The value set must not be lower than the sleep time of +.Xr watchdogd 8 . +A value of 0 disables this feature and the timeout value provided by +.Xr watchdog 4 +will be used. +.It Va dev.wbwd.0.debug_verbose +If set this sysctl will tell the driver to log its current state before and +after the timer reset on each invocation from +.Xr watchdog 9 +to the kernel message buffer for debugging. +.It Va dev.wbwd.0.debug +This read-only value gives the state of some registers on last update. +.El +.Pp +The +.Nm +driver also provides further sysctl options that are hidden by default. +See the source code for more information. +.Sh SEE ALSO +.Xr superio 4 , +.Xr watchdog 4 , +.Xr device.hints 5 , +.Xr watchdog 8 , +.Xr watchdogd 8 , +.Xr watchdog 9 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 10.0 . +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Bjoern A. Zeeb Aq Mt bz@FreeBSD.org . diff --git a/static/freebsd/man4/wdatwd.4 b/static/freebsd/man4/wdatwd.4 new file mode 100644 index 00000000..48cd5d18 --- /dev/null +++ b/static/freebsd/man4/wdatwd.4 @@ -0,0 +1,91 @@ +.\"- +.\" Copyright (c) 2022 Tetsuya Uemura +.\" +.\" 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 November 18, 2022 +.Dt WDATWD 4 +.Os +.Sh NAME +.Nm wdatwd +.Nd device driver for the ACPI WDAT based watchdog interrupt timer +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device wdatwd" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +wdatwd_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides +.Xr watchdog 4 +support for the watchdog interrupt timer in ACPI WDAT (Watchdog Action Table). +.Pp +Since WDAT itself is an abstraction for the real hardware such as ICH WDT, it +must be noted that only one driver can be used at a time, either the real +hardware specific driver or this driver. +.Sh SYSCTL VARIABLES +The following read-only +.Xr sysctl 8 +variables are available: +.Bl -tag -width indent +.It Va dev.wdatwd.%d.running +The status of the watchdog timer. 0 if not running, or 1 if running. +.It Va dev.wdatwd.%d.timeout +The current value of the watchdog timeout in millisecond. +This can be 0 on some systems, and the zero value means that the default +timeout is used. +.It Va dev.wdatwd.%d.timeout_configurable +Whether the timeout is configurable or not. +It is 0 if configurable or any positive value if not. +.It Va dev.wdatwd.%d.timeout_default +The default value of the watchdog timeout in millisecond if any. +.El +.Sh SEE ALSO +.Xr ichwd 4 , +.Xr watchdog 4 , +.Xr watchdog 8 , +.Xr watchdogd 8 , +.Xr watchdog 9 +.Rs +.%T Hardware Watchdog Timers Design Specification +.%R Requirements for Hardware Watchdog Timers Supported by Microsoft(R) Windows Vista(R) and Microsoft Windows Server(R) 2008 Operating Systems +.%A Microsoft Corporation +.%U http://msdn.microsoft.com/en-us/windows/hardware/gg463320.aspx +.%D 2006 +.Re +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Tetsuya Uemura Aq Mt t_uemura@macome.co.jp +of MACOME, Corporation. diff --git a/static/freebsd/man4/wg.4 b/static/freebsd/man4/wg.4 new file mode 100644 index 00000000..8e2fcfe6 --- /dev/null +++ b/static/freebsd/man4/wg.4 @@ -0,0 +1,238 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2020 Gordon Bergling +.\" +.\" 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 February 12, 2025 +.Dt WG 4 +.Os +.Sh NAME +.Nm wg +.Nd "WireGuard protocol driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device wg" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, +place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_wg_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides Virtual Private Network (VPN) interfaces for the secure +exchange of layer 3 traffic with other WireGuard peers using the WireGuard +protocol. +.Pp +A +.Nm +interface recognizes one or more peers, establishes a secure tunnel with +each on demand, and tracks each peer's UDP endpoint for exchanging encrypted +traffic with. +.Pp +The interfaces can be created at runtime using the +.Ic ifconfig Cm wg Ns Ar N Cm create +command. +The interface itself can be configured with +.Xr wg 8 . +.Pp +The following glossary provides a brief overview of WireGuard +terminology: +.Bl -tag -width indent -offset 3n +.It Peer +Peers exchange IPv4 or IPv6 traffic over secure tunnels. +Each +.Nm +interface may be configured to recognize one or more peers. +.It Key +Each peer uses its private key and corresponding public key to +identify itself to others. +A peer configures a +.Nm +interface with its own private key and with the public keys of its peers. +.It Pre-shared key +In addition to the public keys, each peer pair may be configured with a +unique pre-shared symmetric key. +This is used in their handshake to guard against future compromise of the +peers' encrypted tunnel if an attack on their +Diffie-Hellman exchange becomes feasible. +It is optional, but recommended. +.It Allowed IP addresses +A single +.Nm +interface may maintain concurrent tunnels connecting diverse networks. +The interface therefore implements rudimentary routing and reverse-path +filtering functions for its tunneled traffic. +These functions reference a set of allowed IP address ranges configured +against each peer. +.Pp +The interface will route outbound tunneled traffic to the peer configured +with the most specific matching allowed IP address range, or drop it +if no such match exists. +.Pp +The interface will accept tunneled traffic only from the peer +configured with the most specific matching allowed IP address range +for the incoming traffic, or drop it if no such match exists. +That is, tunneled traffic routed to a given peer cannot return through +another peer of the same +.Nm +interface. +This ensures that peers cannot spoof one another's traffic. +.It Handshake +Two peers handshake to mutually authenticate each other and to +establish a shared series of secret ephemeral encryption keys. +Either peer may initiate a handshake. +Handshakes occur only when there is traffic to send, and recur every +two minutes during transfers. +.It Connectionless +Due to the handshake behavior, there is no connected or disconnected +state. +.El +.Ss Keys +Private keys for WireGuard can be generated from any sufficiently +secure random source. +The Curve25519 keys and the pre-shared keys are both 32 bytes +long and are commonly encoded in base64 for ease of use. +.Pp +Keys can be generated with +.Xr wg 8 +as follows: +.Pp +.Dl $ wg genkey +.Pp +Although a valid Curve25519 key must have 5 bits set to +specific values, this is done by the interface and so it +will accept any random 32-byte base64 string. +.Sh NETMAP +.Xr netmap 4 +applications may open a WireGuard interface in emulated mode. +The netmap application will receive decrypted, unencapsulated packets prepended +by a dummy Ethernet header. +The Ethertype field will be one of +.Dv ETHERTYPE_IP +or +.Dv ETHERTYPE_IPV6 +depending on the address family of the packet. +Packets transmitted by the application should similarly begin with a dummy +Ethernet header; this header will be stripped before the packet is encrypted +and tunneled. +.Sh EXAMPLES +Create a +.Nm +interface and set random private key. +.Bd -literal -offset indent +# ifconfig wg0 create +# wg genkey | wg set wg0 listen-port 54321 private-key /dev/stdin +.Ed +.Pp +Retrieve the associated public key from a +.Nm +interface. +.Bd -literal -offset indent +$ wg show wg0 public-key +.Ed +.Pp +Connect to a specific endpoint using its public-key and set the allowed IP address +.Bd -literal -offset indent +# wg set wg0 peer '7lWtsDdqaGB3EY9WNxRN3hVaHMtu1zXw71+bOjNOVUw=' endpoint 10.0.1.100:54321 allowed-ips 192.168.2.100/32 +.Ed +.Pp +Remove a peer +.Bd -literal -offset indent +# wg set wg0 peer '7lWtsDdqaGB3EY9WNxRN3hVaHMtu1zXw71+bOjNOVUw=' remove +.Ed +.Sh DIAGNOSTICS +The +.Nm +interface supports runtime debugging, which can be enabled with: +.Pp +.D1 Ic ifconfig Cm wg Ns Ar N Cm debug +.Pp +Some common error messages include: +.Bl -diag +.It "Handshake for peer X did not complete after 5 seconds, retrying" +Peer X did not reply to our initiation packet, for example because: +.Bl -bullet +.It +The peer does not have the local interface configured as a peer. +Peers must be able to mutually authenticate each other. +.It +The peer endpoint IP address is incorrectly configured. +.It +There are firewall rules preventing communication between hosts. +.El +.It "Invalid handshake initiation" +The incoming handshake packet could not be processed. +This is likely due to the local interface not containing +the correct public key for the peer. +.It "Invalid initiation MAC" +The incoming handshake initiation packet had an invalid MAC. +This is likely because the initiation sender has the wrong public key +for the handshake receiver. +.It "Packet has unallowed src IP from peer X" +After decryption, an incoming data packet has a source IP address that +is not assigned to the allowed IPs of Peer X. +.El +.Sh SEE ALSO +.Xr inet 4 , +.Xr ip 4 , +.Xr ipsec 4 , +.Xr netintro 4 , +.Xr netmap 4 , +.Xr ovpn 4 , +.Xr ipf 5 , +.Xr pf.conf 5 , +.Xr ifconfig 8 , +.Xr ipfw 8 , +.Xr wg 8 +.Rs +.%T WireGuard whitepaper +.%U https://www.wireguard.com/papers/wireguard.pdf +.Re +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 13.2 . +.Sh AUTHORS +.An -nosplit +The +.Nm +device driver was written by +.An Jason A. Donenfeld Aq Mt Jason@zx2c4.com , +.An Matt Dunwoodie Aq Mt ncon@nconroy.net , +.An Kyle Evans Aq Mt kevans@FreeBSD.org , +and +.An Matt Macy Aq Mt mmacy@FreeBSD.org . +.Pp +This manual page was written by +.An Gordon Bergling Aq Mt gbe@FreeBSD.org +and is based on the +.Ox +manual page written by +.An David Gwynne Aq Mt dlg@openbsd.org . diff --git a/static/freebsd/man4/witness.4 b/static/freebsd/man4/witness.4 new file mode 100644 index 00000000..9016da3b --- /dev/null +++ b/static/freebsd/man4/witness.4 @@ -0,0 +1,229 @@ +.\" Copyright (c) 2001 John H. Baldwin +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 26, 2026 +.Dt WITNESS 4 +.Os +.Sh NAME +.Nm witness +.Nd lock validation facility +.Sh SYNOPSIS +.Cd options WITNESS +.Cd options WITNESS_COUNT +.Cd options WITNESS_KDB +.Cd options WITNESS_NO_VNODE +.Cd options WITNESS_SKIPSPIN +.Sh DESCRIPTION +The +.Nm +module keeps track of the locks acquired and released by each thread. +It also keeps track of the order in which locks are acquired with respect +to each other. +Each time a lock is acquired, +.Nm +uses these two lists to verify that a lock is not being acquired in the +wrong order. +If a lock order violation is detected, then a message is output to the +kernel console or log detailing the locks involved and the locations in +question. +Witness can also be configured to drop into the kernel debugger when an order +violation occurs. +.Pp +The +.Nm +code also checks various other conditions such as verifying that one +does not recurse on a non-recursive lock, +or attempt an upgrade on a shared lock held by another thread. +If any of these checks fail, then the kernel will panic. +.Pp +The +.Dv WITNESS_COUNT +kernel option controls the maximum number of +.Nm +entries that are tracked in the kernel. +The maximum number of entries can be queried via the +.Va debug.witness.witness_count +sysctl. +It can also be set from the +.Xr loader 8 +via the +.Va debug.witness.witness_count +environment variable. +.Pp +The +.Dv WITNESS_NO_VNODE +kernel option tells +.Nm +to ignore locking issues between +.Xr vnode 9 +objects. +.Pp +The flag that controls whether or not the kernel debugger is entered when a +lock order violation is detected can be set in a variety of ways. +By default, the flag is off, but if the +.Dv WITNESS_KDB +kernel option is +specified, then the flag will default to on. +It can also be set from the +.Xr loader 8 +via the +.Va debug.witness.kdb +environment variable or after the kernel has booted via the +.Va debug.witness.kdb +sysctl. +If the flag is set to zero, then the debugger will not be entered. +If the flag is non-zero, then the debugger will be entered. +.Pp +The +.Nm +code can also be configured to skip all checks on spin mutexes. +By default, this flag defaults to off, but it can be turned on by +specifying the +.Dv WITNESS_SKIPSPIN +kernel option. +The flag can also be set via the +.Xr loader 8 +environment variable +.Va debug.witness.skipspin . +If the variable is set to a non-zero value, then spin mutexes are skipped. +Once the kernel has booted, the status of this flag can be examined but not +set via the read-only sysctl +.Va debug.witness.skipspin . +.Pp +The sysctl +.Va debug.witness.watch +specifies the level of witness involvement in the system. +A value of 1 specifies that witness is enabled. +A value of 0 specifies that witness is disabled, but that can be enabled +again. +This will maintain a small amount of overhead in the system. +A value of -1 specifies that witness is disabled permanently and +cannot be enabled again. +The sysctl +.Va debug.witness.watch +can be set via +.Xr loader 8 . +.Pp +The sysctl +.Va debug.witness.trace +controls whether +.Nm +prints stack traces when it detects lock violations. +A value of 0 disables stack printing. +A value of 1 specifies that +.Nm +should print a stack trace when a lock hierarchy violation occurs or +non-sleepable locks are held when going to sleep or acquiring a sleepable lock. +A value of 2 specifies that +.Nm +should attempt to display all observed lock chains that contribute to the +established lock order, along with stack traces for when those locks were +first acquired. +The sysctl +.Va debug.witness.trace +can be set via +.Xr loader 8 . +.Pp +The sysctl +.Va debug.witness.output_channel +specifies the output channel used to display warnings emitted by +.Nm . +The possible values are +.Ql console , +indicating that warnings are to be printed to the system console, +.Ql log , +indicating that warnings are to be logged via +.Xr log 9 , +and +.Ql none . +This sysctl can be set via +.Xr loader 8 . +.Pp +The sysctl +.Va debug.witness.badstacks +displays a listing of detected lock order violations cached in the +.Nm +module's current view of the lock hierarchy. +(This means that it may not display information for locks which have been +destroyed.) +It displays a similar level of detail to the messages produced by the run-time +checks. +However, it always tries to show all observed lock chains that contribute to the +established lock order. +(In other words, it acts like +.Va debug.witness.trace +was set to 2.) +It uses '**' to mark lock orders which were attempted but not added to the +hierarchy because they violated the hierarchy the +.Nm +code had previously observed. +.Pp +The +.Nm +code also provides a few extra +.Xr ddb 4 +commands if both +.Nm +and +.Xr ddb 4 +are compiled into the kernel: +.Bl -ohang +.It Ic show locks Op thread +Outputs the list of locks held by a thread to the kernel console +along with the filename and line number at which each lock was last acquired +by the thread. +The optional +.Ar thread +argument may be either a TID, +PID, +or pointer to a thread structure. +If +.Ar thread +is not specified, +then the locks held by the current thread are displayed. +.It Ic show all locks +Outputs the list of locks held by all threads in the system to the +kernel console. +.It Ic show witness +Dumps the current order list to the kernel console. +The code first displays the lock order tree for all of the sleep locks. +Then it displays the lock order tree for all of the spin locks. +Finally, it displays a list of locks that have not yet been acquired. +.It Ic show badstacks +Displays a listing of all WITNESS lock order violations. +This listing is identical to that produced by the +.Va debug.witness.badstacks +sysctl. +.El +.Sh SEE ALSO +.Xr ddb 4 , +.Xr loader 8 , +.Xr sysctl 8 , +.Xr mutex 9 +.Sh HISTORY +The +.Nm +code first appeared in +.Bsx 5.0 +and was imported from there into +.Fx 5.0 . diff --git a/static/freebsd/man4/wlan.4 b/static/freebsd/man4/wlan.4 new file mode 100644 index 00000000..ff983c66 --- /dev/null +++ b/static/freebsd/man4/wlan.4 @@ -0,0 +1,221 @@ +.\" +.\" Copyright (c) 2003 Tom Rhodes +.\" 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 June 13, 2025 +.Dt WLAN 4 +.Os +.Sh NAME +.Nm wlan +.Nd generic WiFi 802.11 link-layer support +.Sh SYNOPSIS +.Cd "device wlan" +.Sh DESCRIPTION +The +.Nm +module provides generic code to support 802.11 drivers. +Where a device does not directly support 802.11 functionality +this layer fills in. +The +.Nm +module is required by all native 802.11 drivers. +.Pp +.Nm +supports multi-mode devices capable of +operating in both 2.4GHz and 5GHz bands and supports numerous +802.11 standards: 802.11a, 802.11b, 802.11g, 802.11n, 802.11ac, and 802.11s (Draft 3.0). +The WPA, 802.11i, and 802.1x security protocols are supported +through a combination of in-kernel code and user-mode applications. +The WME/WMM multi-media protocols are supported entirely within +the +.Nm +module but require a suitably capable hardware device. +Likewise the 802.11h specification is supported only by suitably +capable devices. +.Pp +Drivers provide 802.11 functionality through +.Nm +interfaces that are created at runtime using interface cloning. +This is done with the +.Xr ifconfig 8 +.Cm create +command or using the +.Va wlans_IFX +variable in +.Xr rc.conf 5 . +Some drivers support the creation of multiple +.Nm +interfaces that share the same underlying device; +this is the way by which ``multi-bss support'' is provided but it +can also be used to create WDS links and other interesting applications. +.Pp +There are several types of +.Nm +interfaces that may be created: +.Bl -tag -width monitor +.It Cm sta +A client station in an infrastructure bss +(i.e. one that associates to an access point). +.It Cm hostap +An access point in an infrastructure bss. +.It Cm mesh +A mesh station in an MBSS network. +.It Cm adhoc +A station in an IBSS network. +.It Cm ahdemo +A station operating in ``adhoc demo mode''. +This is essentially an IBSS station that does not use management +frames (e.g. no beacons are transmitted). +An +.Cm ahdemo +interface is especially useful for applications that want to transmit +and receive raw 802.11 packets. +.It Cm monitor +An interface used exclusively for capturing 802.11 frames. +In particular this specified to have read-only properties +which enables it to be operated on frequencies where one +would otherwise not be allowed. +.It Cm wds +A station that passes 4-address 802.11 traffic for the purpose +of tunneling traffic over a wireless link. +Typically this station would share the same MAC address as a +.Cm hostap +interface. +It may be possible to create +.Cm wds +interfaces without a companion +.Cm hostap +interface but that is not guaranteed; one may need to create a +.Cm hostap +interface that does not send beacon frames before +.Cm wds +interfaces may be created. +.El +.Pp +Note that an interface's type cannot be changed once it is created. +.Pp +.Nm +defines several mechanisms by which plugin modules may +be used to extend its functionality. +Cryptographic support such as WEP, TKIP, and AES-CCMP are implemented +as standalone modules (if not statically configured into a system) +that register with +.Nm . +Similarly there is an authenticator framework for defining 802.11 +authentication services and a framework for integrating access +control mechanisms specific to the 802.11 protocol. +.Sh DEBUGGING +If the +.Dv IEEE80211_DEBUG +option is included in the kernel configuration, +debugging controls are available using: +.Pp +.Dl "sysctl net.wlan.X.debug=mask" +.Pp +where +.Ar X +is the number of the +.Nm +instance and mask is a bit-or of control bits that determine which +debugging messages to enable. +For example, +.Pp +.Dl "sysctl net.wlan.0.debug=0x00200000" +.Pp +enables debugging messages related to scanning for an access point, +adhoc neighbor, or an unoccupied channel when operation as an access point. +The +.Xr wlandebug 8 +tool provides a more user-friendly mechanism for doing the same thing. +Note that +.Pp +.Dl "sysctl net.wlan.debug=mask" +.Pp +defines the initial value of the debugging flags for each cloned +.Nm +interface; this is useful to enable debug messages during interface creation. +.Sh COMPATIBILITY +The module name of +.Nm +was used to be compatible with +.Nx . +.Pp +Mesh stations follow the 802.11s Draft 3.0 specification which is +not ratified and subject to change. +Be aware that this specification is incompatible with earlier drafts. +Stations implementing earlier drafts (e.g., Linux) may be incompatible. +.Sh SEE ALSO +.Xr ath 4 , +.Xr bwi 4 , +.Xr bwn 4 , +.Xr ipw 4 , +.Xr iwi 4 , +.Xr iwlwifi 4 , +.Xr iwm 4 , +.Xr iwn 4 , +.Xr iwx 4 , +.Xr malo 4 , +.Xr mwl 4 , +.Xr netintro 4 , +.Xr otus 4 , +.Xr ral 4 , +.Xr rsu 4 , +.Xr rtw88 4 , +.Xr rtw89 4 , +.Xr rtwn 4 , +.Xr rum 4 , +.Xr run 4 , +.Xr uath 4 , +.Xr upgt 4 , +.Xr ural 4 , +.Xr urtw 4 , +.Xr wlan_acl 4 , +.Xr wlan_ccmp 4 , +.Xr wlan_gcmp 4 , +.Xr wlan_tkip 4 , +.Xr wlan_wep 4 , +.Xr wlan_xauth 4 , +.Xr wpi 4 , +.Xr zyd 4 +.Sh STANDARDS +More information can be found in the IEEE 802.11 Standards. +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 5.0 . +.Sh AUTHORS +Atsushi Onoe is the author of original +.Nx +software from which this work began. +.An -nosplit +.An Sam Leffler +brought the code into +.Fx +and then rewrote it to support multi-mode devices, +802.11g, 802.11n, WPA/802.11i, WME, multi-bss, and +add the extensible frameworks +for cryptographic, authentication, and access control plugins. +This manual page was written by +.An Tom Rhodes Aq Mt trhodes@FreeBSD.org . diff --git a/static/freebsd/man4/wlan_acl.4 b/static/freebsd/man4/wlan_acl.4 new file mode 100644 index 00000000..0cd5c16a --- /dev/null +++ b/static/freebsd/man4/wlan_acl.4 @@ -0,0 +1,55 @@ +.\" +.\" Copyright (c) 2004 Sam Leffler +.\" 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 December 7, 2004 +.Dt WLAN_ACL 4 +.Os +.Sh NAME +.Nm wlan_acl +.Nd MAC-based ACL support for 802.11 devices +.Sh SYNOPSIS +.Cd "device wlan_acl" +.Sh DESCRIPTION +The +.Nm +module implements a MAC-based access control plugin for use +with 802.11 devices operating as an access point. +The +.Nm +must be loaded for +.Xr ifconfig 8 +to handle the +.Cm mac:* +requests. +.Sh SEE ALSO +.Xr wlan 4 , +.Xr ifconfig 8 +.Sh STANDARDS +More information can be found in the IEEE 802.11 Standard. +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 6.0 . diff --git a/static/freebsd/man4/wlan_amrr.4 b/static/freebsd/man4/wlan_amrr.4 new file mode 100644 index 00000000..4b7830b0 --- /dev/null +++ b/static/freebsd/man4/wlan_amrr.4 @@ -0,0 +1,57 @@ +.\" +.\" Copyright (c) 2007 Kevin Lo +.\" 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 April 13, 2008 +.Dt WLAN_AMRR 4 +.Os +.Sh NAME +.Nm wlan_amrr +.Nd AMRR rate adaptation algorithm support for 802.11 devices +.Sh SYNOPSIS +.Cd "device wlan_amrr" +.Sh DESCRIPTION +The +.Nm +module implements the Adaptive Multi-Rate Retry tx rate control +algorithm for use by 802.11 device drivers. +.Sh SEE ALSO +.Xr bwi 4 , +.Xr iwn 4 , +.Xr ral 4 , +.Xr rum 4 , +.Xr ural 4 , +.Xr wlan 4 , +.Xr wpi 4 , +.Xr zyd 4 +.Sh STANDARDS +More information can be found in the paper describing the +.Em AMRR +algorithm at +.Pa http://hal.inria.fr/inria-00070784/en/ . +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 6.0 . diff --git a/static/freebsd/man4/wlan_ccmp.4 b/static/freebsd/man4/wlan_ccmp.4 new file mode 100644 index 00000000..ffd4da86 --- /dev/null +++ b/static/freebsd/man4/wlan_ccmp.4 @@ -0,0 +1,65 @@ +.\" +.\" Copyright (c) 2004 Sam Leffler +.\" 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 December 7, 2004 +.Dt WLAN_CCMP 4 +.Os +.Sh NAME +.Nm wlan_ccmp +.Nd AES-CCMP crypto support for 802.11 devices +.Sh SYNOPSIS +.Cd "device wlan_ccmp" +.Sh DESCRIPTION +The +.Nm +module handles the AES-CCMP cryptographic requirements of the +WPA and 802.11i protocols. +It does encapsulation and decapsulation of CCMP-encoded 802.11 frames +and optionally calculates the AES-CCMP cipher. +The +.Nm +module is an 802.11 cryptographic plugin module for use by the +.Xr wlan 4 +module. +This module is automatically loaded if an AES-CCMP key is configured; +typically by a WPA supplicant program such as wpa_supplicant, +or a WPA authenticator program such as +.Nm hostapd . +Should the underlying network device not be capable of doing the AES-CCMP +calculations in hardware, the +.Nm +module will do the work. +.Sh SEE ALSO +.Xr wlan 4 , +.Xr wlan_gcmp 4 , +.Xr wlan_tkip 4 , +.Xr wlan_wep 4 +.Sh STANDARDS +More information can be found in the IEEE 802.11, WPA, and 802.11i Standards. +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 6.0 . diff --git a/static/freebsd/man4/wlan_gcmp.4 b/static/freebsd/man4/wlan_gcmp.4 new file mode 100644 index 00000000..a7657a9a --- /dev/null +++ b/static/freebsd/man4/wlan_gcmp.4 @@ -0,0 +1,72 @@ +.\" +.\" Copyright (c) 2004 Sam Leffler +.\" All rights reserved. +.\" Copyright (c) 2025 The FreeBSD Foundation +.\" +.\" Portions of this documentation were written by Bj\xc3\xb6rn Zeeb +.\" under sponsorship from the FreeBSD Foundation. +.\" +.\" 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. +.\" +.\" Based on wlan_ccmp.4. +.\" +.Dd June 13, 2025 +.Dt WLAN_GCMP 4 +.Os +.Sh NAME +.Nm wlan_gcmp +.Nd AES-GCMP crypto support for 802.11 devices +.Sh SYNOPSIS +.Cd "device wlan_gcmp" +.Sh DESCRIPTION +The +.Nm +module handles the +.Em Galois/Counter Mode Protocol +cryptographic requirements of the IEEE 802.11ad and WPA2/WPA3 protocols. +It does encapsulation and decapsulation of GCMP-encoded 802.11 frames +and optionally calculates the AES-GCMP cipher. +The +.Nm +module is an 802.11 cryptographic plugin module for use by the +.Xr wlan 4 +module. +This module is automatically loaded if an AES-GCMP key is configured; +typically by a WPA supplicant program such as wpa_supplicant, +or a WPA authenticator program such as +.Nm hostapd . +Should the underlying network device not be capable of doing the AES-GCMP +calculations in hardware, the +.Nm +module will do the work. +.Sh SEE ALSO +.Xr wlan 4 , +.Xr wlan_ccmp 4 , +.Xr wlan_tkip 4 , +.Xr wlan_wep 4 +.Sh STANDARDS +More information can be found in the IEEE 802.11, and WPA Standards. +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 15.0 . diff --git a/static/freebsd/man4/wlan_tkip.4 b/static/freebsd/man4/wlan_tkip.4 new file mode 100644 index 00000000..e74c24d4 --- /dev/null +++ b/static/freebsd/man4/wlan_tkip.4 @@ -0,0 +1,65 @@ +.\" +.\" Copyright (c) 2004 Sam Leffler +.\" 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 December 7, 2004 +.Dt WLAN_TKIP 4 +.Os +.Sh NAME +.Nm wlan_tkip +.Nd TKIP and Michael crypto support for 802.11 devices +.Sh SYNOPSIS +.Cd "device wlan_tkip" +.Sh DESCRIPTION +The +.Nm +module handles the TKIP and Michael cryptographic requirements of the +WPA and 802.11i protocols. +It does encapsulation and decapsulation of TKIP-encoded 802.11 frames +and optionally calculates the TKIP cipher and Michael MIC. +The +.Nm +module is an 802.11 cryptographic plugin module for use by the +.Xr wlan 4 +module. +This module is automatically loaded if a TKIP key is configured; +typically by a WPA supplicant program such as wpa_supplicant, +or a WPA authenticator program such as +.Nm hostapd . +Should the underlying network device not be capable of doing the TKIP +and/or Michael calculations in hardware, the +.Nm +module will do the work. +.Sh SEE ALSO +.Xr wlan 4 , +.Xr wlan_ccmp 4 , +.Xr wlan_gcmp 4 , +.Xr wlan_wep 4 +.Sh STANDARDS +More information can be found in the IEEE 802.11, WPA, and 802.11i Standards. +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 6.0 . diff --git a/static/freebsd/man4/wlan_wep.4 b/static/freebsd/man4/wlan_wep.4 new file mode 100644 index 00000000..d83ef23e --- /dev/null +++ b/static/freebsd/man4/wlan_wep.4 @@ -0,0 +1,62 @@ +.\" +.\" Copyright (c) 2004 Sam Leffler +.\" 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 December 7, 2004 +.Dt WLAN_WEP 4 +.Os +.Sh NAME +.Nm wlan_wep +.Nd WEP crypto support for 802.11 devices +.Sh SYNOPSIS +.Cd "device wlan_wep" +.Sh DESCRIPTION +The +.Nm +module handles the WEP cryptographic requirements of the 802.11 protocol. +It does encapsulation and decapsulation of WEP-encoded 802.11 frames +and optionally calculates the WEP cipher. +The +.Nm +module is an 802.11 cryptographic plugin module for use by the +.Xr wlan 4 +module. +This module is automatically loaded if a WEP key is configured with +.Xr ifconfig 8 . +Should the underlying network device not be capable of doing the WEP +calculations in hardware, the +.Nm +module will do the work. +.Sh SEE ALSO +.Xr wlan 4 , +.Xr wlan_ccmp 4 , +.Xr wlan_gcmp 4 , +.Xr wlan_tkip 4 +.Sh STANDARDS +More information can be found in the IEEE 802.11 Standard. +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 6.0 . diff --git a/static/freebsd/man4/wlan_xauth.4 b/static/freebsd/man4/wlan_xauth.4 new file mode 100644 index 00000000..9c89648d --- /dev/null +++ b/static/freebsd/man4/wlan_xauth.4 @@ -0,0 +1,59 @@ +.\" +.\" Copyright (c) 2004 Sam Leffler +.\" 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 December 7, 2004 +.Dt WLAN_XAUTH 4 +.Os +.Sh NAME +.Nm wlan_xauth +.Nd External authenticator support for 802.11 devices +.Sh SYNOPSIS +.Cd "device wlan_xauth" +.Sh DESCRIPTION +The +.Nm +module is a +.Xr wlan 4 +authenticator plugin +for use with user-mode authentication implementations such +as +.Nm hostapd . +It hooks into the 802.11 layer and does nothing. +As a result, 802.11 stations that associate are not authorized to +send or receive frames until they are authorized by an external agent; +typically using a protocol such as WPA, 802.1x, or 802.11i. +.Pp +This module is automatically loaded by the rc script that normally +starts +.Xr hostapd 8 . +.Sh SEE ALSO +.Xr wlan 4 +.Sh STANDARDS +More information can be found in the IEEE 802.11, WPA, and 802.11i Standards. +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 6.0 . diff --git a/static/freebsd/man4/wmt.4 b/static/freebsd/man4/wmt.4 new file mode 100644 index 00000000..b9320371 --- /dev/null +++ b/static/freebsd/man4/wmt.4 @@ -0,0 +1,79 @@ +.\" Copyright (c) 2014-2017 Vladimir Kondratyev +.\" 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 August 19, 2017 +.Dt WMT 4 +.Os +.Sh NAME +.Nm wmt +.Nd MS Windows 7/8/10 - compatible USB HID multi-touch device driver +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines into +your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device wmt" +.Cd "device usb" +.Cd "device hid" +.Cd "device evdev" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +wmt_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the MS Windows 7/8/10 - compatible USB HID +multi-touch devices found in many laptops. +.Pp +To get multi-touch device working in +.Xr X 7 Pq Pa ports/x11/xorg-docs , +install +.Pa ports/x11-drivers/xf86-input-evdev . +.Sh FILES +.Nm +creates a pseudo-device file, +.Pa /dev/input/eventX +which presents the multi-touch device as an input event device. +.Sh SEE ALSO +.Xr usb 4 , +.Xr loader.conf 5 , +.Xr xorg.conf 5 Pq Pa ports/x11/xorg , +.Xr evdev 4 Pq Pa ports/x11-drivers/xf86-input-evdev . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org . +.Sh BUGS +.Nm +cannot act like +.Xr sysmouse 4 , +as +.Xr sysmouse 4 +does not support absolute motion events. diff --git a/static/freebsd/man4/wpi.4 b/static/freebsd/man4/wpi.4 new file mode 100644 index 00000000..9d8d5fb1 --- /dev/null +++ b/static/freebsd/man4/wpi.4 @@ -0,0 +1,216 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2004-2007 +.\" Damien Bergamini . All rights reserved. +.\" Benjamin Close . All rights reserved. +.\" Copyright (c) 2016 Andriy Voskoboinyk +.\" 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 unmodified, 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 October 17, 2024 +.Dt WPI 4 +.Os +.Sh NAME +.Nm wpi +.Nd Intel PRO/Wireless 3945ABG IEEE 802.11a/b/g network driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device wpi" +.Cd "device wpifw" +.Cd "device pci" +.Cd "device wlan" +.Cd "device wlan_amrr" +.Cd "device firmware" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Pp +.Dl if_wpi_load="YES" +.Sh DESCRIPTION +The +.Nm +driver supports running the +Intel PRO/Wireless 3945ABG network adapter in +.Cm station , +.Cm adhoc , +.Cm adhoc-demo , +.Cm hostap , +and +.Cm monitor +mode operation. +This driver requires the wpifw firmware module +and can be configured at runtime with +.Xr ifconfig 8 +or at boot in +.Xr rc.conf 5 . +Only one virtual interface may be configured at any time. +.Pp +The +.Nm +driver can be configured to use +Wired Equivalent Privacy (WEP) or +Wi-Fi Protected Access (WPA-PSK and WPA2-PSK). +WPA is the de facto encryption standard for wireless networks. +It is strongly recommended that WEP +not be used as the sole mechanism +to secure wireless communication, +due to serious weaknesses in it. +The +.Nm +driver offloads both encryption and decryption of data frames to the +hardware for the CCMP cipher. +.Sh HARDWARE +The +.Nm +driver provides support for the +Intel PRO/Wireless 3945ABG Mini PCIe network adapter. +.Sh FILES +.Bl -tag -width "/usr/share/doc/legal/intel_wpi.LICENSE" -compact +.It Pa /usr/share/doc/legal/intel_wpi.LICENSE +.Nm +firmware license +.El +.Sh EXAMPLES +Join an existing BSS network (i.e., connect to an access point): +.Bd -literal -offset indent +ifconfig wlan0 create wlandev wpi0 inet 192.168.0.20 \e + netmask 0xffffff00 +.Ed +.Pp +Join a specific BSS network with network name +.Ar my_net : +.Pp +.Dl "ifconfig wlan0 create wlandev wpi0 ssid my_net up" +.Pp +Join a specific BSS network with 64-bit WEP encryption: +.Bd -literal -offset indent +ifconfig wlan0 create wlandev wpi0 ssid my_net \e + wepmode on wepkey 0x1234567890 weptxkey 1 up +.Ed +.Pp +Create an IBSS network with 128-bit WEP encryption on the channel 4: +.Bd -literal -offset indent +ifconfig wlan0 create wlandev wpi0 wlanmode adhoc ssid my_net \e + wepmode on wepkey 0x01020304050607080910111213 weptxkey 1 \e + channel 4 +.Ed +.Pp +Join/create an 802.11b IBSS network with network name +.Ar my_net : +.Bd -literal -offset indent +ifconfig wlan0 create wlandev wpi0 wlanmode adhoc +ifconfig wlan0 inet 192.168.0.22 netmask 0xffffff00 ssid my_net \e + mode 11b +.Ed +.Pp +Create an 802.11g host-based access point: +.Bd -literal -offset indent +ifconfig wlan0 create wlandev wpi0 wlanmode hostap +ifconfig wlan0 inet 192.168.0.10 netmask 0xffffff00 ssid my_ap \e + mode 11g +.Ed +.Sh DIAGNOSTICS +.Bl -diag +.It "wpi%d: could not load firmware image '%s'" +The driver failed to load the firmware image using the +.Xr firmware 9 +subsystem. +Verify the wpifw firmware module is installed. +.It "wpi%d: %s: timeout waiting for adapter to initialize, error %d" +The onboard microcontroller failed to initialize in time. +This should not happen. +.It "wpi%d: %s: could not load boot firmware" +An attempt to upload the boot firmware image to the onboard microcontroller +failed. +This should not happen. +.It "wpi%d: device timeout" +A frame dispatched to the hardware for transmission did not complete in time. +The driver will reset the hardware and continue. +This should not happen. +.It "wpi%d: scan timeout" +Firmware scan command response was not received in time. +The driver will reset the hardware and continue. +This should not happen. +.It "wpi%d: fatal firmware error" +The onboard microcontroller crashed for some reason. +The driver will reset the hardware and continue. +This should not happen. +.It "wpi%d: RF switch: radio disabled" +The hardware switch controlling the radio is currently turned off. +Data transmission is not possible in this state. +.It "wpi%d: can't map mem space" +The driver was unable to map the device registers into the host address space. +This should not happen. +.It "wpi%d: can't map interrupt" +The driver was unable to allocate an IRQ for the device interrupt. +This should not happen. +.It "wpi%d: can't establish interrupt, error %d" +The driver was unable to install the device interrupt handler. +This should not happen. +.It "wpi%d: %s: bus_dmamap_load failed, error %d" +The driver was unable to map newly allocated mbuf to device +visible address space. +Contents of currently received frame will be lost. +This should not happen. +.El +.Sh SEE ALSO +.Xr pci 4 , +.Xr wlan 4 , +.Xr wlan_amrr 4 , +.Xr wlan_ccmp 4 , +.Xr wlan_tkip 4 , +.Xr wlan_wep 4 , +.Xr wlan_xauth 4 , +.Xr networking 7 , +.Xr hostapd 8 , +.Xr ifconfig 8 , +.Xr wpa_supplicant 8 +.Sh AUTHORS +.An -nosplit +The original +.Nm +driver was written for +.Ox +by +.An Damien Bergamini Aq Mt damien.bergamini@free.fr . +.An Benjamin Close Aq Mt benjsc@FreeBSD.org +ported +.Nm +to +.Fx . +.Sh CAVEATS +.Cm Hostap +mode is not directly supported by the device; +it is implemented through IBSS mode (as a result, DFS/passive +channels are not available in this mode). +.Pp +Powersave may be unstable on some networks +.Po results in occasional Sy 'wpi%d: device timeout' No messages Pc ; +you can try to disable it to improve device stability. diff --git a/static/freebsd/man4/wsp.4 b/static/freebsd/man4/wsp.4 new file mode 100644 index 00000000..50ada937 --- /dev/null +++ b/static/freebsd/man4/wsp.4 @@ -0,0 +1,219 @@ +.\" Copyright (c) 2014 Hans Petter Selasky . +.\" 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 February 9, 2021 +.Dt WSP 4 +.Os +.Sh NAME +.Nm wsp +.Nd Wellspring touchpad driver +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines into +your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device wsp" +.Cd "device hid" +.Cd "device usb" +.Ed +.Pp +Alternatively, to load the driver as a module at boot time, +place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +wsp_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for the Apple Internal Trackpad +device found in many Apple laptops. +.Pp +The driver simulates a three-button mouse using multi-finger press/tap +detection. +A single-finger press generates a left button click. +A two-finger press maps to the right button; whereas a three-finger +press gets treated as a middle button click. +.Pp +The trackpad functions with presses and taps. +A press is a full-forced +press which causes a physical lowering of the trackpad. +A tap is a +touch of the trackpad which does not depress the physical trackpad. +.Pp +The +.Nm +driver supports receiving evdev input device data if enabled. +This data +is used for extended usage of the touchpad like multi-finger support, +pressure detection, tap support, and gestures. +At least the second bit of the +.Xr sysctl 8 +tunable +.Va kern.evdev.rcpt_mask +must be set. +This can be enabled with +.Va kern.evdev.rcpt_mask=3 . +.Pp +Vertical scrolling (z-axis) is enabled by default with a two-finger +tap and the movement of a finger up and down. +Horizontal scrolling (t-axis) is not natively supported by the sysmouse +protocol, therefore must be enabled with evdev data. +This can be enabled with the +.Xr sysctl 8 +tunable +.Va kern.evdev.sysmouse_t_axis=3 . +Horizontal scrolling can be used with a two-finger tap and the movement +of a finger from side to side. +The +.Xr sysctl 8 +tunable +.Va hw.usb.wsp.t_factor +must be greater than 0 for horizontal scrolling to be enabled, too. +.Pp +Horizontal swiping with a three-finger tap is registered as mouse buttons +8 and 9, depending on the direction. +These buttons default to backwards and forwards keyboard events. +.Sh SYSCTL VARIABLES +The following variables are available as +.Xr sysctl 8 +tunables: +.Bl -tag -width indent +.It Va hw.usb.wsp.scale_factor +Controls the pointer sensitivity. +Default is 12. +.El +.Bl -tag -width indent +.It Va hw.usb.wsp.enable_single_tap_clicks +Enables single-tap to register as a left-click. +Default is 1 (enabled). +.El +.Bl -tag -width indent +.It Va hw.usb.wsp.enable_single_tap_movement +Enables movement on the trackpad follow a partially-released left-click. +Default is 1 (enabled). +.El +.Bl -tag -width indent +.It Va hw.usb.wsp.max_finger_diameter +Specifies the maximum finger diameter on the trackpad that is registered as a +finger (a lower value is used for palm detection). Default is 1900. +.El +.Bl -tag -width indent +.It Va max_scroll_finger_distance +Specifies the maximum distance between two fingers where z-axis +and t-axis movements are registered. +Z-axis and T-axis movements +are vertical and horizontal movements with more than one finger +tapped (not clicked), respectively. +Default is 8192. +.El +.Bl -tag -width indent +.It Va hw.usb.wsp.max_double_tap_distance +Specifies the maximum distance between two fingers that a two-finger +click will be registered as a right-click. +Default is 2500. +.El +.Bl -tag -width indent +.It Va hw.usb.wsp.scr_threshold +Specifies the minimum horizontal or vertical distance required to +register as a scrolling gesture. +Default is 20. +.El +.Bl -tag -width indent +.It Va hw.usb.wsp.z_factor +Z-axis sensitivity. +Default is 5. +.El +.Bl -tag -width indent +.It Va hw.usb.wsp.z_invert +Z-axis inversion. +Default is 0 (disabled). +.El +.Bl -tag -width indent +.It Va hw.usb.wsp.t_factor +T-axis sensitivity. +Default is 0 (disabled). +.El +.Bl -tag -width indent +.It Va hw.usb.wsp.t_invert +T-axis inversion. +Default is 0 (disabled). +.El +.Bl -tag -width indent +.It Va hw.usb.wsp.scroll_finger_count +Specifies the number of tapped fingers which registers as a scrolling +movement. +Default is 2. +.El +.Bl -tag -width indent +.It Va hw.usb.wsp.horizontal_swipe_finger_count +Speifies the number of tapped fingers which registers as a swipe +gesture. +Default is 3. +.El +.Bl -tag -width indent +.It Va hw.usb.wsp.pressure_touch_threshold +Specifies the threshold for a finger to be registered as a click. +Default is 50. +.El +.Bl -tag -width indent +.It Va hw.usb.wsp.pressure_untouch_threshold +Specifies the threshold for a finger to be registered as an unclick. +Default is 10. +.El +.Bl -tag -width indent +.It Va hw.usb.wsp.pressure_tap_threshold +Specifies the threadhold for a finger to be registered as a tap. +Default is 120. +.El +.Bl -tag -width indent +.It Va hw.usb.wsp.debug +Specifies the +.Nm +driver debugging level (0-3). +Default is 1. +.El +.Sh FILES +.Nm +creates a blocking pseudo-device file, +.Pa /dev/wsp0 , +which presents the mouse as a +.Em sysmouse +or +.Em mousesystems +type device--see +.Xr moused 8 +for an explanation of these mouse types. +.Sh SEE ALSO +.Xr sysmouse 4 , +.Xr usb 4 , +.Xr loader.conf 5 , +.Xr xorg.conf 5 Pq Pa ports/x11/xorg , +.Xr moused 8 , +.Xr sysctl 8 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Huang Wen Hui Aq Mt huanghwh@gmail.com . diff --git a/static/freebsd/man4/xb360gp.4 b/static/freebsd/man4/xb360gp.4 new file mode 100644 index 00000000..1ff42e97 --- /dev/null +++ b/static/freebsd/man4/xb360gp.4 @@ -0,0 +1,99 @@ +.\" Copyright (c) 2020 Vladimir Kondratyev +.\" +.\" 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 November 30, 2025 +.Dt XB360GP 4 +.Os +.Sh NAME +.Nm xb360gp +.Nd XBox 360 gamepad driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device xb360gp" +.Cd "device hgame" +.Cd "device hid" +.Cd "device hidbus" +.Cd "device hidmap" +.Cd "device evdev" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +xb360gp_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for XBox 360 gamepad driver. +.Pp +The +.Pa /dev/input/event* +device presents the game controller as a +.Ar evdev +type device. +It is accessible to members of the +.Em games +group. +.Sh SYSCTL VARIABLES +The following variable is available as both +.Xr sysctl 8 +variable and +.Xr loader 8 +tunable: +.Bl -tag -width indent +.It Va dev.xb360gp.X.debug +Debug output level, where 0 is debugging disabled and larger values increase +debug message verbosity. +Default is 0. +.El +.Pp +It's default value is set with +.Xr loader 8 +tunable: +.Bl -tag -width indent +.It Va hw.hid.xb360gp.debug +.El +.Sh FILES +.Bl -tag -width /dev/input/event* -compact +.It Pa /dev/input/event* +input event device node. +.El +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Val Packett Aq Mt val@packett.cool . +.Pp +This manual page was written by +.An Vladimir Kondratyev Aq Mt wulf@FreeBSD.org . diff --git a/static/freebsd/man4/xdma.4 b/static/freebsd/man4/xdma.4 new file mode 100644 index 00000000..674da75d --- /dev/null +++ b/static/freebsd/man4/xdma.4 @@ -0,0 +1,75 @@ +.\" Copyright (c) 2016 Ruslan Bukin +.\" All rights reserved. +.\" +.\" This software was developed by SRI International and the University of +.\" Cambridge Computer Laboratory under DARPA/AFRL contract FA8750-10-C-0237 +.\" ("CTSRD"), as part of the DARPA CRASH research programme. +.\" +.\" 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 December 12, 2016 +.Dt XDMA 4 +.Os +.Sh NAME +.Nm xdma +.Nd DMA abstraction layer +.Sh SYNOPSIS +To compile xDMA device support into the kernel, place the following line +in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device xdma" +.Ed +.Pp +To compile xDMA FDT-based test driver, place the following line as well: +.Bd -literal -offset indent +.Cd "device xdma_test" +.Ed +.Sh DESCRIPTION +xDMA is a DMA framework designed to abstract the interaction between device +drivers and DMA engines. +.Pp +xDMA defines an interface for efficient interaction between the device driver +and DMA controller. +The +.Nm +device provides a virtual DMA controller and virtual channels called xchans. +The controller provides virtual channels management (allocation, deallocation, +configuration) and interrupt notification esteblishment needed to receive +events from the hardware DMA controller. +.Nm +supports the following transfer types: +.Bl -hang -offset indent -width xxxxxxxx +.It Nm Cyclic +A non-stop periodic transfer designed for applications like audio. +.It Nm Memcpy +A memory-to-memory transfer. +.El +.Sh SEE ALSO +.Xr bus_dma 9 +.Sh HISTORY +Support for xDMA first appeared in +.Fx 12.0 . +.Sh AUTHORS +.An -nosplit +.Fx +xDMA framework was first added by +.An Ruslan Bukin Aq Mt br@FreeBSD.org . diff --git a/static/freebsd/man4/xen.4 b/static/freebsd/man4/xen.4 new file mode 100644 index 00000000..284b09bc --- /dev/null +++ b/static/freebsd/man4/xen.4 @@ -0,0 +1,138 @@ +.\" Copyright (c) 2010 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" This software was developed by SRI International and the University of +.\" Cambridge Computer Laboratory under DARPA/AFRL contract FA8750-10-C-0237 +.\" ("CTSRD"), as part of the DARPA CRASH research program. +.\" +.\" 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 AUTHORS 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 AUTHORS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 8, 2024 +.Dt XEN 4 +.Os +.Sh NAME +.Nm xen +.Nd Xen Hypervisor Support +.Sh SYNOPSIS +FreeBSD supports running both as a Xen guest and host on amd64 hardware. +Guest support is limited to HVM and PVH modes, while host support is limited to +PVH mode only. +.Pp +Xen support is built by default in the i386 and amd64 GENERIC kernels; note +however that host mode is only available on amd64. +.Sh DESCRIPTION +The Xen Hypervisor allows multiple virtual machines to be run on a single +computer system. +When first released, Xen required that i386 kernels be compiled +"para-virtualized" as the x86 instruction set was not fully virtualizable. +Primarily, para-virtualization modifies the virtual memory system to use +hypervisor calls (hypercalls) rather than direct hardware instructions to +modify the TLB, although para-virtualized device drivers were also required +to access resources such as virtual network interfaces and disk devices. +.Pp +With later instruction set extensions from AMD and Intel to support fully +virtualizable instructions, unmodified virtual memory systems can also be +supported; this is referred to as hardware-assisted virtualization (HVM and PVH). +HVM configurations may either rely on transparently emulated hardware +peripherals, or para-virtualized drivers, which are aware of virtualization, +and hence able to optimize certain behaviors to improve performance or +semantics. +PVH configurations rely on para-virtualized drivers exclusively for IO. +.Pp +.Fx +Para-virtualized device drivers are required in order to support certain +functionality, such as processing management requests, returning idle +physical memory pages to the hypervisor, etc. +.Ss Xen device drivers +These para-virtualized drivers are supported: +.Bl -hang -offset indent -width blkfront +.It Nm balloon +Allow physical memory pages to be returned to the hypervisor as a result of +manual tuning or automatic policy. +.It Nm blkback +Exports local block devices or files to other Xen domains where they can +then be imported via +.Nm blkfront . +.It Nm blkfront +Import block devices from other Xen domains as local block devices, to be +used for file systems, swap, etc. +.It Nm console +Export the low-level system console via the Xen console service. +.It Nm control +Process management operations from Domain 0, including power off, reboot, +suspend, crash, and halt requests. +.It Nm evtchn +Expose Xen events via the +.Pa /dev/xen/evtchn +special device. +.It Nm gntdev +Allow access to the grant table interface via the +.Pa /dev/xen/gntdev +special device. +.It Nm netback +Export local network interfaces to other Xen domains where they can be +imported via +.Nm netfront . +.It Nm netfront +Import network interfaces from other Xen domains as local network interfaces, +which may be used for IPv4, IPv6, etc. +.It Nm privcmd +Allow issuing hypercalls via the +.Pa /dev/xen/privcmd +special device. +.It Nm timer +Implementation of a one-shot high resolution per-CPU timer using the hypercall +interface. +.It Nm acpi cpu +When running as a host forwards power management related information from ACPI +to the hypervisor for better performance management. +.It Nm xenpci +Represents the Xen PCI device, an emulated PCI device that is exposed to +HVM domains. +This device allows detection of the Xen hypervisor, and provides interrupt +and shared memory services required to interact with the hypervisor. +.It Nm xenstore +Information storage space shared between domains. +.El +.Sh HISTORY +Support for +.Nm +first appeared in +.Fx 8.1 . +Support for host mode was added in 11.0 . +.Sh AUTHORS +.An -nosplit +.Fx +support for Xen was first added by +.An Kip Macy Aq Mt kmacy@FreeBSD.org +and +.An Doug Rabson Aq Mt dfr@FreeBSD.org . +Further refinements were made by +.An Justin Gibbs Aq Mt gibbs@FreeBSD.org , +.An Adrian Chadd Aq Mt adrian@FreeBSD.org , +.An Colin Percival Aq Mt cperciva@FreeBSD.org , +and +.An Roger Pau Monné Aq Mt royger@FreeBSD.org . +This manual page was written by +.An Robert Watson Aq Mt rwatson@FreeBSD.org , +and +.An Roger Pau Monné Aq Mt royger@FreeBSD.org . diff --git a/static/freebsd/man4/xhci.4 b/static/freebsd/man4/xhci.4 new file mode 100644 index 00000000..1f9aae5c --- /dev/null +++ b/static/freebsd/man4/xhci.4 @@ -0,0 +1,103 @@ +.\" +.\" Copyright (c) 2011-2022 Hans Petter Selasky. 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 October 21, 2022 +.Dt XHCI 4 +.Os +.Sh NAME +.Nm xhci +.Nd USB eXtensible Host Controller driver +.Sh SYNOPSIS +.Cd "options USB_DEBUG" +.Cd "device xhci" +.Sh DESCRIPTION +The +.Nm +driver provides support for the +.Tn USB +eXtensible Host Controller Interface, +which allows use of +.Tn USB +1.0, 2.0 and 3.0 devices on the same +.Tn USB +port. +.Pp +The +.Tn XHCI +controller supports +.Tn USB +connection speeds from 5.0Gbps and above when using USB 3.x +compliant devices. +.Sh HARDWARE +The +.Nm +driver supports +.Tn XHCI +compatible controllers having PCI class 12 (serial bus), +subclass 3 (USB) and programming interface 48 (XHCI). +.Sh SYSCTL VARIABLES +The following variables are available as both +.Xr sysctl 8 +variables and +.Xr loader 8 +tunables: +.Bl -tag -width indent +.It Va hw.usb.xhci.debug +Set debug output level, where 0 is debugging disabled and larger +values increase debug message verbosity. +The default value is 0. +.It Va hw.usb.xhci.dcepquirk +Set to enable quirk for deconfiguration of endpoints. +The default value is 0. +.It Va hw.usb.xhci.ctlquirk +Set to submit full USB control request as one job, up to 64kBytes. +Else the USB control request will be split into multiple smaller +requests. +The default value is 1. +.It Va hw.usb.xhci.streams +Set to enable USB streams support. +The default value is 0. +.It Va hw.usb.xhci.route +Set bitmap for switching EHCI ports to the XHCI controller. +The default value is 0. +.It Va hw.usb.xhci.polling +Set to use a timer to poll the interrupt handler. +The default value is 0. +.It Va hw.usb.xhci.dma32 +Set to only use 32-bit DMA for the XHCI controller. +The default value is 0. +.It Va hw.usb.xhci.ctlstep +Set to enable control endpoint status state stepping. +The default value is 0. +.El +.Sh SEE ALSO +.Xr ehci 4 , +.Xr ohci 4 , +.Xr uhci 4 and +.Xr usb 4 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 8.2 . diff --git a/static/freebsd/man4/xl.4 b/static/freebsd/man4/xl.4 new file mode 100644 index 00000000..591703ac --- /dev/null +++ b/static/freebsd/man4/xl.4 @@ -0,0 +1,267 @@ +.\" Copyright (c) 1997, 1998 +.\" Bill Paul . 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 Bill Paul. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Bill Paul 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 Bill Paul OR THE VOICES IN HIS HEAD +.\" 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 23, 2008 +.Dt XL 4 +.Os +.Sh NAME +.Nm xl +.Nd "3Com Etherlink XL and Fast Etherlink XL Ethernet device driver" +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device miibus" +.Cd "device xl" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_xl_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for PCI Ethernet adapters and embedded +controllers based on the 3Com "boomerang," "cyclone," "hurricane" +and "tornado" bus-master Etherlink XL chips. +.Pp +The Etherlink XL chips support built-in 10baseT, 10base2 and 10base5 +transceivers as well as an MII bus for externally attached PHY +transceivers. +The 3c905 series typically uses a National Semiconductor +NS 83840A 10/100 PHY for 10/100 Mbps support in full or half-duplex. +The 3c905B adapters have built-in autonegotiation logic mapped onto +the MII for compatibility with previous drivers. +Fast Etherlink XL +adapters such as the 3c905-TX and 3c905B-TX are capable of 10 or +100Mbps data rates in either full or half duplex and can be manually +configured for any supported mode or automatically negotiate the highest +possible mode with a link partner. +.Pp +The +.Nm +driver supports the following media types: +.Bl -tag -width xxxxxxxxxxxxxxxxxxxx +.It autoselect +Enable autoselection of the media type and options. +Note that this +option is only available with the 3c905 and 3c905B adapters with +external PHYs or built-in autonegotiation logic. +For 3c900 adapters, +the driver will choose the mode specified in the EEPROM. +The user can +change this by adding media options to the +.Pa /etc/rc.conf +file. +.It 10baseT/UTP +Set 10Mbps operation. +The +.Ar mediaopt +option can also be used to select either +.Ar full-duplex +or +.Ar half-duplex +modes. +.It 100baseTX +Set 100Mbps (Fast Ethernet) operation. +The +.Ar mediaopt +option can also be used to select either +.Ar full-duplex +or +.Ar half-duplex +modes. +.It 10base5/AUI +Enable AUI transceiver (available only on COMBO cards). +.It 10base2/BNC +Enable BNC coax transceiver (available only on COMBO cards). +.El +.Pp +The +.Nm +driver supports the following media options: +.Bl -tag -width xxxxxxxxxxxxxxxxxxxx +.It full-duplex +Force full duplex operation. +.It half-duplex +Force half duplex operation. +.El +.Pp +Note that the 100baseTX media type is only available if supported +by the adapter. +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The +.Nm +driver supports the following hardware: +.Pp +.Bl -bullet -compact +.It +3Com 3c900-TPO +.It +3Com 3c900-COMBO +.It +3Com 3c905-TX +.It +3Com 3c905-T4 +.It +3Com 3c900B-TPO +.It +3Com 3c900B-TPC +.It +3Com 3c900B-FL +.It +3Com 3c900B-COMBO +.It +3Com 3c905B-T4 +.It +3Com 3c905B-TX +.It +3Com 3c905B-FX +.It +3Com 3c905B-COMBO +.It +3Com 3c905C-TX +.It +3Com 3c980, 3c980B, and 3c980C server adapters +.It +3Com 3cSOHO100-TX OfficeConnect adapters +.It +3Com 3c450 HomeConnect adapters +.It +3Com 3c555, 3c556 and 3c556B mini-PCI adapters +.It +3Com 3C3SH573BT, 3C575TX, 3CCFE575BT, 3CXFE575BT, 3CCFE575CT, 3CXFE575CT, +3CCFEM656, 3CCFEM656B, and 3CCFEM656C, 3CXFEM656, 3CXFEM656B, and +3CXFEM656C CardBus adapters +.It +3Com 3c905-TX, 3c905B-TX 3c905C-TX, 3c920B-EMB, and 3c920B-EMB-WNM embedded adapters +.El +.Pp +Both the 3C656 family of CardBus cards and the 3C556 family of MiniPCI +cards have a built-in proprietary modem. +Neither the +.Nm +driver nor any other +.Fx +driver supports this modem. +.Sh DIAGNOSTICS +.Bl -diag +.It "xl%d: couldn't map memory" +A fatal initialization error has occurred. +.It "xl%d: couldn't map interrupt" +A fatal initialization error has occurred. +.It "xl%d: device timeout" +The device has stopped responding to the network, or there is a problem with +the network connection (cable). +.It "xl%d: no memory for rx list" +The driver failed to allocate an mbuf for the receiver ring. +.It "xl%d: no memory for tx list" +The driver failed to allocate an mbuf for the transmitter ring when +allocating a pad buffer or collapsing an mbuf chain into a cluster. +.It "xl%d: command never completed!" +Some commands issued to the 3c90x ASIC take time to complete: the +driver is supposed to wait until the 'command in progress' bit in +the status register clears before continuing. +In rare instances, this +bit may not clear. +To avoid getting caught in an infinite wait loop, +the driver only polls the bit for a finite number of times before +giving up, at which point it issues this message. +This message may +be printed during driver initialization on slower machines. +If you +see this message but the driver continues to function normally, the +message can probably be ignored. +.It "xl%d: chip is in D3 power state -- setting to D0" +This message applies only to 3c905B adapters, which support power +management. +Some operating systems place the 3c905B in low power +mode when shutting down, and some PCI BIOSes fail to bring the chip +out of this state before configuring it. +The 3c905B loses all of +its PCI configuration in the D3 state, so if the BIOS does not set +it back to full power mode in time, it will not be able to configure it +correctly. +The driver tries to detect this condition and bring +the adapter back to the D0 (full power) state, but this may not be +enough to return the driver to a fully operational condition. +If +you see this message at boot time and the driver fails to attach +the device as a network interface, you will have to perform second +warm boot to have the device properly configured. +.Pp +Note that this condition only occurs when warm booting from another +operating system. +If you power down your system prior to booting +.Fx , +the card should be configured correctly. +.It "xl%d: WARNING: no media options bits set in the media options register!" +This warning may appear when using the driver on some Dell Latitude +docking stations with built-in 3c905-TX adapters. +For whatever the +reason, the 'MII available' bit in the media options register on +this particular equipment is not set, even though it should be (the +3c905-TX always uses an external PHY transceiver). +The driver will +attempt to guess the proper media type based on the PCI device ID +word. +The driver makes a lot of noise about this condition because +the author considers it a manufacturing defect. +.It xl%d: transmission error: %d +.It xl%d: tx underrun, increasing tx start threshold to %d bytes +This message may appear while the adapter tunes its transmission +buffers under various load amounts and are mostly harmless. +It is probably safe to ignore them. +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr arp 4 , +.Xr cardbus 4 , +.Xr miibus 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr polling 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 3.0 . +.Sh AUTHORS +The +.Nm +driver was written by +.An Bill Paul Aq Mt wpaul@ctr.columbia.edu . diff --git a/static/freebsd/man4/xnb.4 b/static/freebsd/man4/xnb.4 new file mode 100644 index 00000000..31eaed85 --- /dev/null +++ b/static/freebsd/man4/xnb.4 @@ -0,0 +1,139 @@ +.\" Copyright (c) 2012 Spectra Logic Corporation +.\" 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, +.\" without modification. +.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer +.\" substantially similar to the "NO WARRANTY" disclaimer below +.\" ("Disclaimer") and any redistribution must be conditioned upon +.\" including a substantially similar Disclaimer requirement for further +.\" binary redistribution. +.\" +.\" NO WARRANTY +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR 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 DAMAGES. +.\" +.\" Authors: Alan Somers (Spectra Logic Corporation) +.\" +.Dd June 6, 2014 +.Dt XNB 4 +.Os +.Sh NAME +.Nm xnb +.Nd "Xen Paravirtualized Backend Ethernet Driver" +.Sh SYNOPSIS +To compile this driver into the kernel, place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "options XENHVM" +.Cd "device xenpci" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides the back half of a paravirtualized +.Xr xen 4 +network connection. +The netback and netfront drivers appear to their respective operating +systems as Ethernet devices linked by a crossover cable. +Typically, +.Nm +will run on Domain 0 and the netfront driver will run on a guest domain. +However, it is also possible to run +.Nm +on a guest domain. +It may be bridged or routed to provide the netfront +domain access to other guest domains or to a physical network. +.Pp +In most respects, the +.Nm +device appears to the OS as any other Ethernet device. +It can be configured at runtime entirely with +.Xr ifconfig 8 . +In particular, it supports MAC changing, arbitrary MTU sizes, checksum +offload for IP, UDP, and TCP for both receive and transmit, and TSO. +However, see +.Sx CAVEATS +before enabling txcsum, rxcsum, or tso. +.Sh SYSCTL VARIABLES +The following read-only variables are available via +.Xr sysctl 8 : +.Bl -tag -width indent +.It Va dev.xnb.%d.dump_rings +Displays information about the ring buffers used to pass requests between the +netfront and netback. +Mostly useful for debugging, but can also be used to +get traffic statistics. +.It Va dev.xnb.%d.unit_test_results +Runs a builtin suite of unit tests and displays the results. +Does not affect the operation of the driver in any way. +Note that the test suite simulates error conditions; this will result in +error messages being printed to the system log. +.El +.Sh SEE ALSO +.Xr arp 4 , +.Xr netintro 4 , +.Xr ng_ether 4 , +.Xr xen 4 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 10.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Alan Somers Aq Mt asomers@FreeBSD.org +and John Suykerbuyk. +.Sh CAVEATS +Packets sent through Xennet pass over shared memory, so the protocol includes +no form of link-layer checksum or CRC. +Furthermore, Xennet drivers always report to their hosts that they support +receive and transmit checksum offloading. +They "offload" the checksum calculation by simply skipping it. +That works fine for packets that are exchanged between two domains on the same +machine. +However, when a Xennet interface is bridged to a physical interface, +a correct checksum must be attached to any packets bound for that physical +interface. +Currently, +.Fx +lacks any mechanism for an Ethernet device to +inform the OS that newly received packets are valid even though their checksums +are not. +So if the netfront driver is configured to offload checksum calculations, +it will pass non-checksumed packets to +.Nm , +which must then calculate the checksum in software before passing the packet +to the OS. +.Pp +For this reason, it is recommended that if +.Nm +is bridged to a physical interface, then transmit checksum offloading should be +disabled on the netfront. +The Xennet protocol does not have any mechanism for the netback to request +the netfront to do this; the operator must do it manually. +.Sh BUGS +The +.Nm +driver does not properly checksum UDP datagrams that span more than one +Ethernet frame. +Nor does it correctly checksum IPv6 packets. +To workaround that bug, disable transmit checksum offloading on the +netfront driver. diff --git a/static/freebsd/man4/xpt.4 b/static/freebsd/man4/xpt.4 new file mode 100644 index 00000000..8faa40cf --- /dev/null +++ b/static/freebsd/man4/xpt.4 @@ -0,0 +1,106 @@ +.\" +.\" Copyright (c) 1998 Kenneth D. Merry. +.\" 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. 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 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 October 10, 1998 +.Dt XPT 4 +.Os +.Sh NAME +.Nm xpt +.Nd CAM transport layer interface +.Sh SYNOPSIS +None. +.Sh DESCRIPTION +The +.Nm +driver provides a way for userland applications to issue certain CAM CCBs +to the kernel. +.Pp +Since the +.Nm +driver allows direct access to the CAM subsystem, system administrators +should exercise caution when granting access to this driver. +If used +improperly, this driver can allow userland applications to crash a machine +or cause data loss. +.Sh KERNEL CONFIGURATION +There is no kernel configuration required for the +.Nm +driver. +It is enabled when +.Tn SCSI +support is enabled in the kernel. +There is one instance of the xpt driver +per CAM transport layer instance. +Since there is currently only one CAM +transport layer, there will only be one instance of this driver. +.Sh IOCTLS +.Bl -tag -width 01234567890123 +.It CAMIOCOMMAND +This ioctl takes certain kinds of CAM CCBs and passes them through to the +CAM transport layer for action. +Only the following CCB types are +supported: +.Pp +.Bl -tag -width XPT_DEV_MATCH -compact +.It XPT_SCAN_BUS +.It XPT_RESET_BUS +.It XPT_SCAN_LUN +.It XPT_ENG_INQ +.It XPT_ENG_EXEC +.It XPT_DEBUG +.It XPT_DEV_MATCH +.It XPT_PATH_INQ +.El +.Pp +The above CCBs are the only ones supported since it makes more sense to +send them through a generic passthrough device rather than a passthrough +device tied to a particular underlying +.Tn SCSI +device. +.It CAMGETPASSTHRU +This ioctl takes an XPT_GDEVLIST CCB, and returns the passthrough device +corresponding to the device in question. +.El +.Sh FILES +.Bl -tag -width /dev/xpt0 -compact +.It Pa /dev/xpt0 +Character device node for the +.Nm +driver. +.El +.Sh DIAGNOSTICS +None. +.Sh SEE ALSO +.Xr cam 3 , +.Xr cam_cdbparse 3 , +.Xr pass 4 , +.Xr camcontrol 8 +.Sh HISTORY +The CAM transport layer driver first appeared in +.Fx 3.0 . +.Sh AUTHORS +.An Kenneth Merry Aq Mt ken@FreeBSD.org diff --git a/static/freebsd/man4/zero.4 b/static/freebsd/man4/zero.4 new file mode 100644 index 00000000..85651d53 --- /dev/null +++ b/static/freebsd/man4/zero.4 @@ -0,0 +1,57 @@ +.\" Copyright (c) 1996 +.\" Mike Pritchard . 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 Mike Pritchard and +.\" contributors. +.\" 4. Neither the name of the author nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" 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 November 9, 2025 +.Dt ZERO 4 +.Os +.Sh NAME +.Nm zero +.Nd the zero device +.Sh DESCRIPTION +The +.Nm +device accepts and reads data as any ordinary (and willing) +file, +but throws away any data written to it, and returns an endless +supply of null bytes when read. +.Sh FILES +.Bl -tag -width /dev/zero +.It Pa /dev/zero +.El +.Sh SEE ALSO +.Xr full 4 , +.Xr gzero 4 , +.Xr null 4 +.Sh HISTORY +A +.Nm +device appeared in +.Bx 4.4 . diff --git a/static/freebsd/man4/zyd.4 b/static/freebsd/man4/zyd.4 new file mode 100644 index 00000000..687adb97 --- /dev/null +++ b/static/freebsd/man4/zyd.4 @@ -0,0 +1,231 @@ +.\" $OpenBSD: zyd.4,v 1.22 2007/05/24 02:49:57 cnst Exp $ +.\" $NetBSD: zyd.4,v 1.1 2007/06/09 11:20:55 kiyohara Exp $ +.\" +.\" Copyright (c) 1997, 1998, 1999 +.\" Bill Paul . 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 Bill Paul. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Bill Paul 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 Bill Paul OR THE VOICES IN HIS HEAD +.\" 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 November 10, 2024 +.Dt ZYD 4 +.Os +.Sh NAME +.Nm zyd +.Nd ZyDAS ZD1211/ZD1211B USB IEEE 802.11b/g wireless network driver +.Sh SYNOPSIS +To compile this driver into the kernel, +place the following lines in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ehci" +.Cd "device uhci" +.Cd "device ohci" +.Cd "device usb" +.Cd "device zyd" +.Cd "device wlan" +.Cd "device wlan_amrr" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_zyd_load="YES" +.Ed +.Sh DESCRIPTION +The +.Nm +driver provides support for wireless network adapters based around +the ZyDAS ZD1211 and ZD1211B USB chips. +.Pp +.Nm +supports +.Cm station +and +.Cm monitor +mode operation. +Only one virtual interface may be configured at any time. +For more information on configuring this device, see +.Xr ifconfig 8 . +.Sh HARDWARE +The following devices are known to be supported by the +.Nm +driver: +.Pp +.Bl -bullet -offset indent -compact +.It +3COM 3CRUSB10075 +.It +Acer WLAN-G-US1 +.It +Airlink+ AWLL3025 +.It +Airlink 101 AWLL3026 +.It +AOpen 802.11g WL54 +.It +Asus A9T integrated wireless +.It +Asus WL-159g +.It +Belkin F5D7050 v.4000 +.It +Billion BiPAC 3011G +.It +Buffalo WLI-U2-KG54L +.It +CC&C WL-2203B +.It +DrayTek Vigor 550 +.It +Edimax EW-7317UG +.It +Edimax EW-7317LDG +.It +Fiberline Networks WL-43OU +.It +iNexQ UR055g +.It +Linksys WUSBF54G +.It +Longshine LCS-8131G3 +.It +MSI US54SE +.It +MyTek MWU-201 USB adapter +.It +Philips SNU5600 +.It +Planet WL-U356 +.It +Planex GW-US54GZ +.It +Planex GW-US54GZL +.It +Planex GW-US54Mini +.It +Safecom SWMULZ-5400 +.It +Sagem XG 760A +.It +Sagem XG 76NA +.It +Sandberg Wireless G54 USB +.It +Sitecom WL-113 +.It +SMC SMCWUSB-G +.It +Sweex wireless USB 54 Mbps +.It +Tekram/Siemens USB adapter +.It +Telegent TG54USB +.It +Trendnet TEW-424UB rev A +.It +Trendnet TEW-429UB +.It +TwinMOS G240 +.It +Unicorn WL-54G +.It +US Robotics 5423 +.It +X-Micro XWL-11GUZX +.It +Yakumo QuickWLAN USB +.It +Zonet ZEW2501 +.It +ZyXEL ZyAIR G-202 +.It +ZyXEL ZyAIR G-220 +.El +.Sh EXAMPLES +The following +example configures zyd0 to join any BSS network using WEP key +.Dq 0x1deadbeef1 , +channel 11: +.Bd -literal -offset indent +ifconfig wlan create wlandev zyd0 channel 11 \e + wepmode on wepkey 0x1deadbeef1 weptxkey 1 \e + inet 192.0.2.20/24 +.Ed +.Pp +Join an existing BSS network, +.Ar my_net : +.Bd -literal -offset indent +ifconfig wlan create wlandev zyd0 192.0.2.20/24 \e + ssid my_net +.Ed +.Sh DIAGNOSTICS +.Bl -diag +.It "zyd%d: could not load firmware (error=%d)" +An error occurred while attempting to upload the firmware to the onboard +microcontroller unit. +.It "zyd%d: could not send command (error=%s)" +An attempt to send a command to the firmware failed. +.It "zyd%d: sorry, radio %s is not supported yet" +Support for the specified radio chip is not yet implemented in the driver. +The device will not attach. +.It "zyd%d: device version mismatch: 0x%x (only >= 43.30 supported)" +Early revisions of the ZD1211 chipset are not supported by this driver. +The device will not attach. +.It "zyd%d: device timeout" +A frame dispatched to the hardware for transmission did not complete in time. +The driver will reset the hardware. +This should not happen. +.El +.Sh SEE ALSO +.Xr intro 4 , +.Xr netintro 4 , +.Xr usb 4 , +.Xr wlan 4 , +.Xr wlan_amrr 4 , +.Xr wlan_ccmp 4 , +.Xr wlan_tkip 4 , +.Xr wlan_wep 4 , +.Xr networking 7 , +.Xr ifconfig 8 , +.Xr wpa_supplicant 8 +.Sh AUTHORS +.An -nosplit +The original +.Nm +driver was written by +.An Florian Stoehr Aq Mt ich@florian-stoehr.de , +.An Damien Bergamini Aq Mt damien@openbsd.org , +and +.An Jonathan Gray Aq Mt jsg@openbsd.org . +.Sh CAVEATS +The +.Nm +driver does not support a lot of the functionality available in the hardware. +More work is required to properly support the IBSS and power management +features. diff --git a/static/freebsd/man5/Makefile b/static/freebsd/man5/Makefile new file mode 100644 index 00000000..0a0569ba --- /dev/null +++ b/static/freebsd/man5/Makefile @@ -0,0 +1,3 @@ +MAN = $(wildcard *.5) + +include ../../mandoc.mk diff --git a/static/freebsd/man5/a.out.5 b/static/freebsd/man5/a.out.5 new file mode 100644 index 00000000..ddbb41e1 --- /dev/null +++ b/static/freebsd/man5/a.out.5 @@ -0,0 +1,453 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This manual page is derived from documentation contributed to Berkeley by +.\" Donn Seeley at UUNET Technologies, Inc. +.\" +.\" 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 June 10, 2010 +.Dt A.OUT 5 +.Os +.Sh NAME +.Nm a.out +.Nd format of executable binary files +.Sh SYNOPSIS +.In a.out.h +.Sh DESCRIPTION +The include file +.In a.out.h +declares three structures and several macros. +The structures describe the format of +executable machine code files +.Pq Sq binaries +on the system. +.Pp +A binary file consists of up to 7 sections. +In order, these sections are: +.Bl -tag -width "text relocations" +.It exec header +Contains parameters used by the kernel +to load a binary file into memory and execute it, +and by the link editor +.Xr ld 1 +to combine a binary file with other binary files. +This section is the only mandatory one. +.It text segment +Contains machine code and related data +that are loaded into memory when a program executes. +May be loaded read-only. +.It data segment +Contains initialized data; always loaded into writable memory. +.It text relocations +Contains records used by the link editor +to update pointers in the text segment when combining binary files. +.It data relocations +Like the text relocation section, but for data segment pointers. +.It symbol table +Contains records used by the link editor +to cross reference the addresses of named variables and functions +.Pq Sq symbols +between binary files. +.It string table +Contains the character strings corresponding to the symbol names. +.El +.Pp +Every binary file begins with an +.Fa exec +structure: +.Bd -literal -offset indent +struct exec { + unsigned long a_midmag; + unsigned long a_text; + unsigned long a_data; + unsigned long a_bss; + unsigned long a_syms; + unsigned long a_entry; + unsigned long a_trsize; + unsigned long a_drsize; +}; +.Ed +.Pp +The fields have the following functions: +.Bl -tag -width a_trsize +.It Fa a_midmag +This field is stored in host byte-order. +It has a number of sub-components accessed by the macros +.Fn N_GETFLAG , +.Fn N_GETMID , +and +.Fn N_GETMAGIC , +and set by the macro +.Fn N_SETMAGIC . +.Pp +The macro +.Fn N_GETFLAG +returns a few flags: +.Bl -tag -width EX_DYNAMIC +.It Dv EX_DYNAMIC +indicates that the executable requires the services of the run-time link editor. +.It Dv EX_PIC +indicates that the object contains position independent code. +This flag is +set by +.Xr as 1 +when given the +.Sq -k +flag and is preserved by +.Xr ld 1 +if necessary. +.El +.Pp +If both EX_DYNAMIC and EX_PIC are set, the object file is a position independent +executable image (e.g.\& a shared library), which is to be loaded into the +process address space by the run-time link editor. +.Pp +The macro +.Fn N_GETMID +returns the machine-id. +This indicates which machine(s) the binary is intended to run on. +.Pp +.Fn N_GETMAGIC +specifies the magic number, which uniquely identifies binary files +and distinguishes different loading conventions. +The field must contain one of the following values: +.Bl -tag -width ZMAGIC +.It Dv OMAGIC +The text and data segments immediately follow the header +and are contiguous. +The kernel loads both text and data segments into writable memory. +.It Dv NMAGIC +As with +.Dv OMAGIC , +text and data segments immediately follow the header and are contiguous. +However, the kernel loads the text into read-only memory +and loads the data into writable memory at the next +page boundary after the text. +.It Dv ZMAGIC +The kernel loads individual pages on demand from the binary. +The header, text segment and data segment are all +padded by the link editor to a multiple of the page size. +Pages that the kernel loads from the text segment are read-only, +while pages from the data segment are writable. +.El +.It Fa a_text +Contains the size of the text segment in bytes. +.It Fa a_data +Contains the size of the data segment in bytes. +.It Fa a_bss +Contains the number of bytes in the +.Sq bss segment +and is used by the kernel to set the initial break +.Pq Xr brk 2 +after the data segment. +The kernel loads the program so that this amount of writable memory +appears to follow the data segment and initially reads as zeroes. +.Em ( bss += block started by symbol) +.It Fa a_syms +Contains the size in bytes of the symbol table section. +.It Fa a_entry +Contains the address in memory of the entry point +of the program after the kernel has loaded it; +the kernel starts the execution of the program +from the machine instruction at this address. +.It Fa a_trsize +Contains the size in bytes of the text relocation table. +.It Fa a_drsize +Contains the size in bytes of the data relocation table. +.El +.Pp +The +.In a.out.h +include file defines several macros which use an +.Fa exec +structure to test consistency or to locate section offsets in the binary file. +.Bl -tag -width N_BADMAG(exec) +.It Fn N_BADMAG exec +Nonzero if the +.Fa a_magic +field does not contain a recognized value. +.It Fn N_TXTOFF exec +The byte offset in the binary file of the beginning of the text segment. +.It Fn N_SYMOFF exec +The byte offset of the beginning of the symbol table. +.It Fn N_STROFF exec +The byte offset of the beginning of the string table. +.El +.Pp +Relocation records have a standard format which +is described by the +.Fa relocation_info +structure: +.Bd -literal -offset indent +struct relocation_info { + int r_address; + unsigned int r_symbolnum : 24, + r_pcrel : 1, + r_length : 2, + r_extern : 1, + r_baserel : 1, + r_jmptable : 1, + r_relative : 1, + r_copy : 1; +}; +.Ed +.Pp +The +.Fa relocation_info +fields are used as follows: +.Bl -tag -width r_symbolnum +.It Fa r_address +Contains the byte offset of a pointer that needs to be link-edited. +Text relocation offsets are reckoned from the start of the text segment, +and data relocation offsets from the start of the data segment. +The link editor adds the value that is already stored at this offset +into the new value that it computes using this relocation record. +.It Fa r_symbolnum +Contains the ordinal number of a symbol structure +in the symbol table (it is +.Em not +a byte offset). +After the link editor resolves the absolute address for this symbol, +it adds that address to the pointer that is undergoing relocation. +(If the +.Fa r_extern +bit is clear, the situation is different; see below.) +.It Fa r_pcrel +If this is set, +the link editor assumes that it is updating a pointer +that is part of a machine code instruction using pc-relative addressing. +The address of the relocated pointer is implicitly added +to its value when the running program uses it. +.It Fa r_length +Contains the log base 2 of the length of the pointer in bytes; +0 for 1-byte displacements, 1 for 2-byte displacements, +2 for 4-byte displacements. +.It Fa r_extern +Set if this relocation requires an external reference; +the link editor must use a symbol address to update the pointer. +When the +.Fa r_extern +bit is clear, the relocation is +.Sq local ; +the link editor updates the pointer to reflect +changes in the load addresses of the various segments, +rather than changes in the value of a symbol (except when +.Fa r_baserel +is also set (see below). +In this case, the content of the +.Fa r_symbolnum +field is an +.Fa n_type +value (see below); +this type field tells the link editor +what segment the relocated pointer points into. +.It Fa r_baserel +If set, the symbol, as identified by the +.Fa r_symbolnum +field, is to be relocated to an offset into the Global Offset Table. +At run-time, the entry in the Global Offset Table at this offset is set to +be the address of the symbol. +.It Fa r_jmptable +If set, the symbol, as identified by the +.Fa r_symbolnum +field, is to be relocated to an offset into the Procedure Linkage Table. +.It Fa r_relative +If set, this relocation is relative to the (run-time) load address of the +image this object file is going to be a part of. +This type of relocation +only occurs in shared objects. +.It Fa r_copy +If set, this relocation record identifies a symbol whose contents should +be copied to the location given in +.Fa r_address . +The copying is done by the run-time link-editor from a suitable data +item in a shared object. +.El +.Pp +Symbols map names to addresses (or more generally, strings to values). +Since the link-editor adjusts addresses, +a symbol's name must be used to stand for its address +until an absolute value has been assigned. +Symbols consist of a fixed-length record in the symbol table +and a variable-length name in the string table. +The symbol table is an array of +.Fa nlist +structures: +.Bd -literal -offset indent +struct nlist { + union { + const char *n_name; + long n_strx; + } n_un; + unsigned char n_type; + char n_other; + short n_desc; + unsigned long n_value; +}; +.Ed +.Pp +The fields are used as follows: +.Bl -tag -width n_un.n_strx +.It Fa n_un.n_strx +Contains a byte offset into the string table +for the name of this symbol. +When a program accesses a symbol table with the +.Xr nlist 3 +function, +this field is replaced with the +.Fa n_un.n_name +field, which is a pointer to the string in memory. +.It Fa n_type +Used by the link editor to determine +how to update the symbol's value. +The +.Fa n_type +field is broken down into three sub-fields using bitmasks. +The link editor treats symbols with the +.Dv N_EXT +type bit set as +.Sq external +symbols and permits references to them from other binary files. +The +.Dv N_TYPE +mask selects bits of interest to the link editor: +.Bl -tag -width N_TEXT +.It Dv N_UNDF +An undefined symbol. +The link editor must locate an external symbol with the same name +in another binary file to determine the absolute value of this symbol. +As a special case, if the +.Fa n_value +field is nonzero and no binary file in the link-edit defines this symbol, +the link-editor will resolve this symbol to an address +in the bss segment, +reserving an amount of bytes equal to +.Fa n_value . +If this symbol is undefined in more than one binary file +and the binary files do not agree on the size, +the link editor chooses the greatest size found across all binaries. +.It Dv N_ABS +An absolute symbol. +The link editor does not update an absolute symbol. +.It Dv N_TEXT +A text symbol. +This symbol's value is a text address and +the link editor will update it when it merges binary files. +.It Dv N_DATA +A data symbol; similar to +.Dv N_TEXT +but for data addresses. +The values for text and data symbols are not file offsets but +addresses; to recover the file offsets, it is necessary +to identify the loaded address of the beginning of the corresponding +section and subtract it, then add the offset of the section. +.It Dv N_BSS +A bss symbol; like text or data symbols but +has no corresponding offset in the binary file. +.It Dv N_FN +A filename symbol. +The link editor inserts this symbol before +the other symbols from a binary file when +merging binary files. +The name of the symbol is the filename given to the link editor, +and its value is the first text address from that binary file. +Filename symbols are not needed for link-editing or loading, +but are useful for debuggers. +.El +.Pp +The +.Dv N_STAB +mask selects bits of interest to symbolic debuggers +such as +.Xr gdb 1 Pq Pa ports/devel/gdb ; +the values are described in +.Xr stab 5 . +.It Fa n_other +This field provides information on the nature of the symbol independent of +the symbol's location in terms of segments as determined by the +.Fa n_type +field. +Currently, the lower 4 bits of the +.Fa n_other +field hold one of two values: +.Dv AUX_FUNC +and +.Dv AUX_OBJECT +(see +.In link.h +for their definitions). +.Dv AUX_FUNC +associates the symbol with a callable function, while +.Dv AUX_OBJECT +associates the symbol with data, irrespective of their locations in +either the text or the data segment. +This field is intended to be used by +.Xr ld 1 +for the construction of dynamic executables. +.It Fa n_desc +Reserved for use by debuggers; passed untouched by the link editor. +Different debuggers use this field for different purposes. +.It Fa n_value +Contains the value of the symbol. +For text, data and bss symbols, this is an address; +for other symbols (such as debugger symbols), +the value may be arbitrary. +.El +.Pp +The string table consists of an +.Em unsigned long +length followed by null-terminated symbol strings. +The length represents the size of the entire table in bytes, +so its minimum value (or the offset of the first string) +is always 4 on 32-bit machines. +.Sh SEE ALSO +.Xr as 1 , +.Xr gdb 1 Pq Pa ports/devel/gdb , +.Xr ld 1 , +.Xr brk 2 , +.Xr execve 2 , +.Xr nlist 3 , +.Xr core 5 , +.Xr elf 5 , +.Xr link 5 , +.Xr stab 5 +.Sh HISTORY +The +.In a.out.h +include file appeared in +.At v7 . +.Sh BUGS +Since not all of the supported architectures use the +.Fa a_midmag +field, +it can be difficult to determine what +architecture a binary will execute on +without examining its actual machine code. +Even with a machine identifier, +the byte order of the +.Fa exec +header is machine-dependent. diff --git a/static/freebsd/man5/acct.5 b/static/freebsd/man5/acct.5 new file mode 100644 index 00000000..217de840 --- /dev/null +++ b/static/freebsd/man5/acct.5 @@ -0,0 +1,124 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 February 13, 2017 +.Dt ACCT 5 +.Os +.Sh NAME +.Nm acct +.Nd execution accounting file +.Sh SYNOPSIS +.In sys/types.h +.In sys/acct.h +.Sh DESCRIPTION +The kernel maintains the following +.Fa acct +information structure for all +processes. +If a process terminates, and accounting is enabled, +the kernel calls the +.Xr acct 2 +function call to prepare and append the record +to the accounting file. +.Bd -literal +#define AC_COMM_LEN 16 + +/* + * Accounting structure version 3 (current). + * The first byte is always zero. + * Time units are microseconds. + */ + +struct acctv3 { + uint8_t ac_zero; /* zero identifies new version */ + uint8_t ac_version; /* record version number */ + uint16_t ac_len; /* record length */ + + char ac_comm[AC_COMM_LEN]; /* command name */ + float ac_utime; /* user time */ + float ac_stime; /* system time */ + float ac_etime; /* elapsed time */ + time_t ac_btime; /* starting time */ + uid_t ac_uid; /* user id */ + gid_t ac_gid; /* group id */ + float ac_mem; /* average memory usage */ + float ac_io; /* count of IO blocks */ + __dev_t ac_tty; /* controlling tty */ + + uint16_t ac_len2; /* record length */ + union { + uint32_t ac_align; /* force v1 compatible alignment */ + +#define AFORK 0x01 /* forked but not exec'ed */ +/* ASU is no longer supported */ +#define ASU 0x02 /* used super-user permissions */ +#define ACOMPAT 0x04 /* used compatibility mode */ +#define ACORE 0x08 /* dumped core */ +#define AXSIG 0x10 /* killed by a signal */ +#define ANVER 0x20 /* new record version */ + + uint8_t ac_flag; /* accounting flags */ + } ac_trailer; + +#define ac_flagx ac_trailer.ac_flag +}; +.Ed +.Pp +If a terminated process was created by an +.Xr execve 2 , +the name of the executed file (at most ten characters of it) +is saved in the field +.Fa ac_comm +and its status is saved by setting one of more of the following flags in +.Fa ac_flag : +.Dv AFORK , +.Dv ACOMPAT , +.Dv ACORE +and +.Dv ASIG . +.Dv ASU +is no longer supported. +.Dv ANVER +is always set in the above structure. +.Sh SEE ALSO +.Xr lastcomm 1 , +.Xr acct 2 , +.Xr execve 2 , +.Xr sa 8 +.Sh HISTORY +A +.Nm +file format appeared in +.At v7 . +The current record format was introduced on May 2007. +It is backwards compatible with the previous format, +which is still documented in +.In sys/acct.h +and supported by +.Xr lastcomm 1 +and +.Xr sa 8 . diff --git a/static/freebsd/man5/ar.5 b/static/freebsd/man5/ar.5 new file mode 100644 index 00000000..e26f385f --- /dev/null +++ b/static/freebsd/man5/ar.5 @@ -0,0 +1,325 @@ +.\" Copyright (c) 2010 Joseph Koshy. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd November 28, 2010 +.Dt AR 5 +.Os +.Sh NAME +.Nm ar +.Nd archive file format for +.Xr ar 1 +and +.Xr ranlib 1 +.Sh SYNOPSIS +.In ar.h +.Sh DESCRIPTION +.Xr ar 1 +archives are created and managed by the +.Xr ar 1 +and +.Xr ranlib 1 +utilities. +These archives are typically used during program development to +hold libraries of program objects. +An +.Xr ar 1 +archive is contained in a single operating system file. +.Pp +This manual page documents two variants of the +.Xr ar 1 +archive format: the BSD archive format, and the SVR4/GNU archive +format. +.Pp +In both variants the archive file starts with an identifying byte +sequence of the seven ASCII characters +.Sq Li "!" +followed by a ASCII linefeed character +.Po +see the constant +.Dq ARMAG +in the header file +.In ar.h +.Pc . +.Pp +Archive members follow the initial identifying byte sequence. +Each archive member is prefixed by a fixed size header describing the +file attributes associated with the member. +.Ss "Archive Headers" +An archive header describes the file attributes for the archive member that +follows it. +The +.Nm +format only supports a limited number of attributes: the file name, +the file creation time stamp, the uid and gid of the creator, the file +mode and the file size. +.Pp +Archive headers are placed at an even byte offset in the archive file. +If the data for an archive member ends at an odd byte offset, then a +padding byte with value 0x0A is used to position the next archive +header on an even byte offset. +.Pp +An archive header comprises the following fixed sized fields: +.Bl -tag -width "Li ar_name" +.It Ar ar_name +(16 bytes) The file name of the archive member. +The format of this field varies between the BSD and SVR4/GNU formats and +is described in more detail in the section +.Sx "Representing File Names" +below. +.It Ar ar_date +(12 bytes) The file modification time for the member in seconds since the +epoch, encoded as a decimal number. +.It Ar ar_uid +(6 bytes) The uid associated with the archive member, encoded as a +decimal number. +.It Ar ar_gid +(6 bytes) The gid associated with the archive member, encoded as a +decimal number. +.It Ar ar_mode +(8 bytes) The file mode for the archive member, encoded as an octal +number. +.It Ar ar_size +(10 bytes) In the SVR4/GNU archive format this field holds the size in +bytes of the archive member, encoded as a decimal number. +In the BSD archive format, for short file names, this field +holds the size in bytes of the archive member, encoded as a decimal +number. +For long file names +.Po +see +.Sx "Representing File Names" +below +.Pc , +the field contains the combined size of the +archive member and its file name, encoded as a decimal number. +.It Ar ar_fmag +(2 bytes) This field holds 2 bytes with values 0x96 and 0x0A +respectively, marking the end of the header. +.El +.Pp +Unused bytes in the fields of an archive header are set to the value +0x20. +.Ss "Representing File Names" +The BSD and SVR4/GNU variants use different schemes for encoding file +names for members. +.Bl -tag -width "SVR4/GNU" +.It "BSD" +File names that are up to 16 bytes long and which do not contain +embedded spaces are stored directly in the +.Ar ar_name +field of the archive header. +File names that are either longer than 16 bytes or which contain +embedded spaces are stored immediately after the archive header +and the +.Ar ar_name +field of the archive header is set to the string +.Dq "#1/" +followed by a decimal representation of the number of bytes needed for +the file name. +In addition, the +.Ar ar_size +field of the archive header is set to the decimal representation of +the combined sizes of the archive member and the file name. +The file contents of the member follows the file name without further +padding. +.Pp +As an example, if the file name for a member was +.Dq "A B" +and its contents was the string +.Dq "C D" , +then the +.Ar ar_name +field of the header would contain +.Dq Li "#1/3" , +the +.Ar ar_size +field of the header would contain +.Dq Li 6 , +and the bytes immediately following the header would be 0x41, 0x20, +0x42, 0x43, 0x20 and 0x44 +.Po +ASCII +.Dq "A BC D" +.Pc . +.It "SVR4/GNU" +File names that are up to 15 characters long are stored directly in the +.Ar ar_name +field of the header, terminated by a +.Dq Li / +character. +.Pp +If the file name is larger than would fit in space for the +.Ar ar_name +field, then the actual file name is kept in the archive +string table +.Po +see +.Sx "Archive String Tables" +below +.Pc , +and the decimal offset of the file name in the string table is stored +in the +.Ar ar_name +field, prefixed by a +.Dq Li / +character. +.Pp +As an example, if the real file name has been stored at offset 768 in +the archive string table, the +.Ar ar_name +field of the header will contain the string +.Dq /768 . +.El +.Ss "Special Archive Members" +The following archive members are special. +.Bl -tag -width indent +.It Dq Li / +In the SVR4/GNU variant of the archive format, the archive member with +name +.Dq Li / +denotes an archive symbol table. +If present, this member will be the very first member in the +archive. +.It Dq Li // +In the SVR4/GNU variant of the archive format, the archive member with +name +.Dq Li // +denotes the archive string table. +This special member is used to hold filenames that do not fit in the +file name field of the header +.Po +see +.Sx "Representing File Names" +above +.Pc . +If present, this member immediately follows the archive symbol table +if an archive symbol table is present, or is the first member otherwise. +.It Dq Li "__.SYMDEF" +This special member contains the archive symbol table in the BSD +variant of the archive format. +If present, this member will be the very first member in the +archive. +.El +.Ss "Archive String Tables" +An archive string table is used in the SVR4/GNU archive format to hold +file names that are too large to fit into the constraints of the +.Ar ar_name +field of the archive header. +An archive string table contains a sequence of file names. +Each file name in the archive string table is terminated by the +byte sequence 0x2F, 0x0A +.Po +the ASCII string +.Dq "/\en" +.Pc . +No padding is used to separate adjacent file names. +.Ss "Archive Symbol Tables" +Archive symbol tables are used to speed up link editing by providing a +mapping between the program symbols defined in the archive +and the corresponding archive members. +Archive symbol tables are managed by the +.Xr ranlib 1 +utility. +.Pp +The format of archive symbol tables is as follows: +.Bl -tag -width "SVR4/GNU" +.It BSD +In the BSD archive format, the archive symbol table comprises +of two parts: a part containing an array of +.Vt "struct ranlib" +descriptors, followed by a part containing a symbol string table. +The sizes and layout of the structures that make up a BSD format +archive symbol table are machine dependent. +.Pp +The part containing +.Vt "struct ranlib" +descriptors begins with a field containing the size in bytes of the +array of +.Vt "struct ranlib" +descriptors encoded as a C +.Vt long +value. +.Pp +The array of +.Vt "struct ranlib" +descriptors follows the size field. +Each +.Vt "struct ranlib" +descriptor describes one symbol. +.Pp +A +.Vt "struct ranlib" +descriptor comprises two fields: +.Bl -tag -width "Ar ran_strx" -compact +.It Ar ran_strx +.Pq C Vt long +This field contains the zero-based offset of the symbol name in the +symbol string table. +.It Ar ran_off +.Pq C Vt long +This field is the file offset to the archive header for the archive +member defining the symbol. +.El +.Pp +The part containing the symbol string table begins with a field +containing the size in bytes of the string table, encoded as a C +.Vt long +value. +This string table follows the size field, and contains +NUL-terminated strings for the symbols in the symbol table. +.It SVR4/GNU +In the SVR4/GNU archive format, the archive symbol table starts with a +4-byte binary value containing the number of entries contained in the +archive symbol table. +This count of entries is stored most significant byte first. +.Pp +Next, there are +.Ar count +4-byte numbers, each stored most significant byte first. +Each number is a binary offset to the archive header for the member in +the archive file for the corresponding symbol table entry. +.Pp +After the binary offset values, there are +.Ar count +NUL-terminated strings in sequence, holding the symbol names for +the corresponding symbol table entries. +.El +.Sh STANDARDS COMPLIANCE +The +.Xr ar 1 +archive format is not currently specified by a standard. +.Pp +This manual page documents the +.Xr ar 1 +archive formats used by the +.Bx 4.4 +and +.Ux SVR4 +operating system releases. +.Sh SEE ALSO +.Xr ar 1 , +.Xr ld 1 , +.Xr ranlib 1 , +.Xr elf 3 , +.Xr elf_getarsym 3 , +.Xr elf_rand 3 diff --git a/static/freebsd/man5/bluetooth.device.conf.5 b/static/freebsd/man5/bluetooth.device.conf.5 new file mode 100644 index 00000000..871ffe99 --- /dev/null +++ b/static/freebsd/man5/bluetooth.device.conf.5 @@ -0,0 +1,182 @@ +.\" Copyright (c) 2005 Maksim Yevmenkin +.\" 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 September 29, 2021 +.Dt BLUETOOTH.DEVICE.CONF 5 +.Os +.Sh NAME +.Nm bluetooth.device.conf +.Nd Bluetooth device configuration file +.Sh DESCRIPTION +Bluetooth device configuration framework provides ability to adjust certain +Bluetooth device parameters on per-device basis. +.Pp +Bluetooth device configuration files are plain text files that should conform +to basic +.Xr sh 1 +syntax. +Even though Bluetooth device are not exactly shell scripts, +they are parsed and passed through shell +.Ic eval +command. +This makes it possible to use various shell tricks in the Bluetooth device +configuration files. +.Pp +The +.Pa /etc/rc.d/bluetooth +script is used to start and stop Bluetooth devices. +This script is not executed by default when system boots. +It is called by +.Xr devd 8 +in response to Bluetooth device arrival and departure events. +It is possible to execute this script by hand if required. +The script accepts Bluetooth device driver name as an extra parameter. +.Pp +The system wide Bluetooth device configuration file is called +.Pa /etc/defaults/\:bluetooth.device.conf . +Configuration parameters set in the system wide Bluetooth device configuration +file apply to every Bluetooth device connected to the system. +.Pp +Configuration parameters overrides for the specific Bluetooth device +should be placed in the +.Pa /etc/bluetooth/ Ns Ar DEVICE_DRIVER_NAME Ns Pa .conf +file. +Where +.Ar DEVICE_DRIVER_NAME +is the device driver name of the Bluetooth device. +.Pp +The following list provides a name and short description for each +variable that can be set in a Bluetooth device configuration file. +.Bl -tag -width indent-two +.It Va authentication_enable +.Pq Vt bool +The +.Va authentication_enable +parameter controls if the device requires to authenticate the remote device +at connection setup. +If set to +.Dq Li YES , +the device will try to authenticate the other device at connection setup. +Bluetooth authentication requests are handled by +.Xr hcsecd 8 +daemon. +.It Va class +.Pq Vt str +The +.Va class +parameter is used to indicate the capabilities of the device to +other devices. +For more details see +.Dq Assigned Numbers - Bluetooth Baseband +document. +.It Va connectable +.Pq Vt bool +The +.Va connectable +parameter controls whether or not the device should periodically scan for +page attempts from other devices. +If set to +.Dq Li YES , +the device will periodically scan for page attempts from other devices. +.It Va discoverable +.Pq Vt bool +The +.Va discoverable +parameter controls whether or not the device should periodically scan for +inquiry requests from other devices. +If set to +.Dq Li YES , +the device will periodically scan for inquiry requests from other devices. +.It Va encryption_mode +.Pq Vt str +The +.Va encryption_mode +parameter controls if the device requires encryption to the remote device +at connection setup. +At connection setup, only the devices with the +.Va authentication_enable +parameter enabled and +.Va encryption_mode +parameter enabled will try to encrypt the connection to the other device. +Possible values are +.Dq Li NONE +encryption disabled, +.Dq Li P2P +encryption for only point-to-point packets, +or +.Dq Li ALL +encryption for both point-to-point and broadcast packets. +.It Va hci_debug_level +.Pq Vt int +HCI node debug level. +Higher values mean more verbose output. +.It Va l2cap_debug_level +.Pq Vt int +L2CAP node debug level. +Higher values mean more verbose output. +.It Va local_name +.Pq Vt str +The +.Va local_name +parameter provides the ability to modify the user friendly name for the device. +.It Va role_switch +.Pq Vt bool +The +.Va role_switch +parameter controls whether the local device should perform role switch. +By default, if role switch is supported, the local device will try to perform +role switch and become Master on incoming connection. +Some devices do not support role switch and thus incoming connections from +such devices will fail. +If +.Va role switch +is disabled then accepting device will remain Slave. +.El +.Sh FILES +.Bl -tag -width ".Pa /etc/defaults/bluetooth.device.conf" -compact +.It Pa /etc/defaults/bluetooth.device.conf +.It Pa /etc/rc.d/bluetooth +.El +.Sh EXAMPLES +The +.Pa /etc/bluetooth/ubt0.conf +file should be used to specify configuration parameters overrides for the +first USB Bluetooth device +(device driver name is +.Li ubt0 ) . +.Pp +The +.Pa /etc/bluetooth/ubt1.conf +file should be used to specify configuration parameters overrides for the +second USB Bluetooth device. +.Sh SEE ALSO +.Xr ng_hci 4 , +.Xr ng_l2cap 4 , +.Xr ng_ubt 4 , +.Xr devd 8 , +.Xr hccontrol 8 , +.Xr hcsecd 8 , +.Xr l2control 8 +.Sh AUTHORS +.An Maksim Yevmenkin Aq Mt m_evmenkin@yahoo.com diff --git a/static/freebsd/man5/bluetooth.hosts.5 b/static/freebsd/man5/bluetooth.hosts.5 new file mode 100644 index 00000000..7f8ef2b6 --- /dev/null +++ b/static/freebsd/man5/bluetooth.hosts.5 @@ -0,0 +1,62 @@ +.\" Copyright (c) 2003 Maksim Yevmenkin +.\" 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. +.\" +.\" $Id: bluetooth.hosts.5,v 1.5 2003/05/20 22:52:39 max Exp $ +.\" +.Dd May 8, 2003 +.Dt BLUETOOTH.HOSTS 5 +.Os +.Sh NAME +.Nm bluetooth.hosts +.Nd Bluetooth host name database +.Sh DESCRIPTION +The +.Pa /etc/bluetooth/hosts +file contains information regarding the known Bluetooth hosts. +For each Bluetooth host a single line should be present with the +following information: +.Bd -unfilled -offset indent +Bluetooth address +official host name +aliases +.Ed +.Pp +Items are separated by any number of blanks and/or tab characters. +A +.Ql # +indicates the beginning of a comment; characters up to the end of the line are +not interpreted by routines which search the file. +.Pp +Bluetooth addresses are specified as six hex bytes separated by columns +(BD_ADDR). +Host names may contain any printable character other than a field +delimiter, newline, or comment character. +.Sh FILES +.Bl -tag -width ".Pa /etc/bluetooth/hosts" -compact +.It Pa /etc/bluetooth/hosts +.El +.Sh SEE ALSO +.Xr bluetooth 3 +.Sh AUTHORS +.An Maksim Yevmenkin Aq Mt m_evmenkin@yahoo.com diff --git a/static/freebsd/man5/bluetooth.protocols.5 b/static/freebsd/man5/bluetooth.protocols.5 new file mode 100644 index 00000000..c2c6d57c --- /dev/null +++ b/static/freebsd/man5/bluetooth.protocols.5 @@ -0,0 +1,61 @@ +.\" Copyright (c) 2003 Maksim Yevmenkin +.\" 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. +.\" +.\" $Id: bluetooth.protocols.5,v 1.1 2003/05/20 22:52:39 max Exp $ +.\" +.Dd May 8, 2003 +.Dt BLUETOOTH.PROTOCOLS 5 +.Os +.Sh NAME +.Nm bluetooth.protocols +.Nd Bluetooth Protocol Service Multiplexor database +.Sh DESCRIPTION +The +.Pa /etc/bluetooth/protocols +file contains information regarding the known Bluetooth Protocol Service +Multiplexor values. +For each Bluetooth Protocol Service Multiplexor a single line should be +present with the following information: +.Bd -unfilled -offset indent +official Protocol Service Multiplexor name +official Protocol Service Multiplexor value +aliases +.Ed +.Pp +Items are separated by any number of blanks and/or tab characters. +A +.Ql # +indicates the beginning of a comment; characters up to the end of the line are +not interpreted by routines which search the file. +.Pp +Bluetooth Protocol Service Multiplexor names may contain any printable +character other than a field delimiter, newline, or comment character. +.Sh FILES +.Bl -tag -width ".Pa /etc/bluetooth/hosts" -compact +.It Pa /etc/bluetooth/protocols +.El +.Sh SEE ALSO +.Xr bluetooth 3 +.Sh AUTHORS +.An Maksim Yevmenkin Aq Mt m_evmenkin@yahoo.com diff --git a/static/freebsd/man5/boot.config.5 b/static/freebsd/man5/boot.config.5 new file mode 100644 index 00000000..ddc23295 --- /dev/null +++ b/static/freebsd/man5/boot.config.5 @@ -0,0 +1,104 @@ +.\" Copyright (c) 2007 Daniel Gerzo +.\" 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 November 14, 2025 +.Dt BOOT.CONFIG 5 +.Os +.Sh NAME +.Nm boot.config +.Nd "Configuration file for the legacy boot blocks" +.Sh DESCRIPTION +The +.Nm +file contains options for the +.Fx +boot block code. +.Pp +When the first- and second-stage +.Fx +boot loaders run, they search the +.Dq Li a +slice of the boot partition for a +.Nm +file (as a result, slices which are missing an +.Dq Li a +partition require user intervention during the boot process). +If the +.Nm +file is found, its contents are used as the default configuration +options for the boot block code and are echoed to the system console. +.Pp +A valid format of this file is to put BIOS drive number, a controller +type, a unit number, a partition, a kernel file name, and any other +valid +.Xr boot 8 +option on a single line, as it is done at the +.Dq Li "boot:" +prompt. +.Pp +The options related to the boot image selection described below and all +the other options available for +.Nm +are documented in detail in the +.Xr boot 8 +manual page. +.Sh FILES +.Bl -tag -width /boot.config -compact +.It Pa /boot.config +parameters for the boot blocks (optional) +.It Pa /boot/config +alternate location for boot config information +.El +.Sh EXAMPLES +The command: +.Bd -literal -offset indent +# echo "-P" > /boot.config +.Ed +.Pp +will activate the serial console of +.Fx +if no keyboard is present, otherwise video console will be used. +.Pp +The command: +.Bd -literal -offset indent +# echo "1:ad(1,a)/boot/loader" > /boot.config +.Ed +.Pp +will instruct the second stage of +.Xr boot 8 +on the first disk to boot with the third +.Xr boot 8 +stage from the second disk. +.Pp +The command: +.Bd -literal -offset indent +# echo "1:ad(1,a)/boot/loader -P" > /boot.config +.Ed +.Pp +will do both of the above. +.Sh SEE ALSO +.Xr boot 8 , +.Xr loader 8 +.Sh AUTHORS +This manual page was written by +.An Daniel Gerzo Aq Mt danger@FreeBSD.org . diff --git a/static/freebsd/man5/core.5 b/static/freebsd/man5/core.5 new file mode 100644 index 00000000..628fdb79 --- /dev/null +++ b/static/freebsd/man5/core.5 @@ -0,0 +1,190 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 17, 2025 +.Dt CORE 5 +.Os +.Sh NAME +.Nm core +.Nd memory image file format +.Sh SYNOPSIS +.In sys/param.h +.Sh DESCRIPTION +A small number of signals which cause abnormal termination of a process +also cause a record of the process's in-core state to be written +to disk for later examination by one of the available debuggers. +(See +.Xr sigaction 2 . ) +This memory image is written to a file named by default +.Nm programname.core +in the working directory; +provided the terminated process had write permission in the directory, +and provided the abnormality did not cause +a system crash. +(In this event, the decision to save the core file is arbitrary, see +.Xr savecore 8 . ) +.Pp +The name of the file is controlled via the +.Xr sysctl 8 +variable +.Va kern.corefile . +The contents of this variable describes a filename to store +the core image to. +This filename can be absolute, or relative (which +will resolve to the current working directory of the program +generating it). +.Pp +The following format specifiers may be used in the +.Va kern.corefile +sysctl to insert additional information into the resulting core +filename: +.Bl -tag -width "1234567890" -compact -offset "12345" +.It Em \&%H +Machine hostname. +.It Em \&%I +An index starting at zero until the sysctl +.Em debug.ncores +is reached. +This can be useful for limiting the number of corefiles +generated by a particular process. +.It Em \&%N +process name. +.It Em \&%P +processes PID. +.It Em \&%S +signal during core. +.It Em \&%U +process UID. +.El +.Pp +The name defaults to +.Em \&%N.core , +yielding the traditional +.Fx +behaviour. +.Pp +The maximum size of a core file is limited by the +.Dv RLIMIT_CORE +.Xr setrlimit 2 +limit. +Files which would be larger than the limit are not created. +.Pp +With a large limit, a process that had mapped a very large, +and perhaps sparsely populated, virtual memory region, could take +a very long time to create core dumps. +The system ignores all signals sent to a process writing a core file, except +.Dv SIGKILL +which terminates the writing and causes immediate exit of the process. +The behavior of +.Dv SIGKILL +can be disabled by setting tunable +.Xr sysctl 8 +variable +.Va kern.core_dump_can_intr +to zero. +.Pp +By default, a process that changes user or group credentials whether +real or effective will not create a corefile. +This behaviour can be +changed to generate a core dump by setting the +.Xr sysctl 8 +variable +.Va kern.sugid_coredump +to 1. +.Pp +Corefiles can be compressed by the kernel if one of the following items +are included in the kernel configuration file: +.Bl -tag -width "1234567890" -compact -offset "12345" +.It options +GZIO +.It options +ZSTDIO +.El +.Pp +The following sysctl control core file compression: +.Bl -tag -width "kern.compress_user_cores_level" -compact -offset "12345" +.It Em kern.compress_user_cores +Enable compression of user cores. +A value of 1 configures +.Xr gzip 1 +compression, +and a value of 2 configures +.Xr zstd 1 +compression. +Compressed core files will have a suffix of +.Ql .gz +or +.Ql .zst +appended to their filenames depending on the selected format. +.It Em kern.compress_user_cores_level +Compression level. +Defaults to 6. +.El +.Sh NOTES +Corefiles are written with open file descriptor information as an ELF note. +By default, file paths are packed to only use as much space as needed. +However, file paths can change at any time, including during core dump, +and this can result in truncated file descriptor data. +.Pp +All file descriptor information can be preserved by disabling packing. +This potentially wastes up to PATH_MAX bytes per open fd. +Packing is disabled with +.Dl sysctl kern.coredump_pack_fileinfo=0 . +.Pp +Similarly, corefiles are written with vmmap information as an ELF note, which +contains file paths. +By default, they are packed to only use as much space as +needed. +By the same mechanism as for the open files note, these paths can also +change at any time and result in a truncated note. +.Pp +All vmmap information can be preserved by disabling packing. +Like the file information, this potentially wastes up to PATH_MAX bytes per +mapped object. +Packing is disabled with +.Dl sysctl kern.coredump_pack_vmmapinfo=0 . +.Sh EXAMPLES +In order to store all core images in per-user private areas under +.Pa /var/coredumps +(assuming the appropriate subdirectories exist and are writable by users), +the following +.Xr sysctl 8 +command can be used: +.Pp +.Dl sysctl kern.corefile=/var/coredumps/\&%U/\&%N.core +.Sh SEE ALSO +.Xr gdb 1 Pq Pa ports/devel/gdb , +.Xr gzip 1 , +.Xr kgdb 1 Pq Pa ports/devel/gdb , +.Xr setrlimit 2 , +.Xr sigaction 2 , +.Xr sysctl 8 +.Sh HISTORY +A +.Nm +file format appeared in +.At v1 . diff --git a/static/freebsd/man5/devfs.conf.5 b/static/freebsd/man5/devfs.conf.5 new file mode 100644 index 00000000..f7141b76 --- /dev/null +++ b/static/freebsd/man5/devfs.conf.5 @@ -0,0 +1,127 @@ +.\" Copyright (c) 2004 Roland Smith +.\" 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 May 25, 2019 +.Dt DEVFS.CONF 5 +.Os +.Sh NAME +.Nm devfs.conf +.Nd boot-time devfs configuration information +.Sh DESCRIPTION +The +.Nm +file provides an easy way to set ownership and permissions, or create +links for devices available at boot. +.Pp +It does not work for devices plugged in and out after the system is up +and running, e.g.\& USB devices. +See +.Xr devfs.rules 5 +for setting ownership and permissions for all device nodes, and +.Xr devd.conf 5 +for actions to be taken when devices are attached or detached. +.Pp +Lines starting with a hash sign +.Pq Ql # +and empty lines are ignored. +The lines that specify +.Nm +rules consist of three parameters separated by whitespace: +.Bl -tag -width indent +.It Ar action +The action to take for the device. +The action names are only significant to the first unique character. +.It Ar devname +The name of the device created by +.Xr devfs 4 . +.It Ar arg +The argument of the +.Ar action . +.El +.Pp +The actions currently supported are: +.Bl -tag -width indent +.It Ic link +This action creates a symbolic link named +.Ar arg +that points to +.Ar devname , +the name of the device created by +.Xr devfs 4 . +.It Ic own +This action changes the ownership of +.Ar devname . +The +.Ar arg +parameter must be in the form of an +.Ar owner Ns : Ns Ar group +pair, in the same format used by +.Xr chown 8 . +.It Ic perm +This action changes the permissions of +.Ar devname . +The +.Ar arg +parameter must be a +.Ar mode +as explained in +.Xr chmod 1 . +.El +.Sh FILES +.Bl -tag -compact -width Pa +.It Pa /etc/devfs.conf +.It Pa /usr/share/examples/etc/devfs.conf +.El +.Sh EXAMPLES +To create a +.Pa /dev/cdrom +link that points to the first CD-ROM, +the following may be added to +.Nm : +.Bd -literal -offset indent +link cd0 cdrom +.Ed +.Pp +To set the owner of a device, the +.Ic own +action may be specified: +.Bd -literal -offset indent +own cd0 root:cdrom +.Ed +.Pp +To set the permissions of a device, a +.Ic perm +action should be used: +.Bd -literal -offset indent +perm cd0 0660 +.Ed +.Sh SEE ALSO +.Xr chmod 1 , +.Xr devfs 4 , +.Xr devd.conf 5 , +.Xr devfs.rules 5 , +.Xr chown 8 +.Sh AUTHORS +This manual page was written by +.An Roland Smith Aq Mt rsmith@xs4all.nl . diff --git a/static/freebsd/man5/devfs.rules.5 b/static/freebsd/man5/devfs.rules.5 new file mode 100644 index 00000000..e878c2a9 --- /dev/null +++ b/static/freebsd/man5/devfs.rules.5 @@ -0,0 +1,133 @@ +.\" Copyright (c) 2004 Roland Smith +.\" 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 December 1, 2020 +.Dt DEVFS.RULES 5 +.Os +.Sh NAME +.Nm devfs.rules +.Nd devfs configuration information +.Sh DESCRIPTION +The +.Nm +file provides an easy way to create and apply +.Xr devfs 8 +rules, even for devices that are not available at boot. +.Pp +For devices available at boot, see +.Xr devfs.conf 5 . +.Pp +The format of this file is simple. +Empty lines and lines beginning with a hash sign +.Pq Ql # +are ignored. +A line between brackets denotes the start of a ruleset. +In the brackets should be the name of the ruleset and its number, +separated by an equal sign. +.Pp +Other lines are rule specifications as documented in +.Xr devfs 8 , +in the section +.Sx "Rule Specification" . +These lines are prepended with +.Dq Li rule +and are passed to +.Xr devfs 8 +by the startup scripts of the system. +It is important to put path elements that contain +.Xr glob 3 +special characters between quotes. +.Pp +Rulesets should have a unique name and number. +.Pp +All rules that follow a ruleset declaration belong to that ruleset, until a +new ruleset is started. +.Pp +One custom ruleset has to be enabled in +.Pa /etc/rc.conf , +otherwise it will not be applied to the +.Pa /dev +file system by the default system startup process. +For example, to enable a +.Dq Li localrules +ruleset for the +.Pa /dev +file system, you would have to use something like this in your +.Pa rc.conf +file: +.Bd -literal -offset indent +devfs_system_ruleset="localrules" +.Ed +.Pp +The rules are loaded at boot via the devfs service. +To load modified rules after the system has booted, run the command: +.Bd -literal -offset indent +service devfs restart +.Ed +.Sh FILES +.Bl -tag -compact -width Pa +.It Pa /etc/defaults/devfs.rules +Default +.Nm +configuration file. +.It Pa /etc/devfs.rules +Local +.Nm +configuration file. +Rulesets in here override those in +.Pa /etc/defaults/devfs.rules +with the same ruleset number, otherwise the two files are effectively merged. +.El +.Sh EXAMPLES +To make all the partitions of +.Xr da 4 +devices readable and writable by their owner and the +.Dq Li usb +group, the following rule may be used: +.Pp +.Dl "[localrules=10]" +.Dl "add path 'da*s*' mode 0660 group usb" +.Pp +The first line declares and starts a new ruleset, with the name +.Va localrules +and the number 10. +.Pp +To give +.Xr usbconfig 8 +and +.Xr libusb 3 +enabled applications permission to all usb devices for their owner and the +.Dq Li usb +group, a similar rule may be used: +.Pp +.Dl "add path 'usb/*' mode 0660 group usb" +.Sh SEE ALSO +.Xr glob 3 , +.Xr devfs 4 , +.Xr devfs.conf 5 , +.Xr devfs 8 , +.Xr service 8 +.Sh AUTHORS +This manual page was written by +.An Roland Smith Aq Mt rsmith@xs4all.nl . diff --git a/static/freebsd/man5/device.hints.5 b/static/freebsd/man5/device.hints.5 new file mode 100644 index 00000000..613e783e --- /dev/null +++ b/static/freebsd/man5/device.hints.5 @@ -0,0 +1,166 @@ +.\" Copyright (c) 2001 +.\" Kazutaka YOKOTA +.\" 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 as +.\" the first lines of this file unmodified. +.\" 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 ``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 November 19, 2019 +.Dt DEVICE.HINTS 5 +.Os +.Sh NAME +.Nm device.hints +.Nd device resource hints +.Sh DESCRIPTION +The +.Nm +file is read in by the boot +.Xr loader 8 +when the system is about to start, and its contents are +passed to the kernel. +It contains various variables to control the boot behavior of +the kernel. +These variables are typically +.Dq device hints , +but can include any kernel tunable values. +.Pp +The file contains one variable per line. +Lines starting with the +.Ql # +character are comments and are ignored by the boot loader. +.Pp +After the file is read by the boot loader, you may examine +the variables with the +.Ic show +command, and may add a new variable, modify an existing one, +or delete a variable with the +.Ic set +and +.Ic unset +commands of the boot loader +(see +.Xr loader 8 ) . +.Pp +After the system has started, you can dump these variables +with the +.Xr kenv 1 +command. +.Sh DEVICE HINTS +Device hint variables are used by device drivers to set up +the device. +They are most often used by ISA device drivers to specify +where the driver will probe for the relevant devices, and what +resources it will attempt to use. +.Pp +A device hint line looks like: +.Pp +.Sm off +.D1 Li hint. Ar driver . Ar unit . Ar keyword Li = Qq Ar value +.Sm on +.Pp +where +.Ar driver +is the name of a device driver, +.Ar unit +is the unit number, and +.Ar keyword +is the keyword of the hint. +The keyword may be: +.Pp +.Bl -tag -width ".Li disabled" -compact -offset indent +.It Li at +specifies a bus to which the device is attached. +.It Li port +specifies the start address of I/O ports to be used by the device. +.It Li portsize +specifies the number of ports used by the device. +.It Li irq +is the interrupt line number to be used. +.It Li drq +is the DMA channel number. +.It Li maddr +specifies the physical memory address used by the device. +.It Li msize +specifies the physical memory size used by the device. +.It Li flags +sets various flag bits for the device. +.It Li disabled +can be set to +.Qq 1 +to disable the device. +.El +.Pp +A device driver may require one or more hint lines with these keywords, +and may accept other keywords not listed here, through +.Xr resource_int_value 9 . +Consult individual device drivers' manual pages for available +keywords and their possible values. +.\" .Sh CONTROL VARIABLES +.\" Lines not starting with +.\" .Dq hint. +.\" specify other control variables for the kernel. +.\" They look: +.\" .Pp +.\" .Dl ="" +.\" XXX +.\" WE SHOULD LIST AVAILABLE VARIABLE NAMES AND THEIR POSSIBLE VALUES HERE! +.\" .Pp +.Sh FILES +.Bl -tag -width ".Pa /sys/ Ns Ar ARCH Ns Pa /conf/GENERIC.hints" -compact +.It Pa /boot/device.hints +Device resource hints file. +.It Pa /sys/ Ns Ar ARCH Ns Pa /conf/GENERIC.hints +Sample resource hints for the +.Pa GENERIC +kernel. +.It Pa /sys/ Ns Ar ARCH Ns Pa /conf/NOTES +Notes on the kernel configuration file and device resource hints. +.El +.Sh EXAMPLES +The following example sets up resources for the +.Xr uart 4 +driver on the ISA bus: +.Bd -literal -offset indent +hint.uart.0.at="isa" +hint.uart.0.port="0x3F8" +hint.uart.0.flags="0x10" +hint.uart.0.irq="4" +.Ed +.Pp +The following example disables the ACPI driver: +.Bd -literal -offset indent +hint.acpi.0.disabled="1" +.Ed +.Pp +Setting a tunable variable: +.Bd -literal -offset indent +vm.pmap.pg_ps_enabled=1 +.Ed +.Sh SEE ALSO +.Xr kenv 1 , +.Xr loader.conf 5 , +.Xr loader 8 , +.Xr resource_int_value 9 +.Sh HISTORY +The +.Nm +file first appeared in +.Fx 5.0 . diff --git a/static/freebsd/man5/dir.5 b/static/freebsd/man5/dir.5 new file mode 100644 index 00000000..06788ccc --- /dev/null +++ b/static/freebsd/man5/dir.5 @@ -0,0 +1,164 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 November 14, 2018 +.Dt DIR 5 +.Os +.Sh NAME +.Nm dir , +.Nm dirent +.Nd directory file format +.Sh SYNOPSIS +.In dirent.h +.Sh DESCRIPTION +Directories provide a convenient hierarchical method of grouping +files while obscuring the underlying details of the storage medium. +A directory file is differentiated from a plain file +by a flag in its +.Xr inode 5 +entry. +It consists of records (directory entries) each of which contains +information about a file and a pointer to the file itself. +Directory entries may contain other directories +as well as plain files; such nested directories are referred to as +subdirectories. +A hierarchy of directories and files is formed in this manner +and is called a file system (or referred to as a file system tree). +.\" An entry in this tree, +.\" nested or not nested, +.\" is a pathname. +.Pp +Each directory file contains two special directory entries; one is a pointer +to the directory itself +called dot +.Ql .\& +and the other a pointer to its parent directory called dot-dot +.Ql \&.. . +Dot and dot-dot +are valid pathnames, however, +the system root directory +.Ql / , +has no parent and dot-dot points to itself like dot. +.Pp +File system nodes are ordinary directory files on which has +been grafted a file system object, such as a physical disk or a +partitioned area of such a disk. +(See +.Xr mount 2 +and +.Xr mount 8 . ) +.Pp +The directory entry format is defined in the file +.In sys/dirent.h +(which should not be included directly by applications): +.Bd -literal +#ifndef _SYS_DIRENT_H_ +#define _SYS_DIRENT_H_ + +#include + +/* + * The dirent structure defines the format of directory entries returned by + * the getdirentries(2) system call. + * + * A directory entry has a struct dirent at the front of it, containing its + * inode number, the length of the entry, and the length of the name + * contained in the entry. These are followed by the name padded to a 8 + * byte boundary with null bytes. All names are guaranteed null terminated. + * The maximum length of a name in a directory is MAXNAMLEN. + * Explicit pad is added between the last member of the header and + * d_name, to avoid having the ABI padding in the end of dirent on + * LP64 arches. There is code depending on d_name being last. Also, + * keeping this pad for ILP32 architectures simplifies compat32 layer. + */ + +struct dirent { + ino_t d_fileno; /* file number of entry */ + off_t d_off; /* directory offset of the next entry */ + __uint16_t d_reclen; /* length of this record */ + __uint8_t d_type; /* file type, see below */ + __uint8_t d_namlen; /* length of string in d_name */ + __uint32_t d_pad0; +#if __BSD_VISIBLE +#define MAXNAMLEN 255 + char d_name[MAXNAMLEN + 1]; /* name must be no longer than this */ +#else + char d_name[255 + 1]; /* name must be no longer than this */ +#endif +}; + +/* + * File types + */ +#define DT_UNKNOWN 0 +#define DT_FIFO 1 +#define DT_CHR 2 +#define DT_DIR 4 +#define DT_BLK 6 +#define DT_REG 8 +#define DT_LNK 10 +#define DT_SOCK 12 +#define DT_WHT 14 + +/* + * Convert between stat structure types and directory types. + */ +#define IFTODT(mode) (((mode) & 0170000) >> 12) +#define DTTOIF(dirtype) ((dirtype) << 12) + +/* + * The _GENERIC_DIRSIZ macro gives the minimum record length which will hold + * the directory entry. This returns the amount of space in struct direct + * without the d_name field, plus enough space for the name with a terminating + * null byte (dp->d_namlen+1), rounded up to a 8 byte boundary. + * + * XXX although this macro is in the implementation namespace, it requires + * a manifest constant that is not. + */ +#define _GENERIC_DIRLEN(namlen) \ + ((__offsetof(struct dirent, d_name) + (namlen) + 1 + 7) & ~7) +#define _GENERIC_DIRSIZ(dp) _GENERIC_DIRLEN((dp)->d_namlen) +#endif /* __BSD_VISIBLE */ + +#ifdef _KERNEL +#define GENERIC_DIRSIZ(dp) _GENERIC_DIRSIZ(dp) +#endif + +#endif /* !_SYS_DIRENT_H_ */ +.Ed +.Sh SEE ALSO +.Xr fs 5 , +.Xr inode 5 +.Sh HISTORY +A +.Nm +file format appeared in +.At v7 . +.Sh BUGS +The usage of the member d_type of struct dirent is unportable as it is +.Fx Ns -specific . +It also may fail on certain file systems, for example the cd9660 file system. diff --git a/static/freebsd/man5/disktab.5 b/static/freebsd/man5/disktab.5 new file mode 100644 index 00000000..96503099 --- /dev/null +++ b/static/freebsd/man5/disktab.5 @@ -0,0 +1,136 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 October 14, 2006 +.Dt DISKTAB 5 +.Os +.Sh NAME +.Nm disktab +.Nd disk description file +.Sh SYNOPSIS +.In disklabel.h +.Sh DESCRIPTION +.Nm Disktab +is a simple database which describes disk geometries and +disk partition characteristics. +It is used +.\"by the formatter(\c +.\"IR.Xr format 8 ) +.\"to determine how to format the disk, and +to initialize the disk label on the disk. +The format is patterned +after the +.Xr termcap 5 +terminal data base. +Entries in +.Nm +consist of a number of `:'-separated fields. +The +first field for each entry gives the names by which a +disk's entry may be selected, separated by `|' characters. +The +last name given should be a long name fully identifying +the disk. +.Pp +The optional fields for each entry are: +.Bl -column "indent" "boolx" +.It Sy "ID Type Description" +.It "\&ty str Type of disk (e.g. removable, winchester)" +.It "\&dt str Type of controller (e.g." +.Tn SMD , ESDI , +floppy) +.It "\&ns num Number of sectors per track" +.It "\&nt num Number of tracks per cylinder" +.It "\&nc num Total number of cylinders on the disk" +.It "\&sc num Number of sectors per cylinder, ns*nt default" +.It "\&su num Number of sectors per unit, sc*nc default" +.It "\&se num Sector size in bytes," +.Dv DEV_BSIZE +default +.It "\&sf bool Controller supports bad144-style bad sector forwarding" +.It "\&rm num Rotation speed, rpm, 3600 default" +.It "\&sk num Sector skew per track, default 0" +.It "\&cs num Sector skew per cylinder, default 0" +.It "\&hs num Headswitch time, usec, default 0" +.It "\&ts num One-cylinder seek time, usec, default 0" +.It "\&il num Sector interleave (n:1), 1 default" +.It "\&d[0-4] num Drive-type-dependent parameters" +.It "\&bs num Boot block size, default" +.Dv BBSIZE +.It "\&sb num Superblock size, default 0" +.It "\&ba num Block size for partition `a' (bytes)" +.It "\&bd num Block size for partition `d' (bytes)" +.It "\&be num Block size for partition `e' (bytes)" +.It "\&bf num Block size for partition `f' (bytes)" +.It "\&bg num Block size for partition `g' (bytes)" +.It "\&bh num Block size for partition `h' (bytes)" +.It "\&fa num Fragment size for partition `a' (bytes)" +.It "\&fd num Fragment size for partition `d' (bytes)" +.It "\&fe num Fragment size for partition `e' (bytes)" +.It "\&ff num Fragment size for partition `f' (bytes)" +.It "\&fg num Fragment size for partition `g' (bytes)" +.It "\&fh num Fragment size for partition `h' (bytes)" +.It "\&oa num Offset of partition `a' in sectors" +.It "\&ob num Offset of partition `b' in sectors" +.It "\&oc num Offset of partition `c' in sectors" +.It "\&od num Offset of partition `d' in sectors" +.It "\&oe num Offset of partition `e' in sectors" +.It "\&of num Offset of partition `f' in sectors" +.It "\&og num Offset of partition `g' in sectors" +.It "\&oh num Offset of partition `h' in sectors" +.It "\&pa num Size of partition `a' in sectors" +.It "\&pb num Size of partition `b' in sectors" +.It "\&pc num Size of partition `c' in sectors" +.It "\&pd num Size of partition `d' in sectors" +.It "\&pe num Size of partition `e' in sectors" +.It "\&pf num Size of partition `f' in sectors" +.It "\&pg num Size of partition `g' in sectors" +.It "\&ph num Size of partition `h' in sectors" +.It "\&ta str Partition type of partition `a'" +.Pf ( Bx 4.2 +file system, swap, etc) +.It "\&tb str Partition type of partition `b'" +.It "\&tc str Partition type of partition `c'" +.It "\&td str Partition type of partition `d'" +.It "\&te str Partition type of partition `e'" +.It "\&tf str Partition type of partition `f'" +.It "\&tg str Partition type of partition `g'" +.It "\&th str Partition type of partition `h'" +.El +.Sh FILES +.Bl -tag -width /etc/disktab -compact +.It Pa /etc/disktab +.El +.Sh SEE ALSO +.Xr getdiskbyname 3 , +.Xr bsdlabel 8 , +.Xr newfs 8 +.Sh HISTORY +The +.Nm +description file appeared in +.Bx 4.2 . diff --git a/static/freebsd/man5/elf.5 b/static/freebsd/man5/elf.5 new file mode 100644 index 00000000..d89a917b --- /dev/null +++ b/static/freebsd/man5/elf.5 @@ -0,0 +1,1469 @@ +.\" Copyright (c) 1999 Jeroen Ruigrok van der Werven +.\" 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 May 26, 2025 +.Dt ELF 5 +.Os +.Sh NAME +.Nm elf +.Nd format of ELF executable binary files +.Sh SYNOPSIS +.In elf.h +.Sh DESCRIPTION +The header file +.In elf.h +defines the format of ELF executable binary files. +Amongst these files are +normal executable files, relocatable object files, core files and shared +libraries. +.Pp +An executable file using the ELF file format consists of an ELF header, +followed by a program header table or a section header table, or both. +The ELF header is always at offset zero of the file. +The program header +table and the section header table's offset in the file are defined in the +ELF header. +The two tables describe the rest of the particularities of +the file. +.Pp +Applications which wish to process ELF binary files for their native +architecture only should include +.In elf.h +in their source code. +These applications should need to refer to +all the types and structures by their generic names +.Dq Elf_xxx +and to the macros by +.Dq ELF_xxx . +Applications written this way can be compiled on any architecture, +regardless whether the host is 32-bit or 64-bit. +.Pp +Should an application need to process ELF files of an unknown +architecture then the application needs to include both +.In sys/elf32.h +and +.In sys/elf64.h +instead of +.In elf.h . +Furthermore, all types and structures need to be identified by either +.Dq Elf32_xxx +or +.Dq Elf64_xxx . +The macros need to be identified by +.Dq ELF32_xxx +or +.Dq ELF64_xxx . +.Pp +Whatever the system's architecture is, it will always include +.In sys/elf_common.h +as well as +.In sys/elf_generic.h . +.Pp +These header files describe the above mentioned headers as C structures +and also include structures for dynamic sections, relocation sections and +symbol tables. +.Pp +The following types are being used for 32-bit architectures: +.Bd -literal -offset indent +Elf32_Addr Unsigned 32-bit program address +Elf32_Half Unsigned 16-bit field +Elf32_Lword Unsigned 64-bit field +Elf32_Off Unsigned 32-bit file offset +Elf32_Sword Signed 32-bit field or integer +Elf32_Word Unsigned 32-bit field or integer +.Ed +.Pp +For 64-bit architectures we have the following types: +.Bd -literal -offset indent +Elf64_Addr Unsigned 64-bit program address +Elf64_Half Unsigned 16-bit field +Elf64_Lword Unsigned 64-bit field +Elf64_Off Unsigned 64-bit file offset +Elf64_Sword Signed 32-bit field +Elf64_Sxword Signed 64-bit field or integer +Elf64_Word Unsigned 32-bit field +Elf64_Xword Unsigned 64-bit field or integer +.Ed +.Pp +All data structures that the file format defines follow the +.Dq natural +size and alignment guidelines for the relevant class. +If necessary, +data structures contain explicit padding to ensure 4-byte alignment +for 4-byte objects, to force structure sizes to a multiple of 4, etc. +.Pp +The ELF header is described by the type Elf32_Ehdr or Elf64_Ehdr: +.Bd -literal -offset indent +typedef struct { + unsigned char e_ident[EI_NIDENT]; + Elf32_Half e_type; + Elf32_Half e_machine; + Elf32_Word e_version; + Elf32_Addr e_entry; + Elf32_Off e_phoff; + Elf32_Off e_shoff; + Elf32_Word e_flags; + Elf32_Half e_ehsize; + Elf32_Half e_phentsize; + Elf32_Half e_phnum; + Elf32_Half e_shentsize; + Elf32_Half e_shnum; + Elf32_Half e_shstrndx; +} Elf32_Ehdr; +.Ed +.Bd -literal -offset indent +typedef struct { + unsigned char e_ident[EI_NIDENT]; + Elf64_Half e_type; + Elf64_Half e_machine; + Elf64_Word e_version; + Elf64_Addr e_entry; + Elf64_Off e_phoff; + Elf64_Off e_shoff; + Elf64_Word e_flags; + Elf64_Half e_ehsize; + Elf64_Half e_phentsize; + Elf64_Half e_phnum; + Elf64_Half e_shentsize; + Elf64_Half e_shnum; + Elf64_Half e_shstrndx; +} Elf64_Ehdr; +.Ed +.Pp +The fields have the following meanings: +.Pp +.Bl -tag -width "e_phentsize" -compact -offset indent +.It Dv e_ident +This array of bytes specifies to interpret the file, +independent of the processor or the file's remaining contents. +Within this array everything is named by macros, which start with +the prefix +.Sy EI_ +and may contain values which start with the prefix +.Sy ELF . +The following macros are defined: +.Pp +.Bl -tag -width "EI_ABIVERSION" -compact +.It Dv EI_MAG0 +The first byte of the magic number. +It must be filled with +.Sy ELFMAG0 . +.It Dv EI_MAG1 +The second byte of the magic number. +It must be filled with +.Sy ELFMAG1 . +.It Dv EI_MAG2 +The third byte of the magic number. +It must be filled with +.Sy ELFMAG2 . +.It Dv EI_MAG3 +The fourth byte of the magic number. +It must be filled with +.Sy ELFMAG3 . +.It Dv EI_CLASS +The fifth byte identifies the architecture for this binary: +.Pp +.Bl -tag -width "ELFCLASSNONE" -compact +.It Dv ELFCLASSNONE +This class is invalid. +.It Dv ELFCLASS32 +This defines the 32-bit architecture. +It supports machines with files +and virtual address spaces up to 4 Gigabytes. +.It Dv ELFCLASS64 +This defines the 64-bit architecture. +.El +.It Dv EI_DATA +The sixth byte specifies the data encoding of the processor-specific +data in the file. +Currently these encodings are supported: +.Pp +.Bl -tag -width "ELFDATA2LSB" -compact +.It Dv ELFDATANONE +Unknown data format. +.It Dv ELFDATA2LSB +Two's complement, little-endian. +.It Dv ELFDATA2MSB +Two's complement, big-endian. +.El +.It Dv EI_VERSION +The version number of the ELF specification: +.Pp +.Bl -tag -width "EV_CURRENT" -compact +.It Dv EV_NONE +Invalid version. +.It Dv EV_CURRENT +Current version. +.El +.It Dv EI_OSABI +This byte identifies the operating system +and ABI to which the object is targeted. +Some fields in other ELF structures have flags +and values that have platform specific meanings; +the interpretation of those fields is determined by the value of this byte. +The following values are currently defined: +.Pp +.Bl -tag -width "ELFOSABI_STANDALONE" -compact +.It Dv ELFOSABI_SYSV +UNIX System V ABI. +.It Dv ELFOSABI_HPUX +HP-UX operating system ABI. +.It Dv ELFOSABI_NETBSD +.Nx +operating system ABI. +.It Dv ELFOSABI_LINUX +GNU/Linux operating system ABI. +.It Dv ELFOSABI_HURD +GNU/Hurd operating system ABI. +.It Dv ELFOSABI_86OPEN +86Open Common IA32 ABI. +.It Dv ELFOSABI_SOLARIS +Solaris operating system ABI. +.It Dv ELFOSABI_MONTEREY +Monterey project ABI. +.It Dv ELFOSABI_IRIX +IRIX operating system ABI. +.It Dv ELFOSABI_FREEBSD +.Fx +operating system ABI. +.It Dv ELFOSABI_TRU64 +TRU64 UNIX operating system ABI. +.It Dv ELFOSABI_ARM +ARM architecture ABI. +.It Dv ELFOSABI_STANDALONE +Standalone (embedded) ABI. +.El +.It Dv EI_ABIVERSION +This byte identifies the version of the ABI +to which the object is targeted. +This field is used to distinguish among incompatible versions of an ABI. +The interpretation of this version number +is dependent on the ABI identified by the EI_OSABI field. +Applications conforming to this specification use the value 0. +.It Dv EI_PAD +Start of padding. +These bytes are reserved and set to zero. +Programs +which read them should ignore them. +The value for EI_PAD will change in +the future if currently unused bytes are given meanings. +.It Dv EI_BRAND +Start of architecture identification. +.It Dv EI_NIDENT +The size of the e_ident array. +.El +.Pp +.It Dv e_type +This member of the structure identifies the object file type: +.Pp +.Bl -tag -width "ET_NONE" -compact +.It Dv ET_NONE +An unknown type. +.It Dv ET_REL +A relocatable file. +.It Dv ET_EXEC +An executable file. +.It Dv ET_DYN +A shared object. +.It Dv ET_CORE +A core file. +.El +.Pp +.It Dv e_machine +This member specifies the required architecture for an individual file: +.Pp +.Bl -tag -width "EM_MIPS_RS4_BE" -compact +.It Dv EM_NONE +An unknown machine. +.It Dv EM_M32 +AT&T WE 32100. +.It Dv EM_SPARC +Sun Microsystems SPARC. +.It Dv EM_386 +Intel 80386. +.It Dv EM_68K +Motorola 68000. +.It Dv EM_88K +Motorola 88000. +.It Dv EM_486 +Intel 80486. +.It Dv EM_860 +Intel 80860. +.It Dv EM_MIPS +MIPS RS3000 (big-endian only). +.It Dv EM_MIPS_RS4_BE +MIPS RS4000 (big-endian only). +.It Dv EM_SPARC64 +SPARC v9 64-bit unofficial. +.It Dv EM_PARISC +HPPA. +.It Dv EM_PPC +PowerPC. +.It Dv EM_ALPHA +Compaq [DEC] Alpha. +.El +.Pp +.It Dv e_version +This member identifies the file version: +.Pp +.Bl -tag -width "EV_CURRENT" -compact +.It Dv EV_NONE +Invalid version +.It Dv EV_CURRENT +Current version +.El +.It Dv e_entry +This member gives the virtual address to which the system first transfers +control, thus starting the process. +If the file has no associated entry +point, this member holds zero. +.It Dv e_phoff +This member holds the program header table's file offset in bytes. +If +the file has no program header table, this member holds zero. +.It Dv e_shoff +This member holds the section header table's file offset in bytes. +If the +file has no section header table this member holds zero. +.It Dv e_flags +This member holds processor-specific flags associated with the file. +Flag +names take the form EF_`machine_flag'. +Currently no flags have been defined. +.It Dv e_ehsize +This member holds the ELF header's size in bytes. +.It Dv e_phentsize +This member holds the size in bytes of one entry in the file's program header +table; all entries are the same size. +.It Dv e_phnum +This member holds the number of entries in the program header +table. +If the file is using extended program header numbering, then the +.Sy e_phnum +member will contain the value +.Dv PN_XNUM +and the actual number of program header table entries will be stored +in the +.Sy sh_info +member of the section header at index +.Dv SHN_UNDEF . +The product of +.Sy e_phentsize +and the number of program header table entries gives the program +header table's size in bytes. +If a file has no program header, +.Sy e_phnum +holds the value zero. +.It Dv e_shentsize +This member holds a sections header's size in bytes. +A section header is one +entry in the section header table; all entries are the same size. +.It Dv e_shnum +This member holds the number of entries in the section header table. +If the file is using extended section numbering, then the +.Sy e_shnum +member will be zero and the actual section number will be stored in the +.Sy sh_size +member of the section header at index +.Dv SHN_UNDEF . +If a file has no section header table, both the +.Sy e_shnum +and the +.Sy e_shoff +fields of the ELF header will be zero. +The product of +.Sy e_shentsize +and the number of sections in the file gives the section header +table's size in bytes. +.It Dv e_shstrndx +This member holds the section header table index of the entry associated +with the section name string table. +If extended section numbering is being used, this field will hold the +value +.Sy SHN_XINDEX , +and the actual section header table index will be present in the +.Sy sh_link +field of the section header entry at index +.Dv SHN_UNDEF . +If the file has no section name string +table, this member holds the value +.Sy SHN_UNDEF . +.El +.Pp +An executable or shared object file's program header table is an array of +structures, each describing a segment or other information the system needs +to prepare the program for execution. +An object file +.Em segment +contains one or more +.Em sections . +Program headers are meaningful only for executable and shared object files. +A file specifies its own program header size with the ELF header's +.Sy e_phentsize +and +.Sy e_phnum +members. +As with the Elf executable header, the program header +also has different versions depending on the architecture: +.Bd -literal -offset indent +typedef struct { + Elf32_Word p_type; + Elf32_Off p_offset; + Elf32_Addr p_vaddr; + Elf32_Addr p_paddr; + Elf32_Word p_filesz; + Elf32_Word p_memsz; + Elf32_Word p_flags; + Elf32_Word p_align; +} Elf32_Phdr; +.Ed +.Bd -literal -offset indent +typedef struct { + Elf64_Word p_type; + Elf64_Word p_flags; + Elf64_Off p_offset; + Elf64_Addr p_vaddr; + Elf64_Addr p_paddr; + Elf64_Xword p_filesz; + Elf64_Xword p_memsz; + Elf64_Xword p_align; +} Elf64_Phdr; +.Ed +.Pp +The main difference between the 32-bit and the 64-bit program header lies +only in the location of a +.Sy p_flags +member in the total struct. +.Pp +.Bl -tag -width "p_offset" -compact -offset indent +.It Dv p_type +This member of the Phdr struct tells what kind of segment this array +element describes or how to interpret the array element's information. +.Pp +.Bl -tag -width "PT_DYNAMIC" -compact +.It Dv PT_NULL +The array element is unused and the other members' values are undefined. +This lets the program header have ignored entries. +.It Dv PT_LOAD +The array element specifies a loadable segment, described by +.Sy p_filesz +and +.Sy p_memsz . +The bytes from the file are mapped to the beginning of the memory +segment. +If the segment's memory size +.Pq Sy p_memsz +is larger than the file size +.Pq Sy p_filesz , +the +.Dq extra +bytes are defined to hold the value 0 and to follow the segment's +initialized area. +The file size may not be larger than the memory size. +Loadable segment entries in the program header table appear in ascending +order, sorted on the +.Sy p_vaddr +member. +.It Dv PT_DYNAMIC +The array element specifies dynamic linking information. +.It Dv PT_INTERP +The array element specifies the location and size of a null-terminated +path name to invoke as an interpreter. +This segment type is meaningful +only for executable files (though it may occur for shared objects). +However +it may not occur more than once in a file. +If it is present it must precede +any loadable segment entry. +.It Dv PT_NOTE +The array element specifies the location and size for auxiliary information. +.It Dv PT_SHLIB +This segment type is reserved but has unspecified semantics. +Programs that +contain an array element of this type do not conform to the ABI. +.It Dv PT_PHDR +The array element, if present, specifies the location and size of the program +header table itself, both in the file and in the memory image of the program. +This segment type may not occur more than once in a file. +Moreover, it may +only occur if the program header table is part of the memory image of the +program. +If it is present it must precede any loadable segment entry. +.It Dv PT_LOPROC +This value up to and including +.Sy PT_HIPROC +are reserved for processor-specific semantics. +.It Dv PT_HIPROC +This value down to and including +.Sy PT_LOPROC +are reserved for processor-specific semantics. +.El +.Pp +.It Dv p_offset +This member holds the offset from the beginning of the file at which +the first byte of the segment resides. +.It Dv p_vaddr +This member holds the virtual address at which the first byte of the +segment resides in memory. +.It Dv p_paddr +On systems for which physical addressing is relevant, this member is +reserved for the segment's physical address. +Under +.Bx +this member is +not used and must be zero. +.It Dv p_filesz +This member holds the number of bytes in the file image of the segment. +It may be zero. +.It Dv p_memsz +This member holds the number of bytes in the memory image of the segment. +It may be zero. +.It Dv p_flags +This member holds flags relevant to the segment: +.Pp +.Bl -tag -width "PF_X" -compact +.It Dv PF_X +An executable segment. +.It Dv PF_W +A writable segment. +.It Dv PF_R +A readable segment. +.El +.Pp +A text segment commonly has the flags +.Sy PF_X +and +.Sy PF_R . +A data segment commonly has +.Sy PF_X , +.Sy PF_W +and +.Sy PF_R . +.It Dv p_align +This member holds the value to which the segments are aligned in memory +and in the file. +Loadable process segments must have congruent values for +.Sy p_vaddr +and +.Sy p_offset , +modulo the page size. +Values of zero and one mean no alignment is required. +Otherwise, +.Sy p_align +should be a positive, integral power of two, and +.Sy p_vaddr +should equal +.Sy p_offset , +modulo +.Sy p_align . +.El +.Pp +An file's section header table lets one locate all the file's sections. +The +section header table is an array of Elf32_Shdr or Elf64_Shdr structures. +The +ELF header's +.Sy e_shoff +member gives the byte offset from the beginning of the file to the section +header table. +.Sy e_shnum +holds the number of entries the section header table contains. +.Sy e_shentsize +holds the size in bytes of each entry. +.Pp +A section header table index is a subscript into this array. +Some section +header table indices are reserved. +An object file does not have sections for +these special indices: +.Pp +.Bl -tag -width "SHN_LORESERVE" -compact +.It Dv SHN_UNDEF +This value marks an undefined, missing, irrelevant, or otherwise meaningless +section reference. +For example, a symbol +.Dq defined +relative to section number +.Sy SHN_UNDEF +is an undefined symbol. +.It Dv SHN_LORESERVE +This value specifies the lower bound of the range of reserved indices. +.It Dv SHN_LOPROC +This value up to and including +.Sy SHN_HIPROC +are reserved for processor-specific semantics. +.It Dv SHN_HIPROC +This value down to and including +.Sy SHN_LOPROC +are reserved for processor-specific semantics. +.It Dv SHN_ABS +This value specifies absolute values for the corresponding reference. +For +example, symbols defined relative to section number +.Sy SHN_ABS +have absolute values and are not affected by relocation. +.It Dv SHN_COMMON +Symbols defined relative to this section are common symbols, such as FORTRAN +COMMON or unallocated C external variables. +.It Dv SHN_HIRESERVE +This value specifies the upper bound of the range of reserved indices. +The +system reserves indices between +.Sy SHN_LORESERVE +and +.Sy SHN_HIRESERVE , +inclusive. +The section header table does not contain entries for the +reserved indices. +.El +.Pp +The section header has the following structure: +.Bd -literal -offset indent +typedef struct { + Elf32_Word sh_name; + Elf32_Word sh_type; + Elf32_Word sh_flags; + Elf32_Addr sh_addr; + Elf32_Off sh_offset; + Elf32_Word sh_size; + Elf32_Word sh_link; + Elf32_Word sh_info; + Elf32_Word sh_addralign; + Elf32_Word sh_entsize; +} Elf32_Shdr; +.Ed +.Bd -literal -offset indent +typedef struct { + Elf64_Word sh_name; + Elf64_Word sh_type; + Elf64_Xword sh_flags; + Elf64_Addr sh_addr; + Elf64_Off sh_offset; + Elf64_Xword sh_size; + Elf64_Word sh_link; + Elf64_Word sh_info; + Elf64_Xword sh_addralign; + Elf64_Xword sh_entsize; +} Elf64_Shdr; +.Ed +.Pp +.Bl -tag -width "sh_addralign" -compact +.It Dv sh_name +This member specifies the name of the section. +Its value is an index +into the section header string table section, giving the location of +a null-terminated string. +.It Dv sh_type +This member categorizes the section's contents and semantics. +.Pp +.Bl -tag -width "SHT_PROGBITS" -compact +.It Dv SHT_NULL +This value marks the section header as inactive. +It does not +have an associated section. +Other members of the section header +have undefined values. +.It Dv SHT_PROGBITS +The section holds information defined by the program, whose +format and meaning are determined solely by the program. +.It Dv SHT_SYMTAB +This section holds a symbol table. +Typically, +.Sy SHT_SYMTAB +provides symbols for link editing, though it may also be used +for dynamic linking. +As a complete symbol table, it may contain +many symbols unnecessary for dynamic linking. +An object file can +also contain a +.Sy SHN_DYNSYM +section. +.It Dv SHT_STRTAB +This section holds a string table. +An object file may have multiple +string table sections. +.It Dv SHT_RELA +This section holds relocation entries with explicit addends, such +as type +.Sy Elf32_Rela +for the 32-bit class of object files. +An object may have multiple +relocation sections. +.It Dv SHT_HASH +This section holds a symbol hash table. +All object participating in +dynamic linking must contain a symbol hash table. +An object file may +have only one hash table. +.It Dv SHT_DYNAMIC +This section holds information for dynamic linking. +An object file may +have only one dynamic section. +.It Dv SHT_NOTE +This section holds information that marks the file in some way. +.It Dv SHT_NOBITS +A section of this type occupies no space in the file but otherwise +resembles +.Sy SHN_PROGBITS . +Although this section contains no bytes, the +.Sy sh_offset +member contains the conceptual file offset. +.It Dv SHT_REL +This section holds relocation offsets without explicit addends, such +as type +.Sy Elf32_Rel +for the 32-bit class of object files. +An object file may have multiple +relocation sections. +.It Dv SHT_SHLIB +This section is reserved but has unspecified semantics. +.It Dv SHT_DYNSYM +This section holds a minimal set of dynamic linking symbols. +An +object file can also contain a +.Sy SHN_SYMTAB +section. +.It Dv SHT_LOPROC +This value up to and including +.Sy SHT_HIPROC +are reserved for processor-specific semantics. +.It Dv SHT_HIPROC +This value down to and including +.Sy SHT_LOPROC +are reserved for processor-specific semantics. +.It Dv SHT_LOUSER +This value specifies the lower bound of the range of indices reserved for +application programs. +.It Dv SHT_HIUSER +This value specifies the upper bound of the range of indices reserved for +application programs. +Section types between +.Sy SHT_LOUSER +and +.Sy SHT_HIUSER +may be used by the application, without conflicting with current or future +system-defined section types. +.El +.Pp +.It Dv sh_flags +Sections support one-bit flags that describe miscellaneous attributes. +If a flag bit is set in +.Sy sh_flags , +the attribute is +.Dq on +for the section. +Otherwise, the attribute is +.Dq off +or does not apply. +Undefined attributes are set to zero. +.Pp +.Bl -tag -width "SHF_EXECINSTR" -compact +.It Dv SHF_WRITE +This section contains data that should be writable during process +execution. +.It Dv SHF_ALLOC +The section occupies memory during process execution. +Some control +sections do not reside in the memory image of an object file. +This +attribute is off for those sections. +.It Dv SHF_EXECINSTR +The section contains executable machine instructions. +.It Dv SHF_MASKPROC +All bits included in this mask are reserved for processor-specific +semantics. +.It Dv SHF_COMPRESSED +The section data is compressed. +.El +.Pp +.It Dv sh_addr +If the section will appear in the memory image of a process, this member +holds the address at which the section's first byte should reside. +Otherwise, the member contains zero. +.It Dv sh_offset +This member's value holds the byte offset from the beginning of the file +to the first byte in the section. +One section type, +.Sy SHT_NOBITS , +occupies no space in the file, and its +.Sy sh_offset +member locates the conceptual placement in the file. +.It Dv sh_size +This member holds the section's size in bytes. +Unless the section type +is +.Sy SHT_NOBITS , +the section occupies +.Sy sh_size +bytes in the file. +A section of type +.Sy SHT_NOBITS +may have a non-zero size, but it occupies no space in the file. +.It Dv sh_link +This member holds a section header table index link, whose interpretation +depends on the section type. +.It Dv sh_info +This member holds extra information, whose interpretation depends on the +section type. +.It Dv sh_addralign +Some sections have address alignment constraints. +If a section holds a +doubleword, the system must ensure doubleword alignment for the entire +section. +That is, the value of +.Sy sh_addr +must be congruent to zero, modulo the value of +.Sy sh_addralign . +Only zero and positive integral powers of two are allowed. +Values of zero +or one mean the section has no alignment constraints. +.It Dv sh_entsize +Some sections hold a table of fixed-sized entries, such as a symbol table. +For such a section, this member gives the size in bytes for each entry. +This member contains zero if the section does not hold a table of +fixed-size entries. +.El +.Pp +Various sections hold program and control information: +.Bl -tag -width ".shstrtab" -compact +.It .bss +(Block Started by Symbol) +This section holds uninitialized data that contributes to the program's +memory image. +By definition, the system initializes the data with zeros +when the program begins to run. +This section is of type +.Sy SHT_NOBITS . +The attributes types are +.Sy SHF_ALLOC +and +.Sy SHF_WRITE . +.It .comment +This section holds version control information. +This section is of type +.Sy SHT_PROGBITS . +No attribute types are used. +.It .ctors +This legacy section holds pointers to initialization routines, +executed before calling the main program entry point. +This section is of type +.Sy SHT_PROGBITS . +The attributes used are +.Sy SHF_ALLOC . +.It .data +This section holds initialized data that contribute to the program's +memory image. +This section is of type +.Sy SHT_PROGBITS . +The attribute types are +.Sy SHF_ALLOC +and +.Sy SHF_WRITE . +.It .data1 +This section holds initialized data that contribute to the program's +memory image. +This section is of type +.Sy SHT_PROGBITS . +The attribute types are +.Sy SHF_ALLOC +and +.Sy SHF_WRITE . +.It .debug +This section holds information for symbolic debugging. +The contents +are unspecified. +This section is of type +.Sy SHT_PROGBITS . +No attribute types are used. +.It .dtors +This legacy section holds pointers to finalization routines, +executed when the program exits normally. +This section is of type +.Sy SHT_PROGBITS . +The attributes used are +.Sy SHF_ALLOC . +.It .dynamic +This section holds dynamic linking information. +The section's attributes +will include the +.Sy SHF_ALLOC +bit. +Whether the +.Sy SHF_WRITE +bit is set is processor-specific. +This section is of type +.Sy SHT_DYNAMIC . +See the attributes above. +.It .dynstr +This section holds strings needed for dynamic linking, most commonly +the strings that represent the names associated with symbol table entries. +This section is of type +.Sy SHT_STRTAB . +The attribute type used is +.Sy SHF_ALLOC . +.It .dynsym +This section holds the dynamic linking symbol table. +This section is of type +.Sy SHT_DYNSYM . +The attribute used is +.Sy SHF_ALLOC . +.It .fini +This legacy section holds executable instructions that contribute to the process +termination code. +When a program exits normally the system arranges to +execute the code in this section. +This section is of type +.Sy SHT_PROGBITS . +The attributes used are +.Sy SHF_ALLOC +and +.Sy SHF_EXECINSTR . +.It .fini_array +This section holds pointers to finalization routines. +When a program exits normally +.Xr rtld 1 +executes the code referenced by this section. +This section is of type +.Sy SHT_FINI_ARRAY . +The attributes used are +.Sy SHF_ALLOC . +Refer to +.Dv NT_FREEBSD_NOINIT_TAG +.Pq below +for a description of how initialization and finalization code is invoked. +.It .got +This section holds the global offset table. +This section is of type +.Sy SHT_PROGBITS . +The attributes are processor-specific. +.It .hash +This section holds a symbol hash table. +This section is of type +.Sy SHT_HASH . +The attribute used is +.Sy SHF_ALLOC . +.It .init +This legacy section holds executable instructions that contribute to the process +initialization code. +When a program starts to run the system arranges to +execute the code in this section before calling the main program entry point. +This section is of type +.Sy SHT_PROGBITS . +The attributes used are +.Sy SHF_ALLOC +and +.Sy SHF_EXECINSTR . +.It .init_array +This section holds pointers to initialization routines. +When a program starts to run +.Xr rtld 1 +executes the code referenced by this section before calling the program entry +point. +This section is of type +.Sy SHT_INIT_ARRAY . +The attributes used are +.Sy SHF_ALLOC . +Refer to +.Dv NT_FREEBSD_NOINIT_TAG +.Pq below +for a description of how initialization and finalization code is invoked. +.It .interp +This section holds the pathname of a program interpreter. +If the file has +a loadable segment that includes the section, the section's attributes will +include the +.Sy SHF_ALLOC +bit. +Otherwise, that bit will be off. +This section is of type +.Sy SHT_PROGBITS . +.It .line +This section holds line number information for symbolic debugging, which +describes the correspondence between the program source and the machine code. +The contents are unspecified. +This section is of type +.Sy SHT_PROGBITS . +No attribute types are used. +.It .note +This section holds information in the +.Dq Note Section +format described below. +This section is of type +.Sy SHT_NOTE . +No attribute types are used. +.It .plt +This section holds the procedure linkage table. +This section is of type +.Sy SHT_PROGBITS . +The attributes are processor-specific. +.It .relNAME +This section holds relocation information as described below. +If the file +has a loadable segment that includes relocation, the section's attributes +will include the +.Sy SHF_ALLOC +bit. +Otherwise the bit will be off. +By convention, +.Dq NAME +is supplied by the section to which the relocations apply. +Thus a relocation +section for +.Sy .text +normally would have the name +.Sy .rel.text . +This section is of type +.Sy SHT_REL . +.It .relaNAME +This section holds relocation information as described below. +If the file +has a loadable segment that includes relocation, the section's attributes +will include the +.Sy SHF_ALLOC +bit. +Otherwise the bit will be off. +By convention, +.Dq NAME +is supplied by the section to which the relocations apply. +Thus a relocation +section for +.Sy .text +normally would have the name +.Sy .rela.text . +This section is of type +.Sy SHT_RELA . +.It .rodata +This section holds read-only data that typically contributes to a +non-writable segment in the process image. +This section is of type +.Sy SHT_PROGBITS . +The attribute used is +.Sy SHF_ALLOC . +.It .rodata1 +This section holds read-only data that typically contributes to a +non-writable segment in the process image. +This section is of type +.Sy SHT_PROGBITS . +The attribute used is +.Sy SHF_ALLOC . +.It .shstrtab +This section holds section names. +This section is of type +.Sy SHT_STRTAB . +No attribute types are used. +.It .strtab +This section holds strings, most commonly the strings that represent the +names associated with symbol table entries. +If the file has a loadable +segment that includes the symbol string table, the section's attributes +will include the +.Sy SHF_ALLOC +bit. +Otherwise the bit will be off. +This section is of type +.Sy SHT_STRTAB . +.It .symtab +This section holds a symbol table. +If the file has a loadable segment +that includes the symbol table, the section's attributes will include +the +.Sy SHF_ALLOC +bit. +Otherwise the bit will be off. +This section is of type +.Sy SHT_SYMTAB . +.It .text +This section holds the +.Dq text , +or executable instructions, of a program. +This section is of type +.Sy SHT_PROGBITS . +The attributes used are +.Sy SHF_ALLOC +and +.Sy SHF_EXECINSTR . +.It .jcr +This section holds information about Java classes that must +be registered. +It is obsolete and binaries created for +.Fx 15 +or later do not process it. +.It .eh_frame +This section holds information used for C++ exception-handling. +.El +.Pp +A section with the +.Dv SHF_COMPRESSED +flag set contains a compressed copy of the section data. +Compressed section data begins with an +.Vt Elf64_Chdr +or +.Vt Elf32_Chdr structure +which encodes the compression algorithm and some characteristics of the +uncompressed data. +.Bd -literal -offset indent +typedef struct { + Elf32_Word ch_type; + Elf32_Word ch_size; + Elf32_Word ch_addralign; +} Elf32_Chdr; +.Ed +.Bd -literal -offset indent +typedef struct { + Elf64_Word ch_type; + Elf64_Word ch_reserved; + Elf64_Xword ch_size; + Elf64_Xword ch_addralign; +} Elf64_Chdr; +.Ed +.Pp +.Bl -tag -width "ch_addralign" -compact +.It Dv ch_type +The compression algorithm used. +A value of +.Dv ELFCOMPRESS_ZLIB +indicates that the data is compressed using +.Xr zlib 3 . +A value of +.Dv ELFCOMPRESS_ZSTD +indicates that the data is compressed using +Zstandard. +.It Dv ch_size +The size, in bytes, of the uncompressed section data. +This corresponds to the +.Sy sh_size +field of a section header containing uncompressed data. +.It Dv ch_addralign +The address alignment of the uncompressed section data. +This corresponds to the +.Sy sh_addralign +field of a section header containing uncompressed data. +.El +.Pp +String table sections hold null-terminated character sequences, commonly +called strings. +The object file uses these strings to represent symbol +and section names. +One references a string as an index into the string +table section. +The first byte, which is index zero, is defined to hold +a null character. +Similarly, a string table's last byte is defined to +hold a null character, ensuring null termination for all strings. +.Pp +An object file's symbol table holds information needed to locate and +relocate a program's symbolic definitions and references. +A symbol table +index is a subscript into this array. +.Bd -literal -offset indent +typedef struct { + Elf32_Word st_name; + Elf32_Addr st_value; + Elf32_Word st_size; + unsigned char st_info; + unsigned char st_other; + Elf32_Half st_shndx; +} Elf32_Sym; +.Ed +.Bd -literal -offset indent +typedef struct { + Elf64_Word st_name; + unsigned char st_info; + unsigned char st_other; + Elf64_Half st_shndx; + Elf64_Addr st_value; + Elf64_Xword st_size; +} Elf64_Sym; +.Ed +.Pp +.Bl -tag -width "st_value" -compact +.It Dv st_name +This member holds an index into the object file's symbol string table, +which holds character representations of the symbol names. +If the value +is non-zero, it represents a string table index that gives the symbol +name. +Otherwise, the symbol table has no name. +.It Dv st_value +This member gives the value of the associated symbol. +.It Dv st_size +Many symbols have associated sizes. +This member holds zero if the symbol +has no size or an unknown size. +.It Dv st_info +This member specifies the symbol's type and binding attributes: +.Pp +.Bl -tag -width "STT_SECTION" -compact +.It Dv STT_NOTYPE +The symbol's type is not defined. +.It Dv STT_OBJECT +The symbol is associated with a data object. +.It Dv STT_FUNC +The symbol is associated with a function or other executable code. +.It Dv STT_SECTION +The symbol is associated with a section. +Symbol table entries of +this type exist primarily for relocation and normally have +.Sy STB_LOCAL +bindings. +.It Dv STT_FILE +By convention the symbol's name gives the name of the source file +associated with the object file. +A file symbol has +.Sy STB_LOCAL +bindings, its section index is +.Sy SHN_ABS , +and it precedes the other +.Sy STB_LOCAL +symbols of the file, if it is present. +.It Dv STT_LOPROC +This value up to and including +.Sy STT_HIPROC +are reserved for processor-specific semantics. +.It Dv STT_HIPROC +This value down to and including +.Sy STT_LOPROC +are reserved for processor-specific semantics. +.El +.Pp +.Bl -tag -width "STB_GLOBAL" -compact +.It Dv STB_LOCAL +Local symbols are not visible outside the object file containing their +definition. +Local symbols of the same name may exist in multiple file +without interfering with each other. +.It Dv STB_GLOBAL +Global symbols are visible to all object files being combined. +One file's +definition of a global symbol will satisfy another file's undefined +reference to the same symbol. +.It Dv STB_WEAK +Weak symbols resemble global symbols, but their definitions have lower +precedence. +.It Dv STB_LOPROC +This value up to and including +.Sy STB_HIPROC +are reserved for processor-specific semantics. +.It Dv STB_HIPROC +This value down to and including +.Sy STB_LOPROC +are reserved for processor-specific semantics. +.Pp +There are macros for packing and unpacking the binding and type fields: +.Pp +.Bl -tag -width "ELF32_ST_INFO(bind, type)" -compact +.It Xo +.Fn ELF32_ST_BIND info +.Xc +or +.Fn ELF64_ST_BIND info +extract a binding from an st_info value. +.It Xo +.Fn ELF64_ST_TYPE info +.Xc +or +.Fn ELF32_ST_TYPE info +extract a type from an st_info value. +.It Xo +.Fn ELF32_ST_INFO bind type +.Xc +or +.Fn ELF64_ST_INFO bind type +convert a binding and a type into an st_info value. +.El +.El +.Pp +.It Dv st_other +This member currently holds zero and has no defined meaning. +.It Dv st_shndx +Every symbol table entry is +.Dq defined +in relation to some section. +This member holds the relevant section +header table index. +.El +.Pp +Relocation is the process of connecting symbolic references with +symbolic definitions. +Relocatable files must have information that +describes how to modify their section contents, thus allowing executable +and shared object files to hold the right information for a process' +program image. +Relocation entries are these data. +.Pp +Relocation structures that do not need an addend: +.Bd -literal -offset indent +typedef struct { + Elf32_Addr r_offset; + Elf32_Word r_info; +} Elf32_Rel; +.Ed +.Bd -literal -offset indent +typedef struct { + Elf64_Addr r_offset; + Elf64_Xword r_info; +} Elf64_Rel; +.Ed +.Pp +Relocation structures that need an addend: +.Bd -literal -offset indent +typedef struct { + Elf32_Addr r_offset; + Elf32_Word r_info; + Elf32_Sword r_addend; +} Elf32_Rela; +.Ed +.Bd -literal -offset indent +typedef struct { + Elf64_Addr r_offset; + Elf64_Xword r_info; + Elf64_Sxword r_addend; +} Elf64_Rela; +.Ed +.Pp +.Bl -tag -width "r_offset" -compact +.It Dv r_offset +This member gives the location at which to apply the relocation action. +For a relocatable file, the value is the byte offset from the beginning +of the section to the storage unit affected by the relocation. +For an +executable file or shared object, the value is the virtual address of +the storage unit affected by the relocation. +.It Dv r_info +This member gives both the symbol table index with respect to which the +relocation must be made and the type of relocation to apply. +Relocation +types are processor-specific. +When the text refers to a relocation +entry's relocation type or symbol table index, it means the result of +applying +.Sy ELF_[32|64]_R_TYPE +or +.Sy ELF[32|64]_R_SYM , +respectively to the entry's +.Sy r_info +member. +.It Dv r_addend +This member specifies a constant addend used to compute the value to be +stored into the relocatable field. +.El +.Ss Note Section +ELF note sections consist of entries with the following format: +.Bl -column -offset indent "namesz" "32 bits" "Null-terminated originator name" +.Sy Field Ta Sy Size Ta Sy Description +.It Va namesz Ta 32 bits Ta Size of "name" +.It Va descsz Ta 32 bits Ta Size of "desc" +.It Va type Ta 32 bits Ta OS-dependent note type +.It Va name Ta Va namesz Ta Null-terminated originator name +.It Va desc Ta Va descsz Ta OS-dependent note data +.El +.Pp +The +.Va name +and +.Va desc +fields are padded to ensure 4-byte alignment. +.Va namesz +and +.Va descsz +specify the unpadded length. +.Pp +.Fx +defines the following ELF note types +.Po with corresponding interpretation of +.Va desc Pc : +.Bl -tag -width 4n +.It Dv NT_FREEBSD_ABI_TAG Pq Value: 1 +Indicates the OS ABI version in a form of a 32-bit integer containing expected +ABI version +.Po i.e., +.Dv __FreeBSD_version Pc . +.It Dv NT_FREEBSD_NOINIT_TAG Pq Value: 2 +Indicates that the C startup does not call initialization routines, and thus +.Xr rtld 1 +must do so. +.Va desc +is ignored. +.It Dv NT_FREEBSD_ARCH_TAG Pq Value: 3 +Contains the MACHINE_ARCH that the executable was built for. +.It Dv NT_FREEBSD_FEATURE_CTL Pq Value: 4 +Contains a bitmask of mitigations and features to enable: +.Bl -tag -width 4n +.It NT_FREEBSD_FCTL_ASLR_DISABLE Pq Value: 0x01 +Request that address randomization (ASLR) not be performed. +See +.Xr security 7 . +.It NT_FREEBSD_FCTL_PROTMAX_DISABLE Pq Value: 0x02 +Request that +.Xr mmap 2 +calls not set PROT_MAX to the initial value of the +.Fa prot +argument. +.It NT_FREEBSD_FCTL_STKGAP_DISABLE Pq Value: 0x04 +Disable stack gap. +.It NT_FREEBSD_FCTL_WXNEEDED Pq Value: 0x08 +Indicate that the binary requires mappings that are simultaneously +writeable and executable. +.It NT_FREEBSD_FCTL_LA48 Pq Value: 0x10 +Request 48-bit linear address space on amd64. +.It NT_FREEBSD_FCTL_LA57 Pq Value: 0x40 +Accept 57-bit linear address space on amd64. +.El +.El +.Sh SEE ALSO +.Xr as 1 , +.Xr gdb 1 Pq Pa ports/devel/gdb , +.Xr ld 1 , +.Xr objdump 1 , +.Xr readelf 1 , +.Xr execve 2 , +.Xr zlib 3 , +.Xr ar 5 , +.Xr core 5 +.Rs +.%A Hewlett Packard +.%B Elf-64 Object File Format +.Re +.Rs +.%A Santa Cruz Operation +.%B System V Application Binary Interface +.Re +.Rs +.%A Unix System Laboratories +.%T Object Files +.%B "Executable and Linking Format (ELF)" +.Re +.Sh HISTORY +The ELF header files made their appearance in +.Fx 2.2.6 . +ELF in itself first appeared in +.At V . +The ELF format is an adopted standard. +.Sh AUTHORS +This manual page was written by +.An Jeroen Ruigrok van der Werven Aq Mt asmodai@FreeBSD.org +with inspiration from BSDi's +.Bsx +.Nm +manpage. diff --git a/static/freebsd/man5/ethers.5 b/static/freebsd/man5/ethers.5 new file mode 100644 index 00000000..03312d17 --- /dev/null +++ b/static/freebsd/man5/ethers.5 @@ -0,0 +1,100 @@ +.\" Copyright (c) 1995 +.\" Bill Paul . 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 Bill Paul. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Bill Paul 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 REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 12, 1995 +.Dt ETHERS 5 +.Os +.Sh NAME +.Nm ethers +.Nd ethernet address database +.Sh DESCRIPTION +The +.Nm +database contains information regarding known 48-bit ethernet addresses +of hosts on an Internetwork. +The data is stored in a file called +.Pa /etc/ethers +in the following format: +.Pp +.D1 Ar ethernet-address fully-qualified-host-name +.Pp +Items are separated by any number of blanks and/or +tab characters. +A ``#'' at the start of a line indicates the +beginning of a comment that extends to the end of the line. +A ``+'' at +the start of a line will cause the +.Xr ethers 3 +library functions to use data stored in the +.Tn NIS +.Pa ethers.byname +and +.Pa ethers.byaddr +maps in addition to the data in the +.Pa /etc/ethers +file. +.Pp +An ethernet address is expressed in +.Tn ASCII +form as "x:x:x:x:x:x" where +.Ar x +is a hexadecimal value between 0x00 and 0xFF. +The address values +should be in network order. +Hostnames specified in the +.Pa /etc/ethers +database should correspond to entries in the +.Xr hosts 5 +file. +.Pp +The +.Fn ether_line +function in the standard C library can be used to break individual +lines in the +.Pa /etc/ethers +database into their individual components: a binary Ethernet address +stored as an +.Pa ether_addr +structure, and a hostname stored as a character string. +.Sh FILES +.Bl -tag -width /etc/services -compact +.It Pa /etc/ethers +The +.Nm +file resides in +.Pa /etc . +.El +.Sh SEE ALSO +.Xr ethers 3 , +.Xr yp 8 +.Sh HISTORY +The +.Nm +format is based on the format used in SunOS 4.1.x. diff --git a/static/freebsd/man5/eui64.5 b/static/freebsd/man5/eui64.5 new file mode 100644 index 00000000..72fa6f72 --- /dev/null +++ b/static/freebsd/man5/eui64.5 @@ -0,0 +1,108 @@ +.\" Copyright (c) 1995 +.\" Bill Paul . 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 Bill Paul. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Bill Paul 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 REGENTS 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 May 11, 2004 +.Dt EUI64 5 +.Os +.Sh NAME +.Nm eui64 +.Nd IEEE EUI-64 address database +.Sh DESCRIPTION +The +.Nm +database contains information regarding known IEEE EUI-64s of hosts. +The data is stored in a file called +.Pa /etc/eui64 +in the following format: +.Bd -ragged -offset indent +.Em EUI-64 host-name +.Ed +.Pp +Items are separated by any number of blanks and/or +tab characters. +A +.Ql # +at the start of a line indicates the +beginning of a comment that extends to the end of the line. +Valid lines may also contain comments. +A +.Ql + +at the start of a line will cause the +.Xr eui64 3 +library functions to use data stored in the +NIS +.Pa eui64.byname +and +.Pa eui64.byid +maps in addition to the data in the +.Pa /etc/eui64 +file. +.Pp +An EUI-64 is expressed in +.Tn ASCII +form as +.Qq x-x-x-x-x-x-x-x +where +.Ar x +is a hexadecimal value between 0x00 and 0xFF. +The address values +should be in network order. +Hostnames specified in the +.Pa /etc/eui64 +database should correspond to entries in the +.Xr hosts 5 +file. +.\" .Pp +.\" The +.\" .Fn eui64_line +.\" function in the standard C library can be used to break individual +.\" lines in the +.\" .Pa /etc/eui64 +.\" database into their individual components: a binary EUI-64 is +.\" stored as an +.\" .Pa eui64_addr +.\" structure, and a hostname stored as a character string. +.Sh FILES +.Bl -tag -width ".Pa /etc/eui64" -compact +.It Pa /etc/eui64 +The +.Nm +file resides in +.Pa /etc . +.El +.Sh SEE ALSO +.Xr eui64 3 , +.Xr yp 8 +.Sh HISTORY +The +.Nm +format is based on the +.Xr ethers 5 +format. diff --git a/static/freebsd/man5/fbtab.5 b/static/freebsd/man5/fbtab.5 new file mode 100644 index 00000000..ab87a5e2 --- /dev/null +++ b/static/freebsd/man5/fbtab.5 @@ -0,0 +1,45 @@ +.\" +.Dd August 22, 1994 +.Dt FBTAB 5 +.Os +.Sh NAME +.Nm fbtab +.Nd change device protection upon login +.Sh DESCRIPTION +The +.Nm +file contains a number of lines specifying a device together with a list +of devices with associated protections. +Comments start with a +.Ql # +and extend to the end of the line. +.Pp +Blank lines or lines with only a comment are ignored. +.Pp +All other lines consist of three fields delimited by +whitespace: a login device +.Pq Pa /dev/ttyv0 , +an octal permission number (0600), and a colon +.Pq Ql \&: +delimited list of device patterns +.Pq Pa /dev/console , /dev/dsp* . +All device patterns are absolute paths. +.Pp +If the tty argument (relative path) matches a login device +name (absolute path), the permissions of the devices in the +colon-delimited list are set as specified in the second +field, and their ownership is changed to that of the UID +and GID arguments. +.Sh FILES +.Bl -tag -width ".Pa /etc/fbtab" -compact +.It Pa /etc/fbtab +The +.Nm +file resides in +.Pa /etc . +.El +.Sh SEE ALSO +.Xr login 1 , +.Xr getty 8 +.Sh AUTHORS +.An Guido van Rooij diff --git a/static/freebsd/man5/forward.5 b/static/freebsd/man5/forward.5 new file mode 100644 index 00000000..e03c647e --- /dev/null +++ b/static/freebsd/man5/forward.5 @@ -0,0 +1,94 @@ +.\" Copyright (c) 1996 +.\" Mike Pritchard . 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 Mike Pritchard and +.\" contributors. +.\" 4. Neither the name of the author nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" 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 2, 1996 +.Dt FORWARD 5 +.Os +.Sh NAME +.Nm forward +.Nd mail forwarding instructions +.Sh DESCRIPTION +The +.Nm .forward +file contains a list of mail addresses or programs +that the user's mail should be redirected to. +If the +file is not present, then no mail forwarding will be done. +Mail may also be forwarded as the standard input to a program +by prefixing the line +with the normal shell pipe symbol (|). +If arguments +are to be passed to the command, then the entire line +should be enclosed in quotes. +For security reasons, the +.Nm .forward +file must be owned by the user the mail is being sent to, +or by root, and the user's shell must be listed in +.Pa /etc/shells . +.Pp +For example, if a +.Nm .forward +file contained the following lines: +.Bd -literal -offset indent +nobody@FreeBSD.org +"|/usr/bin/vacation nobody" +.Ed +.Pp +Mail would be forwarded to +.Aq nobody@FreeBSD.org +and to the program +.Pa /usr/bin/vacation +with the single argument +.Ar nobody . +.Pp +If a local user address is prefixed with a backslash +character, mail is delivered directly to the user's +mail spool file, bypassing further redirection. +.Pp +For example, if user chris had a +.Nm .forward +file containing the following lines: +.Bd -literal -offset indent +chris@otherhost +\echris +.Ed +.Pp +One copy of mail would be forwarded to +.Ar chris@otherhost +and another copy would be retained as mail for local user chris. +.Sh FILES +.Bl -tag -width $HOME/.forward -compact +.It Pa $HOME/.forward +The user's forwarding instructions. +.El +.Sh SEE ALSO +.Xr aliases 5 , +.Xr sendmail 8 diff --git a/static/freebsd/man5/freebsd-update.conf.5 b/static/freebsd/man5/freebsd-update.conf.5 new file mode 100644 index 00000000..5f077cd8 --- /dev/null +++ b/static/freebsd/man5/freebsd-update.conf.5 @@ -0,0 +1,289 @@ +.\"- +.\" Copyright 2006 Colin Percival +.\" All rights reserved +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted providing 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 ``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 February 17, 2022 +.Dt FREEBSD-UPDATE.CONF 5 +.Os +.Sh NAME +.Nm freebsd-update.conf +.Nd configuration file for +.Xr freebsd-update 8 +.Sh DESCRIPTION +The +.Nm +file controls the behaviour of the +.Xr freebsd-update 8 +utility. +The file contains lines consisting of a case-sensitive option name and +zero or more parameters. +Empty lines and any part of a line following a +.Ql # +character are ignored. +Unless stated otherwise, specifying an option multiple times is an +error. +.Pp +The possible options and their meanings are as follows: +.Bl -tag -width "BackupKernelSymbolFiles" +.It Cm AllowAdd +The single parameter following this keyword must be +.Dq yes +or +.Dq no +and specifies whether +.Xr freebsd-update 8 +is allowed to create new files, directories, and symlinks if +these are part of updates downloaded. +Note that +.Xr freebsd-update 8 +will not re-add files which have been deleted from a +.Fx +installation unless those files were previously added as part +of an update. +.It Cm AllowDelete +The single parameter following this keyword must be +.Dq yes +or +.Dq no +and specifies whether +.Xr freebsd-update 8 +is allowed to delete files, directories, and symlinks as +part of updates downloaded. +.It Cm BackupKernel +The single parameter following this keyword must be +.Dq yes +or +.Dq no +and specifies whether +.Xr freebsd-update 8 +will create a backup of the old kernel before installing a new kernel. +This backup kernel can be used to recover a system where the newly +installed kernel somehow did not work. +Note that the backup kernel is not reverted to its original state by +the +.Xr freebsd-update 8 +rollback command. +.It Cm BackupKernelDir +This keyword sets the directory which is used to store a backup +kernel, if the BackupKernel feature is enabled. +If the directory already exist, and it was not created by +.Xr freebsd-update 8 , +the directory is skipped. +In the case of the primary directory name not being usable, a number +starting with +.Sq 1 +is appended to the directory name. +Like with the primary directory name, the constructed directory name is +only used if the path name does not exist, or if the directory was +previously created by +.Xr freebsd-update 8 . +If the constructed directory still exist the appended number is +incremented with 1 and the directory search process restarted. +Should the number increment go above 9, +.Xr freebsd-update 8 +will abort. +.It Cm BackupKernelSymbolFiles +The single parameter following this keyword must be +.Dq yes +or +.Dq no +and specifies whether +.Xr freebsd-update 8 +will also backup kernel symbol files, if they exist. +The kernel symbol files takes up a lot of disk space and are not +needed for recovery purposes. +If the symbol files are needed, after recovering a system using the +backup kernel, the +.Xr freebsd-update 8 +rollback command will recreate the symbol files along with the old +kernel. +.It Cm Components +The parameters following this keyword are the components or +sub-components of +.Fx +which will be updated. +The components are +.Dq src +(source code), +.Dq world +(non-kernel binaries), and +.Dq kernel ; +the sub-components are the individual distribution sets generated as +part of the release process (e.g., +.Dq src/base , +.Dq src/sys , +.Dq world/base , +.Dq world/catpages , +.Dq kernel/smp ) . +Note that prior to +.Fx 6.1 , +the +.Dq kernel +component was distributed as part of +.Dq world/base . +.Pp +This option can be specified multiple times, and the parameters +accumulate. +.It Cm CreateBootEnv +The single parameter following this keyword must be +.Dq yes +or +.Dq no +and specifies whether +.Xr freebsd-update 8 +will create a new boot environment using +.Xr bectl 8 +when installing patches. +.Pp +The name of the new boot environment consists of the current +.Fx +version: +.Bd -literal -offset indent +freebsd-version -ku | sort -V | tail -n 1 +.Ed +.Pp +and a timestamp: +.Bd -literal -offset indent +date +"%Y-%m-%d_%H%M%S" +.Ed +.Pp +separated by a single dash, e.g.: +.Bd -literal -offset indent +13.0-RELEASE-p7_2022-02-16_141502 +.Ed +.Pp +.Xr freebsd-update 8 +does not attempt to create a boot environment +if any of the following applies: +.Pp +.Bl -dash -compact +.It +ZFS is not used. +.It +The ZFS root is not set up for boot environments +.Po see the check command of +.Xr bectl 8 +for details +.Pc . +.It +.Xr freebsd-update 8 +is running in a +.Xr jail 8 . +.It +.Xr freebsd-update 8 +is updating a root directory selected via +the basedir +.Pq Fl b +or jail +.Pq Fl j +flags. +.El +.It Cm IDSIgnorePaths +The parameters following this keyword are regular expressions; +paths which start with a string matching one of these regular +expressions will be ignored by +.Xr freebsd-update 8 +IDS. +.Pp +This option can be specified multiple times, and the parameters +accumulate. +.It Cm IgnorePaths +The parameters following this keyword are regular expressions; +updates to paths which start with a string matching one of +these regular expressions will be ignored. +.Pp +This option can be specified multiple times, and the parameters +accumulate. +.It Cm KeepModifiedMetadata +The single parameter following this keyword must be +.Dq yes +or +.Dq no +and specifies whether +.Xr freebsd-update 8 +should keep existing file ownership, permissions, and flags +when installing updates if these have been modified locally. +.It Cm KeyPrint +The single parameter following this keyword is the SHA256 hash +of the RSA key which will be trusted to sign updates. +.It Cm MailTo +The single parameter following this keyword is the address +to which +.Xr cron 8 +output will be mailed. +.It Cm MergeChanges +The parameters following this keyword are regular expressions; +updates to paths which start with a string matching one of +these regular expressions will be merged with local modifications. +.Pp +This option can be specified multiple times, and the parameters +accumulate. +.It Cm ServerName +The single parameter following this keyword is the name of the +server or server pool from which updates will be downloaded. +.It Cm StrictComponents +The single parameter following this keyword must be +.Dq yes +or +.Dq no +and specifies whether +.Xr freebsd-update 8 +should interpret the list of components of +.Fx +specified via the +.Cm Components +option strictly as a list of components installed which +should be upgraded when the +.Cm upgrade +command is used ("yes"), or merely as a list of components +which might be installed, of which +.Xr freebsd-update 8 +should identify which in fact are present ("no"). +.It Cm UpdateIfUnmodified +The parameters following this keyword are regular expressions; +updates to paths which start with a string matching one of +these regular expressions will be ignored if the files have +been modified locally (unless they are merged \(em see the +.Cm MergeChanges +option). +.Pp +This option can be specified multiple times, and the parameters +accumulate. +.It Cm WorkDir +The single parameter following this keyword is the directory +in which temporary files and downloaded updates will be stored. +.El +.Sh FILES +.Bl -tag -width "/etc/freebsd-update.conf" +.It Pa /etc/freebsd-update.conf +Default location of the +.Xr freebsd-update 8 +configuration file. +.El +.Sh SEE ALSO +.Xr sha256 1 , +.Xr bectl 8 , +.Xr freebsd-update 8 +.Sh AUTHORS +.An Colin Percival Aq Mt cperciva@FreeBSD.org diff --git a/static/freebsd/man5/fs.5 b/static/freebsd/man5/fs.5 new file mode 100644 index 00000000..2e3d5da5 --- /dev/null +++ b/static/freebsd/man5/fs.5 @@ -0,0 +1,428 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 16, 2017 +.Dt FS 5 +.Os +.Sh NAME +.Nm fs , +.Nm inode +.Nd format of file system volume +.Sh SYNOPSIS +.In sys/param.h +.In ufs/ffs/fs.h +.Pp +.In sys/types.h +.In sys/lock.h +.In sys/extattr.h +.In sys/acl.h +.In ufs/ufs/quota.h +.In ufs/ufs/dinode.h +.In ufs/ufs/extattr.h +.Sh DESCRIPTION +The files +.In fs.h +and +.In inode.h +declare several structures, defined variables and macros +which are used to create and manage the underlying format of +file system objects on random access devices (disks). +.Pp +The block size and number of blocks which +comprise a file system are parameters of the file system. +Sectors beginning at +.Dv BBLOCK +and continuing for +.Dv BBSIZE +are used +for a disklabel and for some hardware primary +and secondary bootstrapping programs. +.Pp +The actual file system begins at sector +.Dv SBLOCK +with the +.Em super-block +that is of size +.Dv SBLOCKSIZE . +The following structure describes the super-block and is +from the file +.In ufs/ffs/fs.h : +.Bd -literal +/* + * Super block for an FFS filesystem. + */ +struct fs { + int32_t fs_firstfield; /* historic filesystem linked list, */ + int32_t fs_unused_1; /* used for incore super blocks */ + int32_t fs_sblkno; /* offset of super-block in filesys */ + int32_t fs_cblkno; /* offset of cyl-block in filesys */ + int32_t fs_iblkno; /* offset of inode-blocks in filesys */ + int32_t fs_dblkno; /* offset of first data after cg */ + int32_t fs_old_cgoffset; /* cylinder group offset in cylinder */ + int32_t fs_old_cgmask; /* used to calc mod fs_ntrak */ + int32_t fs_old_time; /* last time written */ + int32_t fs_old_size; /* number of blocks in fs */ + int32_t fs_old_dsize; /* number of data blocks in fs */ + int32_t fs_ncg; /* number of cylinder groups */ + int32_t fs_bsize; /* size of basic blocks in fs */ + int32_t fs_fsize; /* size of frag blocks in fs */ + int32_t fs_frag; /* number of frags in a block in fs */ +/* these are configuration parameters */ + int32_t fs_minfree; /* minimum percentage of free blocks */ + int32_t fs_old_rotdelay; /* num of ms for optimal next block */ + int32_t fs_old_rps; /* disk revolutions per second */ +/* these fields can be computed from the others */ + int32_t fs_bmask; /* ``blkoff'' calc of blk offsets */ + int32_t fs_fmask; /* ``fragoff'' calc of frag offsets */ + int32_t fs_bshift; /* ``lblkno'' calc of logical blkno */ + int32_t fs_fshift; /* ``numfrags'' calc number of frags */ +/* these are configuration parameters */ + int32_t fs_maxcontig; /* max number of contiguous blks */ + int32_t fs_maxbpg; /* max number of blks per cyl group */ +/* these fields can be computed from the others */ + int32_t fs_fragshift; /* block to frag shift */ + int32_t fs_fsbtodb; /* fsbtodb and dbtofsb shift constant */ + int32_t fs_sbsize; /* actual size of super block */ + int32_t fs_spare1[2]; /* old fs_csmask */ + /* old fs_csshift */ + int32_t fs_nindir; /* value of NINDIR */ + int32_t fs_inopb; /* value of INOPB */ + int32_t fs_old_nspf; /* value of NSPF */ +/* yet another configuration parameter */ + int32_t fs_optim; /* optimization preference, see below */ + int32_t fs_old_npsect; /* # sectors/track including spares */ + int32_t fs_old_interleave; /* hardware sector interleave */ + int32_t fs_old_trackskew; /* sector 0 skew, per track */ + int32_t fs_id[2]; /* unique filesystem id */ +/* sizes determined by number of cylinder groups and their sizes */ + int32_t fs_old_csaddr; /* blk addr of cyl grp summary area */ + int32_t fs_cssize; /* size of cyl grp summary area */ + int32_t fs_cgsize; /* cylinder group size */ + int32_t fs_spare2; /* old fs_ntrak */ + int32_t fs_old_nsect; /* sectors per track */ + int32_t fs_old_spc; /* sectors per cylinder */ + int32_t fs_old_ncyl; /* cylinders in filesystem */ + int32_t fs_old_cpg; /* cylinders per group */ + int32_t fs_ipg; /* inodes per group */ + int32_t fs_fpg; /* blocks per group * fs_frag */ +/* this data must be re-computed after crashes */ + struct csum fs_old_cstotal; /* cylinder summary information */ +/* these fields are cleared at mount time */ + int8_t fs_fmod; /* super block modified flag */ + int8_t fs_clean; /* filesystem is clean flag */ + int8_t fs_ronly; /* mounted read-only flag */ + int8_t fs_old_flags; /* old FS_ flags */ + u_char fs_fsmnt[MAXMNTLEN]; /* name mounted on */ + u_char fs_volname[MAXVOLLEN]; /* volume name */ + uint64_t fs_swuid; /* system-wide uid */ + int32_t fs_pad; /* due to alignment of fs_swuid */ +/* these fields retain the current block allocation info */ + int32_t fs_cgrotor; /* last cg searched */ + void *fs_ocsp[NOCSPTRS]; /* padding; was list of fs_cs buffers */ + uint8_t *fs_contigdirs; /* # of contiguously allocated dirs */ + struct csum *fs_csp; /* cg summary info buffer for fs_cs */ + int32_t *fs_maxcluster; /* max cluster in each cyl group */ + u_int *fs_active; /* used by snapshots to track fs */ + int32_t fs_old_cpc; /* cyl per cycle in postbl */ + int32_t fs_maxbsize; /* maximum blocking factor permitted */ + int64_t fs_unrefs; /* number of unreferenced inodes */ + int64_t fs_sparecon64[16]; /* old rotation block list head */ + int64_t fs_sblockloc; /* byte offset of standard superblock */ + struct csum_total fs_cstotal; /* cylinder summary information */ + ufs_time_t fs_time; /* last time written */ + int64_t fs_size; /* number of blocks in fs */ + int64_t fs_dsize; /* number of data blocks in fs */ + ufs2_daddr_t fs_csaddr; /* blk addr of cyl grp summary area */ + int64_t fs_pendingblocks; /* blocks in process of being freed */ + int32_t fs_pendinginodes; /* inodes in process of being freed */ + int32_t fs_snapinum[FSMAXSNAP]; /* list of snapshot inode numbers */ + int32_t fs_avgfilesize; /* expected average file size */ + int32_t fs_avgfpdir; /* expected # of files per directory */ + int32_t fs_save_cgsize; /* save real cg size to use fs_bsize */ + int32_t fs_sparecon32[26]; /* reserved for future constants */ + int32_t fs_flags; /* see FS_ flags below */ + int32_t fs_contigsumsize; /* size of cluster summary array */ + int32_t fs_maxsymlinklen; /* max length of an internal symlink */ + int32_t fs_old_inodefmt; /* format of on-disk inodes */ + uint64_t fs_maxfilesize; /* maximum representable file size */ + int64_t fs_qbmask; /* ~fs_bmask for use with 64-bit size */ + int64_t fs_qfmask; /* ~fs_fmask for use with 64-bit size */ + int32_t fs_state; /* validate fs_clean field */ + int32_t fs_old_postblformat; /* format of positional layout tables */ + int32_t fs_old_nrpos; /* number of rotational positions */ + int32_t fs_spare5[2]; /* old fs_postbloff */ + /* old fs_rotbloff */ + int32_t fs_magic; /* magic number */ +}; + +/* + * Filesystem identification + */ +#define FS_UFS1_MAGIC 0x011954 /* UFS1 fast filesystem magic number */ +#define FS_UFS2_MAGIC 0x19540119 /* UFS2 fast filesystem magic number */ +#define FS_OKAY 0x7c269d38 /* superblock checksum */ +#define FS_42INODEFMT -1 /* 4.2BSD inode format */ +#define FS_44INODEFMT 2 /* 4.4BSD inode format */ + +/* + * Preference for optimization. + */ +#define FS_OPTTIME 0 /* minimize allocation time */ +#define FS_OPTSPACE 1 /* minimize disk fragmentation */ +.Ed +.Pp +Each disk drive contains some number of file systems. +A file system consists of a number of cylinder groups. +Each cylinder group has inodes and data. +.Pp +A file system is described by its super-block, which in turn +describes the cylinder groups. +The super-block is critical +data and is replicated in each cylinder group to protect against +catastrophic loss. +This is done at file system creation +time and the critical +super-block data does not change, so the copies need not be +referenced further unless disaster strikes. +.Pp +Addresses stored in inodes are capable of addressing fragments +of `blocks'. +File system blocks of at most size +.Dv MAXBSIZE +can +be optionally broken into 2, 4, or 8 pieces, each of which is +addressable; these pieces may be +.Dv DEV_BSIZE , +or some multiple of +a +.Dv DEV_BSIZE +unit. +.Pp +Large files consist of exclusively large data blocks. +To avoid +undue wasted disk space, the last data block of a small file is +allocated as only as many fragments of a large block as are +necessary. +The file system format retains only a single pointer +to such a fragment, which is a piece of a single large block that +has been divided. +The size of such a fragment is determinable from +information in the inode, using the +.Fn blksize fs ip lbn +macro. +.Pp +The file system records space availability at the fragment level; +to determine block availability, aligned fragments are examined. +.Pp +The root inode is the root of the file system. +Inode 0 cannot be used for normal purposes and +historically bad blocks were linked to inode 1, +thus the root inode is 2 (inode 1 is no longer used for +this purpose, however numerous dump tapes make this +assumption, so we are stuck with it). +.Pp +The +.Fa fs_minfree +element gives the minimum acceptable percentage of file system +blocks that may be free. +If the freelist drops below this level +only the super-user may continue to allocate blocks. +The +.Fa fs_minfree +element +may be set to 0 if no reserve of free blocks is deemed necessary, +however severe performance degradations will be observed if the +file system is run at greater than 90% full; thus the default +value of +.Fa fs_minfree +is 8%. +.Pp +Empirically the best trade-off between block fragmentation and +overall disk utilization at a loading of 90% comes with a +fragmentation of 8, thus the default fragment size is an eighth +of the block size. +.Pp +The element +.Fa fs_optim +specifies whether the file system should try to minimize the time spent +allocating blocks, or if it should attempt to minimize the space +fragmentation on the disk. +If the value of fs_minfree (see above) is less than 8%, +then the file system defaults to optimizing for space to avoid +running out of full sized blocks. +If the value of minfree is greater than or equal to 8%, +fragmentation is unlikely to be problematical, and +the file system defaults to optimizing for time. +.Pp +.Em Cylinder group related limits : +Each cylinder keeps track of the availability of blocks at different +rotational positions, so that sequential blocks can be laid out +with minimum rotational latency. +With the default of 8 distinguished +rotational positions, the resolution of the +summary information is 2ms for a typical 3600 rpm drive. +.Pp +The element +.Fa fs_old_rotdelay +gives the minimum number of milliseconds to initiate +another disk transfer on the same cylinder. +It is used in determining the rotationally optimal +layout for disk blocks within a file; +the default value for +.Fa fs_old_rotdelay +is 2ms. +.Pp +Each file system has a statically allocated number of inodes. +An inode is allocated for each +.Dv NBPI +bytes of disk space. +The inode allocation strategy is extremely conservative. +.Pp +.Dv MINBSIZE +is the smallest allowable block size. +With a +.Dv MINBSIZE +of 4096 +it is possible to create files of size +2^32 with only two levels of indirection. +.Dv MINBSIZE +must be big enough to hold a cylinder group block, +thus changes to +.Pq Fa struct cg +must keep its size within +.Dv MINBSIZE . +Note that super-blocks are never more than size +.Dv SBLOCKSIZE . +.Pp +The path name on which the file system is mounted is maintained in +.Fa fs_fsmnt . +.Dv MAXMNTLEN +defines the amount of space allocated in +the super-block for this name. +The limit on the amount of summary information per file system +is defined by +.Dv MAXCSBUFS . +For a 4096 byte block size, it is currently parameterized for a +maximum of two million cylinders. +.Pp +Per cylinder group information is summarized in blocks allocated +from the first cylinder group's data blocks. +These blocks are read in from +.Fa fs_csaddr +(size +.Fa fs_cssize ) +in addition to the super-block. +.Pp +.Sy N.B. : +.Fn sizeof "struct csum" +must be a power of two in order for +the +.Fn fs_cs +macro to work. +.Pp +The +.Em "Super-block for a file system" : +The size of the rotational layout tables +is limited by the fact that the super-block is of size +.Dv SBLOCKSIZE . +The size of these tables is +.Em inversely +proportional to the block +size of the file system. +The size of the tables is +increased when sector sizes are not powers of two, +as this increases the number of cylinders +included before the rotational pattern repeats +.Pq Fa fs_cpc . +The size of the rotational layout +tables is derived from the number of bytes remaining in +.Pq Fa struct fs . +.Pp +The number of blocks of data per cylinder group +is limited because cylinder groups are at most one block. +The inode and free block tables +must fit into a single block after deducting space for +the cylinder group structure +.Pq Fa struct cg . +.Pp +The +.Em Inode : +The inode is the focus of all file activity in the +.Ux +file system. +There is a unique inode allocated +for each active file, +each current directory, each mounted-on file, +text file, and the root. +An inode is `named' by its device/i-number pair. +For further information, see the include file +.In ufs/ufs/inode.h . +.Pp +The format of an external attribute is defined by the extattr structure: +.Bd -literal +struct extattr { + uint32_t ea_length; /* length of this attribute */ + uint8_t ea_namespace; /* name space of this attribute */ + uint8_t ea_contentpadlen; /* bytes of padding at end of attribute */ + uint8_t ea_namelength; /* length of attribute name */ + char ea_name[1]; /* attribute name (NOT nul-terminated) */ + /* padding, if any, to align attribute content to 8 byte boundary */ + /* extended attribute content follows */ +}; +.Ed +.Pp +Several macros are defined to manipulate these structures. +Each macro takes a pointer to an extattr structure. +.Bl -tag -width ".Dv EXTATTR_CONTENT_SIZE(eap)" +.It Dv EXTATTR_NEXT(eap) +Returns a pointer to the next extended attribute following +.Fa eap . +.It Dv EXTATTR_CONTENT(eap) +Returns a pointer to the extended attribute content referenced by +.Fa eap . +.It Dv EXTATTR_CONTENT_SIZE(eap) +Returns the size of the extended attribute content referenced by +.Fa eap . +.El +.Pp +The following code identifies an ACL: +.Bd -literal + if (eap->ea_namespace == EXTATTR_NAMESPACE_SYSTEM && + eap->ea_namelength == sizeof(POSIX1E_ACL_ACCESS_EXTATTR_NAME) - 1 && + strncmp(eap->ea_name, POSIX1E_ACL_ACCESS_EXTATTR_NAME, + sizeof(POSIX1E_ACL_ACCESS_EXTATTR_NAME) - 1) == 0) { + aclp = EXTATTR_CONTENT(eap); + acllen = EXTATTR_CONTENT_SIZE(eap); + ... + } +.Ed +.Sh HISTORY +A super-block structure named filsys appeared in +.At v6 . +The file system described in this manual appeared +in +.Bx 4.2 . diff --git a/static/freebsd/man5/fstab.5 b/static/freebsd/man5/fstab.5 new file mode 100644 index 00000000..787fe393 --- /dev/null +++ b/static/freebsd/man5/fstab.5 @@ -0,0 +1,467 @@ +.\" Copyright (c) 1980, 1989, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 14, 2014 +.Dt FSTAB 5 +.Os +.Sh NAME +.Nm fstab +.Nd static information about the file systems +.Sh SYNOPSIS +.In fstab.h +.Sh DESCRIPTION +The file +.Nm +contains descriptive information about the various file +systems. +.Nm +is only read by programs, and not written; +it is the duty of the system administrator to properly create +and maintain this file. +Each file system is described on a separate line; +fields on each line are separated by tabs or spaces. +The order of records in +.Nm +is important because +.Xr fsck 8 , +.Xr mount 8 , +and +.Xr umount 8 +sequentially iterate through +.Nm +doing their thing. +.Pp +The first field, +.Pq Fa fs_spec , +describes the special device or +remote file system to be mounted. +The contents are decoded by the +.Xr strunvis 3 +function. +This allows using spaces or tabs in the device name which would be +interpreted as field separators otherwise. +.Pp +The second field, +.Pq Fa fs_file , +describes the mount point for the file system. +For swap partitions, this field should be specified as +.Dq none . +The contents are decoded by the +.Xr strunvis 3 +function, as above. +.Pp +The third field, +.Pq Fa fs_vfstype , +describes the type of the file system. +The system can support various file system types. +Only the root, /usr, and /tmp file systems need be statically +compiled into the kernel; +everything else will be automatically loaded at mount +time. +(Exception: the FFS cannot currently be demand-loaded.) +Some people still prefer to statically +compile other file systems as well. +.Pp +The fourth field, +.Pq Fa fs_mntops , +describes the mount options associated with the file system. +It is formatted as a comma separated list of options. +It contains at least the type of mount (see +.Fa fs_type +below) plus any additional options appropriate to the file system type. +See the options flag +.Pq Fl o +in the +.Xr mount 8 +page and the file system specific page, such as +.Xr mount_nfs 8 , +for additional options that may be specified. +All options that can be given to the file system specific mount commands +can be used in +.Nm +as well. +They just need to be formatted a bit differently. +The arguments of the +.Fl o +option can be used without the preceding +.Fl o +flag. +Other options need both the file system specific flag and its argument, +separated by an equal sign. +For example, mounting an +.Xr msdosfs 4 +filesystem, the options +.Bd -literal -offset indent +-o sync -o noatime -m 644 -M 755 -u foo -g bar +.Ed +.Pp +should be written as +.Bd -literal -offset indent +sync,noatime,-m=644,-M=755,-u=foo,-g=bar +.Ed +.Pp +in the option field of +.Nm . +.Pp +If the options +.Dq userquota +and/or +.Dq groupquota +are specified, +the file system is automatically processed by the +.Xr quotacheck 8 +command, and user and/or group disk quotas are enabled with +.Xr quotaon 8 . +By default, +file system quotas are maintained in files named +.Pa quota.user +and +.Pa quota.group +which are located at the root of the associated file system. +These defaults may be overridden by putting an equal sign +and an alternative absolute pathname following the quota option. +Thus, if the user quota file for +.Pa /tmp +is stored in +.Pa /var/quotas/tmp.user , +this location can be specified as: +.Bd -literal -offset indent +userquota=/var/quotas/tmp.user +.Ed +.Pp +If the option +.Dq failok +is specified, +the system will ignore any error which happens during the mount of that filesystem, +which would otherwise cause the system to drop into single user mode. +This option is implemented by the +.Xr mount 8 +command and will not be passed to the kernel. +.Pp +If the option +.Dq noauto +is specified, the file system will not be automatically +mounted at system startup. +Note that, for network file systems +of third party types +(i.e., types supported by additional software +not included in the base system) +to be automatically mounted at system startup, +the +.Va extra_netfs_types +.Xr rc.conf 5 +variable must be used to extend the +.Xr rc 8 +startup script's list of network file system types. +.Pp +If the option +.Dq late +is specified, the file system will be automatically mounted +at a stage of system startup after remote mount points are mounted. +For more detail about this option, +see the +.Xr mount 8 +manual page. +.Pp +If the option +.Dq update +is specified, it indicates that the status of an already mounted file +system should be changed accordingly. +This allows, for example, file systems mounted read-only to be upgraded +read-write and vice-versa. +By default, an entry corresponding to a file systems that is already +mounted is going to be skipped over when processing +.Nm , +unless it's a root file system, in which case logic similar to +.Dq update +is applied automatically. +.Pp +The +.Dq update +option is typically used in conjunction with two +.Nm +files. +The first +.Nm +file is used to set up the initial set of file systems. +The second +.Nm +file is then run to update the initial set of file systems and +to add additional file systems. +.Pp +The type of the mount is extracted from the +.Fa fs_mntops +field and stored separately in the +.Fa fs_type +field (it is not deleted from the +.Fa fs_mntops +field). +If +.Fa fs_type +is +.Dq rw +or +.Dq ro +then the file system whose name is given in the +.Fa fs_file +field is normally mounted read-write or read-only on the +specified special file. +.Pp +If +.Fa fs_type +is +.Dq sw +then the special file is made available as a piece of swap +space by the +.Xr swapon 8 +command at the end of the system reboot procedure. +For swap devices, the keyword +.Dq trimonce +triggers the delivery of a +.Dv BIO_DELETE +command to the device. +This command marks the device's blocks as unused, except those that +might store a disk label. +This marking can erase a crash dump. +To delay +.Nm swapon +for a device until after +.Nm savecore +has copied the crash dump to another location, use the +.Dq late +option. +For vnode-backed swap spaces, +.Dq file +is supported in the +.Fa fs_mntops +field. +When +.Fa fs_spec +is an +.Xr md 4 +device file +.Pq Do md Dc or Do md[0-9]* Dc +and +.Dq file +is specified in +.Fa fs_mntopts , +an +.Xr md 4 +device is created with the specified file used as backing store, +and then the new device is used as swap space. +Swap entries on +.Pa .eli +devices will cause automatic creation of encrypted devices. +The +.Dq ealgo , +.Dq aalgo , +.Dq keylen , +.Dq notrim , +and +.Dq sectorsize +options may be passed to control those +.Xr geli 8 +parameters. +The fields other than +.Fa fs_spec +and +.Fa fs_type +are unused. +If +.Fa fs_type +is specified as +.Dq xx +the entry is ignored. +This is useful to show disk partitions which are currently unused. +.Pp +The fifth field, +.Pq Fa fs_freq , +is used for these file systems by the +.Xr dump 8 +command to determine which file systems need to be dumped. +If the fifth field is not present, a value of zero is returned and +.Nm dump +will assume that the file system does not need to be dumped. +If the fifth field is greater than 0, then it specifies the number of days +between dumps for this file system. +.Pp +The sixth field, +.Pq Fa fs_passno , +is used by the +.Xr fsck 8 +and +.Xr quotacheck 8 +programs to determine the order in which file system and quota +checks are done at reboot time. +The +.Fa fs_passno +field can be any value between 0 and +.Ql INT_MAX Ns -1 . +.Pp +The root file system should be specified with a +.Fa fs_passno +of 1, and other file systems should have a +.Fa fs_passno +of 2 or greater. +A file system with a +.Fa fs_passno +value of 1 is always checked sequentially and be completed before +another file system is processed, and it will be processed before +all file systems with a larger +.Fa fs_passno . +.Pp +For any given value of +.Fa fs_passno , +file systems within a drive will be checked sequentially, +but file systems on different drives will be checked at the +same time to utilize parallelism available in the hardware. +Once all file system checks are complete for the current +.Fa fs_passno , +the same process will start over for the next +.Fa fs_passno . +.Pp +If the sixth field is not present or is zero, +a value of zero is returned and +.Xr fsck 8 +and +.Xr quotacheck 8 +will assume that the file system does not need to be checked. +.Pp +The +.Fa fs_passno +field can be used to implement finer control when +the system utilities may determine that the file system resides +on a different physical device, when it actually does not, as with a +.Xr ccd 4 +device. +All file systems with a lower +.Fa fs_passno +value will be completed before starting on file systems with a +higher +.Fa fs_passno +value. +E.g. all file systems with a +.Fa fs_passno +of 2 will be completed before any file systems with a +.Fa fs_passno +of 3 or greater are started. +Gaps are allowed between the different +.Fa fs_passno +values. +E.g. file systems listed in +.Pa /etc/fstab +may have +.Fa fs_passno +values such as 0, 1, 2, 15, 100, 200, 300, and may appear in any order +within +.Pa /etc/fstab . +.Bd -literal +#define FSTAB_RW "rw" /* read/write device */ +#define FSTAB_RQ "rq" /* read/write with quotas */ +#define FSTAB_RO "ro" /* read-only device */ +#define FSTAB_SW "sw" /* swap device */ +#define FSTAB_XX "xx" /* ignore totally */ + +struct fstab { + char *fs_spec; /* block special device name */ + char *fs_file; /* file system path prefix */ + char *fs_vfstype; /* File system type, ufs, nfs */ + char *fs_mntops; /* Mount options ala -o */ + char *fs_type; /* FSTAB_* from fs_mntops */ + int fs_freq; /* dump frequency, in days */ + int fs_passno; /* pass number on parallel fsck */ +}; +.Ed +.Pp +The proper way to read records from +.Pa fstab +is to use the routines +.Xr getfsent 3 , +.Xr getfsspec 3 , +.Xr getfstype 3 , +and +.Xr getfsfile 3 . +.Sh FILES +.Bl -tag -width /etc/fstab -compact +.It Pa /etc/fstab +The file +.Nm +resides in +.Pa /etc . +.El +.Sh EXAMPLES +.Bd -literal +# Device Mountpoint FStype Options Dump Pass# +# +# UFS file system. +/dev/da0p2 / ufs rw 1 1 +# +# Swap space on a block device. +/dev/da0p1 none swap sw 0 0 +# +# Swap space using a block device with GELI encryption. +# aalgo, ealgo, keylen, sectorsize options are available +# for .eli devices. +/dev/da1p2.eli none swap sw 0 0 +# +# tmpfs. +tmpfs /tmp tmpfs rw,size=1g,mode=1777 0 0 +# +# UFS file system on a swap-backed md(4). /dev/md10 is +# automatically created. If it is "md", a unit number +# will be automatically selected. +md10 /scratch mfs rw,-s1g 0 0 +# +# Swap space on a vnode-backed md(4). +md11 none swap sw,file=/swapfile 0 0 +# +# CDROM. "noauto" option is typically used because the +# media is removable. +/dev/cd0 /cdrom cd9660 ro,noauto 0 0 +# +# NFS-exported file system. "serv" is an NFS server name +# or IP address. +serv:/export /nfs nfs rw,noinet6 0 0 +.Ed +.Sh SEE ALSO +.Xr getfsent 3 , +.Xr getvfsbyname 3 , +.Xr strunvis 3 , +.Xr ccd 4 , +.Xr dump 8 , +.Xr fsck 8 , +.Xr geli 8 , +.Xr mount 8 , +.Xr quotacheck 8 , +.Xr quotaon 8 , +.Xr swapon 8 , +.Xr umount 8 +.Sh HISTORY +The +.Nm +file format appeared in +.Bx 4.0 . diff --git a/static/freebsd/man5/group.5 b/static/freebsd/man5/group.5 new file mode 100644 index 00000000..8f7c59c5 --- /dev/null +++ b/static/freebsd/man5/group.5 @@ -0,0 +1,164 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 August 29, 2025 +.Dt GROUP 5 +.Os +.Sh NAME +.Nm group +.Nd format of the group permissions file +.Sh DESCRIPTION +The +.Nm +file is the local source of group information. +It can be used in conjunction with the Hesiod domain +`group', and the NIS maps `group.byname' and `group.bygid', +as controlled by +.Xr nsswitch.conf 5 . +.Pp +The file +.Nm +consists of newline separated +.Tn ASCII +records, one per group, containing four colon +.Ql \&: +separated fields. +These fields are as follows: +.Bl -tag -width password -offset indent -compact +.It group +Name of the group. +.It passwd +Group's +.Em encrypted +password. +.It gid +The group's decimal ID. +.It member +Group members. +.El +.Pp +Lines whose first non-whitespace character is a pound-sign (#) +are comments, and are ignored. +Blank lines that consist +only of spaces, tabs or newlines are also ignored. +.Pp +The +.Ar group +field is the group name used for granting file access to users +who are members of the group. +The +.Ar gid +field is the number associated with the group name. +They should both be unique across the system (and often +across a group of systems) since they control file access. +The +.Ar passwd +field +is an optional +.Em encrypted +password. +This field is rarely used +and an asterisk is normally placed in it rather than leaving it blank. +The +.Ar member +field contains the names of users granted the privileges of +.Ar group . +The member names are separated by commas without spaces or newlines. +A user is automatically in a group if that group was specified +in their +.Pa /etc/passwd +entry and does not need to be added to that group in the +.Nm +file. +.\" .Pp +.\" When the system reads the file +.\" .Pa /etc/group +.\" the fields are read into the structure +.\" .Fa group +.\" declared in +.\" .In grp.h : +.\" .Bd -literal -offset indent +.\" struct group { +.\" char *gr_name; /* group name */ +.\" char *gr_passwd; /* group password */ +.\" int gr_gid; /* group id */ +.\" char **gr_mem; /* group members */ +.\" }; +.\" .Ed +.Sh IMPLEMENTATION NOTES +The +.Xr passwd 1 +command does not change the +.Nm +passwords. +The +.Xr pw 8 +utility's +.Cm groupmod +command should be used instead. +.Sh LIMITS +There are various limitations which are explained in +the function where they occur; see section +.Sx SEE ALSO . +.Pp +In older implementations, +a group cannot have more than 200 members. +The maximum line length of +.Pa /etc/group +is 1024 characters. +Longer lines will be skipped. +This limitation disappeared in +.Fx 3.0 . +Older binaries that are statically linked, depend on old +shared libraries, or +.No non- Ns Fx +binaries in compatibility mode +may still have this limit. +.Sh FILES +.Bl -tag -width /etc/group -compact +.It Pa /etc/group +.El +.Sh SEE ALSO +.Xr newgrp 1 , +.Xr passwd 1 , +.Xr setcred 2 , +.Xr setgroups 2 , +.Xr crypt 3 , +.Xr getgrent 3 , +.Xr initgroups 3 , +.Xr nsswitch.conf 5 , +.Xr passwd 5 , +.Xr chkgrp 8 , +.Xr pw 8 , +.Xr yp 8 +.Sh HISTORY +A +.Nm +file format appeared in +.At v6 . +Support for comments first appeared in +.Fx 3.0 . diff --git a/static/freebsd/man5/hesiod.conf.5 b/static/freebsd/man5/hesiod.conf.5 new file mode 100644 index 00000000..42585224 --- /dev/null +++ b/static/freebsd/man5/hesiod.conf.5 @@ -0,0 +1,78 @@ +.\" $NetBSD: hesiod.conf.5,v 1.2 1999/01/25 22:37:06 lukem Exp $ +.\" +.\" from: #Id: hesiod.conf.5,v 1.1 1996/12/08 21:36:38 ghudson Exp # +.\" +.\" Copyright 1996 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.Dd November 30, 1996 +.Dt HESIOD.CONF 5 +.Os +.Sh NAME +.Nm hesiod.conf +.Nd "configuration file for the Hesiod library" +.Sh DESCRIPTION +The file +.Nm +determines the behavior of the Hesiod library. +Blank lines and lines beginning with a +.Ql # +character are ignored. +All +other lines should be of the form +.Ar variable += +.Ar value , +where the +.Ar value +should be a single word. +Possible +.Ar variables +and +.Ar values +are: +.Bl -tag -width classes +.It Ic lhs +Specifies the domain prefix used for Hesiod queries. +In almost all cases, you should specify +.Dq Li lhs=.ns . +The default value if you do +not specify an lhs value is no domain prefix, which is not compatible +with most Hesiod domains. +.It Ic rhs +Specifies the default Hesiod domain; this value may be overridden by +the +.Ev HES_DOMAIN +environment variable. +You must specify an rhs line for the Hesiod +library to work properly. +.It Ic classes +Specifies which DNS classes Hesiod should do lookups in. +Possible values are +.Cm IN +(the preferred class) and +.Cm HS +(the deprecated class, still used by some sites). +You may specify both classes separated by +a comma to try one class first and then the other if no entry is +available in the first class. +The default value of the classes variable is +.Dq Li IN,HS . +.El +.Sh SEE ALSO +.Xr hesiod 3 +.Sh BUGS +The default value for +.Ic lhs +should probably be more reasonable. diff --git a/static/freebsd/man5/hosts.5 b/static/freebsd/man5/hosts.5 new file mode 100644 index 00000000..674f86a1 --- /dev/null +++ b/static/freebsd/man5/hosts.5 @@ -0,0 +1,91 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 September 15, 2022 +.Dt HOSTS 5 +.Os +.Sh NAME +.Nm hosts +.Nd host name data base +.Sh DESCRIPTION +The +.Nm +file contains information regarding +the known hosts on the network. +It can be used in conjunction with DNS, and the NIS +maps `hosts.byaddr' and `hosts.byname', as controlled by +.Xr nsswitch.conf 5 . +For each host a single line should be present +with the following information: +.Bd -unfilled -offset indent +Internet address +official host name +aliases +.Ed +.Pp +Items are separated by any number of blanks and/or +tab characters. +A ``#'' indicates the beginning of +a comment; characters up to the end of the line are +not interpreted by routines which search the file. +.Pp +This file provides a backup used when the name server +is not running. +For the name server, it is suggested that only a few addresses +be included in this file. +These include addresses for the local interfaces that +.Xr ifconfig 8 +needs at boot time and a few machines on the local network. +.Pp +Network addresses are specified in either the conventional +``.'' (dot) notation for IPv4 or colon hexadecimal notation for IPv6, +as understood by the +.Xr inet_pton 3 +routine +from the Internet address manipulation library, +.Xr inet 3 . +Host names may contain any printable +character other than a field delimiter, newline, +or comment character. +.Sh FILES +.Bl -tag -width /etc/hosts -compact +.It Pa /etc/hosts +The +.Nm +file resides in +.Pa /etc . +.El +.Sh SEE ALSO +.Xr gethostbyname 3 , +.Xr inet 3 , +.Xr nsswitch.conf 5 , +.Xr ifconfig 8 +.Sh HISTORY +The +.Nm +file format appeared in +.Bx 4.1c . diff --git a/static/freebsd/man5/hosts.equiv.5 b/static/freebsd/man5/hosts.equiv.5 new file mode 100644 index 00000000..66598ce7 --- /dev/null +++ b/static/freebsd/man5/hosts.equiv.5 @@ -0,0 +1,139 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 23, 2026 +.Dt HOSTS.EQUIV 5 +.Os +.Sh NAME +.Nm hosts.equiv , +.Nm rhosts +.Nd trusted remote host and user name data base +.Sh DESCRIPTION +The +.Pa hosts.equiv +and +.Pa .rhosts +files contain information regarding +trusted hosts and users on the network. +For each host a single line should be present +with the following information: +.Pp +simple +.Bd -unfilled -offset indent +hostname [username] +.Ed +.Pp +or the more verbose +.Bd -unfilled -offset indent +[+-][hostname|@netgroup] [[+-][username|@netgroup]] +.Ed +.Pp +A +.Dq @ +indicates a host by netgroup or user by netgroup. +A single +.Dq + +matches all hosts or users. +A host name with a leading +.Dq - +will reject +all matching hosts and all their users. +A user name with leading +.Dq - +will reject all matching users from matching hosts. +.Pp +Items are separated by any number of blanks and/or +tab characters. +A +.Dq # +indicates the beginning of +a comment; characters up to the end of the line are +not interpreted by routines which search the file. +.Pp +Host names are specified in the conventional Internet DNS +dotted-domains +.Dq .\& +(dot) notation using the +.Xr inet_addr 3 +routine +from the Internet address manipulation library, +.Xr inet 3 . +Host names may contain any printable +character other than a field delimiter, newline, +or comment character. +.Pp +For security reasons, a user's +.Nm .rhosts +file will be ignored if it is not a regular file, or if it +is not owned by the user, or +if it is writable by anyone other than the user. +.Sh FILES +.Bl -tag -width /etc/hosts.equivxxx -compact +.It Pa /etc/hosts.equiv +The +.Nm +file resides in +.Pa /etc . +.It Pa $HOME/.rhosts +.Nm .rhosts +file resides in +.Pa $HOME . +.El +.Sh EXAMPLES +.Dl bar.com foo +.Pp +Trust user +.Dq foo +from host +.Dq bar.com . +.Pp +.Dl +@allclient +.Pp +Trust all hosts from netgroup +.Dq allclient . +.Pp +.Dl +@allclient -@dau +.Pp +Trust all hosts from netgroup +.Dq allclient +and their users +except users from netgroup +.Dq dau . +.Sh SEE ALSO +.Xr gethostbyname 3 , +.Xr inet 3 , +.Xr innetgr 3 , +.Xr ruserok 3 , +.Xr netgroup 5 , +.Xr ifconfig 8 , +.Xr yp 8 +.Sh BUGS +This manual page is incomplete. +For more information read +the source in +.Pa src/lib/libc/net/rcmd.c +or the SunOS manual page. diff --git a/static/freebsd/man5/hosts.lpd.5 b/static/freebsd/man5/hosts.lpd.5 new file mode 100644 index 00000000..d1f22764 --- /dev/null +++ b/static/freebsd/man5/hosts.lpd.5 @@ -0,0 +1,56 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 June 1, 1996 +.Dt HOSTS.LPD 5 +.Os +.Sh NAME +.Nm hosts.lpd +.Nd trusted hosts that may use local print services +.Sh DESCRIPTION +The +.Nm +file contains a list of hostnames or IP addresses +that are allowed to use your local print services. +List every hostname or IP address on a line itself. +.Pp +If you want to allow access for any and all host, +you can usually use the NIS netgroups feature to +do this by adding a line with a single +.Ql + +character. +.Sh FILES +.Bl -tag -width /etc/hosts.lpdxxxxx -compact +.It Pa /etc/hosts.lpd +The +.Nm +file resides in +.Pa /etc . +.El +.Sh SEE ALSO +.Xr printcap 5 , +.Xr lpd 8 diff --git a/static/freebsd/man5/intro.5 b/static/freebsd/man5/intro.5 new file mode 100644 index 00000000..3e67b319 --- /dev/null +++ b/static/freebsd/man5/intro.5 @@ -0,0 +1,68 @@ +.\" +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 November 17, 2024 +.Dt INTRO 5 +.Os +.Sh NAME +.Nm intro +.Nd introduction to file formats +.Sh DESCRIPTION +This section contains information about the file formats +which comprise most data structures in the +.Bx +environment, including: +.Pp +.Bl -bullet -compact +.It +.Xr ascii 7 +configuration and resource files +.It +system binary file and stream structures +.It +composition of database files +.El +.Sh FILES +.Bl -tag -width "/usr/local/etc/" -compact +.It Pa /etc/ +base system software configuration files +.It Pa /usr/local/etc/ +locally installed software configuration files +.El +.Sh SEE ALSO +.Xr apropos 1 , +.Xr intro 1 , +.Xr hier 7 , +.Xr intro 8 +.Sh HISTORY +The +.Nm Ns Pq 5 +manual page first appeared in +.Fx 2.2 . diff --git a/static/freebsd/man5/libmap.conf.5 b/static/freebsd/man5/libmap.conf.5 new file mode 100644 index 00000000..ae876c1e --- /dev/null +++ b/static/freebsd/man5/libmap.conf.5 @@ -0,0 +1,179 @@ +.\" Copyright (c) 2003 Matthew N. Dodd +.\" Copyright (c) 2013 Dag-Erling Smørgrav +.\" 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 September 16, 2013 +.Dt LIBMAP.CONF 5 +.Os +.Sh NAME +.Nm libmap.conf +.Nd "configuration file for dynamic object dependency mapping" +.Sh DESCRIPTION +The +.Nm libmap +functionality of +.Xr ld-elf.so.1 1 +allows dynamic object dependencies to be mapped to arbitrary names. +.Pp +Each line in +.Pa /etc/libmap.conf +can have one of five forms: +.Bl -tag -width indent +.It Ar origin Ar target +Whenever a dependency on +.Ar origin +is encountered while loading a dynamic object, use +.Ar target +instead of searching for +.Ar origin +in the normal library search paths. +.It Ar path1 Ar path2 +When iterating through a library search path, replace any element that +matches +.Ar path1 +exactly with +.Ar path2 . +.It Bq Ar constraint +Apply +.Ar constraint +to all subsequent mappings until the next constraint line or the end +of the file. +See the +.Sx Constraints +section for details. +.It Cm include Ar file +Parse the contents of +.Ar file +before continuing with the current file. +Nesting depth is limited only by available memory, but each file +encountered is processed only once, and loops are silently ignored. +.It Cm includedir Ar dir +Recurse through +.Ar dir +and parse the contents of any file that ends in +.Pa .conf +before continuing with the current file. +Nesting depth is limited only by available memory, but each directory +or file encountered is processed only once, and loops are silently +ignored. +.El +.Ss Constraints +Constrained mappings only apply when processing binaries or libraries +that satisfy the constraint. +There are three types of constraints: +.Bl -tag -width indent +.It Exact +The constraint is matched literally so that only an executable with an +identical fully qualified pathname will satisfy the constraint. +This means that the executable +.Pa /usr/bin/foo +will not satisfy the constraint +.Bq Pa /usr/bin/./foo , +and vice-versa. +This is the default constraint type. +.It Basename +A constraint with no path is matched against the basename of the +executable. +For instance, the constraint +.Bq Pa foo +will match +.Pa /bin/foo , +.Pa /usr/local/sbin/foo , +or any other executable named +.Pa foo , +no matter what directory it is in. +.It Directory +A constraint with a trailing slash is satisfied if the full pathname +begins with the constraint string. +For instance, the constraint +.Bq Pa /usr/bin/ +will match any executable with a path starting with +.Pa /usr/bin/ . +.El +.Pp +Note that the constraints are matched against the path that was passed +as the first argument to whichever +.Xr exec 3 +function was used to execute the binary in question. +Most programs executed from a shell are run without a full path, via +.Xr execvp 3 +or similar, so the basename constraint type is the most useful. +.Pp +.Bf -symbolic +WARNING! +Constraints apply to all mappings until the next constraint or the end +of the file. +Hence, unconstrained mappings must be placed at the top of the file. +.Ef +.Ss ABI compatibility +On 64-bit architectures that provide 32-bit binary compatibility, the +mappings in +.Pa /etc/libmap.conf +apply only to 64-bit binaries. +Mappings for 32-bit binaries must be placed in +.Pa /etc/libmap32.conf . +.Sh FILES +.Bl -tag -width ".Pa /etc/libmap32.conf" -compact +.It Pa /etc/libmap.conf +The libmap configuration file. +.It Pa /etc/libmap32.conf +The libmap configuration file for 32-bit binaries on 64-bit system. +.El +.Sh EXAMPLES +.Bd -literal +# +# origin target +# +libc_r.so.6 libpthread.so.2 # Everything that uses 'libc_r' +libc_r.so libpthread.so # now uses 'libpthread' + +[/tmp/mplayer] # Test version of mplayer uses libc_r +libpthread.so.2 libc_r.so.6 +libpthread.so libc_r.so + +[/usr/local/jdk1.4.1/] # All Java 1.4.1 programs use libthr + # This works because "javavms" executes + # programs with the full pathname +libpthread.so.2 libthr.so.2 +libpthread.so libthr.so + +# Glue for Linux-only EPSON printer .so to be loaded into cups, etc. +[/usr/local/lib/pips/libsc80c.so] +libc.so.6 pluginwrapper/pips.so +libdl.so.2 pluginwrapper/pips.so +.Ed +.Sh SEE ALSO +.Xr ldd 1 , +.Xr rtld 1 +.Sh HISTORY +The +.Nm libmap +mechanism first appeared in +.Fx 5.1 . +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Matthew N. Dodd Aq Mt winter@jurai.net +and extensively rewritten by +.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . diff --git a/static/freebsd/man5/link.5 b/static/freebsd/man5/link.5 new file mode 100644 index 00000000..61c9c09e --- /dev/null +++ b/static/freebsd/man5/link.5 @@ -0,0 +1,588 @@ +.\" Copyright (c) 1993 Paul Kranenburg +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by Paul Kranenburg. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd October 23, 1993 +.Dt LINK 5 +.Os +.Sh NAME +.Nm link +.Nd dynamic loader and link editor interface +.Sh SYNOPSIS +.In sys/types.h +.In nlist.h +.In link.h +.Sh DESCRIPTION +The include file +.In link.h +declares several structures that are present in dynamically linked +programs and libraries. +The structures define the interface between several components of the +link-editor and loader mechanism. +The layout of a number of these +structures within the binaries resembles the a.out format in many places +as it serves such similar functions as symbol definitions (including the +accompanying string table) and relocation records needed to resolve +references to external entities. +It also records a number of data structures +unique to the dynamic loading and linking process. +These include references +to other objects that are required to complete the link-editing process and +indirection tables to facilitate +.Em Position Independent Code +(PIC for short) to improve sharing of code pages among different processes. +The collection of data structures described here will be referred to as the +.Em Run-time Relocation Section (RRS) +and is embedded in the standard text and data segments of the dynamically +linked program or shared object image as the existing +.Xr a.out 5 +format offers no room for it elsewhere. +.Pp +Several utilities cooperate to ensure that the task of getting a program +ready to run can complete successfully in a way that optimizes the use +of system resources. +The compiler emits PIC code from which shared libraries +can be built by +.Xr ld 1 . +The compiler also includes size information of any initialized data items +through the .size assembler directive. +PIC code differs from conventional code +in that it accesses data variables through an indirection table, the +Global Offset Table, by convention accessible by the reserved name +.Dv _GLOBAL_OFFSET_TABLE_ . +The exact mechanism used for this is machine dependent, usually a machine +register is reserved for the purpose. +The rational behind this construct +is to generate code that is independent of the actual load address. +Only +the values contained in the Global Offset Table may need updating at run-time +depending on the load addresses of the various shared objects in the address +space. +.Pp +Likewise, procedure calls to globally defined functions are redirected through +the Procedure Linkage Table (PLT) residing in the data segment of the core +image. +Again, this is done to avoid run-time modifications to the text segment. +.Pp +The linker-editor allocates the Global Offset Table and Procedure Linkage Table +when combining PIC object files into an image suitable for mapping into the +process address space. +It also collects all symbols that may be needed by the +run-time link-editor and stores these along with the image's text and data bits. +Another reserved symbol, +.Em _DYNAMIC +is used to indicate the presence of the run-time linker structures. +Whenever +_DYNAMIC is relocated to 0, there is no need to invoke the run-time +link-editor. +If this symbol is non-zero, it points at a data structure from +which the location of the necessary relocation- and symbol information can +be derived. +This is most notably used by the start-up module, +.Em crt0 . +The _DYNAMIC structure is conventionally located at the start of the data +segment of the image to which it pertains. +.Sh DATA STRUCTURES +The data structures supporting dynamic linking and run-time relocation +reside both in the text and data segments of the image they apply to. +The text segments contain read-only data such as symbols descriptions and +names, while the data segments contain the tables that need to be modified by +during the relocation process. +.Pp +The _DYNAMIC symbol references a +.Fa _dynamic +structure: +.Bd -literal -offset indent +struct _dynamic { + int d_version; + struct so_debug *d_debug; + union { + struct section_dispatch_table *d_sdt; + } d_un; + struct ld_entry *d_entry; +}; +.Ed +.Bl -tag -width d_version +.It Fa d_version +This field provides for different versions of the dynamic linking +implementation. +The current version numbers understood by +.Xr ld 1 +and +.Xr ld.so 1 +are +.Em LD_VERSION_SUN (3) , +which is used by the +.Tn SunOS +4.x releases, and +.Em LD_VERSION_BSD (8) , +which has been in use since +.Fx 1.1 . +.It Fa d_un +Refers to a +.Em d_version +dependent data structure. +.It Fa so_debug +this field provides debuggers with a hook to access symbol tables of shared +objects loaded as a result of the actions of the run-time link-editor. +.El +.Pp +The +.Fa section_dispatch_table +structure is the main +.Dq dispatcher +table, containing offsets into the image's segments where various symbol +and relocation information is located. +.Bd -literal -offset indent +struct section_dispatch_table { + struct so_map *sdt_loaded; + long sdt_sods; + long sdt_filler1; + long sdt_got; + long sdt_plt; + long sdt_rel; + long sdt_hash; + long sdt_nzlist; + long sdt_filler2; + long sdt_buckets; + long sdt_strings; + long sdt_str_sz; + long sdt_text_sz; + long sdt_plt_sz; +}; +.Ed +.Bl -tag -width sdt_filler1 +.It Fa sdt_loaded +A pointer to the first link map loaded (see below). +This field is set by +.Nm ld.so +.It Fa sdt_sods +The start of a (linked) list of shared object descriptors needed by +.Em this +object. +.It Fa sdt_filler1 +Deprecated (used by SunOS to specify library search rules). +.It Fa sdt_got +The location of the Global Offset Table within this image. +.It Fa sdt_plt +The location of the Procedure Linkage Table within this image. +.It Fa sdt_rel +The location of an array of +.Fa relocation_info +structures +(see +.Xr a.out 5 ) +specifying run-time relocations. +.It Fa sdt_hash +The location of the hash table for fast symbol lookup in this object's +symbol table. +.It Fa sdt_nzlist +The location of the symbol table. +.It Fa sdt_filler2 +Currently unused. +.It Fa sdt_buckets +The number of buckets in +.Fa sdt_hash +.It Fa sdt_strings +The location of the symbol string table that goes with +.Fa sdt_nzlist . +.It Fa sdt_str_sz +The size of the string table. +.It Fa sdt_text_sz +The size of the object's text segment. +.It Fa sdt_plt_sz +The size of the Procedure Linkage Table. +.El +.Pp +A +.Fa sod +structure describes a shared object that is needed +to complete the link edit process of the object containing it. +A list of such objects +(chained through +.Fa sod_next ) +is pointed at +by the +.Fa sdt_sods +in the section_dispatch_table structure. +.Bd -literal -offset indent +struct sod { + long sod_name; + u_int sod_library : 1, + sod_reserved : 31; + short sod_major; + short sod_minor; + long sod_next; +}; +.Ed +.Bl -tag -width sod_library +.It Fa sod_name +The offset in the text segment of a string describing this link object. +.It Fa sod_library +If set, +.Fa sod_name +specifies a library that is to be searched for by +.Nm ld.so . +The path name +is obtained by searching a set of directories +(see also +.Xr ldconfig 8 ) +for a shared object matching +.Em lib\&\&.so.n.m . +If not set, +.Fa sod_name +should point at a full path name for the desired shared object. +.It Fa sod_major +Specifies the major version number of the shared object to load. +.It Fa sod_minor +Specifies the preferred minor version number of the shared object to load. +.El +.Pp +The run-time link-editor maintains a list of structures called +.Em link maps +to keep track of all shared objects loaded into a process' address space. +These structures are only used at run-time and do not occur within +the text or data segment of an executable or shared library. +.Bd -literal -offset indent +struct so_map { + caddr_t som_addr; + char *som_path; + struct so_map *som_next; + struct sod *som_sod; + caddr_t som_sodbase; + u_int som_write : 1; + struct _dynamic *som_dynamic; + caddr_t som_spd; +}; +.Ed +.Bl -tag -width som_dynamic +.It Fa som_addr +The address at which the shared object associated with this link map has +been loaded. +.It Fa som_path +The full path name of the loaded object. +.It Fa som_next +Pointer to the next link map. +.It Fa som_sod +The +.Fa sod +structure that was responsible for loading this shared object. +.It Fa som_sodbase +Tossed out in later versions of the run-time linker. +.It Fa som_write +Set if (some portion of) this object's text segment is currently writable. +.It Fa som_dynamic +Pointer to this object's +.Fa _dynamic +structure. +.It Fa som_spd +Hook for attaching private data maintained by the run-time link-editor. +.El +.Pp +Symbol description with size. +This is simply an +.Fa nlist +structure with one field +.Pq Fa nz_size +added. +Used to convey size information on items in the data segment +of shared objects. +An array of these lives in the shared object's +text segment and is addressed by the +.Fa sdt_nzlist +field of +.Fa section_dispatch_table . +.Bd -literal -offset indent +struct nzlist { + struct nlist nlist; + u_long nz_size; +#define nz_un nlist.n_un +#define nz_strx nlist.n_un.n_strx +#define nz_name nlist.n_un.n_name +#define nz_type nlist.n_type +#define nz_value nlist.n_value +#define nz_desc nlist.n_desc +#define nz_other nlist.n_other +}; +.Ed +.Bl -tag -width nz_size +.It Fa nlist +(see +.Xr nlist 3 ) . +.It Fa nz_size +The size of the data represented by this symbol. +.El +.Pp +A hash table is included within the text segment of shared object +to facilitate quick lookup of symbols during run-time link-editing. +The +.Fa sdt_hash +field of the +.Fa section_dispatch_table +structure points at an array of +.Fa rrs_hash +structures: +.Bd -literal -offset indent +struct rrs_hash { + int rh_symbolnum; /* symbol number */ + int rh_next; /* next hash entry */ +}; +.Ed +.Bl -tag -width rh_symbolnum +.It Fa rh_symbolnum +The index of the symbol in the shared object's symbol table (as given by the +.Fa ld_symbols +field). +.It Fa rh_next +In case of collisions, this field is the offset of the next entry in this +hash table bucket. +It is zero for the last bucket element. +.El +The +.Fa rt_symbol +structure is used to keep track of run-time allocated commons +and data items copied from shared objects. +These items are kept on linked list +and is exported through the +.Fa dd_cc +field in the +.Fa so_debug +structure (see below) for use by debuggers. +.Bd -literal -offset indent +struct rt_symbol { + struct nzlist *rt_sp; + struct rt_symbol *rt_next; + struct rt_symbol *rt_link; + caddr_t rt_srcaddr; + struct so_map *rt_smp; +}; +.Ed +.Bl -tag -width rt_scraddr +.It Fa rt_sp +The symbol description. +.It Fa rt_next +Virtual address of next rt_symbol. +.It Fa rt_link +Next in hash bucket. +Used internally by +.Nm ld.so . +.It Fa rt_srcaddr +Location of the source of initialized data within a shared object. +.It Fa rt_smp +The shared object which is the original source of the data that this +run-time symbol describes. +.El +.Pp +The +.Fa so_debug +structure is used by debuggers to gain knowledge of any shared objects +that have been loaded in the process's address space as a result of run-time +link-editing. +Since the run-time link-editor runs as a part of process +initialization, a debugger that wishes to access symbols from shared objects +can only do so after the link-editor has been called from crt0. +A dynamically linked binary contains a +.Fa so_debug +structure which can be located by means of the +.Fa d_debug +field in +.Fa _dynamic . +.Bd -literal -offset indent +struct so_debug { + int dd_version; + int dd_in_debugger; + int dd_sym_loaded; + char *dd_bpt_addr; + int dd_bpt_shadow; + struct rt_symbol *dd_cc; +}; +.Ed +.Bl -tag -width dd_in_debugger +.It Fa dd_version +Version number of this interface. +.It Fa dd_in_debugger +Set by the debugger to indicate to the run-time linker that the program is +run under control of a debugger. +.It Fa dd_sym_loaded +Set by the run-time linker whenever it adds symbols by loading shared objects. +.It Fa dd_bpt_addr +The address where a breakpoint will be set by the run-time linker to +divert control to the debugger. +This address is determined by the start-up +module, +.Pa crt0.o , +to be some convenient place before the call to _main. +.It Fa dd_bpt_shadow +Contains the original instruction that was at +.Fa dd_bpt_addr . +The debugger is expected to put this instruction back before continuing the +program. +.It Fa dd_cc +A pointer to the linked list of run-time allocated symbols that the debugger +may be interested in. +.El +.Pp +The +.Em ld_entry +structure defines a set of service routines within +.Nm ld.so . +.\" See +.\" .Xr libdl.a +.\" for more information. +.Bd -literal -offset indent +struct ld_entry { + void *(*dlopen)(char *, int); + int (*dlclose)(void *); + void *(*dlsym)(void *, char *); + char *(*dlerror)(void); +}; +.Ed +.Pp +The +.Fa crt_ldso +structure defines the interface between the start-up code in crt0 and +.Nm ld.so . +.Bd -literal -offset indent +struct crt_ldso { + int crt_ba; + int crt_dzfd; + int crt_ldfd; + struct _dynamic *crt_dp; + char **crt_ep; + caddr_t crt_bp; + char *crt_prog; + char *crt_ldso; + struct ld_entry *crt_ldentry; +}; +#define CRT_VERSION_SUN 1 +#define CRT_VERSION_BSD_2 2 +#define CRT_VERSION_BSD_3 3 +#define CRT_VERSION_BSD_4 4 +.Ed +.Bl -tag -width crt_dzfd +.It Fa crt_ba +The virtual address at which +.Nm ld.so +was loaded by crt0. +.It Fa crt_dzfd +On SunOS systems, this field contains an open file descriptor to +.Dq Pa /dev/zero +used to get demand paged zeroed pages. +On +.Fx +systems it contains -1. +.It Fa crt_ldfd +Contains an open file descriptor that was used by crt0 to load +.Nm ld.so . +.It Fa crt_dp +A pointer to main's +.Fa _dynamic +structure. +.It Fa crt_ep +A pointer to the environment strings. +.It Fa crt_bp +The address at which a breakpoint will be placed by the run-time linker +if the main program is run by a debugger. +See +.Fa so_debug +.It Fa crt_prog +The name of the main program as determined by crt0 (CRT_VERSION_BSD3 only). +.It Fa crt_ldso +The path of the run-time linker as mapped by crt0 (CRT_VERSION_BSD4 only). +.El +.Pp +The +.Fa hints_header +and +.Fa hints_bucket +structures define the layout of the library hints, normally found in +.Dq Pa /var/run/ld.so.hints , +which is used by +.Nm ld.so +to quickly locate the shared object images in the +file system. +The organization of the hints file is not unlike that of an +.Dq a.out +object file, in that it contains a header determining the offset and size +of a table of fixed sized hash buckets and a common string pool. +.Bd -literal -offset indent +struct hints_header { + long hh_magic; +#define HH_MAGIC 011421044151 + long hh_version; +#define LD_HINTS_VERSION_1 1 + long hh_hashtab; + long hh_nbucket; + long hh_strtab; + long hh_strtab_sz; + long hh_ehints; +}; +.Ed +.Bl -tag -width hh_strtab_sz +.It Fa hh_magic +Hints file magic number. +.It Fa hh_version +Interface version number. +.It Fa hh_hashtab +Offset of hash table. +.It Fa hh_strtab +Offset of string table. +.It Fa hh_strtab_sz +Size of strings. +.It Fa hh_ehints +Maximum usable offset in hints file. +.El +.Bd -literal -offset indent +/* + * Hash table element in hints file. + */ +struct hints_bucket { + int hi_namex; + int hi_pathx; + int hi_dewey[MAXDEWEY]; + int hi_ndewey; +#define hi_major hi_dewey[0] +#define hi_minor hi_dewey[1] + int hi_next; +}; +.Ed +.Bl -tag -width hi_ndewey +.It Fa hi_namex +Index of the string identifying the library. +.It Fa hi_pathx +Index of the string representing the full path name of the library. +.It Fa hi_dewey +The version numbers of the shared library. +.It Fa hi_ndewey +The number of valid entries in +.Fa hi_dewey . +.It Fa hi_next +Next bucket in case of hashing collisions. +.El +.Sh CAVEATS +Only the (GNU) C compiler currently supports the creation of shared libraries. +Other programming languages cannot be used. diff --git a/static/freebsd/man5/mailer.conf.5 b/static/freebsd/man5/mailer.conf.5 new file mode 100644 index 00000000..e7ec72ab --- /dev/null +++ b/static/freebsd/man5/mailer.conf.5 @@ -0,0 +1,171 @@ +.\" $NetBSD: mailer.conf.5,v 1.2 1999/05/29 18:18:30 christos Exp $ +.\" +.\" Copyright (c) 1998 +.\" Perry E. Metzger. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgment: +.\" This product includes software developed for the NetBSD Project +.\" by Perry E. Metzger. +.\" 4. 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 December 26, 2017 +.Dt MAILER.CONF 5 +.Os +.Sh NAME +.Nm mailer.conf +.Nd configuration file for +.Xr mailwrapper 8 +.Sh DESCRIPTION +The file +.Pa /etc/mail/mailer.conf +contains a series of lines of the form +.Pp +.Ar name +.Ar program +.Op Ar arguments ... +.Pp +The first word of each line is the +.Ar name +of a program invoking +.Xr mailwrapper 8 . +(For example, on a typical system +.Pa /usr/sbin/sendmail +would be a symbolic link to +.Xr mailwrapper 8 , +as would +.Xr newaliases 1 +and +.Xr mailq 1 . +Thus, +.Ar name +might be +.Dq Li sendmail +or +.Dq Li newaliases +etc.) +.Pp +The second word of each line is the name of the +.Ar program +to actually execute when the first name is invoked. +.Pp +The further +.Ar arguments , +if any, are passed to the +.Ar program , +followed by the arguments +.Xr mailwrapper 8 +was called with. +.Pp +The file may also contain comment lines, denoted by a +.Ql # +mark in the first column of any line. +.Sh FILES +.Bl -tag -width Pa +.It Pa /etc/mail/mailer.conf +.El +.Sh EXAMPLES +This example shows how to set up +.Nm +to invoke the traditional +.Xr sendmail 8 +program: +.Bd -literal -offset indent +# Execute the "real" sendmail program located in +# /usr/libexec/sendmail/sendmail +sendmail /usr/libexec/sendmail/sendmail +mailq /usr/libexec/sendmail/sendmail +newaliases /usr/libexec/sendmail/sendmail +.Ed +.Pp +Using +.Nm Postfix +(from ports) +to replace +.Xr sendmail 8 : +.Bd -literal -offset indent +# Emulate sendmail using postfix +sendmail /usr/local/sbin/sendmail +mailq /usr/local/sbin/sendmail +newaliases /usr/local/sbin/sendmail +.Ed +.Pp +Using +.Nm Exim +(from ports) +to replace +.Xr sendmail 8 : +.Bd -literal -offset indent +# Emulate sendmail using exim +sendmail /usr/local/sbin/exim +mailq /usr/local/sbin/exim -bp +newaliases /usr/bin/true +rmail /usr/local/sbin/exim -i -oee +.Ed +.Pp +Using +.Nm mini_sendmail +(from ports) +to replace +.Xr sendmail 8 : +.Bd -literal -offset indent +# Send outgoing mail to a smart relay using mini_sendmail +sendmail /usr/local/bin/mini_sendmail -srelayhost +.Ed +.Pp +Using +.Xr dma 8 +to replace +.Xr sendmail 8 : +.Bd -literal -offset indent +# Execute dma instead of sendmail +sendmail /usr/libexec/dma +mailq /usr/libexec/dma +newaliases /usr/libexec/dma +rmail /usr/libexec/dma +.Ed +.Sh SEE ALSO +.Xr mail 1 , +.Xr mailq 1 , +.Xr newaliases 1 , +.Xr dma 8 , +.Xr mailwrapper 8 , +.Xr sendmail 8 +.Pp +.Xr postfix 1 Pq Pa ports/mail/postfix , +.Xr dma 8 Pq Pa ports/mail/dma , +.Xr exim 8 Pq Pa ports/mail/exim , +.Xr mini_sendmail 8 Pq Pa ports/mail/mini_sendmail +.Sh HISTORY +.Nm +appeared in +.Nx 1.4 . +.Sh AUTHORS +.An Perry E. Metzger Aq Mt perry@piermont.com +.Sh BUGS +The entire reason this program exists is a crock. +Instead, a command +for how to submit mail should be standardized, and all the "behave +differently if invoked with a different name" behavior of things like +.Xr mailq 1 +should go away. diff --git a/static/freebsd/man5/make.conf.5 b/static/freebsd/man5/make.conf.5 new file mode 100644 index 00000000..46bfa91d --- /dev/null +++ b/static/freebsd/man5/make.conf.5 @@ -0,0 +1,688 @@ +.\" Copyright (c) 2000 +.\" Mike W. Meyer +.\" +.\" 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 ``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 November 15, 2022 +.Dt MAKE.CONF 5 +.Os +.Sh NAME +.Nm make.conf +.Nd system build information +.Sh DESCRIPTION +The file +.Nm +contains system-wide settings that will apply to every build using +.Xr make 1 +and the standard +.Pa sys.mk +file. +This is achieved as follows: +.Xr make 1 +processes the system makefile +.Pa sys.mk +before any other file by default, and +.Pa sys.mk +includes +.Nm . +.Pp +The file +.Nm +uses the standard makefile syntax. +However, +.Nm +should not specify any dependencies to +.Xr make 1 . +Instead, +.Nm +is to set +.Xr make 1 +variables that control the actions of other makefiles. +.Pp +The default location of +.Nm +is +.Pa /etc/make.conf , +though an alternative location can be specified in the +.Xr make 1 +variable +.Va __MAKE_CONF . +You may need to override the location of +.Nm +if the system-wide settings are not suitable for a particular build. +For instance, setting +.Va __MAKE_CONF +to +.Pa /dev/null +effectively resets all build controls to their defaults. +.Pp +The primary purpose of +.Nm +is to control the compilation of the +.Fx +sources, documentation, and ported applications, +which are usually found in +.Pa /usr/src , +.Pa /usr/doc , +and +.Pa /usr/ports . +As a rule, the system administrator creates +.Nm +when the values of certain control variables need to be changed +from their defaults. +.Pp +The system build procedures occur in four broad areas: +the world, the kernel, documentation and ports. +Variables set in +.Nm +may be applicable in one, two, or all four of these areas. +In addition, control variables can be specified +for a particular build via the +.Fl D +option of +.Xr make 1 +or in +.Xr environ 7 . +In the case of world and kernel builds it is possible to put these variables +into +.Xr src.conf 5 +instead of +.Nm . +This way the environment for documentation and ports builds is not polluted +by unrelated variables. +.Pp +The following lists provide a name and short description for each +variable you can use during the indicated builds. +The values of +variables flagged as +.Vt bool +are ignored; the variable being +set at all (even to +.Dq Li FALSE +or +.Dq Li NO ) +causes it to +be treated as if it were set. +.Pp +The following list provides a name and short description for variables +that are used for all builds, or are used by the +.Pa makefiles +for things other than builds. +.Bl -tag -width Ar +.It Va ALWAYS_CHECK_MAKE +.Pq Vt bool +Instructs the top-level makefile in the source tree (normally +.Pa /usr/src ) +to always check if +.Xr make 1 +is up-to-date. +Normally this is only done for the world and buildworld targets to handle +upgrades from older versions of +.Fx . +.It Va CFLAGS +.Pq Vt str +Controls the compiler setting when compiling C code. +Optimization levels other than +.Fl O +and +.Fl O2 +are not supported. +.It Va CPUTYPE +.Pq Vt str +Controls which processor should be targeted for generated +code. +This controls processor-specific optimizations in +certain code (currently only OpenSSL) as well as modifying +the value of +.Va CFLAGS +and +.Va COPTFLAGS +to contain the appropriate optimization directive to +.Xr cc 1 . +To set the +.Va CPUTYPE +value, use +.Dq Li ?= +instead of +.Dq Li = +so that it can be overridden by +.Xr make 1 +targets. +The automatic setting of +.Va CFLAGS +may be overridden using the +.Va NO_CPU_CFLAGS +variable. +Refer to +.Pa /usr/share/examples/etc/make.conf +for a list of recognized +.Va CPUTYPE +options. +.It Va CXXFLAGS +.Pq Vt str +Controls the compiler settings when compiling C++ code. +.Va CXXFLAGS +is initially set to the value of +.Va CFLAGS . +If you want to +add to the +.Va CXXFLAGS +value, use +.Dq Li += +instead of +.Dq Li = . +.It Va DTC +.Pq Vt str +Select the compiler for DTS (Device Tree Syntax) file. +.Va DTC +is initially set to the value of dtc +.It Va INSTALL +.Pq Vt str +the default install command. +To install only files for which the target differs or does not exist, use +.Bd -literal -offset indent +INSTALL+= -C +.Ed +Note that some makefiles (including those in +.Pa /usr/share/mk ) +may hardcode options for the supplied install command. +.It Va LOCAL_DIRS +.Pq Vt str +List any directories that should be entered when doing +make's in +.Pa /usr/src +in this variable. +.It Va MAKE_SHELL +.Pq Vt str +Controls the shell used internally by +.Xr make 1 +to process the command scripts in makefiles. +.Xr sh 1 , +.Xr ksh 1 , +and +.Xr csh 1 +all currently supported. +.Pp +.Dl "MAKE_SHELL?=sh" +.It Va MTREE_FOLLOWS_SYMLINKS +.Pq Vt str +Set this to +.Dq Fl L +to cause +.Xr mtree 8 +to follow symlinks. +.It Va NO_CPU_CFLAGS +.Pq Vt str +Setting this variable will prevent CPU specific compiler flags +from being automatically added to +.Va CFLAGS +during compile time. +.El +.Ss "BUILDING THE KERNEL" +The following list provides a name and short description for variables +that are only used doing a kernel build: +.Bl -tag -width Ar +.It Va BOOTWAIT +.Pq Vt int +Controls the amount of time the kernel waits for a console keypress +before booting the default kernel. +The value is approximately milliseconds. +Keypresses are accepted by the BIOS before booting from disk, +making it possible to give custom boot parameters even when this is +set to 0. +.It Va COPTFLAGS +.Pq Vt str +Controls the compiler settings when building the +kernel. +Optimization levels above +.Oo Fl O ( O2 , No ...\& ) Oc +are not guaranteed to work. +.It Va KERNCONF +.Pq Vt str +Controls which kernel configurations will be +built by +.Dq Li "${MAKE} buildkernel" +and installed by +.Dq Li "${MAKE} installkernel" . +For example, +.Bd -literal -offset indent +KERNCONF=MINE DEBUG GENERIC OTHERMACHINE +.Ed +.Pp +will build the kernels specified by the config files +.Pa MINE , DEBUG , GENERIC , +and +.Pa OTHERMACHINE , +and install the kernel specified by the config file +.Pa MINE . +It defaults to +.Pa GENERIC . +.It Va MODULES_OVERRIDE +.Pq Vt str +Set to a list of modules to build instead of all of them. +.It Va NO_KERNELCLEAN +.Pq Vt bool +Set this to skip running +.Dq Li "${MAKE} clean" +during +.Dq Li "${MAKE} buildkernel" . +.It Va NO_KERNELCONFIG +.Pq Vt bool +Set this to skip running +.Xr config 8 +during +.Dq Li "${MAKE} buildkernel" . +.It Va NO_KERNELOBJ +.Pq Vt bool +Set this to skip running +.Dq Li "${MAKE} obj" +during +.Dq Li "${MAKE} buildkernel" . +.It Va NO_MODULES +.Pq Vt bool +Set to not build modules with the kernel. +.It Va PORTS_MODULES +Set this to the list of ports you wish to rebuild every time the kernel +is built. +.It Va WITHOUT_MODULES +.Pq Vt str +Set to a list of modules to exclude from the build. +This provides a +somewhat easier way to exclude modules you are certain you will never +need than specifying +.Va MODULES_OVERRIDE . +This is applied +.Em after +.Va MODULES_OVERRIDE . +.El +.Ss "BUILDING THE WORLD" +The following list provides a name and short description for variables +that are used during the world build: +.Bl -tag -width Ar +.It Va BOOT_COMCONSOLE_PORT +.Pq Vt str +The port address to use for the console if the boot blocks have +been configured to use a serial console instead of the keyboard/video card. +.It Va BOOT_COMCONSOLE_SPEED +.Pq Vt int +The baud rate to use for the console if the boot blocks have +been configured to use a serial console instead of the keyboard/video card. +.It Va BOOT_PXELDR_ALWAYS_SERIAL +.Pq Vt bool +Compile in the code into +.Xr pxeboot 8 +that forces the use of a serial console. +This is analogous to the +.Fl h +option in +.Xr boot 8 +blocks. +.It Va BOOT_PXELDR_PROBE_KEYBOARD +.Pq Vt bool +Compile in the code into +.Xr pxeboot 8 +that probes the keyboard. +If no keyboard is found, boot with the dual console configuration. +This is analogous to the +.Fl D +option in +.Xr boot 8 +blocks. +.It Va ENABLE_SUID_K5SU +.Pq Vt bool +Set this if you wish to use the ksu utility. +Otherwise, it will be +installed without the set-user-ID bit set. +.It Va ENABLE_SUID_NEWGRP +.Pq Vt bool +Set this to install +.Xr newgrp 1 +with the set-user-ID bit set. +Otherwise, +.Xr newgrp 1 +will not be able to change users' groups. +.It Va LOADER_TFTP_SUPPORT +.Pq Vt bool +By default the +.Xr pxeboot 8 +loader retrieves the kernel via NFS. +Defining this and recompiling +.Pa /usr/src/stand +will cause it to retrieve the kernel via TFTP. +This allows +.Xr pxeboot 8 +to load a custom BOOTP diskless kernel yet +still mount the server's +.Pa / +rather than load the server's kernel. +.It Va LOADER_FIREWIRE_SUPPORT +.Pq Vt bool +Defining this and recompiling +.Pa /usr/src/stand/i386 +will add +.Xr dcons 4 +console driver to +.Xr loader 8 +and allow access over FireWire(IEEE1394) using +.Xr dconschat 8 . +Currently, only i386 and amd64 are supported. +.It Va MAN_ARCH +.Pq Vt str +Space-delimited list of one or more MACHINE and/or MACHINE_ARCH values +for which section 4 man pages will be installed. +The special value +.Sq all +installs all available architectures. +It is also the default value. +.It Va MODULES_WITH_WORLD +.Pq Vt bool +Set to build modules with the system instead of the kernel. +.It Va NO_CLEAN +.Pq Vt bool +Set this to disable cleaning during +.Dq Li "make buildworld" . +This should not be set unless you know what you are doing. +.It Va NO_CLEANDIR +.Pq Vt bool +Set this to run +.Dq Li "${MAKE} clean" +instead of +.Dq Li "${MAKE} cleandir" . +.It Va WITH_MANCOMPRESS +.Pq Vt defined +Set to install manual pages compressed. +.It Va WITHOUT_MANCOMPRESS +.Pq Vt defined +Set to install manual pages uncompressed. +.It Va NO_SHARE +.Pq Vt bool +Set to not build in the +.Pa share +subdir. +.It Va NO_SHARED +.Pq Vt bool +Set to build +.Pa /bin +and +.Pa /sbin +statically linked, this can be bad. +If set, every utility that uses +.Pa bsd.prog.mk +will be linked statically. +.It Va PKG_REPO_SIGNING_KEY +.Pq Vt str +Path to rsa private key passed to +.Xr pkg-repo 8 +to sign packages created when building the +.Ar packages +target, i.e.: pkgbase. +The variable is named the same in +.Xr poudriere 8 +so it will automatically be picked up when building pkgbase with poudriere. +.It Va PPP_NO_NAT +.Pq Vt bool +Build +.Xr ppp 8 +without support for network address translation (NAT). +.It Va PPP_NO_NETGRAPH +.Pq Vt bool +Set to build +.Xr ppp 8 +without support for Netgraph. +.It Va PPP_NO_RADIUS +.Pq Vt bool +Set to build +.Xr ppp 8 +without support for RADIUS. +.It Va PPP_NO_SUID +.Pq Vt bool +Set to disable the installation of +.Xr ppp 8 +as a set-user-ID root program. +.It Va SENDMAIL_ADDITIONAL_MC +.Pq Vt str +Additional +.Pa .mc +files which should be built into +.Pa .cf +files at build time. +The value should include the full path to the +.Pa .mc +file(s), e.g., +.Pa /etc/mail/foo.mc , +.Pa /etc/mail/bar.mc . +.It Va SENDMAIL_ALIASES +.Pq Vt str +List of +.Xr aliases 5 +files to rebuild when using +.Pa /etc/mail/Makefile . +The default value is +.Pa /etc/mail/aliases . +.It Va SENDMAIL_CFLAGS +.Pq Vt str +Flags to pass to the compile command when building +.Xr sendmail 8 . +The +.Va SENDMAIL_* +flags can be used to provide SASL support with setting such as: +.Bd -literal -offset indent +SENDMAIL_CFLAGS=-I/usr/local/include -DSASL +SENDMAIL_LDFLAGS=-L/usr/local/lib +SENDMAIL_LDADD=-lsasl +.Ed +.It Va SENDMAIL_CF_DIR +.Pq Vt str +Override the default location for the +.Xr m4 1 +configuration files used to build a +.Pa .cf +file from a +.Pa .mc +file. +.It Va SENDMAIL_DPADD +.Pq Vt str +Extra dependencies to add when building +.Xr sendmail 8 . +.It Va SENDMAIL_LDADD +.Pq Vt str +Flags to add to the end of the +.Xr ld 1 +command when building +.Xr sendmail 8 . +.It Va SENDMAIL_LDFLAGS +.Pq Vt str +Flags to pass to the +.Xr ld 1 +command when building +.Xr sendmail 8 . +.It Va SENDMAIL_M4_FLAGS +.Pq Vt str +Flags passed to +.Xr m4 1 +when building a +.Pa .cf +file from a +.Pa .mc +file. +.It Va SENDMAIL_MAP_PERMS +.Pq Vt str +Mode to use when generating alias and map database files using +.Pa /etc/mail/Makefile . +The default value is 0640. +.It Va SENDMAIL_MAP_SRC +.Pq Vt str +Additional maps to rebuild when using +.Pa /etc/mail/Makefile . +The +.Pa access , +.Pa bitdomain , +.Pa domaintable , +.Pa genericstable , +.Pa mailertable , +.Pa uucpdomain , +and +.Pa virtusertable +maps are always rebuilt if they exist. +.It Va SENDMAIL_MAP_TYPE +.Pq Vt str +Database map type to use when generating map database files using +.Pa /etc/mail/Makefile . +The default value is hash. +The alternative is btree. +.It Va SENDMAIL_MC +.Pq Vt str +The default +.Xr m4 1 +configuration file to use at install time. +The value should include the full path to the +.Pa .mc +file, e.g., +.Pa /etc/mail/myconfig.mc . +Use with caution as a make install will overwrite any existing +.Pa /etc/mail/sendmail.cf . +Note that +.Va SENDMAIL_CF +is deprecated. +.It Va SENDMAIL_SET_USER_ID +.Pq Vt bool +If set, install +.Xr sendmail 8 +as a set-user-ID root binary instead of a set-group-ID binary +and do not install +.Pa /etc/mail/submit.{cf,mc} . +Use of this flag is not recommended and the alternative advice in +.Pa /etc/mail/README +should be followed instead if at all possible. +.It Va SENDMAIL_START_SCRIPT +.Pq Vt str +The script used by +.Pa /etc/mail/Makefile +to start, stop, and restart +.Xr sendmail 8 . +The default value is +.Pa /etc/rc.d/sendmail . +.It Va SENDMAIL_SUBMIT_MC +.Pq Vt str +The default +.Xr m4 1 +configuration file for mail submission +to use at install time. +The value should include the full path to the +.Pa .mc +file, e.g., +.Pa /etc/mail/mysubmit.mc . +Use with caution as a make install will overwrite any existing +.Pa /etc/mail/submit.cf . +.It Va TOP_TABLE_SIZE +.Pq Vt int +.Xr top 1 +uses a hash table for the user names. +The size of this hash can be tuned to match the number of local users. +The table size should be a prime number +approximately twice as large as the number of lines in +.Pa /etc/passwd . +The default number is 20011. +.It Va WANT_FORCE_OPTIMIZATION_DOWNGRADE +.Pq Vt int +Causes the system compiler to be built such that it forces high optimization +levels to a lower one. +.Xr cc 1 +.Fl O2 +and above is known to trigger known optimizer bugs at various +times. +The value assigned is the highest optimization value used. +.El +.Ss "BUILDING DOCUMENTATION" +The following list provides a name and short description for variables +that are used when building documentation. +.Bl -tag -width ".Va PRINTERDEVICE" +.It Va DOC_LANG +.Pq Vt str +The list of languages to build and install when building documentation +in +.Pa /usr/doc . +.It Va PRINTERDEVICE +.Pq Vt str +The default format for system documentation in +.Pa /usr/src/share/doc , +depends on your printer. +This can be set to +.Dq Li ascii +for simple printers, or +.Dq Li ps +for postscript or graphics printers with a ghostscript +filter, or both. +.El +.Ss "BUILDING PORTS" +Several make variables can be set that affect the building of ports. +These variables and their effects are documented in +.Xr ports 7 , +.Pa ${PORTSDIR}/Mk/* +and the +.Fx +Porter's Handbook. +.Sh FILES +.Bl -tag -width ".Pa /usr/share/examples/etc/make.conf" -compact +.It Pa /etc/make.conf +.It Pa /usr/doc/Makefile +.It Pa /usr/ports/Makefile +.It Pa /usr/share/examples/etc/make.conf +.It Pa /usr/share/mk/sys.mk +.It Pa /usr/src/Makefile +.It Pa /usr/src/Makefile.inc1 +.El +.Sh SEE ALSO +.Xr cc 1 , +.Xr install 1 , +.Xr make 1 , +.Xr src.conf 5 , +.Xr style.Makefile 5 , +.Xr environ 7 , +.Xr ports 7 , +.Xr sendmail 8 +.Sh HISTORY +The +.Nm +file appeared sometime before +.Fx 4.0 . +.Sh AUTHORS +This +manual page was written by +.An Mike W. Meyer Aq Mt mwm@mired.org . +.Sh CAVEATS +Note, that +.Ev MAKEOBJDIRPREFIX +and +.Ev MAKEOBJDIR +are environment variables and should not be set in +.Nm +or as command line arguments to +.Xr make 1 , +but in make's environment. +.Sh BUGS +This manual page may occasionally be out of date with respect to +the options currently available for use in +.Nm . +Please check the +.Pa /usr/share/examples/etc/make.conf +file for the latest options which are available. diff --git a/static/freebsd/man5/moduli.5 b/static/freebsd/man5/moduli.5 new file mode 100644 index 00000000..eead6cd0 --- /dev/null +++ b/static/freebsd/man5/moduli.5 @@ -0,0 +1,123 @@ +.\" $OpenBSD: moduli.5,v 1.16 2011/11/28 08:46:27 eric Exp $ +.\" +.\" Copyright (c) 2008 Damien Miller +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd July 19, 2012 +.Dt MODULI 5 +.Os +.Sh NAME +.Nm moduli +.Nd Diffie-Hellman moduli +.Sh DESCRIPTION +The +.Pa /etc/ssh/moduli +file contains prime numbers and generators for use by +.Xr sshd 8 +in the Diffie-Hellman Group Exchange key exchange method. +.Pp +New moduli may be generated with +.Xr ssh-keygen 1 +using a two-step process. +An initial +.Em candidate generation +pass, using +.Ic ssh-keygen -G , +calculates numbers that are likely to be useful. +A second +.Em primality testing +pass, using +.Ic ssh-keygen -T , +provides a high degree of assurance that the numbers are prime and are +safe for use in Diffie-Hellman operations by +.Xr sshd 8 . +This +.Nm +format is used as the output from each pass. +.Pp +The file consists of newline-separated records, one per modulus, +containing seven space-separated fields. +These fields are as follows: +.Bl -tag -width Description -offset indent +.It timestamp +The time that the modulus was last processed as YYYYMMDDHHMMSS. +.It type +Decimal number specifying the internal structure of the prime modulus. +Supported types are: +.Pp +.Bl -tag -width 0x00 -compact +.It 0 +Unknown, not tested. +.It 2 +"Safe" prime; (p-1)/2 is also prime. +.It 4 +Sophie Germain; 2p+1 is also prime. +.El +.Pp +Moduli candidates initially produced by +.Xr ssh-keygen 1 +are Sophie Germain primes (type 4). +Further primality testing with +.Xr ssh-keygen 1 +produces safe prime moduli (type 2) that are ready for use in +.Xr sshd 8 . +Other types are not used by OpenSSH. +.It tests +Decimal number indicating the type of primality tests that the number +has been subjected to represented as a bitmask of the following values: +.Pp +.Bl -tag -width 0x00 -compact +.It 0x00 +Not tested. +.It 0x01 +Composite number \(en not prime. +.It 0x02 +Sieve of Eratosthenes. +.It 0x04 +Probabilistic Miller-Rabin primality tests. +.El +.Pp +The +.Xr ssh-keygen 1 +moduli candidate generation uses the Sieve of Eratosthenes (flag 0x02). +Subsequent +.Xr ssh-keygen 1 +primality tests are Miller-Rabin tests (flag 0x04). +.It trials +Decimal number indicating the number of primality trials +that have been performed on the modulus. +.It size +Decimal number indicating the size of the prime in bits. +.It generator +The recommended generator for use with this modulus (hexadecimal). +.It modulus +The modulus itself in hexadecimal. +.El +.Pp +When performing Diffie-Hellman Group Exchange, +.Xr sshd 8 +first estimates the size of the modulus required to produce enough +Diffie-Hellman output to sufficiently key the selected symmetric cipher. +.Xr sshd 8 +then randomly selects a modulus from +.Fa /etc/ssh/moduli +that best meets the size requirement. +.Sh SEE ALSO +.Xr ssh-keygen 1 , +.Xr sshd 8 +.Rs +.%R RFC 4419 +.%T "Diffie-Hellman Group Exchange for the Secure Shell (SSH) Transport Layer Protocol" +.%D 2006 +.Re diff --git a/static/freebsd/man5/motd.5 b/static/freebsd/man5/motd.5 new file mode 100644 index 00000000..109fc4e5 --- /dev/null +++ b/static/freebsd/man5/motd.5 @@ -0,0 +1,63 @@ +.\" $NetBSD: motd.5,v 1.2 1994/12/28 18:58:53 glass Exp $ +.\" +.\" This file is in the public domain. +.\" +.Dd December 14, 2024 +.Dt MOTD 5 +.Os +.Sh NAME +.Nm motd +.Nd file containing message(s) of the day +.Sh DESCRIPTION +The file +.Pa /var/run/motd +is normally displayed by +.Xr login 1 +after a user has logged in but before the shell is run. +It is generally used for important system-wide announcements. +During system startup, a line containing the kernel version string is +prepended to +.Pa /etc/motd.template +and the contents are written to +.Pa /var/run/motd . +.Pp +.Pa /var/run/motd +can be updated without a system reboot by manually restarting the +motd service after updating +.Pa /etc/motd.template : +.Pp +.Dl service motd restart +.Pp +Individual users may suppress the display of this file by +creating a file named +.Dq Pa .hushlogin +in their home directories or through +.Xr login.conf 5 . +.Sh FILES +.Bl -tag -width "/etc/motd.template" -compact +.It Pa /etc/motd +Symbolic link to +.Pa /var/run/motd . +.It Pa /etc/motd.template +The template file that system administrators can edit. +.It Pa /var/run/motd +The message of the day. +.It Pa $HOME/.hushlogin +Suppresses output of +.Pa /var/run/motd . +.El +.Sh EXAMPLES +.Bd -literal +FreeBSD 12.1-RELEASE (GENERIC) #0: Sun Dec 29 03:08:31 PST 2019 + +/home is full. Please cleanup your directories. +.Ed +.Sh SEE ALSO +.Xr login 1 , +.Xr login.conf 5 +.Sh HISTORY +Prior to +.Fx 13.0 , +.Nm +lived in +.Pa /etc . diff --git a/static/freebsd/man5/mount.conf.5 b/static/freebsd/man5/mount.conf.5 new file mode 100644 index 00000000..4b5c272e --- /dev/null +++ b/static/freebsd/man5/mount.conf.5 @@ -0,0 +1,249 @@ +.\" Copyright (c) 2013 Marcel Moolenaar +.\" Copyright (c) 2013 Craig Rodrigues +.\" 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 AUTHORS 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 AUTHORS 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 October 17, 2013 +.Dt MOUNT.CONF 5 +.Os +.Sh NAME +.Nm mount.conf +.Nd root file system mount configuration file +.Sh SYNOPSIS +.Pa /.mount.conf +.Sh DESCRIPTION +During the bootup process, the +.Fx +kernel will try to mount the root file system +using the logic in the +.Fn vfs_mountroot +function in +.Pa src/sys/kern/vfs_mountroot.c . +The root mount logic can be described as follows: +.Bl -enum +.It +The kernel will synthesize in memory a config file +with default directives for mounting +the root file system. +The logic for this is in +.Fn vfs_mountroot_conf0 . +.It +The kernel will first mount +.Xr devfs 4 +as the root file system. +.It +Next, the kernel will parse the in-memory config file created in step 1 +and try to mount the actual root file system. +See +.Sx FILE FORMAT +for the format of the config file. +.It +When the actual root file system is mounted, +.Xr devfs 4 +will be re-mounted on the +.Pa /dev +directory. +.It +If a +.Pa /.mount.conf +file does not exist in the root file system which was +just mounted, the root mount logic stops here. +.It +If a +.Pa /.mount.conf +file exists in the root file system which was just mounted, +this file will be parsed, and the kernel will use this new config +file to try to re-mount the root file system. +See +.Sx FILE FORMAT +for the format of the config file. +.It +If the new root file system has a +.Pa /.mount +directory, the old root file system will be re-mounted +on +.Pa /.mount . +.It +The root mount logic will go back to step 4. +.El +.Pp +The root mount logic is recursive, and step 8 will +be repeated as long as each new root file system +which is mounted has a +.Pa /.mount.conf +file. +.Sh FILE FORMAT +The kernel parses each line in +.Pa .mount.conf +and then tries to perform the action specified on that line as soon as it is parsed. +.Bl -tag -width "XXXXXXXXXX" +.It Ic # +A line beginning with a # is a comment and is ignored. +.It Ic {FS}:{MOUNTPOINT} {OPTIONS} +The kernel will try to mount this in an +operation equivalent to: +.Bd -literal -offset indent +mount -t {FS} -o {OPTIONS} {MOUNTPOINT} / +.Ed +.Pp +If this is successfully mounted, +further lines in +.Pa .mount.conf +are ignored. +If all lines in +.Pa .mount.conf +have been processed and no root file system has been successfully +mounted, then the action specified by +.Ic .onfail +is performed. +.It Ic .ask +When the kernel processes this line, a +.Li mountroot> +command-line prompt is displayed. +At this prompt, the operator can enter the root mount. +.It Ic .md Ar file +Create a memory backed +.Xr md 4 +virtual disk, using +.Ar file +as the backing store. +.It Ic .onfail Ar [panic|reboot|retry|continue] +If after parsing all the lines in +.Pa .mount.conf +the kernel is unable to mount a root file system, +the +.Ic .onfail +directive tells the kernel what action to perform. +.It Ic .timeout Ar N +Before trying to mount a root file system, +if the root mount device does not exist, wait at most +.Ar N +seconds for the device to appear before trying to mount it. +If +.Ic .timeout +is not specified, the default timeout is 3 seconds. +.El +.Sh EXAMPLES +The following example +.Pa .mount.conf +will direct the kernel to try mounting the root file system +first as an ISO CD9660 file system on +.Pa /dev/cd0 , +then if that does not work, as an ISO CD9660 file system on +.Pa /dev/cd1 , +and then if that does not work, as a UFS file system on +.Pa /dev/ada0s1a . +If that does not work, a +.Li mountroot> +command-line prompt will be displayed where the operator +can manually enter the root file system to mount. +Finally if that does not work, the kernel will panic. +.Bd -literal -offset indent +.Li .onfail panic +.Li .timeout 3 +cd9660:/dev/cd0 ro +.Li .timeout 0 +cd9660:/dev/cd1 ro +.Li .timeout 3 +ufs:/dev/ada0s1a +.Li .ask +.Ed +.Pp +The following example +.Pa .mount.conf +will direct the kernel to create a +.Xr md 4 +memory disk attached to the file +.Pa /data/OS-1.0.iso +and then mount the ISO CD9660 file system +on the md device which was just created. +The last line is a comment which is ignored. +.Bd -literal -offset indent +.Li .timeout 3 +.Li .md /data/OS-1.0.iso +.Li cd9600:/dev/md# ro +.Li # Can also use cd9660:/dev/md0 ro +.Ed +.Pp +The following example +.Pa .mount.conf +will direct the kernel to create a +.Xr md 4 +memory disk attached to the file +.Pa /data/base.ufs.uzip +and then mount the UFS file system +on the md uzip device which was just created +by the +.Xr geom_uzip 4 +driver. +.Bd -literal -offset indent +.Li .md /data/base.ufs.uzip +.Li ufs:/dev/md#.uzip ro +.Li # Can also use ufs:/dev/md0.uzip ro +.Ed +.Pp +The following example +.Pa .mount.conf +will direct the kernel to do a unionfs +mount on a directory +.Pa /jail/freebsd-8-stable +which has a +.Xr chroot 2 +environment. +.Bd -literal -offset indent +.Li .timeout 3 +.Li unionfs:/jail/freebsd-8-stable +.Ed +.Sh NOTES +For each root file system which is mounted, a +.Pa /dev +directory +.Em must +exist so that the root mount logic can properly re-mount +.Xr devfs 4 . +If this directory does not exist, the system +may hang during the bootup process. +.Sh SEE ALSO +.Xr nmount 2 , +.Xr md 4 , +.Xr boot.config 5 , +.Xr fstab 5 , +.Xr boot 8 , +.Xr loader 8 , +.Xr mount 8 +.Sh HISTORY +The +.Nm +file first appeared in +.Fx 9.0 . +.Sh AUTHORS +.An -nosplit +The root mount logic in the +.Fx +kernel which parses +.Pa /.mount.conf +was written by +.An Marcel Moolenaar Aq Mt marcel@FreeBSD.org . +This man page was written by +.An Craig Rodrigues Aq Mt rodrigc@FreeBSD.org . diff --git a/static/freebsd/man5/networks.5 b/static/freebsd/man5/networks.5 new file mode 100644 index 00000000..f0fdf233 --- /dev/null +++ b/static/freebsd/man5/networks.5 @@ -0,0 +1,82 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 June 5, 1993 +.Dt NETWORKS 5 +.Os +.Sh NAME +.Nm networks +.Nd network name data base +.Sh DESCRIPTION +The +.Nm +file contains information regarding +the known networks which comprise the +.Tn DARPA +Internet. +For each network a single line should be present with the following information: +.Bd -unfilled -offset indent +official network name +network number +aliases +.Ed +.Pp +Items are separated by any number of blanks and/or tab characters. +A ``#'' indicates the beginning of a comment; characters up to the end of +the line are not interpreted by routines which search the file. +This file is normally created from the official network data base +maintained at the Network Information Control Center +.Pq Tn NIC , +though local +changes may be required to bring it up to date regarding unofficial aliases +and/or unknown networks. +.Pp +Network numbers may be specified in the conventional +``.'' (dot) notation using the +.Xr inet_network 3 +routine +from the Internet address manipulation library, +.Xr inet 3 . +Network names may contain any printable character other than a field +delimiter, newline, or comment character. +.Sh FILES +.Bl -tag -width /etc/networks -compact +.It Pa /etc/networks +The +.Nm +file resides in +.Pa /etc . +.El +.Sh SEE ALSO +.Xr getnetent 3 +.Sh HISTORY +The +.Nm +file format appeared in +.Bx 4.2 . +.Sh BUGS +A name server should be used instead of a static file. diff --git a/static/freebsd/man5/nsmb.conf.5 b/static/freebsd/man5/nsmb.conf.5 new file mode 100644 index 00000000..0da10343 --- /dev/null +++ b/static/freebsd/man5/nsmb.conf.5 @@ -0,0 +1,166 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2003 +.\" Originally written by Sergey A. Osokin +.\" Rewritten by Tom Rhodes +.\" +.\" 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 ``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 November 2, 2018 +.Dt NSMB.CONF 5 +.Os +.Sh NAME +.Nm nsmb.conf +.Nd configuration file for server message block (SMB1/CIFS) requests +.Sh DESCRIPTION +The +.Nm +file contains information about the computers, users, and shares +or mount points for the +.Tn SMB +network protocol. +.Pp +The configuration files are loaded in the following order: +.Pp +.Bl -enum -offset indent -width "" -compact +.It +.Pa ~/.nsmbrc +.It +.Pa /etc/nsmb.conf +.El +.Pp +As a result, +.Pa /etc/nsmb.conf +settings +override those in +.Pa ~/.nsmbrc . +.Pp +The configuration hierarchy is made up of several sections, +each section containing a few or several lines of parameters +and their assigned values. +Each of these sections must begin with a section name enclosed within +square brackets, similar to: +.Pp +.D1 Bq Ar section_name +.Pp +The end of each section is marked by either the start of a new section, +or by the abrupt ending of the file, commonly referred to as the +.Tn EOF . +Each section may contain zero or more parameters such as: +.Pp +.D1 Bq Ar section_name +.D1 Ar key Ns = Ns Ar value +.Pp +where +.Ar key +represents a parameter name, and +.Ar value +would be the parameter's assigned value. +.Pp +The +.Tn SMB +library uses the following information for section names: +.Pp +.Bl -tag -width indent -compact +.It Ic A) +.Bq Li default +.It Ic B) +.Bq Ar SERVER +.It Ic C) +.Bq Ar SERVER : Ns Ar USER +.It Ic D) +.Op Ar SERVER : Ns Ar USER : Ns Ar SHARE +.El +.Pp +Possible keywords may include: +.Bl -column ".Va retry_count" ".Sy Section" +.It Sy "Keyword Section Comment" +.It Sy " A B C D" +.It Va addr Ta "- + - -" Ta "IP address of SMB server" +.It Va charsets Ta "- + + +" Ta "local:remote charset pair" +.It Va nbns Ta "+ + - -" Ta "address of NetBIOS name server (WINS)" +.It Va nbscope Ta "+ + - -" Ta "NetBIOS scope" +.It Va nbtimeout Ta "+ + - -" Ta "timeout for NetBIOS name servers" +.It Va password Ta "- - + +" Ta "plain text or simple encrypted password used to access the given share" +.It Va retry_count Ta "+ + - -" Ta "number of retries before connection is marked as broken" +.It Va timeout Ta "+ + - -" Ta "SMB request timeout" +.It Va workgroup Ta "+ + + +" Ta "workgroup name" +.El +.Sh FILES +.Bl -tag -width ".Pa /etc/nsmb.conf" +.It Pa /etc/nsmb.conf +The default remote mount-point configuration file. +.It Pa ~/.nsmbrc +The user specific remote mount-point configuration file. +.El +.Sh EXAMPLES +What follows is a sample configuration file which may, +or may not match your environment: +.Bd -literal -offset indent +# Configuration file for example.com +[default] +workgroup=SALES +# The 'FSERVER' is an NT server. +[FSERVER] +charsets=koi8-r:cp866 +addr=fserv.example.com +# User specific data for FSERVER +[FSERVER:MYUSER] +password=$$16144562c293a0314e6e1 +.Ed +.Pp +All lines which begin with the +.Ql # +character are comments and will not be parsed. +The +.Dq Li default +section describes the default workgroup or domain, in this case +.Dq Li SALES . +The next section depicted here as +.Dq Li FSERVER , +defines a server section and then assigns it a charset which is only +required when Cyrillic characters are not used. +The hostname value, +.Dq Li fserv.example.com , +is also assigned in this section. +.Dq Li FSERVER:USER , +defines the user settings and is useful for saving the password used +during a specific connection. +The password may be plaintext or obfuscated using simple encryption. +The simple encrypted password starts with the `$$1' symbols. +Warning: the encryption function is very weak and intended only to hide +clear text passwords. +If the use of simple encryption is desired, the following command may be +used on a password: +.Bd -literal -offset indent +smbutil crypt +.Ed +.Sh SEE ALSO +.Xr smbutil 1 , +.Xr mount_smbfs 8 +.Sh AUTHORS +This manual page was written by +.An -nosplit +.An Sergey Osokin Aq Mt osa@FreeBSD.org +and +.An Tom Rhodes Aq Mt trhodes@FreeBSD.org . diff --git a/static/freebsd/man5/nsswitch.conf.5 b/static/freebsd/man5/nsswitch.conf.5 new file mode 100644 index 00000000..3e033161 --- /dev/null +++ b/static/freebsd/man5/nsswitch.conf.5 @@ -0,0 +1,386 @@ +.\" $NetBSD: nsswitch.conf.5,v 1.14 1999/03/17 20:19:47 garbled Exp $ +.\" +.\" Copyright (c) 1997, 1998, 1999 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Luke Mewburn. +.\" +.\" 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 Luke Mewburn. +.\" 4. 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 September 6, 2020 +.Dt NSSWITCH.CONF 5 +.Os +.Sh NAME +.Nm nsswitch.conf +.Nd name-service switch configuration file +.Sh DESCRIPTION +The +.Nm +file specifies how the +.Xr nsdispatch 3 +(name-service switch dispatcher) routines in the C library should operate. +.Pp +The configuration file controls how a process looks up various databases +containing information regarding hosts, users (passwords), groups, etc. +Each database comes from a source (such as local files, DNS, NIS , +and cache), and the order to look up the sources is specified in +.Nm . +.Pp +Each entry in +.Nm +consists of a database name, and a space separated list of sources. +Each source can have an optional trailing criterion that determines +whether the next listed source is used, or the search terminates at +the current source. +Each criterion consists of one or more status codes, and actions to +take if that status code occurs. +.Ss Sources +The following sources are implemented as part of the base system: +.Pp +.Bl -tag -width Source -compact +.It Sy Source +.Sy Description +.It files +Local files, such as +.Pa /etc/hosts , +and +.Pa /etc/passwd . +.It db +Local database. +.It dns +Internet Domain Name System. +.Dq hosts +and +.Sq networks +use +.Sy IN +class entries, all other databases use +.Sy HS +class (Hesiod) entries. +.It nis +NIS (formerly YP) +.It compat +support +.Sq +/- +in the +.Dq passwd +and +.Dq group +databases. +If this is present, it must be the only source for that entry. +.It cache +makes use of the +.Xr nscd 8 +daemon. +.El +.Pp +Additional sources might be provided by third party software. +.Ss Databases +The following databases are used by the following C library functions: +.Pp +.Bl -tag -width networks -compact +.It Sy Database +.Sy "Used by" +.It group +.Xr getgrent 3 , +.Xr getgrent_r 3 , +.Xr getgrgid_r 3 , +.Xr getgrnam_r 3 , +.Xr setgrent 3 , +.Xr endgrent 3 +.It hosts +.Xr getaddrinfo 3 , +.Xr gethostbyaddr 3 , +.Xr gethostbyaddr_r 3 , +.Xr gethostbyname 3 , +.Xr gethostbyname2 3 , +.Xr gethostbyname_r 3 , +.Xr getipnodebyaddr 3 , +.Xr getipnodebyname 3 +.It networks +.Xr getnetbyaddr 3 , +.Xr getnetbyaddr_r 3 , +.Xr getnetbyname 3 , +.Xr getnetbyname_r 3 +.It passwd +.Xr getpwent 3 , +.Xr getpwent_r 3 , +.Xr getpwnam_r 3 , +.Xr getpwuid_r 3 , +.Xr setpwent 3 , +.Xr endpwent 3 +.It shells +.Xr getusershell 3 +.It services +.Xr getservent 3 +.It rpc +.Xr getrpcbyname 3 , +.Xr getrpcbynumber 3 , +.Xr getrpcent 3 +.It proto +.Xr getprotobyname 3 , +.Xr getprotobynumber 3 , +.Xr getprotoent 3 +.It netgroup +.Xr getnetgrent 3 , +.Xr getnetgrent_r 3 , +.Xr setnetgrent 3 , +.Xr endnetgrent 3 , +.Xr innetgr 3 +.El +.Ss Status codes +The following status codes are available: +.Pp +.Bl -tag -width tryagain -compact +.It Sy Status +.Sy Description +.It success +The requested entry was found. +.It notfound +The entry is not present at this source. +.It tryagain +The source is busy, and may respond to retries. +.It unavail +The source is not responding, or entry is corrupt. +.El +.Ss Actions +For each of the status codes, one of two actions is possible: +.Pp +.Bl -tag -width continue -compact +.It Sy Action +.Sy Description +.It continue +Try the next source +.It return +Return with the current result +.El +.Ss Format of file +A BNF description of the syntax of +.Nm +is: +.Pp +.Bl -tag -width -compact +.It +::= + ":" [ []]* +.It +::= +"[" + "]" +.It +::= + "=" +.It +::= +"success" | "notfound" | "unavail" | "tryagain" +.It +::= +"return" | "continue" +.El +.Pp +Each entry starts on a new line in the file. +A +.Sq # +delimits a comment to end of line. +Blank lines are ignored. +A +.Sq \e +at the end of a line escapes the newline, and causes the next line to +be a continuation of the current line. +All entries are case-insensitive. +.Pp +The default criteria is to return on +.Dq success , +and continue on anything else (i.e, +.Li "[success=return notfound=continue unavail=continue tryagain=continue]" ) . +.Ss Cache +You can enable caching for the particular database by specifying +.Dq cache +in the +.Nm +file. +It should come after +.Dq files , +but before remote sources like +.Dq nis . +You should also enable caching for this database in +.Xr nscd.conf 5 . +If for a particular query +.Dq cache +source returns success, then no further sources are queried. +On the other hand, if there are no previously cached data, the +query result will be placed into the cache right after +all other sources are processed. +Note that +.Dq cache +requires the +.Xr nscd 8 +daemon to be running. +.Ss Compat mode: +/- syntax +In historical multi-source implementations, the +.Sq + +and +.Sq - +characters are used to specify the importing of user password and +group information from NIS . +Although +.Nm +provides alternative methods of accessing distributed sources such as NIS , +specifying a sole source of +.Dq compat +will provide the historical behaviour. +.Pp +An alternative source for the information accessed via +.Sq +/- +can be used by specifying +.Dq passwd_compat: source . +.Dq source +in this case can be +.Sq dns , +.Sq nis , +or +any other source except for +.Sq files +and +.Sq compat . +.Ss Notes +Historically, many of the databases had enumeration functions, often of +the form +.Fn getXXXent . +These made sense when the databases were in local files, but do not make +sense or have lesser relevance when there are possibly multiple sources, +each of an unknown size. +The interfaces are still provided for compatibility, but the source +may not be able to provide complete entries, or duplicate entries may +be retrieved if multiple sources that contain similar information are +specified. +.Pp +To ensure compatibility with previous and current implementations, the +.Dq compat +source must appear alone for a given database. +.Ss Default source lists +If, for any reason, +.Nm +does not exist, or it has missing or corrupt entries, +.Xr nsdispatch 3 +will default to an entry of +.Dq files +for the requested database. +Exceptions are: +.Pp +.Bl -tag -width services_compat -compact +.It Sy Database +.Sy "Default source list" +.It group +compat +.It group_compat +nis +.It hosts +files dns +.It passwd +compat +.It passwd_compat +nis +.It services +compat +.It services_compat +nis +.El +.Sh FILES +.Bl -tag -width /etc/nsswitch.conf -compact +.It Pa /etc/nsswitch.conf +The file +.Nm +resides in +.Pa /etc . +.El +.Sh EXAMPLES +To lookup hosts in +.Pa /etc/hosts +, then in cache, +and then from the DNS, and lookup user information from NIS then files, use: +.Pp +.Bl -tag -width passwd: -compact +.It hosts: +files cache dns +.It passwd: +nis [notfound=return] files +.It group: +nis [notfound=return] files +.El +.Pp +The criteria +.Dq [notfound=return] +sets a policy of "if the user is notfound in nis, do not try files." +This treats nis as the authoritative source of information, except +when the server is down. +.Sh NOTES +The +.Nm +file is parsed by each program only once. +Subsequent changes will not be applied until the program +is restarted. +.Pp +If system got compiled with +.Va WITHOUT_NIS +you have to remove +.Sq nis +entries. +.Pp +.Fx Ns 's +.Lb libc +provides stubs for compatibility with NSS modules +written for the GNU C Library +.Nm nsswitch +interface. +However, these stubs only support the use of the +.Dq Li passwd +and +.Dq Li group +databases. +.Sh SEE ALSO +.Xr nsdispatch 3 , +.Xr nscd.conf 5 , +.Xr resolv.conf 5 , +.Xr nscd 8 , +.Xr ypbind 8 +.Sh HISTORY +The +.Nm +file format first appeared in +.Fx 5.0 . +It was imported from the +.Nx +Project, where it appeared first in +.Nx 1.4 . +.Sh AUTHORS +.An Luke Mewburn Aq Mt lukem@netbsd.org +wrote this freely distributable name-service switch implementation, +using ideas from the ULTRIX +.Xr svc.conf 5 +and Solaris +.Xr nsswitch.conf 4 +manual pages. diff --git a/static/freebsd/man5/os-release.5 b/static/freebsd/man5/os-release.5 new file mode 100644 index 00000000..c2874a65 --- /dev/null +++ b/static/freebsd/man5/os-release.5 @@ -0,0 +1,131 @@ +.\" +.\" 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 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 November 23, 2021 +.Dt OS-RELEASE 5 +.Os +.Sh NAME +.Nm os-release +.Nd file describing the current OS and some of its attributes +.Sh DESCRIPTION +The +.Nm +file is a new-line separated list of key value pairs. +The syntax of this file is a reduced +.Xr sh 1 +variable assignment with the +following restrictions: +.Bl -bullet +.It +Strings cannot be concatenated together +.It +No variable expansion is done +.It +All shell special characters must be quoted as documented in +.Xr sh 1 +.It +Variable assignments must be included inside of double quotes +if they contain characters outside of A-Z, a-z and 0-9 +.It +All strings should be UTF-8 format +.It +Non-printable characters should not be used in the strings +.El +.Pp +Lines starting with the character +.Ql # +are ignored as comments. +.Sh VARIABLES +The following variables are defined by the standard. +.Bl -tag -width XXXXXXXXXX -compact +.It Dv NAME +A string describing the preferred OS name. +.It Dv VERSION +Version string for the OS, in its usual and customary format. +.It Dv ID +Lower case version of the name with only a-z, 0-9, +.Ql \&. , +.Ql - , +and +.Ql _ . +.It Dv VERSION_ID +Lower case version of the version with only a-z, 0-9, +.Ql \&. , +.Ql - , +and +.Ql _ . +.It Dv PRETTY_NAME +A pretty version of the name presented to the user. +May contain release information. +.It Dv ANSI_COLOR +Suggested color presentation for the OS. +This string should be suitable for inclusion within an ESC [ m ANSI/ECMA-48 +escape sequence to render the OS in its preferred color. +This variable is optional. +.It Dv CPE_NAME +A CPE name for the operating system. +This field shall follow the NIST Common Platform Enumeration specification. +.It Dv HOME_URL +.It Dv SUPPORT_URL +.It Dv BUG_REPORT_URL +.It Dv PRIVACY_POLICY_URL +Links on the internet, in RFC 3986 format for different aspects of this OS. +These variables are optional. +.It Dv BUILD_ID +A string identifying the build. +This variable is optional. +.It Dv VARIANT +A string describing the variant of this operating system. +This variable is optional. +.It Dv VARIANT_ID +Lower case version of the variant with only a-z, 0-9, +.Ql \&. , +.Ql - , +and +.Ql _ . +This variable is optional. +.El +.Pp +All other variables have no standard-defined meaning. +.Sh FILES +.Bl -tag -width XXXXXXXXXX -compact +.It Pa /etc/os-release +Symbolic link to actual +.Pa os-release +file. +.It Pa /var/run/os-release +Generated os-release file describing the currently running system. +.El +.Sh SEE ALSO +.Bl -tag -width XXXXXXXXXX -compact +.It CPE Specification +.Lk https://csrc.nist.gov/projects/security-content-automation-protocol/scap-specifications/cpe +.It RFC 3986 +.Lk https://tools.ietf.org/html/rfc3986 +.It os-release Specification +.Lk https://www.linux.org/docs/man5/os-release.html +.El +.Sh HISTORY +This file first appeared in +.Fx 13.0 . diff --git a/static/freebsd/man5/passwd.5 b/static/freebsd/man5/passwd.5 new file mode 100644 index 00000000..b1d9e362 --- /dev/null +++ b/static/freebsd/man5/passwd.5 @@ -0,0 +1,460 @@ +.\" $NetBSD: passwd.5,v 1.12.2.2 1999/12/17 23:14:50 he Exp $ +.\" +.\" Copyright (c) 1988, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" Portions Copyright (c) 1994, Jason Downs. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 May 16, 2023 +.Dt PASSWD 5 +.Os +.Sh NAME +.Nm passwd , +.Nm master.passwd , +.Nm pwd.db , +.Nm spwd.db +.Nd format of the password file +.Sh DESCRIPTION +The +.Nm +files are the local source of password information. +They can be used in conjunction with the Hesiod domains +.Sq Li passwd +and +.Sq Li uid , +and the +NIS +maps +.Sq Li passwd.byname , +.Sq Li passwd.byuid , +.Sq Li master.passwd.byname , +and +.Sq Li master.passwd.byuid , +as controlled by +.Xr nsswitch.conf 5 . +.Pp +For consistency, none of these files should ever be modified +manually. +.Pp +The +.Nm master.passwd +file is readable only by root, and consists of newline separated +records, one per user, containing ten colon +.Pq Ql \&: +separated +fields. +These fields are as follows: +.Bl -tag -width ".Ar password" -offset indent +.It Ar name +User's login name. +.It Ar password +User's +.Em encrypted +password. +.It Ar uid +User's id. +.It Ar gid +User's login group id. +.It Ar class +User's login class. +.It Ar change +Password change time. +.It Ar expire +Account expiration time. +.It Ar gecos +General information about the user. +.It Ar home_dir +User's home directory. +.It Ar shell +User's login shell. +.El +.Pp +The +.Nm +file is generated from the +.Nm master.passwd +file by +.Xr pwd_mkdb 8 , +has the +.Ar class , +.Ar change , +and +.Ar expire +fields removed, and the +.Ar password +field replaced by a +.Ql * +character. +.Pp +The +.Ar name +field is the login used to access the computer account, and the +.Ar uid +field is the number associated with it. +They should both be unique +across the system (and often across a group of systems) since they +control file access. +.Pp +While it is possible to have multiple entries with identical login names +and/or identical user id's, it is usually a mistake to do so. +Routines +that manipulate these files will often return only one of the multiple +entries, and that one by random selection. +.Pp +The login name must not begin with a hyphen +.Pq Ql \&- , +and cannot contain 8-bit characters, tabs or spaces, or any of these +symbols: +.Ql \&,:+&#%^\&(\&)!@~*?<>=|\e\\&/"\&; . +The dollar symbol +.Pq Ql \&$ +is allowed only as the last character for use with Samba. +No field may contain a +colon +.Pq Ql \&: +as this has been used historically to separate the fields +in the user database. +.Pp +Case is significant. +Login names +.Ql Lrrr +and +.Ql lrrr +represent different users. +Be aware of this when interoperating with systems that do not have +case-sensitive login names. +.Pp +In the +.Nm master.passwd +file, +the +.Ar password +field is the +.Em encrypted +form of the password, see +.Xr crypt 3 . +If the +.Ar password +field is empty, no password will be required to gain access to the +machine. +This is almost invariably a mistake, so authentication components +such as PAM can forcibly disallow remote access to passwordless accounts. +Because this file contains the encrypted user passwords, it should +not be readable by anyone without appropriate privileges. +.Pp +A password of +.Ql * +indicates that +password authentication is disabled for that account +(logins through other forms of +authentication, e.g., using +.Xr ssh 1 +keys, will still work). +The field only contains encrypted passwords, and +.Ql * +can never be the result of encrypting a password. +.Pp +An encrypted password prefixed by +.Ql *LOCKED* +means that the account is temporarily locked out +and no one can log into it using any authentication. +For a convenient command-line interface to account locking, see +.Xr pw 8 . +.Pp +The +.Ar group +field is the group that the user will be placed in upon login. +Since this system supports multiple groups (see +.Xr groups 1 ) +this field currently has little special meaning. +.Pp +The +.Ar class +field is a key for a user's login class. +Login classes +are defined in +.Xr login.conf 5 , +which is a +.Xr termcap 5 +style database of user attributes, accounting, resource, +and environment settings. +.Pp +The +.Ar change +field is the number of seconds from the epoch, +.Dv UTC , +until the +password for the account must be changed. +This field may be left empty to turn off the password aging feature; +a value of zero is equivalent to leaving the field empty. +.Pp +The +.Ar expire +field is the number of seconds from the epoch, +.Dv UTC , +until the +account expires. +This field may be left empty to turn off the account aging feature; +a value of zero is equivalent to leaving the field empty. +.Pp +The +.Ar gecos +field normally contains comma +.Pq Ql \&, +separated subfields as follows: +.Pp +.Bl -tag -width ".Ar office" -offset indent -compact +.It Ar name +user's full name +.It Ar office +user's office number +.It Ar wphone +user's work phone number +.It Ar hphone +user's home phone number +.El +.Pp +The full +.Ar name +may contain an ampersand +.Pq Ql & +which will be replaced by +the capitalized login +.Ar name +when the +.Ar gecos +field is displayed or used +by various programs such as +.Xr finger 1 , +.Xr sendmail 8 , +etc. +.Pp +The +.Ar office +and phone number subfields are used by the +.Xr finger 1 +program, and possibly other applications. +.Pp +The user's home directory, +.Ar home_dir , +is the full +.Ux +path name where the user +will be placed on login. +.Pp +The +.Ar shell +field is the command interpreter the user prefers. +If there is nothing in the +.Ar shell +field, the Bourne shell +.Pq Pa /bin/sh +is assumed. +The conventional way to disable logging into an account once and for all, +as it is done for system accounts, +is to set its +.Ar shell +to +.Pa /sbin/nologin +.Pq see Xr nologin 8 . +.Sh HESIOD SUPPORT +If +.Sq Li dns +is specified for the +.Sq Li passwd +database in +.Xr nsswitch.conf 5 , +then +.Nm +lookups occur from the +.Sq Li passwd +Hesiod domain. +.Sh NIS SUPPORT +If +.Sq Li nis +is specified for the +.Sq Li passwd +database in +.Xr nsswitch.conf 5 , +then +.Nm +lookups occur from the +.Sq Li passwd.byname , +.Sq Li passwd.byuid , +.Sq Li master.passwd.byname , +and +.Sq Li master.passwd.byuid +NIS +maps. +.Sh COMPAT SUPPORT +If +.Sq Li compat +is specified for the +.Sq Li passwd +database, and either +.Sq Li dns +or +.Sq Li nis +is specified for the +.Sq Li passwd_compat +database in +.Xr nsswitch.conf 5 , +then the +.Nm +file also supports standard +.Sq Li + Ns / Ns Li - +exclusions and inclusions, based on user names and netgroups. +.Pp +Lines beginning with a +.Ql - +(minus sign) are entries marked as being excluded +from any following inclusions, which are marked with a +.Ql + +(plus sign). +.Pp +If the second character of the line is a +.Ql @ +(at sign), the operation +involves the user fields of all entries in the netgroup specified by the +remaining characters of the +.Ar name +field. +Otherwise, the remainder of the +.Ar name +field is assumed to be a specific user name. +.Pp +The +.Ql + +token may also be alone in the +.Ar name +field, which causes all users from either the Hesiod domain +.Nm +(with +.Sq Li passwd_compat: dns ) +or +.Sq Li passwd.byname +and +.Sq Li passwd.byuid +NIS +maps (with +.Sq Li passwd_compat: nis ) +to be included. +.Pp +If the entry contains non-empty +.Ar uid +or +.Ar gid +fields, the specified numbers will override the information retrieved +from the Hesiod domain or the +NIS +maps. +Likewise, if the +.Ar gecos , +.Ar dir +or +.Ar shell +entries contain text, it will override the information included via +Hesiod or +NIS . +On some systems, the +.Ar passwd +field may also be overridden. +.Sh FILES +.Bl -tag -width ".Pa /etc/master.passwd" -compact +.It Pa /etc/passwd +ASCII +password file, with passwords removed +.It Pa /etc/pwd.db +.Xr db 3 Ns -format +password database, with passwords removed +.It Pa /etc/master.passwd +ASCII +password file, with passwords intact +.It Pa /etc/spwd.db +.Xr db 3 Ns -format +password database, with passwords intact +.El +.Sh COMPATIBILITY +The password file format has changed since +.Bx 4.3 . +The following awk script can be used to convert your old-style password +file into a new style password file. +The additional fields +.Ar class , +.Ar change +and +.Ar expire +are added, but are turned off by default +.Pq setting these fields to zero is equivalent to leaving them blank . +Class is currently not implemented, but change and expire are; to set them, +use the current day in seconds from the epoch + whatever number of seconds +of offset you want. +.Bd -literal -offset indent +BEGIN { FS = ":"} +{ print $1 ":" $2 ":" $3 ":" $4 "::0:0:" $5 ":" $6 ":" $7 } +.Ed +.Sh SEE ALSO +.Xr chpass 1 , +.Xr login 1 , +.Xr passwd 1 , +.Xr crypt 3 , +.Xr getpwent 3 , +.Xr login.conf 5 , +.Xr netgroup 5 , +.Xr nsswitch.conf 5 , +.Xr adduser 8 , +.Xr nologin 8 , +.Xr pw 8 , +.Xr pwd_mkdb 8 , +.Xr vipw 8 , +.Xr yp 8 +.Pp +.%T "Managing NFS and NIS" +(O'Reilly & Associates) +.Sh HISTORY +A +.Nm +file format first appeared in +.At v1 . +.Pp +The +NIS +.Nm +file format first appeared in SunOS. +.Pp +The Hesiod support first appeared in +.Fx 4.1 . +It was imported from the +.Nx +Project, where it first appeared in +.Nx 1.4 . +.Sh BUGS +User information should (and eventually will) be stored elsewhere. +.Pp +Placing +.Sq Li compat +exclusions in the file after any inclusions will have +unexpected results. diff --git a/static/freebsd/man5/pbm.5 b/static/freebsd/man5/pbm.5 new file mode 100644 index 00000000..d70255c8 --- /dev/null +++ b/static/freebsd/man5/pbm.5 @@ -0,0 +1,86 @@ +.\" +.Dd September 27, 1991 +.Dt PBM 5 +.Os +.Sh NAME +.Nm pbm +.Nd portable bitmap file format +.Sh DESCRIPTION +The portable bitmap format is a lowest common denominator monochrome +file format. +It was originally designed to make it reasonable to mail bitmaps +between different types of machines using the typical stupid network +mailers we have today. +Now it serves as the common language of a large family of bitmap +conversion filters. +The definition is as follows: +.Pp +.Bl -bullet -compact +.It +A "magic number" for identifying the file type. +A pbm file's magic number is the two characters "P1". +.It +Whitespace (blanks, TABs, CRs, LFs). +.It +A width, formatted as ASCII characters in decimal. +.It +Whitespace. +.It +A height, again in ASCII decimal. +.It +Whitespace. +.It +Width * height bits, each either '1' or '0', starting at the top-left +corner of the bitmap, proceeding in normal English reading order. +.It +The character '1' means black, '0' means white. +.It +Whitespace in the bits section is ignored. +.It +Characters from a "#" to the next end-of-line are ignored (comments). +.It +No line should be longer than 70 characters. +.El +.Pp +Here is an example of a small bitmap in this format: +.Bd -literal +P1 +# feep.pbm +24 7 +0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 +0 1 1 1 1 0 0 1 1 1 1 0 0 1 1 1 1 0 0 1 1 1 1 0 +0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 1 0 +0 1 1 1 0 0 0 1 1 1 0 0 0 1 1 1 0 0 0 1 1 1 1 0 +0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 0 1 0 0 0 0 +0 1 0 0 0 0 0 1 1 1 1 0 0 1 1 1 1 0 0 1 0 0 0 0 +0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 +.Ed +.Pp +Programs that read this format should be as lenient as possible, +accepting anything that looks remotely like a bitmap. +.Pp +There is also a variant on the format, available +by setting the RAWBITS option at compile time. +This variant is +different in the following ways: +.Pp +.Bl -bullet -compact +.It +The "magic number" is "P4" instead of "P1". +.It +The bits are stored eight per byte, high bit first low bit last. +.It +No whitespace is allowed in the bits section, and only a single character +of whitespace (typically a newline) is allowed after the height. +.It +The files are eight times smaller and many times faster to read and write. +.El +.Sh AUTHORS +Copyright (C) 1989, 1991 by +.An Jef Poskanzer . +.\" Permission to use, copy, modify, and distribute this software and its +.\" documentation for any purpose and without fee is hereby granted, provided +.\" that the above copyright notice appear in all copies and that both that +.\" copyright notice and this permission notice appear in supporting +.\" documentation. This software is provided "as is" without express or +.\" implied warranty. diff --git a/static/freebsd/man5/periodic.conf.5 b/static/freebsd/man5/periodic.conf.5 new file mode 100644 index 00000000..8910895d --- /dev/null +++ b/static/freebsd/man5/periodic.conf.5 @@ -0,0 +1,1095 @@ +.\"- +.\" Copyright (c) 2000 Brian Somers +.\" 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 April 9, 2024 +.Dt PERIODIC.CONF 5 +.Os +.Sh NAME +.Nm periodic.conf +.Nd periodic job configuration information +.Sh DESCRIPTION +The file +.Nm +contains a description of how daily, weekly and monthly system maintenance +jobs should run. +It resides in the +.Pa /etc/defaults +directory and parts may be overridden by a file of the same name in +.Pa /etc , +which itself may be overridden by the +.Pa /etc/periodic.conf.local +file. +.Pp +The +.Nm +file +is actually sourced as a shell script from each of the periodic scripts +and is intended to simply provide default configuration variables. +.Pp +The following variables are used by +.Xr periodic 8 +itself: +.Bl -tag -offset 4n -width 2n +.It Va local_periodic +.Pq Vt str +List of directories to search for periodic scripts. +This list is always prefixed with +.Pa /etc/periodic , +and is only used when an argument to +.Xr periodic 8 +is not an absolute directory name. +.It Ao Ar dir Ac Ns Va _output +.Pq Vt path No or Vt list +What to do with the output of the scripts executed from +the directory +.Ar dir . +If this variable is set to an absolute path name, output is logged to +that file, otherwise it is taken as one or more space separated email +addresses and mailed to those users. +If this variable is not set or is empty, output is sent to standard output. +.Pp +For an unattended machine, suitable values for +.Va daily_output , +.Va weekly_output , +and +.Va monthly_output +might be +.Dq Li /var/log/daily.log , +.Dq Li /var/log/weekly.log , +and +.Dq Li /var/log/monthly.log +respectively, as +.Xr newsyslog 8 +will rotate these files (if they exists) at the appropriate times. +.It Ao Ar dir Ac Ns Va _show_success +.It Ao Ar dir Ac Ns Va _show_info +.It Ao Ar dir Ac Ns Va _show_badconfig +.Pq Vt bool +These variables control whether +.Xr periodic 8 +will mask the output of the executed scripts based on their return code +(where +.Ar dir +is the base directory name in which each script resides). +If the return code of a script is +.Sq 0 +and +.Ao Ar dir Ac Ns Va _show_success +is set to +.Dq Li NO , +.Xr periodic 8 +will mask the script's output. +If the return code of a script is +.Sq 1 +and +.Ao Ar dir Ac Ns Va _show_info +is set to +.Dq Li NO , +.Xr periodic 8 +will mask the script's output. +If the return code of a script is +.Sq 2 +and +.Ao Ar dir Ac Ns Va _show_badconfig +is set to +.Dq Li NO , +.Xr periodic 8 +will mask the script's output. +If these variables are set to neither +.Dq Li YES +nor +.Dq Li NO , +they default to +.Dq Li YES , +.Dq Li YES +and +.Dq Li NO +respectively. +.Pp +Refer to the +.Xr periodic 8 +manual page for how script return codes are interpreted. +.It Va anticongestion_sleeptime +.Pq Vt int +The maximum number of seconds to randomly sleep in order to smooth bursty loads +on a shared resource, such as a download mirror. +.El +.Pp +The following variables are used by the standard scripts that reside in +.Pa /etc/periodic/daily : +.Bl -tag -offset 4n -width 2n +.It Va daily_clean_disks_enable +.Pq Vt bool +Set to +.Dq Li YES +if you want to remove all files matching +.Va daily_clean_disks_files +daily. +.It Va daily_clean_disks_files +.Pq Vt str +Set to a list of file names to match. +Wild cards are permitted. +.It Va daily_clean_disks_days +.Pq Vt num +When +.Va daily_clean_disks_enable +is set to +.Dq Li YES , +this must also be set to the number of days old that a file's access +and modification times must be before it is deleted. +.It Va daily_clean_disks_verbose +.Pq Vt bool +Set to +.Dq Li YES +if you want the removed files to be reported in your daily output. +.It Va daily_clean_tmps_enable +.Pq Vt bool +Set to +.Dq Li YES +if you want to clear temporary directories daily. +.It Va daily_clean_tmps_dirs +.Pq Vt str +Set to the list of directories to clear if +.Va daily_clean_tmps_enable +is set to +.Dq Li YES . +.It Va daily_clean_tmps_days +.Pq Vt num +When +.Va daily_clean_tmps_enable +is set, this must also be set to the number of days old that a file's access +and modification times must be before it is deleted. +.It Va daily_clean_tmps_ignore +.Pq Vt str +Set to the list of files that should not be deleted when +.Va daily_clean_tmps_enable +is set to +.Dq Li YES . +Wild card characters are permitted. +.It Va daily_clean_tmps_verbose +.Pq Vt bool +Set to +.Dq Li YES +if you want the removed files to be reported in your daily output. +.It Va daily_clean_preserve_enable +.Pq Vt bool +Set to +.Dq Li YES +if you wish to remove old files from +.Pa /var/preserve . +.It Va daily_clean_preserve_days +.Pq Vt num +Set to the number of days that files must not have been modified before +they are deleted. +.It Va daily_clean_preserve_verbose +.Pq Vt bool +Set to +.Dq Li YES +if you want the removed files to be reported in your daily output. +.It Va daily_clean_msgs_enable +.Pq Vt bool +Set to +.Dq Li YES +if you wish old system messages to be purged. +.It Va daily_clean_msgs_days +.Pq Vt num +Set to the number of days that files must not have been modified before +they are deleted. +If this variable is left blank, the +.Xr msgs 1 +default is used. +.It Va daily_clean_rwho_enable +.Pq Vt bool +Set to +.Dq Li YES +if you wish old files in +.Pa /var/who +to be purged. +.It Va daily_clean_rwho_days +.Pq Vt num +Set to the number of days that files must not have been modified before +they are deleted. +.It Va daily_clean_rwho_verbose +.Pq Vt bool +Set to +.Dq Li YES +if you want the removed files to be reported in your daily output. +.It Va daily_clean_hoststat_enable +.Pq Vt bool +Set to +.Dq Li YES +to run +.Nm sendmail Fl bH +to automatically purge stale entries from +.Xr sendmail 8 Ns 's +host status cache. +Files will be deleted using the same criteria as +.Xr sendmail 8 +would normally use when determining whether to believe the cached information, +as configured in +.Pa /etc/mail/sendmail.cf . +.It Va daily_backup_efi_enable +.Pq Vt bool +Set to +.Dq Li YES +to create backup of EFI System Partition (ESP). +.It Va daily_backup_gmirror_enable +.Pq Vt bool +Set to +.Dq Li YES +to create backup of gmirror information (i.e., output of +.Nm gmirror Cm list ) , +see +.Xr gmirror 8 . +.It Va daily_backup_gmirror_verbose +.Pq Vt bool +Set to +.Dq Li YES +to report a diff between the new backup and the existing backup +in the daily output. +.It Va daily_backup_gpart_enable +.Pq Vt bool +Set to +.Dq Li YES +to create backups of partition tables, and bootcode partition contents. +.It Va daily_backup_gpart_verbose +.Pq Vt bool +Set to +.Dq Li YES +to be verbose if existing backups for kern.geom.conftxt or the partition tables differ +from the new backups. +.It Va daily_backup_passwd_enable +.Pq Vt bool +Set to +.Dq Li YES +if you want the +.Pa /etc/master.passwd +and +.Pa /etc/group +files backed up and reported on. +Reporting consists of checking both files for modifications and running +.Xr chkgrp 8 +on the +.Pa group +file. +.It Va daily_backup_aliases_enable +.Pq Vt bool +Set to +.Dq Li YES +if you want the +.Pa /etc/mail/aliases +file backed up and modifications to be displayed in your daily output. +.It Va daily_backup_zfs_enable +.Pq Vt bool +Set to +.Dq Li YES +to create backup of the output generated from the +.Xr zfs-list 8 +and +.Xr zpool-list 8 +utilities. +.It Va daily_backup_zfs_list_flags +.Pq Vt str +Set to the arguments for the +.Xr zfs-list 8 +utility. +The default is standard behavior. +.It Va daily_backup_zpool_list_flags +.Pq Vt str +Set to the arguments for the +.Xr zpool-list 8 +utility. +The default is +.Fl v . +.It Va daily_backup_zfs_props_enable +.Pq Vt bool +Set to +.Dq Li YES +to create backup of the output generated from the +.Xr zfs-get 8 +and +.Xr zpool-get 8 +utilities. +.It Va daily_backup_zfs_get_flags +.Pq Vt str +Set to the arguments for the +.Xr zfs-get 8 +utility. +The default is +.Cm all . +.It Va daily_backup_zpool_get_flags +.Pq Vt str +Set to the arguments for the +.Xr zpool-get 8 +utility. +The default is +.Cm all . +.It Va daily_backup_zfs_verbose +.Pq Vt bool +Set to +.Dq Li YES +to report a diff between the new backup and the existing backup +in the daily output. +.It Va daily_calendar_enable +.Pq Vt bool +Set to +.Dq Li YES +if you want to run +.Nm calendar Fl a +daily. +.It Va daily_accounting_enable +.Pq Vt bool +Set to +.Dq Li YES +if you want to rotate your daily process accounting files. +No rotations are necessary unless +.Va accounting_enable +is enabled in +.Xr rc.conf 5 . +.It Va daily_accounting_compress +.Pq Vt bool +Set to +.Dq Li YES +if you want your daily accounting files to be compressed using +.Xr gzip 1 . +.It Va daily_accounting_save +.Pq Vt num +When +.Va daily_accounting_enable +is set, this may also be set to the number of daily accounting files that are +to be saved. +The default is +.Dq Li 3 . +.It Va daily_accounting_flags +.Pq Vt str +Set to the arguments to pass to the +.Xr sa 8 +utility (in addition to +.Fl s ) +when +.Va daily_accounting_enable +is set to +.Dq Li YES . +The default is +.Fl q . +.It Va daily_status_disks_enable +.Pq Vt bool +Set to +.Dq Li YES +if you want to run +.Xr df 1 +(with the arguments supplied in +.Va daily_status_disks_df_flags ) +and +.Nm dump Fl W . +.It Va daily_status_disks_df_flags +.Pq Vt str +Set to the arguments for the +.Xr df 1 +utility when +.Va daily_status_disks_enable +is set to +.Dq Li YES . +The default is +.Fl l Fl h . +.It Va daily_status_zfs_enable +.Pq Vt bool +Set to +.Dq Li YES +if you want to run +.Nm zpool Cm status +on your +.Xr zfs 8 +pools. +.It Va daily_status_zfs_zpool_list_enable +.Pq Vt bool +Set to +.Dq Li YES +if you want to run +.Nm zpool Cm list +on your +.Xr zfs 8 +pools. +Requires +.Va daily_status_zfs_enable +to be set to +.Li YES . +.It Va daily_status_gmirror_enable +.Pq Vt bool +Set to +.Dq Li YES +if you want to run +.Nm gmirror Cm status +on your +.Xr gmirror 8 +devices. +.It Va daily_status_graid3_enable +.Pq Vt bool +Set to +.Dq Li YES +if you want to run +.Nm graid3 Cm status +on your +.Xr graid3 8 +devices. +.It Va daily_status_gstripe_enable +.Pq Vt bool +Set to +.Dq Li YES +if you want to run +.Nm gstripe Cm status +on your +.Xr gstripe 8 +devices. +.It Va daily_status_gconcat_enable +.Pq Vt bool +Set to +.Dq Li YES +if you want to run +.Nm gconcat Cm status +on your +.Xr gconcat 8 +devices. +.It Va daily_status_mfi_enable +.Pq Vt bool +Set to +.Dq Li YES +if you want to run +.Nm mfiutil Cm status +on your +.Xr mfi 4 +devices. +.It Va daily_status_network_enable +.Pq Vt bool +Set to +.Dq Li YES +if you want to run +.Nm netstat Fl i . +.It Va daily_status_network_netstat_flags +.Pq Vt str +Set to additional arguments for the +.Xr netstat 1 +utility when +.Va daily_status_network_enable +is set to +.Dq Li YES . +The default is +.Fl d W . +.It Va daily_status_network_usedns +.Pq Vt bool +Set to +.Dq Li YES +if you want to run +.Xr netstat 1 +without the +.Fl n +option (to do DNS lookups). +.It Va daily_status_uptime_enable +.Pq Vt bool +Set to +.Dq Li YES +if you want to run +.Xr uptime 1 +(or +.Xr ruptime 1 +if +.Va rwhod_enable +is set to +.Dq Li YES +in +.Pa /etc/rc.conf ) . +.It Va daily_status_mailq_enable +.Pq Vt bool +Set to +.Dq Li YES +if you want to run +.Xr mailq 1 . +.It Va daily_status_mailq_shorten +.Pq Vt bool +Set to +.Dq Li YES +if you want to shorten the +.Xr mailq 1 +output when +.Va daily_status_mailq_enable +is set to +.Dq Li YES . +.It Va daily_status_include_submit_mailq +.Pq Vt bool +Set to +.Dq Li YES +if you also want to run +.Xr mailq 1 +on the submit mail queue when +.Va daily_status_mailq_enable +is set to +.Dq Li YES . +This may not work with MTAs other than +.Xr sendmail 8 . +.It Va daily_status_security_enable +.Pq Vt bool +Set to +.Dq Li YES +if you want to run the security check. +The security check is another set of +.Xr periodic 8 +scripts. +The system defaults are in +.Pa /etc/periodic/security . +Local scripts should be placed in +.Pa /usr/local/etc/periodic/security . +See the +.Xr periodic 8 +manual page for more information. +.It Va daily_status_security_inline +.Pq Vt bool +Set to +.Dq Li YES +if you want the security check output inline. +The default is to either mail or log the output according to the value of +.Va daily_status_security_output . +.It Va daily_status_security_output +.Pq Vt str +Where to send the output of the security check if +.Va daily_status_security_inline +is set to +.Dq Li NO . +This variable behaves in the same way as the +.Va *_output +variables above, namely it can be set either to one or more email addresses +or to an absolute file name. +.It Va daily_status_mail_rejects_enable +.Pq Vt bool +Set to +.Dq Li YES +if you want to summarise mail rejections logged to +.Pa /var/log/maillog +for the previous day. +.It Va daily_status_mail_rejects_logs +.Pq Vt num +Set to the number of maillog files that should be checked +for yesterday's mail rejects. +.It Va daily_status_ntpd_enable +.Pq Vt bool +Set to +.Dq Li YES +if you want to enable NTP status check. +.It Va daily_status_world_kernel +.Pq Vt bool +Set to +.Dq Li YES +to check the running userland and kernel are in sync. +.It Va daily_queuerun_enable +.Pq Vt bool +Set to +.Dq Li YES +if you want to manually run the mail queue at least once a day. +.It Va daily_submit_queuerun +.Pq Vt bool +Set to +.Dq Li YES +if you also want to manually run the submit mail queue at least once a day +when +.Va daily_queuerun_enable +is set to +.Dq Li YES . +.It Va daily_scrub_zfs_enable +.Pq Vt bool +Set to +.Dq Li YES +if you want to run a zfs scrub periodically. +.It Va daily_scrub_zfs_pools +.Pq Vt str +A space separated list of names of zfs pools to scrub. +If the list is empty or not set, all zfs pools are scrubbed. +.It Va daily_scrub_zfs_default_threshold +.Pq Vt int +Number of days between a scrub if no pool-specific threshold is set. +If not set, the default value is 35, corresponding to 5 weeks. +.It Va daily_scrub_zfs_ Ns Ao Ar poolname Ac Ns Va _threshold +.Pq Vt int +The same as +.Va daily_scrub_zfs_default_threshold +but specific to the pool +.Ao Ar poolname Ac Ns . +.It Va daily_trim_zfs_enable +.Pq Vt bool +Set to +.Dq Li YES +if you want to run a zfs trim daily. +.It Va daily_trim_zfs_pools +.Pq Vt str +A space separated list of names of zfs pools to trim. +If the list is empty or not set, all zfs pools are trimmed. +.It Va daily_local +.Pq Vt str +Set to a list of extra scripts that should be run after all other +daily scripts. +All scripts must be absolute path names. +.It Va daily_diff_flags +.Pq Vt str +Set to the arguments to pass to the +.Xr diff 1 +utility when generating differences. +The default is +.Fl b +.Fl U Cm 0 . +.El +.Pp +The following variables are used by the standard scripts that reside in +.Pa /etc/periodic/weekly : +.Bl -tag -offset 4n -width 2n +.It Va weekly_locate_enable +.Pq Vt bool +Set to +.Dq Li YES +if you want to run +.Pa /usr/libexec/locate.updatedb . +This script is run using +.Nm nice Fl 5 +as user +.Dq Li nobody , +and generates the table used by the +.Xr locate 1 +command. +.It Va weekly_whatis_enable +.Pq Vt bool +Set to +.Dq Li YES +if you want to run +.Pa /usr/libexec/makewhatis.local . +This script regenerates the database used by the +.Xr apropos 1 +command. +.It Va weekly_noid_enable +.Pq Vt bool +Set to +.Dq Li YES +if you want to locate orphaned files on the system. +An orphaned file is one with an invalid owner or group. +.It Va weekly_noid_dirs +.Pq Vt str +A list of directories under which orphaned files are searched for. +This would usually be set to +.Pa / . +.It Va weekly_status_security_enable +.Pq Vt bool +Weekly counterpart of +.Va daily_status_security_enable . +.It Va weekly_status_security_inline +.Pq Vt bool +Weekly counterpart of +.Va daily_status_security_inline . +.It Va weekly_status_security_output +.Pq Vt str +Weekly counterpart of +.Va daily_status_security_output . +.It Va weekly_status_pkg_enable +.Pq Vt bool +Set to +.Dq Li YES +if you want to use +.Xr pkg-version 8 +to list installed packages which are out of date. +.It Va pkg_version +.Pq Vt str +When +.Va weekly_status_pkg_enable +is set to +.Dq Li YES , +this variable specifies the program that is used to determine the out of +date packages. +If unset, the +.Xr pkg-version 8 +program is used. +As an example, this variable might be set to +.Dq Li portversion +if the +.Pa ports/sysutils/portupgrade +port has been installed. +.It Va pkg_version_index +.Pq Vt str +This variable specifies the +.Pa INDEX +file from +.Pa /usr/ports +that should be used by +.Xr pkg-version 8 . +Because the dependency tree may be substantially different between versions of +.Fx , +there may be more than one +.Pa INDEX +file in +.Pa /usr/ports . +.Pp +Note, if the +.Va pkg_version +variable is set to +.Dq Li portversion , +it will also be necessary to arrange that the correct +.Pa INDEX +file is specified +using environment variables and that +.Va pkg_version_index +is cleared in +.Pa /etc/periodic.conf +.Pq Dq Li pkg_version_index= . +.It Va weekly_local +.Pq Vt str +Set to a list of extra scripts that should be run after all other +weekly scripts. +All scripts must be absolute path names. +.El +.Pp +The following variables are used by the standard scripts that reside in +.Pa /etc/periodic/monthly : +.Bl -tag -offset 4n -width 2n +.It Va monthly_accounting_enable +.Pq Vt bool +Set to +.Dq Li YES +if you want to do login accounting using the +.Xr ac 8 +command. +.It Va monthly_status_security_enable +.Pq Vt bool +Monthly counterpart of +.Va daily_status_security_enable . +.It Va monthly_status_security_inline +.Pq Vt bool +Monthly counterpart of +.Va daily_status_security_inline . +.It Va monthly_status_security_output +.Pq Vt str +Monthly counterpart of +.Va daily_status_security_output . +.It Va monthly_local +.Pq Vt str +Set to a list of extra scripts that should be run after all other +monthly scripts. +All scripts must be absolute path names. +.El +.Pp +The following variables are used by the standard scripts that reside in +.Pa /etc/periodic/security . +Those scripts are usually run from daily +.Pq Va daily_status_security_enable , +weekly +.Pq Va weekly_status_security_enable , +and monthly +.Pq Va monthly_status_security_enable +periodic hooks. +The +.Va ..._period +of each script can be configured as +.Dq daily , +.Dq weekly , +.Dq monthly +or +.Dq NO . +Note that when periodic security scripts are run from +.Xr crontab 5 , +they will be always run unless their +.Va ..._enable +or +.Va ..._period +variable is set to +.Dq NO . +.Bl -tag -offset 4n -width 2n +.It Va security_status_diff_flags +.Pq Vt str +Set to the arguments to pass to the +.Xr diff 1 +utility when generating differences. +The default is +.Fl b +.Fl U Cm 0 . +.It Va security_status_chksetuid_enable +.Pq Vt bool +Set to +.Dq Li YES +to compare the modes and modification times of setuid executables with +the previous day's values. +.It Va security_status_chksetuid_period +.Pq Vt str +Set to either +.Dq Li daily , +.Dq Li weekly , +.Dq Li monthly +or +.Dq Li NO . +.It Va security_status_chkportsum_enable +.Pq Vt bool +Set to +.Dq Li YES +to verify checksums of all installed packages against the known checksums in +.Pa /var/db/pkg . +.It Va security_status_chkportsum_period +.Pq Vt str +Set to either +.Dq Li daily , +.Dq Li weekly , +.Dq Li monthly +or +.Dq Li NO . +.It Va security_status_neggrpperm_enable +.Pq Vt bool +Set to +.Dq Li YES +to check for files where the group of a file has less permissions than +the world at large. +When users are in more than 14 supplemental groups these negative +permissions may not be enforced via NFS shares. +.It Va security_status_neggrpperm_period +.Pq Vt str +Set to either +.Dq Li daily , +.Dq Li weekly , +.Dq Li monthly +or +.Dq Li NO . +.It Va security_status_chkmounts_enable +.Pq Vt bool +Set to +.Dq Li YES +to check for changes mounted file systems to the previous day's values. +.It Va security_status_chkmounts_period +.Pq Vt str +Set to either +.Dq Li daily , +.Dq Li weekly , +.Dq Li monthly +or +.Dq Li NO . +.It Va security_status_noamd +.Pq Vt bool +Set to +.Dq Li YES +if you want to ignore +.Xr amd 8 +mounts when comparing against yesterday's file system mounts in the +.Va security_status_chkmounts_enable +check. +.It Va security_status_chkuid0_enable +.Pq Vt bool +Set to +.Dq Li YES +to check +.Pa /etc/master.passwd +for accounts with UID 0. +.It Va security_status_chkuid0_period +.Pq Vt str +Set to either +.Dq Li daily , +.Dq Li weekly , +.Dq Li monthly +or +.Dq Li NO . +.It Va security_status_passwdless_enable +.Pq Vt bool +Set to +.Dq Li YES +to check +.Pa /etc/master.passwd +for accounts with empty passwords. +.It Va security_status_passwdless_period +.Pq Vt str +Set to either +.Dq Li daily , +.Dq Li weekly , +.Dq Li monthly +or +.Dq Li NO . +.It Va security_status_logincheck_enable +.Pq Vt bool +Set to +.Dq Li YES +to check +.Pa /etc/login.conf +ownership, see +.Xr login.conf 5 +for more information. +.It Va security_status_logincheck_period +.Pq Vt str +Set to either +.Dq Li daily , +.Dq Li weekly , +.Dq Li monthly +or +.Dq Li NO . +.It Va security_status_ipfwdenied_enable +.Pq Vt bool +Set to +.Dq Li YES +to show log entries for packets denied by +.Xr ipfw 8 +since yesterday's check. +.It Va security_status_ipfwdenied_period +.Pq Vt str +Set to either +.Dq Li daily , +.Dq Li weekly , +.Dq Li monthly +or +.Dq Li NO . +.It Va security_status_ipfdenied_enable +.Pq Vt bool +Set to +.Dq Li YES +to show log entries for packets denied by +.Xr ipf 8 +since yesterday's check. +.It Va security_status_ipfdenied_period +.Pq Vt str +Set to either +.Dq Li daily , +.Dq Li weekly , +.Dq Li monthly +or +.Dq Li NO . +.It Va security_status_pfdenied_enable +.Pq Vt bool +Set to +.Dq Li YES +to show log entries for packets denied by +.Xr pf 4 +since yesterday's check. +.It Va security_status_pfdenied_additionalanchors +.Pq Vt str +Space-separated list of additional anchors whose denied packets log entries to +show. +The main ruleset (i.e., the empty-string anchor) and any +.Xr blocklistd 8 +anchors, if present, are always shown. +.It Va security_status_pfdenied_period +.Pq Vt str +Set to either +.Dq Li daily , +.Dq Li weekly , +.Dq Li monthly +or +.Dq Li NO . +.It Va security_status_ipfwlimit_enable +.Pq Vt bool +Set to +.Dq Li YES +to display +.Xr ipfw 8 +rules that have reached their verbosity limit. +.It Va security_status_ipfwlimit_period +.Pq Vt str +Set to either +.Dq Li daily , +.Dq Li weekly , +.Dq Li monthly +or +.Dq Li NO . +.It Va security_status_kernelmsg_enable +.Pq Vt bool +Set to +.Dq Li YES +to show new +.Xr dmesg 8 +entries since yesterday's check. +.It Va security_status_kernelmsg_period +.Pq Vt str +Set to either +.Dq Li daily , +.Dq Li weekly , +.Dq Li monthly +or +.Dq Li NO . +.It Va security_status_loginfail_enable +.Pq Vt bool +Set to +.Dq Li YES +to display failed logins from +.Pa /var/log/messages +in the previous day. +.It Va security_status_loginfail_period +.Pq Vt str +Set to either +.Dq Li daily , +.Dq Li weekly , +.Dq Li monthly +or +.Dq Li NO . +.It Va security_status_tcpwrap_enable +.Pq Vt bool +Set to +.Dq Li YES +to display connections denied by tcpwrappers (see +.Xr hosts_access 5 ) +from +.Pa /var/log/messages +during the previous day. +.It Va security_status_tcpwrap_period +.Pq Vt str +Set to either +.Dq Li daily , +.Dq Li weekly , +.Dq Li monthly +or +.Dq Li NO . +.El +.Sh FILES +.Bl -tag -width ".Pa /etc/defaults/periodic.conf" +.It Pa /etc/defaults/periodic.conf +The default configuration file. +This file contains all default variables and values. +.It Pa /etc/periodic.conf +The usual system specific variable override file. +.It Pa /etc/periodic.conf.local +An additional override file, useful when +.Pa /etc/periodic.conf +is shared or distributed. +.El +.Sh SEE ALSO +.Xr apropos 1 , +.Xr calendar 1 , +.Xr df 1 , +.Xr diff 1 , +.Xr gzip 1 , +.Xr locate 1 , +.Xr man 1 , +.Xr msgs 1 , +.Xr netstat 1 , +.Xr nice 1 , +.Xr login.conf 5 , +.Xr rc.conf 5 , +.Xr ac 8 , +.Xr chkgrp 8 , +.Xr dump 8 , +.Xr newsyslog 8 , +.Xr periodic 8 , +.Xr pkg-version 8 , +.Xr sendmail 8 +.Sh HISTORY +The +.Nm +file appeared in +.Fx 4.1 . +.Sh AUTHORS +.An Brian Somers Aq Mt brian@Awfulhak.org diff --git a/static/freebsd/man5/pf.conf.5 b/static/freebsd/man5/pf.conf.5 new file mode 100644 index 00000000..978634e8 --- /dev/null +++ b/static/freebsd/man5/pf.conf.5 @@ -0,0 +1,3894 @@ +.\" $OpenBSD: pf.conf.5,v 1.406 2009/01/31 19:37:12 sobrado Exp $ +.\" +.\" Copyright (c) 2002, Daniel Hartmeier +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" - Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" - 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 COPYRIGHT HOLDERS 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 +.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN +.\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 22, 2026 +.Dt PF.CONF 5 +.Os +.Sh NAME +.Nm pf.conf +.Nd packet filter configuration file +.Sh DESCRIPTION +The +.Xr pf 4 +packet filter modifies, drops or passes packets according to rules or +definitions specified in +.Nm pf.conf . +.Sh STATEMENT ORDER +There are eight types of statements in +.Nm pf.conf : +.Bl -tag -width xxxx +.It Cm Macros +User-defined variables may be defined and used later, simplifying +the configuration file. +Macros must be defined before they are referenced in +.Nm pf.conf . +.It Cm Tables +Tables provide a mechanism for increasing the performance and flexibility of +rules with large numbers of source or destination addresses. +.It Cm Options +Options tune the behaviour of the packet filtering engine. +.It Cm Ethernet Filtering +Ethernet filtering provides rule-based blocking or passing of Ethernet packets. +.It Cm Traffic Normalization Li (e.g. Em scrub ) +Traffic normalization protects internal machines against inconsistencies +in Internet protocols and implementations. +.It Cm Queueing +Queueing provides rule-based bandwidth control. +.It Cm Translation Li (Various forms of NAT) +Translation rules specify how addresses are to be mapped or redirected to +other addresses. +.It Cm Packet Filtering +Packet filtering provides rule-based blocking or passing of packets. +.El +.Pp +With the exception of +.Cm macros +and +.Cm tables , +the types of statements should be grouped and appear in +.Nm pf.conf +in the order shown above, as this matches the operation of the underlying +packet filtering engine. +By default +.Xr pfctl 8 +enforces this order (see +.Ar set require-order +below). +.Pp +Comments can be put anywhere in the file using a hash mark +.Pq Sq # , +and extend to the end of the current line. +.Pp +Additional configuration files can be included with the +.Ic include +keyword, for example: +.Bd -literal -offset indent +include "/etc/pf/sub.filter.conf" +.Ed +.Sh MACROS +A macro is defined with a command of the form +.Ar name Ns = Ns Ar value . +The macro +.Ar name +can contain letters, digits, and underscores and cannot be a reserved word +(for example, +.Ar pass , +.Ar in , +or +.Ar out ) . +Within unquoted arguments, the string +.Pf $ Ar name +is later expanded to +.Ar value . +Ranges of network addresses used in macros that will be expanded in lists +later on must be quoted with additional simple quotes. +.Pp +For example, +.Bd -literal -offset indent +ext_if = \&"kue0\&" +all_ifs = \&"{\&" $ext_if lo0 \&"}\&" +pass out on $ext_if from any to any +pass in on $ext_if proto tcp from any to any port 25 + +usr_lan_range = "'192.0.2.0/24'" +srv_lan_range = "'198.51.100.0 - 198.51.100.255'" +nat_ranges = \&"{\&" $usr_lan_range $srv_lan_range \&"}\&" +nat on $ext_if from $nat_ranges to any -> ($ext_if) +.Ed +.Sh TABLES +Tables are named structures which can hold a collection of addresses and +networks. +Lookups against tables in +.Xr pf 4 +are relatively fast, making a single rule with tables much more efficient, +in terms of +processor usage and memory consumption, than a large number of rules which +differ only in IP address (either created explicitly or automatically by rule +expansion). +.Pp +Tables can be used as the source or destination of filter rules, +.Ar scrub +rules +or +translation rules such as +.Ar nat +or +.Ar rdr +(see below for details on the various rule types). +Tables can also be used for the redirect address of +.Ar nat +and +.Ar rdr +and in the routing options of filter rules, but not for +.Ar bitmask +pools. +.Pp +Tables can be defined with any of the following +.Xr pfctl 8 +mechanisms. +As with macros, reserved words may not be used as table names. +.Bl -tag -width "manually" +.It Ar manually +Persistent tables can be manually created with the +.Ar add +or +.Ar replace +option of +.Xr pfctl 8 , +before or after the ruleset has been loaded. +.It Pa pf.conf +Table definitions can be placed directly in this file, and loaded at the +same time as other rules are loaded, atomically. +Table definitions inside +.Nm pf.conf +use the +.Ar table +statement, and are especially useful to define non-persistent tables. +The contents of a pre-existing table defined without a list of addresses +to initialize it is not altered when +.Nm pf.conf +is loaded. +A table initialized with the empty list, +.Li { } , +will be cleared on load. +.El +.Pp +Tables may be defined with the following attributes: +.Bl -tag -width counters +.It Ar persist +The +.Ar persist +flag forces the kernel to keep the table even when no rules refer to it. +If the flag is not set, the kernel will automatically remove the table +when the last rule referring to it is flushed. +.It Ar const +The +.Ar const +flag prevents the user from altering the contents of the table once it +has been created. +Without that flag, +.Xr pfctl 8 +can be used to add or remove addresses from the table at any time, even +when running with +.Xr securelevel 7 += 2. +.It Ar counters +The +.Ar counters +flag enables per-address packet and byte counters which can be displayed with +.Xr pfctl 8 . +Note that this feature carries significant memory overhead for large tables. +.El +.Pp +For example, +.Bd -literal -offset indent +table const { 10/8, 172.16/12, 192.168/16 } +table persist +block on fxp0 from { , } to any +.Ed +.Pp +creates a table called private, to hold RFC 1918 private network +blocks, and a table called badhosts, which is initially empty. +A filter rule is set up to block all traffic coming from addresses listed in +either table. +The private table cannot have its contents changed and the badhosts table +will exist even when no active filter rules reference it. +Addresses may later be added to the badhosts table, so that traffic from +these hosts can be blocked by using +.Bd -literal -offset indent +# pfctl -t badhosts -Tadd 204.92.77.111 +.Ed +.Pp +A table can also be initialized with an address list specified in one or more +external files, using the following syntax: +.Bd -literal -offset indent +table persist file \&"/etc/spammers\&" file \&"/etc/openrelays\&" +block on fxp0 from to any +.Ed +.Pp +The files +.Pa /etc/spammers +and +.Pa /etc/openrelays +list IP addresses, one per line. +Any lines beginning with a # are treated as comments and ignored. +In addition to being specified by IP address, hosts may also be +specified by their hostname. +When the resolver is called to add a hostname to a table, +.Em all +resulting IPv4 and IPv6 addresses are placed into the table. +IP addresses can also be entered in a table by specifying a valid interface +name, a valid interface group or the +.Em self +keyword, in which case all addresses assigned to the interface(s) will be +added to the table. +.Sh OPTIONS +.Xr pf 4 +may be tuned for various situations using the +.Ar set +command. +.Bl -tag -width xxxx +.It Ar set timeout +.Pp +.Bl -tag -width "src.track" -compact +.It Ar interval +Interval between purging expired states and fragments. +.It Ar frag +Seconds before an unassembled fragment is expired. +.It Ar src.track +Length of time to retain a source tracking entry after the last state +expires. +.El +.Pp +When a packet matches a stateful connection, the seconds to live for the +connection will be updated to that of the +.Ar proto.modifier +which corresponds to the connection state. +Each packet which matches this state will reset the TTL. +Tuning these values may improve the performance of the +firewall at the risk of dropping valid idle connections. +Alternatively, these values may be adjusted collectively +in a manner suitable for a specific environment using +.Cm set optimization +(see above). +.Pp +.Bl -tag -width xxxx -compact +.It Ar tcp.first +The state after the first packet. +.It Ar tcp.opening +The state after the second packet but before both endpoints have +acknowledged the connection. +.It Ar tcp.tsdiff +Maximum allowed time difference between RFC 1323 compliant packet timestamps. +30 seconds by default. +.It Ar tcp.established +The fully established state. +.It Ar tcp.closing +The state after the first FIN has been sent. +.It Ar tcp.finwait +The state after both FINs have been exchanged and the connection is closed. +Some hosts (notably web servers on Solaris) send TCP packets even after closing +the connection. +Increasing +.Ar tcp.finwait +(and possibly +.Ar tcp.closing ) +can prevent blocking of such packets. +.It Ar tcp.closed +The state after one endpoint sends an RST. +.El +.Pp +SCTP timeout are handled similar to TCP, but with its own set of states: +.Pp +.Bl -tag -width xxxx -compact +.It Ar sctp.first +The state after the first packet. +.It Ar sctp.opening +The state before the destination host ever sends a packet. +.It Ar sctp.established +The fully established state. +.It Ar sctp.closing +The state after the first SHUTDOWN chunk has been sent. +.It Ar sctp.closed +The state after SHUTDOWN_ACK has been exchanged and the connection is closed. +.El +.Pp +ICMP and UDP are handled in a fashion similar to TCP, but with a much more +limited set of states: +.Pp +.Bl -tag -width xxxx -compact +.It Ar udp.first +The state after the first packet. +.It Ar udp.single +The state if the source host sends more than one packet but the destination +host has never sent one back. +.It Ar udp.multiple +The state if both hosts have sent packets. +.It Ar icmp.first +The state after the first packet. +.It Ar icmp.error +The state after an ICMP error came back in response to an ICMP packet. +.El +.Pp +Other protocols are handled similarly to UDP: +.Pp +.Bl -tag -width xxxx -compact +.It Ar other.first +.It Ar other.single +.It Ar other.multiple +.El +.Pp +Timeout values can be reduced adaptively as the number of state table +entries grows. +.Pp +.Bl -tag -width xxxx -compact +.It Ar adaptive.start +When the number of state entries exceeds this value, adaptive scaling +begins. +All timeout values are scaled linearly with factor +(adaptive.end - number of states) / (adaptive.end - adaptive.start). +.It Ar adaptive.end +When reaching this number of state entries, all timeout values become +zero, effectively purging all state entries immediately. +This value is used to define the scale factor, it should not actually +be reached (set a lower state limit, see below). +.El +.Pp +Adaptive timeouts are enabled by default, with an adaptive.start value +equal to 60% of the state limit, and an adaptive.end value equal to +120% of the state limit. +They can be disabled by setting both adaptive.start and adaptive.end to 0. +.Pp +The adaptive timeout values can be defined both globally and for each rule. +When used on a per-rule basis, the values relate to the number of +states created by the rule, otherwise to the total number of +states. +.Pp +For example: +.Bd -literal -offset indent +set timeout tcp.first 120 +set timeout tcp.established 86400 +set timeout { adaptive.start 60000, adaptive.end 120000 } +set limit states 100000 +.Ed +.Pp +With 90000 state table entries, the timeout values are scaled to 50% +(tcp.first 60, tcp.established 43200). +.It Ar set loginterface +Enable collection of packet and byte count statistics for the given +interface or interface group. +These statistics can be viewed using +.Bd -literal -offset indent +# pfctl -s info +.Ed +.Pp +In this example +.Xr pf 4 +collects statistics on the interface named dc0: +.Bd -literal -offset indent +set loginterface dc0 +.Ed +.Pp +One can disable the loginterface using: +.Bd -literal -offset indent +set loginterface none +.Ed +.It Ar set limit +Sets hard limits on the memory pools used by the packet filter. +See +.Xr zone 9 +for an explanation of memory pools. +.Pp +Limits can be set on the following: +.Bl -tag -width pktdelay_pkts +.It Cm states +Set the maximum number of entries in the memory pool used by state table +entries (those generated by +.Ar pass +rules which do not specify +.Cm no state ) . +The default is 100000. +.It Cm src-nodes +Set the maximum number of entries in the memory pool used for tracking +source IP addresses (generated by the +.Ar sticky-address +and +.Ar src.track +options). +The default is 10000. +.It Cm table-entries +Set the number of addresses that can be stored in tables. +The default is 200000. +.It Cm anchors +Set the number of anchors that can exist. +The default is 512. +.It Cm eth-anchors +Set the number of anchors that can exist. +The default is 512. +.El +.Pp +Multiple limits can be combined on a single line: +.Bd -literal -offset indent +set limit { states 20000, frags 2000, src-nodes 2000 } +.Ed +.It Ar set ruleset-optimization +.Bl -tag -width xxxxxxxx -compact +.It Ar none +Disable the ruleset optimizer. +.It Ar basic +Enable basic ruleset optimization. +This is the default behaviour. +Basic ruleset optimization does four things to improve the +performance of ruleset evaluations: +.Pp +.Bl -enum -compact +.It +remove duplicate rules +.It +remove rules that are a subset of another rule +.It +combine multiple rules into a table when advantageous +.It +re-order the rules to improve evaluation performance +.El +.Pp +.It Ar profile +Uses the currently loaded ruleset as a feedback profile to tailor the +ordering of quick rules to actual network traffic. +.El +.Pp +It is important to note that the ruleset optimizer will modify the ruleset +to improve performance. +A side effect of the ruleset modification is that per-rule accounting +statistics will have different meanings than before. +If per-rule accounting is important for billing purposes or whatnot, +either the ruleset optimizer should not be used or a label field should +be added to all of the accounting rules to act as optimization barriers. +.Pp +Optimization can also be set as a command-line argument to +.Xr pfctl 8 , +overriding the settings in +.Nm . +.It Ar set optimization +Optimize state timeouts for one of the following network environments: +.Pp +.Bl -tag -width xxxx -compact +.It Ar normal +A normal network environment. +Suitable for almost all networks. +.It Ar high-latency +A high-latency environment (such as a satellite connection). +.It Ar satellite +Alias for +.Ar high-latency . +.It Ar aggressive +Aggressively expire connections. +This can greatly reduce the memory usage of the firewall at the cost of +dropping idle connections early. +.It Ar conservative +Extremely conservative settings. +Avoid dropping legitimate connections at the +expense of greater memory utilization (possibly much greater on a busy +network) and slightly increased processor utilization. +.El +.Pp +For example: +.Bd -literal -offset indent +set optimization aggressive +.Ed +.It Ar set reassemble yes | no Op Cm no-df +The +.Cm reassemble +option is used to enable or disable the reassembly of fragmented packets, +and can be set to +.Cm yes +or +.Cm no . +If +.Cm no-df +is also specified, fragments with the +.Dq dont-fragment +bit set are reassembled too, +instead of being dropped; +the reassembled packet will have the +.Dq dont-fragment +bit cleared. +The default value is +.Cm no . +.Pp +This option is ignored if there are pre-FreeBSD 14 +.Cm scrub +rules present. +.It Ar set block-policy +The +.Ar block-policy +option sets the default behaviour for the packet +.Ar block +action: +.Pp +.Bl -tag -width xxxxxxxx -compact +.It Ar drop +Packet is silently dropped. +.It Ar return +A TCP RST is returned for blocked TCP packets, +an SCTP ABORT chunk is returned for blocked SCTP packets, +an ICMP UNREACHABLE is returned for blocked UDP packets, +and all other packets are silently dropped. +.El +.Pp +The default value is +.Cm drop . +.Pp +For example: +.Bd -literal -offset indent +set block-policy return +.Ed +.It Ar set fail-policy +The +.Ar fail-policy +option sets the behaviour of rules which should pass a packet but were +unable to do so. +This might happen when a nat or route-to rule uses an empty table as list +of targets or if a rule fails to create state or source node. +The following +.Ar block +actions are possible: +.Pp +.Bl -tag -width xxxxxxxx -compact +.It Ar drop +Incoming packet is silently dropped. +.It Ar return +Incoming packet is dropped and TCP RST is returned for TCP packets, +an SCTP ABORT chunk is returned for blocked SCTP packets, +an ICMP UNREACHABLE is returned for UDP packets, +and no response is sent for other packets. +.El +.Pp +For example: +.Bd -literal -offset indent +set fail-policy return +.Ed +.It Ar set state-policy +The +.Ar state-policy +option sets the default behaviour for states: +.Pp +.Bl -tag -width group-bound -compact +.It Ar if-bound +States are bound to interface. +.It Ar floating +States can match packets on any interfaces (the default). +.El +.Pp +For example: +.Bd -literal -offset indent +set state-policy if-bound +.Ed +.It Ar set syncookies never | always | adaptive +When +.Cm syncookies +are active, pf will answer each incoming TCP SYN with a syncookie SYNACK, +without allocating any resources. +Upon reception of the client's ACK in response to the syncookie +SYNACK, pf will evaluate the ruleset and create state if the ruleset +permits it, complete the three way handshake with the target host and +continue the connection with synproxy in place. +This allows pf to be resilient against large synflood attacks which would +run the state table against its limits otherwise. +Due to the blind answers to every incoming SYN syncookies share the caveats of +synproxy, namely seemingly accepting connections that will be dropped later on. +.Pp +.Bl -tag -width adaptive -compact +.It Cm never +pf will never send syncookie SYNACKs (the default). +.It Cm always +pf will always send syncookie SYNACKs. +.It Cm adaptive +pf will enable syncookie mode when a given percentage of the state table +is used up by half-open TCP connections, as in, those that saw the initial +SYN but didn't finish the three way handshake. +The thresholds for entering and leaving syncookie mode can be specified using +.Bd -literal -offset indent +set syncookies adaptive (start 25%, end 12%) +.Ed +.El +.It Ar set state-defaults +The +.Ar state-defaults +option sets the state options for states created from rules +without an explicit +.Ar keep state . +For example: +.Bd -literal -offset indent +set state-defaults no-sync +.Ed +.It Ar set hostid +The 32-bit +.Ar hostid +identifies this firewall's state table entries to other firewalls +in a +.Xr pfsync 4 +failover cluster. +By default the hostid is set to a pseudo-random value, however it may be +desirable to manually configure it, for example to more easily identify the +source of state table entries. +.Bd -literal -offset indent +set hostid 1 +.Ed +.Pp +The hostid may be specified in either decimal or hexadecimal. +.It Ar set require-order +By default +.Xr pfctl 8 +enforces an ordering of the statement types in the ruleset to: +.Em options , +.Em normalization , +.Em queueing , +.Em translation , +.Em filtering . +Setting this option to +.Ar no +disables this enforcement. +There may be non-trivial and non-obvious implications to an out of +order ruleset. +Consider carefully before disabling the order enforcement. +.It Ar set fingerprints +Load fingerprints of known operating systems from the given filename. +By default fingerprints of known operating systems are automatically +loaded from +.Xr pf.os 5 +in +.Pa /etc +but can be overridden via this option. +Setting this option may leave a small period of time where the fingerprints +referenced by the currently active ruleset are inconsistent until the new +ruleset finishes loading. +The default location for fingerprints is +.Pa /etc/pf.os . +.Pp +For example: +.Pp +.Dl set fingerprints \&"/etc/pf.os.devel\&" +.It Ar set skip on Aq Ar ifspec +List interfaces for which packets should not be filtered. +Packets passing in or out on such interfaces are passed as if pf was +disabled, i.e. pf does not process them in any way. +This can be useful on loopback and other virtual interfaces, when +packet filtering is not desired and can have unexpected effects. +For example: +.Pp +.Dl set skip on lo0 +.It Ar set debug +Set the debug +.Ar level +to one of the following: +.Pp +.Bl -tag -width xxxxxxxxxxxx -compact +.It Ar none +Don't generate debug messages. +.It Ar urgent +Generate debug messages only for serious errors. +.It Ar misc +Generate debug messages for various errors. +.It Ar loud +Generate debug messages for common conditions. +.El +.It Ar set keepcounters +Preserve rule counters across rule updates. +Usually rule counters are reset to zero on every update of the ruleset. +With +.Ar keepcounters +set pf will attempt to find matching rules between old and new rulesets +and preserve the rule counters. +.El +.Sh ETHERNET FILTERING +.Xr pf 4 +has the ability to +.Ar block +and +.Ar pass +packets based on attributes of their Ethernet (layer 2) header. +.Pp +Each time a packet processed by the packet filter comes in on or +goes out through an interface, the filter rules are evaluated in +sequential order, from first to last. +The last matching rule decides what action is taken. +If no rule matches the packet, the default action is to pass +the packet without creating a state. +.Pp +The following actions can be used in the filter: +.Bl -tag -width xxxx +.It Ar block +The packet is blocked. +Unlike for layer 3 traffic the packet is always silently dropped. +.It Ar pass +The packet is passed; +no state is created for layer 2 traffic. +.El +.Ss Parameters applicable to layer 2 rules +The rule parameters specify the packets to which a rule applies. +A packet always comes in on, or goes out through, one interface. +Most parameters are optional. +If a parameter is specified, the rule only applies to packets with +matching attributes. +The matching for some parameters can be inverted with the +.Cm !\& +operator. +Certain parameters can be expressed as lists, in which case +.Xr pfctl 8 +generates all needed rule combinations. +.Bl -tag -width xxxx +.It Ar in No or Ar out +This rule applies to incoming or outgoing packets. +If neither +.Ar in +nor +.Ar out +are specified, the rule will match packets in both directions. +.It Ar quick +If a packet matches a rule which has the +.Ar quick +option set, this rule +is considered the last matching rule, and evaluation of subsequent rules +is skipped. +.It Ar on Aq Ar ifspec +This rule applies only to packets coming in on, or going out through, this +particular interface or interface group. +For more information on interface groups, +see the +.Ic group +keyword in +.Xr ifconfig 8 . +.Ar any +will match any existing interface except loopback ones. +.It Ar bridge-to Aq interface +Packets matching this rule will be sent out of the specified interface without +further processing. +.It Ar proto Aq Ar protocol +This rule applies only to packets of this protocol. +Note that Ethernet protocol numbers are different from those used in +.Xr ip 4 +and +.Xr ip6 4 . +.It Xo +.Ar from Aq Ar source +.Ar to Aq Ar dest +.Xc +This rule applies only to packets with the specified source and destination +MAC addresses. +.It Xo Ar queue Aq Ar queue +.Xc +Packets matching this rule will be assigned to the specified queue. +See +.Sx QUEUEING +for setup details. +.Pp +.It Ar tag Aq Ar string +Packets matching this rule will be tagged with the +specified string. +The tag acts as an internal marker that can be used to +identify these packets later on. +This can be used, for example, to provide trust between +interfaces and to determine if packets have been +processed by translation rules. +Tags are +.Qq sticky , +meaning that the packet will be tagged even if the rule +is not the last matching rule. +Further matching rules can replace the tag with a +new one but will not remove a previously applied tag. +A packet is only ever assigned one tag at a time. +.It Ar tagged Aq Ar string +Used to specify that packets must already be tagged with the given tag in order +to match the rule. +Inverse tag matching can also be done by specifying the ! operator before the +tagged keyword. +.El +.Sh TRAFFIC NORMALIZATION +Traffic normalization is a broad umbrella term +for aspects of the packet filter which deal with +verifying packets, packet fragments, spoofed traffic, +and other irregularities. +.Ss Scrub +Scrub involves sanitising packet content in such a way +that there are no ambiguities in packet interpretation on the receiving side. +It is invoked with the +.Cm scrub +option, added to filter rules. +.Pp +Parameters are specified enclosed in parentheses. +At least one of the following parameters must be specified: +.Bl -tag -width xxxx +.It Ar no-df +Clears the +.Ar dont-fragment +bit from a matching IP packet. +Some operating systems are known to generate fragmented packets with the +.Ar dont-fragment +bit set. +This is particularly true with NFS. +.Ar Scrub +will drop such fragmented +.Ar dont-fragment +packets unless +.Ar no-df +is specified. +.Pp +Unfortunately some operating systems also generate their +.Ar dont-fragment +packets with a zero IP identification field. +Clearing the +.Ar dont-fragment +bit on packets with a zero IP ID may cause deleterious results if an +upstream router later fragments the packet. +Using the +.Ar random-id +modifier (see below) is recommended in combination with the +.Ar no-df +modifier to ensure unique IP identifiers. +.It Ar min-ttl Aq Ar number +Enforces a minimum TTL for matching IP packets. +.It Ar max-mss Aq Ar number +Reduces the maximum segment size (MSS) +on TCP SYN packets to be no greater than +.Ar number . +This is sometimes required in scenarios where the two endpoints +of a TCP connection are not able to carry similar sized packets +and the resulting mismatch can lead to packet fragmentation or loss. +Note that setting the MSS this way can have undesirable effects, +such as interfering with the OS detection features of +.Xr pf 4 . +.It Xo Ar set-tos Aq Ar string +.No \*(Ba Aq Ar number +.Xc +Enforces a +.Em TOS +for matching IP packets. +.Em TOS +may be +given as one of +.Ar critical , +.Ar inetcontrol , +.Ar lowdelay , +.Ar netcontrol , +.Ar throughput , +.Ar reliability , +or one of the DiffServ Code Points: +.Ar ef , +.Ar va , +.Ar af11 No ... Ar af43 , +.Ar cs0 No ... Ar cs7 ; +or as either hex or decimal. +.It Ar random-id +Replaces the IP identification field with random values to compensate +for predictable values generated by many hosts. +This option only applies to packets that are not fragmented +after the optional fragment reassembly. +.It Ar reassemble tcp +Statefully normalizes TCP connections. +.Ar reassemble tcp +performs the following normalizations: +.Pp +.Bl -tag -width timeout -compact +.It ttl +Neither side of the connection is allowed to reduce their IP TTL. +An attacker may send a packet such that it reaches the firewall, affects +the firewall state, and expires before reaching the destination host. +.Ar reassemble tcp +will raise the TTL of all packets back up to the highest value seen on +the connection. +.It timestamp modulation +Modern TCP stacks will send a timestamp on every TCP packet and echo +the other endpoint's timestamp back to them. +Many operating systems will merely start the timestamp at zero when +first booted, and increment it several times a second. +The uptime of the host can be deduced by reading the timestamp and multiplying +by a constant. +Also observing several different timestamps can be used to count hosts +behind a NAT device. +And spoofing TCP packets into a connection requires knowing or guessing +valid timestamps. +Timestamps merely need to be monotonically increasing and not derived off a +guessable base time. +.Ar reassemble tcp +will cause +.Ar scrub +to modulate the TCP timestamps with a random number. +.It extended PAWS checks +There is a problem with TCP on long fat pipes, in that a packet might get +delayed for longer than it takes the connection to wrap its 32-bit sequence +space. +In such an occurrence, the old packet would be indistinguishable from a +new packet and would be accepted as such. +The solution to this is called PAWS: Protection Against Wrapped Sequence +numbers. +It protects against it by making sure the timestamp on each packet does +not go backwards. +.Ar reassemble tcp +also makes sure the timestamp on the packet does not go forward more +than the RFC allows. +By doing this, +.Xr pf 4 +artificially extends the security of TCP sequence numbers by 10 to 18 +bits when the host uses appropriately randomized timestamps, since a +blind attacker would have to guess the timestamp as well. +.El +.El +.Pp +For example, +.Bd -literal -offset indent +match in all scrub (no-df random-id max-mss 1440) +.Ed +.Ss Scrub ruleset (pre-FreeBSD 14) +In order to maintain compatibility with older releases of FreeBSD +.Ar scrub +rules can also be specified in their own ruleset. +In such case they are invoked with the +.Ar scrub +directive. +If there are such rules present they determine packet reassembly behaviour. +When no such rules are present the option +.Ar set reassembly +takes precedence. +The +.Ar scrub +rules can take all parameters specified above for a +.Ar scrub +option of filter rules and 2 more parameters controlling fragment reassembly: +.Bl -tag -width xxxx +.It Ar fragment reassemble +Using +.Ar scrub +rules, fragments can be reassembled by normalization. +In this case, fragments are buffered until they form a complete +packet, and only the completed packet is passed on to the filter. +The advantage is that filter rules have to deal only with complete +packets, and can ignore fragments. +The drawback of caching fragments is the additional memory cost. +This is the default behaviour unless no fragment reassemble is specified. +.It Ar no fragment reassemble +Do not reassemble fragments. +.El +.Pp +For example, +.Bd -literal -offset indent +scrub in on $ext_if all fragment reassemble +.Ed +.Pp +The +.Ar no +option prefixed to a scrub rule causes matching packets to remain unscrubbed, +much in the same way as +.Ar drop quick +works in the packet filter (see below). +This mechanism should be used when it is necessary to exclude specific packets +from broader scrub rules. +.Pp +.Ar scrub +rules in the +.Ar scrub +ruleset are evaluated for every packet before stateful filtering. +This means excessive usage of them will cause performance penalty. +.Ar scrub reassemble tcp +rules must not have the direction (in/out) specified. +.Sh QUEUEING with ALTQ +The ALTQ system is currently not available in the GENERIC kernel nor as +loadable modules. +In order to use the herein after called queueing options one has to use a +custom built kernel. +Please refer to +.Xr altq 4 +to learn about the related kernel options. +.Pp +Packets can be assigned to queues for the purpose of bandwidth +control. +At least two declarations are required to configure queues, and later +any packet filtering rule can reference the defined queues by name. +During the filtering component of +.Nm pf.conf , +the last referenced +.Ar queue +name is where any packets from +.Ar pass +rules will be queued, while for +.Ar block +rules it specifies where any resulting ICMP or TCP RST +packets should be queued. +The +.Ar scheduler +defines the algorithm used to decide which packets get delayed, dropped, or +sent out immediately. +There are three +.Ar schedulers +currently supported. +.Bl -tag -width xxxx +.It Ar cbq +Class Based Queueing. +.Ar Queues +attached to an interface build a tree, thus each +.Ar queue +can have further child +.Ar queues . +Each queue can have a +.Ar priority +and a +.Ar bandwidth +assigned. +.Ar Priority +mainly controls the time packets take to get sent out, while +.Ar bandwidth +has primarily effects on throughput. +.Ar cbq +achieves both partitioning and sharing of link bandwidth +by hierarchically structured classes. +Each class has its own +.Ar queue +and is assigned its share of +.Ar bandwidth . +A child class can borrow bandwidth from its parent class +as long as excess bandwidth is available +(see the option +.Ar borrow , +below). +.It Ar priq +Priority Queueing. +.Ar Queues +are flat attached to the interface, thus, +.Ar queues +cannot have further child +.Ar queues . +Each +.Ar queue +has a unique +.Ar priority +assigned, ranging from 0 to 15. +Packets in the +.Ar queue +with the highest +.Ar priority +are processed first. +.It Ar hfsc +Hierarchical Fair Service Curve. +.Ar Queues +attached to an interface build a tree, thus each +.Ar queue +can have further child +.Ar queues . +Each queue can have a +.Ar priority +and a +.Ar bandwidth +assigned. +.Ar Priority +mainly controls the time packets take to get sent out, while +.Ar bandwidth +primarily affects throughput. +.Ar hfsc +supports both link-sharing and guaranteed real-time services. +It employs a service curve based QoS model, +and its unique feature is an ability to decouple +.Ar delay +and +.Ar bandwidth +allocation. +.El +.Pp +The interfaces on which queueing should be activated are declared using +the +.Ar altq on +declaration. +.Ar altq on +has the following keywords: +.Bl -tag -width xxxx +.It Aq Ar interface +Queueing is enabled on the named interface. +.It Aq Ar scheduler +Specifies which queueing scheduler to use. +Currently supported values +are +.Ar cbq +for Class Based Queueing, +.Ar priq +for Priority Queueing and +.Ar hfsc +for the Hierarchical Fair Service Curve scheduler. +.It Ar bandwidth Aq Ar bw +The maximum bitrate for all queues on an +interface may be specified using the +.Ar bandwidth +keyword. +The value can be specified as an absolute value or as a +percentage of the interface bandwidth. +When using an absolute value, the suffixes +.Ar b , +.Ar Kb , +.Ar Mb , +and +.Ar Gb +are used to represent bits, kilobits, megabits, and +gigabits per second, respectively. +The value must not exceed the interface bandwidth. +If +.Ar bandwidth +is not specified, the interface bandwidth is used +(but take note that some interfaces do not know their bandwidth, +or can adapt their bandwidth rates). +.It Ar qlimit Aq Ar limit +The maximum number of packets held in the queue. +The default is 50. +.It Ar tbrsize Aq Ar size +Adjusts the size, in bytes, of the token bucket regulator. +If not specified, heuristics based on the +interface bandwidth are used to determine the size. +.It Ar queue Aq Ar list +Defines a list of subqueues to create on an interface. +.El +.Pp +In the following example, the interface dc0 +should queue up to 5Mbps in four second-level queues using +Class Based Queueing. +Those four queues will be shown in a later example. +.Bd -literal -offset indent +altq on dc0 cbq bandwidth 5Mb queue { std, http, mail, ssh } +.Ed +.Pp +Once interfaces are activated for queueing using the +.Ar altq +directive, a sequence of +.Ar queue +directives may be defined. +The name associated with a +.Ar queue +must match a queue defined in the +.Ar altq +directive (e.g. mail), or, except for the +.Ar priq +.Ar scheduler , +in a parent +.Ar queue +declaration. +The following keywords can be used: +.Bl -tag -width xxxx +.It Ar on Aq Ar interface +Specifies the interface the queue operates on. +If not given, it operates on all matching interfaces. +.It Ar bandwidth Aq Ar bw +Specifies the maximum bitrate to be processed by the queue. +This value must not exceed the value of the parent +.Ar queue +and can be specified as an absolute value or a percentage of the parent +queue's bandwidth. +If not specified, defaults to 100% of the parent queue's bandwidth. +The +.Ar priq +scheduler does not support bandwidth specification. +.It Ar priority Aq Ar level +Between queues a priority level can be set. +For +.Ar cbq +and +.Ar hfsc , +the range is 0 to 7 and for +.Ar priq , +the range is 0 to 15. +The default for all is 1. +.Ar Priq +queues with a higher priority are always served first. +.Ar Cbq +and +.Ar Hfsc +queues with a higher priority are preferred in the case of overload. +.It Ar qlimit Aq Ar limit +The maximum number of packets held in the queue. +The default is 50. +.El +.Pp +The +.Ar scheduler +can get additional parameters with +.Xo Aq Ar scheduler +.Pf ( Aq Ar parameters ) . +.Xc +Parameters are as follows: +.Bl -tag -width Fl +.It Ar default +Packets not matched by another queue are assigned to this one. +Exactly one default queue is required. +.It Ar red +Enable RED (Random Early Detection) on this queue. +RED drops packets with a probability proportional to the average +queue length. +.It Ar rio +Enables RIO on this queue. +RIO is RED with IN/OUT, thus running +RED two times more than RIO would achieve the same effect. +RIO is currently not supported in the GENERIC kernel. +.It Ar ecn +Enables ECN (Explicit Congestion Notification) on this queue. +ECN implies RED. +.El +.Pp +The +.Ar cbq +.Ar scheduler +supports an additional option: +.Bl -tag -width Fl +.It Ar borrow +The queue can borrow bandwidth from the parent. +.El +.Pp +The +.Ar hfsc +.Ar scheduler +supports some additional options: +.Bl -tag -width Fl +.It Ar realtime Aq Ar sc +The minimum required bandwidth for the queue. +.It Ar upperlimit Aq Ar sc +The maximum allowed bandwidth for the queue. +.It Ar linkshare Aq Ar sc +The bandwidth share of a backlogged queue. +.El +.Pp +.Aq Ar sc +is an acronym for +.Ar service curve . +.Pp +The format for service curve specifications is +.Ar ( m1 , d , m2 ) . +.Ar m2 +controls the bandwidth assigned to the queue. +.Ar m1 +and +.Ar d +are optional and can be used to control the initial bandwidth assignment. +For the first +.Ar d +milliseconds the queue gets the bandwidth given as +.Ar m1 , +afterwards the value given in +.Ar m2 . +.Pp +Furthermore, with +.Ar cbq +and +.Ar hfsc , +child queues can be specified as in an +.Ar altq +declaration, thus building a tree of queues using a part of +their parent's bandwidth. +.Pp +Packets can be assigned to queues based on filter rules by using the +.Ar queue +keyword. +Normally only one +.Ar queue +is specified; when a second one is specified it will instead be used for +packets which have a +.Em TOS +of +.Em lowdelay +and for TCP ACKs with no data payload. +.Pp +To continue the previous example, the examples below would specify the +four referenced +queues, plus a few child queues. +Interactive +.Xr ssh 1 +sessions get priority over bulk transfers like +.Xr scp 1 +and +.Xr sftp 1 . +The queues may then be referenced by filtering rules (see +.Sx PACKET FILTERING +below). +.Bd -literal +queue std bandwidth 10% cbq(default) +queue http bandwidth 60% priority 2 cbq(borrow red) \e + { employees, developers } +queue developers bandwidth 75% cbq(borrow) +queue employees bandwidth 15% +queue mail bandwidth 10% priority 0 cbq(borrow ecn) +queue ssh bandwidth 20% cbq(borrow) { ssh_interactive, ssh_bulk } +queue ssh_interactive bandwidth 50% priority 7 cbq(borrow) +queue ssh_bulk bandwidth 50% priority 0 cbq(borrow) + +block return out on dc0 inet all queue std +pass out on dc0 inet proto tcp from $developerhosts to any port 80 \e + queue developers +pass out on dc0 inet proto tcp from $employeehosts to any port 80 \e + queue employees +pass out on dc0 inet proto tcp from any to any port 22 \e + queue(ssh_bulk, ssh_interactive) +pass out on dc0 inet proto tcp from any to any port 25 \e + queue mail +.Ed +.Sh QUEUEING with dummynet +Queueing can also be done with +.Xr dummynet 4 . +Queues and pipes can be created with +.Xr dnctl 8 . +.Pp +Packets can be assigned to queues and pipes using +.Ar dnqueue +and +.Ar dnpipe +respectively. +.Pp +Both +.Ar dnqueue +and +.Ar dnpipe +take either a single pipe or queue number or two numbers as arguments. +The first pipe or queue number will be used to shape the traffic in the rule +direction, the second will be used to shape the traffic in the reverse +direction. +If the rule does not specify a direction the first packet to create state will +be shaped according to the first number, and the response traffic according to +the second. +.Pp +If the +.Xr dummynet 4 +module is not loaded any traffic sent into a queue or pipe will be dropped. +.Sh TRANSLATION +Translation options modify either the source or destination address and +port of the packets associated with a stateful connection. +.Xr pf 4 +modifies the specified address and/or port in the packet and recalculates +IP, TCP, and UDP checksums as necessary. +.Pp +If specified on a +.Ic match +rule, subsequent rules will see packets as they look +after any addresses and ports have been translated. +These rules will therefore have to filter based on the translated +address and port number. +.Pp +The state entry created permits +.Xr pf 4 +to keep track of the original address for traffic associated with that state +and correctly direct return traffic for that connection. +.Pp +Various types of translation are possible with pf: +.Bl -tag -width xxxx +.It Ar af-to +Translation between different address families (NAT64) is handled +using +.Ar af-to +rules. +Because address family translation overrides the routing table, it's +only possible to use +.Ar af-to +on inbound rules, and a source address of the resulting translation +must always be specified. +.Pp +The optional second argument is the host or subnet the original +addresses are translated into for the destination. +The lowest bits of the original destination address form the host +part of the new destination address according to the specified subnet. +It is possible to embed a complete IPv4 address into an IPv6 address +using a network prefix of /96 or smaller. +.Pp +When a destination address is not specified, it is assumed that the host +part is 32-bit long. +For IPv6 to IPv4 translation this would mean using only the lower 32 +bits of the original IPv6 destination address. +For IPv4 to IPv6 translation the destination subnet defaults to the +subnet of the new IPv6 source address with a prefix length of /96. +See RFC 6052 Section 2.2 for details on how the prefix determines the +destination address encoding. +.Pp +For example, the following rules are identical: +.Bd -literal -offset indent +pass in inet af-to inet6 from 2001:db8::1 to 2001:db8::/96 +pass in inet af-to inet6 from 2001:db8::1 +.Ed +.Pp +In the above example the matching IPv4 packets will be modified to +have a source address of 2001:db8::1 and a destination address will +get prefixed with 2001:db8::/96, e.g. 198.51.100.100 will be +translated to 2001:db8::c633:6464. +.Pp +In the reverse case the following rules are identical: +.Bd -literal -offset indent +pass in inet6 from any to 64:ff9b::/96 af-to inet \e + from 198.51.100.1 to 0.0.0.0/0 +pass in inet6 from any to 64:ff9b::/96 af-to inet \e + from 198.51.100.1 +.Ed +.Pp +The destination IPv4 address is assumed to be embedded inside the +original IPv6 destination address, e.g. 64:ff9b::c633:6464 will be +translated to 198.51.100.100. +.Pp +The current implementation will only extract IPv4 addresses from the +IPv6 addresses with a prefix length of /96 and greater. +.It Ar binat-to +A +.Ar binat-to +rule specifies a bidirectional mapping between an external IP netblock +and an internal IP netblock. +It expands to an outbound +.Ar nat-to +rule and an inbound +.Ar rdr-to +rule. +.It Ar nat-to +A +.Ar nat-to +option specifies that IP addresses are to be changed as the packet +traverses the given interface. +This technique allows one or more IP addresses +on the translating host to support network traffic for a larger range of +machines on an "inside" network. +Although in theory any IP address can be used on the inside, it is strongly +recommended that one of the address ranges defined by RFC 1918 be used. +These netblocks are: +.Bd -literal -offset indent +10.0.0.0 - 10.255.255.255 (all of net 10.0.0.0, i.e., 10.0.0.0/8) +172.16.0.0 - 172.31.255.255 (i.e., 172.16.0.0/12) +192.168.0.0 - 192.168.255.255 (i.e., 192.168.0.0/16) +.Ed +.Pp +.Ar nat-to +is usually applied outbound. +If applied inbound, nat-to to a local IP address is not supported. +.It Pa rdr-to +The packet is redirected to another destination and possibly a +different port. +.Ar rdr-to +can optionally specify port ranges instead of single ports. +For instance: +.Bd -literal -offset indent +match in ... port 2000:2999 rdr-to ... port 4000 +.Ed +redirects ports 2000 to 2999 (inclusive) to port 4000. +.Bd -literal -offset indent +qmatch in ... port 2000:2999 rdr-to ... port 4000:* +.Ed +redirects port 2000 to 4000, 2001 to 4001, ..., 2999 to 4999. +.El +.Pp +.Ar rdr-to +is usually applied inbound. +If applied outbound, rdr-to to a local IP address is not supported. +In addition to modifying the address, some translation rules may modify +source or destination ports for +.Xr tcp 4 +or +.Xr udp 4 +connections; implicitly in the case of +.Ar nat-to +options and both implicitly and explicitly in the case of +.Ar rdr-to +ones. +A +.Ar rdr-to +option may cause the source port to be modified if doing so avoids a conflict +with an existing connection. +A random source port in the range 50001-65535 is chosen in this case. +Port numbers are never translated with a +.Ar binat-to +option. +.Pp +Note that redirecting external incoming connections to the loopback +address, as in +.Bd -literal -offset indent +pass in on egress proto tcp from any to any port smtp \e + rdr-to 127.0.0.1 port spamd +.Ed +.Pp +will effectively allow an external host to connect to daemons +bound solely to the loopback address, circumventing the traditional +blocking of such connections on a real interface. +Unless this effect is desired, any of the local non-loopback addresses +should be used as redirection target instead, which allows external +connections only to daemons bound to this address or not bound to +any address. +.Pp +See +.Sx TRANSLATION EXAMPLES +below. +.Ss NAT ruleset (pre-FreeBSD 15) +In order to maintain compatibility with older releases of FreeBSD +.Ar NAT +rules can also be specified in their own ruleset. +A stateful connection is automatically created to track packets matching +such a rule as long as they are not blocked by the filtering section of +.Nm pf.conf . +Since translation occurs before filtering the filter +engine will see packets as they look after any +addresses and ports have been translated. +Filter rules will therefore have to filter based on the translated +address and port number. +Packets that match a translation rule are only automatically passed if +the +.Ar pass +modifier is given, otherwise they are +still subject to +.Ar block +and +.Ar pass +rules. +.Pp +The following rules can be defined in the NAT ruleset: +.Ar binat , +.Ar nat , +and +.Ar rdr . +They have the same effect as +.Ar binat-to , +.Ar nat-to +and +.Ar rdr-to +options for filter rules. +.Pp +The +.Ar no +option prefixed to a translation rule causes packets to remain untranslated, +much in the same way as +.Ar drop quick +works in the packet filter. +If no rule matches the packet it is passed to the filter engine unmodified. +.Pp +Evaluation order of the translation rules is dependent on the type +of the translation rules and of the direction of a packet. +.Ar binat +rules are always evaluated first. +Then either the +.Ar rdr +rules are evaluated on an inbound packet or the +.Ar nat +rules on an outbound packet. +Rules of the same type are evaluated in the same order in which they +appear in the ruleset. +The first matching rule decides what action is taken. +.Pp +Translation rules apply only to packets that pass through +the specified interface, and if no interface is specified, +translation is applied to packets on all interfaces. +For instance, redirecting port 80 on an external interface to an internal +web server will only work for connections originating from the outside. +Connections to the address of the external interface from local hosts will +not be redirected, since such packets do not actually pass through the +external interface. +Redirections cannot reflect packets back through the interface they arrive +on, they can only be redirected to hosts connected to different interfaces +or to the firewall itself. +.Pp +See +.Sx COMPATIBILITY TRANSLATION EXAMPLES +below. +.Sh PACKET FILTERING +.Xr pf 4 +has the ability to +.Ar block +, +.Ar pass +and +.Ar match +packets based on attributes of their layer 3 (see +.Xr ip 4 +and +.Xr ip6 4 ) +and layer 4 (see +.Xr icmp 4 , +.Xr icmp6 4 , +.Xr tcp 4 , +.Xr sctp 4 , +.Xr udp 4 ) +headers. +In addition, packets may also be +assigned to queues for the purpose of bandwidth control. +.Pp +For each packet processed by the packet filter, the filter rules are +evaluated in sequential order, from first to last. +For +.Ar block +and +.Ar pass +, the last matching rule decides what action is taken. +For +.Ar match +, rules are evaluated every time they match; the pass/block state of a packet +remains unchanged. +If no rule matches the packet, the default action is to pass +the packet. +.Pp +The following actions can be used in the filter: +.Bl -tag -width xxxx +.It Ar block +The packet is blocked. +There are a number of ways in which a +.Ar block +rule can behave when blocking a packet. +The default behaviour is to +.Ar drop +packets silently, however this can be overridden or made +explicit either globally, by setting the +.Ar block-policy +option, or on a per-rule basis with one of the following options: +.Pp +.Bl -tag -width xxxx -compact +.It Ar drop +The packet is silently dropped. +.It Ar return-rst +This applies only to +.Xr tcp 4 +packets, and issues a TCP RST which closes the +connection. +.It Ar return-icmp +.It Ar return-icmp6 +This causes ICMP messages to be returned for packets which match the rule. +By default this is an ICMP UNREACHABLE message, however this +can be overridden by specifying a message as a code or number. +.It Ar return +This causes a TCP RST to be returned for +.Xr tcp 4 +packets, an SCTP ABORT for SCTP +and an ICMP UNREACHABLE for UDP and other packets. +.El +.Pp +Options returning ICMP packets currently have no effect if +.Xr pf 4 +operates on a +.Xr if_bridge 4 , +as the code to support this feature has not yet been implemented. +.Pp +The simplest mechanism to block everything by default and only pass +packets that match explicit rules is specify a first filter rule of: +.Bd -literal -offset indent +block all +.Ed +.It Ar match +The packet is matched. +This mechanism is used to provide fine grained filtering without altering the +block/pass state of a packet. +.Ar match +rules differ from +.Ar block +and +.Ar pass +rules in that parameters are set for every rule a packet matches, not only +on the last matching rule. +For the following parameters, this means that the parameter effectively becomes +"sticky" until explicitly overridden: +.Ar nat-to , +.Ar binat-to , +.Ar rdr-to , +.Ar queue , +.Ar dnpipe , +.Ar dnqueue , +.Ar rtable , +.Ar scrub +. +.It Ar pass +The packet is passed; +state is created unless the +.Ar no state +option is specified. +.El +.Pp +By default +.Xr pf 4 +filters packets statefully; the first time a packet matches a +.Ar pass +rule, a state entry is created; for subsequent packets the filter checks +whether the packet matches any state. +If it does, the packet is passed without evaluation of any rules. +After the connection is closed or times out, the state entry is automatically +removed. +.Pp +This has several advantages. +For TCP connections, comparing a packet to a state involves checking +its sequence numbers, as well as TCP timestamps if a +.Ar scrub reassemble tcp +rule applies to the connection. +If these values are outside the narrow windows of expected +values, the packet is dropped. +This prevents spoofing attacks, such as when an attacker sends packets with +a fake source address/port but does not know the connection's sequence +numbers. +Similarly, +.Xr pf 4 +knows how to match ICMP replies to states. +For example, +.Bd -literal -offset indent +pass out inet proto icmp all icmp-type echoreq +.Ed +.Pp +allows echo requests (such as those created by +.Xr ping 8 ) +out statefully, and matches incoming echo replies correctly to states. +.Pp +Also, looking up states is usually faster than evaluating rules. +.Pp +Furthermore, correct handling of ICMP error messages is critical to +many protocols, particularly TCP. +.Xr pf 4 +matches ICMP error messages to the correct connection, checks them against +connection parameters, and passes them if appropriate. +For example if an ICMP source quench message referring to a stateful TCP +connection arrives, it will be matched to the state and get passed. +.Pp +Finally, state tracking is required for +.Ar nat , binat No and Ar rdr +rules, in order to track address and port translations and reverse the +translation on returning packets. +.Pp +.Xr pf 4 +will also create state for other protocols which are effectively stateless by +nature. +UDP packets are matched to states using only host addresses and ports, +and other protocols are matched to states using only the host addresses. +.Pp +If stateless filtering of individual packets is desired, +the +.Ar no state +keyword can be used to specify that state will not be created +if this is the last matching rule. +A number of parameters can also be set to affect how +.Xr pf 4 +handles state tracking. +See +.Sx STATEFUL TRACKING OPTIONS +below for further details. +.Ss Parameters +The rule parameters specify the packets to which a rule applies. +A packet always comes in on, or goes out through, one interface. +Most parameters are optional. +If a parameter is specified, the rule only applies to packets with +matching attributes. +Certain parameters can be expressed as lists, in which case +.Xr pfctl 8 +generates all needed rule combinations. +.Bl -tag -width xxxx +.It Ar in No or Ar out +This rule applies to incoming or outgoing packets. +If neither +.Ar in +nor +.Ar out +are specified, the rule will match packets in both directions. +.It Ar log Pq Cm all | matches | to Ao Ar interface Ac | Cm user +In addition to any action specified, +log the packet. +Only the packet that establishes the state is logged, +unless the +.Ar no state +option is specified. +The logged packets are sent to a +.Xr pflog 4 +interface, by default pflog0; +pflog0 is monitored by the +.Xr pflogd 8 +logging daemon which logs to the file +.Pa /var/log/pflog +in +.Xr pcap 3 +binary format. +.Pp +The keywords +.Cm all , matches , to , +and +.Cm user +are optional and can be combined using commas, +but must be enclosed in parentheses if given. +.Pp +Use +.Cm all +to force logging of all packets for a connection. +This is not necessary when +.Ar no state +is explicitly specified. +.Pp +If +.Cm matches +is specified, +it logs the packet on all subsequent matching rules. +It is often combined with +.Cm to Aq Ar interface +to avoid adding noise to the default log file. +.Pp +The keyword +.Cm user +logs the +.Ux +user ID of the user that owns the socket and the PID of the process that +has the socket open where the packet is sourced from or destined to +(depending on which socket is local). +This is in addition to the normal information logged. +.Pp +Only the first packet +logged via +.Ar log (all, user) +will have the user credentials logged when using stateful matching. +.Pp +To specify a logging interface other than pflog0, +use the syntax +.Cm to Aq Ar interface . +.It Ar quick +If a packet matches a rule which has the +.Ar quick +option set, this rule +is considered the last matching rule, and evaluation of subsequent rules +is skipped. +.It Ar on Aq Ar interface +This rule applies only to packets coming in on, or going out through, this +particular interface or interface group. +For more information on interface groups, +see the +.Ic group +keyword in +.Xr ifconfig 8 . +.Ar any +will match any existing interface except loopback ones. +.It Aq Ar af +This rule applies only to packets of this address family. +Supported values are +.Ar inet +and +.Ar inet6 . +.It Ar proto Aq Ar protocol +This rule applies only to packets of this protocol. +Common protocols are +.Xr icmp 4 , +.Xr icmp6 4 , +.Xr tcp 4 , +.Xr sctp 4 , +and +.Xr udp 4 . +For a list of all the protocol name to number mappings used by +.Xr pfctl 8 , +see the file +.Pa /etc/protocols . +.It Xo +.Ar from Aq Ar source +.Ar port Aq Ar source +.Ar os Aq Ar source +.Ar to Aq Ar dest +.Ar port Aq Ar dest +.Xc +This rule applies only to packets with the specified source and destination +addresses and ports. +.Pp +Addresses can be specified in CIDR notation (matching netblocks), as +symbolic host names, interface names or interface group names, or as any +of the following keywords: +.Pp +.Bl -tag -width xxxxxxxxxxxxxx -compact +.It Ar any +Any address. +.It Ar no-route +Any address which is not currently routable. +.It Ar urpf-failed +Any source address that fails a unicast reverse path forwarding (URPF) +check, i.e. packets coming in on an interface other than that which holds +the route back to the packet's source address. +.It Ar self +Expands to all addresses assigned to all interfaces. +.It Aq Ar table +Any address that matches the given table. +.El +.Pp +Ranges of addresses are specified by using the +.Sq - +operator. +For instance: +.Dq 10.1.1.10 - 10.1.1.12 +means all addresses from 10.1.1.10 to 10.1.1.12, +hence addresses 10.1.1.10, 10.1.1.11, and 10.1.1.12. +.Pp +Interface names and interface group names, and +.Ar self +can have modifiers appended: +.Pp +.Bl -tag -width xxxxxxxxxxxx -compact +.It Ar :network +Translates to the network(s) attached to the interface. +.It Ar :broadcast +Translates to the interface's broadcast address(es). +.It Ar :peer +Translates to the point-to-point interface's peer address(es). +.It Ar :0 +Do not include interface aliases. +.El +.Pp +Host names may also have the +.Ar :0 +option appended to restrict the name resolution to the first of each +v4 and non-link-local v6 address found. +.Pp +Host name resolution and interface to address translation are done at +ruleset load-time. +When the address of an interface (or host name) changes (under DHCP or PPP, +for instance), the ruleset must be reloaded for the change to be reflected +in the kernel. +Surrounding the interface name (and optional modifiers) in parentheses +changes this behaviour. +When the interface name is surrounded by parentheses, the rule is +automatically updated whenever the interface changes its address. +The ruleset does not need to be reloaded. +This is especially useful with +.Ar nat . +.Pp +Ports can be specified either by number or by name. +For example, port 80 can be specified as +.Em www . +For a list of all port name to number mappings used by +.Xr pfctl 8 , +see the file +.Pa /etc/services . +.Pp +Ports and ranges of ports are specified by using these operators: +.Bd -literal -offset indent += (equal) +!= (unequal) +< (less than) +<= (less than or equal) +> (greater than) +>= (greater than or equal) +: (range including boundaries) +>< (range excluding boundaries) +<> (except range) +.Ed +.Pp +.Sq >< , +.Sq <> +and +.Sq \&: +are binary operators (they take two arguments). +For instance: +.Bl -tag -width Fl +.It Ar port 2000:2004 +means +.Sq all ports >= 2000 and <= 2004 , +hence ports 2000, 2001, 2002, 2003 and 2004. +.It Ar port 2000 >< 2004 +means +.Sq all ports > 2000 and < 2004 , +hence ports 2001, 2002 and 2003. +.It Ar port 2000 <> 2004 +means +.Sq all ports < 2000 or > 2004 , +hence ports 1-1999 and 2005-65535. +.El +.Pp +The operating system of the source host can be specified in the case of TCP +rules with the +.Ar OS +modifier. +See the +.Sx OPERATING SYSTEM FINGERPRINTING +section for more information. +.Pp +The host, port and OS specifications are optional, as in the following examples: +.Bd -literal -offset indent +pass in all +pass in from any to any +pass in proto tcp from any port < 1024 to any +pass in proto tcp from any to any port 25 +pass in proto tcp from 10.0.0.0/8 port >= 1024 \e + to ! 10.1.2.3 port != ssh +pass in proto tcp from any os "OpenBSD" +.Ed +.It Ar all +This is equivalent to "from any to any". +.It Ar group Aq Ar group +Similar to +.Ar user , +this rule only applies to packets of sockets owned by the specified group. +.It Ar user Aq Ar user +This rule only applies to packets of sockets owned by the specified user. +For outgoing connections initiated from the firewall, this is the user +that opened the connection. +For incoming connections to the firewall itself, this is the user that +listens on the destination port. +For forwarded connections, where the firewall is not a connection endpoint, +the user and group are +.Em unknown . +.Pp +All packets, both outgoing and incoming, of one connection are associated +with the same user and group. +Only TCP and UDP packets can be associated with users; for other protocols +these parameters are ignored. +.Pp +User and group refer to the effective (as opposed to the real) IDs, in +case the socket is created by a setuid/setgid process. +User and group IDs are stored when a socket is created; +when a process creates a listening socket as root (for instance, by +binding to a privileged port) and subsequently changes to another +user ID (to drop privileges), the credentials will remain root. +.Pp +User and group IDs can be specified as either numbers or names. +The syntax is similar to the one for ports. +The value +.Em unknown +matches packets of forwarded connections. +.Em unknown +can only be used with the operators +.Cm = +and +.Cm != . +Other constructs like +.Cm user \*(Ge unknown +are invalid. +Forwarded packets with unknown user and group ID match only rules +that explicitly compare against +.Em unknown +with the operators +.Cm = +or +.Cm != . +For instance +.Cm user \*(Ge 0 +does not match forwarded packets. +The following example allows only selected users to open outgoing +connections: +.Bd -literal -offset indent +block out proto { tcp, udp } all +pass out proto { tcp, udp } all user { < 1000, dhartmei } +.Ed +.Pp +The example below permits users with uid between 1000 and 1500 +to open connections: +.Bd -literal -offset indent +block out proto tcp all +pass out proto tcp from self user { 999 >< 1501 } +.Ed +.Pp +The +.Sq \&: +operator, which works for port number matching, does not work for +.Cm user +and +.Cm group +match. +.It Xo Ar flags Aq Ar a +.Pf / Ns Aq Ar b +.No \*(Ba / Ns Aq Ar b +.No \*(Ba any +.Xc +This rule only applies to TCP packets that have the flags +.Aq Ar a +set out of set +.Aq Ar b . +Flags not specified in +.Aq Ar b +are ignored. +For stateful connections, the default is +.Ar flags S/SA . +To indicate that flags should not be checked at all, specify +.Ar flags any . +The flags are: (F)IN, (S)YN, (R)ST, (P)USH, (A)CK, (U)RG, (E)CE, and C(W)R. +.Bl -tag -width Fl +.It Ar flags S/S +Flag SYN is set. +The other flags are ignored. +.It Ar flags S/SA +This is the default setting for stateful connections. +Out of SYN and ACK, exactly SYN may be set. +SYN, SYN+PSH and SYN+RST match, but SYN+ACK, ACK and ACK+RST do not. +This is more restrictive than the previous example. +.It Ar flags /SFRA +If the first set is not specified, it defaults to none. +All of SYN, FIN, RST and ACK must be unset. +.El +.Pp +Because +.Ar flags S/SA +is applied by default (unless +.Ar no state +is specified), only the initial SYN packet of a TCP handshake will create +a state for a TCP connection. +It is possible to be less restrictive, and allow state creation from +intermediate +.Pq non-SYN +packets, by specifying +.Ar flags any . +This will cause +.Xr pf 4 +to synchronize to existing connections, for instance +if one flushes the state table. +However, states created from such intermediate packets may be missing +connection details such as the TCP window scaling factor. +States which modify the packet flow, such as those affected by +.Ar af-to , +.Ar nat , +.Ar binat or +.Ar rdr +rules, +.Ar modulate No or Ar synproxy state +options, or scrubbed with +.Ar reassemble tcp +will also not be recoverable from intermediate packets. +Such connections will stall and time out. +.It Xo Ar icmp-type Aq Ar type +.Ar Op code Aq Ar code +.Xc +.It Xo Ar icmp6-type Aq Ar type +.Ar Op code Aq Ar code +.Xc +This rule only applies to ICMP or ICMPv6 packets with the specified type +and code. +Text names for ICMP types and codes are listed in +.Xr icmp 4 +and +.Xr icmp6 4 . +This parameter is only valid for rules that cover protocols ICMP or +ICMP6. +The protocol and the ICMP type indicator +.Po +.Ar icmp-type +or +.Ar icmp6-type +.Pc +must match. +.It Xo Ar tos Aq Ar string +.No \*(Ba Aq Ar number +.Xc +This rule applies to packets with the specified +.Em TOS +bits set. +.Em TOS +may be +given as one of +.Ar critical , +.Ar inetcontrol , +.Ar lowdelay , +.Ar netcontrol , +.Ar throughput , +.Ar reliability , +or one of the DiffServ Code Points: +.Ar ef , +.Ar va , +.Ar af11 No ... Ar af43 , +.Ar cs0 No ... Ar cs7 ; +or as either hex or decimal. +.Pp +For example, the following rules are identical: +.Bd -literal -offset indent +pass all tos lowdelay +pass all tos 0x10 +pass all tos 16 +.Ed +.It Ar allow-opts +By default, packets with IPv4 options or IPv6 hop-by-hop or destination +options header are blocked. +When +.Ar allow-opts +is specified for a +.Ar pass +rule, packets that pass the filter based on that rule (last matching) +do so even if they contain options. +For packets that match state, the rule that initially created the +state is used. +The implicit +.Ar pass +rule, that is used when a packet does not match +any rules, does not allow IP options or option headers. +Note that IPv6 packets with type 0 routing headers are always dropped. +.It Ar label Aq Ar string +Adds a label (name) to the rule, which can be used to identify the rule. +For instance, +pfctl -s labels +shows per-rule statistics for rules that have labels. +.Pp +The following macros can be used in labels: +.Pp +.Bl -tag -width $srcaddr -compact -offset indent +.It Ar $if +The interface. +.It Ar $srcaddr +The source IP address. +.It Ar $dstaddr +The destination IP address. +.It Ar $srcport +The source port specification. +.It Ar $dstport +The destination port specification. +.It Ar $proto +The protocol name. +.It Ar $nr +The rule number. +.El +.Pp +For example: +.Bd -literal -offset indent +ips = \&"{ 1.2.3.4, 1.2.3.5 }\&" +pass in proto tcp from any to $ips \e + port > 1023 label \&"$dstaddr:$dstport\&" +.Ed +.Pp +expands to +.Bd -literal -offset indent +pass in inet proto tcp from any to 1.2.3.4 \e + port > 1023 label \&"1.2.3.4:>1023\&" +pass in inet proto tcp from any to 1.2.3.5 \e + port > 1023 label \&"1.2.3.5:>1023\&" +.Ed +.Pp +The macro expansion for the +.Ar label +directive occurs only at configuration file parse time, not during runtime. +.It Ar ridentifier Aq Ar number +Add an identifier (number) to the rule, which can be used to correlate the rule +to pflog entries, even after ruleset updates. +.It Cm max-pkt-rate Ar number Ns / Ns Ar seconds +Measure the rate of packets matching the rule and states created by it. +When the specified rate is exceeded, the rule stops matching. +Only packets in the direction in which the state was created are considered, +so that typically requests are counted and replies are not. +For example, +to pass up to 100 ICMP packets per 10 seconds: +.Bd -literal -offset indent +block in proto icmp +pass in proto icmp max-pkt-rate 100/10 +.Ed +.Pp +When the rate is exceeded, all ICMP is blocked until the rate falls below +100 per 10 seconds again. +.Pp +.It Ar max-pkt-size Aq Ar number +Limit each packet to be no more than the specified number of bytes. +This includes the IP header, but not any layer 2 header. +.It Ar once +Create a one shot rule. +The first matching packet marks the rule as expired. +Expired rules are skipped and hidden, unless +.Xr pfctl 8 +is used in debug or verbose mode. +.Pp +.It Xo Ar queue Aq Ar queue +.No \*(Ba ( Aq Ar queue , +.Aq Ar queue ) +.Xc +Packets matching this rule will be assigned to the specified queue. +If two queues are given, packets which have a +.Em TOS +of +.Em lowdelay +and TCP ACKs with no data payload will be assigned to the second one. +See +.Sx QUEUEING +for setup details. +.Pp +For example: +.Bd -literal -offset indent +pass in proto tcp to port 25 queue mail +pass in proto tcp to port 22 queue(ssh_bulk, ssh_prio) +.Ed +.It Cm set prio Ar priority | Pq Ar priority , priority +Packets matching this rule will be assigned a specific queueing priority. +Priorities are assigned as integers 0 through 7. +If the packet is transmitted on a +.Xr vlan 4 +interface, the queueing priority will be written as the priority +code point in the 802.1Q VLAN header. +If two priorities are given, TCP ACKs with no data payload and packets +which have a TOS of +.Cm lowdelay +will be assigned to the second one. +.Pp +For example: +.Bd -literal -offset indent +pass in proto tcp to port 25 set prio 2 +pass in proto tcp to port 22 set prio (2, 5) +.Ed +.It Oo Cm \&! Oc Ns Cm received-on Ar interface +Only match packets which were received on the specified +.Ar interface +(or interface group). +.Ar any +will match any existing interface except loopback ones. +.It Ar tag Aq Ar string +Packets matching this rule will be tagged with the +specified string. +The tag acts as an internal marker that can be used to +identify these packets later on. +This can be used, for example, to provide trust between +interfaces and to determine if packets have been +processed by translation rules. +Tags are +.Qq sticky , +meaning that the packet will be tagged even if the rule +is not the last matching rule. +Further matching rules can replace the tag with a +new one but will not remove a previously applied tag. +A packet is only ever assigned one tag at a time. +Packet tagging can be done during +.Ar nat , +.Ar rdr , +.Ar binat +or +.Ar ether +rules in addition to filter rules. +Tags take the same macros as labels (see above). +.It Ar tagged Aq Ar string +Used with filter, translation or scrub rules +to specify that packets must already +be tagged with the given tag in order to match the rule. +.It Ar rtable Aq Ar number +Used to select an alternate routing table for the routing lookup. +Only effective before the route lookup happened, i.e. when filtering inbound. +.It Xo Ar divert-to Aq Ar host +.Ar port Aq Ar port +.Xc +Used to +.Xr divert 4 +packets to the given divert +.Ar port . +Historically +.Ox pf has another meaning for this, and +.Fx pf uses +this syntax to support +.Xr divert 4 instead. Hence, +.Ar host +has no meaning and can be set to anything like 127.0.0.1. +If a packet is re-injected and does not change direction then it will not be +re-diverted. +.It Ar divert-reply +It has no meaning in +.Fx pf . +.It Ar probability Aq Ar number +A probability attribute can be attached to a rule, with a value set between +0 and 1, bounds not included. +In that case, the rule will be honoured using the given probability value +only. +For example, the following rule will drop 20% of incoming ICMP packets: +.Bd -literal -offset indent +block in proto icmp probability 20% +.Ed +.It Cm state limiter Ar name Oo Cm (limiter options) Oc +Use the specified state limiter to restrict the creation of states +by this rule. +By default if capacity is not available, the packet gets blocked +and ruleset evaluation stops. +Use +.Ic no-match +option to change default behavior such rule is ignored and ruleset +evaluation continues with next rule. +See the +.Sx State Limiters +section for more information. +.Pp +.It Cm source limiter Ar name Oo Cm (limiter options) Oc +Use the specified source limiter to restrict the creation of states +by this rule. +By default if capacity is not available, the packet gets blocked +and ruleset evaluation stops. +Use +.Ic no-match +option to change default behavior such rule is ignored and ruleset +evaluation continues with next rule. +See the +.Sx Source Limiters +section for more information. +.Pp +.It Ar prio Aq Ar number +Only match packets which have the given queueing priority assigned. +.El +.Sh ROUTING +If a packet matches a rule with a route option set, the packet filter will +route the packet according to the type of route option. +When such a rule creates state, the route option is also applied to all +packets matching the same connection. +.Bl -tag -width xxxx +.It Ar route-to +The +.Ar route-to +option routes the packet to the specified interface with an address +for the next hop. +When a +.Ar route-to +rule creates state, only packets that pass in the same direction as the +filter rule specifies will be routed in this way. +Packets passing in the opposite direction (replies) are not affected +and are routed normally. +.It Ar reply-to +The +.Ar reply-to +option is similar to +.Ar route-to , +but routes packets that pass in the opposite direction (replies) to the +specified interface. +Opposite direction is only defined in the context of a state entry, and +.Ar reply-to +is useful only in rules that create state. +It can be used on systems with multiple external connections to +route all outgoing packets of a connection through the interface +the incoming connection arrived through (symmetric routing enforcement). +.It Ar dup-to +The +.Ar dup-to +option creates a duplicate of the packet and routes it like +.Ar route-to . +The original packet gets routed as it normally would. +.El +.Pp +Unlike the kernel's normal forwarding path, the route option forwarding +path does not drop broadcast or multicast traffic when the output +interface has been overridden by a route option. +If a +.Ar route-to , +.Ar reply-to , +or +.Ar dup-to +rule matches traffic destined to a broadcast address (either the +limited broadcast or a subnet-directed broadcast) or to an IPv4/IPv6 +multicast address, the packet is forwarded out the specified interface, +which may cross broadcast domains. +.Pp +Rulesets that use +.Ar route-to , +.Ar reply-to , +or +.Ar dup-to +with a permissive destination +.Po e.g.\& +.Li from any to any +.Pc +can plug this leak with explicit +.Ar block out +rules on the route option's target interface. +To avoid blocking the router's own broadcast or multicast traffic, +scope the block rules to forwarded packets with the +.Ar received-on any +qualifier. +For example, assuming +.Li $wan +is the +.Ar route-to +target interface: +.Bd -literal -offset indent +block out quick on $wan inet from any to 255.255.255.255 received-on any +block out quick on $wan inet from any to ($wan:broadcast) received-on any +block out quick on $wan inet from any to 224.0.0.0/4 received-on any +block out quick on $wan inet6 from any to ff00::/8 received-on any +.Ed +.Pp +One block-out rule set is needed per interface that may be used as +a route option target. +.Sh POOL OPTIONS +For +.Ar nat +and +.Ar rdr +rules, (as well as for the +.Ar route-to , +.Ar reply-to +and +.Ar dup-to +rule options) for which there is a single redirection address which has a +subnet mask smaller than 32 for IPv4 or 128 for IPv6 (more than one IP +address), a variety of different methods for assigning this address can be +used: +.Bl -tag -width xxxx +.It Ar bitmask +The +.Ar bitmask +option applies the network portion of the redirection address to the address +to be modified (source with +.Ar nat , +destination with +.Ar rdr ) . +.It Ar random +The +.Ar random +option selects an address at random within the defined block of addresses. +.It Ar source-hash +The +.Ar source-hash +option uses a hash of the source address to determine the redirection address, +ensuring that the redirection address is always the same for a given source. +An optional key can be specified after this keyword either in hex or as a +string; by default +.Xr pfctl 8 +randomly generates a key for source-hash every time the +ruleset is reloaded. +.It Ar round-robin +The +.Ar round-robin +option loops through the redirection address(es). +.Pp +When more than one redirection address is specified, +.Ar bitmask +is not permitted as a pool type. +.It Ar static-port +With +.Ar nat +rules, the +.Ar static-port +option prevents +.Xr pf 4 +from modifying the source port on TCP and UDP packets. +.It Xo Ar map-e-portset Aq Ar psid-offset +.No / Aq Ar psid-len +.No / Aq Ar psid +.Xc +With +.Ar nat +rules, the +.Ar map-e-portset +option enables the source port translation of MAP-E (RFC 7597) Customer Edge. +In order to make the host act as a MAP-E Customer Edge, setting up a tunneling +interface and pass rules for encapsulated packets are required in addition +to the map-e-portset nat rule. +.Pp +For example: +.Bd -literal -offset indent +nat on $gif_mape_if from $int_if:network to any \e + -> $ipv4_mape_src map-e-portset 6/8/0x34 +.Ed +.Pp +sets PSID offset 6, PSID length 8, PSID 0x34. +.It Ar endpoint-independent +With +.Ar nat +rules, the +.Ar endpoint-independent +option caues +.Xr pf 4 +to always map connections from a UDP source address and port to the same +NAT address and port. +This feature implements "full-cone" NAT behavior. +.El +.Pp +Additionally, options +.Ar sticky-address +and +.Ar prefer-ipv6-nexthop +can be specified to influence how IP addresses selected from pools. +.Pp +The +.Ar sticky-address +option can be specified to help ensure that multiple connections from the +same source are mapped to the same redirection address. +This option can be used with the +.Ar random +and +.Ar round-robin +pool options. +Note that by default these associations are destroyed as soon as there are +no longer states which refer to them; in order to make the mappings last +beyond the lifetime of the states, increase the global options with +.Ar set timeout src.track . +See +.Sx STATEFUL TRACKING OPTIONS +for more ways to control the source tracking. +.Pp +The +.Ar prefer-ipv6-nexthop +option allows for IPv6 addresses to be used as the nexthop +for IPv4 packets routed with the +.Ar route-to +rule option. If a table is used with IPv4 and IPv6 addresses, first the IPv6 addresses +will be used in round-robin fashion, then IPv4 addresses. +.Sh STATE MODULATION +Much of the security derived from TCP is attributable to how well the +initial sequence numbers (ISNs) are chosen. +Some popular stack implementations choose +.Em very +poor ISNs and thus are normally susceptible to ISN prediction exploits. +By applying a +.Ar modulate state +rule to a TCP connection, +.Xr pf 4 +will create a high quality random sequence number for each connection +endpoint. +.Pp +The +.Ar modulate state +directive implicitly keeps state on the rule and is +only applicable to TCP connections. +.Pp +For instance: +.Bd -literal -offset indent +block all +pass out proto tcp from any to any modulate state +pass in proto tcp from any to any port 25 flags S/SFRA modulate state +.Ed +.Pp +Note that modulated connections will not recover when the state table +is lost (firewall reboot, flushing the state table, etc...). +.Xr pf 4 +will not be able to infer a connection again after the state table flushes +the connection's modulator. +When the state is lost, the connection may be left dangling until the +respective endpoints time out the connection. +It is possible on a fast local network for the endpoints to start an ACK +storm while trying to resynchronize after the loss of the modulator. +The default +.Ar flags +settings (or a more strict equivalent) should be used on +.Ar modulate state +rules to prevent ACK storms. +.Pp +Note that alternative methods are available +to prevent loss of the state table +and allow for firewall failover. +See +.Xr carp 4 +and +.Xr pfsync 4 +for further information. +.Sh SYN PROXY +By default, +.Xr pf 4 +passes packets that are part of a +.Xr tcp 4 +handshake between the endpoints. +The +.Ar synproxy state +option can be used to cause +.Xr pf 4 +itself to complete the handshake with the active endpoint, perform a handshake +with the passive endpoint, and then forward packets between the endpoints. +.Pp +No packets are sent to the passive endpoint before the active endpoint has +completed the handshake, hence so-called SYN floods with spoofed source +addresses will not reach the passive endpoint, as the sender can't complete the +handshake. +.Pp +The proxy is transparent to both endpoints, they each see a single +connection from/to the other endpoint. +.Xr pf 4 +chooses random initial sequence numbers for both handshakes. +Once the handshakes are completed, the sequence number modulators +(see previous section) are used to translate further packets of the +connection. +.Ar synproxy state +includes +.Ar modulate state . +.Pp +Rules with +.Ar synproxy +will not work if +.Xr pf 4 +operates on a +.Xr bridge 4 . +Also they act on incoming SYN packets only. +.Pp +Example: +.Bd -literal -offset indent +pass in proto tcp from any to any port www synproxy state +.Ed +.Ss State Limiters +State limiters provide a mechanism to limit the number of states created, +or the rate of state creation, +by a set of rules. +State limiters are configured and loaded with the main ruleset, but +can be used by rules in any anchor. +The overall number of states is still subject to the limit set with +.Cm set limit states , +but the number of states created by a subset of rules can be provided +by a state limiter. +.Pp +A state limiter is configured with the following statement: +.Pp +.Bl -tag -width xxxx -compact +.It Cm state limiter Ar name +Each state limiter is identified by a unique name. +.El +.Pp +State limiters support the following configuration: +.Pp +.Bl -tag -width xxxx -compact +.It Cm id Ar number +A unique identifier between 1 and 255. +This configuration is required. +.It Cm limit Ar number +Specify the maximum number of states. +This configuration is required. +.It Cm rate Ar number Ns / Ns Ar seconds +Limit the rate at which states can be created over a time interval. +The connection rate is an approximation calculated as a moving +average. +.El +.Pp +Pass rules can specify a state limiter using the +.Cm state limiter Ar name +option. +If the number of states allowed has hit the limit, the pass rule +does not match and ruleset evaluation continues past it. +.Pp +An example use case for a state limiter is to restrict the number of +connections allowed to a service that is accessible via multiple +protocols, e.g. a DNS server that can be accessed by both TCP and +UDP on port 53, DNS-over-TLS on TCP port 853, and DNS-over-HTTPS +on TCP port 443 can be limited to 1000 concurrent connections: +.Pp +.Bd -literal -offset indent -compact +state limiter "dns-server" id 1 limit 1000 + +pass in proto { tcp udp } to port domain state limiter "dns-server" +pass in proto tcp to port { 853 443 } state limiter "dns-server" +.Ed +.Ss Source Limiters +Source limiters apply limits on the number of states, +or the rate of state creation, +for connections coming from a source address or network for a set +of rules. +Source limiters are configured and loaded with the main ruleset, but +can be used by rules in any anchor. +The overall number of states is still subject to the limit set with +.Cm set limit states , +but limits on states for a subset of source addresses and rules can +be provided with source limiters. +.Pp +Source address entries in source pools are created on demand, +and are used to account for the states created for each source +address or network. +A source limiter specifies the maximum number of source address +entries it will track, and can be configured to mask bits in network +prefixes to have source entries cover larger portions of the address +space if needed. +.Pp +A source limiter is configured with the following statement: +.Pp +.Bl -tag -width xxxx -compact +.It Cm source limiter Ar name +Each source limiter is uniquely identified by the specified name. +.El +.Pp +Source limiter support the following configuration: +.Pp +.Bl -tag -width xxxx -compact +.It Cm id Ar number +A unique identifier between 1 and 255. +This configuration is required. +.It Cm entries Ar number +Specify the maximum number of source address entries. +This configuration is required. +.It Cm limit Ar number +Specify the maximum number of states for each source address entry. +This configuration is required. +.It Cm rate Ar number Ns / Ns Ar seconds +Limit the rate at which states can be created by each source address +entry over a time interval. +The connection rate is an approximation calculated as a moving +average. +.It Cm inet mask Ar prefixlen +Mask IPv4 source addresses using the prefix length specified with +.Ar prefixlen +when creating an address entry. +The default IPv4 prefix length is 32 bits. +.It Cm inet6 mask Ar prefixlen +Mask IPv6 source addresses using the prefix length specified with +.Ar prefixlen +when creating an address entry. +The default IPv6 prefix length is 128 bits. +.It Cm table < Ns Ar table Ns > Cm above Ar hwm Op Cm below Ar lwm +Add the address to the specified +.Ar table +when the number of states goes above the +.Ar hwm +high water mark. +The address will be removed from the table when the number of states +drops below the +.Ar lwm +low water mark. +The default low water mark is 0. +.El +.Pp +Pass rules can specify a source limiter using the +.Cm source limiter Ar name +option. +.Pp +An example use for a source limiter is the mitigation of denial of +service caused by the exhaustion of firewall resources by network +or port scans from outside the network. +The states created by any one scanner from any one source address +can be limited to avoid impacting other sources. +Below, up to 10000 IPv4 hosts and IPv6 /64 networks from the external +network are each limited to a maximum of 1000 connections, and are +rate limited to creating 100 states over a 10 second interval: +.Pp +.Bd -literal -offset indent -compact +source limiter "internet" id 1 entries 10000 \e + limit 1000 rate 100/10 \e + inet6 mask 64 + +block in on egress +pass in on egress source limiter "internet" +.Ed +.Sh STATEFUL TRACKING OPTIONS +A number of options related to stateful tracking can be applied on a +per-rule basis. +.Ar keep state , +.Ar modulate state +and +.Ar synproxy state +support these options, and +.Ar keep state +must be specified explicitly to apply options to a rule. +.Pp +.Bl -tag -width xxxx -compact +.It Ar max Aq Ar number +Limits the number of concurrent states the rule may create. +When this limit is reached, further packets that would create +state are dropped until existing states time out. +.It Ar no-sync +Prevent state changes for states created by this rule from appearing on the +.Xr pfsync 4 +interface. +.It Xo Aq Ar timeout +.Aq Ar seconds +.Xc +Changes the timeout values used for states created by this rule. +For a list of all valid timeout names, see +.Sx OPTIONS +above. +.It Ar sloppy +Uses a sloppy TCP connection tracker that does not check sequence +numbers at all, which makes insertion and ICMP teardown attacks way +easier. +This is intended to be used in situations where one does not see all +packets of a connection, e.g. in asymmetric routing situations. +Cannot be used with modulate or synproxy state. +.It Ar pflow +States created by this rule are exported on the +.Xr pflow 4 +interface. +.It Ar allow-related +Automatically allow connections related to this one, regardless of rules that +might otherwise affect them. +This currently only applies to SCTP multihomed connection. +.El +.Pp +Multiple options can be specified, separated by commas: +.Bd -literal -offset indent +pass in proto tcp from any to any \e + port www keep state \e + (max 100, source-track rule, max-src-nodes 75, \e + max-src-states 3, tcp.established 60, tcp.closing 5) +.Ed +.Pp +When the +.Ar source-track +keyword is specified, the number of states per source IP is tracked. +.Pp +.Bl -tag -width xxxx -compact +.It Ar source-track rule +The maximum number of states created by this rule is limited by the rule's +.Ar max-src-nodes +and +.Ar max-src-states +options. +Only state entries created by this particular rule count toward the rule's +limits. +.It Ar source-track global +The number of states created by all rules that use this option is limited. +Each rule can specify different +.Ar max-src-nodes +and +.Ar max-src-states +options, however state entries created by any participating rule count towards +each individual rule's limits. +.El +.Pp +The following limits can be set: +.Pp +.Bl -tag -width xxxx -compact +.It Ar max-src-nodes Aq Ar number +Limits the maximum number of source addresses which can simultaneously +have state table entries. +.It Ar max-src-states Aq Ar number +Limits the maximum number of simultaneous state entries that a single +source address can create with this rule. +.El +.Pp +For stateful TCP connections, limits on established connections (connections +which have completed the TCP 3-way handshake) can also be enforced +per source IP. +.Pp +.Bl -tag -width xxxx -compact +.It Ar max-src-conn Aq Ar number +Limits the maximum number of simultaneous TCP connections which have +completed the 3-way handshake that a single host can make. +.It Xo Ar max-src-conn-rate Aq Ar number +.No / Aq Ar seconds +.Xc +Limit the rate of new connections over a time interval. +The connection rate is an approximation calculated as a moving average. +.El +.Pp +When one of these limits is reached, further packets that would create +state are dropped until existing states time out. +.Pp +Because the 3-way handshake ensures that the source address is not being +spoofed, more aggressive action can be taken based on these limits. +With the +.Ar overload Aq Ar table +state option, source IP addresses which hit either of the limits on +established connections will be added to the named table. +This table can be used in the ruleset to block further activity from +the offending host, redirect it to a tarpit process, or restrict its +bandwidth. +.Pp +The optional +.Ar flush +keyword kills all states created by the matching rule which originate +from the host which exceeds these limits. +The +.Ar global +modifier to the flush command kills all states originating from the +offending host, regardless of which rule created the state. +.Pp +For example, the following rules will protect the webserver against +hosts making more than 100 connections in 10 seconds. +Any host which connects faster than this rate will have its address added +to the +.Aq bad_hosts +table and have all states originating from it flushed. +Any new packets arriving from this host will be dropped unconditionally +by the block rule. +.Bd -literal -offset indent +block quick from +pass in on $ext_if proto tcp to $webserver port www keep state \e + (max-src-conn-rate 100/10, overload flush global) +.Ed +.Sh OPERATING SYSTEM FINGERPRINTING +Passive OS Fingerprinting is a mechanism to inspect nuances of a TCP +connection's initial SYN packet and guess at the host's operating system. +Unfortunately these nuances are easily spoofed by an attacker so the +fingerprint is not useful in making security decisions. +But the fingerprint is typically accurate enough to make policy decisions +upon. +.Pp +The fingerprints may be specified by operating system class, by +version, or by subtype/patchlevel. +The class of an operating system is typically the vendor or genre +and would be +.Ox +for the +.Xr pf 4 +firewall itself. +The version of the oldest available +.Ox +release on the main FTP site +would be 2.6 and the fingerprint would be written +.Pp +.Dl \&"OpenBSD 2.6\&" +.Pp +The subtype of an operating system is typically used to describe the +patchlevel if that patch led to changes in the TCP stack behavior. +In the case of +.Ox , +the only subtype is for a fingerprint that was +normalized by the +.Ar no-df +scrub option and would be specified as +.Pp +.Dl \&"OpenBSD 3.3 no-df\&" +.Pp +Fingerprints for most popular operating systems are provided by +.Xr pf.os 5 . +Once +.Xr pf 4 +is running, a complete list of known operating system fingerprints may +be listed by running: +.Pp +.Dl # pfctl -so +.Pp +Filter rules can enforce policy at any level of operating system specification +assuming a fingerprint is present. +Policy could limit traffic to approved operating systems or even ban traffic +from hosts that aren't at the latest service pack. +.Pp +The +.Ar unknown +class can also be used as the fingerprint which will match packets for +which no operating system fingerprint is known. +.Pp +Examples: +.Bd -literal -offset indent +pass out proto tcp from any os OpenBSD +block out proto tcp from any os Doors +block out proto tcp from any os "Doors PT" +block out proto tcp from any os "Doors PT SP3" +block out from any os "unknown" +pass on lo0 proto tcp from any os "OpenBSD 3.3 lo0" +.Ed +.Pp +Operating system fingerprinting is limited only to the TCP SYN packet. +This means that it will not work on other protocols and will not match +a currently established connection. +.Pp +Caveat: operating system fingerprints are occasionally wrong. +There are three problems: an attacker can trivially craft packets to +appear as any operating system; +an operating system patch could change the stack behavior and no fingerprints +will match it until the database is updated; +and multiple operating systems may have the same fingerprint. +.Sh BLOCKING SPOOFED TRAFFIC +"Spoofing" is the faking of IP addresses, typically for malicious +purposes. +The +.Ar antispoof +directive expands to a set of filter rules which will block all +traffic with a source IP from the network(s) directly connected +to the specified interface(s) from entering the system through +any other interface. +.Pp +For example, the line +.Bd -literal -offset indent +antispoof for lo0 +.Ed +.Pp +expands to +.Bd -literal -offset indent +block drop in on ! lo0 inet from 127.0.0.1/8 to any +block drop in on ! lo0 inet6 from ::1 to any +.Ed +.Pp +For non-loopback interfaces, there are additional rules to block incoming +packets with a source IP address identical to the interface's IP(s). +For example, assuming the interface wi0 had an IP address of 10.0.0.1 and a +netmask of 255.255.255.0, +the line +.Bd -literal -offset indent +antispoof for wi0 inet +.Ed +.Pp +expands to +.Bd -literal -offset indent +block drop in on ! wi0 inet from 10.0.0.0/24 to any +block drop in inet from 10.0.0.1 to any +.Ed +.Pp +Caveat: Rules created by the +.Ar antispoof +directive interfere with packets sent over loopback interfaces +to local addresses. +One should pass these explicitly. +.Sh FRAGMENT HANDLING +The size of IP datagrams (packets) can be significantly larger than the +maximum transmission unit (MTU) of the network. +In cases when it is necessary or more efficient to send such large packets, +the large packet will be fragmented into many smaller packets that will each +fit onto the wire. +Unfortunately for a firewalling device, only the first logical fragment will +contain the necessary header information for the subprotocol that allows +.Xr pf 4 +to filter on things such as TCP ports or to perform NAT. +.Pp +Besides the use of +.Ar set reassemble +option or +.Ar scrub +rules as described in +.Sx TRAFFIC NORMALIZATION +above, there are three options for handling fragments in the packet filter. +.Pp +One alternative is to filter individual fragments with filter rules. +If no +.Ar scrub +rule applies to a fragment or +.Ar set reassemble +is set to +.Cm no +, it is passed to the filter. +Filter rules with matching IP header parameters decide whether the +fragment is passed or blocked, in the same way as complete packets +are filtered. +Without reassembly, fragments can only be filtered based on IP header +fields (source/destination address, protocol), since subprotocol header +fields are not available (TCP/UDP port numbers, ICMP code/type). +The +.Ar fragment +option can be used to restrict filter rules to apply only to +fragments, but not complete packets. +Filter rules without the +.Ar fragment +option still apply to fragments, if they only specify IP header fields. +For instance, the rule +.Bd -literal -offset indent +pass in proto tcp from any to any port 80 +.Ed +.Pp +never applies to a fragment, even if the fragment is part of a TCP +packet with destination port 80, because without reassembly this information +is not available for each fragment. +This also means that fragments cannot create new or match existing +state table entries, which makes stateful filtering and address +translation (NAT, redirection) for fragments impossible. +.Pp +It's also possible to reassemble only certain fragments by specifying +source or destination addresses or protocols as parameters in +.Ar scrub +rules. +.Pp +In most cases, the benefits of reassembly outweigh the additional +memory cost, and it's recommended to use +.Ar set reassemble +option or +.Ar scrub +rules with the +.Ar fragment reassemble +modifier to reassemble +all fragments. +.Pp +The memory allocated for fragment caching can be limited using +.Xr pfctl 8 . +Once this limit is reached, fragments that would have to be cached +are dropped until other entries time out. +The timeout value can also be adjusted. +.Pp +When forwarding reassembled IPv6 packets, pf refragments them with +the original maximum fragment size. +This allows the sender to determine the optimal fragment size by +path MTU discovery. +.Sh ANCHORS +Besides the main ruleset, +.Xr pfctl 8 +can load rulesets into +.Ar anchor +attachment points. +An +.Ar anchor +is a container that can hold rules, address tables, and other anchors. +.Pp +An +.Ar anchor +has a name which specifies the path where +.Xr pfctl 8 +can be used to access the anchor to perform operations on it, such as +attaching child anchors to it or loading rules into it. +Anchors may be nested, with components separated by +.Sq / +characters, similar to how file system hierarchies are laid out. +The main ruleset is actually the default anchor, so filter and +translation rules, for example, may also be contained in any anchor. +.Pp +An anchor can reference another +.Ar anchor +attachment point +using the following kinds +of rules: +.Bl -tag -width xxxx +.It Ar nat-anchor Aq Ar name +Evaluates the +.Ar nat +rules in the specified +.Ar anchor . +.It Ar rdr-anchor Aq Ar name +Evaluates the +.Ar rdr +rules in the specified +.Ar anchor . +.It Ar binat-anchor Aq Ar name +Evaluates the +.Ar binat +rules in the specified +.Ar anchor . +.It Ar anchor Aq Ar name +Evaluates the filter rules in the specified +.Ar anchor . +.It Xo Ar load anchor +.Aq Ar name +.Ar from Aq Ar file +.Xc +Loads the rules from the specified file into the +anchor +.Ar name . +.El +.Pp +When evaluation of the main ruleset reaches an +.Ar anchor +rule, +.Xr pf 4 +will proceed to evaluate all rules specified in that anchor. +.Pp +Matching filter and translation rules marked with the +.Ar quick +option are final and abort the evaluation of the rules in other +anchors and the main ruleset. +If the +.Ar anchor +itself is marked with the +.Ar quick +option, +ruleset evaluation will terminate when the anchor is exited if the packet is +matched by any rule within the anchor. +.Pp +.Ar anchor +rules are evaluated relative to the anchor in which they are contained. +For example, all +.Ar anchor +rules specified in the main ruleset will reference anchor +attachment points underneath the main ruleset, and +.Ar anchor +rules specified in a file loaded from a +.Ar load anchor +rule will be attached under that anchor point. +.Pp +Rules may be contained in +.Ar anchor +attachment points which do not contain any rules when the main ruleset +is loaded, and later such anchors can be manipulated through +.Xr pfctl 8 +without reloading the main ruleset or other anchors. +For example, +.Bd -literal -offset indent +ext_if = \&"kue0\&" +block on $ext_if all +anchor spam +pass out on $ext_if all +pass in on $ext_if proto tcp from any \e + to $ext_if port smtp +.Ed +.Pp +blocks all packets on the external interface by default, then evaluates +all rules in the +.Ar anchor +named "spam", and finally passes all outgoing connections and +incoming connections to port 25. +.Bd -literal -offset indent +# echo \&"block in quick from 1.2.3.4 to any\&" \&| \e + pfctl -a spam -f - +.Ed +.Pp +This loads a single rule into the +.Ar anchor , +which blocks all packets from a specific address. +.Pp +The anchor can also be populated by adding a +.Ar load anchor +rule after the +.Ar anchor +rule: +.Bd -literal -offset indent +anchor spam +load anchor spam from "/etc/pf-spam.conf" +.Ed +.Pp +When +.Xr pfctl 8 +loads +.Nm pf.conf , +it will also load all the rules from the file +.Pa /etc/pf-spam.conf +into the anchor. +.Pp +Optionally, +.Ar anchor +rules can specify packet filtering parameters using the same syntax as +filter rules. +When parameters are used, the +.Ar anchor +rule is only evaluated for matching packets. +This allows conditional evaluation of anchors, like: +.Bd -literal -offset indent +block on $ext_if all +anchor spam proto tcp from any to any port smtp +pass out on $ext_if all +pass in on $ext_if proto tcp from any to $ext_if port smtp +.Ed +.Pp +The rules inside +.Ar anchor +spam are only evaluated for +.Ar tcp +packets with destination port 25. +Hence, +.Bd -literal -offset indent +# echo \&"block in quick from 1.2.3.4 to any" \&| \e + pfctl -a spam -f - +.Ed +.Pp +will only block connections from 1.2.3.4 to port 25. +.Pp +Anchors may end with the asterisk +.Pq Sq * +character, which signifies that all anchors attached at that point +should be evaluated in the alphabetical ordering of their anchor name. +For example, +.Bd -literal -offset indent +anchor "spam/*" +.Ed +.Pp +will evaluate each rule in each anchor attached to the +.Li spam +anchor. +Note that it will only evaluate anchors that are directly attached to the +.Li spam +anchor, and will not descend to evaluate anchors recursively. +.Pp +Since anchors are evaluated relative to the anchor in which they are +contained, there is a mechanism for accessing the parent and ancestor +anchors of a given anchor. +Similar to file system path name resolution, if the sequence +.Dq .. +appears as an anchor path component, the parent anchor of the current +anchor in the path evaluation at that point will become the new current +anchor. +As an example, consider the following: +.Bd -literal -offset indent +# echo ' anchor "spam/allowed" ' | pfctl -f - +# echo -e ' anchor "../banned" \en pass' | \e + pfctl -a spam/allowed -f - +.Ed +.Pp +Evaluation of the main ruleset will lead into the +.Li spam/allowed +anchor, which will evaluate the rules in the +.Li spam/banned +anchor, if any, before finally evaluating the +.Ar pass +rule. +.Pp +An +.Ar anchor +rule can also contain a filter ruleset in a brace-delimited block. +In that case, no separate loading of rules into the anchor +is required. +Brace delimited blocks may contain rules or other brace-delimited blocks. +When an anchor is populated this way, the anchor name becomes optional. +.Bd -literal -offset indent +anchor "external" on $ext_if { + block + anchor out { + pass proto tcp from any to port { 25, 80, 443 } + } + pass in proto tcp to any port 22 +} +.Ed +.Pp +Since the parser specification for anchor names is a string, any +reference to an anchor name containing +.Sq / +characters will require double quote +.Pq Sq \&" +characters around the anchor name. +.Sh SCTP CONSIDERATIONS +.Xr pf 4 +supports +.Xr sctp 4 +connections. +It can match ports, track state and NAT SCTP traffic. +However, it will not alter port numbers during nat or rdr translations. +Doing so would break SCTP multihoming. +.Sh TRANSLATION EXAMPLES +This example maps incoming requests on port 80 to port 8080, on +which a daemon is running (because, for example, it is not run as root, +and therefore lacks permission to bind to port 80). +.Bd -literal -offset indent +# use a macro for the interface name, so it can be changed easily +ext_if = \&"ne3\&" + +# map daemon on 8080 to appear to be on 80 +match in on $ext_if proto tcp from any to any port 80 \e + rdr-to 127.0.0.1 port 8080 +.Ed +.Pp +If a +.Ar pass +rule is used with the +.Ar quick +modifier, packets matching the translation rule are passed without +inspecting subsequent filter rules: +.Bd -literal -offset indent +pass in quick on $ext_if proto tcp from any to any port 80 \e + rdr-to 127.0.0.1 port 8080 +.Ed +.Pp +In the example below, vlan12 is configured as 192.168.168.1; +the machine translates all packets coming from 192.168.168.0/24 to 204.92.77.111 +when they are going out any interface except vlan12. +This has the net effect of making traffic from the 192.168.168.0/24 +network appear as though it is the Internet routable address +204.92.77.111 to nodes behind any interface on the router except +for the nodes on vlan12. +(Thus, 192.168.168.1 can talk to the 192.168.168.0/24 nodes.) +.Bd -literal -offset indent +match out on ! vlan12 from 192.168.168.0/24 to any nat-to 204.92.77.111 +.Ed +.Pp +This longer example uses both a NAT and a redirection. +The external interface has the address 157.161.48.183. +On localhost, we are running +.Xr ftp-proxy 8 , +waiting for FTP sessions to be redirected to it. +The three mandatory anchors for +.Xr ftp-proxy 8 +are omitted from this example; see the +.Xr ftp-proxy 8 +manpage. +.Bd -literal -offset indent +# NAT +# Translate outgoing packets' source addresses (any protocol). +# In this case, any address but the gateway's external address is mapped. +pass out on $ext_if inet from ! ($ext_if) to any nat-to ($ext_if) + +# NAT PROXYING +# Map outgoing packets' source port to an assigned proxy port instead of +# an arbitrary port. +# In this case, proxy outgoing isakmp with port 500 on the gateway. +pass out on $ext_if inet proto udp from any port = isakmp to any \e + nat-to ($ext_if) port 500 + +# BINAT +# Translate outgoing packets' source address (any protocol). +# Translate incoming packets' destination address to an internal machine +# (bidirectional). +pass on $ext_if from 10.1.2.150 to any binat-to $ext_if + +# Translate packets arriving on $peer_if addressed to 172.22.16.0/20 +# to the corresponding address in 172.21.16.0/20 (bidirectional). +pass on $peer_if from 172.21.16.0/20 to any binat-to 172.22.16.0/20 + +# RDR +# Translate incoming packets' destination addresses. +# As an example, redirect a TCP and UDP port to an internal machine. +pass in on $ext_if inet proto tcp from any to ($ext_if) port 8080 \e + rdr-to 10.1.2.151 port 22 +pass in on $ext_if inet proto udp from any to ($ext_if) port 8080 \e + rdr-to 10.1.2.151 port 53 + +# RDR +# Translate outgoing ftp control connections to send them to localhost +# for proxying with ftp-proxy(8) running on port 8021. +pass in on $int_if proto tcp from any to any port 21 \e + rdr-to 127.0.0.1 port 8021 +.Ed +.Pp +In this example, a NAT gateway is set up to translate internal addresses +using a pool of public addresses (192.0.2.16/28) and to redirect +incoming web server connections to a group of web servers on the internal +network. +.Bd -literal -offset indent +# NAT LOAD BALANCE +# Translate outgoing packets' source addresses using an address pool. +# A given source address is always translated to the same pool address by +# using the source-hash keyword. +pass out on $ext_if inet from any to any nat-to 192.0.2.16/28 source-hash + +# RDR ROUND ROBIN +# Translate incoming web server connections to a group of web servers on +# the internal network. +pass in on $ext_if proto tcp from any to any port 80 \e + rdr-to { 10.1.2.155, 10.1.2.160, 10.1.2.161 } round-robin +.Ed +.Sh COMPATIBILITY TRANSLATION EXAMPLES +In the example below, the machine sits between a fake internal 144.19.74.* +network, and a routable external IP of 204.92.77.100. +The +.Ar no nat +rule excludes protocol AH from being translated. +.Bd -literal -offset indent +# NAT +no nat on $ext_if proto ah from 144.19.74.0/24 to any +nat on $ext_if from 144.19.74.0/24 to any -> 204.92.77.100 +.Ed +.Pp +In the example below, packets bound for one specific server, as well as those +generated by the sysadmins are not proxied; all other connections are. +.Bd -literal -offset indent +# RDR +no rdr on $int_if proto { tcp, udp } from any to $server port 80 +no rdr on $int_if proto { tcp, udp } from $sysadmins to any port 80 +rdr on $int_if proto { tcp, udp } from any to any port 80 \e + -> 127.0.0.1 port 80 +.Ed +.Sh FILTER EXAMPLES +.Bd -literal -offset indent +# The external interface is kue0 +# (157.161.48.183, the only routable address) +# and the private network is 10.0.0.0/8, for which we are doing NAT. + +# Reassemble incoming traffic +set reassemble yes + +# use a macro for the interface name, so it can be changed easily +ext_if = \&"kue0\&" + +# block and log everything by default +block return log on $ext_if all + +# block anything coming from source we have no back routes for +block in from no-route to any + +# block packets whose ingress interface does not match the one in +# the route back to their source address +block in from urpf-failed to any + +# block and log outgoing packets that do not have our address as source, +# they are either spoofed or something is misconfigured (NAT disabled, +# for instance), we want to be nice and do not send out garbage. +block out log quick on $ext_if from ! 157.161.48.183 to any + +# silently drop broadcasts (cable modem noise) +block in quick on $ext_if from any to 255.255.255.255 + +# block and log incoming packets from reserved address space and invalid +# addresses, they are either spoofed or misconfigured, we cannot reply to +# them anyway (hence, no return-rst). +block in log quick on $ext_if from { 10.0.0.0/8, 172.16.0.0/12, \e + 192.168.0.0/16, 255.255.255.255/32 } to any + +# ICMP + +# pass out/in certain ICMP queries and keep state (ping) +# state matching is done on host addresses and ICMP id (not type/code), +# so replies (like 0/0 for 8/0) will match queries +# ICMP error messages (which always refer to a TCP/UDP packet) are +# handled by the TCP/UDP states +pass on $ext_if inet proto icmp all icmp-type 8 code 0 + +# UDP + +# pass out all UDP connections and keep state +pass out on $ext_if proto udp all + +# pass in certain UDP connections and keep state (DNS) +pass in on $ext_if proto udp from any to any port domain + +# TCP + +# pass out all TCP connections and modulate state +pass out on $ext_if proto tcp all modulate state + +# pass in certain TCP connections and keep state (SSH, SMTP, DNS, IDENT) +pass in on $ext_if proto tcp from any to any port { ssh, smtp, domain, \e + auth } + +# Do not allow Windows 9x SMTP connections since they are typically +# a viral worm. Alternately we could limit these OSes to 1 connection each. +block in on $ext_if proto tcp from any os {"Windows 95", "Windows 98"} \e + to any port smtp + +# IPv6 +# pass in/out all IPv6 traffic: note that we have to enable this in two +# different ways, on both our physical interface and our tunnel +pass quick on gif0 inet6 +pass quick on $ext_if proto ipv6 + +# Packet Tagging + +# three interfaces: $int_if, $ext_if, and $wifi_if (wireless). NAT is +# being done on $ext_if for all outgoing packets. tag packets in on +# $int_if and pass those tagged packets out on $ext_if. all other +# outgoing packets (i.e., packets from the wireless network) are only +# permitted to access port 80. + +pass in on $int_if from any to any tag INTNET +pass in on $wifi_if from any to any + +block out on $ext_if from any to any +pass out quick on $ext_if tagged INTNET +pass out on $ext_if proto tcp from any to any port 80 + +# tag incoming packets as they are redirected to spamd(8). use the tag +# to pass those packets through the packet filter. + +rdr on $ext_if inet proto tcp from to port smtp \e + tag SPAMD -> 127.0.0.1 port spamd + +block in on $ext_if +pass in on $ext_if inet proto tcp tagged SPAMD +.Ed +.Pp +In the example below, a router handling both address families +translates an internal IPv4 subnet to IPv6 using the well-known +64:ff9b::/96 prefix: +.Bd -literal -offset 4n +pass in on $v4_if inet af-to inet6 from ($v6_if) to 64:ff9b::/96 +.Ed +.Pp +Paired with the example above, the example below can be used on +another router handling both address families to translate back +to IPv4: +.Bd -literal -offset 4n +pass in on $v6_if inet6 to 64:ff9b::/96 af-to inet from ($v4_if) +.Ed +.Sh GRAMMAR +Syntax for +.Nm +in BNF: +.Bd -literal +line = ( option | ether-rule | pf-rule | nat-rule | binat-rule | + rdr-rule | antispoof-rule | altq-rule | queue-rule | + trans-anchors | anchor-rule | anchor-close | load-anchor | + table-rule | include ) + +option = "set" ( [ "timeout" ( timeout | "{" timeout-list "}" ) ] | + [ "ruleset-optimization" [ "none" | "basic" | "profile" ]] | + [ "optimization" [ "default" | "normal" | + "high-latency" | "satellite" | + "aggressive" | "conservative" ] ] + [ "limit" ( limit-item | "{" limit-list "}" ) ] | + [ "loginterface" ( interface-name | "none" ) ] | + [ "block-policy" ( "drop" | "return" ) ] | + [ "state-policy" ( "if-bound" | "floating" ) ] + [ "state-defaults" state-opts ] + [ "require-order" ( "yes" | "no" ) ] + [ "fingerprints" filename ] | + [ "skip on" ifspec ] | + [ "debug" ( "none" | "urgent" | "misc" | "loud" ) ] + [ "keepcounters" ] ) + +ether-rule = "ether" etheraction [ ( "in" | "out" ) ] + [ "quick" ] [ "on" ifspec ] [ "bridge-to" interface-name ] + [ etherprotospec ] [ etherhosts ] [ "l3" hosts ] + [ etherfilteropt-list ] + +pf-rule = action [ ( "in" | "out" ) ] + [ "log" [ "(" logopts ")"] ] [ "quick" ] + [ "on" ifspec ] [ route ] [ af ] [ protospec ] + [ hosts ] [ filteropt-list ] + +logopts = logopt [ "," logopts ] +logopt = "all" | "matches" | "user" | "to" interface-name + +etherfilteropt-list = etherfilteropt-list etherfilteropt | etherfilteropt +etherfilteropt = "tag" string | "tagged" string | "queue" ( string ) | + "ridentifier" number | "label" string + +filteropt-list = filteropt-list filteropt | filteropt +filteropt = user | group | flags | icmp-type | icmp6-type | "tos" tos | + "af-to" af "from" ( redirhost | "{" redirhost-list "}" ) + [ "to" ( redirhost | "{" redirhost-list "}" ) ] | + ( "no" | "keep" | "modulate" | "synproxy" ) "state" + [ "(" state-opts ")" ] | + "fragment" | "no-df" | "min-ttl" number | "set-tos" tos | + "max-mss" number | "random-id" | "reassemble tcp" | + fragmentation | "allow-opts" | "once" | + "label" string | "tag" string | [ "!" ] "tagged" string | + "max-pkt-rate" number "/" seconds | + "set prio" ( number | "(" number [ [ "," ] number ] ")" ) | + "max-pkt-size" number | + "queue" ( string | "(" string [ [ "," ] string ] ")" ) | + "rtable" number | "probability" number"%" | "prio" number | + "state limiter" name | + "state limiter" name "(" limiter-opts ")" | + "source limiter" name | + "source limiter" name "(" limiter-opts ")" | "prio" number | + "dnpipe" ( number | "(" number "," number ")" ) | + "dnqueue" ( number | "(" number "," number ")" ) | + "ridentifier" number | + "binat-to" ( redirhost | "{" redirhost-list "}" ) + [ portspec ] [ pooltype ] | + "rdr-to" ( redirhost | "{" redirhost-list "}" ) + [ portspec ] [ pooltype ] | + "nat-to" ( redirhost | "{" redirhost-list "}" ) + [ portspec ] [ pooltype ] [ "static-port" ] | + [ ! ] "received-on" ( interface-name | interface-group ) + +nat-rule = [ "no" ] "nat" [ "pass" [ "log" [ "(" logopts ")" ] ] ] + [ "on" ifspec ] [ af ] + [ protospec ] hosts [ "tag" string ] [ "tagged" string ] + [ "->" ( redirhost | "{" redirhost-list "}" ) + [ portspec ] [ pooltype ] [ "static-port" ] + [ "map-e-portset" number "/" number "/" number ] ] + +binat-rule = [ "no" ] "binat" [ "pass" [ "log" [ "(" logopts ")" ] ] ] + [ "on" interface-name ] [ af ] + [ "proto" ( proto-name | proto-number ) ] + "from" address [ "/" mask-bits ] "to" ipspec + [ "tag" string ] [ "tagged" string ] + [ "->" address [ "/" mask-bits ] ] + +rdr-rule = [ "no" ] "rdr" [ "pass" [ "log" [ "(" logopts ")" ] ] ] + [ "on" ifspec ] [ af ] + [ protospec ] hosts [ "tag" string ] [ "tagged" string ] + [ "->" ( redirhost | "{" redirhost-list "}" ) + [ portspec ] [ pooltype ] ] + +antispoof-rule = "antispoof" [ "log" ] [ "quick" ] + "for" ifspec [ af ] [ "label" string ] + [ "ridentifier" number ] + +table-rule = "table" "<" string ">" [ tableopts-list ] +tableopts-list = tableopts-list tableopts | tableopts +tableopts = "persist" | "const" | "counters" | "file" string | + "{" [ tableaddr-list ] "}" +tableaddr-list = tableaddr-list [ "," ] tableaddr-spec | tableaddr-spec +tableaddr-spec = [ "!" ] tableaddr [ "/" mask-bits ] +tableaddr = hostname | ifspec | "self" | + ipv4-dotted-quad | ipv6-coloned-hex + +altq-rule = "altq on" interface-name queueopts-list + "queue" subqueue +queue-rule = "queue" string [ "on" interface-name ] queueopts-list + subqueue + +anchor-rule = "anchor" [ string ] [ ( "in" | "out" ) ] [ "on" ifspec ] + [ af ] [ protospec ] [ hosts ] [ filteropt-list ] [ "{" ] + +anchor-close = "}" + +trans-anchors = ( "nat-anchor" | "rdr-anchor" | "binat-anchor" ) string + [ "on" ifspec ] [ af ] [ "proto" ] [ protospec ] [ hosts ] + +load-anchor = "load anchor" string "from" filename + +queueopts-list = queueopts-list queueopts | queueopts +queueopts = [ "bandwidth" bandwidth-spec ] | + [ "qlimit" number ] | [ "tbrsize" number ] | + [ "priority" number ] | [ schedulers ] +schedulers = ( cbq-def | priq-def | hfsc-def ) +bandwidth-spec = "number" ( "b" | "Kb" | "Mb" | "Gb" | "%" ) + +etheraction = "pass" | "block" +action = "pass" | "match" | "block" [ return ] | [ "no" ] "scrub" +return = "drop" | "return" | "return-rst" [ "( ttl" number ")" ] | + "return-icmp" [ "(" icmpcode [ [ "," ] icmp6code ] ")" ] | + "return-icmp6" [ "(" icmp6code ")" ] +icmpcode = ( icmp-code-name | icmp-code-number ) +icmp6code = ( icmp6-code-name | icmp6-code-number ) + +ifspec = ( [ "!" ] ( interface-name | interface-group ) ) | + "{" interface-list "}" +interface-list = [ "!" ] ( interface-name | interface-group ) + [ [ "," ] interface-list ] +route = ( "route-to" | "reply-to" | "dup-to" ) + ( routehost | "{" routehost-list "}" ) + [ pooltype ] +af = "inet" | "inet6" + +etherprotospec = "proto" ( proto-number | "{" etherproto-list "}" ) +etherproto-list = proto-number [ [ "," ] etherproto-list ] +protospec = "proto" ( proto-name | proto-number | + "{" proto-list "}" ) +proto-list = ( proto-name | proto-number ) [ [ "," ] proto-list ] + +etherhosts = "from" macaddress "to" macaddress +macaddress = mac | mac "/" masklen | mac "&" mask + +hosts = "all" | + "from" ( "any" | "no-route" | "urpf-failed" | "self" | host | + "{" host-list "}" ) [ port ] [ os ] + "to" ( "any" | "no-route" | "self" | host | + "{" host-list "}" ) [ port ] + +ipspec = "any" | host | "{" host-list "}" +host = [ "!" ] ( address [ "/" mask-bits ] | "<" string ">" ) +redirhost = address [ "/" mask-bits ] +routehost = "(" interface-name address [ "/" mask-bits ] ")" +address = ( interface-name | interface-group | + "(" ( interface-name | interface-group ) ")" | + hostname | ipv4-dotted-quad | ipv6-coloned-hex ) +host-list = host [ [ "," ] host-list ] +redirhost-list = redirhost [ [ "," ] redirhost-list ] +routehost-list = routehost [ [ "," ] routehost-list ] + +port = "port" ( unary-op | binary-op | "{" op-list "}" ) +portspec = "port" ( number | name ) [ ":" ( "*" | number | name ) ] +os = "os" ( os-name | "{" os-list "}" ) +user = "user" ( unary-op | binary-op | "{" op-list "}" ) +group = "group" ( unary-op | binary-op | "{" op-list "}" ) + +unary-op = [ "=" | "!=" | "<" | "<=" | ">" | ">=" ] + ( name | number ) +binary-op = number ( "<>" | "><" | ":" ) number +op-list = ( unary-op | binary-op ) [ [ "," ] op-list ] + +os-name = operating-system-name +os-list = os-name [ [ "," ] os-list ] + +flags = "flags" ( [ flag-set ] "/" flag-set | "any" ) +flag-set = [ "F" ] [ "S" ] [ "R" ] [ "P" ] [ "A" ] [ "U" ] [ "E" ] + [ "W" ] + +icmp-type = "icmp-type" ( icmp-type-code | "{" icmp-list "}" ) +icmp6-type = "icmp6-type" ( icmp-type-code | "{" icmp-list "}" ) +icmp-type-code = ( icmp-type-name | icmp-type-number ) + [ "code" ( icmp-code-name | icmp-code-number ) ] +icmp-list = icmp-type-code [ [ "," ] icmp-list ] + +tos = ( "lowdelay" | "throughput" | "reliability" | + [ "0x" ] number ) + +state-opts = state-opt [ [ "," ] state-opts ] +state-opt = ( "max" number | "no-sync" | timeout | "sloppy" | + "source-track" [ ( "rule" | "global" ) ] | + "max-src-nodes" number | "max-src-states" number | + "max-src-conn" number | + "max-src-conn-rate" number "/" number | + "overload" "<" string ">" [ "flush" ] | + "if-bound" | "floating" | "pflow" ) + +fragmentation = [ "fragment reassemble" ] + +timeout-list = timeout [ [ "," ] timeout-list ] +timeout = ( "tcp.first" | "tcp.opening" | "tcp.established" | + "tcp.closing" | "tcp.finwait" | "tcp.closed" | "tcp.tsdiff" | + "sctp.first" | "sctp.opening" | "sctp.established" | + "sctp.closing" | "sctp.closed" | + "udp.first" | "udp.single" | "udp.multiple" | + "icmp.first" | "icmp.error" | + "other.first" | "other.single" | "other.multiple" | + "frag" | "interval" | "src.track" | + "adaptive.start" | "adaptive.end" ) number + +limit-list = limit-item [ [ "," ] limit-list ] +limit-item = ( "states" | "frags" | "src-nodes" ) number + +pooltype = ( "bitmask" | "random" | + "source-hash" [ ( hex-key | string-key ) ] | + "round-robin" ) [ sticky-address | prefer-ipv6-nexthop ] + +subqueue = string | "{" queue-list "}" +queue-list = string [ [ "," ] string ] +cbq-def = "cbq" [ "(" cbq-opt [ [ "," ] cbq-opt ] ")" ] +priq-def = "priq" [ "(" priq-opt [ [ "," ] priq-opt ] ")" ] +hfsc-def = "hfsc" [ "(" hfsc-opt [ [ "," ] hfsc-opt ] ")" ] +cbq-opt = ( "default" | "borrow" | "red" | "ecn" | "rio" ) +priq-opt = ( "default" | "red" | "ecn" | "rio" ) +hfsc-opt = ( "default" | "red" | "ecn" | "rio" | + linkshare-sc | realtime-sc | upperlimit-sc ) +linkshare-sc = "linkshare" sc-spec +realtime-sc = "realtime" sc-spec +upperlimit-sc = "upperlimit" sc-spec +sc-spec = ( bandwidth-spec | + "(" bandwidth-spec number bandwidth-spec ")" ) +limiter-opts = "block" | "no-match" +include = "include" filename +.Ed +.Sh FILES +.Bl -tag -width "/etc/protocols" -compact +.It Pa /etc/hosts +Host name database. +.It Pa /etc/pf.conf +Default location of the ruleset file. +The file has to be created manually as it is not installed with a +standard installation. +.It Pa /etc/pf.os +Default location of OS fingerprints. +.It Pa /etc/protocols +Protocol name database. +.It Pa /etc/services +Service name database. +.El +.Sh SEE ALSO +.Xr altq 4 , +.Xr carp 4 , +.Xr icmp 4 , +.Xr icmp6 4 , +.Xr ip 4 , +.Xr ip6 4 , +.Xr pf 4 , +.Xr pflow 4 , +.Xr pfsync 4 , +.Xr sctp 4 , +.Xr tcp 4 , +.Xr udp 4 , +.Xr hosts 5 , +.Xr pf.os 5 , +.Xr protocols 5 , +.Xr services 5 , +.Xr ftp-proxy 8 , +.Xr pfctl 8 , +.Xr pflogd 8 +.Sh HISTORY +The +.Nm +file format first appeared in +.Ox 3.0 . diff --git a/static/freebsd/man5/pf.os.5 b/static/freebsd/man5/pf.os.5 new file mode 100644 index 00000000..422f70e8 --- /dev/null +++ b/static/freebsd/man5/pf.os.5 @@ -0,0 +1,221 @@ +.\" $OpenBSD: pf.os.5,v 1.8 2007/05/31 19:19:58 jmc Exp $ +.\" +.\" Copyright (c) 2003 Mike Frantzen +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd May 31, 2007 +.Dt PF.OS 5 +.Os +.Sh NAME +.Nm pf.os +.Nd format of the operating system fingerprints file +.Sh DESCRIPTION +The +.Xr pf 4 +firewall and the +.Xr tcpdump 1 +program can both fingerprint the operating system of hosts that +originate an IPv4 TCP connection. +The file consists of newline-separated records, one per fingerprint, +containing nine colon +.Pq Ql \&: +separated fields. +These fields are as follows: +.Pp +.Bl -tag -width Description -offset indent -compact +.It window +The TCP window size. +.It TTL +The IP time to live. +.It df +The presence of the IPv4 don't fragment bit. +.It packet size +The size of the initial TCP packet. +.It TCP options +An ordered list of the TCP options. +.It class +The class of operating system. +.It version +The version of the operating system. +.It subtype +The subtype of patchlevel of the operating system. +.It description +The overall textual description of the operating system, version and subtype. +.El +.Pp +The +.Ar window +field corresponds to the th->th_win field in the TCP header and is the +source host's advertised TCP window size. +It may be between zero and 65,535 inclusive. +The window size may be given as a multiple of a constant by prepending +the size with a percent sign +.Sq % +and the value will be used as a modulus. +Three special values may be used for the window size: +.Pp +.Bl -tag -width xxx -offset indent -compact +.It * +An asterisk will wildcard the value so any window size will match. +.It S +Allow any window size which is a multiple of the maximum segment size (MSS). +.It T +Allow any window size which is a multiple of the maximum transmission unit +(MTU). +.El +.Pp +The +.Ar ttl +value is the initial time to live in the IP header. +The fingerprint code will account for the volatility of the packet's TTL +as it traverses a network. +.Pp +The +.Ar df +bit corresponds to the Don't Fragment bit in an IPv4 header. +It tells intermediate routers not to fragment the packet and is used for +path MTU discovery. +It may be either a zero or a one. +.Pp +The +.Ar packet size +is the literal size of the full IP packet and is a function of all of +the IP and TCP options. +.Pp +The +.Ar TCP options +field is an ordered list of the individual TCP options that appear in the +SYN packet. +Each option is described by a single character separated by a comma and +certain ones may include a value. +The options are: +.Pp +.Bl -tag -width Description -offset indent -compact +.It Mnnn +maximum segment size (MSS) option. +The value is the maximum packet size of the network link which may +include the +.Sq % +modulus or match all MSSes with the +.Sq * +value. +.It N +the NOP option (NO Operation). +.It T[0] +the timestamp option. +Certain operating systems always start with a zero timestamp in which +case a zero value is added to the option; otherwise no value is appended. +.It S +the Selective ACKnowledgement OK (SACKOK) option. +.It Wnnn +window scaling option. +The value is the size of the window scaling which may include the +.Sq % +modulus or match all window scalings with the +.Sq * +value. +.El +.Pp +No TCP options in the fingerprint may be given with a single dot +.Sq \&. . +.Pp +An example of OpenBSD's TCP options are: +.Pp +.Dl M*,N,N,S,N,W0,N,N,T +.Pp +The first option +.Ar M* +is the MSS option and will match all values. +The second and third options +.Ar N +will match two NOPs. +The fourth option +.Ar S +will match the SACKOK option. +The fifth +.Ar N +will match another NOP. +The sixth +.Ar W0 +will match a window scaling option with a zero scaling size. +The seventh and eighth +.Ar N +options will match two NOPs. +And the ninth and final option +.Ar T +will match the timestamp option with any time value. +.Pp +The TCP options in a fingerprint will only match packets with the +exact same TCP options in the same order. +.Pp +The +.Ar class +field is the class, genre or vendor of the operating system. +.Pp +The +.Ar version +is the version of the operating system. +It is used to distinguish between different fingerprints of operating +systems of the same class but different versions. +.Pp +The +.Ar subtype +is the subtype or patch level of the operating system version. +It is used to distinguish between different fingerprints of operating +systems of the same class and same version but slightly different +patches or tweaking. +.Pp +The +.Ar description +is a general description of the operating system, its version, +patchlevel and any further useful details. +.Sh EXAMPLES +The fingerprint of a plain +.Ox 3.3 +host is: +.Bd -literal + 16384:64:1:64:M*,N,N,S,N,W0,N,N,T:OpenBSD:3.3::OpenBSD 3.3 +.Ed +.Pp +The fingerprint of an +.Ox 3.3 +host behind a PF scrubbing firewall with a no-df rule would be: +.Bd -literal + 16384:64:0:64:M*,N,N,S,N,W0,N,N,T:OpenBSD:3.3:!df:OpenBSD 3.3 scrub no-df +.Ed +.Pp +An absolutely braindead embedded operating system fingerprint could be: +.Bd -literal + 65535:255:0:40:.:DUMMY:1.1:p3:Dummy embedded OS v1.1p3 +.Ed +.Pp +The +.Xr tcpdump 1 +output of +.Bd -literal + # tcpdump -s128 -c1 -nv 'tcp[13] == 2' + 03:13:48.118526 10.0.0.1.3377 > 10.0.0.2.80: S [tcp sum ok] \e + 534596083:534596083(0) win 57344 (DF) [tos 0x10] \e + (ttl 64, id 11315, len 44) +.Ed +.Pp +almost translates into the following fingerprint +.Bd -literal + 57344:64:1:44:M1460: exampleOS:1.0::exampleOS 1.0 +.Ed +.Sh SEE ALSO +.Xr tcpdump 1 , +.Xr pf 4 , +.Xr pf.conf 5 , +.Xr pfctl 8 diff --git a/static/freebsd/man5/phones.5 b/static/freebsd/man5/phones.5 new file mode 100644 index 00000000..373d90fc --- /dev/null +++ b/static/freebsd/man5/phones.5 @@ -0,0 +1,75 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 June 5, 1993 +.Dt PHONES 5 +.Os +.Sh NAME +.Nm phones +.Nd remote host phone number data base +.Sh DESCRIPTION +The file +.Pa /etc/phones +contains the system-wide +private phone numbers for the +.Xr tip 1 +program. +This file is normally unreadable, and so may contain +privileged information. +The format of the file is a series of lines +of the form: [\ \et]*. +The system name is +one of those defined in the +.Xr remote 5 +file and the phone number is constructed from any sequence of +characters terminated only by ``,'' or the end of the line. +The ``='' and ``*'' characters are +indicators to the auto call units to pause and wait for a second dial +tone (when going through an exchange). +The ``='' is required by the +.Tn DF02-AC +and the ``*'' is required by the +.Tn BIZCOMP +1030. +.Pp +Only one phone number per line is permitted. +However, if more than +one line in the file contains the same system name +.Xr tip 1 +will attempt to dial each one in turn, until it establishes a connection. +.Sh FILES +.Bl -tag -width /etc/phones -compact +.It Pa /etc/phones +.El +.Sh SEE ALSO +.Xr tip 1 , +.Xr remote 5 +.Sh HISTORY +The +.Nm +file appeared in +.Bx 4.2 . diff --git a/static/freebsd/man5/portindex.5 b/static/freebsd/man5/portindex.5 new file mode 100644 index 00000000..f943975c --- /dev/null +++ b/static/freebsd/man5/portindex.5 @@ -0,0 +1,98 @@ +.\" +.\" Copyright (c) 2004 Paul Armstrong +.\" Copyright (c) 2009 Thomas Abthorpe +.\" +.\" 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 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 October 14, 2012 +.Dt PORTINDEX 5 +.Os +.Sh NAME +.Nm INDEX +.Nd "File containing information about the state of the ports tree" +.Sh DESCRIPTION +The port index file in +.Pa /usr/ports +contains various bits of information about the ports tree. +Each major branch of +.Fx +has a separate index file, named +.Dq INDEX- Ns Ar N , +where +.Ar N +is the major version number of the +.Fx +branch, i.e.: +.Pa INDEX-7 , +or +.Pa INDEX-8 . +.Bl -tag -width XXXXXXXXXX +.It Cm \&name +The name of the package. +.It Cm \&path +The path to the port directory. +.It Cm \&install prefix +The default install prefix. +.It Cm \&short description +A short description. +.It Cm \&full description +The path to the full description. +.It Cm \&maintainer email +The email address of the maintainer. +.It Cm \&index +The categories this port is part of. +.It Cm \&build dependencies +Ports required to be installed prior to building this port. +.It Cm \&run dependencies +Ports required to be installed for this port to run. +.It Cm \&website +The project website for the port. +.It Cm \&e-deps +Ports that may be required to extract this port. +.It Cm \&p-deps +Ports that may be required to patch this port. +.It Cm \&f-deps +Ports that may be required to fetch this port. +.El +.Sh FILES +.Bl -tag -width /usr/ports/INDEX-8XX +.It Pa /usr/ports/INDEX- Ns Ar N +where +.Ar N +is the major version number of the +.Fx +branch. +.El +.Sh EXAMPLES +.Bd -literal +vim-6.3.15|/usr/ports/editors/vim|/usr/local|Vi "workalike", with many additional features|/usr/ports/editors/vim/pkg-descr|obrien@FreeBSD.org|editors|libiconv-1.9.2_1|libiconv-1.9.2_1|http://www.vim.org/||| +.Ed +.Sh SEE ALSO +.Xr build 7 , +.Xr ports 7 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Paul Armstrong +and +.An Thomas Abthorpe Aq Mt tabthorpe@FreeBSD.org . diff --git a/static/freebsd/man5/protocols.5 b/static/freebsd/man5/protocols.5 new file mode 100644 index 00000000..0b15e3ae --- /dev/null +++ b/static/freebsd/man5/protocols.5 @@ -0,0 +1,84 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 December 7, 2020 +.Dt PROTOCOLS 5 +.Os +.Sh NAME +.Nm protocols +.Nd protocol name data base +.Sh DESCRIPTION +The +.Nm +file contains information regarding the assigned protocol numbers +used by IPv4 and IPv6 to identify the next level protocol. +For each protocol a single line should be present +with the following information: +.Bd -unfilled -offset indent +official protocol name +protocol number +aliases +.Ed +.Pp +Items are separated by any number of blanks and/or +tab characters. +A ``#'' indicates the beginning of +a comment; characters up to the end of the line are +not interpreted by routines which search the file. +.Pp +Protocol names may contain any printable +character other than a field delimiter, newline, +or comment character. +.Sh FILES +.Bl -tag -width /etc/protocols -compact +.It Pa /etc/protocols +The +.Nm +file resides in +.Pa /etc . +.El +.Sh SEE ALSO +.Xr getprotoent 3 +.Rs +.%R RFC 2780 +.%D March 2000 +.%T "IANA Allocation Guidelines For Values In the \ +Internet Protocol and Related Headers" +.Re +.Rs +.%R RFC 5237 +.%D February 2008 +.%T "IANA Allocation Guidelines for the Protocol Field" +.Re +.Sh HISTORY +The +.Nm +file format appeared in +.Bx 4.2 , +describing the "known protocols used in the DARPA Internet". +.Sh BUGS +A name server should be used instead of a static file. diff --git a/static/freebsd/man5/quota.user.5 b/static/freebsd/man5/quota.user.5 new file mode 100644 index 00000000..7bfbd4ed --- /dev/null +++ b/static/freebsd/man5/quota.user.5 @@ -0,0 +1,128 @@ +.\" Copyright (c) 2001 Nik Clayton +.\" +.\" 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 October 30, 2007 +.Dt QUOTA.USER 5 +.Os +.Sh NAME +.Nm quota.user , quota.group +.Nd per file system quota database +.Sh DESCRIPTION +Each file system with active quotas should contain a +.Pa quota.user +and +.Pa quota.group +file in the file system root. +These files are created by +.Xr quotacheck 8 , +and should be edited with +.Xr edquota 8 . +It is possible to specify a different location and file name with the +.Dq Li userquota +and +.Dq Li groupquota +options in the +.Xr fstab 5 +file. +.Pp +The data files contain the following information: +.Pp +.Bl -bullet -offset indent -compact +.It +Current block usage +.It +Current number of files +.It +Soft block limit +.It +Soft file limit +.It +Hard block limit +.It +Hard file limit +.It +Block grace time remaining if over the soft limit +.It +File grace time remaining if over the soft limit +.El +.Pp +See +.Xr edquota 8 +for an explanation on the various limits and grace periods. +.Pp +During normal quota operations the +.Xr quotactl 2 +interface is used to query or set quota information and the kernel +will maintain the data files as needed. +If quotas are disabled on +a file system, but marked as having quotas enabled in +.Xr fstab 5 , +then the quota data files will be used directly. +.Pp +The data files are stored as an array of +.Dq Li struct dqblk +structures, as defined in +.In ufs/ufs/quota.h , +and indexed by UID or GID. +The data files will be written as a sparse file if possible. +Data is only maintained for ids that have either non-zero usage or +non-zero quota limits. +If an attempt is made to access data for an id that would exist past the +end of the current data file, a quota structure with all values set +to zero will be created, and the data file extended as needed. +The +.Xr quotacheck 8 +utility will truncate the data files to the minimum size needed +to store the highest id with either non-zero file usage or +non-zero quota limits. +.Pp +The data record for id 0 has special meaning. +If the +.Dq Dv dqb_btime +or +.Dq Dv dbq_itime +fields are non-zero, they are used to indicate the grace period on +that file system for users who have exceeded their soft limit. +These times can be set by +.Xr edquota 8 +with the +.Fl t +flag. +If no explicit grace period has been set with +.Xr edquota 8 , +then the default value of 7 days will be used. +The default values are defined by +.Dv MAX_DQ_TIME +and +.Dv MAX_IQ_TIME +in +.In ufs/ufs/quota.h . +.Sh SEE ALSO +.Xr quota 1 , +.Xr quotactl 2 , +.Xr fstab 5 , +.Xr edquota 8 , +.Xr quotacheck 8 , +.Xr quotaoff 8 , +.Xr quotaon 8 , +.Xr repquota 8 diff --git a/static/freebsd/man5/rc.conf.5 b/static/freebsd/man5/rc.conf.5 new file mode 100644 index 00000000..b666345d --- /dev/null +++ b/static/freebsd/man5/rc.conf.5 @@ -0,0 +1,5239 @@ +.\" Copyright (c) 1995 +.\" Jordan K. Hubbard +.\" +.\" 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 ``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 2, 2026 +.Dt RC.CONF 5 +.Os +.Sh NAME +.Nm rc.conf +.Nd system configuration information +.Sh DESCRIPTION +The file +.Nm +contains descriptive information about the local host name, configuration +details for any potential network interfaces and which services should be +started up at system initial boot time. +In new installations, the +.Nm +file is generally initialized by the system installation utility. +.Pp +The purpose of +.Nm +is not to run commands or perform system startup actions +directly. +Instead, it is included by the +various generic startup scripts in +.Pa /etc +which conditionalize their +internal actions according to the settings found there. +.Pp +The +.Pa /etc/rc.conf +file is included from the file +.Pa /etc/defaults/rc.conf , +which specifies the default settings for all the available options. +Options need only be specified in +.Pa /etc/rc.conf +when the system administrator wishes to override these defaults. +The file +.Pa /etc/defaults/vendor.conf +allows vendors to override +.Fx +defaults. +The file +.Pa /etc/rc.conf.local +is used to override settings in +.Pa /etc/rc.conf +for historical reasons. +.Pp +The sysrc(8) command provides a scripting interface to modify system +config files. +.Pp +In addition to +.Pa /etc/rc.conf.local +you can also place smaller configuration files for each +.Xr rc 8 +script in the +.Pa /etc/rc.conf.d +directory or +.Ao Ar dir Ac Ns Pa /rc.conf.d +directories (where +.Ao Ar dir Ac +is each entry specified in +.Va local_startup , +but with any trailing +.Pa /rc.d +stripped), +which will be included by the +.Va load_rc_config +function. +For jail configurations you could use the file +.Pa /etc/rc.conf.d/jail +to store jail-specific configuration options. +If +.Va local_startup +contains +.Pa /usr/local/etc/rc.d +and +.Pa /opt/conf , +.Pa /usr/local/etc/rc.conf.d/jail +and +.Pa /opt/conf/rc.conf.d/jail +will be loaded. +If +.Ao Ar dir Ac Ns Pa /rc.conf.d/ Ns Ao Ar name Ac +is a directory then all of the files in the directory will be loaded. +See also the +.Va rc_conf_files +variable below. +.Pp +Options are set with +.Dq Ar name Ns Li = Ns Ar value +assignments that use +.Xr sh 1 +syntax. +The following list provides a name and short description for each +variable that can be set in the +.Nm +file: +.Bl -tag -width indent-two +.It Va rc_debug +.Pq Vt bool +If set to +.Dq Li YES , +enable output of debug messages from rc scripts. +This variable can be helpful in diagnosing mistakes when +editing or integrating new scripts. +Beware that this produces copious output to the terminal and +.Xr syslog 3 . +.It Va rc_info +.Pq Vt bool +If set to +.Dq Li NO , +disable informational messages from the rc scripts. +Informational messages are displayed when +a condition that is not serious enough to warrant a warning or +an error occurs. +.It Va rc_startmsgs +.Pq Vt bool +If set to +.Dq Li YES , +show +.Dq Starting foo: +when faststart is used (e.g., at boot time). +.It Va early_late_divider +.Pq Vt str +The name of the script that should be used as the +delimiter between the +.Dq early +and +.Dq late +stages of the boot process. +The early stage should contain all the services needed to +get the disks (local or remote) mounted so that the late +stage can include scripts contained in the directories +listed in the +.Va local_startup +variable (see below). +Thus, the two likely candidates for this value are +.Pa mountcritlocal +for the typical system, and +.Pa mountcritremote +if the system needs remote file +systems mounted to get access to the +.Va local_startup +directories; for example when +.Pa /usr/local +is NFS mounted. +For +.Pa rc.conf +within a +.Xr jail 8 +.Pa NETWORKING +is likely to be an appropriate value. +Extreme care should be taken when changing this value, +and before changing it one should ensure that there are +adequate provisions to recover from a failed boot +(such as physical contact with the machine, +or reliable remote console access). +.It Va always_force_depends +.Pq Vt bool +Various +.Pa rc.d +scripts use the force_depend function to check whether required +services are already running, and to start them if necessary. +By default during boot time this check is bypassed if the +required service is enabled in +.Pa /etc/rc.conf[.local] . +Setting this option will bypass that check at boot time and +always test whether or not the service is actually running. +Enabling this option is likely to increase your boot time if +services are enabled that utilize the force_depend check. +.It Ao Ar name Ac Ns Va _audit_user +.Pq Vt str +A user name or UID to use as the +.Xr audit 4 +user for the service. +Run the chrooted service under this system group. +By default, when an unprvileged user restarts a service using a utility +such as sudo or doas, the service's will audit session will point to the +unprivileged user, which may be undesirable. +In that case, this variable can be used to override the audit user using +.Xr setaudit 8 . +.It Ao Ar name Ac Ns Va _chroot +.Pq Vt str +.Xr chroot 8 +to this directory before running the service. +.It Ao Ar name Ac Ns Va _cpuset +.Pq Vt str +A list of CPUs to run the service on. +Passed to +.Xr cpuset 1 +using the +.Fl l +flag. +.It Ao Ar name Ac Ns Va _fib +.Pq Vt int +The +.Xr setfib 1 +value to run the service under. +.It Ao Ar name Ac Ns Va _group +.Pq Vt str +Unlike the +.Ao Ar name Ac Ns Va _user +setting, this setting has no effect if the service is not chrooted. +.It Ao Ar name Ac Ns Va _limits +.Pq Vt str +Resource limits to apply to the service using +.Xr limits 1 . +By default, resource limits are based on the login class defined in +.Ao Ar name Ac Ns Va _login_class . +.It Ao Ar name Ac Ns Va _login_class +.Pq Vt str +Login class to be used with +.Ao Ar name Ac Ns Va _limits . +Defaults to +.Dq Li daemon . +.It Ao Ar name Ac Ns Va _nice +.Pq Vt int +The +.Xr nice 1 +value to run the service under. +.It Ao Ar name Ac Ns Va _oomprotect +.Pq Vt str +Use +.Xr protect 1 +to prevent the service from being killed when swap space +is exhausted. +Use +.Dq Li YES +to protect only the service itself, and +.Dq Li ALL +to protect the service and all its child processes. +.Pp +Please note that rc scripts which redefine +.Dl ${argument}_cmd +.Pq see Xr rc.subr 8 +such as PostgreSQL will not inherit the OOM killer protection. +.Pp +This variable has no effect on services running within a +.Xr jail 8 . +.It Ao Ar name Ac Ns Va _setup +.Pq Vt str +Run the specified setup script right before starting the actual service +command. +Useful for automatic configuration file generation. +.It Ao Ar name Ac Ns Va _umask +.Pq Vt int +Run the service using this +.Xr umask 1 +value. +.It Ao Ar name Ac Ns Va _user +.Pq Vt str +Run the service under this user account. +.It Ao Ar name Ac Ns Va _svcj +.Pq Vt bool +If set to +.Dq Li YES , +auto-jail the service with inherited filesystem and other +jail properties depending on +.Ao Ar name Ac Ns Va _svcj_options . +.It Ao Ar name Ac Ns Va _svcj_ipaddrs +.Pq Vt str +A list of IP addresses that the service jail will be permitted to use. +If this is not specified, the service jail will be permitted to use all +assigned IP addresses if networking is enabled in the jail. +.It Ao Ar name Ac Ns Va _svcj_options +.Pq Vt str +A list of jail properties for the service. +See +.Sx SERVICE JAILS +for a list of valid properties. +.It Va apm_enable +.Pq Vt bool +If set to +.Dq Li YES , +enable support for Automatic Power Management with +the +.Xr apm 8 +command. +.It Va apmd_enable +.Pq Vt bool +Run +.Xr apmd 8 +to handle APM event from userland. +This also enables support for APM. +.It Va apmd_flags +.Pq Vt str +If +.Va apmd_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr apmd 8 +daemon. +.It Va devd_enable +.Pq Vt bool +Run +.Xr devd 8 +to handle device added, removed or unknown events from the kernel. +.It Va ddb_enable +.Pq Vt bool +Run +.Xr ddb 8 +to install +.Xr ddb 4 +scripts at boot time. +.It Va ddb_config +.Pq Vt str +Configuration file for +.Xr ddb 8 . +Default +.Pa /etc/ddb.conf . +.It Va devmatch_enable +.Pq Vt bool +If set to +.Dq Li NO , +disable auto-loading of kernel modules with +.Xr devmatch 8 . +.It Va devmatch_blocklist +.Pq Vt str +A whitespace-separated list of kernel modules to be ignored by +.Xr devmatch 8 . +In addition, the +.Xr kenv 1 +.Va devmatch_blocklist +is appended to this variable to allow disabling of +.Xr devmatch 8 +loaded modules from the boot loader. +.It Va devmatch_blacklist +.Pq Vt str +This variable is deprecated. +Use +.Va devmatch_blocklist +instead. +A whitespace-separated list of kernel modules to be ignored by +.Xr devmatch 8 . +.It Va kld_list +.Pq Vt str +A whitespace-separated list of kernel modules to load right after +the local disks are mounted, without any +.Pa .ko +extension or path. +.It Va kldxref_enable +.Pq Vt bool +Set to +.Dq Li NO +by default. +Set to +.Dq Li YES +to automatically rebuild +.Pa linker.hints +files with +.Xr kldxref 8 +at boot time. +.It Va kldxref_clobber +.Pq Vt bool +Set to +.Dq Li NO +by default. +If +.Va kldxref_enable +is true, +setting to +.Dq Li YES +will overwrite existing +.Pa linker.hints +files at boot time. +Otherwise, +only missing +.Pa linker.hints +files are generated. +.It Va kldxref_module_path +.Pq Vt str +Empty by default. +A semi-colon +.Pq Ql \&; +delimited list of paths containing +.Xr kld 4 +modules. +If empty, +the contents of the +.Va kern.module_path +.Xr sysctl 8 +are used. +.It Va powerd_enable +.Pq Vt bool +If set to +.Dq Li YES , +enable the system power control facility with the +.Xr powerd 8 +daemon. +.It Va powerd_flags +.Pq Vt str +If +.Va powerd_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr powerd 8 +daemon. +.It Va svcj_all_enable +Enable auto-jailing of all services which are not explicitly +excluded. +See +.Sx SERVICE JAILS +for more info. +.It Va tmpmfs +Controls the creation of a +.Pa /tmp +memory file system. +Always happens if set to +.Dq Li YES +and never happens if set to +.Dq Li NO . +If set to anything else, a memory file system is created if +.Pa /tmp +is not writable. +.It Va tmpsize +Controls the size of a created +.Pa /tmp +memory file system. +.It Va tmpmfs_flags +Extra options passed to the +.Xr mdmfs 8 +utility when the memory file system for +.Pa /tmp +is created. +The default is +.Dq Li "-S" , +which inhibits the use of softupdates on +.Pa /tmp +so that file system space is freed without delay +after file truncation or deletion. +See +.Xr mdmfs 8 +for other options you can use in +.Va tmpmfs_flags . +.It Va varmfs +Controls the creation of a +.Pa /var +memory file system. +Always happens if set to +.Dq Li YES +and never happens if set to +.Dq Li NO . +If set to anything else, a memory file system is created if +.Pa /var +is not writable. +.It Va varsize +Controls the size of a created +.Pa /var +memory file system. +.It Va varmfs_flags +Extra options passed to the +.Xr mdmfs 8 +utility when the memory file system for +.Pa /var +is created. +The default is +.Dq Li "-S" , +which inhibits the use of softupdates on +.Pa /var +so that file system space is freed without delay +after file truncation or deletion. +See +.Xr mdmfs 8 +for other options you can use in +.Va varmfs_flags . +.It Va populate_var +Controls the automatic population of the +.Pa /var +file system. +Always happens if set to +.Dq Li YES +and never happens if set to +.Dq Li NO . +If set to anything else, a memory file system is created if +.Pa /var +is not writable. +Note that this process requires access to certain commands in +.Pa /usr +before +.Pa /usr +is mounted on normal systems. +.It Va cleanvar_enable +.Pq Vt bool +Clean the +.Pa /var +directory. +.It Va var_run_enable +.Pq Vt bool +Set to "YES" to enable saving of the +.Pa /var/run +directory structure into an mtree file at shutdown and the reload of the +.Pa /var/run +directory structure at boot. +.It Va var_run_autosave +.Pq Vt bool +In some cases it may be undesirable to save +.Pa /var/run +at shutdown. +When set to "NO" +.Pa /var/run +is loaded at reboot but not saved at shutdown. +Typically in this scenario +.Ql service var_run save +would be performed to save a copy of the +.Pa /var/run +directory structure once, to be reloaded during all subsequent reboots. +.It Va var_run_mtree +.Pq Vt str +Where to save the +.Pa /var/run +mtree. +The default location is +.Pa /var/db/mtree/BSD.var-run.mtree . +.It Va local_startup +.Pq Vt str +List of directories to search for startup script files. +.It Va script_name_sep +.Pq Vt str +The field separator to use for breaking down the list of startup script files +into individual filenames. +The default is a space. +It is not necessary to change this unless there are startup scripts with names +containing spaces. +.It Va hostapd_enable +.Pq Vt bool +Set to +.Dq Li YES +to start +.Xr hostapd 8 +at system boot time. +.It Va hostname +.Pq Vt str +The fully qualified domain name (FQDN) of this host on the network. +This should almost certainly be set to something meaningful, even if +there is no network connection. +If +.Xr dhclient 8 +is used to set the hostname via DHCP, +this variable should be set to an empty string. +Within a +.Xr jail 8 +the hostname is generally already set and this variable may be absent. +If this value remains unset when the system is done booting +your console login will display the default hostname of +.Dq Amnesiac . +.It Va nisdomainname +.Pq Vt str +The NIS domain name of this host, or +.Dq Li NO +if NIS is not used. +.It Va hostid_enable +.Pq Vt bool +If set to +.Dq Li NO , +disable the generation or saving of the +.Pa hostid +and +.Pa machine-id +files at system boot and shutdown. +.It Va hostid_file +.Pq Vt str +Path to the +.Pa hostid +file, default +.Pa /etc/hostid . +.It Va hostid_uuidgen_flags +.Pq Vt str +Flags passed to +.Xr uuidgen 1 +when generating a software host UUID. +This is used only if the system cannot determine a hardware UUID. +Set to +.Dq Li -r +by default. +.It Va machine_id_file +.Pq Vt str +Path to the +.Pa machine-id +file, default +.Pa /etc/machine-id . +.It Va dhclient_program +.Pq Vt str +Path to the DHCP client program, defaulting to +.Pa /sbin/dhclient . +.It Va dhclient_flags +.Pq Vt str +Additional flags to pass to the DHCP client program. +See the +.Xr dhclient 8 +manpage for a description of the command line options available. +.It Va dhclient_flags_ Ns Aq Ar iface +Additional flags to pass to the DHCP client program running on +.Ar iface +only. +When specified, this variable overrides +.Va dhclient_flags . +.It Va background_dhclient +.Pq Vt bool +Set to +.Dq Li YES +to start the DHCP client in background. +This can cause trouble with applications depending on +a working network, but it will provide a faster startup +in many cases. +.It Va background_dhclient_ Ns Aq Ar iface +When specified, this variable overrides the +.Va background_dhclient +variable for interface +.Ar iface +only. +.It Va dhclient_arpwait +.Pq Vt bool +Set to +.Dq Li NO +to stop +.Xr dhclient 8 +from waiting for ARP resolution, to make the system boot faster. +This may be done on networks where the DHCP server is certain to +know whether an address is available. +.It Va synchronous_dhclient +.Pq Vt bool +Set to +.Dq Li YES +to start +.Xr dhclient 8 +synchronously at startup. +This behavior can be overridden on a per-interface basis by replacing +the +.Dq Li DHCP +keyword in the +.Va ifconfig_ Ns Aq Ar interface +variable with +.Dq Li SYNCDHCP +or +.Dq Li NOSYNCDHCP . +.It Va defaultroute_delay +.Pq Vt int +When set to a positive value, wait up to this long after configuring +DHCP interfaces at startup to give the interfaces time to receive a lease. +.It Va firewall_enable +.Pq Vt bool +Set to +.Dq Li YES +to load firewall rules at startup. +If the kernel was not built with +.Cd "options IPFIREWALL" , +the +.Pa ipfw.ko +kernel module will be loaded. +See also +.Va ipfilter_enable . +.It Va firewall_script +.Pq Vt str +This variable specifies the full path to the firewall script to run. +The default is +.Pa /etc/rc.firewall . +.It Va firewall_type +.Pq Vt str +Names the firewall type from the selection in +.Pa /etc/rc.firewall , +or the file which contains the local firewall ruleset. +Valid selections from +.Pa /etc/rc.firewall +are: +.Pp +.Bl -tag -width ".Li workstation" -compact +.It Li open +unrestricted IP access +.It Li closed +all IP services disabled, except via +.Dq Li lo0 +.It Li client +basic protection for a workstation +.It Li workstation +basic protection for a workstation using stateful firewalling +.It Li simple +basic protection for a LAN. +.El +.Pp +If a filename is specified, the full path +must be given. +.Pp +Most of the predefined rulesets define additional configuration variables. +These are documented in +.Pa /etc/rc.firewall . +.It Va firewall_quiet +.Pq Vt bool +Set to +.Dq Li YES +to disable the display of firewall rules on the console during boot. +.It Va firewall_logging +.Pq Vt bool +Set to +.Dq Li YES +to enable firewall event logging. +This is equivalent to the +.Dv IPFIREWALL_VERBOSE +kernel option. +.It Va firewall_logif +.Pq Vt bool +Set to +.Dq Li YES +to create pseudo interface +.Li ipfw0 +for logging. +For more details, see +.Xr ipfw 8 +manual page. +.It Va firewall_flags +.Pq Vt str +Flags passed to +.Xr ipfw 8 +if +.Va firewall_type +specifies a filename. +.It Va firewall_coscripts +.Pq Vt str +List of executables and/or rc scripts to run after firewall starts/stops. +Default is empty. +.\" ----- firewall_nat_enable setting -------------------------------- +.It Va firewall_nat_enable +.Pq Vt bool +The +.Xr ipfw 8 +equivalent of +.Va natd_enable . +Setting this to +.Dq Li YES +will automatically load the +.Xr ipfw 8 +NAT kernel module if +.Va firewall_enable +is also set to +.Dq Li YES . +.It Va firewall_nat_interface +.Pq Vt str +The +.Xr ipfw 8 +equivalent of +.Va natd_interface . +This is the name of the public interface or IP address on which +kernel NAT should run. +.It Va firewall_nat_flags +.Pq Vt str +Additional configuration parameters for kernel NAT should be placed here. +.It Va firewall_nat64_enable +.Pq Vt bool +Setting this to +.Dq Li YES +will automatically load the +.Xr ipfw 8 +NAT64 kernel module if +.Va firewall_enable +is also set to +.Dq Li YES . +.It Va firewall_nptv6_enable +.Pq Vt bool +Setting this to +.Dq Li YES +will automatically load the +.Xr ipfw 8 +NPTv6 kernel module if +.Va firewall_enable +is also set to +.Dq Li YES . +.It Va firewall_pmod_enable +.Pq Vt bool +Setting this to +.Dq Li YES +will automatically load the +.Xr ipfw 8 +pmod kernel module if +.Va firewall_enable +is also set to +.Dq Li YES . +.It Va dummynet_enable +.Pq Vt bool +Setting this to +.Dq Li YES +will automatically load the +.Xr dummynet 4 +module if +.Va firewall_enable +is also set to +.Dq Li YES . +.\" ------------------------------------------------------------------- +.It Va ipfw_netflow_enable +.Pq Vt bool +Setting this to +.Dq Li YES +will enable netflow logging via +.Xr ng_netflow 4 . +.Pp +By default a ipfw rule is inserted and all packets are duplicated with +the ngtee command and netflow packets are sent to 127.0.0.1 on the netflow +port using protocol version 5. +.It Va ipfw_netflow_hook +.Pq Vt int +netflow hook name, must be numerical +(default +.Pa 9995 ) . +.It Va ipfw_netflow_rule +.Pq Vt int +ipfw rule number +(default +.Pa 1000 ) . +.It Va ipfw_netflow_ip +.Pq Vt str +Destination server ip for receiving netflow data +(default +.Pa 127.0.0.1 ) . +.It Va ipfw_netflow_port +.Pq Vt int +Destination server port for receiving netflow data +(default +.Pa 9995 ) . +.It Va ipfw_netflow_version +.Pq Vt int +Do not set for using version 5 of the netflow protocol, set it to 9 for using +version 9. +.It Va ipfw_netflow_fib +.Pq Vt int +Only match packet in FIB +.Pa ipfw_netflow_fib +(default is undefined meaning all FIBs). +.It Va natd_program +.Pq Vt str +Path to +.Xr natd 8 . +.It Va natd_enable +.Pq Vt bool +Set to +.Dq Li YES +to enable +.Xr natd 8 . +.Va firewall_enable +must also be set to +.Dq Li YES , +and +.Xr divert 4 +sockets must be enabled in the kernel. +If the kernel was not built with +.Cd "options IPDIVERT" , +the +.Pa ipdivert.ko +kernel module will be loaded. +.It Va natd_interface +.Pq Vt str +This is the name of the public interface on which +.Xr natd 8 +should run. +The interface may be given as an interface name or as an IP address. +.It Va natd_flags +.Pq Vt str +Additional +.Xr natd 8 +flags should be placed here. +The +.Fl n +or +.Fl a +flag is automatically added with the above +.Va natd_interface +as an argument. +.\" ----- ipfilter_enable setting -------------------------------- +.It Va ipfilter_enable +.Pq Vt bool +Set to +.Dq Li NO +by default. +Setting this to +.Dq Li YES +enables +.Xr ipf 8 +packet filtering. +.Pp +Typical usage will require putting +.Bd -literal +ipfilter_enable="YES" +ipnat_enable="YES" +ipmon_enable="YES" +ipfs_enable="YES" +.Ed +.Pp +into +.Pa /etc/rc.conf +and editing +.Pa /etc/ipf.rules +and +.Pa /etc/ipnat.rules +appropriately. +.Pp +Note that +.Va ipfilter_enable +and +.Va ipnat_enable +can be enabled independently. +.Va ipmon_enable +and +.Va ipfs_enable +both require at least one of +.Va ipfilter_enable +and +.Va ipnat_enable +to be enabled. +.Pp +Having +.Bd -literal +options IPFILTER +options IPFILTER_LOG +options IPFILTER_DEFAULT_BLOCK +.Ed +.Pp +in the kernel configuration file is a good idea, too. +.\" ----- ipfilter_program setting ------------------------------ +.It Va ipfilter_program +.Pq Vt str +Path to +.Xr ipf 8 +(default +.Pa /sbin/ipf ) . +.\" ----- ipfilter_rules setting -------------------------------- +.It Va ipfilter_rules +.Pq Vt str +Set to +.Pa /etc/ipf.rules +by default. +This variable contains the name of the filter rule definition file. +The file is expected to be readable for the +.Xr ipf 8 +command to execute. +.\" ----- ipfilter_flags setting -------------------------------- +.It Va ipfilter_flags +.Pq Vt str +Empty by default. +This variable contains flags passed to the +.Xr ipf 8 +program. +.\" ----- ipnat_enable setting ---------------------------------- +.It Va ipnat_enable +.Pq Vt bool +Set to +.Dq Li NO +by default. +Set it to +.Dq Li YES +to enable +.Xr ipnat 8 +network address translation. +See +.Va ipfilter_enable +for a detailed discussion. +.\" ----- ipnat_program setting --------------------------------- +.It Va ipnat_program +.Pq Vt str +Path to +.Xr ipnat 8 +(default +.Pa /sbin/ipnat ) . +.\" ----- ipnat_rules setting ----------------------------------- +.It Va ipnat_rules +.Pq Vt str +Set to +.Pa /etc/ipnat.rules +by default. +This variable contains the name of the file +holding the network address translation definition. +This file is expected to be readable for the +.Xr ipnat 8 +command to execute. +.\" ----- ipnat_flags setting ----------------------------------- +.It Va ipnat_flags +.Pq Vt str +Empty by default. +This variable contains flags passed to the +.Xr ipnat 8 +program. +.\" ----- ipmon_enable setting ---------------------------------- +.It Va ipmon_enable +.Pq Vt bool +Set to +.Dq Li NO +by default. +Set it to +.Dq Li YES +to enable +.Xr ipmon 8 +monitoring (logging +.Xr ipf 8 +and +.Xr ipnat 8 +events). +Setting this variable needs setting +.Va ipfilter_enable +or +.Va ipnat_enable +too. +See +.Va ipfilter_enable +for a detailed discussion. +.\" ----- ipmon_program setting --------------------------------- +.It Va ipmon_program +.Pq Vt str +Path to +.Xr ipmon 8 +(default +.Pa /sbin/ipmon ) . +.\" ----- ipmon_flags setting ----------------------------------- +.It Va ipmon_flags +.Pq Vt str +Set to +.Dq Li -Ds +by default. +This variable contains flags passed to the +.Xr ipmon 8 +program. +Another typical example would be +.Dq Fl D Pa /var/log/ipflog +to have +.Xr ipmon 8 +log directly to a file bypassing +.Xr syslogd 8 . +Make sure to adjust +.Pa /etc/newsyslog.conf +in such case like this: +.Bd -literal +/var/log/ipflog 640 10 100 * Z /var/run/ipmon.pid +.Ed +.\" ----- ipfs_enable setting ----------------------------------- +.It Va ipfs_enable +.Pq Vt bool +Set to +.Dq Li NO +by default. +Set it to +.Dq Li YES +to enable +.Xr ipfs 8 +saving the filter and NAT state tables during shutdown +and reloading them during startup again. +Setting this variable needs setting +.Va ipfilter_enable +or +.Va ipnat_enable +to +.Dq Li YES +too. +See +.Va ipfilter_enable +for a detailed discussion. +Note that if +.Va kern_securelevel +is set to 3, +.Va ipfs_enable +cannot be used +because the raised securelevel will prevent +.Xr ipfs 8 +from saving the state tables at shutdown time. +.\" ----- ipfs_program setting ---------------------------------- +.It Va ipfs_program +.Pq Vt str +Path to +.Xr ipfs 8 +(default +.Pa /sbin/ipfs ) . +.\" ----- ipfs_flags setting ------------------------------------ +.It Va ipfs_flags +.Pq Vt str +Empty by default. +This variable contains flags passed to the +.Xr ipfs 8 +program. +.\" ----- end of added ipf hook --------------------------------- +.It Va pf_enable +.Pq Vt bool +Set to +.Dq Li NO +by default. +Setting this to +.Dq Li YES +enables +.Xr pf 4 +packet filtering. +.Pp +Typical usage will require putting +.Pp +.Dl pf_enable="YES" +.Pp +into +.Pa /etc/rc.conf +and editing +.Pa /etc/pf.conf +appropriately. +Adding +.Pp +.Dl "device pf" +.Pp +builds support for +.Xr pf 4 +into the kernel, otherwise the +kernel module will be loaded. +.It Va pf_rules +.Pq Vt str +Path to +.Xr pf 4 +ruleset configuration file +(default +.Pa /etc/pf.conf ) . +.It Va pf_program +.Pq Vt str +Path to +.Xr pfctl 8 +(default +.Pa /sbin/pfctl ) . +.It Va pf_flags +.Pq Vt str +If +.Va pf_enable +is set to +.Dq Li YES , +these flags are passed to the +.Xr pfctl 8 +program when loading the ruleset. +.It Va pf_fallback_rules_enable +.Pq Vt bool +Set to +.Dq Li NO +by default. +Setting this to +.Dq Li YES +enables loading +.Va pf_fallback_rules_file +or +.Va pf_fallback_rules +in case of a problem when loading the ruleset in +.Va pf_rules . +.It Va pf_fallback_rules_file +.Pq Vt str +Path to a pf ruleset to load in case of failure when loading the +ruleset in +.Va pf_rules +(default +.Pa /etc/pf-fallback.conf ) . +.It Va pf_fallback_rules +.Pq Vt str +A pf ruleset to load in case of failure when loading the ruleset in +.Va pf_rules +and +.Va pf_fallback_rules_file +is not found. +Multiple rules can be set as follows: +.Bd -literal +pf_fallback_rules=" + block drop log all + pass in quick on em0" +.Pp +.Ed +The default fallback rule is +.Dq block drop log all +.It Va pflog_enable +.Pq Vt bool +Set to +.Dq Li NO +by default. +Setting this to +.Dq Li YES +enables +.Xr pflogd 8 +which logs packets from the +.Xr pf 4 +packet filter. +.It Va pflog_logfile +.Pq Vt str +If +.Va pflog_enable +is set to +.Dq Li YES +this controls where +.Xr pflogd 8 +stores the logfile +(default +.Pa /var/log/pflog ) . +Check +.Pa /etc/newsyslog.conf +to adjust logfile rotation for this. +.It Va pflog_program +.Pq Vt str +Path to +.Xr pflogd 8 +(default +.Pa /sbin/pflogd ) . +.It Va pflog_flags +.Pq Vt str +Empty by default. +This variable contains additional flags passed to the +.Xr pflogd 8 +program. +.It Va pflog_instances +.Pq Vt str +If logging to more than one +.Xr pflog 4 +interface is desired, +.Va pflog_instances +is set to the list of +.Xr pflogd 8 +instances that should be started at system boot time. +If +.Va pflog_instances +is set, for each whitespace-separated +.Ar element +in the list, +.Ao Ar element Ac Ns Va _dev +and +.Ao Ar element Ac Ns Va _logfile +elements are assumed to exist. +.Ao Ar element Ac Ns Va _dev +must contain the +.Xr pflog 4 +interface to be watched by the named +.Xr pflogd 8 +instance. +.Ao Ar element Ac Ns Va _logfile +must contain the name of the logfile that will be used by the +.Xr pflogd 8 +instance. +.It Va ftpproxy_enable +.Pq Vt bool +Set to +.Dq Li NO +by default. +Setting this to +.Dq Li YES +enables +.Xr ftp-proxy 8 +which supports the +.Xr pf 4 +packet filter in translating ftp connections. +.It Va ftpproxy_flags +.Pq Vt str +Empty by default. +This variable contains additional flags passed to the +.Xr ftp-proxy 8 +program. +.It Va ftpproxy_instances +.Pq Vt str +Empty by default. +If multiple instances of +.Xr ftp-proxy 8 +are desired at boot time, +.Va ftpproxy_instances +should contain a whitespace-separated list of instance names. +For each +.Ar element +in the list, a variable named +.Ao Ar element Ac Ns Va _flags +should be defined, containing the command-line flags to be passed to the +.Xr ftp-proxy 8 +instance. +.It Va pfsync_enable +.Pq Vt bool +Set to +.Dq Li NO +by default. +Setting this to +.Dq Li YES +enables exposing +.Xr pf 4 +state changes to other hosts over the network by means of +.Xr pfsync 4 . +The +.Va pfsync_syncdev +variable +must also be set then. +.It Va pfsync_syncdev +.Pq Vt str +Empty by default. +This variable specifies the name of the network interface +.Xr pfsync 4 +should operate through. +It must be set accordingly if +.Va pfsync_enable +is set to +.Dq Li YES . +.It Va pfsync_syncpeer +.Pq Vt str +Empty by default. +This variable is optional. +By default, state change messages are sent out on the synchronisation +interface using IP multicast packets. +The protocol is IP protocol 240, PFSYNC, and the multicast group used is +224.0.0.240. +When a peer address is specified using the +.Va pfsync_syncpeer +option, the peer address is used as a destination for the pfsync +traffic, and the traffic can then be protected using +.Xr ipsec 4 . +See the +.Xr pfsync 4 +manpage for more details about using +.Xr ipsec 4 +with +.Xr pfsync 4 +interfaces. +.It Va pfsync_ifconfig +.Pq Vt str +Empty by default. +This variable can contain additional options to be passed to the +.Xr ifconfig 8 +command used to set up +.Xr pfsync 4 . +.It Va tcp_extensions +.Pq Vt bool +Set to +.Dq Li YES +by default. +Setting this to +.Dq Li NO +disables certain TCP options as described by +.Rs +.%T "RFC 1323" +.Re +Setting this to +.Dq Li NO +might help remedy such problems with connections as randomly hanging +or other weird behavior. +Some network devices are known +to be broken with respect to these options. +.It Va log_in_vain +.Pq Vt int +Set to 0 by default. +The +.Xr sysctl 8 +variables, +.Va net.inet.tcp.log_in_vain +and +.Va net.inet.udp.log_in_vain , +as described in +.Xr tcp 4 +and +.Xr udp 4 , +are set to the given value. +.It Va tcp_keepalive +.Pq Vt bool +Set to +.Dq Li YES +by default. +Setting to +.Dq Li NO +will disable probing idle TCP connections to verify that the +peer is still up and reachable. +.It Va tcp_drop_synfin +.Pq Vt bool +Set to +.Dq Li NO +by default. +Setting to +.Dq Li YES +will cause the kernel to ignore TCP frames that have both +the SYN and FIN flags set. +This prevents OS fingerprinting, but may +break some legitimate applications. +.It Va icmp_drop_redirect +.Pq Vt bool +Set to +.Dq Li AUTO +by default. +This setting will be identical to +.Dq Li YES , +if a dynamic routing daemon is enabled, because redirect processing may +cause performance issues for large routing tables. +If no such service is enabled, this setting behaves like a +.Dq Li NO . +Setting to +.Dq Li YES +will cause the kernel to ignore ICMP REDIRECT packets. +Setting to +.Dq Li NO +will cause the kernel to process ICMP REDIRECT packets. +Refer to +.Xr icmp 4 +for more information. +.It Va icmp_log_redirect +.Pq Vt bool +Set to +.Dq Li NO +by default. +Setting to +.Dq Li YES +will cause the kernel to log ICMP REDIRECT packets. +Note that +the log messages are not rate-limited, so this option should only be used +for troubleshooting networks. +Refer to +.Xr icmp 4 +for more information. +.It Va icmp_bmcastecho +.Pq Vt bool +Set to +.Dq Li YES +to respond to broadcast or multicast ICMP ping packets. +Refer to +.Xr icmp 4 +for more information. +.It Va ip_portrange_first +.Pq Vt int +If not set to +.Dq Li NO , +this is the first port in the default portrange. +Refer to +.Xr ip 4 +for more information. +.It Va ip_portrange_last +.Pq Vt int +If not set to +.Dq Li NO , +this is the last port in the default portrange. +Refer to +.Xr ip 4 +for more information. +.It Va network_interfaces +.Pq Vt str +Set to the list of network interfaces to configure on this host or +.Dq Li AUTO +(the default) for all current interfaces. +Setting the +.Va network_interfaces +variable to anything other than the default is deprecated. +Interfaces that the administrator wishes to store configuration for, +but not start at boot should be configured with the +.Dq Li NOAUTO +keyword in their +.Va ifconfig_ Ns Aq Ar interface +variables as described below. +.Pp +An +.Va ifconfig_ Ns Aq Ar interface +variable is assumed to exist for each value of +.Ar interface . +When an interface name contains any of the characters +.Dq Li .-/+ +they are translated to +.Dq Li _ +before lookup. +For example, the interface +.Va em0.102 +would be configured using the variable +.Va ifconfig_em0_102 . +.Pp +The variable can contain arguments to +.Xr ifconfig 8 , +as well as special case-insensitive keywords described below. +Such keywords are removed before passing the value to +.Xr ifconfig 8 +while the order of the other arguments is preserved. +.Pp +For example, to assign the IPv4 address 192.0.2.1/24 to the interface em0: +.Bd -literal +ifconfig_em0="inet 192.0.2.1/24 up" +.Ed +.Pp +If the variable +.Va ifconfig_ Ns Ao Ar interface Ac Ns Pa _ipv6 +is set, then +.Va ifconfig_ Ns Aq Ar interface +does not need to be set unless an IPv4 address should also be assigned to +the interface. +.Pp +It is possible to add IP alias entries using +.Xr ifconfig 8 +syntax with the address family keyword such as +.Li inet . +Assuming that the interface in question was +.Li em0 , +it might look something like this: +.Bd -literal +ifconfig_em0_alias0="inet 127.0.0.253/32" +ifconfig_em0_alias1="inet 127.0.0.254/32" +.Ed +.Pp +It also possible to configure multiple IP addresses in Classless +Inter-Domain Routing +.Pq CIDR +address notation, +whose each address component can be a range like +.Li inet 192.0.2.5-23/24 +or +.Li inet6 2001:db8:1-f::1/64 . +This notation allows address and prefix length part only, +not the other address modifiers. +Note that the maximum number of the generated addresses from a range +specification is limited to an integer value specified in +.Va netif_ipexpand_max +in +.Nm +because a small typo can unexpectedly generate a large number of addresses. +The default value is +.Li 2048 . +It can be increased by adding the following line into +.Nm : +.Bd -literal +netif_ipexpand_max="4096" +.Ed +.Pp +In the case of +.Li 192.0.2.5-23/24 , +the address 192.0.2.5 will be configured with the prefix length /24 and the +addresses 192.0.2.6 to 192.0.2.23 with the non-conflicting prefix length /32 as +explained in the +.Xr ifconfig 8 +alias section. +Note that this special CIDR handling is only for +.Li inet , +not for the other address families such as +.Li inet6 . +.Pp +With the interface in question being +.Li em0 , +an example could look like: +.Bd -literal +ifconfig_em0_alias2="inet 192.0.2.129/27" +ifconfig_em0_alias3="inet 192.0.2.1-5/28" +.Ed +.Pp +and so on. +.Pp +Note that deprecated +.Va ipv4_addrs_ Ns Aq Ar interface +variable was supported for IPv4 CIDR address notation. +The +.Va ifconfig_ Ns Ao Ar interface Ac Ns Va _alias Ns Aq Ar n +variable replaces it, though +.Va ipv4_addrs_ Ns Aq Ar interface +is still supported for backward compatibility. +.Pp +For each +.Va ifconfig_ Ns Ao Ar interface Ac Ns Va _alias Ns Aq Ar n +entry with an address family keyword, +its contents are passed to +.Xr ifconfig 8 . +Execution stops at the first unsuccessful access, so if +something like this is present: +.Bd -literal +ifconfig_em0_alias0="inet 127.0.0.251/32" +ifconfig_em0_alias1="inet 127.0.0.252/32" +ifconfig_em0_alias2="inet 127.0.0.253/32" +ifconfig_em0_alias4="inet 127.0.0.254/32" +.Ed +.Pp +Then note that alias4 would +.Em not +be added since the search would +stop with the missing +.Dq Li alias3 +entry. +Because of this difficult to manage behavior, +there is +.Va ifconfig_ Ns Ao Ar interface Ac Ns Va _aliases +variable, which has the same functionality as +.Va ifconfig_ Ns Ao Ar interface Ac Ns Va _alias Ns Aq Ar n +and can have all of the entries in a variable like the following: +.Bd -literal +ifconfig_em0_aliases="\\ + inet 127.0.0.251/32 \\ + inet 127.0.0.252/32 \\ + inet 127.0.0.253/32 \\ + inet 127.0.0.254/32" +.Ed +.Pp +It also supports netmask notation for backward compatibility. +.Pp +If the +.Pa /etc/start_if . Ns Aq Ar interface +file is present, it is read and executed by the +.Xr sh 1 +interpreter +before configuring the interface as specified in the +.Va ifconfig_ Ns Aq Ar interface +and +.Va ifconfig_ Ns Ao Ar interface Ac Ns Va _alias Ns Aq Ar n +variables. +.Pp +If a +.Va vlans_ Ns Aq Ar interface +variable is set, +a +.Xr vlan 4 +interface will be created for each item in the list with the +.Ar vlandev +argument set to +.Ar interface . +If a vlan interface's name is a number, +then that number is used as the vlan tag and the new vlan interface is +named +.Ar interface . Ns Ar tag . +Otherwise, +the vlan tag must be specified via a +.Va vlan +parameter in the +.Va create_args_ Ns Aq Ar interface +variable. +.Pp +To create a vlan device named +.Li em0.101 +on +.Li em0 +with the vlan tag 101 and the optional IPv4 address 192.0.2.1/24: +.Bd -literal +vlans_em0="101" +ifconfig_em0_101="inet 192.0.2.1/24" +.Ed +.Pp +To create a vlan device named +.Li myvlan +on +.Li em0 +with the vlan tag 102: +.Bd -literal +vlans_em0="myvlan" +create_args_myvlan="vlan 102" +.Ed +.Pp +If a +.Va wlans_ Ns Aq Ar interface +variable is set, +an +.Xr wlan 4 +interface will be created for each item in the list with the +.Ar wlandev +argument set to +.Ar interface . +Further wlan cloning arguments may be passed to the +.Xr ifconfig 8 +.Cm create +command by setting the +.Va create_args_ Ns Aq Ar interface +variable. +One or more +.Xr wlan 4 +devices must be created for each wireless device as of +.Fx 8.0 . +Debugging flags for +.Xr wlan 4 +devices as set by +.Xr wlandebug 8 +may be specified with an +.Va wlandebug_ Ns Aq Ar interface +variable. +The contents of this variable will be passed directly to +.Xr wlandebug 8 . +.Pp +If the +.Va ifconfig_ Ns Aq Ar interface +contains the keyword +.Dq Li NOAUTO +then the interface will not be configured +at boot or by +.Pa /etc/pccard_ether +when +.Va network_interfaces +is set to +.Dq Li AUTO . +.Pp +It is possible to bring up an interface with DHCP by adding +.Dq Li DHCP +to the +.Va ifconfig_ Ns Aq Ar interface +variable. +For instance, to initialize the +.Li em0 +device via DHCP, +it is possible to use something like: +.Bd -literal +ifconfig_em0="DHCP" +.Ed +.Pp +If you want to configure your wireless interface with +.Xr wpa_supplicant 8 +for use with WPA, EAP/LEAP or WEP, you need to add +.Dq Li WPA +to the +.Va ifconfig_ Ns Aq Ar interface +variable. +.Pp +On the other hand, if you want to configure your wireless interface with +.Xr hostapd 8 , +you need to add +.Dq Li HOSTAP +to the +.Va ifconfig_ Ns Aq Ar interface +variable. +.Xr hostapd 8 +will use the settings from +.Pa /etc/hostapd- Ns Ao Ar interface Ac Ns .conf +.Pp +Finally, you can add +.Xr ifconfig 8 +options in this variable, in addition to the +.Pa /etc/start_if . Ns Aq Ar interface +file. +For instance, to configure an +.Xr ath 4 +wireless device in station mode with an address obtained +via DHCP, using WPA authentication and 802.11b mode, it is +possible to use something like: +.Bd -literal +wlans_ath0="wlan0" +ifconfig_wlan0="DHCP WPA mode 11b" +.Ed +.Pp +In addition to the +.Va ifconfig_ Ns Aq Ar interface +form, a fallback variable +.Va ifconfig_DEFAULT +may be configured. +It will be used for all interfaces with no +.Va ifconfig_ Ns Aq Ar interface +variable. +.Pp +It is also possible to rename an interface by doing: +.Bd -literal +ifconfig_em0_name="net0" +ifconfig_net0="inet 192.0.2.1/24" +.Ed +.It Va ipv6_enable +.Pq Vt bool +This variable is deprecated. +Use +.Va ifconfig_ Ns Ao Ar interface Ac Ns _ipv6 +and +.Va ipv6_activate_all_interfaces +if necessary. +.Pp +If the variable is +.Dq Li YES , +.Dq Li inet6 accept_rtadv +is added to all of +.Va ifconfig_ Ns Ao Ar interface Ac Ns _ipv6 +and the +.Va ipv6_activate_all_interfaces +variable is defined as +.Dq Li YES . +.It Va ipv6_prefer +.Pq Vt bool +This variable is deprecated. +Use +.Va ip6addrctl_policy +instead. +.Pp +If the variable is +.Dq Li YES , +the default address selection policy table set by +.Xr ip6addrctl 8 +will be IPv6-preferred. +.Pp +If the variable is +.Dq Li NO , +the default address selection policy table set by +.Xr ip6addrctl 8 +will be IPv4-preferred. +.It Va ipv6_activate_all_interfaces +.Pq Vt bool +This controls initial configuration on IPv6-capable +interfaces with no corresponding +.Va ifconfig_ Ns Ao Ar interface Ac Ns _ipv6 +variable. +Note that it is not always necessary to set this variable to +.Dq YES +to use IPv6 functionality on +.Fx . +In most cases, just configuring +.Va ifconfig_ Ns Ao Ar interface Ac Ns _ipv6 +variables works. +.Pp +If the variable is +.Dq Li NO , +all interfaces which do not have a corresponding +.Va ifconfig_ Ns Ao Ar interface Ac Ns _ipv6 +variable will be marked as +.Dq Li IFDISABLED +at creation. +This means that all IPv6 functionality on that interface +is completely disabled to enforce a security policy. +If the variable is set to +.Dq YES , +the flag will be cleared on all of the interfaces. +.Pp +In most cases, just defining an +.Va ifconfig_ Ns Ao Ar interface Ac Ns _ipv6 +for an IPv6-capable interface should be sufficient. +However, if an interface is added dynamically +.Pq by some tunneling protocols such as PPP, for example , +it is often difficult to define the variable in advance. +In such a case, configuring the +.Dq Li IFDISABLED +flag can be disabled by setting this variable to +.Dq YES . +.Pp +For more details of the +.Dq Li IFDISABLED +flag and keywords +.Dq Li inet6 ifdisabled , +see +.Xr ifconfig 8 . +.Pp +Default is +.Dq Li NO . +.It Va ipv6_privacy +.Pq Vt bool +If the variable is +.Dq Li YES +privacy addresses will be generated for each IPv6 +interface as described in RFC 4941. +.It Va ipv6_network_interfaces +.Pq Vt str +This is the IPv6 equivalent of +.Va network_interfaces . +Normally manual configuration of this variable is not needed. +.It Va ipv6_cpe_wanif +.Pq Vt str +If the variable is set to an interface name, +the +.Xr ifconfig 8 +options +.Dq inet6 -no_radr accept_rtadv +will be added to the specified interface automatically before evaluating +.Va ifconfig_ Ns Ao Ar interface Ac Ns _ipv6 , +and two +.Xr sysctl 8 +variables +.Va net.inet6.ip6.rfc6204w3 +and +.Va net.inet6.ip6.no_radr +will be set to 1. +.Pp +This means the specified interface will accept ICMPv6 Router +Advertisement messages on that link and add the discovered +routers into the Default Router List. +While the other interfaces can still accept RA messages if the +.Dq inet6 accept_rtadv +option is specified, adding +routes into the Default Router List will be disabled by +.Dq inet6 no_radr +option by default. +See +.Xr ifconfig 8 +for more details. +.Pp +Note that ICMPv6 Router Advertisement messages will be +accepted even when +.Va net.inet6.ip6.forwarding +is 1 +.Pq packet forwarding is enabled +when +.Va net.inet6.ip6.rfc6204w3 +is set to 1. +.Pp +Default is +.Dq Li NO . +.It Va ifconfig_ Ns Ao Ar interface Ac Ns _descr +.Pq Vt str +This assigns arbitrary description to an interface. +The +.Xr sysctl 8 +variable +.Va net.ifdescr_maxlen +limits its length. +This static setting may be overridden by commands +started with dynamic interface configuration utilities +like +.Xr dhclient 8 +hooks. +The description can be seen with +.Xr ifconfig 8 +command and it may be exported with +.Xr bsnmpd 1 +daemon using its MIB-2 module. +.It Va ifconfig_ Ns Ao Ar interface Ac Ns _ipv6 +.Pq Vt str +IPv6 functionality on an interface should be configured by +.Va ifconfig_ Ns Ao Ar interface Ac Ns _ipv6 , +instead of setting ifconfig parameters in +.Va ifconfig_ Ns Aq Ar interface . +If this variable is empty, all IPv6 configurations on the +specified interface by other variables such as +.Va ipv6_prefix_ Ns Ao Ar interface Ac +will be ignored. +.Pp +Aliases should be set by +.Va ifconfig_ Ns Ao Ar interface Ac Ns Va _alias Ns Aq Ar n +with +.Dq Li inet6 +keyword. +For example: +.Bd -literal +ifconfig_em0_ipv6="inet6 2001:db8:1::1 prefixlen 64" +ifconfig_em0_alias0="inet6 2001:db8:2::1 prefixlen 64" +.Ed +.Pp +Interfaces that have an +.Dq Li inet6 accept_rtadv +keyword in +.Va ifconfig_ Ns Ao Ar interface Ac Ns _ipv6 +setting will be automatically configured by SLAAC +.Pq StateLess Address AutoConfiguration +described in +.Rs +.%T "RFC 4862" +.Re +.Pp +Note that a link-local address will be automatically configured in +addition to the configured global-scope addresses because the IPv6 +specifications require it on each link. +The address is calculated from the MAC address by using an algorithm +defined in +.Rs +.%T "RFC 4862" +.%O "Section 5.3" +.Re +.Pp +If only a link-local address is needed on the interface, +the following configuration can be used: +.Bd -literal +ifconfig_em0_ipv6="inet6 auto_linklocal" +.Ed +.Pp +A link-local address can also be configured manually. +This is useful for the default router address of an IPv6 router +so that it does not change when the network interface +card is replaced. +For example: +.Bd -literal +ifconfig_em0_ipv6="inet6 fe80::1 prefixlen 64" +.Ed +.It Va ipv6_prefix_ Ns Aq Ar interface +.Pq Vt str +If one or more prefixes are defined in +.Va ipv6_prefix_ Ns Aq Ar interface +addresses based on each prefix and the EUI-64 interface index will be +configured on that interface. +Note that this variable will be ignored when +.Va ifconfig_ Ns Ao Ar interface Ac Ns _ipv6 +is empty. +.Pp +For example, the following configuration +.Bd -literal +ipv6_prefix_em0="2001:db8:1:0 2001:db8:2:0" +.Ed +.Pp +is equivalent to the following: +.Bd -literal +ifconfig_em0_alias0="inet6 2001:db8:1:: eui64 prefixlen 64" +ifconfig_em0_alias1="inet6 2001:db8:1:: prefixlen 64 anycast" +ifconfig_em0_alias2="inet6 2001:db8:2:: eui64 prefixlen 64" +ifconfig_em0_alias3="inet6 2001:db8:2:: prefixlen 64 anycast" +.Ed +.Pp +These Subnet-Router anycast addresses will be added only when +.Va ipv6_gateway_enable +is YES. +.It Va ipv6_default_interface +.Pq Vt str +If not set to +.Dq Li NO , +this is the default output interface for scoped addresses. +This works only with ipv6_gateway_enable="NO". +.It Va ip6addrctl_enable +.Pq Vt bool +This variable is to enable configuring default address selection policy table +.Pq RFC 3484 . +The table can be specified in another variable +.Va ip6addrctl_policy . +For +.Va ip6addrctl_policy +the following keywords can be specified: +.Dq Li ipv4_prefer , +.Dq Li ipv6_prefer , +or +.Dq Li AUTO . +.Pp +If +.Dq Li ipv4_prefer +or +.Dq Li ipv6_prefer +is specified, +.Xr ip6addrctl 8 +installs a pre-defined policy table described in Section 10.3 +.Pq IPv4-preferred +or 2.1 +.Pq IPv6-preferred +of RFC 3484. +.Pp +If +.Dq Li AUTO +is specified, it attempts to read a file +.Pa /etc/ip6addrctl.conf +first. +If this file is found, +.Xr ip6addrctl 8 +reads and installs it. +If not found, a policy is automatically set +according to +.Va ipv6_activate_all_interfaces +variable; if the variable is set to +.Dq Li YES +the IPv6-preferred one is used. +Otherwise IPv4-preferred. +.Pp +The default value of +.Va ip6addrctl_enable +and +.Va ip6addrctl_policy +are +.Dq Li YES +and +.Dq Li AUTO , +respectively. +.It Va cloned_interfaces +.Pq Vt str +Set to the list of clonable network interfaces to create on this host. +Further cloning arguments may be passed to the +.Xr ifconfig 8 +.Cm create +command for each interface by setting the +.Va create_args_ Ns Aq Ar interface +variable. +If an interface name is specified with +.Dq :sticky +keyword, +the interface will not be destroyed even when +.Pa rc.d/netif +script is invoked with +.Dq stop +argument. +This is useful when reconfiguring the interface without destroying it. +Entries in +.Va cloned_interfaces +are automatically appended to +.Va network_interfaces +for configuration. +.It Va cloned_interfaces_sticky +.Pq Vt bool +This variable is to globally enable functionality of +.Dq :sticky +keyword in +.Va cloned_interfaces +for all interfaces. +The default value is +.Dq NO . +Even if this variable is specified to +.Dq YES , +.Dq :nosticky +keyword can be used to override it on per interface basis. +.It Va gif_interfaces +Set to the list of +.Xr gif 4 +tunnel interfaces to configure on this host. +A +.Va gifconfig_ Ns Aq Ar interface +variable is assumed to exist for each value of +.Ar interface . +The value of this variable is used to configure the link layer of the +tunnel using the +.Cm tunnel +option to +.Xr ifconfig 8 . +Additionally, this option ensures that each listed interface is created +via the +.Cm create +option to +.Xr ifconfig 8 +before attempting to configure it. +.Pp +For example, configure two +.Xr gif 4 +interfaces with: +.Bd -literal +gif_interfaces="gif0 gif1" +gifconfig_gif0="100.64.0.1 100.64.0.2" +ifconfig_gif0="inet 10.0.0.1/30 10.0.0.2" +gifconfig_gif1="inet6 2a00::1 2a01::1" +ifconfig_gif1="inet 10.1.0.1/30 10.1.0.2" +.Ed +.It Va ppp_enable +.Pq Vt bool +If set to +.Dq Li YES , +run the +.Xr ppp 8 +daemon. +.It Va ppp_profile +.Pq Vt str +The name of the profile to use from +.Pa /etc/ppp/ppp.conf . +Also used for per-profile overrides of +.Va ppp_mode +and +.Va ppp_nat , +and +.Va ppp_ Ns Ao Ar profile Ac Ns _unit . +When the profile name contains any of the characters +.Dq Li .-/+ +they are translated to +.Dq Li _ +for the proposes of the override variable names. +.It Va ppp_mode +.Pq Vt str +Mode in which to run the +.Xr ppp 8 +daemon. +.It Va ppp_ Ns Ao Ar profile Ac Ns _mode +.Pq Vt str +Overrides the global +.Va ppp_mode +for +.Ar profile . +Accepted modes are +.Dq Li auto , +.Dq Li ddial , +.Dq Li direct +and +.Dq Li dedicated . +See the manual for a full description. +.It Va ppp_nat +.Pq Vt bool +If set to +.Dq Li YES , +enables network address translation. +Used in conjunction with +.Va gateway_enable +allows hosts on private network addresses access to the Internet using +this host as a network address translating router. +Default is +.Dq Li YES . +.It Va ppp_ Ns Ao Ar profile Ac Ns _nat +.Pq Vt str +Overrides the global +.Va ppp_nat +for +.Ar profile . +.It Va ppp_ Ns Ao Ar profile Ac Ns _unit +.Pq Vt int +Set the unit number to be used for this profile. +See the manual description of +.Fl unit Ns Ar N +for details. +.It Va ppp_user +.Pq Vt str +The name of the user under which +.Xr ppp 8 +should be started. +By +default, +.Xr ppp 8 +is started as +.Dq Li root . +.It Va rc_conf_files +.Pq Vt str +This option is used to specify a list of files that will override +the settings in +.Pa /etc/defaults/rc.conf . +The files will be read in the order in which they are specified and should +include the full path to the file. +By default, the files specified are +.Pa /etc/rc.conf +and +.Pa /etc/rc.conf.local . +.It Va zfs_enable +.Pq Vt bool +If set to +.Dq Li YES , +.Pa /etc/rc.d/zfs +will attempt to automatically mount ZFS file systems and initialize ZFS volumes +(ZVOLs). +.It Va zpool_reguid +.Pq Vt str +A space-separated list of ZFS pool names for which new pool GUIDs should be +assigned upon first boot. +This is useful when using a ZFS pool copied from a template, such as a virtual +machine image. +.It Va zpool_upgrade +.Pq Vt str +A space-separated list of ZFS pool names for which the version should be +upgraded upon first boot. +This is useful when using a ZFS pool generated by the +.Xr makefs 8 +utility. +.It Va gptboot_enable +.Pq Vt bool +If set to +.Dq Li YES , +.Pa /etc/rc.d/gptboot +will log if the system successfully (or not) booted from a GPT partition, +which had the +.Ar bootonce +attribute set using +.Xr gpart 8 +utility. +.It Va geli_devices +.Pq Vt str +List of devices to automatically attach on boot. +Note that .eli devices from +.Pa /etc/fstab +are automatically appended to this list. +.It Va geli_groups +.Pq Vt str +List of groups containing devices to automatically attach on boot with the same +keyfiles and passphrase. +This must be accompanied with a corresponding +.Va geli_ Ns Ao Ar group Ac Ns Va _devices +variable. +.It Va geli_tries +.Pq Vt int +Number of times user is asked for the pass-phrase. +If empty, it will be taken from +.Va kern.geom.eli.tries +sysctl variable. +.It Va geli_default_flags +.Pq Vt str +Default flags to use by +.Xr geli 8 +when configuring disk encryption. +Flags can be configured for every device separately by defining the +.Va geli_ Ns Ao Ar device Ac Ns Va _flags +variable, and for every group separately by defining the +.Va geli_ Ns Ao Ar group Ac Ns Va _flags +variable. +.It Va geli_autodetach +.Pq Vt str +Specifies if GELI devices should be marked for detach on last close after +file systems are mounted. +Default is +.Dq Li YES . +This can be changed for every device separately by defining the +.Va geli_ Ns Ao Ar device Ac Ns Va _autodetach +variable. +.It Va root_rw_mount +.Pq Vt bool +Set to +.Dq Li YES +by default. +After the file systems are checked at boot time, the root file system +is remounted as read-write if this is set to +.Dq Li YES . +Diskless systems that mount their root file system from a read-only remote +NFS share should set this to +.Dq Li NO +in their +.Pa rc.conf . +.It Va fsck_y_enable +.Pq Vt bool +If set to +.Dq Li YES , +.Xr fsck 8 +will be run with the +.Fl y +flag if the initial preen +of the file systems fails. +.It Va background_fsck +.Pq Vt bool +If set to +.Dq Li NO , +the system will not attempt to run +.Xr fsck 8 +in the background where possible. +.It Va background_fsck_delay +.Pq Vt int +The amount of time in seconds to sleep before starting a background +.Xr fsck 8 . +It defaults to sixty seconds to allow large applications such as +the X server to start before disk I/O bandwidth is monopolized by +.Xr fsck 8 . +If set to a negative number, the background file system check will be +delayed indefinitely to allow the administrator to run it at a more +convenient time. +For example it may be run from +.Xr cron 8 +by adding a line like +.Pp +.Dl "0 4 * * * root /etc/rc.d/bgfsck forcestart" +.Pp +to +.Pa /etc/crontab . +.It Va netfs_types +.Pq Vt str +List of file system types that are network-based. +This list should generally not be modified by end users. +Use +.Va extra_netfs_types +instead. +.It Va extra_netfs_types +.Pq Vt str +If set to something other than +.Dq Li NO +(the default), +this variable extends the list of file system types +for which automatic mounting at startup by +.Xr rc 8 +should be delayed until the network is initialized. +It should contain +a whitespace-separated list of network file system descriptor pairs, +each consisting of a file system type as passed to +.Xr mount 8 +and a human-readable, one-word description, +joined with a colon +.Pq Ql \&: . +Extending the default list in this way is only necessary +when third party file system types are used. +.It Va syslogd_enable +.Pq Vt bool +If set to +.Dq Li YES , +run the +.Xr syslogd 8 +daemon. +Note, the +.Va syslogd_oomprotect +variable is set to +.Dq Li YES +by default in +.Pa /etc/defaults/rc.conf . +.It Va syslogd_program +.Pq Vt str +Path to +.Xr syslogd 8 +(default +.Pa /usr/sbin/syslogd ) . +.It Va syslogd_flags +.Pq Vt str +If +.Va syslogd_enable +is set to +.Dq Li YES , +these are the flags to pass to +.Xr syslogd 8 . +.It Va inetd_enable +.Pq Vt bool +If set to +.Dq Li YES , +run the +.Xr inetd 8 +daemon. +.It Va inetd_program +.Pq Vt str +Path to +.Xr inetd 8 +(default +.Pa /usr/sbin/inetd ) . +.It Va inetd_flags +.Pq Vt str +If +.Va inetd_enable +is set to +.Dq Li YES , +these are the flags to pass to +.Xr inetd 8 . +.It Va hastd_enable +.Pq Vt bool +If set to +.Dq Li YES , +run the +.Xr hastd 8 +daemon. +.It Va hastd_program +.Pq Vt str +Path to +.Xr hastd 8 +(default +.Pa /sbin/hastd ) . +.It Va hastd_flags +.Pq Vt str +If +.Va hastd_enable +is set to +.Dq Li YES , +these are the flags to pass to +.Xr hastd 8 . +.It Va local_unbound_enable +.Pq Vt bool +If set to +.Dq Li YES , +run the +.Xr unbound 8 +daemon as a local caching DNS resolver. +Note, the +.Va local_unbound_oomprotect +variable is set to +.Dq Li YES +by default in +.Pa /etc/defaults/rc.conf . +.It Va nscd_enable +.Pq Vt bool +Set to +.Dq Li YES +to start the +.Xr nscd 8 +caching daemon for the +.Nm nsswitch +subsystem. +.It Va nscd_flags +.Pq Vt str +If +.Va nscd_enable +is set to +.Dq Li YES , +these flags are passed to +.Xr nscd 8 . +.It Va kdc_enable +.Pq Vt bool +Set to +.Dq Li YES +to start a Kerberos 5 authentication server +at boot time. +.It Va kdc_program +.Pq Vt str +If +.Va kdc_enable +is set to +.Dq Li YES +this is the path to Kerberos 5 Authentication Server. +.It Va kdc_flags +.Pq Vt str +Empty by default. +This variable contains additional flags to be passed to the Kerberos 5 +authentication server. +.It Va kadmind_enable +.Pq Vt bool +Set to +.Dq Li YES +to start +.Xr kadmind 8 , +the Kerberos 5 Administration Daemon; set to +.Dq Li NO +on a slave server. +.It Va kadmind_program +.Pq Vt str +If +.Va kadmind_enable +is set to +.Dq Li YES +this is the path to Kerberos 5 Administration Daemon. +.It Va kpasswdd_enable +.Pq Vt bool +Set to +.Dq Li YES +to start +.Xr kpasswdd 8 , +the Kerberos 5 Password-Changing Daemon; set to +.Dq Li NO +on a slave server. +.It Va kpasswdd_program +.Pq Vt str +If +.Va kpasswdd_enable +is set to +.Dq Li YES +this is the path to Kerberos 5 Password-Changing Daemon. +.It Va kfd_enable +.Pq Vt bool +Set to +.Dq Li YES +to start +.Xr kfd 8 , +the Kerberos 5 ticket forwarding daemon, at the boot time. +.It Va kfd_program +.Pq Vt str +Path to +.Xr kfd 8 +(default +.Pa /usr/libexec/kfd ) . +.It Va rwhod_enable +.Pq Vt bool +If set to +.Dq Li YES , +run the +.Xr rwhod 8 +daemon at boot time. +.It Va rwhod_flags +.Pq Vt str +If +.Va rwhod_enable +is set to +.Dq Li YES , +these are the flags to pass to it. +.It Va update_motd +.Pq Vt bool +If set to +.Dq Li YES , +.Pa /var/run/motd +will be updated at boot time to reflect the kernel release +being run. +If set to +.Dq Li NO , +.Pa /var/run/motd +will not be updated. +.It Va nfs_client_enable +.Pq Vt bool +If set to +.Dq Li YES , +run the NFS client daemons at boot time. +.It Va nfs_access_cache +.Pq Vt int +If +.Va nfs_client_enable +is set to +.Dq Li YES , +this can be set to +.Dq Li 0 +to disable NFS ACCESS RPC caching, or to the number of seconds for which +NFS ACCESS +results should be cached. +A value of 2-10 seconds will substantially reduce network +traffic for many NFS operations. +.It Va nfs_server_enable +.Pq Vt bool +If set to +.Dq Li YES , +run the NFS server daemons at boot time. +.It Va nfs_server_flags +.Pq Vt str +If +.Va nfs_server_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr nfsd 8 +daemon. +.It Va nfsv4_server_enable +.Pq Vt bool +If +.Va nfs_server_enable +is set to +.Dq Li YES +and +.Va nfsv4_server_enable +is set to +.Dq Li YES , +enable the server for NFSv4 as well as NFSv2 and NFSv3. +.It Va nfsv4_server_only +.Pq Vt bool +If +.Va nfs_server_enable +is set to +.Dq Li YES +and +.Va nfsv4_server_only +is set to +.Dq Li YES , +enable the NFS server for NFSv4 only. +.It Va nfs_server_maxio +.Pq Vt int +value to set vfs.nfsd.srvmaxio to, which is the +maximum I/O size for the NFS server. +.It Va tlsclntd_enable +.Pq Vt bool +If set to +.Dq Li YES , +run the +.Xr rpc.tlsclntd 8 +daemon, which is needed for NFS-over-TLS NFS mounts. +.It Va tlsservd_enable +.Pq Vt bool +If set to +.Dq Li YES , +run the +.Xr rpc.tlsservd 8 +daemon, which is needed for the +.Xr nfsd 8 +to support NFS-over-TLS NFS mounts. +.It Va nfsuserd_enable +.Pq Vt bool +If +.Va nfsuserd_enable +is set to +.Dq Li YES , +run the nfsuserd daemon, which is needed for NFSv4 in order +to map between user/group names vs uid/gid numbers. +If +.Va nfsv4_server_enable +is set to +.Dq Li YES , +this will be forced enabled. +.It Va nfsuserd_flags +.Pq Vt str +If +.Va nfsuserd_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr nfsuserd 8 +daemon. +.It Va nfscbd_enable +.Pq Vt bool +If +.Va nfscbd_enable +is set to +.Dq Li YES , +run the nfscbd daemon, which enables callbacks/delegations for the NFSv4 client. +.It Va nfscbd_flags +.Pq Vt str +If +.Va nfscbd_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr nfscbd 8 +daemon. +.It Va mountd_enable +.Pq Vt bool +If set to +.Dq Li YES , +and no +.Va nfs_server_enable +is set, start +.Xr mountd 8 , +but not +.Xr nfsd 8 +daemon. +It is commonly needed to run CFS without real NFS used. +.It Va mountd_flags +.Pq Vt str +If +.Va mountd_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr mountd 8 +daemon. +.It Va weak_mountd_authentication +.Pq Vt bool +If set to +.Dq Li YES , +allow services like PCNFSD to make non-privileged mount +requests. +.It Va nfs_reserved_port_only +.Pq Vt bool +If set to +.Dq Li YES , +provide NFS services only on a secure port. +.It Va nfs_bufpackets +.Pq Vt int +If set to a number, indicates the number of packets worth of +socket buffer space to reserve on an NFS client. +The kernel default is typically 4. +Using a higher number may be +useful on gigabit networks to improve performance. +The minimum value is +2 and the maximum is 64. +.It Va rpc_lockd_enable +.Pq Vt bool +If set to +.Dq Li YES +and also an NFS server or client, run +.Xr rpc.lockd 8 +at boot time. +.It Va rpc_lockd_flags +.Pq Vt str +If +.Va rpc_lockd_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr rpc.lockd 8 +daemon. +.It Va rpc_statd_enable +.Pq Vt bool +If set to +.Dq Li YES +and also an NFS server or client, run +.Xr rpc.statd 8 +at boot time. +.It Va rpc_statd_flags +.Pq Vt str +If +.Va rpc_statd_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr rpc.statd 8 +daemon. +.It Va rpcbind_program +.Pq Vt str +Path to +.Xr rpcbind 8 +(default +.Pa /usr/sbin/rpcbind ) . +.It Va rpcbind_enable +.Pq Vt bool +If set to +.Dq Li YES , +run the +.Xr rpcbind 8 +service at boot time. +.It Va rpcbind_flags +.Pq Vt str +If +.Va rpcbind_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr rpcbind 8 +daemon. +.It Va pppoed_enable +.Pq Vt bool +If set to +.Dq Li YES , +run the +.Xr pppoed 8 +daemon at boot time to provide PPP over Ethernet services. +.It Va pppoed_ Ns Aq Ar provider +.Pq Vt str +.Xr pppoed 8 +listens to requests to this +.Ar provider +and ultimately runs +.Xr ppp 8 +with a +.Ar system +argument of the same name. +.It Va pppoed_flags +.Pq Vt str +Additional flags to pass to +.Xr pppoed 8 . +.It Va pppoed_interface +.Pq Vt str +The network interface to run +.Xr pppoed 8 +on. +This is mandatory when +.Va pppoed_enable +is set to +.Dq Li YES . +.It Va ntpdate_enable +.Pq Vt bool +If set to +.Dq Li YES , +run +.Xr ntpdate 8 +at system startup. +This command is intended to +synchronize the system clock only +.Em once +from some standard reference. +.Pp +Note that the use of the +.Va ntpd_sync_on_start +variable is a preferred alternative to the +.Xr ntpdate 8 +utility as +.Xr ntpdate 8 +is to be retired from the NTP distribution. +.It Va ntpdate_config +.Pq Vt str +Configuration file for +.Xr ntpdate 8 . +Default +.Pa /etc/ntp.conf . +.It Va ntpdate_hosts +.Pq Vt str +A whitespace-separated list of NTP servers to synchronize with at startup. +The default is to use the servers listed in +.Va ntpdate_config , +if that file exists. +.It Va ntpdate_program +.Pq Vt str +Path to +.Xr ntpdate 8 +(default +.Pa /usr/sbin/ntpdate ) . +.It Va ntpdate_flags +.Pq Vt str +If +.Va ntpdate_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr ntpdate 8 +command (typically a hostname). +.It Va ntpd_enable +.Pq Vt bool +If set to +.Dq Li YES , +run the +.Xr ntpd 8 +command at boot time. +.It Va ntpd_program +.Pq Vt str +Path to +.Xr ntpd 8 +(default +.Pa /usr/sbin/ntpd ) . +.It Va ntpd_config +.Pq Vt str +Path to +.Xr ntpd 8 +configuration file. +Default +.Pa /etc/ntp.conf . +.It Va ntpd_flags +.Pq Vt str +If +.Va ntpd_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr ntpd 8 +daemon. +.It Va ntpd_sync_on_start +.Pq Vt bool +If set to +.Dq Li YES , +.Xr ntpd 8 +is run with the +.Fl g +flag, which syncs the system's clock on startup. +See +.Xr ntpd 8 +for more information regarding the +.Fl g +option. +This is a preferred alternative to using +.Xr ntpdate 8 +or specifying the +.Va ntpdate_enable +variable. +.It Va nis_client_enable +.Pq Vt bool +If set to +.Dq Li YES , +run the +.Xr ypbind 8 +service at system boot time. +.It Va nis_client_flags +.Pq Vt str +If +.Va nis_client_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr ypbind 8 +service. +.It Va nis_ypldap_enable +.Pq Vt bool +If set to +.Dq Li YES , +run the +.Xr ypldap 8 +daemon at system boot time. +.It Va nis_ypldap_flags +.Pq Vt str +If +.Va nis.ypldap_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr ypldap 8 +daemon. +.It Va nis_ypset_enable +.Pq Vt bool +If set to +.Dq Li YES , +run the +.Xr ypset 8 +daemon at system boot time. +.It Va nis_ypset_flags +.Pq Vt str +If +.Va nis_ypset_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr ypset 8 +daemon. +.It Va nis_server_enable +.Pq Vt bool +If set to +.Dq Li YES , +run the +.Xr ypserv 8 +daemon at system boot time. +.It Va nis_server_flags +.Pq Vt str +If +.Va nis_server_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr ypserv 8 +daemon. +.It Va nis_ypxfrd_enable +.Pq Vt bool +If set to +.Dq Li YES , +run the +.Xr rpc.ypxfrd 8 +daemon at system boot time. +.It Va nis_ypxfrd_flags +.Pq Vt str +If +.Va nis_ypxfrd_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr rpc.ypxfrd 8 +daemon. +.It Va nis_yppasswdd_enable +.Pq Vt bool +If set to +.Dq Li YES , +run the +.Xr rpc.yppasswdd 8 +daemon at system boot time. +.It Va nis_yppasswdd_flags +.Pq Vt str +If +.Va nis_yppasswdd_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr rpc.yppasswdd 8 +daemon. +.It Va rpc_ypupdated_enable +.Pq Vt bool +If set to +.Dq Li YES , +run the +.Nm rpc.ypupdated +daemon at system boot time. +.It Va bsnmpd_enable +.Pq Vt bool +If set to +.Dq Li YES , +run the +.Xr bsnmpd 1 +daemon at system boot time. +Be sure to understand the security implications of running an SNMP daemon +on your host. +.It Va bsnmpd_flags +.Pq Vt str +If +.Va bsnmpd_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr bsnmpd 1 +daemon. +.It Va defaultrouter +.Pq Vt str +If not set to +.Dq Li NO , +create a default route to this host name or IP address +(use an IP address if this router is also required to get to the +name server!). +.It Va defaultrouter_fibN +.Pq Vt str +If not set to +.Dq Li NO , +create a default route in FIB N to this host name or IP address. +.It Va ipv6_defaultrouter +.Pq Vt str +The IPv6 equivalent of +.Va defaultrouter . +.It Va ipv6_defaultrouter_fibN +.Pq Vt str +The IPv6 equivalent of +.Va defaultrouter_fibN . +.It Va static_arp_pairs +.Pq Vt str +Set to the list of static ARP pairs that are to be added at system +boot time. +For each whitespace separated +.Ar element +in the value, a +.Va static_arp_ Ns Aq Ar element +variable is assumed to exist whose contents will later be passed to a +.Dq Nm arp Cm -S +operation. +For example +.Bd -literal +static_arp_pairs="gw" +static_arp_gw="192.168.1.1 00:01:02:03:04:05" +.Ed +.It Va static_ndp_pairs +.Pq Vt str +Set to the list of static NDP pairs that are to be added at system +boot time. +For each whitespace separated +.Ar element +in the value, a +.Va static_ndp_ Ns Aq Ar element +variable is assumed to exist whose contents will later be passed to a +.Dq Nm ndp Cm -s +operation. +For example +.Bd -literal +static_ndp_pairs="gw" +static_ndp_gw="2001:db8:3::1 00:01:02:03:04:05" +.Ed +.It Va static_routes +.Pq Vt str +Set to the list of static routes that are to be added at system +boot time. +If not set to +.Dq Li NO +then for each whitespace separated +.Ar element +in the value, a +.Va route_ Ns Aq Ar element +variable is assumed to exist +whose contents will later be passed to a +.Dq Nm route Cm add +operation. +For example: +.Bd -literal +static_routes="ext mcast:gif0 gif0local:gif0" +route_ext="-net 10.0.0.0/24 -gateway 192.168.0.1" +route_mcast="-net 224.0.0.0/4 -iface gif0" +route_gif0local="-host 169.254.1.1 -iface lo0" +.Ed +.Pp +When an +.Ar element +is in the form of +.Li name:ifname , +the route is specific to the interface +.Li ifname . +.It Va ipv6_static_routes +.Pq Vt str +The IPv6 equivalent of +.Va static_routes . +If not set to +.Dq Li NO +then for each whitespace separated +.Ar element +in the value, a +.Va ipv6_route_ Ns Aq Ar element +variable is assumed to exist +whose contents will later be passed to a +.Dq Nm route Cm add Fl inet6 +operation. +.It Va gateway_enable +.Pq Vt bool +If set to +.Dq Li YES , +configure host to act as an IP router, e.g.\& to forward packets +between interfaces. +.It Va ipv6_gateway_enable +.Pq Vt bool +The IPv6 equivalent of +.Va gateway_enable . +.It Va routed_enable +.Pq Vt bool +If set to +.Dq Li YES , +run a routing daemon of some sort, based on the +settings of +.Va routed_program +and +.Va routed_flags . +.It Va route6d_enable +.Pq Vt bool +The IPv6 equivalent of +.Va routed_enable . +If set to +.Dq Li YES , +run a routing daemon of some sort, based on the +settings of +.Va route6d_program +and +.Va route6d_flags . +.It Va routed_program +.Pq Vt str +If +.Va routed_enable +is set to +.Dq Li YES , +this is the name of the routing daemon to use. +The default is +.Xr routed 8 . +.It Va route6d_program +.Pq Vt str +The IPv6 equivalent of +.Va routed_program . +The default is +.Xr route6d 8 . +.It Va routed_flags +.Pq Vt str +If +.Va routed_enable +is set to +.Dq Li YES , +these are the flags to pass to the routing daemon. +.It Va route6d_flags +.Pq Vt str +The IPv6 equivalent of +.Va routed_flags . +.It Va rtadvd_enable +.Pq Vt bool +If set to +.Dq Li YES , +run the +.Xr rtadvd 8 +daemon at boot time. +The +.Xr rtadvd 8 +utility sends ICMPv6 Router Advertisement messages to +the interfaces specified in +.Va rtadvd_interfaces . +This should only be enabled with great care. +You may want to fine-tune +.Xr rtadvd.conf 5 . +.It Va rtadvd_flags +.Pq Vt str +If +.Va rtadvd_enable +is set to +.Dq Li YES , +these are the flags to pass to +.Xr rtadvd 8 . +.It Va rtadvd_interfaces +.Pq Vt str +If +.Va rtadvd_enable +is set to +.Dq Li YES +this is the list of interfaces to use. +.It Va arpproxy_all +.Pq Vt bool +If set to +.Dq Li YES , +enable global proxy ARP. +.It Va forward_sourceroute +.Pq Vt bool +If set to +.Dq Li YES +and +.Va gateway_enable +is also set to +.Dq Li YES , +source-routed packets are forwarded. +.It Va accept_sourceroute +.Pq Vt bool +If set to +.Dq Li YES , +the system will accept source-routed packets directed at it. +.It Va rarpd_enable +.Pq Vt bool +If set to +.Dq Li YES , +run the +.Xr rarpd 8 +daemon at system boot time. +.It Va rarpd_flags +.Pq Vt str +If +.Va rarpd_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr rarpd 8 +daemon. +.It Va bootparamd_enable +.Pq Vt bool +If set to +.Dq Li YES , +run the +.Xr bootparamd 8 +daemon at system boot time. +.It Va bootparamd_flags +.Pq Vt str +If +.Va bootparamd_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr bootparamd 8 +daemon. +.It Va stf_interface_ipv4addr +.Pq Vt str +If not set to +.Dq Li NO , +this is the local IPv4 address for 6to4 (IPv6 over IPv4 tunneling +interface). +Specify this entry to enable the 6to4 interface. +.It Va stf_interface_ipv4plen +.Pq Vt int +Prefix length for 6to4 IPv4 addresses, to limit peer address range. +An effective value is 0-31. +.It Va stf_interface_ipv6_ifid +.Pq Vt str +IPv6 interface ID for +.Xr stf 4 . +This can be set to +.Dq Li AUTO . +.It Va stf_interface_ipv6_slaid +.Pq Vt str +IPv6 Site Level Aggregator for +.Xr stf 4 . +.It Va ipv6_ipv4mapping +.Pq Vt bool +If set to +.Dq Li YES +this enables IPv4 mapped IPv6 address communication (like +.Li ::ffff:a.b.c.d ) . +.It Va rtsold_enable +.Pq Vt bool +Set to +.Dq Li YES +to enable the +.Xr rtsold 8 +daemon to send ICMPv6 Router Solicitation messages. +.It Va rtsold_flags +.Pq Vt str +If +.Va rtsold_enable +is set to +.Dq Li YES , +these are the flags to pass to +.Xr rtsold 8 . +.It Va rtsol_flags +.Pq Vt str +For interfaces configured with the +.Dq Li inet6 accept_rtadv +keyword, these are the flags to pass to +.Xr rtsol 8 . +.Pp +Note that +.Va rtsold_enable +is mutually exclusive to +.Va rtsol_flags ; +.Va rtsold_enable +takes precedence. +.It Va keybell +.Pq Vt str +The keyboard bell sound. +Set to +.Dq Li normal , +.Dq Li visual , +.Dq Li off , +or +.Dq Li NO +if the default behavior is desired. +For details, refer to the +.Xr kbdcontrol 1 +manpage. +.It Va keyboard +.Pq Vt str +If set to a non-null string, the virtual console's keyboard input is +set to this device. +.It Va keymap +.Pq Vt str +If set to +.Dq Li NO , +no keymap is installed, otherwise the value is used to install +the keymap file found in +.Pa /usr/share/syscons/keymaps/ Ns Ao Ar value Ac Ns Pa .kbd +(if using +.Xr syscons 4 ) or +.Pa /usr/share/vt/keymaps/ Ns Ao Ar value Ac Ns Pa .kbd +(if using +.Xr vt 4 ) . +.It Va keyrate +.Pq Vt str +The keyboard repeat speed. +Set to +.Dq Li slow , +.Dq Li normal , +.Dq Li fast , +or +.Dq Li NO +if the default behavior is desired. +.It Va keychange +.Pq Vt str +If not set to +.Dq Li NO , +attempt to program the function keys with the value. +The value should +be a single string of the form: +.Dq Ar funkey_number new_value Op Ar funkey_number new_value ... . +.It Va cursor +.Pq Vt str +Can be set to the value of +.Dq Li normal , +.Dq Li blink , +.Dq Li destructive , +or +.Dq Li NO +to set the cursor behavior explicitly or choose the default behavior. +.It Va scrnmap +.Pq Vt str +If set to +.Dq Li NO , +no screen map is installed, otherwise the value is used to install +the screen map file in +.Pa /usr/share/syscons/scrnmaps/ Ns Aq Ar value . +This parameter is ignored when using +.Xr vt 4 +as the console driver. +.It Va font8x16 +.Pq Vt str +If set to +.Dq Li NO , +the default 8x16 font value is used for screen size requests, otherwise +the value in +.Pa /usr/share/syscons/fonts/ Ns Aq Ar value +or +.Pa /usr/share/vt/fonts/ Ns Aq Ar value +is used (depending on the console driver being used). +.It Va font8x14 +.Pq Vt str +If set to +.Dq Li NO , +the default 8x14 font value is used for screen size requests, otherwise +the value in +.Pa /usr/share/syscons/fonts/ Ns Aq Ar value +or +.Pa /usr/share/vt/fonts/ Ns Aq Ar value +is used (depending on the console driver being used). +.It Va font8x8 +.Pq Vt str +If set to +.Dq Li NO , +the default 8x8 font value is used for screen size requests, otherwise +the value in +.Pa /usr/share/syscons/fonts/ Ns Aq Ar value +or +.Pa /usr/share/vt/fonts/ Ns Aq Ar value +is used (depending on the console driver being used). +.It Va blanktime +.Pq Vt int +If set to +.Dq Li NO , +the default screen blanking interval is used, otherwise it is set +to +.Ar value +seconds. +.It Va saver +.Pq Vt str +If not set to +.Dq Li NO , +this is the actual screen saver to use +.Li ( blank , snake , daemon , +etc). +.It Va moused_nondefault_enable +.Pq Vt str +If set to +.Dq Li NO , +the mouse device specified on +the command line is not automatically treated as enabled by the +.Pa /etc/rc.d/moused +script. +Having this variable set to +.Dq Li YES +allows a +.Xr usb 4 +mouse, +for example, +to be enabled as soon as it is plugged in. +.It Va moused_enable +.Pq Vt str +If set to +.Dq Li YES , +the +.Xr moused 8 +daemon is started for doing cut/paste selection on the console. +.It Va moused_type +.Pq Vt str +This is the protocol type of the mouse connected to this host. +This variable must be set if +.Va moused_enable +is set to +.Dq Li YES , +but defaults to +.Dq Li auto +as the +.Xr moused 8 +daemon +is able to detect the appropriate mouse type automatically in many cases. +Set this variable to +one from the following list if the automatic detection fails. +.Pp +If the mouse is attached to the PS/2 mouse port, choose +.Dq Li auto +or +.Dq Li ps/2 , +regardless of the brand and model of the mouse. +Likewise, if the +mouse is attached to the bus mouse port, choose +.Dq Li auto +or +.Dq Li busmouse . +All other protocols are for serial mice and will not work with +the PS/2 and bus mice. +If this is a USB mouse, +.Dq Li auto +is the only protocol type which will work. +.Pp +.Bl -tag -width ".Li x10mouseremote" -compact +.It Li microsoft +Microsoft mouse (serial) +.It Li intellimouse +Microsoft IntelliMouse (serial) +.It Li mousesystems +Mouse systems Corp.\& mouse (serial) +.It Li mmseries +MM Series mouse (serial) +.It Li logitech +Logitech mouse (serial) +.It Li busmouse +A bus mouse +.It Li mouseman +Logitech MouseMan and TrackMan (serial) +.It Li glidepoint +ALPS GlidePoint (serial) +.It Li thinkingmouse +Kensington ThinkingMouse (serial) +.It Li ps/2 +PS/2 mouse +.It Li mmhittab +MM HitTablet (serial) +.It Li x10mouseremote +X10 MouseRemote (serial) +.It Li versapad +Interlink VersaPad (serial) +.El +.Pp +Even if the mouse is not in the above list, it may be compatible +with one in the list. +Refer to the manual page for +.Xr moused 8 +for compatibility information. +.Pp +It should also be noted that while this is enabled, any +other client of the mouse (such as an X server) should access +the mouse through the virtual mouse device, +.Pa /dev/sysmouse , +and configure it as a +.Dq Li sysmouse +type mouse, since all +mouse data is converted to this single canonical format when +using +.Xr moused 8 . +If the client program does not support the +.Dq Li sysmouse +type, +specify the +.Dq Li mousesystems +type. +It is the second preferred type. +.It Va moused_port +.Pq Vt str +If +.Va moused_enable +is set to +.Dq Li YES , +this is the actual port the mouse is on. +It might be +.Pa /dev/cuau0 +for a COM1 serial mouse, or +.Pa /dev/psm0 +for a PS/2 mouse, for example. +.It Va moused_flags +.Pq Vt str +If +.Va moused_flags +is set, its value is used as an additional set of flags to pass to the +.Xr moused 8 +daemon. +.It Va "moused_" Ns Ar XXX Ns Va "_flags" +When +.Va moused_nondefault_enable +is enabled, and a +.Xr moused 8 +daemon is started for a non-default port, the +.Va "moused_" Ns Ar XXX Ns Va "_flags" +set of options has precedence over and replaces the default +.Va moused_flags +(where +.Ar XXX +is the name of the non-default port, i.e.,\& +.Ar ums0 ) . +By setting +.Va "moused_" Ns Ar XXX Ns Va "_flags" +it is possible to set up a different set of default flags for each +.Xr moused 8 +instance. +For example, you can use +.Dq Li "-3" +for the default +.Va moused_flags +to make your laptop's touchpad more comfortable to use, +but an empty set of options for +.Va moused_ums0_flags +when your +.Xr usb 4 +mouse has three or more buttons. +.It Va mousechar_start +.Pq Vt int +If set to +.Dq Li NO , +the default mouse cursor character range +.Li 0xd0 Ns - Ns Li 0xd3 +is used, +otherwise the range start is set +to +.Ar value +character, see +.Xr vidcontrol 1 . +Use if the default range is occupied in the language code table. +.It Va allscreens_flags +.Pq Vt str +If set, +.Xr vidcontrol 1 +is run with these options for each of the virtual terminals +.Pq Pa /dev/ttyv* . +For example, +.Dq Fl m Cm on +will enable the mouse pointer on all virtual terminals +if +.Va moused_enable +is set to +.Dq Li YES . +.It Va allscreens_kbdflags +.Pq Vt str +If set, +.Xr kbdcontrol 1 +is run with these options for each of the virtual terminals +.Pq Pa /dev/ttyv* . +For example, +.Dq Fl h Li 200 +will set the +.Xr syscons 4 +or +.Xr vt 4 +scrollback (history) buffer to 200 lines. +.It Va cron_enable +.Pq Vt bool +If set to +.Dq Li YES , +run the +.Xr cron 8 +daemon at system boot time. +.It Va cron_program +.Pq Vt str +Path to +.Xr cron 8 +(default +.Pa /usr/sbin/cron ) . +.It Va cron_flags +.Pq Vt str +If +.Va cron_enable +is set to +.Dq Li YES , +these are the flags to pass to +.Xr cron 8 . +.It Va cron_dst +.Pq Vt bool +If set to +.Dq Li YES , +enable the special handling of transitions to and from the +Daylight Saving Time in +.Xr cron 8 +(equivalent to using the flag +.Fl s ) . +.It Va lpd_program +.Pq Vt str +Path to +.Xr lpd 8 +(default +.Pa /usr/sbin/lpd ) . +.It Va lpd_enable +.Pq Vt bool +If set to +.Dq Li YES , +run the +.Xr lpd 8 +daemon at system boot time. +.It Va lpd_flags +.Pq Vt str +If +.Va lpd_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr lpd 8 +daemon. +.It Va chkprintcap_enable +.Pq Vt bool +If set to +.Dq Li YES , +run the +.Xr chkprintcap 8 +command before starting the +.Xr lpd 8 +daemon. +.It Va chkprintcap_flags +.Pq Vt str +If +.Va lpd_enable +and +.Va chkprintcap_enable +are set to +.Dq Li YES , +these are the flags to pass to the +.Xr chkprintcap 8 +program. +The default is +.Dq Li -d , +which causes missing directories to be created. +.It Va dumpdev +.Pq Vt str +Indicates the device (usually a swap partition) to which a crash dump +should be written in the event of a system crash. +If the value of this variable is +.Dq Li AUTO , +the first suitable swap device listed in +.Pa /etc/fstab +will be used as dump device. +Otherwise, the value of this variable is passed as the argument to +.Xr dumpon 8 +and +.Xr savecore 8 . +To disable crash dumps, set this variable to +.Dq Li NO . +.It Va dumpon_flags +.Pq Vt str +Flags to pass to +.Xr dumpon 8 +when configuring +.Va dumpdev +as the system dump device. +.It Va dumpdir +.Pq Vt str +When the system reboots after a crash and a crash dump is found on the +device specified by the +.Va dumpdev +variable, +.Xr savecore 8 +will save that crash dump and a copy of the kernel to the directory +specified by the +.Va dumpdir +variable. +The default value is +.Pa /var/crash . +Set to +.Dq Li NO +to not run +.Xr savecore 8 +at boot time when +.Va dumpdir +is set. +.It Va savecore_enable +.Pq Vt bool +If set to +.Dq Li NO , +disable automatic extraction of the crash dump from the +.Va dumpdev . +.It Va savecore_flags +.Pq Vt str +If crash dumps are enabled, these are the flags to pass to the +.Xr savecore 8 +utility. +.It Va quota_enable +.Pq Vt bool +Set to +.Dq Li YES +to turn on user and group disk quotas on system startup via the +.Xr quotaon 8 +command for all file systems marked as having quotas enabled in +.Pa /etc/fstab . +The kernel must be built with +.Cd "options QUOTA" +for disk quotas to function. +.It Va check_quotas +.Pq Vt bool +Set to +.Dq Li YES +to enable user and group disk quota checking via the +.Xr quotacheck 8 +command. +.It Va quotacheck_flags +.Pq Vt str +If +.Va quota_enable +is set to +.Dq Li YES , +and +.Va check_quotas +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr quotacheck 8 +utility. +The default is +.Dq Li "-a" , +which checks quotas for all file systems with quotas enabled in +.Pa /etc/fstab . +.It Va quotaon_flags +.Pq Vt str +If +.Va quota_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr quotaon 8 +utility. +The default is +.Dq Li "-a" , +which enables quotas for all file systems with quotas enabled in +.Pa /etc/fstab . +.It Va quotaoff_flags +.Pq Vt str +If +.Va quota_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr quotaoff 8 +utility when shutting down the quota system. +The default is +.Dq Li "-a" , +which disables quotas for all file systems with quotas enabled in +.Pa /etc/fstab . +.It Va accounting_enable +.Pq Vt bool +Set to +.Dq Li YES +to enable system accounting through the +.Xr accton 8 +facility. +.It Va firstboot_sentinel +.Pq Vt str +This variable specifies the full path to a +.Dq first boot +sentinel file. +If a file exists with this path, +.Pa rc.d +scripts with the +.Dq firstboot +keyword will be run on startup and the sentinel file will be deleted +after the boot process completes. +The sentinel file must be located on a writable file system which is +mounted no later than +.Va early_late_divider +to function properly. +The default is +.Pa /firstboot . +.It Va linux_enable +.Pq Vt bool +Set to +.Dq Li YES +to enable Linux/ELF binary emulation at system initial +boot time. +.It Va sysvipc_enable +.Pq Vt bool +If set to +.Dq Li YES , +load System V IPC primitives at boot time. +.It Va clear_tmp_enable +.Pq Vt bool +Set to +.Dq Li YES +to have +.Pa /tmp +cleaned at startup. +.It Va clear_tmp_X +.Pq Vt bool +Set to +.Dq Li NO +to disable removing of X11 lock files, +and the removal and (secure) recreation +of the various socket directories for X11 +related programs. +.It Va ldconfig_paths +.Pq Vt str +Set to the list of shared library paths to use with +.Xr ldconfig 8 . +NOTE: +.Pa /lib +and +.Pa /usr/lib +will always be added first, so they need not appear in this list. +.It Va ldconfig32_paths +.Pq Vt str +Set to the list of 32-bit compatibility shared library paths to +use with +.Xr ldconfig 8 . +.It Va ldconfig_insecure +.Pq Vt bool +The +.Xr ldconfig 8 +utility normally refuses to use directories +which are writable by anyone except root. +Set this variable to +.Dq Li YES +to disable that security check during system startup. +.It Va ldconfig_local_dirs +.Pq Vt str +Set to the list of local +.Xr ldconfig 8 +directories. +The names of all files in the directories listed will be +passed as arguments to +.Xr ldconfig 8 . +.It Va ldconfig_local32_dirs +.Pq Vt str +Set to the list of local 32-bit compatibility +.Xr ldconfig 8 +directories. +The names of all files in the directories listed will be +passed as arguments to +.Dq Nm ldconfig Fl 32 . +.It Va kern_securelevel_enable +.Pq Vt bool +Set to +.Dq Li YES +to set the kernel security level at system startup. +.It Va kern_securelevel +.Pq Vt int +The kernel security level to set at startup. +The allowed range of +.Ar value +ranges from \-1 (the compile time default) to 3 (the +most secure). +See +.Xr security 7 +for the list of possible security levels and their effect +on system operation. +.It Va sshd_program +.Pq Vt str +Path to the SSH server program +.Pa ( /usr/sbin/sshd +is the default). +.It Va sshd_enable +.Pq Vt bool +Set to +.Dq Li YES +to start +.Xr sshd 8 +at system boot time. +Note, the +.Va sshd_oomprotect +variable is set to +.Dq Li YES +by default in +.Pa /etc/defaults/rc.conf . +.It Va sshd_flags +.Pq Vt str +If +.Va sshd_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr sshd 8 +daemon. +.It Va watchdogd_enable +.Pq Vt bool +If set to +.Dq Li YES , +start the +.Xr watchdogd 8 +daemon at boot time. +This requires that the kernel have been compiled with a +.Xr watchdog 4 +compatible device. +.It Va watchdogd_flags +.Pq Vt str +If +.Va watchdogd_enable +is set to +.Dq Li YES , +these are the flags passed to the +.Xr watchdogd 8 +daemon. +.It Va watchdogd_timeout +.Pq Vt int +If +.Va watchdogd_enable +is set to +.Dq Li YES , +this is a timeout that will be used by the +.Xr watchdogd 8 +daemon. +If this option is set, it overrides +.Fl t +in +.Va watchdogd_flags . +.It Va watchdogd_shutdown_timeout +.Pq Vt int +If +.Va watchdogd_enable +is set to +.Dq Li YES , +this is a timeout that will be set by the +.Xr watchdogd 8 +daemon when it exits during the system shutdown. +This timeout will not be set when returning to the single-user mode +or when the watchdogd service is stopped individually using the +.Xr service 8 +command or the rc.d script. +Note that the timeout will be applied if +.Xr watchdogd 8 +is stopped outside of +.Xr rc 8 +framework. +If this option is set, it overrides +.Fl x +in +.Va watchdogd_flags . +.It Va devfs_rulesets +.Pq Vt str +List of files containing sets of rules for +.Xr devfs 8 . +.It Va devfs_system_ruleset +.Pq Vt str +Rule name(s) to apply to the system +.Pa /dev +itself. +.It Va devfs_set_rulesets +.Pq Vt str +Pairs of already-mounted +.Pa dev +directories and rulesets that should be applied to them. +For example: /mount/dev=ruleset_name +.It Va devfs_load_rulesets +.Pq Vt bool +If set, always load the default rulesets listed in +.Va devfs_rulesets . +.It Va performance_cx_lowest +.Pq Vt str +CPU idle state to use while on AC power. +The string +.Dq Li LOW +indicates that +.Xr acpi 4 +should use the lowest power state available while +.Dq Li HIGH +indicates that the lowest latency state (less power savings) should be used. +.It Va performance_cpu_freq +.Pq Vt str +CPU clock frequency to use while on AC power. +The string +.Dq Li LOW +indicates that +.Xr cpufreq 4 +should use the lowest frequency available while +.Dq Li HIGH +indicates that the highest frequency (less power savings) should be used. +.It Va economy_cx_lowest +.Pq Vt str +CPU idle state to use when off AC power. +The string +.Dq Li LOW +indicates that +.Xr acpi 4 +should use the lowest power state available while +.Dq Li HIGH +indicates that the lowest latency state (less power savings) should be used. +.It Va economy_cpu_freq +.Pq Vt str +CPU clock frequency to use when off AC power. +The string +.Dq Li LOW +indicates that +.Xr cpufreq 4 +should use the lowest frequency available while +.Dq Li HIGH +indicates that the highest frequency (less power savings) should be used. +.It Va jail_enable +.Pq Vt bool +If set to +.Dq Li NO , +any configured jails will not be started. +.It Va jail_conf +.Pq Vt str +The configuration filename used by +.Xr jail 8 +utility. +The default value is +.Pa /etc/jail.conf . +.Pa /etc/jail\&. Ns Ao Va jname Ac Ns Pa .conf +and +.Pa /etc/jail.conf.d/ Ns Ao Va jname Ac Ns Pa .conf +will also be used if +.Ao Va jname Ac +is set in +.Va jail_list . +.It Va jail_parallel_start +.Pq Vt bool +If set to +.Dq Li YES , +all configured jails will be started in the background (in parallel). +.It Va jail_flags +.Pq Vt str +Unset by default. +When set, use as default value for +.Va jail_ Ns Ao Ar jname Ac Ns Va _flags +for every jail in +.Va jail_list . +.It Va jail_list +.Pq Vt str +A space-delimited list of jail names. +When left empty, all of the +.Xr jail 8 +instances defined in the configuration file are started. +The names specified in this list control the jail startup order. +.Xr jail 8 +instances missing from +.Va jail_list +must be started manually. +Note that a jail's +.Va depend +parameter in the configuration file may override this list. +.It Va jail_reverse_stop +.Pq Vt bool +When set to +.Dq Li YES , +all configured jails in +.Va jail_list +are stopped in reverse order. +.It Va jail_ Ns * variables +Note that older releases supported per-jail configuration via +.Nm +variables. +For example, +hostname of a jail named +.Li vjail +was able to be set by +.Li jail_vjail_hostname . +These per-jail configuration variables are now obsolete in favor of +.Xr jail 8 +configuration file. +For backward compatibility, +when per-jail configuration variables are defined, +.Xr jail 8 +configuration files are created as +.Pa /var/run/jail . Ns Ao Ar jname Ac Ns Pa .conf +and used. +.Pp +The following per-jail parameters are handled by +.Pa rc.d/jail +script out of their corresponding +.Nm +variables. +In addition to them, parameters in +.Va jail_ Ns Ao Ar jname Ac Ns Va _parameters +will be added to the configuration file. +They must be a semi-colon +.Pq Ql \&; +delimited list of +.Dq key=value . +For more details, +see +.Xr jail 8 +manual page. +.Bl -tag -width "host.hostname" -offset indent +.It Li path +set from +.Va jail_ Ns Ao Ar jname Ac Ns Va _rootdir +.It Li host.hostname +set from +.Va jail_ Ns Ao Ar jname Ac Ns Va _hostname +.It Li exec.consolelog +set from +.Va jail_ Ns Ao Ar jname Ac Ns Va _consolelog . +The default value is +.Pa /var/log/jail_ Ns Ao Ar jname Ac Ns Pa _console.log . +.It Li interface +set from +.Va jail_ Ns Ao Ar jname Ac Ns Va _interface . +.It Li vnet.interface +set from +.Va jail_ Ns Ao Ar jname Ac Ns Va _vnet_interface . +This implies +.Li vnet +parameter will be enabled and cannot be specified with +.Va jail_ Ns Ao Ar jname Ac Ns Va _interface , +.Va jail_ Ns Ao Ar jname Ac Ns Va _ip +and/or +.Va jail_ Ns Ao Ar jname Ac Ns Va _ip_multi Ns Aq Ar n +at the same time. +.It Li fstab +set from +.Va jail_ Ns Ao Ar jname Ac Ns Va _fstab +.It Li mount +set from +.Va jail_ Ns Ao Ar jname Ac Ns Va _procfs_enable . +.It Li exec.fib +set from +.Va jail_ Ns Ao Ar jname Ac Ns Va _fib +.It Li exec.start +set from +.Va jail_ Ns Ao Ar jname Ac Ns Va _exec_start . +The parameter name was +.Li command +in some older releases. +.It Li exec.prestart +set from +.Va jail_ Ns Ao Ar jname Ac Ns Va _exec_prestart +.It Li exec.poststart +set from +.Va jail_ Ns Ao Ar jname Ac Ns Va _exec_poststart +.It Li exec.stop +set from +.Va jail_ Ns Ao Ar jname Ac Ns Va _exec_stop +.It Li exec.prestop +set from +.Va jail_ Ns Ao Ar jname Ac Ns Va _exec_prestop +.It Li exec.poststop +set from +.Va jail_ Ns Ao Ar jname Ac Ns Va _exec_poststop +.It Li ip4.addr +set if +.Va jail_ Ns Ao Ar jname Ac Ns Va _ip +or +.Va jail_ Ns Ao Ar jname Ac Ns Va _ip_multi Ns Aq Ar n +contain IPv4 addresses +.It Li ip6.addr +set if +.Va jail_ Ns Ao Ar jname Ac Ns Va _ip +or +.Va jail_ Ns Ao Ar jname Ac Ns Va _ip_multi Ns Aq Ar n +contain IPv6 addresses +.It Li allow.mount +set from +.Va jail_ Ns Ao Ar jname Ac Ns Va _mount_enable +.It Li mount.devfs +set from +.Va jail_ Ns Ao Ar jname Ac Ns Va _devfs_enable +.It Li devfs_ruleset +set from +.Va jail_ Ns Ao Ar jname Ac Ns Va _devfs_ruleset . +This must be an integer, +not a string. +.It Li mount.fdescfs +set from +.Va jail_ Ns Ao Ar jname Ac Ns Va _fdescfs_enable +.It Li allow.set_hostname +set from +.Va jail_ Ns Ao Ar jname Ac Ns Va _set_hostname_allow +.It Li allow.rawsocket +set from +.Va jail_ Ns Ao Ar jname Ac Ns Va _socket_unixiproute_only +.It Li allow.sysvipc +set from +.Va jail_ Ns Ao Ar jname Ac Ns Va _sysvipc_allow +.El +.\" ----------------------------------------------------- +.It Va harvest_mask +.Pq Vt int +Set to a bit-mask +representing the entropy sources +you wish to harvest. +Refer to +.Xr random 4 +for more information. +.It Va entropy_dir +.Pq Vt str +Set to +.Dq Li NO +to disable caching entropy via +.Xr cron 8 . +Otherwise set to the directory +in which the entropy files are stored. +To be useful, +there must be +a system cron job +that regularly writes and rotates +files here. +All files found +will be used at boot time. +The default is +.Pa /var/db/entropy . +.It Va entropy_file +.Pq Vt str +Set to +.Dq Li NO +to disable caching entropy through reboots. +Otherwise set to the name +of a file used to store cached entropy. +This file should be located +on a file system that is readable +before all the volumes specified in +.Xr fstab 5 +are mounted. +By default, +.Pa /entropy +is used, +but if +.Pa /var/db/entropy-file +is found it will also be used. +This will be of some use to +.Xr bsdinstall 8 . +.It Va entropy_boot_file +.Pq Vt str +Set to +.Dq Li NO +to disable +very early caching entropy +through reboots. +Otherwise set to the filename +used to read +very early reboot cached entropy. +This file should be located where +.Xr loader 8 +can read it. +See also +.Xr loader.conf 5 . +The default location is +.Pa /boot/entropy . +.It Va entropy_save_sz +.Pq Vt int +Size of the entropy cache files saved by +.Nm save-entropy +periodically. +.It Va entropy_save_num +.Pq Vt int +Number of entropy cache files to save by +.Nm save-entropy +periodically. +.It Va ipsec_enable +.Pq Vt bool +Set to +.Dq Li YES +to run +.Xr setkey 8 +on +.Va ipsec_file +at boot time. +.It Va ipsec_file +.Pq Vt str +Configuration file for +.Xr setkey 8 . +.It Va dmesg_enable +.Pq Vt bool +Set to +.Dq Li YES +to save +.Xr dmesg 8 +to +.Pa /var/run/dmesg.boot +on boot. +.It Va rcshutdown_timeout +.Pq Vt int +If set, start a watchdog timer in the background which will terminate +.Pa rc.shutdown +if +.Xr shutdown 8 +has not completed within the specified time (in seconds). +Notice that in addition to this soft timeout, +.Xr init 8 +also applies a hard timeout for the execution of +.Pa rc.shutdown . +This is configured via +.Xr sysctl 8 +variable +.Va kern.init_shutdown_timeout +and defaults to 120 seconds. +Setting the value of +.Va rcshutdown_timeout +to more than 120 seconds will have no effect until the +.Xr sysctl 8 +variable +.Va kern.init_shutdown_timeout +is also increased. +.It Va virecover_enable +.Pq Vt bool +Set to +.Dq Li NO +to prevent the system from trying to +recover prematurely terminated +.Xr vi 1 +sessions. +.It Va ugidfw_enable +.Pq Vt bool +Set to +.Dq Li YES +to load the +.Xr mac_bsdextended 4 +module upon system initialization and load a default +ruleset file. +.It Va bsdextended_script +.Pq Vt str +The default +.Xr mac_bsdextended 4 +ruleset file to load. +The default value of this variable is +.Pa /etc/rc.bsdextended . +.It Va newsyslog_enable +.Pq Vt bool +If set to +.Dq Li YES , +run +.Xr newsyslog 8 +command at startup. +.It Va newsyslog_flags +.Pq Vt str +If +.Va newsyslog_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr newsyslog 8 +program. +The default is +.Dq Li -CN , +which causes log files flagged with a +.Cm C +to be created. +.It Va mdconfig_md Ns Aq Ar X +.Pq Vt str +Arguments to +.Xr mdconfig 8 +for +.Xr md 4 +device +.Ar X . +At minimum a +.Fl t Ar type +must be specified and either a +.Fl s Ar size +for malloc or swap backed +.Xr md 4 +devices or a +.Fl f Ar file +for vnode backed +.Xr md 4 +devices. +Note that +.Va mdconfig_md Ns Aq Ar X +variables are evaluated until one variable is unset or null. +.It Va mdconfig_md Ns Ao Ar X Ac Ns Va _newfs +.Pq Vt str +Optional arguments passed to +.Xr newfs 8 +to initialize +.Xr md 4 +device +.Ar X . +.It Va mdconfig_md Ns Ao Ar X Ac Ns Va _owner +.Pq Vt str +An ownership specification passed to +.Xr chown 8 +after the specified +.Xr md 4 +device +.Ar X +has been mounted. +Both the +.Xr md 4 +device and the mount point will be changed. +.It Va mdconfig_md Ns Ao Ar X Ac Ns Va _perms +.Pq Vt str +A mode string passed to +.Xr chmod 1 +after the specified +.Xr md 4 +device +.Ar X +has been mounted. +Both the +.Xr md 4 +device and the mount point will be changed. +.It Va mdconfig_md Ns Ao Ar X Ac Ns Va _files +.Pq Vt str +Files to be copied to the mount point of the +.Xr md 4 +device +.Ar X +after it has been mounted. +.It Va mdconfig_md Ns Ao Ar X Ac Ns Va _cmd +.Pq Vt str +Command to execute after the specified +.Xr md 4 +device +.Ar X +has been mounted. +Note that the command is passed to +.Ic eval +and that both +.Va _dev +and +.Va _mp +variables can be used to reference respectively the +.Xr md 4 +device and the mount point. +Assuming that the +.Xr md 4 +device is +.Li md0 , +one could set the following: +.Bd -literal +mdconfig_md0_cmd="tar xfzC /var/file.tgz \e${_mp}" +.Ed +.It Va autobridge_interfaces +.Pq Vt str +Set to the list of bridge interfaces that will have newly arriving interfaces +checked against to be automatically added. +If not set to +.Dq Li NO +then for each whitespace separated +.Ar element +in the value, a +.Va autobridge_ Ns Aq Ar element +variable is assumed to exist which has a whitespace separated list of interface +names to match, these names can use wildcards. +For example: +.Bd -literal +autobridge_interfaces="bridge0" +autobridge_bridge0="tap* dc0 vlan[345]" +.Ed +.It Va mixer_enable +.Pq Vt bool +If set to +.Dq Li YES , +enable support for sound mixer. +.It Va hcsecd_enable +.Pq Vt bool +If set to +.Dq Li YES , +enable Bluetooth security daemon. +.It Va hcsecd_config +.Pq Vt str +Configuration file for +.Xr hcsecd 8 . +Default +.Pa /etc/bluetooth/hcsecd.conf . +.It Va sdpd_enable +.Pq Vt bool +If set to +.Dq Li YES , +enable Bluetooth Service Discovery Protocol daemon. +.It Va sdpd_control +.Pq Vt str +Path to +.Xr sdpd 8 +control socket. +Default +.Pa /var/run/sdp . +.It Va sdpd_groupname +.Pq Vt str +Sets +.Xr sdpd 8 +group to run as after it initializes. +Default +.Dq Li nobody . +.It Va sdpd_username +.Pq Vt str +Sets +.Xr sdpd 8 +user to run as after it initializes. +Default +.Dq Li nobody . +.It Va bthidd_enable +.Pq Vt bool +If set to +.Dq Li YES , +enable Bluetooth Human Interface Device daemon. +.It Va bthidd_config +.Pq Vt str +Configuration file for +.Xr bthidd 8 . +Default +.Pa /etc/bluetooth/bthidd.conf . +.It Va bthidd_hids +.Pq Vt str +Path to a file, where +.Xr bthidd 8 +will store information about known HID devices. +Default +.Pa /var/db/bthidd.hids . +.It Va rfcomm_pppd_server_enable +.Pq Vt bool +If set to +.Dq Li YES , +enable Bluetooth RFCOMM PPP wrapper daemon. +.It Va rfcomm_pppd_server_profile +.Pq Vt str +The name of the profile to use from +.Pa /etc/ppp/ppp.conf . +Multiple profiles can be specified here. +Also used to specify per-profile overrides. +When the profile name contains any of the characters +.Dq Li .-/+ +they are translated to +.Dq Li _ +for the proposes of the override variable names. +.It Va rfcomm_pppd_server_ Ns Ao Ar profile Ac Ns _bdaddr +.Pq Vt str +Overrides local address to listen on. +By default +.Xr rfcomm_pppd 8 +will listen on +.Dq Li ANY +address. +The address can be specified as BD_ADDR or name. +.It Va rfcomm_pppd_server_ Ns Ao Ar profile Ac Ns _channel +.Pq Vt str +Overrides local RFCOMM channel to listen on. +By default +.Xr rfcomm_pppd 8 +will listen on RFCOMM channel 1. +Must set properly if multiple profiles used in the same time. +.It Va rfcomm_pppd_server_ Ns Ao Ar profile Ac Ns _register_sp +.Pq Vt bool +Tells +.Xr rfcomm_pppd 8 +if it should register Serial Port service on the specified RFCOMM channel. +Default +.Dq Li NO . +.It Va rfcomm_pppd_server_ Ns Ao Ar profile Ac Ns _register_dun +.Pq Vt bool +Tells +.Xr rfcomm_pppd 8 +if it should register Dial-Up Networking service on the specified +RFCOMM channel. +Default +.Dq Li NO . +.It Va ubthidhci_enable +.Pq Vt bool +If set to +.Dq Li YES , +change the USB Bluetooth controller from HID mode to HCI mode. +You also need to specify the location of USB Bluetooth controller with the +.Va ubthidhci_busnum +and +.Va ubthidhci_addr +variables. +.It Va ubthidhci_busnum +Bus number where the USB Bluetooth controller is located. +Check the output of +.Xr usbconfig 8 +on your system to find this information. +.It Va ubthidhci_addr +Bus address of the USB Bluetooth controller. +Check the output of +.Xr usbconfig 8 +on your system to find this information. +.It Va utx_enable +.Pq Vt bool +Set to +.Dq Li YES +to enable user accounting through the +.Xr utx 8 +facility. +.It Va netwait_enable +.Pq Vt bool +If set to +.Dq Li YES , +delays the start of network-reliant services until +.Va netwait_if +is up, duplicate address discovery (DAD) has completed, and ICMP +packets to a destination defined in +.Va netwait_ip +are flowing. +Link state is examined first, followed by DAD, then +.Dq Li pinging +an IP address to verify network usability. +If no destination can be reached or timeouts are exceeded, +network services are started anyway with no guarantee that +the network is usable. +.It Va netwait_ip +.Pq Vt str +Empty by default. +This variable contains a space-delimited list of IP addresses to +.Xr ping 8 . +DNS hostnames should not be used as resolution is not guaranteed +to be functional at this point. +If multiple IP addresses are specified, +each will be tried until one is successful or the list is exhausted. +.It Va netwait_timeout +.Pq Vt int +Indicates the total number of seconds to perform a +.Dq Li ping +against each IP address in +.Va netwait_ip , +at a rate of one ping per second. +If any of the pings are successful, +full network connectivity is considered reliable. +The default is 60. +.It Va netwait_if +.Pq Vt str +Empty by default. +Defines the name of the network interface on which watch for link. +.Xr ifconfig 8 +is used to monitor the interface, looking for +.Dq Li status: no carrier . +Once gone, the link is considered up. +This can be a +.Xr vlan 4 +interface if desired. +.It Va netwait_if_timeout +.Pq Vt int +Defines the total number of seconds to wait for link to become usable, +polled at a 1-second interval. +The default is 30. +.It Va netwait_dad +.Pq Vt str +Set to +.Dq Li NO +by default. +Set to +.Dq Li YES +to enable waiting for DAD to complete. +.It Va netwait_dad_timeout +.Pq Vt int +Unset by default. +Indicates the maximum number of seconds to wait for DAD to complete. +If zero or unset, the timeout will be one more than the value of the +.Va net.inet6.ip6.dad_count +sysctl variable. +.It Va rctl_enable +.Pq Vt bool +If set to +.Dq Li YES , +load +.Xr rctl 8 +rules from the defined ruleset. +The kernel must be built with +.Cd "options RACCT" +and +.Cd "options RCTL" . +.It Va rctl_rules +.Pq Vt str +Set to +.Pa /etc/rctl.conf +by default. +This variables contains the +.Xr rctl.conf 5 +ruleset to load for +.Xr rctl 8 . +.It Va iovctl_files +.Pq Vt str +A space-separated list of configuration files used by +.Xr iovctl 8 . +The default value is an empty string. +.It Va autofs_enable +.Pq Vt bool +If set to +.Dq Li YES , +start the +.Xr automount 8 +utility and the +.Xr automountd 8 +and +.Xr autounmountd 8 +daemons at boot time. +.It Va automount_flags +.Pq Vt str +If +.Va autofs_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr automount 8 +program. +By default no flags are passed. +.It Va automountd_flags +.Pq Vt str +If +.Va autofs_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr automountd 8 +daemon. +By default no flags are passed. +.It Va autounmountd_flags +.Pq Vt str +If +.Va autofs_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr autounmountd 8 +daemon. +By default no flags are passed. +.It Va ctld_enable +.Pq Vt bool +If set to +.Dq Li YES , +start the +.Xr ctld 8 +daemon at boot time. +.It Va iscsid_enable +.Pq Vt bool +If set to +.Dq Li YES , +start the +.Xr iscsid 8 +daemon at boot time. +.It Va iscsictl_enable +.Pq Vt bool +If set to +.Dq Li YES , +start the +.Xr iscsictl 8 +utility at boot time. +.It Va iscsictl_flags +.Pq Vt str +If +.Va iscsictl_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr iscsictl 8 +program. +The default is +.Dq Li -Aa , +which configures sessions based on the +.Pa /etc/iscsi.conf +configuration file. +.It Va cfumass_enable +.Pq Vt bool +If set to +.Dq Li YES , +create and export an USB LUN using +.Xr cfumass 4 +at boot time. +.It Va cfumass_dir +.Pq Vt str +The directory where the files exported by USB LUN are located. +The default directory is +.Pa /var/cfumass . +.It Va service_delete_empty +.Pq Vt bool +If set to +.Dq Li YES , +.Ql Li service delete +removes empty +.Dq Li rc.conf.d +files. +.It Va zfs_bootonce_activate +.Pq Vt bool +If set to +.Dq Li YES , +and a boot environment marked bootonce is successfully booted, +it will be made permanently active. +.It Va zfskeys_enable +.Pq Vt bool +If set to +.Dq Li YES , +enable auto-loading of encryption keys for encrypted ZFS datasets. +For every dataset the script will first load the appropriate encryption key +and then attempt to unlock the dataset. +.Pp +The script operates only on datasets which are encrypted with +ZFS native encryption +and have a ZFS +.Dq Li keylocation +dataset property beginning with +.Dq Li file:// . +.It Va zfskeys_datasets +.Pq Vt str +A whitespace-separated list of ZFS datasets to unlock. +The list is empty by default, +which means that the script will attempt to unlock all datasets. +.It Va zfskeys_timeout +.Pq Vt int +Define the total number of seconds to wait for the zfskeys script +to unlock an encrypted dataset. +The default is 10. +.It Va sendmail_enable +.Pq Vt str +If set to +.Dq Li YES , +run the +.Xr sendmail 8 +daemon at system boot time. +If set to +.Dq Li NO , +do not run a +.Xr sendmail 8 +daemon to listen for incoming network mail. +This does not preclude a +.Xr sendmail 8 +daemon listening on the SMTP port of the loopback interface. +The +.Dq Li NONE +option sets each +.Va sendmail_enable , +.Va sendmail_submit_enable , +.Va sendmail_outbound_enable , +.Va sendmail_msp_queue_enable +to +.Dq Li NO . +.It Va sendmail_cert_create +.Pq Vt str +If +.Va sendmail_enable +is set to +.Dq Li YES , +create a signed certificate +.Pa /etc/mail/certs/host.cert +representing +.Pa /etc/mail/certs/host.key +by the CA certificate in +.Pa /etc/mail/certs/cacert.pem . +This will enable connecting hosts to negotiate STARTTLS allowing incoming +email to be encrypted in transit. +.Xr sendmail 8 +needs to be configured to use these generated files. +The default configuration in +.Pa /etc/mail/freebsd.mc +has the required options in it. +.It Va sendmail_cert_cn +.Pq Vt str +If +.Va sendmail_enable +is set to +.Dq Li YES +and +.Va sendmail_cert_create +is set to +.Dq Li YES , +this is the Common Name (CN) of the certificate that will be created. +If +.Va sendmail_cert_cn +is not set, the system's hostname will be used. +If there is no hostname set, +.Dq Li amnesiac +will be used. +.It Va sendmail_flags +.Pq Vt str +If +.Va sendmail_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr sendmail 8 +daemon. +.It Va sendmail_submit_enable +.Pq Vt bool +If set to +.Dq Li YES +and +.Va sendmail_enable +is set to +.Dq Li NO , +run +.Xr sendmail 8 +using +.Va sendmail_submit_flags +instead of +.Va sendmail_flags . +This is intended to allow local mail submission via +a localhost-only listening SMTP service required for running +.Xr sendmail 8 +as a non-set-user-ID binary. +Note that this does not work inside +.Xr jail 2 +systems, as jails do not allow binding to just the localhost interface. +.It Va sendmail_submit_flags +.Pq Vt str +If +.Va sendmail_enable +is set to +.Dq Li NO +and +.Va sendmail_submit_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr sendmail 8 +daemon. +.It Va sendmail_outbound_enable +.Pq Vt bool +If set to +.Dq Li YES +and both +.Va sendmail_enable +and +.Va sendmail_submit_enable +are set to +.Dq Li NO , +run +.Xr sendmail 8 +using +.Va sendmail_outbound_flags +instead of +.Va sendmail_flags . +This is intended to allow local mail queue management +for systems that do not offer a listening SMTP service. +.It Va sendmail_outbound_flags +.Pq Vt str +If both +.Va sendmail_enable +and +.Va sendmail_submit_enable +are set to +.Dq Li NO +and +.Va sendmail_outbound_enable +is set to +.Dq Li YES , +these are the flags to pass to the +.Xr sendmail 8 +daemon. +.It Va sendmail_msp_queue_enable +.Pq Vt bool +If set to +.Dq Li YES , +start a client (MSP) queue runner +.Xr sendmail 8 +daemon at system boot time. +As of sendmail 8.12, a separate queue is used for command line +submissions. +The client queue runner ensures that nothing is +left behind in the submission queue. +.It Va sendmail_msp_queue_flags +.Pq Vt str +If +.Va sendmail_msp_queue_enable +is set to +daemon. +.Dq Li YES , +these are the flags to pass to the +.Xr sendmail 8 +.It Va precious_machine +If set to +.Dq Li YES , +some destructive actions require removal of the action-specific safe-belts +before being allowed. +For instance, the file +.Pa /var/run/noshutdown +is created to prevent +.Xr shutdown 8 +targeted at the wrong machine. +.It Va virtual_oss_enable +.Pq Vt bool +If set to +.Dq Li YES , +run one +.Xr virtual_oss 8 +instance for each configuration defined in +.Pa virtual_oss_configs . +.It Va virtual_oss_configs +.Pq Vt str +Space-separated list of +.Xr virtual_oss 8 +configurations. +For example: +.Bd -literal +virtual_oss_configs="foo bar" +.Ed +.Pp +Configurations need to be defined in +.Pa virtual_oss_ Ns Aq Ar config_name . +By default, there is a +.Pa dsp +configuration which replaces the +.Pa /dev/dsp +device created by +.Xr sound 4 +with a +.Xr virtual_oss 8 +one. +It can be redefined by setting the +.Pa virtual_oss_dsp +variable. +.It Va virtual_oss_ Ns Aq Ar config_name +.Pq Vt str +.Xr virtual_oss 8 +argument list for configuration +.Aq Ar config_name . +.It Va virtual_oss_default_control_device +.Pq Vt str +The +.Xr virtual_oss 8 +control device's name corresponding to the default configuration, +.Pa virtual_oss_dsp . +This is set by default to +.Pa vdsp.ctl . +When +.Pa virtual_oss_dsp +is set, it is strongly encouraged to set this variable as well, and use it as +the +.Fl t +option's argument in +.Pa virtual_oss_dsp , +because it is used by other programs and scripts, such as +.Pa /etc/devd/snd.conf . +.El +.Sh SERVICE JAILS +The service jails part of the rc system automatically puts a service +into a jail. +This jail inherits the filesystem and various other parts of the +parent (if you allow child-jails in your jails, service jails +can be used in jails) depending on the content of the +.Ao Ar name Ac Ns Va _svcj_options +variable. +Typically this variable is set inside rc scripts, but it can be +overridden in the rc config. +Valid options for +.Ao Ar name Ac Ns Va _svcj_options +are: +.Bl -tag -width indent-two +.It mlock +Allows to lock memory pages into the physical memory. +.It netv4 +Allows IPv4 network access and the ability to bind to reserved ports. +If +.Ao Ar name Ac Ns Va _svcj_ipaddrs +is set, only the IPv4 addresses listed there will be visible to the jail, +otherwise all assigned IPv4 addresses will be visible. +This can not be combined with +.Pa netv6 . +.It netv6 +Allows IPv6 network access and the ability to bind to reserved ports. +If +.Ao Ar name Ac Ns Va _svcj_ipaddrs +is set, only the IPv6 addresses listed there will be visible to the jail, +otherwise all assigned IPv6 addresses will be visible. +This can not be combined with +.Pa netv4 . +.It net_basic +Equivalent to enabling both +.Pa netv6 +and +.Pa netv4 . +.It net_raw +Allow to open raw sockets. +This option can be combined with +.Pa netv4 , +.Pa netv6 , +.Pa net_basic . +.It net_all +Allows IPv6 and IPv4 network access as for +.Pa netv4 +and +.Pa netv6 , +allows to open raw sockets, and allows to open sockets of protocol stacks that +have not had jail functionality added to them. +.It nfsd +Allows to run nfsd and affiliated daemons. +.It routing +Allows to modify the system routing table. +.It settime +Allows to set and slew the system time. +.It sysvipc +Inherits the SysV semaphores, SysV shared memory and +SysV messages from the host or the parent jail. +.It sysvipcnew +Creates a new namespace for SysV semaphores, SysV shared memory +and SysV messages for this particular service jail. +.It vmm +Allows access to +.Xr vmm 4 . +This option is only available when +.Xr vmm 4 +is enabled in the kernel. +.El + +All non-network options can be combined with all other options. +From the SysV options only one option can be specified. + +If the +.Ao Ar name Ac Ns Va _svcj +variable is set to +.Dq Li YES , +this particular service is started in a +service jail named +.Va svcj- Ns Ar name . + +The +.Va svcj_all_enable +variable allows to enable service jails for all services of the +system at once. +Services which have +.Ao Ar name Ac Ns Va _svcj +set to +.Dq Li NO +are excluded. +Some services may set +.Ao Ar name Ac Ns Va _svcj +to +.Dq Li NO +in the script to either prevent service jails for this +service at all, or may set it to +.Dq Li NO +if it is not set in the +rc config, to exclude it from +.Va svcj_all_enable +but allow to explicitly enable it. +The sshd service for example would not see other jails, if +it would run as a service jail. +This may or may not be what is needed, and as such it is +excluded from +.Va svcj_all_enable +but can be enabled via setting +.Va sshd_svcj +to +.Dq Li YES . +.Sh FILES +.Bl -tag -width "/etc/defaults/rc.conf" -compact +.It Pa /etc/defaults/rc.conf +.It Pa /etc/defaults/vendor.conf +.It Pa /etc/rc.conf +.It Pa /etc/rc.conf.local +.It Pa /etc/rc.conf.d/ +.El +.Sh SEE ALSO +.Xr chmod 1 , +.Xr cpuset 1 , +.Xr gdb 1 Pq Pa ports/devel/gdb , +.Xr kbdcontrol 1 , +.Xr limits 1 , +.Xr protect 1 , +.Xr sh 1 , +.Xr umask 1 , +.Xr uuidgen 1 , +.Xr vi 1 , +.Xr vidcontrol 1 , +.Xr bridge 4 , +.Xr dummynet 4 , +.Xr ip 4 , +.Xr ipf 4 , +.Xr ipfw 4 , +.Xr ipnat 4 , +.Xr kld 4 , +.Xr pf 4 , +.Xr pflog 4 , +.Xr pfsync 4 , +.Xr tcp 4 , +.Xr udp 4 , +.Xr exports 5 , +.Xr fstab 5 , +.Xr ipf 5 , +.Xr ipnat 5 , +.Xr jail.conf 5 , +.Xr loader.conf 5 , +.Xr login.conf 5 , +.Xr motd 5 , +.Xr newsyslog.conf 5 , +.Xr pf.conf 5 , +.Xr firewall 7 , +.Xr growfs 7 , +.Xr security 7 , +.Xr tuning 7 , +.Xr accton 8 , +.Xr apm 8 , +.Xr bsdinstall 8 , +.Xr bthidd 8 , +.Xr chkprintcap 8 , +.Xr chown 8 , +.Xr cron 8 , +.Xr devfs 8 , +.Xr dhclient 8 , +.Xr geli 8 , +.Xr hcsecd 8 , +.Xr ifconfig 8 , +.Xr inetd 8 , +.Xr iovctl 8 , +.Xr ipf 8 , +.Xr ipfw 8 , +.Xr ipnat 8 , +.Xr jail 8 , +.Xr kldxref 8 , +.Xr loader 8 , +.Xr lpd 8 , +.Xr makewhatis 8 , +.Xr mdconfig 8 , +.Xr mdmfs 8 , +.Xr mixer 8 , +.Xr mountd 8 , +.Xr moused 8 , +.Xr newfs 8 , +.Xr newsyslog 8 , +.Xr nfsd 8 , +.Xr ntpd 8 , +.Xr ntpdate 8 , +.Xr pfctl 8 , +.Xr pflogd 8 , +.Xr ping 8 , +.Xr powerd 8 , +.Xr quotacheck 8 , +.Xr quotaon 8 , +.Xr rc 8 , +.Xr rc.subr 8 , +.Xr rcorder 8 , +.Xr rfcomm_pppd 8 , +.Xr route 8 , +.Xr route6d 8 , +.Xr routed 8 , +.Xr rpc.lockd 8 , +.Xr rpc.statd 8 , +.Xr rpc.tlsclntd 8 , +.Xr rpc.tlsservd 8 , +.Xr rpcbind 8 , +.Xr rwhod 8 , +.Xr savecore 8 , +.Xr sdpd 8 , +.Xr sendmail 8 , +.Xr service 8 , +.Xr sshd 8 , +.Xr swapon 8 , +.Xr sysctl 8 , +.Xr syslogd 8 , +.Xr sysrc 8 , +.Xr unbound 8 , +.Xr usbconfig 8 , +.Xr utx 8 , +.Xr virtual_oss 8 , +.Xr wlandebug 8 , +.Xr yp 8 , +.Xr ypbind 8 , +.Xr ypserv 8 , +.Xr ypset 8 +.Sh HISTORY +The +.Nm +file appeared in +.Fx 2.2.2 . +.Sh AUTHORS +.An Jordan K. Hubbard . diff --git a/static/freebsd/man5/rctl.conf.5 b/static/freebsd/man5/rctl.conf.5 new file mode 100644 index 00000000..bf64e54f --- /dev/null +++ b/static/freebsd/man5/rctl.conf.5 @@ -0,0 +1,72 @@ +.\" Copyright (c) 2011 Edward Tomasz Napierala +.\" Copyright (c) 1999 Chris Costello +.\" 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 October 6, 2023 +.Dt RCTL.CONF 5 +.Os +.Sh NAME +.Nm rctl.conf +.Nd resource limits database defaults +.Sh DESCRIPTION +The +.Pa /etc/rctl.conf +file is read in when the system goes into multi-user mode to set default +contents of the RCTL database. +The +.Pa /etc/rctl.conf +is in the format of the +.Xr rctl 8 +command, i.e.\& +.Bd -literal -offset indent +subject:subject-id:resource:action=amount/per +.Ed +.Pp +Comments are denoted by a +.Dq # +at the beginning of a line. +Comments can also exist at the end of a line, +as seen in the +.Sx EXAMPLES +section, below. +.Sh FILES +.Bl -tag -width /etc/rctl.conf -compact +.It Pa /etc/rctl.conf +Initial settings for +.Xr rctl 8 . +.El +.Sh EXAMPLES +To limit the number of processes for users in login class "testing", +use a rule like +.Bd -literal -offset indent +# Resource limits for the "testing" class. +loginclass:testing:maxproc:deny=100/user # At most 100 processes per user +.Ed +.Sh SEE ALSO +.Xr rctl 8 +.Sh HISTORY +The +.Nm +file appeared in +.Fx 9.0 . diff --git a/static/freebsd/man5/regdomain.5 b/static/freebsd/man5/regdomain.5 new file mode 100644 index 00000000..a9408813 --- /dev/null +++ b/static/freebsd/man5/regdomain.5 @@ -0,0 +1,46 @@ +.\" Copyright (c) 2008 Sam Leffler, Errno Consulting +.\" 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 April 13, 2008 +.Dt REGDOMAIN 5 +.Os +.Sh NAME +.Nm regdomain.xml +.Nd "802.11 wireless regulatory definitions" +.Sh DESCRIPTION +The +.Nm +file describes regulations for the operation of IEEE 802.11 wireless radios. +.Pp +This information is used by the +.Xr ifconfig 8 +program to construct regulatory state for download to the system. +This file should be changed only to reflect changes in regulations. +.Sh FILES +.Bl -tag -width /etc/regdomain.xml -compact +.It Pa /etc/regdomain.xml +XML database of 802.11 regulatory constraints +.El +.Sh SEE ALSO +.Xr wlan 4 , +.Xr ifconfig 8 diff --git a/static/freebsd/man5/remote.5 b/static/freebsd/man5/remote.5 new file mode 100644 index 00000000..63ff8318 --- /dev/null +++ b/static/freebsd/man5/remote.5 @@ -0,0 +1,207 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 October 20, 2003 +.Dt REMOTE 5 +.Os +.Sh NAME +.Nm remote +.Nd remote host description file +.Sh DESCRIPTION +The systems known by +.Xr tip 1 +and their attributes are stored in an +.Tn ASCII +file which +is structured somewhat like the +.Xr termcap 5 +file. +Each line in the file provides a description for a single +.Em system . +Fields are separated by a colon (``:''). +Lines ending in a \e character with an immediately following newline are +continued on the next line. +.Pp +The first entry is the name(s) of the host system. +If there is more +than one name for a system, the names are separated by vertical bars. +After the name of the system comes the fields of the description. +A field name followed by an `=' sign indicates a string value. +A field name followed by a `#' sign indicates a numeric value. +.Pp +Entries named ``tip*'' and ``cu*'' are used as default entries by +.Xr tip 1 , +and the +.Xr cu 1 +interface to +.Nm tip , +as follows. +When +.Nm tip +is invoked with only a phone number, it looks for an entry +of the form ``tip300'', where 300 is the data rate with +which the connection is to be made. +When the +.Nm cu +interface is used, entries of the form ``cu300'' are used. +.Sh CAPABILITIES +Capabilities are either strings (str), numbers (num), or boolean +flags (bool). +A string capability is specified by +.Em capability Ns Ar = Ns Em value ; +for example, ``dv=/dev/harris''. +A numeric capability is specified by +.Em capability Ns Ar # Ns Em value ; +for example, ``xa#99''. +A boolean capability is specified by simply listing the capability. +.Bl -tag -width indent +.It Cm \&at +(str) +Auto call unit type. +.It Cm \&br +(num) +The data rate (bits per second) used for communications on the +serial port. +When a modem is used, the data rate used to communicate +with the remote modem may be different than this rate. +This is a decimal number. +The default rate is 115200 bits per second. +.It Cm \&cm +(str) +An initial connection message to be sent to the remote host. +For example, if a host is reached through a port selector, this +might be set to the appropriate sequence required to switch to the host. +.It Cm \&cu +(str) +Call unit if making a phone call. +Default is the same as the `dv' field. +.It Cm \&di +(str) +Disconnect message sent to the host when a disconnect is requested by +the user. +.It Cm \&du +(bool) +This host is on a dial-up line. +.It Cm \&dv +(str) +.Ux +device(s) to open to establish a connection. +If this file refers to a terminal line, +.Xr tip 1 +attempts to perform an exclusive open on the device to ensure only +one user at a time has access to the port. +.It Cm \&el +(str) +Characters marking an end-of-line. +The default is +.Dv NULL . +`~' escapes are only +recognized by +.Nm tip +after one of the characters in `el', or after a carriage-return. +.It Cm \&fs +(str) +Frame size for transfers. +The default frame size is equal to +.Dv BUFSIZ . +.It Cm \&hd +(bool) +The host uses half-duplex communication, local echo should be performed. +.It Cm \&ie +(str) +Input end-of-file marks. +The default is +.Dv NULL . +.It Cm \&oe +(str) +Output end-of-file string. +The default is +.Dv NULL . +When +.Nm tip +is transferring a file, this +string is sent at end-of-file. +.It Cm \&pa +(str) +The type of parity to use when sending data +to the host. +This may be one of ``even'', +``odd'', ``none'', ``zero'' (always set bit 8 to zero), +``one'' (always set bit 8 to 1). +The default is even parity. +.It Cm \&pn +(str) +Telephone number(s) for this host. +If the telephone number field contains an @ sign, +.Nm tip +searches the file +.Pa /etc/phones +file for a list of telephone numbers (see +.Xr phones 5 ) . +.It Cm \&tc +(str) +Indicates that the list of capabilities is continued in the named +description. +This is used primarily to share common capability information. +.El +.Sh FILES +.Bl -tag -width /etc/remote -compact +.It Pa /etc/remote +The +.Nm +host description file resides in +.Pa /etc . +.El +.Sh EXAMPLES +Here is a short example showing the use of the capability continuation +feature. +It defines a 56k modem connection on the first serial port at 115200 +bits per second, no parity using the Hayes command set with standard +line editing and end of file characters. +The arpavax entry includes everything in the UNIX-57600 entry plus +the phone number for arpavax (in this case an @ character so that it +is retrieved from the environment). +.Bd -literal +UNIX-57600:\e +:dv=/dev/cuau0:el=^D^U^C^S^Q^O@:oe=^D:du:at=hayes:br#115200:pa=none: +arpavax|ax:\e +:pn=\e@:tc=UNIX-57600 +.Ed +.Sh SEE ALSO +.Xr cu 1 , +.Xr tip 1 , +.Xr phones 5 +.Sh HISTORY +The +.Nm +file format appeared in +.Bx 4.2 . +.Sh BUGS +The +.Xr tip 1 +utility uses its own notion of the serial ports data rate rather than the +system default for a serial port. diff --git a/static/freebsd/man5/resolver.5 b/static/freebsd/man5/resolver.5 new file mode 100644 index 00000000..4dd3f8c9 --- /dev/null +++ b/static/freebsd/man5/resolver.5 @@ -0,0 +1,292 @@ +.\" Copyright (c) 1986, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 March 15, 2026 +.Dt RESOLVER 5 +.Os +.Sh NAME +.Nm resolver +.Nd resolver configuration file +.Sh SYNOPSIS +.Nm resolv.conf +.Sh DESCRIPTION +The +.Xr resolver 3 +is a set of routines in the C library +which provide access to the Internet Domain Name System. +The resolver configuration file contains information that is read +by the resolver routines the first time they are invoked by a process. +The file is designed to be human readable and contains a list of +keywords with values that provide various types of resolver information. +.Pp +On a normally configured system, setting this file manually should not +be necessary. +The only name server(s) to be queried will be on the local machine +or automatically configured using DHCP or a similar mechanism, +the domain name is determined from the host name, +and the domain search path is constructed from the domain name. +.Pp +The different configuration options are: +.Bl -tag -width nameserver +.It Sy nameserver +IPv4 or IPv6 address of a name server +that the resolver should query. +Up to +.Dv MAXNS +(currently 3) name servers may be listed, +one per keyword. +If there are multiple servers, +the resolver library queries them in the order listed. +If no +.Sy nameserver +entries are present, +the default is to use the name server on the local machine. +(The algorithm used is to try a name server, and if the query times out, +try the next, until out of name servers, +then repeat trying all the name servers +until a maximum number of retries are made). +.It Sy domain +Local domain name. +Most queries for names within this domain can use short names +relative to the local domain. +If no +.Sy domain +entry is present, the domain is determined +from the local host name returned by +.Xr gethostname 3 ; +the domain part is taken to be everything after the first +.Ql \&. . +Finally, if the host name does not contain a domain part, the root +domain is assumed. +.It Sy search +Search list for host-name lookup. +The search list is normally determined from the local domain name; +by default, it contains only the local domain name. +This may be changed by listing the desired domain search path +following the +.Sy search +keyword with spaces or tabs separating +the names. +Most resolver queries will be attempted using each component +of the search path in turn until a match is found. +Note that this process may be slow and will generate a lot of network +traffic if the servers for the listed domains are not local, +and that queries will time out if no server is available +for one of the domains. +.Pp +The search list is currently limited to six domains +with a total of 256 characters. +.It Sy sortlist +Sortlist allows addresses returned by gethostbyname to be sorted. +A sortlist is specified by IP address netmask pairs. +If the netmask is not specified, +it defaults to the historical Class A/B/C netmask of the net; +this usage is deprecated. +The IP address +and network pairs are separated by slashes. +Up to 10 pairs may +be specified. +E.g., +.Pp +.Dl "sortlist 10.9.1.0/255.255.240.0 10.9.0.0/255.255.0.0" +.It Sy options +Options allows certain internal resolver variables to be modified. +The syntax is +.Pp +\fBoptions\fP \fIoption\fP \fI...\fP +.Pp +where +.Sy option +is one of the following: +.Bl -tag -width no_tld_query +.It Sy debug +sets +.Dv RES_DEBUG +in _res.options. +.It Sy usevc +sets +.Dv RES_USEVC +to use TCP instead of UDP for queries. +.It Sy ndots : Ns Ar n +sets a threshold for the number of dots which must appear in a name given to +.Fn res_query +(see +.Xr resolver 3 ) +before an +.Em initial absolute query +will be made. +The default for +.Em n +is +.Dq 1 , +meaning that if there are any dots in a name, the name +will be tried first as an absolute name before any +.Em search list +elements are appended to it. +.It Sy timeout : Ns Ar n +sets the initial amount of time the resolver will wait +for a response from a remote +name server before retrying the query via a different name server. +The resolver may wait longer during subsequent retries +of the current query since an exponential back-off is applied to +the timeout value. +Measured in seconds, the default is +.Dv RES_TIMEOUT , +the allowed maximum is +.Dv RES_MAXRETRANS +(see +.In resolv.h ) . +.It Sy attempts : Ns Ar n +sets the number of times the resolver will send a query to each of +its name servers +before giving up and returning an error to the calling application. +The default is +.Dv RES_DFLRETRY , +the allowed maximum is +.Dv RES_MAXRETRY +(see +.In resolv.h ) . +.It Sy edns0 +Sets +.Dv RES_USE_EDNS0 . +Attach an OPT pseudo-RR for the EDNS0 extension, +as specified in RFC 2671. +This allows the resolver to advertise a larger UDP receive buffer size, +permitting responses larger than the original 512-byte limit. +.It Sy inet6 +Sets +.Dv RES_USE_INET6 . +Causes +.Xr gethostbyname 3 +to look up AAAA records before A records +and to map IPv4 responses into IPv6 addresses. +The use of this option is discouraged. +.It Sy insecure1 +Sets +.Dv RES_INSECURE1 . +Disables the check that the response was received from the +same server to which the query was sent. +Use of this option is a security risk and is not recommended. +.It Sy insecure2 +Sets +.Dv RES_INSECURE2 . +Disables the check that the response contains a query +matching the one that was sent. +Use of this option is a security risk and is not recommended. +.It Sy no-check-names +Sets +.Dv RES_NOCHECKNAME . +Disables the check of incoming host names for invalid characters +such as underscore, non-ASCII, or control characters. +.It Sy no_tld_query +tells the resolver not to attempt to resolve a top level domain name, that +is, a name that contains no dots. +Use of this option does not prevent +the resolver from obeying the standard +.Sy domain +and +.Sy search +rules with the given name. +.It Sy rotate +Sets +.Dv RES_ROTATE . +Causes the resolver to round-robin among the configured name servers, +distributing the query load instead of always trying the first +listed server. +.It Sy reload-period : Ns Ar n +The resolver checks the modification time of +.Pa /etc/resolv.conf +every +.Ar n +seconds. +If +.Pa /etc/resolv.conf +has changed, it is automatically reloaded. +The default for +.Ar n +is two seconds. +Setting it to zero disables the file check. +.El +.Pp +Options may also be specified as a space or tab separated list using the +.Dv RES_OPTIONS +environment variable. +.El +.Pp +The +.Sy domain +and +.Sy search +keywords are mutually exclusive. +If more than one instance of these keywords is present, +the last instance will override. +.Pp +The keyword and value must appear on a single line, and the keyword +.Pq for example, Sy nameserver +must start the line. +The value follows the keyword, separated by white space. +.Sh FILES +.Bl -tag -width /etc/resolv.conf -compact +.It Pa /etc/resolv.conf +The file +.Nm resolv.conf +resides in +.Pa /etc . +.El +.Sh EXAMPLES +A basic resolv.conf file could be in the following form. +.Bd -literal -offset indent +# The domain directive is only necessary, if your local +# router advertises something like localdomain and you have +# set up your hostnames via an external domain. +domain localdomain.tld + +# In case you a running a local dns server or caching name server +# like local-unbound(8) for example. +nameserver 127.0.0.1 + +# IP address of the local or ISP name service +nameserver 192.168.2.1 + +# Fallback nameservers, in this case these from Google. +nameserver 8.8.8.8 +nameserver 8.8.4.4 + +# Attach an OPT pseudo-RR for the EDNS0 extension, +# as specified in RFC 2671. +options edns0 +.Ed +.Sh SEE ALSO +.Xr gethostbyname 3 , +.Xr resolver 3 , +.Xr hostname 7 , +.Xr resolvconf 8 +.Sh HISTORY +The +.Nm resolv.conf +file format appeared in +.Bx 4.3 . diff --git a/static/freebsd/man5/services.5 b/static/freebsd/man5/services.5 new file mode 100644 index 00000000..e7f65cb9 --- /dev/null +++ b/static/freebsd/man5/services.5 @@ -0,0 +1,103 @@ +.\"- +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 29, 2024 +.Dt SERVICES 5 +.Os +.Sh NAME +.Nm services +.Nd internet service name and port number data base +.Sh DESCRIPTION +The +.Nm +file contains information regarding +the known services available in the +Internet. +For each service a single line should be present +with the following information: +.Bd -unfilled -offset indent +official service name +port number +protocol name +aliases +.Ed +.Pp +Items are separated by any number of blanks and/or tab characters. +The port number and protocol name are considered a single +.Em item ; +a ``/'' is used to +separate the port and protocol (e.g.\& ``512/tcp''). +A ``#'' indicates the beginning of +a comment; subsequent characters up to the end of the line are +not interpreted by the routines which search the file. +.Pp +Service names may contain any printable +character other than a field delimiter, newline, +or comment character. +.Pp +If +.Dq db +is specified as source in the +.Xr nsswitch.conf 5 , +.Pa /var/db/services.db +is searched. +The database in +.Pa /var/db/services.db +needs to be updated with +.Xr services_mkdb 8 +after changes to the services file have been applied. +.Sh NIS INTERACTION +Access to the NIS +.Pa services.byname +map can be enabled by adding a single ``+'' on a line by itself +in the +.Pa /etc/services +file. +This causes the contents of the NIS services map to be inserted +at the location where the ``+'' appears. +.Sh FILES +.Bl -tag -width /etc/services -compact +.It Pa /etc/services +The +.Nm +file resides in +.Pa /etc . +.El +.Sh SEE ALSO +.Xr getservent 3 , +.Xr nsswitch.conf 5 , +.Xr services_mkdb 8 +.Sh HISTORY +The +.Nm +file format appeared in +.Bx 4.2 . +.Sh BUGS +A name server should be used instead of a static file. diff --git a/static/freebsd/man5/shells.5 b/static/freebsd/man5/shells.5 new file mode 100644 index 00000000..13c430cd --- /dev/null +++ b/static/freebsd/man5/shells.5 @@ -0,0 +1,59 @@ +.\" Copyright (c) 1986, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 June 5, 1993 +.Dt SHELLS 5 +.Os +.Sh NAME +.Nm shells +.Nd shell database +.Sh DESCRIPTION +The +.Nm +file contains a list of the shells on the system. +For each shell a single line should be present, consisting of the +shell's path, relative to root. +.Pp +A hash mark (``#'') indicates the beginning of a comment; subsequent +characters up to the end of the line are not interpreted by the +routines which search the file. +Blank lines are also ignored. +.Sh FILES +.Bl -tag -width /etc/shells -compact +.It Pa /etc/shells +The +.Nm +file resides in +.Pa /etc . +.El +.Sh SEE ALSO +.Xr getusershell 3 +.Sh HISTORY +The +.Nm +file format appeared in +.Bx 4.3 tahoe . diff --git a/static/freebsd/man5/src.conf.5 b/static/freebsd/man5/src.conf.5 new file mode 100644 index 00000000..2dd42c57 --- /dev/null +++ b/static/freebsd/man5/src.conf.5 @@ -0,0 +1,2056 @@ +.\" DO NOT EDIT-- this file is @generated by tools/build/options/makeman. +.Dd April 22, 2026 +.Dt SRC.CONF 5 +.Os +.Sh NAME +.Nm src.conf +.Nd "source build options" +.Sh DESCRIPTION +The +.Nm +file contains variables that control what components will be generated during +the build process of the +.Fx +source tree; see +.Xr build 7 . +.Pp +The +.Nm +file uses the standard makefile syntax. +However, +.Nm +should not specify any dependencies to +.Xr make 1 . +Instead, +.Nm +is to set +.Xr make 1 +variables that control the aspects of how the system builds. +.Pp +The default location of +.Nm +is the top level of the source tree, or +.Pa /etc/src.conf +if no +.Nm +is found in the source tree itself, +though an alternative location can be specified in the +.Xr make 1 +variable +.Va SRCCONF . +Overriding the location of +.Nm +may be necessary if the system-wide settings are not suitable +for a particular build. +For instance, setting +.Va SRCCONF +to +.Pa /dev/null +effectively resets all build controls to their defaults. +.Pp +The only purpose of +.Nm +is to control the compilation of the +.Fx +source code, which is usually located in +.Pa /usr/src . +As a rule, the system administrator creates +.Nm +when the values of certain control variables need to be changed +from their defaults. +.Pp +In addition, control variables can be specified +for a particular build via the +.Fl D +option of +.Xr make 1 +or in its environment; see +.Xr environ 7 . +.Pp +The environment of +.Xr make 1 +for the build can be controlled via the +.Va SRC_ENV_CONF +variable, which defaults to +.Pa /etc/src-env.conf . +Some examples that may only be set in this file are +.Va WITH_DIRDEPS_BUILD , +and +.Va WITH_META_MODE , +and +.Va MAKEOBJDIRPREFIX +as they are environment-only variables. +.Pp +The values of +.Va WITH_ +and +.Va WITHOUT_ +variables are ignored regardless of their setting; +even if they would be set to +.Dq Li FALSE +or +.Dq Li NO . +The presence of an option causes +it to be honored by +.Xr make 1 . +.Pp +This list provides a name and short description for variables +that can be used for source builds. +.Bl -tag -width indent +.It Va WITHOUT_ACCT +Do not build process accounting tools such as +.Xr accton 8 +and +.Xr sa 8 . +.It Va WITHOUT_ACPI +Do not build +.Xr acpiconf 8 , +.Xr acpidump 8 +and related programs. +.It Va WITHOUT_APM +Do not build +.Xr apm 8 , +.Xr apmd 8 +and related programs. +.It Va WITH_ASAN +Build the base system with Address Sanitizer (ASan) to detect +memory corruption bugs such as buffer overflows or use-after-free. +Requires that Clang be used as the base system compiler +and that the runtime support library is available. +When set, it enforces these options: +.Pp +.Bl -item -compact +.It +.Va WITH_LLVM_BINUTILS +.El +.It Va WITHOUT_ASSERT_DEBUG +Compile programs and libraries without the +.Xr assert 3 +checks. +.It Va WITHOUT_AT +Do not build +.Xr at 1 +and related utilities. +.It Va WITHOUT_AUDIT +Do not build audit support into system programs. +.It Va WITHOUT_AUTHPF +Do not build +.Xr authpf 8 . +.It Va WITHOUT_AUTOFS +Do not build +.Xr autofs 4 +related programs, libraries, and kernel modules. +.It Va WITHOUT_AUTO_OBJ +Disable automatic creation of objdirs. +This is enabled by default if the wanted OBJDIR is writable by the current user. +.Pp +This must be set in the environment, make command line, or +.Pa /etc/src-env.conf , +not +.Pa /etc/src.conf . +.It Va WITH_BEARSSL +Build the BearSSL library. +.Pp +BearSSL is a tiny SSL library suitable for embedded environments. +For details see +.Lk https://www.BearSSL.org/ +.Pp +This library is currently only used to perform +signature verification and related operations +for Verified Exec and +.Xr loader 8 . +.Pp +Due to size constraints in the BIOS environment on x86, one may need to set +.Va LOADERSIZE +larger than the +default 500000, although often loader is under the 500k limit even with +this option. +Setting +.Va LOADERSIZE +larger than 500000 may cause +.Xr pxeboot 8 +to be too large to work. +Careful testing of the loader in the target environment when built with a larger +limit to establish safe limits is critical because different BIOS environments +reserve differing amounts of the low 640k space, making a precise limit for +everybody impossible. +.Pp +See also +.Va WITH_LOADER_PXEBOOT +for other considerations. +When set, these options are also in effect: +.Pp +.Bl -inset -compact +.It Va WITH_LOADER_EFI_SECUREBOOT +(unless +.Va WITHOUT_LOADER_EFI_SECUREBOOT +is set explicitly) +.It Va WITH_LOADER_VERIEXEC +(unless +.Va WITHOUT_LOADER_VERIEXEC +is set explicitly) +.It Va WITH_LOADER_VERIEXEC_VECTX +(unless +.Va WITHOUT_LOADER_VERIEXEC_VECTX +is set explicitly) +.It Va WITH_VERIEXEC +(unless +.Va WITHOUT_VERIEXEC +is set explicitly) +.El +.It Va WITHOUT_BHYVE +Do not build or install +.Xr bhyve 8 , +associated utilities, and examples. +.Pp +This option only affects amd64/amd64 and arm64/aarch64. +.It Va WITH_BHYVE_SNAPSHOT +Include support for save and restore (snapshots) in +.Xr bhyve 8 +and +.Xr bhyvectl 8 . +.Pp +This option only affects amd64/amd64. +.It Va WITH_BIND_NOW +Build all binaries with the +.Dv DF_BIND_NOW +flag set to indicate that the run-time loader should perform all relocation +processing at process startup rather than on demand. +The combination of the +.Va BIND_NOW +and +.Va RELRO +options provide "full" Relocation Read-Only (RELRO) support. +With full RELRO the entire GOT is made read-only after performing relocation at +startup, avoiding GOT overwrite attacks. +.It Va WITHOUT_BLACKLIST +This option has been renamed to +.Va WITHOUT_BLOCKLIST . +When set, it enforces these options: +.Pp +.Bl -item -compact +.It +.Va WITHOUT_BLOCKLIST +.El +.Pp +When set, these options are also in effect: +.Pp +.Bl -inset -compact +.It Va WITHOUT_BLACKLIST_SUPPORT +(unless +.Va WITH_BLACKLIST_SUPPORT +is set explicitly) +.It Va WITHOUT_BLOCKLIST_SUPPORT +(unless +.Va WITH_BLOCKLIST_SUPPORT +is set explicitly) +.El +.It Va WITHOUT_BLACKLIST_SUPPORT +This option has been renamed to +.Va WITHOUT_BLOCKLIST_SUPPORT . +When set, it enforces these options: +.Pp +.Bl -item -compact +.It +.Va WITHOUT_BLOCKLIST_SUPPORT +.El +.It Va WITHOUT_BLOCKLIST +Set this if you do not want to build +.Xr blocklistd 8 +and +.Xr blocklistctl 8 . +When set, it enforces these options: +.Pp +.Bl -item -compact +.It +.Va WITHOUT_BLACKLIST +.El +.Pp +When set, these options are also in effect: +.Pp +.Bl -inset -compact +.It Va WITHOUT_BLACKLIST_SUPPORT +(unless +.Va WITH_BLACKLIST_SUPPORT +is set explicitly) +.It Va WITHOUT_BLOCKLIST_SUPPORT +(unless +.Va WITH_BLOCKLIST_SUPPORT +is set explicitly) +.El +.It Va WITHOUT_BLOCKLIST_SUPPORT +Build some programs without +.Xr libblocklist 3 +support, like +.Xr fingerd 8 +and +.Xr sshd 8 . +When set, it enforces these options: +.Pp +.Bl -item -compact +.It +.Va WITHOUT_BLACKLIST_SUPPORT +.El +.It Va WITHOUT_BLUETOOTH +Do not build Bluetooth related kernel modules, programs and libraries. +.It Va WITHOUT_BOOT +Do not build the boot blocks and loader. +.It Va WITHOUT_BOOTPARAMD +Do not build or install +.Xr bootparamd 8 . +.It Va WITHOUT_BOOTPD +Do not build or install +.Xr bootpd 8 . +.It Va WITH_BRANCH_PROTECTION +Build with branch protection enabled. +On arm64 enable the use of pointer authentication and +branch target identification instructions on arm64. +These can be used to help mitigate some exploit techniques. +.It Va WITHOUT_BSDINSTALL +Do not build +.Xr bsdinstall 8 , +.Xr sade 8 , +and related programs. +.It Va WITHOUT_BSNMP +Do not build or install +.Xr bsnmpd 1 +and related libraries and data files. +.It Va WITHOUT_CALENDAR +Do not build +.Xr calendar 1 . +.It Va WITHOUT_CAROOT +Do not add the trusted certificates from the Mozilla NSS bundle to +base. +.It Va WITHOUT_CASPER +This option has no effect. +.It Va WITH_CCACHE_BUILD +Use +.Xr ccache 1 +for the build. +No configuration is required except to install the +.Sy devel/ccache +or +.Sy devel/sccache +package. +When using with +.Xr distcc 1 , +set +.Sy CCACHE_PREFIX=/usr/local/bin/distcc . +When using with sccache +set +.Sy CCACHE_NAME=sccache +in +.Xr src.conf 5 . +The default cache directory of +.Pa $HOME/.ccache +will be used, which can be overridden by setting +.Sy CCACHE_DIR . +The +.Sy CCACHE_COMPILERCHECK +option defaults to +.Sy content +when using the in-tree bootstrap compiler, +and +.Sy mtime +when using an external compiler. +The +.Sy CCACHE_CPP2 +option is used for Clang but not GCC. +.Pp +Sharing a cache between multiple work directories requires using a layout +similar to +.Pa /some/prefix/src +.Pa /some/prefix/obj +and an environment such as: +.Bd -literal -offset indent +CCACHE_BASEDIR='${SRCTOP:H}' MAKEOBJDIRPREFIX='${SRCTOP:H}/obj' +.Ed +.Pp +See +.Xr ccache 1 +for more configuration options. +.It Va WITHOUT_CCD +Do not build +.Xr geom_ccd 4 +and related utilities. +.It Va WITHOUT_CDDL +Do not build code licensed under Sun's CDDL. +When set, it enforces these options: +.Pp +.Bl -item -compact +.It +.Va WITHOUT_CTF +.It +.Va WITHOUT_DTRACE +.It +.Va WITHOUT_LOADER_ZFS +.It +.Va WITHOUT_ZFS +.It +.Va WITHOUT_ZFS_TESTS +.El +.It Va WITHOUT_CLANG +Do not build the Clang C/C++ compiler during the regular phase of the build. +When set, it enforces these options: +.Pp +.Bl -item -compact +.It +.Va WITHOUT_CLANG_EXTRAS +.It +.Va WITHOUT_CLANG_FORMAT +.It +.Va WITHOUT_CLANG_FULL +.It +.Va WITHOUT_LLVM_COV +.El +.Pp +When set, these options are also in effect: +.Pp +.Bl -inset -compact +.It Va WITHOUT_LLVM_TARGET_AARCH64 +(unless +.Va WITH_LLVM_TARGET_AARCH64 +is set explicitly) +.It Va WITHOUT_LLVM_TARGET_ALL +(unless +.Va WITH_LLVM_TARGET_ALL +is set explicitly) +.It Va WITHOUT_LLVM_TARGET_ARM +(unless +.Va WITH_LLVM_TARGET_ARM +is set explicitly) +.It Va WITHOUT_LLVM_TARGET_POWERPC +(unless +.Va WITH_LLVM_TARGET_POWERPC +is set explicitly) +.It Va WITHOUT_LLVM_TARGET_RISCV +(unless +.Va WITH_LLVM_TARGET_RISCV +is set explicitly) +.El +.It Va WITHOUT_CLANG_BOOTSTRAP +Do not build the Clang C/C++ compiler during the bootstrap phase of +the build. +To be able to build the system, either gcc or clang bootstrap must be +enabled unless an alternate compiler is provided via XCC. +.It Va WITH_CLANG_EXTRAS +Build additional clang and llvm tools, such as bugpoint and +clang-format. +.It Va WITH_CLANG_FORMAT +Build clang-format. +.It Va WITHOUT_CLANG_FULL +Avoid building the ARCMigrate, Rewriter and StaticAnalyzer components of +the Clang C/C++ compiler. +.It Va WITH_CLEAN +Clean before building world and/or kernel. +Note that recording a new epoch in +.Pa .clean_build_epoch +in the root of the source tree will also force a clean world build. +When set, these options are also in effect: +.Pp +.Bl -inset -compact +.It Va WITHOUT_DEPEND_CLEANUP +(unless +.Va WITH_DEPEND_CLEANUP +is set explicitly) +.El +.It Va WITHOUT_CPP +Do not build +.Xr cpp 1 . +.It Va WITHOUT_CROSS_COMPILER +Do not build any cross compiler in the cross-tools stage of buildworld. +When compiling a different version of +.Fx +than what is installed on the system, provide an alternate +compiler with XCC to ensure success. +When compiling with an identical version of +.Fx +to the host, this option may be safely used. +This option may also be safe when the host version of +.Fx +is close to the sources being built, but all bets are off if there have +been any changes to the toolchain between the versions. +When set, it enforces these options: +.Pp +.Bl -item -compact +.It +.Va WITHOUT_CLANG_BOOTSTRAP +.It +.Va WITHOUT_ELFTOOLCHAIN_BOOTSTRAP +.It +.Va WITHOUT_LLD_BOOTSTRAP +.It +.Va WITHOUT_LLVM_BINUTILS_BOOTSTRAP +.El +.It Va WITHOUT_CRYPT +Do not build any crypto code. +When set, it enforces these options: +.Pp +.Bl -item -compact +.It +.Va WITHOUT_DMAGENT +.It +.Va WITHOUT_KERBEROS +.It +.Va WITHOUT_LDNS +.It +.Va WITHOUT_LDNS_UTILS +.It +.Va WITHOUT_LOADER_ZFS +.It +.Va WITHOUT_MITKRB5 +.It +.Va WITHOUT_OPENSSH +.It +.Va WITHOUT_OPENSSL +.It +.Va WITHOUT_OPENSSL_KTLS +.It +.Va WITHOUT_PKGBOOTSTRAP +.It +.Va WITHOUT_UNBOUND +.It +.Va WITHOUT_ZFS +.It +.Va WITHOUT_ZFS_TESTS +.El +.Pp +When set, these options are also in effect: +.Pp +.Bl -inset -compact +.It Va WITHOUT_KERBEROS_SUPPORT +(unless +.Va WITH_KERBEROS_SUPPORT +is set explicitly) +.El +.It Va WITH_CTF +Compile with CTF (Compact C Type Format) data. +CTF data encapsulates a reduced form of debugging information +similar to DWARF and the venerable stabs and is required for DTrace. +.It Va WITHOUT_CUSE +Do not build CUSE-related programs and libraries. +.It Va WITHOUT_CXGBETOOL +Do not build +.Xr cxgbetool 8 +.Pp +This is a default setting on +arm/armv7 and riscv/riscv64. +.It Va WITH_CXGBETOOL +Build +.Xr cxgbetool 8 +.Pp +This is a default setting on +amd64/amd64, arm64/aarch64, i386/i386, powerpc/powerpc64 and powerpc/powerpc64le. +.It Va WITHOUT_DEBUG_FILES +Avoid building or installing standalone debug files for each +executable binary and shared library. +.It Va WITHOUT_DEPEND_CLEANUP +Do not attempt to detect if the object tree needs cleaning in part or in +whole before building. +This speeds up incremental builds, especially when experimenting with +build options, but may cause the build to inexplicably fail or produce +non-functioning binaries. +.It Va WITH_DETECT_TZ_CHANGES +Make the time handling code detect changes to the timezone files. +.It Va WITH_DIALOG +Do build +.Xr dialog 1 , +.Xr dialog 3 , +.Xr dpv 1 , +and +.Xr dpv 3 . +.It Va WITHOUT_DICT +Do not build the Webster dictionary files. +.It Va WITH_DIRDEPS_BUILD +This is an alternate build system. +For details see +https://www.crufty.net/sjg/docs/freebsd-meta-mode.htm. +Build commands can be seen from the top-level with: +.Dl make show-valid-targets +The build is driven by dirdeps.mk using +.Va DIRDEPS +stored in +Makefile.depend files found in each directory. +.Pp +The build can be started from anywhere, and behaves the same. +The initial instance of +.Xr make 1 +recursively reads +.Va DIRDEPS +from +.Pa Makefile.depend , +computing a graph of tree dependencies from the current origin. +Setting +.Va NO_DIRDEPS +skips checking dirdep dependencies and will only build in the current +and child directories. +.Va NO_DIRDEPS_BELOW +skips building any dirdeps and only build the current directory. +.Pp +This also utilizes the +.Va WITH_META_MODE +logic for incremental builds. +.Pp +The build hides commands executed unless +.Va NO_SILENT +is defined. +.Pp +Note that there is currently no mass install feature for this. +This build is designed for producing packages, that can then be installed +on a target system. +.Pp +The implementation in +.Fx +is incomplete. +Completion would require leaf directories for building each kernel +and package so that their dependencies can be tracked. +When set, it enforces these options: +.Pp +.Bl -item -compact +.It +.Va WITH_INSTALL_AS_USER +.El +.Pp +When set, these options are also in effect: +.Pp +.Bl -inset -compact +.It Va WITH_META_ERROR_TARGET +(unless +.Va WITHOUT_META_ERROR_TARGET +is set explicitly) +.It Va WITH_META_MODE +(unless +.Va WITHOUT_META_MODE +is set explicitly) +.It Va WITH_STAGING +(unless +.Va WITHOUT_STAGING +is set explicitly) +.It Va WITH_STAGING_MAN +(unless +.Va WITHOUT_STAGING_MAN +is set explicitly) +.It Va WITH_STAGING_PROG +(unless +.Va WITHOUT_STAGING_PROG +is set explicitly) +.It Va WITH_SYSROOT +(unless +.Va WITHOUT_SYSROOT +is set explicitly) +.El +.Pp +This must be set in the environment, make command line, or +.Pa /etc/src-env.conf , +not +.Pa /etc/src.conf . +.It Va WITH_DIRDEPS_CACHE +Cache result of dirdeps.mk which can save significant time +for subsequent builds. +Depends on +.Va WITH_DIRDEPS_BUILD . +.Pp +This must be set in the environment, make command line, or +.Pa /etc/src-env.conf , +not +.Pa /etc/src.conf . +.It Va WITH_DISK_IMAGE_TOOLS_BOOTSTRAP +Build +.Xr etdump 1 , +.Xr makefs 8 +and +.Xr mkimg 1 +as bootstrap tools. +.It Va WITHOUT_DMAGENT +Do not build dma Mail Transport Agent. +.It Va WITHOUT_DOCCOMPRESS +Do not install compressed system documentation. +Only the uncompressed version will be installed. +.It Va WITHOUT_DTRACE +Do not build DTrace framework kernel modules, libraries, and user commands. +When set, it enforces these options: +.Pp +.Bl -item -compact +.It +.Va WITHOUT_CTF +.El +.It Va WITH_DTRACE_ASAN +Compile userspace DTrace code (libdtrace, dtrace(1), lockstat(1), plockstat(1)) +with address and undefined behavior sanitizers. +Requires that Clang be used as the base system compiler +and that the runtime support library is available. +.It Va WITH_DTRACE_TESTS +Build and install the DTrace test suite in +.Pa /usr/tests/cddl/usr.sbin/dtrace . +This test suite is considered experimental on architectures other than +amd64/amd64 and running it may cause system instability. +.It Va WITHOUT_DYNAMICROOT +Set this if you do not want to link +.Pa /bin +and +.Pa /sbin +dynamically. +.It Va WITHOUT_EE +Do not build and install +.Xr edit 1 , +.Xr ee 1 , +and related programs. +.It Va WITHOUT_EFI +Set not to build +.Xr efivar 3 +and +.Xr efivar 8 . +.Pp +This is a default setting on +i386/i386, powerpc/powerpc64 and powerpc/powerpc64le. +.It Va WITH_EFI +Build +.Xr efivar 3 +and +.Xr efivar 8 . +.Pp +This is a default setting on +amd64/amd64, arm/armv7, arm64/aarch64 and riscv/riscv64. +.It Va WITHOUT_ELFTOOLCHAIN_BOOTSTRAP +Do not build ELF Tool Chain tools +(addr2line, nm, size, strings and strip) +as part of the bootstrap process. +.Bf -symbolic +An alternate bootstrap tool chain must be provided. +.Ef +.It Va WITHOUT_EXAMPLES +Avoid installing examples to +.Pa /usr/share/examples/ . +.It Va WITHOUT_FDT +Do not build Flattened Device Tree support as part of the base system. +This includes the device tree compiler (dtc) and libfdt support library. +.Pp +This is a default setting on +amd64/amd64 and i386/i386. +.It Va WITH_FDT +Build Flattened Device Tree support as part of the base system. +This includes the device tree compiler (dtc) and libfdt support library. +.Pp +This is a default setting on +arm/armv7, arm64/aarch64, powerpc/powerpc64, powerpc/powerpc64le and riscv/riscv64. +.It Va WITHOUT_FILE +Do not build +.Xr file 1 +and related programs. +.It Va WITHOUT_FINGER +Do not build or install +.Xr finger 1 +and +.Xr fingerd 8 . +.It Va WITHOUT_FLOPPY +Do not build or install programs +for operating floppy disk driver. +.It Va WITHOUT_FORMAT_EXTENSIONS +Do not enable +.Fl fformat-extensions +when compiling the kernel. +Also disables all format checking. +.It Va WITHOUT_FORTH +Build bootloaders without Forth support. +.It Va WITHOUT_FREEBSD_UPDATE +Do not build +.Xr freebsd-update 8 . +.It Va WITHOUT_FTP +Do not build or install +.Xr ftp 1 . +.It Va WITHOUT_GAMES +Do not build games. +.It Va WITHOUT_GOOGLETEST +Neither build nor install +.Lb libgmock , +.Lb libgtest , +and dependent tests. +.It Va WITHOUT_GPIO +Do not build +.Xr gpioctl 8 +as part of the base system. +.It Va WITHOUT_HAST +Do not build +.Xr hastd 8 +and related utilities. +.It Va WITH_HESIOD +Build Hesiod support. +.It Va WITHOUT_HTML +Do not build HTML docs. +.It Va WITHOUT_HYPERV +Do not build or install HyperV utilities. +.Pp +This is a default setting on +arm/armv7, powerpc/powerpc64, powerpc/powerpc64le and riscv/riscv64. +.It Va WITH_HYPERV +Build or install HyperV utilities. +.Pp +This is a default setting on +amd64/amd64, arm64/aarch64 and i386/i386. +.It Va WITHOUT_ICONV +Do not build iconv as part of libc. +.It Va WITHOUT_INCLUDES +Do not install header files. +This option used to be spelled +.Va NO_INCS . +.Bf -symbolic +The option does not work for build targets. +.Ef +.It Va WITHOUT_INET +Do not build programs and libraries related to IPv4 networking. +When set, it enforces these options: +.Pp +.Bl -item -compact +.It +.Va WITHOUT_INET_SUPPORT +.El +.It Va WITHOUT_INET6 +Do not build +programs and libraries related to IPv6 networking. +When set, it enforces these options: +.Pp +.Bl -item -compact +.It +.Va WITHOUT_INET6_SUPPORT +.El +.It Va WITHOUT_INET6_SUPPORT +Build libraries, programs, and kernel modules without IPv6 support. +.It Va WITHOUT_INETD +Do not build +.Xr inetd 8 . +.It Va WITHOUT_INET_SUPPORT +Build libraries, programs, and kernel modules without IPv4 support. +.It Va WITHOUT_INSTALLLIB +Set this to not install optional libraries. +For example, when creating a +.Xr nanobsd 8 +image. +.Bf -symbolic +The option does not work for build targets. +.Ef +.It Va WITH_INSTALL_AS_USER +Make install targets succeed for non-root users by installing +files with owner and group attributes set to that of the user running +the +.Xr make 1 +command. +The user still must set the +.Va DESTDIR +variable to point to a directory where the user has write permissions. +.It Va WITHOUT_IPFILTER +Do not build IP Filter package. +.It Va WITH_IPFILTER_IPFS +Enable building the +.Xr ipfs 8 +tool to save and restore IPFilter state tables. +.It Va WITHOUT_IPFW +Do not build IPFW tools. +.It Va WITHOUT_IPSEC_SUPPORT +Do not build the kernel with +.Xr ipsec 4 +support. +This option is needed for +.Xr ipsec 4 +and +.Xr tcpmd5 4 . +.It Va WITHOUT_ISCSI +Do not build +.Xr iscsid 8 +and related utilities. +.It Va WITHOUT_JAIL +Do not build tools for the support of jails; e.g., +.Xr jail 8 . +.It Va WITHOUT_JEMALLOC_LG_VADDR_WIDE +Disallow programs to use more than 48 address bits on amd64. +Incompatible with LA57 mode. +Enabling this option might result in a slight reduction in memory +consumption for jemalloc metadata, but also requires disabling LA57 +(if hardware supports it). +.It Va WITHOUT_KDUMP +Do not build +.Xr kdump 1 +and +.Xr truss 1 . +.It Va WITHOUT_KERBEROS +Set this to not build Kerberos. +When set, these options are also in effect: +.Pp +.Bl -inset -compact +.It Va WITHOUT_KERBEROS_SUPPORT +(unless +.Va WITH_KERBEROS_SUPPORT +is set explicitly) +.El +.It Va WITHOUT_KERBEROS_SUPPORT +Build some programs without Kerberos support, like +.Xr ssh 1 , +.Xr telnet 1 , +and +.Xr sshd 8 . +.It Va WITH_KERNEL_BIN +Generate and install kernel.bin from kernel as part of the normal build and +install processes for the kernel. Available only on arm and arm64. + +Usually this will be added to the kernel config file with: + +makeoptions WITH_KERNEL_BIN=1 + +though it can also be used on the command line. +.It Va WITH_KERNEL_RETPOLINE +Enable the "retpoline" mitigation for CVE-2017-5715 in the kernel +build. +.It Va WITHOUT_KERNEL_SYMBOLS +Do not install standalone kernel debug symbol files. +This option has no effect at build time. +.It Va WITHOUT_KVM +Do not build the +.Nm libkvm +library as a part of the base system. +.Bf -symbolic +The option has no effect yet. +.Ef +When set, these options are also in effect: +.Pp +.Bl -inset -compact +.It Va WITHOUT_KVM_SUPPORT +(unless +.Va WITH_KVM_SUPPORT +is set explicitly) +.El +.It Va WITHOUT_KVM_SUPPORT +Build some programs without optional +.Nm libkvm +support. +.It Va WITHOUT_LDNS +Setting this variable will prevent the LDNS library from being built. +When set, it enforces these options: +.Pp +.Bl -item -compact +.It +.Va WITHOUT_LDNS_UTILS +.It +.Va WITHOUT_UNBOUND +.El +.It Va WITHOUT_LDNS_UTILS +Setting this variable will prevent building the LDNS utilities +.Xr drill 1 +and +.Xr host 1 . +.It Va WITHOUT_LEGACY_CONSOLE +Do not build programs that support a legacy PC console; e.g., +.Xr kbdcontrol 1 +and +.Xr vidcontrol 1 . +.It Va WITHOUT_LIB32 +On 64-bit platforms, do not build 32-bit library set and a +.Nm ld-elf32.so.1 +runtime linker. +.Pp +This is a default setting on +arm/armv7, i386/i386, powerpc/powerpc64le and riscv/riscv64. +.It Va WITH_LIB32 +On 64-bit platforms, build the 32-bit library set and a +.Nm ld-elf32.so.1 +runtime linker. +.Pp +This is a default setting on +amd64/amd64, arm64/aarch64 and powerpc/powerpc64. +.It Va WITHOUT_LLD +Do not build LLVM's lld linker. +.It Va WITHOUT_LLDB +Do not build the LLDB debugger. +.Pp +This is a default setting on +riscv/riscv64. +.It Va WITH_LLDB +Build the LLDB debugger. +.Pp +This is a default setting on +amd64/amd64, arm/armv7, arm64/aarch64, i386/i386, powerpc/powerpc64 and powerpc/powerpc64le. +.It Va WITHOUT_LLD_BOOTSTRAP +Do not build the LLD linker during the bootstrap phase of +the build. +To be able to build the system an alternate linker must be provided via XLD. +.It Va WITHOUT_LLVM_ASSERTIONS +Disable debugging assertions in LLVM. +.It Va WITHOUT_LLVM_BINUTILS +Install ELF Tool Chain's binary utilities instead of LLVM's. +This includes +.Xr addr2line 1 , +.Xr ar 1 , +.Xr nm 1 , +.Xr objcopy 1 , +.Xr ranlib 1 , +.Xr readelf 1 , +.Xr size 1 , +and +.Xr strip 1 . +Regardless of this setting, LLVM tools are used for +.Xr c++filt 1 +and +.Xr objdump 1 . +.Xr strings 1 +is always provided by ELF Tool Chain. +.It Va WITHOUT_LLVM_BINUTILS_BOOTSTRAP +Do not build LLVM binary utilities during the bootstrap phase of +the build. +To be able to build the system alternate binary utilities must be provided via +.Ev XAR , +.Ev XNM , +.Ev XOBJCOPY , +.Ev XSIZE , +.Ev XSTRINGS , +and +.Ev XSTRIPBIN . + +.It Va WITHOUT_LLVM_COV +Do not build the +.Xr llvm-cov 1 +tool. +.It Va WITH_LLVM_FULL_DEBUGINFO +Generate full debug information for LLVM libraries and tools, which uses +more disk space and build resources, but allows for easier debugging. +.It Va WITH_LLVM_LINK_STATIC_LIBRARIES +Link LLVM libraries (libllvm, libclang, liblldb) statically into each of +the binaries that use them. + +This means that binaries linked against these libraries, such as clang, +ld.lld and lldb will be much larger and position dependent, but will +start more quickly. +.It Va WITHOUT_LLVM_TARGET_AARCH64 +Do not build LLVM target support for AArch64. +The +.Va LLVM_TARGET_ALL +option should be used rather than this in most cases. +.It Va WITHOUT_LLVM_TARGET_ALL +Only build the required LLVM target support. +This option is preferred to specific target support options. +When set, these options are also in effect: +.Pp +.Bl -inset -compact +.It Va WITHOUT_LLVM_TARGET_AARCH64 +(unless +.Va WITH_LLVM_TARGET_AARCH64 +is set explicitly) +.It Va WITHOUT_LLVM_TARGET_ARM +(unless +.Va WITH_LLVM_TARGET_ARM +is set explicitly) +.It Va WITHOUT_LLVM_TARGET_POWERPC +(unless +.Va WITH_LLVM_TARGET_POWERPC +is set explicitly) +.It Va WITHOUT_LLVM_TARGET_RISCV +(unless +.Va WITH_LLVM_TARGET_RISCV +is set explicitly) +.El +.It Va WITHOUT_LLVM_TARGET_ARM +Do not build LLVM target support for ARM. +The +.Va LLVM_TARGET_ALL +option should be used rather than this in most cases. +.It Va WITH_LLVM_TARGET_BPF +Build LLVM target support for BPF. +The +.Va LLVM_TARGET_ALL +option should be used rather than this in most cases. +.It Va WITH_LLVM_TARGET_MIPS +Build LLVM target support for MIPS. +The +.Va LLVM_TARGET_ALL +option should be used rather than this in most cases. +.It Va WITHOUT_LLVM_TARGET_POWERPC +Do not build LLVM target support for PowerPC. +The +.Va LLVM_TARGET_ALL +option should be used rather than this in most cases. +.It Va WITHOUT_LLVM_TARGET_RISCV +Do not build LLVM target support for RISC-V. +The +.Va LLVM_TARGET_ALL +option should be used rather than this in most cases. +.It Va WITHOUT_LLVM_TARGET_X86 +Do not build LLVM target support for X86. +The +.Va LLVM_TARGET_ALL +option should be used rather than this in most cases. +.It Va WITHOUT_LOADER_BIOS_TEXTONLY +Include graphics, font and video mode support in the i386 and amd64 BIOS +boot loader. +.It Va WITH_LOADER_EFI_SECUREBOOT +Enable building +.Xr loader 8 +with support for verification based on certificates obtained from UEFI. +.It Va WITHOUT_LOADER_GELI +Disable inclusion of GELI crypto support in the boot chain binaries. +.Pp +This is a default setting on +powerpc/powerpc64 and powerpc/powerpc64le. +.It Va WITH_LOADER_GELI +Build GELI bootloader support. +.Pp +This is a default setting on +amd64/amd64, arm/armv7, arm64/aarch64, i386/i386 and riscv/riscv64. +.It Va WITHOUT_LOADER_IA32 +Do not build the 32-bit UEFI loader. +.Pp +This is a default setting on +arm/armv7, arm64/aarch64, i386/i386, powerpc/powerpc64, powerpc/powerpc64le and riscv/riscv64. +.It Va WITH_LOADER_IA32 +Build the 32-bit UEFI loader. +.Pp +This is a default setting on +amd64/amd64. +.It Va WITHOUT_LOADER_KBOOT +Do not build kboot, a linuxboot environment loader +.Pp +This is a default setting on +arm/armv7, i386/i386, powerpc/powerpc64le and riscv/riscv64. +.It Va WITH_LOADER_KBOOT +Build kboot, a linuxboot environment loader +.Pp +This is a default setting on +amd64/amd64, arm64/aarch64 and powerpc/powerpc64. +.It Va WITHOUT_LOADER_LUA +Do not build LUA bindings for the boot loader. +.Pp +This is a default setting on +powerpc/powerpc64 and powerpc/powerpc64le. +.It Va WITH_LOADER_LUA +Build LUA bindings for the boot loader. +.Pp +This is a default setting on +amd64/amd64, arm/armv7, arm64/aarch64, i386/i386 and riscv/riscv64. +.It Va WITHOUT_LOADER_OFW +Disable building of openfirmware bootloader components. +.Pp +This is a default setting on +amd64/amd64, arm/armv7, arm64/aarch64, i386/i386 and riscv/riscv64. +.It Va WITH_LOADER_OFW +Build openfirmware bootloader components. +.Pp +This is a default setting on +powerpc/powerpc64 and powerpc/powerpc64le. +.It Va WITHOUT_LOADER_PXEBOOT +Do not build pxeboot on i386/amd64. +When the pxeboot is too large, or unneeded, it may be disabled with this option. +See +.Va WITH_LOADER_PXEBOOT +for how to adjust the defaults when you need both a larger +.Pa /boot/loader +and +.Pa /boot/pxeboot +.Pp +This option only has an effect on x86. +.It Va WITHOUT_LOADER_UBOOT +Disable building of ubldr. +.Pp +This is a default setting on +amd64/amd64, arm64/aarch64, i386/i386, powerpc/powerpc64le and riscv/riscv64. +.It Va WITH_LOADER_UBOOT +Build ubldr. +.Pp +This is a default setting on +arm/armv7 and powerpc/powerpc64. +.It Va WITH_LOADER_USB +Build the usb/kshim library + +.It Va WITH_LOADER_VERBOSE +Build with extra verbose debugging in the loader. +May explode already nearly too large loader over the limit. +Use with care. +.It Va WITH_LOADER_VERIEXEC +Enable building +.Xr loader 8 +with support for verification similar to Verified Exec. +.Pp +Depends on +.Va WITH_BEARSSL . +May require a larger +.Va LOADERSIZE . +When set, these options are also in effect: +.Pp +.Bl -inset -compact +.It Va WITH_LOADER_EFI_SECUREBOOT +(unless +.Va WITHOUT_LOADER_EFI_SECUREBOOT +is set explicitly) +.It Va WITH_LOADER_VERIEXEC_VECTX +(unless +.Va WITHOUT_LOADER_VERIEXEC_VECTX +is set explicitly) +.El +.It Va WITH_LOADER_VERIEXEC_PASS_MANIFEST +Enable building +.Xr loader 8 +with support to pass a verified manifest to the kernel. +The kernel has to be built with a module to parse the manifest. +.Pp +Depends on +.Va WITH_LOADER_VERIEXEC . +.It Va WITH_LOADER_VERIEXEC_VECTX +Enable building +.Xr loader 8 +with support for hashing and verifying kernel and modules as a side effect +of loading. +.Pp +Depends on +.Va WITH_LOADER_VERIEXEC . +.It Va WITHOUT_LOADER_ZFS +Do not build ZFS file system boot loader support. +.It Va WITHOUT_LOCALES +Do not build localization files; see +.Xr locale 1 . +.It Va WITHOUT_LOCATE +Do not build +.Xr locate 1 +and related programs. +.It Va WITHOUT_LPR +Do not build +.Xr lpr 1 +and related programs. +.It Va WITHOUT_LS_COLORS +Build +.Xr ls 1 +without support for colors to distinguish file types. +.It Va WITHOUT_MACHDEP_OPTIMIZATIONS +Prefer machine-independent non-assembler code in libc and libm. +.It Va WITHOUT_MAIL +Do not build any mail support (MUA or MTA). +When set, it enforces these options: +.Pp +.Bl -item -compact +.It +.Va WITHOUT_DMAGENT +.It +.Va WITHOUT_MAILWRAPPER +.It +.Va WITHOUT_SENDMAIL +.El +.It Va WITHOUT_MAILWRAPPER +Do not build the +.Xr mailwrapper 8 +MTA selector. +.It Va WITHOUT_MAKE +Do not install +.Xr make 1 +and related support files. +.It Va WITHOUT_MAKE_CHECK_USE_SANDBOX +Do not execute +.Dq Li "make check" +in limited sandbox mode. +This option should be paired with +.Va WITH_INSTALL_AS_USER +if executed as an unprivileged user. +See +.Xr tests 7 +for more details. +.It Va WITH_MALLOC_PRODUCTION +Disable assertions and statistics gathering in +.Xr malloc 3 . +The run-time options +.Dv opt.abort , +.Dv opt.abort_conf , +and +.Dv opt.junk +also default to false. +.It Va WITHOUT_MAN +Do not build manual pages. +When set, these options are also in effect: +.Pp +.Bl -inset -compact +.It Va WITHOUT_MAN_UTILS +(unless +.Va WITH_MAN_UTILS +is set explicitly) +.El +.It Va WITHOUT_MANCOMPRESS +Do not install compressed man pages. +Only the uncompressed versions will be installed. +.It Va WITH_MANSPLITPKG +Split man pages into their own packages during make package. +.It Va WITHOUT_MAN_UTILS +Do not build utilities for manual pages, +.Xr apropos 1 , +.Xr makewhatis 1 , +.Xr man 1 , +.Xr whatis 1 , +.Xr manctl 8 , +and related support files. +.It Va WITH_META_ERROR_TARGET +Enable the META_MODE .ERROR target. +.Pp +This target will copy the meta file of a failed target +to +.Va ERROR_LOGDIR +(default is +.Ql ${SRCTOP:H}/error ) +to help with failure analysis. +Depends on +.Va WITH_META_MODE . +This default when +.Va WITH_DIRDEPS_BUILD +is set. +.Pp +This must be set in the environment, make command line, or +.Pa /etc/src-env.conf , +not +.Pa /etc/src.conf . +.It Va WITH_META_MODE +Create +.Xr make 1 +meta files when building, which can provide a reliable incremental build when +using +.Xr filemon 4 . +The meta file is created in OBJDIR as +.Pa target.meta . +These meta files track the command that was executed, its output, and the +current directory. +The +.Xr filemon 4 +module is required unless +.Va NO_FILEMON +is defined. +When the module is loaded, any files used by the commands executed are +tracked as dependencies for the target in its meta file. +The target is considered out-of-date and rebuilt if any of these +conditions are true compared to the last build: +.Bl -bullet -compact +.It +The command to execute changes. +.It +The current working directory changes. +.It +The target's meta file is missing. +.It +The target's meta file is missing filemon data when filemon is loaded +and a previous run did not have it loaded. +.It +[requires +.Xr filemon 4 ] +Files read, executed or linked to are newer than the target. +.It +[requires +.Xr filemon 4 ] +Files read, written, executed or linked are missing. +.El +The meta files can also be useful for debugging. +.Pp +The build hides commands that are executed unless +.Va NO_SILENT +is defined. +Errors cause +.Xr make 1 +to show some of its environment for further debugging. +.Pp +The build operates as it normally would otherwise. +This option originally invoked a different build system but that was renamed +to +.Va WITH_DIRDEPS_BUILD . +.Pp +This must be set in the environment, make command line, or +.Pa /etc/src-env.conf , +not +.Pa /etc/src.conf . +.It Va WITHOUT_MITKRB5 +Set this to build KTH Heimdal instead of MIT Kerberos 5. +.It Va WITHOUT_MLX5TOOL +Do not build +.Xr mlx5tool 8 +.Pp +This is a default setting on +arm/armv7 and riscv/riscv64. +.It Va WITH_MLX5TOOL +Build +.Xr mlx5tool 8 +.Pp +This is a default setting on +amd64/amd64, arm64/aarch64, i386/i386, powerpc/powerpc64 and powerpc/powerpc64le. +.It Va WITHOUT_NETCAT +Do not build +.Xr nc 1 +utility. +.It Va WITHOUT_NETGRAPH +Do not build applications to support +.Xr netgraph 4 . +When set, it enforces these options: +.Pp +.Bl -item -compact +.It +.Va WITHOUT_BLUETOOTH +.El +.Pp +When set, these options are also in effect: +.Pp +.Bl -inset -compact +.It Va WITHOUT_NETGRAPH_SUPPORT +(unless +.Va WITH_NETGRAPH_SUPPORT +is set explicitly) +.El +.It Va WITHOUT_NETGRAPH_SUPPORT +Build libraries, programs, and kernel modules without netgraph support. +.It Va WITHOUT_NETLINK +Do not build +.Xr genl 1 +utility. +.It Va WITHOUT_NETLINK_SUPPORT +Make libraries and programs use rtsock and +.Xr sysctl 3 +interfaces instead of +.Xr snl 3 . +.It Va WITHOUT_NIS +Do not build +.Xr NIS 8 +support and related programs. +If set, you might need to adopt your +.Xr nsswitch.conf 5 +and remove +.Sq nis +entries. +.It Va WITHOUT_NLS +Do not build NLS catalogs. +When set, it enforces these options: +.Pp +.Bl -item -compact +.It +.Va WITHOUT_NLS_CATALOGS +.El +.It Va WITHOUT_NLS_CATALOGS +Do not build NLS catalog support for +.Xr csh 1 . +.It Va WITHOUT_NS_CACHING +Disable name caching in the +.Pa nsswitch +subsystem. +The generic caching daemon, +.Xr nscd 8 , +will not be built either if this option is set. +.It Va WITHOUT_NTP +Do not build +.Xr ntpd 8 +and related programs. +.It Va WITHOUT_NUAGEINIT +Do not install the limited cloud init support scripts. +.It Va WITHOUT_OFED +Do not build the +.Dq "OpenFabrics Enterprise Distribution" +InfiniBand software stack, including kernel modules and userspace libraries. +.Pp +This is a default setting on +arm/armv7. +When set, it enforces these options: +.Pp +.Bl -item -compact +.It +.Va WITHOUT_OFED_EXTRA +.El +.It Va WITH_OFED +Build the +.Dq "OpenFabrics Enterprise Distribution" +InfiniBand software stack, including kernel modules and userspace libraries. +.Pp +This is a default setting on +amd64/amd64, arm64/aarch64, i386/i386, powerpc/powerpc64, powerpc/powerpc64le and riscv/riscv64. +.It Va WITH_OFED_EXTRA +Build the non-essential components of the +.Dq "OpenFabrics Enterprise Distribution" +Infiniband software stack, mostly examples. +.It Va WITH_OPENLDAP +Enable building LDAP support for kerberos using an openldap client from ports. +.It Va WITHOUT_OPENMP +Do not build LLVM's OpenMP runtime. +.Pp +This is a default setting on +arm/armv7. +.It Va WITH_OPENMP +Build LLVM's OpenMP runtime. +.Pp +This is a default setting on +amd64/amd64, arm64/aarch64, i386/i386, powerpc/powerpc64, powerpc/powerpc64le and riscv/riscv64. +.It Va WITHOUT_OPENSSH +Do not build OpenSSH. +.It Va WITHOUT_OPENSSL +Do not build OpenSSL. +When set, it enforces these options: +.Pp +.Bl -item -compact +.It +.Va WITHOUT_DMAGENT +.It +.Va WITHOUT_KERBEROS +.It +.Va WITHOUT_LDNS +.It +.Va WITHOUT_LDNS_UTILS +.It +.Va WITHOUT_LOADER_ZFS +.It +.Va WITHOUT_MITKRB5 +.It +.Va WITHOUT_OPENSSH +.It +.Va WITHOUT_OPENSSL_KTLS +.It +.Va WITHOUT_PKGBOOTSTRAP +.It +.Va WITHOUT_UNBOUND +.It +.Va WITHOUT_ZFS +.It +.Va WITHOUT_ZFS_TESTS +.El +.Pp +When set, these options are also in effect: +.Pp +.Bl -inset -compact +.It Va WITHOUT_KERBEROS_SUPPORT +(unless +.Va WITH_KERBEROS_SUPPORT +is set explicitly) +.El +.It Va WITHOUT_OPENSSL_KTLS +Do not include kernel TLS support in OpenSSL. +.Pp +This is a default setting on +arm/armv7, i386/i386 and riscv/riscv64. +.It Va WITH_OPENSSL_KTLS +Include kernel TLS support in OpenSSL. +.Pp +This is a default setting on +amd64/amd64, arm64/aarch64, powerpc/powerpc64 and powerpc/powerpc64le. +.It Va WITHOUT_PAM +Do not build PAM library and modules. +.Bf -symbolic +This option is deprecated and does nothing. +.Ef +When set, these options are also in effect: +.Pp +.Bl -inset -compact +.It Va WITHOUT_PAM_SUPPORT +(unless +.Va WITH_PAM_SUPPORT +is set explicitly) +.El +.It Va WITHOUT_PAM_SUPPORT +Build +.Xr ppp 8 +without PAM support. +.It Va WITHOUT_PF +Do not build PF firewall package. +When set, it enforces these options: +.Pp +.Bl -item -compact +.It +.Va WITHOUT_AUTHPF +.El +.It Va WITHOUT_PIE +Do not build dynamically linked binaries as +Position-Independent Executable (PIE). +.Pp +This is a default setting on +arm/armv7 and i386/i386. +.It Va WITH_PIE +Build dynamically linked binaries as +Position-Independent Executable (PIE). +.Pp +This is a default setting on +amd64/amd64, arm64/aarch64, powerpc/powerpc64, powerpc/powerpc64le and riscv/riscv64. +.It Va WITHOUT_PKGBOOTSTRAP +Do not build +.Xr pkg 7 +bootstrap tool. +.It Va WITHOUT_PKGCONF +Do not build the pkgconf binaries nor the libpkgconf library. +.It Va WITHOUT_PKGSERVE +Do not build or install +.Xr pkg-serve 8 . +.It Va WITHOUT_PMC +Do not build +.Xr pmccontrol 8 +and related programs. +.It Va WITHOUT_PPP +Do not build +.Xr ppp 8 +and related programs. +.It Va WITHOUT_PTHREADS_ASSERTIONS +Disable debugging assertions in pthreads library. +.It Va WITHOUT_QUOTAS +Do not build +.Xr quota 1 +and related programs. +.It Va WITHOUT_RADIUS_SUPPORT +Do not build radius support into various applications, like +.Xr pam_radius 8 +and +.Xr ppp 8 . +.It Va WITH_RATELIMIT +Build the system with rate limit support. +.Pp +This makes +.Dv SO_MAX_PACING_RATE +effective in +.Xr getsockopt 2 , +and +.Ar txrlimit +support in +.Xr ifconfig 8 , +by proxy. +.It Va WITHOUT_RBOOTD +Do not build or install +.Xr rbootd 8 . +.It Va WITHOUT_RELRO +Do not apply the Relocation Read-Only (RELRO) vulnerability mitigation. +See also the +.Va BIND_NOW +option. +.It Va WITH_REPRODUCIBLE_BUILD +Exclude build metadata (such as the build time, user, or host) +from the kernel, boot loaders, and +.Xr uname 1 +output, so that builds produce +bit-for-bit identical output. +.It Va WITH_REPRODUCIBLE_PATHS +Modify the paths encoded in binary artifacts to be standard path + +Normally, the actual path is encoded in the binary. However, this makes the +build differ depending on the path it was built from. With this option enabled, +the paths recorded are /usr/src, regardless of the actual path. With this option +disabled, the actual paths are recorded. +.It Va WITHOUT_RESCUE +Do not build +.Xr rescue 8 . +.It Va WITH_RETPOLINE +Build the base system with the retpoline speculative execution +vulnerability mitigation for CVE-2017-5715. +.It Va WITHOUT_ROUTED +Do not build +.Xr routed 8 +utility. +.It Va WITH_RPCBIND_WARMSTART_SUPPORT +Build +.Xr rpcbind 8 +with warmstart support. +.It Va WITH_RUN_TESTS +Run tests as part of the build. +.It Va WITHOUT_SCTP_SUPPORT +Disable support in the kernel for the +.Xr sctp 4 +Stream Control Transmission Protocol +loadable kernel module. +.It Va WITHOUT_SENDMAIL +Do not build +.Xr sendmail 8 +and related programs. +.It Va WITHOUT_SERVICESDB +Do not install +.Pa /var/db/services.db . +.It Va WITHOUT_SETUID_LOGIN +Set this to disable the installation of +.Xr login 1 +as a set-user-ID root program. +.It Va WITHOUT_SHAREDOCS +Do not build the +.Bx 4.4 +legacy docs. +.It Va WITH_SORT_THREADS +Enable threads in +.Xr sort 1 . +.It Va WITHOUT_SOUND +Do not build userland sound utilities such as +.Xr beep 1 +and +.Xr mixer 8 . +.It Va WITHOUT_SOURCELESS +Do not build kernel modules that include sourceless code (either microcode or native code for host CPU). +When set, it enforces these options: +.Pp +.Bl -item -compact +.It +.Va WITHOUT_SOURCELESS_HOST +.It +.Va WITHOUT_SOURCELESS_UCODE +.El +.It Va WITHOUT_SOURCELESS_HOST +Do not build kernel modules that include sourceless native code for host CPU. +.It Va WITHOUT_SOURCELESS_UCODE +Do not build kernel modules that include sourceless microcode. +.It Va WITHOUT_SPLIT_KERNEL_DEBUG +Do not build standalone kernel debug files. +Debug data (if enabled by the kernel configuration file) +will be included in the kernel and modules. +When set, it enforces these options: +.Pp +.Bl -item -compact +.It +.Va WITHOUT_KERNEL_SYMBOLS +.El +.It Va WITHOUT_SSP +Do not build world with stack smashing protection. +See +.Xr mitigations 7 +for more information. +.It Va WITH_STAGING +Enable staging of files to a stage tree. +This can be best thought of as auto-install to +.Va DESTDIR +with some extra meta data to ensure dependencies can be tracked. +Depends on +.Va WITH_DIRDEPS_BUILD . +When set, these options are also in effect: +.Pp +.Bl -inset -compact +.It Va WITH_STAGING_MAN +(unless +.Va WITHOUT_STAGING_MAN +is set explicitly) +.It Va WITH_STAGING_PROG +(unless +.Va WITHOUT_STAGING_PROG +is set explicitly) +.El +.Pp +This must be set in the environment, make command line, or +.Pa /etc/src-env.conf , +not +.Pa /etc/src.conf . +.It Va WITH_STAGING_MAN +Enable staging of man pages to stage tree. +.It Va WITH_STAGING_PROG +Enable staging of PROGs to stage tree. +.It Va WITH_STALE_STAGED +Check staged files are not stale. +.It Va WITHOUT_STATS +Neither build nor install +.Lb libstats +and dependent binaries. +.It Va WITHOUT_SYSCONS +Do not build +.Xr syscons 4 +support files such as keyboard maps, fonts, and screen output maps. +.It Va WITH_SYSROOT +Enable use of sysroot during build. +Depends on +.Va WITH_DIRDEPS_BUILD . +.Pp +This must be set in the environment, make command line, or +.Pa /etc/src-env.conf , +not +.Pa /etc/src.conf . +.It Va WITHOUT_SYSTEM_COMPILER +Do not opportunistically skip building a cross-compiler during the +bootstrap phase of the build. +Normally, if the currently installed compiler matches the planned bootstrap +compiler type and revision, then it will not be built. +This does not prevent a compiler from being built for installation though, +only for building one for the build itself. +The +.Va WITHOUT_CLANG +option controls that. +.It Va WITHOUT_SYSTEM_LINKER +Do not opportunistically skip building a cross-linker during the +bootstrap phase of the build. +Normally, if the currently installed linker matches the planned bootstrap +linker type and revision, then it will not be built. +This does not prevent a linker from being built for installation though, +only for building one for the build itself. +The +.Va WITHOUT_LLD +option controls that. +.Pp +This option is only relevant when +.Va WITH_LLD_BOOTSTRAP +is set. +.It Va WITHOUT_TALK +Do not build or install +.Xr talk 1 +and +.Xr talkd 8 . +.It Va WITHOUT_TCP_WRAPPERS +Do not build or install +.Xr tcpd 8 , +and related utilities. +.It Va WITHOUT_TCSH +Do not build and install +.Pa /bin/csh +(which is +.Xr tcsh 1 ) . +.It Va WITHOUT_TELNET +Do not build +.Xr telnet 1 +and related programs. +.It Va WITHOUT_TESTS +Do not build nor install the +.Fx +Test Suite in +.Pa /usr/tests/ . +See +.Xr tests 7 +for more details. +This also disables the build of all test-related dependencies, including ATF. +When set, it enforces these options: +.Pp +.Bl -item -compact +.It +.Va WITHOUT_DTRACE_TESTS +.It +.Va WITHOUT_ZFS_TESTS +.El +.Pp +When set, these options are also in effect: +.Pp +.Bl -inset -compact +.It Va WITHOUT_GOOGLETEST +(unless +.Va WITH_GOOGLETEST +is set explicitly) +.It Va WITHOUT_TESTS_SUPPORT +(unless +.Va WITH_TESTS_SUPPORT +is set explicitly) +.El +.It Va WITHOUT_TESTS_SUPPORT +Disable the build of all test-related dependencies, including ATF. +When set, it enforces these options: +.Pp +.Bl -item -compact +.It +.Va WITHOUT_GOOGLETEST +.El +.It Va WITHOUT_TEXTPROC +Do not build +programs used for text processing. +.It Va WITHOUT_TFTP +Do not build or install +.Xr tftp 1 +and +.Xr tftpd 8 . +.It Va WITHOUT_TOOLCHAIN +Do not install +programs used for program development, +compilers, debuggers etc. +When set, it enforces these options: +.Pp +.Bl -item -compact +.It +.Va WITHOUT_CLANG +.It +.Va WITHOUT_CLANG_EXTRAS +.It +.Va WITHOUT_CLANG_FORMAT +.It +.Va WITHOUT_CLANG_FULL +.It +.Va WITHOUT_LLD +.It +.Va WITHOUT_LLDB +.It +.Va WITHOUT_LLVM_COV +.El +.Pp +When set, these options are also in effect: +.Pp +.Bl -inset -compact +.It Va WITHOUT_LLVM_BINUTILS +(unless +.Va WITH_LLVM_BINUTILS +is set explicitly) +.El +.It Va WITH_UBSAN +Build the base system with Undefined Behavior Sanitizer (UBSan) to detect +various kinds of undefined behavior at runtime. +Requires that Clang be used as the base system compiler +and that the runtime support library is available +.It Va WITHOUT_UNBOUND +Do not build +.Xr unbound 8 +and related programs. +.It Va WITH_UNDEFINED_VERSION +Link libraries with --undefined-version which permits version maps to +contain symbols that are not present in the library. +If this is necessary to build a particular configuration, a bug is +present and the configuration should be reported. +.It Va WITHOUT_UNIFIED_OBJDIR +Use the historical object directory format for +.Xr build 7 +targets. +For native-builds and builds done directly in sub-directories the format of +.Pa ${MAKEOBJDIRPREFIX}/${.CURDIR} +is used, +while for cross-builds +.Pa ${MAKEOBJDIRPREFIX}/${TARGET}.${TARGET_ARCH}/${.CURDIR} +is used. +.Pp +This option is transitional and will be removed in a future version of +.Fx , +at which time +.Va WITH_UNIFIED_OBJDIR +will be enabled permanently. +.Pp +This must be set in the environment, make command line, or +.Pa /etc/src-env.conf , +not +.Pa /etc/src.conf . +.It Va WITHOUT_USB +Do not build USB-related programs and libraries. +When set, it enforces these options: +.Pp +.Bl -item -compact +.It +.Va WITHOUT_USB_GADGET_EXAMPLES +.El +.It Va WITHOUT_USB_GADGET_EXAMPLES +Do not build USB gadget kernel modules. +.It Va WITHOUT_UTMPX +Do not build user accounting tools such as +.Xr last 1 , +.Xr users 1 , +.Xr who 1 , +.Xr ac 8 , +.Xr lastlogin 8 +and +.Xr utx 8 . +.It Va WITH_VERIEXEC +Enable building +.Xr veriexec 8 +which loads the contents of verified manifests into the kernel +for use by +.Xr mac_veriexec 4 +.Pp +Depends on +.Va WITH_BEARSSL . +.It Va WITHOUT_VI +Do not build and install vi, view, ex and related programs. +.It Va WITHOUT_VT +Do not build +.Xr vt 4 +support files (fonts and keymaps). +.It Va WITHOUT_WARNS +Set this to not add warning flags to the compiler invocations. +Useful as a temporary workaround when code enters the tree +which triggers warnings in environments that differ from the +original developer. +.It Va WITHOUT_WERROR +Set this to not treat compiler warnings as errors. +Useful as a temporary workaround when working on fixing compiler warnings. +When set, warnings are still printed in the build log but do not fail the build. +.It Va WITHOUT_WIRELESS +Do not build programs used for 802.11 wireless networks; especially +.Xr wpa_supplicant 8 +and +.Xr hostapd 8 . +When set, these options are also in effect: +.Pp +.Bl -inset -compact +.It Va WITHOUT_WIRELESS_SUPPORT +(unless +.Va WITH_WIRELESS_SUPPORT +is set explicitly) +.El +.It Va WITHOUT_WIRELESS_SUPPORT +Build libraries, programs, and kernel modules without +802.11 wireless support. +.It Va WITHOUT_WPA_SUPPLICANT_EAPOL +Build +.Xr wpa_supplicant 8 +without support for the IEEE 802.1X protocol and without +support for EAP-PEAP, EAP-TLS, EAP-LEAP, and EAP-TTLS +protocols (usable only via 802.1X). +.It Va WITH_ZEROREGS +Build the basesystem with code to zero caller-used register contents +on function return. +This prevents leaking temporary values for side channel attacks. +Additionally this reduces the number of usable ROP gadgets for attackers. +.It Va WITHOUT_ZFS +Do not build the ZFS file system kernel module, libraries such as +.Xr libbe 3 , +and user commands such as +.Xr zpool 8 +or +.Xr zfs 8 . +Also disable ZFS support in utilities and libraries which implement +ZFS-specific functionality. +When set, it enforces these options: +.Pp +.Bl -item -compact +.It +.Va WITHOUT_ZFS_TESTS +.El +.It Va WITHOUT_ZFS_TESTS +Do not build and install the legacy ZFS test suite. +.It Va WITHOUT_ZONEINFO +Do not build the timezone database. +When set, it enforces these options: +.Pp +.Bl -item -compact +.It +.Va WITHOUT_ZONEINFO_LEAPSECONDS_SUPPORT +.El +.It Va WITH_ZONEINFO_LEAPSECONDS_SUPPORT +Build leapsecond information in to the timezone database. +This option violates +.St -p1003.1 +and all other applicable standards, and is known to cause unexpected +issues with date/time handling in many applications and programming +languages. +.El +.Pp +The following options accept a single value from a list of valid values. +.Bl -tag -width indent +.It Va INIT_ALL +Control default initialization of stack variables in C and C++ code. +Options other than +.Li none +require the Clang compiler or GCC 12.0 or later. +The default value is +.Li none . +Valid values are: +.Bl -tag -width indent +.It Li none +Do not initialize stack variables (standard C/C++ behavior). +.It Li pattern +Build the base system or kernel with stack variables initialized to +.Pq compiler defined +debugging patterns on function entry. +.It Li zero +Build the base system or kernel with stack variables initialized +to zero on function entry. +This value is converted to +.Li none +for amd64 kernel builds due to incompatibility with ifunc memset. +.El +.It Va LIBC_MALLOC +Specify the +.Xr malloc 3 +implementation used by libc. +The default value is +.Li jemalloc . +Valid values are: +.Bl -tag -width indent +.It Li jemalloc +.El +.Pp +Other implementations are expected in the future in both +.Fx +and downstream consumers. +.El +.Sh FILES +.Bl -tag -compact -width Pa +.It Pa /etc/src.conf +.It Pa /etc/src-env.conf +.It Pa /usr/share/mk/bsd.own.mk +.El +.Sh SEE ALSO +.Xr make 1 , +.Xr make.conf 5 , +.Xr build 7 , +.Xr ports 7 +.Sh HISTORY +The +.Nm +file appeared in +.Fx 7.0 . +.Sh AUTHORS +This manual page was autogenerated by +.An tools/build/options/makeman . diff --git a/static/freebsd/man5/stab.5 b/static/freebsd/man5/stab.5 new file mode 100644 index 00000000..3070c576 --- /dev/null +++ b/static/freebsd/man5/stab.5 @@ -0,0 +1,214 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 June 10, 2010 +.Dt STAB 5 +.Os +.Sh NAME +.Nm stab +.Nd symbol table types +.Sh SYNOPSIS +.In stab.h +.Sh DESCRIPTION +The file +.In stab.h +defines some of the symbol table +.Fa n_type +field values for a.out files. +These are the types for permanent symbols (i.e., not local labels, etc.\&) +used by the old debugger +.Em sdb +and the Berkeley Pascal compiler +.Xr pc 1 . +Symbol table entries can be produced by the +.Pa .stabs +assembler directive. +This allows one to specify a double-quote delimited name, a symbol type, +one char and one short of information about the symbol, and an unsigned +long (usually an address). +To avoid having to produce an explicit label for the address field, +the +.Pa .stabd +directive can be used to implicitly address the current location. +If no name is needed, symbol table entries can be generated using the +.Pa .stabn +directive. +The loader promises to preserve the order of symbol table entries produced +by +.Pa .stab +directives. +As described in +.Xr a.out 5 , +an element of the symbol table +consists of the following structure: +.Bd -literal +/* +* Format of a symbol table entry. +*/ + +struct nlist { + union { + const char *n_name; /* for use when in-core */ + long n_strx; /* index into file string table */ + } n_un; + unsigned char n_type; /* type flag */ + char n_other; /* unused */ + short n_desc; /* see struct desc, below */ + unsigned n_value; /* address or offset or line */ +}; +.Ed +.Pp +The low bits of the +.Fa n_type +field are used to place a symbol into +at most one segment, according to +the following masks, defined in +.In a.out.h . +A symbol can be in none of these segments by having none of these segment +bits set. +.Bd -literal +/* +* Simple values for n_type. +*/ + +#define N_UNDF 0x0 /* undefined */ +#define N_ABS 0x2 /* absolute */ +#define N_TEXT 0x4 /* text */ +#define N_DATA 0x6 /* data */ +#define N_BSS 0x8 /* bss */ + +#define N_EXT 01 /* external bit, or'ed in */ +.Ed +.Pp +The +.Fa n_value +field of a symbol is relocated by the linker, +.Xr ld 1 +as an address within the appropriate segment. +.Fa N_value +fields of symbols not in any segment are unchanged by the linker. +In addition, the linker will discard certain symbols, according to rules +of its own, unless the +.Fa n_type +field has one of the following bits set: +.Bd -literal +/* +* Other permanent symbol table entries have some of the N_STAB bits set. +* These are given in +*/ + +#define N_STAB 0xe0 /* if any of these bits set, don't discard */ +.Ed +.Pp +This allows up to 112 (7 \(** 16) symbol types, split between the various +segments. +Some of these have already been claimed. +The old symbolic debugger, +.Em sdb , +uses the following n_type values: +.Bd -literal +#define N_GSYM 0x20 /* global symbol: name,,0,type,0 */ +#define N_FNAME 0x22 /* procedure name (f77 kludge): name,,0 */ +#define N_FUN 0x24 /* procedure: name,,0,linenumber,address */ +#define N_STSYM 0x26 /* static symbol: name,,0,type,address */ +#define N_LCSYM 0x28 /* .lcomm symbol: name,,0,type,address */ +#define N_RSYM 0x40 /* register sym: name,,0,type,register */ +#define N_SLINE 0x44 /* src line: 0,,0,linenumber,address */ +#define N_SSYM 0x60 /* structure elt: name,,0,type,struct_offset */ +#define N_SO 0x64 /* source file name: name,,0,0,address */ +#define N_LSYM 0x80 /* local sym: name,,0,type,offset */ +#define N_SOL 0x84 /* #included file name: name,,0,0,address */ +#define N_PSYM 0xa0 /* parameter: name,,0,type,offset */ +#define N_ENTRY 0xa4 /* alternate entry: name,linenumber,address */ +#define N_LBRAC 0xc0 /* left bracket: 0,,0,nesting level,address */ +#define N_RBRAC 0xe0 /* right bracket: 0,,0,nesting level,address */ +#define N_BCOMM 0xe2 /* begin common: name,, */ +#define N_ECOMM 0xe4 /* end common: name,, */ +#define N_ECOML 0xe8 /* end common (local name): ,,address */ +#define N_LENG 0xfe /* second stab entry with length information */ +.Ed +.Pp +where the comments give +.Em sdb +conventional use for +.Pa .stab +.Fa s +and the +.Fa n_name , +.Fa n_other , +.Fa n_desc , +and +.Fa n_value +fields +of the given +.Fa n_type . +.Em Sdb +uses the +.Fa n_desc +field to hold a type specifier in the form used +by the Portable C Compiler, +.Xr cc 1 ; +see the header file +.Pa pcc.h +for details on the format of these type values. +.Pp +The Berkeley Pascal compiler, +.Xr pc 1 , +uses the following +.Fa n_type +value: +.Bd -literal +#define N_PC 0x30 /* global pascal symbol: name,,0,subtype,line */ +.Ed +.Pp +and uses the following subtypes to do type checking across separately +compiled files: +.Bd -unfilled -offset indent +1 source file name +2 included file name +3 global label +4 global constant +5 global type +6 global variable +7 global function +8 global procedure +9 external function +10 external procedure +11 library variable +12 library routine +.Ed +.Sh SEE ALSO +.Xr as 1 , +.Xr ld 1 , +.Xr a.out 5 +.Sh HISTORY +The +.Nm +file appeared in +.Bx 4.0 . +.Sh BUGS +More basic types are needed. diff --git a/static/freebsd/man5/style.Makefile.5 b/static/freebsd/man5/style.Makefile.5 new file mode 100644 index 00000000..9a2f1b06 --- /dev/null +++ b/static/freebsd/man5/style.Makefile.5 @@ -0,0 +1,288 @@ +.\" +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" Copyright (c) 2002-2003, 2023, 2025 David O'Brien +.\" 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. Neither the name of the author nor the names of any contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" 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 DAVID O'BRIEN 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 October 29, 2025 +.Dt STYLE.MAKEFILE 5 +.Os +.Sh NAME +.Nm style.Makefile +.Nd FreeBSD Makefile style guide +.Sh DESCRIPTION +This file specifies the preferred style for makefiles in the +.Fx +source tree. +.Bl -bullet +.It +.Cm .PATH : +comes first if needed, and is spelled +.Dq Li ".PATH: " , +with a single +.Tn ASCII +space after a colon. +Do not use the +.Va VPATH +variable. +.It +Special variables (i.e., +.Va LIB , SRCS , MLINKS , +etc.) are listed in order of +.Dq product , +then building and installing a binary. +Special variables may also be listed in +.Dq build +order: i.e., ones for the primary program (or library) first. +The general +.Dq product +order is: +.Va PROG Ns / Ns Oo Va SH Oc Ns Va LIB Ns / Ns Va SCRIPTS +.Va FILES +.Va LINKS +.Va MAN +.Va MLINKS +.Va INCS +.Va SRCS +.Va WARNS +.Va CSTD +.Va CFLAGS +.Va DPADD +.Va LDADD . +The general +.Dq build +order is: +.Va PROG Ns / Ns Oo Va SH Oc Ns Va LIB Ns / Ns Va SCRIPTS +.Va SRCS +.Va WARNS +.Va CSTD +.Va CFLAGS +.Va DPADD +.Va LDADD +.Va INCS +.Va FILES +.Va LINKS +.Va MAN +.Va MLINKS . +.It +Omit +.Va SRCS +when using +.In bsd.prog.mk +and there is a single source file named the same as the +.Va PROG . +.It +Omit +.Va MAN +when using +.In bsd.prog.mk +and the manual page is named the same as the +.Va PROG , +and is in section 1. +.It +All variable assignments are spelled +.Dq Va VAR Ns Ic = , +i.e., no space between the variable name and the +.Ic = . +Keep values sorted alphabetically, if possible. +.It +Variables are expanded with +.Sy {} , +not +.Sy () . +Such as +.Va ${VARIABLE} . +.It +Do not use +.Ic += +to set variables that are only set once +(or to set variables for the first time). +.It +Do not use vertical whitespace in simple makefiles, +but do use it to group locally related things in more complex/longer ones. +.It +.Va WARNS +comes before +.Va CFLAGS , +as it is basically a +.Va CFLAGS +modifier. +It comes before +.Va CFLAGS +rather than after +.Va CFLAGS +so it does not get lost in a sea of +.Va CFLAGS +statements as +.Va WARNS +is an important thing. +The usage of +.Va WARNS +is spelled +.Dq Li "WARNS?= " , +so that it may be overridden on the command line or in +.Xr make.conf 5 . +.It +.Dq Li "MK_WERROR=no" +should not be used, +it defeats the purpose of +.Va WARNS . +It should only be used on the command line and in special circumstances. +.It +.Va CFLAGS +is spelled +.Dq Li "CFLAGS+= " . +.It +Listing +.Fl D Ns 's +before +.Fl I Ns 's +in +.Va CFLAGS +is preferred for alphabetical ordering and to make +.Fl D Ns 's +easier to see. +The +.Fl D Ns 's +often affect conditional compilation, +and +.Fl I Ns 's +tend to be quite long. +Split long +.Va CFLAGS +settings between the +.Fl D Ns 's +and +.Fl I Ns 's. +.It +Lists that span more than one line should be formatted as follows: +.Bd -literal -offset indent +SRCS+=\\ +main.c\\ +trace.c\\ +zoo.c \\ +\& +.Ed +Specifically, the last item in the list should have a trailing '\\'. +This is to avoid causing a "false diff" or "false blame" when +a new item is appended at the end. +In general the list should be English language alphabetized. +A list of libraries or header inclusion paths are notable exceptions +if needed for proper building. +.It +Do not use GCCisms (such as +.Fl g +and +.Fl Wall ) +in +.Va CFLAGS . +.It +Typically, there is one +.Tn ASCII +tab between +.Va VAR Ns Ic = +and the value in order to start the value in column 9. +An +.Tn ASCII +space is allowed for variable names that extend beyond column 9. +A lack of whitespace is also allowed for very long variable names. +.It +.Ic .include In bsd.*.mk +goes last. +.It +Do not use anachronisms like +.Va $< +and +.Va $@ . +Instead use +.Va ${.IMPSRC} +or +.Va ${.ALLSRC} +and +.Va ${.TARGET} . +.It +To not build the +.Dq foo +part of the base system, +use +.Va NO_FOO , +not +.Va NOFOO . +.It +To optionally build something in the base system, +spell the knob +.Va WITH_FOO +not +.Va WANT_FOO +or +.Va USE_FOO . +The latter are reserved for the +.Fx +Ports Collection. +.It +For variables that are only checked with +.Fn defined , +do not provide any fake value. +.El +.Sh EXAMPLES +The simplest program +.Pa Makefile +is: +.Bd -literal -offset indent +PROG= foo + +\&.include +.Ed +.Pp +The simplest library +.Pa Makefile +is: +.Bd -literal -offset indent +LIB= foo +SHLIB_MAJOR= 1 +MAN= libfoo.3 +SRCS= foo.c + +\&.include +.Ed +.Sh SEE ALSO +.Xr make 1 , +.Xr make.conf 5 , +.Xr style 9 +.Sh HISTORY +This manual page is inspired from the +.Xr style 9 +manual page and first appeared in +.Fx 5.1 . +.Sh AUTHORS +.An David O'Brien Aq deo@NUXI.org +.Sh BUGS +There are few hard and fast style rules here. +The desire to express a logical grouping sometimes means not obeying some of the +above. +The style of many things is too dependent on the context of the whole makefile, +or the lines surrounding it. diff --git a/static/freebsd/man5/style.mdoc.5 b/static/freebsd/man5/style.mdoc.5 new file mode 100644 index 00000000..64e2291d --- /dev/null +++ b/static/freebsd/man5/style.mdoc.5 @@ -0,0 +1,229 @@ +.\" +.\" Copyright (c) 2018-2025 Mateusz Piotrowski <0mp@FreeBSD.org> +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd February 16, 2025 +.Dt STYLE.MDOC 5 +.Os +.Sh NAME +.Nm style.mdoc +.Nd FreeBSD manual page style guide +.Sh DESCRIPTION +This file specifies the preferred style for manual pages in the +.Fx +source tree. +.Ss Code Examples +.Bl -dash -width "" +.It +Use literal formatting for examples and literal shell commands, e.g.: +.Bd -literal -offset indent +Then run +\&.Ql make install clean . +.Ed +.Pp +which renders as: +.Bd -filled -offset indent +Then run +.Ql make install clean . +.Ed +.Pp +The incorrect way would be to use macros like +.Sy \&Nm +to stylize the command invocation: +.Bd -literal -offset indent +Then run +\&.Ql Nm make Cm install Cm clean . +.Ed +.Pp +which renders as: +.Bd -filled -offset indent +Then run +.Ql Nm make Cm install Cm clean . +.Ed +.El +.Ss Copyright Header +Refer to +.Xr style 9 . +.Ss HARDWARE Section +Driver manuals in section four should have a +.Sx HARDWARE +section describing hardware known to work with the driver. +This section is drawn verbatim into the Release Hardware Notes, +therefore there are several things to note: +.Bl -dash -width "" +.It +The introductory sentence should be in the form: +.Bd -literal -offset indent +The +\&.Nm +driver supports the following $device_class: +.Ed +.Pp +Followed by the list of supported hardware. +.Pp +This defines what driver the subsection is referring to, +and allows the reader to search through the Hardware Notes +not only for the device models they have, +but also for the device type they are looking to acquire. +.It +The supported hardware should be listed as a bullet list, +or if complexity requires, a column list. +These two list types create very neat subsections +with clean starting and stopping points. +.El +.Ss EXAMPLES Section +.Bl -dash -width "" +.It +Format the +.Sx EXAMPLES +section in the following way: +.Bd -literal -offset indent +\&.Bl -tag -width 0n +\&.It Sy Example 1\\&: Doing Something +\&.Pp +The following command does something. +\&.Bd -literal -offset 2n +\&.Ic # make -VLEGAL +\&.Ed +\&.It Sy Example 2\\&: Doing Something Different +\&.Pp +The following command does something different. +\&.Bd -literal -offset 2n +\&.Ic # bectl list +\&.Ed +\&.Pp +It is good to know this command. +\&.El +.Ed +.Pp +which renders as: +.Bl -tag -width 0n +.It Sy Example 1\&: Doing Something +.Pp +The following command does something. +.Bd -literal -offset 2n +.Ic # make -VLEGAL +.Ed +.It Sy Example 2\&: Doing Something Different +.Pp +The following command does something different. +.Bd -literal -offset 2n +.Ic # bectl list +.Ed +.Pp +It is good to know this command. +.El +.El +.Ss Lists +.Bl -dash -width "" +.It +The +.Fl width +argument to the +.Sy \&.Bl +macro should match the length of the longest rendered item in the list, +e.g.: +.Bd -literal -offset indent +\&.Bl -tag -width "-a address" +\&.It Fl a Ar address +Set the address. +\&.It Fl v +Print the version. +\&.El +.Ed +.Pp +In case the longest item is too long and hurts readability, +the recommendation is to set +the +.Fl width +argument +to +.Ql indent , +e.g.: +.Bd -literal -offset indent +\&.Bl -tag -width "indent" +\&.It Cm build +Build the port. +\&.It Cm install +Install the port. +\&.It Fl install-missing-packages +Install the missing packages. +\&.El +.Ed +.El +.Ss Quoting +.Bl -dash -width "" +.It +Use the +.Sy \&Dq +.Pq Do Dc +macro +for quoting. +Use the +.Sy \&Sq +.Pq So Sc +macro for quoting inside quotes. +The use of the +.Sy \&Qq +.Pq Qo Qc +macro is usually not necessary. +.El +.Ss Variables +.Bl -dash -width "" +.It +Use +.Sy \&Va +instead of +.Sy \&Dv +for +.Xr sysctl 8 +variables like +.Va kdb.enter.panic . +.It +Use the angle brackets +.Sy \&Aq +.Pq Dq Ao Ac +macro +for arguments +.Pq Sy \&Ar +when they are mixed with similarly stylized macros like +.Sy \&Pa +or +.Sy \&Va , +e.g.: +.Bd -literal -offset indent +\&.Va critical_filesystems_ Ns Aq Ar type +.Ed +.Pp +which renders as: +.Bd -filled -offset indent +.Va critical_filesystems_ Ns Aq Ar type +.Ed +.Pp +instead of: +.Bd -literal -offset indent +\&.Va critical_filesystems_ Ns Ar type +.Ed +.Pp +that would be rendered as: +.Bd -filled -offset indent +.Va critical_filesystems_ Ns Ar type +.Ed +.El +.Sh FILES +.Bl -tag -width "/usr/share/examples/mdoc/tab" +.It /usr/share/examples/mdoc/ +Examples for writing manual pages. +.El +.Sh SEE ALSO +.Xr man 1 , +.Xr mandoc 1 , +.Xr mdoc 7 , +.Xr roff 7 , +.Xr style 9 +.Sh HISTORY +This manual page first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org diff --git a/static/freebsd/man5/sysctl.conf.5 b/static/freebsd/man5/sysctl.conf.5 new file mode 100644 index 00000000..cff14172 --- /dev/null +++ b/static/freebsd/man5/sysctl.conf.5 @@ -0,0 +1,106 @@ +.\" Copyright (c) 1999 Chris Costello +.\" 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 June 30, 2022 +.Dt SYSCTL.CONF 5 +.Os +.Sh NAME +.Nm sysctl.conf +.Nd kernel state defaults +.Sh DESCRIPTION +The +.Pa /etc/sysctl.conf +file is read in when the system goes into multi-user mode to set default +settings for the kernel. +The +.Pa /etc/sysctl.conf +file is in the format of the +.Xr sysctl 8 +command, i.e., +.Bd -literal -offset indent +sysctl_mib=value +.Ed +.Pp +Comments are denoted by a +.Dq # +at the beginning of a line. +Comments can also exist at the end of a line, +as seen in the +.Sx EXAMPLES +section, below. +.Pp +For kernel modules loaded via +.Xr rc.subr 8 +system, +additional module-specific settings can be applied +by adding a file in the same format named +.Pf /etc/sysctl.kld.d/.conf . +.Sh FILES +.Bl -tag -width /etc/rc.d/sysctl_lastload -compact +.It Pa /etc/rc.d/sysctl +.Xr rc 8 +script which processes +.Nm +early on in the process of transitioning to multi-user mode. +.It Pa /etc/rc.d/sysctl_lastload +.Xr rc 8 +script which processes +.Nm +shortly before the system reaches the multi-user mode. +.It Pa /etc/sysctl.conf +Initial settings for +.Xr sysctl 8 . +.It Pa /etc/sysctl.conf.local +Machine-specific settings for sites with a common +.Pa /etc/sysctl.conf . +.It Pa /etc/sysctl.kld.d +Module specific settings for kernel modules loaded via +.Xr rc.subr 8 . +.El +.Sh EXAMPLES +To turn off logging of programs that exit due to fatal signals you may use +a configuration like +.Bd -literal -offset indent +# Configure logging. +kern.logsigexit=0 # Do not log fatal signal exits (e.g., sig 11) +.Ed +.Sh SEE ALSO +.Xr rc.conf 5 , +.Xr rc 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Nm +file appeared in +.Fx 4.0 . +.Sh BUGS +If loadable kernel modules are used to introduce additional kernel +functionality and sysctls to manage that functionality, +.Nm +may be processed too early in the boot process to set those sysctls. +Please consult +.Xr rcorder 8 +to learn more about the ordering of +.Xr rc 8 +scripts. diff --git a/static/freebsd/man6/Makefile b/static/freebsd/man6/Makefile new file mode 100644 index 00000000..cd649fe8 --- /dev/null +++ b/static/freebsd/man6/Makefile @@ -0,0 +1,3 @@ +MAN = $(wildcard *.6) + +include ../../mandoc.mk diff --git a/static/freebsd/man6/intro.6 b/static/freebsd/man6/intro.6 new file mode 100644 index 00000000..2cd184f9 --- /dev/null +++ b/static/freebsd/man6/intro.6 @@ -0,0 +1,66 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 November 27, 2017 +.Dt INTRO 6 +.Os +.Sh NAME +.Nm intro +.Nd "introduction to games" +.Sh DESCRIPTION +This section contains information about the traditional BSD games. +The games +are located in +.Pa /usr/bin +if installed. +.Sh FILES +.Bl -tag -width /usr/bin -compact +.It Pa /usr/bin +location of games +.El +.Sh SEE ALSO +.Xr intro 1 , +.Xr banner 6 , +.Xr caesar 6 , +.Xr fortune 6 , +.Xr grdc 6 , +.Xr morse 6 , +.Xr number 6 , +.Xr pom 6 , +.Xr random 6 +.Sh HISTORY +In earlier versions of +.Fx , +games were located in +.Pa /usr/games . +.Pp +The +.Nm +section manual page appeared in +.Fx 2.2 . +Most of the games were moved into the bsdgames port in +.Fx 5.0 . diff --git a/static/freebsd/man7/Makefile b/static/freebsd/man7/Makefile new file mode 100644 index 00000000..57ec7ecb --- /dev/null +++ b/static/freebsd/man7/Makefile @@ -0,0 +1,3 @@ +MAN = $(wildcard *.7) + +include ../../mandoc.mk diff --git a/static/freebsd/man7/arch.7 b/static/freebsd/man7/arch.7 new file mode 100644 index 00000000..628d3837 --- /dev/null +++ b/static/freebsd/man7/arch.7 @@ -0,0 +1,563 @@ +.\" Copyright (c) 2016-2017 The FreeBSD Foundation. +.\" +.\" This documentation was created by Ed Maste under sponsorship of +.\" The FreeBSD Foundation. +.\" +.\" 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 COPYRIGHT HOLDERS ``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 COPYRIGHT HOLDERS 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 November 27, 2025 +.Dt ARCH 7 +.Os +.Sh NAME +.Nm arch +.Nd Architecture-specific details +.Sh DESCRIPTION +Differences between CPU architectures and platforms supported by +.Fx . +.Ss Introduction +This document is a quick reference of key ABI details of +.Fx +architecture ports. +For full details consult the processor-specific ABI supplement +documentation. +.Pp +If not explicitly mentioned, sizes are in bytes. +The architecture details in this document apply to +.Fx 13.0 +and later, unless otherwise noted. +.Pp +.Fx +uses a flat address space. +Variables of types +.Vt unsigned long , +.Vt ptraddr_t , +and +.Vt size_t +have the same representation. +.Pp +In order to maximize compatibility with future pointer integrity mechanisms, +manipulations of pointers as integers should be performed via +.Vt uintptr_t +or +.Vt intptr_t +and no other types as these types are the only integer types where the +C standard guarantees that a pointer may be cast to it and then cast back +to the original type. +On CHERI systems, +.Vt uintptr_t +and +.Vt intptr_t +are defined as +.Vt __uintcap_t +and +.Vt __intcap_t +which represent capabilities that can be manipulated by integer operations. +Pointers should not be cast to +.Vt long , +.Vt ptrdiff_t , +or +.Vt size_t +if they will later be cast back to a pointer that is expected to be +dereferenceable as they remain bare integer types on all architectures. +.Pp +On some architectures, e.g., +AIM variants of +.Dv powerpc64 , +the kernel uses a separate address space. +On other architectures, kernel and a user mode process share a +single address space. +The kernel is located at the highest addresses. +.Pp +On each architecture, the main user mode thread's stack starts near +the highest user address and grows down. +.Pp +.Fx +architecture support varies by release. +This table shows currently supported CPU architectures along with the first +.Fx +release to support each architecture. +.Bl -column -offset indent "Architecture" "Initial Release" +.It Sy Architecture Ta Sy Initial Release +.It aarch64 Ta 11.0 +.It aarch64c Ta 16.0 (planned) +.It amd64 Ta 5.1 +.It armv7 Ta 12.0 +.It powerpc64 Ta 9.0 +.It powerpc64le Ta 13.0 +.It riscv64 Ta 12.0 +.It riscv64c Ta 16.0 (planned) +.El +.Pp +Discontinued architectures are shown in the following table. +.Bl -column -offset indent "Architecture" "Initial Release" "Final Release" +.It Sy Architecture Ta Sy Initial Release Ta Sy Final Release +.It alpha Ta 3.2 Ta 6.4 +.It arm Ta 6.0 Ta 12.4 +.It armeb Ta 8.0 Ta 11.4 +.It armv6 Ta 10.0 Ta 14.x +.It ia64 Ta 5.0 Ta 10.4 +.It i386 Ta 1.0 Ta 14.x +.It mips Ta 8.0 Ta 13.5 +.It mipsel Ta 9.0 Ta 13.5 +.It mipselhf Ta 12.0 Ta 13.5 +.It mipshf Ta 12.0 Ta 13.5 +.It mipsn32 Ta 9.0 Ta 13.5 +.It mips64 Ta 9.0 Ta 13.5 +.It mips64el Ta 9.0 Ta 13.5 +.It mips64elhf Ta 12.0 Ta 13.5 +.It mips64hf Ta 12.0 Ta 13.5 +.It pc98 Ta 2.2 Ta 11.4 +.It powerpc Ta 6.0 Ta 14.x +.It powerpcspe Ta 12.0 Ta 14.x +.It riscv64sf Ta 12.0 Ta 13.5 +.It sparc64 Ta 5.0 Ta 12.4 +.El +.Ss Type sizes +All +.Fx +architectures use some variant of the ELF (see +.Xr elf 5 ) +.Sy Application Binary Interface +(ABI) for the machine processor. +Supported ABIs can be divided into three main groups: +.Bl -tag -width "Dv L64PC128" +.It Dv ILP32 +.Vt int , +.Vt intptr_t , +.Vt long , +and +.Vt void * +types machine representations all have 4-byte size. +.It Dv LP64 +.Vt int +type machine representation uses 4 bytes, +while +.Vt intptr_t , +.Vt long , +and +.Vt void * +are 8 bytes. +.It Dv L64PC128 +.Vt int +type machine representation uses 4 bytes. +.Vt long +type machine representation uses 8 bytes. +.Vt intptr_t +and +.Vt void * +are 16 byte capabilities. +.El +.Pp +Some machines support more than one +.Fx +ABI. +Typically these are 64-bit machines, where the +.Dq native +.Dv LP64 +execution environment is accompanied by the +.Dq legacy +.Dv ILP32 +environment, which was the historical 32-bit predecessor for 64-bit evolution. +Examples are: +.Bl -column -offset indent "powerpc64" "ILP32 counterpart" +.It Sy LP64 Ta Sy ILP32 counterpart +.It Dv amd64 Ta Dv i386 +.It Dv powerpc64 Ta Dv powerpc +.It Dv aarch64 Ta Dv armv7 +.El +.Pp +.Dv aarch64 +will support execution of +.Dv armv7 +binaries if the CPU implements +.Dv AArch32 +execution state. +Binaries targeting +.Dv armv6 +and earlier are no longer supported by +.Fx . +.Pp +Architectures with 128-bit capabilities support both a +.Dq native +.Dv L64PC128 +execution environment and a +.Dv LP64 +environment: +.Bl -column -offset indent "aarch64c" "LP64 counterpart" +.It Sy L64PC128 Ta Sy LP64 counterpart +.It Dv aarch64c Ta Dv aarch64 +.It Dv riscv64c Ta Dv riscv64 +.El +.Pp +On all supported architectures: +.Bl -column -offset indent "long long" "Size" +.It Sy Type Ta Sy Size +.It short Ta 2 +.It int Ta 4 +.It long long Ta 8 +.It float Ta 4 +.It double Ta 8 +.El +.Pp +Integers are represented in two's complement. +Alignment of integer and pointer types is natural, that is, +the address of the variable must be congruent to zero modulo the type size. +The sole exception is that +.Dv i386 +requires only 4-byte alignment for 64-bit integers. +.Pp +Machine-dependent type sizes: +.Bl -column -offset indent "Architecture" "long" "void *" "long double" "time_t" +.It Sy Architecture Ta Sy long Ta Sy void * Ta Sy long double Ta Sy time_t +.It aarch64 Ta 8 Ta 8 Ta 16 Ta 8 +.It aarch64c Ta 8 Ta 16 Ta 16 Ta 8 +.It amd64 Ta 8 Ta 8 Ta 16 Ta 8 +.It armv7 Ta 4 Ta 4 Ta 8 Ta 8 +.It i386 Ta 4 Ta 4 Ta 12 Ta 4 +.It powerpc Ta 4 Ta 4 Ta 8 Ta 8 +.It powerpcspe Ta 4 Ta 4 Ta 8 Ta 8 +.It powerpc64 Ta 8 Ta 8 Ta 8 Ta 8 +.It powerpc64le Ta 8 Ta 8 Ta 8 Ta 8 +.It riscv64 Ta 8 Ta 8 Ta 16 Ta 8 +.It riscv64c Ta 8 Ta 16 Ta 16 Ta 8 +.El +.Pp +.Sy time_t +is 8 bytes on all supported architectures except i386. +.Ss Endianness and Char Signedness +.Bl -column -offset indent "Architecture" "Endianness" "char Signedness" +.It Sy Architecture Ta Sy Endianness Ta Sy char Signedness +.It aarch64 Ta little Ta unsigned +.It aarch64c Ta little Ta unsigned +.It amd64 Ta little Ta signed +.It armv7 Ta little Ta unsigned +.It i386 Ta little Ta signed +.It powerpc Ta big Ta unsigned +.It powerpcspe Ta big Ta unsigned +.It powerpc64 Ta big Ta unsigned +.It powerpc64le Ta little Ta unsigned +.It riscv64 Ta little Ta signed +.It riscv64c Ta little Ta signed +.El +.Ss Page Size +.Bl -column -offset indent "Architecture" "Page Sizes" +.It Sy Architecture Ta Sy Page Sizes +.It aarch64 Ta 4K, 64K, 2M, 1G +.It aarch64c Ta 4K, 64K, 2M, 1G +.It amd64 Ta 4K, 2M, 1G +.It armv7 Ta 4K, 1M +.It i386 Ta 4K, 2M (PAE), 4M +.It powerpc Ta 4K +.It powerpcspe Ta 4K +.It powerpc64 Ta 4K +.It powerpc64le Ta 4K +.It riscv64 Ta 4K, 2M, 1G +.It riscv64c Ta 4K, 2M, 1G +.El +.Ss User Address Space Layout +.Bl -column -offset indent "riscv64 (Sv48)" "0x0001000000000000" "NNNU" +.It Sy Architecture Ta Sy Maximum Address Ta Sy Address Space Size +.It aarch64 Ta 0x0001000000000000 Ta 256TiB +.It aarch64c Ta 0x0001000000000000 Ta 256TiB +.It amd64 (LA48) Ta 0x0000800000000000 Ta 128TiB +.It amd64 (LA57) Ta 0x0100000000000000 Ta 64PiB +.It armv7 Ta 0xbfc00000 Ta 3GiB +.It i386 Ta 0xffc00000 Ta 4GiB +.It powerpc Ta 0xfffff000 Ta 4GiB +.It powerpcspe Ta 0x7ffff000 Ta 2GiB +.It powerpc64 Ta 0x000fffffc0000000 Ta 4PiB +.It powerpc64le Ta 0x000fffffc0000000 Ta 4PiB +.It riscv64 (Sv39) Ta 0x0000004000000000 Ta 256GiB +.It riscv64c (Sv39) Ta 0x0000004000000000 Ta 256GiB +.It riscv64 (Sv48) Ta 0x0000800000000000 Ta 128TiB +.It riscv64c (Sv48) Ta 0x0000800000000000 Ta 128TiB +.El +.Pp +The layout of a process' address space can be queried via the +.Dv KERN_PROC_VM_LAYOUT +.Xr sysctl 3 +MIB. +.Pp +Historically, amd64 CPUs were limited to a 48-bit virtual address space. +Newer CPUs support 5-level page tables, which extend the significant bits of +addresses to 57 bits (LA57 mode). +The address space layout is determined by the CPU's support for LA57. +Setting the +.Sy vm.pmap.la57 +tunable to 0 forces the system into 4-level paging mode, even on hardware that +supports 5-level paging. +In this mode, all processes get a 48-bit address space. +The +.Sy vm.pmap.prefer_la48_uva +tunable determines whether processes running on a LA57 system are limited to +a 48-bit address space by default. +Some applications make use of unused upper bits in pointer values to store +information, and thus implicitly assume they are running in LA48 mode. +To avoid breaking compatibility, all processes run in LA48 mode by default. +The +.Xr elfctl 1 +utility can be used to request LA48 or LA57 mode for specific executables. +Similarly, +.Xr proccontrol 1 +can be used to configure the address space layout when executing a process. +.Pp +The RISC-V specification permits 3-level (Sv39), 4-level (Sv48), and +5-level (Sv57) page tables. +Hardware is only required to implement Sv39; implementations which support +Sv48 must also support Sv39, and implementations which support Sv57 must also +support Sv48. +The +.Sy vm.pmap.mode +tunable can be used to select the layout. +.Fx +currently supports Sv39 and Sv48 and defaults to using Sv39. +.Ss Floating Point +.Bl -column -offset indent "Architecture" "float, double" "long double" +.It Sy Architecture Ta Sy float, double Ta Sy long double +.It aarch64 Ta hard Ta soft, quad precision +.It aarch64c Ta hard Ta soft, quad precision +.It amd64 Ta hard Ta hard, 80 bit +.It armv7 Ta hard Ta hard, double precision +.It i386 Ta hard Ta hard, 80 bit +.It powerpc Ta hard Ta hard, double precision +.It powerpcspe Ta hard Ta hard, double precision +.It powerpc64 Ta hard Ta hard, double precision +.It powerpc64le Ta hard Ta hard, double precision +.It riscv64 Ta hard Ta hard, quad precision +.It riscv64c Ta hard Ta hard, quad precision +.El +.Ss Default Tool Chain +.Fx +uses +.Xr clang 1 +as the default compiler on all supported CPU architectures, +LLVM's +.Xr ld.lld 1 +as the default linker, and +LLVM binary utilities such as +.Xr objcopy 1 +and +.Xr readelf 1 . +.Ss MACHINE_ARCH vs MACHINE_CPUARCH vs MACHINE +.Dv MACHINE_CPUARCH +should be preferred in Makefiles when the generic +architecture is being tested. +.Dv MACHINE_ARCH +should be preferred when there is something specific to a particular type of +architecture where there is a choice of many, or could be a choice of many. +Use +.Dv MACHINE +when referring to the kernel, interfaces dependent on a specific type of kernel +or similar things like boot sequences. +.Bl -column -offset indent "Dv MACHINE" "Dv MACHINE_CPUARCH" "Dv MACHINE_ARCH" +.It Dv MACHINE Ta Dv MACHINE_CPUARCH Ta Dv MACHINE_ARCH +.It arm64 Ta aarch64 Ta aarch64, aarch64c +.It amd64 Ta amd64 Ta amd64 +.It arm Ta arm Ta armv7 +.It i386 Ta i386 Ta i386 +.It powerpc Ta powerpc Ta powerpc, powerpcspe, powerpc64, powerpc64le +.It riscv Ta riscv Ta riscv64, riscv64c +.El +.Ss Predefined Macros +The compiler provides a number of predefined macros. +Some of these provide architecture-specific details and are explained below. +Other macros, including those required by the language standard, are not +included here. +.Pp +The full set of predefined macros can be obtained with this command: +.Bd -literal -offset indent +cc -x c -dM -E /dev/null +.Ed +.Pp +Common type size and endianness macros: +.Bl -column -offset indent "__SIZEOF_POINTER__" "Meaning" +.It Sy Macro Ta Sy Meaning +.It Dv __SIZEOF_LONG__ Ta size in bytes of long +.It Dv __SIZEOF_POINTER__ Ta size in bytes of intptr_t and pointers +.It Dv __SIZEOF_SIZE_T__ Ta size in bytes of size_t +.It Dv __LP64__ Ta 64-bit (8-byte) long and pointer, 32-bit (4-byte) int +.It Dv __ILP32__ Ta 32-bit (4-byte) int, long and pointer +.It Dv __CHERI__ Ta 128-bit (16-byte) capability pointer, 64-bit (8-byte) long +.It Dv BYTE_ORDER Ta Either Dv BIG_ENDIAN or Dv LITTLE_ENDIAN . +.El +.Pp +Because systems were historically either +.Dv __ILP32__ +or +.Dv __LP64__ +it has been common for programmers to test only one and assume the other +one in an else branch. +With the arrival of CHERI architectures, this is no longer the case. +.Dv __SIZEOF_*__ +macros should be used instead. +New uses of +.Dv __ILP32__ +and +.Dv __LP64__ +should be avoided. +Compilers for CHERI targets do not define +.Dv __LP64__ +as their pointers are 128-bit capabilities. +.Pp +Architecture-specific macros: +.Bl -column -offset indent "Architecture" "Predefined macros" +.It Sy Architecture Ta Sy Predefined macros +.It aarch64 Ta Dv __aarch64__ +.It aarch64c Ta Dv __aarch64__ , Dv __CHERI__ +.It amd64 Ta Dv __amd64__ , Dv __x86_64__ +.It armv7 Ta Dv __arm__ , Dv __ARM_ARCH >= 7 +.It i386 Ta Dv __i386__ +.It powerpc Ta Dv __powerpc__ +.It powerpcspe Ta Dv __powerpc__ , Dv __SPE__ +.It powerpc64 Ta Dv __powerpc__ , Dv __powerpc64__ +.It powerpc64le Ta Dv __powerpc__ , Dv __powerpc64__ +.It riscv64 Ta Dv __riscv , Dv __riscv_xlen == 64 +.It riscv64c Ta Dv __riscv , Dv __riscv_xlen == 64 , Dv __CHERI__ +.El +.Pp +Compilers may define additional variants of architecture-specific macros. +The macros above are preferred for use in +.Fx . +.Ss Important Xr make 1 variables +Most of the externally settable variables are defined in the +.Xr build 7 +man page. +These variables are not otherwise documented and are used extensively +in the build system. +.Bl -tag -width "MACHINE_CPUARCH" +.It Dv MACHINE +Represents the hardware platform. +This is the same as the native platform's +.Xr uname 1 +.Fl m +output. +It defines both the userland / kernel interface, as well as the +bootloader / kernel interface. +It should only be used in these contexts. +Each CPU architecture may have multiple hardware platforms it supports +where +.Dv MACHINE +differs among them. +It is used to collect together all the files from +.Xr config 8 +to build the kernel. +It is often the same as +.Dv MACHINE_ARCH +just as one CPU architecture can be implemented by many different +hardware platforms, one hardware platform may support multiple CPU +architecture family members, though with different binaries. +For example, +.Dv MACHINE +of i386 supported the IBM-AT hardware platform while the +.Dv MACHINE +of pc98 supported the Japanese company NEC's PC-9801 and PC-9821 +hardware platforms. +Both of these hardware platforms supported only the +.Dv MACHINE_ARCH +of i386 where they shared a common ABI, except for certain kernel / +userland interfaces relating to underlying hardware platform +differences in bus architecture, device enumeration and boot interface. +Generally, +.Dv MACHINE +should only be used in src/sys and src/stand or in system imagers or +installers. +.It Dv MACHINE_ARCH +Represents the CPU processor architecture. +This is the same as the native platforms +.Xr uname 1 +.Fl p +output. +It defines the CPU instruction family supported. +It may also encode a variation in the byte ordering of multi-byte +integers (endian). +It may also encode a variation in the size of the integer or pointer. +It may also encode a ISA revision. +It may also encode hard versus soft floating point ABI and usage. +It may also encode a variant ABI when the other factors do not +uniquely define the ABI. +It, along with +.Dv MACHINE , +defines the ABI used by the system. +Generally, the plain CPU name specifies the most common (or at least +first) variant of the CPU. +This is why powerpc and powerpc64 imply 'big endian' while armv7 and aarch64 +imply little endian. +If we ever were to support the so-called x32 ABI (using 32-bit +pointers on the amd64 architecture), it would most likely be encoded +as amd64-x32. +It is unfortunate that amd64 specifies the 64-bit evolution of the x86 platform +(it matches the 'first rule') as almost everybody else uses x86_64. +The +.Fx +port was so early, it predated processor name standardization after Intel joined +the market. +At the time, each OS selected its own conventions. +Backwards compatibility means it is not easy to change to the consensus name. +.It Dv MACHINE_CPUARCH +Represents the source location for a given +.Dv MACHINE_ARCH . +It is generally the common prefix for all the MACHINE_ARCH that +share the same implementation, though 'riscv' breaks this rule. +While amd64 and i386 are closely related, MACHINE_CPUARCH is not x86 +for them. +The +.Fx +source base supports amd64 and i386 with two +distinct source bases living in subdirectories named amd64 and i386 +(though behind the scenes there's some sharing that fits into this +framework). +.It Dv CPUTYPE +Sets the flavor of +.Dv MACHINE_ARCH +to build. +It is used to optimize the build for a specific CPU / core that the +binaries run on. +Generally, this does not change the ABI, though it can be a fine line +between optimization for specific cases. +.It Dv TARGET +Used to set +.Dv MACHINE +in the top level Makefile for cross building. +Unused outside of that scope. +It is not passed down to the rest of the build. +Makefiles outside of the top level should not use it at all (though +some have their own private copy for historical reasons). +.It Dv TARGET_ARCH +Used to set +.Dv MACHINE_ARCH +by the top level Makefile for cross building. +Like +.Dv TARGET , +it is unused outside of that scope. +.El +.Sh SEE ALSO +.Xr elfctl 1 , +.Xr proccontrol 1 , +.Xr sysctl 3 , +.Xr src.conf 5 , +.Xr build 7 , +.Xr simd 7 +.Sh HISTORY +An +.Nm +manual page appeared in +.Fx 11.1 . diff --git a/static/freebsd/man7/ascii.7 b/static/freebsd/man7/ascii.7 new file mode 100644 index 00000000..11f4f63c --- /dev/null +++ b/static/freebsd/man7/ascii.7 @@ -0,0 +1,195 @@ +.\" Copyright (c) 1989, 1990, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 4, 2025 +.Dt ASCII 7 +.Os +.Sh NAME +.Nm ascii +.Nd octal, hexadecimal, decimal and binary +.Tn ASCII +character sets +.Sh DESCRIPTION +The +.Nm octal +set: +.Bd -literal -offset left +000 NUL 001 SOH 002 STX 003 ETX 004 EOT 005 ENQ 006 ACK 007 BEL +010 BS 011 HT 012 LF 013 VT 014 FF 015 CR 016 SO 017 SI +020 DLE 021 DC1 022 DC2 023 DC3 024 DC4 025 NAK 026 SYN 027 ETB +030 CAN 031 EM 032 SUB 033 ESC 034 FS 035 GS 036 RS 037 US +040 SP 041 ! 042 " 043 # 044 $ 045 % 046 & 047 ' +050 ( 051 ) 052 * 053 + 054 , 055 - 056 . 057 / +060 0 061 1 062 2 063 3 064 4 065 5 066 6 067 7 +070 8 071 9 072 : 073 ; 074 < 075 = 076 > 077 ? +100 @ 101 A 102 B 103 C 104 D 105 E 106 F 107 G +110 H 111 I 112 J 113 K 114 L 115 M 116 N 117 O +120 P 121 Q 122 R 123 S 124 T 125 U 126 V 127 W +130 X 131 Y 132 Z 133 [ 134 \e\ 135 ] 136 ^ 137 _ +140 ` 141 a 142 b 143 c 144 d 145 e 146 f 147 g +150 h 151 i 152 j 153 k 154 l 155 m 156 n 157 o +160 p 161 q 162 r 163 s 164 t 165 u 166 v 167 w +170 x 171 y 172 z 173 { 174 | 175 } 176 ~ 177 DEL +.Ed +.Pp +The +.Nm hexadecimal +set: +.Bd -literal -offset left +00 NUL 01 SOH 02 STX 03 ETX 04 EOT 05 ENQ 06 ACK 07 BEL +08 BS 09 HT 0a LF 0b VT 0c FF 0d CR 0e SO 0f SI +10 DLE 11 DC1 12 DC2 13 DC3 14 DC4 15 NAK 16 SYN 17 ETB +18 CAN 19 EM 1a SUB 1b ESC 1c FS 1d GS 1e RS 1f US +20 SP 21 ! 22 " 23 # 24 $ 25 % 26 & 27 ' +28 ( 29 ) 2a * 2b + 2c , 2d - 2e . 2f / +30 0 31 1 32 2 33 3 34 4 35 5 36 6 37 7 +38 8 39 9 3a : 3b ; 3c < 3d = 3e > 3f ? +40 @ 41 A 42 B 43 C 44 D 45 E 46 F 47 G +48 H 49 I 4a J 4b K 4c L 4d M 4e N 4f O +50 P 51 Q 52 R 53 S 54 T 55 U 56 V 57 W +58 X 59 Y 5a Z 5b [ 5c \e\ 5d ] 5e ^ 5f _ +60 \` 61 a 62 b 63 c 64 d 65 e 66 f 67 g +68 h 69 i 6a j 6b k 6c l 6d m 6e n 6f o +70 p 71 q 72 r 73 s 74 t 75 u 76 v 77 w +78 x 79 y 7a z 7b { 7c | 7d } 7e ~ 7f DEL +.Ed +.Pp +The +.Nm decimal +set: +.Bd -literal -offset left + 0 NUL 1 SOH 2 STX 3 ETX 4 EOT 5 ENQ 6 ACK 7 BEL + 8 BS 9 HT 10 LF 11 VT 12 FF 13 CR 14 SO 15 SI + 16 DLE 17 DC1 18 DC2 19 DC3 20 DC4 21 NAK 22 SYN 23 ETB + 24 CAN 25 EM 26 SUB 27 ESC 28 FS 29 GS 30 RS 31 US + 32 SP 33 ! 34 " 35 # 36 $ 37 % 38 & 39 ' + 40 ( 41 ) 42 * 43 + 44 , 45 - 46 . 47 / + 48 0 49 1 50 2 51 3 52 4 53 5 54 6 55 7 + 56 8 57 9 58 : 59 ; 60 < 61 = 62 > 63 ? + 64 @ 65 A 66 B 67 C 68 D 69 E 70 F 71 G + 72 H 73 I 74 J 75 K 76 L 77 M 78 N 79 O + 80 P 81 Q 82 R 83 S 84 T 85 U 86 V 87 W + 88 X 89 Y 90 Z 91 [ 92 \e\ 93 ] 94 ^ 95 _ + 96 ` 97 a 98 b 99 c 100 d 101 e 102 f 103 g +104 h 105 i 106 j 107 k 108 l 109 m 110 n 111 o +112 p 113 q 114 r 115 s 116 t 117 u 118 v 119 w +120 x 121 y 122 z 123 { 124 | 125 } 126 ~ 127 DEL +.Ed +.Pp +The +.Nm binary +set: +.Bd -literal -offset left + 00 01 10 11 + +NUL SP @ ` 00000 +SOH ! A a 00001 +STX " B b 00010 +ETX # C c 00011 +EOT $ D d 00100 +ENQ % E e 00101 +ACK & F f 00110 +BEL ' G g 00111 + BS ( H h 01000 + HT ) I i 01001 + LF * J j 01010 + VT + K k 01011 + FF , L l 01100 + CR - M m 01101 + SO . N n 01110 + SI / O o 01111 +DLE 0 P p 10000 +DC1 1 Q q 10001 +DC2 2 R r 10010 +DC3 3 S s 10011 +DC4 4 T t 10100 +NAK 5 U u 10101 +SYN 6 V v 10110 +ETB 7 W w 10111 +CAN 8 X x 11000 + EM 9 Y y 11001 +SUB : Z z 11010 +ESC ; [ { 11011 + FS < \e\ | 11100 + GS = ] } 11101 + RS > ^ - 11110 + US ? _ DEL 11111 +.Ed +.Pp +The full +.Nm names +of the control character set: +.Bd -literal -offset left +NUL NULl +SOH Start Of Heading +STX Start Of Text +ETX End Of Text +EOT End Of Transmission +ENQ ENQuiry +ACK ACKnowledge +BEL BELl + BS BackSpace + HT Horizontal Tab + LF Line Feed (new line) + VT Vertical Tab + FF new page Form Feed + CR Carriage Return + SO Shift Out + SI Shift In +DLE Data Link Escape +DC1 Device Control 1 +DC2 Device Control 2 +DC3 Device Control 3 +DC4 Device Control 4 +NAK Negative AcKnowledge +SYN SYNchronous idle +ETB End of Transmission Block +CAN CANcel + EM End of Medium +SUB SUBstitute +ESC ESCape + FS File Separator + GS Group Separator + RS Record Separator + US Unit Separator +.Ed +.Sh FILES +.Bl -tag -width /usr/share/misc/ascii -compact +.It Pa /usr/share/misc/ascii +.El +.Sh STANDARDS +.Rs +.%T Information Systems - Coded Character Sets - 7-Bit American National\ + Standard Code for Information Interchange (7-Bit ASCII) +.%R INCITS 4-1986[R2017] +.%Q InterNational Committee for Information Technology Standards +.Re +.Sh HISTORY +An +.Nm +manual page appeared in +.At v1 . diff --git a/static/freebsd/man7/bsd.snmpmod.mk.7 b/static/freebsd/man7/bsd.snmpmod.mk.7 new file mode 100644 index 00000000..fc6ca0ae --- /dev/null +++ b/static/freebsd/man7/bsd.snmpmod.mk.7 @@ -0,0 +1,115 @@ +.\" +.\" Copyright (c) 2005,2008 +.\" Hartmut Brandt. +.\" All rights reserved. +.\" +.\" Author: Hartmut Brandt +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 8, 2008 +.Dt BSD.SNMPMOD.MK 7 +.Os +.Sh NAME +.Nm bsd.snmpmod.mk +.Nd building modules for +.Xr bsnmpd 1 +.Sh SYNOPSIS +.Fd ".include " +.Sh DESCRIPTION +The file +.In bsd.snmpmod.mk +simplifies the building of modules for the Begemot SNMP daemon, +.Xr bsnmpd 1 . +It provides some common functions for building a module and +relies on +.In bsd.lib.mk , +which is included by +.In bsd.snmpmod.mk +to actually build the shared library. +.Pp +The following +.Xr make 1 +variables control the special functions: +.Bl -tag -width ".Va EXTRAMIBDEFS" +.It Va MOD +The short name of the module. +The name of the shared library will be +.Pa snmp_${MOD}.so . +There must exist a file +.Pa ${MOD}_tree.def +for compilation with +.Xr gensnmptree 1 +which contains the definition of the MIB tree implemented by the module. +.It Va EXTRAMIBDEFS +A list of extra MIB definition files for +.Xr gensnmptree 1 . +This is optional. +This file list is given to both calls to +.Xr gensnmptree 1 No \(em +the one that extracts the symbols in +.Va XSYM +from the MIB definitions and the one that +generates the table with OIDs served by this module. +.It Va EXTRAMIBSYMS +A list of extra MIB definition files for +.Xr gensnmptree 1 . +This is optional. +This file list is given only to the call to +.Xr gensnmptree 1 +that extracts symbols from MIB definition files. +It is useful if there are dependencies on other MIBs or for extracting global +definitions for enumeration constants. +.It Va XSYM +A list of symbols to be extracted from the MIB definition files by +.Xr gensnmptree 1 . +This is optional. +.It Va DEFS +A list of MIB definition files to be installed. +This is optional. +.It Va BMIBS +A list of textual MIBs to be installed. +This is optional. +.El +.Pp +Three files are automatically created from the MIB definition files and +the +.Va XSYM +variable: +.Bl -tag -width ".Va EXTRAMIBDEFS" +.It Pa ${MOD}_tree.c +This contains a table with the tree implemented by the module. +It is automatically included into the +.Va SRCS +variable. +.It Pa ${MOD}_tree.h +This contains preprocessor defines for all the OIDs defined by the module +and can be included in the module's source code. +.It Pa ${MOD}_oid.h +OID preprocessor definitions for all the symbols listed in +.Va XSYMS . +This is to be included into the module's source code. +.El +.Sh SEE ALSO +.Xr bsnmpd 1 , +.Xr gensnmptree 1 , +.Xr snmpmod 3 diff --git a/static/freebsd/man7/build.7 b/static/freebsd/man7/build.7 new file mode 100644 index 00000000..ef4e2c94 --- /dev/null +++ b/static/freebsd/man7/build.7 @@ -0,0 +1,1196 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2000 +.\" Mike W. Meyer +.\" +.\" 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 ``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 22, 2026 +.Dt BUILD 7 +.Os +.Sh NAME +.Nm build +.Nd general instructions on how to build the +.Fx +system +.Sh DESCRIPTION +The sources for the +.Fx +system and its applications are contained in three directories, +normally: +.Bl -tag -width "/usr/ports" +.It Pa /usr/src +.Dq base system , +loosely defined as everything required to build the system +to a useful state +.It Pa /usr/doc +system documentation, excluding manual pages +.It Pa /usr/ports +third-party software, with a consistent interface for building and +installing them; see +.Xr ports 7 +.El +.Pp +These directories may be initially empty or non-existent until updated +with Git +.Po Pa devel/git +from the +.Fx +Ports Collection +.Pc . +.Pp +The +.Xr make 1 +command is used in each of these directories to build and install the +things in that directory. +Issuing the +.Xr make 1 +command in any directory issues the +.Xr make 1 +command recursively in all subdirectories. +With no target specified, the items in the directories are built +and no further action is taken. +.Pp +A source tree is allowed to be read-only. +As described in +.Xr make 1 , +objects are usually built in a separate object directory hierarchy +specified by the environment variable +.Va MAKEOBJDIRPREFIX , +or under +.Pa /usr/obj +if variable +.Va MAKEOBJDIRPREFIX +is not set. +The canonical object directory is described in the documentation for the +.Cm buildworld +target below. +.Pp +The +.Nm +may be controlled by defining +.Xr make 1 +variables described in the +.Sx ENVIRONMENT +section below, and by the variables documented in +.Xr make.conf 5 . +.Pp +The default components included in the build are specified in the file +.Pa /etc/src.conf +in the source tree. +To override the default file, include the SRCCONF option in the make steps, +pointing to a custom src.conf file. +For more information see +.Xr src.conf 5 . +.Pp +The following list provides the names and actions for the targets +supported by the build system: +.Bl -tag -width ".Cm cleandepend" +.It Cm analyze +Run Clang static analyzer against all objects and present output on stdout. +.It Cm check +Run tests for a given subdirectory. +The default directory used is +.Pa ${.OBJDIR} , +but the check directory can be changed with +.Pa ${CHECKDIR} . +.It Cm checkworld +Run the +.Fx +test suite on installed world. +.It Cm clean +Remove any files created during the build process. +.It Cm cleandepend +Remove the +.Pa ${.OBJDIR}/${DEPENDFILE}* +files generated by prior +.Dq Li "make" +and +.Dq Li "make depend" +steps. +.It Cm cleandir +Remove the canonical object directory if it exists, or perform +actions equivalent to +.Dq Li "make clean cleandepend" +if it does not. +This target will also remove an +.Pa obj +link in +.Pa ${.CURDIR} +if that exists. +.Pp +It is advisable to run +.Dq Li "make cleandir" +twice: the first invocation will remove the canonical object directory +and the second one will clean up +.Pa ${.CURDIR} . +.It Cm depend +Generate a list of build dependencies in file +.Pa ${.OBJDIR}/${DEPENDFILE} . +Per-object dependencies are generated at build time and stored in +.Pa ${.OBJDIR}/${DEPENDFILE}.${OBJ} . +.It Cm install +Install the results of the build to the appropriate location in the +installation directory hierarchy specified in variable +.Va DESTDIR . +.It Cm obj +Create the canonical object directory associated with the current +directory. +.It Cm objlink +Create a symbolic link to the canonical object directory in +.Pa ${.CURDIR} . +.It Cm tags +Generate a tags file using the program specified in the +.Xr make 1 +variable +.Va CTAGS . +The build system supports +.Xr ctags 1 +and +.Nm "GNU Global" . +.El +.Pp +The other supported targets under directory +.Pa /usr/src +are: +.Bl -tag -width ".Cm distributeworld" +.It Cm buildenv +Spawn an interactive shell with environment variables set up for +building the system or individual components. +For cross-building the target architecture needs to be specified with +.Xr make 1 +variables +.Va TARGET_ARCH +and +.Va TARGET . +.Pp +This target is only useful after a complete toolchain (including +the compiler, linker, assembler, headers and libraries) has been +built; see the +.Cm toolchain +target below. +.Pp +.Va BUILDENV_SHELL , +which defaults to +.Pa /bin/sh , +is executed. +This can be set to a command that does something in this build environment, +like cross build an application. +If that application has dependencies, though, the +.Pa devel/poudriere +package or port provides a more generic solution. +.It Cm buildenvvars +Print the shell variables that are set for a +.Cm buildenv +environment and exit. +.It Cm buildworld +Build everything but the kernel, configure files in +.Pa etc , +and +.Pa release . +The object directory can be changed from the default +.Pa /usr/obj +by setting the +.Pa MAKEOBJDIRPREFIX +.Xr make 1 +variable. +The actual build location prefix used +depends on the +.Va WITH_UNIFIED_OBJDIR +option from +.Xr src.conf 5 . +If enabled it is +.Pa ${MAKEOBJDIRPREFIX}${.CURDIR}/${TARGET}.${TARGET_ARCH} +for all builds. +If disabled it is +.Pa ${MAKEOBJDIRPREFIX}${.CURDIR} +for native builds, and +.Pa ${MAKEOBJDIRPREFIX}/${TARGET}.${TARGET_ARCH}${.CURDIR} +for cross builds and native builds with variable +.Va CROSS_BUILD_TESTING +set. +.It Cm cleankernel +Attempts to clean up targets built by a preceding +.Cm buildkernel , +or similar step, built from the same source directory and +.Va KERNCONF . +.It Cm cleanworld +Attempt to clean up targets built by a preceding +.Cm buildworld , +or similar step, built from this source directory. +.It Cm cleanuniverse +When +.Va WITH_UNIFIED_OBJDIR +is enabled, attempt to clean up targets built by a preceding +.Cm buildworld , +.Cm universe , +or similar step, for any architecture built from this source directory. +.It Cm distributeworld +Distribute everything compiled by a preceding +.Cm buildworld +step. +Files are placed in the directory hierarchy specified by +.Xr make 1 +variable +.Va DISTDIR . +This target is used while building a release; see +.Xr release 7 . +.It Cm native-xtools +This target builds a cross-toolchain for the given +.Sy TARGET +and +.Sy TARGET_ARCH , +as well as a select list of static userland tools for the host system. +This is intended to be used in a jail where QEMU is used to improve +performance by avoiding emulating binaries that do not need to be emulated. +.Sy TARGET +and +.Sy TARGET_ARCH +should be defined. +.It Cm native-xtools-install +Installs the results to +.Pa ${DESTDIR}/${NXTP} +where +.Va NXTP +defaults to +.Pa nxb-bin . +.Sy TARGET +and +.Sy TARGET_ARCH +must be defined. +.It Cm packages +Create a +.Xr freebsd-base 7 +package repository containing packages that can be +used to install or upgrade the base system. +The repository is created in the object directory, under +.Pa ${REPODIR}/${PKG_ABI} +where +.Ev REPODIR +is the base directory where the repository will be created, and +.Va PKG_ABI +is the +.Xr pkg 7 +ABI for the build target, for example, +.Pa /usr/obj/${SRCDIR}/repo/FreeBSD:15:amd64 . +.It Cm packageworld +Archive the results of +.Cm distributeworld , +placing the results in +.Va DISTDIR . +This target is used while building a +.Xr release 7 +and is unrelated to building +.Xr freebsd-base 7 +packages. +.It Cm installworld +Install everything built by a preceding +.Cm buildworld +step into the directory hierarchy pointed to by +.Xr make 1 +variable +.Va DESTDIR . +.Pp +If installing onto an NFS file system and running +.Xr make 1 +with the +.Fl j +option, make sure that +.Xr rpc.lockd 8 +is running on both client and server. +See +.Xr rc.conf 5 +on how to make it start at boot time. +.It Cm toolchain +Create the build toolchain needed to build the rest of the system. +For cross-architecture builds, this step creates a cross-toolchain. +.It Cm universe +For each architecture, +execute a +.Cm buildworld +followed by a +.Cm buildkernel +for all kernels for that architecture, +including +.Pa LINT . +This command takes a long time. +.It Cm kernels +Like +.Cm universe +with +.Va WITHOUT_WORLDS +defined so only the kernels for each architecture are built. +.It Cm worlds +Like +.Cm universe +with +.Va WITHOUT_KERNELS +defined so only the worlds for each architecture are built. +.It Cm targets +Print a list of supported +.Va TARGET +/ +.Va TARGET_ARCH +pairs for world and kernel targets. +.It Cm tinderbox +Execute the same targets as +.Cm universe . +In addition print a summary of all failed targets at the end and +exit with an error if there were any. +.It Cm toolchains +Create a build toolchain for each architecture supported by the build system. +.It Cm xdev +Builds and installs a cross-toolchain and sysroot for the given +.Sy TARGET +and +.Sy TARGET_ARCH . +The sysroot contains target library and headers. +The target is an alias for +.Cm xdev-build +and +.Cm xdev-install . +The location of the files installed can be controlled with +.Va DESTDIR . +The target location in +.Va DESTDIR +is +.Pa ${DESTDIR}/${XDTP} +where +.Va XDTP +defaults to +.Pa /usr/${XDDIR} +and +.Va XDDIR +defaults to +.Pa ${TARGET_ARCH}-freebsd . +.It Cm update-packages +Create or update the +.Xr freebsd-base 7 +package repository for the base system. +If an old repository is being updated, +then packages whose contents have not changed since the previous version +will be copied into the new repository to avoid needless updating of the +version number. +.It Cm xdev-build +Builds for the +.Cm xdev +target. +.It Cm xdev-install +Installs the files for the +.Cm xdev +target. +.It Cm xdev-links +Installs autoconf-style symlinks to +.Pa ${DESTDIR}/usr/bin +pointing into the xdev toolchain in +.Pa ${DESTDIR}/${XDTP} . +.El +.Pp +Kernel specific build targets in +.Pa /usr/src +are: +.Bl -tag -width ".Cm distributekernel" +.It Cm buildkernel +Rebuild the kernel and the kernel modules. +The object directory can be changed from the default +.Pa /usr/obj +by setting the +.Pa MAKEOBJDIRPREFIX +.Xr make 1 +variable. +.It Cm installkernel +Install the kernel and the kernel modules to directory +.Pa ${DESTDIR}/boot/kernel , +renaming any pre-existing directory with this name to +.Pa kernel.old +if it contained the currently running kernel. +The target directory under +.Pa ${DESTDIR} +may be modified using the +.Va INSTKERNNAME +or +.Va KODIR +.Xr make 1 +variables. +.It Cm distributekernel +Install the kernel to the directory +.Pa ${DISTDIR}/kernel/boot/kernel . +This target is used while building a release; see +.Xr release 7 . +.It Cm packagekernel +Archive the results of +.Cm distributekernel , +placing the results in +.Va DISTDIR . +This target is used while building a +.Xr release 7 +and is unrelated to building +.Xr freebsd-base 7 +packages. +.It Cm kernel +Equivalent to +.Cm buildkernel +followed by +.Cm installkernel +.It Cm kernel-toolchain +Rebuild the tools needed for kernel compilation. +Use this if you did not do a +.Cm buildworld +first. +.It Cm reinstallkernel +Reinstall the kernel and the kernel modules, overwriting the contents +of the target directory. +As with the +.Cm installkernel +target, the target directory can be specified using the +.Xr make 1 +variable +.Va INSTKERNNAME . +.El +.Pp +Convenience targets for cleaning up the install destination directory +denoted by variable +.Va DESTDIR +include: +.Bl -tag -width ".Cm delete-old-libs" +.It Cm check-old +Print a list of old files and directories in the system. +.It Cm check-old-libs +Print a list of obsolete base system libraries. +.It Cm delete-old +Delete obsolete base system files and directories interactively. +When +.Li -DBATCH_DELETE_OLD_FILES +is specified at the command line, the delete operation will be +non-interactive. +The variables +.Va DESTDIR , +.Va TARGET_ARCH +and +.Va TARGET +should be set as with +.Dq Li "make installworld" . +.It Cm delete-old-libs +Delete obsolete base system libraries interactively. +This target should only be used if no third party software uses these +libraries. +When +.Li -DBATCH_DELETE_OLD_FILES +is specified at the command line, the delete operation will be +non-interactive. +The variables +.Va DESTDIR , +.Va TARGET_ARCH +and +.Va TARGET +should be set as with +.Dq Li "make installworld" . +.El +.Sh ENVIRONMENT +Variables that influence all builds include: +.Bl -tag -width ".Va MAKEOBJDIRPREFIX" +.It Va DEBUG_FLAGS +Defines a set of debugging flags that will be used to build all userland +binaries under +.Pa /usr/src . +When +.Va DEBUG_FLAGS +is defined, the +.Cm install +and +.Cm installworld +targets install binaries from the current +.Va MAKEOBJDIRPREFIX +without stripping, +so that debugging information is retained in the installed binaries. +.It Va DESTDIR +The directory hierarchy prefix where built objects will be installed. +If not set, +.Va DESTDIR +defaults to the empty string. +If set, +.Va DESTDIR +must specify an absolute path. +.It Va MAKEOBJDIRPREFIX +Defines the prefix for directory names in the tree of built objects. +Defaults to +.Pa /usr/obj +if not defined. +This variable should only be set in the environment or +.Pa /etc/src-env.conf +and not via +.Pa /etc/make.conf +or +.Pa /etc/src.conf +or the command line. +.Va MAKEOBJDIRPREFIX +must specify an absolute path. +.It Va WITHOUT_WERROR +If defined, compiler warnings will not cause the build to halt, +even if the makefile says otherwise. +.It Va WITH_CTF +If defined, the build process will run the DTrace CTF conversion +tools on built objects. +.El +.Pp +Additionally, builds in +.Pa /usr/src +are influenced by the following +.Xr make 1 +variables: +.Bl -tag -width ".Va LOCAL_MODULES_DIR" +.It Va CROSS_TOOLCHAIN +Requests use of an external toolchain to build either the world or kernel. +This value of this variable can either be the full path to a file, +or the base name of a file in +.Pa ${LOCALBASE}/share/toolchains . +The file should be a make file which sets variables to request an external +toolchain such as +.Va XCC . +.Pp +External toolchains are available in ports for both LLVM and GCC/binutils. +For external toolchains available in ports, +.Va CROSS_TOOLCHAIN +should be set to the name of the package. +LLVM toolchain packages use the name llvm. +GCC toolchains provide separate packages for each architecture and use the +name ${MACHINE_ARCH}-gcc. +.It Va INSTKERNNAME +If set, specify an alternative name to build and install for the various +kernel make targets. +Defaults to +.Dq Li kernel . +.It Va KERNCONF +Specify one or more space-separated kernels to build and install for the +various kernel make targets. +If multiple kernels are specified, the first listed kernel installs to +.Pa /boot/${INSTKERNNAME} , +and subsequent kernels install to +.Pa /boot/${INSTKERNNAME}.NAME . +.Pp +If unset, it defaults to GENERIC, +except on POWER architectures, +where it defaults to GENERIC64 for powerpc64, +and GENERIC64LE for powerpc64le. +.It Va KERNBUILDDIR +Overrides the default directory to get all the opt_*.h files for +building a kernel module. +Useful for stand-alone modules that depend on +.Xr config 8 +options. +Automatically set for modules built with a kernel. +.It Va KERNCONFDIR +Overrides the directory in which +.Va KERNCONF +and any files included by +.Va KERNCONF +should be found. +Defaults to +.Pa sys/${ARCH}/conf . +.It Va KERNFAST +If set, the build target +.Cm buildkernel +defaults to setting +.Va NO_KERNELCLEAN , +.Va NO_KERNELCONFIG , +and +.Va NO_KERNELOBJ . +When set to a value other than +.Cm 1 +then +.Va KERNCONF +is set to the value of +.Va KERNFAST . +.It Va KODIR +If set, +this variable specifies an alternative directory to install the kernel. +.It Va LOCAL_DIRS +If set, this variable supplies a list of additional directories relative to +the root of the source tree to build as part of the +.Cm everything +target. +The directories are built in parallel with each other, +and with the base system directories. +Insert a +.Va .WAIT +directive at the beginning of the +.Va LOCAL_DIRS +list to ensure all base system directories are built first. +.Va .WAIT +may also be used as needed elsewhere within the list. +.It Va LOCAL_ITOOLS +If set, this variable supplies a list of additional tools that are used by the +.Cm installworld +and +.Cm distributeworld +targets. +.It Va LOCAL_LIB_DIRS +If set, this variable supplies a list of additional directories relative to +the root of the source tree to build as part of the +.Cm libraries +target. +The directories are built in parallel with each other, +and with the base system libraries. +Insert a +.Va .WAIT +directive at the beginning of the +.Va LOCAL_DIRS +list to ensure all base system libraries are built first. +.Va .WAIT +may also be used as needed elsewhere within the list. +.It Va LOCAL_MTREE +If set, this variable supplies a list of additional mtrees relative to the +root of the source tree to use as part of the +.Cm hierarchy +target. +.It Va LOCAL_LEGACY_DIRS +If set, this variable supplies a list of additional directories relative to +the root of the source tree to build as part of the +.Cm legacy +target. +.It Va LOCAL_BSTOOL_DIRS +If set, this variable supplies a list of additional directories relative to +the root of the source tree to build as part of the +.Cm bootstrap-tools +target. +.It Va LOCAL_TOOL_DIRS +If set, this variable supplies a list of additional directories relative to +the root of the source tree to build as part of the +.Cm build-tools +target. +.It Va LOCAL_XTOOL_DIRS +If set, this variable supplies a list of additional directories relative to +the root of the source tree to build as part of the +.Cm cross-tools +target. +.It Va OBJROOT +The object directory root is defined as +.Pa ${OBJDIR}/${SRCDIR}/ . +See +.Pa share/mk/src.sys.obj.mk . +.It Va PKG_FORMAT +Specify a package compression format when building +.Xr freebsd-base 7 +packages. +Default: +.Ql tzst . +Consider using +.Ql tar +to disable compression. +Accepted options are documented in the +.Fl f +description of +.Xr pkg-create 8 . +.It Va PORTS_MODULES +A list of ports with kernel modules that should be built and installed +as part of the +.Cm buildkernel +and +.Cm installkernel +process. +This is currently incompatible with building +.Xr freebsd-base 7 +packages. +Each port must be specified as +.Ar category Ns Li / Ns Ar port Ns Op Li @ Ns Ar flavor , +e.g. +.Bd -literal +PORTS_MODULES=graphics/gpu-firmware-intel-kmod@kabylake +PORTS_MODULES+=graphics/drm-66-kmod +.Ed +.It Va LOCAL_MODULES +A list of external kernel modules that should be built and installed +as part of the +.Cm buildkernel +and +.Cm installkernel +process. +Defaults to the list of sub-directories of +.Va LOCAL_MODULES_DIR . +.It Va LOCAL_MODULES_DIR +The directory in which to search for the kernel modules specified by +.Va LOCAL_MODULES . +Each kernel module should consist of a directory containing a makefile. +Defaults to +.Pa ${LOCALBASE}/sys/modules . +.It Va SRCCONF +Specify a file to override the default +.Pa /etc/src.conf . +The src.conf file controls the components to build. +See +.Xr src.conf 5 +.It Va REPODIR +The root directory used to create the package repository for building +.Xr packages 7 . +Defaults to +.Pa ${OBJROOT}/repo/ . +This can also be set in +.Xr src-env.conf 5 . +.It Va STRIPBIN +Command to use at install time when stripping binaries. +Be sure to add any additional tools required to run +.Va STRIPBIN +to the +.Va LOCAL_ITOOLS +.Xr make 1 +variable before running the +.Cm distributeworld +or +.Cm installworld +targets. +See +.Xr install 1 +for more details. +.It Va SUBDIR_OVERRIDE +Override the default list of sub-directories and only build the +sub-directory named in this variable. +If combined with +.Cm buildworld +then all libraries and includes, and some of the build tools will still build +as well. +Specifying +.Cm -DNO_LIBS , +and +.Cm -DWORLDFAST +will only build the specified directory as was done historically. +When combined with +.Cm buildworld +it is necessary to override +.Va LOCAL_LIB_DIRS +with any custom directories containing libraries. +This allows building a subset of the system in the same way as +.Cm buildworld +does using its sysroot handling. +This variable can also be useful when debugging failed builds. +.Bd -literal -offset indent +make some-target SUBDIR_OVERRIDE=foo/bar +.Ed +.It Va SYSDIR +Specify the location of the kernel source to override the default +.Pa /usr/src/sys . +The kernel source is located in the +.Pa sys +subdirectory of the source tree checked out from the +.Pa src.git +repository. +.It Va TARGET +The target hardware platform. +This is analogous to the +.Dq Nm uname Fl m +output. +This is necessary to cross-build some target architectures. +For example, cross-building for ARM64 machines requires +.Va TARGET_ARCH Ns = Ns Li aarch64 +and +.Va TARGET Ns = Ns Li arm64 . +If not set, +.Va TARGET +defaults to the current hardware platform, unless +.Va TARGET_ARCH +is also set, in which case it defaults to the appropriate +value for that architecture. +.It Va TARGET_ARCH +The target machine processor architecture. +This is analogous to the +.Dq Nm uname Fl p +output. +Set this to cross-build for a different architecture. +If not set, +.Va TARGET_ARCH +defaults to the current machine architecture, unless +.Va TARGET +is also set, in which case it defaults to the appropriate +value for that platform. +Typically, one only needs to set +.Va TARGET . +.El +.Pp +Builds under directory +.Pa /usr/src +are also influenced by defining one or more of the following symbols, +using the +.Fl D +option of +.Xr make 1 : +.Bl -tag -width ".Va LOADER_DEFAULT_INTERP" +.It Va LOADER_DEFAULT_INTERP +Defines what interpreter the default loader program will have. +Valid values include +.Dq 4th , +.Dq lua , +and +.Dq simp . +This creates the default link for +.Pa /boot/loader +to the loader with that interpreter. +It also determines what interpreter is compiled into +.Pa userboot . +.It Va NO_CLEANDIR +If set, the build targets that clean parts of the object tree use the +equivalent of +.Dq make clean +instead of +.Dq make cleandir . +.It Va NO_CLEAN +If set, no object tree files are cleaned at all. +This is the default when +.Va WITH_META_MODE +is used with +.Xr filemon 4 +loaded. +See +.Xr src.conf 5 +for more details. +Setting +.Va NO_CLEAN +implies +.Va NO_KERNELCLEAN , +so when +.Va NO_CLEAN +is set no kernel objects are cleaned either. +.It Va NO_CTF +If set, the build process does not run the DTrace CTF conversion tools +on built objects. +.It Va NO_SHARE +If set, the build does not descend into the +.Pa /usr/src/share +subdirectory (i.e., manual pages, locale data files, timezone data files and +other +.Pa /usr/src/share +files will not be rebuild from their sources). +.It Va NO_KERNELCLEAN +If set, the build process does not run +.Dq make clean +as part of the +.Cm buildkernel +target. +.It Va NO_KERNELCONFIG +If set, the build process does not run +.Xr config 8 +as part of the +.Cm buildkernel +target. +.It Va NO_KERNELOBJ +If set, the build process does not run +.Dq make obj +as part of the +.Cm buildkernel +target. +.It Va NO_LIBS +If set, the libraries phase will be skipped. +.It Va NO_OBJWALK +If set, no object directories will be created. +This should only be used if object directories were created in a +previous build and no new directories are connected. +.It Va UNIVERSE_TOOLCHAIN +Requests use of the toolchain built as part of the +.Cm universe +target as an external toolchain. +.It Va WORLDFAST +If set, the build target +.Cm buildworld +defaults to setting +.Va NO_CLEAN , +.Va NO_OBJWALK , +and will skip most bootstrap phases. +It will only bootstrap libraries and build all of userland. +This option should be used only when it is known that none of the bootstrap +needs changed and that no new directories have been connected to the build. +.El +.Pp +Builds under directory +.Pa /usr/doc +are influenced by the following +.Xr make 1 +variables: +.Bl -tag -width ".Va DOC_LANG" +.It Va DOC_LANG +If set, restricts the documentation build to the language subdirectories +specified as its content. +The default action is to build documentation for all languages. +.El +.Pp +Builds using the +.Cm universe +and related targets are influenced by the following +.Xr make 1 +variables: +.Bl -tag -width ".Va USE_GCC_TOOLCHAINS" +.It Va JFLAG +Pass the value of this variable to each +.Xr make 1 +invocation used to build worlds and kernels. +This can be used to enable multiple jobs within a single architecture's build +while still building each architecture serially. +.It Va MAKE_JUST_KERNELS +Only build kernels for each supported architecture. +.It Va MAKE_JUST_WORLDS +Only build worlds for each supported architecture. +.It Va WITHOUT_WORLDS +Only build kernels for each supported architecture. +.It Va WITHOUT_KERNELS +Only build worlds for each supported architecture. +.It Va UNIVERSE_TARGET +Execute the specified +.Xr make 1 +target for each supported architecture instead of the default action of +building a world and one or more kernels. +This variable implies +.Va WITHOUT_KERNELS . +.It Va USE_GCC_TOOLCHAINS +Use external GCC toolchains to build the requested targets. +If the required toolchain package for a supported architecture is not installed, +the build for that architecture is skipped. +.Pp +A specific version of GCC can be used by setting the value of this variable +to the desired version +.Pq for example, Dq gcc14 ; +otherwise a default version of GCC is used. +.It Va TARGETS +Only build the listed targets instead of each supported architecture. +.It Va EXTRA_TARGETS +In addition to the supported architectures, build the semi-supported +architectures. +A semi-supported architecture has build support in the +.Fx +tree, but receives significantly less testing and is generally for +fringe uses that do not have a wide appeal. +.El +.Sh FILES +.Bl -tag -width ".Pa /usr/share/examples/etc/make.conf" -compact +.It Pa /usr/doc/Makefile +.It Pa /usr/doc/share/mk/doc.project.mk +.It Pa /usr/ports/Mk/bsd.port.mk +.It Pa /usr/ports/Mk/bsd.sites.mk +.It Pa /usr/src/Makefile +.It Pa /usr/src/Makefile.inc1 +.Xr make 1 +infrastructure for each tree +.It Pa /usr/ports/UPDATING +.It Pa /usr/src/UPDATING +notable changes in each tree +.It Pa /usr/share/examples/etc/make.conf +example +.Xr make.conf 5 +.It Pa /etc/src.conf +src build configuration, see +.Xr src.conf 5 +.El +.Sh EXAMPLES +This section describes best practices for common situations. +When manual intervention is necessary, it will be mentioned in +.Pa UPDATING . +Make sure you have full backups before proceeding! +.Ss Example 1: Build and upgrade system in place +If using installed drivers such as graphics or virtual machine guest +drivers, check out the +.Xr ports 7 +tree, and specify the drivers in +.Xr src.conf 5 +so they are built and installed automatically after the kernel: +.Bd -literal -offset indent +git clone https://git.FreeBSD.org/ports.git /usr/ports +cat << EOF >> /etc/src.conf +PORTS_MODULES+=graphics/drm-kmod emulators/virtualbox-ose-kmod +EOF +.Ed +.Pp +Check out the CURRENT branch, build it, and install, +overwriting the current system: +.Bd -literal -offset indent +git clone https://git.FreeBSD.org/src.git /usr/src +cd /usr/src +make buildworld buildkernel +make installkernel +shutdown -r now +.Ed +.Pp +For major version upgrades, boot into single-user mode. +After restarting, install userspace, and merge configurations. +After verifying that you do not need them, delete old files: +.Bd -literal -offset indent +cd /usr/src +etcupdate -p +make installworld +etcupdate -B +make delete-old +shutdown -r now +.Ed +.Pp +After testing the new system and verifying that your applications do not +depend on them, delete the old libraries: +.Pp +.Dl make delete-old-libs +.Ss Example 2: Build and upgrade a custom kernel +Create a custom kernel configuration, +.Va MYKERNEL , +by including an existing configuration and using +.Cm device Ns / Ns Cm nodevice +and +.Cm options Ns / Ns Cm nooption +to select and configure components: +.Bd -literal -offset indent +cd /usr/src +cat << EOF > sys/amd64/conf/MYKERNEL +include GENERIC +ident MYKERNEL +nodevice sound +EOF +.Ed +.Pp +After creating the new kernel configuration, build a fresh toolchain, +build the kernel, and install it directly, moving the old kernel to +.Pa /boot/kernel.old/ : +.Bd -literal -offset indent +make kernel-toolchain +make -DALWAYS_CHECK_MAKE buildkernel KERNCONF=MYKERNEL +make -DALWAYS_CHECK_MAKE installkernel KERNCONF=MYKERNEL +shutdown -r now +.Ed +.Pp +To package the kernel into a +.Xr freebsd-base 7 +package instead of installing it directly, use +.Cm update-packages +instead of +.Cm installkernel : +.Bd -literal -offset indent +make buildworld buildkernel KERNCONF=MYKERNEL +make update-packages KERNCONF=MYKERNEL +.Ed +.Pp +To install the kernel directly to an alternate location, use the +.Va INSTKERNNAME +variable and boot it once to test via +.Xr nextboot 8 : +.Bd -literal -offset indent +make installkernel KERNCONF=MYKERNEL INSTKERNNAME=testkernel +nextboot -k testkernel +shutdown -r now +.Ed +.Ss Example 3: Build and upgrade a single piece of userspace +Rebuild and reinstall a single piece of userspace, in this case +.Xr ls 1 : +.Bd -literal -offset indent +cd /usr/src/bin/ls +make clean all +make install +.Ed +.Ss Example 4: Build and upgrade a loadable kernel module +Rebuild and reinstall a single loadable kernel module, in this case +.Xr sound 4 : +.Bd -literal -offset indent +cd /usr/src/sys/modules/sound +make all install clean cleandepend KMODDIR=/boot/kernel +.Ed +.Ss Example 5: Quickly rebuild a kernel in place +Quickly rebuild and reinstall the kernel, only recompiling the files +changed since last build; note that this will only work if the full +kernel build has been completed in the past, not on a fresh source tree: +.Bd -literal -offset indent +cd /usr/src +make kernel KERNFAST=1 +.Ed +.Ss Example 6: Cross-compiling for different architectures +To rebuild parts of +.Fx +for another CPU architecture, +first prepare your source tree by building the cross-toolchain: +.Bd -literal -offset indent +cd src +make toolchain TARGET_ARCH=aarch64 +.Ed +.Pp +The following sequence of commands can be used to cross-build the system +for the arm64 (aarch64) architecture on a different host architecture, +such as amd64: +.Bd -literal -offset indent +cd /usr/src +make TARGET_ARCH=aarch64 buildworld buildkernel +make TARGET_ARCH=aarch64 DESTDIR=/client installworld installkernel +.Ed +.Pp +Afterwards, to build and install a single piece of userspace, use: +.Bd -literal -offset indent +cd src/bin/ls +make buildenv TARGET_ARCH=aarch64 +make clean all install DESTDIR=/client +.Ed +.Pp +Likewise, to quickly rebuild and reinstall the kernel, use: +.Bd -literal -offset indent +cd src +make buildenv TARGET_ARCH=aarch64 +make kernel KERNFAST=1 DESTDIR=/client +.Ed +.Sh DIAGNOSTICS +.Bl -diag +.It Bad system call (core dumped) +.It rescue/sh check failed, installation aborted +.Pp +The kernel was not updated due to incorrect build procedure. +Study the examples above. +.Sh SEE ALSO +.Xr cc 1 , +.Xr install 1 , +.Xr make 1 , +.Xr make.conf 5 , +.Xr src.conf 5 , +.Xr arch 7 , +.Xr development 7 , +.Xr freebsd-base 7 , +.Xr pkg 7 , +.Xr ports 7 , +.Xr release 7 , +.Xr tests 7 , +.Xr config 8 , +.Xr etcupdate 8 , +.Xr nextboot 8 , +.Xr shutdown 8 +.Sh HISTORY +The +.Nm +manpage first appeared in +.Fx 4.3 . +.Sh AUTHORS +.An Mike W. Meyer Aq Mt mwm@mired.org +.Sh CAVEATS +Old objects can cause obscure build problems; try +.Ql make cleandir cleandir . +.Pp +Environment poisoning can cause obscure build problems; try prefixing +.Xr make 1 +commands with +.Ql env -i +.Pp +When doing a major release upgrade, +booting into single user mode for +.Cm installworld +is required. +.Pp +Updating the boot +.Xr loader 8 +is architecture specific. +Consult +.Xr boot 8 +for your architecture for more details. diff --git a/static/freebsd/man7/c.7 b/static/freebsd/man7/c.7 new file mode 100644 index 00000000..c95bab1c --- /dev/null +++ b/static/freebsd/man7/c.7 @@ -0,0 +1,532 @@ +.\" Copyright (C) 2007, 2010 Gabor Kovesdan. All rights reserved. +.\" Copyright (C) 2021 Faraz Vahedi +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd November 4, 2024 +.Dt C 7 +.Os +.Sh NAME +.Nm c , +.Nm c78 , +.Nm c89 , +.Nm c90 , +.Nm c95 , +.Nm c99 , +.Nm c11 , +.Nm c17 , +.Nm c23 , +.Nm c2y +.Nd The C programming language +.Sh DESCRIPTION +C is a general purpose programming language, which has a strong connection +with the UNIX operating system and its derivatives, since the vast +majority of those systems were written in the C language. +The C language contains some basic ideas from the BCPL language through +the B language written by Ken Thompson in 1970 for the DEC PDP-7 machines. +The development of the UNIX operating system was started on a PDP-7 +machine in assembly language, but it made very difficult to port the existing +code to other systems. +.Pp +In 1972 Dennis M. Ritchie worked out the C programming language for +further development of the UNIX operating system. +The idea was to implement only the C compiler for different +platforms, and implement most part of the operating system +in the new programming language to simplify the portability between +different architectures. +It follows that C is very eligible for (but not limited to) writing +operating systems and low-level applications. +.Pp +The C language did not have a specification or standardized version for +a long time. +It went through a lot of changes and improvements for ages. +In 1978, Brian W. Kernighan and Dennis M. Ritchie published the +first book about C under the title "The C Programming Language". +We can think of this book as the first specification of the language. +This version is often referred as K&R C after the names of the authors. +Sometimes it is referred as C78, as well, after the publishing year of +the first edition of the book. +.Pp +It is important to notice, that the instruction set of the language is +limited to the most fundamental elements for simplicity. +Handling of the standard I/O and such common functions are implemented in +the libraries shipped with the compiler. +As these functions are also widely used, it was demanded to include into +the description what requisites the library should conform to, not just +strictly the language itself. +Accordingly, the aforementioned standards cover the library elements, as well. +The elements of this standard library is still not enough for more +complicated tasks. +In this case the provided system calls of the given operating system can be +used. +To not lose the portability by using these system calls, the POSIX +(Portable Operating System Interface) standard evolved. +It describes what functions should be available to keep portability. +Note, that POSIX is not a C standard, but an operating system standard +and thus is beyond the scope of this manual. +The standards discussed below are all C standards and only cover +the C programming language and the accompanying library. +All listed improvements for each standard edition are taken from the official +standard drafts. +For further details, check the publicly available drafts or +purchase the published standards \(em from either ISO or IEC resources. +.Pp +After the publication of the book mentioned before, +the American National Standards Institute (ANSI) started to work on +standardizing the language, and they announced ANSI X3.159-1989 +in 1989. +It is usually referred to as ANSI C or C89. +The main difference in this standard were the function prototypes, +which is a new way of declaring functions. +With the old-style function declarations, the compiler was unable to +check the sanity of the actual parameters at a function call. +The old syntax was highly error-prone because incompatible parameters +were hard to detect in the program code and the problem only showed up +at run-time. +.Pp +In 1990, the International Organization for Standardization (ISO) adopted +the ANSI standard as ISO/IEC 9899:1990 in 1990. +This is also referred to as ISO C or C90. +It only contains negligible minor modifications against ANSI C, +so the two standards often considered to be fully equivalent. +This was a very important milestone in the history of the C language, but the +development of the language did not stop. +.Pp +The ISO C standard was later extended with an amendment as +ISO/IEC 9899/AMD1 in 1995. +This contained, for example, the wide-character support in +.In wchar.h +and +.In wctype.h , +and also restricted character set support via diagraphs and +.In iso646.h . +This amendment is usually referred to as C95. +Two technical corrigenda were also published: Technical Corrigendum 1 as +ISO/IEC 9899/COR1 in 1994 and Technical Corrigendum 2 as ISO/IEC 9899/COR2 +in 1996. +The continuous development and growth made it necessary to work out a new +standard, which contains the new features and fixes the known defects and +deficiencies of the language. +As a result, ISO/IEC 9899:1999 was born in 1999 as the second edition of the +standard. +Similarly to the other standards, this is informally named after the +publication year as C99. +The improvements include (but are not limited to) the following: +.Bl -bullet -offset indent +.It +digraphs, trigraphs, and alternative spellings for the operators that +use non-ISO646 characters in +.In iso646.h +.It +extended multibyte and wide character library support in +.In wchar.h +and +.In wctype.h +.It +variable length arrays +.It +flexible array members +.It +complex (and imaginary) number arithmetic support in +.In complex.h +.It +type-generic math macros in +.In tgmath.h +.It +the long long int type and library functions +.It +remove implicit int type +.It +universal character names (\eu and \eU) +.It +compound literals +.It +remove implicit function declaration +.It +BCPL style single-line comments +.It +allow mixed declarations and code +.It +the +.Fn vscanf +family of functions in +.In stdio.h +and +.In wchar.h +.It +allow trailing comma in enum declaration +.It +inline functions +.It +the +.Fn snprintf +family of functions in +.In stdio.h +.It +boolean type and macros in +.In stdbool.h +.It +empty macro arguments +.It +_Pragma preprocessing operator +.It +__func__ predefined identifier +.It +va_copy macro in +.In stdarg.h +.It +additional strftime conversion specifiers +.El +.Pp +Later in 2011, the third edition of the standard, ISO/IEC 1989:2011, +commonly referred to as C11 (formerly C1x), came out and replaced the +second edition by ISO/IEC 9899:1999/COR1:2001, ISO/IEC 9899:1999/COR2:2004, +and ISO/IEC 9899:1999/COR3:2007. +The improvements include (but are not limited to) the following: +.Bl -bullet -offset indent +.It +support for multiple threads of execution and atomic operations in +.In threads.h +and +.In stdatomic.h +.It +additional floating-point characteristic macros in +.In float.h +.It +querying and specifying alignment of objects in +.In stdalign.h +and +.In stdlib.h +.It +Unicode character types and functions in +.In uchar.h +.It +type-generic expressions +.It +static assertions in +.In assert.h +.It +anonymous structures and unions +.It +remove the gets function from +.In stdio.h +.It +add the aligned_alloc, at_quick_exit, and quick_exit functions in +.In stdlib.h +.El +.Pp +C11 was later superseded by ISO/IEC 9899:2018, also known as C17 which was +prepared in 2017 and published in June 2018 as the fourth edition. +It incorporates the Technical Corrigendum 1 (ISO/IEC 9899:2011/COR1:2012) +which was published in 2012. +It addressed defects and deficiencies in C11 without introducing new features, +only corrections and clarifications. +.Pp +C23, formally ISO/IEC 9899:2024, is the current standard with significant +updates that supersede C17 (ISO/IEC 9899:2018). +The standardization effort began in 2016, informally as C2x, with the first +WG14 meeting in 2019, and was officially published on October 31, 2024. +C23 was originally anticipated for an earlier release, but the timeline was +extended due to COVID-19 pandemic. +With C23, the value of __STDC_VERSION__ has been updated from 201710L to +202311L. +Key changes include (but are not limited to) the following: +.Bl -bullet -offset indent +.It +Add null pointer type nullptr_t and the nullptr keyword +.It +Add constexpr keyword as a storage-class specifier for objects +.It +Redefine the usage of the auto keyword to support type inference while also +retaining its previous functionality as a storage-class specifier when used +with a type +.It +Add %b binary conversion specifier to the +.Fn printf +and +.Fn scanf +function families +.It +Add binary conversion support (0b and 0B) to the +.Fn strtol +and +.Fn wcstol +function families +.It +Add the #embed directive for binary resource inclusion and __has_embed to +check resource availability with preprocessor directives +.It +Add the #warning directive for diagnostics +.It +Add the #elifdef and #elifndef directives +.It +Add the u8 prefix for character literals to represent UTF-8 encoding, +compatible with C++17 +.It +Add the char8_t type for UTF-8 encoded data and update the types of u8 +character constants and string literals to char8_t +.It +Add functions +.Fn mbrtoc8 +and +.Fn c8rtomb +to convert between narrow multibyte +characters and UTF-8 encoding +.It +Define all char16_t strings and literals as UTF-16 encoded and char32_t +strings and literals as UTF-32 encoded unless specified otherwise +.It +Allow storage-class specifiers within compound literals +.It +Support the latest IEEE 754 standard, ISO/IEC 60559:2020, with binary and +(optional) decimal floating-point arithmetic +.It +Add single-argument _Static_assert for compatibility with C++17 +.It +Add _Decimal32, _Decimal64, _Decimal128 keywords for (optional) decimal +floating-point arithmetic +.It +Add digit separator ' (the single quote character) for literals +.It +Enable specification of the underlying type of an enum +.It +Standardize the +.Fn typeof +operator +.It +Add +.Fn memset_explicit +in +.In string.h +to securely erase sensitive data +regardless of optimizations +.It +Add +.Fn memccpy +in +.In string.h +for efficient string concatenation +.It +Add +.Fn memalignment +in +.In stdlib.h +to determine pointer alignment +.It +Add +.Fn strdup +and +.Fn strndup +in +.In string.h +to allocate string copies +.It +Introduce bit utility functions, macros, and types in the new header +.In stdbit.h +.It +Add +.Fn timegm +in +.In time.h +for converting time structures to calendar time +values +.It +Add __has_include for header availability checking via preprocessor +directives +.It +Add __has_c_attribute to check attribute availability via preprocessor +directives +.It +Add _BitInt(N) and unsigned _BitInt(N) for bit-precise integers, and +BITINT_MAXWIDTH for maximum bit width +.It +Elevate true and false to proper keywords (previously macros from +.In stdbool.h ) +.It +Add keywords alignas, alignof, bool, static_assert, thread_local; previously +defined keywords remain available as alternative spellings +.It +Enable zero initialization with {} (including initialization of VLAs) +.It +Introduce C++11 style attributes using [[]], with adding [[deprecated]], +[[fallthrough]], [[maybe_unused]], [[nodiscard]], and [[noreturn]] +.It +Deprecate _Noreturn, noreturn, header +.In stdnoreturn.h +features introduced +in C11 +.It +Remove trigraph support +.It +Remove K&R function definitions and declarations +.It +Remove non-two's-complement representations for signed integers +.El +.Pp +The next version of the C Standard, informally named C2y, is anticipated +to release within the next six years, targeting 2030 at the latest. +A charter for C2y is still being drafted and discussed, with several +papers under debate from the January 2024 meeting in Strasbourg, France +indicating that this new version may address long-standing requests and +deficiencies noted by the C community, while preserving its core strengths. +.Pp +ISO/IEC JTC1/SC22/WG14 committee is responsible for the ISO/IEC 9899, +C Standard. +.Sh SEE ALSO +.Xr c89 1 , +.Xr c99 1 , +.Xr cc 1 +.Sh STANDARDS +.Rs +.%A ANSI +.%T X3.159-1989 (aka C89 or ANSI C) +.Re +.Pp +.Rs +.%A ISO/IEC +.%T 9899:1990 (aka C90) +.Re +.Pp +.Rs +.%A ISO/IEC +.%T 9899:1990/AMD 1:1995, Amendment 1: C Integrity (aka C95) +.Re +.Pp +.Rs +.%A ISO/IEC +.%T 9899:1990/COR 1:1994, Technical Corrigendum 1 +.Re +.Pp +.Rs +.%A ISO/IEC +.%T 9899:1990/COR 2:1996, Technical Corrigendum 2 +.Re +.Pp +.Rs +.%A ISO/IEC +.%T 9899:1999 (aka C99) +.Re +.Pp +.Rs +.%A ISO/IEC +.%T 9899:1999/COR 1:2001, Technical Corrigendum 1 +.Re +.Pp +.Rs +.%A ISO/IEC +.%T 9899:1999/COR 2:2004, Technical Corrigendum 2 +.Re +.Pp +.Rs +.%A ISO/IEC +.%T 9899:1999/COR 3:2007, Technical Corrigendum 3 +.Re +.Pp +.Rs +.%A ISO/IEC +.%T TR 24731-1:2007 (aka bounds-checking interfaces) +.Re +.Pp +.Rs +.%A ISO/IEC +.%T TS 18037:2008 (aka, embedded C) +.Re +.Pp +.Rs +.%A ISO/IEC +.%T TR 24747:2009 (aka mathematical special functions) +.Re +.Pp +.Rs +.%A ISO/IEC +.%T TR 24732:2009 (aka decimal floating-point) +.Re +.Pp +.Rs +.%A ISO/IEC +.%T TR 24731-2:2010 (aka dynamic allocation functions) +.Re +.Pp +.Rs +.%A ISO/IEC +.%T 9899:2011 (aka C11) +.Re +.Pp +.Rs +.%A ISO/IEC +.%T 9899:2011/COR 1:2012, Technical Corrigendum 1 +.Re +.Pp +.Rs +.%A ISO/IEC +.%T TS 17961:2013 (aka C secure coding rules) +.Re +.Pp +.Rs +.%A ISO/IEC +.%T TS 18861-1:2014 (aka binary floating-point) +.Re +.Pp +.Rs +.%A ISO/IEC +.%T TS 18861-2:2015 (aka decimal floating-point) +.Re +.Pp +.Rs +.%A ISO/IEC +.%T TS 18861-3:2015 (aka interchange and extended types) +.Re +.Pp +.Rs +.%A ISO/IEC +.%T TS 18861-4:2015 (aka supplementary functions) +.Re +.Pp +.Rs +.%A ISO/IEC +.%T TS 17961:2013/COR 1:2016 (aka C secure coding rules TC1) +.Re +.Pp +.Rs +.%A ISO/IEC +.%T TS 18861-5:2016 (aka supplementary attributes) +.Re +.Pp +.Rs +.%A ISO/IEC +.%T 9899:2018 (aka C17) +.Re +.Pp +.Rs +.%A ISO/IEC +.%T 9899:2024 (aka C23) +.Re +.Sh HISTORY +This manual page first appeared in +.Fx 9.0 . +.Sh AUTHORS +.An -nosplit +This manual page was originally written by +.An Gabor Kovesdan Aq Mt gabor@FreeBSD.org . +It was updated by +.An Faraz Vahedi Aq Mt kfv@kfv.io +with information about more recent C standards. diff --git a/static/freebsd/man7/clocks.7 b/static/freebsd/man7/clocks.7 new file mode 100644 index 00000000..26283909 --- /dev/null +++ b/static/freebsd/man7/clocks.7 @@ -0,0 +1,171 @@ +.\" +.\" Copyright (c) 1996 Joerg Wunsch +.\" +.\" 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 18, 2008 +.Dt CLOCKS 7 +.Os +.Sh NAME +.Nm clocks +.Nd various system timers +.Sh SYNOPSIS +.In time.h +.Sh DESCRIPTION +.Dv HZ +is not part of the application interface in +.Bx . +.Pp +There are many different real and virtual (timekeeping) clocks with +different frequencies: +.Bl -bullet +.It +The scheduling clock. +This is a real clock with frequency that happens to be 100. +It is not available to applications. +.It +The statistics clock. +This is a real clock with frequency that happens to be 128. +It is not directly available to applications. +.It +The clock reported by +.Xr clock 3 . +This is a virtual clock with a frequency that happens to be 128. +Its actual frequency is given by the macro +.Dv CLOCKS_PER_SEC . +Note that +.Dv CLOCKS_PER_SEC +may be floating point. +Do not use +.Xr clock 3 +in new programs under +.Fx . +It is feeble compared with +.Xr getrusage 2 . +It is provided for +.Tn ANSI +conformance. +It is implemented by calling +.Xr getrusage 2 +and throwing away information and resolution. +.It +The clock reported by +.Xr times 3 . +This is a virtual clock with a frequency that happens to be 128. +Its actual frequency is given by the macro +.Dv CLK_TCK +(deprecated; do not use) and by +.Fn sysconf _SC_CLK_TCK +and by +.Xr sysctl 3 . +Note that its frequency may be different from +.Dv CLOCKS_PER_SEC . +Do not use +.Xr times 3 +in new programs under +.Fx . +It is feeble compared with +.Xr gettimeofday 2 +together with +.Xr getrusage 2 . +It is provided for +.Tn POSIX +conformance. +It is implemented by calling +.Xr gettimeofday 2 +and +.Xr getrusage 2 +and throwing away information and resolution. +.It +The profiling clock. +This is a real clock with frequency 1024. +It is used mainly by +.Xr moncontrol 3 +and +.Xr gprof 1 . +Applications should determine its actual frequency using +.Xr sysctl 3 +or by reading it from the header in the profiling data file. +.It +The mc146818a clock. +This is a real clock with a nominal frequency of 32768. +It is divided down to give the statistic clock and the profiling clock. +It is not available to applications. +.It +The microseconds clock. +This is a virtual clock with frequency 1000000. +It is used for most timekeeping in +.Bx +and is exported to applications in +.Xr getrusage 2 , +.Xr gettimeofday 2 , +.Xr select 2 , +.Xr getitimer 2 , +etc. +This is the clock that should normally be used by +.Bx +applications. +.It +The i8254 clock. +This is a real clock/timer with a nominal frequency of 1193182. +It has three independent time counters to be used. +It is divided down to give the scheduling clock. +It is not available to applications. +.It +The TSC clock (64-bit register) on fifth-generation or later x86 systems. +This is a real clock with a frequency that is equivalent to the number of +cycles per second of the CPU(s). +Its frequency can be found using the +.Va machdep.tsc_freq +sysctl, if it is available. +It is used to interpolate between values of the scheduling clock. +.It +The ACPI clock. +This is a real clock/timer with a nominal frequency of 3579545. +It is accessed via a 24 or 32 bit register. +Unlike the TSC clock, it maintains a constant tick rate even when the CPU +sleeps or its clock rate changes. +It is not available to applications. +.El +.Pp +Summary: if +.Dv HZ +is not 1000000 then the application is probably using the wrong clock. +.Sh SEE ALSO +.Xr gprof 1 , +.Xr clock_gettime 2 , +.Xr getitimer 2 , +.Xr getrusage 2 , +.Xr gettimeofday 2 , +.Xr select 2 , +.Xr clock 3 , +.Xr moncontrol 3 , +.Xr times 3 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An J\(:org Wunsch +after a description posted by +.An Bruce Evans . diff --git a/static/freebsd/man7/crypto.7 b/static/freebsd/man7/crypto.7 new file mode 100644 index 00000000..37c44156 --- /dev/null +++ b/static/freebsd/man7/crypto.7 @@ -0,0 +1,179 @@ +.\" Copyright (c) 2014-2021 The FreeBSD Foundation +.\" +.\" Portions of this documentation were written by John-Mark Gurney +.\" under the sponsorship of the FreeBSD Foundation and +.\" Rubicon Communications, LLC (Netgate). +.\" +.\" Portions of this documentation were written by Ararat River +.\" Consulting, LLC under sponsorship of the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 11, 2022 +.Dt CRYPTO 7 +.Os +.Sh NAME +.Nm crypto +.Nd OpenCrypto algorithms +.Sh DESCRIPTION +The in-kernel OpenCrypto framework supports several different encryption +and authentication algorithms. +This document describes the parameters and requirements of these algorithms. +Unless otherwise noted, all sizes listed below are in bytes. +.Ss Authenticators +Authenticators compute a value (also known as a digest, hash, or tag) +over an input of bytes. +In-kernel requests can either compute the value for a given input, +or verify if a given tag matches the computed tag for a given input. +The following authentication algorithms are supported: +.Bl -column "CRYPTO_AES_CCM_CBC_MAC" "XXX" "16, 24, 32" "Digest" +.It Sy Name Ta Sy Nonce Ta Sy Key Sizes Ta Sy Digest Ta Sy Description +.It Dv CRYPTO_AES_CCM_CBC_MAC Ta 12 Ta 16, 24, 32 Ta 16 Ta +Authentication-only mode of AES-CCM +.It Dv CRYPTO_AES_NIST_GMAC Ta 12 Ta 16, 24, 32 Ta 16 Ta +Galois message authentication code +.It Dv CRYPTO_BLAKE2B Ta Ta 0, 64 Ta 64 Ta +Blake2b +.It Dv CRYPTO_BLAKE2S Ta Ta 0, 32 Ta 32 Ta +Blake2s +.It Dv CRYPTO_NULL_HMAC Ta Ta Ta 12 Ta +IPsec NULL HMAC +.It Dv CRYPTO_POLY1305 Ta Ta 32 Ta 16 Ta +Poly1305 authenticator +.It Dv CRYPTO_RIPEMD160 Ta Ta Ta 20 Ta +RIPE Message Digest-160 +.It Dv CRYPTO_RIPEMD160_HMAC Ta Ta 64 Ta 20 Ta +RIPE Message Digest-160 HMAC +.It Dv CRYPTO_SHA1 Ta Ta Ta 20 Ta +SHA-1 +.It Dv CRYPTO_SHA1_HMAC Ta Ta 64 Ta 20 Ta +SHA-1 HMAC +.It Dv CRYPTO_SHA2_224 Ta Ta Ta 28 Ta +SHA-2 224 +.It Dv CRYPTO_SHA2_224_HMAC Ta Ta 64 Ta 28 Ta +SHA-2 224 HMAC +.It Dv CRYPTO_SHA2_256 Ta Ta Ta 32 Ta +SHA-2 256 +.It Dv CRYPTO_SHA2_256_HMAC Ta Ta 64 Ta 32 Ta +SHA-2 256 HMAC +.It Dv CRYPTO_SHA2_384 Ta Ta Ta 48 Ta +SHA-2 384 +.It Dv CRYPTO_SHA2_384_HMAC Ta Ta 128 Ta 48 Ta +SHA-2 384 HMAC +.It Dv CRYPTO_SHA2_512 Ta Ta Ta 64 Ta +SHA-2 512 +.It Dv CRYPTO_SHA2_512_HMAC Ta Ta 128 Ta 64 Ta +SHA-2 512 HMAC +.El +.Ss Block Ciphers +Block ciphers in OCF can only operate on messages whose length is an +exact multiple of the cipher's block size. +OCF supports the following block ciphers: +.Bl -column "CRYPTO_CAMELLIA_CBC" "IV Size" "Block Size" "16, 24, 32" +.It Sy Name Ta Sy IV Size Ta Sy Block Size Ta Sy Key Sizes Ta Sy Description +.It Dv CRYPTO_AES_CBC Ta 16 Ta 16 Ta 16, 24, 32 Ta +AES-CBC +.It Dv CRYPTO_AES_XTS Ta 8 Ta 16 Ta 32, 64 Ta +AES-XTS +.It Dv CRYPTO_CAMELLIA_CBC Ta 16 Ta 16 Ta 16, 24, 32 Ta +Camellia CBC +.It Dv CRYPTO_NULL_CBC Ta 0 Ta 4 Ta 0-256 Ta +IPsec NULL cipher +.El +.Pp +.Dv CRYPTO_AES_XTS +implements XEX Tweakable Block Cipher with Ciphertext Stealing +as defined in NIST SP 800-38E. +OCF consumers provide the first 8 bytes of the IV. +The remaining 8 bytes are defined to be a block counter beginning at 0. +.Pp +NOTE: The ciphertext stealing part is not implemented in all backends +which is why this cipher requires input that is a multiple of the block +size. +.Ss Stream Ciphers +Stream ciphers can operate on messages with arbitrary lengths. +OCF supports the following stream ciphers: +.Bl -column "CRYPTO_CHACHA20" "IV Size" "16, 24, 32" +.It Sy Name Ta Sy IV Size Ta Sy Key Sizes Ta Sy Description +.It Dv CRYPTO_AES_ICM Ta 16 Ta 16, 24, 32 Ta +AES Counter Mode +.It Dv CRYPTO_CHACHA20 Ta 16 Ta 16, 32 Ta +ChaCha20 +.El +.Pp +The IV for each request must be provided in +.Fa crp_iv +via the +.Dv CRYPTO_F_IV_SEPARATE +flag. +.Pp +.Dv CRYPTO_AES_ICM +uses the entire IV as a 128-bit big endian block counter. +The IV sets the initial counter value for a message. +If a consumer wishes to use an IV whose value is split into +separate nonce and counter fields (e.g., IPsec), +the consumer is responsible for splitting requests to handle +counter rollover. +.Pp +.Dv CRYPTO_CHACHA20 +accepts a 16 byte IV. +The first 8 bytes are used as a nonce. +The last 8 bytes are used as a 64-bit little-endian block counter. +.Ss Authenticated Encryption with Associated Data Algorithms +AEAD algorithms in OCF combine a stream cipher with an authentication +algorithm to provide both secrecy and authentication. +AEAD algorithms accept additional authentication data (AAD) +in addition to the ciphertext or plaintext. +AAD is passed to the authentication algorithm as input in a method +defined by the specific AEAD algorithm. +.Pp +AEAD algorithms in OCF accept a nonce that is combined with an +algorithm-defined counter to construct the IV for the underlying +stream cipher. +This nonce must be provided in +.Fa crp_iv +via the +.Dv CRYPTO_F_IV_SEPARATE +flag. +Some AEAD algorithms support multiple nonce sizes. +The first size listed is the default nonce size. +.Pp +The following AEAD algorithms are supported: +.Bl -column "CRYPTO_AES_NIST_GCM_16" "12, 7-13" "16, 24, 32" "Tag" +.It Sy Name Ta Sy Nonce Ta Sy Key Sizes Ta Sy Tag Ta Sy Description +.It Dv CRYPTO_AES_NIST_GCM_16 Ta 12 Ta 16, 24, 32 Ta 16 Ta +AES Galois/Counter Mode +.It Dv CRYPTO_AES_CCM_16 Ta 12, 7-13 Ta 16, 24, 32 Ta 16 Ta +AES Counter with CBC-MAC +.It Dv CRYPTO_CHACHA20_POLY1305 Ta 12, 8 Ta 32 Ta 16 Ta +ChaCha20-Poly1305 +.It Dv CRYPTO_XCHACHA20_POLY1305 Ta 24 Ta 32 Ta 16 Ta +XChaCha20-Poly1305 +.El +.Sh SEE ALSO +.Xr crypto 4 , +.Xr crypto 9 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 10.1 . diff --git a/static/freebsd/man7/d.7 b/static/freebsd/man7/d.7 new file mode 100644 index 00000000..59b3389b --- /dev/null +++ b/static/freebsd/man7/d.7 @@ -0,0 +1,413 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> +.\" +.Dd October 28, 2025 +.Dt D 7 +.Os +.Sh NAME +.Nm D +.Nd DTrace scripting language overview +.Sh SYNOPSIS +.Sm off +.Ar provider Cm \&: +.Ar module Cm \&: +.Ar function Cm \&: +.Ar name +.Sm on +.Sm off +.Oo +.Oo +.Cm / +.Ar predicate +.Cm / +.Sm on +.Oc +.Cm \&{ Ns Ar action Ns Cm \&} +.Oc +.Sh DESCRIPTION +.Nm D +is the +.Xr dtrace 1 +scripting language. +This manual provides a brief reference of the +.Nm +language and scripting. +.Pp +This manual page serves as a short reference of the language. +Refer to books listed in +.Sx SEE ALSO +for a complete reference. +.Sh PROBE'S DESCRIPTION +A probe's description consists of four elements: +.Sm off +.D1 Ar provider Ns Cm \&: Ns Ar module Cm \&: Ar function Cm \&: Ar name +.Sm on +.Pp +The exact meaning of +.Ar module , +.Ar function , +and +.Ar name +depends on +.Ar provider . +.Sh USER-DEFINED VARIABLE TYPES +.Bl -column "thread-local" "Syntax" +.It Sy Type Ta Sy Syntax +.It global Ta Va variable_name +.It aggregate Ta Sy @ Ns Va variable_name +.It thread-local Ta Sy self-> Ns Va variable_name +.It clause-local Ta Sy this-> Ns Va variable_name +.El +.Pp +.Em Tips : +.Bl -dash -compact +.It +Always use the variable type with the smallest scope +to minimize processing overhead. +.It +Use aggregate variables instead of global variables when possible. +Aggregate variables are multi-CPU safe in contrast to global variables. +.El +.Sh BUILT-IN VARIABLES +.Ss Probe Arguments +.Bl -tag -width "arg0, ..., arg9" +.It Va args[] +The array of typed probe arguments. +.It Va arg0 , ... , arg9 +The untyped probe arguments represented as 64-bit unsigned integers. +Only the first ten arguments are available this way. +.El +.Ss Probe Information +.Bl -tag -width probeprov +.It Va epid +The enabled probe ID which uniquely identifies an enabled probe. +An enabled probe is defined by its probe ID, its predicates, and its actions. +.It Va id +The probe ID which uniquely identifies a probe available to DTrace. +.It Va probeprov +The +.Ar provider +in the probe's description +.Sm off +.Pq Ar provider Cm \&: Ar module Cm \&: Ar function Cm \&: Ar name +.Sm on . +.It Va probemod +The +.Ar module +in the probe's description +.Sm off +.Pq Ar provider Cm \&: Ar module Cm \&: Ar function Cm \&: Ar name +.Sm on . +.It Va probefunc +The +.Ar function +in the probe's description +.Sm off +.Pq Ar provider Cm \&: Ar module Cm \&: Ar function Cm \&: Ar name +.Sm on . +.It Va probename +The +.Ar name +in the probe's description +.Sm off +.Pq Ar provider Cm \&: Ar module Cm \&: Ar function Cm \&: Ar name +.Sm on . +.El +.Ss Process Information +.Bl -tag -width execname +.It Va execargs +The process arguments. +Effectively, +.Ql curthread->td_proc->p_args . +.It Va execname +The name of the current process. +Effectively, +.Ql curthread->td_proc->p_comm . +.It Va gid +The group ID of the current process. +.It Va pid +The process ID of the current process. +.It Va ppid +The parent process ID of the current process. +.It Va uid +The user ID of the current process. +.El +.Ss Thread Information +.Bl -tag -width curlwpsinfo +.It Va uregs[] +The saved user-mode register values. +.It Va cpu +The ID of the current CPU. +.It Va stackdepth +The kernel stack frame depth. +.It Va ustackdepth +The userspace counterpart of +.Va stackdepth . +.It Va tid +The thread ID. +Depending on the context, +this can be either the ID of a kernel thread or a thread in a user process. +.It Va errno +The +.Xr errno 2 +value of the last system call performed by the current thread. +.It Va curlwpsinfo +A pointer to the +.Vt lwpsinfo_t +representation of the current thread. +Refer to +.Xr dtrace_proc 4 +for more details. +.It Va curpsinfo +A pointer to the +.Vt psinfo_t +representation of the current process. +Refer to +.Xr dtrace_proc 4 +for more details. +.It Va curthread +A pointer to the thread struct that is currently on-CPU. +E.g., +.Ql curthread->td_name +returns the thread name. +The +.In sys/proc.h +header documents all members of +.Vt struct thread . +.It Va caller +The address of the kernel thread instruction at the time of execution +of the current probe. +.It Va ucaller +The userspace counterpart of +.Va caller . +.El +.Ss Timestamps +.Bl -tag -width walltimestamp +.It Va timestamp +The number of nanoseconds since boot. +Suitable for calculating relative time differences of elapsed time and latency. +.It Va vtimestamp +The number of nanoseconds that the current thread spent on CPU. +The counter is not increased during handling of a fired DTrace probe. +Suitable for calculating relative time differences of on-CPU time. +.It Va walltimestamp +The number of nanoseconds since the Epoch +.Pq 1970-01-01T00+00:00 . +Suitable for timestamping logs. +.El +.Sh BUILT-IN FUNCTIONS +.\" Keep the indentation wide enough for the reader to be able to skim through +.\" function names quickly. +.Bl -tag -width "size_t strlen" +.It Ft string Fn strchr "string s" "char c" +Return a substring of +.Fa s +starting at the first occurance of +.Fa c +in +.Fa s . +Return +.Dv NULL +if +.Fa c +does not occur in +.Fa s . +.Pp +For example, +.Bd -literal -compact -offset indent +strchr("abc", 'b'); +.Ed +returns +.Ql "bc" +and +.Bd -literal -compact -offset indent +strchr("abc", 'd'); +.Ed +returns +.Dv NULL . +.It Ft string Fn strjoin "string s1" "string s2" +Return a string resulting from concatenating +.Fa s1 +and +.Fa s2 . +.Pp +For example, +.Bd -literal -compact -offset indent +strjoin("abc", "def") +.Ed +returns +.Ql abcdef . +.It Ft string Fn strrchr "string s" "char c" +Return a substring of +.Fa s +starting at the last occurance of +.Fa c +in +.Fa s . +Similar to +.Fn strchr . +.It Ft string Fn strstr "string haystack" "string needle" +Return a substring of +.Fa haystack +starting at the first occurrence of +.Fa needle . +Return +.Dv NULL +if +.Fa needle +is not a substring of +.Fa haystack . +.Pp +For example, +.Bd -literal -compact -offset indent +strstr("abc1bc2", "bc") +.Ed +returns +.Ql bc1bc2 +and +.Bd -literal -compact -offset indent +strstr("abc", "xy") +.Ed +returns +.Dv NULL . +.It Ft string Fn strtok "string s" "string separators" +Tokenize +.Fa s +with +.Fa separators . +.Pp +For example, +.Bd -literal -compact -offset indent +strtok("abcdefg", "xyzd") +.Ed +returns +.Ql abc . +.It Ft size_t Fn strlen "string s" +Return the length of string +.Fa s . +.It Ft string Fn substr "string s" "int position" "[int length]" +Return a +substring of string +.Fa s +starting at +.Fa position . +The substring will be at most +.Fa length Ns -long . +If +.Fa length +is not specified, use the rest of the string. +If +.Fa position +is greater than +the size of +.Fa s , +return an empty string. +.Pp +For example, +.Bd -literal -compact -offset indent +substr("abcd", 2) +.Ed +returns +.Ql cd , +.Bd -literal -compact -offset indent +substr("abcd", 2, 1) +.Ed +returns +.Ql c , +and +.Bd -literal -compact -offset indent +substr("abcd", 99) +.Ed +returns an empty string. +.El +.Ss Aggregation Functions +.Bl -tag -compact -width "llquantize(value, factor, low, high, nsteps)" +.It Fn avg value +Average +.It Fn count +Count +.It Fn llquantize value factor low high nsteps +Log-linear quantization +.It Fn lquantize value low high nsteps +Linear quantization +.It Fn max value +Maximum +.It Fn min value +Minimum +.It Fn quantize value +Power-of-two frequency distribution +.It Fn stddev value +Standard deviation +.It Fn sum value +Sum +.El +.Ss Kernel Destructive Functions +By default, +.Xr dtrace 1 +does not permit the use of destructive actions. +.Bl -tag -width "chill(nanoseconds)" +.It Fn breakpoint +Set a kernel breakpoint and transfer control to +the +.Xr ddb 4 +kernel debugger. +.It Fn chill nanoseconds +Spin on the CPU for the specified number of +.Fa nanoseconds . +.It Fn panic +Panic the kernel. +.El +.Sh FILES +.Bl -tag -width /usr/share/dtrace +.It Pa /usr/share/dtrace +DTrace scripts shipped with +.Fx +base. +.El +.Sh SEE ALSO +.Xr awk 1 , +.Xr dtrace 1 , +.Xr tracing 7 +.Rs +.%B The illumos Dynamic Tracing Guide +.%D 2008 +.%U https://illumos.org/books/dtrace/ +.Re +.Rs +.%A Brendan Gregg +.%A Jim Mauro +.%B DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD +.%I Prentice Hall +.%D 2011 +.%U https://www.brendangregg.com/dtracebook/ +.Re +.Rs +.%A George Neville-Neil +.%A Jonathan Anderson +.%A Graeme Jenkinson +.%A Brian Kidney +.%A Domagoj Stolfa +.%A Arun Thomas +.%A Robert N. M. Watson +.%C Cambridge, United Kingdom +.%D August 2018 +.%T Univeristy of Cambridge Computer Laboratory +.%R OpenDTrace Specification version 1.0 +.%U https://www.cl.cam.ac.uk/techreports/UCAM-CL-TR-924.pdf +.Re +.Sh HISTORY +This manual page first appeared in +.Fx 15.0 . +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . +.Sh BUGS +The +.Va cwd +variable which typically provides the current working directory is +not supported on +.Fx +at the moment. diff --git a/static/freebsd/man7/development.7 b/static/freebsd/man7/development.7 new file mode 100644 index 00000000..c64e9fa3 --- /dev/null +++ b/static/freebsd/man7/development.7 @@ -0,0 +1,188 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2018 Edward Tomasz Napierala +.\" +.\" 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 AUTHORS 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 AUTHORS 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 September 24, 2025 +.Dt DEVELOPMENT 7 +.Os +.Sh NAME +.Nm development +.Nd introduction to +.Fx +development process +.Sh DESCRIPTION +.Fx +development is split into three major subprojects: doc, ports, and src. +Doc is the documentation, such as the +.Fx +Handbook. +To read more, see: +.Pp +.Lk https://docs.FreeBSD.org/en/books/fdp-primer/ +.Pp +Ports, described further in +.Xr ports 7 , +are the way to build, package, and install third party software. +To read more, see: +.Pp +.Lk https://docs.FreeBSD.org/en/books/porters-handbook/ +.Pp +The last one, src, revolves around the source code for the base system, +consisting of the kernel, and the libraries and utilities commonly called +the world. +.Pp +The Committer's Guide, describing topics relevant to all committers, +can be found at: +.Pp +.Lk https://docs.freebsd.org/en/articles/committers-guide/ +.Pp +.Fx +src development takes place in the project-hosted +Git repository, located at: +.Pp +.Lk https://git.FreeBSD.org/src.git +.Pp +The push URL is: +.Pp +.Lk ssh://git@gitrepo.FreeBSD.org/src.git +.Pp +There is also a list of public, read-only Git mirrors at: +.Pp +.Lk https://docs.FreeBSD.org/en/books/handbook/mirrors/#external-mirrors +.Pp +The +.Ql main +Git branch represents CURRENT; +all changes are first committed to CURRENT and then usually +cherry-picked back to STABLE, which refers to Git branches such as +.Ql stable/14 . +Every few years a new STABLE is branched from CURRENT, +with an incremented major version number. +Releases are then branched off STABLE and numbered with consecutive +minor numbers such as +.Ql releng/14.3 +.Pp +The layout of the source tree is described in its +.Pa README.md +file. +Build instructions can be found in +.Xr build 7 +and +.Xr release 7 . +Kernel programming interfaces (KPIs) are documented in section 9 +manual pages; use +.Ql apropos -s 9 \&. +for a list. +Regression test suite is described in +.Xr tests 7 . +For coding conventions, see +.Xr style 9 . +.Pp +To ask questions regarding development, use the mailing lists, +such as freebsd-arch@ and freebsd-hackers@: +.Pp +.Lk https://lists.FreeBSD.org +.Pp +To get your patches integrated into the main +.Fx +repository use Phabricator; +it is a code review tool that allows other developers to +review the changes, suggest improvements, and, eventually, +allows them to pick up the change and commit it: +.Pp +.Lk https://reviews.FreeBSD.org +.Pp +Or Github: +.Pp +.Lk https://github.com/freebsd +.Pp +To check the latest +.Fx +build and test status of CURRENT and STABLE branches, +the continuous integration system is at: +.Pp +.Lk https://ci.FreeBSD.org +.Sh FILES +.Bl -tag -compact -width "/usr/src/tools/tools/git/git-arc.sh" +.It Pa /usr/src/CONTRIBUTING.md +.Fx +contribution guidelines +.It Pa /usr/src/tools/tools/git/git-arc.sh +Phabricator review tooling +.It Pa /usr/ports/devel/freebsd-git-arc +Phabricator review tooling as a port +.El +.Sh EXAMPLES +Apply a patch from Github pull #1234, using +.Pa devel/gh : +.Pp +.Dl gh pr checkout 1234 +.Pp +Apply a patch from Phabricator review D1234, using +.Xr git-arc 1 : +.Pp +.Dl git arc patch -c D1234 +.Pp +Apply a manually downloaded +.Xr git-format-patch 1 , +.Pa draft.patch , +from Bugzilla or mail: +.Pp +.Dl git am draft.patch +.Pp +Apply a manually downloaded patch, +.Pa draft.diff , +from Bugzilla or mail: +.Pp +.Dl git apply draft.diff +.Sh SEE ALSO +.Xr git 1 , +.Xr git-arc 1 , +.Xr witness 4 , +.Xr build 7 , +.Xr hier 7 , +.Xr ports 7 , +.Xr release 7 , +.Xr tests 7 , +.Xr locking 9 , +.Xr style 9 +.Sh HISTORY +The +.Nm +manual page was originally written by +.An Matthew Dillon Aq Mt dillon@FreeBSD.org +and first appeared in +.Fx 5.0 , +December 2002. +It was since extensively modified by +.An Eitan Adler Aq Mt eadler@FreeBSD.org +to reflect the repository conversion from +.Lk https://www.nongnu.org/cvs/ CVS +to +.Lk https://subversion.apache.org/ Subversion . +It was rewritten from scratch by +.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org +for +.Fx 12.0 . diff --git a/static/freebsd/man7/environ.7 b/static/freebsd/man7/environ.7 new file mode 100644 index 00000000..ada2cc45 --- /dev/null +++ b/static/freebsd/man7/environ.7 @@ -0,0 +1,333 @@ +.\" Copyright (c) 1983, 1990, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 September 3, 2023 +.Dt ENVIRON 7 +.Os +.Sh NAME +.Nm environ +.Nd user environment +.Sh SYNOPSIS +.Ar extern char **environ ; +.Sh DESCRIPTION +An array of strings, called the +.Ar environment +is made available to each process by +.Xr execve 2 +when a process begins. +By convention these strings have the form +.Va name Ns No = Ns Ar value , +and are referred to as +.Dq environment variables . +A process can query, update, and delete these strings using the +.Xr getenv 3 , +.Xr setenv 3 , +and +.Xr unsetenv 3 +functions, respectively. +The shells also provide commands to manipulate the environment; +they are described in the respective shell manual pages. +.Pp +What follows is a list of environment variables typically +seen on a +.Ux +system. +It includes only those variables that a user can expect to see during their +day-to-day use of the system, and is far from complete. +Environment variables specific to a particular program or library function +are documented in the +.Sx ENVIRONMENT +section of the appropriate manual page. +.Sh ENVIRONMENT +.Bl -tag -width LD_LIBRARY_PATH +.It Ev ARCHLEVEL +On +.Em amd64 , +controls the level of SIMD enhancements used. +See +.Xr simd 7 +for details. +.It Ev BLOCKSIZE +The size of the block units used by several disk-related commands, +most notably +.Xr df 1 , +.Xr du 1 +and +.Xr ls 1 . +.Ev BLOCKSIZE +may be specified in units of a byte by specifying a number, +in units of a kilobyte by specifying a number followed by +.Ql K +or +.Ql k , +in units of a megabyte by specifying a number followed by +.Ql M +or +.Ql m , +and in units of a gigabyte by specifying a number followed +by +.Ql G +or +.Ql g . +Sizes less than 512 bytes or greater than a gigabyte are ignored. +This variable is processed by the +.Xr getbsize 3 +function. +.It Ev COLUMNS +The user's preferred width in column positions for the terminal. +Utilities such as +.Xr ls 1 +and +.Xr who 1 +use this to format output into columns. +If unset or empty, utilities will use an +.Xr ioctl 2 +call to ask the terminal driver for the width. +.It Ev EDITOR +Default editor name. +.It Ev EXINIT +A startup list of commands read by +.Xr ex 1 +and +.Xr vi 1 . +.It Ev EXTERROR_VERBOSE +Request the +.Xr err 3 +and +.Xr uexterr_gettext +functions to unconditionally report additional information, +mostly useful for the (kernel) developer to diagnose the issue. +See +.Xr err 3 +and +.Xr exterror 9 +for more details. +.It Ev HOME +A user's login directory, set by +.Xr login 1 +from the password file +.Xr passwd 5 . +.It Ev LANG +This variable configures all programs which use +.Xr setlocale 3 +to use the specified locale unless the +.Ev LC_* +variables are set. +.It Ev LC_ALL +Overrides the values of +.Ev LC_COLLATE , +.Ev LC_CTYPE , +.Ev LC_MESSAGES , +.Ev LC_MONETARY , +.Ev LC_NUMERIC , +.Ev LC_TIME +and +.Ev LANG . +.It Ev LC_COLLATE +Locale to be used for ordering of strings. +.It Ev LC_CTYPE +Locale to be used for character classification +(letter, space, digit, etc.) and for interpreting byte sequences as +multibyte characters. +.It Ev LC_MESSAGES +Locale to be used for diagnostic messages. +.It Ev LC_MONETARY +Locale to be used for interpreting monetary input +and formatting output. +.It Ev LC_NUMERIC +Locale to be used for interpreting numeric input and +formatting output. +.It Ev LC_TIME +Locale to be used for interpreting dates input and +for formatting output. +.It Ev MAIL +The location of the user's +mailbox instead of the default in /var/mail, +used by +.Xr mail 1 , +.Xr sh 1 , +and many other mail clients. +.It Ev MANPATH +The sequence of directories, separated by colons, searched by +.Xr man 1 +when looking for manual pages. +.It Ev NLSPATH +List of directories to be searched for the message catalog referred to by +.Ev LC_MESSAGES . +See +.Xr catopen 3 . +.It Ev PAGER +Default paginator program. +The program specified by this variable is used by +.Xr mail 1 , +.Xr man 1 , +.Xr ftp 1 , +etc, to display information which is longer than the current display. +.It Ev PATH +The sequence of directories, separated by colons, searched by +.Xr csh 1 , +.Xr sh 1 , +.Xr system 3 , +.Xr execvp 3 , +etc, when looking for an executable file. +.Ev PATH +is set to ``/usr/bin:/bin'' initially by +.Xr login 1 . +.It Ev POSIXLY_CORRECT +When set to any value, this environment variable modifies the behaviour +of certain commands to (mostly) execute in a strictly POSIX-compliant manner. +.It Ev PRINTER +The name of the default printer to be used by +.Xr lpr 1 , +.Xr lpq 1 , +and +.Xr lprm 1 . +.It Ev PWD +The current directory pathname. +.It Ev SHELL +The full pathname of the user's login shell. +.It Ev TERM +The kind of terminal for which output is to be prepared. +This information is used by commands, such as +.Xr nroff 1 Pq Pa ports/textproc/groff +or +.Xr plot 1 +which may exploit special terminal capabilities. +See +.Pa /usr/share/misc/termcap +.Pq Xr termcap 5 +for a list of terminal types. +.It Ev TERMCAP +The string describing the terminal in +.Ev TERM , +or, if +it begins with a '/', the name of the termcap file. +See +.Ev TERMPATH +below, and +.Xr termcap 5 . +.It Ev TERMPATH +A sequence of pathnames of termcap files, separated by colons or spaces, +which are searched for terminal descriptions in the order listed. +Having +no +.Ev TERMPATH +is equivalent to a +.Ev TERMPATH +of +.Pa $HOME/.termcap:/etc/termcap . +.Ev TERMPATH +is ignored if +.Ev TERMCAP +contains a full pathname. +.It Ev TMPDIR +The directory in which to store temporary files. +Most applications use either +.Pa /tmp +or +.Pa /var/tmp . +Setting this variable will make them use another directory. +.It Ev TZ +The timezone to use when displaying dates. +The normal format is a pathname relative to +.Pa /usr/share/zoneinfo . +For example, the command +.Pp +.Dl env TZ=America/Los_Angeles date +.Pp +displays the current time in California. +See +.Xr tzset 3 +for more information. +.It Ev USER +The login name of the user. +It is recommended that portable applications use +.Ev LOGNAME +instead. +.El +.Pp +Further names may be placed in the environment by the +.Ic export +command and +.Ar name=value +arguments in +.Xr sh 1 , +or by the +.Ic setenv +command if you use +.Xr csh 1 . +It is unwise to change certain +.Xr sh 1 +variables that are frequently exported by +.Pa .profile +files, such as +.Ev MAIL , +.Ev PS1 , +.Ev PS2 , +and +.Ev IFS , +unless you know what you are doing. +.Pp +The current environment variables can be printed with +.Xr env 1 , +.Xr set 1 +or +.Xr printenv 1 +in +.Xr sh 1 +and +.Xr env 1 , +.Xr printenv 1 +or the +.Cm printenv +built-in command in +.Xr csh 1 . +.Sh SEE ALSO +.Xr cd 1 , +.Xr csh 1 , +.Xr env 1 , +.Xr err 3 , +.Xr ex 1 , +.Xr login 1 , +.Xr printenv 1 , +.Xr sh 1 , +.Xr execve 2 , +.Xr execle 3 , +.Xr getbsize 3 , +.Xr getenv 3 , +.Xr setenv 3 , +.Xr setlocale 3 , +.Xr system 3 , +.Xr termcap 3 , +.Xr termcap 5 , +.Xr simd 7 , +.Xr exterror 9 +.Sh HISTORY +The +.Nm +manual page appeared in +.At v7 . diff --git a/static/freebsd/man7/firewall.7 b/static/freebsd/man7/firewall.7 new file mode 100644 index 00000000..041c66bd --- /dev/null +++ b/static/freebsd/man7/firewall.7 @@ -0,0 +1,440 @@ +.\" Copyright (C) 2001 Matthew Dillon. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd May 26, 2001 +.Dt FIREWALL 7 +.Os +.Sh NAME +.Nm firewall +.Nd simple firewalls under FreeBSD +.Sh FIREWALL BASICS +A Firewall is most commonly used to protect an internal network +from an outside network by preventing the outside network from +making arbitrary connections into the internal network. +Firewalls +are also used to prevent outside entities from spoofing internal +IP addresses and to isolate services such as NFS or SMBFS (Windows +file sharing) within LAN segments. +.Pp +The +.Fx +firewalling system also has the capability to limit bandwidth using +.Xr dummynet 4 . +This feature can be useful when you need to guarantee a certain +amount of bandwidth for a critical purpose. +For example, if you +are doing video conferencing over the Internet via your +office T1 (1.5 MBits/s), you may wish to bandwidth-limit all other +T1 traffic to 1 MBit/s in order to reserve at least 0.5 MBits +for your video conferencing connections. +Similarly if you are +running a popular web or ftp site from a colocation facility +you might want to limit bandwidth to prevent excessive bandwidth +charges from your provider. +.Pp +Finally, +.Fx +firewalls may be used to divert packets or change the next-hop +address for packets to help route them to the correct destination. +Packet diversion is most often used to support NAT (network +address translation), which allows an internal network using +a private IP space to make connections to the outside for browsing +or other purposes. +.Pp +Constructing a firewall may appear to be trivial, but most people +get them wrong. +The most common mistake is to create an exclusive +firewall rather than an inclusive firewall. +An exclusive firewall +allows all packets through except for those matching a set of rules. +An inclusive firewall allows only packets matching the ruleset +through. +Inclusive firewalls are much, much safer than exclusive +firewalls but a tad more difficult to build properly. +The +second most common mistake is to blackhole everything except the +particular port you want to let through. +TCP/IP needs to be able +to get certain types of ICMP errors to function properly - for +example, to implement MTU discovery. +Also, a number of common +system daemons make reverse connections to the +.Sy auth +service in an attempt to authenticate the user making a connection. +Auth is rather dangerous but the proper implementation is to return +a TCP reset for the connection attempt rather than simply blackholing +the packet. +We cover these and other quirks involved with constructing +a firewall in the sample firewall section below. +.Sh IPFW KERNEL CONFIGURATION +You do not need to create a custom kernel to use the IP firewalling features. +If you enable firewalling in your +.Pa /etc/rc.conf +(see below), the ipfw kernel module will be loaded automatically +when necessary. +However, +if you are paranoid you can compile IPFW directly into the +.Fx +kernel by using the +.Sy IPFIREWALL +option set. +If compiled in the kernel, ipfw denies all +packets by default, which means that, if you do not load in +a permissive ruleset via +.Pa /etc/rc.conf , +rebooting into your new kernel will take the network offline. +This can prevent you from being able to access your system if you +are not sitting at the console. +It is also quite common to +update a kernel to a new release and reboot before updating +the binaries. +This can result in an incompatibility between +the +.Xr ipfw 8 +program and the kernel which prevents it from running in the +boot sequence, also resulting in an inaccessible machine. +Because of these problems the +.Sy IPFIREWALL_DEFAULT_TO_ACCEPT +kernel option is also available which changes the default firewall +to pass through all packets. +Note, however, that using this option +may open a small window of opportunity during booting where your +firewall passes all packets. +Still, it is a good option to use +while getting up to speed with +.Fx +firewalling. +Get rid of it once you understand how it all works +to close the loophole, though. +There is a third option called +.Sy IPDIVERT +which allows you to use the firewall to divert packets to a user program +and is necessary if you wish to use +.Xr natd 8 +to give private internal networks access to the outside world. +If you want to be able to limit the bandwidth used by certain types of +traffic, the +.Sy DUMMYNET +option must be used to enable +.Em ipfw pipe +rules. +.Sh SAMPLE IPFW-BASED FIREWALL +Here is an example ipfw-based firewall taken from a machine with three +interface cards. +fxp0 is connected to the 'exposed' LAN. +Machines +on this LAN are dual-homed with both internal 10.\& IP addresses and +Internet-routed IP addresses. +In our example, 192.100.5.x represents +the Internet-routed IP block while 10.x.x.x represents the internal +networks. +While it is not relevant to the example, 10.0.1.x is +assigned as the internal address block for the LAN on fxp0, 10.0.2.x +for the LAN on fxp1, and 10.0.3.x for the LAN on fxp2. +.Pp +In this example we want to isolate all three LANs from the Internet +as well as isolate them from each other, and we want to give all +internal addresses access to the Internet through a NAT gateway running +on this machine. +To make the NAT gateway work, the firewall machine +is given two Internet-exposed addresses on fxp0 in addition to an +internal 10.\& address on fxp0: one exposed address (not shown) +represents the machine's official address, and the second exposed +address (192.100.5.5 in our example) represents the NAT gateway +rendezvous IP. +We make the example more complex by giving the machines +on the exposed LAN internal 10.0.0.x addresses as well as exposed +addresses. +The idea here is that you can bind internal services +to internal addresses even on exposed machines and still protect +those services from the Internet. +The only services you run on +exposed IP addresses would be the ones you wish to expose to the +Internet. +.Pp +It is important to note that the 10.0.0.x network in our example +is not protected by our firewall. +You must make sure that your +Internet router protects this network from outside spoofing. +Also, in our example, we pretty much give the exposed hosts free +reign on our internal network when operating services through +internal IP addresses (10.0.0.x). +This is somewhat of security +risk: what if an exposed host is compromised? +To remove the +risk and force everything coming in via LAN0 to go through +the firewall, remove rules 01010 and 01011. +.Pp +Finally, note that the use of internal addresses represents a +big piece of our firewall protection mechanism. +With proper +spoofing safeguards in place, nothing outside can directly +access an internal (LAN1 or LAN2) host. +.Bd -literal +# /etc/rc.conf +# +firewall_enable="YES" +firewall_type="/etc/ipfw.conf" + +# temporary port binding range let +# through the firewall. +# +# NOTE: heavily loaded services running through the firewall may require +# a larger port range for local-size binding. 4000-10000 or 4000-30000 +# might be a better choice. +ip_portrange_first=4000 +ip_portrange_last=5000 +\&... +.Ed +.Bd -literal +# /etc/ipfw.conf +# +# FIREWALL: the firewall machine / nat gateway +# LAN0 10.0.0.X and 192.100.5.X (dual homed) +# LAN1 10.0.1.X +# LAN2 10.0.2.X +# sw: ethernet switch (unmanaged) +# +# 192.100.5.x represents IP addresses exposed to the Internet +# (i.e. Internet routeable). 10.x.x.x represent internal IPs +# (not exposed) +# +# [LAN1] +# ^ +# | +# FIREWALL -->[LAN2] +# | +# [LAN0] +# | +# +--> exposed host A +# +--> exposed host B +# +--> exposed host C +# | +# INTERNET (secondary firewall) +# ROUTER +# | +# [Internet] +# +# NOT SHOWN: The INTERNET ROUTER must contain rules to disallow +# all packets with source IP addresses in the 10. block in order +# to protect the dual-homed 10.0.0.x block. Exposed hosts are +# not otherwise protected in this example - they should only bind +# exposed services to exposed IPs but can safely bind internal +# services to internal IPs. +# +# The NAT gateway works by taking packets sent from internal +# IP addresses to external IP addresses and routing them to natd, which +# is listening on port 8668. This is handled by rule 00300. Data coming +# back to natd from the outside world must also be routed to natd using +# rule 00301. To make the example interesting, we note that we do +# NOT have to run internal requests to exposed hosts through natd +# (rule 00290) because those exposed hosts know about our +# 10. network. This can reduce the load on natd. Also note that we +# of course do not have to route internal<->internal traffic through +# natd since those hosts know how to route our 10. internal network. +# The natd command we run from /etc/rc.local is shown below. See +# also the in-kernel version of natd, ipnat. +# +# natd -s -u -a 208.161.114.67 +# +# +add 00290 skipto 1000 ip from 10.0.0.0/8 to 192.100.5.0/24 +add 00300 divert 8668 ip from 10.0.0.0/8 to not 10.0.0.0/8 +add 00301 divert 8668 ip from not 10.0.0.0/8 to 192.100.5.5 + +# Short cut the rules to avoid running high bandwidths through +# the entire rule set. Allow established tcp connections through, +# and shortcut all outgoing packets under the assumption that +# we need only firewall incoming packets. +# +# Allowing established tcp connections through creates a small +# hole but may be necessary to avoid overloading your firewall. +# If you are worried, you can move the rule to after the spoof +# checks. +# +add 01000 allow tcp from any to any established +add 01001 allow all from any to any out via fxp0 +add 01001 allow all from any to any out via fxp1 +add 01001 allow all from any to any out via fxp2 + +# Spoof protection. This depends on how well you trust your +# internal networks. Packets received via fxp1 MUST come from +# 10.0.1.x. Packets received via fxp2 MUST come from 10.0.2.x. +# Packets received via fxp0 cannot come from the LAN1 or LAN2 +# blocks. We cannot protect 10.0.0.x here, the Internet router +# must do that for us. +# +add 01500 deny all from not 10.0.1.0/24 in via fxp1 +add 01500 deny all from not 10.0.2.0/24 in via fxp2 +add 01501 deny all from 10.0.1.0/24 in via fxp0 +add 01501 deny all from 10.0.2.0/24 in via fxp0 + +# In this example rule set there are no restrictions between +# internal hosts, even those on the exposed LAN (as long as +# they use an internal IP address). This represents a +# potential security hole (what if an exposed host is +# compromised?). If you want full restrictions to apply +# between the three LANs, firewalling them off from each +# other for added security, remove these two rules. +# +# If you want to isolate LAN1 and LAN2, but still want +# to give exposed hosts free reign with each other, get +# rid of rule 01010 and keep rule 01011. +# +# (commented out, uncomment for less restrictive firewall) +#add 01010 allow all from 10.0.0.0/8 to 10.0.0.0/8 +#add 01011 allow all from 192.100.5.0/24 to 192.100.5.0/24 +# + +# SPECIFIC SERVICES ALLOWED FROM SPECIFIC LANS +# +# If using a more restrictive firewall, allow specific LANs +# access to specific services running on the firewall itself. +# In this case we assume LAN1 needs access to filesharing running +# on the firewall. If using a less restrictive firewall +# (allowing rule 01010), you do not need these rules. +# +add 01012 allow tcp from 10.0.1.0/8 to 10.0.1.1 139 +add 01012 allow udp from 10.0.1.0/8 to 10.0.1.1 137,138 + +# GENERAL SERVICES ALLOWED TO CROSS INTERNAL AND EXPOSED LANS +# +# We allow specific UDP services through: DNS lookups, ntalk, and ntp. +# Note that internal services are protected by virtue of having +# spoof-proof internal IP addresses (10. net), so these rules +# really only apply to services bound to exposed IPs. We have +# to allow UDP fragments or larger fragmented UDP packets will +# not survive the firewall. +# +# If we want to expose high-numbered temporary service ports +# for things like DNS lookup responses we can use a port range, +# in this example 4000-65535, and we set to /etc/rc.conf variables +# on all exposed machines to make sure they bind temporary ports +# to the exposed port range (see rc.conf example above) +# +add 02000 allow udp from any to any 4000-65535,domain,ntalk,ntp +add 02500 allow udp from any to any frag + +# Allow similar services for TCP. Again, these only apply to +# services bound to exposed addresses. NOTE: we allow 'auth' +# through but do not actually run an identd server on any exposed +# port. This allows the machine being authed to respond with a +# TCP RESET. Throwing the packet away would result in delays +# when connecting to remote services that do reverse ident lookups. +# +# Note that we do not allow tcp fragments through, and that we do +# not allow fragments in general (except for UDP fragments). We +# expect the TCP mtu discovery protocol to work properly so there +# should be no TCP fragments. +# +add 03000 allow tcp from any to any http,https +add 03000 allow tcp from any to any 4000-65535,ssh,smtp,domain,ntalk +add 03000 allow tcp from any to any auth,pop3,ftp,ftp-data + +# It is important to allow certain ICMP types through, here is a list +# of general ICMP types. Note that it is important to let ICMP type 3 +# through. +# +# 0 Echo Reply +# 3 Destination Unreachable (used by TCP MTU discovery, aka +# packet-too-big) +# 4 Source Quench (typically not allowed) +# 5 Redirect (typically not allowed - can be dangerous!) +# 8 Echo +# 11 Time Exceeded +# 12 Parameter Problem +# 13 Timestamp +# 14 Timestamp Reply +# +# Sometimes people need to allow ICMP REDIRECT packets, which is +# type 5, but if you allow it make sure that your Internet router +# disallows it. + +add 04000 allow icmp from any to any icmptypes 0,3,8,11,12,13,14 + +# log any remaining fragments that get through. Might be useful, +# otherwise do not bother. Have a final deny rule as a safety to +# guarantee that your firewall is inclusive no matter how the kernel +# is configured. +# +add 05000 deny log ip from any to any frag +add 06000 deny all from any to any +.Ed +.Sh PORT BINDING INTERNAL AND EXTERNAL SERVICES +We have mentioned multi-homing hosts and binding services to internal or +external addresses but we have not really explained it. +When you have a +host with multiple IP addresses assigned to it, you can bind services run +on that host to specific IPs or interfaces rather than all IPs. +Take +the firewall machine for example: with three interfaces +and two exposed IP addresses +on one of those interfaces, the firewall machine is known by 5 different +IP addresses (10.0.0.1, 10.0.1.1, 10.0.2.1, 192.100.5.5, and say +192.100.5.1). +If the firewall is providing file sharing services to the +windows LAN segment (say it is LAN1), you can use samba's 'bind interfaces' +directive to specifically bind it to just the LAN1 IP address. +That +way the file sharing services will not be made available to other LAN +segments. +The same goes for NFS. +If LAN2 has your UNIX engineering +workstations, you can tell nfsd to bind specifically to 10.0.2.1. +You +can specify how to bind virtually every service on the machine and you +can use a light +.Xr jail 8 +to indirectly bind services that do not otherwise give you the option. +.Sh SEE ALSO +.Xr dummynet 4 , +.Xr ipnat 5 , +.Xr rc.conf 5 , +.Xr smb.conf 5 Pq Pa ports/net/samba , +.Xr samba 7 Pq Pa ports/net/samba , +.Xr config 8 , +.Xr ipfw 8 , +.Xr ipnat 8 , +.Xr jail 8 , +.Xr natd 8 , +.Xr nfsd 8 +.Sh ADDITIONAL READING +.Bl -tag -width indent +.It Nm Ipfilter +.Xr ipf 5 , +.Xr ipf 8 , +.Xr ipfstat 8 +.It Nm Packet Filter +.Xr pf.conf 5 , +.Xr pfctl 8 , +.Xr pflogd 8 +.El +.Sh HISTORY +The +.Nm +manual page was originally written by +.An Matthew Dillon +and first appeared +in +.Fx 4.3 , +May 2001. diff --git a/static/freebsd/man7/freebsd-base.7 b/static/freebsd/man7/freebsd-base.7 new file mode 100644 index 00000000..51de679e --- /dev/null +++ b/static/freebsd/man7/freebsd-base.7 @@ -0,0 +1,264 @@ +.\" SPDX-License-Identifier: ISC +.\" +.\" Copyright (c) 2025 Lexi Winter. +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd April 14, 2026 +.Dt FREEBSD-BASE 7 +.Os +.Sh NAME +.\" .Nm pkgbase +.Nm freebsd-base +.Nd base system packages +.Sh DESCRIPTION +The +.Fx +base system may be installed as a set of +.Xr pkg 8 +packages, which supersedes the traditional method of installing using +.Xr tar 1 +archives. +.Pp +All base packages have names beginning with the string +.Dq "FreeBSD-" , +and have an origin beginning with +.Dq base/ . +In the default system configuration, the repository containing these +packages is called +.Dq FreeBSD-base , +but any name may be used. +The repository name can be used with +.Xr pkg 8 +to restrict package operations to the base system packages. +.Pp +Packages for all supported +.Fx +releases as well as active +.Dq STABLE +and +.Dq CURRENT +.\" re@ will provide their own repository before release, at which +.\" point this text will need updating. +branches are hosted on the Internet at +.Lk https://pkg.freebsd.org . +These packages are updated when new errata or security updates are +released (for supported release versions), or twice daily for +development branches. +.Pp +Alternatively, packages may be built from the system source tree +according to the instructions in +.Xr build 7 , +allowing the system to be updated from source code using packages. +.Sh PACKAGE ORGANISATION +To allow customisation of the installed system, each package is split +into several subpackages which contain different components of the +package. +For the package +.Sy FreeBSD-foo , +the following subpackages may be available: +.Pp +.Bl -tag -width "FreeBSD-foo-dev-lib32" -compact +.It Sy "Package name" +.Sy "Description" +.It FreeBSD-foo +Base files for the package (typically executables) +.It FreeBSD-foo-lib +Native runtime libraries +.It FreeBSD-foo-lib32 +32-bit compatibility runtime libraries +.It FreeBSD-foo-dev +Development files (headers and static libraries) +.It FreeBSD-foo-dev-lib32 +32-bit development files +.It FreeBSD-foo-dbg +Debugging symbols +.It FreeBSD-foo-man +Manual pages. +Manual pages are only packaged separately if the +.Sy WITH_MANSPLITPKG +.Xr src.conf 5 +option was enabled when building the system, which is not the default. +.El +.Pp +The exact set of available subpackages differs for each individual +package. For example, some packages may not provide any development +files, in which case the +.Sy -dev +subpackage is not present. +.Sh PACKAGE SETS +Package sets are meta-packages which do not contain any files +themselves, but depend on a selection of other packages, such that each +package set allows the complete set of packages for a supported workload +to be installed. +.Pp +Package sets are provided as packages named +.Sy FreeBSD-set- . +The following package sets are available in the base system: +.Bl -tag -width "minimal-jail" +.It minimal +The minimal set of packages required to bring up a multi-user +.Fx +system. +This includes the core system, along with packages required for +hardware support (such as +.Xr devmatch 8 +and downloadable firmware), and basic networking, including DHCP and +IEEE Std 802.11\(tm wireless networks. +.It minimal-jail +The equivalent of +.Sy minimal +for systems running in a +.Xr jail 8 +environment. +This set excludes hardware support not typically required for jails. +.It devel +Development tools, including C/C++ compilers, the link loader, and +other tools such as +.Xr ar 1 +and +.Xr nm 1 . +This set also includes native development files (headers and static +libraries) for all packages. +.It optional +Optional software which is not part of either the +.Sy devel +or +.Sy minimal +sets. +.It optional-jail +The equivalent of +.Sy optional +for systems running in a +.Xr jail 8 +environment. +This set excludes system functionality which typically does not work +or is not useful in a jail. +.It lib32 +32-compatibility libraries, for running 32-bit applications on a +64-bit host system. +This set includes both runtime libraries and development files. +.It base +The complete base system, excluding tests, the system source code, +and debugging symbols. +Installing the +.Sy base +set is equivalent to installing +.Sy minimal , +.Sy devel +and +.Sy optional . +.It base-jail +The equivalent of +.Sy base +for systems running in a +.Xr jail 8 +environment. +This set excludes system functionality which typically does not work +or is not useful in a jail. +Installing the +.Sy base-jail +set is equivalent to installing +.Sy minimal-jail , +.Sy devel +and +.Sy optional-jail . +.It src +The system source tree for the userland and kernel, installed in +.Pa /usr/src . +.It tests +The system test suite, installed in +.Pa /usr/tests . +.It kernels +All available system kernels. +.El +.Sh EXAMPLES +.Ss Install a single piece of userland +Install the +.Xr vi 1 +text editor on the running system: +.Bd -literal -offset indent +pkg install FreeBSD-vi +.Ed +.Ss Install userland to a jail +Install a new +.Xr jail 8 +system using the +.Sy minimal-jail +package set: +.Bd -literal -offset indent +pkg -r /jails/myjail install FreeBSD-set-minimal-jail +.Ed +.Ss Install native compilers +Install C/C++ compilers on the running system: +.Bd -literal -offset indent +pkg install FreeBSD-set-devel +.Ed +.Ss Update the currently running system +Apply available updates to the running system: +.Bd -literal -offset indent +pkg upgrade -r FreeBSD-base +.Ed +.Ss Install cross compilers +Install the development toolchain for FreeBSD/powerpc64le in an +alternate root (for example, to support cross-compiling software +for a different target than the host system): +.Bd -literal -offset indent +pkg -r /ppcdev -oABI=FreeBSD:16:powerpc64le \e + install FreeBSD-set-devel +.Ed +.Ss Unregister a currently running system +Systems managed through +.Xr pkg 8 +can be unregistered from the package manager \(em +for example to upgrade in-place via +.Dq make installworld . +See +.Xr build 7 . +.Pp +To unregister the base system from the package manager: +.Bd -literal -offset indent +pkg unregister -fg 'FreeBSD-\e*' +.Ed +.Pp +Then, disable the base system package repository. +If a configuration file was created in +.Pa /usr/local/etc/pkg/repos/ +to enable base system packages, remove it: +.Bd -literal -offset indent +rm /usr/local/etc/pkg/repos/FreeBSD-base.conf +.Ed +.Pp +Alternatively, if it is desired to keep it, +edit the file and change +.Dq Li enabled: +to +.Dq Li no +to disable the entry. +.Pp +.Sy Warning : +This is a destructive action +which will prevent updating the base system via +.Xr pkg 8 . +.Sh SEE ALSO +.Xr build 7 , +.Xr pkg 8 , +.Xr src.conf 5 +.Sh HISTORY +Support for installing the base system as packages was introduced in +.Fx 15.0 . +Earlier releases supported a subset of this functionality. +Support for unregistering an existing installation appeared in pkg 2.5. +.Sh CAVEATS +Upgrading from a RELEASE to a STABLE or CURRENT branch requires +.Dq Li pkg upgrade -f . diff --git a/static/freebsd/man7/growfs.7 b/static/freebsd/man7/growfs.7 new file mode 100644 index 00000000..43648d8d --- /dev/null +++ b/static/freebsd/man7/growfs.7 @@ -0,0 +1,140 @@ +.\" Copyright 2014 John-Mark Gurney +.\" 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 November 22, 2022 +.Dt GROWFS 7 +.Os +.Sh NAME +.Nm growfs , +.Nm growfs_fstab +.Nd start up scripts to grow the root file system and add swap +.Sh DESCRIPTION +The +.Nm +script normally runs at the first boot after system installation. +If the boot disk is larger than the root file system and boot partitions, +and the root file system is in the last partition, +.Nm +can expand the root file system. +It can also add a swap partition, with a default size of 10% of the boot disk. +Swap is limited to twice the memory size up to 4 GB, +8 GB up to 8 GB of memory, and memory size over 8 GB. +It is also limited to the +.Xr sysctl 8 +value of +.Li vm.swap_maxpages +divided by 2. +By default, no swap partition is created if an existing swap partition is found +or is listed in +.Pa /etc/fstab , +or the disk is under 15 GB. +The +.Nm growfs_fstab +script adds any new swap partition to +.Pa /etc/fstab +after the root file system is made writable, +and enables its use as a dump partition if the +.Va dumpdev +variable from +.Xr rc.conf 5 +is set to +.Li AUTO . +.Pp +The following options in +.Pa /etc/rc.conf +control the behavior of +.Nm : +.Bl -tag -width ".Va growfs_swap_size" -offset indent +.It Va growfs_enable +.Pq Dq Li NO +If set to +.Dq Li YES , +the first time the machine boots, the root file system will be automatically +expanded, if possible, to fill up all available space after it, +after optionally adding a swap device at the end. +.It Va growfs_swap_size +.Pq Dq Li \& +If set to +.Dq Li 0 , +the addition of a swap partition is disabled. +An empty value +.Pq Dq Li \& +allows the creation of a swap partition with the default size. +If set to another value, +the swap partition will be created with the specified size in bytes, +even if another swap partition is detected. +.El +.Pp +A setting for +.Va growfs_swap_size +can be set in the kernel environment, in which case it overrides +the value from +.Pa /etc/rc.conf . +.Pp +To expand the root file system without rebooting, run the following command: +.Dl % /etc/rc.d/growfs onestart +In addition, if a swap partition is added, run the command: +.Dl % /etc/rc.d/growfs_fstab onestart +Note that if a disk is expanded again, +and if the root file system had previously been expanded +and a swap partition added, it is necessary to delete the swap +partition before this procedure +in order to expand the root file system to the new size. +A new swap partition can be created during the expansion. +.Sh IMPLEMENTATION NOTES +The +.Nm +script only attempts to expand the root file system, +and free space must be available immediately after the root partition. +It is normally used on images that have a single file system. +The script requires that +.Xr awk 1 +be present and in the path. +This usually means that +.Pa /usr +must be available prior to running the script. +.Sh FILES +.Bl -tag -compact -width Pa +.It Pa /etc/fstab +.It Pa /etc/rc.conf +.El +.Sh EXIT STATUS +.Ex -std +.Sh SEE ALSO +.Xr fstab 5 , +.Xr rc.conf 5 , +.Xr growfs 8 , +.Xr zpool 8 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 10.1 . +The ability to add a swap partition was added in +.Fx 13.2 . +.Sh AUTHORS +The man page and script were written by +.An John-Mark Gurney Aq Mt jmg@FreeBSD.org . +The ability to create a swap partition was added by +.An Michael Karels Aq Mt karels@FreeBSD.org . diff --git a/static/freebsd/man7/hier.7 b/static/freebsd/man7/hier.7 new file mode 100644 index 00000000..5482e5ea --- /dev/null +++ b/static/freebsd/man7/hier.7 @@ -0,0 +1,996 @@ +.\"- +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 September 25, 2025 +.Dt HIER 7 +.Os +.Sh NAME +.Nm hier +.Nd index of +.Fx +file system hierarchy +.Sh DESCRIPTION +.Bl -tag -width "/libexec/" +.It Pa / +root directory of the file system +.It Pa /COPYRIGHT +.Fx +copyright information +.It Pa /bin/ +fundamental +.Bx +user utilities; see +.Xr intro 1 +.It Pa /boot/ +programs and configurations used during +.Fx +.Xr boot 8 +.Pp +.Bl -tag -width "loader.conf.d/" -compact +.It Pa defaults/ +default boot configuration files; see +.Xr loader.conf 5 +.It Pa device.hints +kernel variables for controlling drivers; see +.Xr device.hints 5 +.It Pa dtb/ +compiled flattened device tree (FDT) files; see +.Xr fdt 4 +and +.Xr dtc 1 +.Pp +.Bl -tag -width "overlays/" -compact +.It Pa overlays/ +compiled +.Xr fdt 4 +overlays; see +.Va fdt_overlays +in +.Xr loader.conf 5 +.El +.Pp +.It Pa efi/ +the +.Xr uefi 8 +EFI System Partition (ESP) mount point +.It Pa firmware/ +loadable binary firmware kernel modules +.It Pa fonts/ +binary bitmap console fonts; see +.Xr loader.conf 5 +and +.Xr vtfontcvt 8 +.It Pa images/ +beastie boot menu images; see +.Xr loader_lua 8 +.It Pa kernel/ +.Fx +kernel and modules; see +.Xr kldstat 8 +.It Pa kernel.old/ +alternative kernel and modules +.It Pa loader.conf +boot loader configuration; see +.Xr loader.conf 5 +.It Pa loader.conf.d/ +.Xr loader.conf 5 +configuration files +.It Pa lua/ +scripts for the Lua boot loader; see +.Xr loader_lua 8 +.It Pa modules/ +third-party loadable kernel modules, such as those installed with +.Xr pkg 8 +or from +.Xr ports 7 +.It Pa zfs/ +ZFS +.Xr zpool 8 +cache files +.El +.It Pa /compat/ +files supporting binary compatibility with other operating systems +.Pp +.Bl -tag -width "loader.conf.d" -compact +.It Pa linux/ +default location for +.Xr linux 4 +compatibility run-time +.El +.It Pa /dev/ +device nodes and special files; see +.Xr intro 4 +and +.Xr devfs 4 +.Pp +.Bl -tag -width "loader.conf.d" -compact +.It Pa ada0 +first ATA storage device +.It Pa ada0p1 +first partition on ada0 +.It Pa cd0 +first optical drive +.It Pa cuaU0 +first USB serial port; see +.Xr cu 1 +.It Pa da0 +first SCSI storage device +.It Pa da0s1 +first partition on da0 +.It Pa dri/ +GPU character device nodes; see +.Xr drm 7 +.It Pa drm/ +GPU +.Xr drm 7 +special files +.It Pa fd/ +file descriptor files; see +.Xr fd 4 +.It Pa fd0 +first floppy drive +.It Pa gpt/ +storage partitions by GPT label +.It Pa mmcsd0 +first SD storage device +.It Pa mmcsd0s1 +first partition on mmcsd0 +.It Pa nda0 +first NVMe storage device attached via +.Xr cam 3 +.It Pa null +infinite loop that accepts anything and contains nothing +.It Pa nvd0 +first NVMe storage device using NVMe namespaces +.It Pa pts/ +pseudo-terminals; see +.Xr pts 4 +.It Pa random +source of weak randomness; see +.Xr random 4 +.It Pa sa0 +first tape drive +.It Pa usb/ +USB busses +.It Pa vmm/ +active +.Xr bhyve 8 +virtual machines +.It Pa zvol/ +.Xr zfs 8 +volumes +.El +.It Pa /entropy +provides initial state to RNG; see +.Xr save-entropy 8 +.It Pa /etc/ +base system configuration files and scripts; see +.Xr intro 5 +.Pp +.Bl -tag -width "freebsd-update.conf" -compact +.It Pa auto_master +autofs +.Xr automount 8 +configuration +.It Pa bluetooth/ +bluetooth configuration files +.It Pa cron.d/ +tables for driving scheduled tasks; see +.Xr crontab 5 +.It Pa crontab +root's cron table +.It Pa defaults/ +default system configuration files; see +.Xr rc 8 +.It Pa devd/ +configuration for +.Xr devd 8 , +the device state change daemon +.It Pa devfs.conf +boot time device configuration +.It Pa dma/ +configuration for +.Xr dma 8 +.It Pa freebsd-update.conf +configuration for the base system updater; see +.Xr freebsd-update 8 +.It Pa fstab +static filesystem configuration; see +.Xr fstab 5 +.It Pa hosts +database of local hosts if no network name server is running +.It Pa inetd.conf +configuration for +.Bx +heritage internet servers; see +.Xr inetd 8 +.It Pa localtime +local timezone information; see +.Xr ctime 3 +.It Pa jail.conf.d/ +.Xr jail 8 +startup scripts +.It Pa login.conf +login class capability database; see +.Xr login.conf 5 +.It Pa machine-id +defines the UUID for the local system, required for dbus +.It Pa mail/ +.Xr sendmail 8 +control files +.Pp +.Bl -tag -width "mailer.conf" -compact +.It Pa aliases +addresses to deliver system mail +.It Pa mailer.conf +.Xr mailwrapper 8 +configuration +.El +.Pp +.It Pa motd.template +message displayed upon tty login; see +.Xr motd 5 +.It Pa mtree/ +system mapper specification; see +.Xr mtree 8 +.It Pa newsyslog.conf.d/ +log rotation configuration files. +.It Pa ntp/ +stored time for the Network Time Protocol +.It Pa ntp.conf +configuration for the NTP client, +.Xr ntpd 8 +.It Pa pam.d/ +configuration files for the Pluggable Authentication Modules (PAM) library; +see +.Xr pam 3 +.It Pa periodic/ +scripts that are run daily, weekly, or monthly by +.Xr cron 8 ; +see +.Xr periodic 8 +.It Pa pf.conf +configuration for the Packet Filter firewall; see +.Xr pf 4 +.It Pa pkg/ +default configuration for the package manager, +.Xr pkg 8 +.It Pa ppp/ +PPP configuration files; see +.Xr ppp 8 +.It Pa rc.conf +system and daemon configuration; see +.Xr rc.conf 5 +.It Pa rc.d/ +system and daemon startup/control scripts; see +.Xr rc 8 +.It Pa resolv.conf +DNS configuration; see +.Xr resolv.conf 5 +.It Pa resolvconf.conf +DNS configuration manager configuration, often generated by +local-unbound; see +.Xr local-unbound 8 +or +.Xr resolvconf 8 +.It Pa security/ +OpenBSM audit configuration files; see +.Xr audit 8 +.It Pa ssh/ +OpenSSH configuration files; see +.Xr ssh 1 +.It Pa ssl/ +OpenSSL configuration files +.Pp +.Bl -tag -width "untrusted/" -compact +.It Pa cert.pem +System trust store in bundle form; see +.Xr certctl 8 . +.It Pa certs/ +System trust store in OpenSSL hashed-directory form; see +.Xr certctl 8 . +.It Pa openssl.cnf +OpenSSL configuration file; see +.Xr openssl.cnf 5 . +.It Pa untrusted/ +Explicitly distrusted certificates; see +.Xr certctl 8 . +.El +.It Pa sysctl.conf +kernel state defaults; see +.Xr sysctl.conf 5 +.It Pa syslog.conf +system message log configuration +.It Pa ttys +tty creation configuration; see +.Xr getty 8 +.It Pa wpa_supplicant.conf +client wifi configuration; see +.Xr wpa_supplicant.conf 5 +.El +.It Pa /home/ +home directories for users; the typical home for an interactive user +.Va beastie +would be +.Pa /home/beastie/ +.It Pa /lib/ +system libraries critical to binaries in +.Pa /bin +and +.Pa /sbin +.Pp +.Bl -tag -width "nvmecontrol/" -compact +.It Pa geom/ +class-specific libraries for the +.Xr geom 8 +utility +.It Pa nvmecontrol/ +vendor-specific libraries to extend the +.Xr nvmecontrol 8 +utility +.El +.It Pa /libexec/ +system utilities critical to binaries in +.Pa /bin +and +.Pa /sbin +.It Pa /media/ +mount points for removable storage media such as CDs, DVDs, +and USB drives; see +.Xr automount 8 , +or +.Xr bsdisks 8 +if a using a desktop environment from +.Xr ports 7 +.It Pa /mnt/ +empty directory commonly used by +system administrators as a temporary mount point +.It Pa /net/ +automounted NFS shares; see +.Xr auto_master 5 +.It Pa /nonexistent/ +a non-existent directory; +by convention, it serves as a home directory for user accounts +that need no home directory; see also +.Pa /var/empty/ +.It Pa /proc/ +process file system; see +.Xr procfs 4 +.It Pa /rescue/ +statically linked programs for emergency recovery; see +.Xr rescue 8 +.It Pa /root/ +home directory of the root user +.It Pa /sbin/ +fundamental +.Bx +system administration utilities; see +.Xr intro 8 +.It Pa /tmp/ +temporary files commonly removed between system reboots; +see +.Va clear_tmp_enable +in +.Xr rc.conf 5 +.It Pa /usr/ +contains the majority of user utilities and applications +.Pp +.Bl -tag -width "freebsd-dist/" -compact +.It Pa bin/ +common utilities, programming tools, and applications; see +.Xr intro 1 +.It Pa freebsd-dist/ +distribution files +.Pq like base.txz ; +see +.Xr release 7 +and +.Xr bsdinstall 8 +.It Pa include/ +standard C include header files +.It Pa lib/ +shared and +.Xr ar 1 Ns -type +libraries; see +.Xr intro 3 +.Pp +.Bl -tag -width Fl -compact +.It Pa clang/ +shared libraries for the system compiler, +.Xr clang 1 +.It Pa compat/ +shared libraries for compatibility +.It Pa debug/ +standalone debug data for the kernel and base system libraries and binaries +.It Pa dtrace/ +.Xr dtrace 1 +library scripts +.It Pa engines/ +OpenSSL +.Pq Cryptography/SSL toolkit +dynamically loadable engines +.It Pa flua/ +.Fx +Lua shared libraries +.It Pa i18n/ +shared libraries for internationalization +.El +.Pp +.It Pa lib32/ +32-bit compatibility libraries +.It Pa libdata/ +miscellaneous utility data files +.Pp +.Bl -tag -width Fl -compact +.It Pa ldscripts/ +linker scripts; see +.Xr ld 1 +.It Pa pkgconfig/ +collections of compiler and linker flags for the +.Xr pkgconf 1 +development tool +.El +.Pp +.It Pa libexec/ +system daemons and utilities executed by programs +.Pp +.Bl -tag -width "bsdinstall/" -compact +.It Pa bsdconfig/ +utilities called by the ncurses +.Fx +configuration wizard +.It Pa bsdinstall/ +utilities for +.Xr bsdinstall 8 +.It Pa dwatch/ +profiles for +.Xr dwatch 1 +.It Pa fwget/ +utilities called by +.Xr fwget 8 +.It Pa hyperv/ +scripts for communicating with the Hyper-V hypervisor +.It Pa lpr/ +utilities and filters for the line printer system; see +.Xr lpr 1 +.It Pa sendmail/ +the +.Xr sendmail 8 +binary; see +.Xr mailwrapper 8 +.It Pa sm.bin/ +restricted shell for +.Xr sendmail 8 ; +see +.Xr smrsh 8 +.It Pa zfs/ +Z file system utilities +.El +.Pp +.It Pa local/ +local executables, libraries, etc, installed by +.Xr pkg 7 +or +.Xr ports 7 +.Pp +.Bl -tag -width Fl -compact +.It Pa bin/ +local user utilities, see +.Xr intro 1 +.It Pa etc/ +local program configurations +.It Pa include/ +local library headers +.It Pa lib/ +local libraries +.It Pa lib32/ +local 32-bit compatibility libraries +.It Pa libdata/ +local utility data files +.It Pa libexec/ +utilities executed by local utilities +.It Pa sbin/ +local administration utilities +.It Pa share/ +local architecture-independent files +.It Pa share/doc/ +local documentation +.It Pa share/doc/freebsd/ +articles, books, FAQ, and handbooks available from the +.Fx +project +.It Pa share/man/ +local manual pages; see +.Xr man 1 +.El +.Pp +.It Pa obj/ +architecture-specific target tree produced by building +.Fx +from source; see +.Xr build 7 +.It Pa ports/ +.Fx +ports collection; see +.Xr ports 7 +.It Pa sbin/ +system daemons and utilities meant for user execution; see +.Xr intro 8 +.It Pa share/ +architecture-independent files +.Pp +.Bl -tag -width Fl -compact +.It Pa atf/ +scripts for the Automated Testing Framework; see +.Xr ATF 7 +.It Pa bhyve/ +.Xr bhyve 8 +keyboard mappings +.It Pa calendar/ +system-wide calendar files; see +.Xr calendar 1 +.It Pa certs/ +TLS certificates for +.Xr openssl 1 +.It Pa dict/ +word lists; see +.Xr look 1 +.Pp +.Bl -tag -width Fl -compact +.It Pa freebsd +.Fx Ns -specific +terms, proper names, and jargon +.It Pa web2 +words from Webster's Second International +.El +.Pp +.It Pa doc/ +miscellaneous documentation +.It Pa dtrace/ +scripts for the Dynamic Tracing Compiler; see +.Xr dtrace 1 +.It Pa examples/ +various examples for users and programmers +.It Pa firmware/ +firmware images loaded by userland programs +.It Pa games/ +ASCII text files used by +.Bx +heritage games, see +.Xr intro 6 +.It Pa keys/ +known trusted and revoked keys +.Pp +.Bl -tag -width Fl -compact +.It Pa pkg/ +fingerprints for +.Xr pkg 7 +and +.Xr pkg 8 +.El +.Pp +.It Pa locale/ +localization files; see +.Xr setlocale 3 +.It Pa man/ +system manual pages; see +.Xr man 1 +.It Pa misc/ +miscellaneous system-wide files +.Pp +.Bl -tag -width Fl -compact +.It Pa ascii +chart of the ASCII codepoints +.It Pa flowers +the meanings of flowers +.It Pa magic +magic numbers used by +.Xr file 1 +.It Pa termcap +terminal characteristics database; see +.Xr termcap 5 +.El +.Pp +.It Pa mk/ +templates for make; see +.Xr make 1 +.It Pa nls/ +national language support files +.It Pa security/ +data files for security policies such as +.Xr mac_lomac 4 +.It Pa sendmail/ +.Xr sendmail 8 +configuration files +.It Pa skel/ +example +.Pa .\& +(dot) files for new accounts +.It Pa snmp/ +MIBs, example files and tree definitions for the SNMP daemon +.Pp +.Bl -tag -width Fl -compact +.It Pa defs/ +tree definition files for use with +.Xr gensnmptree 1 +.It Pa mibs/ +management Information Base +.Pq MIB +files +.El +.Pp +.It Pa syscons/ +.Xr syscons 4 +files +.Pp +.Bl -tag -width Fl -compact +.It Pa fonts/ +console fonts; see +.Xr vidcontrol 1 +and +.Xr vidfont 1 +.It Pa keymaps/ +console keyboard maps; see +.Xr kbdcontrol 1 +and +.Xr kbdmap 1 +.It Pa scrnmaps/ +console screen maps +.El +.Pp +.It Pa sysroot/ +files necessary for the -sysroot compiler/linker argument to build non-native +binaries +.Pp +.Bl -tag -width "VERSION/" -compact +.It Pa VERSION/ +files for +.Fx +release VERSION; +by convention, +.Dq VERSION +matches +.Xr uname 1 +.Fl r +.It Pa VERSION/MACHINE.MACHINE_ARCH/ +represent the binary ABI for these files; +.Dq MACHINE +matches +.Xr uname 1 +.Fl m ; +.Dq MACHINE_ARCH +matches +.Xr uname 1 +.Fl p +.El +.Pp +.It Pa tabset/ +tab description files for a variety of terminals; used in +the termcap file; see +.Xr termcap 5 +.It Pa vi/ +localization support and utilities for the +.Xr vi 1 +editor +.It Pa vt/ +files used by the system console; see +.Xr vt 4 +.Pp +.Bl -tag -width Fl -compact +.It Pa fonts/ +console fonts; see +.Xr vidcontrol 1 , +.Xr vidfont 1 , +and +.Xr vtfontcvt 8 +.It Pa keymaps/ +console keyboard maps; see +.Xr kbdcontrol 1 +and +.Xr kbdmap 1 +.El +.Pp +.It Pa zoneinfo/ +timezone configuration information; see +.Xr tzfile 5 +.El +.Pp +.It Pa src/ +.Fx +source code; see +.Xr development 7 ; +the layout of the source tree is described by the top-level +.Pa README.md +file +.Pp +.It Pa tests/ +the +.Fx +test suite; see +.Xr tests 7 +.El +.It Pa /var/ +log, temporary, transient, and spool files +.Pp +.Bl -tag -width "preserve/" -compact +.It Pa account/ +system accounting files +.Pp +.Bl -tag -width Ds -compact +.It Pa acct +execution accounting file; see +.Xr acct 5 +.El +.Pp +.It Pa at/ +timed command scheduling files; see +.Xr at 1 +.Pp +.Bl -tag -width Ds -compact +.It Pa jobs/ +job files +.It Pa spool/ +output spool files +.El +.Pp +.It Pa audit/ +security event audit trail files; see +.Xr audit 8 +.It Pa authpf/ +user shell sessions for authenticating gateways; see +.Xr authpf 8 +.It Pa backups/ +critical system configuration backups +.It Pa cache/ +miscellaneous cache files +.Pp +.Bl -tag -width Ds -compact +.It Pa pkg/ +cached packages for +.Xr pkg 8 +.It Pa cups/ +cached printers for the Common Unix Prinitng system; see +.Xr cups 1 +.El +.Pp +.It Pa crash/ +default directory to store kernel crash dumps; see +.Xr crash 8 +and +.Xr savecore 8 +.It Pa cron/ +files used by cron; see +.Xr cron 8 +.Pp +.Bl -tag -width Ds -compact +.It Pa tabs/ +crontab files; see +.Xr crontab 5 +.El +.Pp +.It Pa db/ +autogenerated system-specific database files +.Pp +.Bl -tag -width "freebsd-update/" -compact +.It Pa etcupdate/ +temporary files and log for +.Xr etcupdate 8 +.It Pa freebsd-update/ +downloads and temporary files for +.Xr freebsd-update 8 +.It Pa pkg/ +package database +.El +.Pp +.It Pa empty/ +for use by programs that require an empty directory, +used for instance by +.Xr sshd 8 +for privilege separation +.It Pa games/ +status and score files for +.Bx +heritage games +.It Pa heimdal/ +Kerberos server databases; see +.Xr kdc 8 +.It Pa lib/ +state information for ported Linux applications +.It Pa log/ +system log files +.Pp +.Bl -tag -width "bsdinstall_log" -compact +.It Pa Xorg.0.log +.Xr Xserver 1 +log, if +.Xr X 7 +is installed rotates to +.Pa Xorg.0.log.old +.It Pa aculog +serial line access log; see +.Xr cu 1 +.It Pa auth.log +system authentication log +.It Pa bsdinstall_log +system installation log +.It Pa cron +scheduled task log; see +.Xr cron 8 +.It Pa cups/ +logs for +.Xr cups 1 +.It Pa daemon.log +default log for system daemons +.It Pa devd.log +default log for device state change daemon +.It Pa dmesg.today +kernel message buffer log, rotates to +.Pa dmesg.yesterday +.It Pa debug.log +undiscarded debug syslog messages +.It Pa lpd-errs +logs for the line printer spooler daemon; see +.Xr lpd 8 +.It Pa maillog +.Xr sendmail 8 +log, rotates and compresses to maillog.0.bz2 +.It Pa messages +general system message log; see +.Xr syslogd 8 +.It Pa mount.today +currently loaded +.Xr fstab 5 , +rotates to +.Pa mount.yesterday +.It Pa pf.today +packet filter firewall log; see +.Xr pf 4 +.It Pa pflog +saved packets caught by +.Xr pflogd 8 +.It Pa ppp.log +see +.Xr ppp 8 +.It Pa security +transcript of events marked with the security flag +.It Pa setuid.today +listing of executable files which run with elevated permissions, rotates +to +.Pa setuid.yesterday +.It Pa userlog +logs changes in users or groups +.It Pa utx.lastlogin +last login log; see +.Xr getutxent 3 +.It Pa utx.log +login/logout log; see +.Xr getutxent 3 +.El +.Pp +.It Pa mail/ +user mailbox files +.It Pa msgs/ +system messages database; see +.Xr msgs 1 +.It Pa preserve/ +unused, present for historical reasons +.It Pa quotas/ +UFS quota information files +.It Pa run/ +files containing information about the operating system since it was booted +.Pp +.Bl -tag -width "wpa_supplicant/" -compact +.It Pa bhyve/ +.Xr bhyve 8 +virtual machine +.Xr unix 4 Ns -domain sockets +.It Pa ppp/ +writable by the +.Dq network +group for command connection sockets; see +.Xr ppp 8 +.It Pa utx.active +database of current users; see +.Xr getutxent 3 +.It Pa wpa_supplicant/ +IEEE Std. 802.11 wifi run time files +.El +.Pp +.It Pa rwho/ +information about other systems on the local network; see +.Xr rwhod 8 , +.Xr rwho 1 , +and +.Xr ruptime 1 +.It Pa spool/ +printer and mail system spooling directories +.Pp +.Bl -tag -width "clientmqueue/" -compact +.It Pa clientmqueue/ +undelivered submission mail queue; see +.Xr sendmail 8 +.It Pa cups/ +print jobs and temporary files for +.Xr cups 1 +.It Pa dma/ +undelivered mail queue for +.Dx +Mail Agent; see +.Xr dma 8 +.It Pa lock/ +serial device locks; see +.Xr uucplock 3 +.It Pa lpd/ +line printer spooler daemon spool +.It Pa mqueue/ +undelivered mail queue for +.Xr sendmail 8 +.It Pa output/ +line printer spooling directories +.El +.Pp +.It Pa tmp/ +temporary files not removed between system reboots +.Pp +.Bl -tag -width "vi.recover/" -compact +.It Pa vi.recover/ +recovery files for the +.Xr vi 1 +editor +.El +.Pp +.It Pa unbound/ +files and configuration for +.Xr unbound 8 +.It Pa yp/ +the NIS maps; see +.Xr yp 8 +.El +.El +.Sh NOTES +This manual page documents the default +.Fx +file system layout. +The actual hierarchy on a given system is defined at the system +administrator's discretion. +A well-maintained installation will include a customized version of +this document. +.Sh SEE ALSO +.Xr apropos 1 , +.Xr find 1 , +.Xr grep 1 , +.Xr ls 1 , +.Xr whereis 1 , +.Xr which 1 +.Sh HISTORY +A +.Nm +manual page first appeared in 1979 with +.At v7 . diff --git a/static/freebsd/man7/hostname.7 b/static/freebsd/man7/hostname.7 new file mode 100644 index 00000000..2c15fb6f --- /dev/null +++ b/static/freebsd/man7/hostname.7 @@ -0,0 +1,85 @@ +.\" Copyright (c) 1987, 1990, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 December 25, 2013 +.Dt HOSTNAME 7 +.Os +.Sh NAME +.Nm hostname +.Nd host name resolution description +.Sh DESCRIPTION +Hostnames are domains, where a domain is a hierarchical, dot-separated +list of subdomains; for example, the machine monet, in the Berkeley +subdomain of the EDU subdomain of the Internet would be represented as +.Pp +.Dl monet.Berkeley.EDU +.Pp +(with no trailing dot). +.Pp +Hostnames are often used with network client and server programs, +which must generally translate the name to an address for use. +(This function is generally performed by the library routine +.Xr gethostbyname 3 . ) +Hostnames are resolved by the Internet name resolver in the following +fashion. +.Pp +If the name consists of a single component, i.e., contains no dot, +and if the environment variable +.Dq Ev HOSTALIASES +is set to the name of a file, +that file is searched for any string matching the input hostname. +The file should consist of lines made up of two white-space separated strings, +the first of which is the hostname alias, +and the second of which is the complete hostname +to be substituted for that alias. +If a case-insensitive match is found between the hostname to be resolved +and the first field of a line in the file, the substituted name is looked +up with no further processing. +.Pp +If the input name ends with a trailing dot, +the trailing dot is removed, +and the remaining name is looked up with no further processing. +.Pp +If the input name does not end with a trailing dot, it is looked up +by searching through a list of domains until a match is found. +The default search list includes first the local domain, +then its parent domains with at least 2 name components (longest first). +For example, +in the domain CS.Berkeley.EDU, the name lithium.CChem will be checked first +as lithium.CChem.CS.Berkeley.EDU and then as lithium.CChem.Berkeley.EDU. +Lithium.CChem.EDU will not be tried, as there is only one component +remaining from the local domain. +The search path can be changed from the default +by a system-wide configuration file (see +.Xr resolver 5 ) . +.Sh SEE ALSO +.Xr gethostbyname 3 , +.Xr resolver 5 +.Sh HISTORY +.Nm Hostname +appeared in +.Bx 4.2 . diff --git a/static/freebsd/man7/intro.7 b/static/freebsd/man7/intro.7 new file mode 100644 index 00000000..43e48de8 --- /dev/null +++ b/static/freebsd/man7/intro.7 @@ -0,0 +1,106 @@ +.\" Copyright (c) 1983, 1990, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 14, 2025 +.Dt INTRO 7 +.Os +.Sh NAME +.Nm intro +.Nd miscellaneous information pages +.Sh DESCRIPTION +This section contains miscellaneous documentation. +.Bl -tag -width "mdoc.samples(7)" -offset indent +.It Xr arch 7 +supported CPU architectures and platforms +.It Xr ascii 7 +map of ASCII character set +.It Xr build 7 +build instructions for +.Fx +.It Xr c 7 +the C programming language +.It Xr clocks 7 +system timekeeping clocks available in +.Fx +.It Xr crypto 7 +cryptographic algorithms provided by OpenCrypto in +.Fx +.It Xr d 7 +.Xr dtrace 1 +scripting language overview +.It Xr development 7 +development introduction to +.Fx +.It Xr environ 7 +user environment +.It Xr firewall 7 +simple firewalls under +.Fx +.It Xr hier 7 +file system hierarchy in +.Fx +.It Xr hostname 7 +host name resolution description +.It Xr networking 7 +network connection quickstart guide +.It Xr release 7 +layout of +.Fx +releases and snapshots +.It Xr ports 7 +introduction to the ports infrastructure of +.Fx +.It Xr security 7 +security features available in +.Fx +.It Xr stats 7 +statistics utilities available in +.Fx +.It Xr tests 7 +introduction to the +.Fx +Test Suite +.It Xr tracing 7 +introduction to tracing and performance monitoring facilities +.It Xr tuning 7 +general advice on tuning +.Fx +.El +.Sh SEE ALSO +.Xr man 1 , +.Xr intro 2 , +.Xr intro 3 , +.Xr intro 4 , +.Xr intro 5 , +.Xr intro 6 , +.Xr intro 8 , +.Xr intro 9 +.Sh HISTORY +The +.Nm +section manual page appeared in +.Bx 4.2 . diff --git a/static/freebsd/man7/maclabel.7 b/static/freebsd/man7/maclabel.7 new file mode 100644 index 00000000..5006cc47 --- /dev/null +++ b/static/freebsd/man7/maclabel.7 @@ -0,0 +1,96 @@ +.\" Copyright (c) 2002 Networks Associates Technology, Inc. +.\" All rights reserved. +.\" +.\" This software was developed for the FreeBSD Project by Chris Costello +.\" at Safeport Network Services and Network Associates Labs, the Security +.\" Research Division of Network Associates, Inc. under DARPA/SPAWAR +.\" contract N66001-01-C-8035 ("CBOSS"), as part of the DARPA CHATS research +.\" program. +.\" +.\" 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. The names of the authors may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS 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 AUTHORS 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 October 25, 2002 +.Dt MACLABEL 7 +.Os +.Sh NAME +.Nm maclabel +.Nd Mandatory Access Control label format +.Sh DESCRIPTION +If Mandatory Access Control, or MAC, is enabled in the kernel, +then in addition to the traditional credentials, +each subject +(typically a user or a socket) +and object +(file system object, socket, etc.\&) +is given a +.Em "MAC label" . +The MAC label specifies the necessary subject-specific or +object-specific information necessary for a MAC security policy +.\" .Pq Xr mac 9 +to enforce access control on the subject/object. +.Pp +The format for a MAC label is defined as follows: +.Pp +.Sm off +.D1 Ar policy1 No / Ar qualifier1 , policy2 No / Ar qualifier2 , No ... +.Sm on +.Pp +A MAC label consists of a policy name, +followed by a forward slash, +followed by the subject or object's qualifier, +optionally followed by a comma and one or more additional policy labels. +For example: +.Bd -literal -offset indent +biba/low(low-low) +biba/high(low-high),mls/equal(equal-equal),partition/0 +.Ed +.Sh SEE ALSO +.Xr mac 3 , +.Xr posix1e 3 , +.Xr mac_biba 4 , +.Xr mac_bsdextended 4 , +.Xr mac_ifoff 4 , +.Xr mac_mls 4 , +.Xr mac_none 4 , +.Xr mac_partition 4 , +.Xr mac_seeotheruids 4 , +.Xr mac_test 4 , +.Xr login.conf 5 , +.Xr getfmac 8 , +.Xr getpmac 8 , +.Xr ifconfig 8 , +.Xr setfmac 8 , +.Xr setpmac 8 , +.Xr mac 9 +.Sh HISTORY +MAC first appeared in +.Fx 5.0 . +.Sh AUTHORS +This software was contributed to the +.Fx +Project by NAI Labs, the Security Research Division of Network Associates +Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. diff --git a/static/freebsd/man7/mitigations.7 b/static/freebsd/man7/mitigations.7 new file mode 100644 index 00000000..c12e57e9 --- /dev/null +++ b/static/freebsd/man7/mitigations.7 @@ -0,0 +1,509 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright © 2023 The FreeBSD Foundation +.\" +.\" This documentation was written by Ed Maste , and +.\" Olivier Certner at Kumacom SAS, under +.\" sponsorship of the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 29, 2025 +.Dt MITIGATIONS 7 +.Os +.Sh NAME +.Nm mitigations +.Nd FreeBSD Security Vulnerability Mitigations +.Sh SYNOPSIS +In +.Fx , +various security mitigations are employed to limit the impact of +vulnerabilities and protect the system from malicious attacks. +Some of these mitigations have run-time controls to enable them on a global +or per-process basis, some are optionally enabled or disabled at compile time, +and some are inherent to the implementation and have no controls. +.Pp +The following vulnerability mitigations are covered in this document: +.Pp +.Bl -bullet -compact +.It +Address Space Layout Randomization (ASLR) +.It +Position Independent Executable (PIE) +.It +Write XOR Execute page protection policy +.It +.Dv PROT_MAX +.It +Relocation Read-Only (RELRO) +.It +Bind Now +.It +Stack Overflow Protection +.It +Supervisor Mode Memory Protection +.It +Capsicum +.It +Firmware and Microcode +.It +Architectural Vulnerability Mitigations +.El +.Pp +Please note that the effectiveness and availability of these mitigations may +vary depending on the +.Fx +version and system configuration. +.Sh DESCRIPTION +Security vulnerability mitigations are techniques employed in +.Fx +to limit the potential impact of security vulnerabilities in software and +hardware. +It is essential to understand that mitigations do not directly address the +underlying security issues. +They are not a substitute for secure coding practices. +Mitigations serve as an additional layer of defense, helping to reduce the +likelihood of a successful exploitation of vulnerabilities by making it +more difficult for attackers to achieve their objectives. +.Pp +This manual page describes the security mitigations implemented in +.Fx +to enhance the overall security of the operating system. +Each mitigation is designed to protect against specific types of attacks +and vulnerabilities. +.\" +.Sh SOFTWARE VULNERABILITY MITIGATIONS +.Ss Address Space Layout Randomization (ASLR) +Address Space Layout Randomization (ASLR) is a security mitigation technique +that works by randomizing the memory addresses where system and application +code, data, and libraries are loaded, making it more challenging for attackers +to predict the memory layout and exploit vulnerabilities. +.Pp +ASLR introduces randomness into the memory layout during process execution, +reducing the predictability of memory addresses. +ASLR is intended to make exploitation more difficult in the event that an +attacker discovers a software vulnerability, such as a buffer overflow. +.Pp +ASLR can be enabled on both a global and per-process basis. +Global control is provided by a separate set of +.Xr sysctl 8 +knobs for 32- and 64-bit processes. +It can be or disabled on a per-process basis via +.Xr proccontrol 1 . +Note that an ASLR mode change takes effect upon address space change, +i.e., upon +.Xr execve 2 . +.Pp +Global controls for 32-bit processes: +.Bl -tag -width kern.elf32.aslr.pie_enable +.It Va kern.elf32.aslr.enable +Enable ASLR for 32-bit ELF binaries, other than Position Independent +Executable (PIE) binaries. +.It Va kern.elf32.aslr.pie_enable +Enable ASLR for 32-bit Position Independent Executable (PIE) ELF binaries. +.It Va kern.elf32.aslr.honor_sbrk +Reserve the legacy +.Xr sbrk 2 +region for compatibility with older binaries. +.It Va kern.elf32.aslr.stack +Randomize the stack location for 32-bit ELF binaries. +.El +.Pp +Global controls for 64-bit processes: +.Bl -tag -width kern.elf64.aslr.pie_enable +.It Va kern.elf64.aslr.enable +Enable ASLR for 64-bit ELF binaries, other than Position Independent +Executable (PIE) binaries. +.It Va kern.elf64.aslr.pie_enable +Enable ASLR for 64-bit Position Independent Executable (PIE) ELF binaries. +.It Va kern.elf64.aslr.honor_sbrk +Reserve the legacy +.Xr sbrk 2 +region for compatibility with older binaries. +.It Va kern.elf64.aslr.stack +Randomize the stack location for 64-bit ELF binaries. +.El +.Pp +To execute a command with ASLR enabled or disabled: +.Pp +proccontrol +.Fl m Ar aslr +.Op Fl s Ar enable | disable +.Ar command +.\" +.Ss Position Independent Executable (PIE) +PIE binaries are executable files that do not have a fixed load address. +They can be loaded at an arbitrary memory address by the +.Xr rtld 1 +run-time linker. +With ASLR they are loaded at a random address on each execution. +.\" +.Ss Write XOR Execute page protection policy +Write XOR Execute (W^X) is a vulnerability mitigation strategy that strengthens +the security of the system by controlling memory access permissions. +.Pp +Under the W^X mitigation, memory pages may be writable (W) or executable (E), +but not both at the same time. +This means that code execution is prevented in areas of memory that are +designated as writable, and writing or modification of memory is restricted in +areas marked for execution. +Applications that perform Just In Time (JIT) compilation need to be adapted +to be compatible with W^X. +.Pp +There are separate +.Xr sysctl 8 +knobs to control W^X policy enforcement for 32- and 64-bit processes. +The W^X policy is enabled by setting the appropriate +.Dv allow_wx +sysctl to 0. +.Bl -tag -width kern.elf64.allow_wx +.It Va kern.elf32.allow_wx +Allow 32-bit processes to map pages simultaneously writable and executable. +.It Va kern.elf64.allow_wx +Allow 64-bit processes to map pages simultaneously writable and executable. +.El +.\" +.Ss PROT_MAX +.Dv PROT_MAX +is a +.Fx Ns +-specific extension to +.Xr mmap 2 . +.Dv PROT_MAX +provides the ability to set the maximum protection of a region allocated by +.Xr mmap 2 +and later altered by +.Xr mprotect 2 . +For example, memory allocated originally with an mmap prot argument of +PROT_MAX(PROT_READ | PROT_WRITE) | PROT_READ +may be made writable by a future +.Xr mprotect 2 +call, but may not be made executable. +.\" +.Ss Relocation Read-Only (RELRO) +Relocation Read-Only (RELRO) is a mitigation tool that makes certain portions +of a program's address space that contain ELF metadata read-only, after +relocation processing by +.Xr rtld 1 . +.Pp +When enabled in isolation the RELRO option provides +.Em partial RELRO +support. +In this case the Procedure Linkage Table (PLT)-related part of the +Global Offset Table (GOT) (in the section typically named .got.plt) remains +writable. +.Pp +RELRO is enabled by default. +The +.Xr src.conf 5 +build-time option +.Va WITHOUT_RELRO +may be used to disable it. +.Ss BIND_NOW +The +.Va WITH_BIND_NOW +.Xr src.conf 5 +build-time option causes binaries to be built with the +.Dv DF_BIND_NOW +flag set. +The run-time loader +.Xr rtld 1 +will then perform all relocation processing when the process starts, instead of +on demand (on the first access to each symbol). +.Pp +When enabled in combination with +.Dv RELRO +(which is enabled by default) this provides +.Em full RELRO . +The entire GOT (.got and .got.plt) are made read-only at program startup, +preventing attacks on the relocation table. +Note that this results in a nonstandard Application Binary Interface (ABI), +and it is possible that some applications may not function correctly. +.\" +.Ss Stack Overflow Protection +.Fx +supports stack overflow protection using the Stack Smashing Protector +.Pq SSP +compiler feature. +Stack clash protection is also enabled, +if supported by the compiler for the given architecture. +In userland, SSP adds a per-process randomized canary at the end of every stack +frame which is checked for corruption upon return from the function, +and stack probing in +.Dv PAGE_SIZE +chunks. +In the kernel, a single randomized canary is used globally except on aarch64, +which has a +.Dv PERTHREAD_SSP +.Xr config 8 +option to enable per-thread randomized canaries. +If stack corruption is detected, then the process aborts to avoid potentially +malicious execution as a result of the corruption. +SSP may be enabled or disabled when building +.Fx +base with the +.Xr src.conf 5 +SSP knob. +.Pp +When +.Va WITH_SSP +is enabled, which is the default, world is built with the +.Fl fstack-protector-strong +and +.Fl fstack-clash-protection +compiler options. +The kernel is built with the +.Fl fstack-protector +option. +.Pp +In addition to SSP, a +.Dq FORTIFY_SOURCE +implementation is supported up to level 2 by defining +.Va _FORTIFY_SOURCE +to +.Dv 1 +or +.Dv 2 +before including any +.Fx +headers. +.Fx +world builds can set +.Va FORTIFY_SOURCE +in the environment or +.Pa /etc/src-env.conf +to provide a default value for +.Va _FORTIFY_SOURCE . +When enabled, +.Dq FORTIFY_SOURCE +enables extra bounds checking in various functions that accept buffers to be +written into. +These functions currently have extra bounds checking support: +.Bl -column -offset indent "snprintf()" "memmove()" "strncpy()" "vsnprintf()" "readlink()" +.It Fn bcopy Ta Fn bzero Ta Fn fgets Ta Fn getcwd Ta Fn gets +.It Fn memcpy Ta Fn memmove Ta Fn memset Ta Fn read Ta Fn readlink +.It Fn snprintf Ta Fn sprintf Ta Fn stpcpy Ta Fn stpncpy Ta Fn strcat +.It Fn strcpy Ta Fn strncat Ta Fn strncpy Ta Fn vsnprintf Ta Fn vsprintf +.El +.Pp +.Dq FORTIFY_SOURCE +requires compiler support from +.Xr clang 1 +or +.Xr gcc 1 , +which provide the +.Xr __builtin_object_size 3 +function that is used to determine the bounds of an object. +This feature works best at optimization levels +.Fl O1 +and above, as some object sizes may be less obvious without some data that the +compiler would collect in an optimization pass. +.Pp +Similar to SSP, violating the bounds of an object will cause the program to +abort in an effort to avoid malicious execution. +This effectively provides finer-grained protection than SSP for some class of +function and system calls, along with some protection for buffers allocated as +part of the program data. +.\" +.Ss Supervisor mode memory protection +Certain processors include features that prevent unintended access to memory +pages accessible to userspace (non-privileged) code, while in a privileged +mode. +One feature prevents execution, intended to mitigate exploitation of kernel +vulnerabilities from userland. +Another feature prevents unintended reads from or writes to user space memory +from the kernel. +This also provides effective protection against NULL pointer dereferences from +kernel. +An additional mechanism, +Linear Address Space Separation (LASS), is available on some amd64 machines. +LASS prevents user-mode applications from accessing kernel-mode memory, +and the kernel from unsanctioned access to userspace memory. +Unlike page table-based permission controls, LASS is based only on address +values. +As a consequence of enforcing this separation in hardware, LASS also provides +mitigation against certain speculative-execution side-channel attacks. +.Bl -column -offset indent "Architecture" "Feature" "Access Type Prevented" +.It Sy Architecture Ta Sy Feature Ta Sy Access Type Prevented +.It amd64 Ta LASS Ta All +.It amd64 Ta SMAP Ta Read / Write +.It amd64 Ta SMEP Ta Execute +.It arm64 Ta PAN Ta Read / Write +.It arm64 Ta PXN Ta Execute +.It riscv Ta SUM Ta Read / Write +.It riscv Ta - Ta Execute +.El +.Pp +Most of these features are automatically used by the kernel, +with no user-facing configuration. +LASS is controlled by the +.Va hw.lass +loader tunable. +It is enabled by default, when available. +.\" +.Ss Capsicum +Capsicum is a lightweight OS capability and sandbox framework. +See +.Xr capsicum 4 +for more information. +.Sh HARDWARE VULNERABILITY MITIGATIONS +.Ss Firmware and Microcode +Recent years have seen an unending stream of new hardware vulnerabilities, +notably CPU ones generally caused by detectable microarchitectural side-effects +of speculative execution which leak private data from some other thread or +process or sometimes even internal CPU state that is normally inaccessible. +Hardware vendors usually address these vulnerabilities as they are discovered by +releasing microcode updates, which may then be bundled into platform firmware +updates +.Pq historically called BIOS updates for PCs +or packages to be updated by the operating system at boot time. +.Pp +Platform firmware updates, if available from the manufacturer, +are the best defense as they provide coverage during early boot. +Install them with +.Pa sysutils/flashrom +from the +.Fx +Ports Collection. +.Pp +If platform firmware updates are no longer available, +packaged microcode is available for installation at +.Pa sysutils/cpu-microcode +and can be loaded at runtime using +.Xr loader.conf 5 , +see the package message for more details. +.Pp +The best defense overall against hardware vulnerabilities is to timely apply +these updates when available, as early as possible in the boot process, +and to disable the affected hardware's problematic functionalities when possible +(e.g., CPU Simultaneous Multi-Threading). +Software mitigations are only partial substitutes for these, but they can be +helpful on out-of-support hardware or as complements for just-discovered +vulnerabilities not yet addressed by vendors. +Some software mitigations depend on hardware capabilities provided by a +microcode update. +.Ss Architectural Vulnerability Mitigations +.Fx Ap s +usual policy is to apply by default all OS-level mitigations that do +not require recompilation, except those the particular hardware it is running on +is known not to be vulnerable to +.Pq which sometimes requires firmware updates , +or those that are extremely detrimental to performance in proportion to the +protection they actually provide. +OS-level mitigations generally can have noticeable performance impacts on +specific workloads. +If your threat model allows it, you may want to try disabling some of them in +order to possibly get better performance. +Conversely, minimizing the risks may require you to explicitly enable the most +expensive ones. +The description of each vulnerability/mitigation indicates whether it is enabled +or disabled by default and under which conditions. +It also lists the knobs to tweak to force a particular status. +.Ss Zenbleed +The +.Dq Zenbleed +vulnerability exclusively affects AMD processors based on the Zen2 +microarchitecture. +In contrast with, e.g., Meltdown and the different variants of Spectre, which +leak data by leaving microarchitectural traces, Zenbleed is a genuine hardware +bug affecting the CPU's architectural state. +With particular sequences of instructions whose last ones are mispredicted by +speculative execution, it is possible to make appear in an XMM register data +previously put in some XMM register by some preceding or concurrent task +executing on the same physical core +.Po disabling Simultaneous Multi-Threading +.Pq SMT +is thus not a sufficient protection +.Pc . +.Pp +According to the vulnerability's discoverer, all Zen2-based processors are +affected +.Po see +.Lk https://lock.cmpxchg8b.com/zenbleed.html +.Pc . +As of August 2023, AMD has not publicly listed any corresponding errata but has +issued a security bulletin +.Pq AMD-SB-7008 +entitled +.Dq Cross-Process Information Leak +indicating that platform firmware fixing the vulnerability will be distributed +to manufacturers no sooner than the end of 2023, except for Rome processors for +which it is already available. +No standalone CPU microcodes have been announced so far. +The only readily-applicable fix mentioned by the discoverer is to set a bit of +an undocumented MSR, which reportedly completely stops XMM register leaks. +.Pp +.Fx +currently sets this bit by default on all Zen2 processors. +In the future, it might set it by default only on those Zen2 processors whose +microcode has not been updated to revisions fixing the vulnerability, once such +microcode updates have been actually released and community-tested. +To this mitigation are associated the following knobs: +.Bl -tag -width indent +.It Va machdep.mitigations.zenbleed.enable +A read-write integer tunable and sysctl indicating whether the mitigation should +be forcibly disabled (0), enabled (1) or if it is left to +.Fx +to selectively apply it (2). +Any other integer value is silently converted to and treated as value 2. +Note that this setting is silently ignored when running on non-Zen2 processors +to ease applying a common configuration to heterogeneous machines. +.It Va machdep.mitigations.zenbleed.state +A read-only string indicating the current mitigation state. +It can be either +.Dq Not applicable , +if the processor is not Zen2-based, +.Dq Mitigation enabled +or +.Dq Mitigation disabled . +This state is automatically updated each time the sysctl +.Va machdep.mitigations.zenbleed.enable +is written to. +Note that it can become inaccurate if the chicken bit is set or cleared +directly via +.Xr cpuctl 4 +.Po which includes the +.Xr cpucontrol 8 +utility +.Pc . +.El +.Pp +The performance impact and threat models related to these mitigations +should be considered when configuring and deploying them in a +.Fx +system. +.Pp +Additional mitigation knobs are listed in the +.Sx KNOBS AND TWEAKS +section of +.Xr security 7 . +.Sh SEE ALSO +.Xr elfctl 1 , +.Xr proccontrol 1 , +.Xr rtld 1 , +.Xr mmap 2 , +.Xr src.conf 5 , +.Xr sysctl.conf 5 , +.Xr security 7 , +.Xr cpucontrol 8 , +.Xr sysctl 8 diff --git a/static/freebsd/man7/named_attribute.7 b/static/freebsd/man7/named_attribute.7 new file mode 100644 index 00000000..a0599ef7 --- /dev/null +++ b/static/freebsd/man7/named_attribute.7 @@ -0,0 +1,320 @@ +.\" +.\" Copyright (c) 2025 Rick Macklem +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd August 5, 2025 +.Dt NAMED_ATTRIBUTE 7 +.Os +.Sh NAME +.Nm named_attribute +.Nd Solaris-like extended attribute system interface +.Sh DESCRIPTION +Description of the system interface for named attributes +(the NFS Version 4 terminology). +.Ss Introduction +This document describes an alternate system interface for extended +attributes as compared to +.Xr extattr 2 . +It is based on the interface provided by Solaris and NFS Version 4. +.Pp +This interface associates a directory, known as a named attribute directory, +to a file system object. +This directory is read in the same manner as a normal directory via the +.Xr getdents 2 +or +.Xr getdirentries 2 +system calls. +The +.Pa .\& +and +.Pa ..\& +entries refer to the directory itself and to the associated file object, +respectively. +The other entries in this directory +are the names of the extended attributes for the associated file object +and are referred to as named attributes. +These named attributes are regular files used to store the attribute's +value. +.Pp +A named attribute directory does not live in the file system's name space. +It is accessed via an +.Xr open 2 +or +.Xr openat 2 +system call done on a file to query the named attributes for the file, +with the +.Dv O_NAMEDATTR +flag specified and a +.Fa path +argument of +.Pa .\& . +This file descriptor can be used as the +.Fa fd +argument for a variety of system calls, such as: +.Xr fchdir 2 , +.Xr unlinkat 2 +and +.Xr renameat 2 . +.Xr renameat 2 +is only permitted to rename a named attribute within the same named +attribute directory. +.Pp +When a file descriptor for a file object in the file system's namespace +is used as the +.Fa fd +argument of an +.Xr openat 2 +along with the +.Fa flag +.Dv O_NAMEDATTR +and a +.Fa path +argument that is the name of a named attribute (not +.Pa .\& +or +.Pa ..\& +), a file descriptor for the named attribute is returned. +If the +.Fa flag +.Dv O_CREAT +is specified, the named attribute will be created if it does not exist. +The +.Fa path +argument must be a single component name, with no embedded +.Dq / +in it. +I/O on these named attribute file descriptors may be performed by +standard I/O system calls +such as: +.Xr read 2 , +.Xr write 2 , +.Xr lseek 2 +and +.Xr ftruncate 2 . +.Pp +The +.Dv _PC_NAMEDATTR_ENABLED +.Fa name +argument to +.Xr pathconf 2 +will return 1 if the file system supports named attributes. +The +.Dv _PC_HAS_NAMEDATTR +.Fa name +argument to +.Xr pathconf 2 +will return 1 if there are one or more named attributes for the file. +If an application does a +.Xr openat 2 +of +.Dq .\& +to open a named attribute directory when no named attribute directory exists, +an empty named attribute directory will be created. +Testing +.Dv _PC_HAS_NAMEDATTR +can be done to avoid creating these named attribute directories unnecessarily. +.Pp +The named attribute interface is a different mechanism/system call interface for +manipulating extended attributes compared with +.Xr extattr 2 . +Although the named attribute machanism might require different internal +implementation +of extended attributes within a file system, both ZFS and NFSv4 provide +both mechanisms, which can be used interchangeably to manipulate +extended attributes, but with a few limitations. +.Bl -bullet +.It +The +.Xr extattr 2 +interface requires that an extended attribute's value be set or acquired +via a single system call using a single buffer. +This limits the size of the attribute's value. +.It +The named attribute interface does not support system namespace +extended attributes and, +as such, system namespace extended attributes must be manipulated via +.Xr extattr 2 . +.It +For ZFS, if an extended attribute with a value +that is a small length in bytes is created when the ZFS +.Dv xattr +property is set to +.Dq sa , +that extended attribute is only visible via +.Xr extattr 2 +and not as a named attribute. +Archiving/de-archiving the file via +.Xr tar 1 +after setting the +.Dv xattr +property to +.Dq dir +will make the attribute(s) visible as both named attributes +and via +.Xr extattr 2 . +.It +For ZFS, it is also possible to create two attributes with the same +name by creating one when the ZFS +.Dv xattr +property is set to +.Dq sa +and then creating another one with the same name after the ZFS +property +.Dv xattr +has been changed to +.Dq dir . +The one created when the ZFS +.Dv xattr +property is set to +.Dq sa +may be removed via +.Xr rmextattr 8 . +.It +To avoid these issues for ZFS, it is strongly recommended that the ZFS +property +.Dv xattr +be set to +.Dq dir +as soon as the file system is created, if named attributes +are to be used on the file system. +.El +.Pp +The named attribute mechanism/system call interface provides certain +advantages over +.Xr extattr 2 . +Since the attribute's value is updated via +.Xr read 2 +and +.Xr write 2 +system calls, the attribute's data may be as large as any regular file +and may be partially updated. +(Note that this interface does not provide the atomicity guarantee that +.Xr extattr 2 +does.) +The permission to access a named attribute directory is determined from +the access control information for the associated file object. +However, access control information can be set on each individual attribute +in a manner similar to a regular file. +This provides +.Dq per attribute +granular control over attribute permissions via +.Xr fchown 2 . +.Pp +At this time, the only local file system which supports this interface +is ZFS and only if the +.Dv xattr +property is set to +.Dq dir . +(Note that, even when +.Dq zfs get xattr +shows +.Dq on +the command +.Dq zfs set xattr=dir +must be done, followed by a remount to make the setting take effect.) +A NFSv4 mount will also support this interface, but only if the NFSv4 +server file system supports named attributes (the openattr operation). +The +.Fx +NFSv4 server supports named attributes only +for ZFS exported file systems where the +.Dq xattr +property is set to +.Dq dir +for the file system. +.Sh EXAMPLES +.Bd -literal +#include +#include +#include +#include + +\&... + +/* For a file called "myfile". Failure checks removed for brevity. */ +int file_fd, nameddir_fd, namedattr_fd; +ssize_t siz; +char buf[DIRBLKSIZ], *cp; +struct dirent *dp; +long named_enabled, has_named_attrs; + +\&... +/* Check to see if named attributes are supported. */ +named_enabled = pathconf("myfile", _PC_NAMEDATTR_ENABLED); +if (named_enabled <= 0) + err(1, "Named attributes not enabled"); +/* Test to see if named attribute(s) exist for the file. */ +has_named_attrs = pathconf("myfile", _PC_HAS_NAMEDATTR); +if (has_named_attrs == 1) + printf("myfile has named attribute(s)\\n"); +else + printf("myfile does not have any named attributes\\n"); +/* Open a named attribute directory. */ +file_fd = open("myfile", O_RDONLY, 0); +nameddir_fd = openat(file_fd, ".", O_NAMEDATTR, 0); +\&... +/* and read it, assuming it all fits in DIRBLKSIZ for simplicity. */ +siz = getdents(fd, buf, sizeof(buf)); +cp = buf; +while (cp < &buf[siz]) { + dp = (struct dirent *)cp; + printf("name=%s\\n", dp->d_name); + cp += dp->d_reclen; +} +\&... +/* Open/create a named attribute called "foo". */ +namedattr_fd = openat(file_fd, "foo", O_CREAT | O_RDWR | + O_TRUNC | O_NAMEDATTR, 0600); +\&... +/* Write foo's attribute value. */ +write(namedattr_fd, "xxxyyy", 6); +\&... +/* Read foo's attribute value. */ +lseek(namedattr_fd, 0, SEEK_SET); +siz = read(namedattr_fd, buf, sizeof(buf)); +\&... +/* And close "foo". */ +close(namedattr_fd); +\&... +/* Rename "foo" to "oldfoo". */ +renameat(nameddir_fd, "foo", nameddir_fd, "oldfoo"); +/* and delete "oldfoo". */ +unlinkat(nameddir_fd, "oldfoo", AT_RESOLVE_BENEATH); +.Ed +.Pp +The +.Xr runat 1 +command may be used to perform shell commands on named attributes. +For example: +.Bd -literal +$ runat myfile cp /etc/hosts attrhosts # creates attrhosts +$ runat myfile cat attrhosts # displays contents of attrhosts +$ runat myfile ls -l # lists the attributes for myfile +.Ed +.Pp +If using the +.Xr bash 1 +shell, the command +.Dq cd -@ foo +enters the named attribute directory for the file object +.Dq foo . +.Sh SEE ALSO +.Xr bash 1 , +.Xr runat 1 , +.Xr tar 1 , +.Xr chdir 2 , +.Xr extattr 2 , +.Xr lseek 2 , +.Xr open 2 , +.Xr pathconf 2 , +.Xr read 2 , +.Xr rename 2 , +.Xr truncate 2 , +.Xr unlinkat 2 , +.Xr write 2 , +.Xr zfsprops 7 , +.Xr rmextattr 8 +.Sh HISTORY +This interface first appeared in +.Fx 15.0 . diff --git a/static/freebsd/man7/networking.7 b/static/freebsd/man7/networking.7 new file mode 100644 index 00000000..2174577e --- /dev/null +++ b/static/freebsd/man7/networking.7 @@ -0,0 +1,93 @@ +.\" +.\" Copyright (c) 2024 Alexander Ziaee. Ohio. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd March 21, 2025 +.Dt NETWORKING 7 +.Os +.Sh NAME +.Nm networking , +.Nm wifi +.Nd quickstart guide to connecting to a network +.Sh DESCRIPTION +In the following examples, it is assumed that +we are connecting to Ethernet with the first interface found by the +.Xr ix 4 +driver, and Wi-Fi with the first interface found by the +.Xr iwlwifi 4 +driver, though your hardware will vary. +.Sh EXAMPLES +.Bl -tag -width 0n +.It Sy Example 1: Connecting to an Ethernet network with DHCP +.Pp +Ask for a DHCP lease on the first Intel 10Gb Ethernet interface: +.Bd -literal -offset 2n +.Ic # dhclient ix0 +.Ed +.It Sy Example 2: Connecting to a cellular network with USB tethering +.Pp +Ask for a DHCP lease on the first USB tethering interface: +.Bd -literal -offset 2n +.Ic # dhclient ue0 +.Ed +.It Sy Example 3: Connecting to a Wi-Fi network +.Pp +Identify your Wi-Fi hardware: +.Bd -literal -offset 2n +.Ic % sysctl net.wlan.devices +.Ed +.Pp +Create the +.Sy wlan0 +interface with the first Intel Wi-Fi adapter: +.Bd -literal -offset 2n +.Ic # sysrc wlans_iwlwifi0="wlan0" +.Ed +.Pp +Set that interface to ask for a DHCP lease with +.Xr wpa_supplicant 8 : +.Bd -literal -offset 2n +.Ic # sysrc ifconfig_wlan0="WPA SYNCDHCP" +.Ed +.Pp +Enter the details of the Wi-Fi network: +.Bd -literal -offset 2n +.Ic # cd /etc/ +.Ic # wpa_passphrase \(dqmyssid\(dq \(dqmypassphrase\(dq >> wpa_supplicant.conf +.Ed +.Pp +Restart the network interface daemon: +.Bd -literal -offset 2n +.Ic # service netif restart +.Ed +.It Sy Example 4: Scanning for Wi-Fi networks +.Bd -literal -offset 2n +.Ic % ifconfig wlan0 scan +.Ed +.It Sy Example 5: Airplane mode +.Bd -literal -offset 2n +.Ic # service netif stop +.Ed +.El +.Sh SEE ALSO +.Xr bsdconfig 8 , +.Xr dhclient 8 , +.Xr ifconfig 8 , +.Xr wpa_passphrase 8 +.Pp +The Advanced Networking chapter of the +.Fx +Handbook. +.Sh CAVEATS +Shell Special Characters in the +.Ar SSID +or +.Ar passphrase +will need to be escaped for +.Xr wpa_passphrase 8 , +commonly using +.Ql \e , +see the manual page for your shell for more details. +.Pp +Stopping the network interface service also stops internal networking. diff --git a/static/freebsd/man7/operator.7 b/static/freebsd/man7/operator.7 new file mode 100644 index 00000000..8d6f0d70 --- /dev/null +++ b/static/freebsd/man7/operator.7 @@ -0,0 +1,61 @@ +.\" Copyright (c) 1989, 1990, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 8, 2009 +.Dt OPERATOR 7 +.Os +.Sh NAME +.Nm operator +.Nd C and C++ operator precedence and order of evaluation +.Sh DESCRIPTION +.Bd -ragged -offset indent -compact +.Bl -column "! ~ ++ -- - (type) * & sizeof new delete" +.It Sy "Operator Associativity" +.It "-------- -------------" +.It "() [] -> . left to right" +.It "! ~ ++ -- - (type) * & sizeof new delete right to left" +.It "->* .* left to right" +.It "* / % left to right" +.It "+ - left to right" +.It "<< >> left to right" +.It "< <= > >= left to right" +.It "== != left to right" +.It "& left to right" +.It "^ left to right" +.It "| left to right" +.It "&& left to right" +.It "|| left to right" +.It "?: right to left" +.It "= += -= *= /= %= <<= >>= &= ^= |= throw right to left" +.It "?: (C++, third operand) right to left" +.It ", left to right" +.El +.Ed +.Sh FILES +.Bl -tag -width /usr/share/misc/operator -compact +.It Pa /usr/share/misc/operator +.El diff --git a/static/freebsd/man7/orders.7 b/static/freebsd/man7/orders.7 new file mode 100644 index 00000000..c1c2c120 --- /dev/null +++ b/static/freebsd/man7/orders.7 @@ -0,0 +1,115 @@ +.\" $NetBSD: orders.7,v 1.6 2011/08/06 11:07:18 jruoho Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 November 20, 2022 +.Dt ORDERS 7 +.Os +.Sh NAME +.Nm orders +.Nd orders of magnitude +.Sh DESCRIPTION +The following table lists common multiples of bytes. +.Bl -column -offset 2n \ +"Kilobyte" "Prefix" "Power of 2" "Power of 10" +.It Sy Name Ta Sy Prefix Ta Sy Power of 2 Ta Sy Power of 10 +.It Kilobyte Ta kB Ta 2^10 Ta 10^3 +.It Megabyte Ta MB Ta 2^20 Ta 10^6 +.It Gigabyte Ta GB Ta 2^30 Ta 10^9 +.It Terabyte Ta TB Ta 2^40 Ta 10^12 +.It Petabyte Ta PB Ta 2^50 Ta 10^15 +.It Exabyte Ta EB Ta 2^60 Ta 10^18 +.It Zettabyte Ta ZB Ta 2^70 Ta 10^21 +.It Yottabyte Ta YB Ta 2^80 Ta 10^24 +.It Ronnabyte Ta RB Ta 2^90 Ta 10^27 +.It Quettabyte Ta QB Ta 2^100 Ta 10^30 +.El +.Pp +The following table lists common bit rates as a power of ten. +.Bl -column -offset 2n \ +"Megabit per second" "Prefix" "Bit per second" "Byte per second" +.It Sy Name Ta Sy Prefix Ta Sy Bit per second Ta Sy Byte per second +.It Bit per second Ta bit/s Ta 1 Ta 0.125 +.It Byte per second Ta B/s Ta 8 Ta 1 +.It Kilobit per second Ta kbit/s Ta 10^3 Ta 125 +.It Kilobyte per second Ta kB/s Ta 8 * 10^3 Ta 1000 +.It Megabit per second Ta Mbit/s Ta 10^6 Ta 125000 +.It Megabyte per second Ta MB/s Ta 8 * 10^6 Ta 1000000 +.It Gigabit per second Ta Gbit/s Ta 10^9 Ta 125000000 +.It Gigabyte per second Ta GB/s Ta 8 * 10^9 Ta 1000000000 +.It Terabit per second Ta Tbit/s Ta 10^12 Ta 125000000000 +.It Terabyte per second Ta TB/s Ta 8 * 10^12 Ta 1000000000000 +.El +.Pp +The following table lists common orders of magnitude as a power of ten. +.Bl -column -offset 2n \ +"Septillionth" "Order" "Prefix" "Symbol" "Decimal" +.It Sy Name Ta Sy Order Ta Sy Prefix Ta Sy Symbol Ta Sy Decimal +.It Nonillionth Ta 10^-30 Ta quecto Ta q Ta 0.000000000000000000000000000001 +.It Octillionth Ta 10^-27 Ta ronto Ta r Ta 0.000000000000000000000000001 +.It Septillionth Ta 10^-24 Ta yocto Ta y Ta 0.000000000000000000000001 +.It Sextillionth Ta 10^-21 Ta zepto Ta z Ta 0.000000000000000000001 +.It Quintillionth Ta 10^-18 Ta atto Ta a Ta 0.000000000000000001 +.It Quadrillionth Ta 10^-15 Ta femto Ta f Ta 0.000000000000001 +.It Trillionth Ta 10^-12 Ta pico Ta p Ta 0.000000000001 +.It Billionth Ta 10^-9 Ta nano Ta n Ta 0.000000001 +.It Millionth Ta 10^-6 Ta micro Ta mu Ta 0.000001 +.It Thousandth Ta 10^-3 Ta milli Ta m Ta 0.001 +.It Hundredth Ta 10^-2 Ta centi Ta c Ta 0.01 +.It Tenth Ta 10^-1 Ta deci Ta d Ta 0.1 +.It One Ta 10^0 Ta - Ta - Ta 1 +.It Ten Ta 10^1 Ta deca Ta da Ta 10 +.It Hundred Ta 10^2 Ta hecto Ta h Ta 100 +.It Thousand Ta 10^3 Ta kilo Ta k Ta 1000 +.It Million Ta 10^6 Ta mega Ta M Ta 1000000 +.It Billion Ta 10^9 Ta giga Ta G Ta 1000000000 +.It Trillion Ta 10^12 Ta tera Ta T Ta 1000000000000 +.It Quadrillion Ta 10^15 Ta peta Ta P Ta 1000000000000000 +.It Quintillion Ta 10^18 Ta exa Ta E Ta 1000000000000000000 +.It Sextillion Ta 10^21 Ta zetta Ta Z Ta 1000000000000000000000 +.It Septillion Ta 10^24 Ta yotta Ta Y Ta 1000000000000000000000000 +.It Octillion Ta 10^27 Ta ronna Ta R Ta 1000000000000000000000000000 +.It Nonillion Ta 10^30 Ta quetta Ta Q Ta 1000000000000000000000000000000 +.El +.Sh SEE ALSO +.Xr units 1 , +.Xr number 6 +.Sh STANDARDS +There have been various attempts to standardize the set of binary prefixes. +Organizations such as International Electrotechnical Commission +.Pq Tn IEC +have proposed new prefixes such as +.Dq kibi , +.Dq mebi , +.Dq gibi , +and +.Dq yobi , +but the adoption has been slow at best. +.Sh AUTHORS +This manual page was written by +.An Jukka Ruohonen Aq Mt jruoho@netbsd.org . diff --git a/static/freebsd/man7/ports.7 b/static/freebsd/man7/ports.7 new file mode 100644 index 00000000..6e28f85d --- /dev/null +++ b/static/freebsd/man7/ports.7 @@ -0,0 +1,788 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 1997 David E. O'Brien +.\" +.\" 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 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 February 21, 2026 +.Dt PORTS 7 +.Os +.Sh NAME +.Nm ports +.Nd contributed applications +.Sh DESCRIPTION +The +.Fx +Ports Collection +offers a simple way to compile and install third party applications. +It is also used to build packages, to be installed using +.Xr pkg 8 . +.Pp +The ports tree, typically located at +.Pa /usr/ports , +consists of subdirectories, one for each category; those in turn contain +individual ports. +Each port is a directory with metadata and patches necessary to make +the original application source code compile and run on +.Fx . +Compiling an application is as simple as typing +.Dq Li "make build" +in the port directory. +The +.Pa Makefile +automatically fetches the +application source code, either from a local disk or the network, unpacks it, +applies the patches, and compiles it. +It also recursively handles dependencies \(em other pieces of software +the port depends on in order to build and work. +Afterwards, +.Dq Li "make install" +installs the application. +.Pp +The +.Fx +Ports Collection is maintained in several branches, which differ mostly +by versions of software provided: the +.Em main +branch contains all the latest changes and corresponds to the +.Em latest +package set, while the +.Em quarterly +branches only provide critical fixes. +The +.Em main +branch can be cloned and updated from the Git repository located at: +.Pp +.Lk https://git.FreeBSD.org/ports.git +.Pp +so eg: +.Pp +.Cm git clone https://git.FreeBSD.org/ports.git +.Pp +The +.Em quarterly +branches can be found in Git as branches like +.Pa yyyyQn +, where +.Em yyyy +indicates the year and +.Em n +indicates the quarter +.Po 1 to 4 +.Pc , eg: +.Pp +.Cm git clone -b 2021Q2 https://git.FreeBSD.org/ports.git +.Pp +It is generally a good idea to use the +.Nm +branch that matches the +.Xr pkg 8 +repository being used. +By default, for +.Fx CURRENT +the +.Xr pkg 8 +is configured to install packages built from the +.Em main +branch, while for +.Fx STABLE +or RELEASE versions it is configured to install packages built from +the latest +.Em quarterly +branch. +Currently configured +.Xr pkg 8 +repository can be verified by looking at the +.Em url +field in +.Cm pkg -vv +output. +.Pp +For more information about using ports, see the +.Dq "Packages and Ports" section +in +.Sm off +.%B "The FreeBSD Handbook" +.No \&: +.Sm on +.Pp +.Lk https://docs.FreeBSD.org/en/books/handbook/ports/ +.Pp +For information about creating new ports, see +.Sm off +.%B "The Porter's Handbook" +.No \&: +.Sm on +.Pp +.Lk https://docs.FreeBSD.org/en/books/porters-handbook/ +.Sh TARGETS +Some of the +.Xr make 1 +targets work recursively through subdirectories. +This lets you, for example, install all of the +.Dq Li biology +ports with one command. +The targets that do this are +.Cm build , checksum , clean , configure , +.Cm depends , extract , fetch , install , +and +.Cm package . +.Pp +The following targets will be run automatically by each proceeding +target in order. +That is, +.Cm build +will be run (if necessary) by +.Cm install , +and so on all the way to +.Cm fetch . +Usually, you will only use the +.Cm install +target. +.Bl -tag -width ".Cm configure" +.It Cm config +Configure +.Va OPTIONS +for this port using +.Xr portconfig 1 Pq Pa ports/ports-mgmt/portconfig . +.It Cm fetch +Fetch all of the files needed to build this port from the sites +listed in +.Va MASTER_SITES +and +.Va PATCH_SITES . +See +.Va FETCH_CMD , MASTER_SITE_OVERRIDE +and +.Va MASTER_SITE_BACKUP . +.It Cm checksum +Verify that the fetched distfile's checksum matches the one the port was +tested against. +If the distfile's checksum does not match, it also fetches the distfiles +which are missing or failed the checksum calculation. +Defining +.Va NO_CHECKSUM +will skip this step. +.It Cm depends +Install +(or compile if only compilation is necessary) +any dependencies of the current port. +When called by the +.Cm extract +or +.Cm fetch +targets, this is run in piecemeal as +.Cm fetch-depends , build-depends , +etc. +Defining +.Va NO_DEPENDS +will skip this step. +.It Cm extract +Expand the distfile into a work directory. +.It Cm patch +Apply any patches that are necessary for the port. +.It Cm configure +Configure the port. +Some ports will ask you questions during this stage. +See +.Va INTERACTIVE +and +.Va BATCH . +.It Cm build +Build the port. +This is the same as calling the +.Cm all +target. +.It Cm install +Install the port and register it with the package system. +This is all you really need to do. +.It Cm install-missing-packages +Install missing dependencies from packages instead of building them. +.El +.Pp +The following targets are not run during the normal install process. +.Bl -tag -width ".Cm fetch-recursive" +.It Cm showconfig +Display +.Va OPTIONS +config for this port. +.It Cm showconfig-recursive +Display +.Va OPTIONS +config for this port and all its dependencies. +.It Cm rmconfig +Remove +.Va OPTIONS +config for this port. +.It Cm rmconfig-recursive +Remove +.Va OPTIONS +config for this port and all its dependencies. +.It Cm config-conditional +Skip the ports which have already had their +.Va OPTIONS +configured. +.It Cm config-recursive +Configure +.Va OPTIONS +for this port and all its dependencies using +.Xr portconfig 1 Pq Pa ports/ports-mgmt/portconfig . +.It Cm fetch-list +Show the list of files to fetch in order to build the port (but not its +dependencies). +.It Cm fetch-recursive +Fetch the distfiles of the port and all its dependencies. +.It Cm fetch-recursive-list +Show list of files that would be retrieved by +.Cm fetch-recursive . +.It Cm build-depends-list , run-depends-list +Print a list of all the direct compile or run dependencies for this port. +.It Cm all-depends-list +Print a list of all recursive dependencies for this port. +.It Cm pretty-print-build-depends-list , pretty-print-run-depends-list +Print a list of all the recursive compile or run dependencies for this port by +port name and version. +.It Cm missing +Print a list of missing dependencies to be installed for the port. +.It Cm clean +Remove the expanded source code. +This recurses to dependencies unless +.Va NOCLEANDEPENDS +is defined. +.It Cm distclean +Remove the port's distfiles and perform the +.Cm clean +target. +The +.Cm clean +portion recurses to dependencies unless +.Va NOCLEANDEPENDS +is defined, but the +.Cm distclean +portion never recurses +(this is perhaps a bug). +.It Cm reinstall +Use this to restore a port after using +.Xr pkg-delete 8 +when you should have used +.Cm deinstall . +.It Cm deinstall +Remove an installed port from the system, similar to +.Xr pkg-delete 8 . +.It Cm deinstall-all +Remove all installed ports with the same +.Va PKGORIGIN +from the system. +.It Cm package +Make a binary package for the port. +The port will be installed if it has not already been. +The package is a +.Pa .pkg +file that you can use to +install the port on other machines with +.Xr pkg-add 8 . +If the directory specified by +.Va PACKAGES +does not exist, the package will be put in +.Pa /usr/ports/category/port/work/pkg . +See +.Va PKGREPOSITORY +and +.Va PKGFILE +for more information. +.It Cm package-recursive +Like +.Cm package , +but makes a package for each depending port as well. +.It Cm package-name +Prints the name with version of the port. +.It Cm readmes +Create a port's +.Pa README.html . +This can be used from +.Pa /usr/ports +to create a browsable web of all ports on your system! +.It Cm search +Search the +.Pa INDEX +file for the pattern specified by the +.Va key +(searches the port name, comment, and dependencies), +.Va name +(searches the port name only), +.Va path +(searches the port path), +.Va info +(searches the port info), +.Va maint +(searches the port maintainer), +.Va cat +(searches the port category), +.Va bdeps +(searches the port build-time dependency), +.Va rdeps +(searches the port run-time dependency), +.Va www +(searches the port web site) +.Xr make 1 +variables, and their exclusion counterparts: +.Va xname , xkey +etc. +For example, one would type: +.Pp +.Dl "cd /usr/ports && make search name=query" +.Pp +to find all ports whose +name matches +.Dq Li query . +Results include the matching ports' path, comment, maintainer, +build dependencies, and run dependencies. +.Bd -literal -offset indent +cd /usr/ports && make search name=pear- \e + xbdeps=apache +.Ed +.Pp +To find all ports whose +names contain +.Dq Li pear- +and which do not have apache +listed in build-time dependencies. +.Bd -literal -offset indent +cd /usr/ports && make search name=pear- \e + xname='ht(tp|ml)' +.Ed +.Pp +To find all ports whose names contain +.Dq Li pear- , +but not +.Dq Li html +or +.Dq Li http . +.Bd -literal -offset indent +make search key=apache display=name,path,info keylim=1 +.Ed +.Pp +To find ports that contain +.Dq Li apache +in either of the name, path, info +fields, ignore the rest of the record. +.Pp +By default the search is not case-sensitive. +In order to make it case-sensitive you can use the +.Va icase +variable: +.Bd -literal -offset indent +make search name=p5-R icase=0 +.Ed +.It Cm quicksearch +Reduced +.Cm search +output. +Only display name, path and info. +.It Cm describe +Generate a one-line description of each port for use in the +.Pa INDEX +file. +.It Cm maintainer +Display the port maintainer's email address. +.It Cm index +Create +.Pa /usr/ports/INDEX , +which is used by the +.Cm pretty-print-* +and +.Cm search +targets. +Running the +.Cm index +target will ensure your +.Pa INDEX +file is up to date with your ports tree. +.It Cm fetchindex +Fetch the +.Pa INDEX +file from the +.Fx +cluster. +.El +.Sh ENVIRONMENT +You can change all of these. +.Bl -tag -width ".Va MASTER_SITES" +.It Va PORTSDIR +Location of the ports tree. +This is +.Pa /usr/ports +by default. +.It Va WRKDIRPREFIX +Where to create any temporary files. +Useful if +.Va PORTSDIR +is read-only (perhaps mounted from a CD-ROM). +.It Va DISTDIR +Where to find/put distfiles, normally +.Pa distfiles/ +in +.Va PORTSDIR . +.It Va SU_CMD +Command used to elevate privilege to configure and install a port. +The unprivileged user must have write access to +.Va WRKDIRPREFIX +and +.Va DISTDIR . +The default is +.Ql /usr/bin/su root -c . +Many users set it to +.Ql /usr/local/bin/sudo -E sh -c +for convenience. +.It Va PACKAGES +Used only for the +.Cm package +target; the base directory for the packages tree, normally +.Pa packages/ +in +.Va PORTSDIR . +If this directory exists, the package tree will be (partially) constructed. +This directory does not have to exist; if it does not, packages will be +placed into the current directory, or you can define one of +.Bl -tag -width ".Va PKGREPOSITORY" +.It Va PKGREPOSITORY +Directory to put the package in. +.It Va PKGFILE +The full path to the package. +.El +.It Va LOCALBASE +Where existing things are installed and where to search for files when +resolving dependencies (usually +.Pa /usr/local ) . +.It Va PREFIX +Where to install this port (usually set to the same as +.Va LOCALBASE ) . +.It Va MASTER_SITES +Primary sites for distribution files if not found locally. +.It Va PATCH_SITES +Primary locations for distribution patch files if not found +locally. +.It Va MASTER_SITE_FREEBSD +If set, go to the master +.Fx +site for all files. +.It Va MASTER_SITE_OVERRIDE +Try going to these sites for all files and patches, first. +.It Va MASTER_SITE_BACKUP +Try going to these sites for all files and patches, last. +.It Va RANDOMIZE_MASTER_SITES +Try the download locations in a random order. +.It Va MASTER_SORT +Sort the download locations according to user supplied pattern. +Example: +.Dl .dk .sunet.se .se dk.php.net .no .de heanet.dl.sourceforge.net +.It Va MASTER_SITE_INDEX +Where to get +.Pa INDEX +source built on +.Fx +cluster (for +.Cm fetchindex +target). +Defaults to +.Pa https://download.FreeBSD.org/ports/index/ . +.It Va FETCHINDEX +Command to get +.Pa INDEX +(for +.Cm fetchindex +target). +Defaults to +.Dq Li "fetch -am" . +.It Va NOCLEANDEPENDS +If defined, do not let +.Cm clean +recurse to dependencies. +.It Va FETCH_CMD +Command to use to fetch files. +Normally +.Xr fetch 1 . +.It Va FORCE_PKG_REGISTER +If set, overwrite any existing package registration on the system. +.It Va INTERACTIVE +If defined, only operate on a port if it requires interaction. +.It Va BATCH +If defined, only operate on a port if it can be installed 100% automatically. +.It Va DISABLE_VULNERABILITIES +If defined, disable check for security vulnerabilities using +.Xr pkg-audit 8 +when installing new ports. +.It Va NO_IGNORE +If defined, allow installation of ports marked as +.Aq Va FORBIDDEN . +The default behavior of the Ports framework is to abort when the +installation of a forbidden port is attempted. +Of course, these ports may not work as expected, but if you really know +what you are doing and are sure about installing a forbidden port, then +.Va NO_IGNORE +lets you do it. +.It Va NO_CHECKSUM +If defined, skip verifying the port's checksum. +.It Va TRYBROKEN +If defined, attempt to build a port even if it is marked as +.Aq Va BROKEN . +.It Va PORT_DBDIR +Directory where the results of configuring +.Va OPTIONS +are stored. +Defaults to +.Pa /var/db/ports . +Each port where +.Va OPTIONS +have been configured will have a uniquely named sub-directory, containing a +single file +.Pa options . +.El +.Sh MAKE VARIABLES +The following list provides a name and short description for many of the +variables that are used when building ports. +More information on these and other related variables may be found in +.Pa ${PORTSDIR}/Mk/* +and the +.Fx +Porter's Handbook. +.Bl -tag -width "WITH_CCACHE_BUILD" +.It Va WITH_DEBUG +.Pq Vt bool +If set, debugging symbols are installed for ports binaries. +.It Va WITH_DEBUG_PORTS +A list of origins for which to set +.Va WITH_DEBUG . +.It Va DEBUG_FLAGS +.Pq Default: Ql -g +Additional +.Va CFLAGS +to set when +.Va WITH_DEBUG +is set. +.It Va DEFAULT_VERSIONS +Override the default variant used for ports +with multiple concurrent versions in the tree, +such as database or compiler versions. +.It Va WITH_CCACHE_BUILD +.Pq Vt bool +If set, enables the use of +.Xr ccache 1 +for building ports. +.It Va CCACHE_DIR +Which directory to use for the +.Xr ccache 1 +data. +.El +.Sh FILES +.Bl -tag -width "/usr/ports/Mk/bsd.port.mk" -compact +.It Pa /usr/ports/ +The default ports directory. +.It Pa /usr/ports/Mk/bsd.port.mk +The big Kahuna. +.It Pa /var/db/ports/ +The directory where the results of configuring +.Va OPTIONS +are stored. +.It Pa ${PORT}/Makefile +The specification for building the port. +.It Pa ${PORT}/distfiles +The directory where fetched files are stored. +.It Pa ${PORT}/distinfo +The checksums generated with +.Ql make makesum . +.It Pa ${PORT}/files/ +The directory for any patches. +.It Pa ${PORT}/pkg-descr +The long description of the port. +.It Pa ${PORT}/pkg-plist +The list of all files installed by the port. +.It Pa ${PORT}/work +The port's building and staging directory. +.El +.Sh EXAMPLES +.Bl -tag -width 0n +.It Sy Example 1\&: No Building and Installing a Port +.Pp +The following command builds and installs Emacs. +.Bd -literal -offset 2n +.Li # Ic cd /usr/ports/editors/emacs +.Li # Ic make install +.Ed +.It Sy Example 2\&: No Installing Dependencies with Xr pkg 8 +.Pp +The following example shows how to build and install a port without having to +build its dependencies. +Instead, the dependencies are downloaded via +.Xr pkg 8 . +.Bd -literal -offset 2n +.Li # Ic make install-missing-packages +.Li # Ic make install +.Ed +.Pp +It is especially useful, when the dependencies are costly +in time and resources to build +.Pq like Pa lang/rust . +The drawback is that +.Xr pkg 8 +offers only packages built with the default set of +.Va OPTIONS . +.It Sy Example 3\&: No Building a Non-Default Flavor of a Port +.Pp +The following command builds a non-default flavor of a port. +(In this case +.Pa devel/py-pip +is going to be built with Python 3.7 support.) +.Bd -literal -offset 2n +.Li # Ic cd /usr/ports/devel/py-pip +.Li # Ic env FLAVOR=py37 make build +.Ed +.It Sy Example 4\&: No Setting Ports Options via Xr make.conf 5 +.Pp +The following lines present various ways of configuring ports options via +.Xr make.conf 5 +(as an alternative to, e.g., running +.Dq Li make config ) : +.Bd -literal -offset 2n +# Enable NLS for all ports unless configured otherwise +# using the options dialog. +OPTIONS_SET= NLS +# Disable DOCS for all ports overriding the options set +# via the options dialog. +OPTIONS_UNSET_FORCE= DOCS +# Disable DOCS and EXAMPLES for the shells/zsh port. +shells_zsh_UNSET= DOCS EXAMPLES +.Ed +.Pp +These and other options-related variables are documented in +.Pa /usr/ports/Mk/bsd.options.mk . +.It Sy Example 5\&: No Setting Xr make 1 Variables for Specific Ports via Xr make.conf 5 +.Pp +The following example shows how to set arbitrary +.Xr make 1 +variables only specific ports: +.Bd -literal -offset 2n +# Set DISABLE_MAKE_JOBS for the lang/rust port: +\&.if ${.CURDIR:M*/lang/rust} +DISABLE_MAKE_JOBS= yes +TRYBROKEN= yes +\&.endif +.Ed +.It Sy Example 6\&: No Debugging Ports +By default ports are built and packaged without debugging support (e.g., +debugging symbols are stripped from binaries, optimization flags are used for +compiling, verbose logging is disabled). +Whether ports are built with debugging symbols can be controlled by the +settings in +.Xr make.conf 5 , +e.g., +.Bd -literal -offset 2n +# Enable debugging for all ports. +WITH_DEBUG= yes +# Enable debugging for selected ports. +WITH_DEBUG_PORTS= mail/dovecot security/krb5 +.Ed +.Pp +It is also possible to use the debug variables on the command line: +.Bd -literal -offset 2n +.Li # Ic make WITH_DEBUG DEBUG_FLAGS="-g -O0" build +.Ed +.Pp +See the +.Sx MAKE VARIABLES +section to learn more about the debug variables. +.Pp +To understand the details of what happens when the debug variables are set it +is best to consult the files located at +.Pa ${PORTSDIR}/Mk/* +.Po Pa bsd.port.mk +in particular +.Pc . +.Pp +If debugging is enabled for a specific port, the ports framework will: +.Bl -bullet +.It +Add +.Va DEBUG_FLAGS +(defaults to +.Ql -g ) +to +.Va CFLAGS . +.It +Try to prevent the binaries from being stripped (including checking the install +target to replace +.Ql install-strip +with +.Ql install ) . +Whether a binary has been stripped can be checked with +.Xr file 1 . +.It +Try to enable other debugging features like debug build type or verbose logging. +However, this is port-specific and the ports framework might not be aware of +each supported debugging feature a given piece of software has to offer). +.El +.El +.Sh SEE ALSO +.Xr make 1 , +.Xr make.conf 5 , +.Xr development 7 , +.Xr pkg 7 +.Pp +Additional developer documentation: +.Bl -dash -width "" -offset indent +.It +.Xr portlint 1 +.It +.Pa /usr/ports/Mk/bsd.port.mk +.El +.Pp +Additional user documentation: +.Bl -dash -width "" -offset indent +.It +.Xr pkg 8 +.It +.Lk "https://ports.FreeBSD.org" "Searchable index of all ports" +.El +.Sh HISTORY +The Ports Collection +appeared in +.Fx 1.0 . +It has since spread to +.Nx , +.Ox , +and macOS. +.Sh AUTHORS +.An -nosplit +This manual page was originated by +.An David O'Brien . +.Sh BUGS +Ports documentation is split over four places \(em +.Pa /usr/ports/Mk/bsd.port.mk , +.%B "The Porter's Handbook" , +the +.Dq "Packages and Ports" +chapter of +.%B "The FreeBSD Handbook" , +and +this manual page. diff --git a/static/freebsd/man7/release.7 b/static/freebsd/man7/release.7 new file mode 100644 index 00000000..3309b7ed --- /dev/null +++ b/static/freebsd/man7/release.7 @@ -0,0 +1,806 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2002 Murray Stokely +.\" 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 ``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 October 13, 2025 +.Dt RELEASE 7 +.Os +.Sh NAME +.Nm release +.Nd "release building infrastructure" +.Sh DESCRIPTION +.Fx +provides a complete build environment suitable for users to make +full releases of the +.Fx +operating system. +All of the tools necessary to build a release are available from the +.Fx +source code repository in +.Pa src/release . +A complete release can be built with only a single command, +including the creation of ISO images suitable for burning to CD-ROM, +memory stick images, and a network install directory. +This command is aptly named +.Dq Li "make release" . +.Pp +For some users, it may be desirable to provide an absolutely clean +build environment, with no local modifications to the source tree or to +.Xr make.conf 5 , +and with clean checkouts of specific versions of the doc, src, and ports +trees. +For this purpose, a script +.Pq Pa src/release/release.sh +is provided to automate these checkouts and then execute +.Dq Li "make release" +in a clean +.Xr chroot 8 . +.Pp +Before attempting to build a release, the user is expected to be +familiar with the contents of +.Xr build 7 , +and should have experience upgrading systems from source. +.Pp +The release build process requires that +.Pa /usr/obj +be populated with the output of +.Dq Li "make buildworld" +and +.Dq Li "make buildkernel" . +This is necessary to provide the object files for the release or, when +using +.Pa release.sh , +so that the object files for a complete system can be installed into a clean +.Xr chroot 8 +environment. +.Pp +If the target release build is for a different architecture or machine type, +the +.Va TARGET +and +.Va TARGET_ARCH +variables must be used. +See the supported +.Fa release.conf +variables for more information. +.Pp +The release procedure on some architectures may also require that the +.Xr md 4 +(memory disk) device driver be present in the kernel +.Pq either by being compiled in or available as a module . +.Pp +This document does not cover source code management, quality +assurance, or other aspects of the release engineering process. +.Sh CLEAN RELEASE GENERATION +Official releases of +.Fx +are produced in a clean environment to +ensure consistency between the versions of the src, ports, and doc trees +and to avoid contamination from the host system +.Po such as local patches, changes +to +.Xr make.conf 5 , +etc. +.Pc . +This is accomplished using the wrapper script +.Pa src/release/release.sh . +.Pp +.Ic release.sh +.Op Fl c Ar release.conf +.Pp +.Ic release.sh +checks out the +.Li src/ , +.Li ports/ , +and +.Li doc/ +trees to +.Va CHROOTDIR , +then calls +.Dq Li "make buildworld" +and +.Dq Li "make installworld" +to generate a +.Xr chroot 8 +environment. +Next, +.Dq Li "make release" +is run within the +.Xr chroot 8 +environment and places the result in +.Pa $CHROOTDIR/R . +.Pp +The optional +.Fa release.conf +configuration file supports the following variables: +.Bl -tag -width Ev +.It Va CHROOTDIR +The directory within which the release will be built. +Defaults to +.Pa /scratch . +.It Va CHROOT_MAKEENV +Additional +.Xr make 1 +arguments to pass through, which directly affect the +tuning of the build chroot. +.It Va NOGIT +Do not explicitly require the +.Xr git 1 +port to be installed. +.It Va GITROOT +The +.Xr git 1 +host used to check out the various trees. +Defaults to +.Pa https://git.FreeBSD.org . +.It Va SRCBRANCH +The +.Li src/ +branch to use. +Defaults to +.Fl b Va main . +.It Va PORTBRANCH +The +.Li ports/ +branch to use. +Defaults to +.Va head/@rHEAD . +.It Va TARGET +The target machine type for cross-building a release. +.It Va TARGET_ARCH +The target machine architecture for cross-building a release. +.Pp +For the supported list of +.Va TARGET +and +.Va TARGET_ARCH +combinations, consult the output of +.Dq make targets +as documented in +.Xr build 7 . +.It Va KERNEL +The target kernel configuration to use. +Defaults to +.Va GENERIC . +Multiple +.Va KERNEL +entries may be specified. +.It Va MAKE_CONF +The +.Xr make.conf 5 +to use for the release build. +Defaults to +.Fa /dev/null +to prevent polluting the release with local system changes. +.It Va SRC_CONF +The +.Xr src.conf 5 +to use for the release build. +Defaults to +.Fa /dev/null +to prevent polluting the release with local system changes. +.It Va MAKE_FLAGS +Additional flags to pass to +.Xr make 1 . +.It Va WORLD_FLAGS +Additional flags to pass to +.Xr make 1 +during the +.Dq buildworld +phase. +Defaults to setting the number of +.Xr make 1 +jobs +.Pq Ar -j +to the number of CPUs available on a SMP-capable system. +.It Va KERNEL_FLAGS +Additional flags to pass to +.Xr make 1 +during the +.Dq buildkernel +phase. +Defaults to setting the number of +.Xr make 1 +jobs +.Pq Ar -j +to half the number of CPUs available on a SMP-capable system. +.It Va NOPORTS +Set to a non-empty value to skip the +.Li ports/ +tree checkout. +When set, +.Va NOPORTS +will prevent the +.Fa ports.txz +distribution package from being created. +.It Va WITH_DVD +Set to a non-empty value to include the +.Cm dvdrom +target. +.It Va WITH_COMPRESSED_IMAGES +Set to a non-empty value to compress the release images with +.Xr xz 1 . +The original +.Pq uncompressed +images are not removed. +.It Va XZ_THREADS Pq Vt int +Set to the number of threads +.Xr xz 1 +should use when compressing images. +By default, +.Va XZ_THREADS +is set to +.Va 0 , +which uses all available cores on the system. +.It Va VCSCMD +The command run to obtain the source trees. +Defaults to +.Qq Cm git clone Fl q . +.It Va CHROOTBUILD_SKIP +If defined, the +.Li buildworld , +.Li installworld , +and +.Li distribution +stages of the +.Xr chroot 8 +build environment setup are skipped. +This is intended solely for cases where the +.Xr chroot 8 +userland are provided by alternate means. +.It Va SRC_UPDATE_SKIP +Set to a non-empty value to prevent checkout or update of +.Fa /usr/src +within the +.Xr chroot 8 . +This is intended for use only when +.Fa /usr/src +is expected to exist by alternative means. +.It Va PORTS_UPDATE_SKIP +Set to a non-empty value to prevent checkout or update of +.Fa /usr/ports +within the +.Xr chroot 8 . +This is intended for use only when +.Fa /usr/ports +is expected to exist by alternative means. +.It Va NOPKGBASE +Include legacy tarball distribution sets for use on the install media, +instead of base system packages. +.It Va PKG_CMD +A path to the +.Xr pkg 8 +executable to use when installing packages in release images as a non-root user. +.It Va PKG_REPOS_DIR +An optional path to a directory containing +.Xr pkg 8 +repository configuration files. +These configuration files will be used when installing packages in release +images as a non-root user. +.It Va PKG_REPO_NAME +The name of the repository configuration to use when installing packages in +release images as a non-root user. +.El +.Sh EMBEDDED BUILDS +The following +.Fa release.conf +variables are relevant only to release builds for embedded systems: +.Bl -tag -width Ev +.It Va EMBEDDEDBUILD +Set to a non-null value to enable functionality for embedded device +release builds. +.Pp +When set, +.Va WITH_DVD +is unset. +Additionally, +.Va EMBEDDED_TARGET +and +.Va EMBEDDED_TARGET_ARCH +must also be defined. +When the build environment is created, +.Fa release.sh +runs a separate build script located in an architecture-specific +directory in +.Pa src/release/${EMBEDDED_TARGET}/ . +.It Va EMBEDDEDPORTS +Set to the list of any ports that are required for the target device +in the format of +.Fa category/port . +.It Va EMBEDDED_TARGET +When set, its value is passed to +.Xr make 1 +to set the +.Va TARGET +.Pq value of Cm uname Fl m +to cross build the target userland. +.It Va EMBEDDED_TARGET_ARCH +When set, its value is passed to +.Xr make 1 +to set the +.Va TARGET_ARCH +.Pq value of Cm uname Fl p +to cross build the target userland. +.El +.Sh VIRTUAL MACHINE DISK IMAGES +The following +.Fa release.conf +variables are relevant only to virtual machine disk image builds: +.Bl -tag -width Ev +.It Va WITH_VMIMAGES +Set to a non-null value to build virtual machine disk images as part +of the release build. +.Va WITH_VMIMAGES +may also be specified as an environment variable passed to +.Xr make 1 . +.It Va WITH_COMPRESSED_VMIMAGES +Set to a non-null value to compress the virtual machine disk images with +.Xr xz 1 +as part of the +.Cm install +.Xr make 1 +target. +Note that compressing virtual machine disk images may take a very long +time on some systems. +.It Va VMBASE +Set to change the name of the resulting virtual machine disk image file. +The default value is +.Va vm . +.It Va VMSIZE +Set to change the size of the virtual machine disk capacity. +The default value is +.Va 20g . +See +.Xr makefs 8 +for valid values. +.Pp +Virtual machine disk images are, by default, created as sparse images. +When +.Va WITH_COMPRESSED_VMIMAGES +is used, the resulting files compressed with +.Xr xz 1 +compress to roughly the same size, regardless of the specified disk image +size. +.It Va VMFS +(Deprecated.) +Set to specify which of the filesystem(s) listed in +.Va VMFSLIST +is linked to the historical non-filesystem-labelled file name. +Valid values are +.Va ufs +and +.Va zfs . +The default value is +.Va ufs . +.It Va VMFSLIST +Set to specify the list of file system types to build images for. +Valid values are one or both of +.Va ufs +and +.Va zfs . +The default value is +.Va ufs zfs . +.It Va VMFORMATS +Set to the target virtual disk image format(s) to create. +By default, the +.Va vhdf , Va vmdk , Va qcow2 , +and +.Va raw +formats are created. +See +.Xr mkimg 1 +for valid format values. +.El +.Pp +For a list of supported +.Va VMFORMATS +values +.Pq including cloud hosting provider formats +along with a brief description, run: +.Bd -literal -offset indent +cd /usr/src +make -C release list-vmtargets +.Ed +.Sh CLOUD HOSTING MACHINE IMAGES +The +.Fx +release build tools support building virtual machine images for various +cloud hosting providers, each with their own specific configuration to +include support for each hosting provider by default. +.Pp +The following +.Xr make 1 +environment variables are supported: +.Bl -tag -width Ev +.It Va CLOUDWARE +Set to a list of one or more cloud hosting providers, enclosed in quotes. +Requires +.Va WITH_CLOUDWARE +to also be set. +.It Va WITH_CLOUDWARE +Set to a non-empty value to enable building virtual machine images +for various cloud hosting providers. +Requires +.Va CLOUDWARE +to also be set. +.El +.Pp +Additionally, the +.Va CLOUDWARE +and +.Va WITH_CLOUDWARE +variables can be added to +.Pa release.conf , +and used in conjunction with +.Pa release.sh . +.Pp +For a list of supported +.Va CLOUDWARE +values, run: +.Bd -literal -offset indent +cd /usr/src +make -C release list-cloudware +.Ed +.Sh OCI IMAGES +The +.Fx +release build tools have experimental support for building +Open Container Initiative (OCI) format container base images. +This is enabled using a +.Fa release.conf +variable: +.Bl -tag -width Ev +.It Va WITH_OCIIMAGES +Set to a non-null value to build OCI base images. +.El +.Sh MAKEFILE TARGETS +The release makefile +.Pq Pa src/release/Makefile +is fairly abstruse. +Most developers will only be concerned with the +.Cm release +and +.Cm install +targets. +.\" XXX: Some sort of introduction to this list? All the others have one. +.Bl -tag -width ".Cm packagesystem" +.It Cm release +Meta-target to build all release media and distributions applicable to this +platform. +.It Cm install +Copy all produced release media to +.Pa ${DESTDIR} . +.It Cm cdrom +Builds installation CD-ROM images. +This may require the +.Xr md 4 +(memory disk) device driver be present in the kernel +(either by being compiled in or available as a module). +This target produces files called +.Pa disc1.iso +and +.Pa bootonly.iso +as its output. +.It Cm dvdrom +Builds installation DVD-ROM images. +This may require the +.Xr md 4 +(memory disk) device driver be present in the kernel +(either by being compiled in or available as a module). +This target produces the +.Pa dvd1.iso +file as its output. +.It Cm memstick +Builds an installation memory stick image named +.Pa memstick.img . +Not applicable on all platforms. +Requires that the +.Xr md 4 +.Pq memory disk +device driver be present in the kernel +.Pq either by being compiled in or available as a module . +.It Cm mini-memstick +Similar to +.Cm memstick , +with the exception that the installation distribution sets +are not included. +.It Cm ftp +Creates a directory named +.Pa ftp +containing the distribution files used in network installations +and suitable for upload to an FTP mirror. +.It Cm vm-image +Creates virtual machine disk images in various formats. +The +.Cm vm-image +target requires the +.Va WITH_VMIMAGES +.Xr make 1 +environment variable to be set to a non-null value. +.It Cm vm-cloudware +Builds +.Fx +virtual machine images for various cloud hosting providers. +See +.Qq CLOUD HOSTING MACHINE IMAGES +for implementation details. +.It Cm list-cloudware +Displays the list of valid +.Va CLOUDWARE +values. +.It Cm list-vmtargets +Displays the list of valid +.Va VMFORMATS +and +.Va CLOUDWARE +values. +.El +.Pp +Major subtargets called by targets above: +.Bl -tag -width ".Cm packagesystem" +.It Cm packagesystem +Generates all the distribution archives +.Pq base, kernel, ports, doc +applicable on this platform. +.It Cm disc1 +Builds a bootable installation system containing all the distribution files +packaged by the +.Cm packagesystem +target, and suitable for imaging by the +.Cm cdrom , +.Cm dvdrom +and +.Cm memstick +targets. +.It Cm reldoc +Builds the release documentation. +This includes the release notes, +hardware guide, and installation instructions. +Other documentation, such as the Handbook, +is built during the +.Cm base.txz +target invoked by +.Cm packagesystem . +.El +.Sh ENVIRONMENT +Optional variables: +.Bl -tag -width ".Ev TARGET_ARCH" +.It Ev OSRELEASE +Optional base name for generated media images when invoking the +.Cm install +target +.Pq e.g., FreeBSD-12.1-RELEASE-amd64 . +Defaults to the output of +.Ic `uname -s`-`uname -r`-`uname -p` +within the chroot. +.It Ev WORLDDIR +Location of a directory containing the src tree. +By default, the directory +above the one containing the makefile +.Pq Pa src . +.It Ev PORTSDIR +Location of a directory containing the ports tree. +By default, +.Pa /usr/ports . +If it is unset or cannot be found, ports will not be included in the release. +.It Ev NOPORTS +If defined, the Ports Collection will be omitted from the release. +.It Ev NOSRC +If set, do not include system source code in the release. +.It Ev TARGET +The target hardware platform. +This is analogous to the +.Dq Nm uname Fl m +output. +This is necessary to cross-build some target architectures. +For example, cross-building for ARM64 machines requires +.Ev TARGET_ARCH Ns = Ns Li aarch64 +and +.Ev TARGET Ns = Ns Li arm64 . +If not set, +.Ev TARGET +defaults to the current hardware platform. +.It Ev TARGET_ARCH +The target machine processor architecture. +This is analogous to the +.Dq Nm uname Fl p +output. +Set this to cross-build for a different architecture. +If not set, +.Ev TARGET_ARCH +defaults to the current machine architecture, unless +.Ev TARGET +is also set, in which case it defaults to the appropriate +value for that platform. +Typically, one only needs to set +.Ev TARGET . +.El +.Sh FILES +.Bl -tag -compact -width Pa +.It Pa /scratch +.It Pa /usr/doc/Makefile +.It Pa /usr/doc/share/mk/doc.project.mk +.It Pa /usr/ports/Mk/bsd.port.mk +.It Pa /usr/ports/Mk/bsd.sites.mk +.It Pa /usr/share/examples/etc/make.conf +.It Pa /usr/src/Makefile +.It Pa /usr/src/Makefile.inc1 +.It Pa /usr/src/release/Makefile +.It Pa /usr/src/release/Makefile.vm +.It Pa /usr/src/release/release.sh +.It Pa /usr/src/release/release.conf.sample +.It Pa /usr/src/release/tools/*.conf +.It Pa /usr/src/release/tools/vmimage.subr +.El +.Sh EXAMPLES +The following sequence of commands can be used to build a +.Dq "-CURRENT snapshot": +.Bd -literal -offset indent +cd /usr +git clone -b main https://git.freebsd.org/src.git src +cd src +make buildworld buildkernel +cd release +make obj +make release +make install DESTDIR=/var/freebsd-snapshot +.Ed +.Pp +After running these commands, all produced distribution files (tarballs +for FTP, CD-ROM images, etc.) are available in the +.Pa /var/freebsd-snapshot +directory. +.Pp +The following sequence of commands can be used to build a +.Dq "-CURRENT snapshot" +in a clean environment, including ports and documentation: +.Bd -literal -offset indent +cd /usr/src/release +sh release.sh +.Ed +.Pp +Optionally, a configuration file can be used to customize the release build: +.Bd -literal -offset indent +cd /usr/src/release +sh release.sh -c $HOME/release.conf +.Ed +.Pp +Configuration files specific to various supported embedded systems, such as +the Raspberry Pi, exist in the directory corresponding to the +.Va TARGET +.Xr make 1 +variable. +For example, to build an image for 64-bit Raspberry Pis: +.Bd -literal -offset indent +cd /usr/src/release +sh release.sh -c arm64/RPI.conf +.Ed +.Pp +After running these commands, all prepared release files are available in the +.Pa /scratch +directory. +The target directory can be changed by specifying the +.Va CHROOTDIR +variable in +.Li release.conf . +.Sh COMPATIBILITY +The reldoc target was removed in commit f61e92ca5a23, and +.Ev DOCDIR , +.Ev DOCBRANCH , +.Ev DOC_UPDATE_SKIP , +and +.Ev NODOC +are therefore no longer supported. +.Sh SEE ALSO +.Xr cc 1 , +.Xr git 1 Pq Pa ports/devel/git , +.Xr install 1 , +.Xr make 1 , +.Xr mkimg 1 , +.Xr uname 1 , +.Xr md 4 , +.Xr make.conf 5 , +.Xr build 7 , +.Xr ports 7 , +.Xr chroot 8 , +.Xr mtree 8 , +.Xr sysctl 8 +.Rs +.%T "FreeBSD Release Engineering" +.%U https://docs.freebsd.org/en/articles/freebsd-releng/ +.Re +.Rs +.%T "FreeBSD Developers' Handbook" +.%U https://docs.freebsd.org/en/books/developers-handbook/ +.Re +.Sh HISTORY +.Fx +1.x +used a manual checklist, compiled by +.An Rod Grimes , +to produce a release. +Apart from being incomplete, the list put a lot of specific demands on +available file systems and was quite torturous to execute. +.Pp +As part of the +.Fx 2.0 +release engineering effort, significant +effort was spent getting +.Pa src/release/Makefile +into a shape where it could at least automate most of the tediousness +of building a release in a sterile environment. +.Pp +For the +.Fx 9.0 +release, +.Pa src/release/Makefile +was overhauled and the wrapper script +.Pa src/release/generate-release.sh +introduced to support the introduction of a new installer. +.Pp +For the +.Fx 9.2 +release, +.Pa src/release/release.sh +was introduced to support per-build configuration files. +.Pa src/release/release.sh +is heavily based on the +.Pa src/release/generate-release.sh +script. +.Pp +At near 1000 revisions spread over multiple branches, the +.Xr git 1 +log of +.Pa src/release/Makefile +contains a vivid historical record of some +of the hardships release engineers go through. +.Sh AUTHORS +.Pa src/release/Makefile +was originally written by +.An -nosplit +.An Rod Grimes , +.An Jordan Hubbard , +and +.An Poul-Henning Kamp . +.Pp +This manual page was originally written by +.An Murray Stokely Aq Mt murray@FreeBSD.org . +.Pp +It was updated by +.An Nathan Whitehorn Aq Mt nwhitehorn@FreeBSD.org +to include the +.Fa generate-release.sh +script used for the +.Fx 9.0 +release cycle. +.Pp +It was later updated by +.An Glen Barber Aq Mt gjb@FreeBSD.org +to include the +.Fa release.sh +script used for the +.Fx 9.2 +release cycle. diff --git a/static/freebsd/man7/sdoc.7 b/static/freebsd/man7/sdoc.7 new file mode 100644 index 00000000..cdfb25f0 --- /dev/null +++ b/static/freebsd/man7/sdoc.7 @@ -0,0 +1,242 @@ +.\" Copyright (c) 2001, 2002 Networks Associates Technology, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The names of the authors 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 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. +.\" +.\" $Id: sec-doc.7,v 1.7 2001/12/22 00:14:12 rwatson Exp$ +.\" +.Dd September 5, 2005 +.Dt SDOC 7 +.Os +.Sh NAME +.Nm sdoc +.Nd guide to adding security considerations sections to manual pages +.Sh DESCRIPTION +This document presents guidelines for +adding security considerations sections to manual pages. +It provides two typical examples. +.Pp +The guidelines for writing +.Fx +manual pages in +.Xr groff_mdoc 7 +mandate that each manual page describing a feature of the +.Fx +system should contain a security considerations section +describing what security requirements can be broken +through the misuse of that feature. +When writing these sections, authors should attempt to +achieve a happy medium between two conflicting goals: +brevity and completeness. +On one hand, security consideration sections must not be too verbose, +or busy readers might be dissuaded from reading them. +On the other hand, security consideration sections must not be incomplete, +or they will fail in their purpose of +instructing the reader on how to avoid all insecure uses. +This document provides guidelines for balancing brevity and completeness +in the security consideration section for a given feature of the +.Fx +system. +.Ss Where to Start +Begin by listing +those general security requirements that can be violated +through the misuse of the feature. +There are four classes of security requirements: +.Bl -hang -offset indent +.It Em integrity +(example: non-administrators should not modify system binaries), +.It Em confidentiality +(example: non-administrators should not view the shadow password file), +.It Em availability +(example: the web server should respond to client requests in a timely +fashion), and +.It Em correctness +(example: the ps program should provide exactly the process table +information listing functionality described in its documentation - no more, +no less.) +.El +.Pp +A good security considerations section +should explain how the feature can be misused +to violate each general security requirement in the list. +Each explanation should be accompanied by instructions +the reader should follow in order to avoid a violation. +When referencing potential vulnerabilities +described in the Secure Programming Practices manual page, +.Xr sprog 7 , +likewise cross-reference that document +rather than replicating information. +Whenever possible, refer to this document +rather than reproducing the material it contains. +.Ss Where to Stop +Security problems are often interrelated; +individual problems often have far-reaching implications. +For example, the correctness of virtually any dynamically-linked program +is dependent on the correct implementation and configuration +of the run-time linker. +The correctness of this program, in turn, +depends on the correctness of its libraries, +the compiler used to build it, +the correctness of the preceding compiler that was used to build that compiler, +and so on, +as described by Thompson (see +.Sx SEE ALSO , +below). +.Pp +Due to the need for brevity, security consideration sections +should describe only those issues directly related to the feature +that is the subject of the manual page. +Refer to other manual pages +rather than duplicating the material found there. +.Sh EXAMPLES +Security considerations sections for most individual functions can follow +this simple formula: +.Pp +.Bl -enum -offset indent -compact +.It +Provide one or two sentences describing each potential security +problem. +.It +Provide one or two sentences describing how to avoid each potential +security problem. +.It +Provide a short example in code. +.El +.Pp +This is an example security considerations section for the +.Xr strcpy 3 +manual page: +.Pp +The +.Fn strcpy +function is easily misused in a manner which enables malicious users +to arbitrarily change a running program's functionality +through a buffer overflow attack. +.Pp +Avoid using +.Fn strcpy . +Instead, use +.Fn strncpy +and ensure that no more characters are copied to the destination buffer +than it can hold. +Do not forget to NUL-terminate the destination buffer, +as +.Fn strncpy +will not terminate the destination string if it is truncated. +.Pp +Note that +.Fn strncpy +can also be problematic. +It may be a security concern for a string to be truncated at all. +Since the truncated string will not be as long as the original, +it may refer to a completely different resource +and usage of the truncated resource +could result in very incorrect behavior. +Example: +.Bd -literal +void +foo(const char *arbitrary_string) +{ + char onstack[8]; + +#if defined(BAD) + /* + * This first strcpy is bad behavior. Do not use strcpy()! + */ + (void)strcpy(onstack, arbitrary_string); /* BAD! */ +#elif defined(BETTER) + /* + * The following two lines demonstrate better use of + * strncpy(). + */ + (void)strncpy(onstack, arbitrary_string, sizeof(onstack) - 1); + onstack[sizeof(onstack - 1)] = '\\0'; +#elif defined(BEST) + /* + * These lines are even more robust due to testing for + * truncation. + */ + if (strlen(arbitrary_string) + 1 > sizeof(onstack)) + err(1, "onstack would be truncated"); + (void)strncpy(onstack, arbitrary_string, sizeof(onstack)); +#endif +} +.Ed +.Pp +Security considerations sections for tools and commands +are apt to be less formulaic. +Let your list of potentially-violated security requirements +be your guide; +explain each one and list a solution in as concise a manner as possible. +.Pp +This is an example security considerations section for the +.Xr rtld 1 +manual page: +.Pp +Using the LD_LIBRARY_PATH and LD_PRELOAD environment variables, +malicious users can cause the dynamic linker +to link shared libraries of their own devising +into the address space of processes running non-set-user-ID/group-ID programs. +These shared libraries can arbitrarily change the functionality +of the program by replacing calls to standard library functions +with calls to their own. +Although this feature is disabled for set-user-ID and set-group-ID programs, +it can still be used to create Trojan horses in other programs. +.Pp +All users should be aware that the correct operation of non +set-user-ID/group-ID dynamically-linked programs depends on the proper +configuration of these environment variables, +and take care to avoid actions that might set them to values +which would cause the run-time linker +to link in shared libraries of unknown pedigree. +.Sh SEE ALSO +.Xr groff_mdoc 7 , +.Xr security 7 , +.Xr sprog 7 +.Rs +.%A "Edward Amoroso, AT&T Bell Laboratories" +.%B "Fundamentals of Computer Security Technology" +.%I "P T R Prentice Hall" +.%D "1994" +.Re +.Rs +.%A "Ken Thompson" +.%T "Reflections on Trusting Trust" +.%J "Communications of the ACM" +.%I "Association for Computing Machinery, Inc." +.%P "761-763" +.%N "Vol. 27, No. 8" +.%D "August, 1984" +.Re +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 5.0 . +.Sh AUTHORS +.An Tim Fraser Aq Mt tfraser@tislabs.com , +NAI Labs CBOSS project +.An Brian Feldman Aq Mt bfeldman@tislabs.com , +NAI Labs CBOSS project diff --git a/static/freebsd/man7/security.7 b/static/freebsd/man7/security.7 new file mode 100644 index 00000000..395cf082 --- /dev/null +++ b/static/freebsd/man7/security.7 @@ -0,0 +1,1127 @@ +.\" Copyright (C) 1998 Matthew Dillon. All rights reserved. +.\" Copyright (c) 2019 The FreeBSD Foundation +.\" +.\" Parts of this documentation were written by +.\" Konstantin Belousov under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd March 22, 2026 +.Dt SECURITY 7 +.Os +.Sh NAME +.Nm security , +.Nm securelevel +.Nd introduction to security under FreeBSD +.Sh DESCRIPTION +See +.Xr mitigations 7 +for a description of vulnerability mitigations in +.Fx . +This man page documents other +.Fx +security related topics. +.Pp +Security is a function that begins and ends with the system administrator. +While all +.Bx +multi-user systems have some inherent security, the job of building and +maintaining additional security mechanisms to keep users +.Dq honest +is probably +one of the single largest undertakings of the sysadmin. +Machines are +only as secure as you make them, and security concerns are ever competing +with the human necessity for convenience. +.Ux +systems, +in general, are capable of running a huge number of simultaneous processes +and many of these processes operate as servers \(em meaning that external +entities can connect and talk to them. +As yesterday's mini-computers and mainframes +become today's desktops, and as computers become networked and internetworked, +security becomes an ever bigger issue. +.Pp +Security is best implemented through a layered onion approach. +In a nutshell, +what you want to do is to create as many layers of security as are convenient +and then carefully monitor the system for intrusions. +.Pp +System security also pertains to dealing with various forms of attacks, +including attacks that attempt to crash or otherwise make a system unusable +but do not attempt to break root. +Security concerns can be split up into +several categories: +.Bl -enum -offset indent +.It +Denial of Service attacks (DoS) +.It +User account compromises +.It +Root compromise through accessible servers +.It +Root compromise via user accounts +.It +Backdoor creation +.El +.Pp +A denial of service attack is an action that deprives the machine of needed +resources. +Typically, DoS attacks are brute-force mechanisms that attempt +to crash or otherwise make a machine unusable by overwhelming its servers or +network stack. +Some DoS attacks try to take advantages of bugs in the +networking stack to crash a machine with a single packet. +The latter can +only be fixed by applying a bug fix to the kernel. +Attacks on servers can +often be fixed by properly specifying options to limit the load the servers +incur on the system under adverse conditions. +Brute-force network attacks are harder to deal with. +A spoofed-packet attack, for example, is +nearly impossible to stop short of cutting your system off from the Internet. +It may not be able to take your machine down, but it can fill up your Internet +pipe. +.Pp +A user account compromise is even more common than a DoS attack. +Some +sysadmins still run +.Nm telnetd +and +.Xr ftpd 8 +servers on their machines. +These servers, by default, do not operate over encrypted +connections. +The result is that if you have any moderate-sized user base, +one or more of your users logging into your system from a remote location +(which is the most common and convenient way to log in to a system) +will have his or her password sniffed. +The attentive system administrator will analyze +his remote access logs looking for suspicious source addresses +even for successful logins. +.Pp +One must always assume that once an attacker has access to a user account, +the attacker can break root. +However, the reality is that in a well secured +and maintained system, access to a user account does not necessarily give the +attacker access to root. +The distinction is important because without access +to root the attacker cannot generally hide his tracks and may, at best, be +able to do nothing more than mess with the user's files or crash the machine. +User account compromises are very common because users tend not to take the +precautions that sysadmins take. +.Pp +System administrators must keep in mind that there are potentially many ways +to break root on a machine. +The attacker may know the root password, +the attacker +may find a bug in a root-run server and be able to break root over a network +connection to that server, or the attacker may know of a bug in an SUID-root +program that allows the attacker to break root once he has broken into a +user's account. +If an attacker has found a way to break root on a machine, +the attacker may not have a need to install a backdoor. +Many of the root holes found and closed to date involve a considerable amount +of work by the attacker to clean up after himself, so most attackers do install +backdoors. +This gives you a convenient way to detect the attacker. +Making +it impossible for an attacker to install a backdoor may actually be detrimental +to your security because it will not close off the hole the attacker used to +break in originally. +.Pp +Security remedies should always be implemented with a multi-layered +.Dq onion peel +approach and can be categorized as follows: +.Bl -enum -offset indent +.It +Securing root and staff accounts +.It +Securing root \(em root-run servers and SUID/SGID binaries +.It +Securing user accounts +.It +Securing the password file +.It +Securing the kernel core, raw devices, and file systems +.It +Quick detection of inappropriate changes made to the system +.It +Paranoia +.El +.Sh SECURING THE ROOT ACCOUNT AND SECURING STAFF ACCOUNTS +Do not bother securing staff accounts if you have not secured the root +account. +Most systems have a password assigned to the root account. +The +first thing you do is assume that the password is +.Em always +compromised. +This does not mean that you should remove the password. +The +password is almost always necessary for console access to the machine. +What it does mean is that you should not make it possible to use the password +outside of the console or possibly even with a +.Xr su 1 +utility. +For example, make sure that your PTYs are specified as being +.Dq Li insecure +in the +.Pa /etc/ttys +file +so that direct root logins via +.Xr telnet 1 +are disallowed. +If using +other login services such as +.Xr sshd 8 , +make sure that direct root logins are +disabled there as well. +Consider every access method \(em services such as +.Xr ftp 1 +often fall through the cracks. +Direct root logins should only be allowed +via the system console. +.Pp +Of course, as a sysadmin you have to be able to get to root, so we open up +a few holes. +But we make sure these holes require additional password +verification to operate. +One way to make root accessible is to add appropriate +staff accounts to the +.Dq Li wheel +group (in +.Pa /etc/group ) . +The staff members placed in the +.Li wheel +group are allowed to +.Xr su 1 +to root. +You should never give staff +members native +.Li wheel +access by putting them in the +.Li wheel +group in their password entry. +Staff accounts should be placed in a +.Dq Li staff +group, and then added to the +.Li wheel +group via the +.Pa /etc/group +file. +Only those staff members who actually need to have root access +should be placed in the +.Li wheel +group. +It is also possible, when using an +authentication method such as Kerberos, to use Kerberos's +.Pa .k5login +file in the root account to allow a +.Xr ksu 1 +to root without having to place anyone at all in the +.Li wheel +group. +This +may be the better solution since the +.Li wheel +mechanism still allows an +intruder to break root if the intruder has gotten hold of your password +file and can break into a staff account. +While having the +.Li wheel +mechanism +is better than having nothing at all, it is not necessarily the safest +option. +.Pp +An indirect way to secure the root account is to secure your staff accounts +by using an alternative login access method and *'ing out the crypted password +for the staff accounts. +This way an intruder may be able to steal the password +file but will not be able to break into any staff accounts or root, even if +root has a crypted password associated with it (assuming, of course, that +you have limited root access to the console). +Staff members +get into their staff accounts through a secure login mechanism such as +.Xr kerberos 8 +or +.Xr ssh 1 +using a private/public +key pair. +When you use something like Kerberos you generally must secure +the machines which run the Kerberos servers and your desktop workstation. +When you use a public/private key pair with SSH, you must generally secure +the machine you are logging in +.Em from +(typically your workstation), +but you can +also add an additional layer of protection to the key pair by password +protecting the keypair when you create it with +.Xr ssh-keygen 1 . +Being able +to star-out the passwords for staff accounts also guarantees that staff +members can only log in through secure access methods that you have set up. +You can +thus force all staff members to use secure, encrypted connections for +all their sessions which closes an important hole used by many intruders: that +of sniffing the network from an unrelated, less secure machine. +.Pp +The more indirect security mechanisms also assume that you are logging in +from a more restrictive server to a less restrictive server. +For example, +if your main box is running all sorts of servers, your workstation should not +be running any. +In order for your workstation to be reasonably secure +you should run as few servers as possible, up to and including no servers +at all, and you should run a password-protected screen blanker. +Of course, given physical access to +a workstation, an attacker can break any sort of security you put on it. +This is definitely a problem that you should consider but you should also +consider the fact that the vast majority of break-ins occur remotely, over +a network, from people who do not have physical access to your workstation or +servers. +.Pp +Using something like Kerberos also gives you the ability to disable or +change the password for a staff account in one place and have it immediately +affect all the machines the staff member may have an account on. +If a staff +member's account gets compromised, the ability to instantly change his +password on all machines should not be underrated. +With discrete passwords, changing a password on N machines can be a mess. +You can also impose +re-passwording restrictions with Kerberos: not only can a Kerberos ticket +be made to timeout after a while, but the Kerberos system can require that +the user choose a new password after a certain period of time +(say, once a month). +.Sh SECURING ROOT \(em ROOT-RUN SERVERS AND SUID/SGID BINARIES +The prudent sysadmin only runs the servers he needs to, no more, no less. +Be aware that third party servers are often the most bug-prone. +For example, +running an old version of +.Xr imapd 8 +or +.Xr popper 8 Pq Pa ports/mail/popper +is like giving a universal root +ticket out to the entire world. +Never run a server that you have not checked +out carefully. +Many servers do not need to be run as root. +For example, +the +.Xr talkd 8 , +.Xr comsat 8 , +and +.Xr fingerd 8 +daemons can be run in special user +.Dq sandboxes . +A sandbox is not perfect unless you go to a large amount of trouble, but the +onion approach to security still stands: if someone is able to break in +through a server running in a sandbox, they still have to break out of the +sandbox. +The more layers the attacker must break through, the lower the +likelihood of his success. +Root holes have historically been found in +virtually every server ever run as root, including basic system servers. +If you are running a machine through which people only log in via +.Xr sshd 8 +and never log in via +.Nm telnetd +then turn off this service! +.Pp +.Fx +now defaults to running +.Xr talkd 8 , +.Xr comsat 8 , +and +.Xr fingerd 8 +in a sandbox. +Depending on whether you +are installing a new system or upgrading an existing system, the special +user accounts used by these sandboxes may not be installed. +The prudent +sysadmin would research and implement sandboxes for servers whenever possible. +.Pp +There are a number of other servers that typically do not run in sandboxes: +.Xr sendmail 8 , +.Xr popper 8 , +.Xr imapd 8 , +and others. +There are alternatives to +some of these, but installing them may require more work than you are willing +to put +(the convenience factor strikes again). +You may have to run these +servers as root and rely on other mechanisms to detect break-ins that might +occur through them. +.Pp +The other big potential root hole in a system are the SUID-root and SGID +binaries installed on the system. +Most of these binaries, such as +.Xr su 1 , +reside in +.Pa /bin , /sbin , /usr/bin , +or +.Pa /usr/sbin . +While nothing is 100% safe, +the system-default SUID and SGID binaries can be considered reasonably safe. +Still, root holes are occasionally found in these binaries. +A root hole +was found in Xlib in 1998 that made +.Xr xterm 1 Pq Pa ports/x11/xterm +(which is typically SUID) +vulnerable. +It is better to be safe than sorry and the prudent sysadmin will restrict SUID +binaries that only staff should run to a special group that only staff can +access, and get rid of +.Pq Dq Li "chmod 000" +any SUID binaries that nobody uses. +A server with no display generally does not need an +.Xr xterm 1 Pq Pa ports/x11/xterm +binary. +SGID binaries can be almost as dangerous. +If an intruder can break an SGID-kmem binary the +intruder might be able to read +.Pa /dev/kmem +and thus read the crypted password +file, potentially compromising any passworded account. +Alternatively an +intruder who breaks group +.Dq Li kmem +can monitor keystrokes sent through PTYs, +including PTYs used by users who log in through secure methods. +An intruder +that breaks the +.Dq Li tty +group can write to almost any user's TTY. +If a user +is running a terminal +program or emulator with a keyboard-simulation feature, the intruder can +potentially +generate a data stream that causes the user's terminal to echo a command, which +is then run as that user. +.Sh SECURING USER ACCOUNTS +User accounts are usually the most difficult to secure. +While you can impose +draconian access restrictions on your staff and *-out their passwords, you +may not be able to do so with any general user accounts you might have. +If +you do have sufficient control then you may win out and be able to secure the +user accounts properly. +If not, you simply have to be more vigilant in your +monitoring of those accounts. +Use of SSH and Kerberos for user accounts is +more problematic due to the extra administration and technical support +required, but still a very good solution compared to a crypted password +file. +.Sh SECURING THE PASSWORD FILE +The only sure fire way is to *-out as many passwords as you can and +use SSH or Kerberos for access to those accounts. +Even though the +crypted password file +.Pq Pa /etc/spwd.db +can only be read by root, it may +be possible for an intruder to obtain read access to that file even if the +attacker cannot obtain root-write access. +.Pp +Your security scripts should always check for and report changes to +the password file +(see +.Sx CHECKING FILE INTEGRITY +below). +.Sh SECURING THE KERNEL CORE, RAW DEVICES, AND FILE SYSTEMS +If an attacker breaks root he can do just about anything, but there +are certain conveniences. +For example, most modern kernels have a packet sniffing device driver built in. +Under +.Fx +it is called +the +.Xr bpf 4 +device. +An intruder will commonly attempt to run a packet sniffer +on a compromised machine. +You do not need to give the intruder the +capability and most systems should not have the +.Xr bpf 4 +device compiled in. +.Pp +But even if you turn off the +.Xr bpf 4 +device, you still have +.Pa /dev/mem +and +.Pa /dev/kmem +to worry about. +For that matter, +the intruder can still write to raw disk devices. +Also, there is another kernel feature called the module loader, +.Xr kldload 8 . +An enterprising intruder can use a KLD module to install +his own +.Xr bpf 4 +device or other sniffing device on a running kernel. +To avoid these problems you have to run +the kernel at a higher security level, at least level 1. +The security level can be set with a +.Xr sysctl 8 +on the +.Va kern.securelevel +variable. +Once you have +set the security level to 1, write access to raw devices will be denied and +special +.Xr chflags 1 +flags, such as +.Cm schg , +will be enforced. +You must also ensure +that the +.Cm schg +flag is set on critical startup binaries, directories, and +script files \(em everything that gets run +up to the point where the security level is set. +This might be overdoing it, and upgrading the system is much more +difficult when you operate at a higher security level. +You may compromise and +run the system at a higher security level but not set the +.Cm schg +flag for every +system file and directory under the sun. +Another possibility is to simply +mount +.Pa / +and +.Pa /usr +read-only. +It should be noted that being too draconian in +what you attempt to protect may prevent the all-important detection of an +intrusion. +.Pp +The kernel runs with five different security levels. +Any super-user process can raise the level, but no process +can lower it. +The security levels are: +.Bl -tag -width flag +.It Ic -1 +Permanently insecure mode \- always run the system in insecure mode. +This is the default initial value. +.It Ic 0 +Insecure mode \- immutable and append-only flags may be turned off. +All devices may be read or written subject to their permissions. +.It Ic 1 +Secure mode \- the system immutable and system append-only flags may not +be turned off; +disks for mounted file systems, +.Pa /dev/mem +and +.Pa /dev/kmem +may not be opened for writing; +.Pa /dev/io +(if your platform has it) may not be opened at all; +kernel modules (see +.Xr kld 4 ) +may not be loaded or unloaded. +The kernel debugger may not be entered using the +.Va debug.kdb.enter +sysctl unless a +.Xr mac 9 +policy grants access, for example using +.Xr mac_ddb 4 . +A panic or trap cannot be forced using the +.Va debug.kdb.panic , +.Va debug.kdb.panic_str +and other sysctl's. +.It Ic 2 +Highly secure mode \- same as secure mode, plus disks may not be +opened for writing (except by +.Xr mount 2 ) +whether mounted or not. +This level precludes tampering with file systems by unmounting them, +but also inhibits running +.Xr newfs 8 +while the system is multi-user. +.Pp +In addition, kernel time changes are restricted to less than or equal to one +second. +Attempts to change the time by more than this will log the message +.Dq Time adjustment clamped to +1 second . +.It Ic 3 +Network secure mode \- same as highly secure mode, plus +IP packet filter rules (see +.Xr ipfw 8 , +.Xr ipfirewall 4 +and +.Xr pfctl 8 ) +cannot be changed and +.Xr dummynet 4 +or +.Xr pf 4 +configuration cannot be adjusted. +.El +.Pp +The security level can be configured with variables documented in +.Xr rc.conf 5 . +.Sh CHECKING FILE INTEGRITY: BINARIES, CONFIG FILES, ETC +When it comes right down to it, you can only protect your core system +configuration and control files so much before the convenience factor +rears its ugly head. +For example, using +.Xr chflags 1 +to set the +.Cm schg +bit on most of the files in +.Pa / +and +.Pa /usr +is probably counterproductive because +while it may protect the files, it also closes a detection window. +The +last layer of your security onion is perhaps the most important \(em detection. +The rest of your security is pretty much useless (or, worse, presents you with +a false sense of safety) if you cannot detect potential incursions. +Half +the job of the onion is to slow down the attacker rather than stop him +in order to give the detection layer a chance to catch him in +the act. +.Pp +The best way to detect an incursion is to look for modified, missing, or +unexpected files. +The best +way to look for modified files is from another (often centralized) +limited-access system. +Writing your security scripts on the extra-secure limited-access system +makes them mostly invisible to potential attackers, and this is important. +In order to take maximum advantage you generally have to give the +limited-access box significant access to the other machines in the business, +usually either by doing a read-only NFS export of the other machines to the +limited-access box, or by setting up SSH keypairs to allow the limit-access +box to SSH to the other machines. +Except for its network traffic, NFS is +the least visible method \(em allowing you to monitor the file systems on each +client box virtually undetected. +If your +limited-access server is connected to the client boxes through a switch, +the NFS method is often the better choice. +If your limited-access server +is connected to the client boxes through a hub or through several layers +of routing, the NFS method may be too insecure (network-wise) and using SSH +may be the better choice even with the audit-trail tracks that SSH lays. +.Pp +Once you give a limit-access box at least read access to the client systems +it is supposed to monitor, you must write scripts to do the actual +monitoring. +Given an NFS mount, you can write scripts out of simple system +utilities such as +.Xr find 1 +and +.Xr md5 1 . +It is best to physically +.Xr md5 1 +the client-box files boxes at least once a +day, and to test control files such as those found in +.Pa /etc +and +.Pa /usr/local/etc +even more often. +When mismatches are found relative to the base MD5 +information the limited-access machine knows is valid, it should scream at +a sysadmin to go check it out. +A good security script will also check for +inappropriate SUID binaries and for new or deleted files on system partitions +such as +.Pa / +and +.Pa /usr . +.Pp +When using SSH rather than NFS, writing the security script is much more +difficult. +You essentially have to +.Xr scp 1 +the scripts to the client box in order to run them, making them visible, and +for safety you also need to +.Xr scp 1 +the binaries (such as +.Xr find 1 ) +that those scripts use. +The +.Xr sshd 8 +daemon on the client box may already be compromised. +All in all, +using SSH may be necessary when running over unsecure links, but it is also a +lot harder to deal with. +.Pp +A good security script will also check for changes to user and staff members +access configuration files: +.Pa .rhosts , .shosts , .ssh/authorized_keys +and so forth, files that might fall outside the purview of the MD5 check. +.Pp +If you have a huge amount of user disk space it may take too long to run +through every file on those partitions. +In this case, setting mount +flags to disallow SUID binaries on those partitions is a good +idea. +The +.Cm nosuid +option +(see +.Xr mount 8 ) +is what you want to look into. +I would scan them anyway at least once a +week, since the object of this layer is to detect a break-in whether or +not the break-in is effective. +.Pp +Process accounting +(see +.Xr accton 8 ) +is a relatively low-overhead feature of +the operating system which I recommend using as a post-break-in evaluation +mechanism. +It is especially useful in tracking down how an intruder has +actually broken into a system, assuming the file is still intact after +the break-in occurs. +.Pp +Finally, security scripts should process the log files and the logs themselves +should be generated in as secure a manner as possible \(em remote syslog can be +very useful. +An intruder tries to cover his tracks, and log files are critical +to the sysadmin trying to track down the time and method of the initial +break-in. +One way to keep a permanent record of the log files is to run +the system console to a serial port and collect the information on a +continuing basis through a secure machine monitoring the consoles. +.Sh PARANOIA +A little paranoia never hurts. +As a rule, a sysadmin can add any number +of security features as long as they do not affect convenience, and +can add security features that do affect convenience with some added +thought. +Even more importantly, a security administrator should mix it up +a bit \(em if you use recommendations such as those given by this manual +page verbatim, you give away your methodologies to the prospective +attacker who also has access to this manual page. +.Sh SPECIAL SECTION ON DoS ATTACKS +This section covers Denial of Service attacks. +A DoS attack is typically a packet attack. +While there is not much you can do about modern spoofed +packet attacks that saturate your network, you can generally limit the damage +by ensuring that the attacks cannot take down your servers. +.Bl -enum -offset indent +.It +Limiting server forks +.It +Limiting springboard attacks (ICMP response attacks, ping broadcast, etc.) +.It +Kernel Route Cache +.El +.Pp +A common DoS attack is against a forking server that attempts to cause the +server to eat processes, file descriptors, and memory until the machine +dies. +The +.Xr inetd 8 +server +has several options to limit this sort of attack. +It should be noted that while it is possible to prevent a machine from going +down it is not generally possible to prevent a service from being disrupted +by the attack. +Read the +.Xr inetd 8 +manual page carefully and pay specific attention +to the +.Fl c , C , +and +.Fl R +options. +Note that spoofed-IP attacks will circumvent +the +.Fl C +option to +.Xr inetd 8 , +so typically a combination of options must be used. +Some standalone servers have self-fork-limitation parameters. +.Pp +The +.Xr sendmail 8 +daemon has its +.Fl OMaxDaemonChildren +option which tends to work much +better than trying to use +.Xr sendmail 8 Ns 's +load limiting options due to the +load lag. +You should specify a +.Va MaxDaemonChildren +parameter when you start +.Xr sendmail 8 +high enough to handle your expected load but not so high that the +computer cannot handle that number of +.Nm sendmail Ns 's +without falling on its face. +It is also prudent to run +.Xr sendmail 8 +in +.Dq queued +mode +.Pq Fl ODeliveryMode=queued +and to run the daemon +.Pq Dq Nm sendmail Fl bd +separate from the queue-runs +.Pq Dq Nm sendmail Fl q15m . +If you still want real-time delivery you can run the queue +at a much lower interval, such as +.Fl q1m , +but be sure to specify a reasonable +.Va MaxDaemonChildren +option for that +.Xr sendmail 8 +to prevent cascade failures. +.Pp +The +.Xr syslogd 8 +daemon can be attacked directly and it is strongly recommended that you use +the +.Fl s +option whenever possible, and the +.Fl a +option otherwise. +.Pp +You should also be fairly careful +with connect-back services such as tcpwrapper's reverse-identd, which can +be attacked directly. +You generally do not want to use the reverse-ident +feature of tcpwrappers for this reason. +.Pp +It is a very good idea to protect internal services from external access +by firewalling them off at your border routers. +The idea here is to prevent +saturation attacks from outside your LAN, not so much to protect internal +services from network-based root compromise. +Always configure an exclusive +firewall, i.e., +.So +firewall everything +.Em except +ports A, B, C, D, and M-Z +.Sc . +This +way you can firewall off all of your low ports except for certain specific +services such as +.Xr talkd 8 , +.Xr sendmail 8 , +and other internet-accessible services. +If you try to configure the firewall the other +way \(em as an inclusive or permissive firewall, there is a good chance that you +will forget to +.Dq close +a couple of services or that you will add a new internal +service and forget to update the firewall. +You can still open up the +high-numbered port range on the firewall to allow permissive-like operation +without compromising your low ports. +Also take note that +.Fx +allows you to +control the range of port numbers used for dynamic binding via the various +.Va net.inet.ip.portrange +sysctl's +.Pq Dq Li "sysctl net.inet.ip.portrange" , +which can also +ease the complexity of your firewall's configuration. +I usually use a normal +first/last range of 4000 to 5000, and a hiport range of 49152 to 65535, then +block everything under 4000 off in my firewall +(except for certain specific +internet-accessible ports, of course). +.Pp +Another common DoS attack is called a springboard attack \(em to attack a server +in a manner that causes the server to generate responses which then overload +the server, the local network, or some other machine. +The most common attack +of this nature is the ICMP PING BROADCAST attack. +The attacker spoofs ping +packets sent to your LAN's broadcast address with the source IP address set +to the actual machine they wish to attack. +If your border routers are not +configured to stomp on ping's to broadcast addresses, your LAN winds up +generating sufficient responses to the spoofed source address to saturate the +victim, especially when the attacker uses the same trick on several dozen +broadcast addresses over several dozen different networks at once. +Broadcast attacks of over a hundred and twenty megabits have been measured. +A second common springboard attack is against the ICMP error reporting system. +By +constructing packets that generate ICMP error responses, an attacker can +saturate a server's incoming network and cause the server to saturate its +outgoing network with ICMP responses. +This type of attack can also crash the +server by running it out of +.Vt mbuf Ns 's , +especially if the server cannot drain the +ICMP responses it generates fast enough. +The +.Fx +kernel has a new kernel +compile option called +.Dv ICMP_BANDLIM +which limits the effectiveness of these +sorts of attacks. +The last major class of springboard attacks is related to +certain internal +.Xr inetd 8 +services such as the UDP echo service. +An attacker +simply spoofs a UDP packet with the source address being server A's echo port, +and the destination address being server B's echo port, where server A and B +are both on your LAN. +The two servers then bounce this one packet back and +forth between each other. +The attacker can overload both servers and their +LANs simply by injecting a few packets in this manner. +Similar problems +exist with the internal chargen port. +A competent sysadmin will turn off all +of these +.Xr inetd 8 Ns -internal +test services. +.Sh ACCESS ISSUES WITH KERBEROS AND SSH +There are a few issues with both Kerberos and SSH that need to be addressed +if you intend to use them. +Kerberos5 is an excellent authentication +protocol but the kerberized +.Xr telnet 1 +suck rocks. +There are bugs that make them unsuitable for dealing with binary streams. +Also, by default +Kerberos does not encrypt a session unless you use the +.Fl x +option. +SSH encrypts everything by default. +.Pp +SSH works quite well in every respect except when it is set up to +forward encryption keys. +What this means is that if you have a secure workstation holding +keys that give you access to the rest of the system, and you +.Xr ssh 1 +to an +unsecure machine, your keys become exposed. +The actual keys themselves are +not exposed, but +.Xr ssh 1 +installs a forwarding port for the duration of your +login and if an attacker has broken root on the unsecure machine he can utilize +that port to use your keys to gain access to any other machine that your +keys unlock. +.Pp +We recommend that you use SSH in combination with Kerberos whenever possible +for staff logins. +SSH can be compiled with Kerberos support. +This reduces +your reliance on potentially exposable SSH keys while at the same time +protecting passwords via Kerberos. +SSH keys +should only be used for automated tasks from secure machines (something +that Kerberos is unsuited to). +We also recommend that you either turn off +key-forwarding in the SSH configuration, or that you make use of the +.Va from Ns = Ns Ar IP/DOMAIN +option that SSH allows in its +.Pa authorized_keys +file to make the key only usable to entities logging in from specific +machines. +.Sh KNOBS AND TWEAKS +.Fx +provides several knobs and tweak handles that make some introspection +information access more restricted. +Some people consider this as improving system security, so the knobs are +briefly listed there, together with controls which enable some mitigations +of the hardware state leaks. +.Pp +Hardware mitigation sysctl knobs described below have been moved under +.Va machdep.mitigations , +with backwards-compatibility shims to accept the existing names. +A future change will rationalize the sense of the individual sysctls +(so that enabled / true always indicates that the mitigation is active). +For that reason the previous names remain the canonical way to set the +mitigations, and are documented here. +Backwards compatibility shims for the interim sysctls under +.Pa machdep.mitigations +will not be added. +.Bl -tag -width security.bsd.unprivileged_proc_debug +.It Va security.bsd.see_other_uids +Controls visibility and reachability of subjects (e.g., processes) and objects +(e.g., sockets) owned by a different uid. +The knob directly affects the +.Va kern.proc +sysctls filtering of data, which results in restricted output from +utilities like +.Xr ps 1 . +.It Va security.bsd.see_other_gids +Same, for subjects and objects owned by a different gid. +.It Va security.bsd.see_jail_proc +Same, for subjects and objects belonging to a different jail, including +sub-jails. +.It Va security.bsd.conservative_signals +When enabled, unprivileged users are only allowed to send job control +and usual termination signals like +.Dv SIGKILL , +.Dv SIGINT , +and +.Dv SIGTERM , +to the processes executing programs with changed uids. +.It Va security.bsd.unprivileged_proc_debug +Controls availability of the process debugging facilities to non-root users. +See also +.Xr proccontrol 1 +mode +.Dv trace . +.It Va vm.pmap.pti +Tunable, amd64-only. +Enables mode of operation of virtual memory system where usermode page +tables are sanitized to prevent so-called Meltdown information leak on +some Intel CPUs. +By default, the system detects whether the CPU needs the workaround, +and enables it automatically. +See also +.Xr proccontrol 1 +mode +.Dv kpti . +.It Va machdep.mitigations.flush_rsb_ctxsw +amd64. +Controls Return Stack Buffer flush on context switch, to prevent +cross-process ret2spec attacks. +Only needed, and only enabled by default, if the machine +supports SMEP, otherwise IBRS would do necessary flushing on kernel +entry anyway. +.It Va hw.mds_disable +amd64 and i386. +Controls Microarchitectural Data Sampling hardware information leak +mitigation. +.It Va hw.spec_store_bypass_disable +amd64 and i386. +Controls Speculative Store Bypass hardware information leak mitigation. +.It Va hw.ibrs_disable +amd64 and i386. +Controls Indirect Branch Restricted Speculation hardware information leak +mitigation. +.It Va machdep.syscall_ret_flush_l1d +amd64. +Controls force-flush of L1D cache on return from syscalls which report +errors other than +.Ev EEXIST , +.Ev EAGAIN , +.Ev EXDEV , +.Ev ENOENT , +.Ev ENOTCONN , +and +.Ev EINPROGRESS . +This is mostly a paranoid setting added to prevent hypothetical exploitation +of unknown gadgets for unknown hardware issues. +The error codes exclusion list is composed of the most common errors which +typically occurs on normal system operation. +.It Va machdep.nmi_flush_l1d_sw +amd64. +Controls force-flush of L1D cache on NMI; +this provides software assist for bhyve mitigation of L1 terminal fault +hardware information leak. +.It Va hw.vmm.vmx.l1d_flush +amd64. +Controls the mitigation of L1 Terminal Fault in bhyve hypervisor. +.It Va vm.pmap.allow_2m_x_ept +amd64. +Allows the use of superpages for executable mappings under the EPT +page table format used by hypervisors on Intel CPUs to map the guest +physical address space to machine physical memory. +May be disabled to work around a CPU Erratum called +Machine Check Error Avoidance on Page Size Change. +.It Va machdep.mitigations.rngds.enable +amd64 and i386. +Controls mitigation of Special Register Buffer Data Sampling versus +optimization of the MCU access. +When set to zero, the mitigation is disabled, and the RDSEED and RDRAND +instructions do not incur serialization overhead for shared buffer accesses, +and do not serialize off-core memory accesses. +.It Va kern.elf32.aslr.enable +Controls system-global Address Space Layout Randomization (ASLR) for +normal non-PIE (Position Independent Executable) 32-bit ELF binaries. +See also the +.Xr proccontrol 1 +.Dv aslr +mode, also affected by the per-image control note flag. +.It Va kern.elf32.aslr.pie_enable +Controls system-global Address Space Layout Randomization for +position-independent (PIE) 32-bit binaries. +.It Va kern.elf32.aslr.honor_sbrk +Makes ASLR less aggressive and more compatible with old binaries +relying on the sbrk area. +.It Va kern.elf32.aslr.stack +Enable randomization of the stack for 32-bit binaries. +Otherwise, the stack is mapped at a fixed location determined by the +process ABI. +.It Va kern.elf64.aslr.enable +ASLR control for 64-bit ELF binaries. +.It Va kern.elf64.aslr.pie_enable +ASLR control for 64-bit ELF PIEs. +.It Va kern.elf64.aslr.honor_sbrk +ASLR sbrk compatibility control for 64-bit binaries. +.It Va kern.elf64.aslr.stack +Controls stack address randomization for 64-bit binaries. +.It Va kern.elf32.nxstack +Enables non-executable stack for 32-bit processes. +Enabled by default if supported by hardware and corresponding binary. +.It Va kern.elf64.nxstack +Enables non-executable stack for 64-bit processes. +.It Va kern.elf32.allow_wx +Enables mapping of simultaneously writable and executable pages for +32-bit processes. +.It Va kern.elf64.allow_wx +Enables mapping of simultaneously writable and executable pages for +64-bit processes. +.El +.Sh SEE ALSO +.Xr chflags 1 , +.Xr find 1 , +.Xr md5 1 , +.Xr mdo 1 , +.Xr netstat 1 , +.Xr openssl 1 , +.Xr proccontrol 1 , +.Xr ps 1 , +.Xr ssh 1 , +.Xr xdm 1 Pq Pa ports/x11/xorg-clients , +.Xr group 5 , +.Xr ttys 5 , +.Xr mitigations 7 , +.Xr accton 8 , +.Xr init 8 , +.Xr sshd 8 , +.Xr sysctl 8 , +.Xr syslogd 8 , +.Xr vipw 8 +.Sh HISTORY +The +.Nm +manual page was originally written by +.An Matthew Dillon +and first appeared +in +.Fx 3.1 , +December 1998. diff --git a/static/freebsd/man7/simd.7 b/static/freebsd/man7/simd.7 new file mode 100644 index 00000000..a446112e --- /dev/null +++ b/static/freebsd/man7/simd.7 @@ -0,0 +1,246 @@ +.\" Copyright (c) 2023 The FreeBSD Foundation +. +.\" This documentation was written by Robert Clausecker +.\" under sponsorship from the FreeBSD Foundation. +. +.\" 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 October 21, 2025 +.Dt SIMD 7 +.Os +.Sh NAME +.Nm simd +.Nd SIMD enhancements +. +.Sh DESCRIPTION +On some architectures, the +.Fx +.Em libc +provides enhanced implementations of commonly used functions, replacing +the architecture-independent implementations used otherwise. +Depending on architecture and function, an enhanced +implementation of a function may either always be used or the +.Em libc +detects at runtime which SIMD instruction set extensions are +supported and picks the most suitable implementation automatically. +On +.Cm amd64 , +the environment variable +.Ev ARCHLEVEL +can be used to override this mechanism. +.Pp +Enhanced functions are present for the following architectures: +.Bl -column FUNCTION_________ aarch64_ arm_ amd64_ i386_ ppc64_ -offset indent +.It Em FUNCTION Ta Em AARCH64 Ta Em ARM Ta Em AMD64 Ta Em I386 Ta Em PPC64 Ta Em RISC-V +.It bcmp Ta A Ta Ta S1 Ta S +.It bcopy Ta A Ta S Ta S Ta S Ta SV Ta S +.It bzero Ta A Ta S Ta S Ta S Ta Ta S +.It div Ta Ta Ta S Ta S +.It index Ta A Ta Ta S1 Ta Ta S +.It ldiv Ta Ta Ta S Ta S +.It lldiv Ta Ta Ta S +.It memchr Ta A Ta Ta S1 Ta Ta Ta S +.It memcmp Ta A Ta S Ta S1 Ta S +.It memccpy Ta A Ta Ta S1 +.It memcpy Ta AM Ta S Ta S Ta S Ta SV Ta S +.It memmove Ta AM Ta S Ta S Ta S Ta SV +.It memrchr Ta A Ta Ta S1 +.It memset Ta AM Ta S Ta S Ta S Ta Ta S +.It rindex Ta A Ta Ta S1 Ta S Ta Ta S +.It stpcpy Ta A Ta Ta S1 +.It stpncpy Ta Ta Ta S1 +.It strcat Ta A Ta Ta S1 Ta S +.It strchr Ta A Ta Ta S1 Ta S Ta Ta S +.It strchrnul Ta A Ta Ta S1 Ta Ta Ta S +.It strcmp Ta A Ta S Ta S1 Ta S +.It strcpy Ta A Ta Ta S1 Ta S Ta S2 +.It strcspn Ta S Ta Ta S2 +.It strlcat Ta A Ta Ta S1 +.It strlcpy Ta A Ta Ta S1 +.It strlen Ta A Ta S Ta S1 Ta Ta Ta S +.It strncat Ta A Ta Ta S1 +.It strncmp Ta A Ta S Ta S1 Ta S +.It strncpy Ta Ta Ta S1 Ta Ta S2 +.It strnlen Ta A Ta Ta S1 Ta Ta Ta S +.It strrchr Ta A Ta Ta S1 Ta S Ta Ta S +.It strpbrk Ta S Ta Ta S2 +.It strsep Ta S Ta Ta S2 +.It strspn Ta S Ta Ta S2 +.It swab Ta Ta Ta Ta S +.It timingsafe_bcmp Ta A Ta Ta S1 +.It timingsafe_memcmp Ta S Ta Ta S +.It wcschr Ta Ta Ta Ta S +.It wcscmp Ta Ta Ta Ta S +.It wcslen Ta Ta Ta Ta S +.It wmemchr Ta Ta Ta Ta S +.El +.Pp +.Sy S Ns :\ scalar (non-SIMD), +.Sy 1 Ns :\ amd64 baseline, +.Sy 2 Ns :\ x86-64-v2 +or PowerPC\ 2.05, +.Sy 3 Ns :\ x86-64-v3, +.Sy 4 Ns :\ x86-64-v4, +.Sy V Ns :\ PowerPC\ VSX, +.Sy A Ns :\ Arm\ ASIMD (NEON), +.Sy M Ns :\ Arm\ MOPS. +. +.Sh ENVIRONMENT +.Bl -tag +.It Ev ARCHLEVEL +On +.Em amd64 , +controls the level of SIMD enhancements used. +If this variable is set to an architecture level from the list below +and that architecture level is supported by the processor, SIMD +enhancements up to +.Ev ARCHLEVEL +are used. +If +.Ev ARCHLEVEL +is unset, not recognised, or not supported by the processor, the highest +level of SIMD enhancements supported by the processor is used. +.Pp +A suffix beginning with +.Sq ":" +or +.Sq "+" +in +.Ev ARCHLEVEL +is ignored and may be used for future extensions. +The architecture level can be prefixed with a +.Sq "!" +character to force use of the requested architecture level, even if the +processor does not advertise that it is supported. +This usually causes applications to crash and should only be used for +testing purposes or if architecture level detection yields incorrect +results. +.Pp +The architecture levels follow the AMD64 SysV ABI supplement: +.Bl -tag -width x86-64-v2 +.It Cm scalar +scalar enhancements only (no SIMD) +.It Cm baseline +cmov, cx8, x87 FPU, fxsr, MMX, osfxsr, SSE, SSE2 +.It Cm x86-64-v2 +cx16, lahf/sahf, popcnt, SSE3, SSSE3, SSE4.1, SSE4.2 +.It Cm x86-64-v3 +AVX, AVX2, BMI1, BMI2, F16C, FMA, lzcnt, movbe, osxsave +.It Cm x86-64-v4 +AVX-512F/BW/CD/DQ/VL +.El +.El +. +.Sh DIAGNOSTICS +.Bl -diag +.It "Illegal Instruction" +Printed by +.Xr sh 1 +if a command is terminated through delivery of a +.Dv SIGILL +signal, see +.Xr signal 3 . +.Pp +Use of an unsupported architecture level was forced by setting +.Ev ARCHLEVEL +to a string beginning with a +.Sq "!" +character, causing a process to crash due to use of an unsupported +instruction. +Unset +.Ev ARCHLEVEL , +remove the +.Sq "!" +prefix or select a supported architecture level. +.Pp +Message may also appear for unrelated reasons. +.El +. +.Sh SEE ALSO +.Xr string 3 , +.Xr arch 7 +.Rs +.%A H. J. Lu +.%A Michael Matz +.%A Milind Girkar +.%A Jan Hubi\[u010D]ka \" \(vc +.%A Andreas Jaeger +.%A Mark Mitchell +.%B System V Application Binary Interface +.%D May 23, 2023 +.%T AMD64 Architecture Processor Supplement +.%O Version 1.0 +.Re +. +.Sh HISTORY +Architecture-specific enhanced +.Em libc +functions were added starting +with +.Fx 2.0 +for +.Cm i386 , +.Fx 6.0 +for +.Cm arm , +.Fx 6.1 +for +.Cm amd64 , +.Fx 11.0 +for +.Cm aarch64 , +.Fx 12.0 +for +.Cm powerpc64 , +and +.Fx 16.0 +for +.Cm riscv64 . +SIMD-enhanced functions were first added with +.Fx 13.0 +for +.Cm powerpc64 +and with +.Fx 14.1 +for +.Cm amd64 . +.Pp +A +.Nm +manual page appeared in +.Fx 14.1 . +. +.Sh AUTHOR +.An Robert Clausecker Aq Mt fuz@FreeBSD.org +. +.Sh CAVEATS +Other parts of +.Fx +such as cryptographic routines in the kernel or in +OpenSSL may also use SIMD enhancements. +These enhancements are not subject to the +.Ev ARCHLEVEL +variable and may have their own configuration +mechanism. +. +.Sh BUGS +Use of SIMD enhancements cannot be configured on powerpc64. diff --git a/static/freebsd/man7/sizeof.7 b/static/freebsd/man7/sizeof.7 new file mode 100644 index 00000000..b3c3af1a --- /dev/null +++ b/static/freebsd/man7/sizeof.7 @@ -0,0 +1,308 @@ +.\" +.\" Copyright (C) 2022 Jan Schaumann . +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd December 12, 2022 +.Dt sizeof 7 +.Os +.Sh NAME +.Nm sizeof +operator +.Nd yield the storage size of the given operand +.Sh SYNTAX +.Nm Vt ( type ) +.br +.Nm Vt expression +.Sh DESCRIPTION +The +.Nm +operator yields the size of its operand. +The +.Nm +operator cannot be applied to incomplete types and expressions +with incomplete types (e.g. +.Vt void , +or forward-defined +.Vt struct foo ), +and function types. +.Pp +The size of primitive (non-derived) data types in C may differ +across hardware platforms and implementations. +They are defined by corresponding Application Binary Interface (ABI) +specifications, see +.Xr arch 7 +for details about ABI used by +.Fx . +It may be necessary or useful for a program to be able +to determine the storage size of a data type or object +to account for the platform specifics. +.Pp +The unary +.Nm +operator yields the storage size of an expression or +data type in +.Em char sized units +(C language bytes). +As a result, +.Ql sizeof(char) +is always guaranteed to be 1. +(The number of bits per +.Vt char +is given by the +.Dv CHAR_BIT +definition in the +.In limits.h +header; many systems also provide the "number of bits +per byte" definition as +.Dv NBBY +in the +.In sys/param.h +header.) +.Sh EXAMPLES +Different platforms may use different data models. +For example, systems on which integers, longs, and +pointers are using 32 bits (e.g., i386) are referred +to as using the "ILP32" data model, systems using +64 bit longs and pointers (e.g., amd64 / x86_64) +as the "LP64" data model. +.Pp +The following examples illustrate the possible results +of calling +.Nm +on an ILP32 vs. an LP64 system: +.Pp +When applied to a simple variable or data type, +.Nm +returns the storage size of the data type of the object: +.Bl -column -offset indent \ + ".Li sizeof(struct flex)" ".Sy Result (ILP32)" ".Sy Result (LP64)" +.It Sy Object or type \ + Ta Sy Result (ILP32) \ + Ta Sy Result (LP64) +.It Li sizeof(char) \ + Ta 1 \ + Ta 1 +.It Li sizeof(int) \ + Ta 4 \ + Ta 4 +.It Li sizeof(long) \ + Ta 4 \ + Ta 8 +.It Li sizeof(float) \ + Ta 4 \ + Ta 4 +.It Li sizeof(double) \ + Ta 8 \ + Ta 8 +.It Li sizeof(char *) \ + Ta 4 \ + Ta 8 +.El +.Pp +For initialized data or uninitialized arrays of a +fixed size known at compile time, +.Nm +will return the correct storage size: +.Bd -literal -offset indent +#define DATA "1234567890" +char buf1[] = "abc"; +char buf2[1024]; +char buf3[1024] = { 'a', 'b', 'c' }; +.Ed +.Bl -column -offset indent \ + ".Li sizeof(struct flex)" ".Sy Result" +.It Sy Object or type \ + Ta Sy Result +.It Li sizeof(DATA) \ + Ta 11 +.It Li sizeof(buf1) \ + Ta 4 +.It Li sizeof(buf2) \ + Ta 1024 +.It Li sizeof(buf3) \ + Ta 1024 +.El +.Pp +The examples above are the same for ILP32 and LP64 +platforms, as they are based on character units. +.Pp +When applied to a struct or union, +.Nm +returns the total number of bytes in the object, +including any internal or trailing padding used to +align the object in memory. +This result may thus be larger than if the storage +size of each individual member had been added: +.Bd -literal -offset indent +struct s1 { + char c; +}; + +struct s2 { + char *s; + int i; +}; + +struct s3 { + char *s; + int i; + int j; +}; + +struct s4 { + int i; + uint64_t i64; +}; + +struct s5 { + struct s1 a; + struct s2 b; + struct s3 c; + struct s4 d; +}; +.Ed +.Bl -column -offset indent \ + ".Li sizeof(struct flex)" ".Sy Result (ILP32) " ".Sy Result (LP64)" +.It Sy Object or type \ + Ta Sy Result (ILP32) \ + Ta Sy Result (LP64) +.It Li sizeof(struct s1) \ + Ta 1 \ + Ta 1 +.It Li sizeof(struct s2) \ + Ta 8 \ + Ta 16 +.It Li sizeof(struct s3) \ + Ta 12 \ + Ta 16 +.It Li sizeof(struct s4) \ + Ta 12 \ + Ta 16 +.It Li sizeof(struct s5) \ + Ta 36 \ + Ta 56 +.El +.Pp +When applied to a struct containing a flexible array +member, +.Nm +returns the size of the struct +.Em without +the array, although again possibly including any +padding the compiler deemed appropriate: +.Bd -literal -offset indent +struct flex { + char c; + long b; + char array[]; +} +.Ed +.Bl -column -offset indent \ + ".Li sizeof(struct flex)" ".Sy Result (ILP32) " ".Sy Result (LP64)" +.It Sy Object or type \ + Ta Sy Result (ILP32) \ + Ta Sy Result (LP64) +.It Li sizeof(struct flex) \ + Ta 8 \ + Ta 16 +.El +.Pp +One of the more common uses of the +.Nm +operator is to determine the correct amount of memory +to allocate: +.Bd -literal -offset indent +int *nums = calloc(512, sizeof(int)); +.Ed +.Pp +The +.Nm +operator can be used to calculate the number of +elements in an array by dividing the size of the array +by the size of one of its elements: +.Bd -literal -offset indent +int nums[] = { 1, 2, 3, 4, 5 }; +const int howmany = sizeof(nums) / sizeof(nums[0]); +.Ed +.Pp +Many systems provide this shortcut as the macro +.Dv ntimes() +via the +.In sys/param.h +header file. +.Sh RESULT +The result of the +.Nm +operator is an unsigned integer type, defined in the +.Dv stddef.h +header as a +.Vt size_t . +.Sh NOTES +It is a common mistake to apply +.Nm +to a dynamically allocated array: +.Bd -literal -offset indent +char *buf; +if ((buf = malloc(BUFSIZ)) == NULL) { + perror("malloc"); +} +/* Warning: wrong! */ +(void)strncat(buf, input, sizeof(buf) - 1); +.Ed +.Pp +In that case, the operator will return the storage +size of the pointer ( +.Ql sizeof(char *) +), not the +allocated memory. +.Pp +.Nm +determines the +.Ev size +of the result of the expression given, but +.Em does not +evaluate the expression: +.Bd -literal -offset indent +int a = 42; +printf("%ld - %d\\n", sizeof(a = 10), a); /* Result: "4 - 42" */ +.Ed +.Pp +Since it is evaluated by the compiler and not the +preprocessor, the +.Nm +operator cannot be used in a preprocessor expression. +.Sh SEE ALSO +.Xr arch 7 , +.Xr operator 7 +.Sh STANDARDS +The +.Nm +operator conforms to +.St -ansiC . +.Pp +Handling of flexible array members in structures +conforms to +.St -isoC-99 . +.Sh AUTHORS +This manual page was written by +.An Jan Schaumann Aq Mt jschauma@netmeister.org . diff --git a/static/freebsd/man7/sprog.7 b/static/freebsd/man7/sprog.7 new file mode 100644 index 00000000..cc021a39 --- /dev/null +++ b/static/freebsd/man7/sprog.7 @@ -0,0 +1,178 @@ +.\" +.\" Copyright (c) 2001 Eric Melville +.\" 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 June 3, 2001 +.Dt SPROG 7 +.Os +.Sh NAME +.Nm sprog +.Nd secure programming practices +.Sh DESCRIPTION +Security issues have crept into many systems over the years. +This document is a guide for programming practices that prevent these problems. +.Ss Overview +Writing secure applications takes a very scrutinous and pessimistic outlook. +Applications should be run with the principle of +.Dq Li least privilege +so that no process is ever running with more than the bare minimum access it +needs to accomplish its function. +Previously tested code should be reused whenever possible. +Generally, anything beyond the control of a program should never be trusted. +This includes all forms of user input, system resources, interprocess +communication, and the timing of events. +.Ss Buffer Overflows +One of the most common types of security problems is the buffer overflow. +In short, if a program is not careful with the data it receives, it may be +possible for this data to be written across memory, overwriting the return +address for a function call, and the program will be forced to run code that +does unfriendly things. +.Pp +A good number of functions in the standard C library make it difficult or +even impossible to prevent buffer overflows when used. +These include +.Xr fscanf 3 , +.Xr gets 3 , +.Xr getwd 3 , +.Xr realpath 3 , +.Xr scanf 3 , +.Xr sprintf 3 , +.Xr strcat 3 , +.Xr strcpy 3 , +.Xr vscanf 3 , +and +.Xr vsprintf 3 . +.Pp +Many other functions that deal with strings can also open up a potential +buffer overflow when not used carefully. +For example, +.Xr strncat 3 +does not go out of its way to provide +.Tn NUL +character termination. +Of course, the proper length must always be specified. +Usage of +.Xr strlcat 3 +and +.Xr strlcpy 3 +ensure that strings are null terminated and of the specified length. +.Pp +Functions that receive a string format must also be used carefully. +It is possible for a string to contain additional format specifiers, which +open up another possibility for a buffer overflow. +Never pass a string with untrusted data without using +.Ql %s . +Always use the proper secure idiom: +.Pp +.Dl function("%s", string); +.Pp +There are mechanisms that provide a backstop for these problems at the +library and compiler levels, however, there is no substitute for simply +writing good code. +.Ss Set-user-ID Issues +In many cases, it may be necessary for a program to operate with an increased +set of permissions. +Reasons for this include binding to protected sockets, reading and writing +certain files and directories, and access to various resources. +Using a setuid program is frequently the solution. +However, it is important that programs give up these privileges as soon as +possible. +For example, if a program is binding to a protected socket, it should give +up its privileges as soon as it has finished binding to that socket. +This is accomplished with the +.Xr setuid 2 +family of system calls. +.Ss Limited Environments +The traditional method of restricting a process is with the +.Xr chroot 2 +system call. +This system call changes the root directory from which all other paths are +referenced for a process and any child processes. +Of course, the process must have access to this path to begin with. +The new environment does not actually take effect until +.Xr chdir 2 +is called to place the process into the new environment. +Unfortunately, a process can break out of this environment if root access is +obtained. +.Pp +Often, +.Xr jail 2 +can be used to create a more complete and enclosed environment than +.Xr chroot 2 +can provide. +A jail limits all processes inside that environment, including processes with +superuser privileges. +.Pp +Fine grained privileges, as described by +.Tn POSIX Ns .1e +extensions, are currently a work in progress, and the focus of the +.Tn TrustedBSD +Project. +More information can be found at +.Pa http://www.TrustedBSD.org/ . +.Ss Trust +Programs should not make assumptions about the environment in which they are +running. +This includes user input, signals, environment variables, system resources, +interprocess communications, and shared memory, amongst other things that are +beyond the control of the program. +They should not assume that all forms of invalid data can be detected either. +Instead, they should use positive filtering, and only allow a specific subset +of inputs that are known to be safe. +This is the same logic that an administrator should apply to a firewall, that +is, deny by default and specify what is to be accepted. +.Ss Race Conditions +A race condition is anomalous behavior caused by the relative timing of +events. +Programs should not assume that a particular event will occur before another. +The most common causes of race conditions are signals, access checks, and +file reads. +Signals are asynchronous by nature, so special care must be taken +while dealing with them. +Attempting to check access with sequential non-atomic operations is a very +bad idea, as files can be moved and changed at any given time. +Instead of using a sequence of +.Xr access 2 +and +.Xr open 2 , +use +.Xr seteuid 2 +and then call +.Xr open 2 +directly. +Set +.Xr umask 2 +properly beforehand. +.Sh SEE ALSO +.Xr jail 2 , +.Xr setuid 2 , +.Xr strlcat 3 , +.Xr strlcpy 3 +.Sh AUTHORS +.An -nosplit +.An Eric Melville Aq Mt eric@FreeBSD.org +originally wrote this document based on a chapter of the +.%B "FreeBSD Developer's Handbook" +written by +.An Murray Stokely Aq Mt murray@FreeBSD.org . diff --git a/static/freebsd/man7/stats.7 b/static/freebsd/man7/stats.7 new file mode 100644 index 00000000..0b57d525 --- /dev/null +++ b/static/freebsd/man7/stats.7 @@ -0,0 +1,123 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2020 Daniel Ebdrup Jensen +.\" +.\" 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 October 28, 2025 +.Dt STATS 7 +.Os +.Sh NAME +.Nm stats +.Nd information about various and sundry statistics utilities +.Sh DESCRIPTION +The +.Fx +userland in part contains a series of utilities which can be used +to ascertain system state at runtime and optionally from core files. +.Sh COMMANDS +The following commands +.Pq sorted alphabetically +are currently included in the base system, with more appearing periodically. +.Bl -tag -width "zpool iostat" +.It Nm btsockstat +Show Bluetooth socket information +.It Nm ctlstat +CAM Target Layer statistics utility +.It Nm dwatch +Watch processes as they trigger a particular DTrace probe +.It Nm fstat +Identify active files +.It Nm gstat +Print statistics about GEOM disks +.It Nm ibstat +Display information from the InfiniBand driver +.It Nm ifmcstat +Dump multicast group management statistics per interface +.It Nm iostat +Report kernel subsystem I/O statistics +.It Nm ipfstat +Display IPF packet filter statistics and filter list +.It Nm kldstat +Display status of dynamic kernel linker +.It Nm lockstat +Report kernel lock and profiling statistics +.It Nm mailstats +Display mail statistics +.It Nm netstat +Show network status and statistics +.It Nm nfsstat +Display NFS statistics +.It Nm plockstat +Trace pthread lock statistics using DTrace +.It Nm pmcstat +Performance measurement with performance monitoring hardware +.It Nm procstat +Get detailed process information +.It Nm pstat +Display system data structures +.It Nm sockstat +List open sockets +.It Nm stat +Display file status +.It Nm systat +Display system statistics +.It Nm vmstat +Report virtual memory statistics +.It Nm zpool iostat +Report ZFS I/O statistics +.El +.Sh SEE ALSO +.Xr btsockstat 1 , +.Xr dwatch 1 , +.Xr fstat 1 , +.Xr intro 1 , +.Xr lockstat 1 , +.Xr netstat 1 , +.Xr plockstat 1 , +.Xr procstat 1 , +.Xr sockstat 1 , +.Xr stat 1 , +.Xr systat 1 , +.Xr intro 7 , +.Xr tuning 7 , +.Xr ctlstat 8 , +.Xr gstat 8 , +.Xr ibstat 8 , +.Xr ifmcstat 8 , +.Xr intro 8 , +.Xr iostat 8 , +.Xr ipfstat 8 , +.Xr kldstat 8 , +.Xr mailstats 8 , +.Xr pmcstat 8 , +.Xr pstat 8 , +.Xr vmstat 8 , +.Xr zpool 8 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An Daniel Ebdrup Jensen Aq Mt debdrup@FreeBSD.org diff --git a/static/freebsd/man7/stdint.7 b/static/freebsd/man7/stdint.7 new file mode 100644 index 00000000..70bfac4b --- /dev/null +++ b/static/freebsd/man7/stdint.7 @@ -0,0 +1,134 @@ +.\" Copyright (c) 2002 Mike Barcroft +.\" 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 September 15, 2002 +.Dt STDINT 7 +.Os +.Sh NAME +.Nm stdint +.Nd "standard integer types" +.Sh SYNOPSIS +.In stdint.h +.Sh DESCRIPTION +The +.In stdint.h +header provides source-portable integer types of a specific +size, smallest memory footprint with a minimum size, fastest +access speed with a minimum size, largest integer size, and +those capable of storing pointers. +.Pp +The types +.Vt int8_t , +.Vt int16_t , +.Vt int32_t , +and +.Vt int64_t +provide a signed integer type of width 8, 16, 32, or 64 bits, respectively. +The types +.Vt uint8_t , +.Vt uint16_t , +.Vt uint32_t , +and +.Vt uint64_t +provide an unsigned integer type of width 8, 16, 32, or 64 bits, respectively. +These integer types should be used when a specific size is required. +.Pp +The types +.Vt int_fast8_t , +.Vt int_fast16_t , +.Vt int_fast32_t , +and +.Vt int_fast64_t +provide the fastest signed integer type with a width +of at least 8, 16, 32, or 64 bits, respectively. +The types +.Vt uint_fast8_t , +.Vt uint_fast16_t , +.Vt uint_fast32_t , +and +.Vt uint_fast64_t +provide the fastest unsigned integer type with a width +of at least 8, 16, 32, or 64 bits, respectively. +These types should be used when access speed is +paramount, and when a specific size is not required. +.Pp +The types +.Vt int_least8_t , +.Vt int_least16_t , +.Vt int_least32_t , +and +.Vt int_least64_t +provide the smallest memory footprint signed integer type with +a width of at least 8, 16, 32, or 64 bits, respectively. +The types +.Vt uint_least8_t , +.Vt uint_least16_t , +.Vt uint_least32_t , +and +.Vt uint_least64_t +provide the smallest memory footprint unsigned integer type with +a width of at least 8, 16, 32, or 64 bits, respectively. +These types should be used when memory storage is of +concern, and when a specific size is not required. +.Pp +The type +.Vt intmax_t +provides a signed integer type large +enough to hold any other signed integer. +The type +.Vt uintmax_t +provides an unsigned integer type large +enough to hold any other unsigned integer. +These types are generally the largest signed and unsigned +integer types available on a specific architecture. +.Pp +The type +.Vt intptr_t +provides a signed integer type with the ability to hold a pointer to +.Vt void , +that can later be converted back to a pointer to +.Vt void . +.Pp +The type +.Vt uintptr_t +provides an unsigned integer type with the ability to hold a pointer to +.Vt void , +that can later be converted back to a pointer to +.Vt void . +.Pp +Additionally, the +.In stdint.h +header defines some macros, but none of them are documented here. +.Sh STANDARDS +The +.In stdint.h +header conforms to +.St -isoC-99 +and +.St -p1003.1-2001 . +.Sh HISTORY +The +.In stdint.h +header was first introduced in +.Fx 5.0 . diff --git a/static/freebsd/man7/sticky.7 b/static/freebsd/man7/sticky.7 new file mode 100644 index 00000000..7c2ae04e --- /dev/null +++ b/static/freebsd/man7/sticky.7 @@ -0,0 +1,75 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 June 5, 1993 +.Dt STICKY 7 +.Os +.Sh NAME +.Nm sticky +.Nd sticky text and append-only directories +.Sh DESCRIPTION +A special file mode, called the +.Em sticky bit +(mode S_ISTXT), +is used to indicate special treatment +for directories. +It is ignored for regular files. +See +.Xr chmod 2 +or +the file +.In sys/stat.h +for an explanation of file modes. +.Sh STICKY DIRECTORIES +A directory whose `sticky bit' is set +becomes an append-only directory, or, more accurately, +a directory in which the deletion of files is restricted. +A file in a sticky directory may only be removed or renamed +by a user if the user has write permission for the directory and +the user is the owner of the file, the owner of the directory, +or the super-user. +This feature is usefully applied to directories such as +.Pa /tmp +which must be publicly writable but +should deny users the license to arbitrarily +delete or rename each others' files. +.Pp +Any user may create a sticky directory. +See +.Xr chmod 1 +for details about modifying file modes. +.Sh HISTORY +A +.Nm +command appeared in +.At 32v . +.Sh BUGS +Neither +.Xr open 2 +nor +.Xr mkdir 2 +will create a file with the sticky bit set. diff --git a/static/freebsd/man7/tests.7 b/static/freebsd/man7/tests.7 new file mode 100644 index 00000000..97cc6beb --- /dev/null +++ b/static/freebsd/man7/tests.7 @@ -0,0 +1,322 @@ +.\" $NetBSD: tests.kyua.7,v 1.2 2013/07/20 21:39:59 wiz Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 FOUNDATION OR CONTRIBUTORS BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE +.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER +.\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR +.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN +.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd April 17, 2026 +.Dt TESTS 7 +.Os +.Sh NAME +.Nm tests +.Nd introduction to the +.Fx +Test Suite +.Sh DESCRIPTION +The +.Fx +Test Suite provides a collection of automated tests for two major purposes. +On one hand, the test suite aids +.Em developers +to detect bugs and regressions when they modify the source tree. +On the other hand, it allows +.Em end users +(and, in particular, system administrators) to verify that fresh installations +of the +.Fx +operating system behave correctly on their hardware platform and also to ensure +that the system does not suffer from regressions during regular operation and +maintenance. +.Pp +The +.Fx +Test Suite can be found in the +.Pa /usr/tests +hierarchy. +.Pp +This manual page describes how to run the test suite and how to configure +some of its optional features. +For information on writing the tests, see +.Xr atf 7 . +.Ss Installing the test suite +If the +.Pa /usr/tests +directory is missing, then you will have to enable the build of the test +suite, rebuild your system and install the results. +You can do so by setting +.Sq WITH_TESTS=yes +in your +.Pa /etc/src.conf +file (see +.Xr src.conf 5 +for details) +and rebuilding the system as described in +.Xr build 7 . +.Ss When to run the tests? +Before diving into the details of how to run the test suite, here are some +scenarios in which you should run it: +.Bl -bullet -offset indent +.It +After a fresh installation of +.Fx +to ensure that the system works correctly on your hardware platform. +.It +After an upgrade of +.Fx +to a different version to ensure that the new code works well on your +hardware platform and that the upgrade did not introduce regressions in your +configuration. +.It +After modifying the source tree to detect any new bugs and/or regressions. +.It +Periodically, maybe from a +.Xr cron 8 +job, to ensure that any changes to the system (such as the installation of +third-party packages or manual modifications to configuration files) do not +introduce unexpected failures. +.El +.Ss Running the tests +By default, Kyua looks for tests in the current directory. +To run the whole test suite, either use the +.Fl k +option to specify the top-level +.Pa Kyuafile : +.Bd -literal -offset indent +$ kyua test -k /usr/tests/Kyuafile +.Ed +.Pp +or just change to the test suite root before running Kyua: +.Bd -literal -offset indent +$ cd /usr/tests +$ kyua test +.Ed +.Pp +The above will iterate through all test programs in +.Pa /usr/tests +recursively, execute them, store their results and debugging data in Kyua's +database (by default in +.Pa ~/.kyua/store/ ) , +and print a summary of the results. +This summary includes a brief count of all total tests run and how many of +them failed. +.Pp +It is possible to restrict which tests to run by providing their +names, or a portion of their path, on the command line. +For example, this would execute all of the tests provided for the +.Xr cp 1 +and +.Xr stat 1 +utilities: +.Bd -literal -offset indent +$ cd /usr/tests +$ kyua test bin/cp usr.bin/stat +.Ed +.Pp +This would execute only one of the two test programs provided for +.Xr stat 1 : +.Bd -literal -offset indent +$ cd /usr/tests +$ kyua test usr.bin/stat/stat_test +.Ed +.Pp +This would execute just a single test case: +.Bd -literal -offset indent +$ cd /usr/tests +$ kyua test usr.bin/stat/stat_test:t_flag +.Ed +.Pp +Finally, this would execute that test case in debug mode: +.Bd -literal -offset indent +$ cd /usr/tests +$ kyua debug -p usr.bin/stat/stat_test:t_flag +.Ed +.Pp +The +.Fl p +option tells Kyua to pause before cleanup so you can inspect the +temporary directory to better understand why the test failed. +.Pp +Note that some tests may require root privileges to execute: +.Bd -literal -offset indent +$ cd /usr/tests +$ kyua debug usr.bin/stat/stat_test:h_flag +usr.bin/stat/stat_test:h_flag -> skipped: Requires root privileges +$ sudo kyua debug usr.bin/stat/stat_test:h_flag +[...] +usr.bin/stat/stat_test:h_flag -> passed +.Ed +.Pp +Conversely, some tests will only work correctly if run as an +unprivileged user. +This will normally be noted in the test's metadata, causing Kyua to +automatically drop privileges before running the test. +.Ss Obtaining reports of the tests execution +Additional information about the test results can be retrieved +by using Kyua's various reporting commands. +For example, the following would print a plain-text report of the +tests executed in the latest test run and show which ones failed: +.Bd -literal -offset indent +$ kyua report --verbose +.Ed +.Pp +To show the results of an arbitrary test run, use the +.Fl r +option to specify which results file to read: +.Bd -literal -offset indent +$ kyua report --verbose \\ + -r ~/.kyua/store/results.usr_tests.20260417-173009-335060.db +.Ed +.Pp +Keep in mind that if the tests were run as root, the results will have +been stored in root's +.Pa kyua +directory, and the easiest way to access them will be to run the +.Cm report +command as root as well: +.Bd -literal -offset indent +$ cd /usr/tests +$ sudo kyua test usr.bin/stat +$ sudo kyua report --verbose +.Ed +.Pp +This example would generate an HTML report ready to be published on a +web server: +.Bd -literal -offset indent +$ kyua report-html --output ~/public_html/tests +.Ed +.Pp +For further details on the command-line interface of Kyua, please refer +to its manual page +.Xr kyua 1 . +.Ss Configuring the tests +Some test cases in the +.Fx +Test Suite require manual configuration by the administrator before they can be +run. +Unless certain properties are defined, the tests that require them will be +skipped. +.Pp +Test suites are configured by defining their configuration +variables in +.Pa /etc/kyua/kyua.conf . +The format of this file is detailed in +.Xr kyua.conf 5 . +.Pp +The following configuration variables are available in the +.Fx +Test Suite: +.Bl -tag -width "allow_sysctl_side_effects" +.It Va allow_devfs_side_effects +If defined, enables tests that may destroy and recreate semipermanent device +nodes, like disk devices. +Without this variable, tests may still create and destroy devices nodes that +are normally transient, like /dev/tap* and /dev/pts*, as long as they clean +them up afterwards. +However, tests that require this variable have a relaxed cleanup requirement; +they must recreate any devices that they destroyed, but not necessarily with +the same devnames. +.It Va allow_sysctl_side_effects +Enables tests that change globally significant +.Xr sysctl 8 +variables. +The tests will undo any changes in their cleanup phases. +.It Va allow_network_access +Enables tests that need to access the network the test host is connected to. +Such tests may require properly configured Internet access. +.It Va disks +Must be set to a space delimited list of disk device nodes. +Tests that need destructive access to disks must use these devices. +Tests are not required to preserve any data present on these disks. +.It Va fibs +Must be set to a space delimited list of FIBs (routing tables). +Tests that need to modify a routing table may use any of these. +Tests will cleanup any new routes that they create. +.El +.Ss What to do if something fails? +If there is +.Em any failure +during the execution of the test suite, please consider reporting it to the +.Fx +developers so that the failure can be analyzed and fixed. +To do so, either send a message to the appropriate mailing list or file a +problem report. +For more details please refer to: +.Bl -bullet -offset indent -compact +.It +.Lk https://lists.freebsd.org/ "FreeBSD Mailing Lists" +.It +.Lk https://www.freebsd.org/support/ "Problem Reporting" +.El +.Sh FILES +.Bl -tag -compact -width "/etc/kyua/kyua.conf" +.It Pa /etc/kyua/kyua.conf +System-wide configuration file for +.Xr kyua 1 . +.It Pa ~/.kyua/kyua.conf +User-specific configuration file for +.Xr kyua 1 ; +overrides the system file. +.It Pa ~/.kyua/logs/ +Default location of Kyua debug logs (one +.Pa .log +file per test run). +.It Pa ~/.kyua/store/ +Default location of Kyua test results (one +.Pa .db +file per test run). +.It Pa /usr/tests/ +Location of the +.Fx +Test Suite. +.It Pa /usr/tests/Kyuafile +Top-level test suite definition file. +.El +.Sh SEE ALSO +.Xr kyua 1 , +.Xr atf 7 , +.Xr build 7 , +.Xr development 7 +.Sh HISTORY +The +.Fx +Test Suite first appeared in +.Fx 10.1 +and was installed by default in +.Fx 11.0 . +.Pp +The +.Nm +manual page first appeared in +.Nx 6.0 +and was later ported to +.Fx 10.1 . +.Pp +The test driver, +.Xr kyua 1 , +was imported as part of the base system in +.Fx 13.0 , +previously being available only in +.Xr ports 7 . +.Sh AUTHORS +.An Julio Merino Aq Mt jmmv@FreeBSD.org diff --git a/static/freebsd/man7/tracing.7 b/static/freebsd/man7/tracing.7 new file mode 100644 index 00000000..7085bac7 --- /dev/null +++ b/static/freebsd/man7/tracing.7 @@ -0,0 +1,100 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> +.\" +.Dd July 12, 2025 +.Dt TRACING 7 +.Os +.Sh NAME +.Nm tracing +.Nd introduction to FreeBSD tracing and performance monitoring +.Sh DESCRIPTION +.Fx +features a large variety of tracing and performance monitoring facilities. +Use them to measure performance and +troubleshoot kernel and userland problems both during +.Xr development 7 +and potentially on production systems. +The facilities differ in scope, ease of use, overhead, design, and limitations. +.Ss DTrace +.Xr dtrace 1 +is the most versatile tracing framework available on +.Fx +and is capable of tracing throughout the +.Fx +software stack from the kernel to the applications running in userland. +Refer to +.Xr dtrace 1 +and +.Xr SDT 9 +for more details. +.Pp +.Xr dwatch 1 +is a user-friendly wrapper for DTrace. +It simplifies common DTrace usage patterns and requires less expert knowledge +to operate. +.Ss Userland Tracing +.Xr truss 1 +traces system calls. +It uses +.Xr sysdecode 3 +to pretty-print system call arguments and +.Xr ptrace 2 +to trace processes. +.Pp +.Xr ktrace 1 +is useful for debugging user programs. +It enables kernel trace logging for specified processes. +Like +.Xr truss 1 , +it mainly traces system calls, but instead of using +.Xr ptrace 2 , +it asynchronously logs entries to a trace file configured with +.Xr ktrace 2 +(typically +.Pa ktrace.out ) , +and it can log other types of kernel events, such as page faults +and name lookups +.Po refer to +.Fl t +in +.Xr ktrace 1 +.Pc . +Also, programs can log to a +.Xr ktrace 1 +stream using the +.Xr utrace 2 +system call. +.Ss Kernel Tracing +.Xr ktr 4 +is a facility for logging strings in the kernel. +It comes in handy for some niche purposes during kernel development. +It lets kernel programmers log events to a global ring buffer, +which can later be dumped using +.Xr ktrdump 8 . +.Ss Hardware-Accelerated Tracing +.Xr hwt 4 +is a kernel trace framework providing infrastructure +for hardware-assisted tracing. +.Ss Hardware Counters +.Xr pmcstat 8 , +and its kernel counterpart, +.Xr hwpmc 4 , +is the +.Fx +facility for conducting performance measurements with hardware counters. +.Ss Boot-Time And Shutdown Tracing +.Xr boottrace 4 +is a facility for tracing events at boot and shutdown. +Its target audience are system administrators. +.Pp +.Xr tslog 4 +is a developer-oriented tool for tracing boot-time events. +.Sh HISTORY +The +.Nm +manual page was written by +.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . +It first appeared in +.Fx 15.0 . diff --git a/static/freebsd/man7/tuning.7 b/static/freebsd/man7/tuning.7 new file mode 100644 index 00000000..831362e9 --- /dev/null +++ b/static/freebsd/man7/tuning.7 @@ -0,0 +1,749 @@ +.\" Copyright (C) 2001 Matthew Dillon. All rights reserved. +.\" Copyright (C) 2012 Eitan Adler. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 9, 2026 +.Dt TUNING 7 +.Os +.Sh NAME +.Nm tuning +.Nd performance tuning under FreeBSD +.Sh SYSTEM SETUP - DISKLABEL, NEWFS, TUNEFS, SWAP +The swap partition should typically be approximately 2x the size of +main memory +for systems with less than 4GB of RAM, or approximately equal to +the size of main memory +if you have more. +Keep in mind future memory +expansion when sizing the swap partition. +Configuring too little swap can lead +to inefficiencies in the VM page scanning code as well as create issues +later on if you add more memory to your machine. +On larger systems +with multiple disks, configure swap on each drive. +The swap partitions on the drives should be approximately the same size. +The kernel can handle arbitrary sizes but +internal data structures scale to 4 times the largest swap partition. +Keeping +the swap partitions near the same size will allow the kernel to optimally +stripe swap space across the N disks. +Do not worry about overdoing it a +little, swap space is the saving grace of +.Ux +and even if you do not normally use much swap, it can give you more time to +recover from a runaway program before being forced to reboot. +.Pp +It is not a good idea to make one large partition. +First, +each partition has different operational characteristics and separating them +allows the file system to tune itself to those characteristics. +For example, +the root and +.Pa /usr +partitions are read-mostly, with very little writing, while +a lot of reading and writing could occur in +.Pa /var/tmp . +By properly +partitioning your system fragmentation introduced in the smaller more +heavily write-loaded partitions will not bleed over into the mostly-read +partitions. +.Pp +Properly partitioning your system also allows you to tune +.Xr newfs 8 , +and +.Xr tunefs 8 +parameters. +The only +.Xr tunefs 8 +option worthwhile turning on is +.Em softupdates +with +.Dq Li "tunefs -n enable /filesystem" . +Softupdates drastically improves meta-data performance, mainly file +creation and deletion. +We recommend enabling softupdates on most file systems; however, there +are two limitations to softupdates that you should be aware of when +determining whether to use it on a file system. +First, softupdates guarantees file system consistency in the +case of a crash but could very easily be several seconds (even a minute!\&) +behind on pending write to the physical disk. +If you crash you may lose more work +than otherwise. +Secondly, softupdates delays the freeing of file system +blocks. +If you have a file system (such as the root file system) which is +close to full, doing a major update of it, e.g.,\& +.Dq Li "make installworld" , +can run it out of space and cause the update to fail. +For this reason, softupdates will not be enabled on the root file system +during a typical install. +There is no loss of performance since the root +file system is rarely written to. +.Pp +A number of run-time +.Xr mount 8 +options exist that can help you tune the system. +The most obvious and most dangerous one is +.Cm async . +Only use this option in conjunction with +.Xr gjournal 8 , +as it is far too dangerous on a normal file system. +A less dangerous and more +useful +.Xr mount 8 +option is called +.Cm noatime . +.Ux +file systems normally update the last-accessed time of a file or +directory whenever it is accessed. +This operation is handled in +.Fx +with a delayed write and normally does not create a burden on the system. +However, if your system is accessing a huge number of files on a continuing +basis the buffer cache can wind up getting polluted with atime updates, +creating a burden on the system. +For example, if you are running a heavily +loaded web site, or a news server with lots of readers, you might want to +consider turning off atime updates on your larger partitions with this +.Xr mount 8 +option. +However, you should not gratuitously turn off atime +updates everywhere. +For example, the +.Pa /var +file system customarily +holds mailboxes, and atime (in combination with mtime) is used to +determine whether a mailbox has new mail. +You might as well leave +atime turned on for mostly read-only partitions such as +.Pa / +and +.Pa /usr +as well. +This is especially useful for +.Pa / +since some system utilities +use the atime field for reporting. +.Sh STRIPING DISKS +In larger systems you can stripe partitions from several drives together +to create a much larger overall partition. +Striping can also improve +the performance of a file system by splitting I/O operations across two +or more disks. +The +.Xr gstripe 8 +and +.Xr ccdconfig 8 +utilities may be used to create simple striped file systems. +Generally +speaking, striping smaller partitions such as the root and +.Pa /var/tmp , +or essentially read-only partitions such as +.Pa /usr +is a complete waste of time. +You should only stripe partitions that require serious I/O performance, +typically +.Pa /var , /home , +or custom partitions used to hold databases and web pages. +Choosing the proper stripe size is also +important. +File systems tend to store meta-data on power-of-2 boundaries +and you usually want to reduce seeking rather than increase seeking. +This +means you want to use a large off-center stripe size such as 1152 sectors +so sequential I/O does not seek both disks and so meta-data is distributed +across both disks rather than concentrated on a single disk. +.Sh SYSCTL TUNING +.Xr sysctl 8 +variables permit system behavior to be monitored and controlled at +run-time. +Some sysctls simply report on the behavior of the system; others allow +the system behavior to be modified; +some may be set at boot time using +.Xr rc.conf 5 , +but most will be set via +.Xr sysctl.conf 5 . +There are several hundred sysctls in the system, including many that appear +to be candidates for tuning but actually are not. +In this document we will only cover the ones that have the greatest effect +on the system. +.Pp +The +.Va vm.overcommit +sysctl defines the overcommit behaviour of the vm subsystem. +The virtual memory system always does accounting of the swap space +reservation, both total for system and per-user. +Corresponding values +are available through sysctl +.Va vm.swap_total , +that gives the total bytes available for swapping, and +.Va vm.swap_reserved , +that gives number of bytes that may be needed to back all currently +allocated anonymous memory. +.Pp +Setting bit 0 of the +.Va vm.overcommit +sysctl causes the virtual memory system to return failure +to the process when allocation of memory causes +.Va vm.swap_reserved +to exceed +.Va vm.swap_total . +Bit 1 of the sysctl enforces +.Dv RLIMIT_SWAP +limit +(see +.Xr getrlimit 2 ) . +Root is exempt from this limit. +Bit 2 allows to count most of the physical +memory as allocatable, except wired and free reserved pages +(accounted by +.Va vm.stats.vm.v_free_target +and +.Va vm.stats.vm.v_wire_count +sysctls, respectively). +.Pp +Due to the architecture of the +.Fx +virtual memory subsystem, the use of copy on write (CoW) anonymous +memory, e.g. on +.Xr fork 2 , +causes swap reservation for all three regions (VM objects): +in the original pre-fork mapping, and its copies in +the parent and child, instead of only two. +Eventually the subsystem tries to optimize the internal layout +of the tracking for CoW and often removes (collapses) no longer +needed backing objects, re-assigning its pages and swap +reservations to the copies. +Collapsing frees the swap reserve, but it is not guaranteed +to happen. +.Pp +The +.Va kern.ipc.maxpipekva +loader tunable is used to set a hard limit on the +amount of kernel address space allocated to mapping of pipe buffers. +Use of the mapping allows the kernel to eliminate a copy of the +data from writer address space into the kernel, directly copying +the content of mapped buffer to the reader. +Increasing this value to a higher setting, such as `25165824' might +improve performance on systems where space for mapping pipe buffers +is quickly exhausted. +This exhaustion is not fatal; however, and it will only cause pipes +to fall back to using double-copy. +.Pp +The +.Va kern.ipc.shm_use_phys +sysctl defaults to 0 (off) and may be set to 0 (off) or 1 (on). +Setting +this parameter to 1 will cause all System V shared memory segments to be +mapped to unpageable physical RAM. +This feature only has an effect if you +are either (A) mapping small amounts of shared memory across many (hundreds) +of processes, or (B) mapping large amounts of shared memory across any +number of processes. +This feature allows the kernel to remove a great deal +of internal memory management page-tracking overhead at the cost of wiring +the shared memory into core, making it unswappable. +.Pp +The +.Va vfs.vmiodirenable +sysctl defaults to 1 (on). +This parameter controls how directories are cached +by the system. +Most directories are small and use but a single fragment +(typically 2K) in the file system and even less (typically 512 bytes) in +the buffer cache. +However, when operating in the default mode the buffer +cache will only cache a fixed number of directories even if you have a huge +amount of memory. +Turning on this sysctl allows the buffer cache to use +the VM Page Cache to cache the directories. +The advantage is that all of +memory is now available for caching directories. +The disadvantage is that +the minimum in-core memory used to cache a directory is the physical page +size (typically 4K) rather than 512 bytes. +We recommend turning this option off in memory-constrained environments; +however, when on, it will substantially improve the performance of services +that manipulate a large number of files. +Such services can include web caches, large mail systems, and news systems. +Turning on this option will generally not reduce performance even with the +wasted memory but you should experiment to find out. +.Pp +The +.Va vfs.write_behind +sysctl defaults to 1 (on). +This tells the file system to issue media +writes as full clusters are collected, which typically occurs when writing +large sequential files. +The idea is to avoid saturating the buffer +cache with dirty buffers when it would not benefit I/O performance. +However, +this may stall processes and under certain circumstances you may wish to turn +it off. +.Pp +The +.Va vfs.hirunningspace +sysctl determines how much outstanding write I/O may be queued to +disk controllers system-wide at any given time. +It is used by the UFS file system. +The default is self-tuned and +usually sufficient but on machines with advanced controllers and lots +of disks this may be tuned up to match what the controllers buffer. +Configuring this setting to match tagged queuing capabilities of +controllers or drives with average IO size used in production works +best (for example: 16 MiB will use 128 tags with IO requests of 128 KiB). +Note that setting too high a value +(exceeding the buffer cache's write threshold) can lead to extremely +bad clustering performance. +Do not set this value arbitrarily high! +Higher write queuing values may also add latency to reads occurring at +the same time. +.Pp +The +.Va vfs.read_max +sysctl governs VFS read-ahead and is expressed as the number of blocks +to pre-read if the heuristics algorithm decides that the reads are +issued sequentially. +It is used by the UFS, ext2fs and msdosfs file systems. +With the default UFS block size of 32 KiB, a setting of 64 will allow +speculatively reading up to 2 MiB. +This setting may be increased to get around disk I/O latencies, especially +where these latencies are large such as in virtual machine emulated +environments. +It may be tuned down in specific cases where the I/O load is such that +read-ahead adversely affects performance or where system memory is really +low. +.Pp +The +.Va vfs.ncsizefactor +sysctl defines how large VFS namecache may grow. +The number of currently allocated entries in namecache is provided by +.Va debug.numcache +sysctl and the condition +debug.numcache < kern.maxvnodes * vfs.ncsizefactor +is adhered to. +.Pp +The +.Va vfs.ncnegfactor +sysctl defines how many negative entries VFS namecache is allowed to create. +The number of currently allocated negative entries is provided by +.Va debug.numneg +sysctl and the condition +vfs.ncnegfactor * debug.numneg < debug.numcache +is adhered to. +.Pp +There are various other buffer-cache and VM page cache related sysctls. +We do not recommend modifying these values. +.Pp +The +.Va net.inet.tcp.sendspace +and +.Va net.inet.tcp.recvspace +sysctls are of particular interest if you are running network intensive +applications. +They control the amount of send and receive buffer space +allowed for any given TCP connection. +The default sending buffer is 32K; the default receiving buffer +is 64K. +You can often +improve bandwidth utilization by increasing the default at the cost of +eating up more kernel memory for each connection. +We do not recommend +increasing the defaults if you are serving hundreds or thousands of +simultaneous connections because it is possible to quickly run the system +out of memory due to stalled connections building up. +But if you need +high bandwidth over a fewer number of connections, especially if you have +gigabit Ethernet, increasing these defaults can make a huge difference. +You can adjust the buffer size for incoming and outgoing data separately. +For example, if your machine is primarily doing web serving you may want +to decrease the recvspace in order to be able to increase the +sendspace without eating too much kernel memory. +Note that the routing table (see +.Xr route 8 ) +can be used to introduce route-specific send and receive buffer size +defaults. +.Pp +As an additional management tool you can use pipes in your +firewall rules (see +.Xr ipfw 8 ) +to limit the bandwidth going to or from particular IP blocks or ports. +For example, if you have a T1 you might want to limit your web traffic +to 70% of the T1's bandwidth in order to leave the remainder available +for mail and interactive use. +Normally a heavily loaded web server +will not introduce significant latencies into other services even if +the network link is maxed out, but enforcing a limit can smooth things +out and lead to longer term stability. +Many people also enforce artificial +bandwidth limitations in order to ensure that they are not charged for +using too much bandwidth. +.Pp +Setting the send or receive TCP buffer to values larger than 65535 will result +in a marginal performance improvement unless both hosts support the window +scaling extension of the TCP protocol, which is controlled by the +.Va net.inet.tcp.rfc1323 +sysctl. +These extensions should be enabled and the TCP buffer size should be set +to a value larger than 65536 in order to obtain good performance from +certain types of network links; specifically, gigabit WAN links and +high-latency satellite links. +RFC1323 support is enabled by default. +.Pp +The +.Va net.inet.tcp.always_keepalive +sysctl determines whether or not the TCP implementation should attempt +to detect dead TCP connections by intermittently delivering +.Dq keepalives +on the connection. +By default, this is enabled for all applications; by setting this +sysctl to 0, only applications that specifically request keepalives +will use them. +In most environments, TCP keepalives will improve the management of +system state by expiring dead TCP connections, particularly for +systems serving dialup users who may not always terminate individual +TCP connections before disconnecting from the network. +However, in some environments, temporary network outages may be +incorrectly identified as dead sessions, resulting in unexpectedly +terminated TCP connections. +In such environments, setting the sysctl to 0 may reduce the occurrence of +TCP session disconnections. +.Pp +The +.Va net.inet.tcp.delayed_ack +TCP feature is largely misunderstood. +Historically speaking, this feature +was designed to allow the acknowledgement to transmitted data to be returned +along with the response. +For example, when you type over a remote shell, +the acknowledgement to the character you send can be returned along with the +data representing the echo of the character. +With delayed acks turned off, +the acknowledgement may be sent in its own packet, before the remote service +has a chance to echo the data it just received. +This same concept also +applies to any interactive protocol (e.g.,\& SMTP, WWW, POP3), and can cut the +number of tiny packets flowing across the network in half. +The +.Fx +delayed ACK implementation also follows the TCP protocol rule that +at least every other packet be acknowledged even if the standard 40ms +timeout has not yet passed. +Normally the worst a delayed ACK can do is +slightly delay the teardown of a connection, or slightly delay the ramp-up +of a slow-start TCP connection. +While we are not sure we believe that +the several FAQs related to packages such as SAMBA and SQUID which advise +turning off delayed acks may be referring to the slow-start issue. +.Pp +The +.Va net.inet.ip.portrange.* +sysctls control the port number ranges automatically bound to TCP and UDP +sockets. +There are three ranges: a low range, a default range, and a +high range, selectable via the +.Dv IP_PORTRANGE +.Xr setsockopt 2 +call. +Most +network programs use the default range which is controlled by +.Va net.inet.ip.portrange.first +and +.Va net.inet.ip.portrange.last , +which default to 49152 and 65535, respectively. +Bound port ranges are +used for outgoing connections, and it is possible to run the system out +of ports under certain circumstances. +This most commonly occurs when you are +running a heavily loaded web proxy. +The port range is not an issue +when running a server which handles mainly incoming connections, such as a +normal web server, or has a limited number of outgoing connections, such +as a mail relay. +For situations where you may run out of ports, +we recommend decreasing +.Va net.inet.ip.portrange.first +modestly. +A range of 10000 to 30000 ports may be reasonable. +You should also consider firewall effects when changing the port range. +Some firewalls +may block large ranges of ports (usually low-numbered ports) and expect systems +to use higher ranges of ports for outgoing connections. +By default +.Va net.inet.ip.portrange.last +is set at the maximum allowable port number. +.Pp +The +.Va kern.ipc.soacceptqueue +sysctl limits the size of the listen queue for accepting new TCP connections. +The default value of 128 is typically too low for robust handling of new +connections in a heavily loaded web server environment. +For such environments, +we recommend increasing this value to 1024 or higher. +The service daemon +may itself limit the listen queue size (e.g.,\& +.Xr sendmail 8 , +apache) but will +often have a directive in its configuration file to adjust the queue size up. +Larger listen queues also do a better job of fending off denial of service +attacks. +.Pp +The +.Va kern.maxfiles +sysctl determines how many open files the system supports. +The default is +typically a few thousand but you may need to bump this up to ten or twenty +thousand if you are running databases or large descriptor-heavy daemons. +The read-only +.Va kern.openfiles +sysctl may be interrogated to determine the current number of open files +on the system. +.Sh LOADER TUNABLES +Some aspects of the system behavior may not be tunable at runtime because +memory allocations they perform must occur early in the boot process. +To change loader tunables, you must set their values in +.Xr loader.conf 5 +and reboot the system. +.Pp +.Va kern.maxusers +controls the scaling of a number of static system tables, including defaults +for the maximum number of open files, sizing of network memory resources, etc. +.Va kern.maxusers +is automatically sized at boot based on the amount of memory available in +the system, and may be determined at run-time by inspecting the value of the +read-only +.Va kern.maxusers +sysctl. +.Pp +The +.Va kern.dfldsiz +and +.Va kern.dflssiz +tunables set the default soft limits for process data and stack size +respectively. +Processes may increase these up to the hard limits by calling +.Xr setrlimit 2 . +The +.Va kern.maxdsiz , +.Va kern.maxssiz , +and +.Va kern.maxtsiz +tunables set the hard limits for process data, stack, and text size +respectively; processes may not exceed these limits. +The +.Va kern.sgrowsiz +tunable controls how much the stack segment will grow when a process +needs to allocate more stack. +.Pp +.Va kern.ipc.nmbclusters +may be adjusted to increase the number of network mbufs the system is +willing to allocate. +Each cluster represents approximately 2K of memory, +so a value of 1024 represents 2M of kernel memory reserved for network +buffers. +You can do a simple calculation to figure out how many you need. +If you have a web server which maxes out at 1000 simultaneous connections, +and each connection eats a 16K receive and 16K send buffer, you need +approximately 32MB worth of network buffers to deal with it. +A good rule of +thumb is to multiply by 2, so 32MBx2 = 64MB/2K = 32768. +So for this case +you would want to set +.Va kern.ipc.nmbclusters +to 32768. +We recommend values between +1024 and 4096 for machines with moderates amount of memory, and between 4096 +and 32768 for machines with greater amounts of memory. +Under no circumstances +should you specify an arbitrarily high value for this parameter, it could +lead to a boot-time crash. +The +.Fl m +option to +.Xr netstat 1 +may be used to observe network cluster use. +.Pp +More and more programs are using the +.Xr sendfile 2 +system call to transmit files over the network. +The +.Va kern.ipc.nsfbufs +sysctl controls the number of file system buffers +.Xr sendfile 2 +is allowed to use to perform its work. +This parameter nominally scales +with +.Va kern.maxusers +so you should not need to modify this parameter except under extreme +circumstances. +See the +.Sx TUNING +section in the +.Xr sendfile 2 +manual page for details. +.Sh SCHEDULERS +.Fx +allows having more than one scheduler specified in the kernel config, +and the desired scheduler selected from them at boot time. +Right now the options are: +.Bl -tag -width SCHED_4BSD +.It Cd SCHED_ULE +The modern scheduler with O(1) thread selection behavior. +.It Cd SCHED_4BSD +Classic scheduler inherited from 4.x BSD. +.El +.Pp +At least one option must be specified. +.Cd SCHED_ULE +is used by default if compiled in. +.Pp +The +.Va kern.sched.available +sysctl provides the comma-separated list of available (compiled in) +schedulers. +The +.Va kern.sched.name +loader tunable can be set to select the desired scheduler at boot time. +The +.Va kern.sched.name +sysctl reports which scheduler is used. +.Sh KERNEL CONFIG TUNING +There are a number of kernel options that you may have to fiddle with in +a large-scale system. +In order to change these options you need to be +able to compile a new kernel from source. +The +.Xr config 8 +manual page and the handbook are good starting points for learning how to +do this. +Generally the first thing you do when creating your own custom +kernel is to strip out all the drivers and services you do not use. +Removing things like +.Dv INET6 +and drivers you do not have will reduce the size of your kernel, sometimes +by a megabyte or more, leaving more memory available for applications. +.Pp +.Dv SCSI_DELAY +may be used to reduce system boot times. +The defaults are fairly high and +can be responsible for 5+ seconds of delay in the boot process. +Reducing +.Dv SCSI_DELAY +to something below 5 seconds could work (especially with modern drives). +.Pp +There are a number of +.Dv *_CPU +options that can be commented out. +If you only want the kernel to run +on a Pentium class CPU, you can easily remove +.Dv I486_CPU , +but only remove +.Dv I586_CPU +if you are sure your CPU is being recognized as a Pentium II or better. +Some clones may be recognized as a Pentium or even a 486 and not be able +to boot without those options. +If it works, great! +The operating system +will be able to better use higher-end CPU features for MMU, task switching, +timebase, and even device operations. +Additionally, higher-end CPUs support +4MB MMU pages, which the kernel uses to map the kernel itself into memory, +increasing its efficiency under heavy syscall loads. +.Sh CPU, MEMORY, DISK, NETWORK +The type of tuning you do depends heavily on where your system begins to +bottleneck as load increases. +If your system runs out of CPU (idle times +are perpetually 0%) then you need to consider upgrading the CPU +or perhaps you need to revisit the +programs that are causing the load and try to optimize them. +If your system +is paging to swap a lot you need to consider adding more memory. +If your +system is saturating the disk you typically see high CPU idle times and +total disk saturation. +.Xr systat 1 +can be used to monitor this. +There are many solutions to saturated disks: +increasing memory for caching, mirroring disks, distributing operations across +several machines, and so forth. +.Pp +Finally, you might run out of network resources. +Optimize the network path +as much as possible. +For example, in +.Xr firewall 7 +we describe a firewall protecting internal hosts with a topology where +the externally visible hosts are not routed through it. +Most bottlenecks occur at the WAN link. +If expanding the link is not an option it may be possible to use the +.Xr dummynet 4 +feature to implement peak shaving or other forms of traffic shaping to +prevent the overloaded service (such as web services) from affecting other +services (such as email), or vice versa. +In home installations this could +be used to give interactive traffic (your browser, +.Xr ssh 1 +logins) priority +over services you export from your box (web services, email). +.Sh SEE ALSO +.Xr netstat 1 , +.Xr systat 1 , +.Xr sendfile 2 , +.Xr ata 4 , +.Xr dummynet 4 , +.Xr eventtimers 4 , +.Xr ffs 4 , +.Xr login.conf 5 , +.Xr rc.conf 5 , +.Xr sysctl.conf 5 , +.Xr firewall 7 , +.Xr hier 7 , +.Xr ports 7 , +.Xr stats 7 , +.Xr boot 8 , +.Xr bsdinstall 8 , +.Xr ccdconfig 8 , +.Xr config 8 , +.Xr fsck 8 , +.Xr gjournal 8 , +.Xr gpart 8 , +.Xr gstripe 8 , +.Xr ifconfig 8 , +.Xr ipfw 8 , +.Xr loader 8 , +.Xr mount 8 , +.Xr newfs 8 , +.Xr route 8 , +.Xr sysctl 8 , +.Xr tunefs 8 +.Sh HISTORY +The +.Nm +manual page was originally written by +.An Matthew Dillon +and first appeared +in +.Fx 4.3 , +May 2001. +The manual page was greatly modified by +.An Eitan Adler Aq Mt eadler@FreeBSD.org . diff --git a/static/freebsd/man8/Makefile b/static/freebsd/man8/Makefile new file mode 100644 index 00000000..a2af6bc6 --- /dev/null +++ b/static/freebsd/man8/Makefile @@ -0,0 +1,3 @@ +MAN = $(wildcard *.8) + +include ../../mandoc.mk diff --git a/static/freebsd/man8/beinstall.8 b/static/freebsd/man8/beinstall.8 new file mode 100644 index 00000000..114483ba --- /dev/null +++ b/static/freebsd/man8/beinstall.8 @@ -0,0 +1,128 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2018 Mateusz Piotrowski <0mp@FreeBSD.org> +.\" +.\" 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 October 30, 2020 +.Dt BEINSTALL.SH 8 +.Os +.Sh NAME +.Nm beinstall.sh +.Nd "install a boot environment using the current FreeBSD source tree" +.Sh SYNOPSIS +.Nm +.Op Ar options Ar ... +.Sh DESCRIPTION +.Nm +installs a boot environment using the current +.Fx +source tree. +.Nm +also automatically performs +.Pa /etc +updates +(using +.Xr etcupdate 8 ) +and +package updates using +.Xr pkg-upgrade 8 +automatically in the new boot environment sandbox. +.Pp +Upon successful completion, the system will be ready to boot into the new boot +environment. +Upon failure, the target boot environment will be destroyed. +In all cases, the running system is left untouched +and a reboot into a partially updated system +(due to install or hardware failure) cannot happen. +Additionally, the full installation process requires +only one reboot as it is performed +in a new boot environment. +.Pp +.Nm +requires a fully built world and kernel. +It also requires +.Xr pkg 8 , +which is not present in the base system and has to be installed manually. +.Pp +The +.Ar options +provided to +.Nm +are world and kernel flags like +.Ev KERNCONF +as described in +.Xr build 7 . +.Sh ENVIRONMENT +User modifiable variables. +Set these in the environment if desired: +.Bl -tag -width indent +.It Ev BE_UTILITY Pq default: Dq Li "bectl" +Utility to manage ZFS boot environments. +This can be either +.Xr bectl 8 +from the base system or +.Xr beadm 1 +from ports (sysutils/beadm). +.It Ev CONFIG_UPDATER Pq default: Dq Li "etcupdate" +Config updater: +.Xr etcupdate 8 +is supported. +Set to an empty string to skip. +.It Ev ETCUPDATE_FLAGS Pq default: Dq Li "-F" +Flags for +.Xr etcupdate 8 +if used. +.It Ev NO_PKG_UPGRADE Pq default: Dq Li "" +If not empty, +.Dq Li pkg upgrade +will be skipped. +.El +.Sh FILES +.Bl -tag -width indent +.It Sy src/ Ns Pa tools/build/beinstall.sh +Place where +.Nm +lives in the src tree. +.El +.Sh SEE ALSO +.Xr build 7 , +.Xr development 7 , +.Xr bectl 8 , +.Xr etcupdate 8 , +.Xr pkg 8 +.Sh HISTORY +.Nm +is inspired by and similar in function to +Solaris/illumos-style upgrades. +.Pp +The +.Nm +manual page first appeared in +.Fx 12.0 . +.Sh AUTHORS +The +.Nm +script was implemented by +.An Will Andrews Aq Mt will@FreeBSD.org . +This manual page was written by +.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . diff --git a/static/freebsd/man8/crash.8 b/static/freebsd/man8/crash.8 new file mode 100644 index 00000000..fdb9b721 --- /dev/null +++ b/static/freebsd/man8/crash.8 @@ -0,0 +1,210 @@ +.\" FreeBSD version Copyright (c) 1996 +.\" Mike Pritchard . All rights reserved. +.\" +.\" Adapted from share/man/man8/man8.hp300/crash.8 +.\" +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 25, 2025 +.Dt CRASH 8 +.Os +.Sh NAME +.Nm crash +.Nd FreeBSD system failures +.Sh DESCRIPTION +This section explains a bit about system crashes +and (very briefly) how to analyze crash dumps. +.Pp +When the system crashes voluntarily it prints a message of the form +.Bl -diag -offset indent +.It "panic: why i gave up the ghost" +.El +.Pp +on the console, and if dumps have been enabled (see +.Xr dumpon 8 ) , +takes a dump on a mass storage peripheral, +and then invokes an automatic reboot procedure as +described in +.Xr reboot 8 . +Unless some unexpected inconsistency is encountered in the state +of the file systems due to hardware or software failure, the system +will then resume multi-user operations. +.Pp +The system has a large number of internal consistency checks; if one +of these fails, then it will panic with a very short message indicating +which one failed. +In many instances, this will be the name of the routine which detected +the error, or a two-word description of the inconsistency. +A full understanding of most panic messages requires perusal of the +source code for the system. +.Pp +The most common cause of system failures is hardware failure, which +can reflect itself in different ways. +Here are the messages which +are most likely, with some hints as to causes. +Left unstated in all cases is the possibility that hardware or software +error produced the message in some unexpected way. +.Pp +.Bl -diag -compact +.It Mounting from failed with error +The system was unable to mount the configured root filesystem. +Either the root filesystem has been corrupted, +or the system is attempting to use the wrong device as root filesystem. +.Pp +This is not a panic message; rather it is followed by an interactive +.Sy mountroot> +prompt where the operator can list detected devices and filesystems, +and select an alternative root filesystem to mount. +Alternatively, the system can be booted from recovery media to repair +the situation. +The system install media provides a live environment which is suitable +for this task. +.Pp +.It "init: not found" +This is not a panic message, as reboots are likely to be futile. +Late in the bootstrap procedure, the system was unable to locate +and execute the initialization process, +.Xr init 8 . +The root file system is incorrect or has been corrupted, or the mode +or type of +.Pa /sbin/init +forbids execution or is totally missing. +.Pp +.It "ffs_realloccg: bad optim" +.It "ffs_valloc: dup alloc" +.It "ffs_alloccgblk: cyl groups corrupted" +.It "ffs_alloccg: map corrupted" +.It "blkfree: freeing free block" +.It "blkfree: freeing free frag" +.It "ifree: freeing free inode" +These panic messages are among those that may be produced +when file system inconsistencies are detected. +The problem generally results from a failure to repair damaged file systems +after a crash, hardware failures, or other condition that should not +normally occur. +A file system check will normally correct the problem. +.Pp +.\" .It "trap type %d, code = %x, v = %x" +.\" An unexpected trap has occurred within the system; the trap types are: +.\" .Bl -column xxxx -offset indent +.\" 0 bus error +.\" 1 address error +.\" 2 illegal instruction +.\" 3 divide by zero +.\" .No 4\t Em chk No instruction +.\" .No 5\t Em trapv No instruction +.\" 6 privileged instruction +.\" 7 trace trap +.\" 8 MMU fault +.\" 9 simulated software interrupt +.\" 10 format error +.\" 11 FP coprocessor fault +.\" 12 coprocessor fault +.\" 13 simulated AST +.\" .El +.\" .Pp +.\" The favorite trap type in system crashes is trap type 8, +.\" indicating a wild reference. +.\" ``code'' (hex) is the concatenation of the +.\" MMU +.\" status register +.\" (see ) +.\" in the high 16 bits and the 68020 special status word +.\" (see the 68020 manual, page 6-17) +.\" in the low 16. +.\" ``v'' (hex) is the virtual address which caused the fault. +.\" Additionally, the kernel will dump about a screenful of semi-useful +.\" information. +.\" ``pid'' (decimal) is the process id of the process running at the +.\" time of the exception. +.\" Note that if we panic in an interrupt routine, +.\" this process may not be related to the panic. +.\" ``ps'' (hex) is the 68020 processor status register ``ps''. +.\" ``pc'' (hex) is the value of the program counter saved +.\" on the hardware exception frame. +.\" It may +.\" .Em not +.\" be the PC of the instruction causing the fault. +.\" ``sfc'' and ``dfc'' (hex) are the 68020 source/destination function codes. +.\" They should always be one. +.\" ``p0'' and ``p1'' are the +.\" VAX-like +.\" region registers. +.\" They are of the form: +.\" .Pp +.\" .Bd -ragged -offset indent +.\" '@' +.\" .Ed +.\" .Pp +.\" where both are in hex. +.\" Following these values are a dump of the processor registers (hex). +.\" Finally, is a dump of the stack (user/kernel) at the time of the offense. +.\" .Pp +.It "init died (signal #, exit #)" +The system initialization process has exited with the specified +signal number and exit code. +This is bad news, as no new users will then be able to log in. +Rebooting is the only fix, so the +system just does it right away. +.El +.Pp +That completes the list of panic types you are likely to see. +.Pp +If the system has been configured to take crash dumps (see +.Xr dumpon 8 ) , +then when it crashes it will write (or at least attempt to write) +an image of memory into the back end of the dump device, +usually the same as the primary swap +area. +After the system is rebooted, the program +.Xr savecore 8 +runs and preserves a copy of this core image and the current +system in a specified directory for later perusal. +See +.Xr savecore 8 +for details. +.Pp +To analyze a dump you should begin by running +.Xr kgdb 1 Pq Pa ports/devel/gdb +on the system load image and core dump. +If the core image is the result of a panic, +the panic message is printed. +For more details consult the chapter on kernel debugging in +the +.%B "FreeBSD Developers' Handbook" +.Pq Pa https://www.freebsd.org/doc/en/books/developers-handbook/ . +.Sh SEE ALSO +.Xr kgdb 1 Pq Pa ports/devel/gdb , +.Xr dumpon 8 , +.Xr reboot 8 , +.Xr savecore 8 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 2.2 . diff --git a/static/freebsd/man8/debug.sh.8 b/static/freebsd/man8/debug.sh.8 new file mode 100644 index 00000000..3b59d6ae --- /dev/null +++ b/static/freebsd/man8/debug.sh.8 @@ -0,0 +1,191 @@ +.\" Copyright (c) 1994-2021 Simon J. Gerraty +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" This file is provided in the hope that it will +.\" be of use. There is absolutely NO WARRANTY. +.\" Permission to copy, redistribute or otherwise +.\" use this file is hereby granted provided that +.\" the above copyright notice and this notice are +.\" left intact. +.\" +.\" Please send copies of changes and bug-fixes to: +.\" sjg@crufty.net +.\" +.Dd October 22, 2024 +.Dt DEBUG.SH 8 +.Os +.Sh NAME +.Nm debug.sh +.Nd selectively debug scripts +.Sh SYNOPSIS +.Bl -item -compact +.It +.Ic $_DEBUG_SH .\& Pa debug.sh +.Pp +.It +.Ic DebugOn Oo Fl eo Oc Ar tag ... +.It +.Ic DebugOff Oo Fl eo Oc Oo Cm rc= Ns Ar rc Oc Ar tag ... +.It +.Ic Debugging +.It +.Ic DebugAdd Ar tag +.It +.Ic DebugEcho Op Ar message +.It +.Ic DebugLog Op Ar message +.It +.Ic DebugShell Ar tag ... +.It +.Ic DebugTrace Ar message +.It +.Ic Debug Ar tag ... +.El +.Sh DESCRIPTION +.Nm +provides the following functions to facilitate flexible +run-time tracing of complicated shell scripts. +.Bl -tag -width 4n +.It Ic DebugOn Oo Fl eo Oc Ar tag ... +turns tracing on if any +.Ar tag +is found in +.Va DEBUG_SH +(a comma separated list of tags). +.Pp +It turns tracing off if +.Ar !tag +is found in +.Va DEBUG_SH . +.Pp +It sets +.Va DEBUG_ON +to the +.Ar tag +that caused tracing to be enabled, or +.Va DEBUG_OFF +if we matched +.Ar !tag . +.Pp +If +.Fl e +option is present, returns 1 if no +.Ar tag +matched. +.Pp +If +.Fl o +option is present, tracing is turned off unless there +was a matched +.Ar tag , +useful for functions too noisy to tace. +.It Ic DebugOff Oo Fl eo Oc Oo Cm rc= Ns Ar rc Oc Ar tag ... +turns tracing on if any +.Ar tag +matches +.Va DEBUG_OFF +or off if any +.Ar tag +matches +.Va DEBUG_ON . +This allows nested functions to not interfere with each other. +.Pp +The flags +.Fl e +and +.Fl o +are ignored, they just allow for symmetry with calls to +.Fn DebugOn . +.Pp +The optional +.Ar rc +value will be returned rather than the default of 0. +Thus if +.Fn DebugOff +is the last operation in a function, +.Ar rc +will be the return code of the function. +.It Ic Debugging +returns true if tracing is enabled. +It is useful for bounding complex debug actions, rather than +using lots of +.Ic $DEBUG_DO +lines. +.It Ic DebugAdd Ar tag +Add +.Ar tag +to +.Va DEBUG_SH +to influence later output, +possibly in a child process. +.It Ic DebugEcho +is just shorthand for: +.Bd -literal -offset indent +$DEBUG_DO echo "$@" +.Ed +.It Ic DebugLog Op Ar message +If debugging is enabled, output +.Ar message +prefixed with a time-stamp. +.It Ic DebugShell Ar tag ... +runs an interactive shell if any +.Ar tag +is found in +.Va DEBUG_INTERACTIVE , +and there is a tty available. +The shell used is defined by +.Va DEBUG_SHELL +or +.Va SHELL +and defaults to +.Pa /bin/sh . +.It Ic DebugTrace Ar message +Debug output can be very noisy, and it can be tricky +to align with the script. +This function outputs a very noticeable banner indicating the value of +.Va DEBUG_ON , +and +.Ar message +is passed to +.Fn DebugLog , +finally the banner is repeated. +.It Ic Debug Ar tag ... +For backwards compatibility, calls +.Fn DebugOn +and if that does not turn tracing on, +it calls +.Fn DebugOff +to turn it off. +.El +.Pp +The variables +.Va DEBUG_SKIP +and +.Va DEBUG_DO +are set so as to enable/disable code that should be +skipped/run when debugging is turned on. +.Va DEBUGGING +is the same as +.Va DEBUG_SKIP +for backwards compatibility and is only set by +.Fn Debug . +.Pp +The use of +.Ic $_DEBUG_SH +is to prevent multiple inclusion, +though it does no harm in this case. +.Sh BUGS +Does not work with some versions of +.Xr ksh 1 . +If a function turns tracing on, ksh turns it off when the +function returns - useless. +.Pp +PD ksh works ok ;-) +.Sh AUTHOR +.An -nosplit +.Nm +was written by +.An Simon J Gerraty Aq Mt sjg@crufty.net . + + diff --git a/static/freebsd/man8/diskless.8 b/static/freebsd/man8/diskless.8 new file mode 100644 index 00000000..cc49854a --- /dev/null +++ b/static/freebsd/man8/diskless.8 @@ -0,0 +1,486 @@ +.\"- +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.\" Copyright (c) 1994 Gordon W. Ross, Theo de Raadt +.\" Updated by Luigi Rizzo, Robert Watson +.\" 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. 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 August 11, 2024 +.Dt DISKLESS 8 +.Os +.Sh NAME +.Nm diskless +.Nd booting a system over the network with PXE +.Sh DESCRIPTION +The ability to boot a machine over the network is useful for +.Em diskless +or +.Em dataless +machines, or as a temporary measure while repairing or +re-installing file systems on a local disk. +This file provides a general description of the interactions between +a client and its server when a client is booting over the network. +.Sh OPERATION +When booting a system over the network, there are three +phases of interaction between client and server: +.Bl -enum +.It +The stage-1 bootstrap, typically PXE built into your Ethernet +card, loads a second-stage boot program. +.It +The second-stage boot program, typically +.Xr pxeboot 8 , +loads modules and +the kernel, and boots the kernel. +.It +The kernel +.Tn NFS +mounts the root directory and continues from there. +.El +.Pp +Each of these phases are described in further detail below. +.Pp +First, the stage-1 bootstrap loads the stage-2 boot program over +the network. +The stage-1 bootstrap typically uses +.Tn BOOTP +or +.Tn DHCP +to obtain the filename to load, then uses +.Tn TFTP +to load the file. +This file is typically called +.Pa pxeboot , +and should be copied from +.Pa /boot/pxeboot +into the +.Tn TFTP +directory on the server, which is typically +.Pa /tftpdir . +.Pp +The stage-2 boot program then loads additional modules and the kernel. +These files may not exist on the +.Tn DHCP +or +.Tn BOOTP +server. +You can use the +.Ic next-server +option available in +.Tn DHCP +configurations to specify the server holding +the second stage boot files and kernel. +The stage-2 program uses +.Tn NFS +or +.Tn TFTP +to obtain these files. +By default, +.Tn NFS +is used. +If you are using +.Xr pxeboot 8 , +you can install a version that uses +.Tn TFTP +by setting +.Li LOADER_TFTP_SUPPORT=YES +in your +.Xr make.conf 5 , +then recompiling and reinstalling +.Xr pxeboot 8 +via the command listed below. +It is often necessary to use +.Tn TFTP +here so you can place a custom kernel +in +.Pa /tftpdir/ . +If you use +.Tn NFS +and do not have a custom root file system for the +.Nm +client, the stage-2 boot will load your server's kernel as the kernel for +the +.Nm +machine, which may not be what you want to have happen. +.Bd -literal -offset indent +cd /usr/src/stand +make clean; make; make install +cp /boot/pxeboot /tftpdir/ +.Ed +.Pp +In phase 3, the kernel acquires IP networking configuration in one +of two ways, and then proceeds to mount the root file system and start +operation. +If the phase 2 loader supports passing network configuration to the +kernel using the kernel environment, then the kernel will configure +the network interface using that information. +Otherwise, it must use +.Tn DHCP +or +.Tn BOOTP +to acquire +configuration information. +The boot +scripts recognize a +.Nm +startup and perform +the actions found in +.Pa /etc/rc.d/resolv , +.Pa /etc/rc.d/tmp , +.Pa /etc/rc.d/var , +and +.Pa /etc/rc.initdiskless . +.Sh CONFIGURATION +In order to run a +.Nm +client, you need the following: +.Bl -bullet +.It +An +.Tn NFS +server which exports a root and +.Pa /usr +partitions with appropriate permissions. +The +.Nm +scripts work with read-only partitions, as long as root is exported with +.Fl maproot Ns =0 +so that some system files can be accessed. +As an example, +.Pa /etc/exports +can contain the following lines: +.Bd -literal -offset indent + -ro -maproot=0 -alldirs +/usr -ro -alldirs +.Ed +.Pp +where +.Aq ROOT +is the mount point on the server of the root partition. +The script +.Pa /usr/share/examples/diskless/clone_root +can be used to create a shared read-only root partition, +but in many cases you may decide to export +(again as read-only) the root directory used by +the server itself. +.It +A +.Tn BOOTP +or +.Tn DHCP +server. +.Xr bootpd 8 +can be enabled by +uncommenting the +.Dq Li bootps +line in +.Pa /etc/inetd.conf . +A sample +.Pa /etc/bootptab +can be the following: +.Bd -literal -offset indent + .default:\\ + hn:ht=1:vm=rfc1048:\\ + :sm=255.255.255.0:\\ + :sa=:\\ + :gw=:\\ + :rp=":": + +:ha=0123456789ab:tc=.default +.Ed +.Pp +where +.Aq SERVER , +.Aq GATEWAY +and +.Aq ROOT +have the obvious meanings. +.It +A properly initialized root partition. +The script +.Pa /usr/share/examples/diskless/clone_root +can help in creating it, using the server's root partition +as a reference. +If you are just starting out, you should +simply use the server's own root directory, +.Pa / , +and not try to clone it. +.Pp +You often do not want to use the same +.Pa rc.conf +or +.Pa rc.local +files for the +.Nm +boot as you do on the server. +The +.Nm +boot +scripts provide a mechanism through which you can override various files +in +.Pa /etc +(as well as other subdirectories of root). +.Pp +One difference that you should pay particular attention to is +the value of +.Va local_startup +in +.Pa /etc/defaults/rc.conf . +A typical value for a +.Nm +boot is +.Va mountcritremote , +however your needs may be different. +.Pp +The scripts provide four +overriding directories situated in +.Pa /conf/base , +.Pa /conf/default , +.Pa /conf/ , +and +.Pa /conf/ . +You should always create +.Pa /conf/base/etc , +which will entirely replace the server's +.Pa /etc +on the +.Nm +machine. +You can clone the server's +.Pa /etc +here or you can create a special file which tells the +.Nm +boot scripts +to remount the server's +.Pa /etc +onto +.Pa /conf/base/etc . +You do this by creating the file +.Pa /conf/base/etc/diskless_remount +containing the mount point to use as a basis of the +.Nm +machine's +.Pa /etc . +For example, the file might contain: +.Pp +.Dl 10.0.0.1:/etc +.Pp +Alternatively, if the server contains several independent roots, the file +might contain: +.Pp +.Dl 10.0.0.1:/usr/diskless/4.7-RELEASE/etc +.Pp +This would work, but if you copied +.Pa /usr/diskless/4.7-RELEASE +to +.Pa /usr/diskless/4.8-RELEASE +and upgraded the installation, you would need to modify the +.Pa diskless_remount +files to reflect that move. +To avoid that, paths in +.Pa diskless_remount +files beginning with +.Pa / +have the actual path of the client's root prepended to them so the file +could instead contain: +.Pp +.Dl /etc +.Pp +The +.Nm +scripts create memory file systems to hold the overridden +directories. +Only a 5MB partition is created by default, which may not +be sufficient for your purposes. +To override this, you can create the +file +.Pa /conf/base/etc/md_size +containing the size, in 512 byte sectors, of the memory disk to create +for that directory. +.Pp +You then typically provide file-by-file overrides in the +.Pa /conf/default/etc +directory. +At a minimum, you must provide overrides for +.Pa /etc/fstab , /etc/rc.conf , +and +.Pa /etc/rc.local +via +.Pa /conf/default/etc/fstab , /conf/default/etc/rc.conf , +and +.Pa /conf/default/etc/rc.local . +.Pp +Overrides are hierarchical. +You can supply network-specific defaults +in the +.Pa /conf/ Ns Ao Ar BROADCASTIP Ac Ns Pa /etc +directory, where +.Aq Ar BROADCASTIP +represents the broadcast IP address of +the +.Nm +system as given to it via +.Tn BOOTP . +The +.Pa diskless_remount +and +.Pa md_size +features work in any of these directories. +The configuration feature works on directories other then +.Pa /etc , +you simply create the directory you wish to replace or override in +.Pa /conf/{base,default,,}/* +and work it in the same way that you work +.Pa /etc . +.Pp +Since you normally clone the server's +.Pa /etc +using the +.Pa /conf/base/etc/diskless_remount , +you might wish to remove unneeded files from the memory file system. +For example, +if the server has a firewall but you do not, you might wish +to remove +.Pa /etc/ipfw.conf . +You can do this by creating a +.Pa /conf/base/ Ns Ao Ar DIRECTORY Ac Ns Pa .remove +file. +For example, +.Pa /conf/base/etc.remove , +which contains a list of relative paths that the boot scripts should remove +from the memory file systems. +.Pp +As a minimum, you normally need to have the following in +.Pa /conf/default/etc/fstab +.Bd -literal -offset indent +: / nfs ro 0 0 +:/usr /usr nfs ro 0 0 +.Ed +.Pp +You also need to create a customized version of +.Pa /conf/default/etc/rc.conf +which should contain +the startup options for the +.Nm +client, and +.Pa /conf/default/etc/rc.local +which could be empty but prevents the server's own +.Pa /etc/rc.local +from leaking onto the +.Nm +system. +.Pp +In +.Pa rc.conf , +most likely +you will not need to set +.Va hostname +and +.Va ifconfig_* +because these will be already set by the startup code. +Finally, it might be convenient to use a +.Ic case +statement using +.Li `hostname` +as the switch variable to do machine-specific configuration +in case a number of +.Nm +clients share the same configuration +files. +.It +The kernel for the +.Nm +clients, which will be loaded using +.Tn NFS +or +.Tn TFTP , +must include support for the NFS client: +.Pp +.D1 Cd "options NFSCL" +.D1 Cd "options NFS_ROOT" +.Pp +If you are using a boot mechanism that does not pass network configuration +to the kernel using the kernel environment, you will also need to include +the following options: +.Pp +.D1 Cd "options BOOTP" +.D1 Cd "options BOOTP_NFSROOT" +.D1 Cd "options BOOTP_COMPAT" +.Pp +.Em Note : +the PXE environment does not require these options. +.Pp +The +.Nm +booting environment relies on memory-backed file systems to +support temporary local storage in the event that the root file system +is mounted read-only; as such, it is necessary to add the following +to the device section of the kernel configuration: +.Pp +.D1 Cd "device md" +.Pp +If you use the firewall, remember to default to +.Dq open , +or your kernel +will not be able to send/receive the +.Tn BOOTP +packets. +.El +.Sh SECURITY ISSUES +Be warned that using unencrypted +.Tn NFS +to mount root and user +partitions may expose information such as +encryption keys. +.Sh SEE ALSO +.Xr ethers 5 , +.Xr exports 5 , +.Xr make.conf 5 , +.Xr bootpd 8 , +.Xr mountd 8 , +.Xr nfsd 8 , +.Xr pxeboot 8 , +.Xr reboot 8 , +.Xr tftpd 8 +.Pp +.Pa ports/net/etherboot +.Sh HISTORY +The +.Nm +environment first appeared in +.Fx 2.2.5 . +.Sh BUGS +This manpage is probably incomplete. +.Pp +.Fx +sometimes requires to write onto +the root partition, so the startup scripts mount MFS +file systems on some locations (e.g.\& +.Pa /etc +and +.Pa /var ) , +while +trying to preserve the original content. +The process might not handle all cases. diff --git a/static/freebsd/man8/intro.8 b/static/freebsd/man8/intro.8 new file mode 100644 index 00000000..bfa7d026 --- /dev/null +++ b/static/freebsd/man8/intro.8 @@ -0,0 +1,86 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 October 22, 2006 +.Dt INTRO 8 +.Os +.Sh NAME +.Nm intro +.Nd "introduction to system maintenance procedures and commands" +.Sh DESCRIPTION +This section contains information related to system operation +and maintenance. +.Pp +It describes commands used to create new file systems +.Pq Xr newfs 8 , +verify the integrity of the file systems +.Pq Xr fsck 8 , +control disk usage +.Pq Xr edquota 8 , +maintain system backups +.Pq Xr dump 8 , +and recover files when disks die an untimely death +.Pq Xr restore 8 . +.\" The +.\" .Xr format 8 +.\" manual +.\" for the specific architecture the system is running on should be +.\" consulted when formatting disks and tapes. +Network related services like +.Xr inetd 8 +are also described. +.Pp +All commands set an exit status. +Its value may be tested +to see if the command completed normally. +Unless otherwise noted (rare), the value 0 signifies successful +completion of the command, while a value >0 indicates an error. +Some commands attempt to describe the nature of the failure by using +error codes defined in +.Xr sysexits 3 , +or set the status to arbitrary values >0 (typically 1), but many +such values are not described in the manual. +.Pp +A number of pages in this section describe general system +management topics. +.Pp +For example, the +.Xr boot 8 +manual page describes the system bootstrapping procedures, +and the +.Xr diskless 8 +manual page describes how to boot a system over a network. +The +.Xr crash 8 +manual page +should be consulted to understand how to interpret system +crash dumps. +.Sh HISTORY +The +.Nm +section manual page appeared in +.Bx 4.2 . diff --git a/static/freebsd/man8/nanobsd.8 b/static/freebsd/man8/nanobsd.8 new file mode 100644 index 00000000..44def250 --- /dev/null +++ b/static/freebsd/man8/nanobsd.8 @@ -0,0 +1,366 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2006 Daniel Gerzo +.\" 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 AUTHORS 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 AUTHORS 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 September 9, 2025 +.Dt NANOBSD 8 +.Os +.Sh NAME +.Nm nanobsd.sh +.Nd create an embedded FreeBSD system image +.Sh SYNOPSIS +.Nm +.Op Fl BbfhIiKknpqvWwX +.Op Fl c Ar config-file +.Sh DESCRIPTION +The +.Nm +utility is a script which produces a minimal implementation of +.Fx +(called +.Nm NanoBSD ) , +which typically fits on a small media such as an SD card, +or other mass storage medium. +It can be used to build specialized install images, designed for easy +installation and maintenance. +.Pp +The following options are available: +.Bl -tag -width ".Fl c Ar config-file" -offset indent +.It Fl B +Skip the install stages (both for kernel and world). +.It Fl b +Skip the build stages (both for kernel and world). +.It Fl c Ar config-file +Specify the configuration file to use. +.It Fl f +Skip the code slice extraction. +.It Fl h +Display usage information. +.It Fl I +Build the disk image from an existing build/install. +.It Fl i +Skip the disk image build stage. +.It Fl K +Skip the +.Cm installkernel +stage of the build. +.It Fl k +Skip the +.Cm buildkernel +stage of the build. +.It Fl n +Do not cleanup before each build stage. +This suppresses the normal cleanup work done before the +.Cm buildworld +stage and adds -DNO_CLEAN to the make command line +used for each build stage (world and kernel). +.It Fl p +Don't prepare the image. +Skip running of the customization and early customization scripts for +incremental image refinement from world, kernel, or packages. +.It Fl q +Make output more quiet. +.It Fl v +Make output more verbose. +.It Fl W +Skip the +.Cm installworld +stage of the build. +.It Fl w +Skip the +.Cm buildworld +stage of the build. +.It Fl X +Make +.Cm native-xtools . +.El +.Pp +The features of +.Nm NanoBSD +include: +.Pp +.Bl -bullet -offset indent -compact +.It +Ports and packages work as in +.Fx . +Every single application can be installed and used in a +.Nm NanoBSD +image, the same way as in +.Fx . +.It +No missing functionality. +If it is possible to do something with +.Fx , +it is possible to do the same thing with +.Nm NanoBSD , +unless the specific feature or features were explicitly removed from the +.Nm NanoBSD +image when it was created. +.It +Everything is read-only at run-time. +It is safe to pull the power-plug. +There is no necessity to run +.Xr fsck 8 +after a non-graceful shutdown of the system. +.It +Easy to build and customize. +Making use of just one shell script and one configuration file it is +possible to build reduced and customized images satisfying any arbitrary +set of requirements. +.El +.Ss NanoBSD Media Layout +The mass storage medium is divided into three parts by default (which +are normally mounted read-only): +.Pp +.Bl -bullet -offset indent -compact +.It +Two image partitions: +.Li code#1 +and +.Li code#2 . +.It +The configuration file partition, which can be mounted under the +.Pa /cfg +directory at run time. +.El +.Pp +The +.Pa /etc +and +.Pa /var +directories are +.Xr md 4 +(malloc backed) disks. +.Pp +The configuration file partition persists under the +.Pa /cfg +directory. +It contains files for +.Pa /etc +directory and is briefly mounted read-only right after the system boot, +therefore it is required to copy modified files from +.Pa /etc +back to the +.Pa /cfg +directory if changes are expected to persist after the system restarts. +.Sh BUILDING Nm NanoBSD +A +.Nm NanoBSD +image is built using a simple +.Nm +shell script, which can be +found in the +.Pa src/tools/tools/nanobsd +directory. +This script creates a bootable image, which can be copied on the storage +medium using the +.Xr dd 1 +utility. +.Pp +The necessary commands to build and install a +.Nm NanoBSD +image are: +.Bd -literal -offset indent +cd /usr/src/tools/tools/nanobsd +sh nanobsd.sh +cd /usr/obj/nanobsd.full +dd if=_.disk.full of=/dev/da0 bs=64k +.Ed +.Sh CUSTOMIZING Nm NanoBSD +This is probably the most important and most interesting feature of +.Nm NanoBSD . +This is also where you will be spending most of the time when developing with +.Nm NanoBSD . +.Pp +Customization is done in two ways: +.Pp +.Bl -bullet -offset indent -compact +.It +Configuration options. +.It +Custom functions. +.El +.Pp +With configuration settings, it is possible to configure options passed +to both the +.Cm buildworld +and +.Cm installworld +stages of the +.Nm NanoBSD +build process, as well as internal options passed to the main build +process of +.Nm NanoBSD . +Through these options it is possible to cut the system down, so it will +fit on as little as 64MB. +You can use the configuration options to trim down the system +even more, until it will consist of just the kernel and two or three +files in the userland. +.Pp +The configuration file consists of configuration options, which override +the default values. +The most important directives are: +.Bl -tag -width ".Va CONF_INSTALL" -offset indent +.It Va NANO_NAME +Build name (used to construct the working directory names). +.It Va NANO_SRC +Path to the source tree used to build the image. +.It Va NANO_KERNEL +Name of the kernel configuration file used to build the kernel. +.It Va NANO_ARCH +Machine processor architecture to build. +Defaults to output of +.Cm uname -p . +.It Va NANO_BOOT0CFG +Controls the options passed to +.Xr boot0cfg 8 ; +these dictate +.Nm boot0 Ns 's +behaviour. +.It Va NANO_BOOTLOADER +The +.Nm boot0 +loader to use relative to the +.Va NANO_WORLDDIR +variable. +This defaults to +.Pa boot/boot0sio +and should be overridden to +.Pa boot/boot0 +to provide a VGA +console. +.It Va CONF_BUILD +Options passed to the +.Cm buildworld +stage of the build. +.It Va CONF_INSTALL +Options passed to the +.Cm installworld +stage of the build. +.It Va CONF_WORLD +Options passed to both the +.Cm buildworld +and +.Cm installworld +stages of the build. +.It Va FlashDevice +Defines the type of media to use. +Check the +.Pa FlashDevice.sub +file for more details. +.El +.Pp +For more configuration options, please check the +.Nm +script. +.Pp +To build +.Nm NanoBSD +image using the +.Pa nanobsd.conf +configuration file, use the following command: +.Bd -literal -offset indent +sh nanobsd.sh -c nanobsd.conf +.Ed +.Pp +It is possible to fine-tune +.Nm NanoBSD +using shell functions in the configuration file. +The following example illustrates the basic model of custom functions: +.Bd -literal -offset indent +cust_foo () ( + echo "bar=topless" > \\ + ${NANO_WORLDDIR}/etc/foo +) +customize_cmd cust_foo +.Ed +.Pp +There are a few pre-defined customization functions ready for use: +.Bl -tag -width ".Cm cust_allow_ssh_root" -offset indent +.It Cm cust_comconsole +Disables +.Xr getty 8 +on the virtual +.Xr syscons 4 +or +.Xr vt 4 +terminals +.Pq Pa /dev/ttyv* +and enables the use of the first serial port as the system +console. +.It Cm cust_allow_ssh_root +Allow root to log in via +.Xr sshd 8 . +.It Cm cust_install_files +Installs files from the +.Pa nanobsd/Files +directory, which contains some useful scripts for system administration. +.El +.Sh FILES +.Bl -tag -width ".Pa src/tools/tools/nanobsd" -compact +.It Pa src/tools/tools/nanobsd +Base directory of the +.Nm NanoBSD +build script. +.El +.Sh EXAMPLES +Making persistent changes to +.Pa /etc/resolv.conf : +.Bd -literal -offset indent +vi /etc/resolv.conf +\&... +mount /cfg +cp /etc/resolv.conf /cfg +umount /cfg +.Ed +.Pp +A more useful example of a customization function is the following, +which changes the default size of the +.Pa /etc +directory from 5MB to 30MB: +.Bd -literal -offset indent +cust_etc_size () ( + cd ${NANO_WORLDDIR}/conf + echo 30000 > default/etc/md_size +) +customize_cmd cust_etc_size +.Ed +.Sh SEE ALSO +.Xr make.conf 5 , +.Xr boot 8 , +.Xr boot0cfg 8 +.Sh HISTORY +The +.Nm +utility first appeared in +.Fx 6.0 . +.Sh AUTHORS +.An -nosplit +.Nm NanoBSD +was developed by +.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org . +This manual page was written by +.An Daniel Gerzo Aq Mt danger@FreeBSD.org . diff --git a/static/freebsd/man8/rc.8 b/static/freebsd/man8/rc.8 new file mode 100644 index 00000000..a68878f0 --- /dev/null +++ b/static/freebsd/man8/rc.8 @@ -0,0 +1,587 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Portions of this manual page are Copyrighted by +.\" The NetBSD Foundation. +.\" +.\" 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 September 20, 2024 +.Dt RC 8 +.Os +.Sh NAME +.Nm rc +.Nd command scripts for auto-reboot and daemon startup +.Sh SYNOPSIS +.Nm +.Nm rc.conf +.Nm rc.conf.local +.Nm rc.d/ +.Nm rc.firewall +.Nm rc.local +.Nm rc.resume +.Nm rc.shutdown +.Nm rc.subr +.Nm rc.suspend +.Sh DESCRIPTION +The +.Nm +utility is the command script which controls the automatic boot process +after being called by +.Xr init 8 . +The +.Nm rc.local +script contains commands which are pertinent only +to a specific site. +Typically, the +.Pa /usr/local/etc/rc.d/ +mechanism is used instead of +.Nm rc.local +these days but if +you want to use +.Nm rc.local , +it is still supported. +In this case, it should source +.Pa /etc/rc.conf +and contain additional custom startup code for your system. +The best way to handle +.Nm rc.local , +however, is to separate it out into +.Nm rc.d/ +style scripts and place them under +.Pa /usr/local/etc/rc.d/ . +The +.Nm rc.conf +file contains the global system configuration information referenced +by the startup scripts, while +.Nm rc.conf.local +contains the local system configuration. +See +.Xr rc.conf 5 +for more information. +.Pp +The +.Nm rc.d/ +directories contain scripts which will be automatically +executed at boot time and shutdown time. +.Pp +The +.Xr service 8 +command provides a convenient interface to manage rc.d services. +.Pp +The +.Xr sysrc 8 +command provides a scripting interface to modify system config files. +.Ss Operation of Nm +.Bl -enum +.It +If autobooting, set +.Va autoboot Ns = Ns Li yes +and enable a flag +.Pq Va rc_fast Ns = Ns Li yes , +which prevents the +.Nm rc.d/ +scripts from performing the check for already running processes +(thus speeding up the boot process). +This +.Va rc_fast Ns = Ns Li yes +speedup will not occur when +.Nm +is started up after exiting the single-user shell. +.It +Determine whether the system is booting diskless, +and if so run the +.Pa /etc/rc.initdiskless +script. +.It +Source +.Pa /etc/rc.subr +to load various +.Xr rc.subr 8 +shell functions to use. +.It +Load the configuration files (see below for reloading). +.It +Determine if booting in a jail, and add +.Dq Li nojail +(no jails allowed) or +.Dq Li nojailvnet +(only allow vnet-enabled jails) to the list of KEYWORDS to skip in +.Xr rcorder 8 . +.It +If the file +.Va ${firstboot_sentinel} +does not exist, add +.Dq Li firstboot +to the list of KEYWORDS to skip in +.Xr rcorder 8 . +.It +Invoke +.Xr rcorder 8 +to order the files in +.Pa /etc/rc.d/ +that do not have a +.Dq Li nostart +KEYWORD (refer to +.Xr rcorder 8 Ns 's +.Fl s +flag). +.It +Call +.Fn run_rc_scripts +with the list of scripts to be run. +.Pp +For each script that will call +.Fn run_rc_script +(both functions are from +.Xr rc.subr 8 ) , +which sets +.Va $1 +to +.Dq Li start , +and sources the script in a subshell. +Stop processing when the script that is the value of the +.Va $early_late_divider +has been run. +.It +Check again to see if the file +.Va ${firstboot_sentinel} +exists (in case it is located on a newly mounted file system) +and adjust the list of KEYWORDs to skip appropriately. +.It +Re-run +.Xr rcorder 8 , +this time including the scripts in the +.Va $local_startup +directories. +Call +.Fn run_rc_scripts +again with the new list of scripts. +It will skip any that have already been run and +execute the rest as described above. +.It +If the file +.Va ${firstboot_sentinel} +exists, delete it. +If the file +.Va ${firstboot_sentinel}-reboot +also exists (because it was created by a script), then delete it and reboot. +.El +.Ss Operation of Nm rc.shutdown +.Bl -enum +.It +Set +.Va rc_shutdown +to the value of the first argument passed to +.Nm rc.shutdown +or to +.Dq Li unspecified +if no argument was passed. +.It +Source +.Pa /etc/rc.subr +to load various +.Xr rc.subr 8 +shell functions to use. +.It +Load the configuration files. +.It +Invoke +.Xr rcorder 8 +to order the files in +.Pa /etc/rc.d/ +and the +.Va $local_startup +directories +that have a +.Dq Li shutdown +KEYWORD (refer to +.Xr rcorder 8 Ns 's +.Fl k +flag), +reverse that order, and assign the result to a variable. +.It +Call each script in turn using +.Fn run_rc_script +(from +.Xr rc.subr 8 ) , +which sets +.Va $1 +to +.Dq Li faststop , +and sources the script in a subshell. +.El +.Ss Contents of Nm rc.d/ +.Nm rc.d/ +is located in +.Pa /etc/rc.d/ . +The following file naming conventions are currently used in +.Nm rc.d/ : +.Bl -tag -width ".Pa ALLUPPERCASE" -offset indent +.It Pa ALLUPPERCASE +Scripts that are +.Dq placeholders +to ensure that certain operations are performed before others. +In order of startup, these are: +.Bl -tag -width ".Pa FILESYSTEMS" +.It Pa FILESYSTEMS +Ensure that root and other critical file systems are mounted. +This is the default +.Va $early_late_divider . +.It Pa NETWORKING +Ensure basic network services are running, including general +network configuration. +.It Pa SERVERS +Ensure basic services +exist for services that start early (such as +.Pa nisdomain ) , +because they are required by +.Pa DAEMON +below. +.It Pa DAEMON +Check-point before all general purpose daemons such as +.Pa lpd +and +.Pa ntpd . +.It Pa LOGIN +Check-point before user login services +.Pa ( inetd +and +.Pa sshd ) , +as well as services which might run commands as users +.Pa ( cron +and +.Pa sendmail ) . +.El +.It Pa bar +Scripts that are sourced in a subshell. +The boot does not stop if such a script terminates with a non-zero status, +but a script can stop the boot if necessary by invoking the +.Fn stop_boot +function (from +.Xr rc.subr 8 ) . +.El +.Pp +Each script should contain +.Xr rcorder 8 +keywords, especially an appropriate +.Dq Li PROVIDE +entry, and if necessary +.Dq Li REQUIRE +and +.Dq Li BEFORE +keywords. +.Pp +Each script is expected to support at least the following arguments, which +are automatically supported if it uses the +.Fn run_rc_command +function: +.Bl -tag -width ".Cm restart" -offset indent +.It Cm start +Start the service. +This should check that the service is to be started as specified by +.Xr rc.conf 5 . +Also checks if the service is already running and refuses to start if +it is. +This latter check is not performed by standard +.Fx +scripts if the system is starting directly to multi-user mode, to +speed up the boot process. +If +.Cm forcestart +is given, ignore the +.Xr rc.conf 5 +check and start anyway. +.It Cm stop +If the service is to be started as specified by +.Xr rc.conf 5 , +stop the service. +This should check that the service is running and complain if it is not. +If +.Cm forcestop +is given, ignore the +.Xr rc.conf 5 +check and attempt to stop. +.It Cm restart +Perform a +.Cm stop +then a +.Cm start . +.It Cm status +If the script starts a process (rather than performing a one-off +operation), show the status of the process. +Otherwise it is not necessary to support this argument. +Defaults to displaying the process ID of the program (if running). +.It Cm enable +Enable the service in +.Xr rc.conf 5 . +.It Cm disable +Disable the service in +.Xr rc.conf 5 . +.It Cm delete +Remove the service from +.Xr rc.conf 5 . +If +.Ql Li service_delete_empty +is set to +.Dq Li YES , +.Pa /etc/rc.conf.d/$servicename +will be deleted if empty after modification. +.It Cm describe +Print a short description of what the script does. +.It Cm extracommands +Print the script's non-standard commands. +.It Cm poll +If the script starts a process (rather than performing a one-off +operation), wait for the command to exit. +Otherwise it is not necessary to support this argument. +.It Cm enabled +Return 0 if the service is enabled and 1 if it is not. +This command does not print anything. +.It Cm rcvar +Display which +.Xr rc.conf 5 +variables are used to control the startup of the service (if any). +.El +.Pp +If a script must implement additional commands it can list them in +the +.Va extra_commands +variable, and define their actions in a variable constructed from +the command name (see the +.Sx EXAMPLES +section). +.Pp +The configuration files are normally read only once at the start of a boot +sequence; if a script needs to +.Cm enable +or +.Cm disable +any other script that would run later in the sequence, it must send a +.Dv SIGALRM +to the rc process (identified by +.Ev $RC_PID ) +to have it re-read the files. +.Pp +The following key points apply to old-style scripts in +.Pa /usr/local/etc/rc.d/ : +.Bl -bullet +.It +Scripts are only executed if their +.Xr basename 1 +matches the shell globbing pattern +.Pa *.sh , +and they are executable. +Any other files or directories present within the directory are silently +ignored. +.It +When a script is executed at boot time, it is passed the string +.Dq Li start +as its first and only argument. +At shutdown time, it is passed the string +.Dq Li stop +as its first and only argument. +All +.Nm rc.d/ +scripts are expected to handle these arguments appropriately. +If no action needs to be taken at a given time +(either boot time or shutdown time), +the script should exit successfully and without producing an error message. +.It +The scripts within each directory are executed in lexicographical order. +If a specific order is required, +numbers may be used as a prefix to the existing filenames, +so for example +.Pa 100.foo +would be executed before +.Pa 200.bar ; +without the numeric prefixes the opposite would be true. +.It +The output from each script is traditionally a space character, +followed by the name of the software package being started or shut down, +.Em without +a trailing newline character. +.El +.Sh SCRIPTS OF INTEREST +When an automatic reboot is in progress, +.Nm +is invoked with the argument +.Cm autoboot . +One of the scripts run from +.Pa /etc/rc.d/ +is +.Pa /etc/rc.d/fsck . +This script runs +.Xr fsck 8 +with option +.Fl p +and +.Fl F +to +.Dq preen +all the disks of minor inconsistencies resulting +from the last system shutdown. +If this fails, then checks/repairs of serious inconsistencies +caused by hardware or software failure will be performed +in the background at the end of the booting process. +If +.Cm autoboot +is not set, when going from single-user to multi-user mode for example, +the script does not do anything. +.Pp +The +.Pa /etc/rc.d/serial +script is used to set any special configurations for serial devices. +.Pp +The +.Nm rc.firewall +script is used to configure rules for the kernel based firewall +service. +It has several possible options: +.Pp +.Bl -tag -width ".Ar filename" -compact -offset indent +.It Cm open +will allow anyone in +.It Cm client +will try to protect just this machine +.It Cm simple +will try to protect a whole network +.It Cm closed +totally disables IP services except via +.Pa lo0 +interface +.It Cm UNKNOWN +disables the loading of firewall rules +.It Ar filename +will load the rules in the given filename (full path required). +.El +.Pp +Most daemons, including network related daemons, have their own script in +.Pa /etc/rc.d/ , +which can be used to start, stop, and check the status of the service. +.Pp +Any architecture specific scripts, such as +.Pa /etc/rc.d/apm +for example, specifically check that they are on that architecture +before starting the daemon. +.Pp +Following tradition, all startup files reside in +.Pa /etc . +.Sh FILES +.Bl -tag -compact -width Pa +.It Pa /etc/rc +.It Pa /etc/rc.conf +.It Pa /etc/rc.conf.local +.It Pa /etc/rc.d/ +.It Pa /etc/rc.firewall +.It Pa /etc/rc.local +.It Pa /etc/rc.shutdown +.It Pa /etc/rc.subr +.It Pa /var/run/dmesg.boot +.Xr dmesg 8 +results soon after the +.Nm +process begins. +Useful when +.Xr dmesg 8 +buffer in the kernel no longer has this information. +.El +.Sh EXAMPLES +The following is a minimal +.Nm rc.d/ +style script. +Most scripts require little more than the following. +.Bd -literal -offset indent +#!/bin/sh +# + +# PROVIDE: foo +# REQUIRE: bar_service_required_to_precede_foo + +\&. /etc/rc.subr + +name="foo" +rcvar=foo_enable +command="/usr/local/bin/foo" + +load_rc_config $name +run_rc_command "$1" +.Ed +.Pp +Certain scripts may want to provide enhanced functionality. +The user may access this functionality through additional commands. +The script may list and define as many commands at it needs. +.Bd -literal -offset indent +#!/bin/sh +# + +# PROVIDE: foo +# REQUIRE: bar_service_required_to_precede_foo +# BEFORE: baz_service_requiring_foo_to_precede_it + +\&. /etc/rc.subr + +name="foo" +rcvar=foo_enable +command="/usr/local/bin/foo" +extra_commands="nop hello" +hello_cmd="echo Hello World." +nop_cmd="do_nop" + +do_nop() +{ + echo "I do nothing." +} + +load_rc_config $name +run_rc_command "$1" +.Ed +.Pp +As all processes are killed by +.Xr init 8 +at shutdown, the explicit +.Xr kill 1 +is unnecessary, but is often included. +.Sh SEE ALSO +.Xr kill 1 , +.Xr rc.conf 5 , +.Xr init 8 , +.Xr rc.resume 8 , +.Xr rc.subr 8 , +.Xr rcorder 8 , +.Xr reboot 8 , +.Xr savecore 8 , +.Xr service 8 , +.Xr sysrc 8 +.Pp +.Rs +.%T Practical rc.d scripting in BSD +.%U +.Re +.Sh HISTORY +The +.Nm +utility appeared in +.Bx 4.0 . diff --git a/static/freebsd/man8/rc.subr.8 b/static/freebsd/man8/rc.subr.8 new file mode 100644 index 00000000..45a9e9a6 --- /dev/null +++ b/static/freebsd/man8/rc.subr.8 @@ -0,0 +1,1186 @@ +.\" $NetBSD: rc.subr.8,v 1.12 2004/01/06 00:52:24 lukem Exp $ +.\" +.\" Copyright (c) 2002-2004 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Luke Mewburn. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 October 23, 2024 +.Dt RC.SUBR 8 +.Os +.Sh NAME +.Nm rc.subr +.Nd functions used by system shell scripts +.Sh SYNOPSIS +.Bl -item -compact +.It +.Ic .\& Pa /etc/rc.subr +.Pp +.It +.Ic backup_file Ar action Ar file Ar current Ar backup +.It +.Ic checkyesno Ar var +.It +.Ic check_pidfile Ar pidfile Ar procname Op Ar interpreter +.It +.Ic check_process Ar procname Op Ar interpreter +.It +.Ic DebugOn Ar tag ... +.It +.Ic DebugOff Ar tag ... +.It +.Ic debug Ar message +.It +.Ic dot Ar file ... +.It +.Ic err Ar exitval Ar message +.It +.Ic force_depend Ar name +.It +.Ic info Ar message +.It +.Ic is_verified Ar file +.It +.Ic load_kld Oo Fl e Ar regex Oc Oo Fl m Ar module Oc Ar file +.It +.Ic load_rc_config Oo Ar flag Oc Op Ar service +.It +.Ic load_rc_config_var Ar name Ar var +.It +.Ic mount_critical_filesystems Ar type +.It +.Ic rc_log Ar message +.It +.Ic rc_trace Ar level Ar message +.It +.Ic rc_usage Ar command ... +.It +.Ic reverse_list Ar item ... +.It +.Ic run_rc_command Ar argument +.It +.Ic run_rc_script Ar file Ar argument +.It +.Ic run_rc_scripts Oo options Oc Ar file ... +.It +.Ic safe_dot Ar file ... +.It +.Ic sdot Ar file ... +.It +.Ic startmsg Oo Fl n Oc Ar message +.It +.Ic vdot Ar file ... +.It +.Ic wait_for_pids Op Ar pid ... +.It +.Ic warn Ar message +.El +.Sh DESCRIPTION +The +.Nm +script +contains commonly used shell script functions and variable +definitions which are used by various scripts such as +.Xr rc 8 . +Scripts required by ports in +.Pa /usr/local/etc/rc.d +will also eventually +be rewritten to make use of it. +.Pp +The +.Nm +functions were mostly imported from +.Nx . +.Pp +They are accessed by sourcing +.Pa /etc/rc.subr +into the current shell. +.Pp +The following shell functions are available: +.Bl -tag -width 4n +.It Ic backup_file Ar action file current backup +Make a backup copy of +.Ar file +into +.Ar current . +Save the previous version of +.Ar current +as +.Ar backup . +.Pp +The +.Ar action +argument +may be one of the following: +.Bl -tag -width "remove" +.It Cm add +.Ar file +is now being backed up by or possibly re-entered into this backup mechanism. +.Ar current +is created. +.It Cm update +.Ar file +has changed and needs to be backed up. +If +.Ar current +exists, it is copied to +.Ar backup +and then +.Ar file +is copied to +.Ar current . +.It Cm remove +.Ar file +is no longer being tracked by this backup mechanism. +.Ar current +is moved to +.Ar backup . +.El +.It Ic checkyesno Ar var +Return 0 if +.Ar var +is defined to +.Dq Li YES , +.Dq Li TRUE , +.Dq Li ON , +or +.Ql 1 . +Return 1 if +.Ar var +is defined to +.Dq Li NO , +.Dq Li FALSE , +.Dq Li OFF , +or +.Ql 0 . +Otherwise, warn that +.Ar var +is not set correctly. +The values are case insensitive. +.Em Note : +.Ar var +should be a variable name, not its value; +.Ic checkyesno +will expand the variable by itself. +.It Ic check_pidfile Ar pidfile procname Op Ar interpreter +Parses the first word of the first line of +.Ar pidfile +for a PID, and ensures that the process with that PID +is running and its first argument matches +.Ar procname . +Prints the matching PID if successful, otherwise nothing. +If +.Ar interpreter +is provided, parse the first line of +.Ar procname , +ensure that the line is of the form: +.Pp +.Dl "#! interpreter [...]" +.Pp +and use +.Ar interpreter +with its optional arguments and +.Ar procname +appended as the process string to search for. +.It Ic check_process Ar procname Op Ar interpreter +Prints the PIDs of any processes that are running with a first +argument that matches +.Ar procname . +.Ar interpreter +is handled as per +.Ic check_pidfile . +.It Ic DebugOn Ar tag ... +Enable tracing if not already enabled, +and any +.Ar tag +is found in +.Va DEBUG_SH +(a comma separated list of tags). +.Pp +Record the +.Ar tag +that caused it to be enabled in +.Va DEBUG_ON , +set +.Va DEBUG_DO +empty and +.Va DEBUG_SKIP +to +.Ql \&: . +.Pp +See +.Xr debug.sh 8 +for more details. +.It Ic DebugOff Ar tag ... +Disable tracing if enabled and any +.Ar tag +matches +.Va DEBUG_ON , +which means it was the reason tracing was enabled. +.Pp +Set +.Va DEBUG_DO +to +.Ql \&: , +and +.Va DEBUG_ON , +.Va DEBUG_SKIP +empty. +.It Ic debug Ar message +Display a debugging message to +.Va stderr , +log it to the system log using +.Xr logger 1 , +and +return to the caller. +The error message consists of the script name +(from +.Va $0 ) , +followed by +.Dq Li ": DEBUG: " , +and then +.Ar message . +This function is intended to be used by developers +as an aid to debugging scripts. +It can be turned on or off +by the +.Xr rc.conf 5 +variable +.Va rc_debug . +.It Ic dot Ar file ... +For reading in unverified files. +.Pp +Ensure shell +.Li verify +option is off. +This option is only meaningful when +.Xr mac_veriexec 4 +is active. +.Pp +Read each +.Ar file +if it exists. +.Pp +Restore previous state of the +.Li verify +option. +.It Ic err Ar exitval message +Display an error message to +.Va stderr , +log it to the system log +using +.Xr logger 1 , +and +.Ic exit +with an exit value of +.Ar exitval . +The error message consists of the script name +(from +.Va $0 ) , +followed by +.Dq Li ": ERROR: " , +and then +.Ar message . +.It Ic force_depend Ar name +Output an advisory message and force the +.Ar name +service to start. +The +.Ar name +argument is the +.Xr basename 1 +component of the path to the script located at +.Pa /etc/rc.d +(scripts stored in other locations such as +.Pa /usr/local/etc/rc.d +cannot be controlled with +.Ic force_depend +currently). +If the script fails for any reason it will output a warning +and return with a return value of 1. +If it was successful +it will return 0. +.It Ic is_verified Ar file +If +.Xr veriexec 8 +does not exist, or +.Xr mac_veriexec 4 +is not active, just return success. +Otherwise use +.Xr veriexec 8 +to check if +.Ar file +is verified. +If not verified the return code will be 80 (EAUTH). +.It Ic info Ar message +Display an informational message to +.Va stdout , +and log it to the system log using +.Xr logger 1 . +The message consists of the script name +(from +.Va $0 ) , +followed by +.Dq Li ": INFO: " , +and then +.Ar message . +The display of this informational output can be +turned on or off by the +.Xr rc.conf 5 +variable +.Va rc_info . +.It Ic load_kld Oo Fl e Ar regex Oc Oo Fl m Ar module Oc Ar file +Load +.Ar file +as a kernel module unless it is already loaded. +For the purpose of checking the module status, +either the exact module name can be specified using +.Fl m , +or an +.Xr egrep 1 +regular expression matching the module name can be supplied via +.Fl e . +By default, the module is assumed to have the same name as +.Ar file , +which is not always the case. +.It Ic load_rc_config Oo Ar flag Oc Op Ar service +Source in the configuration file(s) for +.Ar service . +If no +.Ar service +is specified, +only the global configuration file(s) will be loaded. +First, +.Pa /etc/rc.conf +is sourced if it has not yet been read in. +Then, +.Pa /etc/rc.conf.d/ Ns Ar service +is sourced if it is an existing file. +The latter may also contain other variable assignments to override +.Ic run_rc_command +arguments defined by the calling script, to provide an easy +mechanism for an administrator to override the behaviour of a given +.Xr rc.d 8 +script without requiring the editing of that script. +.Pp +The function named by +.Va load_rc_config_reader +(default is +.Ic dot ) +is used to read configuration unless +.Ar flag +is: +.Bl -tag -width Ds +.It Fl s +use +.Ic sdot +to read configuration, +because we want verified configuration or +to use +.Ic safe_dot +to read an unverified configuration. +.It Fl v +use +.Ic vdot +to read in configuration only if it is verified. +.El +.Pp +.Ic DebugOn +will be called with tags derived from +.Ar name +to enable tracing if any appear in +.Va DEBUG_SH . +.It Ic load_rc_config_var Ar name Ar var +Read the +.Xr rc.conf 5 +variable +.Ar var +for +.Ar name +and set in the current shell, using +.Ic load_rc_config +in a sub-shell to prevent unwanted side effects from other variable +assignments. +.It Ic mount_critical_filesystems Ar type +Go through a list of critical file systems, +as found in the +.Xr rc.conf 5 +variable +.Va critical_filesystems_ Ns Ar type , +mounting each one that +is not currently mounted. +.It Ic rc_log Ar message +Output +.Ar message +with a timestamp, which is both human readable and +easily parsed for post processing, using: +.Bd -literal -offset indent +date "+@ %s [%Y-%m-%d %H:%M:%S %Z] $*" +.Ed +.It Ic rc_trace Ar level Ar message +If the file +.Pa /etc/rc.conf.d/rc_trace +exists and is not empty attempt to set +.Va RC_LEVEL +based on its content. +If the file is empty or does not contain +a value for +.Va RC_LEVEL , +set it to +.Li 0 . +.Pp +If +.Ar level +is greater than or equal to +.Va RC_LEVEL +pass +.Ar message +to +.Ic rc_log . +.It Ic rc_usage Ar command ... +Print a usage message for +.Va $0 , +with +.Ar commands +being the list of valid arguments +prefixed by +.Sm off +.Dq Bq Li fast | force | one | quiet . +.Sm on +.It Ic reverse_list Ar item ... +Print the list of +.Ar items +in reverse order. +.It Ic run_rc_command Ar argument +Run the +.Ar argument +method for the current +.Xr rc.d 8 +script, based on the settings of various shell variables. +.Ic run_rc_command +is extremely flexible, and allows fully functional +.Xr rc.d 8 +scripts to be implemented in a small amount of shell code. +.Pp +.Ar argument +is searched for in the list of supported commands, which may be one +of: +.Bl -tag -width "restart" -offset indent +.It Cm start +Start the service. +This should check that the service is to be started as specified by +.Xr rc.conf 5 . +Also checks if the service is already running and refuses to start if +it is. +This latter check is not performed by standard +.Fx +scripts if the system is starting directly to multi-user mode, to +speed up the boot process. +.It Cm stop +If the service is to be started as specified by +.Xr rc.conf 5 , +stop the service. +This should check that the service is running and complain if it is not. +.It Cm restart +Perform a +.Cm stop +then a +.Cm start . +Defaults to displaying the process ID of the program (if running). +.It Cm enabled +Return 0 if the service is enabled and 1 if it is not. +This command does not print anything. +.It Cm rcvar +Display which +.Xr rc.conf 5 +variables are used to control the startup of the service (if any). +.El +.Pp +If +.Va pidfile +or +.Va procname +is set, also support: +.Bl -tag -width "status" -offset indent +.It Cm poll +Wait for the command to exit. +.It Cm status +Show the status of the process. +.El +.Pp +Other supported commands are listed in the optional variable +.Va extra_commands . +.Pp +.Ar argument +may have one of the following prefixes which alters its operation: +.Bl -tag -width "force" -offset indent +.It Li fast +Skip the check for an existing running process, +and sets +.Va rc_fast Ns = Ns Li YES . +.It Li force +Skip the checks for +.Va rcvar +being set to +.Dq Li YES , +and sets +.Va rc_force Ns = Ns Li YES . +This ignores +.Ar argument Ns Va _precmd +returning non-zero, and ignores any of the +.Va required_* +tests failing, and always returns a zero exit status. +.It Li one +Skip the checks for +.Va rcvar +being set to +.Dq Li YES , +but performs all the other prerequisite tests. +.It Li quiet +Inhibits some verbose diagnostics. +Currently, this includes messages +.Qq Starting ${name} +(as checked by +.Ic check_startmsgs +inside +.Nm ) +and errors about usage of services that are not enabled in +.Xr rc.conf 5 . +This prefix also sets +.Va rc_quiet Ns = Ns Li YES . +.Em Note : +.Va rc_quiet +is not intended to completely mask all debug and warning messages, +but only certain small classes of them. +.El +.Pp +.Ic run_rc_command +uses the following shell variables to control its behaviour. +Unless otherwise stated, these are optional. +.Bl -tag -width "procname" -offset indent +.It Va name +The name of this script. +This is not optional. +.It Va rcvar +The value of +.Va rcvar +is checked with +.Ic checkyesno +to determine if this method should be run. +.It Va command +Full path to the command. +Not required if +.Ar argument Ns Va _cmd +is defined for each supported keyword. +Can be overridden by +.Va ${name}_program . +.It Va command_args +Optional arguments and/or shell directives for +.Va command . +.It Va command_interpreter +.Va command +is started with: +.Pp +.Dl "#! command_interpreter [...]" +.Pp +which results in its +.Xr ps 1 +command being: +.Pp +.Dl "command_interpreter [...] command" +.Pp +so use that string to find the PID(s) of the running command +rather than +.Va command . +.It Va extra_commands +Extra commands/keywords/arguments supported. +.It Va pidfile +Path to PID file. +Used to determine the PID(s) of the running command. +If +.Va pidfile +is set, use: +.Pp +.Dl "check_pidfile $pidfile $procname" +.Pp +to find the PID. +Otherwise, if +.Va command +is set, use: +.Pp +.Dl "check_process $procname" +.Pp +to find the PID. +.It Va procname +Process name to check for. +Defaults to the value of +.Va command . +.It Va required_dirs +Check for the existence of the listed directories +before running the +.Cm start +method. +The list is checked before running +.Va start_precmd . +.It Va required_files +Check for the readability of the listed files +before running the +.Cm start +method. +The list is checked before running +.Va start_precmd . +.It Va required_modules +Ensure that the listed kernel modules are loaded +before running the +.Cm start +method. +The list is checked after running +.Va start_precmd . +This is done after invoking the commands from +.Va start_precmd +so that the missing modules are not loaded in vain +if the preliminary commands indicate a error condition. +A word in the list can have an optional +.Dq Li \&: Ns Ar modname +or +.Dq Li ~ Ns Ar pattern +suffix. +The +.Ar modname +or +.Ar pattern +parameter is passed to +.Ic load_kld +through a +.Fl m +or +.Fl e +option, respectively. +See the description of +.Ic load_kld +in this document for details. +.It Va required_vars +Perform +.Ic checkyesno +on each of the list variables +before running the +.Cm start +method. +The list is checked after running +.Va start_precmd . +.It Va ${name}_chdir +Directory to +.Ic cd +to before running +.Va command , +if +.Va ${name}_chroot +is not provided. +.It Va ${name}_chroot +Directory to +.Xr chroot 8 +to before running +.Va command . +Only supported after +.Pa /usr +is mounted. +.It Va ${name}_env +A list of environment variables to run +.Va command +with. +Those variables will be passed as arguments to the +.Xr env 1 +utility unless +.Ar argument Ns Va _cmd +is defined. +In that case the contents of +.Va ${name}_env +will be exported via the +.Xr export 1 +builtin of +.Xr sh 1 , +which puts some limitations on the names of variables +(e.g., a variable name may not start with a digit). +.It Va ${name}_env_file +A file to source for environmental variables to run +.Va command +with. +.Em Note : +all the variables which are being assigned in this file are going +to be exported into the environment of +.Va command . +.It Va ${name}_fib +FIB +.Pa Routing Table +number to run +.Va command +with. +See +.Xr setfib 1 +for more details. +.It Va ${name}_flags +Arguments to call +.Va command +with. +This is usually set in +.Xr rc.conf 5 , +and not in the +.Xr rc.d 8 +script. +The environment variable +.Sq Ev flags +can be used to override this. +.It Va ${name}_nice +.Xr nice 1 +level to run +.Va command +as. +Only supported after +.Pa /usr +is mounted. +.It Va ${name}_limits +Resource limits to apply to +.Va command . +This will be passed as arguments to the +.Xr limits 1 +utility. +By default, the resource limits are based on the login class defined in +.Va ${name}_login_class . +.It Va ${name}_login_class +Login class to use with +.Va ${name}_limits . +Defaults to +.Dq Li daemon . +.It Va ${name}_offcmd +Shell commands to run during start if a service is not enabled. +.It Va ${name}_oomprotect +.Xr protect 1 +.Va command +from being killed when swap space is exhausted. +If +.Dq Li YES +is used, no child processes are protected. +If +.Dq Li ALL , +protect all child processes. +.It Va ${name}_program +Full path to the command. +Overrides +.Va command +if both are set, but has no effect if +.Va command +is unset. +As a rule, +.Va command +should be set in the script while +.Va ${name}_program +should be set in +.Xr rc.conf 5 . +.It Va ${name}_user +User to run +.Va command +as, using +.Xr chroot 8 +if +.Va ${name}_chroot +is set, otherwise +uses +.Xr su 1 . +Only supported after +.Pa /usr +is mounted. +.It Va ${name}_group +Group to run the chrooted +.Va command +as. +.It Va ${name}_groups +Comma separated list of supplementary groups to run the chrooted +.Va command +with. +.It Va ${name}_prepend +Commands to be prepended to +.Va command . +This is a generic version of +.Va ${name}_env , +.Va ${name}_fib , +or +.Va ${name}_nice . +.It Va ${name}_setup +Optional command to be run during +.Cm start , +.Cm restart , +and +.Cm reload +prior to the respective +.Ar argument Ns Va _precmd . +If the command fails for any reason it will output a warning, +but execution will continue. +.It Ar argument Ns Va _cmd +Shell commands which override the default method for +.Ar argument . +.It Ar argument Ns Va _precmd +Shell commands to run just before running +.Ar argument Ns Va _cmd +or the default method for +.Ar argument . +If this returns a non-zero exit code, the main method is not performed. +If the default method is being executed, this check is performed after +the +.Va required_* +checks and process (non-)existence checks. +.It Ar argument Ns Va _postcmd +Shell commands to run if running +.Ar argument Ns Va _cmd +or the default method for +.Ar argument +returned a zero exit code. +.It Va sig_stop +Signal to send the processes to stop in the default +.Cm stop +method. +Defaults to +.Dv SIGTERM . +.It Va sig_reload +Signal to send the processes to reload in the default +.Cm reload +method. +Defaults to +.Dv SIGHUP . +.El +.Pp +For a given method +.Ar argument , +if +.Ar argument Ns Va _cmd +is not defined, then a default method is provided by +.Ic run_rc_command : +.Bl -column "Argument" "Default Method" -offset indent +.It Sy Argument Ta Sy Default method +.It Cm start Ta +If +.Va command +is not running and +.Ic checkyesno Va rcvar +succeeds, start +.Va command . +.It Cm stop Ta +Determine the PIDs of +.Va command +with +.Ic check_pidfile +or +.Ic check_process +(as appropriate), +.Ic kill Va sig_stop +those PIDs, and run +.Ic wait_for_pids +on those PIDs. +.It Cm reload Ta +Similar to +.Cm stop , +except that it uses +.Va sig_reload +instead, and does not run +.Ic wait_for_pids . +Another difference from +.Cm stop +is that +.Cm reload +is not provided by default. +It can be enabled via +.Va extra_commands +if appropriate: +.Pp +.Dl "extra_commands=reload" +.It Cm restart Ta +Runs the +.Cm stop +method, then the +.Cm start +method. +.It Cm status Ta +Show the PID of +.Va command , +or some other script specific status operation. +.It Cm poll Ta +Wait for +.Va command +to exit. +.It Cm rcvar Ta +Display which +.Xr rc.conf 5 +variable is used (if any). +This method always works, even if the appropriate +.Xr rc.conf 5 +variable is set to +.Dq Li NO . +.El +.Pp +The following variables are available to the methods +(such as +.Ar argument Ns Va _cmd ) +as well as after +.Ic run_rc_command +has completed: +.Bl -tag -width "rc_service" -offset indent +.It Va rc_arg +Argument provided to +.Ic run_rc_command , +after fast and force processing has been performed. +.It Va rc_flags +Flags to start the default command with. +Defaults to +.Va ${name}_flags , +unless overridden by the environment variable +.Sq Ev flags . +This variable may be changed by the +.Ar argument Ns Va _precmd +method. +.It Va rc_service +Path to the service script being executed, in case it needs to re-invoke itself. +.It Va rc_pid +PID of +.Va command +(if appropriate). +.It Va rc_fast +Not empty if +.Dq Li fast +prefix was used. +.It Va rc_force +Not empty if +.Dq Li force +prefix was used. +.El +.It Ic run_rc_script Ar file argument +Start the script +.Ar file +with an argument of +.Ar argument , +and handle the return value from the script. +.Pp +Various shell variables are unset before +.Ar file +is started: +.Bd -ragged -offset indent +.Va name , +.Va command , +.Va command_args , +.Va command_interpreter , +.Va extra_commands , +.Va pidfile , +.Va rcvar , +.Va required_dirs , +.Va required_files , +.Va required_vars , +.Ar argument Ns Va _cmd , +.Ar argument Ns Va _precmd . +.Ar argument Ns Va _postcmd . +.Ed +.Pp +Call +.Ic rc_trace +to indicate that +.Ar file +is to be run. +.Pp +However, if +.Ic is_verified Ar file +fails, just return. +.Pp +.Ic DebugOn +will be called with tags derived from +.Va name +and +.Va rc_arg +to enable tracing if any of those tags appear in +.Va DEBUG_SH . +.Pp +.Ic run_rc_script +executes +.Ar file +unless: +.Bl -enum +.It +.Ar file +ends in +.Pa .sh +and lives in +.Pa /etc/rc.d . +.It +.Ar file +appears to be a backup or scratch file +.Po e.g., with a suffix of +.Pa ~ , # , .OLD , ,v , +or +.Pa .orig Pc . +.It +.Ar file +is not executable. +.El +.It Ic run_rc_scripts Oo options Oc file ... +Call +.Ic run_rc_script +for each +.Ar file , +unless it is already recorded as having been run. +.Pp +The +.Ar options +are: +.Bl -tag -width "--break break" +.It Ic --arg Ar arg +Pass +.Ar arg +to +.Ic run_rc_script , +default is +.Ar _boot +set by +.Xr rc 8 . +.It Ic --break Ar break +Stop processing if any +.Ar file +matches any +.Ar break +.El +.It Ic safe_dot Ar file ... +Used by +.Ic sdot +when +.Xr mac_veriexec 4 +is active and +.Ar file +is not verified. +.Pp +This function limits the input from +.Ar file +to simple variable assignments with any +non-alphanumeric characters replaced with +.Ql _ . +.It Ic sdot Ar file ... +For reading in configuration files. +Skip files that do not exist or are empty. +Try using +.Ic vdot +and if that fails (the file is unverified) +fall back to using +.Ic safe_dot . +.It Ic startmsg Oo Fl n Oc Ar message +Display a start message to +.Va stdout . +It should be used instead of +.Xr echo 1 . +The display of this output can be turned off if the +.Xr rc.conf 5 +variable +.Va rc_startmsgs +is set to +.Dq Li NO . +.It Ic stop_boot Op Ar always +Prevent booting to multiuser mode. +If the +.Va autoboot +variable is set to +.Ql yes +(see +.Xr rc 8 +to learn more about +.Va autoboot ) , +or +.Ic checkyesno Ar always +indicates a truth value, then a +.Dv SIGTERM +signal is sent to the parent +process, which is assumed to be +.Xr rc 8 . +Otherwise, the shell exits with a non-zero status. +.It Ic vdot Ar file ... +For reading in only verified files. +.Pp +Ensure shell +.Li verify +option is on. +This option is only meaningful when +.Xr mac_veriexec 4 +is active, +otherwise this function is effectively the same as +.Ic dot . +.Pp +Read in each +.Ar file +if it exists and +.Ic is_verfied Ar file +is successful, otherwise set return code to 80 (EAUTH). +.Pp +Restore previous state of the +.Li verify +option. +.It Ic wait_for_pids Op Ar pid ... +Wait until all of the provided +.Ar pids +do not exist any more, printing the list of outstanding +.Ar pids +every two seconds. +.It Ic warn Ar message +Display a warning message to +.Va stderr +and log it to the system log +using +.Xr logger 1 . +The warning message consists of the script name +(from +.Va $0 ) , +followed by +.Dq Li ": WARNING: " , +and then +.Ar message . +.El +.Sh FILES +.Bl -tag -width "/etc/rc.subr" -compact +.It Pa /etc/rc.subr +The +.Nm +file resides in +.Pa /etc . +.El +.Sh SEE ALSO +.Xr rc.conf 5 , +.Xr debug.sh 8 , +.Xr rc 8 +.Sh HISTORY +The +.Nm +script +appeared in +.Nx 1.3 . +The +.Xr rc.d 8 +support functions appeared in +.Nx 1.5 . +The +.Nm +script +first appeared in +.Fx 5.0 . diff --git a/static/freebsd/man8/rescue.8 b/static/freebsd/man8/rescue.8 new file mode 100644 index 00000000..3e14230a --- /dev/null +++ b/static/freebsd/man8/rescue.8 @@ -0,0 +1,178 @@ +.\" Copyright (c) 2003 Tim Kientzle +.\" Copyright (c) 2003 Simon L. Nielsen +.\" 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 ``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 June 30, 2022 +.Dt RESCUE 8 +.Os +.Sh NAME +.Nm rescue +.Nd rescue utilities in +.Pa /rescue +.Sh DESCRIPTION +The +.Pa /rescue +directory contains a collection of common utilities intended for use +in recovering a badly damaged system. +With the transition to a dynamically-linked root beginning with +.Fx 5.2 , +there is a real possibility that the standard tools in +.Pa /bin +and +.Pa /sbin +may become non-functional due to a failed upgrade or a disk error. +The tools in +.Pa /rescue +are statically linked and should therefore be more resistant to +damage. +However, being statically linked, the tools in +.Pa /rescue +are also less functional than the standard utilities. +In particular, they do not have full use of the locale, +.Xr pam 3 , +and nsswitch libraries. +.Pp +If your system fails to boot, and it shows a prompt similar to: +.Pp +.Dl "Enter full pathname of shell or RETURN for /bin/sh: " +.Pp +the first thing to try running is the standard shell, +.Pa /bin/sh . +If that fails, try running +.Pa /rescue/sh , +which is the +.Nm +shell. +To repair the system, the root partition must first be remounted +read-write. +This can be done with the following +.Xr mount 8 +command: +.Pp +.Dl "/rescue/mount -uw /" +.Pp +The next step is to double-check the contents of +.Pa /bin , /sbin , +and +.Pa /usr/lib , +possibly mounting a +.Fx +rescue or +.Dq "live file system" +CD-ROM and copying files from there. +Once it is possible to successfully run +.Pa /bin/sh , /bin/ls , +and other standard utilities, try rebooting back into the standard +system. +.Pp +The +.Pa /rescue +tools are compiled using +.Xr crunchgen 1 , +which makes them considerably more compact than the standard +utilities. +To build a +.Fx +system where space is critical, +.Pa /rescue +can be used as a replacement for the standard +.Pa /bin +and +.Pa /sbin +directories; simply change +.Pa /bin +and +.Pa /sbin +to be symbolic links pointing to +.Pa /rescue . +Since +.Pa /rescue +is statically linked, it should also be possible to dispense with much +of +.Pa /usr/lib +in such an environment. +.Pp +In contrast to its predecessor +.Pa /stand , +.Pa /rescue +is updated during normal +.Fx +source and binary upgrades. +.Sh FILES +.Bl -tag -width ".Pa /rescue" -compact +.It Pa /rescue +Root of the +.Nm +hierarchy. +.El +.Sh SEE ALSO +.Xr crunchgen 1 , +.Xr crash 8 +.Sh HISTORY +The +.Nm +utilities first appeared in +.Fx 5.2 . +.Sh AUTHORS +.An -nosplit +The +.Nm +system was written by +.An Tim Kientzle Aq Mt kientzle@FreeBSD.org , +based on ideas taken from +.Nx . +This manual page was written by +.An Simon L. Nielsen Aq Mt simon@FreeBSD.org , +based on text by +.An Tim Kientzle Aq Mt kientzle@FreeBSD.org . +.Sh BUGS +Most of the +.Nm +tools work even in a fairly crippled system. +The most egregious exception is the +.Nm +version of +.Xr vi 1 , +which currently requires that +.Pa /usr +be mounted so that it can access the +.Xr termcap 5 +files. +Hopefully, a failsafe +.Xr termcap 3 +entry will eventually be added into the +.Xr ncurses 3 +library, so that +.Pa /rescue/vi +can be used even in a system where +.Pa /usr +cannot immediately be mounted. +In the meantime, the +.Nm +version of the +.Xr ed 1 +editor can be used from +.Pa /rescue/ed +if you need to edit files, but cannot mount +.Pa /usr . diff --git a/static/freebsd/man8/uefi.8 b/static/freebsd/man8/uefi.8 new file mode 100644 index 00000000..e29bed13 --- /dev/null +++ b/static/freebsd/man8/uefi.8 @@ -0,0 +1,134 @@ +.\" Copyright (c) 2014 The FreeBSD Foundation +.\" +.\" 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 AUTHORS 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 AUTHORS 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 August 31, 2023 +.Dt UEFI 8 +.Os +.Sh NAME +.Nm UEFI +.Nd Unified Extensible Firmware Interface bootstrapping procedures +.Sh DESCRIPTION +The +.Nm +Unified Extensible Firmware Interface provides boot- and run-time services +to operating systems. +.Nm +is a replacement for the legacy BIOS on the i386 and amd64 CPU architectures, +and is also used on arm, arm64 and riscv architectures. +.Pp +The UEFI specification is the successor to the Extensible Firmware Interface +(EFI) specification. +The terms UEFI and EFI are often used interchangeably. +.Pp +The +.Nm +boot process loads system bootstrap code located in an EFI System Partition +(ESP). +The ESP is a GPT or MBR partition with a specific identifier that contains an +.Xr msdosfs 4 +FAT file system with a specified file hierarchy. +.Bl -column -offset indent "Partition Scheme" "ESP Identifier" +.It Sy "Partition Scheme" Ta Sy "ESP Identifier" +.It GPT Ta C12A7328-F81F-11D2-BA4B-00A0C93EC93B +.It MBR Ta 0xEF +.El +.Pp +The +.Nm +boot process proceeds as follows: +.Bl -enum -offset indent -compact +.It +.Nm +firmware runs at power up and searches for an OS loader in the EFI system +partition. +The path to the loader may be set by an EFI environment variable managed by +.Xr efibootmgr 8 . +If not set, an architecture-specific default is used. +.Bl -column -offset indent "Architecture" "Default Path" +.It Sy Architecture Ta Sy Default Path +.It amd64 Ta Pa /EFI/BOOT/BOOTX64.EFI +.It arm Ta Pa /EFI/BOOT/BOOTARM.EFI +.It arm64 Ta Pa /EFI/BOOT/BOOTAA64.EFI +.It i386 Ta Pa /EFI/BOOT/BOOTIA32.EFI +.It riscv Ta Pa /EFI/BOOT/BOOTRISCV64.EFI +.El +.Pp +The default +.Nm +boot configuration for +.Fx +installs +.Pa loader.efi +in the default path. +.It +.Pa loader.efi +reads boot configuration from +.Pa /boot.config +or +.Pa /boot/config . +.It +.Pa loader.efi +loads and boots the kernel, as described in +.Xr loader.efi 8 . +.El +.Pp +The +.Xr vt 4 +system console is automatically selected when booting via +.Nm . +.Sh FILES +.Bl -tag -width /boot/loader -compact +.Nm +bootstrap +.It Pa /boot/loader.efi +Final stage bootstrap +.It Pa /boot/kernel/kernel +Default kernel +.It Pa /boot/kernel.old/kernel +Typical non-default kernel (optional) +.El +.Sh SEE ALSO +.Xr msdosfs 4 , +.Xr vt 4 , +.Xr boot.config 5 , +.Xr boot 8 , +.Xr efibootmgr 8 , +.Xr efidp 8 , +.Xr efivar 8 , +.Xr gpart 8 , +.Xr loader.efi 8 , +.Xr uefisign 8 +.Sh HISTORY +EFI boot support for the ia64 architecture first appeared in +.Fx 5.0 . +.Nm +boot support for amd64 first appeared in +.Fx 10.1 ; +for arm64 in +.Fx 11.0 ; +for armv7 in +.Fx 12.0 ; +and for riscv in +.Fx 13.0 . +.Sh BUGS +There is no support for 32-bit i386 booting via UEFI. diff --git a/static/freebsd/man8/yp.8 b/static/freebsd/man8/yp.8 new file mode 100644 index 00000000..1663d4da --- /dev/null +++ b/static/freebsd/man8/yp.8 @@ -0,0 +1,588 @@ +.\" Copyright (c) 1992/3 Theo de Raadt +.\" 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. 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 December 14, 2011 +.Dt YP 8 +.Os +.Sh NAME +.Nm yp +.Nd description of the YP/NIS system +.Sh SYNOPSIS +.Nm +.Sh DESCRIPTION +The +.Nm YP +subsystem allows network management of passwd, group, netgroup, hosts, +services, rpc, bootparams and ethers file +entries through the functions +.Xr getpwent 3 , +.Xr getgrent 3 , +.Xr getnetgrent 3 , +.Xr gethostent 3 , +.Xr getnetent 3 , +.Xr getrpcent 3 , +and +.Xr ethers 3 . +The +.Xr bootparamd 8 +daemon makes direct +.Tn NIS +library calls since there are no +functions in the standard C library for reading bootparams. +.Tn NIS +support is enabled in +.Xr nsswitch.conf 5 . +.Pp +The +.Nm YP +subsystem is started automatically in +.Pa /etc/rc +if it has been initialized in +.Pa /etc/rc.conf +and if the directory +.Pa /var/yp +exists (which it does in the default distribution). +The default +.Tn NIS +domain must also be set with the +.Xr domainname 1 +command, which will happen automatically at system startup if it is +specified in +.Pa /etc/rc.conf . +.Pp +.Tn NIS +is an +.Tn RPC Ns -based +client/server system that allows a group of +machines within an +.Tn NIS +domain to share a common set of configuration files. +This permits a system +administrator to set up +.Tn NIS +client systems with only minimal configuration +data and add, remove or modify configuration data from a single location. +.Pp +The canonical copies of all +.Tn NIS +information are stored on a single machine +called the +.Tn NIS +.Em "master server" . +The databases used to store the information are called +.Tn NIS +.Em maps . +In +.Fx , +these maps are stored in +.Pa /var/yp/ Ns Aq Ar domainname +where +.Aq Ar domainname +is the name of the +.Tn NIS +domain being served. +A single +.Tn NIS +server can +support several domains at once, therefore it is possible to have several +such directories, one for each supported domain. +Each domain will have +its own independent set of maps. +.Pp +In +.Fx , +the +.Tn NIS +maps are Berkeley DB hashed database files (the +same format used for the +.Xr passwd 5 +database files). +Other operating systems that support +.Tn NIS +use old-style +.Nm ndbm +databases instead (largely because Sun Microsystems originally based +their +.Tn NIS +implementation on +.Nm ndbm , +and other vendors have simply licensed +Sun's code rather than design their own implementation with a different +database format). +On these systems, the databases are generally split +into +.Pa .dir +and +.Pa .pag +files which the +.Nm ndbm +code uses to hold separate parts of the hash +database. +The Berkeley DB hash method instead uses a single file for +both pieces of information. +This means that while you may have +.Pa passwd.byname.dir +and +.Pa passwd.byname.pag +files on other operating systems (both of which are really parts of the +same map), +.Fx +will have only one file called +.Pa passwd.byname . +The difference in format is not significant: only the +.Tn NIS +server, +.Xr ypserv 8 , +and related tools need to know the database format of the +.Tn NIS +maps. +Client +.Tn NIS +systems receive all +.Tn NIS +data in +.Tn ASCII +form. +.Pp +There are three main types of +.Tn NIS +systems: +.Bl -enum +.It +.Tn NIS +clients, +which query +.Tn NIS +servers for information. +.It +.Tn NIS +master servers, +which maintain the canonical copies of all +.Tn NIS +maps. +.It +.Tn NIS +slave servers, +which maintain backup copies of +.Tn NIS +maps that are periodically +updated by the master. +.El +.Pp +A +.Tn NIS +client establishes what is called a +.Em binding +to a particular +.Tn NIS +server using the +.Xr ypbind 8 +daemon. +The +.Xr ypbind 8 +utility checks the system's default domain (as set by the +.Xr domainname 1 +command) and begins broadcasting +.Tn RPC +requests on the local network. +These requests specify the name of the domain for which +.Xr ypbind 8 +is attempting to establish a binding. +If a server that has been +configured to serve the requested domain receives one of the broadcasts, +it will respond to +.Xr ypbind 8 , +which will record the server's address. +If there are several servers +available (a master and several slaves, for example), +.Xr ypbind 8 +will use the address of the first one to respond. +From that point +on, the client system will direct all of its +.Tn NIS +requests to that server. +The +.Xr ypbind 8 +utility will occasionally +.Dq ping +the server to make sure it is still up +and running. +If it fails to receive a reply to one of its pings +within a reasonable amount of time, +.Xr ypbind 8 +will mark the domain as unbound and begin broadcasting again in the +hopes of locating another server. +.Pp +.Tn NIS +master and slave servers handle all +.Tn NIS +requests with the +.Xr ypserv 8 +daemon. +The +.Xr ypserv 8 +utility is responsible for receiving incoming requests from +.Tn NIS +clients, +translating the requested domain and map name to a path to the +corresponding database file and transmitting data from the database +back to the client. +There is a specific set of requests that +.Xr ypserv 8 +is designed to handle, most of which are implemented as functions +within the standard C library: +.Bl -tag -width ".Fn yp_master" +.It Fn yp_order +check the creation date of a particular map +.It Fn yp_master +obtain the name of the +.Tn NIS +master server for a given +map/domain +.It Fn yp_match +lookup the data corresponding to a given in key in a particular +map/domain +.It Fn yp_first +obtain the first key/data pair in a particular map/domain +.It Fn yp_next +pass +.Xr ypserv 8 +a key in a particular map/domain and have it return the +key/data pair immediately following it (the functions +.Fn yp_first +and +.Fn yp_next +can be used to do a sequential search of an +.Tn NIS +map) +.It Fn yp_all +retrieve the entire contents of a map +.El +.Pp +There are a few other requests which +.Xr ypserv 8 +is capable of handling (i.e., acknowledge whether or not you can handle +a particular domain +.Pq Dv YPPROC_DOMAIN , +or acknowledge only if you can handle the domain and be silent otherwise +.Pq Dv YPPROC_DOMAIN_NONACK ) +but +these requests are usually generated only by +.Xr ypbind 8 +and are not meant to be used by standard utilities. +.Pp +On networks with a large number of hosts, it is often a good idea to +use a master server and several slaves rather than just a single master +server. +A slave server provides the exact same information as a master +server: whenever the maps on the master server are updated, the new +data should be propagated to the slave systems using the +.Xr yppush 8 +command. +The +.Tn NIS +.Pa Makefile +.Pq Pa /var/yp/Makefile +will do this automatically if the administrator creates +.Pa /var/yp/Makefile.local +and empties the +.Va NOPUSH +variable: +.Bd -literal -offset four +.Li NOPUSH= +.Ed +.Pp +.Va ( NOPUSH +is set to true by default because the default configuration is +for a small network with only one +.Tn NIS +server). +The +.Xr yppush 8 +command will initiate a transaction between the master and slave +during which the slave will transfer the specified maps from the +master server using +.Xr ypxfr 8 . +(The slave server calls +.Xr ypxfr 8 +automatically from within +.Xr ypserv 8 ; +therefore it is not usually necessary for the administrator +to use it directly. +It can be run manually if +desired, however.) +Maintaining +slave servers helps improve +.Tn NIS +performance on large +networks by: +.Bl -bullet +.It +Providing backup services in the event that the +.Tn NIS +master crashes +or becomes unreachable +.It +Spreading the client load out over several machines instead of +causing the master to become overloaded +.It +Allowing a single +.Tn NIS +domain to extend beyond +a local network (the +.Xr ypbind 8 +daemon might not be able to locate a server automatically if it resides on +a network outside the reach of its broadcasts. +It is possible to force +.Xr ypbind 8 +to bind to a particular server with +.Xr ypset 8 +but this is sometimes inconvenient. +This problem can be avoided simply by +placing a slave server on the local network.) +.El +.Pp +The +.Fx +.Xr ypserv 8 +is specially designed to provide enhanced security (compared to +other +.Tn NIS +implementations) when used exclusively with +.Fx +client +systems. +The +.Fx +password database system (which is derived directly +from +.Bx 4.4 ) +includes support for +.Em "shadow passwords" . +The standard password database does not contain users' encrypted +passwords: these are instead stored (along with other information) +in a separate database which is accessible only by the super-user. +If the encrypted password database were made available as an +.Tn NIS +map, this security feature would be totally disabled, since any user +is allowed to retrieve +.Tn NIS +data. +.Pp +To help prevent this, +.Fx Ns 's +.Tn NIS +server handles the shadow password maps +.Pa ( master.passwd.byname , +.Pa master.passwd.byuid , +.Pa shadow.byname +and +.Pa shadow.byuid ) +in a special way: the server will only provide access to these +maps in response to requests that originate on privileged ports. +Since only the super-user is allowed to bind to a privileged port, +the server assumes that all such requests come from privileged +users. +All other requests are denied: requests from non-privileged +ports will receive only an error code from the server. +Additionally, +.Fx Ns 's +.Xr ypserv 8 +includes support for +.An Wietse Venema Ns 's +tcp wrapper package; with tcp +wrapper support enabled, the administrator can configure +.Xr ypserv 8 +to respond only to selected client machines. +.Pp +While these enhancements provide better security than stock +.Tn NIS , +they are by no means 100% effective. +It is still possible for +someone with access to your network to spoof the server into disclosing +the shadow password maps. +.Pp +On the client side, +.Fx Ns 's +.Xr getpwent 3 +functions will automatically search for the +.Pa master.passwd +maps and use them if they exist. +If they do, they will be used, and +all fields in these special maps (class, password age and account +expiration) will be decoded. +If they are not found, the standard +.Pa passwd +maps will be used instead. +.Sh COMPATIBILITY +When using a +.No non- Ns Fx +.Tn NIS +server for +.Xr passwd 5 +files, it is unlikely that the default MD5-based format that +.Fx +uses for passwords will be accepted by it. +If this is the case, the value of the +.Va passwd_format +setting in +.Xr login.conf 5 +should be changed to +.Qq Li des +for compatibility. +.Pp +Some systems, such as +.Tn SunOS +4.x, need +.Tn NIS +to be running in order +for their hostname resolution functions +.Po Fn gethostbyname , +.Fn gethostbyaddr , +etc. +.Pc +to work properly. +On these systems, +.Xr ypserv 8 +performs +.Tn DNS +lookups when asked to return information about +a host that does not exist in its +.Pa hosts.byname +or +.Pa hosts.byaddr +maps. +.Fx Ns 's +resolver uses +.Tn DNS +by default (it can be made to use +.Tn NIS , +if desired), therefore its +.Tn NIS +server does not do +.Tn DNS +lookups +by default. +However, +.Xr ypserv 8 +can be made to perform +.Tn DNS +lookups if it is started with a special +flag. +It can also be made to register itself as an +.Tn NIS +v1 server +in order to placate certain systems that insist on the presence of +a v1 server +.Po Fx +uses only +.Tn NIS +v2, but many other systems, +including +.Tn SunOS +4.x, search for both a v1 and v2 server when binding +.Pc . +.Fx Ns 's +.Xr ypserv 8 +does not actually handle +.Tn NIS +v1 requests, but this +.Dq "kludge mode" +is useful for silencing stubborn systems that search for both +a v1 and v2 server. +.Pp +(Please see the +.Xr ypserv 8 +manual page for a detailed description of these special features +and flags.) +.Sh SEE ALSO +.Xr domainname 1 , +.Xr ypcat 1 , +.Xr ypmatch 1 , +.Xr ypwhich 1 , +.Xr nsswitch.conf 5 , +.Xr yp_mkdb 8 , +.Xr ypbind 8 , +.Xr ypinit 8 , +.Xr yppoll 8 , +.Xr yppush 8 , +.Xr ypserv 8 , +.Xr ypset 8 , +.Xr ypxfr 8 +.Sh HISTORY +The +.Nm YP +subsystem was written from the ground up by +.An Theo de Raadt +to be compatible to Sun's implementation. +Bug fixes, improvements +and +.Tn NIS +server support were later added by +.An Bill Paul . +The server-side code was originally written by +.An Peter Eriksson +and +.An Tobias Reber +and is subject to the GNU Public License. +No Sun code was +referenced. +.Sh BUGS +While +.Fx +now has both +.Tn NIS +client and server capabilities, it does not yet have support for +.Xr ypupdated 8 +or the +.Fn yp_update +function. +Both of these require secure +.Tn RPC , +which +.Fx +does not +support yet either. +.Pp +The +.Xr getservent 3 +and +.Xr getprotoent 3 +functions do not yet have +.Tn NIS +support. +Fortunately, these files +do not need to be updated that often. +.Pp +Many more manual pages should be written, especially +.Xr ypclnt 3 . +For the time being, seek out a local Sun machine and read the +manuals for there. +.Pp +Neither Sun nor this author have found a clean way to handle +the problems that occur when ypbind cannot find its server +upon bootup. diff --git a/static/freebsd/man9/BUF_ISLOCKED.9 b/static/freebsd/man9/BUF_ISLOCKED.9 new file mode 100644 index 00000000..c50d79c8 --- /dev/null +++ b/static/freebsd/man9/BUF_ISLOCKED.9 @@ -0,0 +1,66 @@ +.\" +.\" Copyright (C) 2008 Attilio Rao +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 September 26, 2025 +.Dt BUF_ISLOCKED 9 +.Os +.Sh NAME +.Nm BUF_ISLOCKED +.Nd "returns the state of the lock linked to the buffer" +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.In sys/uio.h +.In sys/bio.h +.In sys/buf.h +.Ft int +.Fn BUF_ISLOCKED "struct buf *bp" +.Sh DESCRIPTION +The +.Fn BUF_ISLOCKED +function returns the status of the lock linked to the buffer in relation to +curthread. +.Pp +It can return: +.Bl -tag -width ".Dv LK_EXCLUSIVE" +.It Dv LK_EXCLUSIVE +An exclusive lock is held by curthread. +.It Dv LK_EXCLOTHER +An exclusive lock is held by someone other than curthread. +.It Dv LK_SHARED +A shared lock is held. +.It Li 0 +The lock is not held by anyone. +.El +.Sh SEE ALSO +.Xr buf 9 , +.Xr BUF_LOCK 9 , +.Xr BUF_UNLOCK 9 , +.Xr lockmgr 9 +.Sh AUTHORS +This manual page was written by +.An Attilio Rao Aq Mt attilio@FreeBSD.org . diff --git a/static/freebsd/man9/BUF_LOCK.9 b/static/freebsd/man9/BUF_LOCK.9 new file mode 100644 index 00000000..f70c3bb9 --- /dev/null +++ b/static/freebsd/man9/BUF_LOCK.9 @@ -0,0 +1,73 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 9, 2001 +.Dt BUF_LOCK 9 +.Os +.Sh NAME +.Nm BUF_LOCK +.Nd "locks a buffer" +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.In sys/uio.h +.In sys/bio.h +.In sys/buf.h +.Ft int +.Fn BUF_LOCK "struct buf *bp" "int locktype" +.Sh DESCRIPTION +The +.Fn BUF_LOCK +function locks the given buffer. +If the lock is already held this +call will block until it can acquire the lock unless +.Dv LK_NOWAIT +is set. +.Pp +Its arguments are: +.Bl -tag -width ".Fa locktype" +.It Fa bp +The buffer to lock. +.It Fa locktype +Flags controlling the type of lock. +See +.Xr lockmgr 9 +for details. +.El +.Sh RETURN VALUES +A value of 0 is returned upon success. +See +.Xr lockmgr 9 +for +information on non-zero return values. +.Sh SEE ALSO +.Xr buf 9 , +.Xr BUF_TIMELOCK 9 , +.Xr BUF_UNLOCK 9 , +.Xr lockmgr 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/BUF_LOCKFREE.9 b/static/freebsd/man9/BUF_LOCKFREE.9 new file mode 100644 index 00000000..489e5865 --- /dev/null +++ b/static/freebsd/man9/BUF_LOCKFREE.9 @@ -0,0 +1,61 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 9, 2001 +.Dt BUF_LOCKFREE 9 +.Os +.Sh NAME +.Nm BUF_LOCKFREE +.Nd "destroys a buffer's lock" +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.In sys/uio.h +.In sys/bio.h +.In sys/buf.h +.Ft void +.Fn BUF_LOCKFREE "struct buf *bp" +.Sh DESCRIPTION +The +.Fn BUF_LOCKFREE +macro destroys the buffer lock. +The lock must not be held when +this macro is called or a panic will result. +.Pp +Its argument is: +.Bl -tag -width ".Fa bp" +.It Fa bp +The buffer whose lock is to be destroyed. +.El +.Sh SEE ALSO +.Xr buf 9 , +.Xr BUF_LOCK 9 , +.Xr BUF_TIMELOCK 9 , +.Xr BUF_UNLOCK 9 , +.Xr lockdestroy 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/BUF_LOCKINIT.9 b/static/freebsd/man9/BUF_LOCKINIT.9 new file mode 100644 index 00000000..40730c20 --- /dev/null +++ b/static/freebsd/man9/BUF_LOCKINIT.9 @@ -0,0 +1,60 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 6, 2005 +.Dt BUF_LOCKINIT 9 +.Os +.Sh NAME +.Nm BUF_LOCKINIT +.Nd "initializes a buffer lock" +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.In sys/uio.h +.In sys/bio.h +.In sys/buf.h +.Ft void +.Fn BUF_LOCKINIT "struct buf *bp" +.Sh DESCRIPTION +The +.Fn BUF_LOCKINIT +macro initializes a buffer lock. +.Pp +Its argument is: +.Bl -tag -width ".Fa bp" +.It Fa bp +The buffer whose lock it to be initialized. +.El +.Sh SEE ALSO +.Xr buf 9 , +.Xr BUF_LOCK 9 , +.Xr BUF_TIMELOCK 9 , +.Xr BUF_UNLOCK 9 , +.Xr lockinit 9 , +.Xr lockmgr 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/BUF_RECURSED.9 b/static/freebsd/man9/BUF_RECURSED.9 new file mode 100644 index 00000000..48cd2a58 --- /dev/null +++ b/static/freebsd/man9/BUF_RECURSED.9 @@ -0,0 +1,63 @@ +.\" +.\" Copyright (C) 2008 Attilio Rao +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 22, 2008 +.Dt BUF_RECURSED 9 +.Os +.Sh NAME +.Nm BUF_RECURSED +.Nd "checks if the lock linked to the buffer is recursed" +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.In sys/uio.h +.In sys/bio.h +.In sys/buf.h +.Ft int +.Fn BUF_RECURSED "struct buf *bp" +.Sh DESCRIPTION +The +.Fn BUF_RECURSED +function checks if the lock linked to the given buffer is recursed and +returns 1 if the condition is true, 0 otherwise. +.Pp +Its argument is: +.Bl -tag -width ".Fa bp" +.It Fa bp +The buffer linked to the lock. +See +.Xr lockmgr_recursed 9 +for details. +.El +.Sh SEE ALSO +.Xr buf 9 , +.Xr BUF_LOCK 9 , +.Xr BUF_UNLOCK 9 , +.Xr lockmgr 9 +.Sh AUTHORS +This manual page was written by +.An Attilio Rao Aq Mt attilio@FreeBSD.org . diff --git a/static/freebsd/man9/BUF_TIMELOCK.9 b/static/freebsd/man9/BUF_TIMELOCK.9 new file mode 100644 index 00000000..dc8f2420 --- /dev/null +++ b/static/freebsd/man9/BUF_TIMELOCK.9 @@ -0,0 +1,81 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 9, 2001 +.Dt BUF_TIMELOCK 9 +.Os +.Sh NAME +.Nm BUF_TIMELOCK +.Nd "locks a buffer" +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.In sys/uio.h +.In sys/bio.h +.In sys/buf.h +.Ft int +.Fn BUF_TIMELOCK "struct buf *bp" "int locktype" "char *wmesg" "int catch" "int timo" +.Sh DESCRIPTION +The +.Fn BUF_TIMELOCK +function locks the given buffer, and limits the amount of time it +will sleep to +.Fa timo +and OR's +.Fa catch +into the sleep's priority. +.Fa wmesg +is the wmesg used in the sleep. +.Pp +Its arguments are: +.Bl -tag -width ".Fa locktype" +.It Fa bp +The buffer to lock. +.It Fa locktype +Flags controlling the type of lock. +See +.Xr lockmgr 9 +for details. +.It Fa wmesg +The wmesg used in any sleeps while acquiring the lock. +.It Fa catch +Priority OR'd into the sleep's priority. +.It Fa timo +The timeout for any sleeps encountered during the lock. +.El +.Sh RETURN VALUES +A value of 0 is returned on success. +See +.Xr lockmgr 9 +for details on non-zero return values. +.Sh SEE ALSO +.Xr buf 9 , +.Xr BUF_LOCK 9 , +.Xr BUF_UNLOCK 9 , +.Xr lockmgr 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/BUF_UNLOCK.9 b/static/freebsd/man9/BUF_UNLOCK.9 new file mode 100644 index 00000000..ed9f4cb8 --- /dev/null +++ b/static/freebsd/man9/BUF_UNLOCK.9 @@ -0,0 +1,62 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 9, 2001 +.Dt BUF_UNLOCK 9 +.Os +.Sh NAME +.Nm BUF_UNLOCK +.Nd "unlocks a locked buffer" +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.In sys/uio.h +.In sys/bio.h +.In sys/buf.h +.Ft void +.Fn BUF_UNLOCK "struct buf *bp" +.Sh DESCRIPTION +The +.Fn BUF_UNLOCK +function unlocks a buffer that was previously locked with +.Fn BUF_LOCK +or +.Fn BUF_TIMELOCK . +.Pp +Its argument is: +.Bl -tag -width ".Fa bp" +.It Fa bp +The buffer to unlock. +The buffer must already be locked. +.El +.Sh SEE ALSO +.Xr buf 9 , +.Xr BUF_LOCK 9 , +.Xr BUF_TIMELOCK 9 , +.Xr lockmgr 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/BUS_ADD_CHILD.9 b/static/freebsd/man9/BUS_ADD_CHILD.9 new file mode 100644 index 00000000..bf777108 --- /dev/null +++ b/static/freebsd/man9/BUS_ADD_CHILD.9 @@ -0,0 +1,83 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2004 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 April 8, 2018 +.Dt BUS_ADD_CHILD 9 +.Os +.Sh NAME +.Nm BUS_ADD_CHILD +.Nd "add a device node to the tree with a given priority" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft device_t +.Fn BUS_ADD_CHILD "device_t dev" "int order" "const char *name" "int unit" +.Sh DESCRIPTION +The +.Fn BUS_ADD_CHILD +method +is used by the driver identify routine to add devices to the tree. +It can also be used to add children to buses that implement this +routine in other contexts, although the behavior is bus specific. +Please see +.Xr device_add_child 9 +for more details. +The interface is the same as +.Xr device_add_child 9 +however, the bus' +.Fn BUS_ADD_CHILD +is called. +.Pp +Buses implementing +.Fn BUS_ADD_CHILD +should insert the device into the tree using +.Xr device_add_child 9 +before adding things such as their own ivars and resource lists to the device. +.Fn BUS_ADD_CHILD +is not called by +.Xr device_add_child 9 . +.Fn BUS_ADD_CHILD +instead calls +.Xr device_add_child 9 . +.Pp +A panic will result when called for a bus that does not implement +.Fn BUS_ADD_CHILD . +Some buses require a special bus-specific routine to be called instead +of +.Fn BUS_ADD_CHILD . +.Sh RETURN VALUES +The +.Fn BUS_ADD_CHILD +method returns +.Vt device_t +added to the tree, or +.Dv NULL +to indicate failure. +.Sh SEE ALSO +.Xr device 9 , +.Xr device_add_child 9 , +.Xr driver 9 +.Sh AUTHORS +This manual page was written by +.An M. Warner Losh . diff --git a/static/freebsd/man9/BUS_BIND_INTR.9 b/static/freebsd/man9/BUS_BIND_INTR.9 new file mode 100644 index 00000000..206d20b2 --- /dev/null +++ b/static/freebsd/man9/BUS_BIND_INTR.9 @@ -0,0 +1,96 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2009 Hudson River Trading LLC +.\" Written by: John H. Baldwin +.\" 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 October 14, 2009 +.Dt BUS_BIND_INTR 9 +.Os +.Sh NAME +.Nm BUS_BIND_INTR , +.Nm bus_bind_intr +.Nd "bind an interrupt resource to a specific CPU" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fo BUS_BIND_INTR +.Fa "device_t dev" "device_t child" "struct resource *irq" "int cpu" +.Fc +.Ft int +.Fn bus_bind_intr "device_t dev" "struct resource *irq" "int cpu" +.Sh DESCRIPTION +The +.Fn BUS_BIND_INTR +method allows an interrupt resource to be pinned to a specific CPU. +The interrupt resource must have an interrupt handler attached via +.Xr BUS_SETUP_INTR 9 . +The +.Fa cpu +parameter corresponds to the ID of a valid CPU in the system. +Binding an interrupt restricts the +.Xr cpuset 2 +of any associated interrupt threads to only include the specified CPU. +It may also direct the low-level interrupt handling of the interrupt to the +specified CPU as well, +but this behavior is platform-dependent. +If the value +.Dv NOCPU +is used for +.Fa cpu , +then the interrupt will be +.Dq unbound +which restores any associated interrupt threads back to the default cpuset. +.Pp +Non-sleepable locks such as mutexes should not be held across calls to these +functions. +.Pp +The +.Fn bus_bind_intr +function is a simple wrapper around +.Fn BUS_BIND_INTR . +.Pp +Note that currently there is no attempt made to arbitrate between +multiple bind requests for the same interrupt from either the same +device or multiple devices. +There is also no arbitration between interrupt binding requests submitted +by userland via +.Xr cpuset 2 +and +.Fn BUS_BIND_INTR . +The most recent binding request is the one that will be in effect. +.Sh RETURN VALUES +Zero is returned on success, otherwise an appropriate error is returned. +.Sh SEE ALSO +.Xr cpuset 2 , +.Xr BUS_SETUP_INTR 9 , +.Xr device 9 +.Sh HISTORY +The +.Fn BUS_BIND_INTR +method and +.Fn bus_bind_intr +functions first appeared in +.Fx 7.2 . diff --git a/static/freebsd/man9/BUS_CHILD_DELETED.9 b/static/freebsd/man9/BUS_CHILD_DELETED.9 new file mode 100644 index 00000000..a7c0d736 --- /dev/null +++ b/static/freebsd/man9/BUS_CHILD_DELETED.9 @@ -0,0 +1,53 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2012 Hudson River Trading LLC +.\" Written by: John H. Baldwin +.\" 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 August 21, 2012 +.Dt BUS_CHILD_DELETED 9 +.Os +.Sh NAME +.Nm BUS_CHILD_DELETED +.Nd "notify a bus device that a child is being deleted" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft void +.Fn BUS_CHILD_DELETED "device_t dev" "device_t child" +.Sh DESCRIPTION +The +.Fn BUS_CHILD_DELETED +method is invoked by the new-bus framework when a device is deleted. +A bus driver can provide an implementation of this method to +release bus-specific resources associated with a device such as +instance variables. +.Sh SEE ALSO +.Xr BUS_ADD_CHILD 9 , +.Xr device 9 +.Sh HISTORY +The +.Fn BUS_CHILD_DELETED +method first appeared in +.Fx 10.0 . diff --git a/static/freebsd/man9/BUS_CHILD_DETACHED.9 b/static/freebsd/man9/BUS_CHILD_DETACHED.9 new file mode 100644 index 00000000..8b59d136 --- /dev/null +++ b/static/freebsd/man9/BUS_CHILD_DETACHED.9 @@ -0,0 +1,53 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2012 Hudson River Trading LLC +.\" Written by: John H. Baldwin +.\" 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 January 9, 2025 +.Dt BUS_CHILD_DETACHED 9 +.Os +.Sh NAME +.Nm BUS_CHILD_DETACHED +.Nd "notify a bus device that a child was detached" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft void +.Fn BUS_CHILD_DETACHED "device_t dev" "device_t child" +.Sh DESCRIPTION +The +.Fn BUS_CHILD_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 +.Xr DEVICE_DETACH 9 +method. +.Sh SEE ALSO +.Xr device 9 , +.Xr DEVICE_DETACH 9 diff --git a/static/freebsd/man9/BUS_CHILD_LOCATION.9 b/static/freebsd/man9/BUS_CHILD_LOCATION.9 new file mode 100644 index 00000000..808b55b8 --- /dev/null +++ b/static/freebsd/man9/BUS_CHILD_LOCATION.9 @@ -0,0 +1,59 @@ +.\" +.\" Copyright (c) 2021 Netflix, Inc. +.\" +.\" 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 April 22, 2021 +.Dt BUS_CHILD_LOCATION 9 +.Os +.Sh NAME +.Nm BUS_CHILD_LOCATION +.Nd "obtain the location of a child on the bus." +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.In sys/sbuf.h +.Ft void +.Fn BUS_CHILD_LOCATION "device_t dev" "device_t child" "struct sbuf *sb" +.Sh DESCRIPTION +The +.Fn BUS_CHILD_LOCATION +method returns the location of the +.Dv child +device. +This location is a series of key=value pairs. +The string must be formatted as a space-separated list of key=value pairs. +Names may only contain alphanumeric characters, underscores ('_') and hyphens ('-'). +Values can contain any non-whitespace characters. +Values containing whitespace can be quoted with double quotes ('"'). +Double quotes and backslashes in quoted values can be escaped with backslashes ('\'). +.Pp +The location is defined as a series of characteristics of the +.Dv child +device that can be used to locate that device independent of what drivers are +attached. +Typically, these are slot numbers, bus addresses, or some topology formation. +Where possible, buses are encouraged to provide locations that are stable from +boot to boot and when other devices are added or removed. +A location is not dependent on the kind of device at that location. +.Sh SEE ALSO +.Xr bus 9 , +.Xr device 9 diff --git a/static/freebsd/man9/BUS_CHILD_PNPINFO.9 b/static/freebsd/man9/BUS_CHILD_PNPINFO.9 new file mode 100644 index 00000000..2117aab6 --- /dev/null +++ b/static/freebsd/man9/BUS_CHILD_PNPINFO.9 @@ -0,0 +1,63 @@ +.\" +.\" Copyright (c) 2021 Netflix, Inc. +.\" +.\" 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 April 22, 2021 +.Dt BUS_CHILD_PNPINFO 9 +.Os +.Sh NAME +.Nm BUS_CHILD_PNPINFO +.Nd "obtain the plug and play information from a device" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.In sys/sbuf.h +.Ft void +.Fn BUS_CHILD_PNPINFO "device_t dev" "device_t child" "struct sbuf *sb" +.Sh DESCRIPTION +The +.Fn BUS_CHILD_LOCATION +method returns the identifying information about the +.Dv child +device. +This information is called the plug and play (pnp) details by some buses. +This information is a series of key=value pairs. +The string must be formatted as a space-separated list of key=value pairs. +Names may only contain alphanumeric characters, underscores ('_') and hyphens ('-'). +Values can contain any non-whitespace characters. +Values containing whitespace can be quoted with double quotes ('"'). +Double quotes and backslashes in quoted values can be escaped with backslashes ('\'). +.Pp +The pnpinfo is defined as a series of characteristics of the +.Dv child +device that are independent of which drivers are attached, but +are used to allow drivers to claim a device. +Typically, plug and play information encodes who made the device, what the model +number is, and some generic details about the device. +By convention, only the generic information about the device that's used by +drivers on that bus to decide on accepting the device is reported. +Other configuration information (such as the cache burst size) needed for the +operation of the device, but that doesn't distinguish it broadly from other +devices is not reported. +.Sh SEE ALSO +.Xr bus 9 , +.Xr device 9 diff --git a/static/freebsd/man9/BUS_CONFIG_INTR.9 b/static/freebsd/man9/BUS_CONFIG_INTR.9 new file mode 100644 index 00000000..aaeb6c3e --- /dev/null +++ b/static/freebsd/man9/BUS_CONFIG_INTR.9 @@ -0,0 +1,113 @@ +.\" Copyright (c) 2003 Marcel Moolenaar +.\" 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 January 16, 2025 +.Dt BUS_CONFIG_INTR 9 +.Os +.\" +.Sh NAME +.Nm BUS_CONFIG_INTR , +.Nm bus_config_intr +.Nd "configure interrupt polarity and trigger mode" +.\" +.Sh SYNOPSIS +.In sys/param.h +.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 +method allows bus or device drivers to provide interrupt polarity and trigger +mode to parent buses. +This typically bubbles all the way up to the root bus (e.g.\& nexus) where the +necessary actions are taken to actually program the hardware. +Since the +.Fn BUS_CONFIG_INTR +method takes an interrupt number, it is assumed but not necessarily required +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" +.It Dv INTR_TRIGGER_CONFORM +The interrupt trigger mode is standard for the bus to which the device is +attached. +.It Dv INTR_TRIGGER_EDGE +The interrupt is edge triggered. +This means that the interrupt is raised by the rising edge of the signal on +the interrupt line. +The signal typically reverts to the original state so as to cause a spike. +.It Dv INTR_TRIGGER_LEVEL +The interrupt is level triggered. +This means that the interrupt is raised when the signal on the interrupt line +transitions and remains unchanged after that until the interrupt has been +serviced, after which the signal transitions back. +.El +.Pp +The +.Fa pol +argument can be any one of: +.Bl -tag -width ".Dv INTR_POLARITY_CONFORM" +.It Dv INTR_POLARITY_CONFORM +The interrupt polarity is standard for the bus to which the device is attached. +.It Dv INTR_POLARITY_HIGH +The interrupt is activated by a high voltage on the interrupt line. +.It Dv INTR_POLARITY_LOW +The interrupt is activated by a low voltage on the interrupt line. +.El +.\" +.Sh RETURN VALUES +Zero is returned on success, otherwise an appropriate error is returned. +.\" +.Sh SEE ALSO +.Xr BUS_SETUP_INTR 9 , +.Xr BUS_TEARDOWN_INTR 9 , +.Xr device 9 , +.Xr driver 9 +.\" +.Sh HISTORY +The +.Fn BUS_CONFIG_INTR +method first appeared in +.Fx 5.2 . +.\" +.Sh AUTHORS +This manual page was written by +.An Marcel Moolenaar Aq Mt marcel@xcllnt.net . diff --git a/static/freebsd/man9/BUS_DESCRIBE_INTR.9 b/static/freebsd/man9/BUS_DESCRIBE_INTR.9 new file mode 100644 index 00000000..80dce06e --- /dev/null +++ b/static/freebsd/man9/BUS_DESCRIBE_INTR.9 @@ -0,0 +1,102 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2009 Hudson River Trading LLC +.\" Written by: John H. Baldwin +.\" 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 December 9, 2015 +.Dt BUS_DESCRIBE_INTR 9 +.Os +.Sh NAME +.Nm BUS_DESCRIBE_INTR , +.Nm bus_describe_intr +.Nd "associate a description with an active interrupt handler" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fo BUS_DESCRIBE_INTR +.Fa "device_t dev" "device_t child" "struct resource *irq" "void *cookie" +.Fa "const char *descr" +.Fc +.Ft int +.Fo bus_describe_intr +.Fa "device_t dev" "struct resource *irq" "void *cookie" "const char *fmt" +.Fa ... +.Fc +.Sh DESCRIPTION +The +.Fn BUS_DESCRIBE_INTR +method associates a description with an active interrupt handler. +The +.Fa cookie +parameter must be the value returned by a successful call to +.Xr BUS_SETUP_INTR 9 +for the interrupt +.Fa irq . +.Pp +The +.Fn bus_describe_intr +function is a simple wrapper around +.Fn BUS_DESCRIBE_INTR . +As a convenience, +.Fn bus_describe_intr +allows the caller to use +.Xr printf 9 +style formatting to build the description string using +.Fa fmt . +.Pp +When an interrupt handler is established by +.Xr BUS_SETUP_INTR 9 , +the handler is named after the device the handler is established for. +This name is then used in various places such as interrupt statistics +displayed by +.Xr systat 1 +and +.Xr vmstat 8 . +For devices that use a single interrupt, +the device name is sufficiently unique to identify the interrupt handler. +However, for devices that use multiple interrupts it can be useful to +distinguish the interrupt handlers. +When a description is set for an active interrupt handler, +a colon followed by the description is appended to the device name to form +the interrupt handler name. +.Sh RETURN VALUES +Zero is returned on success, otherwise an appropriate error is returned. +.Sh SEE ALSO +.Xr systat 1 , +.Xr vmstat 8 , +.Xr BUS_SETUP_INTR 9 , +.Xr device 9 , +.Xr printf 9 +.Sh HISTORY +The +.Fn BUS_DESCRIBE_INTR +method and +.Fn bus_describe_intr +functions first appeared in +.Fx 8.1 . +.Sh BUGS +It is not currently possible to remove a description from an active interrupt +handler. diff --git a/static/freebsd/man9/BUS_GET_CPUS.9 b/static/freebsd/man9/BUS_GET_CPUS.9 new file mode 100644 index 00000000..d076bb82 --- /dev/null +++ b/static/freebsd/man9/BUS_GET_CPUS.9 @@ -0,0 +1,98 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2016 John H. Baldwin +.\" +.\" 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 March 1, 2016 +.Dt BUS_GET_CPUS 9 +.Os +.Sh NAME +.Nm BUS_GET_CPUS , +.Nm bus_get_cpus +.Nd "request a set of device-specific CPUs" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.In sys/cpuset.h +.Ft int +.Fo BUS_GET_CPUS +.Fa "device_t dev" "device_t child" "enum cpu_sets op" "size_t setsize" +.Fa "cpuset_t *cpuset" +.Fc +.Ft int +.Fo bus_get_cpus +.Fa "device_t dev" "enum cpu_sets op" "size_t setsize" "cpuset_t *cpuset" +.Fc +.Sh DESCRIPTION +The +.Fn BUS_GET_CPUS +method queries the parent bus device for a set of device-specific CPUs. +The +.Fa op +argument specifies which set of CPUs to retrieve. +If successful, +the requested set of CPUs are returned in +.Fa cpuset . +The +.Fa setsize +argument specifies the size in bytes of the set passed in +.Fa cpuset . +.Pp +.Fn BUS_GET_CPUS +supports querying different types of CPU sets via the +.Fa op argument. +Not all set types are supported for every device. +If a set type is not supported, +.Fn BUS_GET_CPUS +fails with +.Er EINVAL . +These set types are supported: +.Bl -tag -width ".Dv LOCAL_CPUS" +.It Dv LOCAL_CPUS +The set of CPUs that are local to the device. +If a device is closer to a specific memory domain in a non-uniform memory +architecture system +.Pq NUMA , +this will return the set of CPUs in that memory domain. +.It Dv INTR_CPUS +The preferred set of CPUs that this device should use for device interrupts. +This set type must be supported by all bus drivers. +.El +.Pp +The +.Fn bus_get_cpus +function is a simple wrapper around +.Fn BUS_GET_CPUS . +.Sh RETURN VALUES +Zero is returned on success, otherwise an appropriate error is returned. +.Sh SEE ALSO +.Xr cpuset 2 , +.Xr BUS_BIND_INTR 9 , +.Xr device 9 +.Sh HISTORY +The +.Fn BUS_GET_CPUS +method and +.Fn bus_get_cpus +function first appeared in +.Fx 11.0 . diff --git a/static/freebsd/man9/BUS_GET_PROPERTY.9 b/static/freebsd/man9/BUS_GET_PROPERTY.9 new file mode 100644 index 00000000..74fcd7f7 --- /dev/null +++ b/static/freebsd/man9/BUS_GET_PROPERTY.9 @@ -0,0 +1,74 @@ +.\" - +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2021 Semihalf +.\" +.\" 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 February 18, 2022 +.Dt BUS_GET_PROPERTY 9 +.Os +.Sh NAME +.Nm BUS_GET_PROPERTY +.Nd get child's specific property +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft ssize_t +.Fn BUS_GET_PROPERTY "device_t dev" "device_t child" "const char *propname" \ + "void *propvalue" "size_t size" "device_property_type_t type" +.Sh DESCRIPTION +The +.Fn BUS_GET_PROPERTY +method +is called from driver code which wants to access a child's specific data stored +on the bus. +A property has a name and an associated value. +Implementation shall copy to +.Fa propvalue +at most +.Fa size +bytes. +.Pp +.Fn BUS_GET_PROPERTY +supports different property types specified via the +.Fa type +argument. +The +.Fa size +is guaranteed to be a multiple of the underlying property type. +If a type is not supported, +.Fn BUS_GET_PROPERTY +shall return -1. +.Sh NOTES +If +.Fa propvalue +is NULL or +.Fa size +is zero, the implementation shall return only the size of the property. +.Sh RETURN VALUES +The property size if successful, otherwise -1. +.Sh SEE ALSO +.Xr device 9 , +.Xr device_get_property 9 +.Sh AUTHORS +This manual page was written by +.An Bartlomiej Grzesik . diff --git a/static/freebsd/man9/BUS_HINTED_CHILD.9 b/static/freebsd/man9/BUS_HINTED_CHILD.9 new file mode 100644 index 00000000..860ee3a9 --- /dev/null +++ b/static/freebsd/man9/BUS_HINTED_CHILD.9 @@ -0,0 +1,37 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 John Baldwin +.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/static/freebsd/man9/BUS_NEW_PASS.9 b/static/freebsd/man9/BUS_NEW_PASS.9 new file mode 100644 index 00000000..de34f083 --- /dev/null +++ b/static/freebsd/man9/BUS_NEW_PASS.9 @@ -0,0 +1,54 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2009 Hudson River Trading LLC +.\" Written by: John H. Baldwin +.\" 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 June 8, 2009 +.Dt BUS_NEW_PASS 9 +.Os +.Sh NAME +.Nm BUS_NEW_PASS +.Nd "notify a bus that the pass level has been changed" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft void +.Fn BUS_NEW_PASS "device_t dev" +.Sh DESCRIPTION +The +.Fn BUS_NEW_PASS +method is called on each bus device to rescan the device tree when the pass +level has been changed. +This method is responsible for invoking +.Nm +on child bus devices to propagate the rescan to child devices. +It is also responsible for reprobing any unattached child devices and +allowing drivers for the current pass to identify new children. +A default implementation is provided by +.Xr bus_generic_new_pass 9 . +.Sh SEE ALSO +.Xr bus_generic_new_pass 9 , +.Xr bus_set_pass 9 , +.Xr device 9 diff --git a/static/freebsd/man9/BUS_PRINT_CHILD.9 b/static/freebsd/man9/BUS_PRINT_CHILD.9 new file mode 100644 index 00000000..037ca59f --- /dev/null +++ b/static/freebsd/man9/BUS_PRINT_CHILD.9 @@ -0,0 +1,62 @@ +.\" -*- 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 6, 2005 +.Dt BUS_PRINT_CHILD 9 +.Os +.Sh NAME +.Nm BUS_PRINT_CHILD +.Nd print information about a device +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn BUS_PRINT_CHILD "device_t dev" "device_t child" +.Sh DESCRIPTION +The +.Fn BUS_PRINT_CHILD +method +is called from system code which prints out a description of a +device. +It should describe the attachment that the child has with +the parent. +For instance the TurboLaser bus prints which node the +device is attached to. +Please see +.Xr bus_generic_print_child 9 +for more information regarding the proper formatting of the messages +printed by +.Fn BUS_PRINT_CHILD . +.Sh RETURN VALUES +The number of characters output. +.Sh SEE ALSO +.Xr device 9 , +.Xr driver 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/BUS_READ_IVAR.9 b/static/freebsd/man9/BUS_READ_IVAR.9 new file mode 100644 index 00000000..51e17df2 --- /dev/null +++ b/static/freebsd/man9/BUS_READ_IVAR.9 @@ -0,0 +1,61 @@ +.\" -*- 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 June 16, 1998 +.Dt BUS_READ_IVAR 9 +.Os +.Sh NAME +.Nm BUS_READ_IVAR , +.Nm BUS_WRITE_IVAR +.Nd manipulate bus-specific device instance variables +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn BUS_READ_IVAR "device_t dev" "device_t child" "int index" "uintptr_t *result" +.Ft int +.Fn BUS_WRITE_IVAR "device_t dev" "device_t child" "int index" "uintptr_t value" +.Sh DESCRIPTION +These two methods manage a bus specific set of instance variables of +a child device. +The intention is that each different type of bus +defines a set of appropriate instance variables (such as ports and +irqs for ISA bus etc.) +.Pp +This information could be given to the child device as a struct but +that makes it hard for a bus to add or remove variables without +forcing an edit and recompile for all drivers which may not be +possible for vendor supplied binary drivers. +.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/static/freebsd/man9/BUS_RESCAN.9 b/static/freebsd/man9/BUS_RESCAN.9 new file mode 100644 index 00000000..6f3eb39d --- /dev/null +++ b/static/freebsd/man9/BUS_RESCAN.9 @@ -0,0 +1,48 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2016 John H. Baldwin +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 27, 2016 +.Dt BUS_RESCAN 9 +.Os +.Sh NAME +.Nm BUS_RESCAN +.Nd "rescan a bus checking for devices that have been added or removed" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft void +.Fn BUS_RESCAN "device_t dev" +.Sh DESCRIPTION +The +.Fn BUS_RESCAN +method is called to request a rescan of the child devices on a bus device. +The method should add any devices that have been added since the previous +scan and remove devices that have been removed. +This method is not required to re-examine existing devices to determine if +their properties have changed. +This method is also not required to propagate the rescan request to child +devices. +.Sh SEE ALSO +.Xr device 9 diff --git a/static/freebsd/man9/BUS_SETUP_INTR.9 b/static/freebsd/man9/BUS_SETUP_INTR.9 new file mode 100644 index 00000000..238f434e --- /dev/null +++ b/static/freebsd/man9/BUS_SETUP_INTR.9 @@ -0,0 +1,212 @@ +.\" Copyright (c) 2000 Jeroen Ruigrok van der Werven +.\" 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 November 3, 2010 +.Dt BUS_SETUP_INTR 9 +.Os +.Sh NAME +.Nm BUS_SETUP_INTR , +.Nm bus_setup_intr , +.Nm BUS_TEARDOWN_INTR , +.Nm bus_teardown_intr +.Nd create, attach and teardown an interrupt handler +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fo BUS_SETUP_INTR +.Fa "device_t dev" "device_t child" "struct resource *irq" "int flags" +.Fa "driver_filter_t *filter" "driver_intr_t *ithread" "void *arg" +.Fa "void **cookiep" +.Fc +.Ft int +.Fo bus_setup_intr +.Fa "device_t dev" "struct resource *r" "int flags" +.Fa "driver_filter_t filter" "driver_intr_t ithread" "void *arg" +.Fa "void **cookiep" +.Fc +.Ft int +.Fo BUS_TEARDOWN_INTR +.Fa "device_t dev" "device_t child" "struct resource *irq" "void *cookiep" +.Fc +.Ft int +.Fn bus_teardown_intr "device_t dev" "struct resource *r" "void *cookiep" +.Sh DESCRIPTION +The +.Fn BUS_SETUP_INTR +method +will create and attach an interrupt handler to an interrupt +previously allocated by the resource manager's +.Xr BUS_ALLOC_RESOURCE 9 +method. +The +.Fa flags +are found in +.In sys/bus.h , +and give the broad category of interrupt. +The +.Fa flags +also tell the interrupt handlers about certain +device driver characteristics. +.Dv INTR_EXCL +marks the handler as being +an exclusive handler for this interrupt. +.Dv INTR_MPSAFE +tells the scheduler that the interrupt handler +is well behaved in a preemptive environment +(``SMP safe''), +and does not need +to be protected by the ``Giant Lock'' mutex. +.Dv INTR_ENTROPY +marks the interrupt as being a good source of entropy - +this may be used by the entropy device +.Pa /dev/random . +.Pp +To define a time-critical handler that will not execute any potentially +blocking operation, use the +.Fa filter +argument. +See the +.Sx "Filter Routines" +section below for information on writing a filter. +Otherwise, use the +.Fa ithread +argument. +The defined handler +will be called with the value +.Fa arg +as its only argument. +See the +.Sx "ithread Routines" +section below for more information on writing an interrupt handler. +.Pp +The +.Fa cookiep +argument is a pointer to a +.Vt "void *" +that +.Fn BUS_SETUP_INTR +will write a cookie for the parent bus' use to if it is successful in +establishing an interrupt. +Driver writers may assume that this cookie will be non-zero. +The nexus driver will write 0 on failure to +.Fa cookiep . +.Pp +The interrupt handler will be detached by +.Fn BUS_TEARDOWN_INTR . +The cookie needs to be passed to +.Fn BUS_TEARDOWN_INTR +in order to tear down the correct interrupt handler. +Once +.Fn BUS_TEARDOWN_INTR +returns, it is guaranteed that the interrupt function is not active and +will no longer be called. +.Pp +Mutexes are not allowed to be held across calls to these functions. +.Ss "Filter Routines" +A filter runs in primary interrupt context. +In this context, normal mutexes cannot be used. +Only the spin lock version of these can be used (specified by passing +.Dv MTX_SPIN +to +.Fn mtx_init +when initializing the mutex). +.Xr wakeup 9 +and similar routines can be called. +Atomic operations from +.Pa machine/atomic +may be used. +Reads and writes to hardware through +.Xr bus_space 9 +may be used. +PCI configuration registers may be read and written. +All other kernel interfaces cannot be used. +.Pp +In this restricted environment, care must be taken to account for all +races. +A careful analysis of races should be done as well. +It is generally cheaper to take an extra interrupt, for example, than +to protect variables with spinlocks. +Read, modify, write cycles of hardware registers need to be carefully +analyzed if other threads are accessing the same registers. +.Pp +Generally, a filter routine will use one of two strategies. +The first strategy is to simply mask the interrupt in hardware and +allow the +.Dv ithread +routine to read the state from the hardware and then reenable +interrupts. +The +.Dv ithread +also acknowledges the interrupt before re-enabling the interrupt +source in hardware. +Most PCI hardware can mask its interrupt source. +.Pp +The second common approach is to use a filter with multiple +.Xr taskqueue 9 +tasks. +In this case, the filter acknowledges the interrupts and queues the +work to the appropriate taskqueue. +Where one has to multiplex different kinds of interrupt sources, like +a network card's transmit and receive paths, this can reduce lock +contention and increase performance. +.Pp +You should not +.Xr malloc 9 +from inside a filter. +You may not call anything that uses a normal mutex. +Witness may complain about these. +.Ss "ithread Routines" +You can do whatever you want in an ithread routine, except sleep. +Care must be taken not to sleep in an ithread. +In addition, one should minimize lock contention in an ithread routine +because contested locks ripple over to all other ithread routines on +that interrupt. +.Ss "Sleeping" +Sleeping is voluntarily giving up control of your thread. +All the sleep routine found in +.Xr msleep 9 +sleep. +Waiting for a condition variable described in +.Xr condvar 9 +is sleeping. +Calling any function that does any of these things is sleeping. +.Sh RETURN VALUES +Zero is returned on success, +otherwise an appropriate error is returned. +.Sh SEE ALSO +.Xr random 4 , +.Xr device 9 , +.Xr driver 9 , +.Xr locking 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Jeroen Ruigrok van der Werven Aq Mt asmodai@FreeBSD.org +based on the manual pages for +.Fn BUS_CREATE_INTR +and +.Fn BUS_CONNECT_INTR +written by +.An Doug Rabson Aq Mt dfr@FreeBSD.org . diff --git a/static/freebsd/man9/CTASSERT.9 b/static/freebsd/man9/CTASSERT.9 new file mode 100644 index 00000000..0a55b450 --- /dev/null +++ b/static/freebsd/man9/CTASSERT.9 @@ -0,0 +1,68 @@ +.\" Copyright (c) 2003 Hiten M. Pandya +.\" +.\" 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 August 1, 2015 +.Dt CTASSERT 9 +.Os +.Sh NAME +.Nm CTASSERT +.Nd compile time assertion macro +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.Fn CTASSERT expression +.Sh DESCRIPTION +The +.Fn CTASSERT +macro is deprecated and the C11 standard +.Fn _Static_assert +should be used instead. +The header +.Fa sys/cdefs.h +should be included to provide compatibility for pre-C11 compilers. +.Pp +The +.Fn CTASSERT +macro evaluates +.Fa expression +at compile time and causes a compiler error if it is false. +.Pp +The +.Fn CTASSERT +macro is useful for asserting the size or alignment of important +data structures and variables during compilation, which would +otherwise cause the code to fail at run time. +.Sh EXAMPLES +Assert that the size of the +.Vt uuid +structure is 16 bytes. +.Pp +.Dl "CTASSERT(sizeof(struct uuid) == 16);" +.Sh SEE ALSO +.Xr KASSERT 9 +.Sh AUTHORS +This manual page was written by +.An Hiten M. Pandya Aq Mt hmp@FreeBSD.org . diff --git a/static/freebsd/man9/DB_COMMAND.9 b/static/freebsd/man9/DB_COMMAND.9 new file mode 100644 index 00000000..b07281a3 --- /dev/null +++ b/static/freebsd/man9/DB_COMMAND.9 @@ -0,0 +1,180 @@ +.\"- +.\" Copyright (c) 2008 Guillaume Ballet +.\" 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 5, 2023 +.Dt DB_COMMAND 9 +.Os +.Sh NAME +.Nm DB_COMMAND , +.Nm DB_COMMAND_FLAGS , +.Nm DB_SHOW_COMMAND , +.Nm DB_SHOW_COMMAND_FLAGS , +.Nm DB_SHOW_ALL_COMMAND , +.Nm DB_TABLE_COMMAND , +.Nm DB_TABLE_COMMAND_FLAGS , +.Nm DB_ALIAS , +.Nm DB_ALIAS_FLAGS , +.Nm DB_SHOW_ALIAS , +.Nm DB_SHOW_ALIAS_FLAGS , +.Nm DB_SHOW_ALL_ALIAS , +.Nm DB_TABLE_ALIAS , +.Nm DB_TABLE_ALIAS_FLAGS +.Nm DB_DECLARE_TABLE , +.Nm DB_DEFINE_TABLE , +.Nd Extends the ddb command set +.Sh SYNOPSIS +.In ddb/ddb.h +.Fn DB_COMMAND "command_name" "command_function" +.Fn DB_COMMAND_FLAGS "command_name" "command_function" "flags" +.Fn DB_SHOW_COMMAND "command_name" "command_function" +.Fn DB_SHOW_COMMAND_FLAGS "command_name" "command_function" "flags" +.Fn DB_SHOW_ALL_COMMAND "command_name" "command_function" +.Fn DB_TABLE_COMMAND "table" "command_name" "command_function" +.Fn DB_TABLE_COMMAND_FLAGS "table" "command_name" "command_function" "flags" +.Fn DB_ALIAS "alias_name" "command_function" +.Fn DB_ALIAS_FLAGS "alias_name" "command_function" "flags" +.Fn DB_SHOW_ALIAS "alias_name" "command_function" +.Fn DB_SHOW_ALIAS_FLAGS "alias_name" "command_function" "flags" +.Fn DB_SHOW_ALL_ALIAS "alias_name" "command_function" +.Fn DB_TABLE_ALIAS "table" "alias_name" "command_function" +.Fn DB_TABLE_ALIAS_FLAGS "table" "alias_name" "command_function" "flags" +.Fn DB_DEFINE_TABLE "parent" "name" "table" +.Fn DB_DECLARE_TABLE "table" +.Sh DESCRIPTION +The +.Fn DB_COMMAND +macro adds +.Fa command_name +to the list of top-level commands. +Invoking +.Fa command_name +from ddb will call +.Fa command_function . +.Pp +The +.Fn DB_SHOW_COMMAND +and +.Fn DB_SHOW_ALL_COMMAND +macros are roughly equivalent to +.Fn DB_COMMAND +but in these cases, +.Fa command_name +is a sub-command of the ddb +.Sy show +command and +.Sy show all +command, respectively. +.Pp +The +.Fn DB_TABLE_COMMAND +macro is also similar to +.Fn DB_COMMAND +but adds the new command as a sub-command of the ddb command +.Fa table . +.Pp +The +.Fn DB_ALIAS , +.Fn DB_SHOW_ALIAS , +.Fn DB_SHOW_ALL_ALIAS , +and +.Fn DB_TABLE_ALIAS +macros register the existing +.Fa command_function +under the alternative command name +.Fa alias_name . +.Pp +The _FLAGS variants of these commands allow the programmer to specify a value +for the +.Fa flag +field of the command structure. +The possible flag values are defined alongside +.Ft struct db_command +in +.In ddb/ddb.h . +.Pp +The general command syntax: +.Cm command Ns Op Li \&/ Ns Ar modifier +.Ar address Ns Op , Ns Ar count , +translates into the following parameters for +.Fa command_function : +.Bl -tag -width Fa -offset indent +.It Fa addr +The address passed to the command as an argument. +.It Fa have_addr +A boolean value that is true if the addr field is valid. +.It Fa count +The number of quad words starting at offset +.Fa addr +that the command must process. +.It Fa modif +A pointer to the string of modifiers. +That is, a series of symbols used to pass some options to the command. +For example, the +.Sy examine +command will display words in decimal form if it is passed the modifier "d". +.El +.Pp +The +.Fn DB_DEFINE_TABLE +macro adds a new command +.Fa name +as a sub-command of the existing command table +.Fa parent . +The new command defines a table named +.Fa table +which contains sub-commands. +New commands and aliases can be added to this table by passing +.Fa table +as the first argument to one of the DB_TABLE_ macros. +.Sh EXAMPLES +In your module, the command is declared as: +.Bd -literal +DB_COMMAND(mycmd, my_cmd_func) +{ + if (have_addr) + db_printf("Calling my command with address %p\\n", addr); +} +.Ed +.Pp +An alias for this command is declared as: +.Bd -literal +DB_ALIAS(mycmd2, my_cmd_func); +.Ed +.Pp +Then, when in ddb: +.Bd -literal +.Bf Sy +db> mycmd 0x1000 +Calling my command with address 0x1000 +db> mycmd2 0x2500 +Calling my command with address 0x2500 +db> +.Ef +.Ed +.Sh SEE ALSO +.Xr ddb 4 +.Sh AUTHORS +This manual page was written by +.An Guillaume Ballet Aq Mt gballet@gmail.com . diff --git a/static/freebsd/man9/DECLARE_GEOM_CLASS.9 b/static/freebsd/man9/DECLARE_GEOM_CLASS.9 new file mode 100644 index 00000000..108048f9 --- /dev/null +++ b/static/freebsd/man9/DECLARE_GEOM_CLASS.9 @@ -0,0 +1,177 @@ +.\" +.\" Copyright (c) 2004 Pawel Jakub Dawidek +.\" 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 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 August 13, 2007 +.Dt DECLARE_GEOM_CLASS 9 +.Os +.Sh NAME +.Nm DECLARE_GEOM_CLASS +.Nd "GEOM class declaration macro" +.Sh SYNOPSIS +.In geom/geom.h +.Fn DECLARE_GEOM_CLASS "class" "mod_name" +.Sh DESCRIPTION +The +.Fn DECLARE_GEOM_CLASS +macro registers a GEOM class in GEOM. +A GEOM class itself implements one particular kind of transformation. +Typical examples are: MBR disk partition, +.Bx +disklabel and RAID5 classes. +.Fn DECLARE_GEOM_CLASS +can be used both for compiled in and loaded as +.Xr kld 4 +modules GEOM classes and it is the only official way for class registration. +.Pp +The arguments to +.Fn DECLARE_GEOM_CLASS +are: +.Bl -tag -offset indent -width Fa +.It Fa class +The +.Vt g_class +structure which describes a GEOM class. +.It Fa mod_name +A kernel module name (not a class name!). +.El +.Pp +Structure +.Vt g_class +contains data describing the class. +They are: +.Bl -tag -offset indent -width indent +.It Vt "const char *" Va name +Class name. +.It Vt "g_taste_t *" Va taste +Pointer to function used for taste event handling. +If it is +.Pf non- Dv NULL +it is called in three situations: +.Pp +.Bl -dash -compact +.It +On class activation, all existing providers are offered for tasting. +.It +When new provider is created it is offered for tasting. +.It +After last write access to a provider is closed it is offered for retasting +(on first write open event +.Dq spoil +was sent). +.El +.It Vt "g_config_t *" Va config +This field is not used anymore, its functionality was replaced by the +.Va ctlreq +field. +.It Vt "g_ctl_req_t *" Va ctlreq +Pointer to function used for handling events from userland applications. +.It Vt "g_init_t *" Va init +Pointer to function which is called right after class registration. +.It Vt "g_fini_t *" Va fini +Pointer to function which is called right before class deregistration. +.It Vt "g_ctl_destroy_geom_t *" Va destroy_geom +Pointer to a function which is called for every geom on class unload. +If this field is not set, the class can not be unloaded. +.El +.Pp +Only a +.Fa name +field is required; the rest are optional. +.Sh RESTRICTIONS/CONDITIONS +The fields of +.Vt g_class +should always be initialized using C99-style field naming +(see the initialization of +.Va example_class +below). +.Sh EXAMPLES +Example class declaration. +.Bd -literal -offset indent +static struct g_geom * +g_example_taste(struct g_class *mp, struct g_provider *pp, + int flags __unused) +{ + g_topology_assert(); + + [...] +} + +static void +g_example_ctlreq(struct gctl_req *req, struct g_class *cp, + char const *verb) +{ + + [...] +} + +static int +g_example_destroy_geom(struct gctl_req *req, struct g_class *cp, + struct g_geom *gp) +{ + + g_topology_assert(); + + [...] +} + +static void +g_example_init(struct g_class *mp) +{ + + [...] +} + +static void +g_example_fini(struct g_class *mp) +{ + + [...] +} + +struct g_class example_class = { + .name = "EXAMPLE", + .taste = g_example_taste, + .ctlreq = g_example_ctlreq, + .init = g_example_init, + .fini = g_example_fini, + .destroy_geom = g_example_destroy_geom +}; + +DECLARE_GEOM_CLASS(example_class, g_example); +.Ed +.Sh SEE ALSO +.Xr geom 4 , +.Xr g_attach 9 , +.Xr g_bio 9 , +.Xr g_consumer 9 , +.Xr g_data 9 , +.Xr g_event 9 , +.Xr g_geom 9 , +.Xr g_provider 9 , +.Xr g_provider_by_name 9 , +.Xr g_wither_geom 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . diff --git a/static/freebsd/man9/DECLARE_MODULE.9 b/static/freebsd/man9/DECLARE_MODULE.9 new file mode 100644 index 00000000..f7c49eee --- /dev/null +++ b/static/freebsd/man9/DECLARE_MODULE.9 @@ -0,0 +1,127 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2000 Alexander Langer +.\" +.\" 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 February 13, 2018 +.Dt DECLARE_MODULE 9 +.Os +.Sh NAME +.Nm DECLARE_MODULE +.Nd kernel module declaration macro +.Sh SYNOPSIS +.In sys/param.h +.In sys/kernel.h +.In sys/module.h +.Fn DECLARE_MODULE "name" "moduledata_t data" "sub" "order" +.Fn DECLARE_MODULE_TIED "name" "moduledata_t data" "sub" "order" +.Sh DESCRIPTION +The +.Fn DECLARE_MODULE +macro declares a generic kernel module. +It is used to register the module with the system, using the +.Fn SYSINIT +macro. +.Fn DECLARE_MODULE +is usually used within other macros, such as +.Xr DRIVER_MODULE 9 , +.Xr DEV_MODULE 9 +and +.Xr SYSCALL_MODULE 9 . +Of course, it can also be called directly, for example in +order to implement dynamic sysctls. +.Pp +A module declared with +.Fn DECLARE_MODULE_TIED +will load only if the running kernel version +(as specified by +.Dv __FreeBSD_version ) +is identical to that on which it was built. +This declaration should be used by modules which depend on interfaces beyond +the stable kernel KBI (such as ABI emulators or hypervisors that rely on +internal kernel structures). +.Fn DECLARE_MODULE +will behave like +.Fn DECLARE_MODULE_TIED +when compiled with modules built with the kernel. +This allows locks and other synchronization primitives +to be inlined safely. +.Pp +The arguments are: +.Bl -tag -width indent +.It Fa name +The module name, which will be used in the +.Fn SYSINIT +call to identify the module. +.It Fa data +A +.Vt moduledata_t +structure, which contains two main items, the official name of the +module name, which will be used in the +.Vt module_t +structure and a pointer to the event handler function of type +.Vt modeventhand_t . +.It Fa sub +An argument directed to the +.Fn SYSINIT +macro. +Valid values for this are contained in the +.Vt sysinit_sub_id +enumeration +(see +.In sys/kernel.h ) +and specify the type of system startup interfaces. +The +.Xr DRIVER_MODULE 9 +macro uses a value of +.Dv SI_SUB_DRIVERS +here for example, since these modules contain a driver for a device. +For kernel modules that are loaded at runtime, a value of +.Dv SI_SUB_EXEC +is common. +.It Fa order +An argument for +.Fn SYSINIT . +It represents the KLDs order of initialization within the subsystem. +Valid values are defined in the +.Vt sysinit_elem_order +enumeration +.Pq In sys/kernel.h . +.El +.Sh SEE ALSO +.Xr DEV_MODULE 9 , +.Xr DRIVER_MODULE 9 , +.Xr module 9 , +.Xr SYSCALL_MODULE 9 +.Pp +.Pa /usr/include/sys/kernel.h , +.Pa /usr/share/examples/kld +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Alexander Langer Aq Mt alex@FreeBSD.org , +inspired by the KLD Facility Programming Tutorial by +.An Andrew Reiter Aq Mt arr@watson.org . diff --git a/static/freebsd/man9/DEFINE_IFUNC.9 b/static/freebsd/man9/DEFINE_IFUNC.9 new file mode 100644 index 00000000..8cb216af --- /dev/null +++ b/static/freebsd/man9/DEFINE_IFUNC.9 @@ -0,0 +1,140 @@ +.\" Copyright (c) 2019 The FreeBSD Foundation +.\" +.\" This documentation was written by Mark Johnston +.\" under sponsorship from the FreeBSD Foundation. +.\" +.\" 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 March 10, 2026 +.Dt DEFINE_IFUNC 9 +.Os +.Sh NAME +.Nm DEFINE_IFUNC +.Nd define a kernel function with an implementation selected at run-time +.Sh SYNOPSIS +.In machine/ifunc.h +.Fn DEFINE_IFUNC qual ret_type name args +.Sh DESCRIPTION +ifuncs are a linker feature which allows the programmer to define functions +whose implementation is selected at boot-time or module load-time. +The +.Nm +macro can be used to define an ifunc. +The selection is performed by a resolver function, which returns a pointer +to the selected function. +ifunc resolvers are invoked very early during the machine-dependent +initialization routine, or at load time for dynamically loaded modules. +Resolution must occur before the first call to an ifunc. +ifunc resolution is performed after CPU features are enumerated and after the +kernel's environment is initialized. +The typical use-case for an ifunc is a routine whose behavior depends on +optional CPU features. +For example, newer generations of a given CPU architecture may provide an +instruction to optimize a common operation. +To avoid the overhead of testing for the CPU feature each time the operation +is performed, an ifunc can be used to provide two implementations for the +operation: one targeting platforms with the extra instruction, and one +for older platforms. +.Pp +Because +.Nm +is a macro that defines a dynamically typed function, its usage looks somewhat +unusual. +The +.Ar qual +parameter is a list of zero or more C function qualifiers to be applied to the +ifunc. +This parameter is typically empty or the +.Dv static +qualifier. +.Ar ret_type +is the return type of the ifunc. +.Ar name +is the name of the ifunc. +.Ar args +is a parenthesized, comma-separated list of the parameter types of the function, +as they would appear in a C function declaration. +.Pp +The +.Nm +usage must be followed by the resolver function body. +The resolver must return a function with return type +.Ar ret_type +and parameter types +.Ar args . +The resolver function is defined with the +.Ql resolver +gcc-style function attribute, causing the corresponding +.Xr elf 5 +function symbol to be of type +.Dv STT_GNU_IFUNC +instead of +.Dv STT_FUNC . +The kernel linker invokes the resolver to process relocations targeting ifunc +calls and PLT entries referencing such symbols. +.Sh EXAMPLES +ifunc resolvers are executed early during boot, before most kernel facilities +are available. +They are effectively limited to checking CPU feature flags and tunables. +.Bd -literal +static size_t +fast_strlen(const char *s __unused) +{ + size_t len; + + /* Fast, but may not be correct in all cases. */ + __asm("movq $42,%0\\n" : "=r" (len)); + return (len); +} + +static size_t +slow_strlen(const char *s) +{ + const char *t; + + for (t = s; *t != '\\0'; t++); + return (t - s); +} + +DEFINE_IFUNC(, size_t, strlen, (const char *)) +{ + int enabled; + + enabled = 1; + TUNABLE_INT_FETCH("debug.use_fast_strlen", &enabled); + if (enabled && (cpu_features & CPUID_FAST_STRLEN) != 0) + return (fast_strlen); + else + return (slow_strlen); +} +.Ed +.Pp +This defines a +.Fn strlen +function with an optimized implementation for CPUs that advertise support. +.Sh SEE ALSO +.Xr elf 5 +.Sh NOTES +ifuncs require both toolchain support, to emit function symbols of type +.Dv STT_GNU_IFUNC , +and kernel linker support, to invoke ifunc resolvers during boot or +during module load. diff --git a/static/freebsd/man9/DELAY.9 b/static/freebsd/man9/DELAY.9 new file mode 100644 index 00000000..bfc8f794 --- /dev/null +++ b/static/freebsd/man9/DELAY.9 @@ -0,0 +1,47 @@ +.\" +.\" Copyright (c) 2000 Alfred Perlstein +.\" +.\" 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 April 20, 2013 +.Dt DELAY 9 +.Os +.Sh NAME +.Nm DELAY +.Nd busy loop for an interval +.Sh SYNOPSIS +.In sys/types.h +.In sys/systm.h +.Ft void +.Fn DELAY "int delay" +.Sh DESCRIPTION +Delay for +.Fa delay +microseconds (1/1000000th of a second). +.Sh SEE ALSO +.Xr pause 9 +.Sh AUTHORS +This manual page was written by +.An Alfred Perlstein . diff --git a/static/freebsd/man9/DEVICE_ATTACH.9 b/static/freebsd/man9/DEVICE_ATTACH.9 new file mode 100644 index 00000000..8e7c4625 --- /dev/null +++ b/static/freebsd/man9/DEVICE_ATTACH.9 @@ -0,0 +1,70 @@ +.\" -*- 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 February 5, 2025 +.Dt DEVICE_ATTACH 9 +.Os +.Sh NAME +.Nm DEVICE_ATTACH +.Nd attach a device +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn DEVICE_ATTACH "device_t dev" +.Sh DESCRIPTION +Attach a device to the system after the +.Fn DEVICE_PROBE +method has been called and has indicated that +the device exists. +The +.Fn DEVICE_ATTACH +method should initialize the hardware and allocate other +system resources (such as +.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_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 4 , +.Xr bus_attach_children 9 , +.Xr device 9 , +.Xr DEVICE_DETACH 9 , +.Xr DEVICE_IDENTIFY 9 , +.Xr DEVICE_PROBE 9 , +.Xr DEVICE_SHUTDOWN 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson Aq Mt dfr@FreeBSD.org . diff --git a/static/freebsd/man9/DEVICE_DETACH.9 b/static/freebsd/man9/DEVICE_DETACH.9 new file mode 100644 index 00000000..856c6138 --- /dev/null +++ b/static/freebsd/man9/DEVICE_DETACH.9 @@ -0,0 +1,60 @@ +.\" -*- 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 June 16, 1998 +.Dt DEVICE_DETACH 9 +.Os +.Sh NAME +.Nm DEVICE_DETACH +.Nd detach a device +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn DEVICE_DETACH "device_t dev" +.Sh DESCRIPTION +Detach a device. +This can be called if the user is replacing the +driver software or if a device is about to be physically removed from +the system. +.Pp +The method should deallocate any system resources allocated during the +.Xr DEVICE_ATTACH 9 +method and reset the hardware to a sane state (i.e., disable interrupts +etc.) +.Sh RETURN VALUES +Zero is returned on success, otherwise an appropriate error is returned. +.Sh SEE ALSO +.Xr device 9 , +.Xr DEVICE_ATTACH 9 , +.Xr DEVICE_IDENTIFY 9 , +.Xr DEVICE_PROBE 9 , +.Xr DEVICE_SHUTDOWN 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/DEVICE_IDENTIFY.9 b/static/freebsd/man9/DEVICE_IDENTIFY.9 new file mode 100644 index 00000000..564699b5 --- /dev/null +++ b/static/freebsd/man9/DEVICE_IDENTIFY.9 @@ -0,0 +1,91 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2001 Alexander Langer +.\" +.\" 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 February 5, 2025 +.Dt DEVICE_IDENTIFY 9 +.Os +.Sh NAME +.Nm DEVICE_IDENTIFY +.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 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 +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 each resource. +.Pp +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 parent bus device. +.Bd -literal +void +foo_identify(driver_t *driver, device_t parent) +{ + device_t child; + + retrieve_device_information; + if (devices matches one of your supported devices && + device_find_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_find_child 9 +.Sh AUTHORS +This manual page was written by +.An Alexander Langer Aq Mt alex@FreeBSD.org . diff --git a/static/freebsd/man9/DEVICE_PROBE.9 b/static/freebsd/man9/DEVICE_PROBE.9 new file mode 100644 index 00000000..292ffceb --- /dev/null +++ b/static/freebsd/man9/DEVICE_PROBE.9 @@ -0,0 +1,138 @@ +.\" -*- 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 February 8, 2012 +.Dt DEVICE_PROBE 9 +.Os +.Sh NAME +.Nm DEVICE_PROBE +.Nd probe for device existence +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn DEVICE_PROBE "device_t dev" +.Sh DESCRIPTION +The +.Fn DEVICE_PROBE +method should probe to see if the device is present. +It should return 0 if the device exists, +.Er ENXIO +if it cannot be found. +If some other error happens during the probe (such as a memory +allocation failure), an appropriate error code should be returned. +For +cases where more than one driver matches a device, a priority value can +be returned. +In this case, success codes are values less than or equal +to zero with the highest value representing the best match. +Failure +codes are represented by positive values and the regular +.Ux +error +codes should be used for the purpose. +.Pp +If a driver returns a success code which is less than zero, it must +not assume that it will be the same driver which is attached to the +device. +In particular, it must not assume that any values stored in +the softc structure will be available for its attach method and any +resources allocated during probe must be released and re-allocated +if the attach method is called. +In addition it is an absolute requirement that the probe routine have +no side effects whatsoever. +The probe routine may be called more than once before the attach +routine is called. +.Pp +If a success code of zero is +returned, the driver can assume that it will be the one attached, but +must not hold any resources when the probe routine returns. +A driver may assume that the softc is preserved when it returns +a success code of zero. +.Sh RETURN VALUES +A value equal to or less than zero indicates success, greater than +zero indicates an error (errno). +For values equal to or less than +zero: zero indicates highest priority, no further probing is done; +for a value less than zero, the lower the value the lower the +priority, e.g.\& -100 indicates a lower priority than -50. +.Pp +The following values are used by convention to indicate different +strengths of matching in a probe routine. +Except as noted, these are just suggested values, and there's nothing +magical about them. +.Bl -tag -width BUS_PROBE_NOWILDCARD +.It BUS_PROBE_SPECIFIC +The device that cannot be reprobed, and that no +possible other driver may exist (typically legacy drivers who don't follow +all the rules, or special needs drivers). +.It BUS_PROBE_VENDOR +The device is supported by a vendor driver. +This is for source or binary drivers that are not yet integrated into the +.Fx +tree. +Its use in the base OS is prohibited. +.It BUS_PROBE_DEFAULT +The device is a normal device matching some plug and play ID. +This is +the normal return value for drivers to use. +It is intended that nearly all of the drivers in the tree should return +this value. +.It BUS_PROBE_LOW_PRIORITY +The driver is a legacy driver, or an otherwise less desirable driver +for a given plug and play ID. +The driver has special requirements like when there are two drivers +that support overlapping series of hardware devices. +In this case the one that supports the older part of the line would +return this value, while the one that supports the newer ones would +return BUS_PROBE_DEFAULT. +.It BUS_PROBE_GENERIC +The driver matches the type of device generally. +This allows drivers to match all serial ports generally, with specialized +drivers matching particular types of serial ports that need special +treatment for some reason. +.It BUS_PROBE_HOOVER +The driver matches all unclaimed devices on a bus. +The +.Xr ugen 4 +device is one example. +.It BUS_PROBE_NOWILDCARD +The driver expects its parent to tell it which children to manage +and no probing is really done. +The device only matches if its parent bus specifically said to use +this driver. +.El +.Sh SEE ALSO +.Xr device 9 , +.Xr DEVICE_ATTACH 9 , +.Xr DEVICE_DETACH 9 , +.Xr DEVICE_IDENTIFY 9 , +.Xr DEVICE_SHUTDOWN 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/DEVICE_SHUTDOWN.9 b/static/freebsd/man9/DEVICE_SHUTDOWN.9 new file mode 100644 index 00000000..4ab3646b --- /dev/null +++ b/static/freebsd/man9/DEVICE_SHUTDOWN.9 @@ -0,0 +1,55 @@ +.\" -*- 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 6, 2005 +.Dt DEVICE_SHUTDOWN 9 +.Os +.Sh NAME +.Nm DEVICE_SHUTDOWN +.Nd called during system shutdown +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn DEVICE_SHUTDOWN "device_t dev" +.Sh DESCRIPTION +The +.Fn DEVICE_SHUTDOWN +method is called during system shutdown to allow the driver to put the +hardware into a consistent state for rebooting the computer. +.Sh RETURN VALUES +Zero is returned on success, otherwise an error is returned. +.Sh SEE ALSO +.Xr device 9 , +.Xr DEVICE_ATTACH 9 , +.Xr DEVICE_DETACH 9 , +.Xr DEVICE_IDENTIFY 9 , +.Xr DEVICE_PROBE 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/DEV_MODULE.9 b/static/freebsd/man9/DEV_MODULE.9 new file mode 100644 index 00000000..084ba170 --- /dev/null +++ b/static/freebsd/man9/DEV_MODULE.9 @@ -0,0 +1,103 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2001 Alexander Langer +.\" +.\" 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 19, 2012 +.Dt DEV_MODULE 9 +.Os +.Sh NAME +.Nm DEV_MODULE +.Nd device driver module declaration macro +.Sh SYNOPSIS +.In sys/param.h +.In sys/kernel.h +.In sys/module.h +.In sys/conf.h +.Fn DEV_MODULE "name" "modeventhand_t evh" "void *arg" +.Sh DESCRIPTION +The +.Fn DEV_MODULE +macro declares a device driver kernel module. +It fills in a +.Vt moduledata_t +structure and then calls +.Fn DECLARE_MODULE +with the correct args, where +.Fa name +is the name of the module and +.Fa evh +(with its argument +.Fa arg ) +is the event handler for the module (refer to +.Xr DECLARE_MODULE 9 +for more information). +The event handler is supposed to create the device with +.Fn make_dev +on load and to destroy it when it is unloaded using +.Fn destroy_dev . +.Sh EXAMPLES +.Bd -literal +#include +#include + +static struct cdevsw foo_devsw = { ... }; + +static struct cdev *sdev; + +static int +foo_load(module_t mod, int cmd, void *arg) +{ + int err = 0; + + switch (cmd) { + case MOD_LOAD: + sdev = make_dev(&foo_devsw, 0, UID_ROOT, GID_WHEEL, 0600, "foo"); + break; /* Success*/ + + case MOD_UNLOAD: + case MOD_SHUTDOWN: + destroy_dev(sdev); + break; /* Success*/ + + default: + err = EINVAL; + break; + } + + return(err); +} + +DEV_MODULE(foo, foo_load, NULL); +.Ed +.Sh SEE ALSO +.Xr DECLARE_MODULE 9 , +.Xr destroy_dev 9 , +.Xr make_dev 9 , +.Xr module 9 +.Sh AUTHORS +This manual page was written by +.An Alexander Langer Aq Mt alex@FreeBSD.org . diff --git a/static/freebsd/man9/DRIVER_MODULE.9 b/static/freebsd/man9/DRIVER_MODULE.9 new file mode 100644 index 00000000..c349375b --- /dev/null +++ b/static/freebsd/man9/DRIVER_MODULE.9 @@ -0,0 +1,151 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2000 Alexander Langer +.\" +.\" 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 April 19, 2022 +.Dt DRIVER_MODULE 9 +.Os +.Sh NAME +.Nm DRIVER_MODULE , +.Nm DRIVER_MODULE_ORDERED , +.Nm EARLY_DRIVER_MODULE , +.Nm EARLY_DRIVER_MODULE_ORDERED +.Nd kernel driver declaration macro +.Sh SYNOPSIS +.In sys/param.h +.In sys/kernel.h +.In sys/bus.h +.In sys/module.h +.Fn DRIVER_MODULE name busname "driver_t driver" "modeventhand_t evh" "void *arg" +.Fn DRIVER_MODULE_ORDERED name busname "driver_t driver" "modeventhand_t evh" "void *arg" "int order" +.Fn EARLY_DRIVER_MODULE name busname "driver_t driver" "modeventhand_t evh" "void *arg" "int pass" +.Fn EARLY_DRIVER_MODULE_ORDERED name busname "driver_t driver" "modeventhand_t evh" "void *arg" "enum sysinit_elem_order order" "int pass" +.Sh DESCRIPTION +The +.Fn DRIVER_MODULE +macro declares a kernel driver. +.Fn DRIVER_MODULE +expands to the real driver declaration, where the phrase +.Fa name +is used as the naming prefix for the driver and its functions. +Note that it is supplied as plain text, and not a +.Li char +or +.Li char * . +.Pp +.Fa busname +is the parent bus of the driver (PCI, ISA, PPBUS and others), e.g.\& +.Ql pci , +.Ql isa , +or +.Ql ppbus . +.Pp +The identifier used in +.Fn DRIVER_MODULE +can be different from the driver name. +Also, the same driver identifier can exist on different buses, +which is a pretty clean way of making front ends for different cards +using the same driver on the same or different buses. +For example, the following is allowed: +.Pp +.Fn DRIVER_MODULE foo isa foo_driver NULL NULL ; +.Pp +.Fn DRIVER_MODULE foo pci foo_driver NULL NULL ; +.Pp +.Fa driver +is the driver of type +.Li driver_t , +which contains the information about the driver and is therefore one of the +two most important parts of the call to +.Fn DRIVER_MODULE . +.Pp +The +.Fa evh +argument is the event handler which is called when the driver (or module) +is loaded or unloaded (see +.Xr module 9 ) . +.Pp +The +.Fa arg +is unused at this time and should be a +.Dv NULL +pointer. +.Pp +The +.Fn DRIVER_MODULE_ORDERED +macro allows a driver to be registered in a specific order. +This can be useful if a single kernel module contains multiple drivers +that are inter-dependent. +The +.Fa order +argument should be one of the +.Xr SYSINIT 9 +initialization ordering constants +.Pq Dv SI_ORDER_* . +The default order for a driver module is +.Dv SI_ORDER_MIDDLE . +Typically a module will specify an order of +.Dv SI_ORDER_ANY +for a single driver to ensure it is registered last. +.Pp +The +.Fn EARLY_DRIVER_MODULE +macro allows a driver to be registered for a specific pass level. +The boot time probe and attach process makes multiple passes over the +device tree. +Certain critical drivers that provide basic services needed by other +devices are attached during earlier passes. +Most drivers are attached in a final general pass. +A driver that attaches during an early pass must register for a specific +pass level +.Pq BUS_PASS_* +via the +.Fa pass +argument. +Once a driver is registered it is available to attach to devices for +all subsequent passes. +.Pp +The +.Fn EARLY_DRIVER_MODULE_ORDERED +macro allows a driver to be registered both in a specific order and +for a specific pass level. +.Sh SEE ALSO +.Xr device 9 , +.Xr driver 9 , +.Xr module 9 , +.Xr MODULE_PNP_INFO 9 , +.Xr SYSINIT 9 +.Sh HISTORY +Prior to +.Fx 14.0 , +these macros accepted an additional +.Vt devclass_t +argument after +.Fa driver . +.Sh AUTHORS +This manual page was written by +.An Alexander Langer Aq Mt alex@FreeBSD.org . diff --git a/static/freebsd/man9/EVENTHANDLER.9 b/static/freebsd/man9/EVENTHANDLER.9 new file mode 100644 index 00000000..c3e7c951 --- /dev/null +++ b/static/freebsd/man9/EVENTHANDLER.9 @@ -0,0 +1,288 @@ +.\" Copyright (c) 2004 Joseph Koshy +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 31, 2025 +.Dt EVENTHANDLER 9 +.Os +.Sh NAME +.Nm EVENTHANDLER +.Nd kernel event handling functions +.Sh SYNOPSIS +.In sys/eventhandler.h +.Fn EVENTHANDLER_DECLARE name type +.Fn EVENTHANDLER_DEFINE name func arg priority +.Fn EVENTHANDLER_INVOKE name ... +.Ft eventhandler_tag +.Fn EVENTHANDLER_REGISTER name func arg priority +.Fn EVENTHANDLER_DEREGISTER name tag +.Fn EVENTHANDLER_DEREGISTER_NOWAIT name tag +.Fn EVENTHANDLER_LIST_DECLARE name +.Fn EVENTHANDLER_LIST_DEFINE name +.Fn EVENTHANDLER_DIRECT_INVOKE name +.Ft eventhandler_tag +.Fo eventhandler_register +.Fa "struct eventhandler_list *list" +.Fa "const char *name" +.Fa "void *func" +.Fa "void *arg" +.Fa "int priority" +.Fc +.Ft void +.Fo eventhandler_deregister +.Fa "struct eventhandler_list *list" +.Fa "eventhandler_tag tag" +.Fc +.Ft void +.Fo eventhandler_deregister_nowait +.Fa "struct eventhandler_list *list" +.Fa "eventhandler_tag tag" +.Fc +.Ft "struct eventhandler_list *" +.Fn eventhandler_find_list "const char *name" +.Ft void +.Fn eventhandler_prune_list "struct eventhandler_list *list" +.Sh DESCRIPTION +The +.Nm +mechanism provides a way for kernel subsystems to register interest in +kernel events and have their callback functions invoked when these +events occur. +.Pp +Callback functions are invoked in order of priority. +The relative priority of each callback among other callbacks +associated with an event is given by argument +.Fa priority , +which is an integer ranging from +.Dv EVENTHANDLER_PRI_FIRST +(highest priority), to +.Dv EVENTHANDLER_PRI_LAST +(lowest priority). +The symbol +.Dv EVENTHANDLER_PRI_ANY +may be used if the handler does not have a specific priority +associated with it. +.Pp +The normal way to use this subsystem is via the macro interface. +For events that are high frequency it is suggested that you additionally use +.Fn EVENTHANDLER_LIST_DEFINE +so that the event handlers can be invoked directly using +.Fn EVENTHANDLER_DIRECT_INVOKE +(see below). +This saves the invoker from having to do a locked traversal of a global +list of event handler lists. +.Bl -tag -width indent +.It Fn EVENTHANDLER_DECLARE +This macro declares an event handler named by argument +.Fa name +with callback functions of type +.Fa type . +.It Fn EVENTHANDLER_DEFINE +This macro uses +.Xr SYSINIT 9 +to register a callback function +.Fa func +with event handler +.Fa name . +When invoked, function +.Fa func +will be invoked with argument +.Fa arg +as its first parameter along with any additional parameters passed in +via macro +.Fn EVENTHANDLER_INVOKE +(see below). +.It Fn EVENTHANDLER_REGISTER +This macro registers a callback function +.Fa func +with event handler +.Fa name . +When invoked, function +.Fa func +will be invoked with argument +.Fa arg +as its first parameter along with any additional parameters passed in +via macro +.Fn EVENTHANDLER_INVOKE +(see below). +.Fn EVENTHANDLER_REGISTER +returns a cookie of type +.Vt eventhandler_tag . +.It Fn EVENTHANDLER_DEREGISTER +This macro removes a previously registered callback associated with tag +.Fa tag +from the event handler named by argument +.Fa name . +It waits until no threads are running handlers for this event before +returning, making it safe to unload a module immediately upon return +from this function. +.It Fn EVENTHANDLER_DEREGISTER_NOWAIT +This macro removes a previously registered callback associated with tag +.Fa tag +from the event handler named by argument +.Fa name . +Upon return, one or more threads could still be running the removed +function(s), but no new calls will be made. +To remove a handler function from within that function, use this +version of deregister, to avoid a deadlock. +.It Fn EVENTHANDLER_INVOKE +This macro is used to invoke all the callbacks associated with event +handler +.Fa name . +This macro is a variadic one. +Additional arguments to the macro after the +.Fa name +parameter are passed as the second and subsequent arguments to each +registered callback function. +.It Fn EVENTHANDLER_LIST_DEFINE +This macro defines a reference to an event handler list named by +argument +.Fa name . +It uses +.Xr SYSINIT 9 +to initialize the reference and the eventhandler list. +.It Fn EVENTHANDLER_LIST_DECLARE +This macro declares an event handler list named by argument +.Fa name . +This is only needed for users of +.Fn EVENTHANDLER_DIRECT_INVOKE +which are not in the same compilation unit of that list's definition. +.It Fn EVENTHANDLER_DIRECT_INVOKE +This macro invokes the event handlers registered for the list named by +argument +.Fa name . +This macro can only be used if the list was defined with +.Fn EVENTHANDLER_LIST_DEFINE . +The macro is variadic with the same semantics as +.Fn EVENTHANDLER_INVOKE . +.El +.Pp +The macros are implemented using the following functions: +.Bl -tag -width indent +.It Fn eventhandler_register +The +.Fn eventhandler_register +function is used to register a callback with a given event. +The arguments expected by this function are: +.Bl -tag -width ".Fa priority" +.It Fa list +A pointer to an existing event handler list, or +.Dv NULL . +If +.Fa list +is +.Dv NULL , +the event handler list corresponding to argument +.Fa name +is used. +.It Fa name +The name of the event handler list. +.It Fa func +A pointer to a callback function. +Argument +.Fa arg +is passed to the callback function +.Fa func +as its first argument when it is invoked. +.It Fa priority +The relative priority of this callback among all the callbacks +registered for this event. +Valid values are those in the range +.Dv EVENTHANDLER_PRI_FIRST +to +.Dv EVENTHANDLER_PRI_LAST . +.El +.Pp +The +.Fn eventhandler_register +function returns a +.Fa tag +that can later be used with +.Fn eventhandler_deregister +to remove the particular callback function. +.It Fn eventhandler_deregister +The +.Fn eventhandler_deregister +function removes the callback associated with tag +.Fa tag +from the event handler list pointed to by +.Fa list . +If +.Fa tag +is +.Va NULL , +all callback functions for the event are removed. +This function will not return until all threads have exited from the +removed handler callback function(s). +This function is not safe to call from inside an event handler callback. +.It Fn eventhandler_deregister_nowait +The +.Fn eventhandler_deregister +function removes the callback associated with tag +.Fa tag +from the event handler list pointed to by +.Fa list . +This function is safe to call from inside an event handler +callback. +.It Fn eventhandler_find_list +The +.Fn eventhandler_find_list +function returns a pointer to event handler list structure corresponding +to event +.Fa name . +.It Fn eventhandler_prune_list +The +.Fn eventhandler_prune_list +function removes all deregistered callbacks from the event list +.Fa list . +.El +.Sh RETURN VALUES +The macro +.Fn EVENTHANDLER_REGISTER +and function +.Fn eventhandler_register +return a cookie of type +.Vt eventhandler_tag , +which may be used in a subsequent call to +.Fn EVENTHANDLER_DEREGISTER +or +.Fn eventhandler_deregister . +.Pp +The +.Fn eventhandler_find_list +function +returns a pointer to an event handler list corresponding to parameter +.Fa name , +or +.Dv NULL +if no such list was found. +.Sh HISTORY +The +.Nm +facility first appeared in +.Fx 4.0 . +.Sh AUTHORS +This manual page was written by +.An Joseph Koshy Aq Mt jkoshy@FreeBSD.org +and +.An Matt Joras Aq Mt mjoras@FreeBSD.org . diff --git a/static/freebsd/man9/KASSERT.9 b/static/freebsd/man9/KASSERT.9 new file mode 100644 index 00000000..bab8efe5 --- /dev/null +++ b/static/freebsd/man9/KASSERT.9 @@ -0,0 +1,201 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2000 Jonathan M. Bresler +.\" All rights reserved. +.\" Copyright (c) 2023-2024 The FreeBSD Foundation +.\" +.\" Portions of this documentation were written by Mitchell Horne +.\" under sponsorship from the FreeBSD Foundation. +.\" +.\" 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 March 19, 2024 +.Dt KASSERT 9 +.Os +.Sh NAME +.Nm KASSERT +.Nd kernel expression verification macros +.Sh SYNOPSIS +.Cd "options INVARIANTS" +.Pp +.In sys/param.h +.In sys/systm.h +.Fn KASSERT expression msg +.Fn MPASS expression +.Sh DESCRIPTION +Assertions are widely used within the +.Fx +kernel to verify programmatic assumptions. +For violations of run-time assumptions and invariants, it is desirable to fail +as soon and as loudly as possible. +Assertions are optional code; for non-recoverable error conditions an explicit +call to +.Xr panic 9 +is usually preferred. +.Pp +The +.Fn KASSERT +macro tests the given boolean +.Fa expression . +If +.Fa expression +evaluates to +.Dv false , +and the kernel is compiled with +.Cd "options INVARIANTS" , +the +.Xr panic 9 +function is called. +This terminates the running system at the point of the error, possibly dropping +into the kernel debugger or initiating a kernel core dump. +The second argument, +.Fa msg , +is a +.Xr printf 9 +format string and its arguments, +enclosed in parentheses. +The formatted string will become the panic string. +.Pp +In a kernel that is built without +.Cd "options INVARIANTS" , +the assertion macros are defined to be no-ops. +This eliminates the runtime overhead of widespread assertions from release +builds of the kernel. +Therefore, checks which can be performed in a constant amount of time can be +added as assertions without concern about their performance impact. +More expensive checks, such as those that output to console, or verify the +integrity of a chain of objects are generally best hidden behind the +.Cd DIAGNOSTIC +kernel option. +.Pp +The +.Fn MPASS +macro (read as: "must-pass") +is a convenience wrapper around +.Fn KASSERT +that automatically generates a simple assertion message including file and line +information. +.Ss Assertion Guidelines +When adding new assertions, keep in mind their primary purpose: to aid in +identifying and debugging of complex error conditions. +.Pp +The panic messages resulting from assertion failures should be useful without +the resulting kernel dump; the message may be included in a bug report, and +should contain the relevant information needed to discern how the assertion was +violated. +This is especially important when the error condition is difficult or +impossible for the developer to reproduce locally. +.Pp +Therefore, assertions should adhere to the following guidelines: +.Bl -enum +.It +Whenever possible, the value of a runtime variable checked by an assertion +condition should appear in its message. +.It +Unrelated conditions must appear in separate assertions. +.It +Multiple related conditions should be distinguishable (e.g. by value), or split +into separate assertions. +.It +When in doubt, print more information, not less. +.El +.Pp +Combined, this gives greater clarity into the exact cause of an assertion +panic; see +.Sx EXAMPLES +below. +.Sh EXAMPLES +A hypothetical +.Vt struct foo +object must not have its 'active' flag set when calling +.Fn foo_dealloc : +.Bd -literal -offset indent +void +foo_dealloc(struct foo *fp) +{ + + KASSERT((fp->foo_flags & FOO_ACTIVE) == 0, + ("%s: fp %p is still active, flags=%x", __func__, fp, + fp->foo_flags)); + ... +} +.Ed +.Pp +This assertion provides the full flag set for the object, as well as the memory +pointer, which may be used by a debugger to examine the object in detail +.Po +for example with a 'show foo' command in +.Xr ddb 4 +.Pc . +.Pp +The assertion +.Bd -literal -offset indent +MPASS(td == curthread); +.Ed +.Pp +located on line 87 of a file named foo.c would generate the following panic +message: +.Bd -literal -offset indent +panic: Assertion td == curthread failed at foo.c:87 +.Ed +.Pp +This is a simple condition, and the message provides enough information to +investigate the failure. +.Pp +The assertion +.Bd -literal -offset indent +MPASS(td == curthread && (sz >= SIZE_MIN && sz <= SIZE_MAX)); +.Ed +.Pp +is +.Em NOT +useful enough. +The message doesn't indicate which part of the assertion was violated, nor +does it report the value of +.Dv sz , +which may be critical to understanding +.Em why +the assertion failed. +.Pp +According to the guidelines above, this would be correctly expressed as: +.Bd -literal -offset indent +MPASS(td == curthread); +KASSERT(sz >= SIZE_MIN && sz <= SIZE_MAX, + ("invalid size argument: %u", sz)); +.Ed +.Sh HISTORY +The +.Nm MPASS +macro first appeared in +.Bsx +and was imported into +.Fx 5.0 . +The name originates as an acronym of "multi-processor assert", but has evolved +to mean "must pass", or "must-pass assert". +.Sh SEE ALSO +.Xr panic 9 +.Sh AUTHORS +This manual page was written by +.An Jonathan M. Bresler Aq Mt jmb@FreeBSD.org +and +.An Mitchell Horne Aq Mt mhorne@FreeBSD.org . diff --git a/static/freebsd/man9/LOCK_PROFILING.9 b/static/freebsd/man9/LOCK_PROFILING.9 new file mode 100644 index 00000000..e2b42cad --- /dev/null +++ b/static/freebsd/man9/LOCK_PROFILING.9 @@ -0,0 +1,185 @@ +.\"- +.\" Copyright (c) 2004 Dag-Erling Smørgrav +.\" Copyright (c) 2005 Robert N. M. Watson +.\" Copyright (c) 2006 Kip Macy +.\" 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. 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 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 March 7, 2012 +.Dt LOCK_PROFILING 9 +.Os +.Sh NAME +.Nm LOCK_PROFILING +.Nd kernel lock profiling support +.Sh SYNOPSIS +.Cd "options LOCK_PROFILING" +.Sh DESCRIPTION +The +.Dv LOCK_PROFILING +kernel option adds support for measuring and reporting lock use and +contention statistics. +These statistics are collated by +.Dq acquisition point . +Acquisition points are +distinct places in the kernel source code (identified by source file +name and line number) where a lock is acquired. +.Pp +For each acquisition point, the following statistics are accumulated: +.Bl -bullet +.It +The longest time the lock was ever continuously held after being +acquired at this point. +.It +The total time the lock was held after being acquired at this point. +.It +The total time that threads have spent waiting to acquire the lock. +.It +The total number of non-recursive acquisitions. +.It +The total number of times the lock was already held by another thread +when this point was reached, requiring a spin or a sleep. +.It +The total number of times another thread tried to acquire the lock +while it was held after having been acquired at this point. +.El +.Pp +In addition, the average hold time and average wait time are derived +from the total hold time +and total wait time respectively and the number of acquisitions. +.Pp +The +.Dv LOCK_PROFILING +kernel option also adds the following +.Xr sysctl 8 +variables to control and monitor the profiling code: +.Bl -tag -width indent +.It Va debug.lock.prof.enable +Enable or disable the lock profiling code. +This defaults to 0 (off). +.It Va debug.lock.prof.reset +Reset the current lock profiling buffers. +.It Va debug.lock.prof.stats +The actual profiling statistics in plain text. +The columns are as follows, from left to right: +.Bl -tag -width ".Va cnt_hold" +.It Va max +The longest continuous hold time in microseconds. +.It Va wait_max +The longest continuous wait time in microseconds. +.It Va total +The total (accumulated) hold time in microseconds. +.It Va wait_total +The total (accumulated) wait time in microseconds. +.It Va count +The total number of acquisitions. +.It Va avg +The average hold time in microseconds, derived from the total hold time +and the number of acquisitions. +.It Va wait_avg +The average wait time in microseconds, derived from the total wait time +and the number of acquisitions. +.It Va cnt_hold +The number of times the lock was held and another thread attempted to +acquire the lock. +.It Va cnt_lock +The number of times the lock was already held when this point was +reached. +.It Va name +The name of the acquisition point, derived from the source file name +and line number, followed by the name of the lock in parentheses. +.El +.It Va debug.lock.prof.rejected +The number of acquisition points that were ignored after the table +filled up. +.It Va debug.lock.prof.skipspin +Disable or enable the lock profiling code for the spin locks. +This defaults to 0 (do profiling for the spin locks). +.It Va debug.lock.prof.skipcount +Do sampling approximately every N lock acquisitions. +.El +.Sh SEE ALSO +.Xr sysctl 8 , +.Xr mutex 9 +.Sh HISTORY +Mutex profiling support appeared in +.Fx 5.0 . +Generalized lock profiling support appeared in +.Fx 7.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm MUTEX_PROFILING +code was written by +.An Eivind Eklund Aq Mt eivind@FreeBSD.org , +.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org +and +.An Robert Watson Aq Mt rwatson@FreeBSD.org . +The +.Nm +code was written by +.An Kip Macy Aq Mt kmacy@FreeBSD.org . +This manual page was written by +.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . +.Sh NOTES +The +.Dv LOCK_PROFILING +option increases the size of +.Vt "struct lock_object" , +so a kernel built with that option will not work with modules built +without it. +.Pp +The +.Dv LOCK_PROFILING +option also prevents inlining of the mutex code, which can result in a +fairly severe performance penalty. +This is, however, not always the case. +.Dv LOCK_PROFILING +can introduce a substantial performance overhead that is easily +monitorable using other profiling tools, so combining profiling tools +with +.Dv LOCK_PROFILING +is not recommended. +.Pp +Measurements are made and stored in nanoseconds using +.Xr nanotime 9 , +(on architectures without a synchronized TSC) but are presented in microseconds. +This should still be sufficient for the locks one would be most +interested in profiling (those that are held long and/or acquired +often). +.Pp +.Dv LOCK_PROFILING +should generally not be used in combination with other debugging options, as +the results may be strongly affected by interactions between the features. +In particular, +.Dv LOCK_PROFILING +will report higher than normal +.Xr uma 9 +lock contention when run with +.Dv INVARIANTS +due to extra locking that occurs when +.Dv INVARIANTS +is present; likewise, using it in combination with +.Dv WITNESS +will lead to much higher lock hold times and contention in profiling output. diff --git a/static/freebsd/man9/MODULE_DEPEND.9 b/static/freebsd/man9/MODULE_DEPEND.9 new file mode 100644 index 00000000..a3b433a9 --- /dev/null +++ b/static/freebsd/man9/MODULE_DEPEND.9 @@ -0,0 +1,78 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2001 Alexander Langer +.\" +.\" 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 11, 2005 +.Dt MODULE_DEPEND 9 +.Os +.Sh NAME +.Nm MODULE_DEPEND +.Nd set kernel module dependencies +.Sh SYNOPSIS +.In sys/param.h +.In sys/module.h +.Fn MODULE_DEPEND "name" "moddepend" "int minversion" "int prefversion" "int maxversion" +.Sh DESCRIPTION +The +.Fn MODULE_DEPEND +macro sets a dependency on another kernel module with name +.Fa moddepend , +which has registered +its version with +.Fn MODULE_VERSION . +.Pp +The +.Fn MODULE_DEPEND +macro provides hints to the kernel +.Xr loader 8 +and to the kernel linker to ensure that the named dependency is loaded +prior to the existing module. +It does not change or dictate the order in which modules are +initialized at runtime. +.Pp +Three versions must be specified for +.Fa moddepend : +.Bl -tag -width ".Fa prefversion" +.It Fa minversion +The minimum version on which the current module can depend. +.It Fa maxversion +The maximum version on which the current module can depend. +.It Fa prefversion +The preferred version on which the current module can depend. +.El +.Sh EXAMPLES +.Bd -literal +MODULE_DEPEND(foo, bar, 1, 3, 4); +.Ed +.Sh SEE ALSO +.Xr DECLARE_MODULE 9 , +.Xr module 9 , +.Xr MODULE_VERSION 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Alexander Langer Aq Mt alex@FreeBSD.org . diff --git a/static/freebsd/man9/MODULE_PNP_INFO.9 b/static/freebsd/man9/MODULE_PNP_INFO.9 new file mode 100644 index 00000000..b1cc935b --- /dev/null +++ b/static/freebsd/man9/MODULE_PNP_INFO.9 @@ -0,0 +1,218 @@ +.\" Copyright (c) 2018 Conrad Meyer +.\" 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 May 23, 2019 +.Dt MODULE_PNP_INFO 9 +.Os +.Sh NAME +.Nm MODULE_PNP_INFO +.Nd register plug and play information for device matching +.\" +.Sh SYNOPSIS +.In sys/module.h +.Fo MODULE_PNP_INFO +.Fa "const char *descriptor_string" +.Fa "bus" +.Fa "module" +.Fa "void *table" +.Fa "size_t num_entries" +.Fc +.\" +.Sh DESCRIPTION +The +.Fn MODULE_PNP_INFO +macro registers a +.Fa table +of device-identifying data for use by +.Xr devmatch 8 . +Since it is built off module marking macros, it must follow a +.Xr DRIVER_MODULE 9 +line. +.Pp +The macro takes a +.Fa descriptor_string +that describes the memory layout of table entries. +The string is a series of members separated by semi-colons. +Members are identified by a type and a name. +They are encoded in the descriptor string by concatenating the type with a +colon, followed by the name. +(The special type +.Vt W32 +represents two members. +The first name is encoded like any other type. +The second name is encoded by appending a forward slash and the second +name after the first.) +.Pp +Types are one of the following: +.Bl -tag -width indent +.It Dq Vt U8 +.Vt uint8_t +element. +.It Dq Vt V8 +Same as +.Vt U8 , +except that the sentinel value 0xFF matches any. +.It Dq Vt G16 +.Vt uint16_t +element; any value greater than or equal matches. +.It Dq Vt L16 +.Vt uint16_t +element; any value less than or equal matches. +.It Dq Vt M16 +.Vt uint16_t +element; mask of which of the following fields to use. +.It Dq Vt U16 +.Vt uint16_t +element. +.It Dq Vt V16 +Same as +.Vt U16 , +except that the sentinel value 0xFFFF matches any. +.It Dq Vt U32 +.Vt uint32_t +element. +.It Dq Vt V32 +Same as +.Vt U32 , +except that the sentinel value 0xFFFFFFFF matches any. +.It Dq Vt W32 +Two +.Vt uint16_t +values; the first named member is in the least significant word and the second +named member is in the most significant word. +.It Dq Vt Z +A pointer to a string to match exactly. +.It Dq Vt D +A pointer to a human readable description for the device. +.It Dq Vt P +A pointer that should be ignored. +.It Dq Vt E +EISA PNP Identifier. +.It Dq Vt T +PNP info that is true for the whole table. +The driver code checks for these condition pragmatically before using +this table to match devices. +This item must come last in the list. +.El +.Pp +The pseudo-name +.Dq # +is reserved for fields that should be ignored. +Any member that does not match the parent device's pnpinfo output must be +ignored. +.Pp +The +.Fa bus +parameter is an unquoted word naming the parent bus of the driver. +For example, +.Dq pci . +.Pp +The +.Fa module +parameter is also an unquoted word. +It must be unique to the driver. +Usually the driver's name is used. +.Pp +The +.Fa table +parameter points to the device matching data with entries matching the +.Fa descriptor_string . +.Pp +The +.Fa num_entries +parameter is the number of entries in the table, i.e., +.Ql nitems(table) . +Note that only valid entries should be included. +If the table contains trailing zero or bogus values, they should not be +included in +.Fa num_entries . +.\" +.Sh EXAMPLES +.Bl -tag -width "" +.It Sy Example 1\&: No Using W32 for vendor/device pair +.Pp +The following example shows usage of +.Vt W32 +type when vendor/device values are combined into single +.Vt uint32_t +value: +.Bd -literal +#include +#include + +static struct my_pciids { + uint32_t devid; + const char *desc; +} my_ids[] = { + { 0x12345678, "Foo bar" }, + { 0x9abcdef0, "Baz fizz" }, +}; + +MODULE_PNP_INFO("W32:vendor/device;D:#", pci, my_driver, my_ids, + nitems(my_ids)); +.Ed +.It Sy Example 2\&: No Using T for common vendor value +.Pp +The following example shows usage of +.Vt T +type when all entries in the table have the same vendor value: +.Bd -literal +#include +#include + +static struct my_pciids { + uint16_t device; + const char *desc; +} my_ids[] = { + { 0x9abc, "Foo bar" }, + { 0xdef0, "Baz fizz" }, +}; + +MODULE_PNP_INFO("U16:device;D:#;T:vendor=0x1234", pci, my_driver, + my_ids, nitems(my_ids)); +.Ed +.El +.\" +.Sh BUGS +The +.Nm +macro must follow +.Dv DRIVER_MODULE +invocations due to limitations in the +.Dv linker.hints +file format. +.Sh SEE ALSO +.Xr devmatch 8 , +.Xr DRIVER_MODULE 9 , +.Xr module 9 +.Sh HISTORY +The macro +.Nm +appeared in +.Fx 11.0 . +.Sh AUTHORS +The PNP framework and +.Xr devmatch 8 +utility were written by +.An Warner Losh Aq Mt imp@FreeBSD.org . diff --git a/static/freebsd/man9/MODULE_VERSION.9 b/static/freebsd/man9/MODULE_VERSION.9 new file mode 100644 index 00000000..c35a7f0a --- /dev/null +++ b/static/freebsd/man9/MODULE_VERSION.9 @@ -0,0 +1,57 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2001 Alexander Langer +.\" +.\" 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 March 11, 2001 +.Dt MODULE_VERSION 9 +.Os +.Sh NAME +.Nm MODULE_VERSION +.Nd set kernel module version +.Sh SYNOPSIS +.In sys/param.h +.In sys/module.h +.Fn MODULE_VERSION "name" "int version" +.Sh DESCRIPTION +The +.Fn MODULE_VERSION +macro sets the version of the module called +.Fa name . +Other kernel modules can then depend on this module (see +.Xr MODULE_DEPEND 9 ) . +.Sh EXAMPLES +.Bd -literal +MODULE_VERSION(foo, 1); +.Ed +.Sh SEE ALSO +.Xr DECLARE_MODULE 9 , +.Xr module 9 , +.Xr MODULE_DEPEND 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Alexander Langer Aq Mt alex@FreeBSD.org . diff --git a/static/freebsd/man9/Makefile b/static/freebsd/man9/Makefile new file mode 100644 index 00000000..740d316d --- /dev/null +++ b/static/freebsd/man9/Makefile @@ -0,0 +1,3 @@ +MAN = $(wildcard *.9) + +include ../../mandoc.mk diff --git a/static/freebsd/man9/OF_child.9 b/static/freebsd/man9/OF_child.9 new file mode 100644 index 00000000..43c9caa0 --- /dev/null +++ b/static/freebsd/man9/OF_child.9 @@ -0,0 +1,73 @@ +.\" +.\" Copyright (c) 2018 Oleksandr Tymoshenko +.\" +.\" 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 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 April 9, 2018 +.Dt OF_CHILD 9 +.Os +.Sh NAME +.Nm OF_child , +.Nm OF_parent , +.Nm OF_peer +.Nd navigate device tree +.Sh SYNOPSIS +.In dev/ofw/ofw_bus.h +.In dev/ofw/ofw_bus_subr.h +.Ft phandle_t +.Fn OF_child "phandle_t node" +.Ft phandle_t +.Fn OF_parent "phandle_t node" +.Ft phandle_t +.Fn OF_peer "phandle_t node" +.Sh DESCRIPTION +.Fn OF_child +returns the phandle value of the first child of the +.Fa node . +Zero is returned if there are no child nodes. +.Pp +.Fn OF_parent +returns the phandle for the parent of the +.Fa node . +Zero is returned if +.Fa node +is the root node. +.Pp +.Fn OF_peer +returns the phandle value of the next sibling of the +.Fa node . +Zero is returned if there is no sibling node. +.Sh EXAMPLES +.Bd -literal +phandle_t node, child; + ... +for (child = OF_child(node); child != 0; child = OF_peer(child) { + ... +} +.Ed +.Sh SEE ALSO +.Xr OF_finddevice 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org . diff --git a/static/freebsd/man9/OF_device_from_xref.9 b/static/freebsd/man9/OF_device_from_xref.9 new file mode 100644 index 00000000..0b858866 --- /dev/null +++ b/static/freebsd/man9/OF_device_from_xref.9 @@ -0,0 +1,100 @@ +.\" +.\" Copyright (c) 2018 Oleksandr Tymoshenko +.\" +.\" 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 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 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 +.Fn OF_xref_from_device "device_t dev" +.Sh DESCRIPTION +When a device tree node references another node, the driver may +need to get a device_t instance associated with the referenced node. +For instance, an Ethernet driver accessing a PHY device. +To make this possible, the kernel maintains a table that +maps effective handles to device_t instances. +.Pp +.Fn OF_device_register_xref +adds a map entry from the effective phandle +.Fa xref +to device +.Fa dev . +If a mapping entry for +.Fa xref +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 . +If no such mapping exists, the function returns NULL. +.Pp +.Fn OF_xref_from_device +returns the effective phandle associated with the device +.Fa dev . +If no such mapping exists, the function returns 0. +.Sh EXAMPLES +.Bd -literal + static int + acmephy_attach(device_t dev) + { + phandle_t node; + + /* PHY node is referenced from eth device, register it */ + node = ofw_bus_get_node(dev); + OF_device_register_xref(OF_xref_from_node(node), dev); + + return (0); + } +.Ed +.Sh SEE ALSO +.Xr OF_node_to_xref 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org . diff --git a/static/freebsd/man9/OF_finddevice.9 b/static/freebsd/man9/OF_finddevice.9 new file mode 100644 index 00000000..cb24f4af --- /dev/null +++ b/static/freebsd/man9/OF_finddevice.9 @@ -0,0 +1,71 @@ +.\" +.\" Copyright (c) 2018 Oleksandr Tymoshenko +.\" +.\" 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 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 April 9, 2018 +.Dt OF_FINDDEVICE 9 +.Os +.Sh NAME +.Nm OF_finddevice +.Nd find node in device tree +.Sh SYNOPSIS +.In dev/ofw/ofw_bus.h +.In dev/ofw/ofw_bus_subr.h +.Ft phandle_t +.Fn OF_finddevice "const char *path" +.Sh DESCRIPTION +.Fn OF_finddevice +returns the phandle for the node specified by the +.Fa path . +Returns -1 if the path cannot be found in the tree. +.Sh EXAMPLES +.Bd -literal + phandle_t root, i2c; + + root = OF_finddevice("/"); + i2c = OF_finddevice("/soc/axi/i2c@a0e0000"); + if (i2c != -1) { + ... + } +.Ed +.Sh SEE ALSO +.Xr OF_child 9 , +.Xr OF_parent 9 , +.Xr OF_peer 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org . +.Sh CAVEATS +The return value should only be checked with equality +operators (equal to, not equal to) and not relational comparison +(less than, greater than ). +There is a discrepancy between IEEE 1275 standard and +.Fx Ns 's +internal representation of a phandle: IEEE 1275 +requires the return value of this function to be -1 if the path +is not found. +But phandle_t is an unsigned type, so it cannot +be relationally compared with -1 or 0, this comparison +is always true or always false. diff --git a/static/freebsd/man9/OF_getprop.9 b/static/freebsd/man9/OF_getprop.9 new file mode 100644 index 00000000..8c93d92b --- /dev/null +++ b/static/freebsd/man9/OF_getprop.9 @@ -0,0 +1,354 @@ +.\" +.\" Copyright (c) 2018 Oleksandr Tymoshenko +.\" +.\" 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 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 April 16, 2026 +.Dt OF_GETPROP 9 +.Os +.Sh NAME +.Nm OF_getprop , +.Nm OF_getproplen , +.Nm OF_getencprop , +.Nm OF_hasprop , +.Nm OF_searchprop , +.Nm OF_searchencprop , +.Nm OF_getprop_alloc , +.Nm OF_getencprop_alloc , +.Nm OF_getprop_alloc_multi , +.Nm OF_getencprop_alloc_multi , +.Nm OF_prop_free , +.Nm OF_nextprop , +.Nm OF_setprop +.Nd access properties of device tree node +.Sh SYNOPSIS +.In dev/ofw/ofw_bus.h +.In dev/ofw/ofw_bus_subr.h +.Ft ssize_t +.Fn OF_getproplen "phandle_t node" "const char *propname" +.Ft ssize_t +.Fn OF_getprop "phandle_t node" "const char *propname" \ +"void *buf" "size_t len" +.Ft ssize_t +.Fn OF_getencprop "phandle_t node" "const char *prop" \ +"pcell_t *buf" "size_t len" +.Ft bool +.Fn OF_hasprop "phandle_t node" "const char *propname" +.Ft ssize_t +.Fn OF_searchprop "phandle_t node" "const char *propname" \ +"void *buf" "size_t len" +.Ft ssize_t +.Fn OF_searchencprop "phandle_t node" "const char *propname" \ +"pcell_t *buf" "size_t len" +.Ft ssize_t +.Fn OF_getprop_alloc "phandle_t node" "const char *propname" \ +"void **buf" +.Ft ssize_t +.Fn OF_getencprop_alloc "phandle_t node" "const char *propname" \ +"pcell_t **buf" +.Ft ssize_t +.Fn OF_getprop_alloc_multi "phandle_t node" "const char *propname" \ +"int elsz" "void **buf" +.Ft ssize_t +.Fn OF_getencprop_alloc_multi "phandle_t node" "const char *propname" \ +"int elsz" "pcell_t **buf" +.Ft void +.Fn OF_prop_free "void *buf" +.Ft int +.Fn OF_nextprop "phandle_t node" "const char *propname" \ +"char *buf" "size_t len" +.Ft int +.Fn OF_setprop "phandle_t node" "const char *propname" \ +"const void *buf" "size_t len" +.Sh DESCRIPTION +Device nodes can have associated properties. +Properties consist of a name and a value. +A name is a human-readable string from 1 to 31 characters long. +A value is an array of zero or more bytes that encode certain +information. +The meaning of that bytes depends on how drivers interpret them. +Properties can encode byte arrays, text strings, unsigned 32-bit +values or any combination of these types. +.Pp +Property with a zero-length value usually represents boolean +information. +If the property is present, it signifies true, otherwise false. +.Pp +A byte array is encoded as a sequence of bytes and represents +values like MAC addresses. +.Pp +A text string is a sequence of n printable characters. +It is encoded as a byte array of length n + 1 bytes with +characters represented as bytes plus a terminating null character. +.Pp +Unsigned 32-bit values, also sometimes called cells, are +encoded as a sequence of 4 bytes in big-endian order. +.Pp +.Fn OF_getproplen +returns either the length of the value associated with the property +.Fa propname +in the node identified by +.Fa node , +or 0 if the property exists but has no associated value. +If +.Fa propname +does not exist, -1 is returned. +.Pp +.Fn OF_getprop +copies a maximum of +.Fa len +bytes from the value associated with the property +.Fa propname +of the device node +.Fa node +into the memory specified by +.Fa buf . +Returns the actual size of the value or -1 if the +property does not exist. +.Pp +.Fn OF_getencprop +copies a maximum of +.Fa len +bytes into memory specified by +.Fa buf , +then converts cell values from big-endian to host byte order. +Returns the actual size of the value in bytes, or -1 +if the property does not exist. +.Fa len +must be a multiple of 4. +.Pp +.Fn OF_hasprop +returns +.Dv true +if the device node +.Fa node +has a property specified by +.Fa propname , +and +.Dv false +if the property does not exist. +.Pp +.Fn OF_searchprop +recursively looks for the property specified by +.Fa propname +starting with the device node +.Fa node +followed by the parent node and up to the root node. +If the property is found, the function copies a maximum of +.Fa len +bytes of the value associated with the property +into the memory specified by +.Fa buf . +Returns the actual size in bytes of the value, +or -1 if the property does not exist. +.Pp +.Fn OF_searchencprop +recursively looks for the property specified by +.Fa propname +starting with the device node +.Fa node +followed by the parent node and up to the root node. +If the property is found, the function copies a maximum of +.Fa len +bytes of the value associated with the property +into the memory specified by +.Fa buf , +then converts cell values from big-endian to host byte order. +Returns the actual size in bytes of the value, +or -1 if the property does not exist. +.Pp +.Fn OF_getprop_alloc +allocates memory large enough to hold the +value associated with the property +.Fa propname +of the device node +.Fa node +and copies the value into the newly allocated memory region. +Returns the actual size of the value and stores +the address of the allocated memory in +.Fa *buf . +If the property has a zero-sized value +.Fa *buf +is set NULL. +Returns -1 if the property does not exist or +memory allocation failed. +Allocated memory should be released when no longer required +by calling +.Fn OF_prop_free . +The function might sleep when allocating memory. +.Pp +.Fn OF_getencprop_alloc +allocates enough memory to hold the +value associated with the property +.Fa propname +of the device node +.Fa node , +copies the value into the newly allocated memory region, and +then converts cell values from big-endian to host byte +order. +The actual size of the value is returned and the +address of allocated memory is stored in +.Fa *buf . +If the property has zero-length value, +.Fa *buf +is set to NULL. +Returns -1 if the property does not exist or +memory allocation failed or the size of the value is not +divisible by a cell size (4 bytes). +Allocated memory should be released when no longer required +by calling +.Fn OF_prop_free . +The function might sleep when allocating memory. +.Pp +.Fn OF_getprop_alloc_multi +allocates memory large enough to hold the +value associated with the property +.Fa propname +of the device node +.Fa node +and copies the value into the newly allocated memory region. +The value is expected to be an array of zero or more elements +.Fa elsz +bytes long. +Returns the number of elements in the value and stores +the address of the allocated memory in +.Fa *buf . +If the property has a zero-sized value +.Fa *buf +is set NULL. +Returns -1 if the property does not exist or +memory allocation failed or the size of the value is not +divisible by +.Fa elsz . +Allocated memory should be released when no longer required +by calling +.Fn OF_prop_free . +The function might sleep when allocating memory. +.Pp +.Fn OF_getencprop_alloc_multi +allocates memory large enough to hold the +value associated with the property +.Fa propname +of the device node +.Fa node +and copies the value into the newly allocated memory region, and +then converts cell values from big-endian to host byte +order. +The value is expected to be an array of zero or more elements +.Fa elsz +bytes long. +Returns the number of elements in the value and stores +the address of the allocated memory in +.Fa *buf . +If the property has a zero-sized value +.Fa *buf +is set NULL. +Returns -1 if the property does not exist or +memory allocation failed or the size of the value is not +divisible by +.Fa elsz . +Allocated memory should be released when no longer required +by calling +.Fn OF_prop_free . +The function might sleep when allocating memory. +.Pp +.Fn OF_prop_free +releases memory at +.Fa buf +that was allocated by +.Fn OF_getprop_alloc , +.Fn OF_getencprop_alloc , +.Fn OF_getprop_alloc_multi , +.Fn OF_getencprop_alloc_multi . +.Pp +.Fn OF_nextprop +copies a maximum of +.Fa size +bytes of the name of the property following the +.Fa propname +property into +.Fa buf . +If +.Fa propname +is NULL, the function copies the name of the first property of the +device node +.Fa node . +.Fn OF_nextprop +returns -1 if +.Fa propname +is invalid or there is an internal error, 0 if there are no more +properties after +.Fa propname , +or 1 otherwise. +.Pp +.Fn OF_setprop +sets the value of the property +.Fa propname +in the device node +.Fa node +to the value beginning at the address specified by +.Fa buf +and running for +.Fa len +bytes. +If the property does not exist, the function tries to create +it. +.Fn OF_setprop +returns the actual size of the new value, or -1 if the +property value cannot be changed or the new property +cannot be created. +.Sh EXAMPLES +.Bd -literal + phandle_t node; + phandle_t hdmixref, hdminode; + device_t hdmi; + uint8_t mac[6]; + char *model; + + /* + * Get a byte array property + */ + if (OF_getprop(node, "eth,hwaddr", mac, sizeof(mac)) != sizeof(mac)) + return; + + /* + * Get internal node reference and device associated with it + */ + if (OF_getencprop(node, "hdmi", &hdmixref) <= 0) + return; + hdmi = OF_device_from_xref(hdmixref); + + /* + * Get string value of model property of HDMI framer node + */ + hdminode = OF_node_from_xref(hdmixref); + if (OF_getprop_alloc(hdminode, "model", (void **)&model) <= 0) + return; +.Ed +.Sh SEE ALSO +.Xr OF_device_from_xref 9 , +.Xr OF_node_from_xref 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org . diff --git a/static/freebsd/man9/OF_node_from_xref.9 b/static/freebsd/man9/OF_node_from_xref.9 new file mode 100644 index 00000000..755c8295 --- /dev/null +++ b/static/freebsd/man9/OF_node_from_xref.9 @@ -0,0 +1,99 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2018 Oleksandr Tymoshenko +.\" +.\" 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 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 April 9, 2018 +.Dt OF_NODE_FROM_XREF 9 +.Os +.Sh NAME +.Nm OF_node_from_xref , +.Nm OF_xref_from_node +.Nd convert between kernel phandle and effective phandle +.Sh SYNOPSIS +.In dev/ofw/ofw_bus.h +.In dev/ofw/ofw_bus_subr.h +.Ft phandle_t +.Fn OF_node_from_xref "phandle_t xref" +.Ft phandle_t +.Fn OF_xref_from_node "phandle_t node" +.Sh DESCRIPTION +Some OpenFirmware implementations (FDT, IBM) have a concept +of effective phandle or xrefs. +They are used to cross-reference device tree nodes. +For instance, a framebuffer controller may refer to a GPIO +controller and pin that controls the backlight. +In this example, the GPIO node would have a cell (32-bit integer) +property with a reserved name like "phandle" or "linux,phandle" +whose value uniquely identifies the node. +The actual name depends on the implementation. +The framebuffer node would have a property with the name +described by device bindings (device-specific set of properties). +It can be a cell property or a combined property with one part +of it being a cell. +The value of the framebuffer node's property would be the same +as the value of the GPIO "phandle" property so it can be said +that the framebuffer node refers to the GPIO node. +The kernel uses internal logic to assign unique identifiers +to the device tree nodes, and these values do not match +the values of "phandle" properties. +.Fn OF_node_from_xref +and +.Fn OF_xref_from_node +are used to perform conversion between these two kinds of node +identifiers. +.Pp +.Fn OF_node_from_xref +returns the kernel phandle for the effective phandle +.Fa xref . +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_node +returns the effective phandle for the kernel phandle +.Fa node . +If one cannot be found or the OpenFirmware implementation +does not support effective phandles, the function returns +the input value. +.Sh EXAMPLES +.Bd -literal + phandle_t panelnode, panelxref; + char *model; + + if (OF_getencprop(node, "lcd-panel", &panelxref) <= 0) + return; + + panelnode = OF_node_from_xref(panelxref); + if (OF_getprop_alloc(hdminode, "model", (void **)&model) <= 0) + return; +.Ed +.Sh SEE ALSO +.Xr OF_device_from_xref 9 , +.Xr OF_device_register_xref 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org . diff --git a/static/freebsd/man9/OF_package_to_path.9 b/static/freebsd/man9/OF_package_to_path.9 new file mode 100644 index 00000000..d358ec87 --- /dev/null +++ b/static/freebsd/man9/OF_package_to_path.9 @@ -0,0 +1,51 @@ +.\" +.\" Copyright (c) 2018 Oleksandr Tymoshenko +.\" +.\" 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 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 April 9, 2018 +.Dt OF_PACKAGE_TO_PATH 9 +.Os +.Sh NAME +.Nm OF_package_to_path +.Nd get fully qualified path to a device tree node +.Sh SYNOPSIS +.In dev/ofw/ofw_bus.h +.In dev/ofw/ofw_bus_subr.h +.Ft ssize_t +.Fn OF_package_to_path "phandle_t node" "char *buf" "size_t len" +.Sh DESCRIPTION +.Fn OF_package_to_path +copies at most +.Fa len +bytes of the fully qualified path to the device tree node +.Fa node +into the memory specified by +.Fa buf . +The function returns the number of bytes copied or -1 in case of the error. +.Sh SEE ALSO +.Xr OF_finddevice 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org . diff --git a/static/freebsd/man9/PCI_IOV_ADD_VF.9 b/static/freebsd/man9/PCI_IOV_ADD_VF.9 new file mode 100644 index 00000000..95bf5a21 --- /dev/null +++ b/static/freebsd/man9/PCI_IOV_ADD_VF.9 @@ -0,0 +1,110 @@ +.\" +.\" Copyright (c) 2014 Sandvine Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY 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 May 28, 2015 +.Dt PCI_IOV_ADD_VF 9 +.Os +.Sh NAME +.Nm PCI_IOV_ADD_VF +.Nd inform a PF driver that a VF is being created +.Sh SYNOPSIS +.In sys/bus.h +.In sys/stdarg.h +.In sys/nv.h +.In dev/pci/pci_iov.h +.Ft int +.Fn PCI_IOV_ADD_VF "device_t dev" "uint16_t vfnum" "const nvlist_t *vf_config" +.Sh DESCRIPTION +The +.Fn PCI_IOV_ADD_VF +method is called by the PCI Single-Root I/O Virtualization +.Pq SR-IOV +infrastructure when it is initializing a new Virtual Function (VF) as a child +of the given Physical Function (PF) device. +This method will not be called until a successful call to +.Xr PCI_IOV_INIT 9 +has been made. +It is not guaranteed that this method will be called following a successful call +to +.Xr PCI_IOV_INIT 9 . +If the infrastructure encounters a failure to allocate resources following the +call to +.Xr PCI_IOV_INIT 9 , +the VF creation will be aborted and +.Xr PCI_IOV_UNINIT 9 +will be called immediately without any preceding calls to +.Nm . +.Pp +The index of the VF being initialized is passed in the +.Fa vfnum +argument. +VFs are always numbered sequentially starting at 0. +.Pp +If the driver requested device-specific configuration parameters via a VF schema +in its call to +.Xr pci_iov_attach 9 , +those parameters will be contained in the +.Pa vf_config +argument. +All configuration parameters that were either set as required parameters or that +had a default value set in the VF schema are guaranteed to be present in +.Fa vf_config . +Configuration parameters that were neither set as required nor were given a +default value are optional and may or may not be present in +.Fa vf_config . +.Fa vf_config +will not contain any configuration parameters that were not specified in the VF +schema. +All configuration parameters will have the correct type and will be in the range +of valid values specified in the schema. +.Pp +Note that it is possible for the user to set different configuration values on +different VF devices that are children of the same PF. +The PF driver must not cache configuration parameters passed in previous calls +to +.Fn PCI_IOV_ADD_VF +for other VFs and apply those parameters to the current VF. +.Pp +This function will not be called twice for the same +.Fa vf_num +on the same PF device without +.Xr PCI_IOV_UNINIT 9 +and +.Xr PCI_IOV_INIT 9 +first being called, in that order. +.Sh RETURN VALUES +This method returns 0 on success, otherwise an appropriate error is returned. +If this method returns an error then the current VF device will be destroyed +but the rest of the VF devices will be created and SR-IOV will be enabled on +the PF. +.Sh SEE ALSO +.Xr nv 9 , +.Xr pci 9 , +.Xr PCI_IOV_INIT 9 , +.Xr pci_iov_schema 9 , +.Xr PCI_IOV_UNINIT 9 +.Sh AUTHORS +This manual page was written by +.An Ryan Stone Aq Mt rstone@FreeBSD.org . diff --git a/static/freebsd/man9/PCI_IOV_INIT.9 b/static/freebsd/man9/PCI_IOV_INIT.9 new file mode 100644 index 00000000..8ce94800 --- /dev/null +++ b/static/freebsd/man9/PCI_IOV_INIT.9 @@ -0,0 +1,83 @@ +.\" +.\" Copyright (c) 2014 Sandvine Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY 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 May 28, 2015 +.Dt PCI_IOV_INIT 9 +.Os +.Sh NAME +.Nm PCI_IOV_INIT +.Nd enable SR-IOV on a PF device +.Sh SYNOPSIS +.In sys/bus.h +.In sys/stdarg.h +.In sys/nv.h +.In dev/pci/pci_iov.h +.Ft int +.Fn PCI_IOV_INIT "device_t dev" "uint16_t num_vfs" "const nvlist_t *pf_config" +.Sh DESCRIPTION +The +.Fn PCI_IOV_INIT +method is called by the PCI Single-Root I/O Virtualization (SR-IOV) +infrastructure when the user requests that SR-IOV be enabled on a Physical +Function (PF). +The number of Virtual Functions (VFs) that will be created is passed to this +method in the +.Fa num_vfs +argument. +.Pp +If the driver requested device-specific PF configuration parameters via a PF +schema in its call to +.Xr pci_iov_attach 9 , +those parameters will be available in the +.Fa pf_config +argument. +All configuration parameters that were either set as required parameters or that +had a default value set in the PF schema are guaranteed to be present in +.Fa pf_config . +Configuration parameters that were neither set as required nor were given a +default value are optional and may or may not be present in +.Fa pf_config . +.Fa pf_config +will not contain any configuration parameters that were not specified in the PF +schema. +All configuration parameters will have the correct type and are in the range of +valid values specified in the schema. +.Pp +If this method returns successfully, then this method will not be called again +on the same device until after a call to +.Xr PCI_IOV_UNINIT 9 . +.Sh RETURN VALUES +Returns 0 on success, otherwise an appropriate error is returned. +If this method returns an error then the SR-IOV configuration will be aborted +and no VFs will be created. +.Sh SEE ALSO +.Xr nv 9 , +.Xr pci 9 , +.Xr PCI_IOV_ADD_VF 9 , +.Xr pci_iov_schema 9 , +.Xr PCI_IOV_UNINIT 9 +.Sh AUTHORS +This manual page was written by +.An Ryan Stone Aq Mt rstone@FreeBSD.org . diff --git a/static/freebsd/man9/PCI_IOV_UNINIT.9 b/static/freebsd/man9/PCI_IOV_UNINIT.9 new file mode 100644 index 00000000..800c2752 --- /dev/null +++ b/static/freebsd/man9/PCI_IOV_UNINIT.9 @@ -0,0 +1,61 @@ +.\" +.\" Copyright (c) 2014 Sandvine Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY 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 May 28, 2015 +.Dt PCI_IOV_UNINIT 9 +.Os +.Sh NAME +.Nm PCI_IOV_UNINIT +.Nd disable SR-IOV on a PF device +.Sh SYNOPSIS +.In sys/bus.h +.In dev/pci/pci_iov.h +.Ft void +.Fn PCI_IOV_UNINIT "device_t dev" +.Sh DESCRIPTION +The +.Fn PCI_IOV_UNINIT +method is called by the PCI Single-Root I/O Virtualization (SR-IOV) +infrastructure when the user requests that SR-IOV be disabled on a Physical +Function (PF). +When this method is called, the PF driver must release any SR-IOV-related +resources that it has allocated and disable any device-specific SR-IOV +configuration in the device. +.Pp +This method will only be called following a successful call to +.Xr PCI_IOV_INIT 9 . +It is not guaranteed that +.Xr PCI_IOV_ADD_VF 9 +will have been called for any Virtual Function (VF) after the call to +.Xr PCI_IOV_INIT 9 +and before the call to +.Nm . +.Sh SEE ALSO +.Xr pci 9 , +.Xr PCI_IOV_ADD_VF 9 , +.Xr PCI_IOV_INIT 9 +.Sh AUTHORS +This manual page was written by +.An Ryan Stone Aq Mt rstone@FreeBSD.org . diff --git a/static/freebsd/man9/PHOLD.9 b/static/freebsd/man9/PHOLD.9 new file mode 100644 index 00000000..57c0f522 --- /dev/null +++ b/static/freebsd/man9/PHOLD.9 @@ -0,0 +1,65 @@ +.\" Copyright (c) 2015 Mark Johnston +.\" +.\" 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 November 7, 2015 +.Dt PHOLD 9 +.Os +.Sh NAME +.Nm PHOLD +.Nd hold a process +.Sh SYNOPSIS +.In sys/proc.h +.Fn PHOLD "struct proc *p" +.Fn _PHOLD "struct proc *p" +.Fn PRELE "struct proc *p" +.Fn _PRELE "struct proc *p" +.Fn PROC_ASSERT_HELD "struct proc *p" +.Fn PROC_ASSERT_NOT_HELD "struct proc *p" +.Sh DESCRIPTION +The +.Fn PHOLD +macro increments the hold count of a process, and the +.Fn PRELE +macro decrements the hold count of a process. +.Pp +If a process with a non-zero hold count attempts to exit, it will sleep until +its hold count has reached zero before the kernel begins releasing resources +associated with the process. +Once a process has started exiting, it is invalid to increase its hold count. +Thus, callers must not attempt to hold a process that has the +.Dv P_WEXIT +flag set. +The VM daemon will not swap out the kernel stack of a thread belonging to a +process with a non-zero hold count. +.Pp +The +.Fn _PHOLD +and +.Fn _PRELE +macros are identical to +.Fn PHOLD +and +.Fn PRELE , +except that they must be called with the process lock held. +.Sh AUTHORS +This manual page was written by +.An Mark Johnston Aq Mt markj@FreeBSD.org . diff --git a/static/freebsd/man9/SDT.9 b/static/freebsd/man9/SDT.9 new file mode 100644 index 00000000..65d1c9dc --- /dev/null +++ b/static/freebsd/man9/SDT.9 @@ -0,0 +1,344 @@ +.\" Copyright (c) 2013-2015 Mark Johnston +.\" 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 April 18, 2015 +.Dt SDT 9 +.Os +.Sh NAME +.Nm SDT +.Nd a DTrace framework for adding statically-defined tracing probes +.Sh SYNOPSIS +.In sys/param.h +.In sys/queue.h +.In sys/sdt.h +.Fn SDT_PROVIDER_DECLARE prov +.Fn SDT_PROVIDER_DEFINE prov +.Fn SDT_PROBE_DECLARE prov mod func name +.Fn SDT_PROBE_DEFINE prov mod func name +.Fn SDT_PROBE_DEFINE0 prov mod func name +.Fn SDT_PROBE_DEFINE1 prov mod func name arg0 +.Fn SDT_PROBE_DEFINE2 prov mod func name arg0 arg1 +.Fn SDT_PROBE_DEFINE3 prov mod func name arg0 arg1 arg2 +.Fn SDT_PROBE_DEFINE4 prov mod func name arg0 arg1 arg2 arg3 +.Fn SDT_PROBE_DEFINE5 prov mod func name arg0 arg1 arg2 arg3 arg4 +.Fn SDT_PROBE_DEFINE6 prov mod func name arg0 arg1 arg2 arg3 arg4 arg5 +.Fn SDT_PROBE_DEFINE7 prov mod func name arg0 arg1 arg2 arg3 arg4 arg5 \ + arg6 +.Fn SDT_PROBE_DEFINE0_XLATE prov mod func name +.Fn SDT_PROBE_DEFINE1_XLATE prov mod func name arg0 xarg0 +.Fn SDT_PROBE_DEFINE2_XLATE prov mod func name arg0 xarg0 arg1 xarg1 +.Fn SDT_PROBE_DEFINE3_XLATE prov mod func name arg0 xarg0 arg1 xarg1 \ + arg2 xarg2 +.Fn SDT_PROBE_DEFINE4_XLATE prov mod func name arg0 xarg0 arg1 xarg1 \ + arg2 xarg2 arg3 xarg3 +.Fn SDT_PROBE_DEFINE5_XLATE prov mod func name arg0 xarg0 arg1 xarg1 \ + arg2 xarg2 arg3 xarg3 arg4 xarg4 +.Fn SDT_PROBE_DEFINE6_XLATE prov mod func name arg0 xarg0 arg1 xarg1 \ + arg2 xarg2 arg3 xarg3 arg4 xarg4 arg5 xarg5 +.Fn SDT_PROBE_DEFINE7_XLATE prov mod func name arg0 xarg0 arg1 xarg1 \ + arg2 xarg2 arg3 xarg3 arg4 xarg4 arg5 xarg5 arg6 xarg6 +.Fn SDT_PROBE0 prov mod func name +.Fn SDT_PROBE1 prov mod func name arg0 +.Fn SDT_PROBE2 prov mod func name arg0 arg1 +.Fn SDT_PROBE3 prov mod func name arg0 arg1 arg2 +.Fn SDT_PROBE4 prov mod func name arg0 arg1 arg2 arg3 +.Fn SDT_PROBE5 prov mod func name arg0 arg1 arg2 arg3 arg4 +.Fn SDT_PROBE6 prov mod func name arg0 arg1 arg2 arg3 arg4 arg5 +.Fn SDT_PROBE7 prov mod func name arg0 arg1 arg2 arg3 arg4 arg5 arg6 +.Sh DESCRIPTION +The +.Nm +macros allow programmers to define static trace points in kernel code. +These trace points are used by the +.Nm +framework to create DTrace probes, allowing the code to be instrumented +using +.Xr dtrace 1 . +By default, +.Nm +trace points are disabled and have no effect on the surrounding code. +When a DTrace probe corresponding to a given trace point is enabled, threads +that execute the trace point will call a handler and cause the probe to fire. +Moreover, trace points can take arguments, making it possible to pass data +to the DTrace framework when an enabled probe fires. +.Pp +Multiple trace points may correspond to a single DTrace probe, allowing +programmers to create DTrace probes that correspond to logical system events +rather than tying probes to specific code execution paths. +For instance, a DTrace probe corresponding to the arrival of an IP packet into +the network stack may be defined using two +.Nm +trace points: one for IPv4 packets and one for IPv6 packets. +.Pp +In addition to defining DTrace probes, the +.Nm +macros allow programmers to define new DTrace providers, making it possible to +namespace logically-related probes. +An example is FreeBSD's sctp provider, which contains +.Nm +probes for FreeBSD's +.Xr sctp 4 +implementation. +.Pp +The +.Fn SDT_PROVIDER_DECLARE +and +.Fn SDT_PROVIDER_DEFINE +macros are used respectively to declare and define a DTrace provider named +.Ar prov +with the +.Nm +framework. +A provider need only be defined once; however, the provider must be declared +before defining any +.Nm +probes belonging to that provider. +.Pp +Similarly, the +.Fn SDT_PROBE_DECLARE +and +.Fn SDT_PROBE_DEFINE* +macros are used to declare and define DTrace probes using the +.Nm +framework. +Once a probe has been defined, trace points for that probe may be added to +kernel code. +DTrace probe identifiers consist of a provider, module, function and name, all +of which may be specified in the +.Nm +probe definition. +Note that probes should not specify a module name: the module name of a probe is +used to determine whether or not it should be destroyed when a kernel module is +unloaded. +See the +.Sx BUGS +section. +Note in particular that probes must not be defined across multiple kernel +modules. +.Pp +If +.Ql - +character (dash) is wanted in a probe name, +then it should be represented as +.Ql __ +(double underscore) in the probe +.Ar name +parameter passed to various +.Fn SDT_* +macros, +because of technical reasons +(a dash is not valid in C identifiers). +.Pp +The +.Fn SDT_PROBE_DEFINE* +macros also allow programmers to declare the types of the arguments that are +passed to probes. +This is optional; if the argument types are omitted (through use of the +.Fn SDT_PROBE_DEFINE +macro), users wishing to make use of the arguments will have to manually cast +them to the correct types in their D scripts. +It is strongly recommended that probe definitions include a declaration of their +argument types. +.Pp +The +.Fn SDT_PROBE_DEFINE*_XLATE +macros are used for probes whose argument types are to be dynamically translated +to the types specified by the corresponding +.Ar xarg +arguments. +This is mainly useful when porting probe definitions from other operating +systems. +As seen by +.Xr dtrace 1 , +the arguments of a probe defined using these macros will have types which match +the +.Ar xarg +types in the probe definition. +However, the arguments passed in at the trace point will have types matching the +native argument types in the probe definition, and thus the native type is +dynamically translated to the translated type. +So long as an appropriate translator is defined in +.Pa /usr/lib/dtrace , +scripts making use of the probe need not concern themselves with the underlying +type of a given +.Nm +probe argument. +.Pp +The +.Fn SDT_PROBE* +macros are used to create +.Nm +trace points. +They are meant to be added to executable code and can be used to instrument the +code in which they are called. +.Sh PROVIDERS +A number of kernel DTrace providers are available. +In general, these providers define stable interfaces and should be treated as +such: existing D scripts may be broken if a probe is renamed or its arguments +are modified. +However, it is often useful to define ad-hoc +.Nm +probes for debugging a subsystem or driver. +Similarly, a developer may wish to provide a group of +.Nm +probes without committing to their future stability. +Such probes should be added to the +.Ql sdt +provider instead of defining a new provider. +.Sh EXAMPLES +The DTrace providers available on the current system can be listed with +.Bd -literal -offset indent +dtrace -l | sed 1d | awk '{print $2}' | sort -u +.Ed +.Pp +A detailed list of the probes offered by a given provider can be obtained by +specifying the provider using the +.Fl P +flag. +For example, to view the probes and argument types for the +.Ql sched +provider, run +.Bd -literal -offset indent +dtrace -lv -P sched +.Ed +.Pp +The following probe definition will create a DTrace probe called +.Ql icmp:::receive-unreachable , +which would hypothetically be triggered when the kernel receives an ICMP packet +of type Destination Unreachable: +.Bd -literal -offset indent +SDT_PROVIDER_DECLARE(icmp); + +SDT_PROBE_DEFINE1(icmp, , , receive__unreachable, + "struct icmp *"); + +.Ed +This particular probe would take a single argument: a pointer to the struct +containing the ICMP header for the packet. +Note that the module name of this probe is not specified. +.Pp +Consider a DTrace probe which fires when the network stack receives an IP +packet. +Such a probe would be defined by multiple tracepoints: +.Bd -literal -offset indent +SDT_PROBE_DEFINE3(ip, , , receive, "struct ifnet *", + "struct ip *", "struct ip6_hdr *"); + +int +ip_input(struct mbuf *m) +{ + struct ip *ip; + ... + ip = mtod(m, struct ip *); + SDT_PROBE3(ip, , , receive, m->m_pkthdr.rcvif, ip, NULL); + ... +} + +int +ip6_input(struct mbuf *m) +{ + struct ip6_hdr *ip6; + ... + ip6 = mtod(m, struct ip6_hdr *); + SDT_PROBE3(ip, , , receive, m->m_pkthdr.rcvif, NULL, ip6); + ... +} + +.Ed +In particular, the probe should fire when the kernel receives either an IPv4 +packet or an IPv6 packet. +.Pp +Consider the ICMP probe discussed above. +We note that its second argument is of type +.Ar struct icmp , +which is a type defined in the FreeBSD kernel to represent the ICMP header of +an ICMP packet, defined in RFC 792. +Linux has a corresponding type, +.Ar struct icmphdr , +for the same purpose, but its field names differ from FreeBSD's +.Ar struct icmp . +Similarly, illumos defines the +.Ar icmph_t +type, again with different field names. +Even with the +.Ql icmp:::pkt-receive +probes defined in all three operating systems, +one would still have to write OS-specific scripts to extract a given field out +of the ICMP header argument. +Dynamically-translated types solve this problem: one can define an +OS-independent +.Xr c 7 +struct to represent an ICMP header, say +.Ar struct icmp_hdr_dt , +and define translators from each of the three OS-specific types to +.Ar struct icmp_hdr_dt , +all in the +.Xr dtrace 1 +library path. +Then the FreeBSD probe above can be defined with: +.Bd -literal -offset indent +SDT_PROBE_DEFINE1_XLATE(ip, , , receive, "struct icmp *", + "struct icmp_hdr_dt *"); +.Ed +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr dtrace_io 4 , +.Xr dtrace_ip 4 , +.Xr dtrace_proc 4 , +.Xr dtrace_sched 4 , +.Xr dtrace_tcp 4 , +.Xr dtrace_udp 4 +.Sh AUTHORS +.An -nosplit +DTrace and the +.Nm +framework were originally ported to FreeBSD from Solaris by +.An John Birrell Aq Mt jb@FreeBSD.org . +This manual page was written by +.An Mark Johnston Aq Mt markj@FreeBSD.org . +.Sh BUGS +The +.Nm +macros allow the module and function names of a probe to be specified as part of +a probe definition. +The DTrace framework uses the module name of probes to determine which probes +should be destroyed when a kernel module is unloaded, so the module +name of a probe should match the name of the module in which its defined. +.Nm +will set the module name properly if it is left unspecified in the probe +definition; see the +.Sx EXAMPLES +section. +.Pp +One of the goals of the original +.Nm +implementation (and by extension, of FreeBSD's port) is that inactive +.Nm +probes should have no performance impact. +This is unfortunately not the case; +.Nm +trace points will add a small but non-zero amount of latency to the code +in which they are defined. +A more sophisticated implementation of the probes will help alleviate this +problem. diff --git a/static/freebsd/man9/SYSCALL_MODULE.9 b/static/freebsd/man9/SYSCALL_MODULE.9 new file mode 100644 index 00000000..a6d5349b --- /dev/null +++ b/static/freebsd/man9/SYSCALL_MODULE.9 @@ -0,0 +1,97 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2001 Alexander Langer +.\" +.\" 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 June 15, 2023 +.Dt SYSCALL_MODULE 9 +.Os +.Sh NAME +.Nm SYSCALL_MODULE +.Nd syscall kernel module declaration macro +.Sh SYNOPSIS +.In sys/param.h +.In sys/kernel.h +.In sys/proc.h +.In sys/module.h +.In sys/sysent.h +.Fn SYSCALL_MODULE name "int *offset" "struct sysent *new_sysent" "modeventhand_t evh" "void *arg" +.Sh DESCRIPTION +The +.Fn SYSCALL_MODULE +macro declares a new syscall. +.Fn SYSCALL_MODULE +expands into a kernel module declaration with name +.Ql sys/ Ns Fa name . +.Pp +The rest of the arguments expected by this macro are: +.Bl -tag -width ".Fa new_sysent" +.It Fa offset +A pointer to an +.Vt int +which saves the offset in +.Vt "struct sysent" +where the syscall is allocated. +If the location pointed to by +.Fa offset +holds a non 0 number it will be used if possible. +If it holds 0 then one will be assigned. +.It Fa new_sysent +is a pointer to a structure that specifies the function implementing +the syscall and the number of arguments this function needs (see +.In sys/sysent.h ) . +.It Fa evh +A pointer to the kernel module event handler function with the argument +.Fa arg . +Please refer to +.Xr module 9 +for more information. +.It Fa arg +The argument passed to the callback functions of the +.Fa evh +event handler when it is called. +.El +.Pp +The syscall number assigned to the module can be retrieved using the +.Xr modstat 2 +and +.Xr modfind 2 +system calls. +The MACRO +.Fn SYSCALL_MODULE_HELPER +includes +.Fn SYSCALL_MODULE +and much of its boilerplate code. +.Sh EXAMPLES +A minimal example for a syscall module can be found in +.Pa /usr/share/examples/kld/syscall/module/syscall.c . +.Sh SEE ALSO +.Xr module 9 +.Pp +.Pa /usr/share/examples/kld/syscall/module/syscall.c +.Sh AUTHORS +This manual page was written by +.An Alexander Langer Aq Mt alex@FreeBSD.org . diff --git a/static/freebsd/man9/SYSINIT.9 b/static/freebsd/man9/SYSINIT.9 new file mode 100644 index 00000000..ae360a95 --- /dev/null +++ b/static/freebsd/man9/SYSINIT.9 @@ -0,0 +1,162 @@ +.\" Copyright (c) 2003 Hiten M. Pandya +.\" 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 December 1, 2010 +.Dt SYSINIT 9 +.Os +.Sh NAME +.Nm SYSINIT , +.Nm SYSUNINIT +.Nd a framework for dynamic kernel initialization +.Sh SYNOPSIS +.In sys/param.h +.In sys/kernel.h +.Fn SYSINIT "uniquifier" "enum sysinit_sub_id subsystem" "enum sysinit_elem_order order" "sysinit_cfunc_t func" "const void *ident" +.Fn SYSUNINIT "uniquifier" "enum sysinit_sub_id subsystem" "enum sysinit_elem_order order" "sysinit_cfunc_t func" "const void *ident" +.Sh DESCRIPTION +.Nm +is a mechanism for scheduling the execution of initialization and teardown +routines. +This is similar to init and fini routines with the addition of explicit +ordering metadata. +It allows runtime ordering of subsystem initialization in the kernel as well +as kernel modules (KLDs). +.Pp +The +.Fn SYSINIT +macro creates a +.Vt struct sysinit +and stores it in a startup linker set. +The +.Vt struct sysinit +type as well as the subsystem identifier constants +.Pq Dv SI_SUB_* +and initialization ordering constants +.Pq Dv SI_ORDER_* +are defined in +.In sys/kernel.h : +.Bd -literal +struct sysinit { + enum sysinit_sub_id subsystem; /* subsystem identifier*/ + enum sysinit_elem_order order; /* init order within subsystem*/ + SLIST_ENTRY(sysinit) next; /* singly-linked list */ + sysinit_cfunc_t func; /* function */ + const void *udata; /* multiplexer/argument */ +}; +.Ed +.Pp +The +.Fn SYSINIT +macro takes a +.Fa uniquifier +argument to identify the particular function dispatch data, +the +.Fa subsystem +type of startup interface, the subsystem element +.Fa order +of initialization within the subsystem, the +.Fa func +function to call, +and the data specified in +.Fa ident +argument to pass the function. +.Pp +The +.Fn SYSUNINIT +macro behaves similarly to the +.Fn SYSINIT +macro except that it adds the data to a shutdown linker set. +.Pp +The startup linker set for the kernel is scanned during boot to build a +sorted list of initialization routines. +The initialization routines are then executed in the sorted order. +The +.Fa subsystem +is used as the primary key and is sorted in ascending order. +The +.Fa order +is used as the secondary key and is sorted in ascending order. +The relative order of two routines that have the same +.Fa subsystem +and +.Fa order +is undefined. +.Pp +The startup linker sets for modules that are loaded together with the kernel +by the boot loader are scanned during the +.Dv SI_SUB_KLD +subsystem initialization. +These modules' initialization routines are sorted and merged into the kernel's +list of startup routines and are executed during boot along with the kernel's +initialization routines. +Note that this has the effect that any initialization routines in a kernel +module that are scheduled earlier than +.Dv SI_SUB_KLD +are not executed until after +.Dv SI_SUB_KLD +during boot. +.Pp +The startup linker set for a kernel module loaded at runtime via +.Xr kldload 2 +is scanned, sorted, and executed when the module is loaded. +.Pp +The shutdown linker set for a kernel module is scanned, sorted, and executed +when a kernel module is unloaded. +The teardown routines are sorted in the reverse order of the initialization +routines. +The teardown routines of the kernel and any loaded modules are +.Sy not +executed during shutdown. +.Sh EXAMPLES +This example shows the SYSINIT which displays the copyright notice during boot: +.Bd -literal -offset indent +static void +print_caddr_t(void *data) +{ + printf("%s", (char *)data); +} +SYSINIT(announce, SI_SUB_COPYRIGHT, SI_ORDER_FIRST, print_caddr_t, + copyright); +.Ed +.Sh SEE ALSO +.Xr kld 4 , +.Xr DECLARE_MODULE 9 , +.Xr DEV_MODULE 9 , +.Xr DRIVER_MODULE 9 , +.Xr MTX_SYSINIT 9 , +.Xr SYSCALL_MODULE 9 +.Sh HISTORY +The +.Nm +framework first appeared in +.Fx 2.2 . +.Sh AUTHORS +.An -nosplit +The +.Nm +framework was written by +.An Terrence Lambert Aq Mt terry@FreeBSD.org . +.Pp +This manual page was written by +.An Hiten Pandya Aq Mt hmp@FreeBSD.org . diff --git a/static/freebsd/man9/VFS.9 b/static/freebsd/man9/VFS.9 new file mode 100644 index 00000000..6ea6570b --- /dev/null +++ b/static/freebsd/man9/VFS.9 @@ -0,0 +1,59 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 November 3, 2025 +.Dt VFS 9 +.Os +.Sh NAME +.Nm VFS +.Nd kernel interface to file systems +.Sh DESCRIPTION +Calls used to set or query file systems for settings or information. +.Pp +File systems that do not implement a VFS operation should use the appropriate +.Fa vfs_std +function from +.Pa src/sys/kern/vfs_default.c +rather than implementing empty functions or casting to +.Fa eopnotsupp . +.Sh SEE ALSO +.Xr dtrace_vfs 4 , +.Xr VFS_CHECKEXP 9 , +.Xr VFS_FHTOVP 9 , +.Xr VFS_MOUNT 9 , +.Xr VFS_QUOTACTL 9 , +.Xr VFS_SET 9 , +.Xr VFS_STATFS 9 , +.Xr VFS_SYNC 9 , +.Xr VFS_UNMOUNT 9 , +.Xr VFS_VGET 9 , +.Xr vnode 9 , +.Xr VOP_VPTOFH 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/VFS_CHECKEXP.9 b/static/freebsd/man9/VFS_CHECKEXP.9 new file mode 100644 index 00000000..e374555f --- /dev/null +++ b/static/freebsd/man9/VFS_CHECKEXP.9 @@ -0,0 +1,96 @@ +.\" +.\" Copyright (c) 1999 Alfred Perlstein +.\" +.\" 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 condition +.\" is met: +.\" Redistributions of source code must retain the above copyright +.\" notice, this condition and the following disclaimer. +.\" +.\" 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 June 17, 2020 +.Dt VFS_CHECKEXP 9 +.Os +.Sh NAME +.Nm VFS_CHECKEXP +.Nd check if a file system is exported to a client +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.Ft int +.Fo VFS_CHECKEXP +.Fa "struct mount *mp" +.Fa "struct sockaddr *nam" +.Fa "uint64_t *exflagsp" +.Fa "struct ucred **credanonp" +.Fa "int *numsecflavor" +.Fa "int *secflavors" +.Fc +.Sh DESCRIPTION +The +.Fn VFS_CHECKEXP +macro is used by the NFS server to check if a mount point is exported +to a client. +.Pp +The arguments it expects are: +.Bl -tag -width numsecflavors +.It Fa mp +The mount point to be checked. +.It Fa nam +An mbuf containing the network address of the client. +.It Fa exflagsp +Return parameter for the export flags for this client. +.It Fa credanonp +Return parameter for the anonymous credentials for this client. +.It Fa numsecflavors +Return value for the number of security flavors for this client. +.It Fa secflavors +Must be an array of size MAXSECFLAVORS, in which the security flavors +for this client are returned. +.El +.Pp +The +.Fn VFS_CHECKEXP +macro should be called on a file system's mount structure to determine if it +is exported to a client whose address is contained in +.Fa nam . +.Pp +It is called in the NFS server once a vnode for a file handle has been +acquired, in order to determine what access the client is allowed on +the file system the vnode resides in. +For NFSv4, it is also called whenever the lookup operation crosses a +server file system mount point, to update the access information. +.Pp +The operation is file system specific, but is normally handled by +the default ``vfs_stdcheckexp''. +.Sh RETURN VALUES +The export flags, anonymous credentials and security flavors specific to the +client +will be returned in +.Fa *exflagsp , +.Fa *credanonp , +.Fa *numsecflavors +and +.Fa *secflavors . +.Sh SEE ALSO +.Xr VFS 9 , +.Xr VFS_FHTOVP 9 , +.Xr vnode 9 , +.Xr VOP_VPTOFH 9 +.Sh AUTHORS +This manual page was written by +.An Alfred Perlstein . diff --git a/static/freebsd/man9/VFS_FHTOVP.9 b/static/freebsd/man9/VFS_FHTOVP.9 new file mode 100644 index 00000000..6eb9061b --- /dev/null +++ b/static/freebsd/man9/VFS_FHTOVP.9 @@ -0,0 +1,89 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 May 19, 2019 +.Dt VFS_FHTOVP 9 +.Os +.Sh NAME +.Nm VFS_FHTOVP +.Nd turn an NFS filehandle into a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.In sys/vnode.h +.Ft int +.Fn VFS_FHTOVP "struct mount *mp" "struct fid *fhp" "int flags" "struct vnode **vpp" +.Sh DESCRIPTION +The +.Fn VFS_FHTOVP +macro is used by the NFS server to turn an NFS filehandle into a vnode. +.Pp +The arguments it expects are: +.Bl -tag -width flags +.It Fa mp +The file system. +.It Fa fhp +The filehandle to convert. +.It Fa flags +Additional locking flags to pass through to +.Xr vget 9 . +File systems are allowed to ignore +.Ar flags +and use +.Dv LK_EXCLUSIVE +instead. +.It Fa vpp +Return parameter for the new locked vnode. +.El +.Pp +The contents of the filehandle are defined by the file system and are +not examined by any other part of the system. +It should contain +enough information to uniquely identify a file within the file system +as well as noticing when a file has been removed and the file system +resources have been reused for a new file. +For instance, UFS +file system stores the inode number and inode generation counter in its +filehandle. +.Pp +A call to +.Fn VFS_FHTOVP +should generally be preceded by a call to +.Xr VFS_CHECKEXP 9 +to check if the file is accessible to the client. +.Sh RETURN VALUES +The locked vnode for the file will be returned in +.Fa *vpp . +.Sh SEE ALSO +.Xr VFS 9 , +.Xr VFS_CHECKEXP 9 , +.Xr vnode 9 , +.Xr VOP_VPTOFH 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/VFS_MOUNT.9 b/static/freebsd/man9/VFS_MOUNT.9 new file mode 100644 index 00000000..40ba8c70 --- /dev/null +++ b/static/freebsd/man9/VFS_MOUNT.9 @@ -0,0 +1,82 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 May 23, 2009 +.Dt VFS_MOUNT 9 +.Os +.Sh NAME +.Nm VFS_MOUNT +.Nd mount a file system +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.In sys/vnode.h +.Ft int +.Fn VFS_MOUNT "struct mount *mp" +.Sh DESCRIPTION +The +.Fn VFS_MOUNT +macro mounts a file system into the system's namespace or updates the +attributes of an already mounted file system. +.Pp +The arguments it expects are: +.Bl -tag -width data +.It Fa mp +Structure representing the file system. +.El +.Pp +The +.Fn VFS_MOUNT +macro is called both to mount new file systems and to change the +attributes of an existing file system. +If the +.Dv MNT_UPDATE +flag is set in +.Fa mp->mnt_flag +then the file system should update its internal state from the value of +.Fa mp->mnt_flag . +This can be used, for instance, to convert a read-only file system to +read-write. +It is also used by +.Xr mountd 8 +to update the NFS export information for the file system. +.Pp +If the +.Dv MNT_UPDATE +flag is not specified, then this is a newly mounted file system. +The file system code should allocate and initialize +any private data needed to represent +the file system (it can use the +.Fa mp->mnt_data +field to store this information). +.Sh SEE ALSO +.Xr VFS 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/VFS_QUOTACTL.9 b/static/freebsd/man9/VFS_QUOTACTL.9 new file mode 100644 index 00000000..c29721e7 --- /dev/null +++ b/static/freebsd/man9/VFS_QUOTACTL.9 @@ -0,0 +1,77 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 May 29, 2021 +.Dt VFS_QUOTACTL 9 +.Os +.Sh NAME +.Nm VFS_QUOTACTL +.Nd manipulate file system quotas +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.In sys/vnode.h +.Ft int +.Fn VFS_QUOTACTL "struct mount *mp" "int cmds" "uid_t uid" "void *arg" "bool *mp_busy" +.Sh DESCRIPTION +Implement file system quotas. +.Pp +The +.Fa mp_busy +argument is an input/output parameter. +.Fn VFS_QUOTACTL +must be called with +.Fa mp +marked busy through +.Xr vfs_busy 9 +and +.Fa *mp_busy +set to true. +The filesystem implementation of +.Fn VFS_QUOTACTL +may then unbusy +.Fa mp +using +.Xr vfs_unbusy 9 +prior to performing quota file I/O. +In this case the implementation must set +.Fa *mp_busy +to false to indicate that the caller must not unbusy +.Fa mp +upon completion of +.Fn VFS_QUOTACTL . +.Pp +See +.Xr quotactl 2 +for a description of the remaining arguments. +.Sh SEE ALSO +.Xr quotactl 2 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/VFS_ROOT.9 b/static/freebsd/man9/VFS_ROOT.9 new file mode 100644 index 00000000..5e1b4905 --- /dev/null +++ b/static/freebsd/man9/VFS_ROOT.9 @@ -0,0 +1,65 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 May 23, 2009 +.Dt VFS_ROOT 9 +.Os +.Sh NAME +.Nm VFS_ROOT +.Nd return the root vnode of a file system +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.In sys/vnode.h +.Ft int +.Fn VFS_ROOT "struct mount *mp" "int flags" "struct vnode **vpp" +.Sh DESCRIPTION +Return a locked vnode for the root directory of the file system. +.Pp +Its arguments are: +.Bl -tag -width flags +.It Fa mp +The file system. +.It Fa flags +The lock type. +Could be +.Dv LK_EXCLUSIVE +or +.Dv LK_SHARED . +File system is free to ignore the +.Fa flags +argument and instead acquire an exclusive lock. +.It Fa vpp +Return parameter for the root vnode. +.El +.Sh SEE ALSO +.Xr VFS 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/VFS_SET.9 b/static/freebsd/man9/VFS_SET.9 new file mode 100644 index 00000000..ded1a490 --- /dev/null +++ b/static/freebsd/man9/VFS_SET.9 @@ -0,0 +1,110 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 August 16, 2018 +.Dt VFS_SET 9 +.Os +.Sh NAME +.Nm VFS_SET +.Nd set up loadable file system +.Vt vfsconf +.Sh SYNOPSIS +.In sys/param.h +.In sys/kernel.h +.In sys/module.h +.In sys/mount.h +.Ft void +.Fn VFS_SET "struct vfsops *vfsops" "fsname" "int flags" +.Sh DESCRIPTION +.Fn VFS_SET +creates a +.Vt vfsconf +structure for the loadable module with the given +.Fa vfsops , fsname +and +.Fa flags , +and declares it by calling +.Xr DECLARE_MODULE 9 +using +.Fn vfs_modevent +as the event handler. +.Pp +Possible values for the +.Fa flags +argument are: +.Bl -hang -width ".Dv VFCF_DELEGADMIN" +.It Dv VFCF_STATIC +File system should be statically available in the kernel. +.It Dv VFCF_NETWORK +Network exportable file system. +.It Dv VFCF_READONLY +Does not support write operations. +.It Dv VFCF_SYNTHETIC +Pseudo file system, data does not represent on-disk files. +.It Dv VFCF_LOOPBACK +Loopback file system layer. +.It Dv VFCF_UNICODE +File names are stored as Unicode. +.It Dv VFCF_JAIL +Can be mounted from within a jail if +.Va allow.mount +and +.Va allow.mount. +jail parameters are set. +.It Dv VFCF_DELEGADMIN +Supports delegated administration if +.Va vfs.usermount +sysctl is set to +.Dv 1 . +.It Dv VFCF_SBDRY +When in VFS method, the thread suspension is deferred to the user +boundary upon arrival of stop action. +.El +.Sh PSEUDOCODE +.Bd -literal +/* + * Fill in the fields for which we have special methods. + * The others are initially null. This tells vfs to change them to + * pointers to vfs_std* functions during file system registration. + */ +static struct vfsops myfs_vfsops = { + .vfs_mount = myfs_mount, + .vfs_root = myfs_root, + .vfs_statfs = myfs_statfs, + .vfs_unmount = myfs_unmount, +}; + +VFS_SET(myfs_vfsops, myfs, 0); +.Ed +.Sh SEE ALSO +.Xr jail 2 , +.Xr jail 8 , +.Xr DECLARE_MODULE 9 , +.Xr vfs_modevent 9 , +.Xr vfsconf 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/VFS_STATFS.9 b/static/freebsd/man9/VFS_STATFS.9 new file mode 100644 index 00000000..b9cd6b79 --- /dev/null +++ b/static/freebsd/man9/VFS_STATFS.9 @@ -0,0 +1,114 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 May 23, 2009 +.Dt VFS_STATFS 9 +.Os +.Sh NAME +.Nm VFS_STATFS +.Nd return file system status +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.In sys/vnode.h +.Ft int +.Fn VFS_STATFS "struct mount *mp" "struct statfs *sbp" +.Sh DESCRIPTION +The +.Fn VFS_STATFS +macro returns various pieces of information about the file system, +including recommended I/O sizes, free space, free inodes, etc. +.Pp +The arguments it expects are: +.Bl -tag -width sbp +.It Fa mp +The file system. +.It Fa sbp +A +.Vt statfs +structure, as defined by +.In sys/mount.h , +into which information is placed about the file system. +.El +.Pp +The fields of +.Vt "struct statfs" +related to the file system are as follows: +.Bl -tag -width ".Va f_mntfromname" +.It Va f_type +Type of file system. +.It Va f_flags +A copy of mount exported flags. +.It Va f_bsize +Fragment size. +.It Va f_iosize +Optimal transfer block size. +.It Va f_blocks +The total number of data blocks in the file system. +.It Va f_bfree +The number of free blocks in the file system. +.It Va f_bavail +The number of free blocks available to non-superuser processes. +.It Va f_files +The total number of file nodes in the file system. +.It Va f_ffree +The number of free nodes available to non-superuser processes. +.It Va f_syncwrites +The number of synchronous writes since the file system was mounted. +.It Va f_asyncwrites +The number of asynchronous writes since the file system was mounted. +.It Va f_syncreads +The number of synchronous reads since the file system was mounted. +.It Va f_asyncreads +The number of asynchronous reads since the file system was mounted. +.It Va f_namemax +The maximum file name length for this file system. +.It Va f_owner +The user ID of the user that mounted the file system. +.It Va f_fsid +Unique file system ID. +.It Va f_fstypename +The file system type name; a string of at most +.Dv MFSNAMELEN +bytes. +.It Va f_mntfromname +The device name the file system was mounted from; a string of at most +.Dv MNAMELEN +bytes. +.It Va f_mntonname +The name of the directory on which the file system is mounted; +a string of at most +.Dv MNAMELEN +bytes. +.El +.Sh SEE ALSO +.Xr VFS 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/VFS_SYNC.9 b/static/freebsd/man9/VFS_SYNC.9 new file mode 100644 index 00000000..97633e59 --- /dev/null +++ b/static/freebsd/man9/VFS_SYNC.9 @@ -0,0 +1,79 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 May 23, 2009 +.Dt VFS_SYNC 9 +.Os +.Sh NAME +.Nm VFS_SYNC +.Nd flush unwritten data +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.In sys/vnode.h +.Ft int +.Fn VFS_SYNC "struct mount *mp" "int waitfor" +.Sh DESCRIPTION +The +.Fn VFS_SYNC +macro writes out all unwritten data in the file system mounted as +.Fa mp . +.Pp +The arguments it expects are: +.Bl -tag -width ".Fa waitfor" +.It Fa mp +The file system. +.It Fa waitfor +Whether the function should wait for I/O to complete. +Possible values are: +.Bl -tag -width MNT_NOWAIT +.It Dv MNT_WAIT +synchronously wait for I/O to complete +.It Dv MNT_NOWAIT +start all I/O, but do not wait for it +.It Dv MNT_LAZY +push data not written by file system syncer +.El +.El +.Pp +The +.Fn VFS_SYNC +macro calls the +.Va vfs_sync +method of the file system, which normally calls +.Xr VOP_FSYNC 9 +for all the vnodes in the file system. +.Sh SEE ALSO +.Xr fsync 2 , +.Xr sync 2 , +.Xr VFS 9 , +.Xr vnode 9 , +.Xr VOP_FSYNC 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/VFS_UNMOUNT.9 b/static/freebsd/man9/VFS_UNMOUNT.9 new file mode 100644 index 00000000..f9fb14c4 --- /dev/null +++ b/static/freebsd/man9/VFS_UNMOUNT.9 @@ -0,0 +1,66 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 May 23, 2009 +.Dt VFS_UNMOUNT 9 +.Os +.Sh NAME +.Nm VFS_UNMOUNT +.Nd unmount a file system +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.In sys/vnode.h +.Ft int +.Fn VFS_UNMOUNT "struct mount *mp" "int mntflags" +.Sh DESCRIPTION +The +.Fn VFS_UNMOUNT +macro unmounts a file system. +.Pp +The arguments it expects are: +.Bl -tag -width mntflags +.It Fa mp +The file system. +.It Fa mntflags +Bit-mask of flags for the unmount operation. +The flags currently supported by +.Fn VFS_UNMOUNT +are: +.Bl -tag -width ".Dv MNT_FORCE" +.It Dv MNT_FORCE +Open files are forcibly closed before the file system is unmounted. +.El +.El +.Sh SEE ALSO +.Xr vflush 9 , +.Xr VFS 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/VFS_VGET.9 b/static/freebsd/man9/VFS_VGET.9 new file mode 100644 index 00000000..e3612d2c --- /dev/null +++ b/static/freebsd/man9/VFS_VGET.9 @@ -0,0 +1,81 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 7, 2005 +.Dt VFS_VGET 9 +.Os +.Sh NAME +.Nm VFS_VGET +.Nd convert an inode number to a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.In sys/vnode.h +.Ft int +.Fn VFS_VGET "struct mount *mp" "ino_t ino" "int flags" "struct vnode **vpp" +.Sh DESCRIPTION +The +.Fn VFS_VGET +looks up or creates a vnode from a (mount, inode#) tuple. +.Pp +Its arguments are: +.Bl -tag -width ".Fa flags" +.It Fa mp +The mount point. +.It Fa ino +The inode representing the file. +This is a unique number assigned by the file system when vnodes are first +created. +.It Fa flags +Additional locking flags to pass through to +.Xr vget 9 . +.It Fa vpp +Return parameter for the vnode. +.El +.Pp +This is an optional file system entry-point for file systems mainly +intended for NFS server use, but many file systems +use it internally in +.Xr VOP_LOOKUP 9 +and similar. +.Pp +If the file system does not support this call, then it should return +.Er EOPNOTSUPP . +.Pp +Please see +.Fn ffs_vget +in +.Pa sys/ufs/ffs/ffs_vfsops.c +for the canonical example. +.Sh SEE ALSO +.Xr VFS 9 , +.Xr vget 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/VNET.9 b/static/freebsd/man9/VNET.9 new file mode 100644 index 00000000..679ccc3f --- /dev/null +++ b/static/freebsd/man9/VNET.9 @@ -0,0 +1,471 @@ +.\"- +.\" Copyright (c) 2010 The FreeBSD Foundation +.\" +.\" This documentation was written by CK Software GmbH under sponsorship from +.\" the FreeBSD Foundation. +.\" +.\" 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 September 19, 2025 +.Dt VNET 9 +.Os +.Sh NAME +.Nm VNET +.Nd "network subsystem virtualization infrastructure" +.Sh SYNOPSIS +.Cd "options VIMAGE" +.Cd "options VNET_DEBUG" +.Pp +.In net/vnet.h +.\"------------------------------------------------------------ +.Ss "Constants and Global Variables" +.\" +.Dv VNET_SETNAME +.\" "set_vnet" +.Dv VNET_SYMPREFIX +.\" "vnet_entry_" +.Vt extern struct vnet *vnet0; +.\"------------------------------------------------------------ +.Ss "Variable Declaration" +.Fo VNET +.Fa "name" +.Fc +.\" +.Fo VNET_NAME +.Fa "name" +.Fc +.\" +.Fo VNET_DECLARE +.Fa "type" "name" +.Fc +.\" +.Fo VNET_DEFINE +.Fa "type" "name" +.Fc +.\" +.Fo VNET_DEFINE_STATIC +.Fa "type" "name" +.Fc +.\" +.Bd -literal +#define V_name VNET(name) +.Ed +.\" ------------------------------------------------------------ +.Ss "Virtual Instance Selection" +.\" +.Fo CRED_TO_VNET +.Fa "struct ucred *" +.Fc +.\" +.Fo TD_TO_VNET +.Fa "struct thread *" +.Fc +.\" +.Fo P_TO_VNET +.Fa "struct proc *" +.Fc +.\" +.Fo IS_DEFAULT_VNET +.Fa "struct vnet *" +.Fc +.\" +.Fo VNET_ASSERT +.Fa exp msg +.Fc +.\" +.Fo CURVNET_SET +.Fa "struct vnet *" +.Fc +.\" +.Fo CURVNET_SET_QUIET +.Fa "struct vnet *" +.Fc +.\" +.Fn CURVNET_RESTORE +.\" +.Fo VNET_ITERATOR_DECL +.Fa "struct vnet *" +.Fc +.\" +.Fo VNET_FOREACH +.Fa "struct vnet *" +.Fc +.\" ------------------------------------------------------------ +.Ss "Locking" +.\" +.Fn VNET_LIST_RLOCK +.Fn VNET_LIST_RUNLOCK +.Fn VNET_LIST_RLOCK_NOSLEEP +.Fn VNET_LIST_RUNLOCK_NOSLEEP +.\" ------------------------------------------------------------ +.Ss "Startup and Teardown Functions" +.\" +.Ft "struct vnet *" +.Fo vnet_alloc +.Fa void +.Fc +.\" +.Ft void +.Fo vnet_destroy +.Fa "struct vnet *" +.Fc +.\" +.Fo VNET_SYSINIT +.Fa ident +.Fa "enum sysinit_sub_id subsystem" +.Fa "enum sysinit_elem_order order" +.Fa "sysinit_cfunc_t func" +.Fa "const void *arg" +.Fc +.\" +.Fo VNET_SYSUNINIT +.Fa ident +.Fa "enum sysinit_sub_id subsystem" +.Fa "enum sysinit_elem_order order" +.Fa "sysinit_cfunc_t func" +.Fa "const void *arg" +.Fc +.\" ------------------------------------------------------------ +.Ss "Eventhandlers" +.\" +.Fo VNET_GLOBAL_EVENTHANDLER_REGISTER +.Fa "const char *name" +.Fa "void *func" +.Fa "void *arg" +.Fa "int priority" +.Fc +.\" +.Fo VNET_GLOBAL_EVENTHANDLER_REGISTER_TAG +.Fa "eventhandler_tag tag" +.Fa "const char *name" +.Fa "void *func" +.Fa "void *arg" +.Fa "int priority" +.Fc +.\" ------------------------------------------------------------ +.Sh DESCRIPTION +.Nm +is the name of a technique to virtualize the network stack. +The basic idea is to change global resources most notably variables into +per network stack resources and have functions, sysctls, eventhandlers, +etc. access and handle them in the context of the correct instance. +Each (virtual) network stack is attached to a +.Em prison , +with +.Vt vnet0 +being the unrestricted default network stack of the base system. +.Pp +The global defines for +.Dv VNET_SETNAME +and +.Dv VNET_SYMPREFIX +are shared with +.Xr kvm 3 +to access internals for debugging reasons. +.\" ------------------------------------------------------------ +.Ss "Variable Declaration" +.\" +Variables are virtualized by using the +.Fn VNET_DEFINE +macro rather than writing them out as +.Em type name . +One can still use static initialization, e.g., +.Pp +.Dl Li VNET_DEFINE(int, foo) = 1; +.Pp +Variables declared with the static keyword can use the +.Fn VNET_DEFINE_STATIC +macro, e.g., +.Pp +.Dl Li VNET_DEFINE_STATIC(SLIST_HEAD(, bar), bars); +.Pp +Static initialization is not possible when the virtualized variable +would need to be referenced, e.g., with +.Dq TAILQ_HEAD_INITIALIZER() . +In that case a +.Fn VNET_SYSINIT +based initialization function must be used. +.Pp +External variables have to be declared using the +.Fn VNET_DECLARE +macro. +In either case the convention is to define another macro, +that is then used throughout the implementation to access that variable. +The variable name is usually prefixed by +.Em V_ +to express that it is virtualized. +The +.Fn VNET +macro will then translate accesses to that variable to the copy of the +currently selected instance (see the +.Sx "Virtual instance selection" +section): +.Pp +.Dl Li #define V_name VNET(name) +.Pp +.Em NOTE: +Do not confuse this with the convention used by +.Xr VFS 9 . +.Pp +The +.Fn VNET_NAME +macro returns the offset within the memory region of the virtual network +stack instance. +.\" ------------------------------------------------------------ +.Ss "Virtual Instance Selection" +.\" +There are three different places where the current virtual +network stack pointer is stored and can be taken from: +.Bl -enum -offset indent +.It +a +.Em prison : +.Dl "(struct prison *)->pr_vnet" +.Pp +For convenience the following macros are provided: +.Bd -literal -compact -offset indent +.Fn CRED_TO_VNET "struct ucred *" +.Fn TD_TO_VNET "struct thread *" +.Fn P_TO_VNET "struct proc *" +.Ed +.It +a +.Em socket : +.Dl "(struct socket *)->so_vnet" +.It +an +.Em interface : +.Dl "(struct ifnet *)->if_vnet" +.El +.Pp +.\" +In addition the currently active instance is cached in +.Dq "curthread->td_vnet" +which is usually only accessed through the +.Dv curvnet +macro. +.Pp +.\" +To set the correct context of the current virtual network instance, use the +.Fn CURVNET_SET +or +.Fn CURVNET_SET_QUIET +macros. +The +.Fn CURVNET_SET_QUIET +version will not record vnet recursions in case the kernel was compiled +with +.Cd "options VNET_DEBUG" +and should thus only be used in well known cases, where recursion is +unavoidable. +Both macros will save the previous state on the stack and it must be restored +with the +.Fn CURVNET_RESTORE +macro. +.Pp +.Em NOTE: +As the previous state is saved on the stack, you cannot have multiple +.Fn CURVNET_SET +calls in the same block. +.Pp +.Em NOTE: +As the previous state is saved on the stack, a +.Fn CURVNET_RESTORE +call has to be in the same block as the +.Fn CURVNET_SET +call or in a subblock with the same idea of the saved instances as the +outer block. +.Pp +.Em NOTE: +As each macro is a set of operations and, as previously explained, cannot +be put into its own block when defined, one cannot conditionally set +the current vnet context. +The following will +.Em not +work: +.Bd -literal -offset indent +if (condition) + CURVNET_SET(vnet); +.Ed +.Pp +nor would this work: +.Bd -literal -offset indent +if (condition) { + CURVNET_SET(vnet); +} +CURVNET_RESTORE(); +.Ed +.Pp +.\" +Sometimes one needs to loop over all virtual instances, for example to update +virtual from global state, to run a function from a +.Xr callout 9 +for each instance, etc. +For those cases the +.Fn VNET_ITERATOR_DECL +and +.Fn VNET_FOREACH +macros are provided. +The former macro defines the variable that iterates over the loop, +and the latter loops over all of the virtual network stack instances. +See +.Sx "Locking" +for how to savely traverse the list of all virtual instances. +.Pp +.\" +The +.Fn IS_DEFAULT_VNET +macro provides a safe way to check whether the currently active instance is the +unrestricted default network stack of the base system +.Pq Vt vnet0 . +.Pp +.\" +The +.Fn VNET_ASSERT +macro provides a way to conditionally add assertions that are only active with +.Cd "options VIMAGE" +compiled in and either +.Cd "options VNET_DEBUG" +or +.Cd "options INVARIANTS" +enabled as well. +It uses the same semantics as +.Xr KASSERT 9 . +.\" ------------------------------------------------------------ +.Ss "Locking" +.\" +For public access to the list of virtual network stack instances +e.g., by the +.Fn VNET_FOREACH +macro, read locks are provided. +Macros are used to abstract from the actual type of the locks. +If a caller may sleep while traversing the list, it must use the +.Fn VNET_LIST_RLOCK +and +.Fn VNET_LIST_RUNLOCK +macros. +Otherwise, the caller can use +.Fn VNET_LIST_RLOCK_NOSLEEP +and +.Fn VNET_LIST_RUNLOCK_NOSLEEP . +.\" ------------------------------------------------------------ +.Ss "Startup and Teardown Functions" +.\" +To start or tear down a virtual network stack instance the internal +functions +.Fn vnet_alloc +and +.Fn vnet_destroy +are provided and called from the jail framework. +They run the publicly provided methods to handle network stack +startup and teardown. +.Pp +For public control, the system startup interface has been enhanced +to not only handle a system boot but to also handle a virtual +network stack startup and teardown. +To the base system the +.Fn VNET_SYSINIT +and +.Fn VNET_SYSUNINIT +macros look exactly as if there were no virtual network stack. +In fact, if +.Cd "options VIMAGE" +is not compiled in they are compiled to the standard +.Fn SYSINIT +macros. +In addition to that they are run for each virtual network stack +when starting or, in reverse order, when shutting down. +.\" ------------------------------------------------------------ +.Ss "Eventhandlers" +.\" +Eventhandlers can be handled in two ways: +.Pp +.Bl -enum -offset indent -compact +.It +save the +.Em tags +returned in each virtual instance and properly free the eventhandlers +on teardown using those, or +.It +use one eventhandler that will iterate over all virtual network +stack instances. +.El +.Pp +For the first case one can just use the normal +.Xr EVENTHANDLER 9 +functions, while for the second case the +.Fn VNET_GLOBAL_EVENTHANDLER_REGISTER +and +.Fn VNET_GLOBAL_EVENTHANDLER_REGISTER_TAG +macros are provided. +These differ in that +.Fn VNET_GLOBAL_EVENTHANDLER_REGISTER_TAG +takes an extra first argument that will carry the +.Fa "tag" +upon return. +Eventhandlers registered with either of these will not run +.Fa func +directly but +.Fa func +will be called from an internal iterator function for each vnet. +Both macros can only be used for eventhandlers that do not take +additional arguments, as the variadic arguments from an +.Xr EVENTHANDLER_INVOKE 9 +call will be ignored. +.\" ------------------------------------------------------------ +.Ss "Sysctl Handling" +.\" +A +.Xr sysctl 9 +can be virtualized by adding the +.Dv CTLFLAG_VNET +control flag to the ctlflags bitmask of the macros. +.\" ------------------------------------------------------------ +.Sh SEE ALSO +.Xr jail 2 , +.Xr kvm 3 , +.Xr EVENTHANDLER 9 , +.\" .Xr pcpu 9 , +.Xr KASSERT 9 , +.Xr sysctl 9 +.\" .Xr SYSINIT 9 +.Pp +Marko Zec, Implementing a Clonable Network Stack in the FreeBSD Kernel, +USENIX ATC'03, June 2003, Boston +.Sh HISTORY +The virtual network stack implementation first appeared in +.Fx 8.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +framework was designed and implemented at the University of Zagreb by +.An Marko Zec +under sponsorship of the FreeBSD Foundation and NLnet Foundation, +and later extended and refined by +.An Bjoern A. Zeeb +(also under FreeBSD Foundation sponsorship), and +.An Robert Watson . +.Pp +This manual page was written by +.An Bjoern A. Zeeb, CK Software GmbH, +under sponsorship from the FreeBSD Foundation. diff --git a/static/freebsd/man9/VOP_ACCESS.9 b/static/freebsd/man9/VOP_ACCESS.9 new file mode 100644 index 00000000..facb0da7 --- /dev/null +++ b/static/freebsd/man9/VOP_ACCESS.9 @@ -0,0 +1,101 @@ +.\" -*- nroff -*- +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 September 18, 2009 +.Dt VOP_ACCESS 9 +.Os +.Sh NAME +.Nm VOP_ACCESS , +.Nm VOP_ACCESSX +.Nd "check access permissions of a file or Unix domain socket" +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_ACCESS "struct vnode *vp" "accmode_t accmode" "struct ucred *cred" "struct thread *td" +.Ft int +.Fn VOP_ACCESSX "struct vnode *vp" "accmode_t accmode" "struct ucred *cred" "struct thread *td" +.Sh DESCRIPTION +This entry point checks the access permissions of the file against the +given credentials. +.Pp +Its arguments are: +.Bl -tag -width accmode +.It Fa vp +The vnode of the file to check. +.It Fa accmode +The type of access required. +.It Fa cred +The user credentials to check. +.It Fa td +The thread which is checking. +.El +.Pp +The +.Fa accmode +is a mask which can contain flags described in , e.g. +.Dv VREAD , +.Dv VWRITE +or +.Dv VEXEC . +For +.Fn VOP_ACCESS , +the only flags that may be set in +.Fa accmode +are +.Dv VEXEC , +.Dv VWRITE , +.Dv VREAD , +.Dv VADMIN +and +.Dv VAPPEND . +To check for other flags, one has to use +.Fn VOP_ACCESSX +instead. +.Sh LOCKS +The vnode will be locked on entry and should remain locked on return. +.Sh RETURN VALUES +If the file is accessible in the specified way, then zero is returned, +otherwise an appropriate error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EPERM +An attempt was made to change an immutable file. +.It Bq Er EACCES +The permission bits the file mode or the ACL do not permit the +requested access. +.El +.Sh SEE ALSO +.Xr vaccess 9 , +.Xr vaccess_acl_nfs4 9 , +.Xr vaccess_acl_posix1e 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/VOP_ACLCHECK.9 b/static/freebsd/man9/VOP_ACLCHECK.9 new file mode 100644 index 00000000..d1a09c59 --- /dev/null +++ b/static/freebsd/man9/VOP_ACLCHECK.9 @@ -0,0 +1,100 @@ +.\"- +.\" Copyright (c) 1999 Robert N. M. Watson +.\" 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 December 23, 1999 +.Dt VOP_ACLCHECK 9 +.Os +.Sh NAME +.Nm VOP_ACLCHECK +.Nd check an access control list for a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/acl.h +.Ft int +.Fn VOP_ACLCHECK "struct vnode *vp" "acl_type_t type" "struct acl *aclp" "struct ucred *cred" "struct thread *td" +.Sh DESCRIPTION +This vnode call may be used to determine the validity of a particular access +control list (ACL) for a particular file or directory. +.Pp +Its arguments are: +.Bl -tag -width type +.It Fa vp +The vnode of the file or directory. +.It Fa type +The type of ACL to check. +.It Fa aclp +A pointer to an ACL structure from which to retrieve the ACL data. +.It Fa cred +The user credentials to use in authorizing the request. +.It Fa td +The thread checking the ACL. +.El +.Pp +The +.Fa cred +pointer may be NULL to indicate that access control checks are not to be +performed, if possible. +This cred setting might be used to allow the +kernel to authorize ACL verification that the active process might not be +permitted to do. +.Pp +The vnode ACL interface defines the syntax, and not semantics, of file and +directory ACL interfaces. +More information about ACL management in kernel +may be found in +.Xr acl 9 . +.Sh LOCKS +No locks are required to call this vnode method, and any locks held on +entry will be held on exit. +.Sh RETURN VALUES +If the +.Fa aclp +pointer points to a valid ACL of type +.Fa type +for the object +.Fa vp , +then zero is returned. +Otherwise, an appropriate error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINVAL +The ACL type passed is invalid for this vnode, or the ACL data is invalid. +.It Bq Er EACCES +The file or directory ACL does not permit access. +.It Bq Er ENOMEM +Sufficient memory is not available to fulfill the request. +.It Bq Er EOPNOTSUPP +The file system does not support +.Fn VOP_ACLCHECK . +.El +.Sh SEE ALSO +.Xr acl 9 , +.Xr vnode 9 , +.Xr VOP_GETACL 9 , +.Xr VOP_SETACL 9 +.Sh AUTHORS +This manual page was written by +.An Robert Watson . diff --git a/static/freebsd/man9/VOP_ADVISE.9 b/static/freebsd/man9/VOP_ADVISE.9 new file mode 100644 index 00000000..c6e87916 --- /dev/null +++ b/static/freebsd/man9/VOP_ADVISE.9 @@ -0,0 +1,89 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2013 Hudson River Trading LLC +.\" Written by: John H. Baldwin +.\" 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 September 26, 2015 +.Dt VOP_ADVISE 9 +.Os +.Sh NAME +.Nm VOP_ADVISE +.Nd apply advice about use of file data +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_ADVISE "struct vnode *vp" "off_t start" "off_t end" "int advice" +.Sh DESCRIPTION +This call applies advice for a range of a file's data. +It is used to implement the +.Xr posix_fadvise 2 +system call. +.Pp +Its arguments are: +.Bl -tag -width offset +.It Fa vp +The vnode of the file. +.It Fa start +The start of the range of file data. +.It Fa end +The end of the range of file data. +A value of +.Dv OFF_MAX +indicates that the advice is to be applied up to the end of the file. +.It Fa advice +The type of operation to apply to the file data. +Possible values are: +.Bl -tag -width POSIX_FADV_WILLNEED +.It Dv POSIX_FADV_WILLNEED +Initiate an asynchronous read of the file data if it is not already resident. +.It Dv POSIX_FADV_DONTNEED +Decrease the in-memory priority of clean file data or discard clean file data. +.El +.El +.Pp +If the +.Fa start +and +.Fa end +offsets are both zero, +then the operation should be applied to the entire file. +Note that this call is advisory only and may perform the requested +operation on a subset of the requested range +.Pq including not performing it at all +and still return success. +.Sh LOCKS +The file should be unlocked on entry. +.Sh RETURN VALUES +Zero is returned if the call is successful, otherwise an appropriate +error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINVAL +An invalid value was given for +.Fa advice . +.El +.Sh SEE ALSO +.Xr vnode 9 diff --git a/static/freebsd/man9/VOP_ADVLOCK.9 b/static/freebsd/man9/VOP_ADVLOCK.9 new file mode 100644 index 00000000..0be4686b --- /dev/null +++ b/static/freebsd/man9/VOP_ADVLOCK.9 @@ -0,0 +1,84 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 February 10, 2021 +.Dt VOP_ADVLOCK 9 +.Os +.Sh NAME +.Nm VOP_ADVLOCK +.Nd advisory record locking +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/fcntl.h +.In sys/lockf.h +.Ft int +.Fn VOP_ADVLOCK "struct vnode *vp" "caddr_t id" "int op" "struct flock *fl" "int flags" +.Sh DESCRIPTION +The arguments are: +.Bl -tag -width flags +.It Fa vp +The vnode being manipulated. +.It Fa id +The id token which is changing the lock. +.It Fa op +The operation to perform (see +.Xr fcntl 2 ) . +.It Fa fl +Description of the lock. +.It Fa flags +One or more of the following: +.Pp +.Bl -tag -width ".Dv F_REMOTE" -offset indent -compact +.It Dv F_WAIT +Wait until lock is granted. +.It Dv F_FLOCK +Use +.Xr flock 2 +semantics for lock. +.It Dv F_POSIX +Use POSIX semantics for lock. +.It Dv F_REMOTE +Lock owner is remote NFS client. +.It Dv F_NOINTR +Mask signals while waiting for the lock. +.El +.El +.Pp +This entry point manipulates advisory record locks on the file. +Most file systems delegate the work for this call to +.Fn lf_advlock . +.Sh RETURN VALUES +Zero is returned on success, otherwise an error is returned. +.Sh SEE ALSO +.Xr fcntl 2 , +.Xr flock 2 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/VOP_ALLOCATE.9 b/static/freebsd/man9/VOP_ALLOCATE.9 new file mode 100644 index 00000000..4fcbe773 --- /dev/null +++ b/static/freebsd/man9/VOP_ALLOCATE.9 @@ -0,0 +1,92 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2013 Hudson River Trading LLC +.\" Written by: John H. Baldwin +.\" 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 November 8, 2021 +.Dt VOP_ALLOCATE 9 +.Os +.Sh NAME +.Nm VOP_ALLOCATE +.Nd allocate storage for a file +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fo VOP_ALLOCATE +.Fa "struct vnode *vp" +.Fa "off_t *offset" +.Fa "off_t *len" +.Fa "int ioflag" +.Fa "struct ucred *cred" +.Fc +.Sh DESCRIPTION +This call allocates storage for a range of offsets in a file. +It is used to implement the +.Xr posix_fallocate 2 +system call. +.Pp +Its arguments are: +.Bl -tag -width offset +.It Fa vp +The vnode of the file. +.It Fa offset +The start of the range to allocate storage for in the file. +.It Fa len +The length of the range to allocate storage for in the file. +.It Fa ioflag +Directives and hints to be given to the file system. +.It Fa cred +The credentials of the caller. +.El +.Pp +The +.Fa offset +and +.Fa len +arguments are updated to reflect the portion of the range that +still needs to be allocated on return. +A partial allocation is considered a successful operation. +The file's contents are not changed. +.Sh LOCKS +The file should be exclusively locked on entry and will still be locked on exit. +.Sh RETURN VALUES +Zero is returned if the call is successful, otherwise an appropriate +error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EFBIG +An attempt was made to write a file that exceeds the process's file size +limit or the maximum file size. +.It Bq Er ENOSPC +The file system is full. +.It Bq Er EPERM +An append-only flag is set on the file, but the caller is attempting to +write before the current end of file. +.El +.Sh SEE ALSO +.Xr vnode 9 , +.Xr VOP_READ 9 , +.Xr VOP_WRITE 9 diff --git a/static/freebsd/man9/VOP_ATTRIB.9 b/static/freebsd/man9/VOP_ATTRIB.9 new file mode 100644 index 00000000..d7c55bd6 --- /dev/null +++ b/static/freebsd/man9/VOP_ATTRIB.9 @@ -0,0 +1,149 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 October 2, 2021 +.Dt VOP_ATTRIB 9 +.Os +.Sh NAME +.Nm VOP_GETATTR , +.Nm VOP_SETATTR +.Nd get and set attributes on a file or directory +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fo VOP_GETATTR +.Fa struct vnode *vp +.Fa flags +.Fa struct vattr *vap +.Fa struct ucred *cred +.Fc +.Ft int +.Fo VOP_SETATTR +.Fa struct vnode *vp +.Fa struct vattr *vap +.Fa struct ucred *cred +.Fc +.Ft int +.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, +access time and modification time. +.Pp +.Fn VOP_STAT +returns data in a format suitable for the +.Xr stat 2 +system call and by default is implemented as a wrapper around +.Fn VOP_GETATTR . +Filesystems may want to implement their own variant for performance reasons. +.Pp +For +.Fn VOP_GETATTR +and +.Fn VOP_SETATTR +the arguments are: +.Bl -tag -width cred +.It Fa vp +The vnode of the file. +.It Fa vap +The attributes of the file. +.It Fa cred +The user credentials of the calling thread. +.El +.Pp +For +.Fn VOP_STAT +the arguments are: +.Bl -tag -width active_cred +.It Fa vp +The vnode of the file. +.It Fa sb +The attributes of the file. +.It Fa active_cred +The user credentials of the calling thread. +.It Fa file_cred +The credentials installed on the file description pointing to the vnode or NOCRED. +.El +.Pp +Attributes which are not being modified by +.Fn VOP_SETATTR +should be set to the value +.Dv VNOVAL ; +.Fn VATTR_NULL +may be used to clear all the values, and should generally be used to reset +the contents of +.Fa *vap +prior to setting specific values. +.Sh LOCKS +Both +.Fn VOP_GETATTR +and +.Fn VOP_STAT +expect the vnode to be locked on entry and will leave the vnode locked on +return. +The lock type can be either shared or exclusive. +.Pp +.Fn VOP_SETATTR +expects the vnode to be locked on entry and will leave the vnode locked on +return. +The lock type must be exclusive. +.Sh RETURN VALUES +.Fn VOP_GETATTR +returns 0 if it was able to retrieve the attribute data via +.Fa *vap , +otherwise an appropriate error is returned. +.Fn VOP_SETATTR +returns zero if the attributes were changed successfully, otherwise an +appropriate error is returned. +.Fn VOP_STAT +returns 0 if it was able to retrieve the attribute data +.Fa *sb , +otherwise an appropriate error is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EPERM +The file is immutable. +.It Bq Er EACCES +The caller does not have permission to modify the file or directory attributes. +.It Bq Er EROFS +The file system is read-only. +.El +.Sh SEE ALSO +.Xr VFS 9 , +.Xr vnode 9 , +.Xr VOP_ACCESS 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/VOP_BMAP.9 b/static/freebsd/man9/VOP_BMAP.9 new file mode 100644 index 00000000..82dda716 --- /dev/null +++ b/static/freebsd/man9/VOP_BMAP.9 @@ -0,0 +1,84 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2019 The FreeBSD Foundation +.\" +.\" This documentation was written by BFF Storage Systems, LLC under +.\" sponsorship from the FreeBSD Foundation. +.\" +.\" 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 June 19, 2019 +.Dt VOP_BMAP 9 +.Os +.Sh NAME +.Nm VOP_BMAP +.Nd Logical to physical block number conversion +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_BMAP "struct vnode *vp" "daddr_t bn" "struct bufobj **bop" "daddr_t *bnp" "int *runp" "int *runb" +.Sh DESCRIPTION +This vnode call is used to lookup the physical block number of the file system's +underlying device where a given logical block of a file is stored. +Its arguments are: +.Bl -tag -width type +.It Fa vp +The vnode of the file. +.It Fa bn +Logical block number within the file identified by +.Fa vp . +.It Fa bop +Return storage for the buffer object associated with the file system's +underlying device. +.It Fa bnp +Return storage for the physical block number. +.It Fa runp +Return storage for the number of succeeding logical blocks that may be +efficiently read at the same time as the requested block. +This will usually be the number of logical blocks whose physical blocks are +contiguously allocated. +However a file system is free to define "efficient" as it sees fit. +.It Fa runb +Like +.Fa runp +but for preceding rather than succeeding blocks. +.El +.Pp +Any of the return arguments may be +.Dv NULL +to indicate that the caller does not care about that information. +.Sh LOCKS +The vnode will be locked on entry and should remain locked on return. +.Sh RETURN VALUES +Zero is returned on success, otherwise an error code is returned. +.Sh SEE ALSO +.Xr vnode 9 +.Sh HISTORY +A +.Fn bmap +function first appeared in +.Bx 4.2 . +.Sh AUTHORS +This manual page was written by +.An Alan Somers . diff --git a/static/freebsd/man9/VOP_BWRITE.9 b/static/freebsd/man9/VOP_BWRITE.9 new file mode 100644 index 00000000..fb811124 --- /dev/null +++ b/static/freebsd/man9/VOP_BWRITE.9 @@ -0,0 +1,54 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 July 24, 1996 +.Dt VOP_BWRITE 9 +.Os +.Sh NAME +.Nm VOP_BWRITE +.Nd write a file system buffer +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_BWRITE "struct vnode *vp" "struct buf *bp" +.Sh DESCRIPTION +The arguments are: +.Bl -tag -width 2n +.It Fa vp +The vnode of the file being written to. +.It Fa bp +The buffer to be written. +.El +.Sh RETURN VALUES +Zero is returned on success, otherwise an error is returned. +.Sh SEE ALSO +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/VOP_COPY_FILE_RANGE.9 b/static/freebsd/man9/VOP_COPY_FILE_RANGE.9 new file mode 100644 index 00000000..aa176709 --- /dev/null +++ b/static/freebsd/man9/VOP_COPY_FILE_RANGE.9 @@ -0,0 +1,142 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2019 Rick Macklem +.\" +.\" 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 March 30, 2020 +.Dt VOP_COPY_FILE_RANGE 9 +.Os +.Sh NAME +.Nm VOP_COPY_FILE_RANGE +.Nd copy a byte range within a file or from one file to another in a single +file system or between multiple file systems +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fo VOP_COPY_FILE_RANGE +.Fa "struct vnode *invp" +.Fa "off_t *inoff" +.Fa "struct vnode *outvp" +.Fa "off_t *outoff" +.Fa "size_t *len" +.Fa "unsigned int flags" +.Fa "struct ucred *incred" +.Fa "struct ucred *outcred" +.Fa "struct thread *fsize_td" +.Fc +.Sh DESCRIPTION +This entry point copies a byte range from one regular file to another +or within one file in a single file system. +.Fa invp +and +.Fa outvp +can refer to the same file. +For this case, the byte ranges defined by +.Fa *inoff , +.Fa *outoff and +.Fa *len +will not overlap. +.Pp +The arguments are: +.Bl -tag -width ioflag +.It Fa invp +The vnode of the input file. +.It Fa inoff +A pointer to the file offset for the input file. +.It Fa outvp +The vnode of the output file. +.It Fa outoff +A pointer to the file offset for the output file. +.It Fa len +A pointer to the byte count for the copy. +.It Fa flags +Flags, should be set to 0 for now. +.It Fa incred +The credentials used to read +.Fa invp . +.It Fa outcred +The credentials used to write +.Fa outvp . +.It Fa fsize_td +The thread pointer to be passed to vn_rlimit_fsize(). +This will be +.Dv NULL +for a server thread without limits, such as for the NFS +server or +.Dv curthread +otherwise. +.El +.Pp +On entry and on return, the +.Fa inoff +and +.Fa outoff +arguments point to the locations of the file offsets. +These file offsets should be updated by the number of bytes copied. +The +.Fa len +argument points to the location that stores the number of bytes +to be copied. +Upon a successful return +.Fa len +will be updated to the number of bytes actually copied. +Normally, this will be the number of bytes requested to be copied, +however a copy of fewer bytes than requested is permitted. +This does not necessarily indicate that the copy reached EOF on the input file. +However, if the value pointed to by the +.Fa len +argument is zero upon a successful return, +it indicates that the offset pointed to by +.Fa inoff +is at or beyond EOF on the input file. +.Sh LOCKS +The vnode are unlocked on entry and must be unlocked on return. +The byte ranges for both +.Fa invp +and +.Fa outvp +should be range locked when this call is done. +.Sh RETURN VALUES +Zero is returned on success, otherwise an error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EFBIG +If the copy exceeds the process's file size limit or the maximum file size +for the file system +.Fa invp +and +.Fa outvp +reside on. +.It Bq Er EINTR +A signal interrupted the VOP call before it could be completed. +.It Bq Er EIO +An I/O error occurred while reading/writing the files. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading/writing the files. +.It Bq Er ENOSPC +The file system is full. +.El +.Sh SEE ALSO +.Xr vn_rdwr 9 , +.Xr vnode 9 diff --git a/static/freebsd/man9/VOP_CREATE.9 b/static/freebsd/man9/VOP_CREATE.9 new file mode 100644 index 00000000..326e0e91 --- /dev/null +++ b/static/freebsd/man9/VOP_CREATE.9 @@ -0,0 +1,98 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 November 2, 2018 +.Dt VOP_CREATE 9 +.Os +.Sh NAME +.Nm VOP_CREATE , +.Nm VOP_MKNOD , +.Nm VOP_MKDIR , +.Nm VOP_SYMLINK +.Nd create a file, socket, fifo, device, directory or symlink +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/namei.h +.Ft int +.Fn VOP_CREATE "struct vnode *dvp" "struct vnode **vpp" "struct componentname *cnp" "struct vattr *vap" +.Ft int +.Fn VOP_MKNOD "struct vnode *dvp" "struct vnode **vpp" "struct componentname *cnp" "struct vattr *vap" +.Ft int +.Fn VOP_MKDIR "struct vnode *dvp" "struct vnode **vpp" "struct componentname *cnp" "struct vattr *vap" +.Ft int +.Fn VOP_SYMLINK "struct vnode *dvp" "struct vnode **vpp" "struct componentname *cnp" "struct vattr *vap" "const char *target" +.Sh DESCRIPTION +These entry points create a new file, socket, fifo, device, directory or symlink +in a given directory. +.Pp +The arguments are: +.Bl -tag -width target +.It Fa dvp +The locked vnode of the directory. +.It Fa vpp +The address of a variable where the resulting locked vnode should be stored. +.It Fa cnp +The pathname component created. +.It Fa vap +The attributes that the new object should be created with. +.It Fa target +The pathname of the target of the symlink. +.El +.Pp +These entry points are called after +.Xr VOP_LOOKUP 9 +when an object is being created. +.Sh LOCKS +The directory, +.Fa dvp +will be locked on entry and must remain locked on return. +If the call is successful, the new object will be returned locked. +.Sh RETURN VALUES +If successful, the vnode for the new object is placed in +.Fa *vpp +and zero is returned. +Otherwise, an appropriate error is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ENOSPC +The file system is full. +.It Bq Er EDQUOT +The user's file system space or inode quota would be exceeded. +.El +.Sh SEE ALSO +.Xr vnode 9 , +.Xr VOP_LOOKUP 9 +.Sh HISTORY +The function +.Nm +appeared in +.Bx 4.3 . +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/VOP_DEALLOCATE.9 b/static/freebsd/man9/VOP_DEALLOCATE.9 new file mode 100644 index 00000000..0db4d07a --- /dev/null +++ b/static/freebsd/man9/VOP_DEALLOCATE.9 @@ -0,0 +1,109 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2021 The FreeBSD Foundation +.\" +.\" This manual page was written by Ka Ho Ng under sponsorship from +.\" the FreeBSD Foundation. +.\" +.\" 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 August 25, 2021 +.Dt VOP_DEALLOCATE 9 +.Os +.Sh NAME +.Nm VOP_DEALLOCATE +.Nd zero and/or deallocate storage from a file +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fo VOP_DEALLOCATE +.Fa "struct vnode *vp" +.Fa "off_t *offset" +.Fa "off_t *len" +.Fa "int flags" +.Fa "int ioflag" +.Fa "struct ucred *cred" +.Fc +.Sh DESCRIPTION +This VOP call zeroes/deallocates storage for an offset range in a file. +It is used to implement the +.Xr fspacectl 2 +system call. +.Pp +Its arguments are: +.Bl -tag -width offset +.It Fa vp +The vnode of the file. +.It Fa offset +The start of the range to deallocate storage in the file. +.It Fa len +The length of the range to deallocate storage in the file. +.It Fa flags +The flags of this call. +This should be set to 0 for now. +.It Fa ioflag +Directives and hints to be given to the file system. +.It Fa cred +The credentials of the caller. +.El +.Pp +.Fa *offset +and +.Fa *len +are updated to reflect the portion of the range that +still needs to be zeroed/deallocated on return. +Partial result is considered a successful operation. +For a non-partial successful completion, +.Fa *len +is updated to be the value 0, and +.Fa *offset +is incremented by the number of bytes zeroed before the end-of-file. +.Sh LOCKS +The vnode should be locked on entry and will still be locked on exit. +.Sh RETURN VALUES +Zero is returned if the call is successful, otherwise an appropriate +error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid +.Fa offset , len +or +.Fa flags +parameters are passed into this VOP call. +.It Bq Er ENODEV +The vnode type is not supported by this VOP call. +.It Bq Er ENOSPC +The file system is full. +.It Bq Er EPERM +An append-only flag is set on the file, but the caller is attempting to +zero before the current end of file. +.El +.Sh SEE ALSO +.Xr vnode 9 +.Sh AUTHORS +.Nm +and this manual page was written by +.An Ka Ho Ng Aq Mt khng@FreeBSD.org +under sponsorship from the FreeBSD Foundation. diff --git a/static/freebsd/man9/VOP_FSYNC.9 b/static/freebsd/man9/VOP_FSYNC.9 new file mode 100644 index 00000000..e58119d9 --- /dev/null +++ b/static/freebsd/man9/VOP_FSYNC.9 @@ -0,0 +1,106 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" Copyright (c) 2019 The FreeBSD Foundation +.\" +.\" Portions of this documentation were written by BFF Storage Systems under +.\" sponsorship from the FreeBSD Foundation. +.\" +.\" 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 March 22, 2019 +.Dt VOP_FSYNC 9 +.Os +.Sh NAME +.Nm VOP_FDATASYNC , +.Nm VOP_FSYNC +.Nd flush file system buffers for a file +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_FDATASYNC "struct vnode *vp" "struct thread *td" +.Ft int +.Fn VOP_FSYNC "struct vnode *vp" "int waitfor" "struct thread *td" +.Sh DESCRIPTION +.Fn VOP_FSYNC +ensures that a file can be recovered to its current state following a crash. +That typically requires flushing the file's dirty buffers, its inode, and +possibly other filesystem metadata to persistent media. +.Fn VOP_FSYNC +is used to implement the +.Xr sync 2 +and +.Xr fsync 2 +system calls. +.Pp +Its arguments are: +.Bl -tag -width waitfor +.It Fa vp +The vnode of the file. +.It Fa waitfor +Whether the function should wait for I/O to complete. +Possible values are: +.Bl -tag -width MNT_NOWAIT +.It Dv MNT_WAIT +Synchronously wait for I/O to complete. +.It Dv MNT_NOWAIT +Start all I/O, but do not wait for it. +.It Dv MNT_LAZY +Push data not written by file system syncer. +.El +.It Fa td +The calling thread. +.El +.Pp +.Fn VOP_FDATASYNC +is similar, but it does not require that all of the file's metadata be flushed. +It only requires that the file's data be recoverable after a crash. +That implies that the data itself must be flushed to disk, as well as some +metadata such as the file's size but not necessarily its attributes. +.Fn VOP_FDATASYNC +should always wait for I/O to complete, as if called with +.Dv MNT_WAIT . +.Fn VOP_FDATASYNC +is used to implement +.Xr fdatasync 2 . +.Sh LOCKS +The vnode should be exclusively locked on entry, and stays locked on return. +.Sh RETURN VALUES +Zero is returned if the call is successful, otherwise an appropriate +error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ENOSPC +The file system is full. +.It Bq Er EDQUOT +Quota exceeded. +.El +.Sh SEE ALSO +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/VOP_GETACL.9 b/static/freebsd/man9/VOP_GETACL.9 new file mode 100644 index 00000000..94112f96 --- /dev/null +++ b/static/freebsd/man9/VOP_GETACL.9 @@ -0,0 +1,94 @@ +.\"- +.\" Copyright (c) 1999, 2000, 2001 Robert N. M. Watson +.\" 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 December 23, 1999 +.Dt VOP_GETACL 9 +.Os +.Sh NAME +.Nm VOP_GETACL +.Nd retrieve access control list for a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/acl.h +.Ft int +.Fn VOP_GETACL "struct vnode *vp" "acl_type_t type" "struct acl *aclp" "struct ucred *cred" "struct thread *td" +.Sh DESCRIPTION +This vnode call may be used to retrieve the access control list (ACL) from a +file or directory. +.Pp +Its arguments are: +.Bl -tag -width type +.It Fa vp +The vnode of the file or directory. +.It Fa type +The type of ACL to retrieve. +.It Fa aclp +A pointer to an ACL structure to receive the ACL data. +.It Fa cred +The user credentials to use in authorizing the request. +.It Fa td +The thread requesting the ACL. +.El +.Pp +The +.Fa cred +pointer may be +.Dv NULL +to indicate that access control checks are not to be performed, if possible. +This cred setting might be used to allow the kernel to authorize ACL +retrieval that the active process might not be permitted to do. +.Pp +The vnode ACL interface defines the syntax, and not semantics, of file and +directory ACL interfaces. +More information about ACL management in kernel may be found in +.Xr acl 9 . +.Sh LOCKS +The vnode will be locked on entry and should remain locked on return. +.Sh RETURN VALUES +If the +.Fa aclp +pointer will point to a valid ACL, then zero is returned. +Otherwise, an appropriate error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINVAL +The ACL type passed is invalid for this vnode. +.It Bq Er EACCES +The caller does not have the appropriate privilege. +.It Bq Er ENOMEM +Sufficient memory is not available to fulfill the request. +.It Bq Er EOPNOTSUPP +The file system does not support +.Fn VOP_GETACL . +.El +.Sh SEE ALSO +.Xr acl 9 , +.Xr vnode 9 , +.Xr VOP_ACLCHECK 9 , +.Xr VOP_SETACL 9 +.Sh AUTHORS +This manual page was written by +.An Robert Watson . diff --git a/static/freebsd/man9/VOP_GETEXTATTR.9 b/static/freebsd/man9/VOP_GETEXTATTR.9 new file mode 100644 index 00000000..b06105f8 --- /dev/null +++ b/static/freebsd/man9/VOP_GETEXTATTR.9 @@ -0,0 +1,131 @@ +.\"- +.\" Copyright (c) 1999, 2000, 2001, 2003 Robert N. M. Watson +.\" 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 December 23, 1999 +.Dt VOP_GETEXTATTR 9 +.Os +.Sh NAME +.Nm VOP_GETEXTATTR +.Nd retrieve named extended attribute from a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/extattr.h +.Ft int +.Fo VOP_GETEXTATTR +.Fa "struct vnode *vp" +.Fa "int attrnamespace" +.Fa "const char *name" +.Fa "struct uio *uio" +.Fa "size_t *size" +.Fa "struct ucred *cred" +.Fa "struct thread *td" +.Fc +.Sh DESCRIPTION +This vnode call may be used to retrieve a specific named extended attribute +from a file or directory. +.Pp +Its arguments are: +.Bl -tag -width ".Fa attrnamespace" +.It Fa vp +The vnode of the file or directory. +.It Fa attrnamespace +Integer constant indicating which extended attribute namespace the attribute +name is present in. +.It Fa name +Pointer to a null-terminated character string containing the attribute name. +.It Fa uio +The location of the data to be read. +.It Fa size +If not +.Dv NULL , +on return it will contain the number of bytes required to read all of the +attribute data. +In most cases +.Fa uio +will be +.Dv NULL +when +.Fa size +is not, and vice versa. +.It Fa cred +The user credentials to use in authorizing the request. +.It Fa td +The thread requesting the extended attribute. +.El +.Pp +The +.Fa cred +pointer may be +.Dv NULL +to indicate that access control checks are not to be performed, if possible. +This +.Fa cred +setting might be used to allow the kernel to authorize extended attribute +retrieval that the active process might not be permitted to do. +.Pp +Extended attribute semantics may vary by file system implementing the call. +More information on extended attributes may be found in +.Xr extattr 9 . +.Sh LOCKS +The vnode will be locked on entry and should remain locked on return. +.Sh RETURN VALUES +On success, zero will be returned, and the uio structure will be updated to +reflect data read. +Otherwise, an appropriate error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ENOATTR +The requested attribute was not defined for this vnode. +.It Bq Er EACCES +The caller does not have the appropriate privilege. +.It Bq Er ENXIO +The request was not valid in this file system for the specified vnode and +attribute name. +.It Bq Er ENOMEM +Sufficient memory is not available to fulfill the request. +.It Bq Er EFAULT +The uio structure refers to an invalid userspace address. +.It Bq Er EINVAL +The +.Fa name , +.Fa namespace , +or +.Fa uio +argument is invalid. +.It Bq Er EOPNOTSUPP +The file system does not support +.Fn VOP_GETEXTATTR . +.El +.Sh SEE ALSO +.Xr extattr 9 , +.Xr vnode 9 , +.Xr VOP_LISTEXTATTR 9 , +.Xr VOP_SETEXTATTR 9 +.Sh BUGS +By passing in the empty string as the attribute name, some file systems +will return a list of defined names on the target vnode for the +requested namespace. +This is a bad API, and will be replaced by an explicit VOP. diff --git a/static/freebsd/man9/VOP_GETPAGES.9 b/static/freebsd/man9/VOP_GETPAGES.9 new file mode 100644 index 00000000..bb344543 --- /dev/null +++ b/static/freebsd/man9/VOP_GETPAGES.9 @@ -0,0 +1,205 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" Copyright 2003, Garrett A. Wollman +.\" +.\" 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 June 29, 2019 +.Dt VOP_GETPAGES 9 +.Os +.Sh NAME +.Nm VOP_GETPAGES , +.Nm VOP_PUTPAGES +.Nd read or write VM pages from a file +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In vm/vm.h +.Ft int +.Fo VOP_GETPAGES +.Fa "struct vnode *vp" +.Fa "vm_page_t *ma" +.Fa "int count" +.Fa "int *rbehind" +.Fa "int *rahead" +.Fc +.Ft int +.Fo VOP_PUTPAGES +.Fa "struct vnode *vp" +.Fa "vm_page_t *ma" +.Fa "int bytecount" +.Fa "int flags" +.Fa "int *rtvals" +.Fc +.Sh DESCRIPTION +The +.Fn VOP_GETPAGES +method is called to read in pages of virtual memory which are backed by +ordinary files. +If other adjacent pages are backed by adjacent regions of the same file, +.Fn VOP_GETPAGES +is requested to read those pages as well, although it is not required to +do so. +The +.Fn VOP_PUTPAGES +method does the converse; that is to say, it writes out adjacent dirty +pages of virtual memory. +.Pp +On entry, the vnode lock is held but neither the page queue nor VM object +locks are held. +Both methods return in the same state on both success and error returns. +.Pp +The arguments are: +.Bl -tag -width rbehind +.It Fa vp +The file to access. +.It Fa ma +Pointer to the first element of an array of pages representing a +contiguous region of the file to be read or written. +.It Fa count +The length of the +.Fa ma +array. +.It Fa bytecount +The number of bytes that should be written from the pages of the array. +.It Fa flags +A bitfield of flags affecting the function operation. +If +.Dv VM_PAGER_PUT_SYNC +is set, the write should be synchronous; control must not be returned +to the caller until after the write is finished. +If +.Dv VM_PAGER_PUT_INVAL +is set, the pages are to be invalidated after being written. +If +.Dv VM_PAGER_PUT_NOREUSE +is set, the I/O performed should set the IO_NOREUSE flag, to indicate +to the filesystem that pages should be marked for fast reuse if needed. +This could occur via a call to +.Xr vm_page_deactivate_noreuse 9 , +which puts such pages onto the head of the inactive queue. +If +.Dv VM_PAGER_CLUSTER_OK +is set, writes may be delayed, so that related writes +can be coalesced for efficiency, e.g., +using the clustering mechanism of the buffer cache. +.It Fa rtvals +An array of VM system result codes indicating the status of each +page written by +.Fn VOP_PUTPAGES . +.It Fa rbehind +Optional pointer to integer specifying number of pages to be read behind, if +possible. +If the filesystem supports that feature, number of actually read pages is +reported back, otherwise zero is returned. +.It Fa rahead +Optional pointer to integer specifying number of pages to be read ahead, if +possible. +If the filesystem supports that feature, number of actually read pages is +reported back, otherwise zero is returned. +.El +.Pp +The status of the +.Fn VOP_PUTPAGES +method is returned on a page-by-page basis in the array +.Fa rtvals[] . +The possible status values are as follows: +.Bl -tag -width VM_PAGER_ERROR +.It Dv VM_PAGER_OK +The page was successfully written. +The implementation must call +.Xr vm_page_undirty 9 +to mark the page as clean. +.It Dv VM_PAGER_PEND +The page was scheduled to be written asynchronously. +When the write completes, the completion callback should +call +.Xr vm_object_pip_wakeup 9 +and +.Xr vm_page_sunbusy 9 +to clear the busy flag and awaken any other threads waiting for this page, +in addition to calling +.Xr vm_page_undirty 9 . +.It Dv VM_PAGER_BAD +The page was entirely beyond the end of the backing file. +This condition should not be possible if the vnode's file system +is correctly implemented. +.It Dv VM_PAGER_ERROR +The page could not be written because of an error on the underlying storage +medium or protocol. +.It Dv VM_PAGER_FAIL +Treated identically to +.Dv VM_PAGER_ERROR . +.It Dv VM_PAGER_AGAIN +The page was not handled by this request. +.El +.Pp +The +.Fn VOP_GETPAGES +method must populate and validate all requested pages in order to +return success. +It is expected to release any pages in +.Fa ma +that it does not successfully handle, by calling +.Xr vm_page_free 9 . +When it succeeds, +.Fn VOP_GETPAGES +must set the valid bits appropriately. +Upon entry to +.Fn VOP_GETPAGES , +all pages in +.Fa ma +are busied exclusively. +Upon successful return, the pages must all be busied exclusively +as well, but pages may be unbusied during processing. +The filesystem is responsible for activating paged-out pages, but this +does not necessarily need to be done within +.Fn VOP_GETPAGES +depending on the architecture of the particular filesystem. +.Sh RETURN VALUES +If it successfully reads all pages in +.Fa ma , +.Fn VOP_GETPAGES +returns +.Dv VM_PAGER_OK ; +otherwise, it returns +.Dv VM_PAGER_ERROR . +By convention, the return value of +.Fn VOP_PUTPAGES +is +.Fa rtvals[0] . +.Sh SEE ALSO +.Xr vm_object_pip_wakeup 9 , +.Xr vm_page_free 9 , +.Xr vm_page_sunbusy 9 , +.Xr vm_page_undirty 9 , +.Xr vm_page_xunbusy 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson +and then substantially rewritten by +.An Garrett Wollman . diff --git a/static/freebsd/man9/VOP_INACTIVE.9 b/static/freebsd/man9/VOP_INACTIVE.9 new file mode 100644 index 00000000..a137d6fb --- /dev/null +++ b/static/freebsd/man9/VOP_INACTIVE.9 @@ -0,0 +1,79 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 March 15, 2019 +.Dt VOP_INACTIVE 9 +.Os +.Sh NAME +.Nm VOP_INACTIVE , +.Nm VOP_RECLAIM +.Nd reclaim file system resources for a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_INACTIVE "struct vnode *vp" "struct thread *td" +.Ft int +.Fn VOP_RECLAIM "struct vnode *vp" "struct thread *td" +.Sh DESCRIPTION +The arguments are: +.Bl -tag -width 2n +.It Fa vp +The vnode being reclaimed. +.El +.Pp +.Fn VOP_INACTIVE +is usually called when the kernel is no longer using the vnode. +However, there is no guarantee that it will be called at all, for example if +the last reference was dropped while the vnode lock could not be upgraded +to exclusive without sleeping. +This may be +because the reference count reaches zero or it may be that the +file system is being forcibly unmounted while there are open files. +It can be used to reclaim space on the last close of an +.Sq open but deleted +file. +.Pp +.Fn VOP_RECLAIM +is called when a vnode is being reused for a different file system. +Any file system specific resources associated with the vnode should be +freed. +.Sh LOCKS +For both +.Fn VOP_INACTIVE +and +.Fn VOP_RECLAIM , +the +.Fa vp +will be exclusively locked on entry, and must be left exclusively +locked on return. +.Sh SEE ALSO +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/VOP_INOTIFY.9 b/static/freebsd/man9/VOP_INOTIFY.9 new file mode 100644 index 00000000..43b64468 --- /dev/null +++ b/static/freebsd/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/static/freebsd/man9/VOP_IOCTL.9 b/static/freebsd/man9/VOP_IOCTL.9 new file mode 100644 index 00000000..5a58d842 --- /dev/null +++ b/static/freebsd/man9/VOP_IOCTL.9 @@ -0,0 +1,72 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 July 24, 1996 +.Dt VOP_IOCTL 9 +.Os +.Sh NAME +.Nm VOP_IOCTL +.Nd device specific control +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_IOCTL "struct vnode *vp" "u_long command" "caddr_t data" "int fflag" "struct ucred *cred" "struct thread *td" +.Sh DESCRIPTION +Manipulate a file in device dependent ways. +.Pp +Its arguments are: +.Bl -tag -width command +.It Fa vp +The vnode of the file (normally representing a device). +.It Fa command +The device specific operation to perform. +.It Fa data +Extra data for the specified operation. +.It Fa fflag +Some flags ??? +.It Fa cred +The caller's credentials. +.It Fa td +The calling thread. +.El +.Pp +Most file systems do not implement this entry point. +.Sh LOCKS +The file should not be locked on entry. +.Sh RETURN VALUES +If successful, zero is returned, otherwise an appropriate error code. +.Pp +If the ioctl is not recognized or not handled, +.Er ENOTTY +should be returned. +.Sh SEE ALSO +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/VOP_LINK.9 b/static/freebsd/man9/VOP_LINK.9 new file mode 100644 index 00000000..f553b331 --- /dev/null +++ b/static/freebsd/man9/VOP_LINK.9 @@ -0,0 +1,81 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 July 24, 1996 +.Dt VOP_LINK 9 +.Os +.Sh NAME +.Nm VOP_LINK +.Nd create a new name for a file +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_LINK "struct vnode *dvp" "struct vnode *vp" "struct componentname *cnp" +.Sh DESCRIPTION +This links a new name in the specified directory to an existing file. +.Pp +Its arguments are: +.Bl -tag -width 8n +.It Fa dvp +The vnode of the directory. +.It Fa vp +The vnode of the file to be linked. +.It Fa cnp +Pathname information about the file. +.El +.Pp +The pathname info should +.Em not +be released on exit because it is done +by the caller. +The directory and file vnodes should +.Em not +be released on exit. +.Sh LOCKS +.Fn VOP_LINK +expects the directory and file vnodes to be locked on entry and will leave +the vnodes locked on return. +.Sh RETURN VALUES +Zero is returned if the file was linked successfully, otherwise an +error is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EMLINK +The file has too many links. +.It Bq Er EPERM +The file is immutable. +.It Bq Er EXDEV +A hard link is not possible between different file systems. +.El +.Sh SEE ALSO +.Xr vn_lock 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was originally written by +.An Doug Rabson . diff --git a/static/freebsd/man9/VOP_LISTEXTATTR.9 b/static/freebsd/man9/VOP_LISTEXTATTR.9 new file mode 100644 index 00000000..b5cbe948 --- /dev/null +++ b/static/freebsd/man9/VOP_LISTEXTATTR.9 @@ -0,0 +1,134 @@ +.\"- +.\" Copyright (c) 2003 Network Associates Technology, Inc. +.\" All rights reserved. +.\" +.\" This software was developed for the FreeBSD Project in part by Network +.\" Associates Laboratories, the Security Research Division of Network +.\" Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), +.\" as part of the DARPA CHATS research program. +.\" +.\" 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 August 19, 2005 +.Dt VOP_LISTEXTATTR 9 +.Os +.Sh NAME +.Nm VOP_LISTEXTATTR +.Nd retrieve a list of named extended attributes from a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/extattr.h +.Ft int +.Fo VOP_LISTEXTATTR +.Fa "struct vnode *vp" +.Fa "int attrnamespace" +.Fa "struct uio *uio" +.Fa "size_t *size" +.Fa "struct ucred *cred" +.Fa "struct thread *td" +.Fc +.Sh DESCRIPTION +This vnode call may be used to retrieve a list of named extended attributes +from a specified namespace on a file or directory. +.Pp +Its arguments are: +.Bl -tag -width ".Fa attrnamespace" +.It Fa vp +The vnode of the file or directory. +.It Fa attrnamespace +Integer constant indicating which extended attribute namespace the attribute +name is present in. +.It Fa uio +The location of the data to be read. +The resulting data will be a list of attribute names. +Each list entry consists of a single byte containing the length of +the attribute name, followed by the attribute name. +The attribute name is not terminated by +.Tn ASCII +.Dv NUL . +.It Fa size +If not +.Dv NULL , +on return it will contain the number of bytes required to read the list. +In most cases +.Fa uio +will be +.Dv NULL +when +.Fa size +is not, and vice versa. +.It Fa cred +The user credentials to use in authorizing the request. +.It Fa td +The thread requesting the extended attribute. +.El +.Pp +The +.Fa cred +pointer may be +.Dv NULL +to indicate that access control checks are not to be performed, if possible. +This +.Fa cred +setting might be used to allow the kernel to authorize extended attribute +retrieval that the active process might not be permitted to do. +.Pp +Extended attribute semantics may vary by file system implementing the call. +More information on extended attributes may be found in +.Xr extattr 9 . +.Sh LOCKS +The vnode will be locked on entry and should remain locked on return. +.Sh RETURN VALUES +On success, zero will be returned, and the +.Fa uio +structure will be updated to +reflect the list read. +Otherwise, an appropriate error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EACCES +The caller does not have the appropriate privilege. +.It Bq Er ENXIO +The request was not valid in this file system for the specified vnode and +attribute name. +.It Bq Er ENOMEM +Sufficient memory is not available to fulfill the request. +.It Bq Er EFAULT +The +.Fa uio +structure refers to an invalid userspace address. +.It Bq Er EINVAL +The +.Fa namespace +or +.Fa uio +argument is invalid. +.It Bq Er EOPNOTSUPP +The file system does not support +.Fn VOP_LISTEXTATTR . +.El +.Sh SEE ALSO +.Xr extattr 9 , +.Xr vnode 9 , +.Xr VOP_GETEXTATTR 9 , +.Xr VOP_SETEXTATTR 9 diff --git a/static/freebsd/man9/VOP_LOCK.9 b/static/freebsd/man9/VOP_LOCK.9 new file mode 100644 index 00000000..92bb79d4 --- /dev/null +++ b/static/freebsd/man9/VOP_LOCK.9 @@ -0,0 +1,123 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 August 23, 2022 +.Dt VOP_LOCK 9 +.Os +.Sh NAME +.Nm VOP_LOCK , +.Nm VOP_UNLOCK , +.Nm VOP_ISLOCKED , +.Nm vn_lock +.Nd serialize access to a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/lock.h +.In sys/vnode.h +.Ft int +.Fn VOP_LOCK "struct vnode *vp" "int flags" +.Ft int +.Fn VOP_UNLOCK "struct vnode *vp" +.Ft int +.Fn VOP_ISLOCKED "struct vnode *vp" +.Ft int +.Fn vn_lock "struct vnode *vp" "int flags" +.Sh DESCRIPTION +These calls are used to serialize access to the file system, such as +to prevent two writes to the same file from happening at the +same time. +.Pp +The arguments are: +.Bl -tag -width flags +.It Fa vp +The vnode being locked or unlocked. +.It Fa flags +One of the lock request types: +.Pp +.Bl -tag -width ".Dv LK_CANRECURSE" -offset indent -compact +.It Dv LK_SHARED +Shared lock. +.It Dv LK_EXCLUSIVE +Exclusive lock. +.It Dv LK_UPGRADE +Shared-to-exclusive upgrade. +.It Dv LK_DOWNGRADE +Exclusive-to-shared downgrade. +.It Dv LK_RELEASE +Release any type of lock. +.It Dv LK_DRAIN +Wait for all lock activity to end. +.El +.Pp +The lock type may be +.Em or Ns 'ed +with these lock flags: +.Pp +.Bl -tag -width ".Dv LK_CANRECURSE" -offset indent -compact +.It Dv LK_NOWAIT +Do not sleep to wait for lock. +.It Dv LK_SLEEPFAIL +Sleep, then return failure. +.It Dv LK_CANRECURSE +Allow recursive exclusive lock. +.It Dv LK_NOWITNESS +Instruct +.Xr witness 4 +to ignore this instance. +.El +.Pp +The lock type may be +.Em or Ns 'ed +with these control flags: +.Pp +.Bl -tag -width ".Dv LK_CANRECURSE" -offset indent -compact +.It Dv LK_INTERLOCK +Specify when the caller already has a simple lock +.Po Fn VOP_LOCK +will unlock the simple lock after getting the lock +.Pc . +.It Dv LK_RETRY +Retry until locked. +.El +.Pp +Kernel code should use +.Fn vn_lock +to lock a vnode rather than calling +.Fn VOP_LOCK +directly. +.Fn vn_lock +also does not want a thread specified as argument but it +assumes curthread to be used. +.El +.Sh RETURN VALUES +Zero is returned on success, otherwise an error is returned. +.Sh SEE ALSO +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/VOP_LOOKUP.9 b/static/freebsd/man9/VOP_LOOKUP.9 new file mode 100644 index 00000000..9569c315 --- /dev/null +++ b/static/freebsd/man9/VOP_LOOKUP.9 @@ -0,0 +1,180 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 August 8, 2018 +.Dt VOP_LOOKUP 9 +.Os +.Sh NAME +.Nm VOP_LOOKUP +.Nd lookup a component of a pathname +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/namei.h +.Ft int +.Fn VOP_LOOKUP "struct vnode *dvp" "struct vnode **vpp" "struct componentname *cnp" +.Sh DESCRIPTION +This entry point looks up a single pathname component in a given directory. +.Pp +Its arguments are: +.Bl -tag -width vpp +.It Fa dvp +The locked vnode of the directory to search. +.It Fa vpp +The address of a variable where the resulting locked vnode should be stored. +.It Fa cnp +The pathname component to be searched for. +It is a pointer to a componentname structure defined as follows: +.Bd -literal +struct componentname { + /* + * Arguments to lookup. + */ + u_long cn_nameiop; /* namei operation */ + u_long cn_flags; /* flags to namei */ + struct thread *cn_thread; /* thread requesting lookup */ + struct ucred *cn_cred; /* credentials */ + int cn_lkflags; /* Lock flags LK_EXCLUSIVE or LK_SHARED */ + /* + * Shared between lookup and commit routines. + */ + char *cn_pnbuf; /* pathname buffer */ + char *cn_nameptr; /* pointer to looked up name */ + long cn_namelen; /* length of looked up component */ +}; +.Ed +.El +.Pp +Convert a component of a pathname into a pointer to a locked vnode. +This is a very central and rather complicated routine. +If the file system is not maintained in a strict tree hierarchy, +this can result in a deadlock situation. +.Pp +The +.Fa cnp->cn_nameiop +argument is +.Dv LOOKUP , +.Dv CREATE , +.Dv RENAME , +or +.Dv DELETE +depending on the intended use of the object. +When +.Dv CREATE , +.Dv RENAME , +or +.Dv DELETE +is specified, information usable in +creating, renaming, or deleting a directory entry may be calculated. +.Pp +Overall outline of VOP_LOOKUP: +.Bd -ragged -offset indent +Check accessibility of directory. +Look for name in cache, if found, then return name. +Search for name in directory, goto to found or notfound as appropriate. +.Ed +.Pp +notfound: +.Bd -ragged -offset indent +If creating or renaming and at end of pathname, +return +.Er EJUSTRETURN , +leaving info on available slots else return +.Er ENOENT . +.Ed +.Pp +found: +.Bd -ragged -offset indent +If at end of path and deleting, return information to allow delete. +If at end of path and renaming, lock target +inode and return info to allow rename. +If not at end, add name to cache; if at end and neither creating +nor deleting, add name to cache. +.Ed +.Sh LOCKS +The directory +.Fa dvp +should be locked on entry and exit, regardless of error condition. +If an entry is found in the directory, it will be returned locked. +.Sh RETURN VALUES +Zero is returned with +.Fa *vpp +set to the locked vnode of the file if the component is found. +If the component being searched for is ".", then the vnode just has +an extra reference added to it with +.Xr vref 9 . +The caller must take care to release the locks appropriately in this +case. +.Pp +If the component is not found and the operation is +.Dv CREATE +or +.Dv RENAME , +the flag +.Dv ISLASTCN +is specified and the operation would succeed, the special return value +.Er EJUSTRETURN +is returned. +Otherwise, an appropriate error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ENOTDIR +The vnode +.Fa dvp +does not represent a directory. +.It Bq Er ENOENT +The component +.Fa dvp +was not found in this directory. +.It Bq Er EACCES +Access for the specified operation is denied. +.It Bq Er EJUSTRETURN +A +.Dv CREATE +or +.Dv RENAME +operation would be successful. +.El +.Sh SEE ALSO +.Xr vnode 9 , +.Xr VOP_ACCESS 9 , +.Xr VOP_CREATE 9 , +.Xr VOP_MKDIR 9 , +.Xr VOP_MKNOD 9 , +.Xr VOP_RENAME 9 , +.Xr VOP_SYMLINK 9 +.Sh HISTORY +The function +.Nm +appeared in +.Bx 4.3 . +.Sh AUTHORS +This manual page was written by +.An Doug Rabson , +with some text from comments in +.Pa ufs_lookup.c . diff --git a/static/freebsd/man9/VOP_OPENCLOSE.9 b/static/freebsd/man9/VOP_OPENCLOSE.9 new file mode 100644 index 00000000..672f9faa --- /dev/null +++ b/static/freebsd/man9/VOP_OPENCLOSE.9 @@ -0,0 +1,113 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 October 17, 2025 +.Dt VOP_OPEN 9 +.Os +.Sh NAME +.Nm VOP_OPEN , +.Nm VOP_CLOSE +.Nd open or close a file +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_OPEN "struct vnode *vp" "int mode" "struct ucred *cred" "struct thread *td" "struct file *fp" +.Ft int +.Fn VOP_CLOSE "struct vnode *vp" "int mode" "struct ucred *cred" "struct thread *td" +.Sh DESCRIPTION +The +.Fn VOP_OPEN +entry point is called before a file is accessed by a process and the +.Fn VOP_CLOSE +entry point is called after a file is finished with by the process. +.Pp +The arguments are: +.Bl -tag -width mode +.It Fa vp +The vnode of the file. +.It Fa mode +The access mode required by the calling process. +.It Fa cred +The caller's credentials. +.It Fa td +The thread which is accessing the file. +.It Fa fp +The file being opened. +.El +.Pp +Pointer to the file +.Fa fp +is useful for file systems which require such information, e.g., +.Xr fdescfs 5 . +Use +.Ql NULL +as +.Fa fp +argument to +.Fn VOP_OPEN +for in-kernel opens. +.Pp +The access mode is a set of flags, including +.Dv FREAD , +.Dv FWRITE , +.Dv O_NONBLOCK , +.Dv O_APPEND . +.Pp +The thread +.Fa td +passed to +.Fn VOP_CLOSE +may be +.Ql NULL +if the last reference to the open file is released from a kernel context, e.g., +the destruction of a socket buffer containing the file reference in a +.Dv SCM_RIGHTS +message. +.Sh LOCKS +.Fn VOP_OPEN +expects +.Fa vp +to be locked on entry and will leave it locked on return. +.Pp +.Fn VOP_CLOSE +expects at least a reference to be associated with the vnode and does not +care whether the vnode is locked or not. +The lock and reference state is left unchanged on return. +Note that +.Fa vn_close +expects an unlocked, referenced vnode and will dereference the vnode prior +to returning. +.Sh RETURN VALUES +Zero is returned on success, otherwise an error code is returned. +.Sh SEE ALSO +.Xr vnode 9 , +.Xr VOP_LOOKUP 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/VOP_PATHCONF.9 b/static/freebsd/man9/VOP_PATHCONF.9 new file mode 100644 index 00000000..299b4dc2 --- /dev/null +++ b/static/freebsd/man9/VOP_PATHCONF.9 @@ -0,0 +1,88 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 December 31, 2020 +.Dt VOP_PATHCONF 9 +.Os +.Sh NAME +.Nm VOP_PATHCONF +.Nd return POSIX pathconf information +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/unistd.h +.Ft int +.Fn VOP_PATHCONF "struct vnode *vp" "int name" "long *retval" +.Sh DESCRIPTION +The arguments are: +.Bl -tag -width retval +.It Fa vp +The vnode to get information about. +.It Fa name +The type of information to return. +.It Fa retval +The place to return the information. +.El +.Pp +The value of +.Fa name +specifies what should be returned: +.Bl -tag -width _PC_CHOWN_RESTRICTED +.It Dv _PC_LINK_MAX +The maximum number of links to a file. +.It Dv _PC_NAME_MAX +The maximum number of bytes in a file name. +.It Dv _PC_PATH_MAX +The maximum number of bytes in a pathname. +.It Dv _PC_PIPE_BUF +The maximum number of bytes which will be written atomically to a pipe. +.It Dv _PC_CHOWN_RESTRICTED +Return 1 if appropriate privileges are required for the +.Xr chown 2 +system call, otherwise 0. +.It Dv _PC_NO_TRUNC +Return 1 if file names longer than +.Dv KERN_NAME_MAX +are truncated. +.El +.Sh LOCKS +The vnode will be locked on entry and should remain locked on return. +.Sh RETURN VALUES +If +.Fa name +is recognized, +.Fa *retval +is set to the specified value and zero is returned, otherwise +.Er EINVAL +is returned. +.Sh SEE ALSO +.Xr pathconf 2 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/VOP_PRINT.9 b/static/freebsd/man9/VOP_PRINT.9 new file mode 100644 index 00000000..3e91892b --- /dev/null +++ b/static/freebsd/man9/VOP_PRINT.9 @@ -0,0 +1,52 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 July 24, 1996 +.Dt VOP_PRINT 9 +.Os +.Sh NAME +.Nm VOP_PRINT +.Nd print debugging information +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_PRINT "struct vnode *vp" +.Sh DESCRIPTION +The arguments are: +.Bl -tag -width 2n +.It Fa vp +The vnode to print. +.El +.Sh RETURN VALUES +Zero is returned on success, otherwise an error is returned. +.Sh SEE ALSO +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/VOP_RDWR.9 b/static/freebsd/man9/VOP_RDWR.9 new file mode 100644 index 00000000..2ff4b174 --- /dev/null +++ b/static/freebsd/man9/VOP_RDWR.9 @@ -0,0 +1,103 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 July 24, 1996 +.Dt VOP_RDWR 9 +.Os +.Sh NAME +.Nm VOP_READ , +.Nm VOP_WRITE +.Nd read or write a file +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/uio.h +.Ft int +.Fn VOP_READ "struct vnode *vp" "struct uio *uio" "int ioflag" "struct ucred *cred" +.Ft int +.Fn VOP_WRITE "struct vnode *vp" "struct uio *uio" "int ioflag" "struct ucred *cred" +.Sh DESCRIPTION +These entry points read or write the contents of a file. +.Pp +The arguments are: +.Bl -tag -width ioflag +.It Fa vp +The vnode of the file. +.It Fa uio +The location of the data to be read or written. +.It Fa ioflag +Various flags. +.It Fa cnp +The credentials of the caller. +.El +.Pp +The +.Fa ioflag +argument is used to give directives and hints to the file system. +When attempting a read, the high 16 bits are used to provide a +read-ahead hint (in units of file system blocks) that the file system +should attempt. +The low 16 bits are a bit mask which can contain +the following flags: +.Bl -tag -width "IO_NODELOCKED" +.It Dv IO_UNIT +Do I/O as atomic unit. +.It Dv IO_APPEND +Append write to end. +.It Dv IO_SYNC +Do I/O synchronously. +.It Dv IO_NODELOCKED +Underlying node already locked. +.It Dv IO_NDELAY +.Dv FNDELAY +flag set in file table. +.It Dv IO_VMIO +Data already in VMIO space. +.El +.Sh LOCKS +The file should be locked on entry and will still be locked on exit. +Rangelock covering the whole i/o range should be owned around the call. +.Sh RETURN VALUES +Zero is returned on success, otherwise an error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EFBIG +An attempt was made to write a file that exceeds the process's file size +limit or the maximum file size. +.It Bq Er ENOSPC +The file system is full. +.It Bq Er EPERM +An append-only flag is set on the file, but the caller is attempting to +write before the current end of file. +.El +.Sh SEE ALSO +.Xr uiomove 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/VOP_READDIR.9 b/static/freebsd/man9/VOP_READDIR.9 new file mode 100644 index 00000000..d2cf7c6c --- /dev/null +++ b/static/freebsd/man9/VOP_READDIR.9 @@ -0,0 +1,108 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 December 13, 2021 +.Dt VOP_READDIR 9 +.Os +.Sh NAME +.Nm VOP_READDIR +.Nd read contents of a directory +.Sh SYNOPSIS +.In sys/param.h +.In sys/dirent.h +.In sys/vnode.h +.Ft int +.Fn VOP_READDIR "struct vnode *vp" "struct uio *uio" "struct ucred *cred" "int *eofflag" "int *ncookies" "uint64_t **cookies" +.Sh DESCRIPTION +Read directory entries. +.Bl -tag -width ncookies +.It Fa vp +The vnode of the directory. +.It Fa uio +Where to read the directory contents. +.It Fa cred +The caller's credentials. +.It Fa eofflag +Return end of file status +.Dv ( NULL +if not wanted). +.It Fa ncookies +Number of directory cookies generated for NFS +.Dv ( NULL +if not wanted). +.It Fa cookies +Directory seek cookies generated for NFS +.Dv ( NULL +if not wanted). +.El +The directory contents are read into +.Vt struct dirent +structures. +If the on-disc data structures differ from this then they +should be translated. +.Sh LOCKS +The directory should be locked on entry and will still be locked on exit. +.Sh RETURN VALUES +Zero is returned on success, otherwise an error code is returned. +.Pp +If this is called from the NFS server, the extra arguments +.Fa eofflag , +.Fa ncookies +and +.Fa cookies +are given. +The value of +.Fa *eofflag +should be set to TRUE if the end of the directory is reached while +reading. +The directory seek cookies are returned to the NFS client and may be used +later to restart a directory read part way through the directory. +There should be one cookie returned per directory entry. +The value of +the cookie should be the offset within the directory where the on-disc +version of the appropriate directory entry starts. +Memory for the cookies should be allocated using: +.Bd -literal + ...; + *ncookies = number of entries read; + *cookies = malloc(*ncookies * sizeof(**cookies), M_TEMP, M_WAITOK); +.Ed +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINVAL +An attempt was made to read from an illegal offset in the directory. +.It Bq Er EIO +A read error occurred while reading the directory. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading the directory. +.El +.Sh SEE ALSO +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/VOP_READLINK.9 b/static/freebsd/man9/VOP_READLINK.9 new file mode 100644 index 00000000..ff9ce181 --- /dev/null +++ b/static/freebsd/man9/VOP_READLINK.9 @@ -0,0 +1,67 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 March 30, 2020 +.Dt VOP_READLINK 9 +.Os +.Sh NAME +.Nm VOP_READLINK +.Nd read the target of a symbolic link +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/uio.h +.Ft int +.Fn VOP_READLINK "struct vnode *vp" "struct uio *uio" "struct ucred *cred" +.Sh DESCRIPTION +This reads the target pathname of a symbolic link +.Bl -tag -width uio +.It Fa vp +The vnode of the symlink. +.It Fa uio +The location of the data to be read or written. +.It Fa cred +The credentials of the caller. +.El +.Sh LOCKS +The vnode should be locked on entry and will still be locked on exit. +.Sh RETURN VALUES +Zero is returned on success, otherwise an error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EIO +A read error occurred while reading the contents of the symlink. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading the contents of the symlink. +.El +.Sh SEE ALSO +.Xr uiomove 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/VOP_READ_PGCACHE.9 b/static/freebsd/man9/VOP_READ_PGCACHE.9 new file mode 100644 index 00000000..8a99365e --- /dev/null +++ b/static/freebsd/man9/VOP_READ_PGCACHE.9 @@ -0,0 +1,131 @@ +.\" Copyright (c) 2021 The FreeBSD Foundation +.\" +.\" This documentation was written by +.\" Konstantin Belousov under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" 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 AUTHORS 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 AUTHORS 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 February 28, 2021 +.Dt VOP_READ_PGCACHE 9 +.Os +.Sh NAME +.Nm VOP_READ_PGCACHE +.Nd read a file, fast +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/uio.h +.Ft int +.Fo VOP_READ_PGCACHE +.Fa "struct vnode *vp" +.Fa "struct uio *uio" +.Fa "int ioflag" +.Fa "struct ucred *cred" +.Fc +.Sh DESCRIPTION +This entry point reads the contents of a file. +The intent is to provide the data from caches, which do not require +expensive operations or any disk IO. +For instance, if filesystem uses normal VM page cache and maintains +.Dv v_object +lifetime, it can use +.Xr vn_read_from_obj 9 +helper to return data from the resident +.Dv vp->v_object +pages. +.Pp +The filesystem indicates support for the +.Nm +on specific vnode by setting the +.Dv VIRF_PGREAD +flag in +.Dv vp->v_irflag . +.Pp +The function does not need to satisfy the whole request; it also might choose +to not provide any data. +In these cases, the +.Fa uio +must be advanced by the amount of read data, +.Nm +should return +.Er EJUSTRETURN , +and VFS would handle the rest of the read operation using the +.Xr VOP_READ 9 . +.Pp +The VFS layer does the same deadlock avoidance for accessing userspace +pages from +.Nm +as for +.Xr VOP_READ 9 . +.Pp +Vnode is not locked on the call entry and should not be locked on return. +For a filesystem that requires vnode lock to return any data, it does +not make sense to implement +.Nm +(and set +.Dv VIRF_PGREAD +flag) since VFS arranges the call to +.Xr VOP_READ 9 +as needed. +.Pp +The arguments are: +.Bl -tag -width ioflag +.It Fa vp +The vnode of the file. +.It Fa uio +The location of the data to be read. +.It Fa ioflag +Various flags, see +.Xr VOP_READ 9 +for the list. +.It Fa cred +The credentials of the caller. +.El +.Pp +.Nm +does not handle non-zero +.Fa ioflag +argument. +.Sh LOCKS +The file should be referenced on entry on entry and will still be +referenced on exit. +Rangelock covering the whole read range should be owned around the call. +.Sh RETURN VALUES +Zero is returned on success, when the whole request is satisfied, and no +more data cannot be provided for it by any means. +If more data can be returned, but +.Nm +was unable to provide it, +.Er EJUSTRETURN +must be returned. +The +.Dv uio +records should be updated according to the partial operation done. +.Pp +Otherwise an error code is returned, +same as from +.Xr VOP_READ 9 +.Sh SEE ALSO +.Xr uiomove 9 , +.Xr vnode 9 , +.Xr VOP_READ 9 diff --git a/static/freebsd/man9/VOP_REALLOCBLKS.9 b/static/freebsd/man9/VOP_REALLOCBLKS.9 new file mode 100644 index 00000000..b07b4ba6 --- /dev/null +++ b/static/freebsd/man9/VOP_REALLOCBLKS.9 @@ -0,0 +1,57 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 July 24, 1996 +.Dt VOP_REALLOCBLKS 9 +.Os +.Sh NAME +.Nm VOP_REALLOCBLKS +.Nd rearrange blocks in a file to be contiguous +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_REALLOCBLKS "struct vnode *vp" "struct cluster_save *buflist" +.Sh DESCRIPTION +The arguments are: +.Bl -tag -width buflist +.It Fa vp +The file to manipulate. +.It Fa buflist +A list of buffers to rearrange. +.El +.Pp +This seems to be part of a work in progress. +.Sh RETURN VALUES +Zero is returned on success, otherwise an error is returned. +.Sh SEE ALSO +.Xr buf 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/VOP_REMOVE.9 b/static/freebsd/man9/VOP_REMOVE.9 new file mode 100644 index 00000000..c4a702f8 --- /dev/null +++ b/static/freebsd/man9/VOP_REMOVE.9 @@ -0,0 +1,75 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 July 24, 1996 +.Dt VOP_REMOVE 9 +.Os +.Sh NAME +.Nm VOP_REMOVE , +.Nm VOP_RMDIR +.Nd remove a file or directory +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_REMOVE "struct vnode *dvp" "struct vnode *vp" "struct componentname *cnp" +.Ft int +.Fn VOP_RMDIR "struct vnode *dvp" "struct vnode *vp" "struct componentname *cnp" +.Sh DESCRIPTION +These entry points remove files and directories respectively. +.Pp +The arguments are: +.Bl -tag -width dvp +.It Fa dvp +The vnode of the directory. +.It Fa vp +The vnode of the file to be removed. +.It Fa cnp +Pathname information about the file. +.El +.Sh LOCKS +Both +.Fa dvp +and +.Fa vp +should be locked on entry and remain locked on return. +.Sh RETURN VALUES +Zero is returned on success, otherwise an error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EPERM +The file is immutable. +.It Bq Er ENOTEMPTY +An attempt was made to remove a directory which is not empty. +.El +.Sh SEE ALSO +.Xr vnode 9 , +.Xr VOP_LOOKUP 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/VOP_RENAME.9 b/static/freebsd/man9/VOP_RENAME.9 new file mode 100644 index 00000000..551178f5 --- /dev/null +++ b/static/freebsd/man9/VOP_RENAME.9 @@ -0,0 +1,94 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 July 24, 1996 +.Dt VOP_RENAME 9 +.Os +.Sh NAME +.Nm VOP_RENAME +.Nd rename a file +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_RENAME "struct vnode *fdvp" "struct vnode *fvp" "struct componentname *fcnp" "struct vnode *tdvp" "struct vnode *tvp" "struct componentname *tcnp" +.Sh DESCRIPTION +This renames a file and possibly changes its parent directory. +If the destination object exists, it will be removed first. +.Pp +Its arguments are: +.Bl -tag -width fdvp +.It Fa fdvp +The vnode of the old parent directory. +.It Fa fvp +The vnode of the file to be renamed. +.It Fa fcnp +Pathname information about the file's current name. +.It Fa tdvp +The vnode of the new parent directory. +.It Fa tvp +The vnode of the target file (if it exists). +.It Fa tcnp +Pathname information about the file's new name. +.El +.Sh LOCKS +The source directory and file are unlocked but are expected to have their +ref count bumped on entry. +The VOP routine is expected to +.Xr vrele 9 +both prior +to returning. +.Pp +The destination directory and file are locked as well as having their ref +count bumped. +The VOP routine is expected to +.Xr vput 9 +both prior to +returning. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EPERM +The file is immutable. +.It Bq Er EXDEV +It is not possible to rename a file between different file systems. +.It Bq Er EINVAL +An attempt was made to rename +.Pa \&. +or +.Pa .. , +or to perform an operation which would break the directory tree structure. +.It Bq Er ENOTDIR +An attempt was made to rename a directory to a file or vice versa. +.It Bq Er ENOTEMPTY +An attempt was made to remove a directory which is not empty. +.El +.Sh SEE ALSO +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/VOP_REVOKE.9 b/static/freebsd/man9/VOP_REVOKE.9 new file mode 100644 index 00000000..5444cbe2 --- /dev/null +++ b/static/freebsd/man9/VOP_REVOKE.9 @@ -0,0 +1,68 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2002 Networks Associates Technology, Inc. +.\" All rights reserved. +.\" +.\" This software was developed for the FreeBSD Project by NAI Labs, the +.\" Security Research Division of Network Associates, Inc. under +.\" DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the DARPA +.\" CHATS research program. +.\" +.\" 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. The names of the authors 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 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 June 20, 2019 +.Dt VOP_REVOKE 9 +.Os +.Sh NAME +.Nm VOP_REVOKE +.Nd "revoke access to a device and its aliases" +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_REVOKE "struct vnode *vp" "int flags" +.Sh DESCRIPTION +.Fn VOP_REVOKE +will administratively revoke access to the device specified by +.Fa vp , +as well as any aliases created via +.Xr make_dev_alias 9 . +Further file operations on any of these devices by processes +which have them open will nominally fail. +The +.Fa flags +must be set to +.Dv REVOKEALL +to signify that all access will be revoked; any other value is invalid. +.Sh LOCKS +The +.Fa vp +must be exclusively locked on entry, and will remain locked upon return. +.Sh SEE ALSO +.Xr make_dev_alias 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Brian Fundakowski Feldman . diff --git a/static/freebsd/man9/VOP_SETACL.9 b/static/freebsd/man9/VOP_SETACL.9 new file mode 100644 index 00000000..ec3b25a1 --- /dev/null +++ b/static/freebsd/man9/VOP_SETACL.9 @@ -0,0 +1,103 @@ +.\"- +.\" Copyright (c) 1999, 2000, 2001 Robert N. M. Watson +.\" 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 December 23, 1999 +.Dt VOP_SETACL 9 +.Os +.Sh NAME +.Nm VOP_SETACL +.Nd set the access control list for a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/acl.h +.Ft int +.Fn VOP_SETACL "struct vnode *vp" "acl_type_t type" "struct acl *aclp" "struct ucred *cred" "struct thread *td" +.Sh DESCRIPTION +This vnode call may be used to set the access control list (ACL) for a file +or directory. +.Pp +Its arguments are: +.Bl -tag -width type +.It Fa vp +The vnode of the file or directory. +.It Fa type +The type of ACL to set. +.It Fa aclp +A pointer to an ACL structure from which to retrieve the ACL data. +.It Fa cred +The user credentials to use in authorizing the request. +.It Fa td +The thread setting the ACL. +.El +.Pp +The +.Fa aclp +pointer may be +.Dv NULL +to indicate that the specified ACL should be deleted. +.Pp +The +.Fa cred +pointer may be +.Dv NULL +to indicate that access control checks are not to be performed, if possible. +This cred setting might be used to allow the kernel to authorize ACL +changes that the active process might not be permitted to make. +.Pp +The vnode ACL interface defines the syntax, and not semantics, of file and +directory ACL interfaces. +More information about ACL management in kernel +may be found in +.Xr acl 9 . +.Sh LOCKS +The vnode will be locked on entry and should remain locked on return. +.Sh RETURN VALUES +If the ACL is successfully set, then zero is returned. +Otherwise, an appropriate error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINVAL +The ACL type passed is invalid for this vnode, or the ACL data is invalid. +.It Bq Er EACCES +The caller does not have the appropriate privilege. +.It Bq Er ENOMEM +Sufficient memory is not available to fulfill the request. +.It Bq Er EOPNOTSUPP +The file system does not support +.Fn VOP_SETACL . +.It Bq Er ENOSPC +The file system is out of space. +.It Bq Er EROFS +The file system is read-only. +.El +.Sh SEE ALSO +.Xr acl 9 , +.Xr vnode 9 , +.Xr VOP_ACLCHECK 9 , +.Xr VOP_GETACL 9 +.Sh AUTHORS +This manual page was written by +.An Robert Watson . diff --git a/static/freebsd/man9/VOP_SETEXTATTR.9 b/static/freebsd/man9/VOP_SETEXTATTR.9 new file mode 100644 index 00000000..a0ca7a5a --- /dev/null +++ b/static/freebsd/man9/VOP_SETEXTATTR.9 @@ -0,0 +1,117 @@ +.\"- +.\" Copyright (c) 1999, 2000, 2001 Robert N. M. Watson +.\" 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 December 23, 1999 +.Dt VOP_SETEXTATTR 9 +.Os +.Sh NAME +.Nm VOP_SETEXTATTR +.Nd set named extended attribute for a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/extattr.h +.Ft int +.Fn VOP_SETEXTATTR "struct vnode *vp" "int attrnamespace" "const char *name" "struct uio *uio" "struct ucred *cred" "struct thread *td" +.Sh DESCRIPTION +This vnode call may be used to set specific named extended attribute for a +file or directory. +.Pp +Its arguments are: +.Bl -tag -width type +.It Fa vp +The vnode of the file or directory. +.It Fa attrnamespace +Integer constant indicating which extended attribute namespace the attribute +name is present in. +.It Fa name +Pointer to a null-terminated character string containing the attribute name. +.It Fa uio +The location of the data to be read or written. +.It Fa cred +The user credentials to use in authorizing the request. +.It Fa td +The thread setting the extended attribute. +.El +.Pp +The uio structure is used in a manner similar to the argument of the same +name in +.Xr VOP_WRITE 9 . +However, as extended attributes provide a strict "name=value" semantic, +non-zero offsets will be rejected. +.Pp +The +.Fa uio +pointer may be +.Dv NULL +to indicate that the specified extended attribute should be deleted. +.Pp +The +.Fa cred +pointer may be +.Dv NULL +to indicate that access control checks are not to be performed, if possible. +This +.Fa cred +setting might be used to allow the kernel to authorize extended attribute +changes that the active process might not be permitted to make. +.Pp +Extended attribute semantics may vary by file system implementing the call. +More information on extended attributes may be found in +.Xr extattr 9 . +.Sh LOCKS +The vnode will be locked on entry and should remain locked on return. +.Sh RETURN VALUES +If the extended attribute is successfully set, then zero is returned. +Otherwise, an appropriate error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EACCES +The caller does not have the appropriate privilege. +.It Bq Er ENXIO +The request was not valid in this file system for the specified vnode and +attribute name. +.It Bq Er ENOMEM +Insufficient memory available to fulfill the request. +.It Bq Er EFAULT +The uio structure refers to an invalid userspace address. +.It Bq Er EINVAL +The name, namespace, or uio argument is invalid. +.It Bq Er EOPNOTSUPP +The file system does not support +.Fn VOP_SETEXTATTR . +.It Bq Er ENOSPC +The file system is out of space. +.It Bq Er EROFS +The file system is read-only. +.El +.Sh SEE ALSO +.Xr extattr 9 , +.Xr vnode 9 , +.Xr VOP_GETEXTATTR 9 , +.Xr VOP_LISTEXTATTR 9 +.Sh AUTHORS +This manual page was written by +.An Robert Watson . diff --git a/static/freebsd/man9/VOP_SETLABEL.9 b/static/freebsd/man9/VOP_SETLABEL.9 new file mode 100644 index 00000000..4ab7dd9b --- /dev/null +++ b/static/freebsd/man9/VOP_SETLABEL.9 @@ -0,0 +1,125 @@ +.\"- +.\" Copyright (c) 2021 Robert N. M. Watson +.\" 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 February 27, 2021 +.Dt VOP_SETLABEL 9 +.Os +.Sh NAME +.Nm VOP_SETLABEL +.Nd persistently store an updated MAC label on a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In security/mac.h +.Ft int +.Fn VOP_SETLABEL "struct vnode *vp" "label *label" +.Sh DESCRIPTION +This vnode call is made by +.Xr mac 9 +file relabeling operation has been authorized, and the filesystem must now be +updated. +.Ss Single-Label vs. Multi-Label Filesystems +Filesystems that do not implement per-file labels -- known as single-label +filesystems -- can simply leave the +.Xr vnode 9 +operation undefined. +These filesystems must not set the +.Dv MNT_MULTLABEL +flag in their +.Vt struct mount . +.Pp +Filesystems that do implement per-vnode label storage -- known as multi-label +filesystems -- will set the +.Dv MNT_MULTILABEL +flag in their +.Vt struct mount . +The UFS filesystem uses a superblock flag to persisently configure whether a +specific filesystem implements a label for each +.Xr vnode 9 , +and then keys various behaviors on whether that flag is set. +.Ss Extended Attributes +If the filesystem implements extended attributes, then the MAC Framework's +.Fn vop_stdsetlabel_ea +function can be used, and maps operations into a series of +.Xr VOP_OPENEXTATTR 9 , +.Xr VOP_WRITEEXTATTR 9 , +and +.Xr VOP_CLOSEEXTATTR 9 . +.Pp +Filesystems will also need to call +.Fn mac_vnode_create_extattr +when a new filesystem object is created, so that suitable extended attributes +can be written out, and +.Fn mac_vnode_associate_extattr +when a +.Xr vnode 9 +is associated with a filesystem object for the first time. +These utility functions use +.Xr VOP_OPENEXTATTR 9 , +.Xr VOP_READEXTATTR 9 , +.Xr VOP_WRITEEXTATTR 9 , +and +.Xr VOP_CLOSEEXTATTR 9 +as required. +.Ss Locking and Crash Safety +In all cases, it is important that exclusive +.Xr vnode 9 +locks be held to prevent concurrent access when a MAC label may not yet be +initialized. +It is also important that operations are ordered so that a system crash does +not leave a file improperly labeled. +For example, the extended attribute for a newly created file must be written +to disk before the file is linked by its parent directory, so that there is +no opportunity for a crash to lead to an unlabeled file. +.Sh LOCKS +The vnode will be locked on entry and should remain locked on return. +.Sh RETURN VALUES +If the MAC label is successfully set, then zero is returned. +Otherwise, an appropriate error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EOPNOTSUPP +The file system does not support +.Fn VOP_SETLABEL . +.It Bq Er ENOSPC +The file system is out of space. +.It Bq Er EROFS +The file system is read-only. +.El +.Pp +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 +.Sh AUTHORS +This manual page was written by +.An Robert Watson . diff --git a/static/freebsd/man9/VOP_STRATEGY.9 b/static/freebsd/man9/VOP_STRATEGY.9 new file mode 100644 index 00000000..866ec61a --- /dev/null +++ b/static/freebsd/man9/VOP_STRATEGY.9 @@ -0,0 +1,71 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 June 30, 2022 +.Dt VOP_STRATEGY 9 +.Os +.Sh NAME +.Nm VOP_STRATEGY +.Nd read or write a file system buffer +.Sh SYNOPSIS +.In sys/param.h +.In sys/buf.h +.In sys/vnode.h +.Ft int +.Fn VOP_STRATEGY "struct vnode *vp" "struct buf *bp" +.Sh DESCRIPTION +The arguments are: +.Bl -tag -width 2n +.It Fa vp +The vnode that the buffer is for. +.It Fa bp +The buffer to be read or written. +.El +.Pp +This call either reads or writes data from a file, depending on the value of +.Fa bp->b_iocmd . +.Pp +The call may block. +.Sh RETURN VALUES +Always zero. +Errors should be signalled by setting the +.Dv BIO_ERROR +bit in +.Fa bp->b_ioflags +and setting +.Fa bp->b_error +to the appropriate +.Va errno +value. +.Sh SEE ALSO +.Xr errno 2 , +.Xr buf 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/VOP_VPTOCNP.9 b/static/freebsd/man9/VOP_VPTOCNP.9 new file mode 100644 index 00000000..0c6517d1 --- /dev/null +++ b/static/freebsd/man9/VOP_VPTOCNP.9 @@ -0,0 +1,94 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2008 Joe Marcus Clarke +.\" +.\" 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 March 8, 2015 +.Dt VOP_VPTOCNP 9 +.Os +.Sh NAME +.Nm VOP_VPTOCNP +.Nd translate a vnode to its component name +.Sh SYNOPSIS +.In sys/param.h +.In sys/ucred.h +.In sys/vnode.h +.Ft int +.Fn VOP_VPTOCNP "struct vnode *vp" "struct vnode **dvp" "struct ucred *cred" "char *buf" "int *buflen" +.Sh DESCRIPTION +This translates a vnode into its component name, and writes that name to +the head of the buffer specified by +.Fa buf . +.Bl -tag -width buflen +.It Fa vp +The vnode to translate. +.It Fa dvp +The vnode of the parent directory of +.Fa vp . +.It Fa cred +The caller credentials. +.It Fa buf +The buffer into which to prepend the component name. +.It Fa buflen +The remaining size of the buffer. +.El +.Pp +The default implementation of +.Nm +scans through +.Fa vp Ns 's +parent directory looking for a dirent with a matching file number. +If +.Fa vp +is not a directory, then +.Nm +returns ENOENT. +.Sh LOCKS +The vnode should be locked on entry and will still be locked on exit. +The parent directory vnode will be unlocked on a successful exit. +However, it will have its use count incremented. +.Sh RETURN VALUES +Zero is returned on success, otherwise an error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ENOMEM +The buffer was not large enough to hold the vnode's component name. +.It Bq Er ENOENT +The vnode was not found on the file system. +.El +.Sh SEE ALSO +.Xr vnode 9 , +.Xr VOP_LOOKUP 9 +.Sh NOTES +This interface is a work in progress. +.Sh HISTORY +The function +.Nm +appeared in +.Fx 8.0 . +.Sh AUTHORS +This manual page was written by +.An Joe Marcus Clarke . diff --git a/static/freebsd/man9/VOP_VPTOFH.9 b/static/freebsd/man9/VOP_VPTOFH.9 new file mode 100644 index 00000000..2a2f301e --- /dev/null +++ b/static/freebsd/man9/VOP_VPTOFH.9 @@ -0,0 +1,58 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 February 16, 2007 +.Dt VOP_VPTOFH 9 +.Os +.Sh NAME +.Nm VOP_VPTOFH +.Nd turn a vnode into an NFS filehandle +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_VPTOFH "struct vnode *vp" "struct fid *fhp" +.Sh DESCRIPTION +This is used by the NFS server to create an opaque filehandle which +uniquely identifies the file and which can be used by an NFS client +to access the file in the future. +.Pp +Its arguments are: +.Bl -tag -width fhp +.It Fa vp +The vnode to make a filehandle for. +.It Fa fhp +Return parameter for the filehandle. +.El +.Sh SEE ALSO +.Xr VFS 9 , +.Xr VFS_FHTOVP 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/accept_filter.9 b/static/freebsd/man9/accept_filter.9 new file mode 100644 index 00000000..0b8acc90 --- /dev/null +++ b/static/freebsd/man9/accept_filter.9 @@ -0,0 +1,150 @@ +.\" +.\" Copyright (c) 2000 Alfred Perlstein +.\" +.\" 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 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 June 25, 2000 +.Dt ACCEPT_FILTER 9 +.Os +.Sh NAME +.Nm accept_filter , +.Nm accept_filt_add , +.Nm accept_filt_del , +.Nm accept_filt_generic_mod_event , +.Nm accept_filt_get +.Nd filter incoming connections +.Sh SYNOPSIS +.In sys/types.h +.In sys/module.h +.In sys/socket.h +.Fd #define ACCEPT_FILTER_MOD +.In sys/socketvar.h +.Ft int +.Fn accept_filt_add "struct accept_filter *filt" +.Ft int +.Fn accept_filt_del "char *name" +.Ft int +.Fn accept_filt_generic_mod_event "module_t mod" "int event" "void *data" +.Ft struct accept_filter * +.Fn accept_filt_get "char *name" +.Sh DESCRIPTION +Accept filters allow an application to request +that the kernel pre-process incoming connections. +An accept filter is requested via the +.Xr setsockopt 2 +system call, passing in an +.Fa optname +of +.Dv SO_ACCEPTFILTER . +.Sh IMPLEMENTATION NOTES +A module that wants to be an accept filter +must provide a +.Vt "struct accept_filter" +to the system: +.Bd -literal +struct accept_filter { + char accf_name[16]; + void (*accf_callback)(struct socket *so, void *arg, int waitflag); + void * (*accf_create)(struct socket *so, char *arg); + void (*accf_destroy)(struct socket *so); + SLIST_ENTRY(accept_filter) accf_next; /* next on the list */ +}; +.Ed +.Pp +The module should register it with the function +.Fn accept_filt_add , +passing a pointer to a +.Vt "struct accept_filter" , +allocated with +.Xr malloc 9 . +.Pp +The fields of +.Vt "struct accept_filter" +are as follows: +.Bl -tag -width ".Va accf_callback" +.It Va accf_name +Name of the filter; +this is how it will be accessed from userland. +.It Va accf_callback +The callback that the kernel will do +once the connection is established. +It is the same as a socket upcall +and will be called when the connection is established +and whenever new data arrives on the socket, +unless the callback modifies the socket's flags. +.It Va accf_create +Called whenever a +.Xr setsockopt 2 +installs the filter onto +a listening socket. +.It Va accf_destroy +Called whenever the user removes the accept filter on the socket. +.El +.Pp +The +.Fn accept_filt_del +function +passed the same string used in +.Va accept_filter.accf_name +during registration with +.Fn accept_filt_add , +the kernel will then disallow and further userland use of the filter. +.Pp +The +.Fn accept_filt_get +function is used internally to locate which accept filter to use via the +.Xr setsockopt 2 +system call. +.Pp +The +.Fn accept_filt_generic_mod_event +function provides a simple way to avoid duplication of code +for accept filters which do not use the argument field to load +and unload themselves. +This function can be used in the +.Vt moduledata_t +struct for the +.Xr DECLARE_MODULE 9 +macro. +.Sh SEE ALSO +.Xr setsockopt 2 , +.Xr accf_data 9 , +.Xr accf_dns 9 , +.Xr accf_http 9 , +.Xr malloc 9 +.Sh HISTORY +The accept filter mechanism was introduced in +.Fx 4.0 . +.Sh AUTHORS +This manual page was written by +.An -nosplit +.An Alfred Perlstein , +.An Sheldon Hearn +and +.An Jeroen Ruigrok van der Werven . +.Pp +The accept filter concept was pioneered by +.An David Filo +at Yahoo!\& +and refined to be a loadable module system by +.An Alfred Perlstein . diff --git a/static/freebsd/man9/accf_data.9 b/static/freebsd/man9/accf_data.9 new file mode 100644 index 00000000..47d84d17 --- /dev/null +++ b/static/freebsd/man9/accf_data.9 @@ -0,0 +1,79 @@ +.\" +.\" Copyright (c) 2000 Alfred Perlstein +.\" +.\" 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 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 November 15, 2000 +.Dt ACCF_DATA 9 +.Os +.Sh NAME +.Nm accf_data +.Nd buffer incoming connections until data arrives +.Sh SYNOPSIS +.Cd options INET +.Cd options ACCEPT_FILTER_DATA +.Pp +In +.Xr rc.conf 5 : +.Cd kld_list="accf_data" +.Sh DESCRIPTION +This is a filter to be placed on a socket that will be using +.Fn accept +to receive incoming connections. +.Pp +It prevents the application from receiving the connected descriptor via +.Fn accept +until data arrives on the connection. +.Pp +The +.Fa ACCEPT_FILTER_DATA +kernel option is also a module that can be enabled at runtime via +.Xr kldload 8 +if the INET option has been compiled into the kernel. +.Sh EXAMPLES +Assuming ACCEPT_FILTER_DATA has been included in the kernel config +file or the +.Nm +module +has been loaded, this will enable the data accept filter +on the socket +.Fa sok . +.Bd -literal -offset 0i + struct accept_filter_arg afa; + + bzero(&afa, sizeof(afa)); + strcpy(afa.af_name, "dataready"); + setsockopt(sok, SOL_SOCKET, SO_ACCEPTFILTER, &afa, sizeof(afa)); +.Ed +.Sh SEE ALSO +.Xr setsockopt 2 , +.Xr accept_filter 9 , +.Xr accf_dns 9 , +.Xr accf_http 9 +.Sh HISTORY +The accept filter mechanism and the +accf_data filter were introduced in +.Fx 4.0 . +.Sh AUTHORS +This manual page and the filter were written by +.An Alfred Perlstein . diff --git a/static/freebsd/man9/accf_dns.9 b/static/freebsd/man9/accf_dns.9 new file mode 100644 index 00000000..00b7bcf1 --- /dev/null +++ b/static/freebsd/man9/accf_dns.9 @@ -0,0 +1,80 @@ +.\" +.\" Copyright (c) 2008 David Malone +.\" +.\" 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 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 July 16, 2008 +.Dt ACCF_DNS 9 +.Os +.Sh NAME +.Nm accf_dns +.Nd buffer incoming DNS requests until the whole first request is present +.Sh SYNOPSIS +.Cd options INET +.Cd options ACCEPT_FILTER_DNS +.Pp +In +.Xr rc.conf 5 : +.Cd kld_list="accf_dns" +.Sh DESCRIPTION +This is a filter to be placed on a socket that will be using +.Fn accept +to receive incoming connections. +.Pp +It prevents the application from receiving the connected descriptor via +.Fn accept +until a whole DNS request is available on the socket. +It does this by reading the first two bytes of the request, +to determine its size, +and waiting until the required amount of data is available to be read. +.Pp +The +.Fa ACCEPT_FILTER_DNS +kernel option is also a module that can be enabled at runtime via +.Xr kldload 8 +if the INET option has been compiled into the kernel. +.Sh EXAMPLES +If the +.Nm +module is available in the kernel, +the following code will enable the DNS accept filter +on a socket +.Fa sok . +.Bd -literal -offset 0i + struct accept_filter_arg afa; + + bzero(&afa, sizeof(afa)); + strcpy(afa.af_name, "dnsready"); + setsockopt(sok, SOL_SOCKET, SO_ACCEPTFILTER, &afa, sizeof(afa)); +.Ed +.Sh SEE ALSO +.Xr setsockopt 2 , +.Xr accept_filter 9 , +.Xr accf_data 9 , +.Xr accf_http 9 +.Sh HISTORY +The accept filter mechanism was introduced in +.Fx 4.0 . +.Sh AUTHORS +This manual page and the filter were written by +.An David Malone . diff --git a/static/freebsd/man9/accf_http.9 b/static/freebsd/man9/accf_http.9 new file mode 100644 index 00000000..6037088f --- /dev/null +++ b/static/freebsd/man9/accf_http.9 @@ -0,0 +1,99 @@ +.\" +.\" Copyright (c) 2000 Alfred Perlstein +.\" +.\" 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 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 November 15, 2000 +.Dt ACCF_HTTP 9 +.Os +.Sh NAME +.Nm accf_http +.Nd "buffer incoming connections until a certain complete HTTP request arrives" +.Sh SYNOPSIS +.Cd options INET +.Cd options ACCEPT_FILTER_HTTP +.Pp +In +.Xr rc.conf 5 : +.Cd kld_list="accf_http" +.Sh DESCRIPTION +This is a filter to be placed on a socket that will be using +.Fn accept +to receive incoming HTTP connections. +.Pp +It prevents the application from receiving the connected descriptor via +.Fn accept +until either a full HTTP/1.0 or HTTP/1.1 HEAD or GET request has +been buffered by the kernel. +.Pp +If something other than a HTTP/1.0 or +HTTP/1.1 HEAD or GET request is received the kernel will +allow the application to receive the connection descriptor +via +.Fn accept . +.Pp +The utility of +.Nm +is such that a server will not have to context switch several times +before performing the initial parsing of the request. +This effectively reduces the amount of required CPU utilization +to handle incoming requests by keeping active +processes in preforking servers such as Apache low +and reducing the size of the file descriptor set that needs +to be managed by interfaces such as +.Fn select , +.Fn poll +or +.Fn kevent +based servers. +.Pp +The +.Nm +kernel option is also a module that can be enabled at runtime via +.Xr kldload 8 +if the INET option has been compiled into the kernel. +.Sh EXAMPLES +Assuming ACCEPT_FILTER_HTTP has been included in the kernel config +file or the +.Nm +module +has been loaded, this will enable the http accept filter +on the socket +.Fa sok . +.Bd -literal -offset 0i + struct accept_filter_arg afa; + + bzero(&afa, sizeof(afa)); + strcpy(afa.af_name, "httpready"); + setsockopt(sok, SOL_SOCKET, SO_ACCEPTFILTER, &afa, sizeof(afa)); +.Ed +.Sh SEE ALSO +.Xr setsockopt 2 , +.Xr accept_filter 9 +.Sh HISTORY +The accept filter mechanism and the +accf_http filter were introduced in +.Fx 4.0 . +.Sh AUTHORS +This manual page and the filter were written by +.An Alfred Perlstein . diff --git a/static/freebsd/man9/accf_tls.9 b/static/freebsd/man9/accf_tls.9 new file mode 100644 index 00000000..ce73b370 --- /dev/null +++ b/static/freebsd/man9/accf_tls.9 @@ -0,0 +1,98 @@ +.\" +.\" Copyright (c) 2024 Gleb Smirnoff +.\" +.\" 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 April 24, 2024 +.Dt ACCF_TLS 9 +.Os +.Sh NAME +.Nm accf_tls +.Nd "buffer incoming connections until a TLS handshake like request arrives" +.Sh SYNOPSIS +.Cd options INET +.Cd options ACCEPT_FILTER_TLS +.Pp +In +.Xr rc.conf 5 : +.Cd kld_list="accf_tls" +.Sh DESCRIPTION +This is a filter to be placed on a socket that will be using +.Fn accept 2 +to receive incoming HTTPS connections. +It prevents the application from receiving the connected descriptor via +.Fn accept 2 +until a full TLS handshake has been buffered by the kernel. +The +.Nm +will first check that byte at offset 0 is +.Va 0x16 , +which matches handshake type. +Then it will read 2-byte request length value at offset 3 and will +continue reading until reading the entire length of the handshake is buffered. +If something other than +.Va 0x16 +is at offset 0, the kernel will allow the application to receive the +connection descriptor via +.Fn accept 2 . +.Pp +The utility of +.Nm +is such that a server will not have to context switch several times +before performing the initial parsing of the request. +This effectively reduces the amount of required CPU utilization +to handle incoming requests by keeping active +processes in preforking servers such as Apache low +and reducing the size of the file descriptor set that needs +to be managed by interfaces such as +.Fn select , +.Fn poll +or +.Fn kevent +based servers. +.Sh EXAMPLES +Assuming ACCEPT_FILTER_TLS has been included in the kernel config +file or the +.Nm +module +has been loaded, this will enable the TLS accept filter +on the socket +.Fa sok . +.Bd -literal -offset 0i + struct accept_filter_arg afa; + + bzero(&afa, sizeof(afa)); + strcpy(afa.af_name, "tlsready"); + setsockopt(sok, SOL_SOCKET, SO_ACCEPTFILTER, &afa, sizeof(afa)); +.Ed +.Sh SEE ALSO +.Xr setsockopt 2 , +.Xr accept_filter 9 +.Sh HISTORY +The +.Nm +accept filter was introduced in +.Fx 15.0 . +.Sh AUTHORS +The +.Nm +filter was written by +.An Maksim Yevmenkin . diff --git a/static/freebsd/man9/acl.9 b/static/freebsd/man9/acl.9 new file mode 100644 index 00000000..57daa04c --- /dev/null +++ b/static/freebsd/man9/acl.9 @@ -0,0 +1,223 @@ +.\"- +.\" Copyright (c) 1999-2001 Robert N. M. Watson +.\" 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 September 4, 2015 +.Dt ACL 9 +.Os +.Sh NAME +.Nm acl +.Nd virtual file system access control lists +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/acl.h +.Pp +In the kernel configuration file: +.Cd "options UFS_ACL" +.Sh DESCRIPTION +Access control lists, or ACLs, +allow fine-grained specification of rights +for vnodes representing files and directories. +However, as there are a plethora of file systems with differing ACL semantics, +the vnode interface is aware only of the syntax of ACLs, +relying on the underlying file system to implement the details. +Depending on the underlying file system, each file or directory +may have zero or more ACLs associated with it, named using the +.Fa type +field of the appropriate vnode ACL calls: +.Xr VOP_ACLCHECK 9 , +.Xr VOP_GETACL 9 , +and +.Xr VOP_SETACL 9 . +.Pp +Currently, each ACL is represented in-kernel by a fixed-size +.Vt acl +structure, defined as follows: +.Bd -literal -offset indent +struct acl { + unsigned int acl_maxcnt; + unsigned int acl_cnt; + int acl_spare[4]; + struct acl_entry acl_entry[ACL_MAX_ENTRIES]; +}; +.Ed +.Pp +An ACL is constructed from a fixed size array of ACL entries, +each of which consists of a set of permissions, principal namespace, +and principal identifier. +In this implementation, the +.Vt acl_maxcnt +field is always set to +.Dv ACL_MAX_ENTRIES . +.Pp +Each individual ACL entry is of the type +.Vt acl_entry_t , +which is a structure with the following members: +.Bl -tag -width 2n +.It Vt acl_tag_t Va ae_tag +The following is a list of definitions of ACL types +to be set in +.Va ae_tag : +.Pp +.Bl -tag -width ".Dv ACL_UNDEFINED_FIELD" -offset indent -compact +.It Dv ACL_UNDEFINED_FIELD +Undefined ACL type. +.It Dv ACL_USER_OBJ +Discretionary access rights for processes whose effective user ID +matches the user ID of the file's owner. +.It Dv ACL_USER +Discretionary access rights for processes whose effective user ID +matches the ACL entry qualifier. +.It Dv ACL_GROUP_OBJ +Discretionary access rights for processes whose effective group ID +or any supplemental groups +match the group ID of the file's owner. +.It Dv ACL_GROUP +Discretionary access rights for processes whose effective group ID +or any supplemental groups +match the ACL entry qualifier. +.It Dv ACL_MASK +The maximum discretionary access rights that can be granted +to a process in the file group class. +This is only valid for POSIX.1e ACLs. +.It Dv ACL_OTHER +Discretionary access rights for processes not covered by any other ACL +entry. +This is only valid for POSIX.1e ACLs. +.It Dv ACL_OTHER_OBJ +Same as +.Dv ACL_OTHER . +.It Dv ACL_EVERYONE +Discretionary access rights for all users. +This is only valid for NFSv4 ACLs. +.El +.Pp +Each POSIX.1e ACL must contain exactly one +.Dv ACL_USER_OBJ , +one +.Dv ACL_GROUP_OBJ , +and one +.Dv ACL_OTHER . +If any of +.Dv ACL_USER , +.Dv ACL_GROUP , +or +.Dv ACL_OTHER +are present, then exactly one +.Dv ACL_MASK +entry should be present. +.It Vt uid_t Va ae_id +The ID of user for whom this ACL describes access permissions. +For entries other than +.Dv ACL_USER +and +.Dv ACL_GROUP , +this field should be set to +.Dv ACL_UNDEFINED_ID . +.It Vt acl_perm_t Va ae_perm +This field defines what kind of access the process matching this ACL has +for accessing the associated file. +For POSIX.1e ACLs, the following are valid: +.Bl -tag -width ".Dv ACL_WRITE_NAMED_ATTRS" +.It Dv ACL_EXECUTE +The process may execute the associated file. +.It Dv ACL_WRITE +The process may write to the associated file. +.It Dv ACL_READ +The process may read from the associated file. +.It Dv ACL_PERM_NONE +The process has no read, write or execute permissions +to the associated file. +.El +.Pp +For NFSv4 ACLs, the following are valid: +.Bl -tag -width ".Dv ACL_WRITE_NAMED_ATTRS" +.It Dv ACL_READ_DATA +The process may read from the associated file. +.It Dv ACL_LIST_DIRECTORY +Same as +.Dv ACL_READ_DATA . +.It Dv ACL_WRITE_DATA +The process may write to the associated file. +.It Dv ACL_ADD_FILE +Same as +.Dv ACL_ACL_WRITE_DATA . +.It Dv ACL_APPEND_DATA +.It Dv ACL_ADD_SUBDIRECTORY +Same as +.Dv ACL_APPEND_DATA . +.It Dv ACL_READ_NAMED_ATTRS +Ignored. +.It Dv ACL_WRITE_NAMED_ATTRS +Ignored. +.It Dv ACL_EXECUTE +The process may execute the associated file. +.It Dv ACL_DELETE_CHILD +.It Dv ACL_READ_ATTRIBUTES +.It Dv ACL_WRITE_ATTRIBUTES +.It Dv ACL_DELETE +.It Dv ACL_READ_ACL +.It Dv ACL_WRITE_ACL +.It Dv ACL_WRITE_OWNER +.It Dv ACL_SYNCHRONIZE +Ignored. +.El +.It Vt acl_entry_type_t Va ae_entry_type +This field defines the type of NFSv4 ACL entry. +It is not used with POSIX.1e ACLs. +The following values are valid: +.Bl -tag -width ".Dv ACL_WRITE_NAMED_ATTRS" +.It Dv ACL_ENTRY_TYPE_ALLOW +.It Dv ACL_ENTRY_TYPE_DENY +.El +.It Vt acl_flag_t Va ae_flags +This field defines the inheritance flags of NFSv4 ACL entry. +It is not used with POSIX.1e ACLs. +The following values are valid: +.Bl -tag -width ".Dv ACL_ENTRY_DIRECTORY_INHERIT" +.It Dv ACL_ENTRY_FILE_INHERIT +.It Dv ACL_ENTRY_DIRECTORY_INHERIT +.It Dv ACL_ENTRY_NO_PROPAGATE_INHERIT +.It Dv ACL_ENTRY_INHERIT_ONLY +.It Dv ACL_ENTRY_INHERITED +.El +The +.Dv ACL_ENTRY_INHERITED +flag is set on an ACE that has been inherited from its parent. +It may also be set programmatically, and is valid on both files +and directories. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr vaccess 9 , +.Xr vaccess_acl_nfs4 9 , +.Xr vaccess_acl_posix1e 9 , +.Xr VFS 9 , +.Xr VOP_ACLCHECK 9 , +.Xr VOP_GETACL 9 , +.Xr VOP_SETACL 9 +.Sh AUTHORS +This manual page was written by +.An Robert Watson . diff --git a/static/freebsd/man9/alq.9 b/static/freebsd/man9/alq.9 new file mode 100644 index 00000000..5dcbb2b8 --- /dev/null +++ b/static/freebsd/man9/alq.9 @@ -0,0 +1,439 @@ +.\" +.\" Copyright (c) 2003 Hiten Pandya +.\" Copyright (c) 2009-2010 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" Portions of this software were developed at the Centre for Advanced +.\" Internet Architectures, Swinburne University of Technology, Melbourne, +.\" Australia by Lawrence Stewart under sponsorship from the FreeBSD +.\" Foundation. +.\" +.\" 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, +.\" without modification, immediately at the beginning of the file. +.\" 2. 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 AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR +.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 26, 2010 +.Dt ALQ 9 +.Os +.Sh NAME +.Nm alq , +.Nm alq_open_flags , +.Nm alq_open , +.Nm alq_writen , +.Nm alq_write , +.Nm alq_flush , +.Nm alq_close , +.Nm alq_getn , +.Nm alq_get , +.Nm alq_post_flags , +.Nm alq_post +.Nd Asynchronous Logging Queues +.Sh SYNOPSIS +.In sys/alq.h +.Ft int +.Fo alq_open_flags +.Fa "struct alq **app" +.Fa "const char *file" +.Fa "struct ucred *cred" +.Fa "int cmode" +.Fa "int size" +.Fa "int flags" +.Fc +.Ft int +.Fo alq_open +.Fa "struct alq **app" +.Fa "const char *file" +.Fa "struct ucred *cred" +.Fa "int cmode" +.Fa "int size" +.Fa "int count" +.Fc +.Ft int +.Fn alq_writen "struct alq *alq" "void *data" "int len" "int flags" +.Ft int +.Fn alq_write "struct alq *alq" "void *data" "int flags" +.Ft void +.Fn alq_flush "struct alq *alq" +.Ft void +.Fn alq_close "struct alq *alq" +.Ft struct ale * +.Fn alq_getn "struct alq *alq" "int len" "int flags" +.Ft struct ale * +.Fn alq_get "struct alq *alq" "int flags" +.Ft void +.Fn alq_post_flags "struct alq *alq" "struct ale *ale" "int flags" +.Ft void +.Fn alq_post "struct alq *alq" "struct ale *ale" +.Sh DESCRIPTION +The +.Nm +facility provides an asynchronous fixed or variable length recording +mechanism, known as Asynchronous Logging Queues. +It can record to any +.Xr vnode 9 , +thus providing the ability to journal logs to character +devices as well as regular files. +All functions accept a +.Vt "struct alq" +argument, which is an opaque type that maintains state information +for an Asynchronous Logging Queue. +The logging facility runs in a separate kernel thread, which services +all log entry requests. +.Pp +An +.Dq asynchronous log entry +is defined as +.Vt "struct ale" , +which has the following members: +.Bd -literal -offset indent +struct ale { + intptr_t ae_bytesused; /* # bytes written to ALE. */ + char *ae_data; /* Write ptr. */ + int ae_pad; /* Unused, compat. */ +}; +.Ed +.Pp +An +.Nm +can be created in either fixed or variable length mode. +A variable length +.Nm +accommodates writes of varying length using +.Fn alq_writen +and +.Fn alq_getn . +A fixed length +.Nm +accommodates a fixed number of writes using +.Fn alq_write +and +.Fn alq_get , +each of fixed size (set at queue creation time). +Fixed length mode is deprecated in favour of variable length mode. +.Sh FUNCTIONS +The +.Fn alq_open_flags +function creates a new variable length asynchronous logging queue. +The +.Fa file +argument is the name of the file to open for logging. +If the file does not yet exist, +.Fn alq_open +will attempt to create it. +The +.Fa cmode +argument will be passed to +.Fn vn_open +as the requested creation mode, to be used if the file will be created by +.Fn alq_open . +Consumers of this API may wish to pass +.Dv ALQ_DEFAULT_CMODE , +a default creation mode suitable for most applications. +The +.Fa cred +argument specifies the credentials to use when opening and performing I/O on the file. +The +.Fa size +argument sets the size (in bytes) of the underlying queue. +The ALQ_ORDERED flag may be passed in via +.Fa flags +to indicate that the ordering of writer threads waiting for a busy +.Nm +to free up resources should be preserved. +.Pp +The deprecated +.Fn alq_open +function is implemented as a wrapper around +.Fn alq_open_flags +to provide backwards compatibility to consumers that have not been updated to +utilise the newer +.Fn alq_open_flags +function. +It passes all arguments through to +.Fn alq_open_flags +untouched except for +.Fa size +and +.Fa count , +and sets +.Fa flags +to 0. +To create a variable length mode +.Nm , +the +.Fa size +argument should be set to the size (in bytes) of the underlying queue and the +.Fa count +argument should be set to 0. +To create a fixed length mode +.Nm , +the +.Fa size +argument should be set to the size (in bytes) of each write and the +.Fa count +argument should be set to the number of +.Fa size +byte chunks to reserve capacity for. +.Pp +The +.Fn alq_writen +function writes +.Fa len +bytes from +.Fa data +to the designated variable length mode queue +.Fa alq . +If +.Fn alq_writen +could not write the entry immediately and +.Dv ALQ_WAITOK +is set in +.Fa flags , +the function will be allowed to +.Xr msleep_spin 9 +with the +.Dq Li alqwnord +or +.Dq Li alqwnres +wait message. +A write will automatically schedule the queue +.Fa alq +to be flushed to disk. +This behaviour can be controlled by passing ALQ_NOACTIVATE via +.Fa flags +to indicate that the write should not schedule +.Fa alq +to be flushed to disk. +.Pp +The deprecated +.Fn alq_write +function is implemented as a wrapper around +.Fn alq_writen +to provide backwards compatibility to consumers that have not been updated to +utilise variable length mode queues. +The function will write +.Fa size +bytes of data (where +.Fa size +was specified at queue creation time) from the +.Fa data +buffer to the +.Fa alq . +Note that it is an error to call +.Fn alq_write +on a variable length mode queue. +.Pp +The +.Fn alq_flush +function is used for flushing +.Fa alq +to the log medium that was passed to +.Fn alq_open . +If +.Fa alq +has data to flush and is not already in the process of being flushed, the +function will block doing IO. +Otherwise, the function will return immediately. +.Pp +The +.Fn alq_close +function will close the asynchronous logging queue +.Fa alq +and flush all pending write requests to the log medium. +It will free all resources that were previously allocated. +.Pp +The +.Fn alq_getn +function returns an asynchronous log entry from +.Fa alq , +initialised to point at a buffer capable of receiving +.Fa len +bytes of data. +This function leaves +.Fa alq +in a locked state, until a subsequent +.Fn alq_post +or +.Fn alq_post_flags +call is made. +If +.Fn alq_getn +could not obtain +.Fa len +bytes of buffer immediately and +.Dv ALQ_WAITOK +is set in +.Fa flags , +the function will be allowed to +.Xr msleep_spin 9 +with the +.Dq Li alqgnord +or +.Dq Li alqgnres +wait message. +The caller can choose to write less than +.Fa len +bytes of data to the returned asynchronous log entry by setting the entry's +ae_bytesused field to the number of bytes actually written. +This must be done prior to calling +.Fn alq_post . +.Pp +The deprecated +.Fn alq_get +function is implemented as a wrapper around +.Fn alq_getn +to provide backwards compatibility to consumers that have not been updated to +utilise variable length mode queues. +The asynchronous log entry returned will be initialised to point at a buffer +capable of receiving +.Fa size +bytes of data (where +.Fa size +was specified at queue creation time). +Note that it is an error to call +.Fn alq_get +on a variable length mode queue. +.Pp +The +.Fn alq_post_flags +function schedules the asynchronous log entry +.Fa ale +(obtained from +.Fn alq_getn +or +.Fn alq_get ) +for writing to +.Fa alq . +The ALQ_NOACTIVATE flag may be passed in via +.Fa flags +to indicate that the queue should not be immediately scheduled to be flushed to +disk. +This function leaves +.Fa alq +in an unlocked state. +.Pp +The +.Fn alq_post +function is implemented as a wrapper around +.Fn alq_post_flags +to provide backwards compatibility to consumers that have not been updated to +utilise the newer +.Fn alq_post_flags +function. +It simply passes all arguments through to +.Fn alq_post_flags +untouched, and sets +.Fa flags +to 0. +.Sh IMPLEMENTATION NOTES +The +.Fn alq_writen +and +.Fn alq_write +functions both perform a +.Xr bcopy 3 +from the supplied +.Fa data +buffer into the underlying +.Nm +buffer. +Performance critical code paths may wish to consider using +.Fn alq_getn +(variable length queues) or +.Fn alq_get +(fixed length queues) to avoid the extra memory copy. +Note that a queue remains locked between calls to +.Fn alq_getn +or +.Fn alq_get +and +.Fn alq_post +or +.Fn alq_post_flags , +so this method of writing to a queue is unsuitable for situations where the +time between calls may be substantial. +.Sh LOCKING +Each asynchronous logging queue is protected by a spin mutex. +.Pp +Functions +.Fn alq_flush +and +.Fn alq_open +may attempt to acquire an internal sleep mutex, and should +consequently not be used in contexts where sleeping is +not allowed. +.Sh RETURN VALUES +The +.Fn alq_open +function returns one of the error codes listed in +.Xr open 2 , +if it fails to open +.Fa file , +or else it returns 0. +.Pp +The +.Fn alq_writen +and +.Fn alq_write +functions return +.Er EWOULDBLOCK +if +.Dv ALQ_NOWAIT +was set in +.Fa flags +and either the queue is full or the system is shutting down. +.Pp +The +.Fn alq_getn +and +.Fn alq_get +functions return +.Dv NULL +if +.Dv ALQ_NOWAIT +was set in +.Fa flags +and either the queue is full or the system is shutting down. +.Pp +NOTE: invalid arguments to non-void functions will result in +undefined behaviour. +.Sh SEE ALSO +.Xr syslog 3 , +.Xr kproc 9 , +.Xr ktr 9 , +.Xr msleep_spin 9 , +.Xr vnode 9 +.Sh HISTORY +The +Asynchronous Logging Queues (ALQ) facility first appeared in +.Fx 5.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +facility was written by +.An Jeffrey Roberson Aq Mt jeff@FreeBSD.org +and extended by +.An Lawrence Stewart Aq Mt lstewart@freebsd.org . +.Pp +This manual page was written by +.An Hiten Pandya Aq Mt hmp@FreeBSD.org +and revised by +.An Lawrence Stewart Aq Mt lstewart@freebsd.org . diff --git a/static/freebsd/man9/altq.9 b/static/freebsd/man9/altq.9 new file mode 100644 index 00000000..d4698377 --- /dev/null +++ b/static/freebsd/man9/altq.9 @@ -0,0 +1,600 @@ +.\" $NetBSD: altq.9,v 1.8 2002/05/28 11:41:45 wiz Exp $ +.\" $OpenBSD: altq.9,v 1.4 2001/07/12 12:41:42 itojun Exp $ +.\" +.\" Copyright (C) 2004 Max Laier. All rights reserved. +.\" Copyright (C) 2001 +.\" Sony Computer Science Laboratories Inc. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY SONY CSL 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 SONY CSL 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 March 20, 2018 +.Dt ALTQ 9 +.Os +.\" +.Sh NAME +.Nm ALTQ +.Nd kernel interfaces for manipulating output queues on network interfaces +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In net/if.h +.In net/if_var.h +.\" +.Ss Enqueue macros +.Fn IFQ_ENQUEUE "struct ifaltq *ifq" "struct mbuf *m" "int error" +.Fn IFQ_HANDOFF "struct ifnet *ifp" "struct mbuf *m" "int error" +.Fo IFQ_HANDOFF_ADJ +.Fa "struct ifnet *ifp" "struct mbuf *m" "int adjust" "int error" +.Fc +.\" +.Ss Dequeue macros +.Fn IFQ_DEQUEUE "struct ifaltq *ifq" "struct mbuf *m" +.Fn IFQ_POLL_NOLOCK "struct ifaltq *ifq" "struct mbuf *m" +.Fn IFQ_PURGE "struct ifaltq *ifq" +.Fn IFQ_IS_EMPTY "struct ifaltq *ifq" +.\" +.Ss Driver managed dequeue macros +.Fn IFQ_DRV_DEQUEUE "struct ifaltq *ifq" "struct mbuf *m" +.Fn IFQ_DRV_PREPEND "struct ifaltq *ifq" "struct mbuf *m" +.Fn IFQ_DRV_PURGE "struct ifaltq *ifq" +.Fn IFQ_DRV_IS_EMPTY "struct ifaltq *ifq" +.\" +.Ss General setup macros +.Fn IFQ_SET_MAXLEN "struct ifaltq *ifq" "int len" +.Fn IFQ_INC_LEN "struct ifaltq *ifq" +.Fn IFQ_DEC_LEN "struct ifaltq *ifq" +.Fn IFQ_INC_DROPS "struct ifaltq *ifq" +.Fn IFQ_SET_READY "struct ifaltq *ifq" +.Sh DESCRIPTION +The +.Nm +system is a framework to manage queuing disciplines on network +interfaces. +.Nm +introduces new macros to manipulate output queues. +The output queue macros are used to abstract queue operations and not to +touch the internal fields of the output queue structure. +The macros are independent from the +.Nm +implementation, and compatible with the traditional +.Vt ifqueue +macros for ease of transition. +.Pp +.Fn IFQ_ENQUEUE , +.Fn IFQ_HANDOFF +and +.Fn IFQ_HANDOFF_ADJ +enqueue a packet +.Fa m +to the queue +.Fa ifq . +The underlying queuing discipline may discard the packet. +The +.Fa error +argument is set to 0 on success, or +.Er ENOBUFS +if the packet is discarded. +The packet pointed to by +.Fa m +will be freed by the device driver on success, or by the queuing discipline on +failure, so the caller should not touch +.Fa m +after enqueuing. +.Fn IFQ_HANDOFF +and +.Fn IFQ_HANDOFF_ADJ +combine the enqueue operation with statistic generation and call +.Fn if_start +upon successful enqueue to initiate the actual send. +.Pp +.Fn IFQ_DEQUEUE +dequeues a packet from the queue. +The dequeued packet is returned in +.Fa m , +or +.Fa m +is set to +.Dv NULL +if no packet is dequeued. +The caller must always check +.Fa m +since a non-empty queue could return +.Dv NULL +under rate-limiting. +.Pp +.Fn IFQ_POLL_NOLOCK +returns the next packet without removing it from the queue. +The caller must hold the queue mutex when calling +.Fn IFQ_POLL_NOLOCK +in order to guarantee that a subsequent call to +.Fn IFQ_DEQUEUE_NOLOCK +dequeues the same packet. +.Pp +.Fn IFQ_*_NOLOCK +variants (if available) always assume that the caller holds the queue mutex. +They can be grabbed with +.Fn IFQ_LOCK +and released with +.Fn IFQ_UNLOCK . +.Pp +.Fn IFQ_PURGE +discards all the packets in the queue. +The purge operation is needed since a non-work conserving queue cannot be +emptied by a dequeue loop. +.Pp +.Fn IFQ_IS_EMPTY +can be used to check if the queue is empty. +Note that +.Fn IFQ_DEQUEUE +could still return +.Dv NULL +if the queuing discipline is non-work conserving. +.Pp +.Fn IFQ_DRV_DEQUEUE +moves up to +.Fa ifq->ifq_drv_maxlen +packets from the queue to the +.Dq "driver managed" +queue and returns the first one via +.Fa m . +As for +.Fn IFQ_DEQUEUE , +.Fa m +can be +.Dv NULL +even for a non-empty queue. +Subsequent calls to +.Fn IFQ_DRV_DEQUEUE +pass the packets from the +.Dq "driver managed" +queue without obtaining the queue mutex. +It is the responsibility of the caller to protect against concurrent access. +Enabling +.Nm +for a given queue sets +.Va ifq_drv_maxlen +to 0 as the +.Dq "bulk dequeue" +performed by +.Fn IFQ_DRV_DEQUEUE +for higher values of +.Va ifq_drv_maxlen +is adverse to +.Nm ALTQ Ns 's +internal timing. +Note that a driver must not mix +.Fn IFQ_DRV_* +macros with the default dequeue macros as the default macros do not look at the +.Dq "driver managed" +queue which might lead to an mbuf leak. +.Pp +.Fn IFQ_DRV_PREPEND +prepends +.Fa m +to the +.Dq "driver managed" +queue from where it will be obtained with the next call to +.Fn IFQ_DRV_DEQUEUE . +.Pp +.Fn IFQ_DRV_PURGE +flushes all packets in the +.Dq "driver managed" +queue and calls to +.Fn IFQ_PURGE +afterwards. +.Pp +.Fn IFQ_DRV_IS_EMPTY +checks for packets in the +.Dq "driver managed" +part of the queue. +If it is empty, it forwards to +.Fn IFQ_IS_EMPTY . +.Pp +.Fn IFQ_SET_MAXLEN +sets the queue length limit to the default FIFO queue. +The +.Va ifq_drv_maxlen +member of the +.Vt ifaltq +structure controls the length limit of the +.Dq "driver managed" +queue. +.Pp +.Fn IFQ_INC_LEN +and +.Fn IFQ_DEC_LEN +increment or decrement the current queue length in packets. +This is mostly for internal purposes. +.Pp +.Fn IFQ_INC_DROPS +increments the drop counter and is identical to +.Fn IF_DROP . +It is defined for naming consistency only. +.Pp +.Fn IFQ_SET_READY +sets a flag to indicate that a driver was converted to use the new macros. +.Nm +can be enabled only on interfaces with this flag. +.Sh COMPATIBILITY +.Ss Vt ifaltq structure +In order to keep compatibility with the existing code, the new +output queue structure +.Vt ifaltq +has the same fields. +The traditional +.Fn IF_* +macros and the code directly referencing the fields within +.Va if_snd +still work with +.Vt ifaltq . +.Bd -literal + ##old-style## ##new-style## + | + struct ifqueue { | struct ifaltq { + struct mbuf *ifq_head; | struct mbuf *ifq_head; + struct mbuf *ifq_tail; | struct mbuf *ifq_tail; + int ifq_len; | int ifq_len; + int ifq_maxlen; | int ifq_maxlen; + }; | /* driver queue fields */ + | ...... + | /* altq related fields */ + | ...... + | }; + | +.Ed +The new structure replaces +.Vt "struct ifqueue" +in +.Vt "struct ifnet" . +.Bd -literal + ##old-style## ##new-style## + | + struct ifnet { | struct ifnet { + .... | .... + | + struct ifqueue if_snd; | struct ifaltq if_snd; + | + .... | .... + }; | }; + | +.Ed +The (simplified) new +.Fn IFQ_* +macros look like: +.Bd -literal + #define IFQ_DEQUEUE(ifq, m) \e + if (ALTQ_IS_ENABLED((ifq)) \e + ALTQ_DEQUEUE((ifq), (m)); \e + else \e + IF_DEQUEUE((ifq), (m)); +.Ed +.Ss Enqueue operation +The semantics of the enqueue operation is changed. +In the new style, +enqueue and packet drop are combined since they cannot be easily +separated in many queuing disciplines. +The new enqueue operation corresponds to the following macro that is +written with the old macros. +.Bd -literal +#define IFQ_ENQUEUE(ifq, m, error) \e +do { \e + if (IF_QFULL((ifq))) { \e + m_freem((m)); \e + (error) = ENOBUFS; \e + IF_DROP(ifq); \e + } else { \e + IF_ENQUEUE((ifq), (m)); \e + (error) = 0; \e + } \e +} while (0) +.Ed +.Pp +.Fn IFQ_ENQUEUE +does the following: +.Pp +.Bl -hyphen -compact +.It +queue a packet, +.It +drop (and free) a packet if the enqueue operation fails. +.El +.Pp +If the enqueue operation fails, +.Fa error +is set to +.Er ENOBUFS . +The +.Fa m +mbuf is freed by the queuing discipline. +The caller should not touch mbuf after calling +.Fn IFQ_ENQUEUE +so that the caller may need to copy +.Va m_pkthdr.len +or +.Va m_flags +field beforehand for statistics. +.Fn IFQ_HANDOFF +and +.Fn IFQ_HANDOFF_ADJ +can be used if only default interface statistics and an immediate call to +.Fn if_start +are desired. +The caller should not use +.Fn senderr +since mbuf was already freed. +.Pp +The new style +.Fn if_output +looks as follows: +.Bd -literal + ##old-style## ##new-style## + | + int | int + ether_output(ifp, m0, dst, rt0) | ether_output(ifp, m0, dst, rt0) + { | { + ...... | ...... + | + | mflags = m->m_flags; + | len = m->m_pkthdr.len; + s = splimp(); | s = splimp(); + if (IF_QFULL(&ifp->if_snd)) { | IFQ_ENQUEUE(&ifp->if_snd, m, + | error); + IF_DROP(&ifp->if_snd); | if (error != 0) { + splx(s); | splx(s); + senderr(ENOBUFS); | return (error); + } | } + IF_ENQUEUE(&ifp->if_snd, m); | + ifp->if_obytes += | ifp->if_obytes += len; + m->m_pkthdr.len; | + if (m->m_flags & M_MCAST) | if (mflags & M_MCAST) + ifp->if_omcasts++; | ifp->if_omcasts++; + | + if ((ifp->if_flags & IFF_OACTIVE) | if ((ifp->if_flags & IFF_OACTIVE) + == 0) | == 0) + (*ifp->if_start)(ifp); | (*ifp->if_start)(ifp); + splx(s); | splx(s); + return (error); | return (error); + | + bad: | bad: + if (m) | if (m) + m_freem(m); | m_freem(m); + return (error); | return (error); + } | } + | +.Ed +.Sh HOW TO CONVERT THE EXISTING DRIVERS +First, make sure the corresponding +.Fn if_output +is already converted to the new style. +.Pp +Look for +.Va if_snd +in the driver. +Probably, you need to make changes to the lines that include +.Va if_snd . +.Ss Empty check operation +If the code checks +.Va ifq_head +to see whether the queue is empty or not, use +.Fn IFQ_IS_EMPTY . +.Bd -literal + ##old-style## ##new-style## + | + if (ifp->if_snd.ifq_head != NULL) | if (!IFQ_IS_EMPTY(&ifp->if_snd)) + | +.Ed +.Fn IFQ_IS_EMPTY +only checks if there is any packet stored in the queue. +Note that even when +.Fn IFQ_IS_EMPTY +is +.Dv FALSE , +.Fn IFQ_DEQUEUE +could still return +.Dv NULL +if the queue is under rate-limiting. +.Ss Dequeue operation +Replace +.Fn IF_DEQUEUE +by +.Fn IFQ_DEQUEUE . +Always check whether the dequeued mbuf is +.Dv NULL +or not. +Note that even when +.Fn IFQ_IS_EMPTY +is +.Dv FALSE , +.Fn IFQ_DEQUEUE +could return +.Dv NULL +due to rate-limiting. +.Bd -literal + ##old-style## ##new-style## + | + IF_DEQUEUE(&ifp->if_snd, m); | IFQ_DEQUEUE(&ifp->if_snd, m); + | if (m == NULL) + | return; + | +.Ed +A driver is supposed to call +.Fn if_start +from transmission complete interrupts in order to trigger the next dequeue. +.Ss Poll-and-dequeue operation +If the code polls the packet at the head of the queue and actually uses +the packet before dequeuing it, use +.Fn IFQ_POLL_NOLOCK +and +.Fn IFQ_DEQUEUE_NOLOCK . +.Bd -literal + ##old-style## ##new-style## + | + | IFQ_LOCK(&ifp->if_snd); + m = ifp->if_snd.ifq_head; | IFQ_POLL_NOLOCK(&ifp->if_snd, m); + if (m != NULL) { | if (m != NULL) { + | + /* use m to get resources */ | /* use m to get resources */ + if (something goes wrong) | if (something goes wrong) + | IFQ_UNLOCK(&ifp->if_snd); + return; | return; + | + IF_DEQUEUE(&ifp->if_snd, m); | IFQ_DEQUEUE_NOLOCK(&ifp->if_snd, m); + | IFQ_UNLOCK(&ifp->if_snd); + | + /* kick the hardware */ | /* kick the hardware */ + } | } + | +.Ed +It is guaranteed that +.Fn IFQ_DEQUEUE_NOLOCK +under the same lock as a previous +.Fn IFQ_POLL_NOLOCK +returns the same packet. +Note that they need to be guarded by +.Fn IFQ_LOCK . +.Ss Eliminating Fn IF_PREPEND +If the code uses +.Fn IF_PREPEND , +you have to eliminate it unless you can use a +.Dq "driver managed" +queue which allows the use of +.Fn IFQ_DRV_PREPEND +as a substitute. +A common usage of +.Fn IF_PREPEND +is to cancel the previous dequeue operation. +You have to convert the logic into poll-and-dequeue. +.Bd -literal + ##old-style## ##new-style## + | + | IFQ_LOCK(&ifp->if_snd); + IF_DEQUEUE(&ifp->if_snd, m); | IFQ_POLL_NOLOCK(&ifp->if_snd, m); + if (m != NULL) { | if (m != NULL) { + | + if (something_goes_wrong) { | if (something_goes_wrong) { + IF_PREPEND(&ifp->if_snd, m); | IFQ_UNLOCK(&ifp->if_snd); + return; | return; + } | } + | + | /* at this point, the driver + | * is committed to send this + | * packet. + | */ + | IFQ_DEQUEUE_NOLOCK(&ifp->if_snd, m); + | IFQ_UNLOCK(&ifp->if_snd); + | + /* kick the hardware */ | /* kick the hardware */ + } | } + | +.Ed +.Ss Purge operation +Use +.Fn IFQ_PURGE +to empty the queue. +Note that a non-work conserving queue cannot be emptied by a dequeue loop. +.Bd -literal + ##old-style## ##new-style## + | + while (ifp->if_snd.ifq_head != NULL) {| IFQ_PURGE(&ifp->if_snd); + IF_DEQUEUE(&ifp->if_snd, m); | + m_freem(m); | + } | + | +.Ed +.Ss Conversion using a driver managed queue +Convert +.Fn IF_* +macros to their equivalent +.Fn IFQ_DRV_* +and employ +.Fn IFQ_DRV_IS_EMPTY +where appropriate. +.Bd -literal + ##old-style## ##new-style## + | + if (ifp->if_snd.ifq_head != NULL) | if (!IFQ_DRV_IS_EMPTY(&ifp->if_snd)) + | +.Ed +Make sure that calls to +.Fn IFQ_DRV_DEQUEUE , +.Fn IFQ_DRV_PREPEND +and +.Fn IFQ_DRV_PURGE +are protected with a mutex of some kind. +.Ss Attach routine +Use +.Fn IFQ_SET_MAXLEN +to set +.Va ifq_maxlen +to +.Fa len . +Initialize +.Va ifq_drv_maxlen +with a sensible value if you plan to use the +.Fn IFQ_DRV_* +macros. +Add +.Fn IFQ_SET_READY +to show this driver is converted to the new style. +(This is used to distinguish new-style drivers.) +.Bd -literal + ##old-style## ##new-style## + | + ifp->if_snd.ifq_maxlen = qsize; | IFQ_SET_MAXLEN(&ifp->if_snd, qsize); + | ifp->if_snd.ifq_drv_maxlen = qsize; + | IFQ_SET_READY(&ifp->if_snd); + if_attach(ifp); | if_attach(ifp); + | +.Ed +.Ss Other issues +The new macros for statistics: +.Bd -literal + ##old-style## ##new-style## + | + IF_DROP(&ifp->if_snd); | IFQ_INC_DROPS(&ifp->if_snd); + | + ifp->if_snd.ifq_len++; | IFQ_INC_LEN(&ifp->if_snd); + | + ifp->if_snd.ifq_len--; | IFQ_DEC_LEN(&ifp->if_snd); + | +.Ed +.Sh QUEUING DISCIPLINES +Queuing disciplines need to maintain +.Fa ifq_len +(used by +.Fn IFQ_IS_EMPTY ) . +Queuing disciplines also need to guarantee that the same mbuf is returned if +.Fn IFQ_DEQUEUE +is called immediately after +.Fn IFQ_POLL . +.Sh SEE ALSO +.Xr pf 4 , +.Xr pf.conf 5 , +.Xr pfctl 8 +.Sh HISTORY +The +.Nm +system first appeared in March 1997 and found home in the KAME project +(https://www.kame.net). +It was imported to +.Fx +in 5.3 . diff --git a/static/freebsd/man9/atomic.9 b/static/freebsd/man9/atomic.9 new file mode 100644 index 00000000..b027a0ff --- /dev/null +++ b/static/freebsd/man9/atomic.9 @@ -0,0 +1,654 @@ +.\" Copyright (c) 2000-2001 John H. Baldwin +.\" +.\" 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 16, 2024 +.Dt ATOMIC 9 +.Os +.Sh NAME +.Nm atomic_add , +.Nm atomic_clear , +.Nm atomic_cmpset , +.Nm atomic_fcmpset , +.Nm atomic_fetchadd , +.Nm atomic_interrupt_fence , +.Nm atomic_load , +.Nm atomic_readandclear , +.Nm atomic_set , +.Nm atomic_subtract , +.Nm atomic_store , +.Nm atomic_thread_fence +.Nd atomic operations +.Sh SYNOPSIS +.In machine/atomic.h +.Ft void +.Fn atomic_add_[acq_|rel_] "volatile *p" " v" +.Ft void +.Fn atomic_clear_[acq_|rel_] "volatile *p" " v" +.Ft int +.Fo atomic_cmpset_[acq_|rel_] +.Fa "volatile *dst" +.Fa " old" +.Fa " new" +.Fc +.Ft int +.Fo atomic_fcmpset_[acq_|rel_] +.Fa "volatile *dst" +.Fa " *old" +.Fa " new" +.Fc +.Ft +.Fn atomic_fetchadd_ "volatile *p" " v" +.Ft void +.Fn atomic_interrupt_fence "void" +.Ft +.Fn atomic_load_[acq_] "const volatile *p" +.Ft +.Fn atomic_readandclear_ "volatile *p" +.Ft void +.Fn atomic_set_[acq_|rel_] "volatile *p" " v" +.Ft void +.Fn atomic_subtract_[acq_|rel_] "volatile *p" " v" +.Ft void +.Fn atomic_store_[rel_] "volatile *p" " v" +.Ft +.Fn atomic_swap_ "volatile *p" " v" +.Ft int +.Fn atomic_testandclear_ "volatile *p" "u_int v" +.Ft int +.Fn atomic_testandset_ "volatile *p" "u_int v" +.Ft void +.Fn atomic_thread_fence_[acq|acq_rel|rel|seq_cst] "void" +.Sh DESCRIPTION +Atomic operations are commonly used to implement reference counts and as +building blocks for synchronization primitives, such as mutexes. +.Pp +All of these operations are performed +.Em atomically +across multiple threads and in the presence of interrupts, meaning that they +are performed in an indivisible manner from the perspective of concurrently +running threads and interrupt handlers. +.Pp +On all architectures supported by +.Fx , +ordinary loads and stores of integers in cache-coherent memory are +inherently atomic if the integer is naturally aligned and its size does not +exceed the processor's word size. +However, such loads and stores may be elided from the program by +the compiler, whereas atomic operations are always performed. +.Pp +When atomic operations are performed on cache-coherent memory, all +operations on the same location are totally ordered. +.Pp +When an atomic load is performed on a location in cache-coherent memory, +it reads the entire value that was defined by the last atomic store to +each byte of the location. +An atomic load will never return a value out of thin air. +When an atomic store is performed on a location, no other thread or +interrupt handler will observe a +.Em torn write , +or partial modification of the location. +.Pp +Except as noted below, the semantics of these operations are almost +identical to the semantics of similarly named C11 atomic operations. +.Ss Types +Most atomic operations act upon a specific +.Fa type . +That type is indicated in the function name. +In contrast to C11 atomic operations, +.Fx Ns 's +atomic operations are performed on ordinary integer types. +The available types are: +.Pp +.Bl -tag -offset indent -width short -compact +.It Li int +unsigned integer +.It Li long +unsigned long integer +.It Li ptr +unsigned integer the size of a pointer +.It Li 32 +unsigned 32-bit integer +.It Li 64 +unsigned 64-bit integer +.El +.Pp +For example, the function to atomically add two integers is called +.Fn atomic_add_int . +.Pp +Certain architectures also provide operations for types smaller than +.Dq Li int . +.Pp +.Bl -tag -offset indent -width short -compact +.It Li char +unsigned character +.It Li short +unsigned short integer +.It Li 8 +unsigned 8-bit integer +.It Li 16 +unsigned 16-bit integer +.El +.Pp +These types must not be used in machine-independent code. +.Ss Acquire and Release Operations +By default, a thread's accesses to different memory locations might not be +performed in +.Em program order , +that is, the order in which the accesses appear in the source code. +To optimize the program's execution, both the compiler and processor might +reorder the thread's accesses. +However, both ensure that their reordering of the accesses is not visible to +the thread. +Otherwise, the traditional memory model that is expected by single-threaded +programs would be violated. +Nonetheless, other threads in a multithreaded program, such as the +.Fx +kernel, might observe the reordering. +Moreover, in some cases, such as the implementation of synchronization between +threads, arbitrary reordering might result in the incorrect execution of the +program. +To constrain the reordering that both the compiler and processor might perform +on a thread's accesses, a programmer can use atomic operations with +.Em acquire +and +.Em release +semantics. +.Pp +Atomic operations on memory have up to three variants. +The first, or +.Em relaxed +variant, performs the operation without imposing any ordering constraints on +accesses to other memory locations. +This variant is the default. +The second variant has acquire semantics, and the third variant has release +semantics. +.Pp +An atomic operation can only have +.Em acquire +semantics if it performs a load +from memory. +When an atomic operation has acquire semantics, a load performed as +part of the operation must have +completed before any subsequent load or store (by program order) is +performed. +Conversely, acquire semantics do not require that prior loads or stores have +completed before a load from the atomic operation is performed. +To denote acquire semantics, the suffix +.Dq Li _acq +is inserted into the function name immediately prior to the +.Dq Li _ Ns Aq Fa type +suffix. +For example, to subtract two integers ensuring that the load of +the value from memory is +completed before any subsequent loads and stores are performed, use +.Fn atomic_subtract_acq_int . +.Pp +An atomic operation can only have +.Em release +semantics if it performs a store to memory. +When an atomic operation has release semantics, all prior loads or stores +(by program order) must have completed before a store executed as part of +the operation that is performed. +Conversely, release semantics do not require that a store from the atomic +operation must +have completed before any subsequent load or store is performed. +To denote release semantics, the suffix +.Dq Li _rel +is inserted into the function name immediately prior to the +.Dq Li _ Ns Aq Fa type +suffix. +For example, to add two long integers ensuring that all prior loads and +stores are completed before the store of the result is performed, use +.Fn atomic_add_rel_long . +.Pp +When a release operation by one thread +.Em synchronizes with +an acquire operation by another thread, usually meaning that the acquire +operation reads the value written by the release operation, then the effects +of all prior stores by the releasing thread must become visible to +subsequent loads by the acquiring thread. +Moreover, the effects of all stores (by other threads) that were visible to +the releasing thread must also become visible to the acquiring thread. +These rules only apply to the synchronizing threads. +Other threads might observe these stores in a different order. +.Pp +In effect, atomic operations with acquire and release semantics establish +one-way barriers to reordering that enable the implementations of +synchronization primitives to express their ordering requirements without +also imposing unnecessary ordering. +For example, for a critical section guarded by a mutex, an acquire operation +when the mutex is locked and a release operation when the mutex is unlocked +will prevent any loads or stores from moving outside of the critical +section. +However, they will not prevent the compiler or processor from moving loads +or stores into the critical section, which does not violate the semantics of +a mutex. +.Ss Architecture-dependent caveats for compare-and-swap +The +.Fn atomic_[f]cmpset_ +operations, specifically those without explicitly specified memory +ordering, are defined as relaxed. +Consequently, a thread's accesses to memory locations different from +that of the atomic operation can be reordered in relation to the +atomic operation. +.Pp +However, the implementation on the +.Sy amd64 +and +.Sy i386 +architectures provide sequentially consistent semantics. +In particular, the reordering mentioned above cannot occur. +.Pp +On the +.Sy arm64/aarch64 +architecture, the operation may include either acquire +semantics on the constituent load or release semantics +on the constituent store. +This means that accesses to other locations in program order +before the atomic, might be observed as executed after the load +that is the part of the atomic operation (but not after the store +from the operation due to release). +Similarly, accesses after the atomic might be observed as executed +before the store. +.Ss Thread Fence Operations +Alternatively, a programmer can use atomic thread fence operations to +constrain the reordering of accesses. +In contrast to other atomic operations, fences do not, themselves, access +memory. +.Pp +When a fence has acquire semantics, all prior loads (by program order) must +have completed before any subsequent load or store is performed. +Thus, an acquire fence is a two-way barrier for load operations. +To denote acquire semantics, the suffix +.Dq Li _acq +is appended to the function name, for example, +.Fn atomic_thread_fence_acq . +.Pp +When a fence has release semantics, all prior loads or stores (by program +order) must have completed before any subsequent store operation is +performed. +Thus, a release fence is a two-way barrier for store operations. +To denote release semantics, the suffix +.Dq Li _rel +is appended to the function name, for example, +.Fn atomic_thread_fence_rel . +.Pp +Although +.Fn atomic_thread_fence_acq_rel +implements both acquire and release semantics, it is not a full barrier. +For example, a store prior to the fence (in program order) may be completed +after a load subsequent to the fence. +In contrast, +.Fn atomic_thread_fence_seq_cst +implements a full barrier. +Neither loads nor stores may cross this barrier in either direction. +.Pp +In C11, a release fence by one thread synchronizes with an acquire fence by +another thread when an atomic load that is prior to the acquire fence (by +program order) reads the value written by an atomic store that is subsequent +to the release fence. +In contrast, in +.Fx , +because of the atomicity of ordinary, naturally +aligned loads and stores, fences can also be synchronized by ordinary loads +and stores. +This simplifies the implementation and use of some synchronization +primitives in +.Fx . +.Pp +Since neither a compiler nor a processor can foresee which (atomic) load +will read the value written by an (atomic) store, the ordering constraints +imposed by fences must be more restrictive than acquire loads and release +stores. +Essentially, this is why fences are two-way barriers. +.Pp +Although fences impose more restrictive ordering than acquire loads and +release stores, by separating access from ordering, they can sometimes +facilitate more efficient implementations of synchronization primitives. +For example, they can be used to avoid executing a memory barrier until a +memory access shows that some condition is satisfied. +.Ss Interrupt Fence Operations +The +.Fn atomic_interrupt_fence +function establishes ordering between its call location and any interrupt +handler executing on the same CPU. +It is modeled after the similar C11 function +.Fn atomic_signal_fence , +and adapted for the kernel environment. +.Ss Multiple Processors +In multiprocessor systems, the atomicity of the atomic operations on memory +depends on support for cache coherence in the underlying architecture. +In general, cache coherence on the default memory type, +.Dv VM_MEMATTR_DEFAULT , +is guaranteed by all architectures that are supported by +.Fx . +For example, cache coherence is guaranteed on write-back memory by the +.Tn amd64 +and +.Tn i386 +architectures. +However, on some architectures, cache coherence might not be enabled on all +memory types. +To determine if cache coherence is enabled for a non-default memory type, +consult the architecture's documentation. +.Ss Semantics +This section describes the semantics of each operation using a C like notation. +.Bl -hang +.It Fn atomic_add p v +.Bd -literal -compact +*p += v; +.Ed +.It Fn atomic_clear p v +.Bd -literal -compact +*p &= ~v; +.Ed +.It Fn atomic_cmpset dst old new +.Bd -literal -compact +if (*dst == old) { + *dst = new; + return (1); +} else + return (0); +.Ed +.El +.Pp +Some architectures do not implement the +.Fn atomic_cmpset +functions for the types +.Dq Li char , +.Dq Li short , +.Dq Li 8 , +and +.Dq Li 16 . +.Bl -hang +.It Fn atomic_fcmpset dst *old new +.El +.Pp +On architectures implementing +.Em Compare And Swap +operation in hardware, the functionality can be described as +.Bd -literal -offset indent -compact +if (*dst == *old) { + *dst = new; + return (1); +} else { + *old = *dst; + return (0); +} +.Ed +On architectures which provide +.Em Load Linked/Store Conditional +primitive, the write to +.Dv *dst +might also fail for several reasons, most important of which +is a parallel write to +.Dv *dst +cache line by other CPU. +In this case +.Fn atomic_fcmpset +function also returns +.Dv false , +despite +.Dl *old == *dst . +.Pp +Some architectures do not implement the +.Fn atomic_fcmpset +functions for the types +.Dq Li char , +.Dq Li short , +.Dq Li 8 , +and +.Dq Li 16 . +.Bl -hang +.It Fn atomic_fetchadd p v +.Bd -literal -compact +tmp = *p; +*p += v; +return (tmp); +.Ed +.El +.Pp +The +.Fn atomic_fetchadd +functions are only implemented for the types +.Dq Li int , +.Dq Li long +and +.Dq Li 32 +and do not have any variants with memory barriers at this time. +.Bl -hang +.It Fn atomic_load p +.Bd -literal -compact +return (*p); +.Ed +.It Fn atomic_readandclear p +.Bd -literal -compact +tmp = *p; +*p = 0; +return (tmp); +.Ed +.El +.Pp +The +.Fn atomic_readandclear +functions are not implemented for the types +.Dq Li char , +.Dq Li short , +.Dq Li ptr , +.Dq Li 8 , +and +.Dq Li 16 +and do not have any variants with memory barriers at this time. +.Bl -hang +.It Fn atomic_set p v +.Bd -literal -compact +*p |= v; +.Ed +.It Fn atomic_subtract p v +.Bd -literal -compact +*p -= v; +.Ed +.It Fn atomic_store p v +.Bd -literal -compact +*p = v; +.Ed +.It Fn atomic_swap p v +.Bd -literal -compact +tmp = *p; +*p = v; +return (tmp); +.Ed +.El +.Pp +The +.Fn atomic_swap +functions are not implemented for the types +.Dq Li char , +.Dq Li short , +.Dq Li ptr , +.Dq Li 8 , +and +.Dq Li 16 +and do not have any variants with memory barriers at this time. +.Bl -hang +.It Fn atomic_testandclear p v +.Bd -literal -compact +bit = 1 << (v % (sizeof(*p) * NBBY)); +tmp = (*p & bit) != 0; +*p &= ~bit; +return (tmp); +.Ed +.El +.Bl -hang +.It Fn atomic_testandset p v +.Bd -literal -compact +bit = 1 << (v % (sizeof(*p) * NBBY)); +tmp = (*p & bit) != 0; +*p |= bit; +return (tmp); +.Ed +.El +.Pp +The +.Fn atomic_testandset +and +.Fn atomic_testandclear +functions are only implemented for the types +.Dq Li int , +.Dq Li long , +.Dq ptr , +.Dq Li 32 , +and +.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 +is currently not implemented for some of the atomic operations on the +.Tn arm , +.Tn i386 , +and +.Tn powerpc +architectures. +.Sh RETURN VALUES +The +.Fn atomic_cmpset +function returns the result of the compare operation. +The +.Fn atomic_fcmpset +function returns +.Dv true +if the operation succeeded. +Otherwise it returns +.Dv false +and sets +.Va *old +to the found value. +The +.Fn atomic_fetchadd , +.Fn atomic_load , +.Fn atomic_readandclear , +and +.Fn atomic_swap +functions return the value at the specified address. +The +.Fn atomic_testandset +and +.Fn atomic_testandclear +function returns the result of the test operation. +.Sh EXAMPLES +This example uses the +.Fn atomic_cmpset_acq_ptr +and +.Fn atomic_set_ptr +functions to obtain a sleep mutex and handle recursion. +Since the +.Va mtx_lock +member of a +.Vt "struct mtx" +is a pointer, the +.Dq Li ptr +type is used. +.Bd -literal +/* Try to obtain mtx_lock once. */ +#define _obtain_lock(mp, tid) \\ + atomic_cmpset_acq_ptr(&(mp)->mtx_lock, MTX_UNOWNED, (tid)) + +/* Get a sleep lock, deal with recursion inline. */ +#define _get_sleep_lock(mp, tid, opts, file, line) do { \\ + uintptr_t _tid = (uintptr_t)(tid); \\ + \\ + if (!_obtain_lock(mp, tid)) { \\ + if (((mp)->mtx_lock & MTX_FLAGMASK) != _tid) \\ + _mtx_lock_sleep((mp), _tid, (opts), (file), (line));\\ + else { \\ + atomic_set_ptr(&(mp)->mtx_lock, MTX_RECURSE); \\ + (mp)->mtx_recurse++; \\ + } \\ + } \\ +} while (0) +.Ed +.Sh HISTORY +The +.Fn atomic_add , +.Fn atomic_clear , +.Fn atomic_set , +and +.Fn atomic_subtract +operations were introduced in +.Fx 3.0 . +Initially, these operations were defined on the types +.Dq Li char , +.Dq Li short , +.Dq Li int , +and +.Dq Li long . +.Pp +The +.Fn atomic_cmpset , +.Fn atomic_load_acq , +.Fn atomic_readandclear , +and +.Fn atomic_store_rel +operations were added in +.Fx 5.0 . +Simultaneously, the acquire and release variants were introduced, and +support was added for operation on the types +.Dq Li 8 , +.Dq Li 16 , +.Dq Li 32 , +.Dq Li 64 , +and +.Dq Li ptr . +.Pp +The +.Fn atomic_fetchadd +operation was added in +.Fx 6.0 . +.Pp +The +.Fn atomic_swap +and +.Fn atomic_testandset +operations were added in +.Fx 10.0 . +.Pp +The +.Fn atomic_testandclear +and +.Fn atomic_thread_fence +operations were added in +.Fx 11.0 . +.Pp +The relaxed variants of +.Fn atomic_load +and +.Fn atomic_store +were added in +.Fx 12.0 . +.Pp +The +.Fn atomic_interrupt_fence +operation was added in +.Fx 13.0 . diff --git a/static/freebsd/man9/backlight.9 b/static/freebsd/man9/backlight.9 new file mode 100644 index 00000000..c4c338ce --- /dev/null +++ b/static/freebsd/man9/backlight.9 @@ -0,0 +1,78 @@ +.\" Copyright (c) 2020 Emmanuel Vadot +.\" +.\" 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 October 2, 2020 +.Dt BACKLIGHT 9 +.Os +.Sh NAME +.Nm backlight , +.Nm backlight_register , +.Nm backlight_destroy , +.Nm BACKLIGHT_GET_STATUS , +.Nm BACKLIGHT_SET_STATUS +.Nd BACKLIGHT methods +.Sh SYNOPSIS +.Cd "device backlight" +.In "backlight_if.h" +.In "sys/sys/backlight.h" +.Ft int +.Fn BACKLIGHT_GET_STATUS "device_t bus" "struct backlight_props *props" +.Ft int +.Fn BACKLIGHT_SET_STATUS "device_t bus" "struct backlight_props *props" +.Ft struct cdev * +.Fn backlight_register "const char *name" "device_t dev" +.Ft int +.Fn backlight_destroy "struct cdev *cdev" +.Sh DESCRIPTION +The backlight driver provides a generic way for handling a panel backlight. +.Pp +Drivers for backlight system register themselves globally using the +.Fn backlight_register +function. +They must define two methods, +.Fn BACKLIGHT_GET_STATUS +which is used to query the current brightness level and +.Fn BACKLIGHT_SET_STATUS +which is used to update it. +.Sh INTERFACE +.Bl -tag -width indent +.It Fn BACKLIGHT_GET_STATUS "device_t bus" "struct backlight_props *props" +Driver fills the current brightless level and the optional supported levels. +.It Fn BACKLIGHT_SET_STATUS "device_t bus" "struct backlight_props *props" +Driver update the backlight level based on the brightness member of the props +struct. +.El +.Sh FILES +.Bl -tag -width "/dev/backlight/*" +.It Pa /dev/backlight/* +.El +.Sh SEE ALSO +.Xr backlight 8 +.Sh HISTORY +The +.Nm backlight +interface first appear in +.Fx 13.0 . +The +.Nm backlight +driver and manual page was written by +.An Emmanuel Vadot Aq Mt manu@FreeBSD.org . diff --git a/static/freebsd/man9/bhnd.9 b/static/freebsd/man9/bhnd.9 new file mode 100644 index 00000000..ed3007ea --- /dev/null +++ b/static/freebsd/man9/bhnd.9 @@ -0,0 +1,2664 @@ +.\" Copyright (c) 2015-2016 Landon Fuller +.\" Copyright (c) 2017 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" Portions of this documentation were written by Landon Fuller +.\" under sponsorship from the FreeBSD Foundation. +.\" +.\" 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 March 26, 2018 +.Dt BHND 9 +.Os +.Sh NAME +.Nm bhnd +.Nd BHND driver programming interface +.Sh SYNOPSIS +.In dev/bhnd/bhnd.h +.\" +.Ss Bus Resource Functions +.Ft int +.Fo bhnd_activate_resource +.Fa "device_t dev" "int type" "int rid" "struct bhnd_resource *r" +.Fc +.Ft "struct bhnd_resource *" +.Fo bhnd_alloc_resource +.Fa "device_t dev" "int type" "int *rid" "rman_res_t start" "rman_res_t end" +.Fa "rman_res_t count" "u_int flags" +.Fc +.Ft "struct bhnd_resource *" +.Fo bhnd_alloc_resource_any +.Fa "device_t dev" "int type" "int *rid" "u_int flags" +.Fc +.Ft int +.Fo bhnd_alloc_resources +.Fa "device_t dev" "struct resource_spec *rs" "struct bhnd_resource **res" +.Fc +.Ft int +.Fo bhnd_deactivate_resource +.Fa "device_t dev" "int type" "int rid" "struct bhnd_resource *r" +.Fc +.Ft int +.Fo bhnd_release_resource +.Fa "device_t dev" "int type" "int rid" "struct bhnd_resource *r" +.Fc +.Ft void +.Fo bhnd_release_resources +.Fa "device_t dev" "const struct resource_spec *rs" +.Fa "struct bhnd_resource **res" +.Fc +.\" +.Ss "Bus Space Functions" +.Ft void +.Fo bhnd_bus_barrier +.Fa "struct bhnd_resource *r" "bus_size_t offset" +.Fa "bus_size_t length" "int flags" +.Fc +.Ft uint8_t +.Fn bhnd_bus_read_1 "struct bhnd_resource *r" "bus_size_t offset" +.Ft uint16_t +.Fn bhnd_bus_read_2 "struct bhnd_resource *r" "bus_size_t offset" +.Ft uint32_t +.Fn bhnd_bus_read_4 "struct bhnd_resource *r" "bus_size_t offset" +.Ft void +.Fo bhnd_bus_read_multi_1 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bhnd_bus_read_multi_2 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bhnd_bus_read_multi_4 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bhnd_bus_read_multi_stream_1 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bhnd_bus_read_multi_stream_2 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bhnd_bus_read_multi_stream_4 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bhnd_bus_read_region_1 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bhnd_bus_read_region_2 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bhnd_bus_read_region_4 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bhnd_bus_read_region_stream_1 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bhnd_bus_read_region_stream_2 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bhnd_bus_read_region_stream_4 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fn bhnd_bus_read_stream_1 "struct bhnd_resource *r" "bus_size_t offset" +.Ft void +.Fn bhnd_bus_read_stream_2 "struct bhnd_resource *r" "bus_size_t offset" +.Ft uint32_t +.Fn bhnd_bus_read_stream_4 "struct bhnd_resource *r" "bus_size_t offset" +.Ft void +.Fo bhnd_bus_set_multi_1 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bhnd_bus_set_multi_2 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bhnd_bus_set_multi_4 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bhnd_bus_set_region_1 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bhnd_bus_set_region_2 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bhnd_bus_set_region_4 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fn bhnd_bus_write_1 "struct bhnd_resource *r" "uint8_t value" +.Ft void +.Fn bhnd_bus_write_2 "struct bhnd_resource *r" "uint16_t value" +.Ft void +.Fn bhnd_bus_write_4 "struct bhnd_resource *r" "uint32_t value" +.Ft void +.Fo bhnd_bus_write_multi_1 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bhnd_bus_write_multi_2 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bhnd_bus_write_multi_4 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bhnd_bus_write_multi_stream_1 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bhnd_bus_write_multi_stream_2 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bhnd_bus_write_multi_stream_4 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bhnd_bus_write_region_1 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bhnd_bus_write_region_2 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bhnd_bus_write_region_4 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bhnd_bus_write_region_stream_1 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bhnd_bus_write_region_stream_2 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bhnd_bus_write_region_stream_4 +.Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fn bhnd_bus_write_stream_1 "struct bhnd_resource *r" "uint8_t value" +.Ft void +.Fn bhnd_bus_write_stream_2 "struct bhnd_resource *r" "uint16_t value" +.Ft void +.Fn bhnd_bus_write_stream_4 "struct bhnd_resource *r" "uint32_t value" +.\" +.Ss "Device Configuration Functions" +.Ft int +.Fn bhnd_read_ioctl "device_t dev" "uint16_t *ioctl" +.Ft int +.Fn bhnd_write_ioctl "device_t dev" "uint16_t value" "uint16_t mask" +.Ft int +.Fn bhnd_read_iost "device_t dev" "uint16_t *iost" +.Ft uint32_t +.Fo bhnd_read_config +.Fa "device_t dev" "bus_size_t offset" "void *value" "u_int width" +.Fc +.Ft int +.Fo bhnd_write_config +.Fa "device_t dev" "bus_size_t offset" "const void *value" "u_int width" +.Fc +.Ft int +.Fn bhnd_reset_hw "device_t dev" "uint16_t ioctl" "uint16_t reset_ioctl" +.Ft int +.Fn bhnd_suspend_hw "device_t dev" "uint16_t ioctl" +.Ft bool +.Fn bhnd_is_hw_suspended "device_t dev" +.\" +.Ss "Device Information Functions" +.Ft bhnd_attach_type +.Fo bhnd_get_attach_type +.Fa "device_t dev" +.Fc +.Ft "const struct bhnd_chipid *" +.Fo bhnd_get_chipid +.Fa "device_t dev" +.Fc +.Ft bhnd_devclass_t +.Fo bhnd_get_class +.Fa "device_t dev" +.Fc +.Ft u_int +.Fo bhnd_get_core_index +.Fa "device_t dev" +.Fc +.Ft "struct bhnd_core_info" +.Fo bhnd_get_core_info +.Fa "device_t dev" +.Fc +.Ft int +.Fo bhnd_get_core_unit +.Fa "device_t dev" +.Fc +.Ft uint16_t +.Fo bhnd_get_device +.Fa "device_t dev" +.Fc +.Ft const char * +.Fo bhnd_get_device_name +.Fa "device_t dev" +.Fc +.Ft uint8_t +.Fo bhnd_get_hwrev +.Fa "device_t dev" +.Fc +.Ft uint16_t +.Fo bhnd_get_vendor +.Fa "device_t dev" +.Fc +.Ft const char * +.Fo bhnd_get_vendor_name +.Fa "device_t dev" +.Fc +.Ft int +.Fo bhnd_read_board_info +.Fa "device_t dev" "struct bhnd_board_info *info" +.Fc +.\" +.Ss "Device Matching Functions" +.Ft bool +.Fo bhnd_board_matches +.Fa "const struct bhnd_board_info *board" "const struct bhnd_board_match *desc" +.Fc +.Ft device_t +.Fo bhnd_bus_match_child +.Fa "device_t bus" "const struct bhnd_core_match *desc" +.Fc +.Ft bool +.Fo bhnd_chip_matches +.Fa "const struct bhnd_chipid *chip" "const struct bhnd_chip_match *desc" +.Fc +.Ft "struct bhnd_core_match" +.Fo bhnd_core_get_match_desc +.Fa "const struct bhnd_core_info *core" +.Fc +.Ft bool +.Fo bhnd_core_matches +.Fa "const struct bhnd_core_info *core" "const struct bhnd_core_match *desc" +.Fc +.Ft bool +.Fo bhnd_cores_equal +.Fa "const struct bhnd_core_info *lhs" "const struct bhnd_core_info *rhs" +.Fc +.Ft bool +.Fo bhnd_hwrev_matches +.Fa "uint16_t hwrev" "const struct bhnd_hwrev_match *desc" +.Fc +.Ft "const struct bhnd_core_info *" +.Fo bhnd_match_core +.Fa "const struct bhnd_core_info *cores" "u_int num_cores" +.Fa "const struct bhnd_core_match *desc" +.Fc +.\" +.Ss "Device Table Functions" +.Ft "const struct bhnd_device *" +.Fo bhnd_device_lookup +.Fa "device_t dev" "const struct bhnd_device *table" "size_t entry_size" +.Fc +.Ft bool +.Fo bhnd_device_matches +.Fa "device_t dev" "const struct bhnd_device_match *desc" +.Fc +.Ft uint32_t +.Fo bhnd_device_quirks +.Fa "device_t dev" "const struct bhnd_device *table" "size_t entry_size" +.Fc +.Fo BHND_BOARD_QUIRK +.Fa "board" "flags" +.Fc +.Fo BHND_CHIP_QUIRK +.Fa "chip" "hwrev" "flags" +.Fc +.Fo BHND_CORE_QUIRK +.Fa "hwrev" "flags" +.Fc +.Fo BHND_DEVICE +.Fa "vendor" "device" "desc" "quirks" "..." +.Fc +.Fo BHND_DEVICE_IS_END +.Fa "struct bhnd_device *d" +.Fc +.Fo BHND_DEVICE_QUIRK_IS_END +.Fa "struct bhnd_device_quirk *q" +.Fc +.Fo BHND_PKG_QUIRK +.Fa "chip" "pkg" "flags" +.Fc +.Bd -literal +struct bhnd_device_quirk { + struct bhnd_device_match desc; + uint32_t quirks; +}; +.Ed +.Bd -literal +struct bhnd_device { + const struct bhnd_device_match core; + const char *desc; + const struct bhnd_device_quirk *quirks_table; + uint32_t device_flags; +}; +.Ed +.Bd -literal +enum { + BHND_DF_ANY = 0, + BHND_DF_HOSTB = (1 << 0), + BHND_DF_SOC = (1 << 1), + BHND_DF_ADAPTER = (1 << 2) +}; +.Ed +.Bd -literal +#define BHND_DEVICE_END { { BHND_MATCH_ANY }, NULL, NULL, 0 } +.Ed +.Bd -literal +#define BHND_DEVICE_QUIRK_END { { BHND_MATCH_ANY }, 0 } +.Ed +.\" +.Ss "DMA Address Translation Functions" +.Ft int +.Fo bhnd_get_dma_translation +.Fa "device_t dev" "u_int width" "uint32_t flags" "bus_dma_tag_t *dmat" +.Fa "struct bhnd_dma_translation *translation" +.Fc +.Bd -literal +struct bhnd_dma_translation { + bhnd_addr_t base_addr; + bhnd_addr_t addr_mask; + bhnd_addr_t addrext_mask; + uint32_t flags; +}; +.Ed +.Bd -literal +typedef enum { + BHND_DMA_ADDR_30BIT = 30, + BHND_DMA_ADDR_32BIT = 32, + BHND_DMA_ADDR_64BIT = 64 +} bhnd_dma_addrwidth; +.Ed +.Bd -literal +enum bhnd_dma_translation_flags { + BHND_DMA_TRANSLATION_PHYSMAP = (1<<0), + BHND_DMA_TRANSLATION_BYTESWAPPED = (1<<1) +}; +.Ed +.\" +.Ss "Interrupt Functions" +.Ft u_int +.Fo bhnd_get_intr_count +.Fa "device_t dev" +.Fc +.Ft int +.Fo bhnd_get_intr_ivec +.Fa "device_t dev" "u_int intr" "u_int *ivec" +.Fc +.Ft int +.Fo bhnd_map_intr +.Fa "device_t dev" "u_int intr" "rman_res_t *irq" +.Fc +.Ft void +.Fo bhnd_unmap_intr +.Fa "device_t dev" "rman_res_t irq" +.Fc +.\" +.Ss "NVRAM Functions" +.Ft int +.Fo bhnd_nvram_getvar +.Fa "device_t dev" "const char *name" "void *buf" "size_t *len" +.Fa "bhnd_nvram_type type" +.Fc +.Ft int +.Fo bhnd_nvram_getvar_array +.Fa "device_t dev" "const char *name" "void *buf" "size_t size" +.Fa "bhnd_nvram_type type" +.Fc +.Ft int +.Fo bhnd_nvram_getvar_int +.Fa "device_t dev" "const char *name" "void *value" "int width" +.Fc +.Ft int +.Fn bhnd_nvram_getvar_int8 "device_t dev" "const char *name" "int8_t *value" +.Ft int +.Fn bhnd_nvram_getvar_int16 "device_t dev" "const char *name" "int16_t *value" +.Ft int +.Fn bhnd_nvram_getvar_int32 "device_t dev" "const char *name" "int32_t *value" +.Ft int +.Fo bhnd_nvram_getvar_uint +.Fa "device_t dev" "const char *name" "void *value" "int width" +.Fc +.Ft int +.Fo bhnd_nvram_getvar_uint8 +.Fa "device_t dev" "const char *name" "uint8_t *value" +.Fc +.Ft int +.Fo bhnd_nvram_getvar_uint16 +.Fa "device_t dev" "const char *name" "uint16_t *value" +.Fc +.Ft int +.Fo bhnd_nvram_getvar_uint32 +.Fa "device_t dev" "const char *name" "uint32_t *value" +.Fc +.Ft int +.Fo bhnd_nvram_getvar_str +.Fa "device_t dev" "const char *name" "char *buf" "size_t len" "size_t *rlen" +.Fc +.Ft "const char *" +.Fo bhnd_nvram_string_array_next +.Fa "const char *inp" "size_t ilen" "const char *prev" "size_t *olen" +.Fc +.Bd -literal +typedef enum { + BHND_NVRAM_TYPE_UINT8 = 0, + BHND_NVRAM_TYPE_UINT16 = 1, + BHND_NVRAM_TYPE_UINT32 = 2, + BHND_NVRAM_TYPE_UINT64 = 3, + BHND_NVRAM_TYPE_INT8 = 4, + BHND_NVRAM_TYPE_INT16 = 5, + BHND_NVRAM_TYPE_INT32 = 6, + BHND_NVRAM_TYPE_INT64 = 7, + BHND_NVRAM_TYPE_CHAR = 8, + BHND_NVRAM_TYPE_STRING = 9, + BHND_NVRAM_TYPE_BOOL = 10, + BHND_NVRAM_TYPE_NULL = 11, + BHND_NVRAM_TYPE_DATA = 12 + BHND_NVRAM_TYPE_UINT8_ARRAY = 16, + BHND_NVRAM_TYPE_UINT16_ARRAY = 17, + BHND_NVRAM_TYPE_UINT32_ARRAY = 18, + BHND_NVRAM_TYPE_UINT64_ARRAY = 19, + BHND_NVRAM_TYPE_INT8_ARRAY = 20, + BHND_NVRAM_TYPE_INT16_ARRAY = 21, + BHND_NVRAM_TYPE_INT32_ARRAY = 22, + BHND_NVRAM_TYPE_INT64_ARRAY = 23, + BHND_NVRAM_TYPE_CHAR_ARRAY = 24, + BHND_NVRAM_TYPE_STRING_ARRAY = 25, + BHND_NVRAM_TYPE_BOOL_ARRAY = 26 +} bhnd_nvram_type; +.Ed +.\" +.Ss "Port/Region Functions" +.Ft int +.Fo bhnd_decode_port_rid +.Fa "device_t dev" "int type" "int rid" "bhnd_port_type *port_type" +.Fa "u_int *port" "u_int *region" +.Fc +.Ft u_int +.Fo bhnd_get_port_count +.Fa "device_t dev" "bhnd_port_type type" +.Fc +.Ft int +.Fo bhnd_get_port_rid +.Fa "device_t dev" "bhnd_port_type type" "u_int port" "u_int region" +.Fc +.Ft int +.Fo bhnd_get_region_addr +.Fa "device_t dev" "bhnd_port_type port_type" "u_int port" "u_int region" +.Fa "bhnd_addr_t *region_addr" "bhnd_size_t *region_size" +.Fc +.Ft u_int +.Fo bhnd_get_region_count +.Fa "device_t dev" "bhnd_port_type type" "u_int port" +.Fc +.Ft bool +.Fo bhnd_is_region_valid +.Fa "device_t dev" "bhnd_port_type type" "u_int port" "u_int region" +.Fc +.Bd -literal +typedef enum { + BHND_PORT_DEVICE = 0, + BHND_PORT_BRIDGE = 1, + BHND_PORT_AGENT = 2 +} bhnd_port_type; +.Ed +.\" +.Ss "Power Management Functions" +.Ft int +.Fo bhnd_alloc_pmu +.Fa "device_t dev" +.Fc +.Ft int +.Fo bhnd_release_pmu +.Fa "device_t dev" +.Fc +.Ft int +.Fo bhnd_enable_clocks +.Fa "device_t dev" "uint32_t clocks" +.Fc +.Ft int +.Fo bhnd_request_clock +.Fa "device_t dev" "bhnd_clock clock" +.Fc +.Ft int +.Fo bhnd_get_clock_freq +.Fa "device_t dev" "bhnd_clock clock" "u_int *freq" +.Fc +.Ft int +.Fo bhnd_get_clock_latency +.Fa "device_t dev" "bhnd_clock clock" "u_int *latency" +.Fc +.Ft int +.Fo bhnd_request_ext_rsrc +.Fa "device_t dev" "u_int rsrc" +.Fc +.Ft int +.Fo bhnd_release_ext_rsrc +.Fa "device_t dev" "u_int rsrc" +.Fc +.Bd -literal +typedef enum { + BHND_CLOCK_DYN = (1 << 0), + BHND_CLOCK_ILP = (1 << 1), + BHND_CLOCK_ALP = (1 << 2), + BHND_CLOCK_HT = (1 << 3) +} bhnd_clock; +.Ed +.\" +.Ss "Service Provider Functions" +.Ft int +.Fo bhnd_register_provider +.Fa "device_t dev" "bhnd_service_t service" +.Fc +.Ft int +.Fo bhnd_deregister_provider +.Fa "device_t dev" "bhnd_service_t service" +.Fc +.Ft device_t +.Fo bhnd_retain_provider +.Fa "device_t dev" "bhnd_service_t service" +.Fc +.Ft void +.Fo bhnd_release_provider +.Fa "device_t dev" "device_t provider" "bhnd_service_t service" +.Fc +.Bd -literal +typedef enum { + BHND_SERVICE_CHIPC, + BHND_SERVICE_PWRCTL, + BHND_SERVICE_PMU, + BHND_SERVICE_NVRAM, + BHND_SERVICE_GPIO, + BHND_SERVICE_ANY = 1000 +} bhnd_service_t; +.Ed +.\" +.Ss "Utility Functions" +.Ft "bhnd_erom_class_t *" +.Fo bhnd_driver_get_erom_class +.Fa "driver_t *driver" +.Fc +.Ft bhnd_devclass_t +.Fo bhnd_find_core_class +.Fa "uint16_t vendor" "uint16_t device" +.Fc +.Ft "const char *" +.Fo bhnd_find_core_name +.Fa "uint16_t vendor" "uint16_t device" +.Fc +.Ft bhnd_devclass_t +.Fo bhnd_core_class +.Fa "const struct bhnd_core_info *ci" +.Fc +.Ft "const char *" +.Fo bhnd_core_name +.Fa "const struct bhnd_core_info *ci" +.Fc +.Ft int +.Fo bhnd_format_chip_id +.Fa "char *buffer" "size_t size" "uint16_t chip_id" +.Fc +.Ft void +.Fo bhnd_set_custom_core_desc +.Fa "device_t dev" "const char *dev_name" +.Fc +.Ft void +.Fo bhnd_set_default_core_desc +.Fa "device_t dev" +.Fc +.Ft "const char *" +.Fo bhnd_vendor_name +.Fa "uint16_t vendor" +.Fc +.Bd -literal +#define BHND_CHIPID_MAX_NAMELEN 32 +.Ed +.\" +.Sh DESCRIPTION +.Nm +provides a unified bus and driver programming interface for the +on-chip interconnects and IP cores found in Broadcom Home Networking Division +(BHND) devices. +.Pp +The BHND device family consists of MIPS/ARM SoCs (System On a Chip) and +host-connected chipsets based on a common library of Broadcom IP cores, +connected via one of two on-chip backplane (hardware bus) architectures. +.Pp +Hardware designed prior to 2009 used Broadcom's +.Dq SSB +backplane architecture, based on Sonics Silicon's interconnect IP. +Each core on the Sonics backplane vends a 4 KiB register block, containing both +device-specific CSRs, and SSB-specific per-core device management +(enable/reset/etc) registers. +.Pp +Subsequent hardware is based on Broadcom's +.Dq BCMA +backplane, based on ARM's AMBA IP. +The IP cores used in earlier SSB-based devices were adapted for compatibility +with the new backplane, with additional +.Dq wrapper +cores providing per-core device management functions in place of the SSB +per-core management registers. +.Pp +When BHND hardware is used as a host-connected peripheral (e.g., in a PCI Wi-Fi +card), the on-chip peripheral controller core is configured to operate as +an endpoint device, bridging access to the SoC hardware: +.Bl -dash -offset indent +.It +Host access to SoC address space is provided via a set of register windows +(e.g., a set of configurable windows into SoC address space mapped via PCI BARs) +.It +DMA is supported by the bridge core's sparse mapping of host address space into +the backplane address space. +These address regions may be used as a target for the on-chip DMA engine. +.It +Any backplane interrupt vectors routed to the bridge core may be mapped by the +bridge to host interrupts (e.g., PCI INTx/MSI/MSI-X). +.El +.Pp +The +.Nm +driver programming interface \(em and +.Xr bhndb 4 +host bridge drivers \(em support the implementation of common drivers for +Broadcom IP cores, whether attached via a BHND host bridge, or via the native +SoC backplane. +.\" +.Ss "Bus Resource Functions" +The bhnd_resource functions are wrappers for the standard +.Vt "struct resource" +bus APIs, providing support for +.Vt SYS_RES_MEMORY +resources that, on +.Xr bhndb 4 +bridged chipsets, may require on-demand remapping of address windows +prior to accessing bus memory. +.Pp +These functions are primarily used in the implementation of BHND platform device +drivers that, on host-connected peripherals, must share a small set of register +windows during initial setup and teardown. +.Pp +BHND peripherals are designed to not require register window remapping +during normal operation, and most drivers may safely use the standard +.Vt struct resource +APIs directly. +.Pp +The +.Fn bhnd_activate_resource +function activates a previously allocated resource. +.Pp +The arguments are as follows: +.Bl -tag -width indent +.It Fa dev +The device holding ownership of the allocated resource. +.It Fa type +The type of the resource. +.It Fa rid +The bus-specific handle that identifies the resource being activated. +.It Fa r +A pointer to the resource returned by +.Fn bhnd_alloc_resource . +.El +.Pp +The +.Fn bhnd_alloc_resource +function allocates a resource from a device's parent +.Xr bhnd 4 +bus. +.Pp +The arguments are as follows: +.Bl -tag -width indent +.It Fa dev +The device requesting resource ownership. +.It Fa type +The type of resource to allocate. +This may be any type supported by the standard +.Xr bus_alloc_resource 9 +function. +.It Fa rid +The bus-specific handle identifying the resource being allocated. +.It Fa start +The start address of the resource. +.It Fa end +The end address of the resource. +.It Fa count +The size of the resource. +.It Fa flags +The flags for the resource to be allocated. +These may be any values supported by the standard +.Xr bus_alloc_resource 9 +function. +.El +.Pp +To request that the bus supply the resource's default +.Fa start , +.Fa end , +and +.Fa count +values, pass +.Fa start +and +.Fa end +values of 0ul and ~0ul respectively, and a +.Fa count +of 1. +.Pp +The +.Fn bhnd_alloc_resource_any +function is a convenience wrapper for +.Fn bhnd_alloc_resource , +using the resource's default +.Fa start , +.Fa end , +and +.Fa count +values. +.Pp +The arguments are as follows: +.Bl -tag -width indent +.It Fa dev +The device requesting resource ownership. +.It Fa type +The type of resource to allocate. +This may be any type supported by the standard +.Xr bus_alloc_resource 9 +function. +.It Fa rid +The bus-specific handle identifying the resource being allocated. +.It Fa flags +The flags for the resource to be allocated. +These may be any values supported by the standard +.Xr bus_alloc_resource 9 +function. +.El +.Pp +The +.Fn bhnd_alloc_resources +function allocates resources defined in resource specification from a device's +parent +.Xr bhnd 4 +bus. +.Pp +The arguments are as follows: +.Bl -tag -width indent +.It Fa dev +The device requesting ownership of the resources. +.It Fa rs +A standard bus resource specification. +If all requested resources, are successfully allocated, +this will be updated with the allocated resource identifiers. +.It Fa res +If all requested resources are successfully allocated, this will be populated +with the allocated +.Vt "struct bhnd_resource" +instances. +.El +.Pp +The +.Fn bhnd_deactivate_resource +function deactivates a resource previously activated by. +.Fn bhnd_activate_resource . +The arguments are as follows: +.Bl -tag -width indent +.It Fa dev +The device holding ownership of the activated resource. +.It Fa type +The type of the resource. +.It Fa rid +The bus-specific handle identifying the resource. +.It Fa r +A pointer to the resource returned by bhnd_alloc_resource. +.El +.Pp +The +.Fn bhnd_release_resource +function frees a resource previously returned by +.Fn bhnd_alloc_resource . +The arguments are as follows: +.Bl -tag -width indent +.It Fa dev +The device holding ownership of the resource. +.It Fa type +The type of the resource. +.It Fa rid +The bus-specific handle identifying the resource. +.It Fa r +A pointer to the resource returned by bhnd_alloc_resource. +.El +.Pp +The +.Fn bhnd_release_resources +function frees resources previously returned by +.Fn bhnd_alloc_resources . +The arguments are as follows: +.Bl -tag -width indent +.It Fa dev +The device that owns the resources. +.It Fa rs +A standard bus resource specification previously initialized by +.Fn bhnd_alloc_resources . +.It Fa res +The resources to be released. +.El +.Pp +The +.Vt bhnd_resource +structure contains the following fields: +.Bl -tag -width "direct" +.It Fa res +A pointer to the bus +.Vt struct resource . +.It Fa direct +If true, the resource requires bus window remapping before it is MMIO +accessible. +.El +.\" +.Ss "Bus Space Functions" +The bhnd_bus_space functions wrap their equivalent +.Xr bus_space 9 +counterparts, and provide support for accessing bus memory via +.Vt "struct bhnd_resource". +.Pp +.Bl -ohang -offset indent -compact +.It Fn bhnd_bus_barrier +.It Fn bhnd_bus_[read|write]_[1|2|4] +.It Fn bhnd_bus_[read_multi|write_multi]_[1|2|4] +.It Fn bhnd_bus_[read_multi_stream|write_multi_stream]_[1|2|4] +.It Fn bhnd_bus_[read_region|write_region]_[1|2|4] +.It Fn bhnd_bus_[read_region_stream|write_region_stream]_[1|2|4] +.It Fn bhnd_bus_[read_stream|write_stream]_[1|2|4] +.It Fn bhnd_bus_[set_multi|set_stream]_[1|2|4] +.El +.Pp +Drivers that do not rely on +.Vt "struct bhnd_resource" +should use the standard +.Vt struct resource +and +.Xr bus_space 9 +APIs directly. +.\" +.Ss "Device Configuration Functions" +The +.Fn bhnd_read_ioctl +function is used to read the I/O control register value of device +.Fa dev , +returning the current value in +.Fa ioctl . +.Pp +The +.Fn bhnd_write_ioctl +function is used to modify the I/O control register of +.Fa dev . +The new value of the register is computed by updating any bits set in +.Fa mask +to +.Fa value . +The following I/O control flags are supported: +.Bl -tag -width ".Dv BHND_IOCTL_CLK_FORCE" -offset indent +.It Dv BHND_IOCTL_BIST +Initiate a built-in self-test (BIST). +Must be cleared after BIST results are read via the IOST (I/O Status) register. +.It Dv BHND_IOCTL_PME +Enable posting of power management events by the core. +.It Dv BHND_IOCTL_CLK_FORCE +Force disable of clock gating, resulting in all clocks being distributed within +the core. +Should be set when asserting/deasserting reset to ensure the reset signal fully +propagates to the entire core. +.It Dv BHND_IOCTL_CLK_EN +If cleared, the core clock will be disabled. +Should be set during normal operation, and cleared when the core is held in +reset. +.It Dv BHND_IOCTL_CFLAGS +The mask of IOCTL bits reserved for additional core-specific I/O control flags. +.El +.Pp +The +.Fn bhnd_read_iost +function is used to read the I/O status register of device +.Fa dev , +returning the current value in +.Fa iost . +The following I/O status flags are supported: +.Bl -tag -width ".Dv BHND_IOST_BIST_DONE" -offset indent +.It Dv BHND_IOST_BIST_DONE +Set upon BIST completion. +Will be cleared when the +.Dv BHND_IOCTL_BIST +flag of the I/O control register is cleared using +.Fn bhnd_write_ioctl . +.It Dv BHND_IOST_BIST_FAIL +Set upon detection of a BIST error; the value is unspecified if BIST has not +completed and +.Dv BHND_IOST_BIST_DONE +is not also set. +.It Dv BHND_IOST_CLK +Set if the core has required that clocked be ungated, or cleared otherwise. +The value is undefined if a core does not support clock gating. +.It Dv BHND_IOST_DMA64 +Set if this core supports 64-bit DMA. +.It Dv BHND_IOST_CFLAGS +The mask of IOST bits reserved for additional core-specific I/O status flags. +.El +.Pp +The +.Fn bhnd_read_config +function is used to read a data item of +.Fa width +bytes at +.Fa offset +from the backplane-specific agent/config space of the device +.Fa dev . +.Pp +The +.Fn bhnd_write_config +function is used to write a data item of +.Fa width +bytes with +.Fa value +at +.Fa offset +from the backplane-specific agent/config space of the device +.Fa dev . +The requested +.Fa width +must be one of 1, 2, or 4 bytes. +.Pp +The agent/config space accessible via +.Fn bhnd_read_config +and +.Fn bhnd_write_config +is backplane-specific, and these functions should only be used for functionality +that is not available via another +.Nm +function. +.Pp +The +.Fn bhnd_suspend_hw +function transitions the device +.Fa dev +to a low power +.Dq RESET +state, writing +.Fa ioctl +to the I/O control flags of +.Fa dev . +The hardware may be brought out of this state using +.Fn bhnd_reset_hw . +.Pp +The +.Fn bhnd_reset_hw +function first transitions the device +.Fa dev +to a low power RESET state, writing +.Fa ioctl_reset +to the I/O control flags +of +.Fa dev , +and then brings the device out of RESET, writing +.Fa ioctl +to the device's I/O control flags. +.Pp +The +.Fn bhnd_is_hw_suspended +function returns +.Dv true +if the device +.Fa dev +is currently held in a RESET state, or is otherwise not clocked. +Otherwise, it returns +.Dv false . +.Pp +Any outstanding per-device PMU requests made using +.Fn bhnd_enable_clocks , +.Fn bhnd_request_clock , +or +.Fn bhnd_request_ext_rsrc +will be released automatically upon placing a device into a RESET state. +.Ss "Device Information Functions" +The +.Fn bhnd_get_attach_type +function returns the attachment type of the parent +.Xr bhnd 4 +bus of device +.Fa dev . +.Pp +The following attachment types are supported: +.Bl -hang -width ".Dv BHND_ATTACH_ADAPTER" -offset indent +.It Dv BHND_ATTACH_ADAPTER +The bus is resident on a bridged adapter, such as a PCI Wi-Fi device. +.It Dv BHND_ATTACH_NATIVE +The bus is resident on the native host, such as the primary or secondary bus of +an embedded SoC. +.El +.Pp +The +.Fn bhnd_get_chipid +function returns chip information from the parent +.Xr bhnd 4 +bus of device +.Fa dev . +The returned +.Vt bhnd_chipid +struct contains the following fields: +.Bl -tag -width "enum_addr" -offset indent +.It Fa chip_id +The chip identifier. +.It Fa chip_rev +The chip's hardware revision. +.It Fa chip_pkg +The chip's semiconductor package identifier. +.Pp +Several different physical semiconductor package variants may exist for a given +chip, each of which may require driver workarounds for hardware errata, +unpopulated components, etc. +.It Fa chip_type +The interconnect architecture used by this chip. +.It Fa chip_caps +The +.Nm +capability flags supported by this chip. +.It Fa enum_addr +The backplane enumeration address. +On SSB devices, this will be the base address of the first SSB core. +On BCMA devices, this will be the address of the enumeration ROM (EROM) core. +.It Fa ncores +The number of cores on the chip backplane, or 0 if unknown. +.El +.Pp +The following constants are defined for known +.Fa chip_type +values: +.Bl -tag -width ".Dv BHND_CHIPTYPE_BCMA_ALT" -offset indent -compact +.It Dv BHND_CHIPTYPE_SIBA +SSB interconnect. +.It Dv BHND_CHIPTYPE_BCMA +BCMA interconnect. +.It Dv BHND_CHIPTYPE_BCMA_ALT +BCMA-compatible variant found in Broadcom Northstar ARM SoCs. +.It Dv BHND_CHIPTYPE_UBUS +UBUS interconnect. +This BCMA-derived interconnect is found in Broadcom BCM33xx DOCSIS SoCs, and +BCM63xx xDSL SoCs. +UBUS is not currently supported by +.Xr bhnd 4 . +.El +.Pp +The following +.Fa chip_caps +flags are supported: +.Bl -tag -width ".Dv BHND_CAP_BP64" -offset indent -compact +.It Dv BHND_CAP_BP64 +The backplane supports 64-bit addressing. +.It Dv BHND_CAP_PMU +PMU is present. +.El +.Pp +Additional symbolic constants for known +.Fa chip_id , +.Fa chip_pkg , +and +.Fa chip_type +values are defined in +.In dev/bhnd/bhnd_ids.h . +.Pp +The +.Fn bhnd_get_class +function returns the BHND class of device +.Fa dev , +if the device's +.Em vendor +and +.Em device +identifiers are recognized. +Otherwise, returns +.Dv BHND_DEVCLASS_OTHER . +.Pp +One of the following device classes will be returned: +.Pp +.Bl -tag -width ".Dv BHND_DEVCLASS_SOC_ROUTER" -offset indent -compact +.It Dv BHND_DEVCLASS_CC +ChipCommon I/O Controller +.It Dv BHND_DEVCLASS_CC_B +ChipCommon Auxiliary Controller +.It Dv BHND_DEVCLASS_PMU +PMU Controller +.It Dv BHND_DEVCLASS_PCI +PCI Host/Device Bridge +.It Dv BHND_DEVCLASS_PCIE +PCIe Host/Device Bridge +.It Dv BHND_DEVCLASS_PCCARD +PCMCIA Host/Device Bridge +.It Dv BHND_DEVCLASS_RAM +Internal RAM/SRAM +.It Dv BHND_DEVCLASS_MEMC +Memory Controller +.It Dv BHND_DEVCLASS_ENET +IEEE 802.3 MAC/PHY +.It Dv BHND_DEVCLASS_ENET_MAC +IEEE 802.3 MAC +.It Dv BHND_DEVCLASS_ENET_PHY +IEEE 802.3 PHY +.It Dv BHND_DEVCLASS_WLAN +IEEE 802.11 MAC/PHY/Radio +.It Dv BHND_DEVCLASS_WLAN_MAC +IEEE 802.11 MAC +.It Dv BHND_DEVCLASS_WLAN_PHY +IEEE 802.11 PHY +.It Dv BHND_DEVCLASS_CPU +CPU Core +.It Dv BHND_DEVCLASS_SOC_ROUTER +Interconnect Router +.It Dv BHND_DEVCLASS_SOC_BRIDGE +Interconnect Host Bridge +.It Dv BHND_DEVCLASS_EROM +Device Enumeration ROM +.It Dv BHND_DEVCLASS_NVRAM +NVRAM/Flash Controller +.It Dv BHND_DEVCLASS_SOFTMODEM +Analog/PSTN SoftModem Codec +.It Dv BHND_DEVCLASS_USB_HOST +USB Host Controller +.It Dv BHND_DEVCLASS_USB_DEV +USB Device Controller +.It Dv BHND_DEVCLASS_USB_DUAL +USB Host/Device Controller +.It Dv BHND_DEVCLASS_OTHER +Other / Unknown +.It Dv BHND_DEVCLASS_INVALID +Invalid Class +.El +.Pp +The +.Fn bhnd_get_core_info +function returns the core information for device +.Fa dev . +The returned +.Vt bhnd_core_info +structure contains the following fields: +.Pp +.Bl -tag -width "core_idx" -offset indent -compact +.It Fa vendor +Vendor identifier (JEP-106, ARM 4-bit continuation encoded) +.It Fa device +Device identifier +.It Fa hwrev +Hardware revision +.It Fa core_idx +Core index +.It Fa unit +Core unit +.El +.Pp +Symbolic constants for common vendor and device identifiers are defined in +.In dev/bhnd/bhnd_ids.h . +Common vendor identifiers include: +.Pp +.Bl -tag -width ".Dv BHND_MFGID_MIPS" -offset indent -compact +.It Dv BHND_MFGID_ARM +ARM +.It Dv BHND_MFGID_BCM +Broadcom +.It Dv BHND_MFGID_MIPS +MIPS +.El +.Pp +The +.Fn bhnd_get_core_index , +.Fn bhnd_get_core_unit , +.Fn bhnd_get_device , +.Fn bhnd_get_hwrev , +and +.Fn bhnd_get_vendor +functions are convenience wrappers for +.Fn bhnd_get_core_info , +returning, respect the +.Fa core_idx , +.Fa core_unit , +.Fa device , +.Fa hwrev , +or +.Fa vendor +field from the +.Vt bhnd_core_info +structure. +.Pp +The +.Fn bhnd_get_device_name +function returns a human readable name for device +.Fa dev . +.Pp +The +.Fn bhnd_get_vendor_name +function returns a human readable name for the vendor of device +.Fa dev . +.Pp +The +.Fn bhnd_read_board_info +function attempts to read the board information for device +.Fa dev . +The board information will be returned in the location pointed to by +.Fa info +on success. +.Pp +The +.Vt bhnd_board_info +structure contains the following fields: +.Bl -tag -width "board_srom_rev" -offset indent +.It Fa board_vendor +Vendor ID of the board manufacturer (PCI-SIG assigned). +.It Fa board_type +Board ID. +.It Fa board_devid +Device ID. +.It Fa board_rev +Board revision. +.It Fa board_srom_rev +Board SROM format revision. +.It Fa board_flags +Board flags (1) +.It Fa board_flags2 +Board flags (2) +.It Fa board_flags3 +Board flags (3) +.El +.Pp +The +.Fa board_devid +field is the Broadcom PCI device ID that most closely matches the +capabilities of the BHND device (if any). +.Pp +On PCI devices, the +.Fa board_vendor , +.Fa board_type , +and +.Fa board_devid +fields default to the PCI Subsystem Vendor ID, PCI Subsystem ID, and PCI +device ID, unless overridden in device NVRAM. +.Pp +On other devices, including SoCs, the +.Fa board_vendor , +.Fa board_type , +and +.Fa board_devid +fields will be populated from device NVRAM. +.Pp +Symbolic constants for common board flags are defined in +.In dev/bhnd/bhnd_ids.h . +.Ss "Device Matching Functions" +The bhnd device matching functions are used to match against core, chip, and +board-level device attributes. +Match requirements are specified using the +.Vt "struct bhnd_board_match" , +.Vt "struct bhnd_chip_match" , +.Vt "struct bhnd_core_match" , +.Vt "struct bhnd_device_match" , +and +.Vt "struct bhnd_hwrev_match" +match descriptor structures. +.Pp +The +.Fn bhnd_board_matches +function returns +.Dv true +if +.Fa board +matches the board match descriptor +.Fa desc . +Otherwise, it returns +.Dv false . +.Pp +The +.Fn bhnd_chip_matches +function returns +.Dv true +if +.Fa chip +matches the chip match descriptor +.Fa desc . +Otherwise, it returns +.Dv false . +.Pp +The +.Fn bhnd_core_matches +function returns +.Dv true +if +.Fa core +matches the core match descriptor +.Fa desc . +Otherwise, it returns +.Dv false . +.Pp +The +.Fn bhnd_device_matches +function returns +.Dv true +if the device +.Fa dev +matches the device match descriptor +.Fa desc . +Otherwise, it returns +.Dv false . +.Pp +The +.Fn bhnd_hwrev_matches +function returns +.Dv true +if +.Fa hwrev +matches the hwrev match descriptor +.Fa desc . +Otherwise, it returns +.Dv false . +.Pp +The +.Fn bhnd_bus_match_child +function returns the first child device of +.Fa bus +that matches the device match descriptor +.Fa desc . +If no matching child is found, +.Dv NULL +is returned. +.Pp +The +.Fn bhnd_core_get_match_desc +function returns an equality match descriptor for the core info in +.Fa core . +The returned descriptor will match only on core attributes identical to those +defined by +.Fa core . +.Pp +The +.Fn bhnd_cores_equal +function is a convenience wrapper for +.Fn bhnd_core_matches +and +.Fn bhnd_core_get_match_desc . +This function returns +.Dv true +if the +.Vt bhnd_core_info +structures +.Fa lhs +and +.Fa rhs +are equal. +Otherwise, it returns +.Dv false . +.Pp +The +.Fn bhnd_match_core +function returns a pointer to the first entry in the array +.Fa cores +of length +.Fa num_cores +that matches +.Fa desc . +If no matching core is found, +.Dv NULL +is returned. +.Pp +A +.Vt bhnd_board_match +match descriptor may be initialized using one or more of the following macros: +.Bl -tag -width "Fn BHND_MATCH_BOARD_VENDOR vendor" -offset indent +.It Fn BHND_MATCH_BOARD_VENDOR "vendor" +Match on boards with a vendor equal to +.Fa vendor . +.It Fn BHND_MATCH_BOARD_TYPE "type" +Match on boards with a type equal to +.Dv "BHND_BOARD_ ##" +.Fa type +.It Fn BHND_MATCH_SROMREV "sromrev" +Match on boards with a sromrev that matches +.Dv "BHND_HWREV_ ##" +.Fa sromrev . +.It Fn BHND_MATCH_BOARD_REV "hwrev" +Match on boards with hardware revisions that match +.Dv "BHND_ ##" +.Fa hwrev . +.It Fn BHND_MATCH_BOARD "vendor" "type" +A convenience wrapper for +.Fn BHND_MATCH_BOARD_VENDOR +and +.Fn BHND_MATCH_BOARD_TYPE . +.El +.Pp +For example: +.Bd -literal -offset indent +struct bhnd_board_match board_desc = { + BHND_MATCH_BOARD_VENDOR(BHND_MFGID_BROADCOM), + BHND_MATCH_BOARD_TYPE(BCM94360X52C), + BHND_MATCH_BOARD_REV(HWREV_ANY), + BHND_MATCH_SROMREV(RANGE(0, 10)) +}; +.Ed +.Pp +A +.Vt bhnd_chip_match +match descriptor may be initialized using one or more of the following macros: +.Bl -tag -width "Fn BHND_MATCH_CHIP_IPR id pkg hwrev" -offset indent +.It Fn BHND_MATCH_CHIP_ID "id" +Match on chips with an ID equal to +.Dv "BHND_CHIPID_ ##" +.Fa id +.It Fn BHND_MATCH_CHIP_REV "hwrev" +Match on chips with hardware revisions that match +.Dv "BHND_ ##" +.Fa hwrev . +.It Fn BHND_MATCH_CHIP_PKG "pkg" +Match on chips with a package ID equal to +.Dv "BHND_PKGID_ ##" +.Fa pkg +.It Fn BHND_MATCH_CHIP_TYPE "type" +Match on chips with a chip type equal to +.Dv "BHND_CHIPTYPE_ ##" +.Fa type +.It Fn BHND_MATCH_CHIP_IP "id" "pkg" +A convenience wrapper for +.Fn BHND_MATCH_CHIP_ID +and +.Fn BHND_MATCH_CHIP_PKG . +.It Fn BHND_MATCH_CHIP_IPR "id" "pkg" "hwrev" +A convenience wrapper for +.Fn BHND_MATCH_CHIP_ID , +.Fn BHND_MATCH_CHIP_PKG , +and +.Fn BHND_MATCH_CHIP_REV . +.It Fn BHND_MATCH_CHIP_IR "id" "hwrev" +A convenience wrapper for +.Fn BHND_MATCH_CHIP_ID +and +.Fn BHND_MATCH_CHIP_REV . +.El +.Pp +For example: +.Bd -literal -offset indent +struct bhnd_chip_match chip_desc = { + BHND_MATCH_CHIP_IP(BCM4329, BCM4329_289PIN), + BHND_MATCH_CHIP_TYPE(SIBA) +}; +.Ed +.Pp +A +.Vt bhnd_core_match +match descriptor may be initialized using one or more of the following macros: +.Bl -tag -width "Fn BHND_MATCH_CORE_VENDOR vendor" -offset indent +.It Fn BHND_MATCH_CORE_VENDOR "vendor" +Match on cores with a vendor ID equal to +.Fa vendor +.It Fn BHND_MATCH_CORE_ID "id" +Match on cores with a device ID equal to +.Fa id +.It Fn BHND_MATCH_CORE_REV "hwrev" +Match on cores with hardware revisions that match +.Dv "BHND_ ##" +.Fa hwrev . +.It Fn BHND_MATCH_CORE_CLASS "class" +Match on cores with a core device class equal to +.Fa class +.It Fn BHND_MATCH_CORE_IDX "idx" +Match on cores with a core index equal to +.Fa idx +.It Fn BHND_MATCH_CORE_UNIT "unit" +Match on cores with a core unit equal to +.Fa unit +.It Fn BHND_MATCH_CORE "vendor" "id" +A convenience wrapper for +.Fn BHND_MATCH_CORE_VENDOR +and +.Fn BHND_MATCH_CORE_ID . +.El +.Pp +For example: +.Bd -literal -offset indent +struct bhnd_core_match core_desc = { + BHND_MATCH_CORE(BHND_MFGID_BROADCOM, BHND_COREID_CC), + BHND_MATCH_CORE_REV(HWREV_RANGE(0, 10)) +}; +.Ed +.Pp +The +.Vt bhnd_device_match +match descriptor supports matching on all board, chip, and core attributes, +and may be initialized using any of the +.Vt bhnd_board_match , +.Vt bhnd_chip_match , +or +.Vt bhnd_core_match +macros. +.Pp +For example: +.Bd -literal -offset indent +struct bhnd_device_match device_desc = { + BHND_MATCH_CHIP_IP(BCM4329, BCM4329_289PIN), + BHND_MATCH_BOARD_VENDOR(BHND_MFGID_BROADCOM), + BHND_MATCH_BOARD_TYPE(BCM94329AGB), + BHND_MATCH_CORE(BHND_MFGID_BROADCOM, BHND_COREID_CC), +}; +.Ed +.Pp +A +.Vt bhnd_hwrev_match +match descriptor may be initialized using one of the following macros: +.Pp +.Bl -tag -width "Fn BHND_HWREV_RANGE start end" -offset indent -compact +.It Dv BHND_HWREV_ANY +Matches any hardware revision. +.It Fn BHND_HWREV_EQ "hwrev" +Matches any hardware revision equal to +.Fa hwrev +.It Fn BHND_HWREV_GTE "hwrev" +Matches any hardware revision greater than or equal to +.Fa hwrev +.It Fn BHND_HWREV_LTE "hwrev" +Matches any hardware revision less than or equal to +.Fa hwrev +.It Fn BHND_HWREV_RANGE "start" "end" +Matches any hardware revision within an inclusive range. +If +.Dv BHND_HWREV_INVALID +is specified as the +.Fa end +value, will match on any revision equal to or greater than +.Fa start +.El +.\" +.Ss "Device Table Functions" +The bhnd device table functions are used to query device and +quirk tables. +.Pp +The +.Fn bhnd_device_lookup +function returns a pointer to the first entry in device table +.Fa table +that matches the device +.Fa dev . +The table entry size is specified by +.Fa entry_size . +.Pp +The +.Fn bhnd_device_quirks +function scan the device table +.Fa table +for all quirk entries that match the device +.Fa dev , +returning the bitwise OR of all matching quirk flags. +The table entry size is specified by +.Fa entry_size . +.Pp +The +.Vt bhnd_device +structure contains the following fields: +.Bl -tag -width "quirks_table" -offset indent -compact +.It Fa core +A +.Vt bhnd_device_match +descriptor. +.It Fa desc +A verbose device description suitable for use with +.Xr device_set_desc 9 , +or +.Dv NULL . +.It Fa quirks_table +The quirks table for this device, or +.Dv NULL . +.It Fa device_flags +The device flags required when matching this entry. +.El +.Pp +The following device flags are supported: +.Bl -tag -width ".Dv BHND_DF_ADAPTER" -offset indent -compact +.It Dv BHND_DF_ANY +Match on any device. +.It Dv BHND_DF_HOSTB +Match only if the device is the +.Xr bhndb 4 +host bridge. +Implies +.Dv BHND_DF_ADAPTER . +.It Dv BHND_DF_SOC +Match only if the device is attached to a native SoC backplane. +.It Dv BHND_DF_ADAPTER +Match only if the device is attached to a +.Xr bhndb 4 +bridged backplane. +.El +.Pp +A +.Vt bhnd_device +table entry may be initialized using one of the following macros: +.Bl -ohang -offset indent +.It Fn BHND_DEVICE "vendor" "device" "desc" "quirks" "flags" +Match on devices with a vendor ID equal to +.Dv BHND_MFGID_ ## +.Fa vendor +and a core device ID equal to +.Dv BHND_COREID_ ## +.Fa device . +.Pp +The device's verbose description is specified by the +.Fa desc +argument, a pointer to the device-specific quirks table is specified by the +.Fa quirks +argument, and any required device flags may be provided in +.Fa flags . +The optional +.Fa flags +argument defaults to +.Dv BHND_DF_ANY +if omitted. +.It Dv BHND_DEVICE_END +Terminate the +.Vt bhnd_device +table. +.El +.Pp +For example: +.Bd -literal -offset indent +struct bhnd_device bhnd_usb11_devices[] = { + BHND_DEVICE(BCM, USB, "Broadcom USB1.1 Controller", + bhnd_usb11_quirks), + BHND_DEVICE_END +}; +.Ed +.Pp +The +.Vt bhnd_device_quirk +structure contains the following fields: +.Bl -tag -width "quirks_table" -offset indent -compact +.It Fa desc +A +.Vt bhnd_device_match +descriptor. +.It Fa quirks +Applicable quirk flags. +.El +.Pp +A bhnd_device_quirk table entry may be initialized using one of the following +convenience macros: +.Bl -tag -width "Fn BHND_CHIP_QUIRK chip hwrev flags" -offset indent +.It Fn BHND_BOARD_QUIRK "board" "flags" +Set quirk flags +.Fa flags +on devices with a board type equal to +.Dv BHND_BOARD_ ## +.Fa board . +.It Fn BHND_CHIP_QUIRK "chip" "hwrev" "flags" +Set quirk flags +.Fa flags +on devices with a chip ID equal to +.Dv BHND_CHIPID_BCM ## +.Fa chip +and chip hardware revision that matches +.Dv BHND_ ## +.Fa hwrev . +.It Fn BHND_PKG_QUIRK "chip" "pkg" flags" +Set quirk flags +.Fa flags +on devices with a chip ID equal to +.Dv BHND_CHIPID_BCM ## +.Fa chip +and chip package equal to +.Dv BHND_ ## chip ## +.Fa pkg . +.It Fn BHND_CORE_QUIRK "hwrev" flags" +Set quirk flags +.Fa flags +on devices with a core hardware revision that matches +.Dv BHND_ ## +.Fa hwrev . +.El +For example: +.Bd -literal -offset indent +struct bhnd_device_quirk bhnd_usb11_quirks[] = { + BHND_DEVICE(BCM, USB, "Broadcom USB1.1 Controller", + bhnd_usb11_quirks), + BHND_DEVICE_END +}; +.Ed +.Ss "DMA Address Translation Functions" +The +.Fn bhnd_get_dma_translation +function is used to request a DMA address translation descriptor suitable +for use with a maximum DMA address width of +.Fa width , +with support for the requested translation +.Fa flags . +.Pp +If a suitable DMA address translation descriptor is found, it will be stored in +.Fa translation , +and a bus DMA tag specifying the DMA translation's address restrictions will +be stored in +.Fa dmat . +The +.Fa translation +and +.Fa dmat +arguments may be +.Dv NULL +if the translation descriptor or DMA tag are not desired. +.Pp +The following DMA translation flags are supported: +.Bl -ohang -width ".Dv BHND_DMA_TRANSLATION_BYTESWAPPED" -offset indent +.It Dv BHND_DMA_TRANSLATION_PHYSMAP +The translation remaps the device's physical address space. +.Pp +This is used in conjunction with +.Dv BHND_DMA_TRANSLATION_BYTESWAPPED +to define a DMA translation that provides byteswapped access to physical memory +on big-endian MIPS SoCs. +.It Dv BHND_DMA_TRANSLATION_BYTESWAPPED +The translation provides a byte-swapped mapping; write requests will be +byte-swapped before being written to memory, and read requests will be +byte-swapped before being returned. +.Pp +This is primarily used to perform efficient byte swapping of DMA data on +embedded MIPS SoCs executing in big-endian mode. +.El +.Pp +The following symbolic constants are defined for common DMA address widths: +.Pp +.Bl -tag -width ".Dv BHND_DMA_ADDR_64BIT" -offset indent -compact +.It Dv BHND_DMA_ADDR_30BIT +30-bit DMA +.It Dv BHND_DMA_ADDR_32BIT +32-bit DMA +.It Dv BHND_DMA_ADDR_64BIT +64-bit DMA +.El +.Pp +The +.Vt bhnd_dma_translation +structure contains the following fields: +.Bl -tag -width "addrext_mask" +.It Fa base_addr +Host-to-device physical address translation. +This may be added to a host physical address to produce a device DMA address. +.It Fa addr_mask +Device-addressable address mask. +This defines the device DMA address range, and excludes any bits reserved for +mapping the address within the translation window at +.Fa base_addr . +.It Fa addrext_mask +Device-addressable extended address mask. +If a the per-core BHND DMA engine supports the 'addrext' control field, it can +be used to provide address bits excluded by +.Fa addr_mask . +.Pp +Support for DMA extended address changes \(em including coordination with the +core providing device-to-host DMA address translation \(em is handled +transparently by the DMA engine. +.Pp +For example, on PCI Wi-Fi devices, the Wi-Fi core's DMA engine will (in effect) +update the PCI host bridge core's DMA +.Dv sbtopcitranslation +base address to map the target address prior to performing a DMA transaction. +.It Fa flags +Translation flags. +.El +.\" +.Ss "Interrupt Functions" +The +.Fn bhnd_get_intr_count +function is used to determine the number of backplane interrupt lines assigned +to the device +.Fa dev . +Interrupt line identifiers are allocated in monotonically increasing order, +starting with 0. +.Pp +The +.Fn bhnd_get_intr_ivec +function is used to determine the backplane interrupt vector assigned to +interrupt line +.Fa intr +on the device +.Fa dev , +writing the result to +.Fa ivec . +Interrupt vector assignments are backplane-specific: On BCMA devices, this +function returns the OOB bus line assigned to the interrupt. +On SIBA devices, it returns the target OCP slave flag number assigned to the +interrupt. +.Pp +The +.Fn bhnd_map_intr +function is used to map interrupt line +.Fa intr +assigned to device +.Fa dev +to an IRQ number, writing the result to +.Fa irq . +Until unmapped, this IRQ may be used when allocating a resource of type +SYS_RES_IRQ. +.Pp +Ownership of the interrupt mapping is assumed by the caller, and must be +explicitly released using +.Fa bhnd_unmap_intr . +.Pp +The +.Fn bhnd_unmap_intr +function is used to unmap bus IRQ +.Fa irq +previously mapped using +.Fn bhnd_map_intr +by the device +.Fa dev . +.\" +.Ss "NVRAM Functions" +The +.Fn bhnd_nvram_getvar +function is used to read the value of NVRAM variable +.Fa name +from the NVRAM provider(s) registered with the parent +.Xr bhnd 4 +bus of device +.Fa dev , +coerced to the desired data representation +.Fa type , +written to the buffer specified by +.Fa buf . +.Pp +Before the call, the maximum capacity of +.Fa buf +is specified by +.Fa len . +After a successful call \(em or if +.Er ENOMEM +is returned \(em the size of the available data will be written to +.Fa len . +The size of the desired data representation can be determined by calling +.Fn bhnd_nvram_getvar +with a +.Dv NULL +argument for +.Fa buf . +.Pp +The following NVRAM data types are supported: +.Pp +.Bl -tag -width ".Dv BHND_NVRAM_TYPE_UINT64_ARRAY" -offset indent -compact +.It Dv BHND_NVRAM_TYPE_UINT8 +unsigned 8-bit integer +.It Dv BHND_NVRAM_TYPE_UINT16 +unsigned 16-bit integer +.It Dv BHND_NVRAM_TYPE_UINT32 +unsigned 32-bit integer +.It Dv BHND_NVRAM_TYPE_UINT64 +signed 64-bit integer +.It Dv BHND_NVRAM_TYPE_INT8 +signed 8-bit integer +.It Dv BHND_NVRAM_TYPE_INT16 +signed 16-bit integer +.It Dv BHND_NVRAM_TYPE_INT32 +signed 32-bit integer +.It Dv BHND_NVRAM_TYPE_INT64 +signed 64-bit integer +.It Dv BHND_NVRAM_TYPE_CHAR +UTF-8 character +.It Dv BHND_NVRAM_TYPE_STRING +UTF-8 NUL-terminated string +.It Dv BHND_NVRAM_TYPE_BOOL +uint8 boolean value +.It Dv BHND_NVRAM_TYPE_NULL +NULL (empty) value +.It Dv BHND_NVRAM_TYPE_DATA +opaque octet string +.It Dv BHND_NVRAM_TYPE_UINT8_ARRAY +array of uint8 integers +.It Dv BHND_NVRAM_TYPE_UINT16_ARRAY +array of uint16 integers +.It Dv BHND_NVRAM_TYPE_UINT32_ARRAY +array of uint32 integers +.It Dv BHND_NVRAM_TYPE_UINT64_ARRAY +array of uint64 integers +.It Dv BHND_NVRAM_TYPE_INT8_ARRAY +array of int8 integers +.It Dv BHND_NVRAM_TYPE_INT16_ARRAY +array of int16 integers +.It Dv BHND_NVRAM_TYPE_INT32_ARRAY +array of int32 integers +.It Dv BHND_NVRAM_TYPE_INT64_ARRAY +array of int64 integers +.It Dv BHND_NVRAM_TYPE_CHAR_ARRAY +array of UTF-8 characters +.It Dv BHND_NVRAM_TYPE_STRING_ARRAY +array of UTF-8 NUL-terminated strings +.It Dv BHND_NVRAM_TYPE_BOOL_ARRAY +array of uint8 boolean values +.El +.Pp +The +.Fn bhnd_nvram_getvar_array , +.Fn bhnd_nvram_getvar_int , +.Fn bhnd_nvram_getvar_int8 , +.Fn bhnd_nvram_getvar_int16 , +.Fn bhnd_nvram_getvar_int32 , +.Fn bhnd_nvram_getvar_uint , +.Fn bhnd_nvram_getvar_uint8 , +.Fn bhnd_nvram_getvar_uint16 , +.Fn bhnd_nvram_getvar_uint32 , +and +.Fn bhnd_nvram_getvar_str +functions are convenience wrappers for +.Fn bhnd_nvram_getvar . +.Pp +The +.Fn bhnd_nvram_getvar_array +function returns either a value of exactly +.Fa size +in +.Fa buf , +or returns an error code of +.Er ENXIO +if the data representation is not exactly +.Fa size +in length. +.Pp +The +.Fn bhnd_nvram_getvar_int +and +.Fn bhnd_nvram_getvar_uint +functions return the value of NVRAM variable +.Fa name , +coerced to a signed or unsigned integer +type of +.Fa width +(1, 2, or 4 bytes). +.Pp +The +.Fn bhnd_nvram_getvar_int8 , +.Fn bhnd_nvram_getvar_int16 , +.Fn bhnd_nvram_getvar_int32 , +.Fn bhnd_nvram_getvar_uint , +.Fn bhnd_nvram_getvar_uint8 , +.Fn bhnd_nvram_getvar_uint16 , +and +.Fn bhnd_nvram_getvar_uint32 +functions return the value of NVRAM variable +.Fa name , +coerced to a signed or unsigned 8, 16, or 32-bit integer type. +.Pp +The +.Fn bhnd_nvram_getvar_str +functions return the value of NVRAM variable +.Fa name , +coerced to a NUL-terminated string. +.Pp +The +.Fn bhnd_nvram_string_array_next +function iterates over all strings in the +.Fa inp +.Dv BHND_NVRAM_TYPE_STRING_ARRAY +value. +The size of +.Fa inp , +including any terminating NUL character(s), is specified using the +.Fa ilen +argument. +The +.Fa prev +argument should be either a string pointer previously returned by +.Fn bhnd_nvram_string_array_next , +or +.Dv NULL +to begin iteration. +If +.Fa prev is not +.Dv NULL , +the +.Fa olen +argument must be a pointer to the length previously returned by +.Fn bhnd_nvram_string_array_next . +On success, the next string element's length will be written to this pointer. +.\" +.Ss "Port/Region Functions" +Per-device interconnect memory mappings are identified by a combination of +.Em port type , +.Em port number , +and +.Em region number . +Port and memory region identifiers are allocated in monotonically increasing +order for each +.Em port type , +starting with 0. +.Pp +The following port types are supported: +.Bl -tag -width ".Dv BHND_PORT_DEVICE" -offset indent +.It Dv BHND_PORT_DEVICE +Device memory. +The device's control/status registers are always mapped by the first device port +and region, and will be assigned a +.Dv SYS_RES_MEMORY +resource ID of 0. +.It Dv BHND_PORT_BRIDGE +Bridge memory. +.It Dv BHND_PORT_AGENT +Interconnect agent/wrapper. +.El +.Pp +The +.Fn bhnd_decode_port_rid +function is used to decode the resource ID +.Fa rid +assigned to device +.Fa dev , +of resource type +.Fa type , +writing the port type to +.Fa port_type , +port number to +.Fa port , +and region number +to +.Fa region . +.Pp +The +.Fn bhnd_get_port_count +function returns the number of ports of type +.Fa type +assigned to device +.Fa dev . +.Pp +The +.Fn bhnd_get_port_rid +function returns the resource ID for the +.Dv SYS_RES_MEMORY +resource mapping the +.Fa port +of +.Fa type +and +.Fa region +on device +.Fa dev , +or -1 if the port or region are invalid, or do not have an assigned resource ID. +.Pp +The +.Fn bhnd_get_region_addr +function is used to determine the base address and size of the memory +.Fa region +on +.Fa port +of +.Fa type +assigned to +.Fa dev . +The region's base device address will be written to +.Fa region_addr , +and the region size to +.Fa region_size . +.Pp +The +.Fn bhnd_get_region_count +function returns the number of memory regions mapped to +.Fa port +of +.Fa type +on device +.Fa dev . +.Pp +The +.Fn bhnd_is_region_valid +function returns +.Dv true +if +.Fa region +is a valid region mapped by +.Fa port +of +.Fa type +on device +.Fa dev . +.\" +.Ss "Power Management Functions" +Drivers must ask the parent +.Xr bhnd 4 +bus to allocate device PMU state using +.Fn bhnd_alloc_pmu +before calling any another bhnd PMU functions. +.Pp +The +.Fn bhnd_alloc_pmu +function is used to allocate per-device PMU state and enable PMU request +handling for device +.Fa dev . +The memory region containing the device's PMU register block must be allocated +using +.Xr bus_alloc_resource 9 +or +.Fn bhnd_alloc_resource +before calling +.Fn bhnd_alloc_pmu , +and must not be released until after calling +.Fn bhnd_release_pmu . +.Pp +On all supported BHND hardware, the PMU register block is mapped by the device's +control/status registers in the first device port and region. +.Pp +The +.Fn bhnd_release_pmu +function releases the per-device PMU state previously allocated for device +.Fa dev +using +.Fn bhnd_alloc_pmu . +Any outstanding clock and external resource requests will be discarded upon +release of the device PMU state. +.Pp +The +.Fn bhnd_enable_clocks +function is used to request that +.Fa clocks +be powered up and routed to the backplane on behalf of device +.Fa dev . +This will power any clock sources required (e.g., XTAL, PLL, etc) and wait until +the requested clocks are stable. +If the request succeeds, any previous clock requests issued by +.Fa dev +will be discarded. +.Pp +The following clocks are supported, and may be combined using bitwise OR to +request multiple clocks: +.Bl -tag -width ".Dv BHND_CLOCK_DYN" -offset indent +.It BHND_CLOCK_DYN +Dynamically select an appropriate clock source based on all outstanding clock +requests by any device attached to the parent +.Xr bhnd 4 +bus. +.It BHND_CLOCK_ILP +Idle Low-Power (ILP) Clock. +May be used if no register access is required, or long request latency is +acceptable. +.It BHND_CLOCK_ALP +Active Low-Power (ALP) Clock. +Supports low-latency register access and low-rate DMA. +.It BHND_CLOCK_HT +High Throughput (HT) Clock. +Supports high bus throughput and lowest-latency register access. +.El +.Pp +The +.Fn bhnd_request_clock +function is used to request that +.Fa clock +(or faster) be powered up and routed to device +.Fa dev . +.Pp +The +.Fn bhnd_get_clock_freq +function is used to request the current clock frequency of +.Fa clock , +writing the frequency in Hz to +.Fa freq . +.Pp +The +.Fn bhnd_get_clock_latency +function is used to determine the transition latency required for +.Fa clock , +writing the latency in microseconds to +.Fa latency . +The +.Dv BHND_CLOCK_HT +latency value is suitable for use as the D11 Wi-Fi core +.Em fastpwrup_dly +value. +.Pp +The +.Fn bhnd_request_ext_rsrc +function is used to request that the external PMU-managed resource assigned to +device +.Fa dev , +identified by device-specific identifier +.Fa rsrc , +be powered up. +.Pp +The +.Fn bhnd_release_ext_rsrc +function releases any outstanding requests by device +.Fa dev +for the PMU-managed resource identified by device-specific identifier +.Fa rsrc . +If an external resource is shared by multiple devices, it will not be powered +down until all device requests are released. +.\" +.Ss "Service Provider Functions" +The +.Fn bhnd_register_provider +function is used to register device +.Fa dev +as a provider for platform +.Fa service +with the parent +.Xr bhnd 4 +bus. +.Pp +The following service types are supported: +.Bl -tag -width ".Dv BHND_SERVICE_INVALID" -offset indent +.It Dv BHND_SERVICE_CHIPC +ChipCommon service. +The providing device must implement the bhnd_chipc interface. +.It Dv BHND_SERVICE_PWRCTL +Legacy PWRCTL service. +The providing device must implement the bhnd_pwrctl interface. +.It Dv BHND_SERVICE_PMU +PMU service. +The providing device must implement the bhnd_pmu interface. +.It Dv BHND_SERVICE_NVRAM +NVRAM service. +The providing device must implement the bhnd_nvram interface. +.It Dv BHND_SERVICE_GPIO +GPIO service. +The providing device must implement the standard +.Xr gpio 4 +interface. +.It Dv BHND_SERVICE_ANY +Matches on any service type. +May be used with +.Fn bhnd_deregister_provider +to remove all service provider registrations for a device. +.El +.Pp +The +.Fn bhnd_deregister_provider +function attempts to remove provider registration for the device +.Fa dev +and +.Fa service . +If a +.Fa service +argument of +.Dv BHND_SERVICE_ANY +is specified, this function will attempt to remove +.Em all service provider registrations for +.Fa dev . +.Pp +The +.Fn bhnd_retain_provider +function retains and returns a reference to the provider registered for +.Fa service +with the parent +.Xr bhnd 4 +bus of device +.Fa dev , +if available. +On success, the caller is responsible for releasing this provider reference +using +.Fn bhnd_release_provider . +The service provider is guaranteed to remain available until the provider +reference is released. +.Pp +The +.Fn bhnd_release_provider +function releases a reference to a +.Fa provider +for +.Fa service , +previously retained by device +.Fa dev +using +.Fn bhnd_retain_provider . +.\" +.Ss "Utility Functions" +The +.Fn bhnd_driver_get_erom_class +function returns the +.Xr bhnd_erom 9 +class for the device enumeration table format used by +.Xr bhnd 4 +bus driver instance +.Fa driver . +If the driver does not support +.Xr bhnd_erom 9 +device enumeration, +.Dv NULL +is returned. +.Pp +The +.Fn bhnd_find_core_class +function looks up the BHND class, if known, for the BHND vendor ID +.Fa vendor +and device ID +.Fa device . +.Pp +The +.Fn bhnd_find_core_name +function is used to fetch the human-readable name, if known, for the BHND core +with a vendor ID of +.Fa vendor +and device ID of +.Fa device . +.Pp +The +.Fn bhnd_core_class +and +.Fn bhnd_core_name +functions are convenience wrappers for +.Fn bhnd_find_core_class +and +.Fn bhnd_find_core_name , +that use the +.Fa vendor +and +.Fa device +fields of the core info structure +.Fa ci . +.Pp +The +.Fn bhnd_format_chip_id +function writes a NUL-terminated human-readable representation of the BHND +.Fa chip_id +value to the specified +.Fa buffer +with a capacity of +.Fa size . +No more than +.Fa size-1 +characters will be written, with the +.Fa size'th +character set to '\\0'. +A buffer size of +.Dv BHND_CHIPID_MAX_NAMELEN +is sufficient for any string representation produced using +.Fn bhnd_format_chip_id . +.Pp +The +.Fn bhnd_set_custom_core_desc +function uses the +.Xr bhnd 4 +device identification of +.Fa dev , +overriding the core name with the specified +.Fa dev_name , +to populate the device's verbose description using +.Xr device_set_desc 9 . +.Pp +The +.Fn bhnd_set_default_core_desc +function uses the +.Xr bhnd 4 +device identification of +.Fa dev +to populate the device's verbose description using +.Xr device_set_desc 9 . +.Pp +The +.Fn bhnd_vendor_name +function returns the human-readable name for the JEP-106, ARM 4-bit +continuation encoded manufacturer ID +.Fa vendor , +if known. +.\" +.Sh RETURN VALUES +.Ss Bus Resource Functions +The +.Fn bhnd_activate_resource , +.Fn bhnd_alloc_resources , +.Fn bhnd_deactivate_resource , +and +.Fn bhnd_release_resource +functions return 0 on success, otherwise an appropriate error code is returned. +.Pp +The +.Fn bhnd_alloc_resource +and +.Fn bhnd_alloc_resource_any +functions return a pointer to +.Vt "struct resource" +on success, a null pointer otherwise. +.\" +.Ss "Device Configuration Functions" +The +.Fn bhnd_read_config +and +.Fn bhnd_write_config +functions return 0 on success, or one of the following values on error: +.Bl -tag -width Er +.It Bq Er EINVAL +The device is not a direct child of the +.Xr bhnd 4 +bus +.It Bq Er EINVAL +The requested width is not one of 1, 2, or 4 bytes. +.It Bq Er ENODEV +Accessing agent/config space for the device is unsupported. +.It Bq Er EFAULT +The requested offset or width exceeds the bounds of the mapped agent/config +space. +.El +.Pp +The +.Fn bhnd_read_ioctl , +.Fn bhnd_write_ioctl , +.Fn bhnd_read_iost , +.Fn bhnd_reset_hw , +and +.Fn bhnd_suspend_hw +functions return 0 on success, otherwise an appropriate error code is returned. +.\" +.Ss "Device Information Functions" +The +.Fn bhnd_read_board_info +function returns 0 on success, otherwise an appropriate error code is returned. +.\" +.Ss "DMA Address Translation Functions" +The +.Fn bhnd_get_dma_translation +function returns 0 on success, or one of the following values on error: +.Bl -tag -width Er +.It Bq Er ENODEV +DMA is not supported. +.It Bq Er ENOENT +No DMA translation matching the requested address width and translation flags +is available. +.El +.Pp +If fetching the requested DMA address translation otherwise fails, an +appropriate error code will be returned. +.\" +.Ss "Interrupt Functions" +The +.Fn bhnd_get_intr_ivec +function returns +0 on success, or +.Er ENXIO +if the requested interrupt line exceeds the number of interrupt lines assigned +to the device. +.Pp +The +.Fn bhnd_map_intr +function returns 0 on success, otherwise an appropriate error code is returned. +.\" +.Ss "NVRAM Functions" +The +.Fn bhnd_nvram_getvar , +.Fn bhnd_nvram_getvar_array , +.Fn bhnd_nvram_getvar_int , +.Fn bhnd_nvram_getvar_int8 , +.Fn bhnd_nvram_getvar_int16 , +.Fn bhnd_nvram_getvar_int32 , +.Fn bhnd_nvram_getvar_uint , +.Fn bhnd_nvram_getvar_uint8 , +.Fn bhnd_nvram_getvar_uint16 , +and +.Fn bhnd_nvram_getvar_uint32 +functions return 0 on success, or one of the following values on error: +.Bl -tag -width Er +.It Bq Er ENODEV +If an NVRAM provider has not been registered with the bus. +.It Bq Er ENOENT +The requested variable was not found. +.It Bq Er ENOMEM +If the buffer of size is too small to hold the requested value. +.It Bq Er EOPNOTSUPP +If the value's native type is incompatible with and cannot be coerced to the +requested type. +.It Bq Er ERANGE +If value coercion would overflow (or underflow) the requested type +.El +.Pp +If reading the variable otherwise fails, an appropriate error code will be +returned. +.\" +.Ss "Port/Region Functions" +The +.Fn bhnd_decode_port_rid +function returns +0 on success, or an appropriate error code if no matching port/region is found. +.Pp +The +.Fn bhnd_get_port_rid +function returns the resource ID for the requested port and region, +or -1 if the port or region are invalid, or do not have an assigned resource ID. +.Pp +The +.Fn bhnd_get_region_addr +function returns +0 on success, or an appropriate error code if no matching port/region is found. +.\" +.Ss "PMU Functions" +The +.Fn bhnd_alloc_pmu +function returns 0 on success, otherwise an appropriate error code is returned. +.Pp +The +.Fn bhnd_release_pmu +function returns 0 on success, otherwise an appropriate error code is returned, +and the core state will be left unmodified. +.Pp +The +.Fn bhnd_enable_clocks +and +.Fn bhnd_request_clock +functions return 0 on success, or one of the following values on error: +.Bl -tag -width Er +.It Bq Er ENODEV +An unsupported clock was requested. +.It Bq Er ENXIO +No PMU or PWRCTL provider has been registered with the bus. +.El +.Pp +The +.Fn bhnd_get_clock_freq +function returns 0 on success, or +.Er ENODEV +if the frequency for the specified clock is not available. +.Pp +The +.Fn bhnd_get_clock_latency +function returns 0 on success, or +.Er ENODEV +if the transition latency for the specified clock is not available. +.Pp +The +.Fn bhnd_request_ext_rsrc +and +.Fn bhnd_release_ext_rsrc +functions return 0 on success, otherwise an appropriate error code is returned. +.\" +.Ss "Service Provider Functions" +The +.Fn bhnd_register_provider +function returns 0 on success, +.Er EEXIST +if an entry for service already exists, or an appropriate error code if +service registration otherwise fails. +.Pp +The +.Fn bhnd_deregister_provider +function returns 0 on success, or +.Er EBUSY +if active references to the service provider exist. +.Pp +The +.Fn bhnd_retain_provider +function returns a pointer to +.Vt "device_t" +on success, a null pointer if the requested provider is not registered. +.\" +.Ss "Utility Functions" +The +.Fn bhnd_format_chip_id +function returns the total number of bytes written on success, or a negative +integer on failure. +.\" +.Sh SEE ALSO +.Xr bhnd 4 , +.Xr bhnd_erom 9 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver programming interface and this manual page were written by +.An Landon Fuller Aq Mt landonf@FreeBSD.org . diff --git a/static/freebsd/man9/bhnd_erom.9 b/static/freebsd/man9/bhnd_erom.9 new file mode 100644 index 00000000..1e8101f0 --- /dev/null +++ b/static/freebsd/man9/bhnd_erom.9 @@ -0,0 +1,483 @@ +.\" Copyright (c) 2015-2016 Landon Fuller +.\" Copyright (c) 2017 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" Portions of this documentation were written by Landon Fuller +.\" under sponsorship from the FreeBSD Foundation. +.\" +.\" 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 November 9, 2017 +.Dt BHND_EROM 9 +.Os +.Sh NAME +.Nm bhnd_erom , +.Nm bhnd_erom_alloc , +.Nm bhnd_erom_dump , +.Nm bhnd_erom_fini_static , +.Nm bhnd_erom_free , +.Nm bhnd_erom_free_core_table , +.Nm bhnd_erom_get_core_table , +.Nm bhnd_erom_init_static , +.Nm bhnd_erom_io , +.Nm bhnd_erom_io_fini , +.Nm bhnd_erom_io_map , +.Nm bhnd_erom_io_read , +.Nm bhnd_erom_iobus_init , +.Nm bhnd_erom_iores_new , +.Nm bhnd_erom_lookup_core , +.Nm bhnd_erom_lookup_core_addr , +.Nm bhnd_erom_probe , +.Nm bhnd_erom_probe_driver_classes +.Nd BHND device enumeration table parsing +.Sh SYNOPSIS +.In dev/bhnd/bhnd.h +.In dev/bhnd/bhnd_erom.h +.\" +.Vt typedef struct bhnd_erom bhnd_erom_t ; +.Vt typedef struct kobj_class bhnd_erom_class_t ; +.Vt typedef struct bhnd_erom_static bhnd_erom_static_t ; +.Ft int +.Fo bhnd_erom_probe +.Fa "bhnd_erom_class_t *cls" +.Fa "struct bhnd_erom_io *eio" +.Fa "const struct bhnd_chipid *hint" +.Fa "struct bhnd_chipid *cid" +.Fc +.Ft bhnd_erom_class_t * +.Fo bhnd_erom_probe_driver_classes +.Fa "devclass_t bus_devclass" +.Fa "struct bhnd_erom_io *eio" +.Fa "const struct bhnd_chipid *hint" +.Fa "struct bhnd_chipid *cid" +.Fc +.Ft bhnd_erom_t * +.Fo bhnd_erom_alloc +.Fa "bhnd_erom_class_t *cls" +.Fa "const struct bhnd_chipid *cid" +.Fa "struct bhnd_erom_io *eio" +.Fc +.Ft void +.Fo bhnd_erom_free +.Fa "bhnd_erom_t *erom" +.Fc +.Ft int +.Fo bhnd_erom_init_static +.Fa "bhnd_erom_class_t *cls" +.Fa "bhnd_erom_t *erom" +.Fa "size_t esize" +.Fa "const struct bhnd_chipid *cid" +.Fa "struct bhnd_erom_io *eio" +.Fc +.Ft void +.Fo bhnd_erom_fini_static +.Fa "bhnd_erom_t *erom" +.Fc +.Ft int +.Fo bhnd_erom_dump +.Fa "bhnd_erom_t *erom" +.Fc +.Ft int +.Fo bhnd_erom_get_core_table +.Fa "bhnd_erom_t *erom" +.Fa "struct bhnd_core_info **cores" +.Fa "u_int *num_cores" +.Fc +.Ft void +.Fo bhnd_erom_free_core_table +.Fa "bhnd_erom_t *erom" +.Fa "struct bhnd_core_info *cores" +.Fc +.Ft int +.Fo bhnd_erom_lookup_core +.Fa "bhnd_erom_t *erom" +.Fa "const struct bhnd_core_match *desc" +.Fa "struct bhnd_core_info *core" +.Fc +.Ft int +.Fo bhnd_erom_lookup_core_addr +.Fa "bhnd_erom_t *erom" +.Fa "const struct bhnd_core_match *desc" +.Fa "bhnd_port_type type" +.Fa "u_int port" +.Fa "u_int region" +.Fa "struct bhnd_core_info *core" +.Fa "bhnd_addr_t *addr" +.Fa "bhnd_size_t *size" +.Fc +.\" +.Ss Bus Space I/O +.Ft struct bhnd_erom_io * +.Fo bhnd_erom_iores_new +.Fa "device_t dev" +.Fa "int rid" +.Fc +.Ft int +.Fo bhnd_erom_iobus_init +.Fa "struct bhnd_erom_iobus *iobus" +.Fa "bhnd_addr_t addr" +.Fa "bhnd_size_t size" +.Fa "bus_space_tag_t bst" +.Fa "bus_space_handle_t bsh" +.Fc +.Ft void +.Fo bhnd_erom_io_fini +.Fa "struct bhnd_erom_io *eio" +.Fc +.Ft int +.Fo bhnd_erom_io_map +.Fa "struct bhnd_erom_io *eio" +.Fa "bhnd_addr_t addr" +.Fa "bhnd_size_t size" +.Fc +.Ft uint32_t +.Fo bhnd_erom_io_read +.Fa "struct bhnd_erom_io *eio" +.Fa "bhnd_size_t offset" +.Fa "u_int width" +.Fc +.In dev/bhnd/bhnd_eromvar.h +.Bd -literal +struct bhnd_erom_io { + bhnd_erom_io_map_t *map; + bhnd_erom_io_read_t *read; + bhnd_erom_io_fini_t *fini; +}; +.Ed +.Ft typedef int +.Fo \*(lpbhnd_erom_io_map_t\*(rp +.Fa "struct bhnd_erom_io *eio" +.Fa "bhnd_addr_t addr" +.Fa "bhnd_size_t size" +.Fc +.Ft typedef uint32_t +.Fo \*(lpbhnd_erom_io_read_t\*(rp +.Fa "struct bhnd_erom_io *eio" +.Fa "bhnd_size_t offset" +.Fa "u_int width" +.Fc +.Ft typedef void +.Fo "\*(lpbhnd_erom_io_fini_t\*(rp +.Fa "struct bhnd_erom_io *eio" +.Fc +.\" +.Sh DESCRIPTION +The +.Nm +framework provides a common parser interface to the BHND device enumeration +table formats supported by +.Xr bhnd 4 +bus drivers. +.Pp +The +.Fn bhnd_erom_probe +function is used to identify a +.Xr bhnd 4 +bus device and determine whether the erom class +.Fa cls +is capable of parsing its device enumeration table. +If successful, the probed chip identification is written to the location +pointed to by +.Fa cid . +.Pp +A pointer to a bus I/O instance mapping the device registers of the first +hardware core must be provided using the +.Fa eio +argument. +The registers can be mapped using +.Fn bhnd_erom_io_map . +.Pp +On devices that do not provide standard +.Xr bhnd_chipc 4 +chip identification registers via the first hardware core, a pointer to chip +information for the device must be specified using the +.Fa hint +argument. +Otherwise, the +.Fa hint +argument should be +.Dv NULL . +.Pp +The +.Fn bhnd_erom_probe_driver_classes +function is a convenience wrapper for +.Fn bhnd_erom_probe . +This function will iterate over all drivers instances in the device class +.Fa bus_devclass , +using +.Xr bhnd_driver_get_erom_class 9 +to fetch each driver's erom class and probe the hardware core mapped by +.Fa eio . +A pointer to the erom class with the highest probe priority is returned on +success. +If there are no successful probe results from the erom classes, +.Dv NULL +is returned. +.Pp +The +.Fn bhnd_erom_alloc +function allocates and returns a new parser instance of the device enumeration +class +.Fa cls +for the chip identified by +.Fa cid , +using the bus I/O instance +.Fa eio +to map and read the device table. +On success, the returned +.Vt bhnd_erom_t +assumes ownership of +.Fa eio . +.Pp +The +.Fn bhnd_erom_free +function releases all resources held by an erom parser successfully allocated +using +.Fn bhnd_erom_alloc . +.Pp +Clients can manage the allocation of memory themselves with +.Fn bhnd_erom_init_static . +This is useful in cases like performing device enumeration before +.Xr malloc 9 +initialization. +.Fn bhnd_erom_init_static +is called with +.Fa erom +set to a pointer to the memory for the instance, and the total available bytes +in +.Fa esize . +.Pp +The +.Vt bhnd_erom_static +structure is large enough to statically allocate any supported parser class +instance state. +Pointers to a +.Vt bhnd_erom_static +structure can be cast to +.Vt bhnd_erom_t . +.Pp +The +.Fn bhnd_erom_fini_static +function releases all resources held by an erom parser successfully +initialized using +.Fn bhnd_erom_init_static . +.Pp +The +.Fn bhnd_erom_dump +function enumerates and prints all device table entries in +.Fa erom . +.Pp +The +.Fn bhnd_erom_get_core_table +function enumerates all device table entries in +.Fa erom , +returning a table of core information structures in +.Fa cores +and the count in +.Fa num_cores . +The memory allocated for the table must be freed using +.Fn bhnd_erom_free_core_table . +.Pp +The +.Fn bhnd_erom_free_core_table +function frees any memory allocated in a previous call to +.Fn bhnd_erom_get_core_table . +.Pp +The +.Fn bhnd_erom_lookup_core +function locates the first device table entry in +.Fa erom +that matches core match descriptor +.Fa desc , +writing the core information of the matching entry to +.Fa core . +.Pp +The +.Fn bhnd_erom_lookup_core_addr +function locates the first device table entry in +.Fa erom +that matches core match descriptor +.Fa desc , +fetching the base address and size of the memory region +.Fa region +mapped to the port +.Fa port +of type +.Fa type . +On success, the core information of the matching entry is written to +.Fa core , +the base address of the port region is written to +.Fa addr , +and the total size of the port region is written to +.Fa size . +If the core information is not desired, set +.Fa core +to +.Dv NULL . +.Ss Bus Space I/O +The +.Vt bhnd_erom_io +structure provides a set of I/O callbacks used by +.Nm +to map and read the device enumeration table. +Clients may either use the existing +.Fn bhnd_erom_iores_new +or +.Fn bhnd_erom_iobus_init +functions to allocate a bus I/O instance, or implement the +.Vt bhnd_erom_io +callbacks directly. +.Pp +The +.Vt bhnd_erom_io +structure contains these required fields: +.Bl -tag -width "read" -offset indent +.It Fa map +A function implementing +.Fn bhnd_erom_io_map . +.It Fa read +A function implementing +.Fn bhnd_erom_io_read . +.It Fa fini +A function implementing +.Fn bhnd_erom_io_fini . +.El +.Pp +The +.Fn bhnd_erom_iores_new +function allocates and returns a new bus I/O instance that will perform mapping +by using +.Xr bhnd_alloc_resource 9 +to allocate +.Dv SYS_RES_MEMORY +bus resources on demand from the device +.Fa dev +using a resource ID of +.Fa rid . +.Pp +The +.Fn bhnd_erom_iobus_init +function initializes a caller-allocated bus I/O instance +.Fa iobus +that will perform bus I/O using the bus space tag +.Fa bst +and handle +.Fa bsh . +The base address and total size mapped by +.Fa bsh +should be specified using the +.Fa addr +and +.Fa size +arguments. +.Pp +The +.Fn bhnd_erom_io_fini +function frees all resources held by the bus I/O instance +.Fa eio . +.Pp +The +.Fn bhnd_erom_io_map +function is used to request that the bus I/O instance +.Fa eio +map +.Xr bhnd 4 +bus space at bus address +.Fa addr +with a mapping of size +.Fa size . +.Pp +The +.Fn bhnd_erom_io_read +function is used to read a data item of +.Fa width +bytes from the bus I/O instance +.Fa eio +at +.Fa offset , +relative to the bus address previously mapped using +.Fn bhnd_erom_io_map . +.Pp +The +.Fa width +must be one of 1, 2, or 4 bytes. +.Sh RETURN VALUES +The +.Fn bhnd_erom_probe +function returns a standard +.Xr DEVICE_PROBE 9 +result. +.Pp +A return value equal to or less than zero indicates success. +Values greater than zero indicates an error, and will be an appropriate error +code. +For values less than or equal to zero, the erom class returning the highest +value should be used to parse the erom table. +.Er ENXIO +is returned if the device is not supported by the parser. +.Pp +The +.Fn bhnd_erom_probe_driver_classes +function returns a pointer to the probed +.Vt bhnd_erom_class_t +instance on success, a null pointer otherwise. +.Pp +The +.Fn bhnd_erom_alloc +function returns a pointer to +.Vt bhnd_erom_t +on success, or +.Dv NULL +if an error occurred allocating or initializing the EROM parser. +.Pp +The +.Fn bhnd_erom_init_static +function returns 0 on success, +.Er ENOMEM +if the allocation size is smaller than required by the erom class, or +an appropriate error code if initialization otherwise fails. +.Pp +The +.Fn bhnd_erom_lookup_core +function returns 0 on success, +.Er ENOENT +if no matching core is found, or an appropriate error code if parsing the device +table otherwise fails. +.Pp +The +.Fn bhnd_erom_dump , +.Fn bhnd_erom_get_core_table , +.Fn bhnd_erom_iobus_init , +.Fn bhnd_erom_io_map , +functions return 0 on success, otherwise an appropriate error code is returned. +.Sh SEE ALSO +.Xr bhnd 4 , +.Xr bhnd 9 , +.Xr bhnd_alloc_resource 9 , +.Xr bhnd_driver_get_erom_class 9 , +.Xr bus_space 9 +.Sh AUTHORS +.An -nosplit +The +.Nm +framework and this manual page were written by +.An Landon Fuller Aq Mt landonf@FreeBSD.org . diff --git a/static/freebsd/man9/bios.9 b/static/freebsd/man9/bios.9 new file mode 100644 index 00000000..4bea48a1 --- /dev/null +++ b/static/freebsd/man9/bios.9 @@ -0,0 +1,179 @@ +.\" +.\" Copyright (c) 1997 Michael Smith +.\" 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 ``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 August 9, 2005 +.Dt BIOS 9 +.Os +.Sh NAME +.Nm bios_sigsearch , +.Nm bios32_SDlookup , +.Nm bios32 , +.Nm bios_oem_strings +.Nd interact with PC BIOS +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.In machine/pc/bios.h +.Ft uint32_t +.Fn bios_sigsearch "uint32_t start" "u_char *sig" "int siglen" "int paralen" "int sigofs" +.Ft int +.Fn bios32_SDlookup "struct bios32_SDentry *ent" +.Ft int +.Fn bios32 "struct bios_regs *br" "u_int offset" "u_short segment" +.Fn BIOS_PADDRTOVADDR "addr" +.Fn BIOS_VADDRTOPADDR "addr" +.Vt extern struct bios32_SDentry PCIbios ; +.Vt extern struct SMBIOS_table SMBIOStable ; +.Vt extern struct DMI_table DMItable ; +.Ft int +.Fn bios_oem_strings "struct bios_oem *oem" "u_char *buffer" "size_t maxlen" +.Bd -literal +struct bios_oem_signature { + char * anchor; /* search anchor string in BIOS memory */ + size_t offset; /* offset from anchor (may be negative) */ + size_t totlen; /* total length of BIOS string to copy */ +}; +struct bios_oem_range { + u_int from; /* shouldn't be below 0xe0000 */ + u_int to; /* shouldn't be above 0xfffff */ +}; +struct bios_oem { + struct bios_oem_range range; + struct bios_oem_signature signature[]; +}; +.Ed +.Sh DESCRIPTION +These functions provide a general-purpose interface for dealing with +the BIOS functions and data encountered on x86 PC-architecture systems. +.Bl -tag -width 20n +.It Fn bios_sigsearch +Searches the BIOS address space for a service signature, usually an +uppercase ASCII sequence surrounded by underscores. +The search begins at +.Fa start , +or at the beginning of the BIOS if +.Fa start +is zero. +.Fa siglen +bytes of the BIOS image and +.Fa sig +are compared at +.Fa sigofs +bytes offset from the current location. +If no match is found, the +current location is incremented by +.Fa paralen +bytes and the search repeated. +If the signature is found, its effective +physical address is returned. +If no signature is found, zero is returned. +.It Fn bios_oem_strings +Searches a given BIOS memory range for one or more strings, +and composes a printable concatenation of those found. +The routine expects a structure describing the BIOS address +.Fa range +(within +.Li 0xe0000 +- +.Li 0xfffff ) , +and a { +.Dv NULL , Li 0 , 0 +} -terminated array of +.Vt bios_oem_signature +structures which define the +.Va anchor +string, an +.Va offset +from the beginning of the match (which may be negative), and +.Va totlen +number of bytes to be collected from BIOS memory starting at that offset. +Unmatched anchors are ignored, whereas matches are copied from BIOS memory +starting at their corresponding +.Vt offset +with unprintable characters being replaced with space, and consecutive spaces +being suppressed. +This composed string is stored in +.Fa buffer +up to the given +.Fa maxlen +bytes (including trailing +.Ql \e0 , +and any trailing space suppressed). +If an error is encountered, i.e.\& trying to read out of said BIOS range, +other invalid input, or +.Fa buffer +overflow, a negative integer is returned, otherwise the +length of the composed string is returned. +In particular, a return +value of 0 means that none of the given anchor strings were found in +the specified BIOS memory range. +.It Fn BIOS_VADDRTOPADDR +Returns the effective physical address which corresponds to the kernel +virtual address +.Fa addr . +.It Fn BIOS_PADDRTOVADDR +Returns the kernel virtual address which corresponds to the effective +physical address +.Fa addr . +.It SMBIOStable +If not NULL, points to a +.Ft struct SMBIOS_table +structure containing information read from the System Management BIOS table +during system startup. +.It DMItable +If not NULL, points to a +.Ft struct DMI_table +structure containing information read from the Desktop Management Interface +parameter table during system startup. +.El +.Sh BIOS32 +At system startup, the BIOS is scanned for the BIOS32 Service Directory +(part of the PCI specification), and the existence of the directory is +recorded. +This can then be used to locate other services. +.Bl -tag -width 20n +.It Fn bios32_SDlookup +Attempts to locate the BIOS32 service matching the 4-byte identifier +passed in the +.Fa ident +field of the +.Fa ent +argument. +.It Fn bios32 +Calls a bios32 function. +This presumes that the function is capable of +working within the kernel segment (normally the case). +The virtual address +of the entrypoint is supplied in +.Fa entry +and the register arguments to the function are supplied in +.Fa args . +.It PCIbios +If not NULL, points to a +.Ft struct bios32_SDentry +structure describing the PCI BIOS entrypoint which was found during system +startup. +.El diff --git a/static/freebsd/man9/bitset.9 b/static/freebsd/man9/bitset.9 new file mode 100644 index 00000000..b77cfec6 --- /dev/null +++ b/static/freebsd/man9/bitset.9 @@ -0,0 +1,658 @@ +.\" Copyright (c) 2015 Conrad Meyer +.\" 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 September 20, 2021 +.Dt BITSET 9 +.Os +.Sh NAME +.Nm bitset(9) +\(em +.Nm BITSET_DEFINE , +.Nm BITSET_T_INITIALIZER , +.Nm BITSET_FSET , +.Nm BIT_CLR , +.Nm BIT_COPY , +.Nm BIT_ISSET , +.Nm BIT_SET , +.Nm BIT_ZERO , +.Nm BIT_FILL , +.Nm BIT_SETOF , +.Nm BIT_EMPTY , +.Nm BIT_ISFULLSET , +.Nm BIT_FFS , +.Nm BIT_FFS_AT , +.Nm BIT_FLS , +.Nm BIT_FOREACH_ISSET , +.Nm BIT_FOREACH_ISCLR , +.Nm BIT_COUNT , +.Nm BIT_SUBSET , +.Nm BIT_OVERLAP , +.Nm BIT_CMP , +.Nm BIT_OR , +.Nm BIT_OR2 , +.Nm BIT_ORNOT , +.Nm BIT_ORNOT2 , +.Nm BIT_AND , +.Nm BIT_AND2 , +.Nm BIT_ANDNOT , +.Nm BIT_ANDNOT2 , +.Nm BIT_XOR , +.Nm BIT_XOR2 , +.Nm BIT_CLR_ATOMIC , +.Nm BIT_SET_ATOMIC , +.Nm BIT_SET_ATOMIC_ACQ , +.Nm BIT_TEST_SET_ATOMIC , +.Nm BIT_TEST_CLR_ATOMIC , +.Nm BIT_AND_ATOMIC , +.Nm BIT_OR_ATOMIC , +.Nm BIT_COPY_STORE_REL +.Nd bitset manipulation macros +.Sh SYNOPSIS +.In sys/_bitset.h +.In sys/bitset.h +.\" +.Fn BITSET_DEFINE "STRUCTNAME" "const SETSIZE" +.Fn BITSET_T_INITIALIZER "ARRAY_CONTENTS" +.Fn BITSET_FSET "N_WORDS" +.\" +.Fn BIT_CLR "const SETSIZE" "size_t bit" "struct STRUCTNAME *bitset" +.Fn BIT_COPY "const SETSIZE" "struct STRUCTNAME *from" "struct STRUCTNAME *to" +.Ft bool +.Fn BIT_ISSET "const SETSIZE" "size_t bit" "struct STRUCTNAME *bitset" +.Fn BIT_SET "const SETSIZE" "size_t bit" "struct STRUCTNAME *bitset" +.Fn BIT_ZERO "const SETSIZE" "struct STRUCTNAME *bitset" +.Fn BIT_FILL "const SETSIZE" "struct STRUCTNAME *bitset" +.Fn BIT_SETOF "const SETSIZE" "size_t bit" "struct STRUCTNAME *bitset" +.Ft bool +.Fn BIT_EMPTY "const SETSIZE" "struct STRUCTNAME *bitset" +.Ft bool +.Fn BIT_ISFULLSET "const SETSIZE" "struct STRUCTNAME *bitset" +.Ft long +.Fn BIT_FFS "const SETSIZE" "struct STRUCTNAME *bitset" +.Ft long +.Fn BIT_FFS_AT "const SETSIZE" "struct STRUCTNAME *bitset" "long start" +.Ft long +.Fn BIT_FLS "const SETSIZE" "struct STRUCTNAME *bitset" +.Fo BIT_FOREACH_ISSET +.Fa "const SETSIZE" +.Fa "size_t bit" +.Fa "const struct STRUCTNAME *bitset" +.Fc +.Fo BIT_FOREACH_ISCLR +.Fa "const SETSIZE" +.Fa "size_t bit" +.Fa "const struct STRUCTNAME *bitset" +.Fc +.Ft long +.Fn BIT_COUNT "const SETSIZE" "struct STRUCTNAME *bitset" +.Ft bool +.Fo BIT_SUBSET +.Fa "const SETSIZE" "struct STRUCTNAME *haystack" "struct STRUCTNAME *needle" +.Fc +.Ft bool +.Fo BIT_OVERLAP +.Fa "const SETSIZE" "struct STRUCTNAME *bitset1" "struct STRUCTNAME *bitset2" +.Fc +.Ft bool +.Fo BIT_CMP +.Fa "const SETSIZE" "struct STRUCTNAME *bitset1" "struct STRUCTNAME *bitset2" +.Fc +.Fn BIT_OR "const SETSIZE" "struct STRUCTNAME *dst" "struct STRUCTNAME *src" +.Fo BIT_OR2 +.Fa "const SETSIZE" +.Fa "struct STRUCTNAME *dst" +.Fa "struct STRUCTNAME *src1" +.Fa "struct STRUCTNAME *src2" +.Fc +.Fn BIT_ORNOT "const SETSIZE" "struct STRUCTNAME *dst" "struct STRUCTNAME *src" +.Fo BIT_ORNOT2 +.Fa "const SETSIZE" +.Fa "struct STRUCTNAME *dst" +.Fa "struct STRUCTNAME *src1" +.Fa "struct STRUCTNAME *src2" +.Fc +.Fn BIT_AND "const SETSIZE" "struct STRUCTNAME *dst" "struct STRUCTNAME *src" +.Fo BIT_AND2 +.Fa "const SETSIZE" +.Fa "struct STRUCTNAME *dst" +.Fa "struct STRUCTNAME *src1" +.Fa "struct STRUCTNAME *src2" +.Fc +.Fn BIT_ANDNOT "const SETSIZE" "struct STRUCTNAME *dst" "struct STRUCTNAME *src" +.Fo BIT_ANDNOT2 +.Fa "const SETSIZE" +.Fa "struct STRUCTNAME *dst" +.Fa "struct STRUCTNAME *src1" +.Fa "struct STRUCTNAME *src2" +.Fc +.Fn BIT_XOR "const SETSIZE" "struct STRUCTNAME *dst" "struct STRUCTNAME *src" +.Fo BIT_XOR2 +.Fa "const SETSIZE" +.Fa "struct STRUCTNAME *dst" +.Fa "struct STRUCTNAME *src1" +.Fa "struct STRUCTNAME *src2" +.Fc +.\" +.Fn BIT_CLR_ATOMIC "const SETSIZE" "size_t bit" "struct STRUCTNAME *bitset" +.Fn BIT_SET_ATOMIC "const SETSIZE" "size_t bit" "struct STRUCTNAME *bitset" +.Fn BIT_SET_ATOMIC_ACQ "const SETSIZE" "size_t bit" "struct STRUCTNAME *bitset" +.Ft bool +.Fn BIT_TEST_SET_ATOMIC "const SETSIZE" "size_t bit" "struct STRUCTNAME *bitset" +.Ft bool +.Fn BIT_TEST_CLR_ATOMIC "const SETSIZE" "size_t bit" "struct STRUCTNAME *bitset" +.\" +.Fo BIT_AND_ATOMIC +.Fa "const SETSIZE" "struct STRUCTNAME *dst" "struct STRUCTNAME *src" +.Fc +.Fo BIT_OR_ATOMIC +.Fa "const SETSIZE" "struct STRUCTNAME *dst" "struct STRUCTNAME *src" +.Fc +.Fo BIT_COPY_STORE_REL +.Fa "const SETSIZE" "struct STRUCTNAME *from" "struct STRUCTNAME *to" +.Fc +.Fd #define _WANT_FREEBSD_BITSET +.Sh DESCRIPTION +The +.Nm +family of macros provide a flexible and efficient bitset implementation if the +maximum size of the set is known at compilation. +Throughout this manual page, the name +.Fa SETSIZE +refers to the size of the bitset in bits. +Individual bits in bitsets are referenced with indices zero through +.Fa SETSIZE - 1 . +One example use of +.In sys/bitset.h +is +.In sys/cpuset.h . +.Pp +These macros are meant to be used in the kernel and are visible if +.Dv _KERNEL is defined when +.In sys/_bitset.h +or +.In sys/bitset.h +are included in a program. +Userland programs must define +.Dv _WANT_FREEBSD_BITSET +before including these files to make the macros visible. +.Pp +The +.Fn BITSET_DEFINE +macro defines a bitset struct +.Fa STRUCTNAME +with room to represent +.Fa SETSIZE +bits. +.Pp +The +.Fn BITSET_T_INITIALIZER +macro allows one to initialize a bitset struct with a compile time literal +value. +.Pp +The +.Fn BITSET_FSET +macro generates a compile time literal, usable by +.Fn BITSET_T_INITIALIZER , +representing a full bitset (all bits set). +For examples of +.Fn BITSET_T_INITIALIZER +and +.Fn BITSET_FSET +usage, see the +.Sx BITSET_T_INITIALIZER EXAMPLE +section. +The +.Fa N_WORDS +parameter to +.Fn BITSET_FSET +should be: +.Bd -literal -offset indent +__bitset_words(SETSIZE) +.Ed +.Pp +The +.Fn BIT_CLR +macro clears bit +.Fa bit +in the bitset pointed to by +.Fa bitset . +The +.Fn BIT_CLR_ATOMIC +macro is identical, but the bit is cleared atomically. +The +.Fn BIT_TEST_CLR_ATOMIC +macro atomically clears the bit and returns whether it was set. +.Pp +The +.Fn BIT_COPY +macro copies the contents of the bitset +.Fa from +to the bitset +.Fa to . +.Fn BIT_COPY_STORE_REL +is similar, but copies component machine words from +.Fa from +and writes them to +.Fa to +with atomic store with release semantics. +(That is, if +.Fa to +is composed of multiple machine words, +.Fn BIT_COPY_STORE_REL +performs multiple individually atomic operations.) +.Pp +The +.Fn BIT_ISSET +macro returns +.Dv true +if the bit +.Fa bit +in the bitset pointed to by +.Fa bitset +is set. +.Pp +The +.Fn BIT_SET +macro sets bit +.Fa bit +in the bitset pointed to by +.Fa bitset . +The +.Fn BIT_SET_ATOMIC +macro is identical, but the bit is set atomically. +The +.Fn BIT_SET_ATOMIC_ACQ +macro sets the bit with acquire semantics. +The +.Fn BIT_TEST_SET_ATOMIC +macro atomically sets the bit and returns whether it was set. +.Pp +The +.Fn BIT_ZERO +macro clears all bits in +.Fa bitset . +.Pp +The +.Fn BIT_FILL +macro sets all bits in +.Fa bitset . +.Pp +The +.Fn BIT_SETOF +macro clears all bits in +.Fa bitset +before setting only bit +.Fa bit . +.Pp +The +.Fn BIT_EMPTY +macro returns +.Dv true +if +.Fa bitset +is empty. +.Pp +The +.Fn BIT_ISFULLSET +macro returns +.Dv true +if +.Fa bitset +is full (all bits set). +.Pp +The +.Fn BIT_FFS +macro returns the 1-index of the first (lowest) set bit in +.Fa bitset , +or zero if +.Fa bitset +is empty. +Like with +.Xr ffs 3 , +to use the non-zero result of +.Fn BIT_FFS +as a +.Fa bit +index parameter to any other +.Nm +macro, you must subtract one from the result. +.Pp +The +.Fn BIT_FFS_AT +macro returns the 1-index of the first (lowest) set bit in +.Fa bitset , +which is greater than the given 1-indexed +.Fa start , +or zero if no bits in +.Fa bitset +greater than +.Fa start +are set. +.Pp +The +.Fn BIT_FLS +macro returns the 1-index of the last (highest) set bit in +.Fa bitset , +or zero if +.Fa bitset +is empty. +Like with +.Xr fls 3 , +to use the non-zero result of +.Fn BIT_FLS +as a +.Fa bit +index parameter to any other +.Nm +macro, you must subtract one from the result. +.Pp +The +.Fn BIT_FOREACH_ISSET +macro can be used to iterate over all set bits in +.Fa bitset . +The index variable +.Fa bit +must have been declared with type +.Ft int , +and upon each iteration +.Fa bit +is set to the index of successive set bits. +The value of +.Fa bit +after the loop terminates is undefined. +Similarly, +.Fn BIT_FOREACH_ISCLR +iterates over all clear bits in +.Fa bitset . +In the loop body, the currently indexed bit may be set or cleared. +However, setting or clearing bits other than the currently indexed +bit does not guarantee that they will or will not be returned in +subsequent iterations of the same loop. +.Pp +The +.Fn BIT_COUNT +macro returns the total number of set bits in +.Fa bitset . +.Pp +The +.Fn BIT_SUBSET +macro returns +.Dv true +if +.Fa needle +is a subset of +.Fa haystack . +.Pp +The +.Fn BIT_OVERLAP +macro returns +.Dv true +if +.Fa bitset1 +and +.Fa bitset2 +have any common bits. +(That is, if +.Fa bitset1 +AND +.Fa bitset2 +is not the empty set.) +.Pp +The +.Fn BIT_CMP +macro returns +.Dv true +if +.Fa bitset1 +is NOT equal to +.Fa bitset2 . +.Pp +The +.Fn BIT_OR +macro sets bits present in +.Fa src +in +.Fa dst . +(It is the +.Nm +equivalent of the scalar: +.Fa dst +|= +.Fa src . ) +.Fn BIT_OR_ATOMIC +is similar, but sets bits in the component machine words in +.Fa dst +atomically. +(That is, if +.Fa dst +is composed of multiple machine words, +.Fn BIT_OR_ATOMIC +performs multiple individually atomic operations.) +.Pp +The +.Fn BIT_OR2 +macro computes +.Fa src1 +bitwise or +.Fa src2 +and assigns the result to +.Fa dst . +(It is the +.Nm +equivalent of the scalar: +.Fa dst += +.Fa src1 +| +.Fa src2 . ) +.Pp +The +.Fn BIT_ORNOT +macro sets bits not in +.Fa src +in +.Fa dst . +(It is the +.Nm +equivalent of the scalar: +.Fa dst +|= +.Fa ~ src . ) +.Pp +The +.Fn BIT_ORNOT2 +macro computes +.Fa src1 +bitwise or not +.Fa src2 +and assigns the result to +.Fa dst . +(It is the +.Nm +equivalent of the scalar: +.Fa dst += +.Fa src1 +| ~ +.Fa src2 . ) +.Pp +The +.Fn BIT_AND +macro clears bits absent from +.Fa src +from +.Fa dst . +(It is the +.Nm +equivalent of the scalar: +.Fa dst +&= +.Fa src . ) +.Fn BIT_AND_ATOMIC +is similar, with the same atomic semantics as +.Fn BIT_OR_ATOMIC . +.Pp +The +.Fn BIT_AND2 +macro computes +.Fa src1 +bitwise and +.Fa src2 +and assigns the result to +.Fa dst . +(It is the +.Nm +equivalent of the scalar: +.Fa dst += +.Fa src1 +& +.Fa src2 . ) +.Pp +The +.Fn BIT_ANDNOT +macro clears bits set in +.Fa src +from +.Fa dst . +(It is the +.Nm +equivalent of the scalar: +.Fa dst +&= +.Fa ~ src . ) +.Pp +The +.Fn BIT_ANDNOT2 +macro computes +.Fa src1 +bitwise and not +.Fa src2 +and assigns the result to +.Fa dst . +(It is the +.Nm +equivalent of the scalar: +.Fa dst += +.Fa src1 +& ~ +.Fa src2 . ) +.Pp +The +.Fn BIT_XOR +macro toggles bits set in +.Fa src +in +.Fa dst . +(It is the +.Nm +equivalent of the scalar: +.Fa dst +^= +.Fa src . ) +.Pp +The +.Fn BIT_XOR2 +macro computes +.Fa src1 +bitwise exclusive or +.Fa src2 +and assigns the result to +.Fa dst . +(It is the +.Nm +equivalent of the scalar: +.Fa dst += +.Fa src1 +^ +.Fa src2 . ) +.Sh BITSET_T_INITIALIZER EXAMPLE +.Bd -literal +BITSET_DEFINE(_myset, MYSETSIZE); + +struct _myset myset; + +/* Initialize myset to filled (all bits set) */ +myset = BITSET_T_INITIALIZER(BITSET_FSET(__bitset_words(MYSETSIZE))); + +/* Initialize myset to only the lowest bit set */ +myset = BITSET_T_INITIALIZER(0x1); +.Ed +.Sh SEE ALSO +.Xr bitstring 3 , +.Xr cpuset 9 +.Sh HISTORY +The +.Nm +macros first appeared in +.Fx 10.0 +in January 2014. +They were MFCed to +.Fx 9.3 , +released in July 2014. +.Pp +This manual page first appeared in +.Fx 11.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +macros were generalized and pulled out of +.In sys/cpuset.h +as +.In sys/_bitset.h +and +.In sys/bitset.h +by +.An Attilio Rao Aq Mt attilio@FreeBSD.org . +This manual page was written by +.An Conrad Meyer Aq Mt cem@FreeBSD.org . +.Sh CAVEATS +The +.Fa SETSIZE +argument to all of these macros must match the value given to +.Fn BITSET_DEFINE . +.Pp +Unlike every other reference to individual set members, which are zero-indexed, +.Fn BIT_FFS , +.Fn BIT_FFS_AT +and +.Fn BIT_FLS +return a one-indexed result (or zero if the set is empty). +.Pp +In order to use the macros defined in +.In sys/bitset.h +and +.In sys/_bitset.h +in userland programs, +.Dv _WANT_FREEBSD_BITSET +has to be defined before including the header files. +This requirements exists to prevent a name space pollution due to macros defined in +.Nm +in programs that include +.In sys/cpuset.h +or +.In sched.h . diff --git a/static/freebsd/man9/bpf.9 b/static/freebsd/man9/bpf.9 new file mode 100644 index 00000000..b11013fe --- /dev/null +++ b/static/freebsd/man9/bpf.9 @@ -0,0 +1,299 @@ +.\" Copyright (c) 2004 FreeBSD Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY 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 [your name] 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 May 11, 2012 +.Dt BPF 9 +.Os +.\" +.Sh NAME +.Nm bpf +.Nd "Berkeley Packet Filter" +.\" +.Sh SYNOPSIS +.In net/bpf.h +.\" +.Ft void +.Fn bpfattach "struct ifnet *ifp" "u_int dlt" "u_int hdrlen" +.Ft void +.Fo bpfattach2 +.Fa "struct ifnet *ifp" "u_int dlt" "u_int hdrlen" "struct bpf_if **driverp" +.Fc +.Ft void +.Fn bpfdetach "struct ifnet *ifp" +.Ft void +.Fn bpf_tap "struct ifnet *ifp" "u_char *pkt" "u_int *pktlen" +.Ft void +.Fn bpf_mtap "struct ifnet *ifp" "struct mbuf *m" +.Ft void +.Fn bpf_mtap2 "struct bpf_if *bp" "void *data" "u_int dlen" "struct mbuf *m" +.Ft u_int +.Fo bpf_filter +.Fa "const struct bpf_insn *pc " "u_char *pkt" "u_int wirelen" "u_int buflen" +.Fc +.Ft int +.Fn bpf_validate "const struct bpf_insn *fcode" "int flen" +.\" +.Sh DESCRIPTION +The Berkeley Packet Filter provides a raw interface, +that is protocol independent, +to data link layers. +It allows all packets on the network, +even those destined for other hosts, +to be passed from a network interface to user programs. +Each program may specify a filter, +in the form of a +.Nm +filter machine program. +The +.Xr bpf 4 +manual page +describes the interface used by user programs. +This manual page describes the functions used by interfaces to pass packets to +.Nm +and the functions for testing and running +.Nm +filter machine programs. +.Pp +The +.Fn bpfattach +function +attaches a network interface to +.Nm . +The +.Fa ifp +argument +is a pointer to the structure that defines the interface to be +attached to an interface. +The +.Fa dlt +argument +is the data link-layer type: +.Dv DLT_NULL +(no link-layer encapsulation), +.Dv DLT_EN10MB +(Ethernet), +.Dv DLT_IEEE802_11 +(802.11 wireless networks), +etc. +The rest of the link layer types can be found in +.In net/bpf.h . +The +.Fa hdrlen +argument +is the fixed size of the link header; +variable length headers are not yet supported. +The +.Nm +system will hold a pointer to +.Fa ifp->if_bpf . +This variable will set to a +.Pf non- Dv NULL +value when +.Nm +requires packets from this interface to be tapped using the functions below. +.Pp +The +.Fn bpfattach2 +function +allows multiple +.Nm +instances to be attached to a single interface, +by registering an explicit +.Fa if_bpf +rather than using +.Fa ifp->if_bpf . +It is then possible to run +.Xr tcpdump 1 +on the interface for any data link-layer types attached. +.Pp +The +.Fn bpfdetach +function detaches a +.Nm +instance from an interface, +specified by +.Fa ifp . +The +.Fn bpfdetach +function +should be called once for each +.Nm +instance attached. +.Pp +The +.Fn bpf_tap +function +is used by an interface to pass the packet to +.Nm . +The packet data (including link-header), +pointed to by +.Fa pkt , +is of length +.Fa pktlen , +which must be a contiguous buffer. +The +.Fa ifp +argument +is a pointer to the structure that defines the interface to be tapped. +The packet is parsed by each processes filter, +and if accepted, +it is buffered for the process to read. +.Pp +The +.Fn bpf_mtap +function is like +.Fn bpf_tap +except that it is used to tap packets that are in an +.Vt mbuf +chain, +.Fa m . +The +.Fa ifp +argument +is a pointer to the structure that defines the interface to be tapped. +Like +.Fn bpf_tap , +.Fn bpf_mtap +requires a link-header for whatever data link layer type is specified. +Note that +.Nm +only reads from the +.Vt mbuf +chain, +it does not free it or keep a pointer to it. +This means that an +.Vt mbuf +containing the link-header +can be prepended to the chain if necessary. +A cleaner interface to achieve this is provided by +.Fn bpf_mtap2 . +.Pp +The +.Fn bpf_mtap2 +function +allows the user to pass a link-header +.Fa data , +of length +.Fa dlen , +independent of the +.Vt mbuf +.Fa m , +containing the packet. +This simplifies the passing of some link-headers. +.Pp +The +.Fn bpf_filter +function +executes the filter program starting at +.Fa pc +on the packet +.Fa pkt . +The +.Fa wirelen +argument +is the length of the original packet and +.Fa buflen +is the amount of data present. +The +.Fa buflen +value of 0 is special; it indicates that the +.Fa pkt +is actually a pointer to an mbuf chain +.Pq Vt "struct mbuf *" . +.Pp +The +.Fn bpf_validate +function +checks that the filter code +.Fa fcode , +of length +.Fa flen , +is valid. +.\" +.Sh RETURN VALUES +The +.Fn bpf_filter +function returns \-1 +(cast to an unsigned integer) +if there is no filter. +Otherwise, it returns the result of the filter program. +.Pp +The +.Fn bpf_validate +function +returns 0 when the program is not a valid filter program. +.\" +.Sh EVENT HANDLERS +.Nm +invokes +.Fa bpf_track +.Xr EVENTHANDLER 9 +event each time listener attaches to or detaches from an interface. +Pointer to +.Pq Vt "struct ifnet *" +is passed as the first argument, interface +.Fa dlt +follows. +Last argument indicates listener is attached (1) or detached (0). +Note that handler is invoked with +.Nm +global lock held, which implies restriction on sleeping and calling +.Nm +subsystem inside +.Xr EVENTHANDLER 9 +dispatcher. +Note that handler is not called for write-only listeners. +.\" +.Sh SEE ALSO +.Xr tcpdump 1 , +.Xr bpf 4 , +.Xr EVENTHANDLER 9 +.\" +.Sh HISTORY +The Enet packet filter was created in 1980 by Mike Accetta and +Rick Rashid at Carnegie-Mellon University. +Jeffrey Mogul, +at Stanford, +ported the code to +.Bx +and continued its development from 1983 on. +Since then, +it has evolved into the Ultrix Packet Filter at +.Tn DEC , +a +.Tn STREAMS +.Tn NIT +module under +.Tn SunOS +4.1, and +.Tn BPF . +.\" +.Sh AUTHORS +.An -nosplit +.An Steven McCanne , +of Lawrence Berkeley Laboratory, implemented BPF in Summer 1990. +Much of the design is due to +.An Van Jacobson . +This manpage was written by +.An Orla McGann . diff --git a/static/freebsd/man9/buf.9 b/static/freebsd/man9/buf.9 new file mode 100644 index 00000000..ff9a1d0d --- /dev/null +++ b/static/freebsd/man9/buf.9 @@ -0,0 +1,189 @@ +.\" Copyright (c) 1998 +.\" The Regents of the University of California. 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. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 December 22, 1998 +.Dt BUF 9 +.Os +.Sh NAME +.Nm buf +.Nd "kernel buffer I/O scheme used in FreeBSD VM system" +.Sh DESCRIPTION +The kernel implements a KVM abstraction of the buffer cache which allows it +to map potentially disparate vm_page's into contiguous KVM for use by +(mainly file system) devices and device I/O. +This abstraction supports +block sizes from +.Dv DEV_BSIZE +(usually 512) to upwards of several pages or more. +It also supports a relatively primitive byte-granular valid range and dirty +range currently hardcoded for use by NFS. +The code implementing the +VM Buffer abstraction is mostly concentrated in +.Pa sys/kern/vfs_bio.c +in the +.Fx +source tree. +.Pp +One of the most important things to remember when dealing with buffer pointers +.Pq Vt struct buf +is that the underlying pages are mapped directly from the buffer +cache. +No data copying occurs in the scheme proper, though some file systems +such as UFS do have to copy a little when dealing with file fragments. +The second most important thing to remember is that due to the underlying page +mapping, the +.Va b_data +base pointer in a buf is always +.Em page Ns -aligned , +not +.Em block Ns -aligned . +When you have a VM buffer representing some +.Va b_offset +and +.Va b_size , +the actual start of the buffer is +.Ql b_data + (b_offset & PAGE_MASK) +and not just +.Ql b_data . +Finally, the VM system's core buffer cache supports +valid and dirty bits +.Pq Va m->valid , m->dirty +for pages in +.Dv DEV_BSIZE +chunks. +Thus +a platform with a hardware page size of 4096 bytes has 8 valid and 8 dirty +bits. +These bits are generally set and cleared in groups based on the device +block size of the device backing the page. +Complete page's worth are often +referred to using the +.Dv VM_PAGE_BITS_ALL +bitmask (i.e., 0xFF if the hardware page +size is 4096). +.Pp +VM buffers also keep track of a byte-granular dirty range and valid range. +This feature is normally only used by the NFS subsystem. +I am not sure why it +is used at all, actually, since we have +.Dv DEV_BSIZE +valid/dirty granularity +within the VM buffer. +If a buffer dirty operation creates a +.Dq hole , +the dirty range will extend to cover the hole. +If a buffer validation +operation creates a +.Dq hole +the byte-granular valid range is left alone and +will not take into account the new extension. +Thus the whole byte-granular +abstraction is considered a bad hack and it would be nice if we could get rid +of it completely. +.Pp +A VM buffer is capable of mapping the underlying VM cache pages into KVM in +order to allow the kernel to directly manipulate the data associated with +the +.Pq Va vnode , b_offset , b_size . +The kernel typically unmaps VM buffers the moment +they are no longer needed but often keeps the +.Vt struct buf +structure +instantiated and even +.Va bp->b_pages +array instantiated despite having unmapped +them from KVM. +If a page making up a VM buffer is about to undergo I/O, the +system typically unmaps it from KVM and replaces the page in the +.Va b_pages[] +array with a place-marker called bogus_page. +The place-marker forces any kernel +subsystems referencing the associated +.Vt struct buf +to re-lookup the associated +page. +I believe the place-marker hack is used to allow sophisticated devices +such as file system devices to remap underlying pages in order to deal with, +for example, re-mapping a file fragment into a file block. +.Pp +VM buffers are used to track I/O operations within the kernel. +Unfortunately, +the I/O implementation is also somewhat of a hack because the kernel wants +to clear the dirty bit on the underlying pages the moment it queues the I/O +to the VFS device, not when the physical I/O is actually initiated. +This +can create confusion within file system devices that use delayed-writes because +you wind up with pages marked clean that are actually still dirty. +If not +treated carefully, these pages could be thrown away! +Indeed, a number of +serious bugs related to this hack were not fixed until the +.Fx 2.2.8 / +.Fx 3.0 +release. +The kernel uses an instantiated VM buffer (i.e., +.Vt struct buf ) +to place-mark pages +in this special state. +The buffer is typically flagged +.Dv B_DELWRI . +When a +device no longer needs a buffer it typically flags it as +.Dv B_RELBUF . +Due to +the underlying pages being marked clean, the +.Ql B_DELWRI|B_RELBUF +combination must +be interpreted to mean that the buffer is still actually dirty and must be +written to its backing store before it can actually be released. +In the case +where +.Dv B_DELWRI +is not set, the underlying dirty pages are still properly +marked as dirty and the buffer can be completely freed without losing that +clean/dirty state information. +(XXX do we have to check other flags in +regards to this situation ???) +.Pp +The kernel reserves a portion of its KVM space to hold VM Buffer's data +maps. +Even though this is virtual space (since the buffers are mapped +from the buffer cache), we cannot make it arbitrarily large because +instantiated VM Buffers +.Pq Vt struct buf Ap s +prevent their underlying pages in the +buffer cache from being freed. +This can complicate the life of the paging +system. +.Sh HISTORY +The +.Nm +manual page was originally written by +.An Matthew Dillon +and first appeared in +.Fx 3.1 , +December 1998. diff --git a/static/freebsd/man9/buf_ring.9 b/static/freebsd/man9/buf_ring.9 new file mode 100644 index 00000000..ae3b8505 --- /dev/null +++ b/static/freebsd/man9/buf_ring.9 @@ -0,0 +1,131 @@ +.\" Copyright (c) 2009 Bitgravity Inc +.\" Written by: Kip Macy +.\" 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 September 27, 2012 +.Dt BUF_RING 9 +.Os +.Sh NAME +.Nm buf_ring , +.Nm buf_ring_alloc , +.Nm buf_ring_free , +.Nm buf_ring_enqueue , +.Nm buf_ring_dequeue_mc , +.Nm buf_ring_dequeue_sc , +.Nm buf_ring_count , +.Nm buf_ring_empty , +.Nm buf_ring_full , +.Nm buf_ring_peek +.Nd multi-producer, {single, multi}-consumer lock-less ring buffer +.Sh SYNOPSIS +.In sys/param.h +.In sys/buf_ring.h +.Ft struct buf_ring * +.Fn buf_ring_alloc "int count" "struct malloc_type *type" "int flags" "struct mtx *sc_lock" +.Ft void +.Fn buf_ring_free "struct buf_ring *br" "struct malloc_type *type" +.Ft int +.Fn buf_ring_enqueue "struct buf_ring *br" "void *buf" +.Ft void * +.Fn buf_ring_dequeue_mc "struct buf_ring *br" +.Ft void * +.Fn buf_ring_dequeue_sc "struct buf_ring *br" +.Ft int +.Fn buf_ring_count "struct buf_ring *br" +.Ft int +.Fn buf_ring_empty "struct buf_ring *br" +.Ft int +.Fn buf_ring_full "struct buf_ring *br" +.Ft void * +.Fn buf_ring_peek "struct buf_ring *br" +.Sh DESCRIPTION +The +.Nm +functions provide a lock-less multi-producer and lock-less multi-consumer as +well as single-consumer ring buffer. +.Pp +The +.Fn buf_ring_alloc +function is used to allocate a buf_ring ring buffer with +.Fa count +slots using malloc_type +.Fa type +and memory flags +.Fa flags . +The single consumer interface is protected by +.Fa sc_lock . +.Pp +The +.Fn buf_ring_free +function is used to free a buf_ring. +The user is responsible for freeing any enqueued items. +.Pp +The +.Fn buf_ring_enqueue +function is used to enqueue a buffer to a buf_ring. +.Pp +The +.Fn buf_ring_dequeue_mc +function is a multi-consumer safe way of dequeueing elements from a buf_ring. +.Pp +The +.Fn buf_ring_dequeue_sc +function is a single-consumer interface to dequeue elements - requiring +the user to serialize accesses with a lock. +.Pp +The +.Fn buf_ring_count +function returns the number of elements in a buf_ring. +.Pp +The +.Fn buf_ring_empty +function returns +.Dv TRUE +if the buf_ring is empty, +.Dv FALSE +otherwise. +.Pp +The +.Fn buf_ring_full +function returns +.Dv TRUE +if no more items can be enqueued, +.Dv FALSE +otherwise. +.Pp +The +.Fn buf_ring_peek +function returns a pointer to the last element in the buf_ring if the +buf_ring is not empty, +.Dv NULL +otherwise. +.Sh RETURN VALUES +The +.Fn buf_ring_enqueue +function return +.Er ENOBUFS +if there are no available slots in the buf_ring. +.Sh HISTORY +These functions were introduced in +.Fx 8.0 . diff --git a/static/freebsd/man9/bus_activate_resource.9 b/static/freebsd/man9/bus_activate_resource.9 new file mode 100644 index 00000000..7b87197b --- /dev/null +++ b/static/freebsd/man9/bus_activate_resource.9 @@ -0,0 +1,126 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2003 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 March 13, 2024 +.Dt BUS_ACTIVATE_RESOURCE 9 +.Os +.Sh NAME +.Nm bus_activate_resource , bus_deactivate_resource +.Nd activate or deactivate a resource +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Pp +.In machine/bus.h +.In sys/rman.h +.In machine/resource.h +.Ft int +.Fo bus_activate_resource +.Fa "device_t dev" "struct resource *r" +.Fc +.Ft int +.Fo bus_deactivate_resource +.Fa "device_t dev" "struct resource *r" +.Fc +.Sh DESCRIPTION +These functions activate or deactivate a previously allocated resource. +In general, resources must be activated before they can be accessed by +the driver. +Bus drivers may perform additional actions to ensure that the resource is +ready to be accessed. +For example, +the PCI bus driver enables memory decoding in a PCI device's command register +when activating a memory resource. +.Pp +The arguments are as follows: +.Bl -tag -width indent +.It Fa dev +The device that requests ownership of the resource. +Before allocation, the resource is owned by the parent bus. +.It Fa r +A pointer to the +.Vt "struct resource" +returned by +.Xr bus_alloc_resource 9 . +.El +.Ss Resource Mapping +Resources which can be mapped for CPU access by a +.Xr bus_space 9 +tag and handle will create a mapping of the entire resource when activated. +The tag and handle for this mapping are stored in +.Fa r +and can be retrieved via +.Xr rman_get_bustag 9 +and +.Xr rman_get_bushandle 9 . +These can be used with the +.Xr bus_space 9 +API to access device registers or memory described by +.Fa r . +If the mapping is associated with a virtual address, +the virtual address can be retrieved via +.Xr rman_get_virtual 9 . +.Pp +This implicit mapping can be disabled by passing the +.Dv RF_UNMAPPED +flag to +.Xr bus_alloc_resource 9 . +A driver may use this if it wishes to allocate its own mappings of a resource +using +.Xr bus_map_resource 9 . +.Pp +A wrapper API for +.Xr bus_space 9 +is also provided that accepts the associated resource as the first argument +in place of the +.Xr bus_space 9 +tag and handle. +The functions in this wrapper API are named similarly to the +.Xr bus_space 9 +API except that +.Dq _space +is removed from their name. +For example, +.Fn bus_read_4 +can be used in place of +.Fn bus_space_read_4 . +The wrapper API is preferred in new drivers. +.Pp +These two statements both read a 32-bit register at the start of a +resource: +.Bd -literal + bus_space_read_4(rman_get_bustag(res), rman_get_bushandle(res), 0); + bus_read_4(res, 0); +.Ed +.Sh RETURN VALUES +Zero is returned on success, otherwise an error is returned. +.Sh SEE ALSO +.Xr bus_alloc_resource 9 , +.Xr bus_map_resource 9 , +.Xr bus_space 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/static/freebsd/man9/bus_adjust_resource.9 b/static/freebsd/man9/bus_adjust_resource.9 new file mode 100644 index 00000000..27173894 --- /dev/null +++ b/static/freebsd/man9/bus_adjust_resource.9 @@ -0,0 +1,95 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2011 Hudson River Trading LLC +.\" Written by: John H. Baldwin +.\" 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 March 13, 2024 +.Dt BUS_ADJUST_RESOURCE 9 +.Os +.Sh NAME +.Nm bus_adjust_resource +.Nd adjust resource allocated from a parent bus +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Pp +.In machine/bus.h +.In sys/rman.h +.In machine/resource.h +.Ft int +.Fo bus_adjust_resource +.Fa "device_t dev" "struct resource *r" +.Fa "rman_res_t start" "rman_res_t end" +.Fc +.Sh DESCRIPTION +This function is used to ask the parent bus to adjust the resource range +assigned to an allocated resource. +The resource +.Fa r +should have been allocated by a previous call to +.Xr bus_alloc_resource 9 . +The new resource range must overlap the existing range of +.Fa r . +.Pp +Note that none of the constraints of the original allocation request such +as alignment or boundary restrictions are checked by +.Fn bus_adjust_resource . +It is the caller's responsibility to enforce any such requirements. +.Sh RETURN VALUES +The +.Fn bus_adjust_resource +method returns zero on success or an error code on failure. +.Sh EXAMPLES +Grow an existing memory resource by 4096 bytes. +.Bd -literal + struct resource *res; + int error; + + error = bus_adjust_resource(dev, res, rman_get_start(res), + rman_get_end(res) + 0x1000); +.Ed +.Sh ERRORS +.Fn bus_adjust_resource +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa dev +device does not have a parent device. +.It Bq Er EINVAL +The +.Fa r +resource is a shared resource. +.It Bq Er EINVAL +The new address range does not overlap with the existing address range of +.Fa r . +.It Bq Er EBUSY +The new address range conflicts with another allocated resource. +.El +.Sh SEE ALSO +.Xr bus_alloc_resource 9 , +.Xr bus_release_resource 9 , +.Xr device 9 , +.Xr driver 9 diff --git a/static/freebsd/man9/bus_alloc_resource.9 b/static/freebsd/man9/bus_alloc_resource.9 new file mode 100644 index 00000000..d69917d1 --- /dev/null +++ b/static/freebsd/man9/bus_alloc_resource.9 @@ -0,0 +1,187 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2000 Alexander Langer +.\" +.\" 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 March 6, 2026 +.Dt BUS_ALLOC_RESOURCE 9 +.Os +.Sh NAME +.Nm bus_alloc_resource , +.Nm bus_alloc_resource_any , +.Nm bus_alloc_resource_anywhere +.Nd allocate resources from a parent bus +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Pp +.In machine/bus.h +.In sys/rman.h +.In machine/resource.h +.Ft struct resource * +.Fo bus_alloc_resource +.Fa "device_t dev" "int type" "int rid" "rman_res_t start" "rman_res_t end" +.Fa "rman_res_t count" "u_int flags" +.Fc +.Ft struct resource * +.Fn bus_alloc_resource_any "device_t dev" "int type" "int rid" "u_int flags" +.Ft struct resource * +.Fo bus_alloc_resource_anywhere +.Fa "device_t dev" "int type" "int rid" "rman_res_t count" "u_int flags" +.Fc +.Sh DESCRIPTION +This is an easy interface to the resource-management functions. +It hides the indirection through the parent's method table. +This function generally should be called in attach, but (except in some +rare cases) never earlier. +.Pp +The +.Fn bus_alloc_resource_any +and +.Fn bus_alloc_resource_anywhere +functions are convenience wrappers for +.Fn bus_alloc_resource . +.Fn bus_alloc_resource_any +sets +.Fa start , +.Fa end , +and +.Fa count +to the default resource (see description of +.Fa start +below). +.Fn bus_alloc_resource_anywhere +sets +.Fa start +and +.Fa end +to the default resource and uses the provided +.Fa count +argument. +.Pp +The arguments are as follows: +.Bl -item +.It +.Fa dev +is the device that requests ownership of the resource. +Before allocation, the resource is owned by the parent bus. +.It +.Fa type +is the type of resource you want to allocate. +It is one of: +.Bl -tag -width SYS_RES_MEMORY +.It Dv PCI_RES_BUS +for PCI bus numbers +.It Dv SYS_RES_IRQ +for IRQs +.It Dv SYS_RES_DRQ +for ISA DMA lines +.It Dv SYS_RES_IOPORT +for I/O ports +.It Dv SYS_RES_MEMORY +for I/O memory +.El +.It +.Fa rid +is a bus specific handle that identifies the resource being allocated. +For ISA this is an index into an array of resources that have been setup +for this device by either the PnP mechanism, or via the hints mechanism. +For PCCARD, this is an index into the array of resources described by the PC Card's +CIS entry. +For PCI, the offset into PCI config space which has the BAR to use to access +the resource. +.It +.Fa start +and +.Fa end +are the start/end addresses of the resource. +If you specify values of 0ul for +.Fa start +and ~0ul for +.Fa end +and 1 for +.Fa count , +the default values for the bus are calculated. +.It +.Fa count +is the size of the resource. +For example, the size of an I/O port is usually 1 byte (but some devices +override this). +If you specified the default values for +.Fa start +and +.Fa end , +then the default value of the bus is used if +.Fa count +is smaller than the default value and +.Fa count +is used, if it is bigger than the default value. +.It +.Fa flags +sets the flags for the resource. +You can set zero or more of these flags: +.Bl -tag -width RF_PREFETCHABLE +.It Dv RF_ACTIVE +activate resource atomically. +.It Dv RF_PREFETCHABLE +resource is prefetchable. +.It Dv RF_SHAREABLE +resource permits contemporaneous sharing. +It should always be set unless you know that the resource cannot be shared. +It is the bus driver's task to filter out the flag if the bus does not +support sharing. +.It Dv RF_UNMAPPED +do not establish implicit mapping when activated via +.Xr bus_activate_resource 9 . +.El +.El +.Sh RETURN VALUES +A pointer to +.Va struct resource +is returned on success, a null pointer otherwise. +.Sh EXAMPLES +This is some example code that allocates a 32 byte I/O port range and an IRQ. +.Bd -literal + struct resource *portres, *irqres; + + portres = bus_alloc_resource(dev, SYS_RES_IOPORT, 0, + 0ul, ~0ul, 32, RF_ACTIVE); + irqres = bus_alloc_resource_any(dev, SYS_RES_IRQ, 0, + RF_ACTIVE | RF_SHAREABLE); +.Ed +.Sh SEE ALSO +.Xr bus_activate_resource 9 , +.Xr bus_adjust_resource 9 , +.Xr bus_map_resource 9 , +.Xr bus_release_resource 9 , +.Xr device 9 , +.Xr driver 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Alexander Langer Aq Mt alex@big.endian.de +with parts by +.An Warner Losh Aq Mt imp@FreeBSD.org . diff --git a/static/freebsd/man9/bus_attach_children.9 b/static/freebsd/man9/bus_attach_children.9 new file mode 100644 index 00000000..81a24a42 --- /dev/null +++ b/static/freebsd/man9/bus_attach_children.9 @@ -0,0 +1,152 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 John Baldwin +.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_DETACH 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/static/freebsd/man9/bus_child_present.9 b/static/freebsd/man9/bus_child_present.9 new file mode 100644 index 00000000..1d5c78f4 --- /dev/null +++ b/static/freebsd/man9/bus_child_present.9 @@ -0,0 +1,81 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2003 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 March 27, 2003 +.Dt BUS_CHILD_PRESENT 9 +.Os +.Sh NAME +.Nm bus_child_present +.Nd "ask the bus driver to see if this device is still really present" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Pp +.In machine/bus.h +.In sys/rman.h +.In machine/resource.h +.Ft int +.Fn bus_child_present "device_t dev" +.Sh DESCRIPTION +The +.Fn bus_child_present +function requests that the parent device driver of +.Fa dev +check to see if the +hardware represented by +.Fa dev +is still physically accessible at this time. +While the notion of accessible varies from bus to bus, generally +hardware that is not accessible cannot be accessed via the +.Fn bus_space* +methods that would otherwise be used to access the device. +.Pp +This does not ask the question +.Dq does this device have children? +which can better be answered by +.Xr device_get_children 9 . +.Sh RETURN VALUES +A zero return value indicates that the device is not present in the +system. +A non-zero return value indicates that the device is present in the +system, or that the state of the device cannot be determined. +.Sh EXAMPLES +This is some example code. +It only calls stop when the +.Xr dc 4 +device is actually present. +.Bd -literal -offset indent +device_t dev; +dc_softc *sc; + +sc = device_get_softc(dev); +if (bus_child_present(dev)) + dc_stop(sc); +.Ed +.Sh SEE ALSO +.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/static/freebsd/man9/bus_dma.9 b/static/freebsd/man9/bus_dma.9 new file mode 100644 index 00000000..0bf27eb5 --- /dev/null +++ b/static/freebsd/man9/bus_dma.9 @@ -0,0 +1,1333 @@ +.\" Copyright (c) 2002, 2003 Hiten M. Pandya. +.\" 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, +.\" without modification, immediately at the beginning of the file. +.\" 2. 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 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, CONTRIBUTORS OR THE +.\" VOICES IN HITEN PANDYA'S HEAD 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. +.\" +.\" Copyright (c) 1996, 1997, 1998, 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe of the Numerical Aerospace Simulation Facility, +.\" NASA Ames Research Center. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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. +.\" $NetBSD: bus_dma.9,v 1.25 2002/10/14 13:43:16 wiz Exp $ +.\" +.Dd May 25, 2020 +.Dt BUS_DMA 9 +.Os +.Sh NAME +.Nm bus_dma , +.Nm bus_dma_tag_create , +.Nm bus_dma_tag_destroy , +.Nm bus_dma_template_init , +.Nm bus_dma_template_tag , +.Nm bus_dma_template_clone , +.Nm bus_dma_template_fill , +.Nm BUS_DMA_TEMPLATE_FILL , +.Nm bus_dmamap_create , +.Nm bus_dmamap_destroy , +.Nm bus_dmamap_load , +.Nm bus_dmamap_load_bio , +.Nm bus_dmamap_load_ccb , +.Nm bus_dmamap_load_crp , +.Nm bus_dmamap_load_crp_buffer , +.Nm bus_dmamap_load_mbuf , +.Nm bus_dmamap_load_mbuf_sg , +.Nm bus_dmamap_load_uio , +.Nm bus_dmamap_unload , +.Nm bus_dmamap_sync , +.Nm bus_dmamem_alloc , +.Nm bus_dmamem_free +.Nd Bus and Machine Independent DMA Mapping Interface +.Sh SYNOPSIS +.In machine/bus.h +.Ft int +.Fn bus_dma_tag_create "bus_dma_tag_t parent" "bus_size_t alignment" \ +"bus_addr_t boundary" "bus_addr_t lowaddr" "bus_addr_t highaddr" \ +"bus_dma_filter_t *filtfunc" "void *filtfuncarg" "bus_size_t maxsize" \ +"int nsegments" "bus_size_t maxsegsz" "int flags" "bus_dma_lock_t *lockfunc" \ +"void *lockfuncarg" "bus_dma_tag_t *dmat" +.Ft int +.Fn bus_dma_tag_destroy "bus_dma_tag_t dmat" +.Ft void +.Fo bus_dma_template_init +.Fa "bus_dma_template_t *template" +.Fa "bus_dma_tag_t parent" +.Fc +.Ft int +.Fo bus_dma_template_tag +.Fa "bus_dma_template_t *template" +.Fa "bus_dma_tag_t *dmat" +.Fc +.Ft void +.Fo bus_dma_template_clone +.Fa "bus_dma_template_t *template" +.Fa "bus_dma_tag_t dmat" +.Fc +.Ft void +.Fo bus_dma_template_fill +.Fa "bus_dma_template_t *template" +.Fa "bus_dma_param_t params[]" +.Fa "u_int count" +.Fc +.Fo BUS_DMA_TEMPLATE_FILL +.Fa "bus_dma_template_t *template" +.Fa "bus_dma_param_t param ..." +.Fc +.Ft int +.Fn bus_dmamap_create "bus_dma_tag_t dmat" "int flags" "bus_dmamap_t *mapp" +.Ft int +.Fn bus_dmamap_destroy "bus_dma_tag_t dmat" "bus_dmamap_t map" +.Ft int +.Fn bus_dmamap_load "bus_dma_tag_t dmat" "bus_dmamap_t map" "void *buf" \ +"bus_size_t buflen" "bus_dmamap_callback_t *callback" "void *callback_arg" \ +"int flags" +.Ft int +.Fn bus_dmamap_load_bio "bus_dma_tag_t dmat" "bus_dmamap_t map" \ +"struct bio *bio" "bus_dmamap_callback_t *callback" "void *callback_arg" \ +"int flags" +.Ft int +.Fn bus_dmamap_load_ccb "bus_dma_tag_t dmat" "bus_dmamap_t map" \ +"union ccb *ccb" "bus_dmamap_callback_t *callback" "void *callback_arg" \ +"int flags" +.Ft int +.Fn bus_dmamap_load_crp "bus_dma_tag_t dmat" "bus_dmamap_t map" \ +"struct crypto *crp" "bus_dmamap_callback_t *callback" "void *callback_arg" \ +"int flags" +.Ft int +.Fn bus_dmamap_load_crp_buffer "bus_dma_tag_t dmat" "bus_dmamap_t map" \ +"struct crypto_buffer *cb" "bus_dmamap_callback_t *callback" \ +"void *callback_arg" "int flags" +.Ft int +.Fn bus_dmamap_load_mbuf "bus_dma_tag_t dmat" "bus_dmamap_t map" \ +"struct mbuf *mbuf" "bus_dmamap_callback2_t *callback" "void *callback_arg" \ +"int flags" +.Ft int +.Fn bus_dmamap_load_mbuf_sg "bus_dma_tag_t dmat" "bus_dmamap_t map" \ +"struct mbuf *mbuf" "bus_dma_segment_t *segs" "int *nsegs" "int flags" +.Ft int +.Fn bus_dmamap_load_uio "bus_dma_tag_t dmat" "bus_dmamap_t map" \ +"struct uio *uio" "bus_dmamap_callback2_t *callback" "void *callback_arg" \ +"int flags" +.Ft void +.Fn bus_dmamap_unload "bus_dma_tag_t dmat" "bus_dmamap_t map" +.Ft void +.Fn bus_dmamap_sync "bus_dma_tag_t dmat" "bus_dmamap_t map" \ +"op" +.Ft int +.Fn bus_dmamem_alloc "bus_dma_tag_t dmat" "void **vaddr" \ +"int flags" "bus_dmamap_t *mapp" +.Ft void +.Fn bus_dmamem_free "bus_dma_tag_t dmat" "void *vaddr" \ +"bus_dmamap_t map" +.Sh DESCRIPTION +Direct Memory Access (DMA) is a method of transferring data +without involving the CPU, thus providing higher performance. +A DMA transaction can be achieved between device to memory, +device to device, or memory to memory. +.Pp +The +.Nm +API is a bus, device, and machine-independent (MI) interface to +DMA mechanisms. +It provides the client with flexibility and simplicity by +abstracting machine dependent issues like setting up +DMA mappings, handling cache issues, bus specific features +and limitations. +.Sh OVERVIEW +A tag structure +.Vt ( bus_dma_tag_t ) +is used to describe the properties of a group of related DMA +transactions. +One way to view this is that a tag describes the limitations of a DMA engine. +For example, if a DMA engine in a device is limited to 32-bit addresses, +that limitation is specified by a parameter when creating the tag +for that device. +Similarly, a tag can be marked as requiring buffers whose addresses are +aligned to a specific boundary. +.Pp +Some devices may require multiple tags to describe DMA +transactions with differing properties. +For example, a device might require 16-byte alignment of its descriptor ring +while permitting arbitrary alignment of I/O buffers. +In this case, +the driver must create one tag for the descriptor ring and a separate tag for +I/O buffers. +If a device has restrictions that are common to all DMA transactions +in addition to restrictions that differ between unrelated groups of +transactions, +the driver can first create a +.Dq parent +tag that describes the common restrictions. +The per-group tags can then inherit these restrictions from this +.Dq parent +tag rather than having to list them explicitly when creating the per-group tags. +.Pp +A mapping structure +.Vt ( bus_dmamap_t ) +represents a mapping of a memory region for DMA. +On systems with I/O MMUs, +the mapping structure tracks any I/O MMU entries used by a request. +For DMA requests that require bounce pages, +the mapping tracks the bounce pages used. +.Pp +To prepare for one or more DMA transactions, +a mapping must be bound to a memory region by calling one of the +.Fn bus_dmamap_load +functions. +These functions configure the mapping which can include programming entries +in an I/O MMU and/or allocating bounce pages. +An output of these functions +(either directly or indirectly by invoking a callback routine) +is the list of scatter/gather address ranges a consumer can pass to a DMA +engine to access the memory region. +When a mapping is no longer needed, +the mapping must be unloaded via +.Fn bus_dmamap_unload . +.Pp +Before and after each DMA transaction, +.Fn bus_dmamap_sync +must be used to ensure that the correct data is used by the DMA engine and +the CPU. +If a mapping uses bounce pages, +the sync operations copy data between the bounce pages and the memory region +bound to the mapping. +Sync operations also handle architecture-specific details such as CPU cache +flushing and CPU memory operation ordering. +.Sh STATIC VS DYNAMIC +.Nm +handles two types of DMA transactions: static and dynamic. +Static transactions are used with a long-lived memory region that is reused +for many transactions such as a descriptor ring. +Dynamic transactions are used for transfers to or from transient buffers +such as I/O buffers holding a network packet or disk block. +Each transaction type uses a different subset of the +.Nm +API. +.Ss Static Transactions +Static transactions use memory regions allocated by +.Nm . +Each static memory region is allocated by calling +.Fn bus_dmamem_alloc . +This function requires a valid tag describing the properties of the +DMA transactions to this region such as alignment or address restrictions. +Multiple regions can share a single tag if they share the same restrictions. +.Pp +.Fn bus_dmamem_alloc +allocates a memory region along with a mapping object. +The associated tag, memory region, and mapping object must then be passed to +.Fn bus_dmamap_load +to bind the mapping to the allocated region and obtain the +scatter/gather list. +.Pp +It is expected that +.Fn bus_dmamem_alloc +will attempt to allocate memory requiring less expensive sync operations +(for example, implementations should not allocate regions requiring bounce +pages), +but sync operations should still be used. +For example, a driver should use +.Fn bus_dmamap_sync +in an interrupt handler before reading descriptor ring entries written by the +device prior to the interrupt. +.Pp +When a consumer is finished with a memory region, +it should unload the mapping via +.Fn bus_dmamap_unload +and then release the memory region and mapping object via +.Fn bus_dmamem_free . +.Ss Dynamic Transactions +Dynamic transactions map memory regions provided by other parts of the system. +A tag must be created via +.Fn bus_dma_tag_create +to describe the DMA transactions to and from these memory regions, +and a pool of mapping objects must be allocated via +.Fn bus_dmamap_create +to track the mappings of any in-flight transactions. +.Pp +When a consumer wishes to schedule a transaction for a memory region, +the consumer must first obtain an unused mapping object from its pool +of mapping objects. +The memory region must be bound to the mapping object via one of the +.Fn bus_dmamap_load +functions. +Before scheduling the transaction, +the consumer should sync the memory region via +.Fn bus_dmamap_sync +with one or more of the +.Dq PRE +flags. +After the transaction has completed, +the consumer should sync the memory region via +.Fn bus_dmamap_sync +with one or more of the +.Dq POST +flags. +The mapping can then be unloaded via +.Fn bus_dmamap_unload , +and the mapping object can be returned to the pool of unused mapping objects. +.Pp +When a consumer is no longer scheduling DMA transactions, +the mapping objects should be freed via +.Fn bus_dmamap_destroy , +and the tag should be freed via +.Fn bus_dma_tag_destroy . +.Sh STRUCTURES AND TYPES +.Bl -tag -width indent +.It Vt bus_dma_tag_t +A machine-dependent (MD) opaque type that describes the +characteristics of a group of DMA transactions. +DMA tags are organized into a hierarchy, with each child +tag inheriting the restrictions of its parent. +This allows all devices along the path of DMA transactions +to contribute to the constraints of those transactions. +.It Vt bus_dma_template_t +A template is a structure for creating a +.Fa bus_dma_tag_t +from a set of defaults. +Once initialized with +.Fn bus_dma_template_init , +a driver can over-ride individual fields to suit its needs. +The following fields start with the indicated default values: +.Bd -literal + alignment 1 + boundary 0 + lowaddr BUS_SPACE_MAXADDR + highaddr BUS_SPACE_MAXADDR + maxsize BUS_SPACE_MAXSIZE + nsegments BUS_SPACE_UNRESTRICTED + maxsegsize BUS_SPACE_MAXSIZE + flags 0 + lockfunc NULL + lockfuncarg NULL +.Ed +.Pp +Descriptions of each field are documented with +.Fn bus_dma_tag_create . +Note that the +.Fa filtfunc +and +.Fa filtfuncarg +attributes of the DMA tag are not supported with templates. +.It Vt bus_dma_filter_t +Client specified address filter having the format: +.Bl -tag -width indent +.It Ft int +.Fn "client_filter" "void *filtarg" "bus_addr_t testaddr" +.El +.Pp +Address filters can be specified during tag creation to allow +for devices whose DMA address restrictions cannot be specified +by a single window. +The +.Fa filtarg +argument is specified by the client during tag creation to be passed to all +invocations of the callback. +The +.Fa testaddr +argument contains a potential starting address of a DMA mapping. +The filter function operates on the set of addresses from +.Fa testaddr +to +.Ql trunc_page(testaddr) + PAGE_SIZE - 1 , +inclusive. +The filter function should return zero if any mapping in this range +can be accommodated by the device and non-zero otherwise. +.Pp +.Em Note: The use of filters is no longer supported and will result in an error. +.It Vt bus_dma_segment_t +A machine-dependent type that describes individual +DMA segments. +It contains the following fields: +.Bd -literal + bus_addr_t ds_addr; + bus_size_t ds_len; +.Ed +.Pp +The +.Fa ds_addr +field contains the device visible address of the DMA segment, and +.Fa ds_len +contains the length of the DMA segment. +Although the DMA segments returned by a mapping call will adhere to +all restrictions necessary for a successful DMA operation, some conversion +(e.g.\& a conversion from host byte order to the device's byte order) is +almost always required when presenting segment information to the device. +.It Vt bus_dmamap_t +A machine-dependent opaque type describing an individual mapping. +One map is used for each memory allocation that will be loaded. +Maps can be reused once they have been unloaded. +Multiple maps can be associated with one DMA tag. +While the value of the map may evaluate to +.Dv NULL +on some platforms under certain conditions, +it should never be assumed that it will be +.Dv NULL +in all cases. +.It Vt bus_dmamap_callback_t +Client specified callback for receiving mapping information resulting from +the load of a +.Vt bus_dmamap_t +via +.Fn bus_dmamap_load , +.Fn bus_dmamap_load_bio , +.Fn bus_dmamap_load_ccb , +.Fn bus_dmamap_load_crp , +or +.Fn bus_dmamap_load_crp_buffer . +Callbacks are of the format: +.Bl -tag -width indent +.It Ft void +.Fn "client_callback" "void *callback_arg" "bus_dma_segment_t *segs" \ +"int nseg" "int error" +.El +.Pp +The +.Fa callback_arg +is the callback argument passed to dmamap load functions. +The +.Fa segs +and +.Fa nseg +arguments describe an array of +.Vt bus_dma_segment_t +structures that represent the mapping. +This array is only valid within the scope of the callback function. +The success or failure of the mapping is indicated by the +.Fa error +argument. +More information on the use of callbacks can be found in the +description of the individual dmamap load functions. +.It Vt bus_dmamap_callback2_t +Client specified callback for receiving mapping information resulting from +the load of a +.Vt bus_dmamap_t +via +.Fn bus_dmamap_load_uio +or +.Fn bus_dmamap_load_mbuf . +.Pp +Callback2s are of the format: +.Bl -tag -width indent +.It Ft void +.Fn "client_callback2" "void *callback_arg" "bus_dma_segment_t *segs" \ +"int nseg" "bus_size_t mapsize" "int error" +.El +.Pp +Callback2's behavior is the same as +.Vt bus_dmamap_callback_t +with the addition that the length of the data mapped is provided via +.Fa mapsize . +.It Vt bus_dmasync_op_t +Memory synchronization operation specifier. +Bus DMA requires explicit synchronization of memory with its device +visible mapping in order to guarantee memory coherency. +The +.Vt bus_dmasync_op_t +allows the type of DMA operation that will be or has been performed +to be communicated to the system so that the correct coherency measures +are taken. +The operations are represented as bitfield flags that can be combined together, +though it only makes sense to combine PRE flags or POST flags, not both. +See the +.Fn bus_dmamap_sync +description below for more details on how to use these operations. +.Pp +All operations specified below are performed from the host memory point of view, +where a read implies data coming from the device to the host memory, and a write +implies data going from the host memory to the device. +Alternatively, the operations can be thought of in terms of driver operations, +where reading a network packet or storage sector corresponds to a read operation +in +.Nm . +.Bl -tag -width ".Dv BUS_DMASYNC_POSTWRITE" +.It Dv BUS_DMASYNC_PREREAD +Perform any synchronization required prior to an update of host memory by the +device. +.It Dv BUS_DMASYNC_PREWRITE +Perform any synchronization required after an update of host memory by the CPU +and prior to device access to host memory. +.It Dv BUS_DMASYNC_POSTREAD +Perform any synchronization required after an update of host memory by the +device and prior to CPU access to host memory. +.It Dv BUS_DMASYNC_POSTWRITE +Perform any synchronization required after device access to host memory. +.El +.It Vt bus_dma_lock_t +Client specified lock/mutex manipulation method. +This will be called from +within busdma whenever a client lock needs to be manipulated. +In its current form, the function will be called immediately before +the callback for a DMA load operation that has been deferred with +.Dv BUS_DMA_LOCK +and immediately after with +.Dv BUS_DMA_UNLOCK . +If the load operation does not need to be deferred, then it +will not be called since the function loading the map should +be holding the appropriate locks. +This method is of the format: +.Bl -tag -width indent +.It Ft void +.Fn "lockfunc" "void *lockfunc_arg" "bus_dma_lock_op_t op" +.El +.Pp +The +.Fa lockfuncarg +argument is specified by the client during tag creation to be passed to all +invocations of the callback. +The +.Fa op +argument specifies the lock operation to perform. +.Pp +Two +.Vt lockfunc +implementations are provided for convenience. +.Fn busdma_lock_mutex +performs standard mutex operations on the sleep mutex provided via +.Fa lockfuncarg . +.Fn dflt_lock +will generate a system panic if it is called. +It is substituted into the tag when +.Fa lockfunc +is passed as +.Dv NULL +to +.Fn bus_dma_tag_create +and is useful for tags that should not be used with deferred load operations. +.It Vt bus_dma_lock_op_t +Operations to be performed by the client-specified +.Fn lockfunc . +.Bl -tag -width ".Dv BUS_DMA_UNLOCK" +.It Dv BUS_DMA_LOCK +Acquires and/or locks the client locking primitive. +.It Dv BUS_DMA_UNLOCK +Releases and/or unlocks the client locking primitive. +.El +.El +.Sh FUNCTIONS +.Bl -tag -width indent +.It Fn bus_dma_tag_create "parent" "alignment" "boundary" "lowaddr" \ +"highaddr" "*filtfunc" "*filtfuncarg" "maxsize" "nsegments" "maxsegsz" \ +"flags" "lockfunc" "lockfuncarg" "*dmat" +Allocates a DMA tag, and initializes it according to +the arguments provided: +.Bl -tag -width ".Fa filtfuncarg" +.It Fa parent +A parent tag from which to inherit restrictions. +The restrictions passed in other arguments can only further tighten the +restrictions inherited from the parent tag. +.Pp +All tags created by a device driver must inherit from the tag returned by +.Fn bus_get_dma_tag +to honor restrictions between the parent bridge, CPU memory, and the +device. +.It Fa alignment +Alignment constraint, in bytes, of any mappings created using this tag. +The alignment must be a power of 2. +Hardware that can DMA starting at any address would specify +.Em 1 +for byte alignment. +Hardware requiring DMA transfers to start on a multiple of 4K +would specify +.Em 4096 . +.It Fa boundary +Boundary constraint, in bytes, of the target DMA memory region. +The boundary indicates the set of addresses, all multiples of the +boundary argument, that cannot be crossed by a single +.Vt bus_dma_segment_t . +The boundary must be a power of 2 and must be no smaller than the +maximum segment size. +.Ql 0 +indicates that there are no boundary restrictions. +.It Fa lowaddr , highaddr +Bounds of the window of bus address space that +.Em cannot +be directly accessed by the device. +The window contains all addresses greater than +.Fa lowaddr +and less than or equal to +.Fa highaddr . +For example, a device incapable of DMA above 4GB, would specify a +.Fa highaddr +of +.Dv BUS_SPACE_MAXADDR +and a +.Fa lowaddr +of +.Dv BUS_SPACE_MAXADDR_32BIT . +Similarly a device that can only perform DMA to addresses below +16MB would specify a +.Fa highaddr +of +.Dv BUS_SPACE_MAXADDR +and a +.Fa lowaddr +of +.Dv BUS_SPACE_MAXADDR_24BIT . +Some implementations require that some region of device visible +address space, overlapping available host memory, be outside the +window. +This area of +.Ql safe memory +is used to bounce requests that would otherwise conflict with +the exclusion window. +.It Fa filtfunc +Formerly the optional filter function; must be +.Dv NULL . +.It Fa filtfuncarg +Must be +.Dv NULL . +.It Fa maxsize +Maximum size, in bytes, of the sum of all segment lengths in a given +DMA mapping associated with this tag. +.It Fa nsegments +Number of discontinuities (scatter/gather segments) allowed +in a DMA mapped region. +.It Fa maxsegsz +Maximum size, in bytes, of a segment in any DMA mapped region associated +with +.Fa dmat . +.It Fa flags +Are as follows: +.Bl -tag -width ".Dv BUS_DMA_ALLOCNOW" +.It Dv BUS_DMA_ALLOCNOW +Pre-allocate enough resources to handle at least one map load operation on +this tag. +If sufficient resources are not available, +.Er ENOMEM +is returned. +This should not be used for tags that only describe buffers that will be +allocated with +.Fn bus_dmamem_alloc . +Also, due to resource sharing with other tags, this flag does not guarantee +that resources will be allocated or reserved exclusively for this tag. +It should be treated only as a minor optimization. +.It Dv BUS_DMA_COHERENT +Indicate that the DMA engine and CPU are cache-coherent. +Cached memory may be used to back allocations created by +.Fn bus_dmamem_alloc . +For +.Fn bus_dma_tag_create , +the +.Dv BUS_DMA_COHERENT +flag is currently implemented on arm64. +.El +.It Fa lockfunc +Optional lock manipulation function (may be +.Dv NULL ) +to be called when busdma +needs to manipulate a lock on behalf of the client. +If +.Dv NULL +is specified, +.Fn dflt_lock +is used. +.It Fa lockfuncarg +Optional argument to be passed to the function specified by +.Fa lockfunc . +.It Fa dmat +Pointer to a bus_dma_tag_t where the resulting DMA tag will +be stored. +.El +.Pp +Returns +.Er ENOMEM +if sufficient memory is not available for tag creation +or allocating mapping resources. +Returns +.Er EINVAL +if either +.Fa filtfunc +or +.Fa filtarg +arguments are not +.Dv NULL . +.It Fn bus_dma_tag_destroy "dmat" +Deallocate the DMA tag +.Fa dmat +that was created by +.Fn bus_dma_tag_create . +.Pp +Returns +.Er EBUSY +if any DMA maps remain associated with +.Fa dmat +or +.Ql 0 +on success. +.It Fn bus_dma_template_init "*template" "parent" +Initializes a +.Fa bus_dma_template_t +structure. +If the +.Fa parent +argument is non-NULL, this parent tag is associated with the template and +will be compiled into the dma tag that is later created. +The values of the parent are not copied into the template. +During tag creation in +.Fn bus_dma_tag_template , +any parameters from the parent tag that are more restrictive than what is +in the provided template will overwrite what goes into the new tag. +.It Fn bus_dma_template_tag "*template" "*dmat" +Unpacks a template into a tag, and returns the tag via the +.Fa dmat . +All return values are identical to +.Fn bus_dma_tag_create . +The template is not modified by this function, and can be reused and/or +freed upon return. +.It Fn bus_dma_template_clone "*template" "dmat" +Copies the fields from an existing tag to a template. +The template does not need to be initialized first. +All of its fields will be overwritten by the values contained in the tag. +When paired with +.Fn bus_dma_template_tag , +this function is useful for creating copies of tags. +.It Fn bus_dma_template_fill "*template" "params[]" "count" +Fills in the selected fields of the template with the keyed values from the +.Fa params +array. +This is not meant to be called directly, use +.Fn BUS_DMA_TEMPLATE_FILL +instead. +.It Fn BUS_DMA_TEMPLATE_FILL "*template" "param ..." +Fills in the selected fields of the template with a variable number of +key-value parameters. +The macros listed below take an argument of the specified type and encapsulate +it into a key-value structure that is directly usable as a parameter argument. +Multiple parameters may be provided at once. +.Bd -literal + BD_PARENT() void * + BD_ALIGNMENT() uintmax_t + BD_BOUNDARY() uintmax_t + BD_LOWADDR() vm_paddr_t + BD_HIGHADDR() vm_paddr_t + BD_MAXSIZE() uintmax_t + BD_NSEGMENTS() uintmax_t + BD_MAXSEGSIZE() uintmax_t + BD_FLAGS() uintmax_t + BD_LOCKFUNC() void * + BD_LOCKFUNCARG() void * +.Ed +.It Fn bus_dmamap_create "dmat" "flags" "*mapp" +Allocates and initializes a DMA map. +Arguments are as follows: +.Bl -tag -width ".Fa nsegments" +.It Fa dmat +DMA tag. +.It Fa flags +Are as follows: +.Bl -tag -width ".Dv BUS_DMA_COHERENT" +.It Dv BUS_DMA_COHERENT +Attempt to map the memory loaded with this map such that cache sync +operations are as cheap as possible. +This flag is typically set on maps when the memory loaded with these will +be accessed by both a CPU and a DMA engine, frequently such as control data +and as opposed to streamable data such as receive and transmit buffers. +Use of this flag does not remove the requirement of using +.Fn bus_dmamap_sync , +but it may reduce the cost of performing these operations. +.El +.It Fa mapp +Pointer to a +.Vt bus_dmamap_t +where the resulting DMA map will be stored. +.El +.Pp +Returns +.Er ENOMEM +if sufficient memory is not available for creating the +map or allocating mapping resources. +.It Fn bus_dmamap_destroy "dmat" "map" +Frees all resources associated with a given DMA map. +Arguments are as follows: +.Bl -tag -width ".Fa dmat" +.It Fa dmat +DMA tag used to allocate +.Fa map . +.It Fa map +The DMA map to destroy. +.El +.Pp +Returns +.Er EBUSY +if a mapping is still active for +.Fa map . +.It Fn bus_dmamap_load "dmat" "map" "buf" "buflen" "*callback" \ +"callback_arg" "flags" +Creates a mapping in device visible address space of +.Fa buflen +bytes of +.Fa buf , +associated with the DMA map +.Fa map . +This call will always return immediately and will not block for any reason. +Arguments are as follows: +.Bl -tag -width ".Fa buflen" +.It Fa dmat +DMA tag used to allocate +.Fa map . +.It Fa map +A DMA map without a currently active mapping. +.It Fa buf +A kernel virtual address pointer to a contiguous (in KVA) buffer, to be +mapped into device visible address space. +.It Fa buflen +The size of the buffer. +.It Fa callback Fa callback_arg +The callback function, and its argument. +This function is called once sufficient mapping resources are available for +the DMA operation. +If resources are temporarily unavailable, this function will be deferred until +later, but the load operation will still return immediately to the caller. +Thus, callers should not assume that the callback will be called before the +load returns, and code should be structured appropriately to handle this. +See below for specific flags and error codes that control this behavior. +.It Fa flags +Are as follows: +.Bl -tag -width ".Dv BUS_DMA_NOWAIT" +.It Dv BUS_DMA_NOWAIT +The load should not be deferred in case of insufficient mapping resources, +and instead should return immediately with an appropriate error. +.It Dv BUS_DMA_NOCACHE +The generated transactions to and from the virtual page are non-cacheable. +.El +.El +.Pp +Return values to the caller are as follows: +.Bl -tag -width ".Er EINPROGRESS" +.It 0 +The callback has been called and completed. +The status of the mapping has been delivered to the callback. +.It Er EINPROGRESS +The mapping has been deferred for lack of resources. +The callback will be called as soon as resources are available. +Callbacks are serviced in FIFO order. +.Pp +Note that subsequent load operations for the same tag that do not require +extra resources will still succeed. +This may result in out-of-order processing of requests. +If the caller requires the order of requests to be preserved, +then the caller is required to stall subsequent requests until a pending +request's callback is invoked. +.It Er ENOMEM +The load request has failed due to insufficient resources, and the caller +specifically used the +.Dv BUS_DMA_NOWAIT +flag. +.It Er EINVAL +The load request was invalid. +The callback has been called and has been provided the same error. +This error value may indicate that +.Fa dmat , +.Fa map , +.Fa buf , +or +.Fa callback +were invalid, or +.Fa buflen +was larger than the +.Fa maxsize +argument used to create the dma tag +.Fa dmat . +.El +.Pp +When the callback is called, it is presented with an error value +indicating the disposition of the mapping. +Error may be one of the following: +.Bl -tag -width ".Er EINPROGRESS" +.It 0 +The mapping was successful and the +.Fa dm_segs +callback argument contains an array of +.Vt bus_dma_segment_t +elements describing the mapping. +This array is only valid during the scope of the callback function. +.It Er EFBIG +A mapping could not be achieved within the segment constraints provided +in the tag even though the requested allocation size was less than maxsize. +.El +.It Fn bus_dmamap_load_bio "dmat" "map" "bio" "callback" "callback_arg" "flags" +This is a variation of +.Fn bus_dmamap_load +which maps buffers pointed to by +.Fa bio +for DMA transfers. +.Fa bio +may point to either a mapped or unmapped buffer. +.It Fn bus_dmamap_load_ccb "dmat" "map" "ccb" "callback" "callback_arg" "flags" +This is a variation of +.Fn bus_dmamap_load +which maps data pointed to by +.Fa ccb +for DMA transfers. +The data for +.Fa ccb +may be any of the following types: +.Bl -tag -width ".Er CAM_DATA_SG_PADDR" +.It CAM_DATA_VADDR +The data is a single KVA buffer. +.It CAM_DATA_PADDR +The data is a single bus address range. +.It CAM_DATA_SG +The data is a scatter/gather list of KVA buffers. +.It CAM_DATA_SG_PADDR +The data is a scatter/gather list of bus address ranges. +.It CAM_DATA_BIO +The data is contained in a +.Vt struct bio +attached to the CCB. +.El +.Pp +.Fn bus_dmamap_load_ccb +supports the following CCB XPT function codes: +.Pp +.Bl -item -offset indent -compact +.It +XPT_ATA_IO +.It +XPT_CONT_TARGET_IO +.It +XPT_SCSI_IO +.El +.It Fn bus_dmamap_load_crp "dmat" "map" "crp" "callback" "callback_arg" "flags" +This is a variation of +.Fn bus_dmamap_load +which maps the input buffer pointed to by +.Fa crp +for DMA transfers. +The +.Dv BUS_DMA_NOWAIT +flag is implied, thus no callback deferral will happen. +.It Fn bus_dmamap_load_crp_buffer "dmat" "map" "cb" "callback" "callback_arg" \ +"flags" +This is a variation of +.Fn bus_dmamap_load +which maps the crypto data buffer pointed to by +.Fa cb +for DMA transfers. +The +.Dv BUS_DMA_NOWAIT +flag is implied, thus no callback deferral will happen. +.It Fn bus_dmamap_load_mbuf "dmat" "map" "mbuf" "callback2" "callback_arg" \ +"flags" +This is a variation of +.Fn bus_dmamap_load +which maps mbuf chains +for DMA transfers. +A +.Vt bus_size_t +argument is also passed to the callback routine, which +contains the mbuf chain's packet header length. +The +.Dv BUS_DMA_NOWAIT +flag is implied, thus no callback deferral will happen. +.Pp +Mbuf chains are assumed to be in kernel virtual address space. +.Pp +Beside the error values listed for +.Fn bus_dmamap_load , +.Er EINVAL +will be returned if the size of the mbuf chain exceeds the maximum limit of the +DMA tag. +.It Fn bus_dmamap_load_mbuf_sg "dmat" "map" "mbuf" "segs" "nsegs" "flags" +This is just like +.Fn bus_dmamap_load_mbuf +except that it returns immediately without calling a callback function. +It is provided for efficiency. +The scatter/gather segment array +.Va segs +is provided by the caller and filled in directly by the function. +The +.Va nsegs +argument is returned with the number of segments filled in. +Returns the same errors as +.Fn bus_dmamap_load_mbuf . +.It Fn bus_dmamap_load_uio "dmat" "map" "uio" "callback2" "callback_arg" "flags" +This is a variation of +.Fn bus_dmamap_load +which maps buffers pointed to by +.Fa uio +for DMA transfers. +A +.Vt bus_size_t +argument is also passed to the callback routine, which contains the size of +.Fa uio , +i.e. +.Fa uio->uio_resid . +The +.Dv BUS_DMA_NOWAIT +flag is implied, thus no callback deferral will happen. +Returns the same errors as +.Fn bus_dmamap_load . +.Pp +If +.Fa uio->uio_segflg +is +.Dv UIO_USERSPACE , +then it is assumed that the buffer, +.Fa uio +is in +.Fa "uio->uio_td->td_proc" Ns 's +address space. +User space memory must be in-core and wired prior to attempting a map +load operation. +Pages may be locked using +.Xr vslock 9 . +.It Fn bus_dmamap_unload "dmat" "map" +Unloads a DMA map. +Arguments are as follows: +.Bl -tag -width ".Fa dmam" +.It Fa dmat +DMA tag used to allocate +.Fa map . +.It Fa map +The DMA map that is to be unloaded. +.El +.Pp +.Fn bus_dmamap_unload +will not perform any implicit synchronization of DMA buffers. +This must be done explicitly by a call to +.Fn bus_dmamap_sync +prior to unloading the map. +.It Fn bus_dmamap_sync "dmat" "map" "op" +Performs synchronization of a device visible mapping with the CPU visible +memory referenced by that mapping. +Arguments are as follows: +.Bl -tag -width ".Fa dmat" +.It Fa dmat +DMA tag used to allocate +.Fa map . +.It Fa map +The DMA mapping to be synchronized. +.It Fa op +Type of synchronization operation to perform. +See the definition of +.Vt bus_dmasync_op_t +for a description of the acceptable values for +.Fa op . +.El +.Pp +The +.Fn bus_dmamap_sync +function +is the method used to ensure that CPU's and device's direct +memory access (DMA) to shared +memory is coherent. +For example, the CPU might be used to set up the contents of a buffer +that is to be made available to a device. +To ensure that the data are visible via the device's mapping of that +memory, the buffer must be loaded and a DMA sync operation of +.Dv BUS_DMASYNC_PREWRITE +must be performed after the CPU has updated the buffer and before the device +access is initiated. +If the CPU modifies this buffer again later, another +.Dv BUS_DMASYNC_PREWRITE +sync operation must be performed before an additional device +access. +Conversely, suppose a device updates memory that is to be read by a CPU. +In this case, the buffer must be loaded, and a DMA sync operation of +.Dv BUS_DMASYNC_PREREAD +must be performed before the device access is initiated. +The CPU will only be able to see the results of this memory update +once the DMA operation has completed and a +.Dv BUS_DMASYNC_POSTREAD +sync operation has been performed. +.Pp +If read and write operations are not preceded and followed by the +appropriate synchronization operations, behavior is undefined. +.It Fn bus_dmamem_alloc "dmat" "**vaddr" "flags" "*mapp" +Allocates memory that is mapped into KVA at the address returned +in +.Fa vaddr +and that is permanently loaded into the newly created +.Vt bus_dmamap_t +returned via +.Fa mapp . +Arguments are as follows: +.Bl -tag -width ".Fa alignment" +.It Fa dmat +DMA tag describing the constraints of the DMA mapping. +.It Fa vaddr +Pointer to a pointer that will hold the returned KVA mapping of +the allocated region. +.It Fa flags +Flags are defined as follows: +.Bl -tag -width ".Dv BUS_DMA_NOWAIT" +.It Dv BUS_DMA_WAITOK +The routine can safely wait (sleep) for resources. +.It Dv BUS_DMA_NOWAIT +The routine is not allowed to wait for resources. +If resources are not available, +.Dv ENOMEM +is returned. +.It Dv BUS_DMA_COHERENT +Attempt to map this memory in a coherent fashion. +See +.Fn bus_dmamap_create +above for a description of this flag. +For +.Fn bus_dmamem_alloc , +the +.Dv BUS_DMA_COHERENT +flag is currently implemented on arm and arm64. +.It Dv BUS_DMA_ZERO +Causes the allocated memory to be set to all zeros. +.It Dv BUS_DMA_NOCACHE +The allocated memory will not be cached in the processor caches. +All memory accesses appear on the bus and are executed +without reordering. +For +.Fn bus_dmamem_alloc , +the +.Dv BUS_DMA_NOCACHE +flag is currently implemented on amd64 and i386 where it results in the +Strong Uncacheable PAT to be set for the allocated virtual address range. +.El +.It Fa mapp +Pointer to a +.Vt bus_dmamap_t +where the resulting DMA map will be stored. +.El +.Pp +The size of memory to be allocated is +.Fa maxsize +as specified in the call to +.Fn bus_dma_tag_create +for +.Fa dmat . +.Pp +The current implementation of +.Fn bus_dmamem_alloc +will allocate all requests as a single segment. +.Pp +An initial load operation is required to obtain the bus address of the allocated +memory, and an unload operation is required before freeing the memory, as +described below in +.Fn bus_dmamem_free . +Maps are automatically handled by this function and should not be explicitly +allocated or destroyed. +.Pp +Although an explicit load is not required for each access to the memory +referenced by the returned map, the synchronization requirements +as described in the +.Fn bus_dmamap_sync +section still apply and should be used to achieve portability on architectures +without coherent buses. +.Pp +Returns +.Er ENOMEM +if sufficient memory is not available for completing +the operation. +.It Fn bus_dmamem_free "dmat" "*vaddr" "map" +Frees memory previously allocated by +.Fn bus_dmamem_alloc . +Any mappings +will be invalidated. +Arguments are as follows: +.Bl -tag -width ".Fa vaddr" +.It Fa dmat +DMA tag. +.It Fa vaddr +Kernel virtual address of the memory. +.It Fa map +DMA map to be invalidated. +.El +.El +.Sh RETURN VALUES +Behavior is undefined if invalid arguments are passed to +any of the above functions. +If sufficient resources cannot be allocated for a given +transaction, +.Er ENOMEM +is returned. +All +routines that are not of type +.Vt void +will return 0 on success or an error +code on failure as discussed above. +.Pp +All +.Vt void +routines will succeed if provided with valid arguments. +.Sh LOCKING +Two locking protocols are used by +.Nm . +The first is a private global lock that is used to synchronize access to the +bounce buffer pool on the architectures that make use of them. +This lock is strictly a leaf lock that is only used internally to +.Nm +and is not exposed to clients of the API. +.Pp +The second protocol involves protecting various resources stored in the tag. +Since almost all +.Nm +operations are done through requests from the driver that created the tag, +the most efficient way to protect the tag resources is through the lock that +the driver uses. +In cases where +.Nm +acts on its own without being called by the driver, the lock primitive +specified in the tag is acquired and released automatically. +An example of this is when the +.Fn bus_dmamap_load +callback function is called from a deferred context instead of the driver +context. +This means that certain +.Nm +functions must always be called with the same lock held that is specified in the +tag. +These functions include: +.Pp +.Bl -item -offset indent -compact +.It +.Fn bus_dmamap_load +.It +.Fn bus_dmamap_load_bio +.It +.Fn bus_dmamap_load_ccb +.It +.Fn bus_dmamap_load_mbuf +.It +.Fn bus_dmamap_load_mbuf_sg +.It +.Fn bus_dmamap_load_uio +.It +.Fn bus_dmamap_unload +.It +.Fn bus_dmamap_sync +.El +.Pp +There is one exception to this rule. +It is common practice to call some of these functions during driver start-up +without any locks held. +So long as there is a guarantee of no possible concurrent use of the tag by +different threads during this operation, it is safe to not hold a lock for +these functions. +.Pp +Certain +.Nm +operations should not be called with the driver lock held, either because +they are already protected by an internal lock, or because they might sleep +due to memory or resource allocation. +The following functions must not be +called with any non-sleepable locks held: +.Pp +.Bl -item -offset indent -compact +.It +.Fn bus_dma_tag_create +.It +.Fn bus_dmamap_create +.It +.Fn bus_dmamem_alloc +.El +.Pp +All other functions do not have a locking protocol and can thus be +called with or without any system or driver locks held. +.Sh SEE ALSO +.Xr devclass 9 , +.Xr device 9 , +.Xr driver 9 , +.Xr rman 9 , +.Xr vslock 9 +.Pp +.Rs +.%A "Jason R. Thorpe" +.%T "A Machine-Independent DMA Framework for NetBSD" +.%J "Proceedings of the Summer 1998 USENIX Technical Conference" +.%Q "USENIX Association" +.%D "June 1998" +.Re +.Sh HISTORY +The +.Nm +interface first appeared in +.Nx 1.3 . +.Pp +The +.Nm +API was adopted from +.Nx +for use in the CAM SCSI subsystem. +The alterations to the original API were aimed to remove the need for +a +.Vt bus_dma_segment_t +array stored in each +.Vt bus_dmamap_t +while allowing callers to queue up on scarce resources. +.Sh AUTHORS +The +.Nm +interface was designed and implemented by +.An Jason R. Thorpe +of the Numerical Aerospace Simulation Facility, NASA Ames Research Center. +Additional input on the +.Nm +design was provided by +.An -nosplit +.An Chris Demetriou , +.An Charles Hannum , +.An Ross Harvey , +.An Matthew Jacob , +.An Jonathan Stone , +and +.An Matt Thomas . +.Pp +The +.Nm +interface in +.Fx +benefits from the contributions of +.An Justin T. Gibbs , +.An Peter Wemm , +.An Doug Rabson , +.An Matthew N. Dodd , +.An Sam Leffler , +.An Maxime Henrion , +.An Jake Burkholder , +.An Takahashi Yoshihiro , +.An Scott Long +and many others. +.Pp +This manual page was written by +.An Hiten M. Pandya +and +.An Justin T. Gibbs . diff --git a/static/freebsd/man9/bus_generic_detach.9 b/static/freebsd/man9/bus_generic_detach.9 new file mode 100644 index 00000000..b7a2aa6e --- /dev/null +++ b/static/freebsd/man9/bus_generic_detach.9 @@ -0,0 +1,67 @@ +.\" -*- 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 February 5, 2025 +.Dt BUS_GENERIC_DETACH 9 +.Os +.Sh NAME +.Nm bus_generic_detach +.Nd generic implementation of +.Dv DEVICE_DETACH +for buses +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn bus_generic_detach "device_t dev" +.Sh DESCRIPTION +This function provides an implementation of the +.Xr DEVICE_DETACH 9 +method +which can be used by most bus code. +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 +.An Doug Rabson . diff --git a/static/freebsd/man9/bus_generic_new_pass.9 b/static/freebsd/man9/bus_generic_new_pass.9 new file mode 100644 index 00000000..709f91c3 --- /dev/null +++ b/static/freebsd/man9/bus_generic_new_pass.9 @@ -0,0 +1,55 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2009 Hudson River Trading LLC +.\" Written by: John H. Baldwin +.\" 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 January 15, 2017 +.Dt BUS_GENERIC_NEW_PASS 9 +.Os +.Sh NAME +.Nm bus_generic_new_pass +.Nd "generic implementation of BUS_NEW_PASS for bus devices" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft void +.Fn bus_generic_new_pass "device_t dev" +.Sh DESCRIPTION +This function provides an implementation of the +.Xr BUS_NEW_PASS 9 +method which can be used by bus drivers. +It first invokes the +.Xr DEVICE_IDENTIFY 9 +method for any drivers whose pass level is equal to the new pass level. +Then, for each attached child device it calls +.Xr BUS_NEW_PASS 9 +to rescan child buses, +and for each unattached child device it calls +.Xr device_probe_and_attach 9 . +.Sh SEE ALSO +.Xr BUS_NEW_PASS 9 , +.Xr bus_set_pass 9 , +.Xr device 9 , +.Xr DEVICE_IDENTIFY 9 diff --git a/static/freebsd/man9/bus_generic_print_child.9 b/static/freebsd/man9/bus_generic_print_child.9 new file mode 100644 index 00000000..8a72c8e7 --- /dev/null +++ b/static/freebsd/man9/bus_generic_print_child.9 @@ -0,0 +1,114 @@ +.\" -*- 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 February 5, 2025 +.Dt BUS_GENERIC_PRINT_CHILD 9 +.Os +.Sh NAME +.Nm bus_generic_print_child , +.Nm bus_print_child_domain , +.Nm bus_print_child_footer , +.Nm bus_print_child_header +.Nd generic implementation of +.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 +.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: numa-domain 1 on bar0 +.Ed +.Pp +.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 . +.Pp +.Fn bus_print_child_header +outputs the device name and unit followed by the device description +in angle brackets +.Po +.Dq foo0: +.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 +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 +.An Doug Rabson . diff --git a/static/freebsd/man9/bus_generic_read_ivar.9 b/static/freebsd/man9/bus_generic_read_ivar.9 new file mode 100644 index 00000000..3783de89 --- /dev/null +++ b/static/freebsd/man9/bus_generic_read_ivar.9 @@ -0,0 +1,55 @@ +.\" -*- 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_READ_IVAR 9 +.Os +.Sh NAME +.Nm bus_generic_read_ivar , +.Nm bus_generic_write_ivar +.Nd generic implementation of +.Dv BUS_READ_IVAR +and +.Dv BUS_WRITE_IVAR +for buses +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn bus_generic_read_ivar "device_t dev" "device_t child" "int index" "uintptr_t *result" +.Ft int +.Fn bus_generic_write_ivar "device_t dev" "device_t child" "int index" "uintptr_t value" +.Sh DESCRIPTION +These functions simply return +.Er ENOENT . +.Sh SEE ALSO +.Xr device 9 , +.Xr driver 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/bus_generic_shutdown.9 b/static/freebsd/man9/bus_generic_shutdown.9 new file mode 100644 index 00000000..264a2127 --- /dev/null +++ b/static/freebsd/man9/bus_generic_shutdown.9 @@ -0,0 +1,57 @@ +.\" -*- 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_SHUTDOWN 9 +.Os +.Sh NAME +.Nm bus_generic_shutdown +.Nd generic implementation of +.Dv DEVICE_SHUTDOWN +for buses +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn bus_generic_shutdown "device_t dev" +.Sh DESCRIPTION +This function provides an implementation of the +.Xr DEVICE_SHUTDOWN 9 +method +which can be used by most bus code. +It simply calls the +.Xr DEVICE_SHUTDOWN 9 +method of 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/static/freebsd/man9/bus_get_resource.9 b/static/freebsd/man9/bus_get_resource.9 new file mode 100644 index 00000000..f93a877d --- /dev/null +++ b/static/freebsd/man9/bus_get_resource.9 @@ -0,0 +1,93 @@ +.\" +.\" Copyright (c) 2008 +.\" The DragonFly Project. 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. Neither the name of The DragonFly Project nor the names of its +.\" contributors may be used to endorse or promote products derived +.\" from this software without specific, prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 +.\" COPYRIGHT HOLDERS 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. +.\" +.\" $DragonFly: src/share/man/man9/bus_get_resource.9,v 1.1 2008/11/09 09:48:41 swildner Exp $ +.\" +.Dd September 26, 2015 +.Dt BUS_GET_RESOURCE 9 +.Os +.Sh NAME +.Nm bus_get_resource +.Nd "read a resource range/value with a given resource ID" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.In sys/rman.h +.Ft int +.Fo bus_get_resource +.Fa "device_t dev" "int type" "int rid" "rman_res_t *startp" "rman_res_t *countp" +.Fc +.Sh DESCRIPTION +The +.Fn bus_get_resource +function reads the range or value of the resource +.Fa type , rid +pair and stores it in the +.Fa startp +and +.Fa countp +arguments. +.Pp +The arguments are as follows: +.Bl -tag -width ".Fa startp" +.It Fa dev +The device to read the resource from. +.It Fa type +The type of resource you want to read. +It is one of: +.Pp +.Bl -tag -width ".Dv SYS_RES_MEMORY" -compact +.It Dv SYS_RES_IRQ +for IRQs +.It Dv SYS_RES_DRQ +for ISA DMA lines +.It Dv SYS_RES_MEMORY +for I/O memory +.It Dv SYS_RES_IOPORT +for I/O ports +.El +.It Fa rid +A bus-specific handle that identifies the resource being read. +.It Fa startp +A pointer to the start address of this resource. +.It Fa countp +A pointer to the length of the resource. +For example, the size of the memory in bytes. +.El +.Sh RETURN VALUES +Zero is returned on success, otherwise an error is returned. +.Sh SEE ALSO +.Xr bus_set_resource 9 , +.Xr device 9 , +.Xr driver 9 +.Sh AUTHORS +This manual page was written by +.An Sascha Wildner . diff --git a/static/freebsd/man9/bus_map_resource.9 b/static/freebsd/man9/bus_map_resource.9 new file mode 100644 index 00000000..5cccb815 --- /dev/null +++ b/static/freebsd/man9/bus_map_resource.9 @@ -0,0 +1,153 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2016 John H. Baldwin +.\" +.\" 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 March 13, 2024 +.Dt BUS_MAP_RESOURCE 9 +.Os +.Sh NAME +.Nm bus_map_resource , bus_unmap_resource , resource_init_map_request +.Nd map or unmap an active resource +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Pp +.In machine/bus.h +.In sys/rman.h +.In machine/resource.h +.Ft int +.Fo bus_map_resource +.Fa "device_t dev" "struct resource *r" +.Fa "struct resource_map_request *args" "struct resource_map *map" +.Fc +.Ft int +.Fo bus_unmap_resource +.Fa "device_t dev" "struct resource *r" "struct resource_map *map" +.Fc +.Ft void +.Fn resource_init_map_request "struct resource_map_request *args" +.Sh DESCRIPTION +These functions create or destroy a mapping of a previously activated +resource. +Mappings permit CPU access to the resource via the +.Xr bus_space 9 +API. +.Pp +The arguments are as follows: +.Bl -tag -width indent +.It Fa dev +The device that owns the resource. +.It Fa r +A pointer to the +.Vt "struct resource" +returned by +.Xr bus_alloc_resource 9 . +.It Fa args +A set of optional properties to apply when creating a mapping. +This argument can be set to +.Dv NULL +to request a mapping of the entire resource with the default properties. +.It Fa map +The resource mapping to create or destroy. +.El +.Ss Resource Mappings +Resource mappings are described by a +.Vt "struct resource_map" +object. +This structure contains a +.Xr bus_space 9 +tag and handle in the +.Va r_bustag +and +.Va r_bushandle +members that can be used for CPU access to the mapping. +The structure also contains a +.Va r_vaddr +member which contains the virtual address of the mapping if one exists. +.Pp +The wrapper API for +.Vt "struct resource" +objects described in +.Xr bus_activate_resource 9 +can also be used with +.Vt "struct resource_map" . +For example, +a pointer to a mapping object can be passed as the first argument to +.Fn bus_read_4 . +This wrapper API is preferred over using the +.Va r_bustag +and +.Va r_bushandle +members directly. +.Ss Optional Mapping Properties +The +.Vt "struct resource_map_request" +object passed in +.Fa args +can be used to specify optional properties of a mapping. +The structure must be initialized by invoking +.Fn resource_init_map_request . +Properties are then specified by setting one or more of these members: +.Bl -tag -width indent +.It Va offset , length +These two members specify a region of the resource to map. +By default a mapping is created for the entire resource. +The +.Va offset +is relative to the start of the resource. +.It Va memattr +Specifies a memory attribute to use when mapping the resource. +By default memory mappings use the +.Dv VM_MEMATTR_UNCACHEABLE +attribute. +.El +.Sh RETURN VALUES +Zero is returned on success, otherwise an error is returned. +.Sh EXAMPLES +This maps a PCI memory BAR with the write-combining memory attribute and +reads the first 32-bit word: +.Bd -literal + struct resource *r; + struct resource_map map; + struct resource_map_request req; + uint32_t val; + int rid; + + rid = PCIR_BAR(0); + r = bus_alloc_resource_any(dev, SYS_RES_MEMORY, &rid, RF_ACTIVE | + RF_UNMAPPED); + resource_init_map_request(&req); + req.memattr = VM_MEMATTR_WRITE_COMBINING; + bus_map_resource(dev, SYS_RES_MEMORY, r, &req, &map); + val = bus_read_4(&map, 0); +.Ed +.Sh SEE ALSO +.Xr bus_activate_resource 9 , +.Xr bus_alloc_resource 9 , +.Xr bus_space 9 , +.Xr device 9 , +.Xr driver 9 +.Sh AUTHORS +This manual page was written by +.An John Baldwin Aq Mt jhb@FreeBSD.org . diff --git a/static/freebsd/man9/bus_release_resource.9 b/static/freebsd/man9/bus_release_resource.9 new file mode 100644 index 00000000..5203295a --- /dev/null +++ b/static/freebsd/man9/bus_release_resource.9 @@ -0,0 +1,88 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2000 Alexander Langer +.\" +.\" 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 March 13, 2024 +.Dt BUS_RELEASE_RESOURCE 9 +.Os +.Sh NAME +.Nm bus_release_resource +.Nd release resources on a bus +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Pp +.In machine/bus.h +.In sys/rman.h +.In machine/resource.h +.Ft int +.Fn bus_release_resource "device_t dev" "struct resource *r" +.Sh DESCRIPTION +Free a resource allocated by +.Xr bus_alloc_resource 9 . +The resource must not be in use on release, i.e., call an appropriate function +before (e.g.\& +.Xr bus_teardown_intr 9 +for IRQs). +.Bl -item +.It +.Fa dev +is the device that owns the resource. +.It +.Fa r +is the pointer to +.Va struct resource , +i.e., the resource itself, +returned by +.Xr bus_alloc_resource 9 . +.El +.Sh RETURN VALUES +.Er EINVAL +is returned, if the device +.Fa dev +has no parent, +.Dv 0 +otherwise. +The kernel will panic, if it cannot release the resource. +.Sh EXAMPLES +.Bd -literal + /* deactivate IRQ */ + bus_teardown_intr(dev, foosoftc->irqres, foosoftc->irqid); + + /* release IRQ resource */ + bus_release_resource(dev, foosoftc->irqres); + + /* release I/O port resource */ + bus_release_resource(dev, foosoftc->portres); +.Ed +.Sh SEE ALSO +.Xr bus_alloc_resource 9 , +.Xr device 9 , +.Xr driver 9 +.Sh AUTHORS +This manual page was written by +.An Alexander Langer Aq Mt alex@big.endian.de . diff --git a/static/freebsd/man9/bus_set_pass.9 b/static/freebsd/man9/bus_set_pass.9 new file mode 100644 index 00000000..6c34cc31 --- /dev/null +++ b/static/freebsd/man9/bus_set_pass.9 @@ -0,0 +1,52 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2009 Hudson River Trading LLC +.\" Written by: John H. Baldwin +.\" 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 June 8, 2009 +.Dt BUS_SET_PASS 9 +.Os +.Sh NAME +.Nm bus_set_pass +.Nd "raise the bus pass level" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft void +.Fn bus_set_pass "int pass" +.Sh DESCRIPTION +The +.Nm +function is called during boot to raise the bus pass level to +.Fa pass . +The function will rescan the device tree for each pass level between the +current pass level and the new level that has at least one associated +driver. +The device tree rescans are implemented by invoking the +.Xr BUS_NEW_PASS 9 +method on the root bus device. +.Sh SEE ALSO +.Xr BUS_NEW_PASS 9 , +.Xr device 9 diff --git a/static/freebsd/man9/bus_set_resource.9 b/static/freebsd/man9/bus_set_resource.9 new file mode 100644 index 00000000..06f1da9f --- /dev/null +++ b/static/freebsd/man9/bus_set_resource.9 @@ -0,0 +1,90 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2003 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 March 29, 2003 +.Dt BUS_SET_RESOURCE 9 +.Os +.Sh NAME +.Nm bus_set_resource +.Nd "associate a definite resource with a given resource ID" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Pp +.In machine/bus.h +.In sys/rman.h +.In machine/resource.h +.Ft int +.Fo bus_set_resource +.Fa "device_t dev" "int type" "int rid" "rman_res_t start" "rman_res_t count" +.Fc +.Sh DESCRIPTION +The +.Fn bus_set_resource +function +sets the start address of the resource +.Fa type , rid +pair to be +.Fa count +long. +Typically, client drivers do not use this interface. +Bus drivers, however, often use it to set up the resources a client +driver uses. +.Pp +The arguments are as follows: +.Bl -tag -width indent +.It Fa dev +The device to set the resource on. +.It Fa type +The type of resource you want to allocate. +It is one of: +.Pp +.Bl -tag -width ".Dv SYS_RES_MEMORY" -compact +.It Dv SYS_RES_IRQ +for IRQs +.It Dv SYS_RES_DRQ +for ISA DMA lines +.It Dv SYS_RES_IOPORT +for I/O ports +.It Dv SYS_RES_MEMORY +for I/O memory +.El +.It Fa rid +A bus-specific handle that identifies the resource being allocated. +.It Fa start +The start address of this resource. +.It Fa count +The length of the resource. +For example, the size of the memory in bytes. +.El +.Sh RETURN VALUES +Zero is returned on success, otherwise an error is returned. +.Sh SEE ALSO +.Xr bus_alloc_resource 9 , +.Xr bus_get_resource 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/static/freebsd/man9/bus_space.9 b/static/freebsd/man9/bus_space.9 new file mode 100644 index 00000000..12ab5d8d --- /dev/null +++ b/static/freebsd/man9/bus_space.9 @@ -0,0 +1,1866 @@ +.\" $NetBSD: bus_space.9,v 1.9 1999/03/06 22:09:29 mycroft Exp $ +.\" +.\" Copyright (c) 2005 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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. +.\" +.\" +.\" Copyright (c) 1997 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christopher G. Demetriou. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 May 1, 2021 +.Dt BUS_SPACE 9 +.Os +.Sh NAME +.Nm bus_space , +.Nm bus_space_barrier , +.Nm bus_space_copy_region_1 , +.Nm bus_space_copy_region_2 , +.Nm bus_space_copy_region_4 , +.Nm bus_space_copy_region_8 , +.Nm bus_space_copy_region_stream_1 , +.Nm bus_space_copy_region_stream_2 , +.Nm bus_space_copy_region_stream_4 , +.Nm bus_space_copy_region_stream_8 , +.Nm bus_space_free , +.Nm bus_space_map , +.Nm bus_space_peek_1 , +.Nm bus_space_peek_2 , +.Nm bus_space_peek_4 , +.Nm bus_space_peek_8 , +.Nm bus_space_poke_1 , +.Nm bus_space_poke_2 , +.Nm bus_space_poke_4 , +.Nm bus_space_poke_8 , +.Nm bus_space_read_1 , +.Nm bus_space_read_2 , +.Nm bus_space_read_4 , +.Nm bus_space_read_8 , +.Nm bus_space_read_multi_1 , +.Nm bus_space_read_multi_2 , +.Nm bus_space_read_multi_4 , +.Nm bus_space_read_multi_8 , +.Nm bus_space_read_multi_stream_1 , +.Nm bus_space_read_multi_stream_2 , +.Nm bus_space_read_multi_stream_4 , +.Nm bus_space_read_multi_stream_8 , +.Nm bus_space_read_region_1 , +.Nm bus_space_read_region_2 , +.Nm bus_space_read_region_4 , +.Nm bus_space_read_region_8 , +.Nm bus_space_read_region_stream_1 , +.Nm bus_space_read_region_stream_2 , +.Nm bus_space_read_region_stream_4 , +.Nm bus_space_read_region_stream_8 , +.Nm bus_space_read_stream_1 , +.Nm bus_space_read_stream_2 , +.Nm bus_space_read_stream_4 , +.Nm bus_space_read_stream_8 , +.Nm bus_space_set_multi_1 , +.Nm bus_space_set_multi_2 , +.Nm bus_space_set_multi_4 , +.Nm bus_space_set_multi_8 , +.Nm bus_space_set_multi_stream_1 , +.Nm bus_space_set_multi_stream_2 , +.Nm bus_space_set_multi_stream_4 , +.Nm bus_space_set_multi_stream_8 , +.Nm bus_space_set_region_1 , +.Nm bus_space_set_region_2 , +.Nm bus_space_set_region_4 , +.Nm bus_space_set_region_8 , +.Nm bus_space_set_region_stream_1 , +.Nm bus_space_set_region_stream_2 , +.Nm bus_space_set_region_stream_4 , +.Nm bus_space_set_region_stream_8 , +.Nm bus_space_subregion , +.Nm bus_space_unmap , +.Nm bus_space_write_1 , +.Nm bus_space_write_2 , +.Nm bus_space_write_4 , +.Nm bus_space_write_8 , +.Nm bus_space_write_multi_1 , +.Nm bus_space_write_multi_2 , +.Nm bus_space_write_multi_4 , +.Nm bus_space_write_multi_8 , +.Nm bus_space_write_multi_stream_1 , +.Nm bus_space_write_multi_stream_2 , +.Nm bus_space_write_multi_stream_4 , +.Nm bus_space_write_multi_stream_8 , +.Nm bus_space_write_region_1 , +.Nm bus_space_write_region_2 , +.Nm bus_space_write_region_4 , +.Nm bus_space_write_region_8 , +.Nm bus_space_write_region_stream_1 , +.Nm bus_space_write_region_stream_2 , +.Nm bus_space_write_region_stream_4 , +.Nm bus_space_write_region_stream_8 , +.Nm bus_space_write_stream_1 , +.Nm bus_space_write_stream_2 , +.Nm bus_space_write_stream_4 , +.Nm bus_space_write_stream_8 +.Nd "bus space manipulation functions" +.Sh SYNOPSIS +.In machine/bus.h +.Ft int +.Fo bus_space_map +.Fa "bus_space_tag_t space" "bus_addr_t address" +.Fa "bus_size_t size" "int flags" "bus_space_handle_t *handlep" +.Fc +.Ft void +.Fo bus_space_unmap +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t size" +.Fc +.Ft int +.Fo bus_space_subregion +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" +.Fa "bus_size_t offset" "bus_size_t size" "bus_space_handle_t *nhandlep" +.Fc +.Ft int +.Fo bus_space_alloc +.Fa "bus_space_tag_t space" "bus_addr_t reg_start" "bus_addr_t reg_end" +.Fa "bus_size_t size" "bus_size_t alignment" "bus_size_t boundary" +.Fa "int flags" "bus_addr_t *addrp" "bus_space_handle_t *handlep" +.Fc +.Ft void +.Fo bus_space_free +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t size" +.Fc +.Ft int +.Fo bus_space_peek_1 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" +.Fa "uint8_t *datap" +.Fc +.Ft int +.Fo bus_space_peek_2 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" +.Fa "uint8_t *datap" +.Fc +.Ft int +.Fo bus_space_peek_4 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" +.Fa "uint8_t *datap" +.Fc +.Ft int +.Fo bus_space_peek_8 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" +.Fa "uint8_t *datap" +.Fc +.Ft int +.Fo bus_space_poke_1 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" +.Fa "uint8_t *datap" +.Fc +.Ft int +.Fo bus_space_poke_2 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" +.Fa "uint8_t *datap" +.Fc +.Ft int +.Fo bus_space_poke_4 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" +.Fa "uint8_t *datap" +.Fc +.Ft int +.Fo bus_space_poke_8 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" +.Fa "uint8_t *datap" +.Fc +.Ft uint8_t +.Fo bus_space_read_1 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" +.Fc +.Ft uint16_t +.Fo bus_space_read_2 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" +.Fc +.Ft uint32_t +.Fo bus_space_read_4 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" +.Fc +.Ft uint64_t +.Fo bus_space_read_8 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" +.Fc +.Ft uint8_t +.Fo bus_space_read_stream_1 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" +.Fc +.Ft uint16_t +.Fo bus_space_read_stream_2 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" +.Fc +.Ft uint32_t +.Fo bus_space_read_stream_4 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" +.Fc +.Ft uint64_t +.Fo bus_space_read_stream_8 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" +.Fc +.Ft void +.Fo bus_space_write_1 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" +.Fa "bus_size_t offset" "uint8_t value" +.Fc +.Ft void +.Fo bus_space_write_2 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" +.Fa "bus_size_t offset" "uint16_t value" +.Fc +.Ft void +.Fo bus_space_write_4 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" +.Fa "bus_size_t offset" "uint32_t value" +.Fc +.Ft void +.Fo bus_space_write_8 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" +.Fa "bus_size_t offset" "uint64_t value" +.Fc +.Ft void +.Fo bus_space_write_stream_1 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" +.Fa "bus_size_t offset" "uint8_t value" +.Fc +.Ft void +.Fo bus_space_write_stream_2 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" +.Fa "bus_size_t offset" "uint16_t value" +.Fc +.Ft void +.Fo bus_space_write_stream_4 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" +.Fa "bus_size_t offset" "uint32_t value" +.Fc +.Ft void +.Fo bus_space_write_stream_8 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" +.Fa "bus_size_t offset" "uint64_t value" +.Fc +.Ft void +.Fo bus_space_barrier +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" +.Fa "bus_size_t offset" "bus_size_t length" "int flags" +.Fc +.Ft void +.Fo bus_space_read_region_1 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_region_2 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_region_4 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_region_8 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_region_stream_1 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_region_stream_2 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_region_stream_4 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_region_stream_8 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_region_1 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_region_2 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_region_4 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_region_8 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_region_stream_1 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_region_stream_2 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_region_stream_4 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_region_stream_8 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_copy_region_1 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset" +.Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_copy_region_2 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset" +.Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_copy_region_4 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset" +.Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_copy_region_8 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset" +.Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_copy_region_stream_1 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset" +.Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_copy_region_stream_2 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset" +.Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_copy_region_stream_4 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset" +.Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_copy_region_stream_8 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset" +.Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_region_1 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_region_2 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_region_4 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_region_8 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_region_stream_1 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_region_stream_2 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_region_stream_4 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_region_stream_8 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_multi_1 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_multi_2 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_multi_4 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_multi_8 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_multi_stream_1 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_multi_stream_2 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_multi_stream_4 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_multi_stream_8 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_multi_1 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_multi_2 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_multi_4 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_multi_8 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_multi_stream_1 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_multi_stream_2 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_multi_stream_4 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_multi_stream_8 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_multi_1 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_multi_2 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_multi_4 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_multi_8 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_multi_stream_1 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_multi_stream_2 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_multi_stream_4 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_multi_stream_8 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t value" +.Fa "bus_size_t count" +.Fc +.Sh DESCRIPTION +The +.Nm +functions exist to allow device drivers +machine-independent access to bus memory and register areas. +All of the +functions and types described in this document can be used by including +the +.In machine/bus.h +header file. +.Pp +Many common devices are used on multiple architectures, but are accessed +differently on each because of architectural constraints. +For instance, a device which is mapped in one system's I/O space may be +mapped in memory space on a second system. +On a third system, architectural +limitations might change the way registers need to be accessed (e.g.\& +creating a non-linear register space). +In some cases, a single +driver may need to access the same type of device in multiple ways in a +single system or architecture. +The goal of the +.Nm +functions is to allow a single driver source file to manipulate a set +of devices on different system architectures, and to allow a single driver +object file to manipulate a set of devices on multiple bus types on a +single architecture. +.Pp +Not all buses have to implement all functions described in this +document, though that is encouraged if the operations are logically +supported by the bus. +Unimplemented functions should cause +compile-time errors if possible. +.Pp +All of the interface definitions described in this document are shown as +function prototypes and discussed as if they were required to be +functions. +Implementations are encouraged to implement prototyped +(type-checked) versions of these interfaces, but may implement them as +macros if appropriate. +Machine-dependent types, variables, and functions +should be marked clearly in +.In machine/bus.h +to avoid confusion with the +machine-independent types and functions, and, if possible, should be +given names which make the machine-dependence clear. +.Sh CONCEPTS AND GUIDELINES +Bus spaces are described by bus space tags, which can be created only by +machine-dependent code. +A given machine may have several different types +of bus space (e.g.\& memory space and I/O space), and thus may provide +multiple different bus space tags. +Individual buses or devices on a machine may use more than one bus space +tag. +For instance, ISA devices are +given an ISA memory space tag and an ISA I/O space tag. +Architectures +may have several different tags which represent the same type of +space, for instance because of multiple different host bus interface +chipsets. +.Pp +A range in bus space is described by a bus address and a bus size. +The +bus address describes the start of the range in bus space. +The bus +size describes the size of the range in bytes. +Buses which are not byte +addressable may require use of bus space ranges with appropriately +aligned addresses and properly rounded sizes. +.Pp +Access to regions of bus space is facilitated by use of bus space handles, +which are usually created by mapping a specific range of a bus space. +Handles may also be created by allocating +and mapping a range of bus space, the actual location of which is picked +by the implementation within bounds specified by the caller of the +allocation function. +.Pp +All of the bus space access functions require one bus space tag +argument, at least one handle argument, and at least one offset argument +(a bus size). +The bus space tag specifies the space, each handle specifies a region in +the space, and each offset specifies the offset into the region of the +actual location(s) to be accessed. +Offsets are given in bytes, though buses +may impose alignment constraints. +The offset used to access data +relative to a given handle must be such that all of the data being +accessed is in the mapped region that the handle describes. +Trying to +access data outside that region is an error. +.Pp +Because some architectures' memory systems use buffering to improve +memory and device access performance, there is a mechanism which can be +used to create +.Dq barriers +in the bus space read and write stream. +There +are three types of barriers: read, write, and read/write. +All reads +started to the region before a read barrier must complete before any reads +after the read barrier are started. +(The analogous requirement is true for +write barriers.) +Read/write barriers force all reads and writes started +before the barrier to complete before any reads or writes after the +barrier are started. +Correctly-written drivers will include all +appropriate barriers, and assume only the read/write ordering imposed by +the barrier operations. +.Pp +People trying to write portable drivers with the +.Nm +functions should +try to make minimal assumptions about what the system allows. +In particular, +they should expect that the system requires bus space addresses being +accessed to be naturally aligned (i.e., base address of handle added to +offset is a multiple of the access size), and that the system does +alignment checking on pointers (i.e., pointer to objects being read and +written must point to properly-aligned data). +.Pp +The descriptions of the +.Nm +functions given below all assume that +they are called with proper arguments. +If called with invalid arguments +or arguments that are out of range (e.g.\& trying to access data outside of +the region mapped when a given handle was created), undefined behaviour +results. +In that case, they may cause the +system to halt, either intentionally (via panic) or unintentionally (by +causing a fatal trap of by some other means) or may cause improper +operation which is not immediately fatal. +Functions which return +.Ft void +or which return data read from bus space (i.e., functions which +do not obviously return an error code) do not fail. +They could only fail +if given invalid arguments, and in that case their behaviour is undefined. +Functions which take a count of bytes have undefined results if the specified +.Fa count +is zero. +.Sh TYPES +Several types are defined in +.In machine/bus.h +to facilitate use of the +.Nm +functions by drivers. +.Ss Vt bus_addr_t +The +.Vt bus_addr_t +type is used to describe bus addresses. +It must be an +unsigned integral type +capable of holding the largest bus address usable by the architecture. +This +type is primarily used when mapping and unmapping bus space. +.Ss Vt bus_size_t +The +.Vt bus_size_t +type is used to describe sizes of ranges in bus space. +It must be an +unsigned integral type capable of holding the size of the largest bus +address range usable on the architecture. +This type is used by virtually all +of the +.Nm +functions, describing sizes when mapping regions and +offsets into regions when performing space access operations. +.Ss Vt bus_space_tag_t +The +.Vt bus_space_tag_t +type is used to describe a particular bus space on a machine. +Its +contents are machine-dependent and should be considered opaque by +machine-independent code. +This type is used by all +.Nm +functions to name the space on which they are operating. +.Ss Vt bus_space_handle_t +The +.Vt bus_space_handle_t +type is used to describe a mapping of a range of bus space. +Its +contents are machine-dependent and should be considered opaque by +machine-independent code. +This type is used when performing bus space +access operations. +.Sh MAPPING AND UNMAPPING BUS SPACE +This section is specific to the +.Nx +version of these functions and may or may not apply to the +.Fx +version. +.Pp +Bus space must be mapped before it can be used, and should be +unmapped when it is no longer needed. +The +.Fn bus_space_map +and +.Fn bus_space_unmap +functions provide these capabilities. +.Pp +Some drivers need to be able to pass a subregion of already-mapped bus +space to another driver or module within a driver. +The +.Fn bus_space_subregion +function allows such subregions to be created. +.Ss Fn bus_space_map space address size flags handlep +The +.Fn bus_space_map +function maps the region of bus space named by the +.Fa space , address , +and +.Fa size +arguments. +If successful, it returns zero +and fills in the bus space handle pointed to by +.Fa handlep +with the handle +that can be used to access the mapped region. +If unsuccessful, +it will return non-zero and leave the bus space handle pointed +to by +.Fa handlep +in an undefined state. +.Pp +The +.Fa flags +argument controls how the space is to be mapped. +Supported flags include: +.Bl -tag -width ".Dv BUS_SPACE_MAP_CACHEABLE" +.It Dv BUS_SPACE_MAP_CACHEABLE +Try to map the space so that accesses can be cached and/or +prefetched by the system. +If this flag is not specified, the +implementation should map the space so that it will not be cached or +prefetched. +.Pp +This flag must have a value of 1 on all implementations for backward +compatibility. +.It Dv BUS_SPACE_MAP_LINEAR +Try to map the space so that its contents can be accessed linearly via +normal memory access methods (e.g.\& pointer dereferencing and structure +accesses). +This is useful when software wants to do direct access to a memory +device, e.g.\& a frame buffer. +If this flag is specified and linear +mapping is not possible, the +.Fn bus_space_map +call should fail. +If this +flag is not specified, the system may map the space in whatever way is +most convenient. +.It Dv BUS_SPACE_MAP_NONPOSTED +Try to map the space using non-posted device memory. +This is to support buses and devices where mapping with posted device +memory is unsupported or broken. +This flag is currently only available on arm64. +.El +.Pp +Not all combinations of flags make sense or are supported with all +spaces. +For instance, +.Dv BUS_SPACE_MAP_CACHEABLE +may be meaningless when +used on many systems' I/O port spaces, and on some systems +.Dv BUS_SPACE_MAP_LINEAR +without +.Dv BUS_SPACE_MAP_CACHEABLE +may never work. +When the system hardware or firmware provides hints as to how spaces should be +mapped (e.g.\& the PCI memory mapping registers' +.Dq prefetchable +bit), those +hints should be followed for maximum compatibility. +On some systems, +requesting a mapping that cannot be satisfied (e.g.\& requesting a +non-cacheable mapping when the system can only provide a cacheable one) +will cause the request to fail. +.Pp +Some implementations may keep track of use of bus space for some or all +bus spaces and refuse to allow duplicate allocations. +This is encouraged +for bus spaces which have no notion of slot-specific space addressing, +such as ISA, and for spaces which coexist with those spaces +(e.g.\& PCI memory and I/O spaces co-existing with ISA memory and +I/O spaces). +.Pp +Mapped regions may contain areas for which there is no device on the +bus. +If space in those areas is accessed, the results are +bus-dependent. +.Ss Fn bus_space_unmap space handle size +The +.Fn bus_space_unmap +function unmaps a region of bus space mapped with +.Fn bus_space_map . +When unmapping a region, the +.Fa size +specified should be +the same as the size given to +.Fn bus_space_map +when mapping that region. +.Pp +After +.Fn bus_space_unmap +is called on a handle, that handle is no longer +valid. +(If copies were made of the handle they are no longer valid, +either.) +.Pp +This function will never fail. +If it would fail (e.g.\& because of an +argument error), that indicates a software bug which should cause a +panic. +In that case, +.Fn bus_space_unmap +will never return. +.Ss Fn bus_space_subregion space handle offset size nhandlep +The +.Fn bus_space_subregion +function is a convenience function which makes a +new handle to some subregion of an already-mapped region of bus space. +The subregion described by the new handle starts at byte offset +.Fa offset +into the region described by +.Fa handle , +with the size give by +.Fa size , +and must be wholly contained within the original region. +.Pp +If successful, +.Fn bus_space_subregion +returns zero and fills in the bus +space handle pointed to by +.Fa nhandlep . +If unsuccessful, it returns non-zero and leaves the bus space handle +pointed to by +.Fa nhandlep +in an +undefined state. +In either case, the handle described by +.Fa handle +remains valid and is unmodified. +.Pp +When done with a handle created by +.Fn bus_space_subregion , +the handle should +be thrown away. +Under no circumstances should +.Fn bus_space_unmap +be used on the handle. +Doing so may confuse any resource management +being done on the space, and will result in undefined behaviour. +When +.Fn bus_space_unmap +or +.Fn bus_space_free +is called on a handle, all subregions of that handle become invalid. +.Sh ALLOCATING AND FREEING BUS SPACE +This section is specific to the +.Nx +version of these functions and may or may not apply to the +.Fx +version. +.Pp +Some devices require or allow bus space to be allocated by the operating +system for device use. +When the devices no longer need the space, the +operating system should free it for use by other devices. +The +.Fn bus_space_alloc +and +.Fn bus_space_free +functions provide these capabilities. +.Ss Fn bus_space_alloc space reg_start reg_end size alignment boundary \ +flags addrp handlep +The +.Fn bus_space_alloc +function allocates and maps a region of bus space with the size given by +.Fa size , +corresponding to the given constraints. +If successful, it returns +zero, fills in the bus address pointed to by +.Fa addrp +with the bus space address of the allocated region, and fills in +the bus space handle pointed to by +.Fa handlep +with the handle that can be used to access that region. +If unsuccessful, it returns non-zero and leaves the bus address pointed to by +.Fa addrp +and the bus space handle pointed to by +.Fa handlep +in an undefined state. +.Pp +Constraints on the allocation are given by the +.Fa reg_start , reg_end , alignment , +and +.Fa boundary +parameters. +The allocated region will start at or after +.Fa reg_start +and end before or at +.Fa reg_end . +The +.Fa alignment +constraint must be a power of two, and the allocated region will start at +an address that is an even multiple of that power of two. +The +.Fa boundary +constraint, if non-zero, ensures that the region is allocated so that +.Fa "first address in region" +/ +.Fa boundary +has the same value as +.Fa "last address in region" +/ +.Fa boundary . +If the constraints cannot be met, +.Fn bus_space_alloc +will fail. +It is an error to specify a set of +constraints that can never be met +(for example, +.Fa size +greater than +.Fa boundary ) . +.Pp +The +.Fa flags +parameter is the same as the like-named parameter to +.Fn bus_space_map , +the same flag values should be used, and they have the +same meanings. +.Pp +Handles created by +.Fn bus_space_alloc +should only be freed with +.Fn bus_space_free . +Trying to use +.Fn bus_space_unmap +on them causes undefined behaviour. +The +.Fn bus_space_subregion +function can be used on +handles created by +.Fn bus_space_alloc . +.Ss Fn bus_space_free space handle size +The +.Fn bus_space_free +function unmaps and frees a region of bus space mapped +and allocated with +.Fn bus_space_alloc . +When unmapping a region, the +.Fa size +specified should be the same as the size given to +.Fn bus_space_alloc +when allocating the region. +.Pp +After +.Fn bus_space_free +is called on a handle, that handle is no longer valid. +(If copies were +made of the handle, they are no longer valid, either.) +.Pp +This function will never fail. +If it would fail (e.g.\& because of an +argument error), that indicates a software bug which should cause a +panic. +In that case, +.Fn bus_space_free +will never return. +.Sh READING AND WRITING SINGLE DATA ITEMS +The simplest way to access bus space is to read or write a single data +item. +The +.Fn bus_space_read_N +and +.Fn bus_space_write_N +families of functions provide +the ability to read and write 1, 2, 4, and 8 byte data items on buses +which support those access sizes. +.Ss Fn bus_space_read_1 space handle offset +.Ss Fn bus_space_read_2 space handle offset +.Ss Fn bus_space_read_4 space handle offset +.Ss Fn bus_space_read_8 space handle offset +The +.Fn bus_space_read_N +family of functions reads a 1, 2, 4, or 8 byte data item from +the offset specified by +.Fa offset +into the region specified by +.Fa handle +of the bus space specified by +.Fa space . +The location being read must lie within the bus space region specified by +.Fa handle . +.Pp +For portability, the starting address of the region specified by +.Fa handle +plus the offset should be a multiple of the size of data item being read. +On some systems, not obeying this requirement may cause incorrect data to +be read, on others it may cause a system crash. +.Pp +Read operations done by the +.Fn bus_space_read_N +functions may be executed out +of order with respect to other pending read and write operations unless +order is enforced by use of the +.Fn bus_space_barrier +function. +.Pp +These functions will never fail. +If they would fail (e.g.\& because of an +argument error), that indicates a software bug which should cause a +panic. +In that case, they will never return. +.Ss Fn bus_space_write_1 space handle offset value +.Ss Fn bus_space_write_2 space handle offset value +.Ss Fn bus_space_write_4 space handle offset value +.Ss Fn bus_space_write_8 space handle offset value +The +.Fn bus_space_write_N +family of functions writes a 1, 2, 4, or 8 byte data item to the offset +specified by +.Fa offset +into the region specified by +.Fa handle +of the bus space specified by +.Fa space . +The location being written must lie within +the bus space region specified by +.Fa handle . +.Pp +For portability, the starting address of the region specified by +.Fa handle +plus the offset should be a multiple of the size of data item being +written. +On some systems, not obeying this requirement may cause +incorrect data to be written, on others it may cause a system crash. +.Pp +Write operations done by the +.Fn bus_space_write_N +functions may be executed +out of order with respect to other pending read and write operations +unless order is enforced by use of the +.Fn bus_space_barrier +function. +.Pp +These functions will never fail. +If they would fail (e.g.\& because of an +argument error), that indicates a software bug which should cause a +panic. +In that case, they will never return. +.Sh PROBING BUS SPACE FOR HARDWARE WHICH MAY NOT RESPOND +One problem with the +.Fn bus_space_read_N +and +.Fn bus_space_write_N +family of functions is that they provide no protection against +exceptions which can occur when no physical hardware or +device responds to the read or write cycles. +In such a situation, the system typically would panic due to a kernel-mode +bus error. +The +.Fn bus_space_peek_N +and +.Fn bus_space_poke_N +family of functions provide a mechanism to handle these exceptions +gracefully without the risk of crashing the system. +.Pp +As with +.Fn bus_space_read_N +and +.Fn bus_space_write_N , +the peek and poke functions provide the ability to read and +write 1, 2, 4, and 8 byte data items on busses which support those +access sizes. +All of the constraints specified in the descriptions of the +.Fn bus_space_read_N +and +.Fn bus_space_write_N +functions also apply to +.Fn bus_space_peek_N +and +.Fn bus_space_poke_N . +.Pp +In addition, explicit calls to the +.Fn bus_space_barrier +function are not required as the implementation will ensure all +pending operations complete before the peek or poke operation starts. +The implementation will also ensure that the peek or poke operations +complete before returning. +.Pp +The return value indicates the outcome of the peek or poke operation. +A return value of zero implies that a hardware device is +responding to the operation at the specified offset in the bus space. +A non-zero return value indicates that the kernel intercepted a +hardware exception (e.g., bus error) when the peek or poke operation +was attempted. +Note that some busses are incapable of generating exceptions when +non-existent hardware is accessed. +In such cases, these functions will always return zero and the value of +the data read by +.Fn bus_space_peek_N +will be unspecified. +.Pp +Finally, it should be noted that at this time the +.Fn bus_space_peek_N +and +.Fn bus_space_poke_N +functions are not re-entrant and should not, therefore, be used +from within an interrupt service routine. +This constraint may be removed at some point in the future. +.Pp +.Bl -ohang -compact +.It Fn bus_space_peek_1 "space" "handle" "offset" "datap" +.It Fn bus_space_peek_2 "space" "handle" "offset" "datap" +.It Fn bus_space_peek_4 "space" "handle" "offset" "datap" +.It Fn bus_space_peek_8 "space" "handle" "offset" "datap" +.Pp +The +.Fn bus_space_peek_N +family of functions cautiously read a 1, 2, 4, or 8 byte data item from +the offset specified by +.Fa offset +in the region specified by +.Fa handle +of the bus space specified by +.Fa space . +The data item read is stored in the location pointed to by +.Fa datap . +It is permissible for +.Fa datap +to be NULL, in which case the data item will be discarded after being read. +.Pp +.It Fn bus_space_poke_1 "space" "handle" "offset" "value" +.It Fn bus_space_poke_2 "space" "handle" "offset" "value" +.It Fn bus_space_poke_4 "space" "handle" "offset" "value" +.It Fn bus_space_poke_8 "space" "handle" "offset" "value" +.Pp +The +.Fn bus_space_poke_N +family of functions cautiously write a 1, 2, 4, or 8 byte data item +specified by +.Fa value +to the offset specified by +.Fa offset +in the region specified by +.Fa handle +of the bus space specified by +.Fa space . +.El +.Sh BARRIERS +In order to allow high-performance buffering implementations to avoid bus +activity on every operation, read and write ordering should be specified +explicitly by drivers when necessary. +The +.Fn bus_space_barrier +function provides that ability. +.Ss Fn bus_space_barrier space handle offset length flags +The +.Fn bus_space_barrier +function enforces ordering of bus space read and write operations +for the specified subregion (described by the +.Fa offset +and +.Fa length +parameters) of the region named by +.Fa handle +in the space named by +.Fa space . +.Pp +The +.Fa flags +argument controls what types of operations are to be ordered. +Supported flags are: +.Bl -tag -width ".Dv BUS_SPACE_BARRIER_WRITE" +.It Dv BUS_SPACE_BARRIER_READ +Synchronize read operations. +.It Dv BUS_SPACE_BARRIER_WRITE +Synchronize write operations. +.El +.Pp +Those flags can be combined (or-ed together) to enforce ordering on both +read and write operations. +.Pp +All of the specified type(s) of operation which are done to the region +before the barrier operation are guaranteed to complete before any of the +specified type(s) of operation done after the barrier. +.Pp +Example: Consider a hypothetical device with two single-byte ports, one +write-only input port (at offset 0) and a read-only output port (at +offset 1). +Operation of the device is as follows: data bytes are written +to the input port, and are placed by the device on a stack, the top of +which is read by reading from the output port. +The sequence to correctly +write two data bytes to the device then read those two data bytes back +would be: +.Bd -literal +/* + * t and h are the tag and handle for the mapped device's + * space. + */ +bus_space_write_1(t, h, 0, data0); +bus_space_barrier(t, h, 0, 1, BUS_SPACE_BARRIER_WRITE); /* 1 */ +bus_space_write_1(t, h, 0, data1); +bus_space_barrier(t, h, 0, 2, + BUS_SPACE_BARRIER_READ|BUS_SPACE_BARRIER_WRITE); /* 2 */ +ndata1 = bus_space_read_1(t, h, 1); +bus_space_barrier(t, h, 1, 1, BUS_SPACE_BARRIER_READ); /* 3 */ +ndata0 = bus_space_read_1(t, h, 1); +/* data0 == ndata0, data1 == ndata1 */ +.Ed +.Pp +The first barrier makes sure that the first write finishes before the +second write is issued, so that two writes to the input port are done +in order and are not collapsed into a single write. +This ensures that +the data bytes are written to the device correctly and in order. +.Pp +The second barrier makes sure that the writes to the output port finish +before any of the reads to the input port are issued, thereby making sure +that all of the writes are finished before data is read. +This ensures +that the first byte read from the device really is the last one that was +written. +.Pp +The third barrier makes sure that the first read finishes before the +second read is issued, ensuring that data is read correctly and in order. +.Pp +The barriers in the example above are specified to cover the absolute +minimum number of bus space locations. +It is correct (and often +easier) to make barrier operations cover the device's whole range of bus +space, that is, to specify an offset of zero and the size of the +whole region. +.Sh REGION OPERATIONS +Some devices use buffers which are mapped as regions in bus space. +Often, drivers want to copy the contents of those buffers to or from +memory, e.g.\& into mbufs which can be passed to higher levels of the +system or from mbufs to be output to a network. +In order to allow +drivers to do this as efficiently as possible, the +.Fn bus_space_read_region_N +and +.Fn bus_space_write_region_N +families of functions are provided. +.Pp +Drivers occasionally need to copy one region of a bus space to another, +or to set all locations in a region of bus space to contain a single +value. +The +.Fn bus_space_copy_region_N +family of functions and the +.Fn bus_space_set_region_N +family of functions allow drivers to perform these operations. +.Ss Fn bus_space_read_region_1 space handle offset datap count +.Ss Fn bus_space_read_region_2 space handle offset datap count +.Ss Fn bus_space_read_region_4 space handle offset datap count +.Ss Fn bus_space_read_region_8 space handle offset datap count +The +.Fn bus_space_read_region_N +family of functions reads +.Fa count +1, 2, 4, or 8 byte data items from bus space +starting at byte offset +.Fa offset +in the region specified by +.Fa handle +of the bus space specified by +.Fa space +and writes them into the array specified by +.Fa datap . +Each successive data item is read from an offset +1, 2, 4, or 8 bytes after the previous data item (depending on which +function is used). +All locations being read must lie within the bus +space region specified by +.Fa handle . +.Pp +For portability, the starting address of the region specified by +.Fa handle +plus the offset should be a multiple of the size of data items being +read and the data array pointer should be properly aligned. +On some +systems, not obeying these requirements may cause incorrect data to be +read, on others it may cause a system crash. +.Pp +Read operations done by the +.Fn bus_space_read_region_N +functions may be executed in any order. +They may also be executed out +of order with respect to other pending read and write operations unless +order is enforced by use of the +.Fn bus_space_barrier +function. +There is no way to insert barriers between reads of +individual bus space locations executed by the +.Fn bus_space_read_region_N +functions. +.Pp +These functions will never fail. +If they would fail (e.g.\& because of an +argument error), that indicates a software bug which should cause a +panic. +In that case, they will never return. +.Ss Fn bus_space_write_region_1 space handle offset datap count +.Ss Fn bus_space_write_region_2 space handle offset datap count +.Ss Fn bus_space_write_region_4 space handle offset datap count +.Ss Fn bus_space_write_region_8 space handle offset datap count +The +.Fn bus_space_write_region_N +family of functions reads +.Fa count +1, 2, 4, or 8 byte data items from the array +specified by +.Fa datap +and writes them to bus space starting at byte offset +.Fa offset +in the region specified by +.Fa handle +of the bus space specified +by +.Fa space . +Each successive data item is written to an offset 1, 2, 4, +or 8 bytes after the previous data item (depending on which function is +used). +All locations being written must lie within the bus space region +specified by +.Fa handle . +.Pp +For portability, the starting address of the region specified by +.Fa handle +plus the offset should be a multiple of the size of data items being +written and the data array pointer should be properly aligned. +On some +systems, not obeying these requirements may cause incorrect data to be +written, on others it may cause a system crash. +.Pp +Write operations done by the +.Fn bus_space_write_region_N +functions may be +executed in any order. +They may also be executed out of order with +respect to other pending read and write operations unless order is +enforced by use of the +.Fn bus_space_barrier +function. +There is no way to insert barriers between writes of +individual bus space locations executed by the +.Fn bus_space_write_region_N +functions. +.Pp +These functions will never fail. +If they would fail (e.g.\& because of an +argument error), that indicates a software bug which should cause a +panic. +In that case, they will never return. +.Ss Fn bus_space_copy_region_1 space srchandle srcoffset dsthandle \ +dstoffset count +.Ss Fn bus_space_copy_region_2 space srchandle srcoffset dsthandle \ +dstoffset count +.Ss Fn bus_space_copy_region_4 space srchandle srcoffset dsthandle \ +dstoffset count +.Ss Fn bus_space_copy_region_8 space srchandle srcoffset dsthandle \ +dstoffset count +The +.Fn bus_space_copy_region_N +family of functions copies +.Fa count +1, 2, 4, or 8 byte data items in bus space +from the area starting at byte offset +.Fa srcoffset +in the region specified by +.Fa srchandle +of the bus space specified by +.Fa space +to the area starting at byte offset +.Fa dstoffset +in the region specified by +.Fa dsthandle +in the same bus space. +Each successive data item read or written has +an offset 1, 2, 4, or 8 bytes after the previous data item (depending +on which function is used). +All locations being read and written must +lie within the bus space region specified by their respective handles. +.Pp +For portability, the starting addresses of the regions specified by the +each handle plus its respective offset should be a multiple of the size +of data items being copied. +On some systems, not obeying this +requirement may cause incorrect data to be copied, on others it may cause +a system crash. +.Pp +Read and write operations done by the +.Fn bus_space_copy_region_N +functions may be executed in any order. +They may also be executed out +of order with respect to other pending read and write operations unless +order is enforced by use of the +.Fn bus_space_barrier +function. +There is no way to insert barriers between reads or writes of +individual bus space locations executed by the +.Fn bus_space_copy_region_N +functions. +.Pp +Overlapping copies between different subregions of a single region +of bus space are handled correctly by the +.Fn bus_space_copy_region_N +functions. +.Pp +These functions will never fail. +If they would fail (e.g.\& because of an +argument error), that indicates a software bug which should cause a +panic. +In that case, they will never return. +.Ss Fn bus_space_set_region_1 space handle offset value count +.Ss Fn bus_space_set_region_2 space handle offset value count +.Ss Fn bus_space_set_region_4 space handle offset value count +.Ss Fn bus_space_set_region_8 space handle offset value count +The +.Fn bus_space_set_region_N +family of functions writes the given +.Fa value +to +.Fa count +1, 2, 4, or 8 byte +data items in bus space starting at byte offset +.Fa offset +in the region specified by +.Fa handle +of the bus space specified by +.Fa space . +Each successive data item has an offset 1, 2, 4, or 8 bytes after the +previous data item (depending on which function is used). +All +locations being written must lie within the bus space region specified +by +.Fa handle . +.Pp +For portability, the starting address of the region specified by +.Fa handle +plus the offset should be a multiple of the size of data items being +written. +On some systems, not obeying this requirement may cause +incorrect data to be written, on others it may cause a system crash. +.Pp +Write operations done by the +.Fn bus_space_set_region_N +functions may be +executed in any order. +They may also be executed out of order with +respect to other pending read and write operations unless order is +enforced by use of the +.Fn bus_space_barrier +function. +There is no way to insert barriers between writes of +individual bus space locations executed by the +.Fn bus_space_set_region_N +functions. +.Pp +These functions will never fail. +If they would fail (e.g.\& because of an +argument error), that indicates a software bug which should cause a +panic. +In that case, they will never return. +.Sh READING AND WRITING A SINGLE LOCATION MULTIPLE TIMES +Some devices implement single locations in bus space which are to be read +or written multiple times to communicate data, e.g.\& some ethernet +devices' packet buffer FIFOs. +In order to allow drivers to manipulate +these types of devices as efficiently as possible, the +.Fn bus_space_read_multi_N , +.Fn bus_space_set_multi_N , +and +.Fn bus_space_write_multi_N +families of functions are provided. +.Ss Fn bus_space_read_multi_1 space handle offset datap count +.Ss Fn bus_space_read_multi_2 space handle offset datap count +.Ss Fn bus_space_read_multi_4 space handle offset datap count +.Ss Fn bus_space_read_multi_8 space handle offset datap count +The +.Fn bus_space_read_multi_N +family of functions reads +.Fa count +1, 2, 4, or 8 byte data items from bus space +at byte offset +.Fa offset +in the region specified by +.Fa handle +of the bus space specified by +.Fa space +and writes them into the array specified by +.Fa datap . +Each successive data item is read from the same location in bus +space. +The location being read must lie within the bus space region +specified by +.Fa handle . +.Pp +For portability, the starting address of the region specified by +.Fa handle +plus the offset should be a multiple of the size of data items being +read and the data array pointer should be properly aligned. +On some +systems, not obeying these requirements may cause incorrect data to be +read, on others it may cause a system crash. +.Pp +Read operations done by the +.Fn bus_space_read_multi_N +functions may be +executed out of order with respect to other pending read and write +operations unless order is enforced by use of the +.Fn bus_space_barrier +function. +Because the +.Fn bus_space_read_multi_N +functions read the same bus space location multiple times, they +place an implicit read barrier between each successive read of that bus +space location. +.Pp +These functions will never fail. +If they would fail (e.g.\& because of an +argument error), that indicates a software bug which should cause a +panic. +In that case, they will never return. +.Ss Fn bus_space_write_multi_1 space handle offset datap count +.Ss Fn bus_space_write_multi_2 space handle offset datap count +.Ss Fn bus_space_write_multi_4 space handle offset datap count +.Ss Fn bus_space_write_multi_8 space handle offset datap count +The +.Fn bus_space_write_multi_N +family of functions reads +.Fa count +1, 2, 4, or 8 byte data items from the array +specified by +.Fa datap +and writes them into bus space at byte offset +.Fa offset +in the region specified by +.Fa handle +of the bus space specified by +.Fa space . +Each successive data item is written to the same location in +bus space. +The location being written must lie within the bus space +region specified by +.Fa handle . +.Pp +For portability, the starting address of the region specified by +.Fa handle +plus the offset should be a multiple of the size of data items being +written and the data array pointer should be properly aligned. +On some +systems, not obeying these requirements may cause incorrect data to be +written, on others it may cause a system crash. +.Pp +Write operations done by the +.Fn bus_space_write_multi_N +functions may be executed out of order with respect to other pending +read and write operations unless order is enforced by use of the +.Fn bus_space_barrier +function. +Because the +.Fn bus_space_write_multi_N +functions write the same bus space location multiple times, they +place an implicit write barrier between each successive write of that +bus space location. +.Pp +These functions will never fail. +If they would fail (e.g.\& because of an +argument error), that indicates a software bug which should cause a +panic. +In that case, they will never return. +.Ss Fn bus_space_set_multi_1 space handle offset value count +.Ss Fn bus_space_set_multi_2 space handle offset value count +.Ss Fn bus_space_set_multi_4 space handle offset value count +.Ss Fn bus_space_set_multi_8 space handle offset value count +The +.Fn bus_space_set_multi_N +writes +.Fa value +into bus space at byte offset +.Fa offset +in the region specified by +.Fa handle +of the bus space specified by +.Fa space , +.Fa count +times. +The location being written must lie within the bus space +region specified by +.Fa handle . +.Pp +For portability, the starting address of the region specified by +.Fa handle +plus the offset should be a multiple of the size of data items being +written and the data array pointer should be properly aligned. +On some +systems, not obeying these requirements may cause incorrect data to be +written, on others it may cause a system crash. +.Pp +Write operations done by the +.Fn bus_space_set_multi_N +functions may be executed out of order with respect to other pending +read and write operations unless order is enforced by use of the +.Fn bus_space_barrier +function. +Because the +.Fn bus_space_set_multi_N +functions write the same bus space location multiple times, they +place an implicit write barrier between each successive write of that +bus space location. +.Pp +These functions will never fail. +If they would fail (e.g.\& because of an +argument error), that indicates a software bug which should cause a +panic. +In that case, they will never return. +.Sh STREAM FUNCTIONS +Most of the +.Nm +functions imply a host byte-order and a bus byte-order and take care of +any translation for the caller. +In some cases, however, hardware may map a FIFO or some other memory region +for which the caller may want to use multi-word, yet untranslated access. +Access to these types of memory regions should be with the +.Fn bus_space_*_stream_N +functions. +.Pp +.Bl -tag -compact -width Fn +.It Fn bus_space_read_stream_1 +.It Fn bus_space_read_stream_2 +.It Fn bus_space_read_stream_4 +.It Fn bus_space_read_stream_8 +.It Fn bus_space_read_multi_stream_1 +.It Fn bus_space_read_multi_stream_2 +.It Fn bus_space_read_multi_stream_4 +.It Fn bus_space_read_multi_stream_8 +.It Fn bus_space_read_region_stream_1 +.It Fn bus_space_read_region_stream_2 +.It Fn bus_space_read_region_stream_4 +.It Fn bus_space_read_region_stream_8 +.It Fn bus_space_write_stream_1 +.It Fn bus_space_write_stream_2 +.It Fn bus_space_write_stream_4 +.It Fn bus_space_write_stream_8 +.It Fn bus_space_write_multi_stream_1 +.It Fn bus_space_write_multi_stream_2 +.It Fn bus_space_write_multi_stream_4 +.It Fn bus_space_write_multi_stream_8 +.It Fn bus_space_write_region_stream_1 +.It Fn bus_space_write_region_stream_2 +.It Fn bus_space_write_region_stream_4 +.It Fn bus_space_write_region_stream_8 +.It Fn bus_space_copy_region_stream_1 +.It Fn bus_space_copy_region_stream_2 +.It Fn bus_space_copy_region_stream_4 +.It Fn bus_space_copy_region_stream_8 +.It Fn bus_space_set_multi_stream_1 +.It Fn bus_space_set_multi_stream_2 +.It Fn bus_space_set_multi_stream_4 +.It Fn bus_space_set_multi_stream_8 +.It Fn bus_space_set_region_stream_1 +.It Fn bus_space_set_region_stream_2 +.It Fn bus_space_set_region_stream_4 +.It Fn bus_space_set_region_stream_8 +.El +.Pp +These functions are defined just as their non-stream counterparts, +except that they provide no byte-order translation. +.Sh COMPATIBILITY +The current +.Nx +version of the +.Nm +interface specification differs slightly from the original +specification that came into wide use and +.Fx +adopted. +A few of the function names and arguments have changed +for consistency and increased functionality. +.Sh SEE ALSO +.Xr bus_dma 9 +.Sh HISTORY +The +.Nm +functions were introduced in a different form (memory and I/O spaces +were accessed via different sets of functions) in +.Nx 1.2 . +The functions were merged to work on generic +.Dq spaces +early in the +.Nx 1.3 +development cycle, and many drivers were converted to use them. +This document was written later during the +.Nx 1.3 +development cycle, and the specification was updated to fix some +consistency problems and to add some missing functionality. +.Pp +The manual page was then adapted to the version of the interface that +.Fx +imported for the CAM SCSI drivers, plus subsequent evolution. +The +.Fx +.Nm +version was imported in +.Fx 3.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +interfaces were designed and implemented by the +.Nx +developer +community. +Primary contributors and implementors were +.An Chris Demetriou , +.An Jason Thorpe , +and +.An Charles Hannum , +but the rest of the +.Nx +developers and the user community played a significant role in development. +.Pp +.An Justin Gibbs +ported these interfaces to +.Fx . +.Pp +.An Chris Demetriou +wrote this manual page. +.Pp +.An Warner Losh +modified it for the +.Fx +implementation. +.Sh BUGS +This manual may not completely and accurately document the interface, +and many parts of the interface are unspecified. diff --git a/static/freebsd/man9/byteorder.9 b/static/freebsd/man9/byteorder.9 new file mode 100644 index 00000000..42f33620 --- /dev/null +++ b/static/freebsd/man9/byteorder.9 @@ -0,0 +1,167 @@ +.\" Copyright (c) 2002 Mike Barcroft +.\" 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 April 29, 2002 +.Dt BYTEORDER 9 +.Os +.Sh NAME +.Nm bswap16 , bswap32 , bswap64 , +.Nm be16toh , be32toh , be64toh , htobe16 , htobe32 , htobe64 , +.Nm htole16 , htole32 , htole64 , le16toh , le32toh , le64toh , +.Nm be16enc , be16dec , be32enc , be32dec , be64enc , be64dec , +.Nm le16enc , le16dec , le32enc , le32dec , le64enc , le64dec +.Nd byte order operations +.Sh SYNOPSIS +.In sys/endian.h +.Ft uint16_t +.Fn bswap16 "uint16_t int16" +.Ft uint32_t +.Fn bswap32 "uint32_t int32" +.Ft uint64_t +.Fn bswap64 "uint64_t int64" +.Ft uint16_t +.Fn be16toh "uint16_t big16" +.Ft uint32_t +.Fn be32toh "uint32_t big32" +.Ft uint64_t +.Fn be64toh "uint64_t big64" +.Ft uint16_t +.Fn htobe16 "uint16_t host16" +.Ft uint32_t +.Fn htobe32 "uint32_t host32" +.Ft uint64_t +.Fn htobe64 "uint64_t host64" +.Ft uint16_t +.Fn htole16 "uint16_t host16" +.Ft uint32_t +.Fn htole32 "uint32_t host32" +.Ft uint64_t +.Fn htole64 "uint64_t host64" +.Ft uint16_t +.Fn le16toh "uint16_t little16" +.Ft uint32_t +.Fn le32toh "uint32_t little32" +.Ft uint64_t +.Fn le64toh "uint64_t little64" +.Ft uint16_t +.Fn be16dec "const void *" +.Ft uint32_t +.Fn be32dec "const void *" +.Ft uint64_t +.Fn be64dec "const void *" +.Ft uint16_t +.Fn le16dec "const void *" +.Ft uint32_t +.Fn le32dec "const void *" +.Ft uint64_t +.Fn le64dec "const void *" +.Ft void +.Fn be16enc "void *" uint16_t +.Ft void +.Fn be32enc "void *" uint32_t +.Ft void +.Fn be64enc "void *" uint64_t +.Ft void +.Fn le16enc "void *" uint16_t +.Ft void +.Fn le32enc "void *" uint32_t +.Ft void +.Fn le64enc "void *" uint64_t +.Sh DESCRIPTION +The +.Fn bswap16 , +.Fn bswap32 , +and +.Fn bswap64 +functions return a byte order swapped integer. +On big endian systems, the number is converted to little endian byte order. +On little endian systems, the number is converted to big endian byte order. +.Pp +The +.Fn be16toh , +.Fn be32toh , +and +.Fn be64toh +functions return a big endian byte ordered integer +converted to the system's native byte order. +The return value will be the same as the argument on big endian systems. +.Pp +The +.Fn le16toh , +.Fn le32toh , +and +.Fn le64toh +functions return a little endian byte ordered integer +converted to the system's native byte order. +The return value will be the same as the argument on little endian systems. +.Pp +The +.Fn htobe16 , +.Fn htobe32 , +and +.Fn htobe64 +functions return an integer in the system's native +byte order converted to big endian byte order. +The return value will be the same as the argument on big endian systems. +.Pp +The +.Fn htole16 , +.Fn htole32 , +and +.Fn htole64 +functions return a integer in the system's native +byte order converted to little endian byte order. +The return value will be the same as the argument on little endian systems. +.Pp +The +.Fn be16enc , +.Fn be16dec , +.Fn be32enc , +.Fn be32dec , +.Fn be64enc , +.Fn be64dec , +.Fn le16enc , +.Fn le16dec , +.Fn le32enc , +.Fn le32dec , +.Fn le64enc , +and +.Fn le64dec +functions encode and decode integers to/from byte strings on any alignment +in big/little endian format. +.Sh SEE ALSO +.Xr byteorder 3 +.Sh HISTORY +The +.Fn hto* +and +.Fn *toh +functions first appeared in +.Fx 5.0 , +and were originally developed by the +.Nx +project. +.Pp +The encode/decode functions first appeared in +.Fx 5.1 . diff --git a/static/freebsd/man9/callout.9 b/static/freebsd/man9/callout.9 new file mode 100644 index 00000000..637049ec --- /dev/null +++ b/static/freebsd/man9/callout.9 @@ -0,0 +1,886 @@ +.\" $NetBSD: timeout.9,v 1.2 1996/06/23 22:32:34 pk Exp $ +.\" +.\" Copyright (c) 1996 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Paul Kranenburg. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 REGENTS 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 November 4, 2025 +.Dt CALLOUT 9 +.Os +.Sh NAME +.Nm callout_active , +.Nm callout_deactivate , +.Nm callout_drain , +.Nm callout_init , +.Nm callout_init_mtx , +.Nm callout_init_rm , +.Nm callout_init_rw , +.Nm callout_pending , +.Nm callout_reset , +.Nm callout_reset_curcpu , +.Nm callout_reset_on , +.Nm callout_reset_sbt , +.Nm callout_reset_sbt_curcpu , +.Nm callout_reset_sbt_on , +.Nm callout_schedule , +.Nm callout_schedule_curcpu , +.Nm callout_schedule_on , +.Nm callout_schedule_sbt , +.Nm callout_schedule_sbt_curcpu , +.Nm callout_schedule_sbt_on , +.Nm callout_stop , +.Nm callout_when +.Nd execute a function after a specified length of time +.Sh SYNOPSIS +.In sys/types.h +.In sys/callout.h +.Bd -literal +typedef void callout_func_t (void *); +.Ed +.Ft int +.Fn callout_active "struct callout *c" +.Ft void +.Fn callout_deactivate "struct callout *c" +.Ft int +.Fn callout_drain "struct callout *c" +.Ft void +.Fn callout_init "struct callout *c" "int mpsafe" +.Ft void +.Fn callout_init_mtx "struct callout *c" "struct mtx *mtx" "int flags" +.Ft void +.Fn callout_init_rm "struct callout *c" "struct rmlock *rm" "int flags" +.Ft void +.Fn callout_init_rw "struct callout *c" "struct rwlock *rw" "int flags" +.Ft int +.Fn callout_pending "struct callout *c" +.Ft int +.Fo callout_reset +.Fa "struct callout *c" +.Fa "int ticks" +.Fa "callout_func_t *func" +.Fa "void *arg" +.Fc +.Ft int +.Fo callout_reset_curcpu +.Fa "struct callout *c" +.Fa "int ticks" +.Fa "callout_func_t *func" +.Fa "void *arg" +.Fc +.Ft int +.Fo callout_reset_on +.Fa "struct callout *c" +.Fa "int ticks" +.Fa "callout_func_t *func" +.Fa "void *arg" +.Fa "int cpu" +.Fc +.Ft int +.Fo callout_reset_sbt +.Fa "struct callout *c" +.Fa "sbintime_t sbt" +.Fa "sbintime_t pr" +.Fa "callout_func_t *func" +.Fa "void *arg" +.Fa "int flags" +.Fc +.Ft int +.Fo callout_reset_sbt_curcpu +.Fa "struct callout *c" +.Fa "sbintime_t sbt" +.Fa "sbintime_t pr" +.Fa "callout_func_t *func" +.Fa "void *arg" +.Fa "int flags" +.Fc +.Ft int +.Fo callout_reset_sbt_on +.Fa "struct callout *c" +.Fa "sbintime_t sbt" +.Fa "sbintime_t pr" +.Fa "callout_func_t *func" +.Fa "void *arg" +.Fa "int cpu" +.Fa "int flags" +.Fc +.Ft int +.Fn callout_schedule "struct callout *c" "int ticks" +.Ft int +.Fn callout_schedule_curcpu "struct callout *c" "int ticks" +.Ft int +.Fn callout_schedule_on "struct callout *c" "int ticks" "int cpu" +.Ft int +.Fo callout_schedule_sbt +.Fa "struct callout *c" +.Fa "sbintime_t sbt" +.Fa "sbintime_t pr" +.Fa "int flags" +.Fc +.Ft int +.Fo callout_schedule_sbt_curcpu +.Fa "struct callout *c" +.Fa "sbintime_t sbt" +.Fa "sbintime_t pr" +.Fa "int flags" +.Fc +.Ft int +.Fo callout_schedule_sbt_on +.Fa "struct callout *c" +.Fa "sbintime_t sbt" +.Fa "sbintime_t pr" +.Fa "int cpu" +.Fa "int flags" +.Fc +.Ft int +.Fn callout_stop "struct callout *c" +.Ft sbintime_t +.Fo callout_when +.Fa "sbintime_t sbt" +.Fa "sbintime_t precision" +.Fa "int flags" +.Fa "sbintime_t *sbt_res" +.Fa "sbintime_t *precision_res" +.Fc +.Sh DESCRIPTION +The +.Nm callout +API is used to schedule a call to an arbitrary function at a specific +time in the future. +Consumers of this API are required to allocate a callout structure +.Pq struct callout +for each pending function invocation. +This structure stores state about the pending function invocation including +the function to be called and the time at which the function should be invoked. +Pending function calls can be cancelled or rescheduled to a different time. +In addition, +a callout structure may be reused to schedule a new function call after a +scheduled call is completed. +.Pp +Callouts only provide a single-shot mode. +If a consumer requires a periodic timer, +it must explicitly reschedule each function call. +This is normally done by rescheduling the subsequent call within the called +function. +.Pp +Callout functions must not sleep. +They may not acquire sleepable locks, +wait on condition variables, +perform blocking allocation requests, +or invoke any other action that might sleep. +.Pp +Each callout structure must be initialized by +.Fn callout_init , +.Fn callout_init_mtx , +.Fn callout_init_rm , +or +.Fn callout_init_rw +before it is passed to any of the other callout functions. +The +.Fn callout_init +function initializes a callout structure in +.Fa c +that is not associated with a specific lock. +If the +.Fa mpsafe +argument is zero, +the callout structure is not considered to be +.Dq multi-processor safe ; +and the Giant lock will be acquired before calling the callout function +and released when the callout function returns. +.Pp +The +.Fn callout_init_mtx , +.Fn callout_init_rm , +and +.Fn callout_init_rw +functions initialize a callout structure in +.Fa c +that is associated with a specific lock. +The lock is specified by the +.Fa mtx , +.Fa rm , +or +.Fa rw +parameter. +The associated lock must be held while stopping or rescheduling the +callout. +The callout subsystem acquires the associated lock before calling the +callout function and releases it after the function returns. +If the callout was cancelled while the callout subsystem waited for the +associated lock, +the callout function is not called, +and the associated lock is released. +This ensures that stopping or rescheduling the callout will abort any +previously scheduled invocation. +.Pp +A sleepable read-mostly lock +.Po +one initialized with the +.Dv RM_SLEEPABLE +flag +.Pc +may not be used with +.Fn callout_init_rm . +Similarly, other sleepable lock types such as +.Xr sx 9 +and +.Xr lockmgr 9 +cannot be used with callouts because sleeping is not permitted in +the callout subsystem. +.Pp +These +.Fa flags +may be specified for +.Fn callout_init_mtx , +.Fn callout_init_rm , +or +.Fn callout_init_rw : +.Bl -tag -width ".Dv CALLOUT_RETURNUNLOCKED" +.It Dv CALLOUT_RETURNUNLOCKED +The callout function will release the associated lock itself, +so the callout subsystem should not attempt to unlock it +after the callout function returns. +.It Dv CALLOUT_SHAREDLOCK +The lock is only acquired in read mode when running the callout handler. +This flag is ignored by +.Fn callout_init_mtx . +.El +.Pp +The function +.Fn callout_stop +cancels a callout +.Fa c +if it is currently pending. +If the callout is pending and successfully stopped, then +.Fn callout_stop +returns a value of one. +If the callout is not set, or +has already been serviced, then +negative one is returned. +If the callout is currently being serviced and cannot be stopped, +then zero will be returned. +If the callout is currently being serviced and cannot be stopped, and at the +same time a next invocation of the same callout is also scheduled, then +.Fn callout_stop +unschedules the next run and returns zero. +If the callout has an associated lock, +then that lock must be held when this function is called. +.Pp +The function +.Fn callout_drain +is identical to +.Fn callout_stop +except that it will wait for the callout +.Fa c +to complete if it is already in progress. +This function MUST NOT be called while holding any +locks on which the callout might block, or deadlock will result. +Note that if the callout subsystem has already begun processing this +callout, then the callout function may be invoked before +.Fn callout_drain +returns. +However, the callout subsystem does guarantee that the callout will be +fully stopped before +.Fn callout_drain +returns. +.Pp +The +.Fn callout_reset +and +.Fn callout_schedule +function families schedule a future function invocation for callout +.Fa c . +If +.Fa c +already has a pending callout, +it is cancelled before the new invocation is scheduled. +These functions return a value of one if a pending callout was cancelled +and zero if there was no pending callout. +If the callout has an associated lock, +then that lock must be held when any of these functions are called. +.Pp +The time at which the callout function will be invoked is determined by +either the +.Fa ticks +argument or the +.Fa sbt , +.Fa pr , +and +.Fa flags +arguments. +When +.Fa ticks +is used, +the callout is scheduled to execute after +.Fa ticks Ns No /hz +seconds. +Non-positive values of +.Fa ticks +are silently converted to the value +.Sq 1 . +.Pp +The +.Fa sbt , +.Fa pr , +and +.Fa flags +arguments provide more control over the scheduled time including +support for higher resolution times, +specifying the precision of the scheduled time, +and setting an absolute deadline instead of a relative timeout. +The callout is scheduled to execute in a time window which begins at +the time specified in +.Fa sbt +and extends for the amount of time specified in +.Fa pr . +If +.Fa sbt +specifies a time in the past, +the window is adjusted to start at the current time. +A non-zero value for +.Fa pr +allows the callout subsystem to coalesce callouts scheduled close to each +other into fewer timer interrupts, +reducing processing overhead and power consumption. +These +.Fa flags +may be specified to adjust the interpretation of +.Fa sbt +and +.Fa pr : +.Bl -tag -width ".Dv C_DIRECT_EXEC" +.It Dv C_ABSOLUTE +Handle the +.Fa sbt +argument as an absolute time since boot. +By default, +.Fa sbt +is treated as a relative amount of time, +similar to +.Fa ticks . +.It Dv C_DIRECT_EXEC +Run the handler directly from hardware interrupt context instead of from the +softclock thread. +This reduces latency and overhead, but puts more constraints on the callout +function. +Callout functions run in this context may use only spin mutexes for locking +and should be as small as possible because they run with absolute priority. +.It Fn C_PREL +Specifies relative event time precision as binary logarithm of time interval +divided by acceptable time deviation: 1 -- 1/2, 2 -- 1/4, etc. +Note that the larger of +.Fa pr +or this value is used as the length of the time window. +Smaller values +.Pq which result in larger time intervals +allow the callout subsystem to aggregate more events in one timer interrupt. +.It Dv C_PRECALC +The +.Fa sbt +argument specifies the absolute time at which the callout should be run, +and the +.Fa pr +argument specifies the requested precision, which will not be +adjusted during the scheduling process. +The +.Fa sbt +and +.Fa pr +values should be calculated by an earlier call to +.Fn callout_when +which uses the user-supplied +.Fa sbt , +.Fa pr , +and +.Fa flags +values. +.It Dv C_HARDCLOCK +Align the timeouts to +.Fn hardclock +calls if possible. +.El +.Pp +The +.Fn callout_reset +functions accept a +.Fa func +argument which identifies the function to be called when the time expires. +It must be a pointer to a function that takes a single +.Fa void * +argument. +Upon invocation, +.Fa func +will receive +.Fa arg +as its only argument. +The +.Fn callout_schedule +functions reuse the +.Fa func +and +.Fa arg +arguments from the previous callout. +Note that one of the +.Fn callout_reset +functions must always be called to initialize +.Fa func +and +.Fa arg +before one of the +.Fn callout_schedule +functions can be used. +.Pp +The callout subsystem provides a softclock thread for each CPU in the system. +Callouts are assigned to a single CPU and are executed by the softclock thread +for that CPU. +Initially, +callouts are assigned to CPU 0. +The +.Fn callout_reset_on , +.Fn callout_reset_sbt_on , +.Fn callout_schedule_on +and +.Fn callout_schedule_sbt_on +functions assign the callout to CPU +.Fa cpu . +The +.Fn callout_reset_curcpu , +.Fn callout_reset_sbt_curpu , +.Fn callout_schedule_curcpu +and +.Fn callout_schedule_sbt_curcpu +functions assign the callout to the current CPU. +The +.Fn callout_reset , +.Fn callout_reset_sbt , +.Fn callout_schedule +and +.Fn callout_schedule_sbt +functions schedule the callout to execute in the softclock thread of the CPU +to which it is currently assigned. +.Pp +Softclock threads are not pinned to their respective CPUs by default. +The softclock thread for CPU 0 can be pinned to CPU 0 by setting the +.Va kern.pin_default_swi +loader tunable to a non-zero value. +Softclock threads for CPUs other than zero can be pinned to their +respective CPUs by setting the +.Va kern.pin_pcpu_swi +loader tunable to a non-zero value. +.Pp +The macros +.Fn callout_pending , +.Fn callout_active +and +.Fn callout_deactivate +provide access to the current state of the callout. +The +.Fn callout_pending +macro checks whether a callout is +.Em pending ; +a callout is considered +.Em pending +when a timeout has been set but the time has not yet arrived. +Note that once the timeout time arrives and the callout subsystem +starts to process this callout, +.Fn callout_pending +will return +.Dv FALSE +even though the callout function may not have finished +.Pq or even begun +executing. +The +.Fn callout_active +macro checks whether a callout is marked as +.Em active , +and the +.Fn callout_deactivate +macro clears the callout's +.Em active +flag. +The callout subsystem marks a callout as +.Em active +when a timeout is set and it clears the +.Em active +flag in +.Fn callout_stop +and +.Fn callout_drain , +but it +.Em does not +clear it when a callout expires normally via the execution of the +callout function. +.Pp +The +.Fn callout_when +function may be used to pre-calculate the absolute time at which the +timeout should be run and the precision of the scheduled run time +according to the required time +.Fa sbt , +precision +.Fa precision , +and additional adjustments requested by the +.Fa flags +argument. +Flags accepted by the +.Fn callout_when +function are the same as flags for the +.Fn callout_reset +function. +The resulting time is assigned to the variable pointed to by the +.Fa sbt_res +argument, and the resulting precision is assigned to +.Fa *precision_res . +When passing the results to +.Fa callout_reset , +add the +.Va C_PRECALC +flag to +.Fa flags , +to avoid incorrect re-adjustment. +The function is intended for situations where precise time of the callout +run should be known in advance, since +trying to read this time from the callout structure itself after a +.Fn callout_reset +call is racy. +.Ss "Avoiding Race Conditions" +The callout subsystem invokes callout functions from its own thread +context. +Without some kind of synchronization, +it is possible that a callout +function will be invoked concurrently with an attempt to stop or reset +the callout by another thread. +In particular, since callout functions typically acquire a lock as +their first action, the callout function may have already been invoked, +but is blocked waiting for that lock at the time that another thread +tries to reset or stop the callout. +.Pp +There are three main techniques for addressing these +synchronization concerns. +The first approach is preferred as it is the simplest: +.Bl -enum -offset indent +.It +Callouts can be associated with a specific lock when they are initialized +by +.Fn callout_init_mtx , +.Fn callout_init_rm , +or +.Fn callout_init_rw . +When a callout is associated with a lock, +the callout subsystem acquires the lock before the callout function is +invoked. +This allows the callout subsystem to transparently handle races between +callout cancellation, +scheduling, +and execution. +Note that the associated lock must be acquired before calling +.Fn callout_stop +or one of the +.Fn callout_reset +or +.Fn callout_schedule +functions to provide this safety. +.Pp +A callout initialized via +.Fn callout_init +with +.Fa mpsafe +set to zero is implicitly associated with the +.Va Giant +mutex. +If +.Va Giant +is held when cancelling or rescheduling the callout, +then its use will prevent races with the callout function. +.It +The return value from +.Fn callout_stop +.Po +or the +.Fn callout_reset +and +.Fn callout_schedule +function families +.Pc +indicates whether or not the callout was removed. +If it is known that the callout was set and the callout function has +not yet executed, then a return value of +.Dv FALSE +indicates that the callout function is about to be called. +For example: +.Bd -literal -offset indent +if (sc->sc_flags & SCFLG_CALLOUT_RUNNING) { + if (callout_stop(&sc->sc_callout)) { + sc->sc_flags &= ~SCFLG_CALLOUT_RUNNING; + /* successfully stopped */ + } else { + /* + * callout has expired and callout + * function is about to be executed + */ + } +} +.Ed +.It +The +.Fn callout_pending , +.Fn callout_active +and +.Fn callout_deactivate +macros can be used together to work around the race conditions. +When a callout's timeout is set, the callout subsystem marks the +callout as both +.Em active +and +.Em pending . +When the timeout time arrives, the callout subsystem begins processing +the callout by first clearing the +.Em pending +flag. +It then invokes the callout function without changing the +.Em active +flag, and does not clear the +.Em active +flag even after the callout function returns. +The mechanism described here requires the callout function itself to +clear the +.Em active +flag using the +.Fn callout_deactivate +macro. +The +.Fn callout_stop +and +.Fn callout_drain +functions always clear both the +.Em active +and +.Em pending +flags before returning. +.Pp +The callout function should first check the +.Em pending +flag and return without action if +.Fn callout_pending +returns +.Dv TRUE . +This indicates that the callout was rescheduled using +.Fn callout_reset +just before the callout function was invoked. +If +.Fn callout_active +returns +.Dv FALSE +then the callout function should also return without action. +This indicates that the callout has been stopped. +Finally, the callout function should call +.Fn callout_deactivate +to clear the +.Em active +flag. +For example: +.Bd -literal -offset indent +mtx_lock(&sc->sc_mtx); +if (callout_pending(&sc->sc_callout)) { + /* callout was reset */ + mtx_unlock(&sc->sc_mtx); + return; +} +if (!callout_active(&sc->sc_callout)) { + /* callout was stopped */ + mtx_unlock(&sc->sc_mtx); + return; +} +callout_deactivate(&sc->sc_callout); +/* rest of callout function */ +.Ed +.Pp +Together with appropriate synchronization, such as the mutex used above, +this approach permits the +.Fn callout_stop +and +.Fn callout_reset +functions to be used at any time without races. +For example: +.Bd -literal -offset indent +mtx_lock(&sc->sc_mtx); +callout_stop(&sc->sc_callout); +/* The callout is effectively stopped now. */ +.Ed +.Pp +If the callout is still pending then these functions operate normally, +but if processing of the callout has already begun then the tests in +the callout function cause it to return without further action. +Synchronization between the callout function and other code ensures that +stopping or resetting the callout will never be attempted while the +callout function is past the +.Fn callout_deactivate +call. +.Pp +The above technique additionally ensures that the +.Em active +flag always reflects whether the callout is effectively enabled or +disabled. +If +.Fn callout_active +returns false, then the callout is effectively disabled, since even if +the callout subsystem is actually just about to invoke the callout +function, the callout function will return without action. +.El +.Pp +There is one final race condition that must be considered when a +callout is being stopped for the last time. +In this case it may not be safe to let the callout function itself +detect that the callout was stopped, since it may need to access +data objects that have already been destroyed or recycled. +To ensure that the callout is completely finished, a call to +.Fn callout_drain +should be used. +In particular, +a callout should always be drained prior to destroying its associated lock +or releasing the storage for the callout structure. +.Sh RETURN VALUES +The +.Fn callout_active +macro returns the state of a callout's +.Em active +flag. +.Pp +The +.Fn callout_pending +macro returns the state of a callout's +.Em pending +flag. +.Pp +The +.Fn callout_reset +and +.Fn callout_schedule +function families return a value of one if the callout was pending before the new +function invocation was scheduled. +.Pp +The +.Fn callout_stop +and +.Fn callout_drain +functions return a value of one if the callout was still pending when it was +called, a zero if the callout could not be stopped and a negative one is it +was either not running or has already completed. +.Sh SEE ALSO +.Xr dtrace_callout_execute 4 +.Sh HISTORY +.Fx +initially used the long standing +.Bx +linked list +callout mechanism which offered O(n) insertion and removal running time +but did not generate or require handles for untimeout operations. +.Pp +.Fx 3.0 +introduced a new set of timeout and untimeout routines from +.Nx +based on the work of +.An Adam M. Costello +and +.An George Varghese , +published in a technical report entitled +.%T "Redesigning the BSD Callout and Timer Facilities" +and modified for inclusion in +.Fx +by +.An Justin T. Gibbs . +The original work on the data structures used in that implementation +was published by +.An G. Varghese +and +.An A. Lauck +in the paper +.%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility" +in the +.%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" . +.Pp +.Fx 3.3 +introduced the first implementations of +.Fn callout_init , +.Fn callout_reset , +and +.Fn callout_stop +which permitted callers to allocate dedicated storage for callouts. +This ensured that a callout would always fire unlike +.Fn timeout +which would silently fail if it was unable to allocate a callout. +.Pp +.Fx 5.0 +permitted callout handlers to be tagged as MPSAFE via +.Fn callout_init . +.Pp +.Fx 5.3 +introduced +.Fn callout_drain . +.Pp +.Fx 6.0 +introduced +.Fn callout_init_mtx . +.Pp +.Fx 8.0 +introduced per-CPU callout wheels, +.Fn callout_init_rw , +and +.Fn callout_schedule . +.Pp +.Fx 9.0 +changed the underlying timer interrupts used to drive callouts to prefer +one-shot event timers instead of a periodic timer interrupt. +.Pp +.Fx 10.0 +switched the callout wheel to support tickless operation. +These changes introduced +.Vt sbintime_t +and the +.Fn callout_reset_sbt* +family of functions. +.Fx 10.0 also added +.Dv C_DIRECT_EXEC +and +.Fn callout_init_rm . +.Pp +.Fx 10.2 +introduced the +.Fn callout_schedule_sbt* +family of functions. +.Pp +.Fx 11.0 +introduced +.Fn callout_async_drain . +.Fx 11.1 +introduced +.Fn callout_when . +.Fx 13.0 +removed +.Vt timeout_t , +.Fn timeout , +and +.Fn untimeout . diff --git a/static/freebsd/man9/casuword.9 b/static/freebsd/man9/casuword.9 new file mode 100644 index 00000000..2623bea9 --- /dev/null +++ b/static/freebsd/man9/casuword.9 @@ -0,0 +1,112 @@ +.\" Copyright (c) 2014, 2019 The FreeBSD Foundation +.\" +.\" Part of this documentation was written by +.\" Konstantin Belousov under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" 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 AUTHORS 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 AUTHORS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 19, 2019 +.Dt CASU 9 +.Os +.Sh NAME +.Nm casueword , +.Nm casueword32 , +.Nm casuword , +.Nm casuword32 +.Nd fetch, compare and store data from user-space +.Sh SYNOPSIS +.In sys/types.h +.In sys/systm.h +.Ft int +.Fo casueword +.Fa "volatile u_long *base" +.Fa "u_long oldval" +.Fa "u_long *oldvalp" +.Fa "u_long newval" +.Fc +.Ft int +.Fo casueword32 +.Fa "volatile uint32_t *base" +.Fa "uint32_t oldval" +.Fa "uint32_t *oldvalp" +.Fa "uint32_t newval" +.Fc +.Ft u_long +.Fo casuword +.Fa "volatile u_long *base" +.Fa "u_long oldval" +.Fa "u_long newval" +.Fc +.Ft uint32_t +.Fo casuword32 +.Fa "volatile uint32_t *base" +.Fa "uint32_t oldval" +.Fa "uint32_t newval" +.Fc +.Sh DESCRIPTION +The +.Nm +functions are designed to perform atomic compare-and-swap operation on +the value in the usermode memory of the current process. +.Pp +The +.Nm +routines reads the value from user memory with address +.Pa base , +and compare the value read with +.Pa oldval . +If the values are equal, +.Pa newval +is written to the +.Pa *base . +In case of +.Fn casueword32 +and +.Fn casueword , +old value is stored into the (kernel-mode) variable pointed by +.Pa *oldvalp . +The userspace value must be naturally aligned. +.Pp +The callers of +.Fn casuword +and +.Fn casuword32 +functions cannot distinguish between -1 read from +userspace and function failure. +.Sh RETURN VALUES +The +.Fn casuword +and +.Fn casuword32 +functions return the data fetched or -1 on failure. +The +.Fn casueword +and +.Fn casueword32 +functions return 0 on success, -1 on failure to access memory, +and 1 when comparison or store failed. +The store can fail on load-linked/store-conditional architectures. +.Sh SEE ALSO +.Xr atomic 9 , +.Xr fetch 9 , +.Xr store 9 diff --git a/static/freebsd/man9/cd.9 b/static/freebsd/man9/cd.9 new file mode 100644 index 00000000..74151f8a --- /dev/null +++ b/static/freebsd/man9/cd.9 @@ -0,0 +1,121 @@ +.\" Copyright (c) 1997 +.\" John-Mark Gurney. 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 John-Mark Gurney 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 March 25, 2014 +.Dt CD 9 +.Os +.Sh NAME +.Nm cd +.Nd CDROM driver for the CAM SCSI subsystem +.Sh DESCRIPTION +The +.Nm +device driver provides a read-only interface for CDROM drives +.Tn ( SCSI +type 5) +and WORM drives +.Tn ( SCSI +type 4) +that support CDROM type commands. +Some drives do not behave as the driver expects. +See the +.Sx QUIRKS +section for information on possible flags. +.Sh QUIRKS +Each +.Tn CD-ROM +device can have different interpretations of the +.Tn SCSI +spec. +This can lead to drives requiring special handling in the driver. +The following is a list of quirks that the driver recognizes. +.Bl -tag -width CD_Q_BCD_TRACKS +.It Dv CD_Q_NO_TOUCH +This flag tells the driver not to probe the drive at attach time to see if +there is a disk in the drive and find out what size it is. +This flag is currently unimplemented in the CAM +.Nm +driver. +.It Dv CD_Q_BCD_TRACKS +This flag is for broken drives that return the track numbers in packed BCD +instead of straight decimal. +If the drive seems to skip tracks +(tracks 10-15 are skipped) +then you have a drive that is in need of this flag. +.It Dv CD_Q_NO_CHANGER +This flag tells the driver that the device in question is not a changer. +This is only necessary for a CDROM device with multiple luns that are not a +part of a changer. +.It Dv CD_Q_CHANGER +This flag tells the driver that the given device is a multi-lun changer. +In general, the driver will figure this out automatically when it sees a +LUN greater than 0. +Setting this flag only has the effect of telling the +driver to run the initial read capacity command for LUN 0 of the changer +through the changer scheduling code. +.It Dv CD_Q_10_BYTE_ONLY +This flag tells the driver that the given device only accepts 10 byte MODE +SENSE/MODE SELECT commands. +In general these types of quirks should not be +added to the +.Xr cd 4 +driver. +The reason is that the driver does several things to attempt to +determine whether the drive in question needs 10 byte commands. +First, it +issues a CAM Path Inquiry command to determine whether the protocol that +the drive speaks typically only allows 10 byte commands. +(ATAPI and USB +are two prominent examples of protocols where you generally only want to +send 10 byte commands.) +Then, if it gets an ILLEGAL REQUEST error back +from a 6 byte MODE SENSE or MODE SELECT command, it attempts to send the 10 +byte version of the command instead. +The only reason you would need a +quirk is if your drive uses a protocol (e.g., +.Tn SCSI ) +that typically does not have a problem with 6 byte commands. +.El +.Sh FILES +.Bl -tag -width /sys/cam/scsi/scsi_cd.c -compact +.It Pa /sys/cam/scsi/scsi_cd.c +is the driver source file. +.El +.Sh SEE ALSO +.Xr cd 4 , +.Xr scsi 4 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 2.2 . +.Sh AUTHORS +.An -nosplit +This +manual page was written by +.An John-Mark Gurney Aq Mt jmg@FreeBSD.org . +It was updated for CAM and +.Fx 3.0 +by +.An Kenneth Merry Aq Mt ken@FreeBSD.org . diff --git a/static/freebsd/man9/cdefs.9 b/static/freebsd/man9/cdefs.9 new file mode 100644 index 00000000..cc56e34d --- /dev/null +++ b/static/freebsd/man9/cdefs.9 @@ -0,0 +1,487 @@ +.\"- +.\" Copyright (c) 2024 M. Warner Losh +.\" +.\" 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/static/freebsd/man9/cnv.9 b/static/freebsd/man9/cnv.9 new file mode 100644 index 00000000..fa5310e1 --- /dev/null +++ b/static/freebsd/man9/cnv.9 @@ -0,0 +1,218 @@ +.\" +.\" Copyright (c) 2016 Adam Starak +.\" 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 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" +.Sh LIBRARY +.Lb libnv +.Sh SYNOPSIS +.In sys/cnv.h +.Ft const char * +.Fn cnvlist_name "const void *cookie" +.Ft int +.Fn cnvlist_type "const void *cookie" +.\" +.Ft bool +.Fn cnvlist_get_bool "const void *cookie" +.Ft uint64_t +.Fn cnvlist_get_number "const void *cookie" +.Ft "const char *" +.Fn cnvlist_get_string "const void *cookie" +.Ft "const nvlist_t *" +.Fn cnvlist_get_nvlist "const void *cookie" +.Ft "const void *" +.Fn cnvlist_get_binary "const void *cookie" "size_t *sizep" +.Ft "const bool *" +.Fn cnvlist_get_bool_array "const void *cookie" "size_t *nitemsp" +.Ft "const uint64_t *" +.Fn cnvlist_get_number_array "const void *cookie" "size_t *nitemsp" +.Ft "const char * const *" +.Fn cnvlist_get_string_array "const void *cookie" "size_t *nitemsp" +.Ft "const nvlist_t * const *" +.Fn cnvlist_get_nvlist_array "const void *cookie" "size_t *nitemsp" +.Ft int +.Fn cnvlist_get_descriptor "const void *cookie" +.Ft "const int *" +.Fn cnvlist_get_descriptor_array "const void *cookie" "size_t *nitemsp" +.\" +.Ft bool +.Fn cnvlist_take_bool "void *cookie" +.Ft uint64_t +.Fn cnvlist_take_number "void *cookie" +.Ft "const char *" +.Fn cnvlist_take_string "void *cookie" +.Ft "const nvlist_t *" +.Fn cnvlist_take_nvlist "void *cookie" +.Ft "const void *" +.Fn cnvlist_take_binary "void *cookie" "size_t *sizep" +.Ft "const bool *" +.Fn cnvlist_take_bool_array "void *cookie" "size_t *nitemsp" +.Ft "const uint64_t *" +.Fn cnvlist_take_number_array "void *cookie" "size_t *nitemsp" +.Ft "const char * const *" +.Fn cnvlist_take_string_array "void *cookie" "size_t *nitemsp" +.Ft "const nvlist_t * const *" +.Fn cnvlist_take_nvlist_array "void *cookie" "size_t *nitemsp" +.Ft int +.Fn cnvlist_take_descriptor "void *cookie" +.Ft "const int *" +.Fn cnvlist_take_descriptor_array "void *cookie" "size_t *nitemsp" +.\" +.Ft void +.Fn cnvlist_free_null "void *cookie" +.Ft void +.Fn cnvlist_free_bool "void *cookie" +.Ft void +.Fn cnvlist_free_number "void *cookie" +.Ft void +.Fn cnvlist_free_string "void *cookie" +.Ft void +.Fn cnvlist_free_nvlist "void *cookie" +.Ft void +.Fn cnvlist_free_descriptor "void *cookie" +.Ft void +.Fn cnvlist_free_binary "void *cookie" +.Ft void +.Fn cnvlist_free_bool_array "void *cookie" +.Ft void +.Fn cnvlist_free_number_array "void *cookie" +.Ft void +.Fn cnvlist_free_string_array "void *cookie" +.Ft void +.Fn cnvlist_free_nvlist_array "void *cookie" +.Ft void +.Fn cnvlist_free_descriptor_array "void *cookie" +.Sh DESCRIPTION +The +.Nm libnv +library permits easy management of name/value pairs and can send and receive +them over sockets. +For more information, see +.Xr nv 9 . +.Pp +The concept of cookies is explained in +.Fn nvlist_next , +.Fn nvlist_get_parent , +and +.Fn nvlist_get_pararr +from +.Xr nv 9 . +.Pp +The +.Fn cnvlist_name +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 +.Fa cookie . +Types which can be returned are described in +.Xr nv 9 . +.Pp +The +.Nm cnvlist_get +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. +The nvlist must not be in an error state. +.Pp +The +.Nm cnvlist_take +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 . +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 +.Fn close 2 . +.Pp +The +.Nm cnvlist_free +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 +aborts. +.Sh EXAMPLES +The following example demonstrates how to deal with the cnvlist API. +.Bd -literal +int type; +void *cookie, *scookie, *bcookie; +nvlist_t *nvl; +char *name; + +nvl = nvlist_create(0); +nvlist_add_bool(nvl, "test", 1 == 2); +nvlist_add_string(nvl, "test2", "cnvlist"); +cookie = NULL; + +while (nvlist_next(nvl, &type, &cookie) != NULL) { + switch (type) { + case NV_TYPE_BOOL: + printf("test: %d\\n", cnvlist_get_bool(cookie)); + bcookie = cookie; + break; + case NV_TYPE_STRING: + printf("test2: %s\\n", cnvlist_get_string(cookie)); + scookie = cookie; + break; + } +} + +name = cnvlist_take_string(scookie); +cnvlist_free_bool(bcookie); + +printf("test2: %s\\n", name); +free(name); + +printf("nvlist_empty = %d\\n", nvlist_empty(nvl)); +nvlist_destroy(nvl); + +return (0); +.Ed +.Sh SEE ALSO +.Xr close 2 , +.Xr free 3 , +.Xr nv 9 +.Sh AUTHORS +The +.Nm cnv +API was created during the Google Summer Of Code 2016 by +.An Adam Starak . diff --git a/static/freebsd/man9/condvar.9 b/static/freebsd/man9/condvar.9 new file mode 100644 index 00000000..afadd733 --- /dev/null +++ b/static/freebsd/man9/condvar.9 @@ -0,0 +1,259 @@ +.\" +.\" Copyright (C) 2000 Jason Evans . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 February 19, 2013 +.Dt CONDVAR 9 +.Os +.Sh NAME +.Nm condvar , +.Nm cv_init , +.Nm cv_destroy , +.Nm cv_wait , +.Nm cv_wait_sig , +.Nm cv_wait_unlock , +.Nm cv_timedwait , +.Nm cv_timedwait_sbt , +.Nm cv_timedwait_sig , +.Nm cv_timedwait_sig_sbt , +.Nm cv_signal , +.Nm cv_broadcast , +.Nm cv_broadcastpri , +.Nm cv_wmesg +.Nd kernel condition variable +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.In sys/condvar.h +.Ft void +.Fn cv_init "struct cv *cvp" "const char *desc" +.Ft void +.Fn cv_destroy "struct cv *cvp" +.Ft void +.Fn cv_wait "struct cv *cvp" "lock" +.Ft int +.Fn cv_wait_sig "struct cv *cvp" "lock" +.Ft void +.Fn cv_wait_unlock "struct cv *cvp" "lock" +.Ft int +.Fn cv_timedwait "struct cv *cvp" "lock" "int timo" +.Ft int +.Fn cv_timedwait_sbt "struct cv *cvp" "lock" "sbintime_t sbt" \ +"sbintime_t pr" "int flags" +.Ft int +.Fn cv_timedwait_sig "struct cv *cvp" "lock" "int timo" +.Ft int +.Fn cv_timedwait_sig_sbt "struct cv *cvp" "lock" "sbintime_t sbt" \ +"sbintime_t pr" "int flags" +.Ft void +.Fn cv_signal "struct cv *cvp" +.Ft void +.Fn cv_broadcast "struct cv *cvp" +.Ft void +.Fn cv_broadcastpri "struct cv *cvp" "int pri" +.Ft const char * +.Fn cv_wmesg "struct cv *cvp" +.Sh DESCRIPTION +Condition variables are used in conjunction with mutexes to wait for conditions +to occur. +Condition variables are created with +.Fn cv_init , +where +.Fa cvp +is a pointer to space for a +.Vt struct cv , +and +.Fa desc +is a pointer to a null-terminated character string that describes the condition +variable. +Condition variables are destroyed with +.Fn cv_destroy . +Threads wait on condition variables by calling +.Fn cv_wait , +.Fn cv_wait_sig , +.Fn cv_wait_unlock , +.Fn cv_timedwait , +or +.Fn cv_timedwait_sig . +Threads unblock waiters by calling +.Fn cv_signal +to unblock one waiter, or +.Fn cv_broadcast +or +.Fn cv_broadcastpri +to unblock all waiters. +In addition to waking waiters, +.Fn cv_broadcastpri +ensures that all of the waiters have a priority of at least +.Fa pri +by raising the priority of any threads that do not. +.Fn cv_wmesg +returns the description string of +.Fa cvp , +as set by the initial call to +.Fn cv_init . +.Pp +The +.Fa lock +argument is a pointer to either a +.Xr mutex 9 , +.Xr rwlock 9 , +or +.Xr sx 9 +lock. +A +.Xr mutex 9 +argument must be initialized with +.Dv MTX_DEF +and not +.Dv MTX_SPIN . +A thread must hold +.Fa lock +before calling +.Fn cv_wait , +.Fn cv_wait_sig , +.Fn cv_wait_unlock , +.Fn cv_timedwait , +or +.Fn cv_timedwait_sig . +When a thread waits on a condition, +.Fa lock +is atomically released before the thread is blocked, then reacquired +before the function call returns. +In addition, the thread will fully drop the +.Va Giant +mutex +(even if recursed) +while the it is suspended and will reacquire the +.Va Giant +mutex before the function returns. +The +.Fn cv_wait_unlock +function does not reacquire the lock before returning. +Note that the +.Va Giant +mutex may be specified as +.Fa lock . +However, +.Va Giant +may not be used as +.Fa lock +for the +.Fn cv_wait_unlock +function. +All waiters must pass the same +.Fa lock +in conjunction with +.Fa cvp . +.Pp +When +.Fn cv_wait , +.Fn cv_wait_sig , +.Fn cv_wait_unlock , +.Fn cv_timedwait , +and +.Fn cv_timedwait_sig +unblock, their calling threads are made runnable. +.Fn cv_timedwait +and +.Fn cv_timedwait_sig +wait for at most +.Fa timo +/ +.Dv HZ +seconds before being unblocked and returning +.Er EWOULDBLOCK ; +otherwise, they return 0. +.Fn cv_wait_sig +and +.Fn cv_timedwait_sig +return prematurely with a value of +.Er EINTR +or +.Er ERESTART +if a signal is caught, or 0 if signaled via +.Fn cv_signal +or +.Fn cv_broadcast . +.Pp +.Fn cv_timedwait_sbt +and +.Fn cv_timedwait_sig_sbt +functions take +.Fa sbt +argument instead of +.Fa timo . +It allows to specify relative or absolute unblock time with higher resolution +in form of +.Vt sbintime_t . +The parameter +.Fa pr +allows to specify wanted absolute event precision. +The parameter +.Fa flags +allows to pass additional +.Fn callout_reset_sbt +flags. +.Sh RETURN VALUES +If successful, +.Fn cv_wait_sig , +.Fn cv_timedwait , +and +.Fn cv_timedwait_sig +return 0. +Otherwise, a non-zero error code is returned. +.Pp +.Fn cv_wmesg +returns the description string that was passed to +.Fn cv_init . +.Sh ERRORS +.Fn cv_wait_sig +and +.Fn cv_timedwait_sig +will fail if: +.Bl -tag -width Er +.It Bq Er EINTR +A signal was caught and the system call should be interrupted. +.It Bq Er ERESTART +A signal was caught and the system call should be restarted. +.El +.Pp +.Fn cv_timedwait +and +.Fn cv_timedwait_sig +will fail if: +.Bl -tag -width Er +.It Bq Er EWOULDBLOCK +Timeout expired. +.El +.Sh SEE ALSO +.Xr callout 9 , +.Xr locking 9 , +.Xr mtx_pool 9 , +.Xr mutex 9 , +.Xr rwlock 9 , +.Xr sema 9 , +.Xr sleep 9 , +.Xr sx 9 diff --git a/static/freebsd/man9/config_intrhook.9 b/static/freebsd/man9/config_intrhook.9 new file mode 100644 index 00000000..4ab49130 --- /dev/null +++ b/static/freebsd/man9/config_intrhook.9 @@ -0,0 +1,137 @@ +.\" +.\" Copyright (C) 2006 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 March 8, 2021 +.Dt CONFIG_INTRHOOK 9 +.Os +.Sh NAME +.Nm config_intrhook +.Nd schedule a function to be run after interrupts have been enabled, +but before root is mounted +.Sh SYNOPSIS +.In sys/kernel.h +.Vt typedef void (*ich_func_t)(void *arg); +.Ft int +.Fn config_intrhook_establish "struct intr_config_hook *hook" +.Ft void +.Fn config_intrhook_disestablish "struct intr_config_hook *hook" +.Ft int +.Fn config_intrhook_drain "struct intr_config_hook *hook" +.Ft void +.Fn config_intrhook_oneshot "ich_func_t func" "void *arg" +.Sh DESCRIPTION +The +.Fn config_intrhook_establish +function schedules a function to be run after interrupts have been +enabled, but before root is mounted. +If the system has already passed this point in its initialization, +the function is called immediately. +.Pp +The +.Fn config_intrhook_disestablish +function removes the entry from the hook queue. +.Pp +The +.Fn config_intrhook_drain +function removes the entry from the hook queue in a safe way. +If the hook is not currently active it removes +.Fa hook +from the hook queue and returns +.Vt ICHS_QUEUED . +If the hook is active, it waits for the hook to complete before returning +.Vt ICHS_RUNNING . +If the hook has previously completed, it returns +.Vt ICHS_DONE . +Because a +.Vt config_intrhook +is undefined prior to +.Fn config_intrhook_establish , +this function may only be called after that function has returned. +.Pp +The +.Fn config_intrhook_oneshot +function schedules a function to be run as described for +.Fn config_intrhook_establish ; +the entry is automatically removed from the hook queue +after that function runs. +This is appropriate when additional device configuration must be done +after interrupts are enabled, but there is no need to stall the +boot process after that. +This function allocates memory using M_WAITOK; do not call this while +holding any non-sleepable locks. +.Pp +Before root is mounted, all the previously established hooks are +run. +The boot process is then stalled until all handlers remove their hook +from the hook queue with +.Fn config_intrhook_disestablish . +The boot process then proceeds to attempt to mount the root file +system. +Any driver that can potentially provide devices they wish to be +mounted as root must use either this hook, or probe all these devices +in the initial probe. +Since interrupts are disabled during the probe process, many drivers +need a method to probe for devices with interrupts enabled. +.Pp +The requests are made with the +.Vt intr_config_hook +structure. +This structure is defined as follows: +.Bd -literal +struct intr_config_hook { + TAILQ_ENTRY(intr_config_hook) ich_links;/* Private */ + ich_func_t ich_func; /* function to call */ + void *ich_arg; /* Argument to call */ +}; +.Ed +.Pp +Storage for the +.Vt intr_config_hook +structure must be provided by the driver. +It must be stable from just before the hook is established until +after the hook is disestablished. +.Pp +Specifically, hooks are run at +.Fn SI_SUB_INT_CONFIG_HOOKS , +which is immediately after the scheduler is started, +and just before the root file system device is discovered. +.Sh RETURN VALUES +A zero return value means the hook was successfully added to the queue +(with either deferred or immediate execution). +A non-zero return value means the hook could not be added to the queue +because it was already on the queue. +.Sh SEE ALSO +.Xr DEVICE_ATTACH 9 +.Sh HISTORY +These functions were introduced in +.Fx 3.0 +with the CAM subsystem, but are available for any driver to use. +.Sh AUTHORS +.An -nosplit +The functions were written by +.An Justin Gibbs Aq Mt gibbs@FreeBSD.org . +This manual page was written by +.An M. Warner Losh Aq Mt imp@FreeBSD.org . diff --git a/static/freebsd/man9/contigmalloc.9 b/static/freebsd/man9/contigmalloc.9 new file mode 100644 index 00000000..2e5d55ae --- /dev/null +++ b/static/freebsd/man9/contigmalloc.9 @@ -0,0 +1,149 @@ +.\" +.\" Copyright (c) 2004 Joseph Koshy +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' +.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd July 26, 2024 +.Dt CONTIGMALLOC 9 +.Os +.Sh NAME +.Nm contigmalloc +.Nd manage contiguous kernel physical memory +.Sh SYNOPSIS +.In sys/types.h +.In sys/malloc.h +.Ft "void *" +.Fo contigmalloc +.Fa "unsigned long size" +.Fa "struct malloc_type *type" +.Fa "int flags" +.Fa "vm_paddr_t low" +.Fa "vm_paddr_t high" +.Fa "unsigned long alignment" +.Fa "vm_paddr_t boundary" +.Fc +.In sys/param.h +.In sys/domainset.h +.Ft "void *" +.Fo contigmalloc_domainset +.Fa "unsigned long size" +.Fa "struct malloc_type *type" +.Fa "struct domainset *ds" +.Fa "int flags" +.Fa "vm_paddr_t low" +.Fa "vm_paddr_t high" +.Fa "unsigned long alignment" +.Fa "vm_paddr_t boundary" +.Fc +.Sh DESCRIPTION +The +.Fn contigmalloc +function allocates +.Fa size +bytes of contiguous physical memory that is aligned to +.Fa alignment +bytes, and which does not cross a boundary of +.Fa boundary +bytes. +If successful, the allocation will reside between physical addresses +.Fa low +and +.Fa high . +The returned pointer points to a wired kernel virtual +address range of +.Fa size +bytes allocated from the kernel virtual address (KVA) map. +.Pp +The +.Fn contigmalloc_domainset +variant allows the caller to additionally specify a +.Xr numa 4 +domain selection policy. +See +.Xr domainset 9 +for some example policies. +.Pp +The +.Fa flags +parameter modifies +.Fn contigmalloc Ns 's +behaviour as follows: +.Bl -tag -width indent +.It Dv M_ZERO +Causes the allocated physical memory to be zero filled. +.It Dv M_NOWAIT +Causes +.Fn contigmalloc +to return +.Dv NULL +if the request cannot be immediately fulfilled due to resource shortage. +.El +.Pp +Other flags (if present) are ignored. +.Pp +The +.Fn contigfree +function is deprecated. +Use +.Xr free 9 +instead. +.Sh IMPLEMENTATION NOTES +The +.Fn contigmalloc +function does not sleep waiting for memory resources to be freed up, +but instead actively reclaims pages before giving up. +However, unless +.Dv M_NOWAIT +is specified, it may select a page for reclamation that must first be +written to backing storage, causing it to sleep. +.Pp +.Sh RETURN VALUES +The +.Fn contigmalloc +function returns a kernel virtual address if allocation succeeds, +or +.Dv NULL +otherwise. +.Sh EXAMPLES +.Bd -literal +void *p; +p = contigmalloc(8192, M_DEVBUF, M_ZERO, 0, (1L << 22), + 32 * 1024, 1024 * 1024); +.Ed +.Pp +Ask for 8192 bytes of zero-filled memory residing between physical +address 0 and 4194303 inclusive, aligned to a 32K boundary and not +crossing a 1M address boundary. +.Sh DIAGNOSTICS +The +.Fn contigmalloc +function will panic if +.Fa size +is zero, or if +.Fa alignment +or +.Fa boundary +is not a power of two. +.Sh SEE ALSO +.Xr malloc 9 , +.Xr memguard 9 diff --git a/static/freebsd/man9/copy.9 b/static/freebsd/man9/copy.9 new file mode 100644 index 00000000..3a3105dd --- /dev/null +++ b/static/freebsd/man9/copy.9 @@ -0,0 +1,164 @@ +.\" $NetBSD: copy.9,v 1.2 1996/01/09 03:23:04 thorpej Exp $ +.\" +.\" Copyright (c) 1996 Jason R. Thorpe. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed by Kenneth Stailey. +.\" +.\" 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 for the NetBSD Project +.\" by Jason R. Thorpe. +.\" 4. 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 May 11, 2020 +.Dt COPY 9 +.Os +.Sh NAME +.Nm copy , +.Nm copyin , +.Nm copyin_nofault , +.Nm copyout , +.Nm copyout_nofault , +.Nm copystr , +.Nm copyinstr +.Nd heterogeneous address space copy functions +.Sh SYNOPSIS +.In sys/types.h +.In sys/systm.h +.Ft int +.Fn copyin "const void *uaddr" "void *kaddr" "size_t len" +.Ft int +.Fn copyin_nofault "const void *uaddr" "void *kaddr" "size_t len" +.Ft int +.Fn copyout "const void *kaddr" "void *uaddr" "size_t len" +.Ft int +.Fn copyout_nofault "const void *kaddr" "void *uaddr" "size_t len" +.Ft int __deprecated +.Fn copystr "const void *kfaddr" "void *kdaddr" "size_t len" "size_t *done" +.Ft int +.Fn copyinstr "const void *uaddr" "void *kaddr" "size_t len" "size_t *done" +.Sh DESCRIPTION +The +.Nm +functions are designed to copy contiguous data from one address space +to another. +.Pp +.Fn copystr +is deprecated and should be replaced with +.Xr strlcpy 9 . +It will be removed from +.Fx 13 . +.Pp +The +.Fn copyin +and +.Fn copyin_nofault +functions copy +.Fa len +bytes of data from the user-space address +.Fa uaddr +to the kernel-space address +.Fa kaddr . +.Pp +The +.Fn copyout +and +.Fn copyout_nofault +functions copy +.Fa len +bytes of data from the kernel-space address +.Fa kaddr +to the user-space address +.Fa uaddr . +.Pp +The +.Fn copyin_nofault +and +.Fn copyout_nofault +functions require that the kernel-space and user-space data be +accessible without incurring a page fault. +The source and destination addresses must be physically mapped for +read and write access, respectively, and neither the source nor +destination addresses may be pageable. +.Pp +The +.Fn copystr +function copies a NUL-terminated string, at most +.Fa len +bytes long, from kernel-space address +.Fa kfaddr +to kernel-space address +.Fa kdaddr . +The number of bytes actually copied, including the terminating +NUL, is returned in +.Fa *done +(if +.Fa done +is +.No non- Ns Dv NULL ) . +.Pp +The +.Fn copyinstr +function copies a NUL-terminated string, at most +.Fa len +bytes long, from user-space address +.Fa uaddr +to kernel-space address +.Fa kaddr . +The number of bytes actually copied, including the terminating +NUL, is returned in +.Fa *done +(if +.Fa done +is +.No non- Ns Dv NULL ) . +.Sh RETURN VALUES +The +.Nm +functions return 0 on success. +All but +.Fn copystr +return +.Er EFAULT +if a bad address is encountered. +The +.Fn copyin_nofault +and +.Fn copyout_nofault +functions return +.Er EFAULT +if a page fault occurs. +The +.Fn copystr +and +.Fn copyinstr +functions return +.Er ENAMETOOLONG +if the string is longer than +.Fa len +bytes. +.Sh SEE ALSO +.Xr fetch 9 , +.Xr store 9 diff --git a/static/freebsd/man9/coredumper_register.9 b/static/freebsd/man9/coredumper_register.9 new file mode 100644 index 00000000..f4c9eb4a --- /dev/null +++ b/static/freebsd/man9/coredumper_register.9 @@ -0,0 +1,168 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 Kyle Evans +.\" +.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/static/freebsd/man9/counter.9 b/static/freebsd/man9/counter.9 new file mode 100644 index 00000000..05af87e8 --- /dev/null +++ b/static/freebsd/man9/counter.9 @@ -0,0 +1,298 @@ +.\"- +.\" Copyright (c) 2013 Gleb Smirnoff +.\" 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 June 19, 2025 +.Dt COUNTER 9 +.Os +.Sh NAME +.Nm counter +.Nd "SMP-friendly kernel counter implementation" +.Sh SYNOPSIS +.In sys/types.h +.In sys/systm.h +.In sys/counter.h +.Ft counter_u64_t +.Fn counter_u64_alloc "int wait" +.Ft void +.Fn counter_u64_free "counter_u64_t c" +.Ft void +.Fn counter_u64_add "counter_u64_t c" "int64_t v" +.Ft void +.Fn counter_enter +.Ft void +.Fn counter_exit +.Ft void +.Fn counter_u64_add_protected "counter_u64_t c" "int64_t v" +.Ft uint64_t +.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 +.Fn SYSCTL_COUNTER_U64 parent nbr name access ptr descr +.Fn SYSCTL_ADD_COUNTER_U64 ctx parent nbr name access ptr descr +.Fn SYSCTL_COUNTER_U64_ARRAY parent nbr name access ptr len descr +.Fn SYSCTL_ADD_COUNTER_U64_ARRAY ctx parent nbr name access ptr len descr +.Sh DESCRIPTION +.Nm +is a generic facility to create counters +that can be utilized for any purpose (such as collecting statistical +data). +A +.Nm +is guaranteed to be lossless when several kernel threads do simultaneous +updates. +However, +.Nm +does not block the calling thread, +also no +.Xr atomic 9 +operations are used for the update, therefore the counters +can be used in any non-interrupt context. +Moreover, +.Nm +has special optimisations for SMP environments, making +.Nm +update faster than simple arithmetic on the global variable. +Thus +.Nm +is considered suitable for accounting in the performance-critical +code paths. +.Bl -tag -width indent +.It Fn counter_u64_alloc wait +Allocate a new 64-bit unsigned counter. +The +.Fa wait +argument is the +.Xr malloc 9 +wait flag, should be either +.Va M_NOWAIT +or +.Va M_WAITOK . +If +.Va M_NOWAIT +is specified the operation may fail and return +.Dv NULL . +.It Fn counter_u64_free c +Free the previously allocated counter +.Fa c . +It is safe to pass +.Dv NULL . +.It Fn counter_u64_add c v +Add +.Fa v +to +.Fa c . +The KPI does not guarantee any protection from wraparound. +.It Fn counter_enter +Enter mode that would allow the safe update of several counters via +.Fn counter_u64_add_protected . +On some machines this expands to +.Xr critical 9 +section, while on other is a nop. +See +.Sx IMPLEMENTATION DETAILS . +.It Fn counter_exit +Exit mode for updating several counters. +.It Fn counter_u64_add_protected c v +Same as +.Fn counter_u64_add , +but should be preceded by +.Fn counter_enter . +.It Fn counter_u64_fetch c +Take a snapshot of counter +.Fa c . +The data obtained is not guaranteed to reflect the real cumulative +value for any moment. +.It Fn counter_u64_zero c +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 +which uses +.Nm +internally. +Returns non-negative value if the rate is not yet reached during the current +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 +initializer for the global counter +.Fa c . +.It Fn COUNTER_U64_DEFINE_EARLY c +Define and initialize a global counter +.Fa c . +It is always safe to increment +.Fa c , +though updates prior to the +.Dv SI_SUB_COUNTER +.Xr SYSINIT 9 +event are lost. +.It Fn SYSCTL_COUNTER_U64 parent nbr name access ptr descr +Declare a static +.Xr sysctl 9 +oid that would represent a +.Nm . +The +.Fa ptr +argument should be a pointer to allocated +.Vt counter_u64_t . +A read of the oid returns value obtained through +.Fn counter_u64_fetch . +Any write to the oid zeroes it. +.It Fn SYSCTL_ADD_COUNTER_U64 ctx parent nbr name access ptr descr +Create a +.Xr sysctl 9 +oid that would represent a +.Nm . +The +.Fa ptr +argument should be a pointer to allocated +.Vt counter_u64_t . +A read of the oid returns value obtained through +.Fn counter_u64_fetch . +Any write to the oid zeroes it. +.It Fn SYSCTL_COUNTER_U64_ARRAY parent nbr name access ptr len descr +Declare a static +.Xr sysctl 9 +oid that would represent an array of +.Nm . +The +.Fa ptr +argument should be a pointer to allocated array of +.Vt counter_u64_t's . +The +.Fa len +argument should specify number of elements in the array. +A read of the oid returns len-sized array of +.Vt uint64_t +values obtained through +.Fn counter_u64_fetch . +Any write to the oid zeroes all array elements. +.It Fn SYSCTL_ADD_COUNTER_U64_ARRAY ctx parent nbr name access ptr len descr +Create a +.Xr sysctl 9 +oid that would represent an array of +.Nm . +The +.Fa ptr +argument should be a pointer to allocated array of +.Vt counter_u64_t's . +The +.Fa len +argument should specify number of elements in the array. +A read of the oid returns len-sized array of +.Vt uint64_t +values obtained through +.Fn counter_u64_fetch . +Any write to the oid zeroes all array elements. +.El +.Sh IMPLEMENTATION DETAILS +On all architectures +.Nm +is implemented using per-CPU data fields that are specially aligned +in memory, to avoid inter-CPU bus traffic due to shared use +of the variables between CPUs. +These are allocated using +.Va UMA_ZONE_PCPU +.Xr uma 9 +zone. +The update operation only touches the field that is private to current CPU. +Fetch operation loops through all per-CPU fields and obtains a snapshot +sum of all fields. +.Pp +On amd64 a +.Nm counter +update is implemented as a single instruction without lock semantics, +operating on the private data for the current CPU, +which is safe against preemption and interrupts. +.Pp +On i386 architecture, when machine supports the cmpxchg8 instruction, +this instruction is used. +The multi-instruction sequence provides the same guarantees as the +amd64 single-instruction implementation. +.Pp +On some architectures updating a counter require a +.Xr critical 9 +section. +.Sh EXAMPLES +The following example creates a static counter array exported to +userspace through a sysctl: +.Bd -literal -offset indent +#define MY_SIZE 8 +static counter_u64_t array[MY_SIZE]; +SYSCTL_COUNTER_U64_ARRAY(_debug, OID_AUTO, counter_array, CTLFLAG_RW, + &array[0], MY_SIZE, "Test counter array"); +.Ed +.Sh SEE ALSO +.Xr atomic 9 , +.Xr critical 9 , +.Xr locking 9 , +.Xr malloc 9 , +.Xr ratecheck 9 , +.Xr sysctl 9 , +.Xr SYSINIT 9 , +.Xr uma 9 +.Sh HISTORY +The +.Nm +facility first appeared in +.Fx 10.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +facility was written by +.An Gleb Smirnoff +and +.An Konstantin Belousov . diff --git a/static/freebsd/man9/cpu_machdep.9 b/static/freebsd/man9/cpu_machdep.9 new file mode 100644 index 00000000..415d86a8 --- /dev/null +++ b/static/freebsd/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/static/freebsd/man9/cpuset.9 b/static/freebsd/man9/cpuset.9 new file mode 100644 index 00000000..0ca04f92 --- /dev/null +++ b/static/freebsd/man9/cpuset.9 @@ -0,0 +1,388 @@ +.\" Copyright (c) 2015 Conrad Meyer +.\" 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 August 7, 2025 +.Dt CPUSET 9 +.Os +.Sh NAME +.Nm cpuset(9) +\(em +.Nm CPUSET_T_INITIALIZER , +.Nm CPUSET_FSET , +.Nm CPU_CLR , +.Nm CPU_COPY , +.Nm CPU_ISSET , +.Nm CPU_SET , +.Nm CPU_ZERO , +.Nm CPU_FILL , +.Nm CPU_SETOF , +.Nm CPU_EMPTY , +.Nm CPU_ISFULLSET , +.Nm CPU_FFS , +.Nm CPU_COUNT , +.Nm CPU_SUBSET , +.Nm CPU_OVERLAP , +.Nm CPU_CMP , +.Nm CPU_OR , +.Nm CPU_ORNOT , +.Nm CPU_AND , +.Nm CPU_ANDNOT , +.Nm CPU_XOR , +.Nm CPU_CLR_ATOMIC , +.Nm CPU_TEST_CLR_ATOMIC , +.Nm CPU_SET_ATOMIC , +.Nm CPU_SET_ATOMIC_ACQ , +.Nm CPU_TEST_SET_ATOMIC , +.Nm CPU_AND_ATOMIC , +.Nm CPU_OR_ATOMIC , +.Nm CPU_COPY_STORE_REL +.Nd cpuset manipulation macros +.Sh SYNOPSIS +.In sys/_cpuset.h +.In sys/cpuset.h +.\" +.Fn CPUSET_T_INITIALIZER "ARRAY_CONTENTS" +.Vt CPUSET_FSET +.\" +.Fn CPU_CLR "size_t cpu_idx" "cpuset_t *cpuset" +.Fn CPU_COPY "cpuset_t *from" "cpuset_t *to" +.Ft bool +.Fn CPU_ISSET "size_t cpu_idx" "cpuset_t *cpuset" +.Fn CPU_SET "size_t cpu_idx" "cpuset_t *cpuset" +.Fn CPU_ZERO "cpuset_t *cpuset" +.Fn CPU_FILL "cpuset_t *cpuset" +.Fn CPU_SETOF "size_t cpu_idx" "cpuset_t *cpuset" +.Ft bool +.Fn CPU_EMPTY "cpuset_t *cpuset" +.Ft bool +.Fn CPU_ISFULLSET "cpuset_t *cpuset" +.Ft int +.Fn CPU_FFS "cpuset_t *cpuset" +.Ft int +.Fn CPU_COUNT "cpuset_t *cpuset" +.\" +.Ft bool +.Fn CPU_SUBSET "cpuset_t *haystack" "cpuset_t *needle" +.Ft bool +.Fn CPU_OVERLAP "cpuset_t *cpuset1" "cpuset_t *cpuset2" +.Ft bool +.Fn CPU_CMP "cpuset_t *cpuset1" "cpuset_t *cpuset2" +.Fn CPU_OR "cpuset_t *dst" "cpuset_t *src1" "cpuset_t *src2" +.Fn CPU_ORNOT "cpuset_t *dst" "cpuset_t *src1" "cpuset_t *src2" +.Fn CPU_AND "cpuset_t *dst" "cpuset_t *src1" "cpuset_t *src2" +.Fn CPU_ANDNOT "cpuset_t *dst" "cpuset_t *src1" "cpuset_t *src2" +.Fn CPU_XOR "cpuset_t *dst" "cpuset_t *src1" "cpuset_t *src2" +.\" +.Fn CPU_CLR_ATOMIC "size_t cpu_idx" "cpuset_t *cpuset" +.Fn CPU_TEST_CLR_ATOMIC "size_t cpu_idx" "cpuset_t *cpuset" +.Fn CPU_SET_ATOMIC "size_t cpu_idx" "cpuset_t *cpuset" +.Fn CPU_SET_ATOMIC_ACQ "size_t cpu_idx" "cpuset_t *cpuset" +.Fn CPU_TEST_SET_ATOMIC "size_t cpu_idx" "cpuset_t *cpuset" +.\" +.Fn CPU_AND_ATOMIC "cpuset_t *dst" "cpuset_t *src" +.Fn CPU_OR_ATOMIC "cpuset_t *dst" "cpuset_t *src" +.Fn CPU_COPY_STORE_REL "cpuset_t *from" "cpuset_t *to" +.Sh DESCRIPTION +The +.Nm +family of macros provide a flexible and efficient CPU set implementation, +backed by the +.Xr bitset 9 +macros. +Each CPU is represented by a single bit. +The maximum number of CPUs representable by +.Vt cpuset_t +is +.Va CPU_SETSIZE . +Individual CPUs in cpusets are referenced with indices zero through +.Fa CPU_SETSIZE - 1 . +.Pp +The +.Fn CPUSET_T_INITIALIZER +macro allows one to initialize a +.Vt cpuset_t +with a compile time literal value. +.Pp +The +.Fn CPUSET_FSET +macro defines a compile time literal, usable by +.Fn CPUSET_T_INITIALIZER , +representing a full cpuset (all CPUs present). +For examples of +.Fn CPUSET_T_INITIALIZER +and +.Fn CPUSET_FSET +usage, see the +.Sx CPUSET_T_INITIALIZER EXAMPLE +section. +.Pp +The +.Fn CPU_CLR +macro removes CPU +.Fa cpu_idx +from the cpuset pointed to by +.Fa cpuset . +The +.Fn CPU_CLR_ATOMIC +macro is identical, but the bit representing the CPU is cleared with atomic +machine instructions. +The +.Fn CPU_TEST_CLR_ATOMIC +macro atomically clears the bit representing the CPU and returns whether it +was set. +.Pp +The +.Fn CPU_COPY +macro copies the contents of the cpuset +.Fa from +to the cpuset +.Fa to . +.Fn CPU_COPY_STORE_REL +is similar, but copies component machine words from +.Fa from +and writes them to +.Fa to +with atomic store with release semantics. +(That is, if +.Fa to +is composed of multiple machine words, +.Fn CPU_COPY_STORE_REL +performs multiple individually atomic operations.) +.Pp +The +.Fn CPU_SET +macro adds CPU +.Fa cpu_idx +to the cpuset pointed to by +.Fa cpuset , +if it is not already present. +The +.Fn CPU_SET_ATOMIC +macro is identical, but the bit representing the CPU is set with atomic +machine instructions. +The +.Fn CPU_SET_ATOMIC_ACQ +macro sets the bit representing the CPU with atomic acquire semantics. +The +.Fn CPU_TEST_SET_ATOMIC +macro atomically sets the bit representing the CPU and returns whether it was +set. +.Pp +The +.Fn CPU_ISSET +macro returns +.Dv true +if CPU +.Fa cpu_idx +is a member of the cpuset pointed to by +.Fa cpuset . +.Pp +The +.Fn CPU_ZERO +macro removes all CPUs from +.Fa cpuset . +.Pp +The +.Fn CPU_FILL +macro adds all CPUs to +.Fa cpuset . +.Pp +The +.Fn CPU_SETOF +macro removes all CPUs in +.Fa cpuset +before adding only CPU +.Fa cpu_idx . +.Pp +The +.Fn CPU_EMPTY +macro returns +.Dv true +if +.Fa cpuset +is empty. +.Pp +The +.Fn CPU_ISFULLSET +macro returns +.Dv true +if +.Fa cpuset +is full (the set of all CPUs). +.Pp +The +.Fn CPU_FFS +macro returns the 1-index of the first (lowest) CPU in +.Fa cpuset , +or zero if +.Fa cpuset +is empty. +Like with +.Xr ffs 3 , +to use the non-zero result of +.Fn CPU_FFS +as a +.Fa cpu_idx +index parameter to any other +.Nm +macro, you must subtract one from the result. +.Pp +The +.Fn CPU_COUNT +macro returns the total number of CPUs in +.Fa cpuset . +.Pp +The +.Fn CPU_SUBSET +macro returns +.Dv true +if +.Fa needle +is a subset of +.Fa haystack . +.Pp +The +.Fn CPU_OVERLAP +macro returns +.Dv true +if +.Fa cpuset1 +and +.Fa cpuset2 +have any common CPUs. +(That is, if +.Fa cpuset1 +AND +.Fa cpuset2 +is not the empty set.) +.Pp +The +.Fn CPU_CMP +macro returns +.Dv true +if +.Fa cpuset1 +is NOT equal to +.Fa cpuset2 . +.Pp +The +.Fn CPU_OR +macro adds CPUs present in +.Fa src +to +.Fa dst . +(It is the +.Nm +equivalent of the scalar: +.Fa dst +|= +.Fa src . ) +.Fn CPU_OR_ATOMIC +is similar, but sets the bits representing CPUs in the component machine words +in +.Fa dst +with atomic machine instructions. +(That is, if +.Fa dst +is composed of multiple machine words, +.Fn CPU_OR_ATOMIC +performs multiple individually atomic operations.) +.Pp +The +.Fn CPU_ORNOT +macro add CPUs not in +.Fa src +to +.Fa dst . +(It is the +.Nm +equivalent of the scalar: +.Fa dst +|= +.Fa ~ src . ) +.Pp +The +.Fn CPU_AND +macro removes CPUs absent from +.Fa src +from +.Fa dst . +(It is the +.Nm +equivalent of the scalar: +.Fa dst +&= +.Fa src . ) +.Fn CPU_AND_ATOMIC +is similar, with the same atomic semantics as +.Fn CPU_OR_ATOMIC . +.Pp +The +.Fn CPU_ANDNOT +macro removes CPUs in +.Fa src +from +.Fa dst . +(It is the +.Nm +equivalent of the scalar: +.Fa dst +&= +.Fa ~ src . ) +.Sh CPUSET_T_INITIALIZER EXAMPLE +.Bd -literal +cpuset_t myset; + +/* Initialize myset to filled (all CPUs) */ +myset = CPUSET_T_INITIALIZER(CPUSET_FSET); + +/* Initialize myset to only the lowest CPU */ +myset = CPUSET_T_INITIALIZER(0x1); +.Ed +.Sh SEE ALSO +.Xr cpuset 1 , +.Xr cpuset 2 , +.Xr bitset 9 +.Sh HISTORY +.In sys/cpuset.h +first appeared in +.Fx 7.1 , +released in January 2009, and in +.Fx 8.0 , +released in November 2009. +.Pp +This manual page first appeared in +.Fx 11.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +macros were written by +.An Jeff Roberson Aq Mt jeff@FreeBSD.org . +This manual page was written by +.An Conrad Meyer Aq Mt cem@FreeBSD.org . +.Sh CAVEATS +Unlike every other reference to individual set members, which are zero-indexed, +.Fn CPU_FFS +returns a one-indexed result (or zero if the cpuset is empty). diff --git a/static/freebsd/man9/cr_bsd_visible.9 b/static/freebsd/man9/cr_bsd_visible.9 new file mode 100644 index 00000000..d16f4bb6 --- /dev/null +++ b/static/freebsd/man9/cr_bsd_visible.9 @@ -0,0 +1,117 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2023 Olivier Certner +.\" +.\" 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 August 18, 2023 +.Dt CR_BSD_VISIBLE 9 +.Os +.Sh NAME +.Nm cr_bsd_visible +.Nd determine if subjects may see entities according to BSD security policies +.Sh SYNOPSIS +.In sys/proc.h +.Ft int +.Fn cr_bsd_visible "struct ucred *u1" "struct ucred *u2" +.Sh DESCRIPTION +This function determines if a subject with credentials +.Fa u1 +is denied seeing an object or subject associated to credentials +.Fa u2 +by the following policies and associated +.Xr sysctl 8 +knobs: +.Bl -tag -width indent +.It Va security.bsd.seeotheruids +If set to 0, subjects cannot see other subjects or objects if they are not +associated with the same real user ID. +The corresponding internal function is +.Xr cr_canseeotheruids 9 . +.It Va security.bsd.seeothergids +If set to 0, subjects cannot see other subjects or objects if they are not both +a member of at least one common group. +The corresponding internal function is +.Xr cr_canseeothergids 9 . +.It Va security.bsd.see_jail_proc +If set to 0, subjects cannot see other subjects or objects that are not +associated with the same jail as they are. +The corresponding internal function is +.Xr cr_canseejailproc 9 . +.El +.Pp +As usual, the superuser (effective user ID 0) is exempt from any of these +policies provided that the +.Xr sysctl 8 +variable +.Va security.bsd.suser_enabled +is non-zero and no active MAC policy explicitly denies the exemption +.Po +see +.Xr priv_check_cred 9 +.Pc . +.Pp +This function is intended to be used as a helper to implement +.Xr cr_cansee 9 +and similar functions. +.Sh RETURN VALUES +This function returns zero if a subject with credentials +.Fa u1 +may see a subject or object with credentials +.Fa u2 +by the active above-mentioned policies, or +.Er ESRCH +otherwise. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ESRCH +Credentials +.Fa u1 +and +.Fa u2 +do not have the same real user ID. +.It Bq Er ESRCH +Credentials +.Fa u1 +and +.Fa u2 +are not members of any common group +.Po +as determined by +.Xr realgroupmember 9 +.Pc . +.It Bq Er ESRCH +Credentials +.Fa u1 +and +.Fa u2 +are not in the same jail. +.El +.Sh SEE ALSO +.Xr cr_cansee 9 , +.Xr cr_canseejailproc 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/static/freebsd/man9/cr_cansee.9 b/static/freebsd/man9/cr_cansee.9 new file mode 100644 index 00000000..a93afb8e --- /dev/null +++ b/static/freebsd/man9/cr_cansee.9 @@ -0,0 +1,83 @@ +.\" +.\" Copyright (c) 2006 Ceri Davies +.\" Copyright (c) 2023 Olivier Certner +.\" +.\" 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 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 August 18, 2023 +.Dt CR_CANSEE 9 +.Os +.Sh NAME +.Nm cr_cansee +.Nd "determine visibility of objects given their user credentials" +.Sh SYNOPSIS +.In sys/proc.h +.Ft int +.Fn cr_cansee "struct ucred *u1" "struct ucred *u2" +.Sh DESCRIPTION +This function determines if a subject with credential +.Fa u1 +can see a subject or object associated to credential +.Fa u2 . +.Pp +Specific types of subjects may need to submit to additional or different +restrictions. +As an example, for processes, see +.Xr p_cansee 9 , +which calls this function. +.Pp +The implementation relies on +.Xr cr_bsd_visible 9 +and consequently the +.Xr sysctl 8 +variables referenced in its manual page influence the result. +.Sh RETURN VALUES +This function returns zero if the subject with credential +.Fa u1 +can +.Dq see +the subject or object with credential +.Fa u2 , +or +.Er ESRCH +otherwise. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ESRCH +The subject with credential +.Fa u1 +has been jailed and the subject or object with credential +.Fa u2 +does not belong to the same jail or one of its sub-jails, as determined by +.Xr prison_check 9 . +.It Bq Er ESRCH +The MAC subsystem denied visibility. +.It Bq Er ESRCH +.Xr cr_bsd_visible 9 +denied visibility according to the BSD security policies in force. +.El +.Sh SEE ALSO +.Xr cr_bsd_visible 9 , +.Xr mac 9 , +.Xr p_cansee 9 , +.Xr prison_check 9 diff --git a/static/freebsd/man9/cr_canseejailproc.9 b/static/freebsd/man9/cr_canseejailproc.9 new file mode 100644 index 00000000..775c7672 --- /dev/null +++ b/static/freebsd/man9/cr_canseejailproc.9 @@ -0,0 +1,81 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2023 Olivier Certner +.\" +.\" 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 August 18, 2023 +.Dt CR_CANSEEJAILPROC 9 +.Os +.Sh NAME +.Nm cr_canseejailproc +.Nd determine if subjects may see entities in sub-jails +.Sh SYNOPSIS +.Ft int +.Fn cr_canseejailproc "struct ucred *u1" "struct ucred *u2" +.Sh DESCRIPTION +.Bf -emphasis +This function is internal. +Its functionality is integrated into the function +.Xr cr_bsd_visible 9 , +which should be called instead. +.Ef +.Pp +This function checks if a subject associated to credentials +.Fa u1 +is denied seeing a subject or object associated to credentials +.Fa u2 +by a policy that requires both credentials to be associated to the same jail. +This is a restriction to the baseline jail policy that a subject can see +subjects or objects in its own jail or any sub-jail of it. +.Pp +This policy is active if and only if the +.Xr sysctl 8 +variable +.Va security.bsd.see_jail_proc +is set to zero. +.Pp +As usual, the superuser (effective user ID 0) is exempt from this policy +provided that the +.Xr sysctl 8 +variable +.Va security.bsd.suser_enabled +is non-zero and no active MAC policy explicitly denies the exemption +.Po +see +.Xr priv_check_cred 9 +.Pc . +.Sh RETURN VALUES +The +.Fn cr_canseejailproc +function returns 0 if the policy is disabled, both credentials are associated to +the same jail, or if +.Fa u1 +has privilege exempting it from the policy. +Otherwise, it returns +.Er ESRCH . +.Sh SEE ALSO +.Xr cr_bsd_visible 9 , +.Xr priv_check_cred 9 +.Sh AUTHORS +This manual page was written by +.An Olivier Certner Aq Mt olce.freebsd@certner.fr . diff --git a/static/freebsd/man9/cr_canseeothergids.9 b/static/freebsd/man9/cr_canseeothergids.9 new file mode 100644 index 00000000..530335d5 --- /dev/null +++ b/static/freebsd/man9/cr_canseeothergids.9 @@ -0,0 +1,83 @@ +.\" +.\" Copyright (c) 2003 Joseph Koshy +.\" Copyright (c) 2023 Olivier Certner +.\" +.\" 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 August 18, 2023 +.Dt CR_CANSEEOTHERGIDS 9 +.Os +.Sh NAME +.Nm cr_canseeothergids +.Nd determine if subjects may see entities in a disjoint group set +.Sh SYNOPSIS +.Ft int +.Fn cr_canseeothergids "struct ucred *u1" "struct ucred *u2" +.Sh DESCRIPTION +.Bf -emphasis +This function is internal. +Its functionality is integrated into the function +.Xr cr_bsd_visible 9 , +which should be called instead. +.Ef +.Pp +This function checks if a subject associated to credentials +.Fa u1 +is denied seeing a subject or object associated to credentials +.Fa u2 +by a policy that requires both credentials to have at least one group in common. +For this determination, the real and supplementary group IDs are used, but +not the effective group IDs, as per +.Xr realgroupmember 9 . +.Pp +This policy is active if and only if the +.Xr sysctl 8 +variable +.Va security.bsd.see_other_gids +is set to zero. +.Pp +As usual, the superuser (effective user ID 0) is exempt from this policy +provided that the +.Xr sysctl 8 +variable +.Va security.bsd.suser_enabled +is non-zero and no active MAC policy explicitly denies the exemption +.Po +see +.Xr priv_check_cred 9 +.Pc . +.Sh RETURN VALUES +The +.Fn cr_canseeothergids +function returns 0 if the policy is disabled, the credentials share at least one +common group, or if +.Fa u1 +has privilege exempting it from the policy. +Otherwise, it returns +.Er ESRCH . +.Sh SEE ALSO +.Xr cr_bsd_visible 9 , +.Xr priv_check_cred 9 , +.Xr realgroupmember 9 diff --git a/static/freebsd/man9/cr_canseeotheruids.9 b/static/freebsd/man9/cr_canseeotheruids.9 new file mode 100644 index 00000000..230c5ea5 --- /dev/null +++ b/static/freebsd/man9/cr_canseeotheruids.9 @@ -0,0 +1,79 @@ +.\" +.\" Copyright (c) 2003 Joseph Koshy +.\" Copyright (c) 2023 Olivier Certner +.\" +.\" 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 August 18, 2023 +.Dt CR_CANSEEOTHERUIDS 9 +.Os +.Sh NAME +.Nm cr_canseeotheruids +.Nd determine if subjects may see entities with differing user ID +.Sh SYNOPSIS +.Ft int +.Fn cr_canseeotheruids "struct ucred *u1" "struct ucred *u2" +.Sh DESCRIPTION +.Bf -emphasis +This function is internal. +Its functionality is integrated into the function +.Xr cr_bsd_visible 9 , +which should be called instead. +.Ef +.Pp +This function checks if a subject associated to credentials +.Fa u1 +is denied seeing a subject or object associated to credentials +.Fa u2 +by a policy that requires both credentials to have the same real user ID. +.Pp +This policy is active if and only if the +.Xr sysctl 8 +variable +.Va security.bsd.see_other_uids +is set to zero. +.Pp +As usual, the superuser (effective user ID 0) is exempt from this policy +provided that the +.Xr sysctl 8 +variable +.Va security.bsd.suser_enabled +is non-zero and no active MAC policy explicitly denies the exemption +.Po +see +.Xr priv_check_cred 9 +.Pc . +.Sh RETURN VALUES +The +.Fn cr_canseeotheruids +function returns 0 if the policy is disabled, both credentials have the same +real user ID, or if +.Fa u1 +has privilege exempting it from the policy. +Otherwise, it returns +.Er ESRCH . +.Sh SEE ALSO +.Xr cr_bsd_visible 9 , +.Xr priv_check_cred 9 diff --git a/static/freebsd/man9/critical_enter.9 b/static/freebsd/man9/critical_enter.9 new file mode 100644 index 00000000..0b1e5559 --- /dev/null +++ b/static/freebsd/man9/critical_enter.9 @@ -0,0 +1,101 @@ +.\" Copyright (c) 2001,2002 John H. Baldwin +.\" +.\" 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 March 20, 2023 +.Dt CRITICAL_ENTER 9 +.Os +.Sh NAME +.Nm critical_enter , +.Nm critical_exit +.Nd enter and exit a critical region +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.Ft void +.Fn critical_enter "void" +.Ft void +.Fn critical_exit "void" +.Fn CRITICAL_ASSERT "struct thread *td" +.Sh DESCRIPTION +These functions are used to prevent preemption in a critical region of code. +All that is guaranteed is that the thread currently executing on a CPU will +not be preempted. +Specifically, a thread in a critical region will not migrate to another CPU +while it is in a critical region, nor will the current CPU switch to a +different thread. +The current CPU may still trigger faults and exceptions during a critical +section; however, these faults are usually fatal. +.Pp +The CPU might also receive and handle interrupts within a critical section. +When this occurs the interrupt exit will not result in a context switch, and +execution will continue in the critical section. +Thus, the net effect of a critical section on the current thread's execution is +similar to running with interrupts disabled, except that timer interrupts and +filtered interrupt handlers do not incur a latency penalty. +.Pp +The +.Fn critical_enter +and +.Fn critical_exit +functions manage a per-thread counter to handle nested critical sections. +If a thread is made runnable that would normally preempt the current thread +while the current thread is in a critical section, +then the preemption will be deferred until the current thread exits the +outermost critical section. +.Pp +Note that these functions do not provide any inter-CPU synchronization, data +protection, or memory ordering guarantees, and thus should +.Em not +be used to protect shared data structures. +.Pp +These functions should be used with care as an unbound or infinite loop within +a critical region will deadlock the CPU. +Also, they should not be interlocked with operations on mutexes, sx locks, +semaphores, or other synchronization primitives, as these primitives may +require a context switch to operate. +One exception to this is that spin mutexes include a critical section, +so in certain cases critical sections may be interlocked with spin mutexes. +.Pp +Critical regions should be only as wide as necessary. +That is, code which does not require the critical section to operate correctly +should be excluded from its bounds whenever possible. +Abuse of critical sections has an effect on overall system latency and timer +precision, since disabling preemption will delay the execution of threaded +interrupt handlers and +.Xr callout 9 +events on the current CPU. +.Pp +The +.Fn CRITICAL_ASSERT +macro verifies that the provided thread +.Fa td +is currently executing in a critical section. +It is a wrapper around +.Xr KASSERT 9 . +.Sh SEE ALSO +.Xr callout 9 , +.Xr KASSERT 9 , +.Xr locking 9 +.Sh HISTORY +These functions were introduced in +.Fx 5.0 . diff --git a/static/freebsd/man9/crypto.9 b/static/freebsd/man9/crypto.9 new file mode 100644 index 00000000..4d54b751 --- /dev/null +++ b/static/freebsd/man9/crypto.9 @@ -0,0 +1,148 @@ +.\" $OpenBSD: crypto.9,v 1.19 2002/07/16 06:31:57 angelos Exp $ +.\" +.\" The author of this manual page is Angelos D. Keromytis (angelos@cis.upenn.edu) +.\" +.\" Copyright (c) 2000, 2001 Angelos D. Keromytis +.\" +.\" Permission to use, copy, and modify this software with or without fee +.\" is hereby granted, provided that this entire notice is included in +.\" all source code copies of any software which is or includes a copy or +.\" modification of this software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR +.\" IMPLIED WARRANTY. IN PARTICULAR, NONE OF THE AUTHORS MAKES ANY +.\" REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE +.\" MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR +.\" PURPOSE. +.\" +.Dd April 12, 2021 +.Dt CRYPTO 9 +.Os +.Sh NAME +.Nm crypto +.Nd API for cryptographic services in the kernel +.Sh SYNOPSIS +.In opencrypto/cryptodev.h +.Sh DESCRIPTION +.Nm +is a framework for in-kernel cryptography. +It permits in-kernel consumers to encrypt and decrypt data +and also enables userland applications to use cryptographic hardware +through the +.Pa /dev/crypto +device. +.Pp +.Nm +supports encryption and decryption operations +using block and stream ciphers as well as computation and verification +of message authentication codes (MACs). +Consumers allocate sessions to describe a transform as discussed in +.Xr crypto_session 9 . +Consumers then allocate request objects to describe each transformation +such as encrypting a network packet or decrypting a disk sector. +Requests are described in +.Xr crypto_request 9 . +.Pp +Device drivers are responsible for processing requests submitted by +consumers. +.Xr crypto_driver 9 +describes the interfaces drivers use to register with the framework, +helper routines the framework provides to facilitate request processing, +and the interfaces drivers are required to provide. +.Ss Callbacks +Since the consumers may not be associated with a process, drivers may +not +.Xr sleep 9 . +The same holds for the framework. +Thus, a callback mechanism is used +to notify a consumer that a request has been completed (the +callback is specified by the consumer on a per-request basis). +The callback is invoked by the framework whether the request was +successfully completed or not. +Errors are reported to the callback function. +.Pp +Session initialization does not use callbacks and returns errors +synchronously. +.Ss Session Migration +Operations may fail with a specific error code, +.Er EAGAIN , +to indicate that a session handle has changed and that the +request may be re-submitted immediately with the new session. +The consumer should update its saved copy of the session handle +to the value of +.Fa crp_session +so that future requests use the new session. +.Ss Supported Algorithms +More details on some algorithms may be found in +.Xr crypto 7 . +.Pp +The following authentication algorithms are supported: +.Pp +.Bl -tag -offset indent -width CRYPTO_AES_CCM_CBC_MAC -compact +.It Dv CRYPTO_AES_CCM_CBC_MAC +.It Dv CRYPTO_AES_NIST_GMAC +.It Dv CRYPTO_BLAKE2B +.It Dv CRYPTO_BLAKE2S +.It Dv CRYPTO_NULL_HMAC +.It Dv CRYPTO_POLY1305 +.It Dv CRYPTO_RIPEMD160 +.It Dv CRYPTO_RIPEMD160_HMAC +.It Dv CRYPTO_SHA1 +.It Dv CRYPTO_SHA1_HMAC +.It Dv CRYPTO_SHA2_224 +.It Dv CRYPTO_SHA2_224_HMAC +.It Dv CRYPTO_SHA2_256 +.It Dv CRYPTO_SHA2_256_HMAC +.It Dv CRYPTO_SHA2_384 +.It Dv CRYPTO_SHA2_384_HMAC +.It Dv CRYPTO_SHA2_512 +.It Dv CRYPTO_SHA2_512_HMAC +.El +.Pp +The following encryption algorithms are supported: +.Pp +.Bl -tag -offset indent -width CRYPTO_CAMELLIA_CBC -compact +.It Dv CRYPTO_AES_CBC +.It Dv CRYPTO_AES_ICM +.It Dv CRYPTO_AES_XTS +.It Dv CRYPTO_CAMELLIA_CBC +.It Dv CRYPTO_CHACHA20 +.It Dv CRYPTO_NULL_CBC +.El +.Pp +The following authenticated encryption with additional data (AEAD) +algorithms are supported: +.Pp +.Bl -tag -offset indent -width CRYPTO_CHACHA20_POLY1305 -compact +.It Dv CRYPTO_AES_CCM_16 +.It Dv CRYPTO_AES_NIST_GCM_16 +.It Dv CRYPTO_CHACHA20_POLY1305 +.El +.Pp +The following compression algorithms are supported: +.Pp +.Bl -tag -offset indent -width CRYPTO_DEFLATE_COMP -compact +.It Dv CRYPTO_DEFLATE_COMP +.El +.Sh FILES +.Bl -tag -width ".Pa sys/opencrypto/crypto.c" +.It Pa sys/opencrypto/crypto.c +most of the framework code +.El +.Sh SEE ALSO +.Xr crypto 4 , +.Xr ipsec 4 , +.Xr crypto 7 , +.Xr crypto_driver 9 , +.Xr crypto_request 9 , +.Xr crypto_session 9 , +.Xr sleep 9 +.Sh HISTORY +The cryptographic framework first appeared in +.Ox 2.7 +and was written by +.An Angelos D. Keromytis Aq Mt angelos@openbsd.org . +.Sh BUGS +The framework needs a mechanism for determining which driver is +best for a specific set of algorithms associated with a session. +Some type of benchmarking is in order here. diff --git a/static/freebsd/man9/crypto_buffer.9 b/static/freebsd/man9/crypto_buffer.9 new file mode 100644 index 00000000..f14ae937 --- /dev/null +++ b/static/freebsd/man9/crypto_buffer.9 @@ -0,0 +1,348 @@ +.\" Copyright (c) 2020, Chelsio Inc +.\" +.\" 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. Neither the name of the Chelsio Inc nor the names of its +.\" contributors may be used to endorse or promote products derived from +.\" this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 COPYRIGHT OWNER 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. +.\" +.\" * Other names and brands may be claimed as the property of others. +.\" +.Dd February 11, 2022 +.Dt CRYPTO_BUFFER 9 +.Os +.Sh NAME +.Nm crypto_buffer +.Nd symmetric cryptographic request buffers +.Sh SYNOPSIS +.In opencrypto/cryptodev.h +.Ft int +.Fo crypto_apply +.Fa "struct cryptop *crp" +.Fa "int off" +.Fa "int len" +.Fa "int (*f)(void *, void *, u_int)" +.Fa "void *arg" +.Fc +.Ft int +.Fo crypto_apply_buf +.Fa "struct crypto_buffer *cb" +.Fa "int off" +.Fa "int len" +.Fa "int (*f)(void *, void *, u_int)" +.Fa "void *arg" +.Fc +.Ft void * +.Fo crypto_buffer_contiguous_subsegment +.Fa "struct crypto_buffer *cb" +.Fa "size_t skip" +.Fa "size_t len" +.Fc +.Ft size_t +.Fn crypto_buffer_len "struct crypto_buffer *cb" +.Ft void * +.Fo crypto_contiguous_subsegment +.Fa "struct cryptop *crp" +.Fa "size_t skip" +.Fa "size_t len" +.Fc +.Ft void +.Fo crypto_cursor_init +.Fa "struct crypto_buffer_cursor *cc" +.Fa "const struct crypto_buffer *cb" +.Fc +.Ft void +.Fn crypto_cursor_advance "struct crypto_buffer_cursor *cc" "size_t amount" +.Ft void +.Fo crypto_cursor_copyback +.Fa "struct crypto_buffer_cursor *cc" +.Fa "int size" +.Fa "const void *src" +.Fc +.Ft void +.Fo crypto_cursor_copydata +.Fa "struct crypto_buffer_cursor *cc" +.Fa "int size" +.Fa "void *dst" +.Fc +.Ft void +.Fo crypto_cursor_copydata_noadv +.Fa "struct crypto_buffer_cursor *cc" +.Fa "int size" +.Fa "void *dst" +.Fc +.Ft void * +.Fn crypto_cursor_segment "struct crypto_buffer_cursor *cc" "size_t *len" +.Ft void +.Fo crypto_cursor_copy +.Fa "const struct crypto_buffer_cursor *fromc" +.Fa "struct crypto_buffer_cursor *toc" +.Fc +.Ft bool +.Fn CRYPTO_HAS_OUTPUT_BUFFER "struct cryptop *crp" +.Sh DESCRIPTION +Symmetric cryptographic requests use data buffers to describe the data to +be modified. +Requests can either specify a single data buffer whose contents are modified +in place, +or requests may specify separate data buffers for input and output. +.Vt struct crypto_buffer +provides an abstraction that permits cryptographic requests to operate on +different types of buffers. +.Vt struct crypto_cursor +allows cryptographic drivers to iterate over a data buffer. +.Pp +.Fn CRYPTO_HAS_OUTPUT_BUFFER +returns true if +.Fa crp +uses separate buffers for input and output and false if +.Fa crp +uses a single buffer. +.Pp +.Fn crypto_buffer_len +returns the length of data buffer +.Fa cb +in bytes. +.Pp +.Fn crypto_apply_buf +invokes a caller-supplied function +to a region of the data buffer +.Fa cb . +The function +.Fa f +is called one or more times. +For each invocation, +the first argument to +.Fa f +is the value of +.Fa arg +passed to +.Fn crypto_apply_buf . +The second and third arguments to +.Fa f +are a pointer and length to a segment of the buffer mapped into the kernel. +The function is called enough times to cover the +.Fa len +bytes of the data buffer which starts at an offset +.Fa off . +If any invocation of +.Fa f +returns a non-zero value, +.Fn crypto_apply_buf +immediately returns that value without invoking +.Fa f +on any remaining segments of the region, +otherwise +.Fn crypto_apply_buf +returns the value from the final call to +.Fa f . +.Fn crypto_apply +invokes the callback +.Fa f +on a region of the input data buffer for +.Fa crp . +.Pp +.Fn crypto_buffer_contiguous_subsegment +attempts to locate a single, virtually-contiguous segment of the data buffer +.Fa cb . +The segment must be +.Fa len +bytes long and start at an offset of +.Fa skip +bytes. +If a segment is found, +a pointer to the start of the segment is returned. +Otherwise, +.Dv NULL +is returned. +.Fn crypto_contiguous_subsegment +attempts to locate a single, virtually-contiguous segment in the input data +buffer for +.Fa crp . +.Ss Data Buffers +Data buffers are described by an instance of +.Vt struct crypto buffer . +The +.Fa cb_type +member contains the type of the data buffer. +The following types are supported: +.Bl -tag -width " CRYPTO_BUF_CONTIG" +.It Dv CRYPTO_BUF_NONE +An invalid buffer. +Used to mark the output buffer when a crypto request uses a single data buffer. +.It Dv CRYPTO_BUF_CONTIG +An array of bytes mapped into the kernel's address space. +.It Dv CRYPTO_BUF_UIO +A scatter/gather list of kernel buffers as described in +.Xr uio 9 . +.It Dv CRYPTO_BUF_MBUF +A chain of network memory buffers as described in +.Xr mbuf 9 . +.It Dv CRYPTO_BUF_SINGLE_MBUF +A single network memory buffer as described in +.Xr mbuf 9 . +.It Dv CRYPTO_BUF_VMPAGE +A scatter/gather list of +.Vt vm_page_t +structures describing pages in the kernel's address space. +This buffer type is only available if +.Dv CRYPTO_HAS_VMPAGE +is true. +.El +.Pp +The structure also contains the following type-specific fields: +.Bl -tag -width " cb_vm_page_offset" +.It Fa cb_buf +A pointer to the start of a +.Dv CRYPTO_BUF_CONTIG +data buffer. +.It Fa cb_buf_len +The length of a +.Dv CRYPTO_BUF_CONTIG +data buffer +.It Fa cb_mbuf +A pointer to a +.Vt struct mbuf +for +.Dv CRYPTO_BUF_MBUF +and +.Dv CRYPTO_BUF_SINGLE_MBUF . +.It Fa cb_uio +A pointer to a +.Vt struct uio +for +.Dv CRYPTO_BUF_UIO . +.It Fa cb_vm_page +A pointer to an array of +.Vt struct vm_page +for +.Dv CRYPTO_BUF_VMPAGE . +.It Fa cb_vm_page_len +The total amount of data included in the +.Fa cb_vm_page +array, in bytes. +.It Fa cb_vm_page_offset +Offset in bytes in the first page of +.Fa cb_vm_page +where valid data begins. +.El +.Ss Cursors +Cursors provide a mechanism for iterating over a data buffer. +They are primarily intended for use in software drivers which access data +buffers via virtual addresses. +.Pp +.Fn crypto_cursor_init +initializes the cursor +.Fa cc +to reference the start of the data buffer +.Fa cb . +.Pp +.Fn crypto_cursor_advance +advances the cursor +.Fa amount +bytes forward in the data buffer. +.Pp +.Fn crypto_cursor_copyback +copies +.Fa size +bytes from the local buffer pointed to by +.Fa src +into the data buffer associated with +.Fa cc . +The bytes are written to the current position of +.Fa cc , +and the cursor is then advanced by +.Fa size +bytes. +.Pp +.Fn crypto_cursor_copydata +copies +.Fa size +bytes out of the data buffer associated with +.Fa cc +into a local buffer pointed to by +.Fa dst . +The bytes are read from the current position of +.Fa cc , +and the cursor is then advanced by +.Fa size +bytes. +.Pp +.Fn crypto_cursor_copydata_noadv +is similar to +.Fn crypto_cursor_copydata +except that it does not change the current position of +.Fa cc . +.Pp +.Fn crypto_cursor_segment +returns the start of the virtually-contiguous segment at the current position of +.Fa cc . +The length of the segment is stored in +.Fa len . +.Sh RETURN VALUES +.Fn crypto_apply +and +.Fn crypto_apply_buf +return the return value from the caller-supplied callback function. +.Pp +.Fn crypto_buffer_contiguous_subsegment , +.Fn crypto_contiguous_subsegment , +and +.Fn crypto_cursor_segment +return a pointer to a contiguous segment or +.Dv NULL . +.Pp +.Fn crypto_buffer_len +returns the length of a buffer in bytes. +.Pp +.Fn crypto_cursor_seglen +returns the length in bytes of a contiguous segment. +.Pp +.Fn crypto_cursor_copy +makes a deep copy of the cursor +.Fa fromc . +The two copies do not share any state and can thus be used +independently. +.Pp +.Fn CRYPTO_HAS_OUTPUT_BUFFER +returns true if the request uses a separate output buffer. +.Sh SEE ALSO +.Xr ipsec 4 , +.Xr crypto 7 , +.Xr bus_dma 9 , +.Xr crypto 9 , +.Xr crypto_driver 9 , +.Xr crypto_request 9 , +.Xr crypto_session 9 , +.Xr mbuf 9 , +.Xr uio 9 +.Sh HISTORY +The +.Nm +functions first appeared in +.Fx 13 . +.Sh AUTHORS +The +.Nm +functions and this manual page were written by +.An John Baldwin Aq Mt jhb@FreeBSD.org . diff --git a/static/freebsd/man9/crypto_driver.9 b/static/freebsd/man9/crypto_driver.9 new file mode 100644 index 00000000..51b036da --- /dev/null +++ b/static/freebsd/man9/crypto_driver.9 @@ -0,0 +1,337 @@ +.\" Copyright (c) 2020, Chelsio Inc +.\" +.\" 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. Neither the name of the Chelsio Inc nor the names of its +.\" contributors may be used to endorse or promote products derived from +.\" this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 COPYRIGHT OWNER 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. +.\" +.\" * Other names and brands may be claimed as the property of others. +.\" +.Dd April 12, 2021 +.Dt CRYPTO_DRIVER 9 +.Os +.Sh NAME +.Nm crypto_driver +.Nd interface for symmetric cryptographic drivers +.Sh SYNOPSIS +.In opencrypto/cryptodev.h +.Ft void +.Fn crypto_copyback "struct cryptop *crp" "int off" "int size" "const void *src" +.Ft void +.Fn crypto_copydata "struct cryptop *crp" "int off" "int size" "void *dst" +.Ft void +.Fn crypto_done "struct cryptop *crp" +.Ft int32_t +.Fn crypto_get_driverid "device_t dev" "size_t session_size" "int flags" +.Ft void * +.Fn crypto_get_driver_session "crypto_session_t crypto_session" +.Ft void +.Fn crypto_read_iv "struct cryptop *crp" "void *iv" +.Ft int +.Fn crypto_unblock "uint32_t driverid" "int what" +.Ft int +.Fn crypto_unregister_all "uint32_t driverid" +.Ft int +.Fn CRYPTODEV_FREESESSION "device_t dev" "crypto_session_t crypto_session" +.Ft int +.Fo CRYPTODEV_NEWSESSION +.Fa "device_t dev" +.Fa "crypto_session_t crypto_session" +.Fa "const struct crypto_session_params *csp" +.Fc +.Ft int +.Fo CRYPTODEV_PROBESESSION +.Fa "device_t dev" +.Fa "const struct crypto_session_params *csp" +.Fc +.Ft int +.Fn CRYPTODEV_PROCESS "device_t dev" "struct cryptop *crp" "int flags" +.Ft void +.Fo hmac_init_ipad +.Fa "struct auth_hash *axf" +.Fa "const char *key" +.Fa "int klen" +.Fa "void *auth_ctx" +.Fc +.Ft void +.Fo hmac_init_opad +.Fa "struct auth_hash *axf" +.Fa "const char *key" +.Fa "int klen" +.Fa "void *auth_ctx" +.Fc +.Sh DESCRIPTION +Symmetric cryptographic drivers process cryptographic requests +submitted to sessions associated with the driver. +.Pp +Cryptographic drivers call +.Fn crypto_get_driverid +to register with the cryptographic framework. +.Fa dev +is the device used to service requests. +The +.Fn CRYPTODEV +methods are defined in the method table for the device driver attached to +.Fa dev . +.Fa session_size +specifies the size of a driver-specific per-session structure allocated by +the cryptographic framework. +.Fa flags +is a bitmask of properties about the driver. +Exactly one of +.Dv CRYPTOCAP_F_SOFTWARE +or +.Dv CRYPTOCAP_F_HARDWARE +must be specified. +.Dv CRYPTOCAP_F_SOFTWARE +should be used for drivers which process requests using host CPUs. +.Dv CRYPTOCAP_F_HARDWARE +should be used for drivers which process requests on separate co-processors. +.Dv CRYPTOCAP_F_SYNC +should be set for drivers which process requests synchronously in +.Fn CRYPTODEV_PROCESS . +.Dv CRYPTOCAP_F_ACCEL_SOFTWARE +should be set for software drivers which use accelerated CPU instructions. +.Fn crypto_get_driverid +returns an opaque driver id. +.Pp +.Fn crypto_unregister_all +unregisters a driver from the cryptographic framework. +If there are any pending operations or open sessions, +this function will sleep. +.Fa driverid +is the value returned by an earlier call to +.Fn crypto_get_driverid . +.Pp +When a new session is created by +.Fn crypto_newsession , +.Fn CRYPTODEV_PROBESESSION +is invoked by the cryptographic framework on each active driver to +determine the best driver to use for the session. +This method should inspect the session parameters in +.Fa csp . +If a driver does not support requests described by +.Fa csp , +this method should return an error value. +If the driver does support requests described by +.Fa csp , +it should return a negative value. +The framework prefers drivers with the largest negative value, +similar to +.Xr DEVICE_PROBE 9 . +The following values are defined for non-error return values from this +method: +.Bl -tag -width "CRYPTODEV_PROBE_ACCEL_SOFTWARE" +.It Dv CRYPTODEV_PROBE_HARDWARE +The driver processes requests via a co-processor. +.It Dv CRYPTODEV_PROBE_ACCEL_SOFTWARE +The driver processes requests on the host CPU using optimized instructions +such as AES-NI. +.It Dv CRYPTODEV_PROBE_SOFTWARE +The driver processes requests on the host CPU. +.El +.Pp +This method should not sleep. +.Pp +Once the framework has chosen a driver for a session, +the framework invokes the +.Fn CRYPTODEV_NEWSESSION +method to initialize driver-specific session state. +Prior to calling this method, +the framework allocates a per-session driver-specific data structure. +This structure is initialized with zeroes, +and its size is set by the +.Fa session_size +passed to +.Fn crypto_get_driverid . +This method can retrieve a pointer to this data structure by passing +.Fa crypto_session +to +.Fn crypto_get_driver_session . +Session parameters are described in +.Fa csp . +.Pp +This method should not sleep. +.Pp +.Fn CRYPTODEV_FREESESSION +is invoked to release any driver-specific state when a session is +destroyed. +The per-session driver-specific data structure is explicitly zeroed +and freed by the framework after this method returns. +If a driver requires no additional tear-down steps, it can leave +this method undefined. +.Pp +This method should not sleep. +.Pp +.Fn CRYPTODEV_PROCESS +is invoked for each request submitted to an active session. +This method can either complete a request synchronously or +schedule it to be completed asynchronously, +but it must not sleep. +.Pp +If this method is not able to complete a request due to insufficient +resources such as a full command queue, +it can defer the request by returning +.Dv ERESTART . +The request will be queued by the framework and retried once the +driver releases pending requests via +.Fn crypto_unblock . +Any requests submitted to sessions belonging to the driver will also +be queued until +.Fn crypto_unblock +is called. +.Pp +If a driver encounters errors while processing a request, +it should report them via the +.Fa crp_etype +field of +.Fa crp +rather than returning an error directly. +.Pp +.Fa flags +may be set to +.Dv CRYPTO_HINT_MORE +if there are additional requests queued for this driver. +The driver can use this as a hint to batch completion interrupts. +Note that these additional requests may be from different sessions. +.Pp +.Fn crypto_get_driver_session +returns a pointer to the driver-specific per-session data structure +for the session +.Fa crypto_session . +This function can be used in the +.Fn CRYPTODEV_NEWSESSION , +.Fn CRYPTODEV_PROCESS , +and +.Fn CRYPTODEV_FREESESSION +callbacks. +.Pp +.Fn crypto_copydata +copies +.Fa size +bytes out of the input buffer for +.Fa crp +into a local buffer pointed to by +.Fa dst . +The bytes are read starting at an offset of +.Fa off +bytes in the request's input buffer. +.Pp +.Fn crypto_copyback +copies +.Fa size +bytes from the local buffer pointed to by +.Fa src +into the output buffer for +.Fa crp . +The bytes are written starting at an offset of +.Fa off +bytes in the request's output buffer. +.Pp +.Fn crypto_read_iv +copies the IV or nonce for +.Fa crp +into the local buffer pointed to by +.Fa iv . +.Pp +A driver calls +.Fn crypto_done +to mark the request +.Fa crp +as completed. +Any errors should be set in +.Fa crp_etype +prior to calling this function. +.Pp +If a driver defers a request by returning +.Dv ERESTART +from +.Dv CRYPTO_PROCESS , +the framework will queue all requests for the driver until the driver calls +.Fn crypto_unblock +to indicate that the temporary resource shortage has been relieved. +For example, +if a driver returns +.Dv ERESTART +due to a full command ring, +it would invoke +.Fn crypto_unblock +from a command completion interrupt that makes a command ring entry available. +.Fa driverid +is the value returned by +.Fn crypto_get_driverid . +.Fa what +indicates which types of requests the driver is able to handle again: +.Bl -tag -width "CRYPTO_SYMQ" +.It Dv CRYPTO_SYMQ +indicates that the driver is able to handle symmetric requests passed to +.Fn CRYPTODEV_PROCESS . +.El +.Pp +.Fn hmac_init_ipad +prepares an authentication context to generate the inner hash of an HMAC. +.Fa axf +is a software implementation of an authentication algorithm such as the +value returned by +.Fn crypto_auth_hash . +.Fa key +is a pointer to a HMAC key of +.Fa klen +bytes. +.Fa auth_ctx +points to a valid authentication context for the desired algorithm. +The function initializes the context with the supplied key. +.Pp +.Fn hmac_init_opad +is similar to +.Fn hmac_init_ipad +except that it prepares an authentication context to generate the +outer hash of an HMAC. +.Sh RETURN VALUES +.Fn crypto_apply +returns the return value from the caller-supplied callback function. +.Pp +.Fn crypto_contiguous_subsegment +returns a pointer to a contiguous segment or +.Dv NULL . +.Pp +.Fn crypto_get_driverid +returns a driver identifier on success or -1 on error. +.Pp +.Fn crypto_unblock , +.Fn crypto_unregister_all , +.Fn CRYPTODEV_FREESESSION , +.Fn CRYPTODEV_NEWSESSION , +and +.Fn CRYPTODEV_PROCESS +return zero on success or an error on failure. +.Pp +.Fn CRYPTODEV_PROBESESSION +returns a negative value on success or an error on failure. +.Sh SEE ALSO +.Xr crypto 7 , +.Xr crypto 9 , +.Xr crypto_buffer 9 , +.Xr crypto_request 9 , +.Xr crypto_session 9 diff --git a/static/freebsd/man9/crypto_request.9 b/static/freebsd/man9/crypto_request.9 new file mode 100644 index 00000000..80c0e5ec --- /dev/null +++ b/static/freebsd/man9/crypto_request.9 @@ -0,0 +1,527 @@ +.\" Copyright (c) 2020, Chelsio Inc +.\" +.\" 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. Neither the name of the Chelsio Inc nor the names of its +.\" contributors may be used to endorse or promote products derived from +.\" this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 COPYRIGHT OWNER 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. +.\" +.\" * Other names and brands may be claimed as the property of others. +.\" +.Dd May 8, 2025 +.Dt CRYPTO_REQUEST 9 +.Os +.Sh NAME +.Nm crypto_request +.Nd symmetric cryptographic operations +.Sh SYNOPSIS +.In opencrypto/cryptodev.h +.Ft "struct cryptop *" +.Fn crypto_clonereq "crypto_session_t cses" "struct cryptop *crp" "int how" +.Ft int +.Fn crypto_dispatch "struct cryptop *crp" +.Ft int +.Fn crypto_dispatch_async "struct cryptop *crp" "int flags" +.Ft void +.Fn crypto_dispatch_batch "struct cryptopq *crpq" "int flags" +.Ft void +.Fn crypto_destroyreq "struct cryptop *crp" +.Ft void +.Fn crypto_freereq "struct cryptop *crp" +.Ft "struct cryptop *" +.Fn crypto_getreq "crypto_session_t cses" "int how" +.Ft void +.Fn crypto_initreq "struct cryptop *crp" "crypto_session_t cses" +.Ft void +.Fn crypto_use_buf "struct cryptop *crp" "void *buf" "int len" +.Ft void +.Fn crypto_use_mbuf "struct cryptop *crp" "struct mbuf *m" +.Ft void +.Fn crypto_use_uio "struct cryptop *crp" "struct uio *uio" +.Ft void +.Fn crypto_use_vmpage "struct cryptop *crp" "vm_page_t *pages" "int len" "int offset" +.Ft void +.Fn crypto_use_output_buf "struct cryptop *crp" "void *buf" "int len" +.Ft void +.Fn crypto_use_output_mbuf "struct cryptop *crp" "struct mbuf *m" +.Ft void +.Fn crypto_use_output_uio "struct cryptop *crp" "struct uio *uio" +.Ft void +.Fn crypto_use_output_vmpage "struct cryptop *crp" "vm_page_t *pages" "int len" "int offset" +.Sh DESCRIPTION +Each symmetric cryptographic operation in the kernel is described by +an instance of +.Vt struct cryptop +and is associated with an active session. +.Pp +Requests can either be allocated dynamically or use caller-supplied +storage. +Dynamically allocated requests should be allocated by either +.Fn crypto_getreq +or +.Fn crypto_clonereq , +and freed by +.Fn crypto_freereq +once the request has completed. +Requests using caller-supplied storage should be initialized by +.Fn crypto_initreq +at the start of each operation and destroyed by +.Fn crypto_destroyreq +once the request has completed. +.Pp +For +.Fn crypto_clonereq , +.Fn crypto_getreq , +and +.Fn crypto_initreq , +.Fa cses +is a reference to an active session. +For +.Fn crypto_clonereq +and +.Fn crypto_getreq , +.Fa how +is passed to +.Xr malloc 9 +and should be set to either +.Dv M_NOWAIT +or +.Dv M_WAITOK . +.Pp +.Fn crypto_clonereq +allocates a new request that inherits request inputs such as request buffers +from the original +.Fa crp +request. +However, the new request is associated with the +.Fa cses +session rather than inheriting the session from +.Fa crp . +.Fa crp +must not be a completed request. +.Pp +Once a request has been initialized, +the caller should set fields in the structure to describe +request-specific parameters. +Unused fields should be left as-is. +.Pp +The +.Fn crypto_dispatch , +.Fn crypto_dispatch_async , +and +.Fn crypto_dispatch_batch +functions pass one or more crypto requests to the driver attached to the +request's session. +If there are errors in the request's fields, these functions may return an +error to the caller. +If errors are encountered while servicing the request, they will instead +be reported to the request's callback function +.Pq Fa crp_callback +via +.Fa crp_etype . +.Pp +Note that a request's callback function may be invoked before +.Fn crypto_dispatch +returns. +.Pp +Once a request has signaled completion by invoking its callback function, +it should be freed via +.Fn crypto_destroyreq +or +.Fn crypto_freereq . +.Pp +Cryptographic operations include several fields to describe the request. +.Ss Request Buffers +Requests can either specify a single data buffer that is modified in place +.Po +.Fa crp_buf +.Pc +or separate input +.Po +.Fa crp_buf +.Pc +and output +.Po +.Fa crp_obuf +.Pc +buffers. +Note that separate input and output buffers are not supported for compression +mode requests. +.Pp +All requests must have a valid +.Fa crp_buf +initialized by one of the following functions: +.Bl -tag -width "Fn crypto_use_vmpage" +.It Fn crypto_use_buf +Uses an array of +.Fa len +bytes pointed to by +.Fa buf +as the data buffer. +.It Fn crypto_use_mbuf +Uses the network memory buffer +.Fa m +as the data buffer. +.It Fn crypto_use_uio +Uses the scatter/gather list +.Fa uio +as the data buffer. +.It Fn crypto_use_vmpage +Uses the array of +.Vt vm_page_t +structures as the data buffer. +.El +.Pp +One of the following functions should be used to initialize +.Fa crp_obuf +for requests that use separate input and output buffers: +.Bl -tag -width "Fn crypto_use_output_vmpage" +.It Fn crypto_use_output_buf +Uses an array of +.Fa len +bytes pointed to by +.Fa buf +as the output buffer. +.It Fn crypto_use_output_mbuf +Uses the network memory buffer +.Fa m +as the output buffer. +.It Fn crypto_use_output_uio +Uses the scatter/gather list +.Fa uio +as the output buffer. +.It Fn crypto_use_output_vmpage +Uses the array of +.Vt vm_page_t +structures as the output buffer. +.El +.Ss Request Regions +Each request describes one or more regions in the data buffers. +Each region is described by an offset relative to the start of a +data buffer and a length. +The length of some regions is the same for all requests belonging to +a session. +Those lengths are set in the session parameters of the associated +session. +All requests must define a payload region. +Other regions are only required for specific session modes. +.Pp +For requests with separate input and output data buffers, +the AAD, IV, and payload regions are always defined as regions in the +input buffer, +and a separate payload output region is defined to hold the output of +encryption or decryption in the output buffer. +The digest region describes a region in the input data buffer for +requests that verify an existing digest. +For requests that compute a digest, +the digest region describes a region in the output data buffer. +Note that the only data written to the output buffer is the encryption +or decryption result and any computed digest. +AAD and IV regions are not copied from the input buffer into the output +buffer but are only used as inputs. +.Pp +The following regions are defined: +.Bl -column "Payload Output" "Input/Output" +.It Sy Region Ta Sy Buffer Ta Sy Description +.It AAD Ta Input Ta +Embedded Additional Authenticated Data +.It IV Ta Input Ta +Embedded IV or nonce +.It Payload Ta Input Ta +Data to encrypt, decrypt, compress, or decompress +.It Payload Output Ta Output Ta +Encrypted or decrypted data +.It Digest Ta Input/Output Ta +Authentication digest, hash, or tag +.El +.Bl -column "Payload Output" ".Fa crp_payload_output_start" +.It Sy Region Ta Sy Start Ta Sy Length +.It AAD Ta Fa crp_aad_start Ta Fa crp_aad_length +.It IV Ta Fa crp_iv_start Ta Fa csp_ivlen +.It Payload Ta Fa crp_payload_start Ta Fa crp_payload_length +.It Payload Output Ta Fa crp_payload_output_start Ta Fa crp_payload_length +.It Digest Ta Fa crp_digest_start Ta Fa csp_auth_mlen +.El +.Pp +Requests are permitted to operate on only a subset of the data buffer. +For example, +requests from IPsec operate on network packets that include headers not +used as either additional authentication data (AAD) or payload data. +.Ss Request Operations +All requests must specify the type of operation to perform in +.Fa crp_op . +Available operations depend on the session's mode. +.Pp +Compression requests support the following operations: +.Bl -tag -width CRYPTO_OP_DECOMPRESS +.It Dv CRYPTO_OP_COMPRESS +Compress the data in the payload region of the data buffer. +.It Dv CRYPTO_OP_DECOMPRESS +Decompress the data in the payload region of the data buffer. +.El +.Pp +Cipher requests support the following operations: +.Bl -tag -width CRYPTO_OP_DECRYPT +.It Dv CRYPTO_OP_ENCRYPT +Encrypt the data in the payload region of the data buffer. +.It Dv CRYPTO_OP_DECRYPT +Decrypt the data in the payload region of the data buffer. +.El +.Pp +Digest requests support the following operations: +.Bl -tag -width CRYPTO_OP_COMPUTE_DIGEST +.It Dv CRYPTO_OP_COMPUTE_DIGEST +Calculate a digest over the payload region of the data buffer +and store the result in the digest region. +.It Dv CRYPTO_OP_VERIFY_DIGEST +Calculate a digest over the payload region of the data buffer. +Compare the calculated digest to the existing digest from the digest region. +If the digests match, +complete the request successfully. +If the digests do not match, +fail the request with +.Er EBADMSG . +.El +.Pp +AEAD and Encrypt-then-Authenticate requests support the following +operations: +.Bl -tag -width CRYPTO_OP +.It Dv CRYPTO_OP_ENCRYPT | Dv CRYPTO_OP_COMPUTE_DIGEST +Encrypt the data in the payload region of the data buffer. +Calculate a digest over the AAD and payload regions and store the +result in the data buffer. +.It Dv CRYPTO_OP_DECRYPT | Dv CRYPTO_OP_VERIFY_DIGEST +Calculate a digest over the AAD and payload regions of the data buffer. +Compare the calculated digest to the existing digest from the digest region. +If the digests match, +decrypt the payload region. +If the digests do not match, +fail the request with +.Er EBADMSG . +.El +.Ss Request AAD +AEAD and Encrypt-then-Authenticate requests may optionally include +Additional Authenticated Data. +AAD may either be supplied in the AAD region of the input buffer or +as a single buffer pointed to by +.Fa crp_aad . +In either case, +.Fa crp_aad_length +always indicates the amount of AAD in bytes. +.Ss Request ESN +IPsec requests may optionally include Extended Sequence Numbers (ESN). +ESN may either be supplied in +.Fa crp_esn +or as part of the AAD pointed to by +.Fa crp_aad . +.Pp +If the ESN is stored in +.Fa crp_esn , +.Dv CSP_F_ESN +should be set in +.Fa csp_flags . +This use case is dedicated for encrypt and authenticate mode, since the +high-order 32 bits of the sequence number are appended after the Next Header +(RFC 4303). +.Pp +AEAD modes supply the ESN in a separate AAD buffer (see e.g. RFC 4106, Chapter 5 +AAD Construction). +.Ss Request IV and/or Nonce +Some cryptographic operations require an IV or nonce as an input. +An IV may be stored either in the IV region of the data buffer or in +.Fa crp_iv . +By default, +the IV is assumed to be stored in the IV region. +If the IV is stored in +.Fa crp_iv , +.Dv CRYPTO_F_IV_SEPARATE +should be set in +.Fa crp_flags +and +.Fa crp_iv_start +should be left as zero. +.Pp +Requests that store part, but not all, of the IV in the data buffer should +store the partial IV in the data buffer and pass the full IV separately in +.Fa crp_iv . +.Ss Request and Callback Scheduling +The crypto framework provides multiple methods of scheduling the dispatch +of requests to drivers along with the processing of driver callbacks. +The +.Fn crypto_dispatch , +.Fn crypto_dispatch_async , +and +.Fn crypto_dispatch_batch +functions can be used to request different dispatch scheduling policies. +.Pp +.Fn crypto_dispatch +synchronously passes the request to the driver. +The driver itself may process the request synchronously or asynchronously +depending on whether the driver is implemented by software or hardware. +.Pp +.Fn crypto_dispatch_async +dispatches the request asynchronously. +If the driver is inherently synchronous, the request is queued to a taskqueue +backed by a pool of worker threads. +This can increase throughput by allowing requests from a single producer to be +processed in parallel. +By default the pool is sized to provide one thread for each CPU. +Worker threads dequeue requests and pass them to the driver asynchronously. +.Fn crypto_dispatch_async +additionally takes a +.Va flags +parameter. +The +.Dv CRYPTO_ASYNC_ORDERED +flag indicates that completion callbacks for requests must be called in the +same order as requests were dispatched. +If the driver is asynchronous, the behavior of +.Fn crypto_dispatch_async +is identical to that of +.Fn crypto_dispatch . +.Pp +.Fn crypto_dispatch_batch +allows the caller to collect a batch of requests and submit them to the driver +at the same time. +This allows hardware drivers to optimize the scheduling of request processing +and batch completion interrupts. +A batch is submitted to the driver by invoking the driver's process method on +each request, specifying +.Dv CRYPTO_HINT_MORE +with each request except for the last. +The +.Fa flags +parameter to +.Fn crypto_dispatch_batch +is currently ignored. +.Pp +Callback function scheduling is simpler than request scheduling. +Callbacks can either be invoked synchronously from +.Fn crypto_done , +or they can be queued to a pool of worker threads. +This pool of worker threads is also sized to provide one worker thread +for each CPU by default. +Note that a callback function invoked synchronously from +.Fn crypto_done +must follow the same restrictions placed on threaded interrupt handlers. +.Pp +By default, +callbacks are invoked asynchronously by a worker thread. +If +.Dv CRYPTO_F_CBIMM +is set, +the callback is always invoked synchronously from +.Fn crypto_done . +If +.Dv CRYPTO_F_CBIFSYNC +is set, +the callback is invoked synchronously if the request was processed by a +software driver or asynchronously if the request was processed by a +hardware driver. +.Pp +If a request was scheduled to the taskqueue with +.Dv CRYPTO_ASYNC_ORDERED , +callbacks are always invoked asynchronously ignoring +.Dv CRYPTO_F_CBIMM +and +.Dv CRYPTO_F_CBIFSYNC . +This flag is used by IPsec to ensure that decrypted network packets are +passed up the network stack in roughly the same order they were received. +.Ss Other Request Fields +In addition to the fields and flags enumerated above, +.Vt struct cryptop +includes the following: +.Bl -tag -width crp_payload_length +.It Fa crp_session +A reference to the active session. +This is set when the request is created by +.Fn crypto_getreq +and should not be modified. +Drivers can use this to fetch driver-specific session state or +session parameters. +.It Fa crp_etype +Error status. +Either zero on success, or an error if a request fails. +Set by drivers prior to completing a request via +.Fn crypto_done . +.It Fa crp_flags +A bitmask of flags. +.It Fa crp_cipher_key +Pointer to a request-specific encryption key. +If this value is not set, +the request uses the session encryption key. +.It Fa crp_auth_key +Pointer to a request-specific authentication key. +If this value is not set, +the request uses the session authentication key. +.It Fa crp_opaque +An opaque pointer. +This pointer permits users of the cryptographic framework to store +information about a request to be used in the callback. +.It Fa crp_callback +Callback function. +This must point to a callback function of type +.Vt void (*)(struct cryptop *) . +The callback function should inspect +.Fa crp_etype +to determine the status of the completed operation. +It should also arrange for the request to be freed via +.Fn crypto_freereq . +.It Fa crp_olen +Used with compression and decompression requests to describe the updated +length of the payload region in the data buffer. +.Pp +If a compression request increases the size of the payload, +then the data buffer is unmodified, the request completes successfully, +and +.Fa crp_olen +is set to the size the compressed data would have used. +Callers can compare this to the payload region length to determine if +the compressed data was discarded. +.El +.Sh RETURN VALUES +.Fn crypto_dispatch +returns an error if the request contained invalid fields, +or zero if the request was valid. +.Fn crypto_getreq +returns a pointer to a new request structure on success, +or +.Dv NULL +on failure. +.Dv NULL +can only be returned if +.Dv M_NOWAIT +was passed in +.Fa how . +.Sh SEE ALSO +.Xr ipsec 4 , +.Xr crypto 7 , +.Xr crypto 9 , +.Xr crypto_session 9 , +.Xr mbuf 9 , +.Xr uio 9 +.Sh BUGS +Not all drivers properly handle mixing session and per-request keys +within a single session. +Consumers should either use a single key for a session specified in +the session parameters or always use per-request keys. diff --git a/static/freebsd/man9/crypto_session.9 b/static/freebsd/man9/crypto_session.9 new file mode 100644 index 00000000..7ff10237 --- /dev/null +++ b/static/freebsd/man9/crypto_session.9 @@ -0,0 +1,269 @@ +.\" Copyright (c) 2020, Chelsio Inc +.\" +.\" 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. Neither the name of the Chelsio Inc nor the names of its +.\" contributors may be used to endorse or promote products derived from +.\" this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 COPYRIGHT OWNER 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. +.\" +.\" * Other names and brands may be claimed as the property of others. +.\" +.Dd June 22, 2020 +.Dt CRYPTO_SESSION 9 +.Os +.Sh NAME +.Nm crypto_session +.Nd state used for symmetric cryptographic services +.Sh SYNOPSIS +.In opencrypto/cryptodev.h +.Ft struct auth_hash * +.Fn crypto_auth_hash "const struct crypto_session_params *csp" +.Ft struct enc_xform * +.Fn crypto_cipher "const struct crypto_session_params *csp" +.Ft const struct crypto_session_params * +.Fn crypto_get_params "crypto_session_t cses" +.Ft int +.Fo crypto_newsession +.Fa "crypto_session_t *cses" +.Fa "const struct crypto_session_params *csp" +.Fa "int crid" +.Fc +.Ft int +.Fn crypto_freesession "crypto_session_t cses" +.Sh DESCRIPTION +Symmetric cryptographic operations in the kernel are associated with +cryptographic sessions. +Sessions hold state shared across multiple requests. +Active sessions are associated with a single cryptographic driver. +.Pp +The +.Vt crypto_session_t +type represents an opaque reference to an active session. +Session objects are allocated and managed by the cryptographic +framework. +.Pp +New sessions are created by +.Fn crypto_newsession . +.Fa csp +describes various parameters associated with the new session such as +the algorithms to use and any session-wide keys. +.Fa crid +can be used to request either a specific cryptographic driver or +classes of drivers. +For the latter case, +.Fa crid +should be set to a mask of the following values: +.Bl -tag -width "CRYPTOCAP_F_HARDWARE" +.It Dv CRYPTOCAP_F_HARDWARE +Request hardware drivers. +Hardware drivers do not use the host CPU to perform operations. +Typically, a separate co-processor performs the operations asynchronously. +.It Dv CRYPTOCAP_F_SOFTWARE +Request software drivers. +Software drivers use the host CPU to perform operations. +The kernel includes a simple, yet portable implementation of each supported +algorithm in the +.Xr cryptosoft 4 +driver. +Additional software drivers may also be available on architectures which +provide instructions designed to accelerate cryptographic operations. +.El +.Pp +If both hardware and software drivers are requested, +hardware drivers are preferred over software drivers. +Accelerated software drivers are preferred over the baseline software driver. +If multiple hardware drivers are available, +the framework will distribute sessions across these drivers in a round-robin +fashion. +.Pp +On success, +.Fn crypto_newsession +saves a reference to the newly created session in +.Fa cses . +.Pp +.Fn crypto_freesession +is used to free the resources associated with the session +.Fa cses . +.Pp +.Fn crypto_auth_hash +returns a structure describing the baseline software implementation of an +authentication algorithm requested by +.Fa csp . +If +.Fa csp +does not specify an authentication algorithm, +or requests an invalid algorithm, +.Dv NULL +is returned. +.Pp +.Fn crypto_cipher +returns a structure describing the baseline software implementation of an +encryption algorithm requested by +.Fa csp . +If +.Fa csp +does not specify an encryption algorithm, +or requests an invalid algorithm, +.Dv NULL +is returned. +.Pp +.Fn crypto_get_params +returns a pointer to the session parameters used by +.Fa cses . +.Ss Session Parameters +Session parameters are used to describe the cryptographic operations +performed by cryptographic requests. +Parameters are stored in an instance of +.Vt struct crypto_session_params . +When initializing parameters to pass to +.Fn crypto_newsession , +the entire structure should first be zeroed. +Needed fields should then be set leaving unused fields as zero. +This structure contains the following fields: +.Bl -tag -width csp_cipher_klen +.It Fa csp_mode +Type of operation to perform. +This field must be set to one of the following: +.Bl -tag -width CSP_MODE_COMPRESS +.It Dv CSP_MODE_COMPRESS +Compress or decompress request payload. +.Pp +The compression algorithm is specified in +.Fa csp_cipher_alg . +.It Dv CSP_MODE_CIPHER +Encrypt or decrypt request payload. +.Pp +The encryption algorithm is specified in +.Fa csp_cipher_alg . +.It Dv CSP_MODE_DIGEST +Compute or verify a digest, or hash, of request payload. +.Pp +The authentication algorithm is specified in +.Fa csp_auth_alg . +.It Dv CSP_MODE_AEAD +Authenticated encryption with additional data. +Decryption operations require the digest, or tag, +and fail if it does not match. +.Pp +The AEAD algorithm is specified in +.Fa csp_cipher_alg . +.It Dv CSP_MODE_ETA +Encrypt-then-Authenticate. +In this mode, encryption operations encrypt the payload and then +compute an authentication digest over the request additional authentication +data followed by the encrypted payload. +Decryption operations fail without decrypting the data if the provided digest +does not match. +.Pp +The encryption algorithm is specified in +.Fa csp_cipher_alg +and the authentication algorithm is specified in +.Fa csp_auth_alg . +.El +.It Fa csp_flags +A mask of optional driver features. +Drivers will only attach to a session if they support all of the +requested features. +.Bl -tag -width CSP_F_SEPARATE_OUTPUT +.It Dv CSP_F_SEPARATE_OUTPUT +Support requests that use separate input and output buffers. +Sessions with this flag set permit requests with either a single buffer +that is modified in-place, or requests with separate input and output +buffers. +Sessions without this flag only permit requests with a single buffer that +is modified in-place. +.It Dv CSP_F_SEPARATE_AAD +Support requests that use a separate buffer for AAD rather than providing +AAD as a region in the input buffer. +Sessions with this flag set permit requests with AAD passed in either in +a region of the input buffer or in a single, virtually-contiguous buffer. +Sessions without this flag only permit requests with AAD passed in as +a region in the input buffer. +.It Dv CSP_F_ESN +Support requests that use a separate buffer for IPsec ESN (Extended Sequence +Numbers). +.Pp +Sessions with this flag set permit requests with IPsec ESN passed in special +buffer. +It is required for IPsec ESN support of encrypt and authenticate mode where +the high-order 32 bits of the sequence number are appended after the Next +Header (RFC 4303). +.El +.It Fa csp_ivlen +If either the cipher or authentication algorithms require an explicit +initialization vector (IV) or nonce, +this specifies the length in bytes. +All requests for a session use the same IV length. +.It Fa csp_cipher_alg +Encryption or compression algorithm. +.It Fa csp_cipher_klen +Length of encryption or decryption key in bytes. +All requests for a session use the same key length. +.It Fa csp_cipher_key +Pointer to encryption or decryption key. +If all requests for a session use request-specific keys, +this field should be left as +.Dv NULL . +This pointer and associated key must remain valid for the duration of the +crypto session. +.It Fa csp_auth_alg +Authentication algorithm. +.It Fa csp_auth_klen +Length of authentication key in bytes. +If the authentication algorithm does not use a key, +this field should be left as zero. +.It Fa csp_auth_key +Pointer to the authentication key. +If all requests for a session use request-specific keys, +this field should be left as +.Dv NULL . +This pointer and associated key must remain valid for the duration of the +crypto session. +.It Fa csp_auth_mlen +The length in bytes of the digest. +If zero, the full length of the digest is used. +If non-zero, the first +.Fa csp_auth_mlen +bytes of the digest are used. +.El +.Sh RETURN VALUES +.Fn crypto_newsession +returns a non-zero value if an error occurs or zero on success. +.Pp +.Fn crypto_auth_hash +and +.Fn crypto_cipher +return +.Dv NULL +if the request is valid or a pointer to a structure on success. +.Sh SEE ALSO +.Xr crypto 7 , +.Xr crypto 9 , +.Xr crypto_request 9 +.Sh BUGS +The current implementation of +.Nm crypto_freesession +does not provide a way for the caller to know that there are no other +references to the keys stored in the session's associated parameters. +This function should probably sleep until any in-flight cryptographic +operations associated with the session are completed. diff --git a/static/freebsd/man9/deadfs.9 b/static/freebsd/man9/deadfs.9 new file mode 100644 index 00000000..5f4d037a --- /dev/null +++ b/static/freebsd/man9/deadfs.9 @@ -0,0 +1,36 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> +.\" +.Dd October 24, 2025 +.Dt DEADFS 9 +.Os +.Sh NAME +.Nm deadfs +.Nd pseudo-filesystem to own reclaimed vnodes +.Sh DESCRIPTION +The +.Nm +file system implements operations that do not modify any data +and instead return indications of invalid IO. +Its role is to provide a fallback vnode operations vector for reclaimed +.Xr vnode 9 Ap s . +.Pp +It is a kernel-only pseudo-file system and so cannot be mounted from userspace. +.Sh SEE ALSO +.Xr insmntque 9 , +.Xr vnode 9 , +.Xr VOP_RECLAIM 9 +.Sh HISTORY +UNIX System Manager's Manual (SMM) for +.Bx 4.4 +described +.Nm +as a file system +.Dq where rejected vnodes go to die . +.Sh AUTHORS +The +.Nm +manual page was written by +.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . diff --git a/static/freebsd/man9/dev_clone.9 b/static/freebsd/man9/dev_clone.9 new file mode 100644 index 00000000..56bdd1a9 --- /dev/null +++ b/static/freebsd/man9/dev_clone.9 @@ -0,0 +1,76 @@ +.\" Copyright (c) 2008 Konstantin Belousov +.\" 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 January 3, 2009 +.Dt DEV_CLONE 9 +.Os +.Sh NAME +.Nm dev_clone , +.Nm drain_dev_clone_events +.Nd eventhandler for name-based device cloning in devfs +.Sh SYNOPSIS +.In sys/param.h +.In sys/conf.h +.Ft void +.Fn clone_handler "void *arg" "struct ucred *cr" "char *name" "int namelen" "struct cdev **dev" +.Bd -literal +EVENTHANDLER_REGISTER(dev_clone, clone_handler, arg, priority); +.Ed +.Ft void +.Fn drain_dev_clone_events +.Sh DESCRIPTION +A device driver may register a listener that will be notified each time +a name lookup on the +.Xr devfs 4 +mount point fails to find the vnode. +A listener shall be registered for the +.Va dev_clone +event. +When called, it is supplied with the first argument +.Va arg +that was specified at handler registration time, +appropriate credentials +.Va cr , +and a name +.Va name +of length +.Va namelen +that we look for. +If the handler decides that the name is appropriate and wants to create the device +that will be associated with the name, it should return it to devfs +in the +.Va dev +argument. +.Pp +The +.Fn drain_dev_clone_events +function is a barrier. +It is guaranteed that all calls to eventhandlers for +.Nm dev_clone +that were started before +.Fn drain_dev_clone_events +call, are finished before it returns control. +.Sh SEE ALSO +.Xr devfs 4 , +.Xr namei 9 diff --git a/static/freebsd/man9/dev_refthread.9 b/static/freebsd/man9/dev_refthread.9 new file mode 100644 index 00000000..f615725b --- /dev/null +++ b/static/freebsd/man9/dev_refthread.9 @@ -0,0 +1,151 @@ +.\" Copyright (c) 2018 Conrad Meyer +.\" 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 August 29, 2018 +.Dt DEV_REFTHREAD 9 +.Os +.Sh NAME +.Nm dev_refthread , +.Nm devvn_refthread , +.Nm dev_relthread +.Nd safely access device methods +.Sh SYNOPSIS +.In sys/param.h +.In sys/conf.h +.Ft "struct cdevsw *" +.Fn dev_refthread "struct cdev *dev" "int *ref" +.Ft "struct cdevsw *" +.Fn devvn_refthread "struct vnode *vp" "struct cdev **devp" "int *ref" +.Ft void +.Fn dev_relthread "struct cdev *dev" "int ref" +.Sh DESCRIPTION +The +.Fn dev_refthread +(or +.Fn devvn_refthread ) +and +.Fn dev_relthread +routines provide a safe way to access +.Xr devfs 4 +devices that may be concurrently destroyed by +.Fn destroy_dev +(e.g., removable media). +.Pp +If successful, +.Fn dev_refthread +and +.Fn devvn_refthread +acquire a "thread reference" to the associated +.Vt "struct cdev" +and return a non-NULL pointer to the cdev's +.Vt "struct cdevsw" +method table. +For the duration of that reference, the cdev's associated private data and +method table object are valid. +Destruction of the cdev sleeps until the thread reference is released. +.Pp +A reference cannot prevent media removal. +It is an implementation detail of individual drivers how method calls from +callers with +.Fn dev_refthread +references are handled when the device is +pending destruction. +A common behavior for disk devices is to return the +.Er ENXIO +status, but that is not required by this KPI. +.Pp +The +.Fn devvn_refthread +variant of +.Fn dev_refthread +extracts the +.Vt "struct cdev" +pointer out of the +.Dv VCHR +.Xr vnode 9 +automatically before performing the same actions as +.Fn dev_refthread . +Additionally, a pointer to the +.Vt "struct cdev" +is returned to the caller via +.Fa "*devp" . +.Fn devvn_refthread +correctly handles possible parallel reclamation of the vnode. +.Pp +.Fn dev_relthread +is used to release a reference to a +.Vt "struct cdev" . +.Fn dev_relthread +.Sy must +only be invoked when the associated invocation of +.Fn dev_refthread +or +.Fn devvn_refthread +returned a non-NULL +.Vt "struct cdevsw *" . +.Sh CONTEXT +.Vt struct cdev +objects have two reference counts, +.Va si_refcount +and +.Va si_threadcount . +The +.Fn dev_refthread , +.Fn devvn_refthread , +and +.Fn dev_relthread +functions manipulate the +.Va si_threadcount . +The +.Va si_threadcount +reference guarantees the liveness of the +.Vt struct cdev +object. +The other +.Va si_refcount +reference provides only the weaker guarantee that the memory backing the +.Vt struct cdev +has not been freed. +.Sh RETURN VALUES +If +.Fn dev_refthread +or +.Fn devvn_refthread +are unsuccessful, they return +.Dv NULL . +.Bf Em +If these routines are unsuccessful, they do not increment the +.Vt "struct cdev" +.Va si_threadcount +and do not initialize the value pointed to by the +.Fa "*ref" +parameter in any way. +.Ef +.Sh SEE ALSO +.Xr devfs 4 , +.Xr destroy_dev 9 +.Sh CAVEATS +Do not invoke +.Fn dev_relthread +unless the matching refthread routine succeeded! diff --git a/static/freebsd/man9/devclass.9 b/static/freebsd/man9/devclass.9 new file mode 100644 index 00000000..cbf81f3b --- /dev/null +++ b/static/freebsd/man9/devclass.9 @@ -0,0 +1,68 @@ +.\" -*- 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 June 16, 1998 +.Dt DEVCLASS 9 +.Os +.Sh NAME +.Nm devclass +.Nd object representing a class of devices +.Sh SYNOPSIS +.Vt typedef struct devclass *devclass_t ; +.Sh DESCRIPTION +The +.Vt devclass +object has two main functions in the system. +The first is to manage +the allocation of unit numbers for device instances and the second is +to hold the list of device drivers for a particular bus type. +Each +.Vt devclass +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 +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 , +.Xr devclass_find 9 , +.Xr devclass_find_driver 9 , +.Xr devclass_get_device 9 , +.Xr devclass_get_devices 9 , +.Xr devclass_get_maxunit 9 , +.Xr devclass_get_name 9 , +.Xr devclass_get_softc 9 , +.Xr device 9 , +.Xr driver 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/devclass_find.9 b/static/freebsd/man9/devclass_find.9 new file mode 100644 index 00000000..1e5661e4 --- /dev/null +++ b/static/freebsd/man9/devclass_find.9 @@ -0,0 +1,54 @@ +.\" -*- 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 June 16, 1998 +.Dt DEVCLASS_FIND 9 +.Os +.Sh NAME +.Nm devclass_find +.Nd search for a devclass +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft devclass_t +.Fn devclass_find "const char *classname" +.Sh DESCRIPTION +Search for the +.Vt devclass +with the specified name. +.Sh RETURN VALUES +If the +.Vt devclass +exists, it is returned, otherwise +.Dv NULL +is returned. +.Sh SEE ALSO +.Xr devclass 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/devclass_get_count.9 b/static/freebsd/man9/devclass_get_count.9 new file mode 100644 index 00000000..526a95cd --- /dev/null +++ b/static/freebsd/man9/devclass_get_count.9 @@ -0,0 +1,45 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2004 Nate Lawson +.\" 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 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 5, 2004 +.Dt DEVCLASS_GET_COUNT 9 +.Os +.Sh NAME +.Nm devclass_get_count +.Nd get the number of devices in a devclass +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn devclass_get_count "devclass_t dc" +.Sh DESCRIPTION +Returns the number of device instances in the specified +.Vt devclass . +.Sh SEE ALSO +.Xr devclass 9 , +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Nate Lawson . diff --git a/static/freebsd/man9/devclass_get_device.9 b/static/freebsd/man9/devclass_get_device.9 new file mode 100644 index 00000000..e66e994b --- /dev/null +++ b/static/freebsd/man9/devclass_get_device.9 @@ -0,0 +1,50 @@ +.\" -*- 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 June 16, 1998 +.Dt DEVCLASS_GET_DEVICE 9 +.Os +.Sh NAME +.Nm devclass_get_device +.Nd translate unit number to device +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft device_t +.Fn devclass_get_device "devclass_t dc" "int unit" +.Sh DESCRIPTION +This function retrieves the device instance with the given unit number +and returns it. +.Sh RETURN VALUES +If the device exists, it is returned, otherwise NULL is returned. +.Sh SEE ALSO +.Xr devclass 9 , +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/devclass_get_devices.9 b/static/freebsd/man9/devclass_get_devices.9 new file mode 100644 index 00000000..1c0c1354 --- /dev/null +++ b/static/freebsd/man9/devclass_get_devices.9 @@ -0,0 +1,58 @@ +.\" -*- 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 May 19, 2005 +.Dt DEVCLASS_GET_DEVICES 9 +.Os +.Sh NAME +.Nm devclass_get_devices +.Nd get a list of devices in a devclass +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn devclass_get_devices "devclass_t dc" "device_t **devlistp" "int *devcountp" +.Sh DESCRIPTION +Retrieve a list of all device instances currently in the devclass and +return the list in +.Fa *devlistp +and the count in +.Fa *devcountp . +The memory allocated for the list should be freed using +.Fn free "*devlistp" "M_TEMP" , +even if +.Fa *devcountp +is 0. +.Sh RETURN VALUES +Zero is returned on success, otherwise an appropriate error is returned. +.Sh SEE ALSO +.Xr devclass 9 , +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/devclass_get_drivers.9 b/static/freebsd/man9/devclass_get_drivers.9 new file mode 100644 index 00000000..b5937cb3 --- /dev/null +++ b/static/freebsd/man9/devclass_get_drivers.9 @@ -0,0 +1,58 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2005 Nate Lawson +.\" +.\" 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 May 19, 2005 +.Dt DEVCLASS_GET_DRIVERS 9 +.Os +.Sh NAME +.Nm devclass_get_drivers +.Nd "get a list of drivers in a devclass" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn devclass_get_drivers "devclass_t dc" "driver_t ***listp" "int *countp" +.Sh DESCRIPTION +Retrieve a list of pointers to all driver instances currently in the +devclass and return the list in +.Fa *listp +and the number of drivers in the list in +.Fa *countp . +The memory allocated for the list should be freed using +.Fn free *listp M_TEMP , +even if +.Fa *countp +is 0. +.Sh RETURN VALUES +Zero is returned on success, otherwise an appropriate error is returned. +.Sh SEE ALSO +.Xr devclass 9 , +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Nate Lawson . diff --git a/static/freebsd/man9/devclass_get_maxunit.9 b/static/freebsd/man9/devclass_get_maxunit.9 new file mode 100644 index 00000000..f99fa62f --- /dev/null +++ b/static/freebsd/man9/devclass_get_maxunit.9 @@ -0,0 +1,64 @@ +.\" -*- 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 September 10, 2010 +.Dt DEVCLASS_GET_MAXUNIT 9 +.Os +.Sh NAME +.Nm devclass_get_maxunit +.Nd find the maximum unit number in the class +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn devclass_get_maxunit "devclass_t dc" +.Sh DESCRIPTION +Returns the next unit number to be allocated to device instances in the +.Dv devclass . +This is one greater than the highest currently allocated unit. +.Sh RETURN VALUES +The +.Fn devclass_get_maxunit +function returns -1 if +.Fa dc +is +.Dv NULL , +otherwise it returns the next unit +number in +.Fa dc's +devclass. +.Sh ERRORS +None. +.Sh SEE ALSO +.Xr devclass 9 , +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . +.Sh BUGS +The name is confusing since it is one greater than the maximum unit. diff --git a/static/freebsd/man9/devclass_get_name.9 b/static/freebsd/man9/devclass_get_name.9 new file mode 100644 index 00000000..e66e7de6 --- /dev/null +++ b/static/freebsd/man9/devclass_get_name.9 @@ -0,0 +1,47 @@ +.\" -*- 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 June 16, 1998 +.Dt DEVCLASS_GET_NAME 9 +.Os +.Sh NAME +.Nm devclass_get_name +.Nd access the name of a devclass +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft const char * +.Fn devclass_get_name "devclass_t dc" +.Sh DESCRIPTION +Return the name of a devclass. +.Sh SEE ALSO +.Xr devclass 9 , +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/devclass_get_softc.9 b/static/freebsd/man9/devclass_get_softc.9 new file mode 100644 index 00000000..3580c1e3 --- /dev/null +++ b/static/freebsd/man9/devclass_get_softc.9 @@ -0,0 +1,50 @@ +.\" -*- 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 June 16, 1998 +.Dt DEVCLASS_GET_SOFTC 9 +.Os +.Sh NAME +.Nm devclass_get_softc +.Nd translate unit number to driver private structure +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft void * +.Fn devclass_get_softc "devclass_t dc" "int unit" +.Sh DESCRIPTION +This function retrieves the driver private instance variables for the +device with the given unit number and returns it. +.Sh RETURN VALUES +If the device exists, its driver-private variables are returned, +otherwise NULL is returned. +.Sh SEE ALSO +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/devctl_notify.9 b/static/freebsd/man9/devctl_notify.9 new file mode 100644 index 00000000..701b470c --- /dev/null +++ b/static/freebsd/man9/devctl_notify.9 @@ -0,0 +1,74 @@ +.\" +.\" Copyright (c) 2020 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 September 22, 2020 +.Dt DEVCTL_NOTIFY 9 +.Os +.Sh NAME +.Nm devctl_notify +.Nd Send a message, via devctl, to userland +.Sh SYNOPSIS +.In sys/devctl.h +.Ft void +.Fn devctl_notify "const char *system" "const char *subsystem" "const char *type" "const char *data" +.Sh DESCRIPTION +Send a notification to user land via +.Xr devctl 4 . +See +.Xr devctl 4 +for the format of these messages. +.Pp +The +.Nm +function creates a string using the following template: +.Bd -literal +snprintf(buffer, sizeof(buffer), "!system=%s subsystem=%s type=%s", + system, subsystem, type); +.Ed +.Pp +The +.Va system , +.Va subsystem , +and +.Va type +pointers cannot be NULL. +.Pp +The +.Va data +argument may be NULL (for no additions) or a message formatted +properly for +.Xr devctl 4 . +A space will be added to the above template and this argument copied +verbatim to form the message passed to userland. +Senders should balance between only passing data that userland can not +discover itself and sending all the data userland will want to use to +decide what to do with the message. +.Pp +The current total message length limit is just under 1kb. +Senders should try to remain well below this limit. +.Sh SEE ALSO +.Xr devctl 4 , +.Xr devd 8 +.Sh AUTHORS +This manual page was written by +.An M. Warner Losh diff --git a/static/freebsd/man9/devctl_process_running.9 b/static/freebsd/man9/devctl_process_running.9 new file mode 100644 index 00000000..155d0039 --- /dev/null +++ b/static/freebsd/man9/devctl_process_running.9 @@ -0,0 +1,56 @@ +.\" +.\" Copyright (c) 2020 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 September 22, 2020 +.Dt DEVCTL_PROCESS_RUNNING 9 +.Os +.Sh NAME +.Nm devctl_process_running +.Nd Returns true when devctl has a consumer process running +.Sh SYNOPSIS +.In sys/devctl.h +.Ft bool +.Fn devctl_process_running "void" +.Sh DESCRIPTION +The +.Nm +call returns +.Vt true +when a process has the devctl device open for +reading, and +.Vt false +otherwise. +One can assume from this that the default +.Xr devd 8 +or similar is running when +.Vt true +is returned. +Some subsystems will send a message and allow userland to do something +before proceeding with a default action if there's a timeout. +This call allows those subsystems to do the default action right away +when no process is running. +.Sh SEE ALSO +.Xr devd 8 +.Sh AUTHORS +This manual page was written by +.An M. Warner Losh diff --git a/static/freebsd/man9/devctl_safe_quote_sb.9 b/static/freebsd/man9/devctl_safe_quote_sb.9 new file mode 100644 index 00000000..e73574fb --- /dev/null +++ b/static/freebsd/man9/devctl_safe_quote_sb.9 @@ -0,0 +1,53 @@ +.\" +.\" Copyright (c) 2020 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 September 22, 2020 +.Dt DEVCTL_SAFE_QUOTE_SB 9 +.Os +.Sh NAME +.Nm devctl_safe_quote_sb +.Nd Insert a string, properly quoted, into a sbuf +.Sh SYNOPSIS +.In sys/devctl.h +.In sys/sbuf.h +.Ft void +.Fn devctl_safe_quote_sb "struct sbuf *sb" "const char *src" +.Sh DESCRIPTION +Copy the string from +.Va src +into +.Va sb . +All backslash characters are doubled. +All double quote characters +.Sq \&" +are also preceded by a backslash. +All other characters are copied without modification. +The +.Xr devctl 4 +protocol requires quoted string to be quoted thus. +This routine centralizes this knowledge. +.Sh SEE ALSO +.Xr devd 8 +.Sh AUTHORS +This manual page was written by +.An M. Warner Losh diff --git a/static/freebsd/man9/devfs_set_cdevpriv.9 b/static/freebsd/man9/devfs_set_cdevpriv.9 new file mode 100644 index 00000000..0cbfd3ee --- /dev/null +++ b/static/freebsd/man9/devfs_set_cdevpriv.9 @@ -0,0 +1,159 @@ +.\" Copyright (c) 2008 Konstantin Belousov +.\" 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 March 23, 2024 +.Dt DEVFS_CDEVPRIV 9 +.Os +.Sh NAME +.Nm devfs_set_cdevpriv , +.Nm devfs_get_cdevpriv , +.Nm devfs_clear_cdevpriv , +.Nm devfs_foreach_cdevpriv +.Nd manage per-open filedescriptor data for devices +.Sh SYNOPSIS +.In sys/param.h +.In sys/conf.h +.Bd -literal +typedef void d_priv_dtor_t(void *data); +.Ed +.Ft int +.Fn devfs_get_cdevpriv "void **datap" +.Ft int +.Fn devfs_set_cdevpriv "void *priv" "d_priv_dtor_t *dtr" +.Ft void +.Fn devfs_clear_cdevpriv "void" +.Ft int +.Fo devfs_foreach_cdevpriv +.Fa "struct cdev *dev" +.Fa "int (*cb)(void *data, void *arg)" +.Fa "void *arg" +.Fc +.Sh DESCRIPTION +The +.Fn devfs_xxx_cdevpriv +family of functions allows the +.Fa cdev +driver methods to associate some driver-specific data with each +user process +.Xr open 2 +of the device special file. +Currently, functioning of these functions is restricted to the context +of the +.Fa cdevsw +switch method calls performed as +.Xr devfs 4 +operations in response to system calls that use filedescriptors. +.Pp +The +.Fn devfs_set_cdevpriv +function associates a data pointed by +.Va priv +with current calling context (filedescriptor). +The data may be retrieved later, possibly from another call +performed on this filedescriptor, by the +.Fn devfs_get_cdevpriv +function. +The +.Fn devfs_clear_cdevpriv +disassociates previously attached data from context. +Immediately after +.Fn devfs_clear_cdevpriv +finished operating, the +.Va dtr +callback is called, with private data supplied +.Va data +argument. +The +.Fn devfs_clear_cdevpriv +function will be also be called if the open callback +function returns an error code. +.Pp +On the last filedescriptor close, system automatically arranges +.Fn devfs_clear_cdevpriv +call. +.Pp +If successful, the functions return 0. +.Pp +The function +.Fn devfs_set_cdevpriv +returns the following values on error: +.Bl -tag -width Er +.It Bq Er ENOENT +The current call is not associated with some filedescriptor. +.It Bq Er EBUSY +The private driver data is already associated with current +filedescriptor. +.El +.Pp +The function +.Fn devfs_get_cdevpriv +returns the following values on error: +.Bl -tag -width Er +.It Bq Er EBADF +The current call is not associated with some filedescriptor. +.It Bq Er ENOENT +The private driver data was not associated with current +filedescriptor, or +.Fn devfs_clear_cdevpriv +was called. +.El +.Pp +The function +.Fn devfs_foreach_cdevpriv +sequentially calls the function +.Fa cb +for each +.Nm cdevpriv +structure, currently associated with the +.Fa cdev +device. +The iterated +.Nm cdevpriv +data pointer and the user-supplied context +.Fa arg +are passed to the function +.Fa cb . +If +.Fa cb +returns non-zero value, the iteration stops on that element. +The +.Fn devfs_foreach_cdevpriv +returns the return value from the last call to +.Fa cb , +or zero if no +.Nm cdevpriv +data is currently associated with the device. +.Pp +Current implementation of the iterator makes it impossible to use +any blockable locking inside the callback +.Fa cb . +.Sh SEE ALSO +.Xr close 2 , +.Xr open 2 , +.Xr devfs 4 +.Sh HISTORY +The +.Fn devfs_cdevpriv +family of functions first appeared in +.Fx 7.1 . diff --git a/static/freebsd/man9/device.9 b/static/freebsd/man9/device.9 new file mode 100644 index 00000000..f813b7d7 --- /dev/null +++ b/static/freebsd/man9/device.9 @@ -0,0 +1,102 @@ +.\" -*- 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 DEVICE 9 +.Os +.Sh NAME +.Nm device +.Nd an abstract representation of a device +.Sh SYNOPSIS +.Vt typedef struct _device *device_t ; +.Sh DESCRIPTION +The device object represents a piece of hardware attached to the +system such as an expansion card, the bus which that card is plugged +into, disk drives attached to the expansion card etc. +The system defines one device, +.Va root_bus +and all other devices are created dynamically during +autoconfiguration. +Normally devices representing top-level buses in +the system (ISA, PCI etc.) will be attached directly to +.Va root_bus +and other devices will be added as children of their relevant bus. +.Pp +The devices in a system form a tree. +All devices except +.Va root_bus +have a parent (see +.Xr device_get_parent 9 ) . +In addition, any device can have children attached to it (see +.Xr device_add_child 9 , +.Xr device_add_child_ordered 9 , +.Xr device_find_child 9 , +.Xr device_get_children 9 , +and +.Xr device_delete_child 9 ) . +.Pp +A device which has been successfully probed and attached to the +system will also have a driver (see +.Xr device_get_driver 9 +and +.Xr driver 9 ) +and a devclass (see +.Xr device_get_devclass 9 +and +.Xr devclass 9 ) . +Various other attributes of the device include a unit number (see +.Xr device_get_unit 9 ) , +verbose description (normally supplied by the driver, see +.Xr device_set_desc 9 +and +.Xr device_get_desc 9 ) , +a set of bus-specific variables (see +.Xr device_get_ivars 9 ) +and a set of driver-specific variables (see +.Xr device_get_softc 9 ) . +.Pp +Devices can be in one of several states: +.Bl -tag -width DS_NOTPRESENT +.It Dv DS_NOTPRESENT +the device has not been probed for existence or the probe failed +.It Dv DS_ALIVE +the device probe succeeded but not yet attached +.It Dv DS_ATTACHED +the device has been successfully attached +.It Dv DS_BUSY +the device is currently open +.El +.Pp +The current state of the device can be determined by calling +.Xr device_get_state 9 . +.Sh SEE ALSO +.Xr devclass 9 , +.Xr driver 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/device_add_child.9 b/static/freebsd/man9/device_add_child.9 new file mode 100644 index 00000000..dfd0d190 --- /dev/null +++ b/static/freebsd/man9/device_add_child.9 @@ -0,0 +1,132 @@ +.\" -*- 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 February 11, 2018 +.Dt DEVICE_ADD_CHILD 9 +.Os +.Sh NAME +.Nm device_add_child , +.Nm device_add_child_ordered +.Nd "add a new device as a child of an existing device" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft device_t +.Fn device_add_child "device_t dev" "const char *name" "int unit" +.Ft device_t +.Fn device_add_child_ordered "device_t dev" "int order" "const char *name" "int unit" +.Sh DESCRIPTION +Create a new child device of +.Fa dev . +The +.Fa name +and +.Fa unit +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 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 +appropriate for the device. +If a name is specified then only drivers of that name are probed. +If no name is given then all drivers for the owning bus are probed. +In any event, only the name of the device is stored so that one may +safely unload/load a driver bound to that name. +.Pp +This allows buses which can uniquely identify device instances (such +as PCI) to allow each driver to check each device instance for a +match. +For buses which rely on supplied probe hints where only one +driver can have a chance of probing the device, the driver name should +be specified as the device name. +.Pp +Normally unit numbers will be chosen automatically by the system and a +unit number of +.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 +be passed. +If the specified unit number is already allocated, a new +unit will be allocated and a diagnostic message printed. +.Pp +If the devices attached to a bus must be probed in a specific order +(e.g.,\& for the ISA bus some devices are sensitive to failed probe attempts +of unrelated drivers and therefore must be probed first), +the +.Fa order +argument of +.Fn device_add_child_ordered +should be used to specify a partial ordering. +The new device will be added before any existing device with a greater +order. +If +.Fn device_add_child +is used, then the new child will be added as if its order was zero. +.Pp +When adding a device in the context of +.Xr DEVICE_IDENTIFY 9 +routine, the +.Xr device_find_child 9 +routine should be used to ensure that the device has not already been +added to the tree. +Because the device name and +.Vt devclass_t +are associated at probe time (not child addition time), previous +instances of the driver (say in a module that was later unloaded) may +have already added the instance. +Authors of bus drivers must likewise be careful when adding children +when they are loaded and unloaded to avoid duplication of children +devices. +.Pp +When adding a child to another device node, such as in an identify +routine, use +.Xr BUS_ADD_CHILD 9 +instead of +.Fn device_add_child . +.Xr BUS_ADD_CHILD 9 +will call +.Fn device_add_child +and add the proper bus-specific data to the new child. +.Fn device_add_child +does not call +.Xr BUS_ADD_CHILD 9 . +.Sh RETURN VALUES +The new device if successful, NULL otherwise. +.Sh SEE ALSO +.Xr BUS_ADD_CHILD 9 , +.Xr device 9 , +.Xr device_delete_child 9 , +.Xr device_find_child 9 , +.Xr DEVICE_IDENTIFY 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/device_delete_child.9 b/static/freebsd/man9/device_delete_child.9 new file mode 100644 index 00000000..819c7f5e --- /dev/null +++ b/static/freebsd/man9/device_delete_child.9 @@ -0,0 +1,67 @@ +.\" -*- 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 February 5, 2025 +.Dt DEVICE_DELETE_CHILD 9 +.Os +.Sh NAME +.Nm device_delete_child +.Nd delete a child from a device +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn device_delete_child "device_t dev" "device_t child" +.Sh DESCRIPTION +The specified device is removed from +.Fa dev +and deleted. +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 +.An Doug Rabson . diff --git a/static/freebsd/man9/device_delete_children.9 b/static/freebsd/man9/device_delete_children.9 new file mode 100644 index 00000000..d70fc6fe --- /dev/null +++ b/static/freebsd/man9/device_delete_children.9 @@ -0,0 +1,56 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2018 Jeroen Ruigrok van der Werven +.\" +.\" 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 September 28, 2018 +.Dt DEVICE_DELETE_CHILDREN 9 +.Os +.Sh NAME +.Nm device_delete_children +.Nd delete all child devices of a given device +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn device_delete_children "device_t dev" +.Sh DESCRIPTION +The +.Fn device_delete_children +function deletes all child devices of the given device +.Fa dev , +if any, +using the +.Fn device_delete_child +function for each device it finds. +If a child device cannot be deleted, this function will return an error code. +.Sh RETURN VALUES +Zero is returned on success, a non-zero return value indicates failure. +.Sh SEE ALSO +.Xr device_delete_child 9 +.Sh AUTHORS +This manual page was written by +.An Jeroen Ruigrok van der Werven . diff --git a/static/freebsd/man9/device_enable.9 b/static/freebsd/man9/device_enable.9 new file mode 100644 index 00000000..5f485ed9 --- /dev/null +++ b/static/freebsd/man9/device_enable.9 @@ -0,0 +1,61 @@ +.\" -*- 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 June 16, 1998 +.Dt DEVICE_ENABLE 9 +.Os +.Sh NAME +.Nm device_enable , +.Nm device_disable , +.Nm device_is_enabled +.Nd manipulate device enabled flag +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft void +.Fn device_enable "device_t dev" +.Ft void +.Fn device_disable "device_t dev" +.Ft int +.Fn device_is_enabled "device_t dev" +.Sh DESCRIPTION +Each device has an enabled flag associated with it. +A device is +enabled by default when it is created but may be disabled (for +instance to prevent a destructive or time consuming probe attempt). +To disable a device, call +.Fn device_disable , +to re-enable it, call +.Fn device_enable +and to test to see if a device is enabled, call +.Fn device_is_enabled . +.Sh SEE ALSO +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/device_find_child.9 b/static/freebsd/man9/device_find_child.9 new file mode 100644 index 00000000..69c767c1 --- /dev/null +++ b/static/freebsd/man9/device_find_child.9 @@ -0,0 +1,60 @@ +.\" -*- 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 February 8, 2005 +.Dt DEVICE_FIND_CHILD 9 +.Os +.Sh NAME +.Nm device_find_child +.Nd search for a child of a device +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft device_t +.Fn device_find_child "device_t dev" "const char *classname" "int unit" +.Sh DESCRIPTION +This function looks for a specific child of +.Dv dev +with the given +.Fa classname +and +.Fa unit . +If +.Fa unit +is \-1, it returns the first child of +.Fa dev +with a matching +.Fa classname +(that is, the one with the lowest unit). +.Sh RETURN VALUES +If it exists, the child device is returned, otherwise NULL. +.Sh SEE ALSO +.Xr device_add_child 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/device_get_children.9 b/static/freebsd/man9/device_get_children.9 new file mode 100644 index 00000000..45f8f468 --- /dev/null +++ b/static/freebsd/man9/device_get_children.9 @@ -0,0 +1,91 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" Copyright (c) 2025 Dag-Erling Smørgrav +.\" +.\" 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 November 28, 2025 +.Dt DEVICE_GET_CHILDREN 9 +.Os +.Sh NAME +.Nm device_get_children , +.Nm device_has_children +.Nd examine devices connected to a device +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn device_get_children "device_t dev" "device_t **devlistp" "int *devcountp" +.Ft bool +.Fn device_has_children "device_t dev" +.Sh DESCRIPTION +The +.Nm device_get_children +function retrieves a list of all device instances currently connected +to +.Fa dev . +It returns the list in +.Fa *devlistp +and the count in +.Fa *devcountp . +The memory allocated for the list should be freed using +.Fn free "*devlistp" "M_TEMP" . +.Fa devlistp +and +.Fa devcountp +are not changed when an error is returned. +.Pp +As a special case, if +.Fa devlistp +is null, no memory is allocated but the count is still returned in +.Fa *devcountp . +.Pp +The +.Nm device_has_children +function returns +.Dv true +if +.Fa dev +has at least one child and +.Dv false +if it has none. +.Sh RETURN VALUES +The +.Nm device_get_children +function returns zero on success and an appropriate error otherwise. +The +.Nm device_has_children +function returns true if the specified device has at least one child +and false otherwise. +.Sh SEE ALSO +.Xr devclass 9 , +.Xr device 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Doug Rabson Aq Mt dfr@FreeBSD.org +and +.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . diff --git a/static/freebsd/man9/device_get_devclass.9 b/static/freebsd/man9/device_get_devclass.9 new file mode 100644 index 00000000..142baaeb --- /dev/null +++ b/static/freebsd/man9/device_get_devclass.9 @@ -0,0 +1,50 @@ +.\" -*- 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 June 16, 1998 +.Dt DEVICE_GET_DEVCLASS 9 +.Os +.Sh NAME +.Nm device_get_devclass +.Nd access the devclass of a device +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft devclass_t +.Fn device_get_devclass "device_t dev" +.Sh DESCRIPTION +The current devclass associated with the device is returned. +If the device has no devclass, +.Dv NULL +is returned. +.Sh SEE ALSO +.Xr devclass 9 , +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/device_get_driver.9 b/static/freebsd/man9/device_get_driver.9 new file mode 100644 index 00000000..9694b2b4 --- /dev/null +++ b/static/freebsd/man9/device_get_driver.9 @@ -0,0 +1,50 @@ +.\" -*- 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 June 16, 1998 +.Dt DEVICE_GET_DRIVER 9 +.Os +.Sh NAME +.Nm device_get_driver +.Nd access the current driver of a device +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft driver_t * +.Fn device_get_driver "device_t dev" +.Sh DESCRIPTION +The current driver associated with the device is returned. +If the device has no driver, +.Dv NULL +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/static/freebsd/man9/device_get_ivars.9 b/static/freebsd/man9/device_get_ivars.9 new file mode 100644 index 00000000..deeede02 --- /dev/null +++ b/static/freebsd/man9/device_get_ivars.9 @@ -0,0 +1,62 @@ +.\" -*- 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 June 16, 1998 +.Dt DEVICE_GET_IVARS 9 +.Os +.Sh NAME +.Nm device_get_ivars , +.Nm device_set_ivars +.Nd access bus private variables +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft "void *" +.Fn device_get_ivars "device_t dev" +.Ft void +.Fn device_set_ivars "device_t dev" "void *ivar" +.Sh DESCRIPTION +The +.Fn device_get_ivars +function returns the bus-specific instance variables of a device. +.Pp +The +.Fn device_set_ivars +function sets the bus-specific instance variables of a device. +.Pp +Typically, only bus drivers will use these functions. +The kernel assumes that the bus driver will manage this memory, and no +automatic memory allocation or deallocation happens. +Client drivers should access ivars through the +.Xr BUS_READ_IVAR 9 +interface instead. +.Sh SEE ALSO +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/device_get_name.9 b/static/freebsd/man9/device_get_name.9 new file mode 100644 index 00000000..8a4a280b --- /dev/null +++ b/static/freebsd/man9/device_get_name.9 @@ -0,0 +1,50 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2003 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 April 21, 2003 +.Dt DEVICE_GET_NAME 9 +.Os +.Sh NAME +.Nm device_get_name , device_get_nameunit +.Nd access the name of a device's device class or instance +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft const char * +.Fn device_get_name "device_t dev" +.Ft const char * +.Fn device_get_nameunit "device_t dev" +.Sh DESCRIPTION +The +.Fn device_get_name +function returns the name of the device's device class. +.Pp +The +.Fn device_get_nameunit +function returns the name of the device's instance. +.Sh SEE ALSO +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Warner Losh . diff --git a/static/freebsd/man9/device_get_parent.9 b/static/freebsd/man9/device_get_parent.9 new file mode 100644 index 00000000..f5649139 --- /dev/null +++ b/static/freebsd/man9/device_get_parent.9 @@ -0,0 +1,44 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2003 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 April 21, 2003 +.Dt DEVICE_GET_PARENT 9 +.Os +.Sh NAME +.Nm device_get_parent +.Nd return the device's parent +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft device_t +.Fn device_get_parent "device_t dev" +.Sh DESCRIPTION +The +.Fn device_get_parent +function returns the name of the device's parent device. +.Sh SEE ALSO +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Warner Losh . diff --git a/static/freebsd/man9/device_get_property.9 b/static/freebsd/man9/device_get_property.9 new file mode 100644 index 00000000..dc7a7206 --- /dev/null +++ b/static/freebsd/man9/device_get_property.9 @@ -0,0 +1,90 @@ +.\" - +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2021 Semihalf +.\" +.\" 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 September 29, 2022 +.Dt DEVICE_GET_PROPERTY 9 +.Os +.Sh NAME +.Nm device_get_property , +.Nm device_has_property +.Nd access device specific data +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft ssize_t +.Fn device_get_property "device_t dev" "const char *prop" "void *val" "size_t sz" \ + "device_property_type_t type" +.Ft bool +.Fn device_has_property "device_t dev" "const char *prop" +.Sh DESCRIPTION +Access device specific data provided by the parent bus. +Drivers can use these properties to obtain device capabilities and set +necessary quirks. +.Pp +The underlying property type is specified with the +.Fa type +argument. +Currently the following types are supported: +.Bl -tag -width ".Dv DEVICE_PROP_BUFFER" +.It Dv DEVICE_PROP_BUFFER +The underlying property is a string of bytes. +.It Dv DEVICE_PROP_ANY +Wildcard property type. +.It Dv DEVICE_PROP_HANDLE +Following a reference the underlying property is a handle of the +respective bus. +.It Dv DEVICE_PROP_UINT32 +The underlying property is an array of unsigned 32 bit integers. +The +.Fa sz +argument shall be a multiple of 4. +.It Dv DEVICE_PROP_UINT64 +The underlying property is an array of unsigned 64 bit integers. +The +.Fa sz +argument shall be a multiple of 8. +.El +.Sh NOTES +You can pass NULL as pointer to property's value when calling +.Fn device_get_property +to obtain its size. +.Pp +Currently this interface is implemented by +.Xr simplebus 4 +and +.Xr acpi 4 . +.Sh RETURN VALUES +.Fn device_get_property +if successful returns property's size, otherwise returns -1. +.Pp +.Fn device_has_property +returns true if given property was found. +.Sh SEE ALSO +.Xr acpi 4 , +.Xr simplebus 4 , +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Bartlomiej Grzesik . diff --git a/static/freebsd/man9/device_get_softc.9 b/static/freebsd/man9/device_get_softc.9 new file mode 100644 index 00000000..c15868b3 --- /dev/null +++ b/static/freebsd/man9/device_get_softc.9 @@ -0,0 +1,67 @@ +.\" -*- 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 21, 2015 +.Dt DEVICE_GET_SOFTC 9 +.Os +.Sh NAME +.Nm device_get_softc +.Nd access driver private instance variables +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft void * +.Fn device_get_softc "device_t dev" +.Sh DESCRIPTION +Return the driver-specific software context of +.Fa dev . +The softc is automatically allocated and zeroed when the device is +attached. +The softc is also initialized and present when a device is probed, +but is subject to caveats as described in +.Xr DEVICE_PROBE 9 . +The size of the allocation is determined by the device's +.Vt driver_t +information used to define the driver. +The softc typically encapsulates the state of this instance of the +device. +.Pp +Driver writers are discouraged from using their own softc management +mechanisms. +Driver writers should not copy such mechanisms found in drivers in the +tree that predate this function. +.Sh RETURN VALUES +The pointer to the driver-specific instance variable is returned. +.Sh SEE ALSO +.Xr device 9 , +.Xr DEVICE_PROBE 9 , +.Xr device_set_softc 9 , +.Xr driver 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/device_get_state.9 b/static/freebsd/man9/device_get_state.9 new file mode 100644 index 00000000..d4ca43f2 --- /dev/null +++ b/static/freebsd/man9/device_get_state.9 @@ -0,0 +1,97 @@ +.\" -*- 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 June 16, 1998 +.Dt DEVICE_GET_STATE 9 +.Os +.Sh NAME +.Nm device_get_state , +.Nm device_busy , +.Nm device_unbusy , +.Nm device_is_alive , +.Nm device_is_attached +.Nd manipulate device state +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft device_state_t +.Fn device_get_state "device_t dev" +.Ft void +.Fn device_busy "device_t dev" +.Ft void +.Fn device_unbusy "device_t dev" +.Ft int +.Fn device_is_alive "device_t dev" +.Ft int +.Fn device_is_attached "device_t dev" +.Sh DESCRIPTION +The current state of a device is accessed by calling +.Fn device_get_state +which returns +.Dv DS_NOTPRESENT , +.Dv DS_ALIVE , +.Dv DS_ATTACHED +or +.Dv DS_BUSY +(described in +.Xr device 9 ) . +To test see if a device was successfully probed, call +.Fn device_is_alive +which simply returns if the state is greater or equal to +.Dv DS_ALIVE . +To test see if a device was successfully attached, call +.Fn device_is_attached +which simply returns if the state is greater or equal to +.Dv DS_ATTACHED . +.Pp +Each device has a busy count which is incremented when +.Fn device_busy +is called and decremented when +.Fn device_unbusy +is called. +Both routines return an error if the device state is less than +.Dv DS_ATTACHED . +.Pp +When +.Fn device_busy +is called on a device in the +.Dv DS_ATTACHED +state, the device changes to the +.Dv DS_BUSY +state. +When +.Fn device_unbusy +is called and after decrementing, the busy count for the device is +zero, the device changes to the +.Dv DS_ATTACHED +state. +.Sh SEE ALSO +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/device_get_sysctl.9 b/static/freebsd/man9/device_get_sysctl.9 new file mode 100644 index 00000000..b01302ba --- /dev/null +++ b/static/freebsd/man9/device_get_sysctl.9 @@ -0,0 +1,52 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2006 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 June 18, 2011 +.Dt DEVICE_GET_SYSCTL 9 +.Os +.Sh NAME +.Nm device_get_sysctl_ctx , +.Nm device_get_sysctl_tree +.Nd manipulate the sysctl oid tree for driver specific sysctl nodes +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft "struct sysctl_ctx_list *" +.Fn device_get_sysctl_ctx "device_t dev" +.Ft "struct sysctl_oid *" +.Fn device_get_sysctl_tree "device_t dev" +.Sh DESCRIPTION +The newbus system automatically adds a sysctl node for each device +in the system. +This node can be accessed with the +.Fn device_get_sysctl_tree +function. +The context for the node can be obtained with the +.Fn device_get_sysctl_ctx +function. +.Sh SEE ALSO +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Warner Losh . diff --git a/static/freebsd/man9/device_get_unit.9 b/static/freebsd/man9/device_get_unit.9 new file mode 100644 index 00000000..b294e544 --- /dev/null +++ b/static/freebsd/man9/device_get_unit.9 @@ -0,0 +1,46 @@ +.\" -*- 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 June 16, 1998 +.Dt DEVICE_GET_UNIT 9 +.Os +.Sh NAME +.Nm device_get_unit +.Nd access the unit number of a device +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn device_get_unit "device_t dev" +.Sh DESCRIPTION +Return the unit number of the device. +.Sh SEE ALSO +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/device_printf.9 b/static/freebsd/man9/device_printf.9 new file mode 100644 index 00000000..ee84feab --- /dev/null +++ b/static/freebsd/man9/device_printf.9 @@ -0,0 +1,55 @@ +.\" +.\" Copyright (c) 2003 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 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 21, 2003 +.Dt DEVICE_PRINTF 9 +.Os +.Sh NAME +.Nm device_printf +.Nd formatted output conversion +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn device_printf "device_t dev" "const char *fmt" ... +.Sh DESCRIPTION +The +.Fn device_printf +function is a convenience interface to the +.Xr printf 9 +function. +It outputs the name of the +.Fa dev +device, followed by a colon and a space, and then what +.Xr printf 9 +would print if you passed +.Fa fmt +and the remaining arguments to it. +.Sh RETURN VALUES +The +.Fn device_printf +function returns the number of characters displayed. +.Sh SEE ALSO +.Xr printf 3 , +.Xr printf 9 diff --git a/static/freebsd/man9/device_probe_and_attach.9 b/static/freebsd/man9/device_probe_and_attach.9 new file mode 100644 index 00000000..0c438be3 --- /dev/null +++ b/static/freebsd/man9/device_probe_and_attach.9 @@ -0,0 +1,165 @@ +.\" -*- 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 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 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 +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 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 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 +.An Doug Rabson . diff --git a/static/freebsd/man9/device_quiet.9 b/static/freebsd/man9/device_quiet.9 new file mode 100644 index 00000000..c7e5aa82 --- /dev/null +++ b/static/freebsd/man9/device_quiet.9 @@ -0,0 +1,66 @@ +.\" -*- 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 September 12, 2016 +.Dt DEVICE_QUIET 9 +.Os +.Sh NAME +.Nm device_quiet , +.Nm device_verbose , +.Nm device_is_quiet +.Nd manipulate device quiet flag +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft void +.Fn device_quiet "device_t dev" +.Ft void +.Fn device_verbose "device_t dev" +.Ft int +.Fn device_is_quiet "device_t dev" +.Sh DESCRIPTION +Each device has a quiet flag associated with it. +A device is +verbose by default when it is created but may be quieted to prevent +printing of the device identification string during attach +and printing of a message during detach. +To quiet a device, call +.Fn device_quiet +during a device driver probe routine. +To re-enable probe messages, +call +.Fn device_verbose . +To test to see if a device is quieted, call +.Fn device_is_quiet . +.Pp +Devices are implicitly marked verbose after a driver detaches. +.Sh SEE ALSO +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/device_set_desc.9 b/static/freebsd/man9/device_set_desc.9 new file mode 100644 index 00000000..5037c90f --- /dev/null +++ b/static/freebsd/man9/device_set_desc.9 @@ -0,0 +1,67 @@ +.\" -*- 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 9, 2024 +.Dt DEVICE_SET_DESC 9 +.Os +.Sh NAME +.Nm device_set_desc , +.Nm device_set_descf , +.Nm device_set_desc_copy , +.Nm device_get_desc +.Nd access the description of a device +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft void +.Fn device_set_desc "device_t dev" "const char *desc" +.Ft void +.Fn device_set_descf "device_t dev" "const char *fmt" "..." +.Ft void +.Fn device_set_desc_copy "device_t dev" "const char *desc" +.Ft const char * +.Fn device_get_desc "device_t dev" +.Sh DESCRIPTION +Manipulate the verbose description of a device. +This description (if +present) is printed as part of the message when it is attached during +autoconfiguration. +The variation +.Fn device_set_desc_copy +is used to set the description if the string passed is a temporary +buffer which will be overwritten. +In this case, the system will copy +the string, otherwise the pointer passed will be used directly. +.Fn device_set_descf +is a printf-like version of +.Fn device_set_desc . +.Sh SEE ALSO +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/device_set_driver.9 b/static/freebsd/man9/device_set_driver.9 new file mode 100644 index 00000000..72ae19f0 --- /dev/null +++ b/static/freebsd/man9/device_set_driver.9 @@ -0,0 +1,47 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2003 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 April 21, 2003 +.Dt DEVICE_SET_DRIVER 9 +.Os +.Sh NAME +.Nm device_set_driver +.Nd "associate a specific driver with a device node in the tree" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft void +.Fn device_set_driver "device_t dev" "driver_t *driver" +.Sh DESCRIPTION +This function associates a specific driver with a given device node +in the tree. +It is typically used in +.Xr DEVICE_IDENTIFY 9 +functions to add devices to a bus that does not support doing so +automatically, such as the ISA bus. +.Sh SEE ALSO +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An M. Warner Losh . diff --git a/static/freebsd/man9/device_set_flags.9 b/static/freebsd/man9/device_set_flags.9 new file mode 100644 index 00000000..4f35a117 --- /dev/null +++ b/static/freebsd/man9/device_set_flags.9 @@ -0,0 +1,54 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1999 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 September 6, 1999 +.Dt DEVICE_GET_FLAGS 9 +.Os +.Sh NAME +.Nm device_set_flags , +.Nm device_get_flags +.Nd manipulate driver flags +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft void +.Fn device_set_flags "device_t dev" "uint32_t flags" +.Ft uint32_t +.Fn device_get_flags "device_t dev" +.Sh DESCRIPTION +Each device supports a set of driver-dependent flags which are often +used to control device behaviour. +These flags are read by calling +.Fn device_get_flags +and written by calling +.Fn device_set_flags . +.Sh SEE ALSO +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/devstat.9 b/static/freebsd/man9/devstat.9 new file mode 100644 index 00000000..3682ad02 --- /dev/null +++ b/static/freebsd/man9/devstat.9 @@ -0,0 +1,548 @@ +.\" +.\" Copyright (c) 1998, 1999 Kenneth D. Merry. +.\" 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. 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 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 15, 2020 +.Dt DEVSTAT 9 +.Os +.Sh NAME +.Nm devstat , +.Nm devstat_end_transaction , +.Nm devstat_end_transaction_bio , +.Nm devstat_end_transaction_bio_bt , +.Nm devstat_new_entry , +.Nm devstat_remove_entry , +.Nm devstat_start_transaction , +.Nm devstat_start_transaction_bio +.Nd kernel interface for keeping device statistics +.Sh SYNOPSIS +.In sys/devicestat.h +.Ft struct devstat * +.Fo devstat_new_entry +.Fa "const void *dev_name" +.Fa "int unit_number" +.Fa "uint32_t block_size" +.Fa "devstat_support_flags flags" +.Fa "devstat_type_flags device_type" +.Fa "devstat_priority priority" +.Fc +.Ft void +.Fn devstat_remove_entry "struct devstat *ds" +.Ft void +.Fo devstat_start_transaction +.Fa "struct devstat *ds" +.Fa "const struct bintime *now" +.Fc +.Ft void +.Fo devstat_start_transaction_bio +.Fa "struct devstat *ds" +.Fa "struct bio *bp" +.Fc +.Ft void +.Fo devstat_end_transaction +.Fa "struct devstat *ds" +.Fa "uint32_t bytes" +.Fa "devstat_tag_type tag_type" +.Fa "devstat_trans_flags flags" +.Fa "const struct bintime *now" +.Fa "const struct bintime *then" +.Fc +.Ft void +.Fo devstat_end_transaction_bio +.Fa "struct devstat *ds" +.Fa "const struct bio *bp" +.Fc +.Ft void +.Fo devstat_end_transaction_bio_bt +.Fa "struct devstat *ds" +.Fa "const struct bio *bp" +.Fa "const struct bintime *now" +.Fc +.Sh DESCRIPTION +The devstat subsystem is an interface for recording device +statistics, as its name implies. +The idea is to keep reasonably detailed +statistics while utilizing a minimum amount of CPU time to record them. +Thus, no statistical calculations are actually performed in the kernel +portion of the +.Nm +code. +Instead, that is left for user programs to handle. +.Pp +The historical and antiquated +.Nm +model assumed a single active IO operation per device, which is not accurate +for most disk-like drivers in the 2000s and beyond. +New consumers of the interface should almost certainly use only the "bio" +variants of the start and end transacation routines. +.Pp +.Fn devstat_new_entry +allocates and initializes +.Va devstat +structure and returns a pointer to it. +.Fn devstat_new_entry +takes several arguments: +.Bl -tag -width device_type +.It dev_name +The device name, e.g., da, cd, sa. +.It unit_number +Device unit number. +.It block_size +Block size of the device, if supported. +If the device does not support a +block size, or if the blocksize is unknown at the time the device is added +to the +.Nm +list, it should be set to 0. +.It flags +Flags indicating operations supported or not supported by the device. +See below for details. +.It device_type +The device type. +This is broken into three sections: base device type +(e.g., direct access, CDROM, sequential access), interface type (IDE, SCSI +or other) and a pass-through flag to indicate pas-through devices. +See below for a complete list of types. +.It priority +The device priority. +The priority is used to determine how devices are +sorted within +.Nm devstat Ns 's +list of devices. +Devices are sorted first by priority (highest to lowest), +and then by attach order. +See below for a complete list of available +priorities. +.El +.Pp +.Fn devstat_remove_entry +removes a device from the +.Nm +subsystem. +It takes the devstat structure for the device in question as +an argument. +The +.Nm +generation number is incremented and the number of devices is decremented. +.Pp +.Fn devstat_start_transaction +registers the start of a transaction with the +.Nm +subsystem. +Optionally, if the caller already has a +.Fn binuptime +value available, it may be passed in +.Fa *now . +Usually the caller can just pass +.Dv NULL +for +.Fa now , +and the routine will gather the current +.Fn binuptime +itself. +The busy count is incremented with each transaction start. +When a device goes from idle to busy, the system uptime is recorded in the +.Va busy_from +field of the +.Va devstat +structure. +.Pp +.Fn devstat_start_transaction_bio +records the +.Fn binuptime +in the provided bio's +.Fa bio_t0 +and then invokes +.Fn devstat_start_transaction . +.Pp +.Fn devstat_end_transaction +registers the end of a transaction with the +.Nm +subsystem. +It takes six arguments: +.Bl -tag -width tag_type +.It ds +The +.Va devstat +structure for the device in question. +.It bytes +The number of bytes transferred in this transaction. +.It tag_type +Transaction tag type. +See below for tag types. +.It flags +Transaction flags indicating whether the transaction was a read, write, or +whether no data was transferred. +.It now +The +.Fn binuptime +at the end of the transaction, or +.Dv NULL . +.It then +The +.Fn binuptime +at the beginning of the transaction, or +.Dv NULL . +.El +.Pp +If +.Fa now +is +.Dv NULL , +it collects the current time from +.Fn binuptime . +If +.Fa then +is +.Dv NULL , +the operation is not tracked in the +.Va devstat +.Fa duration +table. +.Pp +.Fn devstat_end_transaction_bio +is a thin wrapper for +.Fn devstat_end_transaction_bio_bt +with a +.Dv NULL +.Fa now +parameter. +.Pp +.Fn devstat_end_transaction_bio_bt +is a wrapper for +.Fn devstat_end_transaction +which pulls all needed information from a +.Va "struct bio" +prepared by +.Fn devstat_start_transaction_bio . +The bio must be ready for +.Fn biodone +(i.e., +.Fa bio_bcount +and +.Fa bio_resid +must be correctly initialized). +.Pp +The +.Va devstat +structure is composed of the following fields: +.Bl -tag -width dev_creation_time +.It sequence0 , +.It sequence1 +An implementation detail used to gather consistent snapshots of device +statistics. +.It start_count +Number of operations started. +.It end_count +Number of operations completed. +The +.Dq busy_count +can be calculated by subtracting +.Fa end_count +from +.Fa start_count . +.Fa ( sequence0 +and +.Fa sequence1 +are used to get a consistent snapshot.) +This is the current number of outstanding transactions for the device. +This should never go below zero, and on an idle device it should be zero. +If either one of these conditions is not true, it indicates a problem. +.Pp +There should be one and only one +transaction start event and one transaction end event for each transaction. +.It dev_links +Each +.Va devstat +structure is placed in a linked list when it is registered. +The +.Va dev_links +field contains a pointer to the next entry in the list of +.Va devstat +structures. +.It device_number +The device number is a unique identifier for each device. +The device +number is incremented for each new device that is registered. +The device +number is currently only a 32-bit integer, but it could be enlarged if +someone has a system with more than four billion device arrival events. +.It device_name +The device name is a text string given by the registering driver to +identify itself. +(e.g., +.Dq da , +.Dq cd , +.Dq sa , +etc.) +.It unit_number +The unit number identifies the particular instance of the peripheral driver +in question. +.It bytes[4] +This array contains the number of bytes that have been read (index +.Dv DEVSTAT_READ ) , +written (index +.Dv DEVSTAT_WRITE ) , +freed or erased (index +.Dv DEVSTAT_FREE ) , +or other (index +.Dv DEVSTAT_NO_DATA ) . +All values are unsigned 64-bit integers. +.It operations[4] +This array contains the number of operations of a given type that have been +performed. +The indices are identical to those for +.Fa bytes +above. +.Dv DEVSTAT_NO_DATA +or "other" represents the number of transactions to the device which are +neither reads, writes, nor frees. +For instance, +.Tn SCSI +drivers often send a test unit ready command to +.Tn SCSI +devices. +The test unit ready command does not read or write any data. +It merely causes the device to return its status. +.It duration[4] +This array contains the total bintime corresponding to completed operations of +a given type. +The indices are identical to those for +.Fa bytes +above. +(Operations that complete using the historical +.Fn devstat_end_transaction +API and do not provide a non-NULL +.Fa then +are not accounted for.) +.It busy_time +This is the amount of time that the device busy count has been greater than +zero. +This is only updated when the busy count returns to zero. +.It creation_time +This is the time, as reported by +.Fn getmicrotime +that the device was registered. +.It block_size +This is the block size of the device, if the device has a block size. +.It tag_types +This is an array of counters to record the number of various tag types that +are sent to a device. +See below for a list of tag types. +.It busy_from +If the device is not busy, this was the time that a transaction last completed. +If the device is busy, this the most recent of either the time that the device +became busy, or the time that the last transaction completed. +.It flags +These flags indicate which statistics measurements are supported by a +particular device. +These flags are primarily intended to serve as an aid +to userland programs that decipher the statistics. +.It device_type +This is the device type. +It consists of three parts: the device type +(e.g., direct access, CDROM, sequential access, etc.), the interface (IDE, +SCSI or other) and whether or not the device in question is a pass-through +driver. +See below for a complete list of device types. +.It priority +This is the priority. +This is the first parameter used to determine where +to insert a device in the +.Nm +list. +The second parameter is attach order. +See below for a list of available priorities. +.It id +Identification for GEOM nodes. +.El +.Pp +Each device is given a device type. +Pass-through devices have the same underlying device type and interface as the +device they provide an interface for, but they also have the pass-through flag +set. +The base device types are identical to the +.Tn SCSI +device type numbers, so with +.Tn SCSI +peripherals, the device type returned from an inquiry is usually ORed with the +.Tn SCSI +interface type and the pass-through flag if appropriate. +The device type +flags are as follows: +.Bd -literal -offset indent +typedef enum { + DEVSTAT_TYPE_DIRECT = 0x000, + DEVSTAT_TYPE_SEQUENTIAL = 0x001, + DEVSTAT_TYPE_PRINTER = 0x002, + DEVSTAT_TYPE_PROCESSOR = 0x003, + DEVSTAT_TYPE_WORM = 0x004, + DEVSTAT_TYPE_CDROM = 0x005, + DEVSTAT_TYPE_SCANNER = 0x006, + DEVSTAT_TYPE_OPTICAL = 0x007, + DEVSTAT_TYPE_CHANGER = 0x008, + DEVSTAT_TYPE_COMM = 0x009, + DEVSTAT_TYPE_ASC0 = 0x00a, + DEVSTAT_TYPE_ASC1 = 0x00b, + DEVSTAT_TYPE_STORARRAY = 0x00c, + DEVSTAT_TYPE_ENCLOSURE = 0x00d, + DEVSTAT_TYPE_FLOPPY = 0x00e, + DEVSTAT_TYPE_MASK = 0x00f, + DEVSTAT_TYPE_IF_SCSI = 0x010, + DEVSTAT_TYPE_IF_IDE = 0x020, + DEVSTAT_TYPE_IF_OTHER = 0x030, + DEVSTAT_TYPE_IF_NVME = 0x040, + DEVSTAT_TYPE_IF_MASK = 0x0f0, + DEVSTAT_TYPE_PASS = 0x100 +} devstat_type_flags; +.Ed +.Pp +Devices have a priority associated with them, which controls roughly where +they are placed in the +.Nm +list. +The priorities are as follows: +.Bd -literal -offset indent +typedef enum { + DEVSTAT_PRIORITY_MIN = 0x000, + DEVSTAT_PRIORITY_OTHER = 0x020, + DEVSTAT_PRIORITY_PASS = 0x030, + DEVSTAT_PRIORITY_FD = 0x040, + DEVSTAT_PRIORITY_WFD = 0x050, + DEVSTAT_PRIORITY_TAPE = 0x060, + DEVSTAT_PRIORITY_CD = 0x090, + DEVSTAT_PRIORITY_DISK = 0x110, + DEVSTAT_PRIORITY_ARRAY = 0x120, + DEVSTAT_PRIORITY_MAX = 0xfff +} devstat_priority; +.Ed +.Pp +Each device has associated with it flags to indicate what operations are +supported or not supported. +The +.Va devstat_support_flags +values are as follows: +.Bl -tag -width DEVSTAT_NO_ORDERED_TAGS +.It DEVSTAT_ALL_SUPPORTED +Every statistic type is supported by the device. +.It DEVSTAT_NO_BLOCKSIZE +This device does not have a blocksize. +.It DEVSTAT_NO_ORDERED_TAGS +This device does not support ordered tags. +.It DEVSTAT_BS_UNAVAILABLE +This device supports a blocksize, but it is currently unavailable. +This +flag is most often used with removable media drives. +.El +.Pp +Transactions to a device fall into one of three categories, which are +represented in the +.Va flags +passed into +.Fn devstat_end_transaction . +The transaction types are as follows: +.Bd -literal -offset indent +typedef enum { + DEVSTAT_NO_DATA = 0x00, + DEVSTAT_READ = 0x01, + DEVSTAT_WRITE = 0x02, + DEVSTAT_FREE = 0x03 +} devstat_trans_flags; +#define DEVSTAT_N_TRANS_FLAGS 4 +.Ed +.Pp +DEVSTAT_NO_DATA is a type of transactions to the device which are neither +reads or writes. +For instance, +.Tn SCSI +drivers often send a test unit ready command to +.Tn SCSI +devices. +The test unit ready command does not read or write any data. +It merely causes the device to return its status. +.Pp +There are four possible values for the +.Va tag_type +argument to +.Fn devstat_end_transaction : +.Bl -tag -width DEVSTAT_TAG_ORDERED +.It DEVSTAT_TAG_SIMPLE +The transaction had a simple tag. +.It DEVSTAT_TAG_HEAD +The transaction had a head of queue tag. +.It DEVSTAT_TAG_ORDERED +The transaction had an ordered tag. +.It DEVSTAT_TAG_NONE +The device does not support tags. +.El +.Pp +The tag type values correspond to the lower four bits of the +.Tn SCSI +tag definitions. +In CAM, for instance, the +.Va tag_action +from the CCB is ORed with 0xf to determine the tag type to pass in to +.Fn devstat_end_transaction . +.Pp +There is a macro, +.Dv DEVSTAT_VERSION +that is defined in +.In sys/devicestat.h . +This is the current version of the +.Nm +subsystem, and it should be incremented each time a change is made that +would require recompilation of userland programs that access +.Nm +statistics. +Userland programs use this version, via the +.Va kern.devstat.version +.Nm sysctl +variable to determine whether they are in sync with the kernel +.Nm +structures. +.Sh SEE ALSO +.Xr systat 1 , +.Xr devstat 3 , +.Xr iostat 8 , +.Xr rpc.rstatd 8 , +.Xr vmstat 8 +.Sh HISTORY +The +.Nm +statistics system appeared in +.Fx 3.0 . +.Sh AUTHORS +.An Kenneth Merry Aq Mt ken@FreeBSD.org +.Sh BUGS +There may be a need for +.Fn spl +protection around some of the +.Nm +list manipulation code to ensure, for example, that the list of devices +is not changed while someone is fetching the +.Va kern.devstat.all +.Nm sysctl +variable. diff --git a/static/freebsd/man9/devtoname.9 b/static/freebsd/man9/devtoname.9 new file mode 100644 index 00000000..b62f08ef --- /dev/null +++ b/static/freebsd/man9/devtoname.9 @@ -0,0 +1,46 @@ +.\" Copyright (c) 1999 Chris Costello +.\" 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 February 10, 2012 +.Dt DEVTONAME 9 +.Os +.Sh NAME +.Nm devtoname +.Nd "converts character device into a string indicating the device name" +.Sh SYNOPSIS +.In sys/param.h +.In sys/conf.h +.Ft const char * +.Fn devtoname "struct cdev *dev" +.Sh DESCRIPTION +The +.Fn devtoname +function returns a pointer to the name of the device passed to it. +The name is whatever was set to it in +.Fn make_dev . +.Sh HISTORY +The +.Fn devtoname +interface first appeared in +.Fx 4.0 diff --git a/static/freebsd/man9/disk.9 b/static/freebsd/man9/disk.9 new file mode 100644 index 00000000..41436427 --- /dev/null +++ b/static/freebsd/man9/disk.9 @@ -0,0 +1,259 @@ +.\" +.\" Copyright (c) 2003 Robert N. M. Watson +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 30, 2020 +.Dt DISK 9 +.Os +.Sh NAME +.Nm disk +.Nd kernel disk storage API +.Sh SYNOPSIS +.In geom/geom_disk.h +.Ft struct disk * +.Fn disk_alloc void +.Ft void +.Fn disk_create "struct disk *disk" "int version" +.Ft void +.Fn disk_gone "struct disk *disk" +.Ft void +.Fn disk_destroy "struct disk *disk" +.Ft int +.Fn disk_resize "struct disk *disk" "int flags" +.Ft void +.Fn disk_add_alias "struct disk *disk" "const char *alias" +.Sh DESCRIPTION +The disk storage API permits kernel device drivers providing access to +disk-like storage devices to advertise the device to other kernel +components, including +.Xr GEOM 4 +and +.Xr devfs 4 . +.Pp +Each disk device is described by a +.Vt "struct disk" +structure, which contains a variety of parameters for the disk device, +function pointers for various methods that may be performed on the device, +as well as private data storage for the device driver. +In addition, some fields are reserved for use by GEOM in managing access +to the device and its statistics. +.Pp +GEOM has the ownership of +.Vt "struct disk" , +and drivers must allocate storage for it with the +.Fn disk_alloc +function, +fill in the fields and call +.Fn disk_create +when the device is ready to service requests. +.Fn disk_add_alias +adds an alias for the disk and must be called before +.Fn disk_create , +but may be called multiple times. +For each alias added, a device node will be created with +.Xr make_dev_alias 9 +in the same way primary device nodes are created with +.Xr make_dev 9 +for +.Va d_name +and +.Va d_unit . +Care should be taken to ensure that only one driver creates aliases +for any given name. +.Fn disk_resize +can be called by the driver after modifying +.Va d_mediasize +to notify GEOM about the disk capacity change. +The +.Fa flags +field should be set to either M_WAITOK, or M_NOWAIT. +.Fn disk_gone +orphans all of the providers associated with the drive, setting an error +condition of ENXIO in each one. +In addition, it prevents a re-taste on last close for writing if an error +condition has been set in the provider. +After calling +.Fn disk_destroy , +the device driver is not allowed to access the contents of +.Vt "struct disk" +anymore. +.Pp +The +.Fn disk_create +function +takes a second parameter, +.Fa version , +which must always be passed +.Dv DISK_VERSION . +If GEOM detects that the driver is compiled against an unsupported version, +it will ignore the device and print a warning on the console. +.Ss Descriptive Fields +The following fields identify the disk device described by the structure +instance, and must be filled in prior to submitting the structure to +.Fn disk_create +and may not be subsequently changed: +.Bl -tag -width indent +.It Vt u_int Va d_flags +Optional flags indicating to the storage framework what optional features +or descriptions the storage device driver supports. +Currently supported flags are +.Dv DISKFLAG_OPEN +(maintained by storage framework), +.Dv DISKFLAG_CANDELETE +(maintained by device driver), +and +.Dv DISKFLAG_CANFLUSHCACHE +(maintained by device driver). +.It Vt "const char *" Va d_name +Holds the name of the storage device class, e.g., +.Dq Li ahd . +This value typically uniquely identifies a particular driver device, +and must not conflict with devices serviced by other device drivers. +.It Vt u_int Va d_unit +Holds the instance of the storage device class, e.g., +.Dq Li 4 . +This namespace is managed by the device driver, and assignment of unit +numbers might be a property of probe order, or in some cases topology. +Together, the +.Va d_name +and +.Va d_unit +values will uniquely identify a disk storage device. +.El +.Ss Disk Device Methods +The following fields identify various disk device methods, if implemented: +.Bl -tag -width indent +.It Vt "disk_open_t *" Va d_open +Optional: invoked when the disk device is opened. +If no method is provided, open will always succeed. +.It Vt "disk_close_t *" Va d_close +Optional: invoked when the disk device is closed. +Although an error code may be returned, the call should always terminate +any state setup by the corresponding open method call. +.It Vt "disk_strategy_t *" Va d_strategy +Mandatory: invoked when a new +.Vt "struct bio" +is to be initiated on the disk device. +.It Vt "disk_ioctl_t *" Va d_ioctl +Optional: invoked when an I/O control operation is initiated on the disk device. +Please note that for security reasons these operations should not +be able to affect other devices than the one on which they are performed. +.It Vt "dumper_t *" Va d_dump +Optional: if configured with +.Xr dumpon 8 , +this function is invoked from a very restricted system state after a +kernel panic to record a copy of the system RAM to the disk. +.It Vt "disk_getattr_t *" Va d_getattr +Optional: if this method is provided, it gives the disk driver the +opportunity to override the default GEOM response to BIO_GETATTR requests. +This function should return -1 if the attribute is not handled, 0 if the +attribute is handled, or an errno to be passed to +.Fn g_io_deliver . +.It Vt "disk_gone_t *" Va d_gone +Optional: if this method is provided, it will be called after +.Fn disk_gone +is called, once GEOM has finished its cleanup process. +Once this callback is called, it is safe for the disk driver to free all of +its resources, as it will not be receiving further calls from GEOM. +.El +.Ss Mandatory Media Properties +The following fields identify the size and granularity of the disk device. +These fields must stay stable from return of the drivers open method until +the close method is called, but it is perfectly legal to modify them in +the open method before returning. +.Bl -tag -width indent +.It Vt u_int Va d_sectorsize +The sector size of the disk device in bytes. +.It Vt off_t Va d_mediasize +The size of the disk device in bytes. +.It Vt u_int Va d_maxsize +The maximum supported size in bytes of an I/O request. +Requests larger than this size will be chopped up by GEOM. +.El +.Ss Optional Media Properties +These optional fields can provide extra information about the disk +device. +Do not initialize these fields if the field/concept does not apply. +These fields must stay stable from return of the drivers open method until +the close method is called, but it is perfectly legal to modify them in +the open method before returning. +.Bl -tag -width indent +.It Vt u_int Va d_fwsectors , Vt u_int Va d_fwheads +The number of sectors and heads advertised on the disk device by the +firmware or BIOS. +These values are almost universally bogus, but on some architectures +necessary for the correct calculation of disk partitioning. +.It Vt u_int Va d_stripeoffset , Vt u_int Va d_stripesize +These two fields can be used to describe the width and location of +natural performance boundaries for most disk technologies. +Please see +.Pa src/sys/geom/notes +for details. +.It Vt char Va d_ident[DISK_IDENT_SIZE] +This field can and should be used to store disk's serial number if the +d_getattr method described above isn't implemented, or if it does not +support the GEOM::ident attribute. +.It Vt char Va d_descr[DISK_IDENT_SIZE] +This field can be used to store the disk vendor and product description. +.It Vt uint16_t Va d_hba_vendor +This field can be used to store the PCI vendor ID for the HBA connected to +the disk. +.It Vt uint16_t Va d_hba_device +This field can be used to store the PCI device ID for the HBA connected to +the disk. +.It Vt uint16_t Va d_hba_subvendor +This field can be used to store the PCI subvendor ID for the HBA connected to +the disk. +.It Vt uint16_t Va d_hba_subdevice +This field can be used to store the PCI subdevice ID for the HBA connected to +the disk. +.El +.Ss Driver Private Data +This field may be used by the device driver to store a pointer to +private data to implement the disk service. +.Bl -tag -width indent +.It Vt "void *" Va d_drv1 +Private data pointer. +Typically used to store a pointer to the drivers +.Vt softc +structure for this disk device. +.El +.Sh SEE ALSO +.Xr devfs 4 , +.Xr GEOM 4 +.Sh HISTORY +The +.Nm kernel disk storage API +first appeared in +.Fx 4.9 . +.Sh AUTHORS +This manual page was written by +.An Robert Watson . +.Sh BUGS +Disk aliases are not a general purpose aliasing mechanism, but are +intended only to ease the transition from one name to another. +They can be used to ensure that nvd0 and nda0 are the same thing. +They cannot be used to implement the diskX concept from macOS. diff --git a/static/freebsd/man9/dnv.9 b/static/freebsd/man9/dnv.9 new file mode 100644 index 00000000..16f603df --- /dev/null +++ b/static/freebsd/man9/dnv.9 @@ -0,0 +1,120 @@ +.\" +.\" Copyright (c) 2016 Adam Starak +.\" 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 January 3, 2025 +.Dt DNV 9 +.Os +.Sh NAME +.Nm dnvlist_get , +.Nm dnvlist_take +.Nd "API for getting name/value pairs with a default value" +.Sh LIBRARY +.Lb libnv +.Sh SYNOPSIS +.In sys/dnv.h +.Ft bool +.Fn dnvlist_get_bool "const nvlist_t *nvl" "const char *name" "bool defval" +.Ft uint64_t +.Fn dnvlist_get_number "const nvlist_t *nvl" "const char *name" "uint64_t defval" +.Ft char * +.Fn dnvlist_get_string "const nvlist_t *nvl" "const char *name" "const char *defval" +.Ft nvlist_t * +.Fn dnvlist_get_nvlist "const nvlist_t *nvl" "const char *name" "nvlist_t *defval" +.Ft int +.Fn dnvlist_get_descriptor "const nvlist_t *nvl" "const char *name" "int defval" +.Ft void * +.Fn dnvlist_get_binary "const nvlist_t *nvl" "const char *name" "size_t *sizep" "void *defval" "size_t defsize" +.Ft bool +.Fn dnvlist_take_bool "const nvlist_t *nvl" "const char *name" "bool defval" +.Ft uint64_t +.Fn dnvlist_take_number "const nvlist_t *nvl" "const char *name" "uint64_t defval" +.Ft char * +.Fn dnvlist_take_string "const nvlist_t *nvl" "const char *name" "const char *defval" +.Ft nvlist_t * +.Fn dnvlist_take_nvlist "const nvlist_t *nvl" "const char *name" "nvlist_t *defval" +.Ft int +.Fn dnvlist_take_descriptor "const nvlist_t *nvl" "const char *name" "int defval" +.Ft void * +.Fn dnvlist_take_binary "const nvlist_t *nvl" "const char *name" "size_t *sizep" "void *defval" "size_t defsize" +.Sh DESCRIPTION +The +.Nm libnv +library permits easy management of name/value pairs and can send and receive +them over sockets. +For more information, see +.Xr nv 9 . +.Pp +The +.Nm dnvlist_get +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 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 +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 +responsible for freeing returned memory with +.Fn free 3 . +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 +.Fn close 2 . +.Sh SEE ALSO +.Xr close 2 , +.Xr free 3 , +.Xr nv 9 +.Sh HISTORY +The +.Nm dnv +API appeared in +.Fx 11.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm dnv +API was implemented by +.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net +under sponsorship from the FreeBSD Foundation. +This manual page was written by +.An Adam Starak Aq Mt starak.adam@gmail.com diff --git a/static/freebsd/man9/domain.9 b/static/freebsd/man9/domain.9 new file mode 100644 index 00000000..d7e743ea --- /dev/null +++ b/static/freebsd/man9/domain.9 @@ -0,0 +1,227 @@ +.\" +.\" Copyright (C) 2001 Chad David . All rights reserved. +.\" Copyright (C) 2022 Gleb Smirnoff +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 September 14, 2022 +.Dt DOMAIN 9 +.Os +.Sh NAME +.Nm domain , +.Nm protosw +.Nd "programming interface for kernel socket implementation" +.Sh SYNOPSIS +.In sys/param.h +.In sys/kernel.h +.In sys/protosw.h +.In sys/domain.h +.Ft void +.Fn domain_add "struct domain *dom" +.Ft void +.Fn domain_remove "struct domain *dom" +.Ft void +.Fn DOMAIN_SET "domain" +.Ft int +.Fn protosw_register "struct domain *dom" "struct protosw *pr" +.Ft int +.Fn protosw_unregister "struct protosw *pr" +.Sh DESCRIPTION +The +.Nm +subsystem allows implementation of communication protocols that are exposed to +the userland via the +.Xr socket 2 +API. +When an application performs a +.Fn socket "domain" "type" "protocol" +syscall, the kernel searches for a +.Nm +matching the +.Ar domain +argument, then within this domain, searches for a protocol +matching +.Ar type . +If the third argument, +.Ar protocol , +is not +.Dv 0 , +that value must also match. +The structure found must implement certain methods, so that +.Xr socket 2 +API works for this particular kind of a socket. +.Pp +A minimal +.Nm +structure implementing a domain shall be initialized with sparse C99 +initializer and has public fields as follows: +.Bd -literal +struct domain { + /* + * Mandatory fields. + */ + int dom_family; /* PF_xxx, first argument of socket(2) */ + char *dom_name; /* text name of the domain */ + u_int dom_nprotosw; /* length of dom_protosw[] */ + /* + * Following methods are optional. + */ + int (*dom_probe)(void); /* check for support */ + struct rib_head *(*dom_rtattach)(uint32_t); /* init route table */ + void (*dom_rtdetach)(struct rib_head *); /* clean up table */ + void *(*dom_ifattach)(struct ifnet *); /* interface attach */ + void (*dom_ifdetach)(struct ifnet *, void *);/* & detach callbacks */ + int (*dom_ifmtu)(struct ifnet *); /* mtu change */ + /* + * Mandatory variable size array of pointers to protosw structs. + */ + struct protosw *dom_protosw[]; +}; +.Ed +.Pp +Each domain contains the +.Va dom_protosw +array of protocol switch structures +.Pq Vt "struct protosw *" , +one for each socket type supported. +The array may have +.Dv NULL +spacers for loadable protocols. +Sparse C99 initializers shall be used to initialize +.Nm protosw +structures. +The structure has mandatory field +.Va pr_type +and mandatory +.Va pr_attach +method. +The rest of the methods are optional, but a meaningful protocol should +implement some. +.Bd -literal +struct protosw { + short pr_type; /* second argument of socket(2) */ + short pr_protocol; /* third argument of socket(2) or 0 */ + short pr_flags; /* see protosw.h */ + pr_soreceive_t *pr_soreceive; /* recv(2) */ + pr_rcvd_t *pr_rcvd; /* soreceive_generic() if PR_WANTRCV */ + pr_sosend_t *pr_sosend; /* send(2) */ + pr_send_t *pr_send; /* send(2) via sosend_generic() */ + pr_ready_t *pr_ready; /* sendfile/ktls readyness */ + pr_sopoll_t *pr_sopoll; /* poll(2) */ + pr_attach_t *pr_attach; /* creation: socreate(), sonewconn() */ + pr_detach_t *pr_detach; /* destruction: sofree() */ + pr_connect_t *pr_connect; /* connect(2) */ + pr_disconnect_t *pr_disconnect; /* sodisconnect() */ + pr_close_t *pr_close; /* close(2) */ + pr_shutdown_t *pr_shutdown; /* shutdown(2) */ + pr_abort_t *pr_abort; /* abrupt tear down: soabort() */ + pr_aio_queue_t *pr_aio_queue; /* aio(9) */ + pr_bind_t *pr_bind; /* bind(2) */ + pr_bindat_t *pr_bindat; /* bindat(2) */ + pr_listen_t *pr_listen; /* listen(2) */ + pr_accept_t *pr_accept; /* accept(2) */ + pr_connectat_t *pr_connectat; /* connectat(2) */ + pr_connect2_t *pr_connect2; /* socketpair(2) */ + pr_control_t *pr_control; /* ioctl(2) */ + pr_rcvoob_t *pr_rcvoob; /* soreceive_rcvoob() */ + pr_ctloutput_t *pr_ctloutput; /* control output (from above) */ + pr_peeraddr_t *pr_peeraddr; /* getpeername(2) */ + pr_sockaddr_t *pr_sockaddr; /* getsockname(2) */ + pr_sense_t *pr_sense; /* stat(2) */ +}; +.Ed +.Pp +The following functions handle the registration of new domains and protocols. +.Pp +.Fn domain_add +adds a new protocol domain to the system. +In most cases +.Fn domain_add +is not called directly, instead +.Fn DOMAIN_SET +is used, which is a wrapper around +.Fn SYSINIT +macro. +If the new domain has defined a +.Va dom_probe +routine, it is called first in +.Fn domain_add +to determine if the domain should be supported on the current system. +If the probe routine returns a non-0 value, then the domain will not be added. +Once a domain is added it cannot be completely unloaded. +This is because there is +no reference counting system in place to determine if there are any +active references from sockets within that domain. +However, the experimental +.Fn domain_remove +exists, and unloadable domains may be supported in the future. +.Pp +.Fn protosw_register +dynamically adds a protocol to a domain, if the latter +has an empty slot in its +.Va dom_protosw . +Dynamically added protocol can later be unloaded with +.Fn protosw_unregister . +.Sh RETURN VALUES +The +.Fn domain_add +never fails, but it may not add a domain if its +.Va dom_probe +fails. +.Pp +The +.Fn protosw_register +function may fail if: +.Bl -tag -width Er +.It Bq Er EEXIST +A protocol with the same value of +.Va pr_type +and +.Va pr_protocol +already exists in the domain. +.It Bq Er ENOMEM +The domain doesn't have any NULL slots in its +.Va dom_protosw . +.El +.Sh SEE ALSO +.Xr socket 2 , +.Xr SYSINIT 9 +.Sh HISTORY +The +.Nm +subsystem first appeared in +.Bx 4.3 +as the part of the very first +.Xr socket 2 +API implementation. +.Pp +The +.Nm +subsystem and this manual page were significantly rewritten in +.Fx 14 . +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca +and +.An Gleb Smirnoff Aq Mt glebius@FreeBSD.org . diff --git a/static/freebsd/man9/domainset.9 b/static/freebsd/man9/domainset.9 new file mode 100644 index 00000000..702c9f83 --- /dev/null +++ b/static/freebsd/man9/domainset.9 @@ -0,0 +1,179 @@ +.\" Copyright (c) 2018 Jeffrey Roberson +.\" 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 June 24, 2025 +.Dt DOMAINSET 9 +.Os +.Sh NAME +.Nm domainset(9) +.Nd domainset functions and operation +.Sh SYNOPSIS +.In sys/_domainset.h +.In sys/domainset.h +.\" +.Bd -literal -offset indent +struct domainset { + domainset_t ds_mask; + uint16_t ds_policy; + domainid_t ds_prefer; + ... +}; +.Ed +.Pp +.Ft struct domainset * +.Fn DOMAINSET_FIXED domain +.Ft struct domainset * +.Fn DOMAINSET_FT +.Ft struct domainset * +.Fn DOMAINSET_IL +.Ft struct domainset * +.Fn DOMAINSET_RR +.Ft struct domainset * +.Fn DOMAINSET_PREF domain +.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 +.Nm +API provides memory domain allocation policy for NUMA machines. +Each +.Vt domainset +contains a bitmask of allowed domains, an integer policy, and an optional +preferred domain. +Together, these specify a search order for memory allocations as well as +the ability to restrict threads and objects to a subset of available +memory domains for system partitioning and resource management. +.Pp +Every thread in the system and optionally every +.Vt vm_object_t , +which is used to represent files and other memory sources, has +a reference to a +.Vt struct domainset . +The domainset associated with the object is consulted first and the system +falls back to the thread policy if none exists. +.Pp +The allocation policy has the following possible values: +.Bl -tag -width "foo" +.It Dv DOMAINSET_POLICY_ROUNDROBIN +Memory is allocated from each domain in the mask in a round-robin fashion. +This distributes bandwidth evenly among available domains. +This policy can specify a single domain for a fixed allocation. +.It Dv DOMAINSET_POLICY_FIRSTTOUCH +Memory is allocated from the node that it is first accessed on. +Allocation falls back to round-robin if the current domain is not in the +allowed set or is out of memory. +This policy optimizes for locality but may give pessimal results if the +memory is accessed from many CPUs that are not in the local domain. +.It Dv DOMAINSET_POLICY_PREFER +Memory is allocated from the node in the +.Vt prefer +member. +The preferred node must be set in the allowed mask. +If the preferred node is out of memory the allocation falls back to +round-robin among allowed sets. +.It Dv DOMAINSET_POLICY_INTERLEAVE +Memory is allocated in a striped fashion with multiple pages +allocated to each domain in the set according to the offset within +the object. +The strip width is object dependent and may be as large as a +super-page (2MB on amd64). +This gives good distribution among memory domains while keeping system +efficiency higher and is preferential to round-robin for general use. +.El +.Pp +The +.Fn DOMAINSET_FIXED , +.Fn DOMAINSET_FT , +.Fn DOMAINSET_IL , +.Fn DOMAINSET_RR +and +.Fn DOMAINSET_PREF +macros provide pointers to global pre-defined policies for use when the +desired policy is known at compile time. +.Fn DOMAINSET_FIXED +is a policy which only permits allocations from the specified domain. +.Fn DOMAINSET_FT +is a policy which attempts to allocate memory local to the current CPU, +falling back to a round-robin policy if the initial allocation fails. +.Fn DOMAINSET_IL +and +.Fn DOMAINSET_RR +provide round-robin selection among all domains in the system, corresponding +to the +.Dv DOMAINSET_POLICY_INTERLEAVE +and +.Dv DOMAINSET_POLICY_ROUNDROBIN +policies, respectively. +The +.Fn DOMAINSET_PREF +policies attempt allocation from the specified domain, but unlike +.Fn DOMAINSET_FIXED +will fall back to other domains to satisfy the request. +These policies should be used in preference to +.Fn DOMAINSET_FIXED +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 +valid domainset or NULL. +It is critical that consumers not use domainsets that have not been +returned by this function. +.Vt domainset +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 +.Xr cpuset 2 . +It is intended for use with +.Xr sysctl 9 . +.Sh SEE ALSO +.Xr cpuset 1 , +.Xr cpuset 2 , +.Xr cpuset_setdomain 2 , +.Xr bitset 9 +.Sh HISTORY +.In sys/domainset.h +first appeared in +.Fx 12.0 . diff --git a/static/freebsd/man9/dpcpu.9 b/static/freebsd/man9/dpcpu.9 new file mode 100644 index 00000000..6a19b8de --- /dev/null +++ b/static/freebsd/man9/dpcpu.9 @@ -0,0 +1,163 @@ +.\"- +.\" Copyright (c) 2017 Robert N. M. Watson +.\" 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 5, 2018 +.Dt DPCPU 9 +.Os +.Sh NAME +.Nm dpcpu +.Nd Kernel Dynamic Per-CPU Memory Allocator +.Sh SYNOPSIS +.In sys/pcpu.h +.Ss Per-CPU Variable Definition and Declaration +.Fn DPCPU_DEFINE "type" "name" +.Fn DPCPU_DEFINE_STATIC "type" "name" +.Fn DPCPU_DECLARE "type" "name" +.Ss Current CPU Accessor Functions +.Fn DPCPU_PTR "name" +.Fn DPCPU_GET "name" +.Fn DPCPU_SET "name" "value" +.Ss Named CPU Accessor Functions +.Fn DPCPU_ID_PTR "cpu" "name" +.Fn DPCPU_ID_GET "cpu" "name" +.Fn DPCPU_ID_SET "cpu" "name" "value" +.Sh DESCRIPTION +.Nm +instantiates one instance of a global variable with each CPU in the system. +Dynamically allocated per-CPU variables are defined using +.Fn DPCPU_DEFINE , +which defines a variable of name +.Ar name +and type +.Ar type . +Arbitrary C types may be used, including structures and arrays. +If no initialization is provided, then each per-CPU instance of the variable +will be zero-filled (i.e., as though allocated in BSS): +.Bd -literal -offset 1234 +DPCPU_DEFINE(int, foo_int); +.Ed +.Pp +Values may also be initialized statically with the definition, causing each +per-CPU instance to be initialized with the value: +.Bd -literal -offset 1234 +DPCPU_DEFINE(int, foo_int) = 1; +.Ed +.Pp +Values that can be defined as +.Dv static +must use +.Fn DPCPU_DEFINE_STATIC : +.Bd -literal -offset 1234 +DPCPU_DEFINE_STATIC(int, foo_int); +.Ed +.Pp +.Fn DPCPU_DECLARE +produces a declaration of the per-CPU variable suitable for use in header +files. +.Pp +The current CPU's variable instance can be accessed via +.Nm DPCPU_PTR +(which returns a pointer to the per-CPU instance), +.Nm DPCPU_GET +(which retrieves the value of the per-CPU instance), +and +.Nm DPCPU_SET +(which sets the value of the per-CPU instance). +.Pp +Instances of variables associated with specific CPUs can be accessed via the +.Nm DPCPU_ID_PTR , +.Nm DPCPU_ID_GET , +and +.Nm DPGPU_ID_SET +accessor functions, which accept an additional CPU ID argument, +.Ar cpu . +.Ss Synchronization +In addition to the ordinary synchronization concerns associated with global +variables, which may imply the use of +.Xr atomic 9 , +.Xr mutex 9 , +or other kernel synchronization primitives, it is further the case that +thread migration could dynamically change the instance of a variable being +accessed by a thread between operations. +This requires additional care when reasoning about and protecting per-CPU +variables. +.Pp +For example, it may be desirable to protect access using +.Xr critical_section 9 +to prevent both preemption and migration during use. +Alternatively, it may be desirable to cache the CPU ID at the start of a +sequence of accesses, using suitable synchronization to make non-atomic +sequences safe in the presence of migration. +.Bd -literal -offset 1234 +DPCPU_DEFINE_STATIC(int, foo_int); +DPCPU_DEFINE_STATIC(struct mutex, foo_lock); + +void +foo_int_increment(void) +{ + int cpu, value; + + /* Safe as atomic access. */ + atomic_add_int(DPCPU_PTR(foo_int), 1); + + /* + * Protect with a critical section, which prevents preemption + * and migration. However, access to instances from remote CPUs + * is not safe, as critical sections prevent concurrent access + * only from the current CPU. + */ + critical_enter(); + value = DPCPU_GET(foo_int); + value++; + DPCPU_SET(foo_int, value); + critical_exit(); + + /* + * Protect with a per-CPU mutex, tolerating migration, but + * potentially accessing the variable from multiple CPUs if + * migration occurs after reading curcpu. Remote access to a + * per-CPU variable is safe as long as the correct mutex is + * acquired. + */ + cpu = curcpu; + mtx_lock(DPCPU_ID_PTR(cpu, foo_lock)); + value = DPCPU_ID_GET(cpu, foo_int); + value++; + DPCPU_ID_SET(cpu, foo_int); + mtx_unlock(DPCPU_ID_PTR(cpu, foo_lock)); +} +.Ed +.Sh SEE ALSO +.Xr atomic 9 , +.Xr critical_enter 9 , +.Xr mutex 9 +.Sh HISTORY +.Nm +was first introduced by +.An Jeff Roberson +in +.Fx 8.0 . +This manual page was written by +.An Robert N. M. Watson . diff --git a/static/freebsd/man9/drbr.9 b/static/freebsd/man9/drbr.9 new file mode 100644 index 00000000..49c70bac --- /dev/null +++ b/static/freebsd/man9/drbr.9 @@ -0,0 +1,138 @@ +.\" Copyright (c) 2009 Bitgravity Inc +.\" Written by: Kip Macy +.\" 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 September 27, 2012 +.Dt DRBR 9 +.Os +.Sh NAME +.Nm drbr , +.Nm drbr_free , +.Nm drbr_enqueue , +.Nm drbr_dequeue , +.Nm drbr_dequeue_cond , +.Nm drbr_flush , +.Nm drbr_empty , +.Nm drbr_inuse +.Nd network driver interface to buf_ring +.Sh SYNOPSIS +.In sys/param.h +.In net/if.h +.In net/if_var.h +.Ft void +.Fn drbr_free "struct buf_ring *br" "struct malloc_type *type" +.Ft int +.Fn drbr_enqueue "struct ifnet *ifp" "struct buf_ring *br" "struct mbuf *m" +.Ft struct mbuf * +.Fn drbr_dequeue "struct ifnet *ifp" "struct buf_ring *br" +.Ft struct mbuf * +.Fn drbr_dequeue_cond "struct ifnet *ifp" "struct buf_ring *br" "int (*func) (struct mbuf *, void *)" "void *arg" +.Ft void +.Fn drbr_flush "struct ifnet *ifp" "struct buf_ring *br" +.Ft int +.Fn drbr_empty "struct ifnet *ifp" "struct buf_ring *br" +.Ft int +.Fn drbr_inuse "struct ifnet *ifp" "struct buf_ring *br" +.Sh DESCRIPTION +The +.Nm +functions provide an API to network drivers for using +.Xr buf_ring 9 +for enqueueing and dequeueing packets. +This is meant as a replacement for the IFQ interface for packet queuing. +It allows a packet to be enqueued with a single atomic and packet +dequeue to be done without any per-packet atomics as it is protected +by the driver's tx queue lock. +If +.Dv INVARIANTS +is enabled, +.Fn drbr_dequeue +will assert that the tx queue lock is held when it is called. +.Pp +The +.Fn drbr_free +function frees all the enqueued mbufs and then frees the buf_ring. +.Pp +The +.Fn drbr_enqueue +function is used to enqueue an mbuf to a buf_ring, falling back to the +ifnet's IFQ if +.Xr ALTQ 4 +is enabled. +.Pp +The +.Fn drbr_dequeue +function is used to dequeue an mbuf from a buf_ring or, if +.Xr ALTQ 4 +is enabled, from the ifnet's IFQ. +.Pp +The +.Fn drbr_dequeue_cond +function is used to conditionally dequeue an mbuf from a buf_ring based +on whether +.Fa func +returns +.Dv TRUE +or +.Dv FALSE . +.Pp +The +.Fn drbr_flush +function frees all mbufs enqueued in the buf_ring and the ifnet's IFQ. +.Pp +The +.Fn drbr_empty +function returns +.Dv TRUE +if there are no mbufs enqueued, +.Dv FALSE +otherwise. +.Pp +The +.Fn drbr_inuse +function returns the number of mbufs enqueued. +Note to users that this is intrinsically racy as there is no guarantee that +there will not be more mbufs when +.Fn drbr_dequeue +is actually called. +Provided the tx queue lock is held there will not be less. +.Sh RETURN VALUES +The +.Fn drbr_enqueue +function returns +.Er ENOBUFS +if there are no slots available in the buf_ring and +.Dv 0 +on success. +.Pp +The +.Fn drbr_dequeue +and +.Fn drbr_dequeue_cond +functions return an mbuf on success and +.Dv NULL +if the buf_ring is empty. +.Sh HISTORY +These functions were introduced in +.Fx 8.0 . diff --git a/static/freebsd/man9/driver.9 b/static/freebsd/man9/driver.9 new file mode 100644 index 00000000..0cfbd297 --- /dev/null +++ b/static/freebsd/man9/driver.9 @@ -0,0 +1,117 @@ +.\" -*- 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 April 19, 2022 +.Dt DRIVER 9 +.Os +.Sh NAME +.Nm driver +.Nd structure describing a device driver +.Sh SYNOPSIS +.Bd -literal +#include +#include +#include +#include + +static int foo_probe(device_t); +static int foo_attach(device_t); +static int foo_detach(device_t); +static int foo_frob(device_t, int, int); +static int foo_twiddle(device_t, char *); + +static device_method_t foo_methods[] = { + /* Methods from the device interface */ + DEVMETHOD(device_probe, foo_probe), + DEVMETHOD(device_attach, foo_attach), + DEVMETHOD(device_detach, foo_detach), + + /* Methods from the bogo interface */ + DEVMETHOD(bogo_frob, foo_frob), + DEVMETHOD(bogo_twiddle, foo_twiddle), + + /* Terminate method list */ + DEVMETHOD_END +}; + +static driver_t foo_driver = { + "foo", + foo_methods, + sizeof(struct foo_softc) +}; + +DRIVER_MODULE(foo, bogo, foo_driver, NULL, NULL); +.Ed +.Sh DESCRIPTION +Each driver in the kernel is described by a +.Dv driver_t +structure. +The structure contains the name of the device, a pointer +to a list of methods, an indication of the kind of device which the +driver implements and the size of the private data which the driver +needs to associate with a device instance. +Each driver will implement +one or more sets of methods (called interfaces). +The example driver +implements the standard "driver" interface and the fictitious "bogo" +interface. +.Pp +When a driver is registered with the system (by the +.Dv DRIVER_MODULE +macro, see +.Xr DRIVER_MODULE 9 ) , +it is added to the list of drivers contained in the devclass +of its parent bus type. +For instance all PCI drivers would be +contained in the devclass named "pci" and all ISA drivers would be +in the devclass named "isa". +The reason the drivers are not held in the device object of the parent +bus is to handle multiple instances of a given type of bus. +The +.Dv DRIVER_MODULE +macro will also create the devclass with the name of the driver and +can optionally call extra initialisation code in the driver by +specifying an extra module event handler and argument as the last two +arguments. +.Sh SEE ALSO +.Xr devclass 9 , +.Xr device 9 , +.Xr DEVICE_ATTACH 9 , +.Xr DEVICE_DETACH 9 , +.Xr DEVICE_IDENTIFY 9 , +.Xr DEVICE_PROBE 9 , +.Xr DEVICE_SHUTDOWN 9 , +.Xr DRIVER_MODULE 9 +.Sh HISTORY +The +.Nm +framework first appeared in +.Fx 2.2.7 . +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/ecn.9 b/static/freebsd/man9/ecn.9 new file mode 100644 index 00000000..3f407811 --- /dev/null +++ b/static/freebsd/man9/ecn.9 @@ -0,0 +1,184 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2026 Pouria Mousavizadeh Tehrani +.\" 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 ``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 March 19, 2026 +.Dt ECN 9 +.Os +.Sh NAME +.Nm ecn , +.Nm ip_ecn_ingress , +.Nm ip_ecn_egress , +.Nm ip6_ecn_ingress , +.Nm ip6_ecn_egress +.Nd IP ECN interfaces for tunnel encapsulation/decapsulation +.Sh SYNOPSIS +.In sys/netinet/ip_ecn.h +.In sys/netinet6/ip6_ecn.h +.\" +.Ss "Constants" +.Dv ECN_COMPLETE +.Dv ECN_ALLOWED +.Dv ECN_FORBIDDEN +.Dv ECN_NOCARE +.\" +.Ss "ECN Manipulation Functions" +.Ft "void" +.Fn ip_ecn_ingress "int mode" "uint8_t *outer" "const uint8_t *inner" +.Ft "void" +.Fn "ip6_ecn_ingress" "int mode" "uint32_t *outer" "const uint32_t *inner" +.Ft "int" +.Fn "ip_ecn_egress" "int mode" "uint8_t *outer" "const uint8_t *inner" +.Ft "int" +.Fn "ip6_ecn_egress" "int mode" "uint32_t *outer" "const uint32_t *inner" +.\" +.Sh DESCRIPTION +The +.Fn ip_ecn_ingress +and +.Fn ip_ecn_egress +interfaces implement Explicit Congestion Notification (ECN) processing for +tunnel encapsulation (ingress) and decapsulation (egress). They operate on +the ECN bits in the IP Type of Service (TOS) or +IPv6 Traffic Class (TCLASS) header field. +These functions implements the standard specification of RFC6040 in +.Vt ECN_ALLOWED +mode for +.Fn ip_ecn_egress +with addition of +.Vt ECN_FORBIDDEN +mode as compatibility mode in +.Fn ip_ecn_ingress . +.Ss Interface +The functions for manipulating +.Vt ip_tos +and +.Vt ipv6_flow +are as follows: +.Bl -tag -width indent -offset indent +.It Fn ip_ecn_ingress Fn ip6_ecn_ingress +Perform ECN processing at encapsulation time (ingress) based on +the ECN bits of the +.Vt ip_tos +field in +.Vt "struct ip" +or the +.Vt ip6_flow +field in +.Vt "struct ip6_hdr" +as +.Va inner +to +.Va outer . +It also copies the DSCP value from +.Va inner +to +.Va outer . +.It Fn ip_ecn_egress Fn ip6_ecn_egress +Perform ECN processing at decapsulation time (egress) based on +the ECN bits of +.Va outer +to +.Va inner . +.Vt ECN_ALLOWED +mode may modify the +.Va inner +ECN bits or instruct the caller to drop or log +by returning +.Vt ECN_WARN +or +.Vt ECN_ALARM +values. +.El +.Pp +Return codes for +.Fn ip_ecn_egress +are as follows: +.Bl -tag -width ".Dv ECN_SUCCESS" -offset indent +.It Dv ECN_DROP +(0) Caller MUST drop the packet. +.It Dv ECN_SUCCESS +(1) Processing succeeded; +inner ECN bits may have been updated. +.It Dv ECN_WARN +(2) Processing succeeded; +caller MAY log a warning for an anomalous ECN combination. +.It Dv ECN_ALARM +(3) Processing succeeded; +caller SHOULD log and MAY raise an alarm for a serious ECN anomaly. +.El +.Pp +The following modes are handled by functions: +.Bl -tag -width ".Dv ECN_FORBIDDEN" -offset indent +.It Dv ECN_COMPLETE +Normal mode as defined in RFC6040. +ECN bits are preserved through encapsulation; +decapsulation follows RFC6040 rules and it returns +.Vt ECN_WARN +or +.Vt ECN_ALARM +values when a potentially dangerous packet detected. +.It Dv ECN_ALLOWED +Normal mode as defined in RFC6040 without security checks. +ECN bits are preserved through encapsulation; +decapsulation follows RFC6040 rules. +.It Dv ECN_FORBIDDEN +Compatibility mode. +ECN is stripped on encapsulation and decapsulation will +drop packets that carry CE in the outer header. +This mode should not be used in +.Fn ip_ecn_egress +or +.Fn ip6_ecn_egress +since the +.Vt ECN_ALLOWED +mode already covers all possible scenarios as specified in RFC6040. +.It Dv ECN_NOCARE +leave ECN bits unchanged and ignored. +.El +.Ss IPV6 HANDLING +IPv6 interfaces +.Fn ip6_ecn_ingress +and +.Fn ip6_ecn_egress +extract the 8-bit DSCP and ECN values from the 32-bit +.Vt ip6_flow +and insert it to IPv4 equivalent interfaces. +.Sh SEE ALSO +.Xr ip 4 , +.Xr ip6 4 , +.Xr ipsec 4 +.Sh HISTORY +Historically +.Fn ip_ecn_egress +used a boolean-style return. +The current API preserves numeric mapping for drop (ECN_DROP == 0) +and success (ECN_SUCCESS == 1) but defines additional non-zero +status codes (ECN_WARN, ECN_ALARM). +Callers that only test for non-zero success will continue to +treat WARN/ALARM as success. +.Sh AUTHORS +.An Pouria Mousavizadeh Tehrani Aq Mt pouria@FreeBSD.org diff --git a/static/freebsd/man9/efirt.9 b/static/freebsd/man9/efirt.9 new file mode 100644 index 00000000..e0859168 --- /dev/null +++ b/static/freebsd/man9/efirt.9 @@ -0,0 +1,261 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2018 Kyle Evans +.\" +.\" 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 November 2, 2021 +.Dt EFIRT 9 +.Os +.Sh NAME +.Nm efirt , +.Nm efi_rt_ok , +.Nm efi_get_table , +.Nm efi_get_time , +.Nm efi_get_time_capabilities , +.Nm efi_reset_system , +.Nm efi_set_time , +.Nm efi_var_get , +.Nm efi_var_nextname , +.Nm efi_var_set +.Nd kernel access to UEFI runtime services +.Sh SYNOPSIS +.Cd "options EFIRT" +.Pp +.In sys/efi.h +.Ft int +.Fn efi_rt_ok "void" +.Ft int +.Fn efi_get_table "struct uuid *uuid" "void **ptr" +.Ft int +.Fn efi_get_time "struct efi_tm *tm" +.Ft int +.Fn efi_get_time_capabilities "struct efi_tmcap *tmcap" +.Ft int +.Fn efi_reset_system "enum efi_reset type" +.Ft int +.Fn efi_set_time "struct efi_tm *tm" +.Ft int +.Fn efi_var_get "uint16_t *name" "struct uuid *vendor" "uint32_t *attrib" \ + "size_t *datasize" "void *data" +.Ft int +.Fn efi_var_nextname "size_t *namesize" "uint16_t *name" "struct uuid *vendor" +.Ft int +.Fn efi_var_set "uint16_t *name" "struct uuid *vendor" "uint32_t attrib" \ + "size_t datasize" "void *data" +.Sh DESCRIPTION +All of the following calls will return +.Dv ENXIO +if UEFI runtime services are not available. +.Nm +is currently only available on amd64 and arm64. +.Pp +The +.Fn efi_rt_ok +Returns 0 if UEFI runtime services are present and functional, or +.Dv ENXIO +if not. +.Pp +The +.Fn efi_get_table +function gets a table by uuid from the UEFI system table. +Returns 0 if the table was found and populates *ptr with the address. +Returns +.Dv ENXIO +if the configuration table or system table are unset. +Returns +.Dv ENOENT +if the requested table cannot be found. +.Pp +The +.Fn efi_get_time +function gets the current time from the RTC, if available. +Returns 0 and populates the +.Vt struct efi_tm +on success. +Returns +.Dv EINVAL +if the +.Vt struct efi_tm +is +.Dv NULL , +or +.Dv EIO +if the time could not be retrieved due to a hardware error. +.Pp +The +.Fn efi_get_time_capabilities +function gets the capabilities from the RTC. +Returns 0 and populates the +.Vt struct efi_tmcap +on success. +Returns +.Dv EINVAL +if the +.Vt struct efi_tm +is +.Dv NULL , +or +.Dv EIO +if the time could not be retrieved due to a hardware error. +.Pp +The +.Fn efi_reset_system +function requests a reset of the system. +The +.Fa type +argument may be one of the +.Vt enum efi_reset +values: +.Bl -tag -width ".Dv EFI_RESET_SHUTDOWN" +.It Dv EFI_RESET_COLD +Perform a cold reset of the system, and reboot. +.It Dv EFI_RESET_WARM +Perform a warm reset of the system, and reboot. +.It Dv EFI_RESET_SHUTDOWN +Power off the system. +.El +.Pp +The +.Fn efi_set_time +function sets the time on the RTC to the time described by the +.Vt struct efi_tm +passed in. +Returns 0 on success, +.Dv EINVAL +if a time field is out of range, or +.Dv EIO +if the time could not be set due to a hardware error. +.Pp +The +.Fn efi_var_get +function fetches the variable identified by +.Fa vendor +and +.Fa name . +Returns 0 and populates +.Fa attrib , +.Fa datasize , +and +.Fa data +on success. +Otherwise, one of the following errors are returned: +.Bl -tag -width ".Dv EOVERFLOW" +.It Dv ENOENT +The variable was not found. +.It Dv EOVERFLOW +.Fa datasize +is not sufficient to hold the variable data. +.Fa namesize +is updated to reflect the size needed to complete the request. +.It Dv EINVAL +One of +.Fa name , +.Fa vendor , +or +.Fa datasize +are NULL. +Alternatively, +.Fa datasize +is large enough to hold the response but +.Fa data +is NULL. +.It Dv EIO +The variable could not be retrieved due to a hardware error. +.It Dv EDOOFUS +The variable could not be retrieved due to an authentication failure. +.El +.Pp +The +.Fn efi_var_nextname +function is used for enumeration of variables. +On the initial call to +.Fn efi_var_nextname , +.Fa name +should be an empty string. +Subsequent calls should pass in the last +.Fa name +and +.Fa vendor +returned until +.Dv ENOENT +is returned. +Returns 0 and populates +.Fa namesize , +.Fa name , +and +.Fa vendor +with the next variable's data. +Otherwise, returns one of the following errors: +.Bl -tag -width ".Dv EOVERFLOW" +.It Dv ENOENT +The next variable was not found. +.It Dv EOVERFLOW +.Fa datasize +is not sufficient to hold the variable data. +.Fa namesize +is updated to reflect the size needed to complete the request. +.It Dv EINVAL +One of +.Fa name , +.Fa vendor , +or +.Fa datasize +are NULL. +.It Dv EIO +The variable could not be retrieved due to a hardware error. +.El +.Pp +The +.Fn efi_var_set +function sets the variable described by +.Fa name +and +.Fa vendor . +Returns 0 if the variable has been successfully. +Otherwise, returns one of the following errors: +.Bl -tag -width ".Dv EOVERFLOW" +.It Dv EINVAL +Either +.Fa attrib +was an invalid combination of attributes, +.Fa datasize +exceeds the maximum allowed size, or +.Fa name +is an empty Unicode stirng. +.It Dv EAGAIN +Not enough storage is available to hold the variable and its data. +.It Dv EIO +The variable could not be saved due to a hardware error. +.It Dv EROFS +The variable in question is read-only or may not be deleted. +.It Dv EDOOFUS +The variable could not be set due to an authentication failure. +.It Dv ENOENT +The variable trying to be updated or deleted was not found. +.El +.Sh SEE ALSO +.Xr efidev 4 +.Sh AUTHORS +This manual page was written by +.An Kyle Evans Aq Mt kevans@FreeBSD.org . diff --git a/static/freebsd/man9/epoch.9 b/static/freebsd/man9/epoch.9 new file mode 100644 index 00000000..826f8872 --- /dev/null +++ b/static/freebsd/man9/epoch.9 @@ -0,0 +1,290 @@ +.\" +.\" Copyright (C) 2018 Matthew Macy . +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 March 25, 2024 +.Dt EPOCH 9 +.Os +.Sh NAME +.Nm epoch , +.Nm epoch_context , +.Nm epoch_alloc , +.Nm epoch_free , +.Nm epoch_enter , +.Nm epoch_exit , +.Nm epoch_wait , +.Nm epoch_enter_preempt , +.Nm epoch_exit_preempt , +.Nm epoch_wait_preempt , +.Nm epoch_call , +.Nm epoch_drain_callbacks , +.Nm in_epoch , +.Nm in_epoch_verbose +.Nd kernel epoch based reclamation +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.In sys/epoch.h +.\" Types +.Bd -literal +struct epoch; /* Opaque */ +.Ed +.Vt typedef "struct epoch *epoch_t" ; +.Bd -literal +struct epoch_context { + void *data[2]; +}; +.Ed +.Vt typedef "struct epoch_context *epoch_context_t" ; +.Vt typedef "void epoch_callback_t(epoch_context_t)" ; +.Bd -literal +struct epoch_tracker; /* Opaque */ +.Ed +.Vt typedef "struct epoch_tracker *epoch_tracker_t" ; +.\" Declarations +.Ft epoch_t +.Fn epoch_alloc "const char *name" "int flags" +.Ft void +.Fn epoch_free "epoch_t epoch" +.Ft void +.Fn epoch_enter "epoch_t epoch" +.Ft void +.Fn epoch_exit "epoch_t epoch" +.Ft void +.Fn epoch_wait "epoch_t epoch" +.Ft void +.Fn epoch_enter_preempt "epoch_t epoch" "epoch_tracker_t et" +.Ft void +.Fn epoch_exit_preempt "epoch_t epoch" "epoch_tracker_t et" +.Ft void +.Fn epoch_wait_preempt "epoch_t epoch" +.Ft void +.Fn epoch_call "epoch_t epoch" "epoch_callback_t callback" "epoch_context_t ctx" +.Ft void +.Fn epoch_drain_callbacks "epoch_t epoch" +.Ft int +.Fn in_epoch "epoch_t epoch" +.Ft int +.Fn in_epoch_verbose "epoch_t epoch" "int dump_onfail" +.Sh DESCRIPTION +Epochs are used to guarantee liveness and immutability of data by +deferring reclamation and mutation until a grace period has elapsed. +Epochs do not have any lock ordering issues. +Entering and leaving an epoch section will never block. +.Pp +Epochs are allocated with +.Fn epoch_alloc . +The +.Fa name +argument is used for debugging convenience when the +.Cd EPOCH_TRACE +kernel option is configured. +By default, epochs do not allow preemption during sections. +By default mutexes cannot be held across +.Fn epoch_wait_preempt . +The +.Fa flags +specified are formed by +.Em OR Ns 'ing +the following values: +.Bl -tag -offset indent -width Ds +.It Dv EPOCH_LOCKED +Permit holding mutexes across +.Fn epoch_wait_preempt +(requires +.Dv EPOCH_PREEMPT ) . +When doing this one must be cautious of creating a situation where a deadlock +is possible. +.It Dv EPOCH_PREEMPT +The +.Vt epoch +will allow preemption during sections. +Only non-sleepable locks may be acquired during a preemptible epoch. +The functions +.Fn epoch_enter_preempt , +.Fn epoch_exit_preempt , +and +.Fn epoch_wait_preempt +must be used in place of +.Fn epoch_enter , +.Fn epoch_exit , +and +.Fn epoch_wait , +respectively. +.El +.Pp +.Vt epoch Ns s +are freed with +.Fn epoch_free . +.Pp +Threads indicate the start of an epoch critical section by calling +.Fn epoch_enter +(or +.Fn epoch_enter_preempt +for preemptible epochs). +Threads call +.Fn epoch_exit +(or +.Fn epoch_exit_preempt +for preemptible epochs) +to indicate the end of a critical section. +.Vt struct epoch_tracker Ns s +are stack objects whose pointers are passed to +.Fn epoch_enter_preempt +and +.Fn epoch_exit_preempt +(much like +.Vt struct rm_priotracker ) . +.Pp +Threads can defer work until a grace period has expired since any thread has +entered the epoch either synchronously or asynchronously. +.Fn epoch_call +defers work asynchronously by invoking the provided +.Fa callback +at a later time. +.Fn epoch_wait +(or +.Fn epoch_wait_preempt ) +blocks the current thread until the grace period has expired and the work can be +done safely. +.Pp +Default, non-preemptible epoch wait +.Fn ( epoch_wait ) +is guaranteed to have much shorter completion times relative to +preemptible epoch wait +.Fn ( epoch_wait_preempt ) . +(In the default type, none of the threads in an epoch section will be preempted +before completing its section.) +.Pp +INVARIANTS can assert that a thread is in an epoch by using +.Fn in_epoch . +.Fn in_epoch "epoch" +is equivalent to invoking +.Fn in_epoch_verbose "epoch" "0" . +If +.Cd EPOCH_TRACE +is enabled, +.Fn in_epoch_verbose "epoch" "1" +provides additional verbose debugging information. +.Pp +The epoch API currently does not support sleeping in epoch_preempt sections. +A caller should never call +.Fn epoch_wait +in the middle of an epoch section for the same epoch as this will lead to a deadlock. +.Pp +The +.Fn epoch_drain_callbacks +function is used to drain all pending callbacks which have been invoked by prior +.Fn epoch_call +function calls on the same epoch. +This function is useful when there are shared memory structure(s) +referred to by the epoch callback(s) which are not refcounted and are +rarely freed. +The typical place for calling this function is right before freeing or +invalidating the shared resource(s) used by the epoch callback(s). +This function can sleep and is not optimized for performance. +.Sh RETURN VALUES +.Fn in_epoch curepoch +will return 1 if curthread is in curepoch, 0 otherwise. +.Sh EXAMPLES +Async free example: +Thread 1: +.Bd -literal +int +in_pcbladdr(struct inpcb *inp, struct in_addr *faddr, struct in_laddr *laddr, + struct ucred *cred) +{ + /* ... */ + epoch_enter(net_epoch); + CK_STAILQ_FOREACH(ifa, &ifp->if_addrhead, ifa_link) { + sa = ifa->ifa_addr; + if (sa->sa_family != AF_INET) + continue; + sin = (struct sockaddr_in *)sa; + if (prison_check_ip4(cred, &sin->sin_addr) == 0) { + ia = (struct in_ifaddr *)ifa; + break; + } + } + epoch_exit(net_epoch); + /* ... */ +} +.Ed +Thread 2: +.Bd -literal +void +ifa_free(struct ifaddr *ifa) +{ + + if (refcount_release(&ifa->ifa_refcnt)) + epoch_call(net_epoch, ifa_destroy, &ifa->ifa_epoch_ctx); +} + +void +if_purgeaddrs(struct ifnet *ifp) +{ + + /* .... * + IF_ADDR_WLOCK(ifp); + CK_STAILQ_REMOVE(&ifp->if_addrhead, ifa, ifaddr, ifa_link); + IF_ADDR_WUNLOCK(ifp); + ifa_free(ifa); +} +.Ed +.Pp +Thread 1 traverses the ifaddr list in an epoch. +Thread 2 unlinks with the corresponding epoch safe macro, marks as logically free, +and then defers deletion. +More general mutation or a synchronous +free would have to follow a call to +.Fn epoch_wait . +.Sh SEE ALSO +.Xr callout 9 , +.Xr locking 9 , +.Xr mtx_pool 9 , +.Xr mutex 9 , +.Xr rwlock 9 , +.Xr sema 9 , +.Xr sleep 9 , +.Xr sx 9 +.Sh HISTORY +The +.Nm +framework first appeared in +.Fx 11.0 . +.Sh CAVEATS +One must be cautious when using +.Fn epoch_wait_preempt . +Threads are pinned during epoch sections, so if a thread in a section is then +preempted by a higher priority compute bound thread on that CPU, it can be +prevented from leaving the section indefinitely. +.Pp +Epochs are not a straight replacement for read locks. +Callers must use safe list and tailq traversal routines in an epoch (see ck_queue). +When modifying a list referenced from an epoch section safe removal +routines must be used and the caller can no longer modify a list entry +in place. +An item to be modified must be handled with copy on write +and frees must be deferred until after a grace period has elapsed. diff --git a/static/freebsd/man9/ether_gen_addr.9 b/static/freebsd/man9/ether_gen_addr.9 new file mode 100644 index 00000000..aa7d73ae --- /dev/null +++ b/static/freebsd/man9/ether_gen_addr.9 @@ -0,0 +1,78 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (C) 2021 Kyle Evans +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 June 1, 2021 +.Dt ETHER_GEN_ADDR 9 +.Os +.Sh NAME +.Nm ether_gen_addr +.Nd "generate an arbitrary MAC address for use" +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In net/if.h +.In net/if_var.h +.In net/ethernet.h +.Ft void +.Fn ether_gen_addr "struct ifnet *ifp" "struct ether_addr *hwaddr" +.Sh DESCRIPTION +The +.Fn ether_gen_addr +function generates an arbitrary MAC address for use by an ethernet interface +that does not have an assigned address. +.Pp +By default, +.Nm +attempts to generate a stable MAC address using the hostid of the jail that +the +.Ar ifp +is being added to. +During early boot, the hostid may not be set on machines that haven't yet +populated +.Pa /etc/hostid , +or on machines that do not use +.Xr loader 8 . +.Pp +.Nm +can fail to derive a MAC address due to memory allocation failure, or because +the hostid has not been populated. +In these cases, a locally-administered unicast MAC address will be randomly +generated and returned via the +.Ar hwaddr +parameter. +.Pp +If +.Nm +succeeds, then it will return a MAC address in the FreeBSD Foundation OUI, +.Dq 58:9c:fc , +via the +.Ar hwaddr +parameter. +.Sh AUTHORS +This manual page was written by +.An Kyle Evans Aq Mt kevans@FreeBSD.org . diff --git a/static/freebsd/man9/eventtimers.9 b/static/freebsd/man9/eventtimers.9 new file mode 100644 index 00000000..bbf8307e --- /dev/null +++ b/static/freebsd/man9/eventtimers.9 @@ -0,0 +1,251 @@ +.\" +.\" Copyright (c) 2011-2013 Alexander Motin +.\" 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 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 April 2, 2014 +.Dt EVENTTIMERS 9 +.Os +.Sh NAME +.Nm eventtimers +.Nd kernel event timers subsystem +.Sh SYNOPSIS +.In sys/timeet.h +.Bd -literal +struct eventtimer; + +typedef int et_start_t(struct eventtimer *et, + sbintime_t first, sbintime_t period); +typedef int et_stop_t(struct eventtimer *et); +typedef void et_event_cb_t(struct eventtimer *et, void *arg); +typedef int et_deregister_cb_t(struct eventtimer *et, void *arg); + +struct eventtimer { + SLIST_ENTRY(eventtimer) et_all; + char *et_name; + int et_flags; +#define ET_FLAGS_PERIODIC 1 +#define ET_FLAGS_ONESHOT 2 +#define ET_FLAGS_PERCPU 4 +#define ET_FLAGS_C3STOP 8 +#define ET_FLAGS_POW2DIV 16 + int et_quality; + int et_active; + uint64_t et_frequency; + sbintime_t et_min_period; + sbintime_t et_max_period; + et_start_t *et_start; + et_stop_t *et_stop; + et_event_cb_t *et_event_cb; + et_deregister_cb_t *et_deregister_cb; + void *et_arg; + void *et_priv; + struct sysctl_oid *et_sysctl; +}; +.Ed +.Ft int +.Fn et_register "struct eventtimer *et" +.Ft int +.Fn et_deregister "struct eventtimer *et" +.Ft void +.Fn et_change_frequency "struct eventtimer *et" "uint64_t newfreq" +.Fn ET_LOCK +.Fn ET_UNLOCK +.Ft struct eventtimer * +.Fn et_find "const char *name" "int check" "int want" +.Ft int +.Fn et_init "struct eventtimer *et" "et_event_cb_t *event" "et_deregister_cb_t *deregister" "void *arg" +.Ft int +.Fn et_start "struct eventtimer *et" "sbintime_t first" "sbintime_t period" +.Ft int +.Fn et_stop "struct eventtimer *et" +.Ft int +.Fn et_ban "struct eventtimer *et" +.Ft int +.Fn et_free "struct eventtimer *et" +.Sh DESCRIPTION +Event timers are responsible for generating interrupts at specified time +or periodically, to run different time-based events. +Subsystem consists of three main parts: +.Bl -tag -width "Consumers" +.It Drivers +Manage hardware to generate requested time events. +.It Consumers +.Pa sys/kern/kern_clocksource.c +uses event timers to supply kernel with +.Fn hardclock , +.Fn statclock +and +.Fn profclock +time events. +.It Glue code +.Pa sys/sys/timeet.h , +.Pa sys/kern/kern_et.c +provide APIs for event timer drivers and consumers. +.El +.Sh DRIVER API +Driver API is built around eventtimer structure. +To register its functionality driver allocates that structure and calls +.Fn et_register . +Driver should fill following fields there: +.Bl -tag -width Va +.It Va et_name +Unique name of the event timer for management purposes. +.It Va et_flags +Set of flags, describing timer capabilities: +.Bl -tag -width "ET_FLAGS_PERIODIC" -compact +.It ET_FLAGS_PERIODIC +Periodic mode supported. +.It ET_FLAGS_ONESHOT +One-shot mode supported. +.It ET_FLAGS_PERCPU +Timer is per-CPU. +.It ET_FLAGS_C3STOP +Timer may stop in CPU sleep state. +.It ET_FLAGS_POW2DIV +Timer supports only 2^n divisors. +.El +.It Va et_quality +Abstract value to certify whether this timecounter is better than the others. +Higher value means better. +.It Va et_frequency +Timer oscillator's base frequency, if applicable and known. +Used by consumers to predict set of possible frequencies that could be +obtained by dividing it. +Should be zero if not applicable or unknown. +.It Va et_min_period , et_max_period +Minimal and maximal reliably programmable time periods. +.It Va et_start +Driver's timer start function pointer. +.It Va et_stop +Driver's timer stop function pointer. +.It Va et_priv +Driver's private data storage. +.El +.Pp +After the event timer functionality is registered, it is controlled via +.Va et_start +and +.Va et_stop +methods. +.Va et_start +method is called to start the specified event timer. +The last two arguments are used to specify time when events should be +generated. +.Va first +argument specifies time period before the first event generated. +In periodic mode NULL value specifies that first period is equal to the +.Va period +argument value. +.Va period +argument specifies the time period between following events for the +periodic mode. +The NULL value there specifies the one-shot mode. +At least one of these two arguments should be not NULL. +When event time arrive, driver should call +.Va et_event_cb +callback function, passing +.Va et_arg +as the second argument. +.Va et_stop +method is called to stop the specified event timer. +For the per-CPU event timers +.Va et_start +and +.Va et_stop +methods control timers associated with the current CPU. +.Pp +Driver may deregister its functionality by calling +.Fn et_deregister . +.Pp +If the frequency of the clock hardware can change while it is +running (for example, during power-saving modes), the driver must call +.Fn et_change_frequency +on each change. +If the given event timer is the active timer, +.Fn et_change_frequency +stops the timer on all CPUs, updates +.Va et->frequency , +then restarts the timer on all CPUs so that all +current events are rescheduled using the new frequency. +If the given timer is not currently active, +.Fn et_change_frequency +simply updates +.Va et->frequency . +.Sh CONSUMER API +.Fn et_find +allows consumer to find available event timer, optionally matching specific +name and/or capability flags. +Consumer may read returned eventtimer structure, but should not modify it. +When wanted event timer is found, +.Fn et_init +should be called for it, submitting +.Va event +and optionally +.Va deregister +callbacks functions, and the opaque argument +.Va arg . +That argument will be passed as argument to the callbacks. +Event callback function will be called on scheduled time events. +It is called from the hardware interrupt context, so no sleep is permitted +there. +Deregister callback function may be called to report consumer that the event +timer functionality is no longer available. +On this call, consumer should stop using event timer before the return. +.Pp +After the timer is found and initialized, it can be controlled via +.Fn et_start +and +.Fn et_stop . +The arguments are the same as described in driver API. +Per-CPU event timers can be controlled only from specific CPUs. +.Pp +.Fn et_ban +allows consumer to mark event timer as broken via clearing both one-shot and +periodic capability flags, if it was somehow detected. +.Fn et_free +is the opposite to +.Fn et_init . +It releases the event timer for other consumers use. +.Pp +.Fn ET_LOCK +and +.Fn ET_UNLOCK +macros should be used to manage +.Xr mutex 9 +lock around +.Fn et_find , +.Fn et_init +and +.Fn et_free +calls to serialize access to the list of the registered event timers and the +pointers returned by +.Fn et_find . +.Fn et_start +and +.Fn et_stop +calls should be serialized in consumer's internal way to avoid concurrent +timer hardware access. +.Sh SEE ALSO +.Xr eventtimers 4 +.Sh AUTHORS +.An Alexander Motin Aq Mt mav@FreeBSD.org diff --git a/static/freebsd/man9/extattr.9 b/static/freebsd/man9/extattr.9 new file mode 100644 index 00000000..3ee2ed5e --- /dev/null +++ b/static/freebsd/man9/extattr.9 @@ -0,0 +1,99 @@ +.\"- +.\" Copyright (c) 1999, 2000, 2001, 2003 Robert N. M. Watson +.\" 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 September 5, 2023 +.Dt EXTATTR 9 +.Os +.Sh NAME +.Nm extattr +.Nd virtual file system named extended attributes +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/extattr.h +.Sh DESCRIPTION +Named extended attributes allow additional meta-data to be associated +with vnodes representing files and directories. +The semantics of this additional data is that of a "name=value" pair, where +a name may be defined or undefined, and if defined, associated with zero or +more bytes of arbitrary binary data. +Extended attribute names exist within a set of namespaces; each operation +on an extended attribute is required to provide the namespace to which to +operation refers. +If the same name is present in multiple namespaces, the extended attributes +associated with the names are stored and manipulated independently. +The following two namespaces are defined universally, although individual +file systems may implement additional namespaces, or not implement +these namespaces: +.Dv EXTATTR_NAMESPACE_USER , +.Dv EXTATTR_NAMESPACE_SYSTEM . +The semantics of these attributes are intended to be as follows: user +attribute data is protected according the normal discretionary +and mandatory protections associated with the data in the file or +directory; system attribute data is protected such that appropriate +privilege is required to directly access or manipulate these attributes. +By default, processes in a +.Xr jail 8 +cannot access the system attribute data unless the +.Va allow.extattr +configuration parameter is specified. +.Pp +Reads of extended attribute data may return specific contiguous regions of +the meta-data, in the style of +.Xr VOP_READ 9 , +but writes will replace the entire current "value" associated with +a given name. +As there are a plethora of file systems with differing extended attributes, +availability and functionality of these functions may be limited, and they +should be used with awareness of the underlying semantics of the supporting +file system. +Authorization schemes for extended attribute data may also vary by file +system, as well as maximum attribute size, and whether or not any or +specific new attributes may be defined. +.Pp +Extended attributes are named using a null-terminated character string. +Depending on underlying file system semantics, this name may or may not be +case-sensitive. +Appropriate vnode extended attribute calls are: +.Xr VOP_GETEXTATTR 9 , +.Xr VOP_LISTEXTATTR 9 , +and +.Xr VOP_SETEXTATTR 9 . +.Sh SEE ALSO +.Xr jail 8 , +.Xr VFS 9 , +.Xr VOP_GETEXTATTR 9 , +.Xr VOP_LISTEXTATTR 9 , +.Xr VOP_SETEXTATTR 9 +.Sh AUTHORS +This manual page was written by +.An Robert Watson . +.Sh BUGS +In addition, the interface does not provide a mechanism to retrieve +the current set of available attributes; it has been suggested that +providing a +.Dv NULL +attribute name should cause a list of defined attributes for the passed file +or directory, but this is not currently implemented. diff --git a/static/freebsd/man9/exterror.9 b/static/freebsd/man9/exterror.9 new file mode 100644 index 00000000..47ffda06 --- /dev/null +++ b/static/freebsd/man9/exterror.9 @@ -0,0 +1,230 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 The FreeBSD Foundation +.\" +.\" This documentation was written by +.\" Konstantin Belousov under sponsorship +.\" from the FreeBSD Foundation. +.\" +.Dd November 5, 2025 +.Dt EXTERROR 9 +.Os +.Sh NAME +.Nm exterror +.Nd provide extended error information to userspace +.Sh SYNOPSIS +.Bd -literal -offset left -compact +#define EXTERR_CATEGORY EXTERR_CAT_MYCATEGORY +.Ed +.In sys/exterrvar.h +.Vt struct kexterr; +.Ft void +.Fn exterr_clear "struct kexterr *ke" +.Ft int +.Fn exterr_set_from "const struct kexterr *ke" +.Ft int +.Fn EXTERROR "int error" "const char *msg" ... +.Ft void +.Fn EXTERROR_KE "struct kexterr *ke" "int error" "const char *msg" ... +.Sh DESCRIPTION +The +.Nm +framework allows the kernel to return additional information about an error +along with the standard +.Xr errno 3 +error code, which is terse and often lacking context. +.Pp +The terseness is especially visible with commonly overloaded error codes like +.Er EINVAL +or +.Er EIO , +which occur at many places for a given syscall, or even +outside the context of the current kernel call. +Identifying the specific cause for the returned error using only the +.Va errno +value requires searching for all instances that the error is returned +in the kernel and trying to guess which is the most likely code path +to have returned the error. +.Nm +attaches additional data to the error itself +and records the error category and +the kernel source code file line number. +The intent of +.Nm +is to make it easier for a user to identify the cause of the error. +.Sh USAGE +Before +.Nm +can be used in the given source .c file, the category of extended errors +should be allocated in the +.In sys/exterr_cat.h +file. +The category is the unique integer, that, together with the source +line number, uniquely identifies the extended error occurrence. +Then, the +.Va EXTERR_CATEGORY +symbol should be defined as an alias for the allocated category, as +shown in the summary. +.Pp +A typical code fragment to report an error is just +.D1 return (EINVAL); +An extended error can augment the error code with additional information: +.D1 return (EXTERROR(EINVAL, \[dq]Invalid length\[dq])); +The error data and metadata is saved in the current thread storage. +The metadata includes the category and the source file line number. +.Pp +Arguments to the +.Fn EXTERROR +macro: +.Bl -dash +.It +The first argument to +.Fn EXTERROR +is the errno error code. +.It +The second argument is a constant string with the unbound lifetime, +which should tersely provide enough human-readable details about +the error. +.It +The +.Fn EXTERROR +macro can take two optional 64-bit integer arguments, +whose meaning is specific to the subsystem. +The format string may include up to two printf-like format +specifiers to insert the optional argument values in the +user output, which is done in userspace. +.Pp +The format specifier must be for an integer type, and include the +.Dq j +format modifier to accept only the types +.Vt intmax_t +or +.Vt uintmax_t . +.El +.Pp +The strings passed as the second argument are only retained +in the kernel text if the +.Cd option EXTERR_STRINGS +was enabled in the kernel config. +Otherwise they are stripped at compile time and are not available +to userspace at runtime. +.Pp +The +.Fn EXTERROR +macro can be used in any context where the current thread is defined. +Specifically, +.Fn EXTERROR +cannot be used in interrupt contexts and context switch code. +Additionally, use of +.Fn EXTERROR +in kernel threads is not sensible as there is no userspace to retrieve +the extended error data. +.Pp +The +.Fn EXTERROR_KE +macro is similar to +.Fn EXTERROR , +but it takes an explicit pointer +.Fa kep +to the +.Vt struct kexterr +to fill with the extended error information. +The macro expression value is +.Vt void . +See below for description of the asynchronous i/o error facilities. +.Pp +The +.Fn exterr_clear +function clears the content of the +.Vt struct kexterr +pointed to by the argument +.Fa ke . +.Pp +The +.Fn exterr_set_from +function sets the current thread extended error data from the +.Fa struct kexterr +pointed to by the argument +.Fa ke . +.Sh USERSPACE ACCESS TO EXTENDED ERROR DATA +There is no syscall overhead for using +.Nm +in the non-error case. +When an error occurs that has supplied extended information, +the kernel copies out that information into the userspace +per-thread area that was registered with the kernel, typically on +image activation, or later at thread startup. +The area is controlled by the +.Xr exterrctl 2 +internal syscall, normally done by the userspace C runtime. +.Pp +Userspace programs do not need to access the extended information +area directly. +There is no field that is stable for the specific error condition. +Instead, the base +.Lb c +functions +.Xr err 3 +and +.Xr warn 3 +were modified to print the extended information if it is available +in addition to the usual +.Va errno +decoding. +.Sh ASYNCHRONOUS INPUT/OUTPUT +Due to the nature of the +.Fx +i/o subsystem, most input/output requests, presented as buffers (as in +.Vt struct buf ) +and geom bio's ( +.Vt struct bio ) +are processed asynchronously in filesystem- and geom-private threads. +This makes it challenging to pass any extended error information +from the geom providers and drivers, where an error typically occurs, +back to the thread that initiated the request, and is the consumer of +the result. +.Pp +To alleviate the mismatch, both +.Vt struct buf +and +.Vt struct bio +have member of the +.Vt struct kexterr +type. +For buffers, the +.Va b_exterr +for +.Vt struct buf , +and +.Va bio_exterr +for +.Vt struct bio . +Asynchronous i/o code can use the +.Fn EXTERROR_KE +macro, passing the pointer to the current request's embedded +.Vt struct kexterr , +to record the extended error. +In both cases, the +.Va BIO_EXTERR +flag should be set to indicate that whole extended error is valid, +not only the +.Va b_error +or +.Va bio_error +values. +.Pp +Both VFS and geom generic layers, and several geom providers that generate +subordinate bio's from the original request, are aware of the extended +errors. +They pass +.Vt kexterr +from the failed request back to the thread that create the request. +.Sh SEE ALSO +.Xr errno 3 , +.Xr err 3 , +.Xr uexterr_gettext 3 +.Sh HISTORY +The +.Nm +facility was introduced in +.Fx 15.0 . diff --git a/static/freebsd/man9/fail.9 b/static/freebsd/man9/fail.9 new file mode 100644 index 00000000..346f4dc3 --- /dev/null +++ b/static/freebsd/man9/fail.9 @@ -0,0 +1,283 @@ +.\" +.\" Copyright (c) 2009-2019 Dell EMC Isilon http://www.isilon.com/ +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 June 6, 2019 +.Dt FAIL 9 +.Os +.Sh NAME +.Nm DEBUG_FP , +.Nm KFAIL_POINT_CODE , +.Nm KFAIL_POINT_CODE_FLAGS , +.Nm KFAIL_POINT_CODE_COND , +.Nm KFAIL_POINT_ERROR , +.Nm KFAIL_POINT_EVAL , +.Nm KFAIL_POINT_DECLARE , +.Nm KFAIL_POINT_DEFINE , +.Nm KFAIL_POINT_GOTO , +.Nm KFAIL_POINT_RETURN , +.Nm KFAIL_POINT_RETURN_VOID , +.Nm KFAIL_POINT_SLEEP_CALLBACKS , +.Nm fail_point +.Nd fail points +.Sh SYNOPSIS +.In sys/fail.h +.Fn KFAIL_POINT_CODE "parent" "name" "code" +.Fn KFAIL_POINT_CODE_FLAGS "parent" "name" "flags" "code" +.Fn KFAIL_POINT_CODE_COND "parent" "name" "cond" "flags" "code" +.Fn KFAIL_POINT_ERROR "parent" "name" "error_var" +.Fn KFAIL_POINT_EVAL "name" "code" +.Fn KFAIL_POINT_DECLARE "name" +.Fn KFAIL_POINT_DEFINE "parent" "name" "flags" +.Fn KFAIL_POINT_GOTO "parent" "name" "error_var" "label" +.Fn KFAIL_POINT_RETURN "parent" "name" +.Fn KFAIL_POINT_RETURN_VOID "parent" "name" +.Fn KFAIL_POINT_SLEEP_CALLBACKS "parent" "name" "pre_func" "pre_arg" "post_func" "post_arg" "code" +.Sh DESCRIPTION +Fail points are used to add code points where errors may be injected +in a user controlled fashion. +Fail points provide a convenient wrapper around user-provided error +injection code, providing a +.Xr sysctl 9 +MIB, and a parser for that MIB that describes how the error +injection code should fire. +.Pp +The base fail point macro is +.Fn KFAIL_POINT_CODE +where +.Fa parent +is a sysctl tree (frequently +.Sy DEBUG_FP +for kernel fail points, but various subsystems may wish to provide +their own fail point trees), and +.Fa name +is the name of the MIB in that tree, and +.Fa code +is the error injection code. +The +.Fa code +argument does not require braces, but it is considered good style to +use braces for any multi-line code arguments. +Inside the +.Fa code +argument, the evaluation of +.Sy RETURN_VALUE +is derived from the +.Fn return +value set in the sysctl MIB. +.Pp +Additionally, +.Fn KFAIL_POINT_CODE_FLAGS +provides a +.Fa flags +argument which controls the fail point's behaviour. +This can be used to e.g., mark the fail point's context as non-sleepable, +which causes the +.Sy sleep +action to be coerced to a busy wait. +The supported flags are: +.Bl -ohang -offset indent +.It FAIL_POINT_USE_TIMEOUT_PATH +Rather than sleeping on a +.Fn sleep +call, just fire the post-sleep function after a timeout fires. +.It FAIL_POINT_NONSLEEPABLE +Mark the fail point as being in a non-sleepable context, which coerces +.Fn sleep +calls to +.Fn delay +calls. +.El +.Pp +Likewise, +.Fn KFAIL_POINT_CODE_COND +supplies a +.Fa cond +argument, which allows you to set the condition under which the fail point's +code may fire. +This is equivalent to: +.Bd -literal + if (cond) + KFAIL_POINT_CODE_FLAGS(...); + +.Ed +See +.Sx SYSCTL VARIABLES +below. +.Pp +The remaining +.Fn KFAIL_POINT_* +macros are wrappers around common error injection paths: +.Bl -inset +.It Fn KFAIL_POINT_RETURN parent name +is the equivalent of +.Sy KFAIL_POINT_CODE(..., return RETURN_VALUE) +.It Fn KFAIL_POINT_RETURN_VOID parent name +is the equivalent of +.Sy KFAIL_POINT_CODE(..., return) +.It Fn KFAIL_POINT_ERROR parent name error_var +is the equivalent of +.Sy KFAIL_POINT_CODE(..., error_var = RETURN_VALUE) +.It Fn KFAIL_POINT_GOTO parent name error_var label +is the equivalent of +.Sy KFAIL_POINT_CODE(..., { error_var = RETURN_VALUE; goto label;}) +.El +.Pp +You can also introduce fail points by separating the declaration, +definition, and evaluation portions. +.Bl -inset +.It Fn KFAIL_POINT_DECLARE name +is used to declare the +.Sy fail_point +struct. +.It Fn KFAIL_POINT_DEFINE parent name flags +defines and initializes the +.Sy fail_point +and sets up its +.Xr sysctl 9 . +.It Fn KFAIL_POINT_EVAL name code +is used at the point that the fail point is executed. +.El +.Sh SYSCTL VARIABLES +The +.Fn KFAIL_POINT_* +macros add sysctl MIBs where specified. +Many base kernel MIBs can be found in the +.Sy debug.fail_point +tree (referenced in code by +.Sy DEBUG_FP ) . +.Pp +The sysctl variable may be set in a number of ways: +.Bd -literal + [%][*][(args...)][->] +.Ed +.Pp +The argument specifies which action to take; it can be one of: +.Bl -tag -width ".Dv return" +.It Sy off +Take no action (does not trigger fail point code) +.It Sy return +Trigger fail point code with specified argument +.It Sy sleep +Sleep the specified number of milliseconds +.It Sy panic +Panic +.It Sy break +Break into the debugger, or trap if there is no debugger support +.It Sy print +Print that the fail point executed +.It Sy pause +Threads sleep at the fail point until the fail point is set to +.Sy off +.It Sy yield +Thread yields the cpu when the fail point is evaluated +.It Sy delay +Similar to sleep, but busy waits the cpu. +(Useful in non-sleepable contexts.) +.El +.Pp +The % and * modifiers prior to control when + is executed. +The % form (e.g. "1.2%") can be used to specify a +probability that will execute. +This is a decimal in the range (0, 100] which can specify up to +1/10,000% precision. +The * form (e.g. "5*") can be used to specify the number of +times should be executed before this is disabled. +Only the last probability and the last count are used if multiple +are specified, i.e. "1.2%2%" is the same as "2%". +When both a probability and a count are specified, the probability +is evaluated before the count, i.e. "2%5*" means "2% of the time, +but only 5 times total". +.Pp +The operator -> can be used to express cascading terms. +If you specify ->, it means that if does not +.Ql execute , + is evaluated. +For the purpose of this operator, the +.Fn return +and +.Fn print +operators are the only types that cascade. +A +.Fn return +term only cascades if the code executes, and a +.Fn print +term only cascades when passed a non-zero argument. +A pid can optionally be specified. +The fail point term is only executed when invoked by a process with a +matching p_pid. +.Sh EXAMPLES +.Bl -tag -width Sy +.It Sy sysctl debug.fail_point.foobar="2.1%return(5)" +21/1000ths of the time, execute +.Fa code +with RETURN_VALUE set to 5. +.It Sy sysctl debug.fail_point.foobar="2%return(5)->5%return(22)" +2/100ths of the time, execute +.Fa code +with RETURN_VALUE set to 5. +If that does not happen, 5% of the time execute +.Fa code +with RETURN_VALUE set to 22. +.It Sy sysctl debug.fail_point.foobar="5*return(5)->0.1%return(22)" +For 5 times, return 5. +After that, 1/1000th of the time, return 22. +.It Sy sysctl debug.fail_point.foobar="0.1%5*return(5)" +Return 5 for 1 in 1000 executions, but only 5 times total. +.It Sy sysctl debug.fail_point.foobar="1%*sleep(50)" +1/100th of the time, sleep 50ms. +.It Sy sysctl debug.fail_point.foobar="1*return(5)[pid 1234]" +Return 5 once, when pid 1234 executes the fail point. +.El +.Sh AUTHORS +.An -nosplit +This manual page was written by +.Pp +.An Matthew Bryan Aq Mt matthew.bryan@isilon.com +and +.Pp +.An Zach Loafman Aq Mt zml@FreeBSD.org . +.Sh CAVEATS +It is easy to shoot yourself in the foot by setting fail points too +aggressively or setting too many in combination. +For example, forcing +.Fn malloc +to fail consistently is potentially harmful to uptime. +.Pp +The +.Fn sleep +sysctl setting may not be appropriate in all situations. +Currently, +.Fn fail_point_eval +does not verify whether the context is appropriate for calling +.Fn msleep . +You can force it to evaluate a +.Sy sleep +action as a +.Sy delay +action by specifying the +.Sy FAIL_POINT_NONSLEEPABLE +flag at the point the fail point is declared. diff --git a/static/freebsd/man9/fdt_pinctrl.9 b/static/freebsd/man9/fdt_pinctrl.9 new file mode 100644 index 00000000..6c50488c --- /dev/null +++ b/static/freebsd/man9/fdt_pinctrl.9 @@ -0,0 +1,189 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2018 Oleksandr Tymoshenko +.\" +.\" 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 June 23, 2018 +.Dt fdt_pinctrl 9 +.Os +.Sh NAME +.Nm fdt_pinctrl +.Nd helper functions for FDT pinmux controller drivers +.Sh SYNOPSIS +.In dev/fdt/fdt_pinctrl.h +.Ft int +.Fn fdt_pinctrl_configure "device_t client" "u_int index" +.Ft int +.Fn fdt_pinctrl_configure_by_name "device_t client" "const char * name" +.Ft int +.Fn fdt_pinctrl_register "device_t pinctrl" "const char *pinprop" +.Ft int +.Fn fdt_pinctrl_configure_tree "device_t pinctrl" +.Sh DESCRIPTION +.Xr fdt_pinctrl 4 +provides an API for manipulating I/O pin configurations on +pinmux controllers and pinmux clients. +On the controller side, the standard newbus probe and +attach methods are implemented. +As part of handling attach, it calls the +.Fn fdt_pinctrl_register +function to register itself as a pinmux controller. +Then +.Fn fdt_pinctrl_configure_tree +is used to walk the device tree and configure pins specified by the pinctrl-0 +property for all active devices. +The driver also implements the +.Fn fdt_pinctrl_configure +method, which allows client devices to change their +pin configurations after startup. +If a client device requires a pin configuration change at some +point of its lifecycle, it uses the +.Fn fdt_pinctrl_configure +or +.Fn fdt_pinctrl_configure_by_name +functions. +.Pp +.Fn fdt_pinctrl_configure +is used by client device +.Fa client +to request a pin configuration +described by the pinctrl-N property with index +.Fa index . +.Pp +.Fn fdt_pinctrl_configure_by_name +is used by client device +.Fa client +to request the pin configuration with name +.Fa name . +.Pp +.Fn fdt_pinctrl_register +registers a pinctrl driver so that it can be used by other devices which call +.Fn fdt_pinctrl_configure +or +.Fn fdt_pinctrl_configure_by_name . +It also registers each child node of the pinctrl driver's node which contains +a property with the name given in +.Fa pinprop . +If +.Fa pinprop +is +.Dv NULL , +every descendant node is registered. +It is possible for the driver to register itself +as a pinmux controller for more than one pin property type +by calling +.Fn fdt_pinctrl_register +multiple types. +.Pp +.Fn fdt_pinctrl_configure_tree +walks through enabled devices in the device tree. +If the pinctrl-0 property contains references +to child nodes of the specified pinctrl device, +their pins are configured. +.Sh EXAMPLES +.Bd -literal +static int +foo_configure_pins(device_t dev, phandle_t cfgxref) +{ + phandle_t cfgnode; + uint32_t *pins, *functions; + int npins, nfunctions; + + cfgnode = OF_node_from_xref(cfgxref); + pins = NULL; + npins = OF_getencprop_alloc_multi(cfgnode, "foo,pins", sizeof(*pins), + (void **)&pins); + functions = NULL; + nfunctions = OF_getencprop_alloc_multi(cfgnode, "foo,functions", + sizeof(*functions), (void **)&functions); + ... +} + +static int +foo_is_gpio(device_t dev, device_t gpiodev, bool *is_gpio) +{ + return (foo_is_pin_func_gpio(is_gpio)); +} + +static int +foo_set_flags(device_t dev, device_t gpiodev, uint32_t pin, uint32_t flags) +{ + int rv; + + rv = foo_is_pin_func_gpio(is_gpio); + if (rv != 0) + return (rv); + foo_set_flags(pin, flags); + return (0); +} + +static int +foo_get_flags(device_t dev, device_t gpiodev, uint32_t pin, uint32_t *flags) +{ + int rv; + + rv = foo_is_pin_func_gpio(is_gpio); + if (rv != 0) + return (rv); + foo_get_flags(pin, flags); + return (0); +} + +static int +foo_attach(device_t dev) +{ + ... + + fdt_pinctrl_register(dev, "foo,pins"); + /* + * It is possible to register more than one pinprop handler + */ + fdt_pinctrl_register(dev, "bar,pins"); + fdt_pinctrl_configure_tree(dev); + + return (0); +} + +static device_method_t foo_methods[] = { + ... + + /* fdt_pinctrl interface */ + DEVMETHOD(fdt_pinctrl_configure, foo_configure_pins), + DEVMETHOD(fdt_pinctrl_is_gpio, foo_is_gpio), + DEVMETHOD(fdt_pinctrl_set_flags, foo_set_flags), + DEVMETHOD(fdt_pinctrl_get_flags, foo_get_flags), + + /* Terminate method list */ + DEVMETHOD_END +}; + +DRIVER_MODULE(foo, simplebus, foo_driver, foo_devclass, NULL, NULL); +.Ed +.Sh SEE ALSO +.Xr fdt_pinctrl 4 +.Sh AUTHORS +This manual page was written by +.An Oleksandr Tymoshenko . diff --git a/static/freebsd/man9/fetch.9 b/static/freebsd/man9/fetch.9 new file mode 100644 index 00000000..c544ec80 --- /dev/null +++ b/static/freebsd/man9/fetch.9 @@ -0,0 +1,140 @@ +.\" $NetBSD: fetch.9,v 1.2 1996/01/09 21:59:24 perry Exp $ +.\" +.\" Copyright (c) 1996 Jason R. Thorpe. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed by Kenneth Stailey. +.\" +.\" 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 for the NetBSD Project +.\" by Jason R. Thorpe. +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd July 22, 2021 +.Dt FETCH 9 +.Os +.Sh NAME +.Nm fetch , +.Nm fubyte , +.Nm fuword , +.Nm fuword16 , +.Nm fuword32 , +.Nm fuword64 , +.Nm fueword , +.Nm fueword32 , +.Nm fueword64 +.Nd fetch data from user-space +.Sh SYNOPSIS +.In sys/types.h +.In sys/systm.h +.Ft int +.Fn fubyte "volatile const void *base" +.Ft long +.Fn fuword "volatile const void *base" +.Ft int +.Fn fuword16 "volatile const void *base" +.Ft int32_t +.Fn fuword32 "volatile const void *base" +.Ft int64_t +.Fn fuword64 "volatile const void *base" +.Ft int +.Fn fueword "volatile const void *base" "long *val" +.Ft int +.Fn fueword32 "volatile const void *base" "int32_t *val" +.Ft int +.Fn fueword64 "volatile const void *base" "int64_t *val" +.Sh DESCRIPTION +The +.Nm +functions are designed to copy small amounts of data from user-space +of the current process. +If the user address is naturally aligned, then the operation will be +performed atomically. +Otherwise it may fail or be performed non-atomically, depending on +the platform. +.Pp +The +.Nm +routines provide the following functionality: +.Bl -tag -width "fueword32()" +.It Fn fubyte +Fetches a byte of data from the user-space address +.Pa base . +The byte read is zero-extended into the results variable. +.It Fn fuword +Fetches a word of data (long) from the user-space address +.Pa base . +.It Fn fuword16 +Fetches 16 bits of data from the user-space address +.Pa base . +The half-word read is zero-extended into the results variable. +.It Fn fuword32 +Fetches 32 bits of data from the user-space address +.Pa base . +.It Fn fuword64 +Fetches 64 bits of data from the user-space address +.Pa base . +.It Fn fueword +Fetches a word of data (long) from the user-space address +.Pa base +and stores the result in the variable pointed by +.Pa val . +.It Fn fueword32 +Fetches 32 bits of data from the user-space address +.Pa base +and stores the result in the variable pointed by +.Pa val . +.It Fn fueword64 +Fetches 64 bits of data from the user-space address +.Pa base +and stores the result in the variable pointed by +.Pa val . +.El +.Pp +The callers of +.Fn fuword , +.Fn fuword32 +and +.Fn fuword64 +functions cannot distinguish between -1 read from +userspace and function failure. +.Sh RETURN VALUES +The +.Fn fubyte , +.Fn fuword , +.Fn fuword16 , +.Fn fuword32 , +and +.Fn fuword64 +functions return the data fetched or -1 on failure. +The +.Fn fueword , +.Fn fueword32 +and +.Fn fueword64 +functions return 0 on success and -1 on failure. +.Sh SEE ALSO +.Xr copy 9 , +.Xr store 9 diff --git a/static/freebsd/man9/firmware.9 b/static/freebsd/man9/firmware.9 new file mode 100644 index 00000000..43f965a2 --- /dev/null +++ b/static/freebsd/man9/firmware.9 @@ -0,0 +1,385 @@ +.\" Copyright (c) 2006 Max Laier +.\" 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 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 25, 2024 +.Dt FIRMWARE 9 +.Os +.Sh NAME +.Nm firmware_register , +.Nm firmware_unregister , +.Nm firmware_get , +.Nm firmware_get_flags , +.Nm firmware_put +.Nd firmware image loading and management +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.In sys/linker.h +.In sys/firmware.h +.Bd -literal +struct firmware { + const char *name; /* system-wide name */ + const void *data; /* location of image */ + size_t datasize; /* size of image in bytes */ + unsigned int version; /* version of the image */ +}; +.Ed +.Ft "const struct firmware *" +.Fo firmware_register +.Fa "const char *imagename" +.Fa "const void *data" +.Fa "size_t datasize" +.Fa "unsigned int version" +.Fa "const struct firmware *parent" +.Fc +.Ft int +.Fn firmware_unregister "const char *imagename" +.Ft "const struct firmware *" +.Fn firmware_get "const char *imagename" +.Ft "const struct firmware *" +.Fn firmware_get_flags "const char *imagename" "uint32_t flags" +.Ft void +.Fn firmware_put "const struct firmware *fp" "int flags" +.Sh DESCRIPTION +The +.Nm firmware +abstraction provides a convenient interface for loading +.Nm firmware images +into the kernel, and for accessing such images from kernel components. +.Pp +A +.Nm firmware image +(or +.Nm image +for brevity) +is an opaque block of data residing in kernel memory. +It is associated to a unique +.Nm imagename +which constitutes a search key, and to an integer +.Nm version +number, which is also an opaque piece of information for the +firmware subsystem. +.Pp +An image is registered with the +.Nm firmware +subsystem by calling the function +.Fn firmware_register , +and unregistered by calling +.Fn firmware_unregister . +These functions are usually (but not exclusively) called by +specially crafted kernel modules that contain the firmware image. +The modules can be statically compiled in the kernel, or loaded by +.Pa /boot/loader , +manually at runtime, or on demand by the firmware subsystem. +.Pp +Firmware binary files may also be loaded directly rather than embedded into +kernel modules. +.Pp +.Nm Clients +of the firmware subsystem can request access to a given image +by calling the function +.Fn firmware_get +with the +.Nm imagename +they want as an argument, or by calling +.Fn firmware_get_flags +with the +.Nm imagename +and +.Nm flags +they want as an arguments. +If a matching image is not already registered, +the firmware subsystem will try to load it using the +mechanisms specified below (typically, a kernel module +with +.Nm +the same name +as the image). +.Sh API DESCRIPTION +The kernel +.Nm +firmware API +is made of the following functions: +.Pp +.Fn firmware_register +registers with the kernel an image of size +.Nm datasize +located at address +.Nm data , +under the name +.Nm imagename . +.Pp +The function returns NULL on error (e.g. because an +image with the same name already exists, or the image +table is full), or a +.Ft const struct firmware * +pointer to the image requested. +.Pp +.Fn firmware_unregister +tries to unregister the firmware image +.Nm imagename +from the system. +The function is successful and returns 0 +if there are no pending references to the image, otherwise +it does not unregister the image and returns EBUSY. +.Pp +.Fn firmware_get +and +.Fn firmware_get_flags +return the requested firmware image. +The +.Fa flags +argument may be set to +.Dv FIRMWARE_GET_NOWARN +to indicate that errors on firmware load or registration should +only be logged in case of +.Nm booverbose . +If the image is not yet registered with the system, +the functions try to load it. +This involves the linker subsystem and disk access, so +.Fn firmware_get +or +.Fn firmware_get_flags +must not be called with any locks (except for +.Va Giant ) . +Note also that if the firmware image is loaded from a filesystem +it must already be mounted. +In particular this means that it may be necessary to defer requests +from a driver attach method unless it is known the root filesystem is +already mounted. +.Pp +On success, +.Fn firmware_get +and +.Fn firmware_get_flags +return a pointer to the image description and increase the reference count +for this image. +On failure, the functions return NULL. +.Pp +.Fn firmware_put +drops a reference to a firmware image. +The +.Fa flags +argument may be set to +.Dv FIRMWARE_UNLOAD +to indicate that +firmware_put is free to reclaim resources associated with +the firmware image if this is the last reference. +By default a firmware image will be deferred to a +.Xr taskqueue 9 +thread so the call may be done while holding a lock. +In certain cases, such as on driver detach, this cannot be allowed. +.Sh FIRMWARE LOADING VIA MODULES +As mentioned before, any component of the system can register +firmware images at any time by simply calling +.Fn firmware_register . +.Pp +This is typically done when a module containing +a firmware image is given control, +whether compiled in, or preloaded by +.Pa /boot/loader , +or manually loaded with +.Xr kldload 8 . +However, a system can implement additional mechanisms to bring +these images into memory before calling +.Fn firmware_register . +.Pp +When +.Fn firmware_get +or +.Fn firmware_get_flags +does not find the requested image, it tries to load it using +one of the available loading mechanisms. +At the moment, there is only one, namely +.Nm Loadable kernel modules . +.Pp +A firmware image named +.Nm foo +is looked up by trying to load the module named +.Nm foo.ko , +using the facilities described in +.Xr kld 4 . +In particular, images are looked up in the directories specified +by the sysctl variable +.Nm kern.module_path +which on most systems defaults to +.Pa /boot/kernel;/boot/modules . +.Pp +Note that in case a module contains multiple images, +the caller should first request a +.Fn firmware_get +or +.Fn firmware_get_flags +for the first image contained in the module, followed by requests +for the other images. +.Sh BUILDING FIRMWARE LOADABLE MODULES +A firmware module is built by embedding the +.Nm firmware image +into a suitable loadable kernel module that calls +.Fn firmware_register +on loading, and +.Fn firmware_unregister +on unloading. +.Pp +Various system scripts and makefiles let you build a module +by simply writing a Makefile with the following entries: +.Bd -literal + + KMOD= imagename + FIRMWS= image_file:imagename[:version] + .include + +.Ed +where KMOD is the basename of the module; FIRMWS is a list of +colon-separated tuples indicating the image_file's to be embedded +in the module, the imagename and version of each firmware image. +.Pp +If you need to embed firmware images into a system, you should write +appropriate entries in the or file, e.g. this example is +from +.Nm sys/conf/files +.Bd -literal +iwn1000fw.c optional iwn1000fw | iwnfw \\ + compile-with "${AWK} -f $S/tools/fw_stub.awk iwn1000.fw:iwn1000fw -miwn1000fw -c${.TARGET}" \\ + no-ctfconvert no-implicit-rule before-depend local \\ + clean "iwn1000fw.c" +# +# NB: ld encodes the path in the binary symbols generated for the +# firmware image so link the file to the object directory to +# get known values for reference in the _fw.c file. +# +iwn1000fw.fwo optional iwn1000fw | iwnfw \\ + dependency "iwn1000.fw" \\ + compile-with "${NORMAL_FWO}" \\ + no-implicit-rule \\ + clean "iwn1000fw.fwo" +.Ed +.Pp +Firmware was previously committed to the source tree as uuencoded files, +but this is no longer required; the binary firmware file should be committed +to the tree as provided by the vendor. +.Pp +Note that generating the firmware modules in this way requires +the availability of the following tools: +.Xr awk 1 , +.Xr make 1 , +the compiler and the linker. +.Sh LOADING BINARY FIRMWARE FILES +.Ss Binary Firmware Format +Binary firmware files can also be loaded, either from +.Pa /boot/loader , +or when +.Nm firmware_get +cannot find the registered firmware from a kernel module. +Binary firmware files are raw binary files that the creator of the firmware +made. +They offer an easier way to load firmware, but one that lacks the full +flexibility and generality of kernel modules with the following restrictions: +.Bl -bullet -compact +.It +Binary firmware files only hold one set of firmware. +.It +They do not offer kernel module dependencies to ensure they are loaded +automatically by the boot loader. +.It +They cannot be compiled into the kernel. +.It +The +.Nm imagename +is identical to the full path name used to load the module. +.It +The version number is assumed to be zero. +.El +.Ss Loading from Pa /boot/loader +Binary firmware files may be loaded either from the command line with +.Dq load -t firmware /boot/firmware/filename +or using the +.Xr loader.conf 5 +mechanism to load modules with a type of +.Dq firmware +For example +.Bd -literal +wififw_load="YES" +wififw_name="/boot/firmware/wifi2034_fw.bin" +wififw_type="firmware" +.Ed +.Ss On demand loading from Nm firmware_get +If no kernel module with an embedded firmware image named +.Nm imagename +is loaded, then +.Nm imagename +will be appended to the module path (by default +.Pa /boot/firmware/ ) +and if that file exists, it will be loaded and registered using +.Nm firmware_register +using the full path to the filename as +.Nm imagename . +.Ss Searching for imagename +.Nm firmware_get +uses the following algorithm to find firmware images: +.Bl -bullet -compact +.It +If an existing firmware image is registered for +.Fa imagename, +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 +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. +If a match is found, the matching image is returned. +.It +The kernel searches for a file named +.Fa imagename +in the firmware image path +(by default +.Pa /boot/firmware/ ) . +If that file exists and can be read, +it contents are registered as a firmware image with the full path as the +.Nm imagename +and that firmware is returned. +Currently, there is an 8MB limit on the size of the firmware image. +This can be changed by by the sysctl variable +.Nm debug.max_firmware_size . +.El +.Sh SEE ALSO +.Xr kld 4 , +.Xr module 9 +.Pp +.Pa /boot/firmware +.Pp +.Pa /usr/share/examples/kld/firmware +.Sh HISTORY +The +.Nm firmware +system was introduced in +.Fx 6.1 . +Binary firmware loading was introduced in +.Fx 15.0 . +.Sh AUTHORS +This manual page was written by +.An Max Laier Aq Mt mlaier@FreeBSD.org . diff --git a/static/freebsd/man9/fpu_kern.9 b/static/freebsd/man9/fpu_kern.9 new file mode 100644 index 00000000..92dc0eaa --- /dev/null +++ b/static/freebsd/man9/fpu_kern.9 @@ -0,0 +1,216 @@ +.\" Copyright (c) 2014 +.\" Konstantin Belousov . 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 ``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 October 13, 2020 +.Dt FPU_KERN 9 +.Os +.Sh NAME +.Nm fpu_kern +.Nd "facility to use the FPU in the kernel" +.Sh SYNOPSIS +.In machine/fpu.h +.Ft struct fpu_kern_ctx * +.Fn fpu_kern_alloc_ctx "u_int flags" +.Ft void +.Fn fpu_kern_free_ctx "struct fpu_kern_ctx *ctx" +.Ft void +.Fn fpu_kern_enter "struct thread *td" "struct fpu_kern_ctx *ctx" "u_int flags" +.Ft int +.Fn fpu_kern_leave "struct thread *td" "struct fpu_kern_ctx *ctx" +.Ft int +.Fn fpu_kern_thread "u_int flags" +.Ft int +.Fn is_fpu_kern_thread "u_int flags" +.Sh DESCRIPTION +The +.Nm +family of functions allows the use of FPU hardware in kernel code. +Modern FPUs are not limited to providing hardware implementation for +floating point arithmetic; they offer advanced accelerators for cryptography +and other computational-intensive algorithms. +These facilities share registers with the FPU hardware. +.Pp +Typical kernel code does not need access to the FPU. +Saving a large register file on each entry to the kernel would waste +time. +When kernel code uses the FPU, the current FPU state must be saved to +avoid corrupting the user-mode state, and vice versa. +.Pp +The management of the save and restore is automatic. +The processor catches accesses to the FPU registers +when the non-current context tries to access them. +Explicit calls are required for the allocation of the save area and +the notification of the start and end of the code using the FPU. +.Pp +The +.Fn fpu_kern_alloc_ctx +function allocates the memory used by +.Nm +to track the use of the FPU hardware state and the related software state. +The +.Fn fpu_kern_alloc_ctx +function requires the +.Fa flags +argument, which currently accepts the following flags: +.Bl -tag -width ".Dv FPU_KERN_NOWAIT" -offset indent +.It Dv FPU_KERN_NOWAIT +Do not wait for the available memory if the request could not be satisfied +without sleep. +.It 0 +No special handling is required. +.El +.Pp +The function returns the allocated context area, or +.Va NULL +if the allocation failed. +.Pp +The +.Fn fpu_kern_free_ctx +function frees the context previously allocated by +.Fn fpu_kern_alloc_ctx . +.Pp +The +.Fn fpu_kern_enter +function designates the start of the region of kernel code where the +use of the FPU is allowed. +Its arguments are: +.Bl -tag -width ".Fa ctx" -offset indent +.It Fa td +Currently must be +.Va curthread . +.It Fa ctx +The context save area previously allocated by +.Fn fpu_kern_alloc_ctx +and not currently in use by another call to +.Fn fpu_kern_enter . +.It Fa flags +This argument currently accepts the following flags: +.Bl -tag -width ".Dv FPU_KERN_NORMAL" -offset indent +.It Dv FPU_KERN_NORMAL +Indicates that the caller intends to access the full FPU state. +Must be specified currently. +.It Dv FPU_KERN_KTHR +Indicates that no saving of the current FPU state should be performed, +if the thread called +.Xr fpu_kern_thread 9 +function. +This is intended to minimize code duplication in callers which +could be used from both kernel thread and syscall contexts. +The +.Fn fpu_kern_leave +function correctly handles such contexts. +.It Dv FPU_KERN_NOCTX +Avoid nesting save area. +If the flag is specified, the +.Fa ctx +must be passed as +.Va NULL . +The flag should only be used for really short code blocks +which can be executed in a critical section. +It avoids the need to allocate the FPU context by the cost +of increased system latency. +.El +.El +.Pp +The function does not sleep or block. +It could cause an FPU trap during execution, and on the first FPU access +after the function returns, as well as after each context switch. +On i386 and amd64 this will be the +.Nm Device Not Available +exception (see Intel Software Developer Manual for the reference). +.Pp +The +.Fn fpu_kern_leave +function ends the region started by +.Fn fpu_kern_enter . +It is erroneous to use the FPU in the kernel before +.Fn fpu_kern_enter +or after +.Fn fpu_kern_leave . +The function takes the +.Fa td +thread argument, which currently must be +.Va curthread , +and the +.Fa ctx +context pointer, previously passed to +.Fn fpu_kern_enter . +After the function returns, the context may be freed or reused +by another invocation of +.Fn fpu_kern_enter . +The function always returns 0. +.Pp +The +.Fn fpu_kern_thread +function enables an optimization for threads which never leave to +the usermode. +The current thread will reuse the usermode save area for the kernel FPU state +instead of requiring an explicitly allocated context. +There are no flags defined for the function, and no error states +that the function returns. +Once this function has been called, neither +.Fn fpu_kern_enter +nor +.Fn fpu_kern_leave +is required to be called and the fpu is available for use in the calling thread. +.Pp +The +.Fn is_fpu_kern_thread +function returns the boolean indicating whether the current thread +entered the mode enabled by +.Fn fpu_kern_thread . +There is currently no flags defined for the function, the return +value is true if the current thread have the permanent FPU save area, +and false otherwise. +.Sh NOTES +The +.Nm +is currently implemented only for the i386, amd64, arm64, and powerpc +architectures. +.Pp +There is no way to handle floating point exceptions raised from +kernel mode. +.Pp +The unused +.Fa flags +arguments +to the +.Nm +functions are to be extended to allow specification of the +set of the FPU hardware state used by the code region. +This would allow optimizations of saving and restoring the state. +.Sh AUTHORS +The +.Nm +facitily and this manual page were written by +.An Konstantin Belousov Aq Mt kib@FreeBSD.org . +The arm64 support was added by +.An Andrew Turner Aq Mt andrew@FreeBSD.org . +The powerpc support was added by +.An Shawn Anastasio Aq Mt sanastasio@raptorengineering.com . +.Sh BUGS +.Fn fpu_kern_leave +should probably have type +.Ft void +(like +.Fn fpu_kern_enter ) . diff --git a/static/freebsd/man9/g_access.9 b/static/freebsd/man9/g_access.9 new file mode 100644 index 00000000..ef90af07 --- /dev/null +++ b/static/freebsd/man9/g_access.9 @@ -0,0 +1,163 @@ +.\" +.\" Copyright (c) 2004 Pawel Jakub Dawidek +.\" 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 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 16, 2004 +.Dt G_ACCESS 9 +.Os +.Sh NAME +.Nm g_access +.Nd "control access to GEOM consumers and their providers" +.Sh SYNOPSIS +.In geom/geom.h +.Ft int +.Fn g_access "struct g_consumer *cp" "int dcr" "int dcw" "int dce" +.Sh DESCRIPTION +The +.Fn g_access +function allows to open, close, and generally change access to the provider +which is attached to the given consumer +.Fa cp . +The arguments +.Fa dcr , +.Fa dcw , +and +.Fa dce +represent relative read, write, and exclusive access count changes. +Read and write access counts are self explanatory, and +exclusive access counts deny write access to other interested parties. +A provider's access count is the sum of the access counts of all +attached consumers. +.Pp +After attaching a consumer to a provider with +.Xr g_attach 9 , +the +.Fn g_access +function has to be called on the consumer before starting I/O requests. +.Sh RESTRICTIONS/CONDITIONS +The consumer has to be attached to a provider. +.Pp +The intended change must not result in a negative access count. +.Pp +No-operation is not permitted +.Fa ( dcr += +.Fa dcw += +.Fa dce += +.Li 0 ) . +.Pp +The provider's geom must have an access method defined (e.g., +.Va gp->access ) . +.Pp +The topology lock has to be held. +.Sh RETURN VALUES +The +.Fn g_access +function returns 0 if successful; otherwise an error code is returned. +Note that +.Fn g_access +cannot fail when the arguments +.Fa dcr , +.Fa dcw , +and +.Fa dce +are less than or equal to 0. +.Sh EXAMPLES +Create a consumer, attach it to a given provider, gain read access and +read first sector. +.Bd -literal -offset indent +void +some_function(struct g_geom *mygeom, struct g_provider *pp) +{ + struct g_consumer *cp; + void *ptr; + int error; + + g_topology_assert(); + + /* Create new consumer on 'mygeom' geom. */ + cp = g_new_consumer(mygeom); + /* Attach newly created consumer to given provider. */ + if (g_attach(cp, pp) != 0) { + g_destroy_consumer(cp); + return; + } + /* Open provider for reading through our consumer. */ + error = g_access(cp, 1, 0, 0); + if (error != 0) { + printf("Cannot access provider: %s\\n", error); + g_detach(cp); + g_destroy_consumer(cp); + return; + } + + /* + * Don't hold topology lock while reading. + */ + g_topology_unlock(); + ptr = g_read_data(cp, 0, pp->sectorsize, &error); + if (ptr == NULL) + printf("Error while reading: %d\\n", error); + /* + * Do something useful with data. + */ + g_topology_lock(); + + /* Disconnect from provider (release access count). */ + g_access(cp, -1, 0, 0); + /* Detach from provider. */ + g_detach(cp); + /* Destroy consumer. */ + g_destroy_consumer(cp); +} +.Ed +.Sh ERRORS +Possible errors: +.Bl -tag -width Er +.It Bq Er EPERM +The function is trying to open a provider with an exclusive access count, but +it is already open for writing. +.It Bq Er EPERM +The function is trying to open a provider for writing, but it is already +exclusively open. +.El +.Pp +Any other error that can be returned by the provider's access method. +.Sh SEE ALSO +.Xr geom 4 , +.Xr DECLARE_GEOM_CLASS 9 , +.Xr g_attach 9 , +.Xr g_bio 9 , +.Xr g_consumer 9 , +.Xr g_data 9 , +.Xr g_event 9 , +.Xr g_geom 9 , +.Xr g_provider 9 , +.Xr g_provider_by_name 9 , +.Xr g_wither_geom 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . diff --git a/static/freebsd/man9/g_attach.9 b/static/freebsd/man9/g_attach.9 new file mode 100644 index 00000000..92f801c5 --- /dev/null +++ b/static/freebsd/man9/g_attach.9 @@ -0,0 +1,141 @@ +.\" +.\" Copyright (c) 2004 Pawel Jakub Dawidek +.\" 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 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 October 10, 2020 +.Dt G_ATTACH 9 +.Os +.Sh NAME +.Nm g_attach , +.Nm g_detach +.Nd "attach/detach GEOM consumers to/from providers" +.Sh SYNOPSIS +.In geom/geom.h +.Ft int +.Fn g_attach "struct g_consumer *cp" "struct g_provider *pp" +.Ft void +.Fn g_detach "struct g_consumer *cp" +.Sh DESCRIPTION +The +.Fn g_attach +function attaches given consumer +.Fa cp +to given provider +.Fa pp , +thus establishing a communication channel between the consumer and the +provider that allows to change access counts and perform I/O operations. +.Pp +The +.Fn g_detach +function detaches given consumer +.Fa cp +from its corresponding provider, tearing down the communication channel +between them. +.Sh RESTRICTIONS/CONDITIONS +.Fn g_attach : +.Bl -item -offset indent +.It +The consumer must not be attached to a provider. +.It +The operation must not create a topology loop. +.It +The topology lock has to be held. +.El +.Pp +.Fn g_detach : +.Bl -item -offset indent +.It +The consumer has to be attached. +.It +The access count has to be 0. +.It +There must be no active requests. +.It +The topology lock has to be held. +.El +.Sh RETURN VALUES +The +.Fn g_attach +function returns 0 if successful; otherwise an error code is returned. +.Sh EXAMPLES +Create a consumer, attach it to a given provider, gain read access and clean up. +.Bd -literal -offset indent +void +some_function(struct g_geom *mygeom, struct g_provider *pp) +{ + struct g_consumer *cp; + + g_topology_assert(); + + /* Create new consumer on 'mygeom' geom. */ + cp = g_new_consumer(mygeom); + /* Attach newly created consumer to given provider. */ + if (g_attach(cp, pp) != 0) { + g_destroy_consumer(cp); + return; + } + /* Open provider for reading through our consumer. */ + if (g_access(cp, 1, 0, 0) != 0) { + g_detach(cp); + g_destroy_consumer(cp); + return; + } + + g_topology_unlock(); + /* + * Read data from provider. + */ + g_topology_lock(); + + /* Disconnect from provider (release access count). */ + g_access(cp, -1, 0, 0); + /* Detach from provider. */ + g_detach(cp); + /* Destroy consumer. */ + g_destroy_consumer(cp); +} +.Ed +.Sh ERRORS +Possible errors: +.Bl -tag -width Er +.It Bq Er ELOOP +The operation creates a topology loop. +.It Bq Er ENXIO +Provider got orphaned. +.El +.Sh SEE ALSO +.Xr geom 4 , +.Xr DECLARE_GEOM_CLASS 9 , +.Xr g_access 9 , +.Xr g_bio 9 , +.Xr g_consumer 9 , +.Xr g_data 9 , +.Xr g_event 9 , +.Xr g_geom 9 , +.Xr g_provider 9 , +.Xr g_provider_by_name 9 , +.Xr g_wither_geom 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . diff --git a/static/freebsd/man9/g_bio.9 b/static/freebsd/man9/g_bio.9 new file mode 100644 index 00000000..fc278cd2 --- /dev/null +++ b/static/freebsd/man9/g_bio.9 @@ -0,0 +1,327 @@ +.\" +.\" Copyright (c) 2004-2006 Pawel Jakub Dawidek +.\" 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 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 October 26, 2025 +.Dt G_BIO 9 +.Os +.Sh NAME +.Nm g_new_bio , +.Nm g_clone_bio , +.Nm g_destroy_bio , +.Nm g_format_bio , +.Nm g_print_bio , +.Nm g_reset_bio +.Nd "GEOM bio controlling functions" +.Sh SYNOPSIS +.In sys/bio.h +.In geom/geom.h +.Ft "struct bio *" +.Fn g_new_bio void +.Ft "struct bio *" +.Fn g_alloc_bio void +.Ft "struct bio *" +.Fn g_clone_bio "struct bio *bp" +.Ft "struct bio *" +.Fn g_duplicate_bio "struct bio *bp" +.Ft void +.Fn g_destroy_bio "struct bio *bp" +.Ft void +.Fn g_format_bio "struct sbuf *sb" "const struct bio *bp" +.Ft void +.Fo g_print_bio +.Fa "struct sbuf *sb" "const char *prefix" "const struct bio *bp" +.Fa "const char *fmtsuffix" ... +.Fc +.Ft void +.Fn g_reset_bio "struct bio *bp" +.Sh DESCRIPTION +A +.Vt "struct bio" +is used by GEOM to describe I/O requests, its +most important fields are described below: +.Bl -tag -width ".Va bio_attribute" +.It Va bio_cmd +I/O request command. +There are five I/O requests available in GEOM: +.Bl -tag -width ".Dv BIO_GETATTR" +.It Dv BIO_READ +A read request. +.It Dv BIO_WRITE +A write request. +.It Dv BIO_DELETE +Indicates that a certain range of data is no longer used and that +it can be erased or freed as the underlying technology supports. +Technologies like flash adaptation layers can arrange to erase the relevant +blocks before they will become reassigned and cryptographic devices may +want to fill random bits into the range to reduce the amount of data +available for attack. +.It Dv BIO_GETATTR +Inspect and manipulate out-of-band +attributes on a particular provider or path. +Attributes are named by ascii strings and are stored in the +.Va bio_attribute +field. +.It Dv BIO_FLUSH +Tells underlying providers to flush their write caches. +.El +.It Va bio_flags +Available flags: +.Bl -tag -width ".Dv BIO_ERROR" +.It Dv BIO_ERROR +Request failed (error value is stored in +.Va bio_error +field). +.It Dv BIO_DONE +Request finished. +.El +.It Va bio_cflags +Private use by the consumer. +.It Va bio_pflags +Private use by the provider. +.It Va bio_offset +Offset into provider. +.It Va bio_data +Pointer to data buffer. +.It Va bio_error +Error value when +.Dv BIO_ERROR +is set. +.It Va bio_done +Pointer to function which will be called when the request is finished. +.It Va bio_driver1 +Private use by the provider. +.It Va bio_driver2 +Private use by the provider. +.It Va bio_caller1 +Private use by the consumer. +.It Va bio_caller2 +Private use by the consumer. +.It Va bio_attribute +Attribute string for +.Dv BIO_GETATTR +request. +.It Va bio_from +Consumer to use for request (attached to provider stored in +.Va bio_to +field) (typically read-only for a class). +.It Va bio_to +Destination provider (typically read-only for a class). +.It Va bio_length +Request length in bytes. +.It Va bio_completed +Number of bytes completed, but they may not be completed from +the front of the request. +.It Va bio_children +Number of +.Vt bio +clones (typically read-only for a class). +.It Va bio_inbed +Number of finished +.Vt bio +clones. +.It Va bio_parent +Pointer to parent +.Vt bio . +.El +.Pp +The +.Fn g_new_bio +function allocates a new, empty +.Vt bio +structure. +.Pp +.Fn g_alloc_bio +- same as +.Fn g_new_bio , +but always succeeds (allocates bio with the +.Dv M_WAITOK +malloc flag). +.Pp +The +.Fn g_clone_bio +function allocates a new +.Vt bio +structure and copies the following fields from the +.Vt bio +given as an argument to clone: +.Va bio_cmd , +.Va bio_length , +.Va bio_offset , +.Va bio_data , +.Va bio_attribute . +The field +.Va bio_parent +in the clone points to the passed +.Vt bio +and the field +.Va bio_children +in the passed +.Vt bio +is incremented. +.Pp +This function should be used for every request which enters through +the provider of a particular geom and needs to be scheduled down. +Proper order is: +.Pp +.Bl -enum -compact +.It +Clone the received +.Vt "struct bio" . +.It +Modify the clone. +.It +Schedule the clone on its own consumer. +.El +.Pp +.Fn g_duplicate_bio +- same as +.Fn g_clone_bio , +but always succeeds (allocates bio with the +.Dv M_WAITOK +malloc flag). +.Pp +The +.Fn g_destroy_bio +function deallocates and destroys the given +.Vt bio +structure. +.Pp +The +.Fn g_format_bio +function prints information about the given +.Vt bio +structure into the provided +.Vt sbuf . +.Pp +The +.Fn g_print_bio +function is a convenience wrapper around +.Fn g_format_bio +that can be used for debugging purposes. +It prints a provided +.Fa prefix +string, followed by the formatted +.Vt bio , +followed by a +.Fa fmtsuffix +in the style of +.Xr printf 9 . +Any of the prefix or suffix strings may be the empty string. +.Fn g_print_bio +always prints a newline character at the end of the line. +.Pp +The +.Fn g_reset_bio +function resets the given +.Vt bio +structure back to its initial state. +.Fn g_reset_bio +preserves internal data structures, while setting all +user visible fields to their initial values. +When reusing a +.Vt bio +obtained from +.Fn g_new_bio , +.Fn g_alloc_bio , +.Fn g_clone_bio , +or +.Fn g_duplicate_bio +for multiple transactions, +.Fn g_reset_bio +must be called between the transactions in lieu of +.Fn bzero . +While not strictly required for a +.Vt bio +structure created by other means, +.Fn g_reset_bio +should be used to initialize it and between transactions. +.Sh RETURN VALUES +The +.Fn g_new_bio +and +.Fn g_clone_bio +functions return a pointer to the allocated +.Vt bio , +or +.Dv NULL +if an error occurred. +.Sh EXAMPLES +Implementation of +.Dq Dv NULL Ns -transformation , +meaning that an I/O request is cloned and scheduled down without any +modifications. +Let us assume that field +.Va ex_consumer +in structure +.Vt example_softc +contains a consumer attached to the provider we want to operate on. +.Bd -literal -offset indent +void +example_start(struct bio *bp) +{ + struct example_softc *sc; + struct bio *cbp; + + g_print_bio("Request received: ", bp, ""); + + sc = bp->bio_to->geom->softc; + if (sc == NULL) { + g_io_deliver(bp, ENXIO); + return; + } + + /* Let's clone our bio request. */ + cbp = g_clone_bio(bp); + if (cbp == NULL) { + g_io_deliver(bp, ENOMEM); + return; + } + cbp->bio_done = g_std_done; /* Standard 'done' function. */ + + /* Ok, schedule it down. */ + /* + * The consumer can be obtained from + * LIST_FIRST(&bp->bio_to->geom->consumer) as well, + * if there is only one in our geom. + */ + g_io_request(cbp, sc->ex_consumer); +} +.Ed +.Sh SEE ALSO +.Xr dtrace_io 4 , +.Xr geom 4 , +.Xr DECLARE_GEOM_CLASS 9 , +.Xr g_access 9 , +.Xr g_attach 9 , +.Xr g_consumer 9 , +.Xr g_data 9 , +.Xr g_event 9 , +.Xr g_geom 9 , +.Xr g_provider 9 , +.Xr g_provider_by_name 9 , +.Xr g_wither_geom 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . diff --git a/static/freebsd/man9/g_consumer.9 b/static/freebsd/man9/g_consumer.9 new file mode 100644 index 00000000..a565b50e --- /dev/null +++ b/static/freebsd/man9/g_consumer.9 @@ -0,0 +1,135 @@ +.\" +.\" Copyright (c) 2004 Pawel Jakub Dawidek +.\" 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 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 16, 2004 +.Dt G_CONSUMER 9 +.Os +.Sh NAME +.Nm g_new_consumer , +.Nm g_destroy_consumer +.Nd "GEOM consumers management" +.Sh SYNOPSIS +.In geom/geom.h +.Ft "struct g_consumer *" +.Fn g_new_consumer "struct g_geom *gp" +.Ft void +.Fn g_destroy_consumer "struct g_consumer *cp" +.Sh DESCRIPTION +A GEOM consumer is the backdoor through which a geom connects to +another GEOM provider and through which I/O requests are sent. +.Pp +The +.Fn g_new_consumer +function creates a new consumer on geom +.Fa gp . +Before using the new consumer, it has to be attached to a provider with +.Xr g_attach 9 +and opened with +.Xr g_access 9 . +.Pp +The +.Fn g_destroy_consumer +function destroys the given consumer and cancels all related pending events. +This function is the last stage of killing an unwanted consumer. +.Sh RESTRICTIONS/CONDITIONS +.Fn g_new_consumer : +.Bl -item -offset indent +.It +The geom +.Fa gp +has to have an +.Va orphan +method defined. +.It +The topology lock has to be held. +.El +.Pp +.Fn g_destroy_consumer : +.Bl -item -offset indent +.It +The consumer must not be attached to a provider. +.It +The access count has to be 0. +.It +The topology lock has to be held. +.El +.Sh RETURN VALUES +The +.Fn g_new_consumer +function +returns a pointer to the newly created consumer. +.Sh EXAMPLES +Create consumer, attach it to given provider, gain read access and clean up. +.Bd -literal -offset indent +void +some_function(struct g_geom *mygeom, struct g_provider *pp) +{ + struct g_consumer *cp; + + g_topology_assert(); + + /* Create new consumer on 'mygeom' geom. */ + cp = g_new_consumer(mygeom); + /* Attach newly created consumer to given provider. */ + if (g_attach(cp, pp) != 0) { + g_destroy_consumer(cp); + return; + } + /* Open provider for reading through our consumer. */ + if (g_access(cp, 1, 0, 0) != 0) { + g_detach(cp); + g_destroy_consumer(cp); + return; + } + + g_topology_unlock(); + /* + * Read data from provider. + */ + g_topology_lock(); + + /* Disconnect from provider (release access count). */ + g_access(cp, -1, 0, 0); + /* Detach from provider. */ + g_detach(cp); + /* Destroy consumer. */ + g_destroy_consumer(cp); +} +.Ed +.Sh SEE ALSO +.Xr geom 4 , +.Xr DECLARE_GEOM_CLASS 9 , +.Xr g_access 9 , +.Xr g_attach 9 , +.Xr g_bio 9 , +.Xr g_data 9 , +.Xr g_event 9 , +.Xr g_geom 9 , +.Xr g_provider 9 , +.Xr g_provider_by_name 9 , +.Xr g_wither_geom 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . diff --git a/static/freebsd/man9/g_data.9 b/static/freebsd/man9/g_data.9 new file mode 100644 index 00000000..716d0be7 --- /dev/null +++ b/static/freebsd/man9/g_data.9 @@ -0,0 +1,122 @@ +.\" +.\" Copyright (c) 2004-2005 Pawel Jakub Dawidek +.\" 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 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 March 30, 2020 +.Dt G_DATA 9 +.Os +.Sh NAME +.Nm g_read_data , +.Nm g_write_data +.Nd "read/write data from/to GEOM consumer" +.Sh SYNOPSIS +.In geom/geom.h +.Ft "void *" +.Fo g_read_data +.Fa "struct g_consumer *cp" "off_t offset" "off_t length" "int *error" +.Fc +.Ft int +.Fo g_write_data +.Fa "struct g_consumer *cp" "off_t offset" "void *ptr" "off_t length" +.Fc +.Sh DESCRIPTION +The +.Fn g_read_data +function reads +.Fa length +bytes of data from the provider attached to consumer +.Fa cp , +starting at offset +.Fa offset . +The buffer returned from +.Fn g_read_data +is allocated with +.Fn g_malloc , +so it should be freed by the caller with +.Fn g_free +after use. +If the operation fails, an error value will be stored in the +.Fa error +argument if it is not +.Dv NULL . +.Pp +The +.Fn g_write_data +function writes +.Fa length +bytes of data from the buffer pointed to by +.Fa ptr +to the provider attached to consumer +.Fa cp , +starting at offset +.Fa offset . +.Sh RESTRICTIONS/CONDITIONS +The +.Fa length +argument +should be a multiple of the provider's sectorsize +and less than or equal to +.Dv DFLTPHYS +.Dv ( DFLTPHYS +is defined in +.In sys/param.h ) . +.Pp +The topology lock must not be held. +.Sh RETURN VALUES +The +.Fn g_read_data +function returns a pointer to a data buffer or +.Dv NULL +if an error occurred. +In that case an error value is stored in the +.Fa error +argument unless it is +.Dv NULL . +.Pp +The +.Fn g_write_data +function returns 0 if successful; otherwise an error code is returned. +.Sh ERRORS +Possible errors: +.Bl -tag -width Er +.It Bq Er EIO +An I/O error occurred while reading from or writing to the consumer. +.It Bq Er EINTEGRITY +Corrupted data was detected while reading from the consumer. +.El +.Sh SEE ALSO +.Xr geom 4 , +.Xr DECLARE_GEOM_CLASS 9 , +.Xr g_access 9 , +.Xr g_attach 9 , +.Xr g_bio 9 , +.Xr g_consumer 9 , +.Xr g_event 9 , +.Xr g_geom 9 , +.Xr g_provider 9 , +.Xr g_provider_by_name 9 , +.Xr g_wither_geom 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . diff --git a/static/freebsd/man9/g_event.9 b/static/freebsd/man9/g_event.9 new file mode 100644 index 00000000..e6fea902 --- /dev/null +++ b/static/freebsd/man9/g_event.9 @@ -0,0 +1,217 @@ +.\" +.\" Copyright (c) 2004 Pawel Jakub Dawidek +.\" 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 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 July 23, 2021 +.Dt G_EVENT 9 +.Os +.Sh NAME +.Nm g_post_event , +.Nm g_waitfor_event , +.Nm g_cancel_event +.Nd "GEOM events management" +.Sh SYNOPSIS +.In geom/geom.h +.Ft int +.Fn g_post_event "g_event_t *func" "void *arg" "int flag" ... +.Ft int +.Fn g_waitfor_event "g_event_t *func" "void *arg" "int flag" ... +.Ft void +.Fn g_cancel_event "void *ref" +.Ft "struct g_event *" +.Fn g_alloc_event "int flag" +.Ft void +.Fn g_post_event_ep "g_event_t *func" "void *arg" "struct g_event *ep" ... +.Sh DESCRIPTION +The GEOM framework has its own event queue to inform classes about important +events. +The event queue can be also used by GEOM classes themselves, for example +to work around some restrictions in the I/O path, where sleeping, heavy weight +tasks, etc.\& are not permitted. +.Pp +The +.Fn g_post_event +function tells the GEOM framework to call function +.Fa func +with argument +.Fa arg +from the event queue. +The +.Fa flag +argument is passed to +.Xr malloc 9 +for memory allocations inside of +.Fn g_post_event . +The only allowed flags are +.Dv M_WAITOK +and +.Dv M_NOWAIT . +The rest of the arguments are used as references to identify the event. +An event can be canceled by using any of the given references as an +argument to +.Fn g_cancel_event . +The list of references has to end with a +.Dv NULL +value. +.Pp +The +.Fn g_waitfor_event +function is a blocking version of the +.Fn g_post_event +function. +It waits until the event is finished or canceled and then returns. +.Pp +The +.Fn g_post_event_ep +function posts the event with a pre-allocated +.Va struct g_event . +An event may be pre-allocated with +.Fn g_alloc_event . +.Pp +The +.Fn g_cancel_event +function cancels all event(s) identified by +.Fa ref . +Cancellation is equivalent to calling the requested function +with requested arguments and argument +.Fa flag +set to +.Dv EV_CANCEL . +.Sh RESTRICTIONS/CONDITIONS +.Fn g_post_event : +.Bl -item -offset indent +.It +The argument +.Fa flag +has to be +.Dv M_WAITOK +or +.Dv M_NOWAIT . +.It +The list of references has to end with a +.Dv NULL +value. +.El +.Pp +.Fn g_waitfor_event : +.Bl -item -offset indent +.It +The argument +.Fa flag +has to be +.Dv M_WAITOK +or +.Dv M_NOWAIT . +.It +The list of references has to end with a +.Dv NULL +value. +.It +The +.Fn g_waitfor_event +function cannot be called from an event, since doing so would result +in a deadlock. +.El +.Pp +.Fn g_alloc_event : +.Bl -item -offset indent +.It +The argument +.Fa flag +has to be +.Dv M_WAITOK +or +.Dv M_NOWAIT . +.It +The returned +.Va struct g_event * +must be freed with +.Fn g_free +if +.Fn g_post_event_ep +is not called. +.El +.Sh RETURN VALUES +The +.Fn g_post_event +and +.Fn g_waitfor_event +functions +return 0 if successful; otherwise an error code is returned. +.Sh EXAMPLES +Example of a function called from the event queue. +.Bd -literal -offset indent +void +example_event(void *arg, int flag) +{ + + if (flag == EV_CANCEL) { + printf("Event with argument %p canceled.\\n", arg); + return; + } + + printf("Event with argument %p called.\\n", arg); +} +.Ed +.Sh ERRORS +Possible errors for the +.Fn g_post_event +function: +.Bl -tag -width Er +.It Bq Er ENOMEM +The +.Fa flag +argument was set to +.Dv M_NOWAIT +and there was insufficient memory. +.El +.Pp +Possible errors for the +.Fn g_waitfor_event +function: +.Bl -tag -width Er +.It Bq Er EAGAIN +The event was canceled. +.It Bq Er ENOMEM +The +.Fa flag +argument was set to +.Dv M_NOWAIT +and there was insufficient memory. +.El +.Sh SEE ALSO +.Xr geom 4 , +.Xr DECLARE_GEOM_CLASS 9 , +.Xr g_access 9 , +.Xr g_attach 9 , +.Xr g_bio 9 , +.Xr g_consumer 9 , +.Xr g_data 9 , +.Xr g_geom 9 , +.Xr g_provider 9 , +.Xr g_provider_by_name 9 , +.Xr g_wither_geom 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . diff --git a/static/freebsd/man9/g_geom.9 b/static/freebsd/man9/g_geom.9 new file mode 100644 index 00000000..99d0ba07 --- /dev/null +++ b/static/freebsd/man9/g_geom.9 @@ -0,0 +1,217 @@ +.\" +.\" Copyright (c) 2004 Pawel Jakub Dawidek +.\" 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 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 April 24, 2016 +.Dt G_GEOM 9 +.Os +.Sh NAME +.Nm g_new_geomf , +.Nm g_new_geom , +.Nm g_destroy_geom +.Nd "geom management" +.Sh SYNOPSIS +.In geom/geom.h +.Ft "struct g_geom *" +.Fn g_new_geomf "struct g_class *mp" "const char *fmt" ... +.Ft "struct g_geom *" +.Fn g_new_geom "struct g_class *mp" "const char *name" +.Ft void +.Fn g_destroy_geom "struct g_geom *gp" +.Sh DESCRIPTION +The geom (do not confuse +.Dq geom +with +.Dq GEOM ) +is an instance of a GEOM class. +For example: in a typical i386 +.Fx +system, there will be one geom +of class MBR for each disk. +The geom's name is not really important, it is only used in the XML +dump and for debugging purposes. +There can be many geoms with the same name. +.Pp +The +.Fn g_new_geomf +function creates a new geom, which will be an instance of the class +.Fa mp . +The geom's name is created in a +.Xr printf 3 Ns +-like way from the rest of the arguments. +.Pp +The +.Fn g_new_geom +function is very similar to +.Fn g_new_geomf +except that it accepts a regular string instead of a +.Xr printf 3 Ns +-like format string as the geom's name. +.Pp +The +.Fn g_destroy_geom +function destroys the given geom immediately and cancels all related pending +events. +.Pp +The +.Vt g_geom +structure +contains fields that should be set by the caller after geom creation, but before +creating any providers or consumers related to this geom (not all are required): +.Bl -tag -offset indent -width indent +.It Vt "g_start_t *" Va start +Pointer to a function used for I/O processing. +.It Vt "g_spoiled_t *" Va spoiled +Pointer to a function used for consumers spoiling. +.It Vt "g_dumpconf_t *" Va dumpconf +Pointer to a function used for configuration in XML format dumping. +.It Vt "g_access_t *" Va access +Pointer to a function used for access control. +.It Vt "g_orphan_t *" Va orphan +Pointer to a function used to inform about orphaned consumer. +.It Vt "g_ioctl_t *" Va ioctl +Pointer to a function used for handling ioctl requests. +.It Vt "void *" Va softc +Field for private use. +.El +.Sh RESTRICTIONS/CONDITIONS +If you intend to use providers in this geom you must set field +.Va start +of your geom. +.Pp +If you are planning to use consumers in your geom you must set fields +.Va orphan +and +.Va access +for it. +.Pp +.Fn g_new_geomf +and +.Fn g_new_geom : +.Bl -item -offset indent +.It +Class +.Fa mp +must be valid (registered in GEOM). +.It +The topology lock has to be held. +.El +.Pp +.Fn g_destroy_geom : +.Bl -item -offset indent +.It +The geom cannot possess any providers. +.It +The geom cannot possess any consumers. +.It +The topology lock has to be held. +.El +.Sh RETURN VALUES +The +.Fn g_new_geomf +function +returns a pointer to the newly created geom. +.Sh EXAMPLES +Create an example geom. +.Bd -literal -offset indent +static void +g_example_start(struct bio *bp) +{ + + [...] +} + +static void +g_example_orphan(struct g_consumer *cp) +{ + + g_topology_assert(); + + [...] +} + +static void +g_example_spoiled(struct g_consumer *cp) +{ + + g_topology_assert(); + + [...] +} + +static int +g_example_access(struct g_provider *pp, int dr, int dw, int de) +{ + + [...] +} + +static struct g_geom * +create_example_geom(struct g_class *myclass) +{ + struct g_geom *gp; + + g_topology_lock(); + gp = g_new_geomf(myclass, "example_geom"); + g_topology_unlock(); + gp->start = g_example_start; + gp->orphan = g_example_orphan; + gp->spoiled = g_example_spoiled; + gp->access = g_example_access; + gp->softc = NULL; + + return (gp); +} + +static int +destroy_example_geom(struct g_geom *gp) +{ + + g_topology_lock(); + if (!LIST_EMPTY(&gp->provider) || + !LIST_EMPTY(&gp->consumer)) { + g_topology_unlock(); + return (EBUSY); + } + g_destroy_geom(gp); + g_topology_unlock(); + + return (0); +} +.Ed +.Sh SEE ALSO +.Xr geom 4 , +.Xr DECLARE_GEOM_CLASS 9 , +.Xr g_access 9 , +.Xr g_attach 9 , +.Xr g_bio 9 , +.Xr g_consumer 9 , +.Xr g_data 9 , +.Xr g_event 9 , +.Xr g_provider 9 , +.Xr g_provider_by_name 9 , +.Xr g_wither_geom 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . diff --git a/static/freebsd/man9/g_provider.9 b/static/freebsd/man9/g_provider.9 new file mode 100644 index 00000000..940772b2 --- /dev/null +++ b/static/freebsd/man9/g_provider.9 @@ -0,0 +1,143 @@ +.\" +.\" Copyright (c) 2004 Pawel Jakub Dawidek +.\" 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 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 16, 2004 +.Dt G_PROVIDER 9 +.Os +.Sh NAME +.Nm g_new_providerf , +.Nm g_destroy_provider , +.Nm g_error_provider +.Nd "GEOM providers management" +.Sh SYNOPSIS +.In geom/geom.h +.Ft "struct g_provider *" +.Fn g_new_providerf "struct g_geom *gp" "const char *fmt" ... +.Ft void +.Fn g_destroy_provider "struct g_provider *pp" +.Ft void +.Fn g_error_provider "struct g_provider *pp" "int error" +.Sh DESCRIPTION +A GEOM provider is the front gate at which a geom offers service. +A provider is +.Dq a disk-like thing which appears in Pa /dev +\[en] a logical disk in other words. +All providers have three main properties: name, sectorsize and size. +.Pp +The +.Fn g_new_providerf +function creates a new provider on given geom +.Fa gp . +The name of the provider, which will appear as device in +.Xr devfs 4 , +is created +in a +.Xr printf 3 Ns +-like way from the rest of +the arguments. +After creation, the caller has to set the provider's +.Va mediasize +and +.Va sectorsize , +as well as other desired initializations, and then call +.Fn g_error_provider +to reset the provider's error, which is initially set to +.Er ENXIO . +.Pp +The +.Fn g_destroy_provider +function destroys the given provider, cancels all related pending events and +removes the corresponding devfs entry. +.Pp +The +.Fn g_error_provider +function is used to set the provider's error value. +If set to a nonzero, all I/O requests will be denied, +as well as increasing its access count will not be possible (error +.Fa error +will be returned). +.Sh RESTRICTIONS/CONDITIONS +.Fn g_new_provider : +.Bl -item -offset indent +.It +The provider name should be unique, but this is not enforced by GEOM. +If the name is not unique, one will end up with two (or more) files +with the same name, which is a programmer error. +.It +The geom +.Fa gp +has to have a +.Fa start +method defined. +.It +The topology lock has to be held. +.El +.Pp +.Fn g_destroy_provider : +.Bl -item -offset indent +.It +The provider must not have consumers attached. +.It +The access count has to be 0. +.It +The topology lock has to be held. +.El +.Sh RETURN VALUES +The +.Fn g_new_providerf +function returns a pointer to the newly created provider. +.Sh EXAMPLES +Create an example provider, set its parameters and make it usable. +.Bd -literal -offset indent +struct g_provider * +create_example_provider(struct g_geom *gp) +{ + struct g_provider *pp; + + g_topology_lock(); + pp = g_new_providerf(gp, "example_provider"); + g_topology_unlock(); + pp->mediasize = 65536; + pp->sectorsize = 512; + g_error_provider(pp, 0); + + return (pp); +} +.Ed +.Sh SEE ALSO +.Xr geom 4 , +.Xr DECLARE_GEOM_CLASS 9 , +.Xr g_access 9 , +.Xr g_attach 9 , +.Xr g_bio 9 , +.Xr g_consumer 9 , +.Xr g_data 9 , +.Xr g_event 9 , +.Xr g_geom 9 , +.Xr g_provider_by_name 9 , +.Xr g_wither_geom 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . diff --git a/static/freebsd/man9/g_provider_by_name.9 b/static/freebsd/man9/g_provider_by_name.9 new file mode 100644 index 00000000..6c7e87c0 --- /dev/null +++ b/static/freebsd/man9/g_provider_by_name.9 @@ -0,0 +1,75 @@ +.\" +.\" Copyright (c) 2004 Pawel Jakub Dawidek +.\" 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 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 29, 2021 +.Dt G_PROVIDER_BY_NAME 9 +.Os +.Sh NAME +.Nm g_provider_by_name +.Nd "find GEOM provider with given name" +.Sh SYNOPSIS +.In geom/geom.h +.Ft "struct g_provider *" +.Fn g_provider_by_name "const char *name" +.Sh DESCRIPTION +The +.Fn g_provider_by_name +function searches for a provider called +.Fa name +and returns the structure +.Vt g_provider +bound to it. +Argument +.Fa name +can be a name or full path (i.e., +.Dq Pa da0 , +or +.Dq Pa /dev/da0 ) . +.Sh RESTRICTIONS/CONDITIONS +The topology lock has to be held. +.Sh RETURN VALUES +The +.Fn g_provider_by_name +function +returns a pointer to the provider called +.Fa name +or +.Dv NULL +if there is no such provider. +.Sh SEE ALSO +.Xr geom 4 , +.Xr DECLARE_GEOM_CLASS 9 , +.Xr g_access 9 , +.Xr g_attach 9 , +.Xr g_bio 9 , +.Xr g_consumer 9 , +.Xr g_data 9 , +.Xr g_event 9 , +.Xr g_geom 9 , +.Xr g_provider 9 , +.Xr g_wither_geom 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . diff --git a/static/freebsd/man9/g_wither_geom.9 b/static/freebsd/man9/g_wither_geom.9 new file mode 100644 index 00000000..4e34cea9 --- /dev/null +++ b/static/freebsd/man9/g_wither_geom.9 @@ -0,0 +1,84 @@ +.\" +.\" Copyright (c) 2004 Pawel Jakub Dawidek +.\" 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 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 16, 2004 +.Dt G_WITHER_GEOM 9 +.Os +.Sh NAME +.Nm g_wither_geom +.Nd "destroy geom and related providers and consumers when you get a chance" +.Sh SYNOPSIS +.In geom/geom.h +.Ft void +.Fn g_wither_geom "struct g_geom *gp" "int error" +.Sh DESCRIPTION +The +.Fn g_wither_geom +function tells GEOM that geom +.Fa gp +is to be destroyed. +GEOM sets an error on each provider of the given geom (in the +orphaning process) and waits for a chance to destroy the geom. +If the access count of any possessed consumer goes to 0, the consumer will be +detached and destroyed automatically. +If the last consumer attached to any possessed provider will be detached, +the provider will be destroyed. +If there are no more providers nor consumers, the geom will be +destroyed. +.Pp +This is an automatic +.Dq garbage collect +to avoid duplicated code in all classes. +Before it is called, field +.Va softc +should be disposed of and set to +.Dv NULL . +Note that the +.Fn g_wither_geom +function gives no guarantee that the geom will be immediately destroyed, mostly +because the access counts of the geom's consumers and providers may not be 0. +That is why calling this function for every geom from a given class is not enough +to be sure that the class can be unloaded. +.Sh RESTRICTIONS/CONDITIONS +The argument +.Fa error +must be nonzero. +.Pp +The topology lock has to be held. +.Sh SEE ALSO +.Xr geom 4 , +.Xr DECLARE_GEOM_CLASS 9 , +.Xr g_access 9 , +.Xr g_attach 9 , +.Xr g_bio 9 , +.Xr g_consumer 9 , +.Xr g_data 9 , +.Xr g_event 9 , +.Xr g_geom 9 , +.Xr g_provider 9 , +.Xr g_provider_by_name 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . diff --git a/static/freebsd/man9/get_cyclecount.9 b/static/freebsd/man9/get_cyclecount.9 new file mode 100644 index 00000000..52242dd5 --- /dev/null +++ b/static/freebsd/man9/get_cyclecount.9 @@ -0,0 +1,87 @@ +.\" Copyright (c) 2000 Mark R V Murray +.\" 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 March 15, 2011 +.Dt GET_CYCLECOUNT 9 +.Os +.Sh NAME +.Nm get_cyclecount +.Nd get the CPU's fast counter register contents +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.In machine/cpu.h +.Ft uint64_t +.Fn get_cyclecount "void" +.Sh DESCRIPTION +The +.Fn get_cyclecount +function uses a register +available in most modern CPUs +to return a value +that is monotonically increasing +inside each CPU. +.Pp +On SMP systems, +there will be a number of +separate monotonic sequences, +one for each CPU running. +The value in the SMP case is +selected from one of these sequences, +dependent on which CPU +was scheduled to service the request. +.Pp +The speed and the maximum value +of each counter +is CPU-dependent. +Some CPUs +(such as the +.Tn Intel +80486) +do not have such a register, +so +.Fn get_cyclecount +on these platforms +returns a (monotonic) combination of numbers +represented by the +structure returned by +.Xr binuptime 9 . +.Pp +The +.Tn AMD64 +and +.Tn Intel 64 +processors use the +.Li TSC +register. +.Sh SEE ALSO +.Xr binuptime 9 +.Sh HISTORY +The +.Fn get_cyclecount +function first appeared in +.Fx 5.0 . +.Sh AUTHORS +This manual page was written by +.An Mark Murray Aq Mt markm@FreeBSD.org . diff --git a/static/freebsd/man9/getenv.9 b/static/freebsd/man9/getenv.9 new file mode 100644 index 00000000..05508148 --- /dev/null +++ b/static/freebsd/man9/getenv.9 @@ -0,0 +1,264 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2013 Hudson River Trading LLC +.\" Written by: John H. Baldwin +.\" 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 September 21, 2020 +.Dt GETENV 9 +.Os +.Sh NAME +.Nm freeenv , +.Nm kern_getenv , +.Nm getenv_int , +.Nm getenv_long , +.Nm getenv_string , +.Nm getenv_quad , +.Nm getenv_uint , +.Nm getenv_ulong , +.Nm getenv_bool , +.Nm getenv_is_true , +.Nm getenv_is_false , +.Nm kern_setenv , +.Nm testenv , +.Nm kern_unsetenv +.Nd kernel environment variable functions +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.Ft void +.Fn freeenv "char *env" +.Ft char * +.Fn kern_getenv "const char *name" +.Ft int +.Fn getenv_int "const char *name" "int *data" +.Ft int +.Fn getenv_long "const char *name" "long *data" +.Ft int +.Fn getenv_string "const char *name" "char *data" "int size" +.Ft int +.Fn getenv_quad "const char *name" "quad_t *data" +.Ft int +.Fn getenv_uint "const char *name" "unsigned int *data" +.Ft int +.Fn getenv_ulong "const char *name" "unsigned long *data" +.Ft int +.Fn getenv_bool "const char *name" "bool *data" +.Ft bool +.Fn getenv_is_true "const char *name" +.Ft bool +.Fn getenv_is_false "const char *name" +.Ft int +.Fn kern_setenv "const char *name" "const char *value" +.Ft int +.Fn testenv "const char *name" +.Ft int +.Fn kern_unsetenv "const char *name" +.Sh DESCRIPTION +These functions set, unset, fetch, and parse variables from the kernel's +environment. +.Pp +The +.Fn kern_getenv +function obtains the current value of the kernel environment variable +.Fa name +and returns a pointer to the string value. +The caller should not modify the string pointed to by the return value. +The +.Fn kern_getenv +function may allocate temporary storage, +so the +.Fn freeenv +function must be called to release any allocated resources when the value +returned by +.Fn kern_getenv +is no longer needed. +.Pp +The +.Fn freeenv +function is used to release the resources allocated by a previous call to +.Fn kern_getenv . +The +.Fa env +argument passed to +.Fn freeenv +is the pointer returned by the earlier call to +.Fn kern_getenv . +Like +.Xr free 3 , +the +.Fa env +argument can be +.Va NULL , +in which case no action occurs. +.Pp +The +.Fn kern_setenv +function inserts or resets the kernel environment variable +.Fa name +to +.Fa value . +If the variable +.Fa name +already exists, +its value is replaced. +This function can fail if an internal limit on the number of environment +variables is exceeded. +.Pp +The +.Fn kern_unsetenv +function deletes the kernel environment variable +.Fa name . +.Pp +The +.Fn testenv +function is used to determine if a kernel environment variable exists. +It returns a non-zero value if the variable +.Fa name +exists and zero if it does not. +.Pp +The +.Fn getenv_int , +.Fn getenv_long , +.Fn getenv_quad , +.Fn getenv_uint , +and +.Fn getenv_ulong +functions look for a kernel environment variable +.Fa name +and parse it as a signed integer, +long integer, +signed 64-bit integer, +unsigned integer, +or an unsigned long integer, +respectively. +These functions fail and return zero if +.Fa name +does not exist or if any invalid characters are present in its value. +On success, +these function store the parsed value in the integer variable pointed to +by +.Fa data . +If the parsed value overflows the integer type, +a truncated value is stored in +.Fa data +and zero is returned. +If the value begins with a prefix of +.Dq 0x +it is interpreted as hexadecimal. +If it begins with a prefix of +.Dq 0 +it is interpreted as octal. +Otherwise, +the value is interpreted as decimal. +The value may contain a single character suffix specifying a unit for +the value. +The interpreted value is multiplied by the unit's magnitude before being +returned. +The following unit suffixes are supported: +.Bl -column -offset indent ".Sy Unit" ".Sy Magnitude" +.It Sy Unit Ta Sy Magnitude +.It k Ta 2^10 +.It m Ta 2^20 +.It g Ta 2^30 +.It t Ta 2^40 +.El +.Pp +The +.Fn getenv_string +function stores a copy of the kernel environment variable +.Fa name +in the buffer described by +.Fa data +and +.Fa size . +If the variable does not exist, +zero is returned. +If the variable exists, +up to +.Fa size - 1 +characters of its value are copied to the buffer pointed to by +.Fa data +followed by a null character and a non-zero value is returned. +.Pp +The +.Fn getenv_bool +function interprets the value of the kernel environment variable +.Fa name +as a boolean value by performing a case-insensitive comparison against the +strings "1", +"0", +"true", +and "false". +If the environment variable exists and has a valid boolean value, then that +value will be copied to the variable pointed to by +.Fa data . +If the environment variable exists but is not a boolean value, then a warning +will be printed to the kernel message buffer. +The +.Fn getenv_is_true +and +.Fn getenv_is_false +functions are wrappers around +.Fn getenv_bool +that simplify testing for a desired boolean value. +.Sh RETURN VALUES +The +.Fn kern_getenv +function returns a pointer to an environment variable's value on success or +.Dv NULL +if the variable does not exist. +.Pp +The +.Fn kern_setenv +and +.Fn kern_unsetenv +functions return zero on success and -1 on failure. +.Pp +The +.Fn testenv +function returns zero if the specified environment variable does not exist and +a non-zero value if it does exist. +.Pp +The +.Fn getenv_int , +.Fn getenv_long , +.Fn getenv_string , +.Fn getenv_quad , +.Fn getenv_uint , +.Fn getenv_ulong , +and +.Fn getenv_bool +functions return a non-zero value on success and zero on failure. +.Pp +The +.Fn getenv_is_true +and +.Fn getenv_is_false +functions return +.Dv true +if the specified environment variable exists and its value matches the desired +boolean condition, and +.Dv false +otherwise. diff --git a/static/freebsd/man9/getnewvnode.9 b/static/freebsd/man9/getnewvnode.9 new file mode 100644 index 00000000..d35c1a08 --- /dev/null +++ b/static/freebsd/man9/getnewvnode.9 @@ -0,0 +1,66 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 November 1, 2023 +.Dt GETNEWVNODE 9 +.Os +.Sh NAME +.Nm getnewvnode +.Nd "get a new vnode" +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/mount.h +.Ft int +.Fn getnewvnode "const char *tag" "struct mount *mp" "struct vop_vector *vops" "struct vnode **vpp" +.Sh DESCRIPTION +The +.Fn getnewvnode +function initializes a new vnode, assigning it the vnode operations passed in +.Fa vops . +.Pp +The arguments to +.Fn getnewvnode +are: +.Bl -tag -width ".Fa vops" +.It Fa tag +The file system type string. +This field should only be referenced for debugging or for userland utilities. +.It Fa mp +The mount point to add the new vnode to. +.It Fa vops +The vnode operations to assign to the new vnode. +.It Fa vpp +Points to the new vnode upon successful completion. +.El +.Sh RETURN VALUES +.Fn getnewvnode +returns 0 on success. +.Sh BUGS +It never returns an error, instead either succeeds or blocks indefinitely. +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/gone_in.9 b/static/freebsd/man9/gone_in.9 new file mode 100644 index 00000000..1b60e1eb --- /dev/null +++ b/static/freebsd/man9/gone_in.9 @@ -0,0 +1,92 @@ +.\" Copyright (c) 2021 The FreeBSD Foundation +.\" +.\" This document was written by Ed Maste under sponsorship from +.\" The FreeBSD Foundation. +.\" +.\" 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 ``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 June 24, 2025 +.Dt GONE_IN 9 +.Os +.Sh NAME +.Nm gone_in , +.Nm gone_in_dev +.Nd deprecation notice functions +.Sh SYNOPSIS +.In sys/systm.h +.Ft void +.Fn gone_in "int major" "const char *msg" "..." +.Ft void +.Fn gone_in_dev "device_t dev" "int major" "const char *msg" "..." +.Sh DESCRIPTION +The +.Nm gone_in +functions are used to provide a notice that the kernel is actively using a +driver or some other functionality that is deprecated, and is planned for +removal in a future +.Fx +release. +The notice is sent to the kernel +.Xr dmesg 8 +log and will appear on the console. +The +.Fa major +argument specifies the major version of the +.Fx +release that will remove the deprecated functionality. +The notice shall be printed only once, thus +.Nm +functions are safe to use in often executed code paths. +.Pp +.Nm gone_in_dev +will prepend driver name before the notice. +.Pp +In releases before +.Fa major +the provided notice will be appended with +.Do +To be removed in FreeBSD +.Fa major Ns +.Dc . +.Sh EXAMPLES +.Bd -literal -offset indent +void +example_api(foo_t *args) +{ + gone_in(16, "Warning! %s[%u] uses obsolete API. ", + curthread->td_proc->p_comm, curthread->td_proc->p_pid); + + /* API implementation omitted. */ +} + +int +example_driver_attach(struct example_driver_softc *sc) +{ + /* Attach code omitted. */ + + gone_in_dev(sc->dev, 16, "driver is deprecated"); +} +.Ed +.Sh HISTORY +The +.Nm +functions first appeared in +.Fx 11 . diff --git a/static/freebsd/man9/groupmember.9 b/static/freebsd/man9/groupmember.9 new file mode 100644 index 00000000..e7e28bae --- /dev/null +++ b/static/freebsd/man9/groupmember.9 @@ -0,0 +1,79 @@ +.\" +.\" Copyright (C) 2001 Chad David . All rights reserved. +.\" Copyright (C) 2023 Olivier Certner +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 October 31, 2024 +.Dt GROUPMEMBER 9 +.Os +.Sh NAME +.Nm groupmember +.Nd checks if credentials mandate some group membership +.Sh SYNOPSIS +.In sys/param.h +.In sys/ucred.h +.Ft bool +.Fn groupmember "gid_t gid" "const struct ucred *cred" +.Ft bool +.Fn realgroupmember "gid_t gid" "const struct ucred *cred" +.Sh DESCRIPTION +The +.Fn groupmember +function checks if credentials +.Fa cred +indicate that the associated subject or object is a member of the group +designated by the group ID +.Fa gid . +.Pp +Considered groups in +.Fa cred +are the effective and supplementary groups. +The real group is not taken into account. +.Pp +Function +.Fn realgroupmember +works the same except that it considers instead the real and supplementary +groups, and not the effective one. +.Sh RETURN VALUES +The +.Fn groupmember +and +.Fn realgroupmember +functions return +.Dv true +if the given credentials indicate membership of the group +.Fa gid , +or +.Dv false +otherwise. +.Sh SEE ALSO +.Xr getgroups 2 , +.Xr setgroups 2 +.Sh AUTHORS +This manual page was initially written by +.An -nosplit +.An Chad David Aq Mt davidc@acns.ab.ca +and was revised by +.An Olivier Certner Aq Mt olce.freebsd@certner.fr . diff --git a/static/freebsd/man9/hardclock.9 b/static/freebsd/man9/hardclock.9 new file mode 100644 index 00000000..757aed11 --- /dev/null +++ b/static/freebsd/man9/hardclock.9 @@ -0,0 +1,116 @@ +.\" $NetBSD: hardclock.9,v 1.3 2010/03/25 15:17:38 jruoho Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Thomas Klausner. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 February 27, 2023 +.Dt HARDCLOCK 9 +.Os +.Sh NAME +.Nm hardclock +.Nd real-time timer +.Sh SYNOPSIS +.Ft void +.Fn hardclock "int cnt" "int usermode" +.Sh DESCRIPTION +The +.Fn hardclock +function is called periodically based on pending work. +The rate ranges from +.Va hz +times per second on a very busy system, to twice a second on an idle system. +The +.Fa cnt +argument reports an estimate of the number of ticks since the last call. +Over long timescales, the average sum of +.Fa cnt +over one second is +.Va hz . +See +.Xr hz 9 +for important details over shorter time scales. +The +.Fa usermode +argument is non-zero when +.Fn hardclock +is called from an context that interrupted usermode execution. +.Pp +.Fn hardclock +may perform different tasks such as: +.Bl -bullet -offset indent +.It +Run the current process's virtual and profile time (decrease the +corresponding timers, if they are activated, and generate +.Li SIGVTALRM +or +.Li SIGPROF , +respectively). +.It +Increment the time-of-day, taking care of any +.Xr ntpd 8 +or +.Xr adjtime 2 +induced changes and leap seconds, as well as any necessary +compensations to keep in sync with PPS signals or external clocks, if +supported by the kernel. +.It +Schedule softclock interrupts +.Po +.Xr swi 9 +.Pc +processing. +.It +Collect +.Xr hwpmc 4 +statistics. +.It +Do device polling, when enabled +.Po +see +.Xr polling 4 +.Pc . +.It +Implement software +.Xr watchdog 9 +processing. +.It +Enqueue +.Xr epoch 9 +processing. +.El +.Sh SEE ALSO +.Xr adjtime 2 , +.Xr ntp_adjtime 2 , +.Xr signal 3 , +.Xr hwpmc 4 , +.Xr polling 4 , +.Xr ntpd 8 , +.Xr epoch 9 , +.Xr eventtimers 9 , +.Xr hz 9 , +.Xr swi 9 , +.Xr watchdog 9 diff --git a/static/freebsd/man9/hash.9 b/static/freebsd/man9/hash.9 new file mode 100644 index 00000000..d97ad251 --- /dev/null +++ b/static/freebsd/man9/hash.9 @@ -0,0 +1,226 @@ +.\" Copyright (c) 2001 Tobias Weingartner +.\" 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. 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. +.\" +.\" $OpenBSD: hash.9,v 1.5 2003/04/17 05:08:39 jmc Exp $ +.\" +.Dd June 30, 2015 +.Dt HASH 9 +.Os +.Sh NAME +.Nm hash , +.Nm hash32 , +.Nm hash32_buf , +.Nm hash32_str , +.Nm hash32_strn , +.Nm hash32_stre , +.Nm hash32_strne , +.Nm jenkins_hash , +.Nm jenkins_hash32 , +.Nm murmur3_32_hash , +.Nm murmur3_32_hash32 +.Nd general kernel hashing functions +.Sh SYNOPSIS +.In sys/hash.h +.Ft uint32_t +.Fn hash32_buf "const void *buf" "size_t len" "uint32_t hash" +.Ft uint32_t +.Fn hash32_str "const void *buf" "uint32_t hash" +.Ft uint32_t +.Fn hash32_strn "const void *buf" "size_t len" "uint32_t hash" +.Ft uint32_t +.Fn hash32_stre "const void *buf" "int end" "const char **ep" "uint32_t hash" +.Ft uint32_t +.Fn hash32_strne "const void *buf" "size_t len" "int end" "const char **ep" "uint32_t hash" +.Ft uint32_t +.Fn jenkins_hash "const void *buf" "size_t len" "uint32_t hash" +.Ft uint32_t +.Fn jenkins_hash32 "const uint32_t *buf" "size_t count" "uint32_t hash" +.Ft uint32_t +.Fn murmur3_32_hash "const void *buf" "size_t len" "uint32_t hash" +.Ft uint32_t +.Fn murmur3_32_hash32 "const uint32_t *buf" "size_t count" "uint32_t hash" +.Sh DESCRIPTION +The +.Fn hash32 +functions are used to give a consistent and general interface to +a decent hashing algorithm within the kernel. +These functions can be used to hash +.Tn ASCII +.Dv NUL +terminated strings, as well as blocks of memory. +.Pp +A +.Fa len +argument is the length of the buffer in bytes. +A +.Fa count +argument is the length of the buffer in 32-bit words. +.Pp +The +.Fn hash32_buf +function is used as a general buffer hashing function. +The argument +.Fa buf +is used to pass in the location, and +.Fa len +is the length of the buffer in bytes. +The argument +.Fa hash +is used to extend an existing hash, or is passed the initial value +.Dv HASHINIT +to start a new hash. +.Pp +The +.Fn hash32_str +function is used to hash a +.Dv NUL +terminated string passed in +.Fa buf +with initial hash value given in +.Fa hash . +.Pp +The +.Fn hash32_strn +function is like the +.Fn hash32_str +function, except it also takes a +.Fa len +argument, which is the maximal length of the expected string. +.Pp +The +.Fn hash32_stre +and +.Fn hash32_strne +functions are helper functions used by the kernel to hash pathname +components. +These functions have the additional termination condition +of terminating when they find a character given by +.Fa end +in the string to be hashed. +If the argument +.Fa ep +is not +.Dv NULL , +it is set to the point in the buffer at which the hash function +terminated hashing. +.Pp +The +.Fn jenkins_hash +function has same semantics as the +.Fn hash32_buf , +but provides more advanced hashing algorithm with better distribution. +.Pp +The +.Fn jenkins_hash32 +uses same hashing algorithm as the +.Fn jenkins_hash +function, but works only on +.Ft uint32_t +sized arrays, thus is simpler and faster. +It accepts an array of +.Ft uint32_t +values in its first argument and size of this array in the second argument. +.Pp +The +.Fn murmur3_32_hash +and +.Fn murmur3_32_hash32 +functions are similar to +.Fn jenkins_hash +and +.Fn jenkins_hash32 , +but implement the 32-bit version of MurmurHash3. +.Sh RETURN VALUES +The +.Fn hash32 +functions return a 32 bit hash value of the buffer or string. +.Sh EXAMPLES +.Bd -literal -offset indent +LIST_HEAD(head, cache) *hashtbl = NULL; +u_long mask = 0; + +void +sample_init(void) +{ + + hashtbl = hashinit(numwanted, type, flags, &mask); +} + +void +sample_use(char *str, int len) +{ + uint32_t hash; + + hash = hash32_str(str, HASHINIT); + hash = hash32_buf(&len, sizeof(len), hash); + hashtbl[hash & mask] = len; +} +.Ed +.Sh SEE ALSO +.Xr free 9 , +.Xr hashinit 9 , +.Xr malloc 9 +.Sh LIMITATIONS +The +.Fn hash32 +functions are only 32 bit functions. +They will prove to give poor 64 bit performance, especially for the +top 32 bits. +At the current time, this is not seen as a great limitation, as these +hash values are usually used to index into an array. +Should these hash values be used for other means, this limitation should +be revisited. +.Sh HISTORY +The +.Nm +functions first appeared in +.Nx 1.6 . +The current implementation of +.Nm hash32 +functions was first committed to +.Ox 3.2 , +and later imported to +.Fx 6.1 . +The +.Nm jenkins_hash +functions were added in +.Fx 10.0 . +The +.Nm murmur3_32_hash +functions were added in +.Fx 10.1 . +.Sh AUTHORS +The +.Nm hash32 +functions were written by +.An Tobias Weingartner . +The +.Nm jenkins_hash +functions were written by +.An Bob Jenkins . +The +.Nm murmur3_32_hash +functions were written by +.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . diff --git a/static/freebsd/man9/hashalloc.9 b/static/freebsd/man9/hashalloc.9 new file mode 100644 index 00000000..c68444bf --- /dev/null +++ b/static/freebsd/man9/hashalloc.9 @@ -0,0 +1,314 @@ +.\" +.\" Copyright (c) 2026 Gleb Smirnoff +.\" 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 April 12, 2026 +.Dt HASHALLOC 9 +.Os +.Sh NAME +.Nm hashalloc , +.Nm hashfree +.Nd allocate and free kernel hash tables +.Sh SYNOPSIS +.In sys/malloc.h +.In sys/hash.h +.Ft void * +.Fn hashalloc "struct hashalloc_args *args" +.Ft void +.Fn hashfree "void *table" "struct hashalloc_args *args" +.Sh DESCRIPTION +The +.Fn hashalloc +and +.Fn hashfree +functions provide a flexible kernel programming interface (KPI) for allocating +and freeing hash tables with configurable bucket headers. +.Pp +.Pp +.Fn hashalloc +allocates memory for a hash table according to the parameters +specified in the +.Fa args +structure. +It computes an appropriate number of buckets (adjusting +.Fa args->size +as needed based on the requested +.Fa type ) , +allocates memory using +.Xr malloc 9 , +initializes each bucket's queue header (e.g., +.Vt LIST_HEAD , +.Vt TAILQ_HEAD , +etc.), and, if requested, initializes per-bucket locks. +The returned memory allocation can be used as an array of header structures +that start with initialized list header of the requested type followed by +initialized lock of requested type. +.Pp +.Fn hashfree +frees a hash table previously allocated by +.Fn hashalloc . +.Pp +Both functions require the caller to pass the same (or equivalent) +.Fa struct hashalloc_args +that specifies the desired configuration of the hash table and has the +following members: +.Bd -literal -offset indent +struct hashalloc_args { + /* Required arguments */ + size_t size; /* in: desired buckets, out: allocated */ + int mflags; /* malloc(9) flags */ + struct malloc_type *mtype; /* malloc(9) type */ + /* Optional arguments */ + size_t hdrsize; /* bucket header size; 0 = auto */ + enum { + HASH_TYPE_POWER2, + HASH_TYPE_PRIME, + } type; /* default HASH_TYPE_POWER2 */ + enum { + HASH_HEAD_LIST, + HASH_HEAD_CK_LIST, + HASH_HEAD_SLIST, + HASH_HEAD_CK_SLIST, + HASH_HEAD_STAILQ, + HASH_HEAD_CK_STAILQ, + HASH_HEAD_TAILQ, + } head; /* default HASH_HEAD_LIST */ + enum { + HASH_LOCK_NONE, + HASH_LOCK_MTX, + HASH_LOCK_RWLOCK, + HASH_LOCK_SX, + HASH_LOCK_RMLOCK, + HASH_LOCK_RMSLOCK, + } lock; /* default HASH_LOCK_NONE */ + int lopts; /* lock init options */ + const char *lname; /* lock name */ + int (*ctor)(void *); /* bucket constructor */ + void (*dtor)(void *); /* bucket destructor */ + /* Returned arguments */ + int error; /* error code in case of failure */ +}; +.Ed +.Pp +Argument members +.Fa size , +.Fa mflags +and +.Fa mtype +are required for the +.Fn hashalloc . +The argument +.Fa size , +as filled by earlier call to +.Fn hashalloc , +and +.Fa mtype +are required for the +.Fn hashfree . +The rest of arguments are optional and have reasonable defaults. +A hash table that was allocated with a non-default allocation arguments shall +pass the same arguments to +.Fn hashfree . +The structure shall be initialized with sparse C99 initializer as it may +contain opaque extension members. +The structure may be allocated on the stack of a caller. +.Bl -tag -width ".Fa hdrsize" +.It Fa size +Desired number of buckets for +.Fn hashalloc . +Upon a successful return +.Fn hashalloc +sets this member to the actual number allocated +(may be rounded up to power-of-2 or nearest prime). +The value returned by +.Fn hashalloc +shall be later supplied to the +.Fn hashfree . +.It Fa mflags , Fa mtype +Passed directly to +.Xr malloc 9 . +.It Fa hdrsize +Optional member that allows the caller to set a different (increased) size +of a bucket header. +.It Fa type +Bucket count policy: +.Bl -tag -width ".Dv HASH_TYPE_POWER2" +.It Dv HASH_TYPE_POWER2 +Rounded up to largest power of two less than or equal to argument +.Fa size . +.It Dv HASH_TYPE_PRIME +Sized to the largest prime number less than or equal to argument +.Fa size . +.El +.Pp +Default is +.Dv HASH_TYPE_POWER2 . +.It Fa head +Queue header type for each bucket, a +.Xr queue 3 +or +Concurrency-kit (CK) type. +.Bl -tag -width ".Dv HASH_HEAD_CK_STAILQ" +.It Dv HASH_HEAD_LIST +.Xr queue 3 +.Fd LIST_HEAD +.It Dv HASH_HEAD_CK_LIST +Concurrency-kit +.Fd CK_LIST_HEAD +.It Dv HASH_HEAD_SLIST +.Xr queue 3 +.Fd SLIST_HEAD +.It Dv HASH_HEAD_CK_SLIST +Concurrency-kit +.Fd CK_SLIST_HEAD +.It Dv HASH_HEAD_STAILQ +.Xr queue 3 +.Fd STAILQ_HEAD +.It Dv HASH_HEAD_CK_STAILQ +Concurrency-kit +.Fd CK_STAILQ_HEAD +.It Dv HASH_HEAD_TAILQ +.Xr queue 3 +.Fd TAILQ_HEAD +.El +.Pp +Default is +.Dv HASH_HEAD_LIST . +.It Fa lock +Synchronization: +.Bl -tag -width ".Dv HASH_LOCK_RWLOCK" +.It Dv HASH_LOCK_NONE +No per-bucket lock. +.It Dv HASH_LOCK_MTX +Per-bucket +.Xr mutex 9 . +.It Dv HASH_LOCK_RWLOCK +Per-bucket +.Xr rwlock 9 . +.It Dv HASH_LOCK_SX +Per-bucket +.Xr sx 9 . +.It Dv HASH_LOCK_RMLOCK +Per-bucket +.Xr rmlock 9 . +.It Dv HASH_LOCK_RMSLOCK +Per-bucket sleepable (rms) +.Xr rmlock 9 . +.El +.Pp +Default is +.Dv HASH_LOCK_NONE . +.It Fa lopts +Options passed to +.Xr mtx_init 9 , +.Xr rw_init 9 , +.Xr sx_init 9 , +.Xr rm_init 9 +or +.Xr rms_init 9 +(if locking is enabled). +.It Fa lname +Lock name. +This member is required unless +.Fa lock +is +.Dv HASH_LOCK_NONE . +.It Fa ctor +Optional constructor to be called by +.Fn hashalloc +for each bucket after list header and lock initialization. +May fail with error code, yielding in a failure of +.Fn hashalloc . +.It Fa dtor +Optional destructor to be called by +.Fn hashfree +for each bucket before lock destructors and list emptyness checks. +.El +.Sh RETURN VALUES +.Fn hashalloc +returns a pointer to the allocated and initialized hash table on success, or +.Dv NULL +on memory allocation failure or constructor failure. +The +.Fa error +member of +.Fa args +is set to appropriate error code. +When +.Fa mflags +in +.Fa args +contain the +.Va M_WAITOK +flag and the +.Fa ctor +is either NULL or never fails, then +.Fn hashalloc +never fails. +.Sh EXAMPLES +A simple mutex-protected hash table using TAILQ buckets: +.Bd -literal -offset indent +struct bucket { + TAILQ_HEAD(, foo) head; + struct mtx lock; +} *table; + +struct hashalloc_args args = { + .size = 9000, + .mflags = M_WAITOK, + .mtype = M_FOO, + .head = HASH_HEAD_TAILQ, + .lock = HASH_LOCK_MTX, + .lopts = MTX_DEF, + .lname = "bucket of foo", +}; + +table = hashalloc(&args); +/* Use table as array of struct bucket ... */ +mtx_lock(&table[hash].lock); +TAILQ_INSERT_HEAD(&table[hash].head, foo, next); + +/* Later */ +hashfree(table, &args); +.Ed +.Sh SEE ALSO +.Xr malloc 9 , +.Xr mutex 9 , +.Xr rmlock 9 , +.Xr rwlock 9 , +.Xr sx 9 , +.Xr queue 3 +.Sh HISTORY +The +.Nm +KPI first appeared in +.Fx 16.0 . +It supersedes older interface +.Fn hashinit , +that was available since +.Bx 4.4 , +by offering greater control over the hash table structure and locking +strategy. +.Sh AUTHORS +.An Gleb Smirnoff Aq Mt glebius@FreeBSD.org diff --git a/static/freebsd/man9/hashinit.9 b/static/freebsd/man9/hashinit.9 new file mode 100644 index 00000000..8c6a3888 --- /dev/null +++ b/static/freebsd/man9/hashinit.9 @@ -0,0 +1,197 @@ +.\" +.\" Copyright (c) 2004 Joseph Koshy +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' +.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd March 17, 2026 +.Dt HASHINIT 9 +.Os +.Sh NAME +.Nm hashinit , hashinit_flags , hashdestroy , phashinit , phashinit_flags +.Nd manage kernel hash tables +.Sh SYNOPSIS +.In sys/malloc.h +.In sys/systm.h +.In sys/queue.h +.Ft "void *" +.Fn hashinit "int nelements" "struct malloc_type *type" "u_long *hashmask" +.Ft void +.Fo hashinit_flags +.Fa "int nelements" "struct malloc_type *type" "u_long *hashmask" "int flags" +.Fc +.Ft void +.Fn hashdestroy "void *hashtbl" "struct malloc_type *type" "u_long hashmask" +.Ft "void *" +.Fn phashinit "int nelements" "struct malloc_type *type" "u_long *nentries" +.Fn phashinit_flags "int nelements" "struct malloc_type *type" "u_long *nentries" "int flags" +.Sh WARNING +This KPI is obsolete and scheduled for removal in +.Fx 17 . +Use +.Xr hashalloc 9 +instead. +.Sh DESCRIPTION +The +.Fn hashinit , +.Fn hashinit_flags , +.Fn phashinit +and +.Fn phashinit_flags +functions allocate space for hash tables of size given by the argument +.Fa nelements . +.Pp +The +.Fn hashinit +function allocates hash tables that are sized to largest power of two +less than or equal to argument +.Fa nelements . +The +.Fn phashinit +function allocates hash tables that are sized to the largest prime +number less than or equal to argument +.Fa nelements . +The +.Fn hashinit_flags +function operates like +.Fn hashinit +but also accepts an additional argument +.Fa flags +which control various options during allocation. +.Fn phashinit_flags +function operates like +.Fn phashinit +but also accepts an additional argument +.Fa flags +which control various options during allocation. +Allocated hash tables are contiguous arrays of +.Xr LIST_HEAD 3 +entries, allocated using +.Xr malloc 9 , +and initialized using +.Xr LIST_INIT 3 . +The malloc arena to be used for allocation is pointed to by argument +.Fa type . +.Pp +The +.Fn hashdestroy +function frees the space occupied by the hash table pointed to by argument +.Fa hashtbl . +Argument +.Fa type +determines the malloc arena to use when freeing space. +The argument +.Fa hashmask +should be the bit mask returned by the call to +.Fn hashinit +that allocated the hash table. +The argument +.Fa flags +must be used with one of the following values. +.Pp +.Bl -tag -width ".Dv HASH_NOWAIT" -offset indent -compact +.It Dv HASH_NOWAIT +Any malloc performed by the +.Fn hashinit_flags +and +.Fn phashinit_flags +function will not be allowed to wait, and therefore may fail. +.It Dv HASH_WAITOK +Any malloc performed by +.Fn hashinit_flags +and +.Fn phashinit_flags +function is allowed to wait for memory. +This is also the behavior of +.Fn hashinit +and +.Fn phashinit . +.El +.Sh IMPLEMENTATION NOTES +The largest prime hash value chosen by +.Fn phashinit +is 32749. +.Sh RETURN VALUES +The +.Fn hashinit +function returns a pointer to an allocated hash table and sets the +location pointed to by +.Fa hashmask +to the bit mask to be used for computing the correct slot in the +hash table. +.Pp +The +.Fn phashinit +function returns a pointer to an allocated hash table and sets the +location pointed to by +.Fa nentries +to the number of rows in the hash table. +.Sh EXAMPLES +A typical example is shown below: +.Bd -literal -offset indent +\&... +static LIST_HEAD(foo, foo) *footable; +static u_long foomask; +\&... +footable = hashinit(32, M_FOO, &foomask); +.Ed +.Pp +Here we allocate a hash table with 32 entries from the malloc arena +pointed to by +.Dv M_FOO . +The mask for the allocated hash table is returned in +.Va foomask . +A subsequent call to +.Fn hashdestroy +uses the value in +.Va foomask : +.Bd -literal -offset indent +\&... +hashdestroy(footable, M_FOO, foomask); +.Ed +.Sh DIAGNOSTICS +The +.Fn hashinit +and +.Fn phashinit +functions will panic if argument +.Fa nelements +is less than or equal to zero. +.Pp +The +.Fn hashdestroy +function will panic if the hash table +pointed to by +.Fa hashtbl +is not empty. +.Sh SEE ALSO +.Xr hashalloc 9 , +.Xr LIST_HEAD 3 , +.Xr malloc 9 +.Sh BUGS +There is no +.Fn phashdestroy +function, and using +.Fn hashdestroy +to free a hash table allocated by +.Fn phashinit +usually has grave consequences. diff --git a/static/freebsd/man9/hexdump.9 b/static/freebsd/man9/hexdump.9 new file mode 100644 index 00000000..c5a8f418 --- /dev/null +++ b/static/freebsd/man9/hexdump.9 @@ -0,0 +1,92 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2003 Scott Long +.\" +.\" 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 December 7, 2003 +.Dt HEXDUMP 9 +.Os +.Sh NAME +.Nm hexdump +.Nd "dump a block of bytes to the console in hexadecimal form" +.Sh SYNOPSIS +.In sys/systm.h +.Ft void +.Fn hexdump "void *ptr" "int length" "const char *hdr" "int flags" +.Sh DESCRIPTION +The +.Fn hexdump +function prints an array of bytes to the console in hexadecimal form, along with +the +.Tn ASCII +representation of the bytes, if possible. +By default, each line of +output will start with an offset count, followed by 16 hexadecimal values, +followed by 16 +.Tn ASCII +characters. +.Bl -tag -width indent +.It Fa ptr +Pointer to the array of bytes to print. +It does not need to be +.Dv NUL Ns +-terminated. +.It Fa length +Number of bytes to print. +.It Fa hdr +Pointer to a +.Dv NUL Ns +-terminated character string that will be prepended to each +line of output. +A value of +.Dv NULL +implies that no header will be printed. +.It Fa flags +Flags for controlling the formatting of the output. +.Bl -tag -width ".Dv HD_OMIT_COUNT" +.It Bits 0-7 +Integer value of the number of bytes to display on each line. +A value of 0 implies that the default value of 16 will be used. +.It Bits 8-15 +Character +.Tn ASCII +value to use as the separator for the hexadecimal output. +A value of 0 implies that the default value of 32 +.Tn ( ASCII +space) will be used. +.It Dv HD_OMIT_COUNT +Do not print the offset column at the beginning of each line. +.It Dv HD_OMIT_HEX +Do not print the hexadecimal values on each line. +.It Dv HD_OMIT_CHARS +Do not print the character values on each line. +.El +.El +.Sh SEE ALSO +.Xr ascii 7 +.Sh AUTHORS +This manual page was written by +.An Scott Long . diff --git a/static/freebsd/man9/hhook.9 b/static/freebsd/man9/hhook.9 new file mode 100644 index 00000000..592ac7a9 --- /dev/null +++ b/static/freebsd/man9/hhook.9 @@ -0,0 +1,379 @@ +.\" +.\" Copyright (c) 2010-2011 The FreeBSD Foundation +.\" +.\" This documentation was written at the Centre for Advanced Internet +.\" Architectures, Swinburne University of Technology, Melbourne, Australia by +.\" David Hayes and Lawrence Stewart under sponsorship from the FreeBSD +.\" Foundation. +.\" +.\" 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 June 21, 2013 +.Dt HHOOK 9 +.Os +.Sh NAME +.Nm hhook , +.Nm hhook_head_register , +.Nm hhook_head_deregister , +.Nm hhook_head_deregister_lookup , +.Nm hhook_run_hooks , +.Nm HHOOKS_RUN_IF , +.Nm HHOOKS_RUN_LOOKUP_IF +.Nd Helper Hook Framework +.Sh SYNOPSIS +.In sys/hhook.h +.Ft typedef int +.Fn "\*(lp*hhook_func_t\*(rp" "int32_t hhook_type" "int32_t hhook_id" \ +"void *udata" "void *ctx_data" "void *hdata" "struct osd *hosd" +.Fn "int hhook_head_register" "int32_t hhook_type" "int32_t hhook_id" \ +"struct hhook_head **hhh" "uint32_t flags" +.Fn "int hhook_head_deregister" "struct hhook_head *hhh" +.Fn "int hhook_head_deregister_lookup" "int32_t hhook_type" "int32_t hhook_id" +.Fn "void hhook_run_hooks" "struct hhook_head *hhh" "void *ctx_data" \ +"struct osd *hosd" +.Fn HHOOKS_RUN_IF "hhh" "ctx_data" "hosd" +.Fn HHOOKS_RUN_LOOKUP_IF "hhook_type" "hhook_id" "ctx_data" "hosd" +.Sh DESCRIPTION +.Nm +provides a framework for managing and running arbitrary hook functions at +defined hook points within the kernel. +The KPI was inspired by +.Xr pfil 9 , +and in many respects can be thought of as a more generic superset of pfil. +.Pp +The +.Xr khelp 9 +and +.Nm +frameworks are tightly integrated. +Khelp is responsible for registering and deregistering Khelp module hook +functions with +.Nm +points. +The KPI functions used by +.Xr khelp 9 +to do this are not documented here as they are not relevant to consumers wishing +to instantiate hook points. +.Ss Information for Khelp Module Implementors +Khelp modules indirectly interact with +.Nm +by defining appropriate hook functions for insertion into hook points. +Hook functions must conform to the +.Ft hhook_func_t +function pointer declaration +outlined in the +.Sx SYNOPSIS . +.Pp +The +.Fa hhook_type +and +.Fa hhook_id +arguments identify the hook point which has called into the hook function. +These are useful when a single hook function is registered for multiple hook +points and wants to know which hook point has called into it. +.In sys/hhook.h +lists available +.Fa hhook_type +defines and subsystems which export hook points are responsible for defining +the +.Fa hhook_id +value in appropriate header files. +.Pp +The +.Fa udata +argument will be passed to the hook function if it was specified in the +.Vt struct hookinfo +at hook registration time. +.Pp +The +.Fa ctx_data +argument contains context specific data from the hook point call site. +The data type passed is subsystem dependent. +.Pp +The +.Fa hdata +argument is a pointer to the persistent per-object storage allocated for use by +the module if required. +The pointer will only ever be NULL if the module did not request per-object +storage. +.Pp +The +.Fa hosd +argument can be used with the +.Xr khelp 9 +framework's +.Fn khelp_get_osd +function to access data belonging to a different Khelp module. +.Pp +Khelp modules instruct the Khelp framework to register their hook functions with +.Nm +points by creating a +.Vt "struct hookinfo" +per hook point, which contains the following members: +.Bd -literal -offset indent +struct hookinfo { + hhook_func_t hook_func; + struct helper *hook_helper; + void *hook_udata; + int32_t hook_id; + int32_t hook_type; +}; +.Ed +.Pp +Khelp modules are responsible for setting all members of the struct except +.Va hook_helper +which is handled by the Khelp framework. +.Ss Creating and Managing Hook Points +Kernel subsystems that wish to provide +.Nm +points typically need to make four and possibly five key changes to their +implementation: +.Bl -bullet +.It +Define a list of +.Va hhook_id +mappings in an appropriate subsystem header. +.It +Register each hook point with the +.Fn hhook_head_register +function during initialisation of the subsystem. +.It +Select or create a standardised data type to pass to hook functions as +contextual data. +.It +Add a call to +.Fn HHOOKS_RUN_IF +or +.Fn HHOOKS_RUN_IF_LOOKUP +at the point in the subsystem's code where the hook point should be executed. +.It +If the subsystem can be dynamically added/removed at runtime, each hook +point registered with the +.Fn hhook_head_register +function when the subsystem was initialised needs to be deregistered with the +.Fn hhook_head_deregister +or +.Fn hhook_head_deregister_lookup +functions when the subsystem is being deinitialised prior to removal. +.El +.Pp +The +.Fn hhook_head_register +function registers a hook point with the +.Nm +framework. +The +.Fa hook_type +argument defines the high level type for the hook point. +Valid types are defined in +.In sys/hhook.h +and new types should be added as required. +The +.Fa hook_id +argument specifies a unique, subsystem specific identifier for the hook point. +The +.Fa hhh +argument will, if not NULL, be used to store a reference to the +.Vt struct hhook_head +created as part of the registration process. +Subsystems will generally want to store a local copy of the +.Vt struct hhook_head +so that they can use the +.Fn HHOOKS_RUN_IF +macro to instantiate hook points. +The HHOOK_WAITOK flag may be passed in via the +.Fa flags +argument if +.Xr malloc 9 +is allowed to sleep waiting for memory to become available. +If the hook point is within a virtualised subsystem (e.g. the network stack), +the HHOOK_HEADISINVNET flag should be passed in via the +.Fa flags +argument so that the +.Vt struct hhook_head +created during the registration process will be added to a virtualised list. +.Pp +The +.Fn hhook_head_deregister +function deregisters a previously registered hook point from the +.Nm +framework. +The +.Fa hhh +argument is the pointer to the +.Vt struct hhook_head +returned by +.Fn hhoook_head_register +when the hook point was registered. +.Pp +The +.Fn hhook_head_deregister_lookup +function can be used instead of +.Fn hhook_head_deregister +in situations where the caller does not have a cached copy of the +.Vt struct hhook_head +and wants to deregister a hook point using the appropriate +.Fa hook_type +and +.Fa hook_id +identifiers instead. +.Pp +The +.Fn hhook_run_hooks +function should normally not be called directly and should instead be called +indirectly via the +.Fn HHOOKS_RUN_IF +macro. +However, there may be circumstances where it is preferable to call the function +directly, and so it is documented here for completeness. +The +.Fa hhh +argument references the +.Nm +point to call all registered hook functions for. +The +.Fa ctx_data +argument specifies a pointer to the contextual hook point data to pass into the +hook functions. +The +.Fa hosd +argument should be the pointer to the appropriate object's +.Vt struct osd +if the subsystem provides the ability for Khelp modules to associate per-object +data. +Subsystems which do not should pass NULL. +.Pp +The +.Fn HHOOKS_RUN_IF +macro is the preferred way to implement hook points. +It only calls the +.Fn hhook_run_hooks +function if at least one hook function is registered for the hook point. +By checking for registered hook functions, the macro minimises the cost +associated with adding hook points to frequently used code paths by reducing to +a simple if test in the common case where no hook functions are registered. +The arguments are as described for the +.Fn hhook_run_hooks +function. +.Pp +The +.Fn HHOOKS_RUN_IF_LOOKUP +macro performs the same function as the +.Fn HHOOKS_RUN_IF +macro, but performs an additional step to look up the +.Vt struct hhook_head +for the specified +.Fa hook_type +and +.Fa hook_id +identifiers. +It should not be used except in code paths which are infrequently executed +because of the reference counting overhead associated with the look up. +.Sh IMPLEMENTATION NOTES +Each +.Vt struct hhook_head +protects its internal list of hook functions with a +.Xr rmlock 9 . +Therefore, anytime +.Fn hhook_run_hooks +is called directly or indirectly via the +.Fn HHOOKS_RUN_IF +or +.Fn HHOOKS_RUN_IF_LOOKUP +macros, a non-sleepable read lock will be acquired and held across the calls to +all registered hook functions. +.Sh RETURN VALUES +.Fn hhook_head_register +returns 0 if no errors occurred. +It returns EEXIST if a hook point with the same +.Fa hook_type +and +.Fa hook_id +is already registered. +It returns EINVAL if the HHOOK_HEADISINVNET flag is not set in +.Fa flags +because the implementation does not yet support hook points in non-virtualised +subsystems (see the +.Sx BUGS +section for details). +It returns ENOMEM if +.Xr malloc 9 +failed to allocate memory for the new +.Vt struct hhook_head . +.Pp +.Fn hhook_head_deregister +and +.Fn hhook_head_deregister_lookup +return 0 if no errors occurred. +They return ENOENT if +.Fa hhh +is NULL. +They return EBUSY if the reference count of +.Fa hhh +is greater than one. +.Sh EXAMPLES +A well commented example Khelp module can be found at: +.Pa /usr/share/examples/kld/khelp/h_example.c +.Pp +The +.Xr tcp 4 +implementation provides two +.Nm +points which are called for packets sent/received when a connection is in the +established phase. +Search for HHOOK in the following files: +.Pa sys/netinet/tcp_var.h , +.Pa sys/netinet/tcp_input.c , +.Pa sys/netinet/tcp_output.c +and +.Pa sys/netinet/tcp_subr.c . +.Sh SEE ALSO +.Xr khelp 9 +.Sh ACKNOWLEDGEMENTS +Development and testing of this software were made possible in part by grants +from the FreeBSD Foundation and Cisco University Research Program Fund at +Community Foundation Silicon Valley. +.Sh HISTORY +The +.Nm +framework first appeared in +.Fx 9.0 . +.Pp +The +.Nm +framework was first released in 2010 by Lawrence Stewart whilst studying at +Swinburne University of Technology's Centre for Advanced Internet Architectures, +Melbourne, Australia. +More details are available at: +.Pp +http://caia.swin.edu.au/urp/newtcp/ +.Sh AUTHORS +.An -nosplit +The +.Nm +framework was written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org . +.Pp +This manual page was written by +.An David Hayes Aq Mt david.hayes@ieee.org +and +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org . diff --git a/static/freebsd/man9/hz.9 b/static/freebsd/man9/hz.9 new file mode 100644 index 00000000..081c9f6e --- /dev/null +++ b/static/freebsd/man9/hz.9 @@ -0,0 +1,159 @@ +.\" +.\" Copyright (c) 2021 Netflix, Inc. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 1, 2021 +.Dt HZ 9 +.Os +.Sh NAME +.Nm hz , +.Nm tick , +.Nm stathz , +.Nm profhz +.Nd system time model +.Sh SYNOPSIS +.In sys/kernel.h +.Pp +.Vt extern int hz; +.Vt extern int tick; +.Vt extern int stathz; +.Vt extern int profhz; /* deprecated */ +.Sh DESCRIPTION +.Fx +utilizes periodic, one-shot, global or per-CPU +timing hardware using +.Xr eventtimers 9 +to produce traditional clock behavior. +These clocks regulate periodic events in the system. +.Pp +The main clock is used to update the system's notion of time via +.Xr timecounters 9 +and to pace periodic system processing as documented in +.Xr hardclock 9 . +That routine may be called once every 1 / +.Va hz +seconds, though the call is omitted if no work is needed in the next tick and it +has not been 0.5 seconds since the last call. +.Pp +The stat clock running at +.Va stathz +gathers statistics on the system and its processes. +It computes values for +.Xr getrusage 2 +and statistics displayed by +.Xr ps 1 +and +.Xr top 1 . +.Pp +Finally, a profiling clock may run at +.Vt profhz +to sample user program counter values for profiling purposes. +This profiling mechanism has been replaced by the more functional +.Xr hwpmc 4 +and may be removed in a future version of +.Fx . +.Pp +.Va tick +is the length of time in microseconds of one system tick. +.Pp +These system variables are also available as +.Em struct clockinfo +from +.Xr sysctl 3 +and +.Sy kern.clockrate +from +.Xr sysctl 8 . +.Pp +The current global and per-CPU CPU time usage is returned to the user in units +of 1 / +.Va stathz +ticks in the +.Sy kern.cp_time +and +.Sy kern.cp_times +sysctl MIBs. +.Pp +The +.Va hz +rate may be overridden by defining +.Dv HZ +in the kernel configuration file or setting +.Sy kern.hz +system tuneable via +.Xr loader.conf 5 . +.Pp +The current default is 1000 Hz for a tick of 1 ms for real hardware. +For virtual machine guests, the default is 100 Hz for a tick of 10 ms. +Only override the default value if you really know what you are doing. +Due to the adaptive nature of timeouts, changing this value has less effect than +it had in the past. +.Sh SEE ALSO +.Xr ps 1 , +.Xr top 1 , +.Xr setitimer 2 , +.Xr timer_settime 2 , +.Xr loader.conf 5 , +.Xr eventtimers 9 , +.Xr hardclock 9 , +.Xr microtime 9 , +.Xr time_second 9 , +.Xr timecounters 9 +.Sh IMPLEMENTATION NOTES +Historically, both the +.Va stathz +and +.Va profhz +clocks have run off the same physical timer running at the slower rate when no +process is using the profile features, or at the higher rate when at least one +process is using it. +Although the interface is deprecated by +.St -p1003.1-2008 +in favor of +.Xr timer_settime 2 , +several programs still use +.Xr setitimer 2 +and +.Va ITIMER_PROF +for a higher-resolution periodic interrupt than has been traditionally +available. +.Pp +Historically, +.Xr hardclock 9 +has also been run off a separate interrupt, except on constrained platforms that +lack enough periodic interrupt sources. +.Fx +uses +.Xr eventtimers 9 +to abstract these details away, though some old code may still harbor +assumptions that are an imperfect fit to this abstraction. +.Pp +.Xr timecounters 9 +are limited to 32-bits and wrap after about a second, so we must update the +time hands they maintain at least every half second to get the proper wrapping +math. +In addition, +.Va kern.cp_times +needs to updated at least once a second so that the values displayed by +.Xr top 1 +update every second. diff --git a/static/freebsd/man9/ieee80211.9 b/static/freebsd/man9/ieee80211.9 new file mode 100644 index 00000000..40c8c243 --- /dev/null +++ b/static/freebsd/man9/ieee80211.9 @@ -0,0 +1,714 @@ +.\" +.\" Copyright (c) 2004 Bruce M. Simpson +.\" Copyright (c) 2004 Darron Broad +.\" Copyright (c) 2009 Sam Leffler, Errno Consulting +.\" 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 April 24, 2024 +.Dt IEEE80211 9 +.Os +.Sh NAME +.Nm IEEE80211 +.Nd 802.11 network layer +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.Ft void +.Fn ieee80211_ifattach "struct ieee80211com *ic" +.Ft void +.Fn ieee80211_ifdetach "struct ieee80211com *ic" +.Ft int +.Fn ieee80211_mhz2ieee "u_int freq" "u_int flags" +.Ft int +.Fn ieee80211_chan2ieee "struct ieee80211com *ic" "const struct ieee80211_channel *c" +.Ft u_int +.Fn ieee80211_ieee2mhz "u_int chan" "u_int flags" +.Ft int +.Fn ieee80211_media_change "struct ifnet *ifp" +.Ft void +.Fn ieee80211_media_status "struct ifnet *ifp" "struct ifmediareq *imr" +.Ft int +.Fn ieee80211_setmode "struct ieee80211com *ic" "enum ieee80211_phymode mode" +.Ft enum ieee80211_phymode +.Fo ieee80211_chan2mode +.Fa "const struct ieee80211_channel *chan" +.Fc +.Ft int +.Fo ieee80211_rate2media +.Fa "struct ieee80211com *ic" "int rate" "enum ieee80211_phymode mode" +.Fc +.Ft int +.Fn ieee80211_media2rate "int mword" +.Sh DESCRIPTION +IEEE 802.11 device drivers are written to use the infrastructure provided +by the +.Nm +software layer. +This software provides a support framework for drivers that includes +ifnet cloning, state management, and a user management API by which +applications interact with 802.11 devices. +Most drivers depend on the +.Nm +layer for protocol services but devices that off-load functionality +may bypass the layer to connect directly to the device. +.Pp +A +.Nm +device driver implements a virtual radio API that is exported to +users through network interfaces (aka vaps) that are cloned from the +underlying device. +These interfaces have an operating mode +(station, adhoc, hostap, wds, monitor, etc.\&) +that is fixed for the lifetime of the interface. +Devices that can support multiple concurrent interfaces allow +multiple vaps to be cloned. +This enables construction of interesting applications such as +an AP vap and one or more WDS vaps +or multiple AP vaps, each with a different security model. +The +.Nm +layer virtualizes most 802.11 state +and coordinates vap state changes including scheduling multiple vaps. +State that is not virtualized includes the current channel and +WME/WMM parameters. +Protocol processing is typically handled entirely in the +.Nm +layer with drivers responsible purely for moving data between the host +and device. +Similarly, +.Nm +handles most +.Xr ioctl 2 +requests without entering the driver; +instead drivers are notified of state changes that +require their involvement. +.Pp +The virtual radio interface defined by the +.Nm +layer means that drivers must be structured to follow specific rules. +Drivers that support only a single interface at any time must still +follow these rules. +.Pp +Most of these functions require that attachment to the stack is performed +before calling. +.Pp +.\" +The +.Fn ieee80211_ifattach +function attaches the wireless network interface +.Fa ic +to the 802.11 network stack layer. +This function must be called before using any of the +.Nm +functions which need to store driver state across invocations. +.Pp +.\" +The +.Fn ieee80211_ifdetach +function frees any +.Nm +structures associated with the driver, and performs Ethernet and BPF +detachment on behalf of the caller. +.Pp +.\" +The +.Fn ieee80211_mhz2ieee +utility function converts the frequency +.Fa freq +(specified in MHz) to an IEEE 802.11 channel number. +The +.Fa flags +argument is a hint which specifies whether the frequency is in +the 2GHz ISM band +.Pq Vt IEEE80211_CHAN_2GHZ +or the 5GHz band +.Pq Vt IEEE80211_CHAN_5GHZ ; +appropriate clipping of the result is then performed. +.Pp +.\" +The +.Fn ieee80211_chan2ieee +function converts the channel specified in +.Fa *c +to an IEEE channel number for the driver +.Fa ic . +If the conversion would be invalid, an error message is printed to the +system console. +This function REQUIRES that the driver is hooked up to the +.Nm +subsystem. +.Pp +.\" +The +.Fn ieee80211_ieee2mhz +utility function converts the IEEE channel number +.Ft chan +to a frequency (in MHz). +The +.Fa flags +argument is a hint which specifies whether the frequency is in +the 2GHz ISM band +.Pq Vt IEEE80211_CHAN_2GHZ +or the 5GHz band +.Pq Vt IEEE80211_CHAN_5GHZ ; +appropriate clipping of the result is then performed. +.Pp +.\" +The +.Fn ieee80211_media_status +and +.Fn ieee80211_media_change +functions are device-independent handlers for +.Vt ifmedia +commands and are not intended to be called directly. +.Pp +.\" +The +.Fn ieee80211_setmode +function is called from within the 802.11 stack to change the mode +of the driver's PHY; it is not intended to be called directly. +.Pp +.\" +The +.Fn ieee80211_chan2mode +function returns the PHY mode required for use with the channel +.Fa chan . +This is typically used when selecting a rate set, to be advertised in +beacons, for example. +.Pp +.\" +The +.Fn ieee80211_rate2media +function converts the bit rate +.Fa rate +(measured in units of 0.5Mbps) to an +.Vt ifmedia +sub-type, for the device +.Fa ic +running in PHY mode +.Fa mode . +The +.Fn ieee80211_media2rate +performs the reverse of this conversion, returning the bit rate (in 0.5Mbps +units) corresponding to an +.Vt ifmedia +sub-type. +. +.Sh DATA STRUCTURES +The virtual radio architecture splits state between a single per-device +.Vt ieee80211com +structure and one or more +.Vt ieee80211vap +structures. +Drivers are expected to setup various shared state in these structures +at device attach and during vap creation but otherwise should treat them +as read-only. +The +.Vt ieee80211com +structure is allocated by the +.Nm +layer as adjunct data to a device's +.Vt ifnet ; +it is accessed through the +.Vt if_l2com +structure member. +The +.Vt ieee80211vap +structure is allocated by the driver in the +.Dq vap create +method +and should be extended with any driver-private state. +This technique of giving the driver control to allocate data structures +is used for other +.Nm +data structures and should be exploited to maintain driver-private state +together with public +.Nm +state. +.Pp +The other main data structures are the station, or node, table +that tracks peers in the local BSS, and the channel table that defines +the current set of available radio channels. +Both tables are bound to the +.Vt ieee80211com +structure and shared by all vaps. +Long-lasting references to a node are counted to guard against +premature reclamation. +In particular every packet sent/received holds a node reference +(either explicitly for transmit or implicitly on receive). +.Pp +The +.Vt ieee80211com +and +.Vt ieee80211vap +structures also hold a collection of method pointers that drivers +fill-in and/or override to take control of certain operations. +These methods are the primary way drivers are bound to the +.Nm +layer and are described below. +.Sh DRIVER ATTACH/DETACH +Drivers attach to the +.Nm +layer with the +.Fn ieee80211_ifattach +function. +The driver is expected to allocate and setup any device-private +data structures before passing control. +The +.Vt ieee80211com +structure must be pre-initialized with state required to setup the +.Nm +layer: +.Bl -tag -width ic_channels +.It Dv ic_ifp +Backpointer to the physical device's ifnet. +.It Dv ic_caps +Device/driver capabilities; see below for a complete description. +.It Dv ic_channels +Table of channels the device is capable of operating on. +This is initially provided by the driver but may be changed +through calls that change the regulatory state. +.It Dv ic_nchan +Number of entries in +.Dv ic_channels . +.El +.Pp +On return from +.Fn ieee80211_ifattach +the driver is expected to override default callback functions in the +.Vt ieee80211com +structure to register it's private routines. +Methods marked with a +.Dq * +must be provided by the driver. +.Bl -tag -width ic_channels +.It Dv ic_vap_create* +Create a vap instance of the specified type (operating mode). +Any fixed BSSID and/or MAC address is provided. +Drivers that support multi-bssid operation may honor the requested BSSID +or assign their own. +.It Dv ic_vap_delete* +Destroy a vap instance created with +.Dv ic_vap_create . +.It Dv ic_getradiocaps +Return the list of calibrated channels for the radio. +The default method returns the current list of channels +(space permitting). +.It Dv ic_setregdomain +Process a request to change regulatory state. +The routine may reject a request or constrain changes (e.g. reduce +transmit power caps). +The default method accepts all proposed changes. +.It Dv ic_send_mgmt +Send an 802.11 management frame. +The default method fabricates the frame using +.Nm +state and passes it to the driver through the +.Dv ic_raw_xmit +method. +.It Dv ic_raw_xmit +Transmit a raw 802.11 frame. +The default method drops the frame and generates a message on the console. +.It Dv ic_updateslot +Update hardware state after an 802.11 IFS slot time change. +There is no default method; the pointer may be NULL in which case +it will not be used. +.It Dv ic_update_mcast +Update hardware for a change in the multicast packet filter. +The default method prints a console message. +.It Dv ic_update_promisc +Update hardware for a change in the promiscuous mode setting. +The default method prints a console message. +.It Dv ic_newassoc +Update driver/device state for association to a new AP (in station mode) +or when a new station associates (e.g. in AP mode). +There is no default method; the pointer may be NULL in which case +it will not be used. +.It Dv ic_node_alloc +Allocate and initialize a +.Vt ieee80211_node +structure. +This method cannot sleep. +The default method allocates zero'd memory using +.Xr malloc 9 . +Drivers should override this method to allocate extended storage +for their own needs. +Memory allocated by the driver must be tagged with +.Dv M_80211_NODE +to balance the memory allocation statistics. +.It Dv ic_node_free +Reclaim storage of a node allocated by +.Dv ic_node_alloc . +Drivers are expected to +.Em interpose +their own method to cleanup private state but must call through +this method to allow +.Nm +to reclaim it's private state. +.It Dv ic_node_cleanup +Cleanup state in a +.Vt ieee80211_node +created by +.Dv ic_node_alloc . +This operation is distinguished from +.Dv ic_node_free +in that it may be called long before the node is actually reclaimed +to cleanup adjunct state. +This can happen, for example, when a node must not be reclaimed +due to references held by packets in the transmit queue. +Drivers typically interpose +.Dv ic_node_cleanup +instead of +.Dv ic_node_free . +.It Dv ic_node_age +Age, and potentially reclaim, resources associated with a node. +The default method ages frames on the power-save queue (in AP mode) +and pending frames in the receive reorder queues (for stations using A-MPDU). +.It Dv ic_node_drain +Reclaim all optional resources associated with a node. +This call is used to free up resources when they are in short supply. +.It Dv ic_node_getrssi +Return the Receive Signal Strength Indication (RSSI) in .5 dBm units for +the specified node. +This interface returns a subset of the information +returned by +.Dv ic_node_getsignal . +The default method calculates a filtered average over the last ten +samples passed in to +.Xr ieee80211_input 9 +or +.Xr ieee80211_input_all 9 . +.It Dv ic_node_getsignal +Return the RSSI and noise floor (in .5 dBm units) for a station. +The default method calculates RSSI as described above; +the noise floor returned is the last value supplied to +.Xr ieee80211_input 9 +or +.Xr ieee80211_input_all 9 . +.It Dv ic_node_getmimoinfo +Return MIMO radio state for a station in support of the +.Dv IEEE80211_IOC_STA_INFO +ioctl request. +The default method returns nothing. +.It Dv ic_scan_start* +Prepare driver/hardware state for scanning. +This callback is done in a sleepable context. +.It Dv ic_scan_end* +Restore driver/hardware state after scanning completes. +This callback is done in a sleepable context. +.It Dv ic_set_channel* +Set the current radio channel using +.Vt ic_curchan . +This callback is done in a sleepable context. +.It Dv ic_scan_curchan +Start scanning on a channel. +This method is called immediately after each channel change +and must initiate the work to scan a channel and schedule a timer +to advance to the next channel in the scan list. +This callback is done in a sleepable context. +The default method handles active scan work (e.g. sending ProbeRequest +frames), and schedules a call to +.Xr ieee80211_scan_next 9 +according to the maximum dwell time for the channel. +Drivers that off-load scan work to firmware typically use this method +to trigger per-channel scan activity. +.It Dv ic_scan_mindwell +Handle reaching the minimum dwell time on a channel when scanning. +This event is triggered when one or more stations have been found on +a channel and the minimum dwell time has been reached. +This callback is done in a sleepable context. +The default method signals the scan machinery to advance +to the next channel as soon as possible. +Drivers can use this method to preempt further work (e.g. if scanning +is handled by firmware) or ignore the request to force maximum dwell time +on a channel. +.It Dv ic_recv_action +Process a received Action frame. +The default method points to +.Xr ieee80211_recv_action 9 +which provides a mechanism for setting up handlers for each Action frame class. +.It Dv ic_send_action +Transmit an Action frame. +The default method points to +.Xr ieee80211_send_action 9 +which provides a mechanism for setting up handlers for each Action frame class. +.It Dv ic_ampdu_enable +Check if transmit A-MPDU should be enabled for the specified station and AC. +The default method checks a per-AC traffic rate against a per-vap +threshold to decide if A-MPDU should be enabled. +This method also rate-limits ADDBA requests so that requests are not +made too frequently when a receiver has limited resources. +.It Dv ic_addba_request +Request A-MPDU transmit aggregation. +The default method sets up local state and issues an +ADDBA Request Action frame. +Drivers may interpose this method if they need to setup private state +for handling transmit A-MPDU. +.It Dv ic_addb_response +Process a received ADDBA Response Action frame and setup resources as +needed for doing transmit A-MPDU. +.It Dv ic_addb_stop +Shutdown an A-MPDU transmit stream for the specified station and AC. +The default method reclaims local state after sending a DelBA Action frame. +.It Dv ic_bar_response +Process a response to a transmitted BAR control frame. +.It Dv ic_ampdu_rx_start +Prepare to receive A-MPDU data from the specified station for the TID. +.It Dv ic_ampdu_rx_stop +Terminate receipt of A-MPDU data from the specified station for the TID. +.El +.Pp +Once the +.Nm +layer is attached to a driver there are two more steps typically done +to complete the work: +.Bl -enum +.It +Setup +.Dq radiotap support +for capturing raw 802.11 packets that pass through the device. +This is done with a call to +.Xr ieee80211_radiotap_attach 9 . +.It +Do any final device setup like enabling interrupts. +.El +.Pp +State is torn down and reclaimed with a call to +.Fn ieee80211_ifdetach . +Note this call may result in multiple callbacks into the driver +so it should be done before any critical driver state is reclaimed. +On return from +.Fn ieee80211_ifdetach +all associated vaps and ifnet structures are reclaimed or inaccessible +to user applications so it is safe to teardown driver state without +worry about being re-entered. +The driver is responsible for calling +.Xr if_free 9 +on the ifnet it allocated for the physical device. +.Sh DRIVER CAPABILITIES +Driver/device capabilities are specified using several sets of flags +in the +.Vt ieee80211com +structure. +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 +.Nm +layer propagates a subset of these capabilities to each vap through +the equivalent fields: +.Vt iv_caps , +.Vt iv_cryptocaps , +and +.Vt iv_htcaps . +The following general capabilities are defined: +.Bl -tag -width IEEE80211_C_8023ENCAP +.It Dv IEEE80211_C_STA +Device is capable of operating in station (aka Infrastructure) mode. +.It Dv IEEE80211_C_8023ENCAP +Device requires 802.3-encapsulated frames be passed for transmit. +By default +.Nm +will encapsulate all outbound frames as 802.11 frames (without a PLCP header). +.It Dv IEEE80211_C_FF +Device supports Atheros Fast-Frames. +.It Dv IEEE80211_C_TURBOP +Device supports Atheros Dynamic Turbo mode. +.It Dv IEEE80211_C_IBSS +Device is capable of operating in adhoc/IBSS mode. +.It Dv IEEE80211_C_PMGT +Device supports dynamic power-management (aka power save) in station mode. +.It Dv IEEE80211_C_HOSTAP +Device is capable of operating as an Access Point in Infrastructure mode. +.It Dv IEEE80211_C_AHDEMO +Device is capable of operating in Adhoc Demo mode. +In this mode the device is used purely to send/receive raw 802.11 frames. +.It Dv IEEE80211_C_SWRETRY +Device supports software retry of transmitted frames. +.It Dv IEEE80211_C_TXPMGT +Device support dynamic transmit power changes on transmitted frames; +also known as Transmit Power Control (TPC). +.It Dv IEEE80211_C_SHSLOT +Device supports short slot time operation (for 802.11g). +.It Dv IEEE80211_C_SHPREAMBLE +Device supports short preamble operation (for 802.11g). +.It Dv IEEE80211_C_MONITOR +Device is capable of operating in monitor mode. +.It Dv IEEE80211_C_DFS +Device supports radar detection and/or DFS. +DFS protocol support can be handled by +.Nm +but the device must be capable of detecting radar events. +.It Dv IEEE80211_C_MBSS +Device is capable of operating in MeshBSS (MBSS) mode +(as defined by 802.11s Draft 3.0). +.It Dv IEEE80211_C_WPA1 +Device supports WPA1 operation. +.It Dv IEEE80211_C_WPA2 +Device supports WPA2/802.11i operation. +.It Dv IEEE80211_C_BURST +Device supports frame bursting. +.It Dv IEEE80211_C_WME +Device supports WME/WMM operation +(at the moment this is mostly support for sending and receiving +QoS frames with EDCF). +.It Dv IEEE80211_C_WDS +Device supports transmit/receive of 4-address frames. +.It Dv IEEE80211_C_BGSCAN +Device supports background scanning. +.It Dv IEEE80211_C_TXFRAG +Device supports transmit of fragmented 802.11 frames. +.It Dv IEEE80211_C_TDMA +Device is capable of operating in TDMA mode. +.El +.Pp +The follow general crypto capabilities are defined. +In general +.Nm +will fall-back to software support when a device is not capable +of hardware acceleration of a cipher. +This can be done on a per-key basis. +.Nm +can also handle software +.Dv Michael +calculation combined with hardware +.Dv AES +acceleration. +.Bl -tag -width IEEE80211_C_8023ENCAP +.It Dv IEEE80211_CRYPTO_WEP +Device supports hardware WEP cipher. +.It Dv IEEE80211_CRYPTO_TKIP +Device supports hardware TKIP cipher. +.It Dv IEEE80211_CRYPTO_AES_OCB +Device supports hardware AES-OCB cipher. +.It Dv IEEE80211_CRYPTO_AES_CCM +Device supports hardware AES-CCM cipher. +.It Dv IEEE80211_CRYPTO_TKIPMIC +Device supports hardware Michael for use with TKIP. +.It Dv IEEE80211_CRYPTO_CKIP +Devices supports hardware CKIP cipher. +.El +.Pp +The follow general 802.11n capabilities are defined. +The first capabilities are defined exactly as they appear in the +802.11n specification. +Capabilities beginning with IEEE80211_HTC_AMPDU are used solely by the +.Nm +layer. +.Bl -tag -width IEEE80211_C_8023ENCAP +.It Dv IEEE80211_HTCAP_CHWIDTH40 +Device supports 20/40 channel width operation. +.It Dv IEEE80211_HTCAP_SMPS_DYNAMIC +Device supports dynamic SM power save operation. +.It Dv IEEE80211_HTCAP_SMPS_ENA +Device supports static SM power save operation. +.It Dv IEEE80211_HTCAP_GREENFIELD +Device supports Greenfield preamble. +.It Dv IEEE80211_HTCAP_SHORTGI20 +Device supports Short Guard Interval on 20MHz channels. +.It Dv IEEE80211_HTCAP_SHORTGI40 +Device supports Short Guard Interval on 40MHz channels. +.It Dv IEEE80211_HTCAP_TXSTBC +Device supports Space Time Block Convolution (STBC) for transmit. +.It Dv IEEE80211_HTCAP_RXSTBC_1STREAM +Device supports 1 spatial stream for STBC receive. +.It Dv IEEE80211_HTCAP_RXSTBC_2STREAM +Device supports 1-2 spatial streams for STBC receive. +.It Dv IEEE80211_HTCAP_RXSTBC_3STREAM +Device supports 1-3 spatial streams for STBC receive. +.It Dv IEEE80211_HTCAP_MAXAMSDU_7935 +Device supports A-MSDU frames up to 7935 octets. +.It Dv IEEE80211_HTCAP_MAXAMSDU_3839 +Device supports A-MSDU frames up to 3839 octets. +.It Dv IEEE80211_HTCAP_DSSSCCK40 +Device supports use of DSSS/CCK on 40MHz channels. +.It Dv IEEE80211_HTCAP_PSMP +Device supports PSMP. +.It Dv IEEE80211_HTCAP_40INTOLERANT +Device is intolerant of 40MHz wide channel use. +.It Dv IEEE80211_HTCAP_LSIGTXOPPROT +Device supports L-SIG TXOP protection. +.It Dv IEEE80211_HTC_AMPDU +Device supports A-MPDU aggregation. +Note that any 802.11n compliant device must support A-MPDU receive +so this implicitly means support for +.Em transmit +of A-MPDU frames. +.It Dv IEEE80211_HTC_AMSDU +Device supports A-MSDU aggregation. +Note that any 802.11n compliant device must support A-MSDU receive +so this implicitly means support for +.Em transmit +of A-MSDU frames. +.It Dv IEEE80211_HTC_HT +Device supports High Throughput (HT) operation. +This capability must be set to enable 802.11n functionality +in +.Nm . +.It Dv IEEE80211_HTC_SMPS +Device supports MIMO Power Save operation. +.It Dv IEEE80211_HTC_RIFS +Device supports Reduced Inter Frame Spacing (RIFS). +.El +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr ieee80211_amrr 9 , +.Xr ieee80211_beacon 9 , +.Xr ieee80211_bmiss 9 , +.Xr ieee80211_crypto 9 , +.Xr ieee80211_ddb 9 , +.Xr ieee80211_input 9 , +.Xr ieee80211_node 9 , +.Xr ieee80211_output 9 , +.Xr ieee80211_proto 9 , +.Xr ieee80211_radiotap 9 , +.Xr ieee80211_regdomain 9 , +.Xr ieee80211_scan 9 , +.Xr ieee80211_vap 9 , +.Xr ifnet 9 , +.Xr malloc 9 +.Sh HISTORY +The +.Nm +series of functions first appeared in +.Nx 1.5 , +and were later ported to +.Fx 4.6 . +This man page was updated with the information from +.Nx +.Nm +man page. +.Sh AUTHORS +.An -nosplit +The original +.Nx +.Nm +man page was written by +.An Bruce M. Simpson Aq Mt bms@FreeBSD.org +and +.An Darron Broad Aq Mt darron@kewl.org . diff --git a/static/freebsd/man9/ieee80211_amrr.9 b/static/freebsd/man9/ieee80211_amrr.9 new file mode 100644 index 00000000..69aa4818 --- /dev/null +++ b/static/freebsd/man9/ieee80211_amrr.9 @@ -0,0 +1,192 @@ +.\" +.\" Copyright (c) 2009 Sam Leffler, Errno Consulting +.\" 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 August 4, 2009 +.Dt IEEE8021_AMRR 9 +.Os +.Sh NAME +.Nm ieee80211_amrr +.Nd 802.11 network driver transmit rate control support +.Sh SYNOPSIS +.In net80211/ieee80211_amrr.h +.Ft void +.Fo ieee80211_amrr_init +.Fa "struct ieee80211_amrr *" +.Fa "struct ieee80211vap *" +.Fa "int amin" +.Fa "int amax" +.Fa "int interval" +.Fc +.\" +.Ft void +.Fn ieee80211_amrr_cleanup "struct ieee80211_amrr *" +.\" +.Ft void +.Fn ieee80211_amrr_setinterval "struct ieee80211_amrr *" "int interval" +.\" +.Ft void +.Fo ieee80211_amrr_node_init +.Fa "struct ieee80211_amrr *" +.Fa "struct ieee80211_amrr_node *" +.Fa "struct ieee80211_node *" +.Fc +.\" +.Ft int +.Fo ieee80211_amrr_choose +.Fa "struct ieee80211_node *" +.Fa "struct ieee80211_amrr_node *" +.Fc +.\" +.Ft void +.Fo ieee80211_amrr_tx_complete +.Fa "struct ieee80211_amrr_node *" +.Fa "int ok" +.Fa "int retries" +.Fc +.\" +.Ft void +.Fo ieee80211_amrr_tx_update +.Fa "struct ieee80211_amrr_node *" +.Fa "int txnct" +.Fa "int success" +.Fa "int retrycnt" +.Fc +.Sh DESCRIPTION +.Nm +is an implementation of the AMRR transmit rate control algorithm +for drivers that use the +.Nm net80211 +software layer. +A rate control algorithm is responsible for choosing the transmit +rate for each frame. +To maximize throughput algorithms try to use the highest rate that +is appropriate for the operating conditions. +The rate will vary as conditions change; the distance between two stations +may change, transient noise may be present that affects signal quality, +etc. +.Nm +uses very simple information from a driver to do it's job: +whether a frame was successfully delivered and how many transmit +attempts were made. +While this enables its use with virtually any wireless device it +limits it's effectiveness--do not expect it to function well in +difficult environments and/or respond quickly to changing conditions. +.Pp +.Nm +requires per-vap state and per-node state for each station it is to +select rates for. +The API's are designed for drivers to pre-allocate state in the +driver-private extension areas of each vap and node. +For example the +.Xr ral 4 +driver defines a vap as: +.Bd -literal -offset indent +struct rt2560_vap { + struct ieee80211vap ral_vap; + struct ieee80211_beacon_offsets ral_bo; + struct ieee80211_amrr amrr; + + int (*ral_newstate)(struct ieee80211vap *, + enum ieee80211_state, int); +}; +.Ed +.Pp +The +.Vt amrr +structure member holds the per-vap state for +.Nm +and +.Xr ral 4 +initializes it in the vap create method with: +.Bd -literal -offset indent +ieee80211_amrr_init(&rvp->amrr, vap, + IEEE80211_AMRR_MIN_SUCCESS_THRESHOLD, + IEEE80211_AMRR_MAX_SUCCESS_THRESHOLD, + 500 /* ms */); +.Ed +.Pp +The node is defined as: +.Bd -literal -offset indent +struct rt2560_node { + struct ieee80211_node ni; + struct ieee80211_amrr_node amrr; +}; +.Ed +.Pp +with initialization done in the driver's +.Vt iv_newassoc +method: +.Bd -literal -offset indent +static void +rt2560_newassoc(struct ieee80211_node *ni, int isnew) +{ + struct ieee80211vap *vap = ni->ni_vap; + + ieee80211_amrr_node_init(&RT2560_VAP(vap)->amrr, + &RT2560_NODE(ni)->amrr, ni); +} +.Ed +.Pp +Once +.Nm +state is setup, transmit rates are requested by calling +.Fn ieee80211_amrr_choose +in the transmit path; e.g.: +.Bd -literal -offset indent +tp = &vap->iv_txparms[ieee80211_chan2mode(ni->ni_chan)]; +if (IEEE80211_IS_MULTICAST(wh->i_addr1)) { + rate = tp->mcastrate; +} else if (m0->m_flags & M_EAPOL) { + rate = tp->mgmtrate; +} else if (tp->ucastrate != IEEE80211_FIXED_RATE_NONE) { + rate = tp->ucastrate; +} else { + (void) ieee80211_amrr_choose(ni, &RT2560_NODE(ni)->amrr); + rate = ni->ni_txrate; +} +.Ed +.Pp +Note a rate is chosen only for unicast data frames when a fixed +transmit rate is not configured; the other cases are handled with +the +.Nm net80211 +transmit parameters. +Note also that +.Fn ieee80211_amrr_choose +writes the chosen rate in +.Vt ni_txrate ; +this eliminates copying the value as it is exported to user applications so +they can display the current transmit rate in status. +.Pp +The remaining work a driver must do is feed status back to +.Nm +when a frame transmit completes using +.Fn ieee80211_amrr_tx_complete . +Drivers that poll a device to retrieve statistics can use +.Fn ieee80211_amrr_tx_update +(instead or in addition). +.Sh SEE ALSO +.Xr ieee80211 9 , +.Xr ieee80211_output 9 diff --git a/static/freebsd/man9/ieee80211_beacon.9 b/static/freebsd/man9/ieee80211_beacon.9 new file mode 100644 index 00000000..3738b7df --- /dev/null +++ b/static/freebsd/man9/ieee80211_beacon.9 @@ -0,0 +1,113 @@ +.\" +.\" Copyright (c) 2009 Sam Leffler, Errno Consulting +.\" 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 August 4, 2009 +.Dt IEEE80211_BEACON 9 +.Os +.Sh NAME +.Nm ieee80211_beacon +.Nd 802.11 beacon support +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.Pp +.Ft "struct mbuf *" +.Fo ieee80211_beacon_alloc +.Fa "struct ieee80211_node *" +.Fa "struct ieee80211_beacon_offsets *" +.Fc +.\" +.Ft int +.Fo ieee80211_beacon_update +.Fa "struct ieee80211_node *" +.Fa "struct ieee80211_beacon_offsets *" +.Fa "struct mbuf *" +.Fa "int mcast" +.Fc +.\" +.Ft void +.Fn ieee80211_beacon_notify "struct ieee80211vap *" "int what" +.Sh DESCRIPTION +The +.Nm net80211 +software layer provides a support framework for drivers that includes +a template-based mechanism for dynamic update of beacon frames transmit +in hostap, adhoc, and mesh operating modes. +Drivers should use +.Fn ieee80211_beacon_alloc +to create an initial beacon frame. +The +.Vt ieee80211_beacon_offsets +structure holds information about the beacon contents that is used +to optimize updates done with +.Fn ieee80211_beacon_update . +.Pp +Update calls should only be done when something changes that +affects the contents of the beacon frame. +When this happens the +.Dv iv_update_beacon +method is invoked and a driver-supplied routine must do the right thing. +For devices that involve the host to transmit each +beacon frame this work may be as simple as marking a bit in the +.Vt ieee80211_beacon_offsets +structure: +.Bd -literal +static void +ath_beacon_update(struct ieee80211vap *vap, int item) +{ + struct ieee80211_beacon_offsets *bo = &ATH_VAP(vap)->av_boff; + setbit(bo->bo_flags, item); +} +.Ed +.Pp +with the +.Fn ieee80211_beacon_update +call done before the next beacon is to be sent. +.Pp +Devices that off-load beacon generation may instead choose to use +this callback to push updates immediately to the device. +Exactly how that is accomplished is unspecified. +One possibility is to update the beacon frame contents and extract +the appropriate information element, but other scenarios are possible. +.Sh MULTI-VAP BEACON SCHEDULING +Drivers that support multiple vaps that can each beacon need to consider +how to schedule beacon frames. +There are two possibilities at the moment: +.Em burst +all beacons at TBTT or +.Em stagger beacons +over the beacon interval. +Bursting beacon frames may result in aperiodic delivery that can affect +power save operation of associated stations. +Applying some jitter (e.g. by randomly ordering burst frames) may be +sufficient to combat this and typically this is not an issue unless +stations are using aggressive power save techniques +such as U-APSD (sometimes employed by VoIP phones). +Staggering frames requires more interrupts and device support that +may not be available. +Staggering beacon frames is usually superior to bursting frames, up to +about eight vaps, at which point the overhead becomes significant and +the channel becomes noticeably busy anyway. +.Sh SEE ALSO +.Xr ieee80211 9 diff --git a/static/freebsd/man9/ieee80211_bmiss.9 b/static/freebsd/man9/ieee80211_bmiss.9 new file mode 100644 index 00000000..2c3661b6 --- /dev/null +++ b/static/freebsd/man9/ieee80211_bmiss.9 @@ -0,0 +1,89 @@ +.\" +.\" Copyright (c) 2009 Sam Leffler, Errno Consulting +.\" 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 August 4, 2009 +.Dt IEEE80211_BMISS 9 +.Os +.Sh NAME +.Nm ieee80211_bmiss +.Nd 802.11 beacon miss support +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.Pp +.Ft void +.Fn ieee80211_beacon_miss "struct ieee80211com *" +.Sh DESCRIPTION +The +.Nm net80211 +software layer provides a support framework for drivers that includes +handling beacon miss events in station mode. +Drivers can dispatch beacon miss events that are recognized in hardware or +.Nm net80211 +can detect beacon miss if the driver dispatches received beacon frames +through the normal receive path. +Software beacon miss support is especially useful when multiple vaps +are operating and any hardware beacon miss support is not available +(e.g. operating as an access point together with one or more station +mode vaps). +.Pp +Drivers should dispatch beacon miss events recognized in the driver with +.Fn ieee80211_beacon_miss . +This causes some number of ProbeRequest frames to be sent to the +access point to check if the association is still alive. +If no response is received and roaming mode is set to +.Dv IEEE80211_ROAMING_AUTO +then +.Nm net80211 +will try to re-associate and if that fails +trigger a scan to look for the access point or another suitable AP. +When the +.Nm net80211 +state machine is being operated manually, e.g. by +.Xr wpa_supplicant 8 , +then applications are notified of the state change and are responsible +for handling the work of scanning for a new access point. +The number of beacon miss events (without a ProbeResponse) is user +settable with the +.Dv IEEE80211_IOC_BMISSTHRESHOLD +request. +.Pp +Software beacon miss detection is enabled per-vap by setting the +.Dv IEEE80211_FEXT_SWBMISS +flag. +Typically this is done when a vap is setup +when the +.Dv IEEE80211_CLONE_NOBEACONS +option is supplied to the clone operation. +But drivers may also force this when they know they need help detecting +beacon miss. +When beacon miss is detected in software the event is dispatched without +driver involvement. +Note that software beacon miss handling is not limited to station mode; +it can be used in any operating mode where beacons from a peer station +are received. +.Sh SEE ALSO +.Xr wpa_supplicant 8 , +.Xr ieee80211 9 , +.Xr ieee80211_vap 9 diff --git a/static/freebsd/man9/ieee80211_crypto.9 b/static/freebsd/man9/ieee80211_crypto.9 new file mode 100644 index 00000000..7e2d5558 --- /dev/null +++ b/static/freebsd/man9/ieee80211_crypto.9 @@ -0,0 +1,258 @@ +.\" +.\" Copyright (c) 2004 Bruce M. Simpson +.\" Copyright (c) 2004 Darron Broad +.\" 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. +.\" $Id: ieee80211_crypto.9,v 1.3 2004/03/04 10:42:56 bruce Exp $ +.\" +.Dd March 29, 2010 +.Dt IEEE80211_CRYPTO 9 +.Os +.Sh NAME +.Nm ieee80211_crypto +.Nd 802.11 cryptographic support +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.\" +.Pp +.Ft void +.Fn ieee80211_crypto_register "const struct ieee80211_cipher *" +.\" +.Ft void +.Fn ieee80211_crypto_unregister "const struct ieee80211_cipher *" +.\" +.Ft int +.Fn ieee80211_crypto_available "int cipher" +.\" +.Pp +.Ft void +.Fo ieee80211_notify_replay_failure +.Fa "struct ieee80211vap *" +.Fa "const struct ieee80211_frame *" +.Fa "const struct ieee80211_key *" +.Fa "uint64_t rsc" +.Fa "int tid" +.Fc +.\" +.Ft void +.Fo ieee80211_notify_michael_failure +.Fa "struct ieee80211vap *" +.Fa "const struct ieee80211_frame *" +.Fa "u_int keyix" +.Fc +.\" +.Ft int +.Fo ieee80211_crypto_newkey +.Fa "struct ieee80211vap *" +.Fa "int cipher" +.Fa "int flags" +.Fa "struct ieee80211_key *" +.Fc +.\" +.Ft int +.Fn ieee80211_crypto_setkey "struct ieee80211vap *" "struct ieee80211_key *" +.\" +.Ft int +.Fn ieee80211_crypto_delkey "struct ieee80211vap *" "struct ieee80211_key *" +.\" +.Ft void +.Fn ieee80211_key_update_begin "struct ieee80211vap *" +.\" +.Ft void +.Fn ieee80211_key_update_end "struct ieee80211vap *" +.\" +.Ft void +.Fn ieee80211_crypto_delglobalkeys "struct ieee80211vap *" +.\" +.Ft void +.Fn ieee80211_crypto_reload_keys "struct ieee80211com *" +.\" +.Pp +.Ft struct ieee80211_key * +.Fn ieee80211_crypto_encap "struct ieee80211_node *" "struct mbuf *" +.\" +.Ft struct ieee80211_key * +.Fn ieee80211_crypto_decap "struct ieee80211_node *" "struct mbuf *" "int flags" +.\" +.Ft int +.Fo ieee80211_crypto_demic +.Fa "struct ieee80211vap *" +.Fa "struct ieee80211_key *" +.Fa "struct mbuf *" +.Fa "int force" +.Fc +.\" +.Ft int +.Fo ieee80211_crypto_enmic +.Fa "struct ieee80211vap *" +.Fa "struct ieee80211_key *" +.Fa "struct mbuf *" +.Fa "int force" +.Fc +.Sh DESCRIPTION +The +.Nm net80211 +layer includes comprehensive cryptographic support for 802.11 protocols. +Software implementations of ciphers required by +WPA and 802.11i are provided as well as encap/decap processing of 802.11 frames. +Software ciphers are written as kernel modules and +register with the core crypto support. +The cryptographic framework supports hardware acceleration of ciphers +by drivers with automatic fall-back to software implementations when a +driver is unable to provide necessary hardware services. +.Sh CRYPTO CIPHER MODULES +.Nm net80211 +cipher modules register their services using +.Fn ieee80211_crypto_register +and supply a template that describes their operation. +This +.Vt ieee80211_cipher +structure defines protocol-related state such as the number of bytes +of space in the 802.11 header to reserve/remove during encap/decap +and entry points for setting up keys and doing cryptographic operations. +.Pp +Cipher modules can associate private state to each key through the +.Vt wk_private +structure member. +If state is setup by the module it will be called before a key is destroyed +so it can reclaim resources. +.Pp +Crypto modules can notify the system of two events. +When a packet replay event is recognized +.Fn ieee80211_notify_replay_failure +can be used to signal the event. +When a +.Dv TKIP +Michael failure is detected +.Fn ieee80211_notify_michael_failure +can be invoked. +Drivers may also use these routines to signal events detected by the +hardware. +.Sh CRYPTO KEY MANAGEMENT +The +.Nm net80211 +layer implements a per-vap 4-element +.Dq global key table +and a per-station +.Dq unicast key +for protocols such as WPA, 802.1x, and 802.11i. +The global key table is designed to support legacy WEP operation +and Multicast/Group keys, +though some applications also use it to implement WPA in station mode. +Keys in the global table are identified by a key index in the range 0-3. +Per-station keys are identified by the MAC address of the station and +are typically used for unicast PTK bindings. +.Pp +.Nm net80211 +provides +.Xr ioctl 2 +operations for managing both global and per-station keys. +Drivers typically do not participate in software key management; +they are involved only when providing hardware acceleration of +cryptographic operations. +.Pp +.Fn ieee80211_crypto_newkey +is used to allocate a new +.Nm net80211 +key or reconfigure an existing key. +The cipher must be specified along with any fixed key index. +The +.Nm net80211 +layer will handle allocating cipher and driver resources to support the key. +.Pp +Once a key is allocated it's contents can be set using +.Fn ieee80211_crypto_setkey +and deleted with +.Fn ieee80211_crypto_delkey +(with any cipher and driver resources reclaimed). +.Pp +.Fn ieee80211_crypto_delglobalkeys +is used to reclaim all keys in the global key table for a vap; it +typically is used only within the +.Nm net80211 +layer. +.Pp +.Fn ieee80211_crypto_reload_keys +handles hardware key state reloading from software key state, such +as required after a suspend/resume cycle. +.Sh DRIVER CRYPTO SUPPORT +Drivers identify ciphers they have hardware support for through the +.Vt ic_cryptocaps +field of the +.Vt ieee80211com +structure. +If hardware support is available then a driver should also fill in the +.Dv iv_key_alloc , +.Dv iv_key_set , +and +.Dv iv_key_delete +methods of each +.Vt ieee80211vap +created for use with the device. +In addition the methods +.Dv iv_key_update_begin +and +.Dv iv_key_update_end +can be setup to handle synchronization requirements +for updating hardware key state. +.Pp +When +.Nm net80211 +allocates a software key and the driver can accelerate the +cipher operations the +.Dv iv_key_alloc +method will be invoked. +Drivers may return a token that is associated with outbound traffic +(for use in encrypting frames). +Otherwise, e.g. if hardware resources are not available, the driver will +not return a token and +.Nm net80211 +will arrange to do the work in software and pass frames +to the driver that are already prepared for transmission. +.Pp +For receive, drivers mark frames with the +.Dv M_WEP +mbuf flag to indicate the hardware has decrypted the payload. +If frames have the +.Dv IEEE80211_FC1_PROTECTED +bit marked in their 802.11 header and are not tagged with +.Dv M_WEP +then decryption is done in software. +For more complicated scenarios the software key state is consulted; e.g. +to decide if Michael verification needs to be done in software after +the hardware has handled TKIP decryption. +.Pp +Drivers that manage complicated key data structures, e.g. faulting +software keys into a hardware key cache, can safely manipulate software +key state by bracketing their work with calls to +.Fn ieee80211_key_update_begin +and +.Fn ieee80211_key_update_end . +These calls also synchronize hardware key state update +when receive traffic is active. +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr wlan_ccmp 4 , +.Xr wlan_tkip 4 , +.Xr wlan_wep 4 , +.Xr ieee80211 9 diff --git a/static/freebsd/man9/ieee80211_ddb.9 b/static/freebsd/man9/ieee80211_ddb.9 new file mode 100644 index 00000000..0b4e9e23 --- /dev/null +++ b/static/freebsd/man9/ieee80211_ddb.9 @@ -0,0 +1,69 @@ +.\" +.\" Copyright (c) 2009 Sam Leffler, Errno Consulting +.\" 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 August 4, 2009 +.Dt IEEE80211_DDB 9 +.Os +.Sh NAME +.Nm ieee80211_ddb +.Nd 802.11 ddb support +.Sh SYNOPSIS +.Bd -ragged +.Cd options DDB +.Ed +.Bd -ragged +.Cd show vap [addr] +.Cd show all vaps +.Cd show com [addr] +.Cd show sta [addr] +.Cd show statab [addr] +.Cd show mesh [addr] +.Ed +.Sh DESCRIPTION +The +.Nm net80211 +layer includes +.Xr ddb 4 +support for displaying important data structures. +This is especially important because wireless applications are often +built for embedded environments where cross-machine or post-mortem +debugging facilities like +.Xr kgdb 1 Pq Pa ports/devel/gdb +are infeasible. +.Pp +The most commonly used command is +.Bd -literal -offset indent +show all vaps/a +.Ed +.Pp +which dumps the contents of all +.Vt ieee80211vap , +.Vt ieee80211com , +and +.Vt ieee80211_node +data structures in the system. +.Sh SEE ALSO +.Xr ddb 4 , +.Xr ieee80211 9 diff --git a/static/freebsd/man9/ieee80211_input.9 b/static/freebsd/man9/ieee80211_input.9 new file mode 100644 index 00000000..7556bbc6 --- /dev/null +++ b/static/freebsd/man9/ieee80211_input.9 @@ -0,0 +1,114 @@ +.\" +.\" Copyright (c) 2004 Bruce M. Simpson +.\" Copyright (c) 2004 Darron Broad +.\" 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 August 4, 2009 +.Dt IEEE80211_INPUT 9 +.Os +.Sh NAME +.Nm ieee80211_input +.Nd software 802.11 stack input functions +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.Ft void +.Fo ieee80211_input +.Fa "struct ieee80211_node *" +.Fa "struct mbuf *" +.Fa "int rssi" +.Fa "int noise" +.Fc +.Ft void +.Fo ieee80211_input_all +.Fa "struct ieee80211com *" +.Fa "struct mbuf *" +.Fa "int rssi" +.Fa "int noise" +.Fc +.Sh DESCRIPTION +The +.Nm net80211 +layer that supports 802.11 device drivers requires that +receive processing be single-threaded. +Typically this is done using a dedicated driver +.Xr taskqueue 9 +thread. +.Fn ieee80211_input +and +.Fn ieee80211_input_all +process received 802.11 frames and are designed +for use in that context; e.g. no driver locks may be held. +.Pp +The frame passed up in the +.Vt mbuf +must have the 802.11 protocol header at the front; all device-specific +information and/or PLCP must be removed. +Any CRC must be stripped from the end of the frame. +The 802.11 protocol header should be 32-bit aligned for +optimal performance but receive processing does not require it. +If the frame holds a payload and that is not aligned to a 32-bit +boundary then the payload will be re-aligned so that it is suitable +for processing by protocols such as +.Xr ip 4 . +.Pp +If a device (such as +.Xr ath 4 ) +inserts padding after the 802.11 header to align +the payload to a 32-bit boundary the +.Dv IEEE80211_C_DATAPAD +capability must be set. +Otherwise header and payload are assumed contiguous in the mbuf chain. +.Pp +If a received frame must pass +through the A-MPDU receive reorder buffer then the mbuf +must be marked with the +.Dv M_AMPDU +flag. +Note that for the moment this is required of all frames received from +a station and TID where a Block ACK stream is active, not just A-MPDU +aggregates. +It is sufficient to check for +.Dv IEEE80211_NODE_HT +in the +.Vt ni_flags +of the station's node table entry, any frames that do not require reorder +processing will be dispatched with only minimal overhead. +.Pp +The +.Vt rssi +parameter is the Receive Signal Strength Indication of the frame +measured in 0.5dBm units relative to the noise floor. +The +.Vt noise +parameter is the best approximation of the noise floor in +dBm units at the time the frame was received. +RSSI and noise are used by the +.Nm net80211 +layer to make scanning and roaming decisions in station mode +and to do auto channel selection for hostap and similar modes. +Otherwise the values are made available to user applications +(with the rssi presented as a filtered average over the last ten values +and the noise floor the last reported value). +.Sh SEE ALSO +.Xr ieee80211 9 diff --git a/static/freebsd/man9/ieee80211_node.9 b/static/freebsd/man9/ieee80211_node.9 new file mode 100644 index 00000000..6dd492e3 --- /dev/null +++ b/static/freebsd/man9/ieee80211_node.9 @@ -0,0 +1,242 @@ +.\" +.\" Copyright (c) 2004 Bruce M. Simpson +.\" Copyright (c) 2004 Darron Broad +.\" 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 October 2, 2023 +.Dt IEEE80211_NODE 9 +.Os +.Sh NAME +.Nm ieee80211_node +.Nd software 802.11 stack node management functions +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.\" +.Ft struct ieee80211_node * +.Fo ieee80211_find_rxnode +.Fa "struct ieee80211com *" +.Fa "const struct ieee80211_frame_min *" +.Fc +.\" +.Ft struct ieee80211_node * +.Fo ieee80211_find_rxnode_withkey +.Fa "struct ieee80211com *" +.Fa "const struct ieee80211_frame_min *" +.Fa "ieee80211_keyix" +.Fc +.\" +.Ft struct ieee80211_node * +.Fn ieee80211_ref_node "struct ieee80211_node *" +.\" +.Ft void +.Fn ieee80211_free_node "struct ieee80211_node *" +.\" +.Ft void +.Fo ieee80211_iterate_nodes +.Fa "struct ieee80211_node_table *" +.Fa "ieee80211_iter_func *f" +.Fa "void *arg" +.Fc +.\" +.Ft void +.Fo ieee80211_dump_nodes +.Fa "struct ieee80211_node_table *" +.Fc +.\" +.Ft void +.Fo ieee80211_dump_node +.Fa "struct ieee80211_node *" +.Fc +.Sh DESCRIPTION +The +.Nm net80211 +layer that supports 802.11 device drivers maintains a database of +peer stations called the +.Dq node table +in the +.Vt ic_sta +entry of the +.Vt ieee80211com +structure. +Station mode vaps create an entry for the access point +the station is associated to. +AP mode vaps create entries for associated stations. +Adhoc and mesh mode vaps create entries for neighbor stations. +WDS mode vaps create an entry for the peer station. +Stations for all vaps reside in the same table; each node +entry has a +.Vt ni_vap +field that identifies the vap that created it. +In some instances an entry is used by multiple vaps (e.g. for +dynamic WDS a station associated to an ap vap may also be the peer +of a WDS vap). +.Pp +Node table entries are reference counted. +That is, there is a count of all long term references that determines +when an entry may be reclaimed. +References are held by every in-flight frame sent to a station to +ensure the entry is not reclaimed while the frame is queued or otherwise +held by a driver. +Routines that lookup a table entry return a +.Dq held reference +(i.e. a pointer to a table entry with the reference count incremented). +The +.Fn ieee80211_ref_node +call explicitly increments the reference count of a node. +.Fn ieee80211_free_node +decrements the reference count of a node and if the count goes to zero +reclaims the table entry. +.Pp +The station table and its entries are exposed to drivers in several ways. +Each frame transmitted to a station includes a reference to the +associated node in the +.Vt m_pkthdr.rcvif +field. +This reference must be reclaimed by the driver when transmit processing +is done. +For each frame received the driver must lookup the table entry to +use in dispatching the frame +.Dq up the stack . +This lookup implicitly obtains a reference to the table entry and +the driver must reclaim the reference when frame processing is completed. +Otherwise drivers frequently inspect the contents of the +.Vt iv_bss +node when handling state machine changes as important information +is maintained in the data structure. +.Pp +The node table is opaque to drivers. +Entries may be looked up using one of the pre-defined API's or the +.Fn ieee80211_iterate_nodes +call may be used to iterate through all entries to do per-node +processing or implement some non-standard search mechanism. +Note that +.Fn ieee80211_iterate_nodes +is single-threaded per-device +and the effort processing involved is fairly +substantial so it should be used carefully. +.Pp +Two routines are provided to print the contents of nodes to the console +for debugging: +.Fn ieee80211_dump_node +displays the contents of a single node while +.Fn ieee80211_dump_nodes +displays the contents of the specified node table. +Nodes may also be displayed using +.Xr ddb 4 +with the +.Dq show node +directive and the station node table can be displayed with +.Dq show statab . +.Sh DRIVER PRIVATE STATE +Node data structures may be extended by the driver to include +driver-private state. +This is done by overriding the +.Vt ic_node_alloc +method used to allocate a node table entry. +The driver method must allocate a structure that is an extension +of the +.Vt ieee80211_node +structure. +For example the +.Xr iwi 4 +driver defines a private node structure as: +.Bd -literal -offset indent +struct iwi_node { + struct ieee80211_node in_node; + int in_station; +}; +.Ed +.Pp +and then provides a private allocation routine that does this: +.Bd -literal -offset indent +static struct ieee80211_node * +iwi_node_alloc(struct ieee80211vap *vap, + const uint8_t mac[IEEE80211_ADDR_LEN]) +{ + struct iwi_node *in; + + in = malloc(sizeof(struct iwi_node), M_80211_NODE, + M_NOWAIT | M_ZERO); + if (in == NULL) + return NULL; + in->in_station = -1; + return &in->in_node; +} +.Ed +.Pp +Note that when reclaiming a node allocated by the driver the +.Dq parent method +must be called to ensure +.Nm net80211 +state is reclaimed; for example: +.Bd -literal -offset indent +static void +iwi_node_free(struct ieee80211_node *ni) +{ + struct ieee80211com *ic = ni->ni_ic; + struct iwi_softc *sc = ic->ic_ifp->if_softc; + struct iwi_node *in = (struct iwi_node *)ni; + + if (in->in_station != -1) + free_unr(sc->sc_unr, in->in_station); + sc->sc_node_free(ni); /* invoke net80211 free handler */ +} +.Ed +.Pp +Beware that care must be taken to avoid holding references that +might cause nodes from being reclaimed. +.Nm net80211 +will reclaim a node when the last reference is reclaimed in +its data structures. +However if a driver holds additional references then +.Nm net80211 +will not recognize this and table entries will not be reclaimed. +Such references should not be needed if the driver overrides the +.Vt ic_node_cleanup +and/or +.Vt ic_node_free +methods. +.Sh KEY TABLE SUPPORT +Node table lookups are typically done using a hash of the stations' +mac address. +When receiving frames this is sufficient to find the node table entry +for the transmitter. +But some devices also identify the sending station in the device +state received with each frame and this data can be used to optimize +lookups on receive using a companion table called the +.Dq keytab . +This table records a separate node table reference that can be fetched +without any locking using the table index. +This logic is handled with the +.Fn ieee80211_find_rxnode_withkey +call: if a keytab entry is found using the specified index then it is +returned directly; otherwise a normal lookup is done and the keytab +entry is written using the specified index. +If the specified index is +.Dv IEEE80211_KEYIX_NONE +then a normal lookup is done without a table update. +.Sh SEE ALSO +.Xr ddb 4 , +.Xr ieee80211 9 , +.Xr ieee80211_proto 9 diff --git a/static/freebsd/man9/ieee80211_output.9 b/static/freebsd/man9/ieee80211_output.9 new file mode 100644 index 00000000..80aa6d69 --- /dev/null +++ b/static/freebsd/man9/ieee80211_output.9 @@ -0,0 +1,192 @@ +.\" +.\" Copyright (c) 2004 Bruce M. Simpson +.\" Copyright (c) 2004 Darron Broad +.\" 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. +.\" $Id: ieee80211_output.9,v 1.5 2004/03/04 12:31:18 bruce Exp $ +.\" +.Dd March 29, 2010 +.Dt IEEE80211_OUTPUT 9 +.Os +.Sh NAME +.Nm ieee80211_output +.Nd software 802.11 stack output functions +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.\" +.Ft int +.Fn M_WME_GETAC "struct mbuf *" +.\" +.Ft int +.Fn M_SEQNO_GET "struct mbuf *" +.\" +.Ft struct ieee80211_key * +.Fn ieee80211_crypto_encap "struct ieee80211_node *" "struct mbuf *" +.\" +.Ft void +.Fo ieee80211_process_callback +.Fa "struct ieee80211_node *" +.Fa "struct mbuf *" +.Fa "int" +.Fc +.Sh DESCRIPTION +The +.Nm net80211 +layer that supports 802.11 device drivers handles most of the +work required to transmit frames. +Drivers usually receive fully-encapsulated 802.11 frames that +have been classified and assigned a transmit priority; +all that is left is to do +crypto encapsulation, +prepare any hardware-specific state, +and +push the packet out to the device. +Outbound frames are either generated by the +.Nm net80211 +layer (e.g. management frames) or are passed down +from upper layers through the +.Xr ifnet 9 +transmit queue. +Data frames passed down for transmit flow through +.Nm net80211 +which handles aggregation, 802.11 encapsulation, and then +dispatches the frames to the driver through it's transmit queue. +.Pp +There are two control paths by which frames reach a driver for transmit. +Data packets are queued to the device's +.Vt if_snd +queue and the driver's +.Vt if_start +method is called. +Other frames are passed down using the +.Vt ic_raw_xmit +method without queueing (unless done by the driver). +The raw transmit path may include data frames from user applications +that inject them through +.Xr bpf 4 +and NullData frames generated by +.Nm net80211 +to probe for idle stations (when operating as an access point). +.Pp +.Nm net80211 +handles all state-related bookkeeping and management for the handling +of data frames. +Data frames are only transmit for a vap in the +.Dv IEEE80211_S_RUN +state; there is no need, for example, to check for frames sent down +when CAC or CSA is active. +Similarly, +.Nm net80211 +handles activities such as background scanning and power save mode, +frames will not be sent to a driver unless it is operating on the +BSS channel with +.Dq full power . +.Pp +All frames passed to a driver for transmit hold a reference to a +node table entry in the +.Vt m_pkthdr.rcvif +field. +The node is associated with the frame destination. +Typically it is the receiver's entry but in some situations it may be +a placeholder entry or the +.Dq next hop station +(such as in a mesh network). +In all cases the reference must be reclaimed with +.Fn ieee80211_free_node +when the transmit work is completed. +The rule to remember is: +.Nm net80211 +passes responsibility for the +.Vt mbuf +and +.Dq node reference +to the driver with each frame it hands off for transmit. +.Sh PACKET CLASSIFICATION +All frames passed by +.Nm net80211 +for transmit are assigned a priority based on any vlan tag +assigned to the receiving station and/or any Diffserv setting +in an IP or IPv6 header. +If both vlan and Diffserv priority are present the higher of the +two is used. +If WME/WMM is being used then any ACM policy (in station mode) is +also enforced. +The resulting AC is attached to the mbuf and may be read back using the +.Fn M_WME_GETAC +macro. +.Pp +PAE/EAPOL frames are tagged with an +.Dv M_EAPOL +mbuf flag; drivers should transmit them with care, usually by +using the transmit rate for management frames. +Multicast/broadcast frames are marked with the +.Dv M_MCAST +mbuf flag. +Frames coming out of a station's power save queue and that have +more frames immediately following are marked with the +.Dv M_MORE_DATA +mbuf flag. +Such frames will be queued consecutively in the driver's +.Vt if_snd +queue and drivers should preserve the ordering when passing +them to the device. +.Sh FRAGMENTED FRAMES +The +.Nm net80211 +layer will fragment data frames according to the setting of +.Vt iv_fragthreshold +if a driver marks the +.Dv IEEE80211_C_TXFRAG +capability. +Fragmented frames are placed +in the devices transmit queue with the fragments chained together with +.Vt m_nextpkt . +Each frame is marked with the +.Dv M_FRAG +mbuf flag, and the first and last are marked with +.Dv M_FIRSTFRAG +and +.Dv M_LASTFRAG , +respectively. +Drivers are expected to process all fragments or none. +.Sh TRANSMIT CALLBACKS +Frames sent by +.Nm net80211 +may be tagged with the +.Dv M_TXCB +mbuf flag to indicate a callback should be done +when their transmission completes. +The callback is done using +.Fn ieee80211_process_callback +with the last parameter set to a non-zero value if an error occurred +and zero otherwise. +Note +.Nm net80211 +understands that drivers may be incapable of determining status; +a device may not report if an ACK frame is received and/or a device may queue +transmit requests in its hardware and only report status on whether +the frame was successfully queued. +.Sh SEE ALSO +.Xr bpf 4 , +.Xr ieee80211 9 , +.Xr ifnet 9 diff --git a/static/freebsd/man9/ieee80211_proto.9 b/static/freebsd/man9/ieee80211_proto.9 new file mode 100644 index 00000000..9d2b3882 --- /dev/null +++ b/static/freebsd/man9/ieee80211_proto.9 @@ -0,0 +1,239 @@ +.\" +.\" Copyright (c) 2009 Sam Leffler, Errno Consulting +.\" 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 August 4, 2009 +.Dt IEEE80211_PROTO 9 +.Os +.Sh NAME +.Nm ieee80211_proto +.Nd 802.11 state machine support +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.Pp +.Ft void +.Fn ieee80211_start_all "struct ieee80211com *" +.Ft void +.Fn ieee80211_stop_all "struct ieee80211com *" +.Ft void +.Fn ieee80211_suspend_all "struct ieee80211com *" +.Ft void +.Fn ieee80211_resume_all "struct ieee80211com *" +.Pp +.Dv enum ieee80211_state ; +.Ft int +.Fn ieee80211_new_state "struct ieee80211vap *" "enum ieee80211_state" "int" +.Pp +.Ft void +.Fn ieee80211_wait_for_parent "struct ieee80211com *" +.Sh DESCRIPTION +The +.Nm net80211 +layer that supports 802.11 device drivers uses a state machine +to control operation of vaps. +These state machines vary according to the vap operating mode. +Station mode state machines follow the 802.11 MLME states +in the protocol specification. +Other state machines are simpler and reflect operational work +such as scanning for a BSS or automatically selecting a channel to +operate on. +When multiple vaps are operational the state machines are used to +coordinate operation such as choosing a channel. +The state machine mechanism also serves to bind the +.Nm net80211 +layer to a driver; this is described more below. +.Pp +The following states are defined for state machines: +.Bl -tag -width IEEE80211_S_ASSOC +.It Dv IEEE80211_S_INIT +Default/initial state. +A vap in this state should not hold any dynamic state (e.g. entries +for associated stations in the node table). +The driver must quiesce the hardware; e.g. there should be no +interrupts firing. +.It Dv IEEE80211_S_SCAN +Scanning for a BSS or choosing a channel to operate on. +Note that scanning can also take place in other states (e.g. when +background scanning is active); this state is entered when +initially bringing a vap to an operational state or after an +event such as a beacon miss (in station mode). +.It Dv IEEE80211_S_AUTH +Authenticating to an access point (in station mode). +This state is normally reached from +.Dv IEEE80211_S_SCAN +after selecting a BSS, but may also be reached from +.Dv IEEE80211_S_ASSOC +or +.Dv IEEE80211_S_RUN +if the authentication handshake fails. +.It Dv IEEE80211_S_ASSOC +Associating to an access point (in station mode). +This state is reached from +.Dv IEEE80211_S_AUTH +after successfully authenticating or from +.Dv IEEE80211_S_RUN +if a DisAssoc frame is received. +.It Dv IEEE80211_S_CAC +Doing Channel Availability Check (CAC). +This state is entered only when DFS is enabled and the channel selected +for operation requires CAC. +.It Dv IEEE80211_S_RUN +Operational. +In this state a vap can transmit data frames, accept requests for +stations associating, etc. +Beware that data traffic is also gated by whether the associated +.Dq port +is authorized. +When WPA/802.11i/802.1x is operational authorization may happen separately; +e.g. in station mode +.Xr wpa_supplicant 8 +must complete the handshakes and plumb the necessary keys before a port +is authorized. +In this state a BSS is operational and associated state is valid and may +be used; e.g. +.Vt ic_bss +and +.Vt ic_bsschan +are guaranteed to be usable. +.It Dv IEEE80211_S_CSA +Channel Switch Announcement (CSA) is pending. +This state is reached only from +.Dv IEEE80211_S_RUN +when either a CSA is received from an access point (in station mode) +or the local station is preparing to change channel. +In this state traffic may be muted depending on the Mute setting in the CSA. +.It Dv IEEE80211_S_SLEEP +Asleep to save power (in station mode). +This state is reached only from +.Dv IEEE80211_S_RUN +when power save operation is enabled and the local station is deemed +sufficiently idle to enter low power mode. +.El +.Pp +Note that states are ordered (as shown above); +e.g. a vap must be in the +.Dv IEEE80211_S_RUN +or +.Dq greater +before it can transmit frames. +Certain +.Nm net80211 +data are valid only in certain states; e.g. the +.Vt iv_bsschan +that specifies the channel for the operating BSS should never be used +except in +.Dv IEEE80211_S_RUN +or greater. +.Sh STATE CHANGES +State machine changes are typically handled internal to the +.Nm net80211 +layer in response to +.Xr ioctl 2 +requests, received frames, or external events such as a beacon miss. +The +.Fn ieee80211_new_state +function is used to initiate a state machine change on a vap. +The new state and an optional argument are supplied. +The request is initially processed to handle coordination of multiple vaps. +For example, only one vap at a time can be scanning, if multiple vaps +request a change to +.Dv IEEE80211_S_SCAN +the first will be permitted to run and the others will be +.Em deferred +until the scan operation completes at which time the selected channel +will be adopted. +Similarly +.Nm net80211 +handles coordination of combinations of vaps such as an AP and station vap +where the station may need to roam to follow the AP it is associated to +(dragging along the AP vap to the new channel). +Another important coordination is the handling of +.Dv IEEE80211_S_CAC +and +.Dv IEEE80211_S_CSA . +No more than one vap can ever be actively changing state at a time. +In fact +.Nm net80211 +single-threads the state machine logic in a dedicated +.Xr taskqueue 9 +thread that is also used to synchronize work such as scanning and +beacon miss handling. +.Pp +After multi-vap scheduling/coordination is done the per-vap +.Vt iv_newstate +method is called to carry out the state change work. +Drivers use this entry to setup private state and then dispatch +the call to the +.Nm net80211 +layer using the previously defined method pointer (in OOP-parlance they +call the +.Dq super method +). +.Pp +.Nm net80211 +handles two state changes specially. +On transition to +.Dv IEEE80211_S_RUN +the +.Dv IFF_DRV_OACTIVE +bit on the vap's transmit queue is cleared so traffic can flow. +On transition to +.Dv IEEE80211_S_INIT +any state in the scan cache associated with the vap is flushed +and any frames pending on the transmit queue are flushed. +.Sh DRIVER INTEGRATION +Drivers are expected to override the +.Vt iv_newstate +method to interpose their own code and handle setup work required +by state changes. +Otherwise drivers must call +.Fn ieee80211_start_all +in response to being marked up through an +.Dv SIOCSIFFLAGS +ioctl request and they should use +.Fn ieee80211_suspend_all +and +.Fn ieee80211_resume_all +to implement suspend/resume support. +.Pp +There is also an +.Fn ieee80211_stop_all +call to force all vaps to an +.Dv IEEE80211_S_INIT +state but this should not be needed by a driver; control is usually +handled by +.Nm net80211 +or, in the case of card eject or vap destroy, +work will be initiated outside the driver. +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr wpa_supplicant 8 , +.Xr ieee80211 9 , +.Xr ifnet 9 , +.Xr taskqueue 9 +.Sh HISTORY +The state machine concept was part of the original +.Nm ieee80211 +code base that first appeared in +.Nx 1.5 . diff --git a/static/freebsd/man9/ieee80211_radiotap.9 b/static/freebsd/man9/ieee80211_radiotap.9 new file mode 100644 index 00000000..74e4f839 --- /dev/null +++ b/static/freebsd/man9/ieee80211_radiotap.9 @@ -0,0 +1,298 @@ +.\" +.\" Copyright (c) 2004 Bruce M. Simpson , +.\" Darron Broad , +.\" David Young . +.\" 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 March 11, 2019 +.Dt IEEE80211_RADIOTAP 9 +.Os +.Sh NAME +.Nm ieee80211_radiotap +.Nd 802.11 device packet capture support +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.\" +.Pp +.Ft void +.Fo ieee80211_radiotap_attach +.Fa "struct ieee80211com *" +.Fa "struct ieee80211_radiotap_header *th" +.Fa "int tlen" +.Fa "uint32_t tx_radiotap" +.Fa "struct ieee80211_radiotap_header *rh" +.Fa "int rlen" +.Fa "uint32_t rx_radiotap" +.Fc +.\" +.Ft int +.Fn ieee80211_radiotap_active_vap "struct ieee80211vap *" +.\" +.Ft int +.Fn ieee80211_radiotap_active "struct ieee80211com *" +.\" +.Ft void +.Fn ieee80211_radiotap_tx "struct ieee80211vap *" "struct mbuf *" +.Sh DESCRIPTION +The +.Nm net80211 +layer used by 802.11 drivers includes support for a device-independent +packet capture format called +.Nm radiotap +that is understood by tools such as +.Xr tcpdump 1 . +This facility is designed for capturing 802.11 traffic, +including information that is not part of the normal 802.11 frame structure. +.Pp +Radiotap was designed to balance the desire for a hardware-independent, +extensible capture format against the need to +conserve CPU and memory bandwidth on embedded systems. +These considerations led to a format consisting of +a standard preamble followed by an extensible bitmap indicating the +presence of optional capture fields. +A +.Nm net80211 +device driver supporting +.Vt radiotap +defines two packed structures that it shares with +.Nm net80211 . +These structures embed an instance of a +.Vt ieee80211_radiotap_header +structure at the beginning, +with subsequent fields in the appropriate order, +and macros to set the bits of the +.Va it_present +bitmap to indicate which fields exist and are filled in by the driver. +This information is then supplied through the +.Fn ieee80211_radiotap_attach +call after a successful +.Fn ieee80211_ifattach +request. +.Pp +With radiotap setup, drivers just need to fill in per-packet +capture state for frames sent/received and dispatch capture state +in the transmit path (since control is not returned to the +.Nm net80211 +layer before the packet is handed to the device). +To minimize overhead this work should be done only when one +or more processes are actively capturing data; +this is checked with one of +.Fn ieee80211_radiotap_active_vap +and +.Fn ieee80211_radiotap_active . +In the transmit path capture work looks like this: +.Bd -literal -offset indent +if (ieee80211_radiotap_active_vap(vap)) { + ... /* record transmit state */ + ieee80211_radiotap_tx(vap, m); /* capture transmit event */ +} +.Ed +.Pp +While in the receive path capture is handled in +.Nm net80211 +but state must be captured before dispatching a frame: +.Bd -literal -offset indent +if (ieee80211_radiotap_active(ic)) { + ... /* record receive state */ +} +\&... +ieee80211_input(...); /* packet capture handled in net80211 */ +.Ed +.Pp +.\" +The following fields are defined for +.Vt radiotap , +in the order in which they should appear in the buffer supplied +to +.Nm net80211 . +.Bl -tag -width indent +.It Dv IEEE80211_RADIOTAP_TSFT +This field contains the unsigned 64-bit value, in microseconds, +of the MAC's 802.11 Time Synchronization Function (TSF). +In theory, for each received frame, this value is recorded +when the first bit of the MPDU arrived at the MAC. +In practice, hardware snapshots the TSF otherwise and one cannot assume +this data is accurate without driver adjustment. +.It Dv IEEE80211_RADIOTAP_FLAGS +This field contains a single unsigned 8-bit value, containing one or +more of these bit flags: +.Bl -tag -width indent +.It Dv IEEE80211_RADIOTAP_F_CFP +Frame was sent/received during the Contention Free Period (CFP). +.It Dv IEEE80211_RADIOTAP_F_SHORTPRE +Frame was sent/received with short preamble. +.It Dv IEEE80211_RADIOTAP_F_WEP +Frame was encrypted. +.It Dv IEEE80211_RADIOTAP_F_FRAG +Frame was an 802.11 fragment. +.It Dv IEEE80211_RADIOTAP_F_FCS +Frame contents includes the FCS. +.It Dv IEEE80211_RADIOTAP_F_DATAPAD +Frame contents potentially has padding between the 802.11 header and the +data payload to align the payload to a 32-bit boundary. +.It Dv IEEE80211_RADIOTAP_F_BADFCS +Frame was received with an invalid FCS. +.It Dv IEEE80211_RADIOTAP_F_SHORTGI +Frame was sent/received with Short Guard Interval. +.El +.It Dv IEEE80211_RADIOTAP_RATE +This field contains a single unsigned 8-bit value that is the data rate. +Legacy rates are in units of 500Kbps. +MCS rates (used on 802.11n/HT channels) have the high bit set and +the MCS in the low 7 bits. +.It Dv IEEE80211_RADIOTAP_CHANNEL +This field contains two unsigned 16-bit values. +The first value is the center frequency for the channel +the frame was sent/received on. +The second value is a bitmap containing flags that specify channel properties. +.Pp +This field is deprecated in favor of +.Dv IEEE80211_RADIOTAP_XCHANNEL +but may be used to save space in the capture file for legacy devices. +.\".It Dv IEEE80211_RADIOTAP_FHSS +.\"This field contains two 8-bit values. +.\"This field should be present only for frequency-hopping radios. +.\"The first byte is the hop set. +.\"The second byte is the pattern in use. +.It Dv IEEE80211_RADIOTAP_DBM_ANTSIGNAL +This field contains a single signed 8-bit value that indicates the +RF signal power at the antenna, in decibels difference from 1mW. +.It Dv IEEE80211_RADIOTAP_DBM_ANTNOISE +This field contains a single signed 8-bit value that indicates the +RF noise power at the antenna, in decibels difference from 1mW. +.\".It Dv IEEE80211_RADIOTAP_LOCK_QUALITY +.\"This field contains a single unsigned 16-bit value, indicating the +.\"quality of the Barker Code lock. +.\"No unit is specified for this field. +.\"There does not appear to be a standard way of measuring this at this time; +.\"this quantity is often referred to as +.\".Dq "Signal Quality" +.\"in some datasheets. +.\".It Dv IEEE80211_RADIOTAP_TX_ATTENUATION +.\"This field contains a single unsigned 16-bit value, expressing transmit +.\"power as unitless distance from maximum power set at factory calibration. +.\"0 indicates maximum transmit power. +.\"Monotonically nondecreasing with lower power levels. +.\".It Dv IEEE80211_RADIOTAP_DB_TX_ATTENUATION +.\"This field contains a single unsigned 16-bit value, expressing transmit +.\"power as decibel distance from maximum power set at factory calibration. +.\"0 indicates maximum transmit power. +.\"Monotonically nondecreasing with lower power levels. +.It Dv IEEE80211_RADIOTAP_DBM_TX_POWER +Transmit power expressed as decibels from a 1mW reference. +This field is a single signed 8-bit value. +This is the absolute power level measured at the antenna port. +.It Dv IEEE80211_RADIOTAP_ANTENNA +This field contains a single unsigned 8-bit value that specifies +which antenna was used to transmit or receive the frame. +Antenna numbering is device-specific but typically the primary antenna has +the lowest number. +On transmit a value of zero may be seen which typically means +antenna selection is left to the device. +.It Dv IEEE80211_RADIOTAP_DB_ANTSIGNAL +This field contains a single unsigned 8-bit value that indicates the +RF signal power at the antenna, in decibels difference from an +arbitrary, fixed reference. +.It Dv IEEE80211_RADIOTAP_DB_ANTNOISE +This field contains a single unsigned 8-bit value that indicates the +RF noise power at the antenna, in decibels difference from an +arbitrary, fixed reference. +.It Dv IEEE80211_RADIOTAP_XCHANNEL +This field contains four values: a 32-bit unsigned bitmap of +flags that describe the channel attributes, a 16-bit unsigned +frequency in MHz (typically the channel center), an 8-bit +unsigned IEEE channel number, and a signed 8-bit value that +holds the maximum regulatory transmit power cap in .5 dBm +(8 bytes total). +Channel flags are defined in: +.In net80211/_ieee80211.h +(only a subset are found in +.In net80211/ieee80211_radiotap.h ). +This property supersedes +.Dv IEEE80211_RADIOTAP_CHANNEL +and is the only way to completely express all +channel attributes and the +mapping between channel frequency and IEEE channel number. +.El +.Sh EXAMPLES +Radiotap receive definitions for the Intersil Prism driver: +.Bd -literal -offset indent +#define WI_RX_RADIOTAP_PRESENT \\ + ((1 << IEEE80211_RADIOTAP_TSFT) \\ + (1 << IEEE80211_RADIOTAP_FLAGS) | \\ + (1 << IEEE80211_RADIOTAP_RATE) | \\ + (1 << IEEE80211_RADIOTAP_CHANNEL) | \\ + (1 << IEEE80211_RADIOTAP_DB_ANTSIGNAL) | \\ + (1 << IEEE80211_RADIOTAP_DB_ANTNOISE)) + +struct wi_rx_radiotap_header { + struct ieee80211_radiotap_header wr_ihdr; + uint64_t wr_tsf; + uint8_t wr_flags; + uint8_t wr_rate; + uint16_t wr_chan_freq; + uint16_t wr_chan_flags; + uint8_t wr_antsignal; + uint8_t wr_antnoise; +} __packed __aligned(8); +.Ed +.Pp +and transmit definitions for the Atheros driver: +.Bd -literal -offset indent +#define ATH_TX_RADIOTAP_PRESENT ( \\ + (1 << IEEE80211_RADIOTAP_FLAGS) | \\ + (1 << IEEE80211_RADIOTAP_RATE) | \\ + (1 << IEEE80211_RADIOTAP_DBM_TX_POWER) | \\ + (1 << IEEE80211_RADIOTAP_ANTENNA) | \\ + (1 << IEEE80211_RADIOTAP_XCHANNEL) | \\ + 0) + +struct ath_tx_radiotap_header { + struct ieee80211_radiotap_header wt_ihdr; + uint8_t wt_flags; + uint8_t wt_rate; + uint8_t wt_txpower; + uint8_t wt_antenna; + uint32_t wt_chan_flags; + uint16_t wt_chan_freq; + uint8_t wt_chan_ieee; + int8_t wt_chan_maxpow; +} __packed; +.Ed +.Sh SEE ALSO +.Xr tcpdump 1 , +.Xr bpf 4 , +.Xr ieee80211 9 +.Sh HISTORY +The +.Nm +definitions first appeared in +.Nx 1.5 . +.\" +.Sh AUTHORS +.An -nosplit +The original version of this manual page was written by +.An Bruce M. Simpson Aq Mt bms@FreeBSD.org +and +.An Darron Broad Aq Mt darron@kewl.org . diff --git a/static/freebsd/man9/ieee80211_regdomain.9 b/static/freebsd/man9/ieee80211_regdomain.9 new file mode 100644 index 00000000..cf632724 --- /dev/null +++ b/static/freebsd/man9/ieee80211_regdomain.9 @@ -0,0 +1,141 @@ +.\" +.\" Copyright (c) 2009 Sam Leffler, Errno Consulting +.\" 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 August 4, 2009 +.Dt IEEE80211_REGDOMAIN 9 +.Os +.Sh NAME +.Nm ieee80211_regdomain +.Nd 802.11 regulatory support +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.In net80211/ieee80211_regdomain.h +.Pp +.Ft int +.Fo ieee80211_init_channels +.Fa "struct ieee80211com *" +.Fa "const struct ieee80211_regdomain *" +.Fa "const uint8_t bands[]" +.Fc +.\" +.Ft void +.Fo ieee80211_sort_channels +.Fa "struct ieee80211_channel *" +.Fa "int nchans" +.Fc +.\" +.Ft "struct ieee80211_appie *" +.Fn ieee80211_alloc_countryie "struct ieee80211com *" +.Sh DESCRIPTION +The +.Nm net80211 +software layer provides a support framework for drivers that includes +comprehensive regulatory support. +.Nm net80211 +provides mechanisms that enforce +.Em "regulatory policy" +by privileged user applications. +.Pp +Drivers define a device's capabilities and can +intercept and control regulatory changes requested through +.Nm net80211 . +The initial regulatory state, including the channel list, must be +filled in by the driver before calling +.Fn ieee80211_ifattach . +The channel list should reflect the set of channels the device is +.Em calibrated +for use on. +This list may also be requested later through the +.Vt ic_getradiocaps +method in the +.Vt ieee80211com +structure. +The +.Fn ieee80211_init_channels +function is provided as a rudimentary fallback for drivers that do not +(or cannot) fill in a proper channel list. +Default regulatory state is supplied such as the regulatory SKU, +ISO country code, location (e.g. indoor, outdoor), and a set of +frequency bands the device is capable of operating on. +.Nm net80211 +populates the channel table in +.Vt ic_channels +with a default set of channels and capabilities. +Note this mechanism should be used with care as any mismatch between +the channel list created and the device's capabilities can result +in runtime errors (e.g. a request to operate on a channel the device +does not support). +The SKU and country information are used for generating 802.11h protocol +elements and related operation such as for 802.11d; mis-setup by a +driver is not fatal, only potentially confusing. +.Pp +Devices that do not have a fixed/default regulatory state can set +the regulatory SKU to +.Dv SKU_DEBUG +and country code to +.Dv CTRY_DEFAULT +and leave proper setup to user applications. +If default settings are known they can be installed and/or an event +can be dispatched to user space using +.Fn ieee80211_notify_country +so that +.Xr devd 8 +will do the appropriate setup work at system boot (or device insertion). +.Pp +The channel table is sorted to optimize lookups using the +.Fn ieee80211_sort_channels +routine. +This should be done whenever the channel table contents are modified. +.Pp +The +.Fn ieee80211_alloc_countryie +function allocates an information element as specified by 802.11h. +Because this is expensive to generate it is cached in +.Vt ic_countryie +and generated only when regulatory state changes. +Drivers that call +.Fn ieee80211_alloc_countryie +directly should not help with this caching; doing so may confuse the +.Nm net80211 +layer. +.Sh DRIVER REGULATORY CONTROL +Drivers can control regulatory change requests by overriding the +.Vt ic_setregdomain +method that checks change requests. +While drivers can reject any request that does not meet its requirements +it is recommended that one be lenient in what is accepted and, whenever +possible, instead of rejecting a request, alter it to be correct. +For example, if the transmit power cap for a channel is too high the +driver can either reject the request or (better) reduce the cap to be +compliant. +Requests that include unacceptable channels should cause the request +to be rejected as otherwise a mismatch may be created between application +state and the state managed by +.Nm net80211 . +The exact rules by which to operate are still being codified. +.Sh SEE ALSO +.Xr regdomain 5 , +.Xr ifconfig 8 , +.Xr ieee80211 9 diff --git a/static/freebsd/man9/ieee80211_scan.9 b/static/freebsd/man9/ieee80211_scan.9 new file mode 100644 index 00000000..9dd0b125 --- /dev/null +++ b/static/freebsd/man9/ieee80211_scan.9 @@ -0,0 +1,348 @@ +.\" +.\" Copyright (c) 2009 Sam Leffler, Errno Consulting +.\" 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 March 29, 2010 +.Dt IEEE80211_SCAN 9 +.Os +.Sh NAME +.Nm ieee80211_scan +.Nd 802.11 scanning support +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.Pp +.Ft int +.Fo ieee80211_start_scan +.Fa "struct ieee80211vap *" +.Fa "int flags" +.Fa "u_int duration" +.Fa "u_int mindwell" +.Fa "u_int maxdwell" +.Fa "u_int nssid" +.Fa "const struct ieee80211_scan_ssid ssids[]" +.Fc +.\" +.Ft int +.Fo ieee80211_check_scan +.Fa "struct ieee80211vap *" +.Fa "int flags" +.Fa "u_int duration" +.Fa "u_int mindwell" +.Fa "u_int maxdwell" +.Fa "u_int nssid" +.Fa "const struct ieee80211_scan_ssid ssids[]" +.Fc +.\" +.Ft int +.Fn ieee80211_check_scan_current "struct ieee80211vap *" +.\" +.Ft int +.Fn ieee80211_bg_scan "struct ieee80211vap *" "int" +.\" +.Ft int +.Fn ieee80211_cancel_scan "struct ieee80211vap *" +.\" +.Ft int +.Fn ieee80211_cancel_scan_any "struct ieee80211vap *" +.\" +.Ft int +.Fn ieee80211_scan_next "struct ieee80211vap *" +.\" +.Ft int +.Fn ieee80211_scan_done "struct ieee80211vap *" +.\" +.Ft int +.Fn ieee80211_probe_curchan "struct ieee80211vap *" "int" +.\" +.Ft void +.Fo ieee80211_add_scan +.Fa "struct ieee80211vap *" +.Fa "const struct ieee80211_scanparams *" +.Fa "const struct ieee80211_frame *" +.Fa "int subtype" +.Fa "int rssi" +.Fa "int noise" +.Fc +.\" +.Ft void +.Fn ieee80211_scan_timeout "struct ieee80211com *" +.\" +.Ft void +.Fo ieee80211_scan_assoc_fail +.Fa "struct ieee80211vap *" +.Fa "const uint8_t mac[IEEE80211_ADDR_LEN]" +.Fa "int reason" +.Fc +.\" +.Ft void +.Fn ieee80211_scan_flush "struct ieee80211vap *" +.\" +.Ft void +.Fo ieee80211_scan_iterate +.Fa "struct ieee80211vap *" +.Fa "ieee80211_scan_iter_func" +.Fa "void *" +.Fc +.\" +.Ft void +.Fn ieee80211_scan_dump_channels "const struct ieee80211_scan_state *" +.\" +.Ft void +.Fo ieee80211_scanner_register +.Fa "enum ieee80211_opmode" +.Fa "const struct ieee80211_scanner *" +.Fc +.\" +.Ft void +.Fo ieee80211_scanner_unregister +.Fa "enum ieee80211_opmode" +.Fa "const struct ieee80211_scanner *" +.Fc +.\" +.Ft void +.Fn ieee80211_scanner_unregister_all "const struct ieee80211_scanner *" +.\" +.Ft const struct ieee80211_scanner * +.Fn ieee80211_scanner_get "enum ieee80211_opmode" +.Sh DESCRIPTION +The +.Nm net80211 +software layer provides an extensible framework for scanning. +Scanning is the procedure by which a station locates a BSS to join +(in infrastructure and IBSS mode), or a channel to use (when operating +as an AP or an IBSS master). +Scans are either +.Dq active +or +.Dq passive . +An active scan causes one or more ProbeRequest frames to be sent on +visiting each channel. +A passive request causes each channel in the scan set to be visited but +no frames to be transmitted; the station only listens for traffic. +Note that active scanning may still need to listen for traffic before +sending ProbeRequest frames depending on regulatory constraints. +.Pp +A scan operation involves constructing a set of channels to inspect +(the scan set), +visiting each channel and collecting information +(e.g. what BSS are present), +and then analyzing the results to make decisions such as which BSS to join. +This process needs to be as fast as possible so +.Nm net80211 +does things like intelligently construct scan sets and dwell on a channel +only as long as necessary. +Scan results are cached and the scan cache is used to avoid scanning when +possible and to enable roaming between access points when operating +in infrastructure mode. +.Pp +Scanning is handled by pluggable modules that implement +.Em policy +per-operating mode. +The core scanning support provides an infrastructure to support these +modules and exports a common API to the rest of the +.Nm net80211 +layer. +Policy modules decide what channels to visit, what state to record to +make decisions, and selects the final station/channel to return as the +result of a scan. +.Pp +Scanning is done synchronously when initially bringing a vap to +an operational state and optionally in the background to maintain +the scan cache for doing roaming and rogue AP monitoring. +Scanning is not tied to the +.Nm net80211 +state machine that governs vaps except for linkage to the +.Dv IEEE80211_S_SCAN +state. +Only one vap at a time may be scanning; this scheduling policy +is handled in +.Fn ieee80211_new_state +and is transparent to scanning code. +.Pp +Scanning is controlled by a set of parameters that (potentially) +constrains the channel set and any desired SSID's and BSSID's. +.Nm net80211 +comes with a standard scanner module that works with all available +operating modes and supports +.Dq background scanning +and +.Dq roaming +operation. +.Sh SCANNER MODULES +Scanning modules use a registration mechanism to hook into the +.Nm net80211 +layer. +Use +.Fn ieee80211_scanner_register +to register a scan module for a particular operating mode and +.Fn ieee80211_scanner_unregister +or +.Fn ieee80211_scanner_unregister_all +to clear entries (typically on module unload). +Only one scanner module can be registered at any time for an operating mode. +.Sh DRIVER SUPPORT +Scanning operations are usually managed by the +.Nm net80211 +layer. +Drivers must provide +.Vt ic_scan_start +and +.Vt ic_scan_stop +methods that are called at the start of a scan and when the +work is done; these should handle work such as enabling receive +of Beacon and ProbeResponse frames and disable any BSSID matching. +The +.Vt ic_set_channel +method is used to change channels while scanning. +.Nm net80211 +will generate ProbeRequest frames and transmit them using the +.Nm ic_raw_xmit +method. +Frames received while scanning are dispatched to +.Nm net80211 +using the normal receive path. +Devices that off-load scan work to firmware most easily mesh with +.Nm net80211 +by operating on a channel-at-a-time basis as this defers control to +.Nm net80211's +scan machine scheduler. +But multi-channel scanning +is supported if the driver manually dispatches results using +.Fn ieee80211_add_scan +routine to enter results into the scan cache. +.Sh SCAN REQUESTS +Scan requests occur by way of the +.Dv IEEE80211_SCAN_REQUEST +ioctl or through a change in a vap's state machine that requires +scanning. +In both cases the scan cache can be checked first and, if it is deemed +suitably +.Dq warm +then it's contents are used without leaving the current channel. +To start a scan without checking the cache +.Fn ieee80211_start_scan +can be called; otherwise +.Fn ieee80211_check_scan +can be used to first check the scan cache, kicking off a scan if +the cache contents are out of date. +There is also +.Fn ieee80211_check_scan_current +which is a shorthand for using previously set scan parameters for +checking the scan cache and then scanning. +.Pp +Background scanning is done using +.Fn ieee80211_bg_scan +in a co-routine fashion. +The first call to this routine will start a background scan that +runs for a limited period of time before returning to the BSS channel. +Subsequent calls advance through the scan set until all channels are +visited. +Typically these later calls are timed to allow receipt of +frames buffered by an access point for the station. +.Pp +A scan operation can be canceled using +.Fn ieee80211_cancel_scan +if it was initiated by the specified vap, or +.Fn ieee80211_cancel_scan_any +to force termination regardless which vap started it. +These requests are mostly used by +.Nm net80211 +in the transmit path to cancel background scans when frames are to be sent. +Drivers should not need to use these calls (or most of the calls described +on this page). +.Pp +The +.Fn ieee80211_scan_next +and +.Fn ieee80211_scan_done +routines do explicit iteration through the scan set and should +not normally be used by drivers. +.Fn ieee80211_probe_curchan +handles the work of transmitting ProbeRequest frames when visiting +a channel during an active scan. +When the channel attributes are marked with +.Dv IEEE80211_CHAN_PASSIVE +this function will arrange that before any frame is transmitted 802.11 +traffic is first received (in order to comply with regulatory constraints). +.Pp +Min/max dwell time parameters are used to constrain time spent visiting +a channel. +The maximum dwell time constrains the time spent listening for traffic. +The minimum dwell time is used to reduce this time--when it is reached +and one or more frames have been received then an immediate channel +change will be done. +Drivers can override this behaviour through the +.Vt iv_scan_mindwell +method. +.Sh SCAN CACHE MANAGEMENT +The scan cache contents are managed by the scan policy module and +are opaque outside this module. +The +.Nm net80211 +scan framework defines API's for interacting. +The validity of the scan cache contents are controlled by +.Vt iv_scanvalid +which is exported to user space through the +.Dv IEEE80211_SCAN_VALID +request. +.Pp +The cache contents can be explicitly flushed with +.Fn ieee80211_scan_flush +or by setting the +.Dv IEEE80211_SCAN_FLUSH +flag when starting a scan operation. +.Pp +Scan cache entries are created with the +.Fn ieee80211_add_scan +routine; usually on receipt of Beacon or ProbeResponse frames. +Existing entries are typically updated based on the latest information +though some information such as RSSI and noise floor readings may be +combined to present an average. +.Pp +The cache contents is aged through +.Fn ieee80211_scan_timeout +calls. +Typically these happen together with other station table activity; every +.Dv IEEE80211_INACT_WAIT +seconds (default 15). +.Pp +Individual cache entries are marked usable with +.Fn ieee80211_scan_assoc_success +and faulty with +.Fn ieee80211_scan_assoc_fail +with the latter taking an argument to identify if there was no response +to Authentication/Association requests or if a negative response was +received (which might hasten cache eviction or blacklist the entry). +.Pp +The cache contents can be viewed using the +.Fn ieee80211_scan_iterate +call. +Cache entries are exported in a public format that is exported to user +applications through the +.Dv IEEE80211_SCAN_RESULTS +request. +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr ieee80211 9 , +.Xr ieee80211_proto 9 diff --git a/static/freebsd/man9/ieee80211_vap.9 b/static/freebsd/man9/ieee80211_vap.9 new file mode 100644 index 00000000..ee811107 --- /dev/null +++ b/static/freebsd/man9/ieee80211_vap.9 @@ -0,0 +1,152 @@ +.\" +.\" Copyright (c) 2009 Sam Leffler, Errno Consulting +.\" 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 August 4, 2009 +.Dt IEEE80211_VAP 9 +.Os +.Sh NAME +.Nm net80211_vap +.Nd 802.11 network layer virtual radio support +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.Ft int +.Fo ieee80211_vap_setup +.Fa "struct ieee80211com *" +.Fa "struct ieee80211vap *" +.Fa "const char name[IFNAMSIZ]" +.Fa "int unit" +.Fa "int opmode" +.Fa "int flags" +.Fa "const uint8_t bssid[IEEE80211_ADDR_LEN]" +.Fa "const uint8_t macaddr[IEEE80211_ADDR_LEN]" +.Fc +.\" +.Ft int +.Fo ieee80211_vap_attach +.Fa "struct ieee80211vap *" +.Fa "ifm_change_cb_t media_change" +.Fa "ifm_stat_cb_t media_stat" +.Fc +.\" +.Ft void +.Fn ieee80211_vap_detach "struct ieee80211vap *" +.Sh DESCRIPTION +The +.Nm net80211 +software layer provides a support framework for drivers that includes +a virtual radio API that is exported to +users through network interfaces (aka vaps) that are cloned from the +underlying device. +These interfaces have an operating mode +(station, adhoc, hostap, wds, monitor, etc.\&) +that is fixed for the lifetime of the interface. +Devices that can support multiple concurrent interfaces allow +multiple vaps to be cloned. +.Pp +The virtual radio interface defined by the +.Nm net80211 +layer means that drivers must be structured to follow specific rules. +Drivers that support only a single interface at any time must still +follow these rules. +.Pp +The virtual radio architecture splits state between a single per-device +.Vt ieee80211com +structure and one or more +.Vt ieee80211vap +structures. +Vaps are created with the +.Dv SIOCIFCREATE2 +request. +This results in a call into the driver's +.Vt ic_vap_create +method where the driver can decide if the request should be accepted. +.Pp +The vap creation process is done in three steps. +First the driver allocates the data structure with +.Xr malloc 9 . +This data structure must have an +.Vt ieee80211vap +structure at the front but is usually extended with driver-private state. +Next the vap is setup with a call to +.Fn ieee80211_vap_setup . +This request initializes +.Nm net80211 +state but does not activate the interface. +The driver can then override methods setup by +.Nm net80211 +and setup driver resources before finally calling +.Fn ieee80211_vap_attach +to complete the process. +Both these calls must be done without holding any driver locks as +work may require the process block/sleep. +.Pp +A vap is deleted when an +.Dv SIOCIFDESTROY +ioctl request is made or when the device detaches (causing all +associated vaps to automatically be deleted). +Delete requests cause the +.Vt ic_vap_delete +method to be called. +Drivers must quiesce the device before calling +.Fn ieee80211_vap_detach +to deactivate the vap and isolate it from activities such as requests +from user applications. +The driver can then reclaim resources held by the vap and re-enable +device operation. +The exact procedure for quiescing a device is unspecified but typically +it involves blocking interrupts and stopping transmit and receive +processing. +.Sh MULTI-VAP OPERATION +Drivers are responsible for deciding if multiple vaps can be created +and how to manage them. +Whether or not multiple concurrent vaps can be supported depends on a +device's capabilities. +For example, multiple hostap vaps can usually be supported but many +devices do not support assigning each vap a unique BSSID. +If a device supports hostap operation it can usually support concurrent +station mode vaps but possibly with limitations such as losing support +for hardware beacon miss support. +Devices that are capable of hostap operation and can send and receive +4-address frames should be able to support WDS vaps together with an +ap vap. +But in contrast some devices cannot support WDS vaps without at least one +ap vap (this however can be finessed by forcing the ap vap to not transmit +beacon frames). +All devices should support the creation of any number of monitor mode vaps +concurrent with other vaps but it is the responsibility of the driver to +allow this. +.Pp +An important consequence of supporting multiple concurrent vaps is that +a driver's +.Vt iv_newstate +method must be written to handle being called for each vap. +Where necessary, drivers must track private state for all vaps +and not just the one whose state is being changed (e.g. for +handling beacon timers the driver may need to know if all vaps +that beacon are stopped before stopping the hardware timers). +.Sh SEE ALSO +.Xr ieee80211 9 , +.Xr ifnet 9 , +.Xr malloc 9 diff --git a/static/freebsd/man9/iflib.9 b/static/freebsd/man9/iflib.9 new file mode 100644 index 00000000..9f312b9d --- /dev/null +++ b/static/freebsd/man9/iflib.9 @@ -0,0 +1,42 @@ +.Dd September 20, 2018 +.Dt IFLIB 9 +.Os +.Sh NAME +.Nm iflib +.Nd Network Interface Driver Framework +.Sh DESCRIPTION +.Nm +is a framework for writing network interface drivers for +.Fx . +It is designed to remove a large amount of the boilerplate that is often +needed for modern network interface devices, allowing driver authors to +focus on the specific code needed for their hardware. +.Pp +There are three logical components to +.Nm +each of which is described in its own manual page. +These are: +.Bl -tag -width ".Xr iflibtxrx 9" +.It Xr iflibdi 9 +Device-independent functions, used to integrate +.Nm +into the rest of the +.Fx +networking stack. +.It Xr iflibdd 9 +Device-dependent functions, used when writing new +.Nm +based drivers. +.It Xr iflibtxrx 9 +Device-dependent transmit and receive functions, used when writing new +.Nm +based drivers. +.El +.Sh SEE ALSO +.Xr iflib 4 , +.Xr iflibdd 9 , +.Xr iflibdi 9 , +.Xr iflibtxrx 9 , +.Xr ifnet 9 +.Sh AUTHORS +.An Benno Rice Aq Mt benno@FreeBSD.org diff --git a/static/freebsd/man9/iflibdd.9 b/static/freebsd/man9/iflibdd.9 new file mode 100644 index 00000000..67645fe5 --- /dev/null +++ b/static/freebsd/man9/iflibdd.9 @@ -0,0 +1,318 @@ +.Dd May 3, 2018 +.Dt IFLIBDD 9 +.Os +.Sh NAME +.Nm iflibdd +.Nd Device Dependent Configuration Functions +.Sh SYNOPSIS +.In "ifdi_if.h" +.Ss "Soft Queue Setup and Teardown Functions" +.Ss "Mandatory Functions" +.Ft int +.Fo ifdi_tx_queues_alloc +.Fa "if_ctx_t ctx" +.Fa "caddr_t *vaddrs" +.Fa "uint64_t *paddrs" +.Fa "int ntxqs" +.Fa "int ntxqsets" +.Fc +.Ft int +.Fo ifdi_rx_queues_alloc +.Fa "if_ctx_t ctx" +.Fa "caddr_t *vaddrs" +.Fa "uint64_t *paddrs" +.Fa "int nrxqs" +.Fa "int nrxqsets" +.Fc +.Ft int +.Fo ifdi_queues_free +.Fa "if_ctx_t ctx" +.Fc +.Ss "Optional Functions" +.Ft int +.Fo ifdi_txq_setup +.Fa "if_ctx_t ctx" +.Fa "uint16_t qid" +.Fc +.Ft int +.Fo ifdi_rxq_setup +.Fa "if_ctx_t ctx" +.Fa "uint16_t qid" +.Fc +.Ss "Device Setup and Teardown Functions" +.Ss "Mandatory Functions" +.Ft int +.Fo ifdi_attach_pre +.Fa "if_ctx_t ctx" +.Fc +.Ft int +.Fo ifdi_attach_post +.Fa "if_ctx_t ctx" +.Fc +.Ft int +.Fo ifdi_detach +.Fa "if_ctx_t ctx" +.Fc +.Ss "Optional Functions" +.Ft void +.Fo ifdi_vlan_register +.Fa "if_ctx_t ctx" +.Fa "uint16_t vtag" +.Fc +.Ft void +.Fo ifdi_vlan_unregister +.Fa "if_ctx_t ctx" +.Fa "uint16_t vtag" +.Fc +.Ft int +.Fo ifdi_suspend +.Fa "if_ctx_t ctx" +.Fc +.Ft int +.Fo ifdi_resume +.Fa "if_ctx_t ctx" +.Fc +.Ss "Device Configuration Functions" +.Ss "Mandatory Functions" +.Ft void +.Fo ifdi_init +.Fa "if_ctx_t ctx" +.Fc +.Ft void +.Fo ifdi_stop +.Fa "if_ctx_t ctx" +.Fc +.Ft void +.Fo ifdi_multi_set +.Fa "if_ctx_t ctx" +.Fc +.Ft int +.Fo ifdi_mtu_set +.Fa "if_ctx_t ctx" +.Fa "uint32_t mtu" +.Fc +.Ft void +.Fo ifdi_media_status +.Fa "if_ctx_t ctx" +.Fa "struct ifmediareq *ifr" +.Fc +.Ft int +.Fo ifdi_media_change +.Fa "if_ctx_t ctx" +.Fc +.Ft void +.Fo ifdi_promisc_set +.Fa "if_ctx_t ctx" +.Fa "int flags" +.Fc +.Ft uint64_t +.Fo ifdi_get_counter +.Fa "if_ctx_t ctx" +.Fa "ift_counter cnt" +.Fc +.Ft void +.Fo ifdi_update_admin_status +.Fa "if_ctx_t ctx" +.Fc +.Ss "Optional Functions" +.Ft void +.Fo ifdi_media_set +.Fa "if_ctx_t ctx" +.Fc +.Ss "Interrupt enable/disable" +.Ss "Mandatory Functions" +.Ft void +.Fo ifdi_intr_enable +.Fa "if_ctx_t ctx" +.Fc +.Ft void +.Fo ifdi_queue_intr_enable +.Fa "if_ctx_t ctx" +.Fa "uint16_t qid" +.Fc +.Ft void +.Fo ifdi_intr_disable +.Fa "if_ctx_t ctx" +.Fc +.Ss IOV Support +.Ft init +.Fo iov_init +.Fa "if_ctx_t ctx" +.Fa "uint16_t num_vfs" +.Fa "const nvlist_t *params" +.Fc +.Ft void +.Fo iov_uinit +.Fa "if_ctx_t ctx" +.Fc +.Ft void +.Fo ifdi_vflr_handle +.Fa "if_ctx_t ctx" +.Fc +.Ft int +.Fo ifdi_vf_add +.Fa "if_ctx_t ctx" +.Fa "uint16_t vfnum" +.Fa "const nvlist_t *params" +.Fc +.Ss "Optional Functions" +.Ft void +.Fo ifdi_link_intr_enable +.Fa "if_ctx_t ctx" +.Fc +.Ss "Optional Service Routines" +.Ft void +.Fo ifdi_timer +.Fa "if_ctx_t ctx" +.Fc +.Ft void +.Fo ifdi_watchdog_reset +.Fa "if_ctx_t ctx" +.Fc +.Ss "Additional Functions" +.Ft void +.Fo ifdi_led_func +.Fa "if_ctx_t ctx" +.Fa "int onoff" +.Fc +.Ft int +.Fo ifdi_sysctl_int_delay +.Fa "if_ctx_t ctx" +.Fa "if_int_delay_info_t iidi" +.Fc +.Ft int +.Fo ifdi_i2c_req +.Fa "if_ctx_t ctx" +.Fa "struct ifi2creq *req" +.Fc +.Sh FUNCTIONS +The above named functions are device dependent configuration functions. +These routines are registered with iflib by the driver and are called from the +corresponding iflib function to configure device specific functions and +registers. +.Ss Device Dependent Functions +.Ss Soft Queue Setup and Teardown +.Bl -ohang -offset indent +.It Fn ifdi_tx_queues_alloc +Mandatory function that is called during iflib_attach to allocate transmit +queues. +vaddrs and paddrs are arrays of virtual and physical addresses respectively of +the hardware transmit queues. +ntxqs is the number of queues per qset. +ntxqsets is the number of qsets. +.It Fn ifdi_rx_queues_alloc +Mandatory function that is called during iflib_attach to allocate receive +queues. +vaddrs and paddrs are arrays of virtual and physical addresses respectively of +the hardware receive queues. +nrxqs is the number of queues per qset. +nrxqsets is the number of qsets. +.It Fn ifdi_queues_free +Mandatory function that frees the allocated queues and associated transmit +buffers. +.It Fn ifdi_txq_setup +Optional function for each transmit queue that handles device specific +initialization. +.It Fn ifdi_rxq_setup +Optional function for each receive queue that handles device specific +initialization. +.El +.Ss Device Setup and Teardown +.Bl -ohang -offset indent +.It Fn ifdi_attach_pre +Mandatory function implemented by the driver to perform any attach logic that +procedes interrupt and queue allocation, queue setup, and interrupt assignment. +.It Fn ifdi_attach_post +Mandatory function implemented by the driver to perform any attach logic that +occurs after ifdi_attach_pre, and iflib's queue setup and MSI/MSIX(X) or legacy +interrupt assignment. +.It Fn ifdi_detach +Mandatory function that frees any resources allocated by the driver in +ifdi_attach_pre and ifdi_attach_post. +.It Fn ifdi_vlan_register +Optional function called by the VLAN config eventhandler. +.Va vtag +is the new VLAN tag. +.It Fn ifdi_vlan_unregister +Optional function called by the VLAN unconfig eventhandler. +.It Fn ifdi_suspend +Optional function that suspends the driver. +.It Fn ifdi_resume +Optional function that resumes a driver. +.El +.Ss Device Configuration Functions +.Bl -ohang -offset indent +.It Fn ifdi_init +Mandatory function that will initialize and bring up the hardware. +For example, it will reset the chip and enable the receiver unit. +It should mark the interface running, but not active ( +.Dv IFF_DRV_RUNNING , +.Dv ~IIF_DRV_OACTIVE ). +.It Fn ifdi_stop +Mandatory function that should disable all traffic on the interface by issuing +a global reset on the MAC and deallocating the TX and RX buffers. +.It Fn ifdi_multi_set +Programs the interfaces multicast addresses +.It Fn ifdi_media_status +Media Ioctl Callback. +Function is called whenever the user queries the status of the interface using +.Xr ifconfig 8 . +The driver sets the appropriate link type and speed in ifmr->ifm_active. +.It Fn ifdi_mtu_set +Sets the mtu interface to the value of the second function parameter mtu. +.It Fn ifdi_media_change +Function is called when the user changes speed/duplex using the media/mediaopt +option with +.Xr ifconfig 8 . +.It Fn ifdi_promisc_set +Enables or disables promisc settings depending upon the flags value. +.Va flags +contains the interface's +.Xr ifnet 9 +flags. +.It Fn ifdi_get_counter +Returns the value for counter cnt depending upon counter type. +.It Fn ifdi_update_admin_status +Sets the link_up state to TRUE or FALSE depending upon the OS link state. +A real check of the hardware only happens with a link interrupt. +.It Fn ifdi_media_set +Need to define +.El +.Ss Interrupt Enable/Disable +.Bl -ohang -offset indent +.It Fn ifdi_intr_enable +Mandatory function that enables all interrupts. +.It Fn ifdi_intr_disable +Mandatory function that disables all interrupts. +.It Fn ifdi_queue_intr_enable +Mandatory function that enables interrupts on queue qid. +.It Fn iov_init +Initialize num_vfs VFs. +.It Fn io_uninit +Tear down the context for all VFs. +.It Fn ifdi_vflr_handle +Handle any VFs that have reset themselves via a Function Level Reset (FLR). +.It Fn ifdi_vf_add +Set parameters in params in VF vfnum. +.El +.Ss Service Routines +.Bl -ohang -offset indent +.It Fn ifdi_timer +Optional timer routine that will be run every 500ms. +.It Fn ifdi_watchdog_reset +Optional function to run when a transmit queue is hung. +.El +.Ss Additional Functions +.Bl -ohang -offset indent +.It Fn ifdi_led_func +.It Fn ifdi_sysctl_int_delay +.It Fn ifdi_i2c_req +.El +.Sh SEE ALSO +.Xr ifconfig 8 , +.Xr iflibdi 9 , +.Xr iflibtxrx 9 , +.Xr ifnet 9 +.Sh AUTHORS +This manual page was written by +.An Nicole Graziano diff --git a/static/freebsd/man9/iflibdi.9 b/static/freebsd/man9/iflibdi.9 new file mode 100644 index 00000000..57fa02c6 --- /dev/null +++ b/static/freebsd/man9/iflibdi.9 @@ -0,0 +1,236 @@ +.Dd May 21, 2019 +.Dt IFLIBDI 9 +.Os +.Sh NAME +.Nm iflibdi +.Nd Device Independent Configuration Functions +.Sh SYNOPSIS +.In "ifdi_if.h" +.Ss "Device Independent Functions" +.Ft int +.Fo iflib_device_attach +.Fa "device_t dev" +.Fc +.Ft int +.Fo iflib_device_detach +.Fa "device_t dev" +.Fc +.Ft int +.Fo iflib_device_suspend +.Fa "device_t dev" +.Fc +.Ft int +.Fo iflib_device_resume +.Fa "device_t dev" +.Fc +.Ft int +.Fo iflib_device_register +.Fa "device_t dev" +.Fa "void *softc" +.Fa "if_shared_ctx_t sctx" +.Fa "if_ctx_t *ctxp" +.Fc +.Ft int +.Fo iflib_device_deregister +.Fa "if_ctx_t ctx" +.Fc +.Ft int +.Fo iflib_irq_alloc +.Fa "if_ctx_t ctx" +.Fa "if_irq_t irq_info" +.Fa "int rid" +.Fa "driver_filter_t filter" +.Fa "void *filter_arg" +.Fa "driver_intr_t handler" +.Fa "void *arg" +.Fa "char *name" +.Fc +.Ft int +.Fo iflib_irq_alloc_generic +.Fa "if_ctx_t ctx" +.Fa "if_irq_t irq" +.Fa "int rid" +.Fa "intr_type_t type" +.Fa "driver_filter_t *filter" +.Fa "void *filter_arg" +.Fa "int qid" +.Fa "char *name" +.Fc +.Ft void +.Fo iflib_led_create +.Fa "if_ctx_t ctx" +.Fc +.Ft void +.Fo iflib_tx_intr_deferred +.Fa "if_ctx_t ctx" +.Fa "int txqid" +.Fc +.Ft void +.Fo iflib_rx_intr_deferred +.Fa "if_ctx_t ctx" +.Fa "int rxqid" +.Fc +.Ft void +.Fo iflib_link_intr_deferred +.Fa "if_ctx_t ctx" +.Fc +.Ft void +.Fo iflib_link_state_change +.Fa "if_ctx_t ctx" +.Fa "int linkstate" +.Fc +.Ft void +.Fo iflib_add_int_delay_sysctl +.Fa "if_ctx_t ctx" +.Fa "const char *" +.Fa "const char *" +.Fa "if_int_delay_info_t" +.Fa "int" +.Fa "int" +.Fc +.Ss "Global Variables" +.Vt extern struct if_txrx +.Sh DATA STRUCTURES +The \fIif_ctx_t\fP Structure is the device independent data structure that +contains statistics and identifying information used to transmit and receive +data packets. +The interface is associated with an array of queues assigned sequentially. +Each queue has its own transmit (iflib_txq_t) and receive (iflib_rxq_t) queue. +The transmit queue is used to hold packets while the interface is in the +process of sending another. +The receive queue is used to receive packets that are awaiting processing. +.Ss The if_ctx_t Structure +The fields of +.Vt "struct if_ctx_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. +.It Va ifc_dev +.Pq Vt "device_t" +The underlying device structure. +.It Va ifc_ip +.Pq Vt "if_t" +A link back to the interface structure +.It Va ifc_cpus +.Pq Vt "cpuset_t" +.It Va ifc_mutex +.Pq Vt "struct mtx" +Mutex lock used to maintain data integrity +.It Va ifc_mtx_name +.Pq Vt "char *" +The name of the mutex +.It Va ifc_txqs +.Pq Vt "iflib_txq_t" +Device independent transmit queue maintained internally by iflib +.It Va ifc_rxqs +.Pq Vt "iflib_rxq_t" +Device independent receive queue maintained internally by iflib +.It Va ifc_qsets +.Pq Vt "iflib_qset_t" +Output queue that contains a single transmit (ifc_txq_t) and receive +(ifc_rxq_t) queue +.It Va ifc_if_flags +.Pq Vt "uint32_t" +Flags describing the operational parameter of the interface +.It Va ifc_in_detach +.Pq Vt "int" +.It Va ifc_link_state +.Pq Vt "int" +Describes the current link state of the Ethernet interface. +Its possible values are either active or inactive. +.It Va ifc_link_irq +.Pq Vt "int" +.It Va ifc_vlan_attach_event +.Pq Vt "eventhandler_tag" +.It Va ifc_vlan_detach_event +.Pq Vt "eventhandler_tag" +.It Va ifc_pause_frames +.Pq Vt "int" +.It Va ifc_watchdog_events +.Pq Vt "int" +.It Va ifc_mac +.Pq Vt "uint8_t" +.It Va ifc_msix_mem +.Pq Vt "struct resource *" +.It Va ifc_legacy_irq +.Pq Vt "struct if_irq" +.It Va ifc_admin_task +.Pq Vt "struct grouptask" +Taskqueue task scheduled for link state change events of the interface +.It Va ifc_filter_info +.Pq Vt "struct iflib_filter_info" +Statistics and information relating to the interface device filter +.It Va ifc_media +.Pq Vt "struct ifmedia" +.It Va ifc_txrx +.Pq Vt "struct if_txrx" +.El +.Sh FUNCTIONS +The above named functions are found exclusively in iflib. +They are independent of the underlying hardware type or configuration. +.Ss Device Independent Functions +.Bl -ohang -offset indent +.It Fn iflib_device_attach +Function initiates a device registration with the iflib framework. +It calls the iflib_register function, which is responsible for allocating +and initializing the \fIif_ctx_t\fP structure. +.It Fn iflib_device_detach +Shutdown and detach the device. +Unregister vlan events, drain any dependent tasks, and release irq, pci, and +msix memory. +.It Fn iflib_device_suspend +Suspend a device by calling the device dependent suspend function and +bus_generic_suspend. +.It Fn iflib_device_resume +Resume a device by calling the device dependent resume function, the +iflib_init_locked function, and bus_generic_resume. +.It Fn iflib_device_register +Register a device with the iflib framework. +Allocate and initialize the +\fIif_ctx_t\fP structure. +Setup and initialize the MSI or MSI/X interrupt queues if necessary. +Allocate memory for queues and qset structure setup. +.It Fn iflib_irq_alloc +Allocate an interrupt resource for a given rid value with an associated filter +and handler function. +.It Fn iflib_irq_alloc_generic +Performs the same function as iflib_device_irq_alloc along with the additional +functionality of adding a taskgroup. +The data fields and callback function are determined by the type of interrupt, +such as +.Dv IFLIB_INTR_TX , +.Dv IFLIB_INTR_RX , +and +.Dv IFLIB_INTR_ADMIN . +.It Fn iflib_led_create +Calls led_create to initialize the ctx->ifc_led_dev field +.It Fn iflib_tx_intr_deferred +Calls GROUPTASK_ENQUEUE to enqueue the transfer queues ift_task. +.It Fn iflib_rx_intr_deferred +Calls GROUPTASK_ENQUEUE to enqueue the receive queues ifr_task. +.It Fn iflib_link_intr_deferred +Calls GROUPTASK_ENQUEUE to enqueue the link task +.It Fn iflib_link_state_change +Change the interface link status to either +.Dv LINK_STATE_UP +or +.Dv LINK_STATE_DOWN +as specified by the second argument to the function. +.Pp +.Em Interface Link States +The following link states are currently defined: +.It Dv LINK_STATE_UP +The link is up. +.It Dv LINK_STATE_DOWN +The link is down. +.It Fn iflib_add_int_delay_sysctl +Modifies settings to user defined values for a given set of variables. +.El +.Sh SEE ALSO +.Xr iflibdd 9 , +.Xr iflibtxrx 9 +.Sh AUTHORS +This manual page was written by +.An Nicole Graziano diff --git a/static/freebsd/man9/iflibtxrx.9 b/static/freebsd/man9/iflibtxrx.9 new file mode 100644 index 00000000..df017dea --- /dev/null +++ b/static/freebsd/man9/iflibtxrx.9 @@ -0,0 +1,239 @@ +.Dd December 17, 2020 +.Dt IFLIBTXTX 9 +.Os +.Sh NAME +.Nm iflibtxrx +.Nd Device Dependent Transmit and Receive Functions +.Sh SYNOPSIS +.In "ifdi_if.h" +.Ss "Interface Manipulation Functions" +.Ft int +.Fo isc_txd_encap +.Fa "void *sc" +.Fa "if_pkt_info_t pi" +.Fc +.Ft void +.Fo isc_txd_flush +.Fa "void *sc" +.Fa "uint16_t qid" +.Fa "uint32_t _pidx_or_credits_" +.Fc +.Ft int +.Fo isc_txd_credits_update +.Fa "void *sc" +.Fa "uint16_t qid" +.Fa "bool clear" +.Fc +.Ft int +.Fo isc_rxd_available +.Fa "void *sc" +.Fa "uint16_t qsid" +.Fa "uint32_t cidx" +.Fc +.Ft void +.Fo isc_rxd_refill +.Fa "void *sc" +.Fa "uint16_t qsid" +.Fa "uint8_t flid" +.Fa "uint32_t pidx" +.Fa "uint64_t *paddrs" +.Fa "caddr_t *vaddrs" +.Fa "uint16_t count" +.Fc +.Ft void +.Fo isc_rxd_flush +.Fa "void *sc" +.Fa "uint16_t qsid" +.Fa "uint8_t flid" +.Fa "uint32_t pidx" +.Fc +.Ft int +.Fo isc_rxd_pkt_get +.Fa "void *sc" +.Fa "if_rxd_info_t ri" +.Fc +.Ss "Global Variables" +.Vt extern struct if_txrx +.Sh DATA STRUCTURES +The device dependent mechanisms for handling packet transmit and receive are +primarily defined by the functions named above. +The if_pkt_info data structure contains statistics and identifying info +necessary for packet transmission. +While the data structure for packet receipt is the if_rxd_info structure. +.Ss The if_pkt_info Structure +The fields of +.Vt "struct if_pkt_info" +are as follows: +.Bl -tag -width ".Va if_capabilities" -offset indent +.It Va ipi_len +.Pq Vt "uint32_t" +Denotes the size of packet to be sent on the transmit queue. +.It Va ipi_segs +.Pq Vt "bus_dma_segment_t *" +A pointer to the bus_dma_segment of the device independent transfer queue +defined in iflib. +.It Va ipi_qsidx +Unique index value assigned sequentially to each transmit queue. +Used to reference the currently transmitting queue. +.It Va ipi_nsegs +.Pq Vt "uint16_t" +Number of descriptors to be read into the device dependent transfer +descriptors. +.It Va ipi_ndescs +.Pq Vt "uint16_t" +Number of descriptors in use. +Calculated by subtracting the old pidx value from the new pidx value. +.It Va ipi_flags +.Pq Vt "uint16_t" +Flags defined on a per packet basis. +.It Va ipi_pidx +.Pq Vt "uint32_t" +Value of first pidx sent to the isc_encap function for encapsulation and +subsequent transmission. +.It Va ipi_new_pidx +.Pq Vt "uint32_t" +Value set after the termination of the isc_encap function. +This value will become the first pidx sent to the isc-encap the next time that +the function is called. +.It Va \fBThe Following Fields Are Used For Offload Handling\fP +.It Va ipi_csum_flags +.Pq Vt "uint64_t" +Flags describing the checksum values, used on a per packet basis. +.It Va ipi_tso_segsz +.Pq Vt "uint16_t" +Size of the TSO Segment Size. +.It Va ipi_mflags +.Pq Vt "uint16_t" +Flags describing the operational parameters of the mbuf. +.It Va ipi_vtag +.Pq Vt "uint16_t" +Contains the VLAN information in the Ethernet Frame. +.It Va ipi_etype +.Pq Vt "uint16_t" +Type of ethernet header protocol as contained by the struct ether_vlan_header. +.It Va ipi_ehrdlen +.Pq Vt "uint8_t" +Length of the Ethernet Header. +.It Va ipi_ip_hlen +.Pq Vt "uint8_t" +Length of the TCP Header +.It Va ipi_tcp_hlen +.Pq Vt "uint8_t" +Length of the TCP Header. +.It Va ipi_tcp_hflags +.Pq Vt "uint8_t" +Flags describing the operational parameters of the TCP Header. +.It Va ipi_ipproto +.Pq Vt "uint8_t" +Specifies the type of IP Protocol in use. +Example TCP, UDP, or SCTP. +.El +.Ss The if_rxd_info Structure +The fields of +.Vt "struct if_rxd_info" +are as follows: +.Bl -tag -width ".Va if_capabilities" -offset indent +.It Va iri_qsidx +.Pq Vt "uint16_t" +Unique index value assigned sequentially to each receive queue. +Used to reference the currently receiving queue. +.It Va iri_vtag +.Pq Vt "uint16_t" +Contains the VLAN information in the Ethernet Frame. +.It Va iri_len +.Pq Vt "uint16_t" +Denotes the size of a received packet. +.It Va iri_next_offset +.Pq Vt "uint16_t" +Denotes the offset value for the next packet to be receive. +A Null value signifies the end of packet. +.It Va iri_cidx +.Pq Vt "uint32_t" +Denotes the index value of the packet currently being processed in the +consumer queue. +.It Va iri_flowid +.Pq Vt "uint32_t" +Value of the RSS hash for the packet. +.It Va iri_flags +.Pq Vt "uint" + Flags describing the operational parameters of the mbuf contained in the + receive packet. +.It Va iri_csum_flags +.Pq Vt "uint32_t" +Flags describing the checksum value contained in the receive packet. +.It Va iri_csum_data +.Pq Vt "uint32_t" +Checksum data contained in the +.Xr mbuf 9 +packet header. +.It Va iri_m +.Pq Vt "struct mbuf *" +A mbuf for drivers that manage their own receive queues. +.It Va iri_ifp +.Pq Vt "struct ifnet *" +A link back to the interface structure. +Utilized by drivers that have multiple interface per softc. +.It Va iri_rsstype +.Pq Vt "uint8_t" +The value of the RSS hash type. +.It Va iri_pad +.Pq Vt "uint8_t" +The length of any padding contained by the received data. +.It Va iri_qidx +.Pq Vt "uint8_t" +Represents the type of queue event. +If value >= 0 then it is the freelist id otherwise it is a completion queue +event. +.El +.Sh FUNCTIONS +All function calls are associated exclusively with either packet transmission +or receipt. +The void *sc passed as the first argument to all of the following functions +represents the driver's softc. +.Ss Transmit Packet Functions +.Bl -ohang -offset indent +.It Fn isc_txd_encap +Transmit function that sends a packet on an interface. +The if_pkt_info data structure contains data information fields describing the +packet. +This function returns 0 if successful, otherwise an error value is returned. +.It Fn isc_txd_flush +Flush function is called immediately after the isc_txd_encap function transmits +a packet. +It updates the hardware producer index or increments the descriptors used to +pidx_or_credits in the queue designated by the qid number. +This is often referred to as poking the doorbell register. +.It Fn isc_txd_credits_update +Credit function advances the buffer ring and calculates the credits +(descriptors) processed. +Until the I/O is complete it cleans the range in case of multisegments and +updates the count of processed packets. +The function returns the number of processed credits. +.El +.Ss Receive Packet Functions +.Bl -ohang -offset indent +.It Fn isc_rxd_available +Function calculates the remaining number of descriptors from a position given +by idx. +The function returns this value. +.It Fn isc_rxd_refill +Starting with the physical address paddrs, the function reads a packet into the +rx_ring until a value designated by count is reached. +vaddrs is typically not needed and is provided for devices that place their own +metadata in the packet header. +.It Fn isc_rxd_flush +Flush function updates the producer pointer on the free list flid in queue set +number qid to pidx to reflect the presence of new buffers. +.It Fn isc_rxd_pkt_get +Process a single software descriptor. +rxr->rx_base[i] contains a descriptor that describes a received packet. +Hardware specific information about the buffer referred to by ri is returned in +the data structure if_rxd_info +.El +.Sh SEE ALSO +.Xr iflibdd 9 , +.Xr iflibdi 9 , +.Xr mbuf 9 +.Sh AUTHORS +This manual page was written by +.An Nicole Graziano diff --git a/static/freebsd/man9/ifnet.9 b/static/freebsd/man9/ifnet.9 new file mode 100644 index 00000000..e0a4dae9 --- /dev/null +++ b/static/freebsd/man9/ifnet.9 @@ -0,0 +1,1692 @@ +.\" -*- Nroff -*- +.\" Copyright 1996, 1997 Massachusetts Institute of Technology +.\" +.\" Permission to use, copy, modify, and distribute this software and +.\" its documentation for any purpose and without fee is hereby +.\" granted, provided that both the above copyright notice and this +.\" permission notice appear in all copies, that both the above +.\" copyright notice and this permission notice appear in all +.\" supporting documentation, and that the name of M.I.T. not be used +.\" in advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. M.I.T. makes +.\" no representations about the suitability of this software for any +.\" purpose. It is provided "as is" without express or implied +.\" warranty. +.\" +.\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS +.\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE, +.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT +.\" SHALL M.I.T. 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 10, 2024 +.Dt IFNET 9 +.Os +.Sh NAME +.Nm if_t , +.Nm ifnet , +.Nm ifaddr , +.Nm ifqueue , +.Nm if_data +.Nd kernel interfaces for manipulating network interfaces +.Sh SYNOPSIS +.In sys/param.h +.In sys/time.h +.In sys/socket.h +.In net/if.h +.In net/if_var.h +.In net/if_types.h +.\" +.Ss "Interface Manipulation Functions" +.Ft "if_t" +.Fn if_alloc "u_char type" +.Ft "if_t" +.Fn if_alloc_dev "u_char type" "device_t dev" +.Ft "if_t" +.Fn if_alloc_domain "u_char type" "int numa_domain" +.Ft void +.Fn if_attach "if_t ifp" +.Ft void +.Fn if_detach "if_t ifp" +.Ft void +.Fn if_free "if_t ifp" +.Ft void +.Fn if_free_type "if_t ifp" "u_char type" +.Ft void +.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 "if_t ifp" "int pswitch" +.Ft int +.Fn if_allmulti "if_t ifp" "int amswitch" +.Ft "if_t" +.Fn ifunit "const char *name" +.Ft "if_t" +.Fn ifunit_ref "const char *name" +.Ft void +.Fn if_up "if_t ifp" +.\" +.Ss "Interface Address Functions" +.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" "if_t ifp" +.Ft void +.Fn ifa_ref "struct ifaddr *ifa" +.Ft void +.Fn ifa_free "struct ifaddr *ifa" +.\" +.Ss "Interface Multicast Address Functions" +.Ft int +.Fn if_addmulti "if_t ifp" "struct sockaddr *sa" "struct ifmultiaddr **ifmap" +.Ft int +.Fn if_delmulti "if_t ifp" "struct sockaddr *sa" +.Ft "struct ifmultiaddr *" +.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 "if_t ifp" "struct mbuf *m" +.Ft int +.Fo \*(lp*if_output\*(rp +.Fa "if_t ifp" "struct mbuf *m" +.Fa "const struct sockaddr *dst" "struct route *ro" +.Fc +.Ft void +.Fn \*(lp*if_start\*(rp "if_t ifp" +.Ft int +.Fn \*(lp*if_transmit\*(rp "if_t ifp" "struct mbuf *m" +.Ft void +.Fn \*(lp*if_qflush\*(rp "if_t ifp" +.Ft int +.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 "if_t ifp" "struct sockaddr **retsa" "struct sockaddr *addr" +.Fc +.Ss "struct ifaddr member function" +.Ft void +.Fo \*(lp*ifa_rtrequest\*(rp +.Fa "int cmd" "struct rtentry *rt" "struct rt_addrinfo *info" +.Fc +.\" +.Ss "Global Variables" +.Vt extern struct ifnethead ifnet ; +.\" extern struct ifindex_entry *ifindex_table ; +.Vt extern int if_index ; +.Vt extern int ifqmaxlen ; +.Sh DATA STRUCTURES +The kernel mechanisms for handling network interfaces reside primarily +in the +.Vt ifnet , if_data , ifaddr , +and +.Vt ifmultiaddr +structures in +.In net/if.h +and +.In net/if_var.h +and the functions named above and defined in +.Pa /sys/net/if.c . +Those interfaces which are intended to be used by user programs +are defined in +.In net/if.h ; +these include the interface flags, the +.Vt if_data +structure, and the structures defining the appearance of +interface-related messages on the +.Xr route 4 +routing socket and in +.Xr sysctl 3 . +The header file +.In net/if_var.h +defines the kernel-internal interfaces, including the +.Vt ifnet , ifaddr , +and +.Vt ifmultiaddr +structures and the functions which manipulate them. +(A few user programs will need +.In net/if_var.h +because it is the prerequisite of some other header file like +.In netinet/if_ether.h . +Most references to those two files in particular can be replaced by +.In net/ethernet.h . ) +.Pp +The system keeps a linked list of interfaces using the +.Li TAILQ +macros defined in +.Xr queue 3 ; +this list is headed by a +.Vt "struct ifnethead" +called +.Va ifnet . +The elements of this list are of type +.Vt "struct ifnet" , +and most kernel routines which manipulate interface as such accept or +return pointers to these structures. +Each interface structure +contains an +.Vt if_data +structure used for statistics and information. +Each interface also has a +.Li TAILQ +of interface addresses, described by +.Vt ifaddr +structures. +An +.Dv AF_LINK +address +(see +.Xr link_addr 3 ) +describing the link layer implemented by the interface (if any) +is accessed by the +.Va if_addr +structure. +(Some trivial interfaces do not provide any link layer addresses; +this structure, while still present, serves only to identify the +interface name and index.) +.Pp +Finally, those interfaces supporting reception of multicast datagrams +have a +.Li TAILQ +of multicast group memberships, described by +.Vt ifmultiaddr +structures. +These memberships are reference-counted. +.Pp +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 accessors +The accessors for +.Vt "if_t" +are as follows: +.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 Fn if_getindex +.Pq Vt u_short +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 ) . +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 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 address. +.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 +aware, the system is a NUMA system, and the ifnet is allocated +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 +.Vt ifnet +structures are gained by calling the +.Fn if_ref +function and released by calling the +.Fn if_rele +function. +They are used to allow kernel code walking global interface lists +to release the +.Vt ifnet +lock yet keep the +.Vt ifnet +structure stable. +.Pp +There are in addition a number of function pointers which the driver +must initialize to complete its interface with the generic interface +layer: +.Bl -ohang -offset indent +.It Fn if_input +Pass a packet to an appropriate upper layer as determined +from the link-layer header of the packet. +This routine is to be called from an interrupt handler or +used to emulate reception of a packet on this interface. +A single function implementing +.Fn if_input +can be shared among multiple drivers utilizing the same link-layer +framing, e.g., Ethernet. +.It Fn if_output +Output a packet on interface +.Fa ifp , +or queue it on the output queue if the interface is already active. +.It Fn if_transmit +Transmit a packet on an interface or queue it if the interface is +in use. +This function will return +.Dv ENOBUFS +if the devices software and hardware queues are both full. +This function must be installed after +.Fn if_attach +to override the default implementation. +This function is exposed in order to allow drivers to manage their own queues +and to reduce the latency caused by a frequently gratuitous enqueue / dequeue +pair to ifq. +The suggested internal software queuing mechanism is buf_ring. +.It Fn if_qflush +Free mbufs in internally managed queues when the interface is marked down. +This function must be installed after +.Fn if_attach +to override the default implementation. +This function is exposed in order to allow drivers to manage their own queues +and to reduce the latency caused by a frequently gratuitous enqueue / dequeue +pair to ifq. +The suggested internal software queuing mechanism is buf_ring. +.It Fn if_start +Start queued output on an interface. +This function is exposed in +order to provide for some interface classes to share a +.Fn if_output +among all drivers. +.Fn if_start +may only be called when the +.Dv IFF_DRV_OACTIVE +flag is not set. +(Thus, +.Dv IFF_DRV_OACTIVE +does not literally mean that output is active, but rather that the +device's internal output queue is full.) Please note that this function +will soon be deprecated. +.It Fn if_ioctl +Process interface-related +.Xr ioctl 2 +requests +(defined in +.In sys/sockio.h ) . +Preliminary processing is done by the generic routine +.Fn ifioctl +to check for appropriate privileges, locate the interface being +manipulated, and perform certain generic operations like twiddling +flags and flushing queues. +See the description of +.Fn ifioctl +below for more information. +.It Fn if_init +Initialize and bring up the hardware, +e.g., reset the chip and enable the receiver unit. +Should mark the interface running, +but not active +.Dv ( IFF_DRV_RUNNING , ~IIF_DRV_OACTIVE ) . +.It Fn if_resolvemulti +Check the requested multicast group membership, +.Fa addr , +for validity, and if necessary compute a link-layer group which +corresponds to that address which is returned in +.Fa *retsa . +Returns zero on success, or an error code on failure. +.El +.Ss "Interface Flags" +Interface flags are used for a number of different purposes. +Some +flags simply indicate information about the type of interface and its +capabilities; others are dynamically manipulated to reflect the +current state of the interface. +Flags of the former kind are marked +.Aq S +in this table; the latter are marked +.Aq D . +Flags which begin with +.Dq IFF_DRV_ +are stored in +.Va if_drv_flags ; +all other flags are stored in +.Va if_flags . +.Pp +The macro +.Dv IFF_CANTCHANGE +defines the bits which cannot be set by a user program using the +.Dv SIOCSIFFLAGS +command to +.Xr ioctl 2 ; +these are indicated by an asterisk +.Pq Ql * +in the following listing. +.Pp +.Bl -tag -width ".Dv IFF_POINTOPOINT" -offset indent -compact +.It Dv IFF_UP +.Aq D +The interface has been configured up by the user-level code. +.It Dv IFF_BROADCAST +.Aq S* +The interface supports broadcast. +.It Dv IFF_DEBUG +.Aq D +Used to enable/disable driver debugging code. +.It Dv IFF_LOOPBACK +.Aq S +The interface is a loopback device. +.It Dv IFF_POINTOPOINT +.Aq S* +The interface is point-to-point; +.Dq broadcast +address is actually the address of the other end. +.It Dv IFF_DRV_RUNNING +.Aq D* +The interface has been configured and dynamic resources were +successfully allocated. +Probably only useful internal to the +interface. +.It Dv IFF_NOARP +.Aq D +Disable network address resolution on this interface. +.It Dv IFF_PROMISC +.Aq D* +This interface is in promiscuous mode. +.It Dv IFF_PPROMISC +.Aq D +This interface is in the permanently promiscuous mode (implies +.Dv IFF_PROMISC ) . +.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 +are to be queued. +.It Dv IFF_SIMPLEX +.Aq S* +The interface cannot hear its own transmissions. +.It Dv IFF_LINK0 +.It Dv IFF_LINK1 +.It Dv IFF_LINK2 +.Aq D +Control flags for the link layer. +(Currently abused to select among +multiple physical layers on some devices.) +.It Dv IFF_MULTICAST +.Aq S* +This interface supports multicast. +.It Dv IFF_CANTCONFIG +.Aq S* +The interface is not configurable in a meaningful way. +Primarily useful for +.Dv IFT_USB +interfaces registered at the interface list. +.It Dv IFF_MONITOR +.Aq D +This interface blocks transmission of packets and discards incoming +packets after BPF processing. +Used to monitor network traffic but not interact +with the network in question. +.It Dv IFF_STATICARP +.Aq D +Used to enable/disable ARP requests on this interface. +.It Dv IFF_DYING +.Aq D* +Set when the +.Vt ifnet +structure of this interface is being released and still has +.Va if_refcount +references. +.El +.Ss "Interface Capabilities Flags" +Interface capabilities are specialized features an interface may +or may not support. +These capabilities are very hardware-specific +and allow, when enabled, +to offload specific network processing to the interface +or to offer a particular feature for use by other kernel parts. +.Pp +It should be stressed that a capability can be completely +uncontrolled (i.e., stay always enabled with no way to disable it) +or allow limited control over itself (e.g., depend on another +capability's state.) +Such peculiarities are determined solely by the hardware and driver +of a particular interface. +Only the driver possesses +the knowledge on whether and how the interface capabilities +can be controlled. +Consequently, capabilities flags in +.Va if_capenable +should never be modified directly by kernel code other than +the interface driver. +The command +.Dv SIOCSIFCAP +to +.Fn ifioctl +is the dedicated means to attempt altering +.Va if_capenable +on an interface. +Userland code shall use +.Xr ioctl 2 . +.Pp +The following capabilities are currently supported by the system: +.Bl -tag -width ".Dv IFCAP_VLAN_HWTAGGING" -offset indent +.It Dv IFCAP_RXCSUM +This interface can do checksum validation on receiving data. +Some interfaces do not have sufficient buffer storage to store frames +above a certain MTU-size completely. +The driver for the interface might disable hardware checksum validation +if the MTU is set above the hardcoded limit. +.It Dv IFCAP_TXCSUM +This interface can do checksum calculation on transmitting data. +.It Dv IFCAP_HWCSUM +A shorthand for +.Pq Dv IFCAP_RXCSUM | IFCAP_TXCSUM . +.It Dv IFCAP_NETCONS +This interface can be a network console. +.It Dv IFCAP_VLAN_MTU +The +.Xr vlan 4 +driver can operate over this interface in software tagging mode +without having to decrease MTU on +.Xr vlan 4 +interfaces below 1500 bytes. +This implies the ability of this interface to cope with frames somewhat +longer than permitted by the Ethernet specification. +.It Dv IFCAP_VLAN_HWTAGGING +This interface can do VLAN tagging on output and +demultiplex frames by their VLAN tag on input. +.It Dv IFCAP_JUMBO_MTU +This Ethernet interface can transmit and receive frames up to +9000 bytes long. +.It Dv IFCAP_POLLING +This interface supports +.Xr polling 4 . +See below for details. +.It Dv IFCAP_VLAN_HWCSUM +This interface can do checksum calculation on both transmitting +and receiving data on +.Xr vlan 4 +interfaces (implies +.Dv IFCAP_HWCSUM ) . +.It Dv IFCAP_TSO4 +This Ethernet interface supports TCP4 Segmentation offloading. +.It Dv IFCAP_TSO6 +This Ethernet interface supports TCP6 Segmentation offloading. +.It Dv IFCAP_TSO +A shorthand for +.Pq Dv IFCAP_TSO4 | IFCAP_TSO6 . +.It Dv IFCAP_TOE4 +This Ethernet interface supports TCP4 Offload Engine. +.It Dv IFCAP_TOE6 +This Ethernet interface supports TCP6 Offload Engine. +.It Dv IFCAP_TOE +A shorthand for +.Pq Dv IFCAP_TOE4 | IFCAP_TOE6 . +.It Dv IFCAP_WOL_UCAST +This Ethernet interface supports waking up on any Unicast packet. +.It Dv IFCAP_WOL_MCAST +This Ethernet interface supports waking up on any Multicast packet. +.It Dv IFCAP_WOL_MAGIC +This Ethernet interface supports waking up on any Magic packet such +as those sent by +.Xr wake 8 . +.It Dv IFCAP_WOL +A shorthand for +.Pq Dv IFCAP_WOL_UCAST | IFCAP_WOL_MCAST | IFCAP_WOL_MAGIC . +.It Dv IFCAP_VLAN_HWFILTER +This interface supports frame filtering in hardware on +.Xr vlan 4 +interfaces. +.It Dv IFCAP_VLAN_HWTSO +This interface supports TCP Segmentation offloading on +.Xr vlan 4 +interfaces (implies +.Dv IFCAP_TSO ) . +.It Dv IFCAP_LINKSTATE +This Ethernet interface supports dynamic link state changes. +.It Dv IFCAP_NETMAP +This Ethernet interface supports +.Xr netmap 4 . +.El +.Pp +The ability of advanced network interfaces to offload certain +computational tasks from the host CPU to the board is limited +mostly to TCP/IP. +Therefore a separate field associated with an interface +(see +.Va ifnet.if_data.ifi_hwassist +below) +keeps a detailed description of its enabled capabilities +specific to TCP/IP processing. +The TCP/IP module consults the field to see which tasks +can be done on an +.Em outgoing +packet by the interface. +The flags defined for that field are a superset of those for +.Va mbuf.m_pkthdr.csum_flags , +namely: +.Bl -tag -width ".Dv CSUM_FRAGMENT" -offset indent +.It Dv CSUM_IP +The interface will compute IP checksums. +.It Dv CSUM_TCP +The interface will compute TCP checksums. +.It Dv CSUM_UDP +The interface will compute UDP checksums. +.El +.Pp +An interface notifies the TCP/IP module about the tasks +the former has performed on an +.Em incoming +packet by setting the corresponding flags in the field +.Va mbuf.m_pkthdr.csum_flags +of the +.Vt mbuf chain +containing the packet. +See +.Xr mbuf 9 +for details. +.Pp +The capability of a network interface to operate in +.Xr polling 4 +mode involves several flags in different +global variables and per-interface fields. +The capability flag +.Dv IFCAP_POLLING +set in interface's +.Va if_capabilities +indicates support for +.Xr polling 4 +on the particular interface. +If set in +.Va if_capabilities , +the same flag can be marked or cleared in the interface's +.Va if_capenable +within +.Fn ifioctl , +thus initiating switch of the interface to +.Xr polling 4 +mode or interrupt +mode, respectively. +The actual mode change is managed by the driver-specific +.Fn if_ioctl +routine. +The +.Xr polling 4 +handler returns the number of packets processed. +.Ss The if_data Structure +The +.Vt if_data +structure contains statistics and identifying information used +by management programs, and which is exported to user programs by way +of the +.Xr ifmib 4 +branch of the +.Xr sysctl 3 +MIB. +The following elements of the +.Vt if_data +structure are initialized by the interface and are not expected to change +significantly over the course of normal operation: +.Bl -tag -width ".Va ifi_lastchange" -offset indent +.It Va ifi_type +.Pq Vt u_char +The type of the interface, as defined in +.In net/if_types.h +and described below in the +.Sx "Interface Types" +section. +.It Va ifi_physical +.Pq Vt u_char +Intended to represent a selection of physical layers on devices which +support more than one; never implemented. +.It Va ifi_addrlen +.Pq Vt u_char +Length of a link-layer address on this device, or zero if there are +none. +Used to initialized the address length field in +.Vt sockaddr_dl +structures referring to this interface. +.It Va ifi_hdrlen +.Pq Vt u_char +Maximum length of any link-layer header which might be prepended by +the driver to a packet before transmission. +The generic code computes +the maximum over all interfaces and uses that value to influence the +placement of data in +.Vt mbuf Ns s +to attempt to ensure that there is always +sufficient space to prepend a link-layer header without allocating an +additional +.Vt mbuf . +.It Va ifi_datalen +.Pq Vt u_char +Length of the +.Vt if_data +structure. +Allows some stabilization of the routing socket ABI in the face of +increases in the length of +.Vt struct ifdata . +.It Va ifi_mtu +.Pq Vt u_long +The maximum transmission unit of the medium, exclusive of any +link-layer overhead. +.It Va ifi_metric +.Pq Vt u_long +A dimensionless metric interpreted by a user-mode routing process. +.It Va ifi_epoch +.Pq Vt time_t +The system uptime when interface was attached or the statistics +below were reset. +This is intended to be used to set the SNMP variable +.Va ifCounterDiscontinuityTime . +It may also be used to determine if two successive queries for an +interface of the same index have returned results for the same +interface. +.El +.Pp +The structure additionally contains generic statistics applicable to a +variety of different interface types (except as noted, all members are +of type +.Vt u_long ) : +.Bl -tag -width ".Va ifi_lastchange" -offset indent +.It Va ifi_link_state +.Pq Vt u_char +The current link state of Ethernet interfaces. +See the +.Sx Interface Link States +section for possible values. +.It Va ifi_ipackets +Number of packets received. +.It Va ifi_ierrors +Number of receive errors detected (e.g., FCS errors, DMA overruns, +etc.). +More detailed breakdowns can often be had by way of a +link-specific MIB. +.It Va ifi_opackets +Number of packets transmitted. +.It Va ifi_oerrors +Number of output errors detected (e.g., late collisions, DMA overruns, +etc.). +More detailed breakdowns can often be had by way of a +link-specific MIB. +.It Va ifi_collisions +Total number of collisions detected on output for CSMA interfaces. +(This member is sometimes [ab]used by other types of interfaces for +other output error counts.) +.It Va ifi_ibytes +Total traffic received, in bytes. +.It Va ifi_obytes +Total traffic transmitted, in bytes. +.It Va ifi_imcasts +Number of packets received which were sent by link-layer multicast. +.It Va ifi_omcasts +Number of packets sent by link-layer multicast. +.It Va ifi_iqdrops +Number of packets dropped on input. +Rarely implemented. +.It Va ifi_oqdrops +Number of packets dropped on output. +.It Va ifi_noproto +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 SNMP ) . +.El +.Ss Interface Types +The header file +.In net/if_types.h +defines symbolic constants for a number of different types of +interfaces. +The most common are: +.Pp +.Bl -tag -offset indent -width ".Dv IFT_PROPVIRTUAL" -compact +.It Dv IFT_OTHER +none of the following +.It Dv IFT_ETHER +Ethernet +.It Dv IFT_ISO88023 +ISO 8802-3 CSMA/CD +.It Dv IFT_ISO88024 +ISO 8802-4 Token Bus +.It Dv IFT_ISO88025 +ISO 8802-5 Token Ring +.It Dv IFT_ISO88026 +ISO 8802-6 DQDB MAN +.It Dv IFT_FDDI +FDDI +.It Dv IFT_PPP +Internet Point-to-Point Protocol +.Pq Xr ppp 8 +.It Dv IFT_LOOP +The loopback +.Pq Xr lo 4 +interface +.It Dv IFT_SLIP +Serial Line IP +.It Dv IFT_PARA +Parallel-port IP +.Pq Dq PLIP +.It Dv IFT_ATM +Asynchronous Transfer Mode +.It Dv IFT_USB +USB Interface +.El +.Ss Interface Link States +The following link states are currently defined: +.Pp +.Bl -tag -offset indent -width ".Dv LINK_STATE_UNKNOWN" -compact +.It Dv LINK_STATE_UNKNOWN +The link is in an invalid or unknown state. +.It Dv LINK_STATE_DOWN +The link is down. +.It Dv LINK_STATE_UP +The link is up. +.El +.Ss The ifaddr Structure +Every interface is associated with a list +(or, rather, a +.Li TAILQ ) +of addresses, rooted at the interface structure's +.Va if_addrhead +member. +The first element in this list is always an +.Dv AF_LINK +address representing the interface itself; multi-access network +drivers should complete this structure by filling in their link-layer +addresses after calling +.Fn if_attach . +Other members of the structure represent network-layer addresses which +have been configured by means of the +.Dv SIOCAIFADDR +command to +.Xr ioctl 2 , +called on a socket of the appropriate protocol family. +The elements of this list consist of +.Vt ifaddr +structures. +Most protocols will declare their own protocol-specific +interface address structures, but all begin with a +.Vt "struct ifaddr" +which provides the most-commonly-needed functionality across all +protocols. +Interface addresses are reference-counted. +.Pp +The members of +.Vt "struct ifaddr" +are as follows: +.Bl -tag -width ".Va ifa_rtrequest" -offset indent +.It Va ifa_addr +.Pq Vt "struct sockaddr *" +The local address of the interface. +.It Va ifa_dstaddr +.Pq Vt "struct sockaddr *" +The remote address of point-to-point interfaces, and the broadcast +address of broadcast interfaces. +.Va ( ifa_broadaddr +is a macro for +.Va ifa_dstaddr . ) +.It Va ifa_netmask +.Pq Vt "struct sockaddr *" +The network mask for multi-access interfaces, and the confusion +generator for point-to-point interfaces. +.It Va ifa_ifp +.Pq Vt "if_t" +A link back to the interface structure. +.It Va ifa_link +.Pq Fn TAILQ_ENTRY ifaddr +.Xr queue 3 +glue for list of addresses on each interface. +.It Va ifa_rtrequest +See below. +.It Va ifa_flags +.Pq Vt u_short +Some of the flags which would be used for a route representing this +address in the route table. +.It Va ifa_refcnt +.Pq Vt short +The reference count. +.El +.Pp +References to +.Vt ifaddr +structures are gained by calling the +.Fn ifa_ref +function and released by calling the +.Fn ifa_free +function. +.Pp +.Fn ifa_rtrequest +is a pointer to a function which receives callouts from the routing +code +.Pq Fn rtrequest +to perform link-layer-specific actions upon requests to add, +or delete routes. +The +.Fa cmd +argument indicates the request in question: +.Dv RTM_ADD , +or +.Dv RTM_DELETE . +The +.Fa rt +argument is the route in question; the +.Fa info +argument contains the specific destination being manipulated. +.Sh FUNCTIONS +The functions provided by the generic interface code can be divided +into two groups: those which manipulate interfaces, and those which +manipulate interface addresses. +In addition to these functions, there +may also be link-layer support routines which are used by a number of +drivers implementing a specific link layer over different hardware; +see the documentation for that link layer for more details. +.Ss The ifmultiaddr Structure +Every multicast-capable interface is associated with a list of +multicast group memberships, which indicate at a low level which +link-layer multicast addresses (if any) should be accepted, and at a +high level, in which network-layer multicast groups a user process has +expressed interest. +.Pp +The elements of the structure are as follows: +.Bl -tag -width ".Va ifma_refcount" -offset indent +.It Va ifma_link +.Pq Fn LIST_ENTRY ifmultiaddr +.Xr queue 3 +macro glue. +.It Va ifma_addr +.Pq Vt "struct sockaddr *" +A pointer to the address which this record represents. +The +memberships for various address families are stored in arbitrary +order. +.It Va ifma_lladdr +.Pq Vt "struct sockaddr *" +A pointer to the link-layer multicast address, if any, to which the +network-layer multicast address in +.Va ifma_addr +is mapped, else a null pointer. +If this element is non-nil, this +membership also holds an invisible reference to another membership for +that link-layer address. +.It Va ifma_refcount +.Pq Vt u_int +A reference count of requests for this particular membership. +.El +.Ss Interface Manipulation Functions +.Bl -ohang -offset indent +.It Fn if_alloc +Allocate and initialize +.Vt "struct ifnet" . +Initialization includes the allocation of an interface index and may +include the allocation of a +.Fa type +specific structure in +.Va if_l2com . +.It Fn if_alloc_dev +Allocate and initialize +.Vt "struct ifnet" +as +.Fn if_alloc +does, with the addition that the ifnet can be tagged with the +appropriate NUMA domain derived from the +.Fa dev +argument passed by the caller. +.It Fn if_alloc_domain +Allocate and initialize +.Vt "struct ifnet" +as +.Fn if_alloc +does, with the addition that the ifnet will be tagged with the NUMA +domain via the +.Fa numa_domain +argument passed by the caller. +.It Fn if_attach +Link the specified interface +.Fa ifp +into the list of network interfaces. +Also initialize the list of +addresses on that interface, and create a link-layer +.Vt ifaddr +structure to be the first element in that list. +(A pointer to +this address structure is saved in the +.Vt ifnet +structure.) +The +.Fa ifp +must have been allocated by +.Fn if_alloc , +.Fn if_alloc_dev +or +.Fn if_alloc_domain . +.It Fn if_detach +Shut down and unlink the specified +.Fa ifp +from the interface list. +.It Fn if_free +Free the given +.Fa ifp +back to the system. +The interface must have been previously detached if it was ever attached. +.It Fn if_free_type +Identical to +.Fn if_free +except that the given +.Fa type +is used to free +.Va if_l2com +instead of the type in +.Va if_type . +This is intended for use with drivers that change their interface type. +.It Fn if_down +Mark the interface +.Fa ifp +as down (i.e., +.Dv IFF_UP +is not set), +flush its output queue, notify protocols of the transition, +and generate a message from the +.Xr route 4 +routing socket. +.It Fn if_up +Mark the interface +.Fa ifp +as up, notify protocols of the transition, +and generate a message from the +.Xr route 4 +routing socket. +.It Fn ifpromisc +Add or remove a promiscuous reference to +.Fa ifp . +If +.Fa pswitch +is true, add a reference; +if it is false, remove a reference. +On reference count transitions +from zero to one and one to zero, set the +.Dv IFF_PROMISC +flag appropriately and call +.Fn if_ioctl +to set up the interface in the desired mode. +.It Fn if_allmulti +As +.Fn ifpromisc , +but for the all-multicasts +.Pq Dv IFF_ALLMULTI +flag instead of the promiscuous flag. +.It Fn ifunit +Return an +.Vt ifnet +pointer for the interface named +.Fa name . +.It Fn ifunit_ref +Return a reference-counted (via +.Fn ifa_ref ) +.Vt ifnet +pointer for the interface named +.Fa name . +This is the preferred function over +.Fn ifunit . +The caller is responsible for releasing the reference with +.Fn if_rele +when it is finished with the ifnet. +.It Fn ifioctl +Process the ioctl request +.Fa cmd , +issued on socket +.Fa so +by thread +.Fa td , +with data parameter +.Fa data . +This is the main routine for handling all interface configuration +requests from user mode. +It is ordinarily only called from the socket-layer +.Xr ioctl 2 +handler, and only for commands with class +.Sq Li i . +Any unrecognized commands will be passed down to socket +.Fa so Ns 's +protocol for +further interpretation. +The following commands are handled by +.Fn ifioctl : +.Pp +.Bl -tag -width ".Dv SIOCGIFNETMASK" -offset indent -compact +.It Dv SIOCGIFCONF +Get interface configuration. +(No call-down to driver.) +.Pp +.It Dv SIOCSIFNAME +Set the interface name. +.Dv RTM_IFANNOUNCE +departure and arrival messages are sent so that +routing code that relies on the interface name will update its interface +list. +Caller must have appropriate privilege. +(No call-down to driver.) +.It Dv SIOCGIFCAP +.It Dv SIOCGIFDATA +.It Dv SIOCGIFFIB +.It Dv SIOCGIFFLAGS +.It Dv SIOCGIFMETRIC +.It Dv SIOCGIFMTU +.It Dv SIOCGIFPHYS +Get interface capabilities, data, FIB, flags, metric, MTU, medium selection. +(No call-down to driver.) +.Pp +.It Dv SIOCSIFCAP +Enable or disable interface capabilities. +Caller must have appropriate privilege. +Before a call to the driver-specific +.Fn if_ioctl +routine, the requested mask for enabled capabilities is checked +against the mask of capabilities supported by the interface, +.Va if_capabilities . +Requesting to enable an unsupported capability is invalid. +The rest is supposed to be done by the driver, +which includes updating +.Va if_capenable +and +.Va if_data.ifi_hwassist +appropriately. +.Pp +.It Dv SIOCGIFCAPNV +.Xr nv 9 +version of the +.Dv SIOCGIFCAP +ioctl. +Caller must provide a pointer to +.Vt struct ifreq_cap_nv +as +.Fa data , +where the member +.Dv buffer +points to some buffer containing +.Dv buf_length +bytes. +The serialized nvlist with description of the device capabilities +is written to the buffer. +If buffer is too short, the structure is updated with +.Dv buffer +member set to +.Dv NULL , +.Dv length +set to the minimal required length, and error +.Er EFBIG +is returned. +.Pp +Elements of the returned nvlist for simple capabilities are boolean, +identified by names. +Presence of the boolean element means that corresponding capability is +supported by the interface. +Element's value describes the current configured state: +.Dv true +means that the capability is enabled, and +.Dv false +that it is disabled. +.Pp +Driver indicates support for both +.Dv SIOCGIFCAPNV +and +.Dv SIOCSIFCAPNV +requests by setting +.Dv IFCAP_NV +non-modifiable capability bit in +.Dv if_capabilities . +.Pp +.It Dv SIOCSIFCAPNV +.Xr nv 9 +version of the +.Dv SIOCSIFCAP +ioctl. +Caller must provide the pointer to +.Vt struct ifreq_cap_nv +as +.Fa data , +where the member +.Dv buffer +points to serialized nvlist of +.Dv length +bytes. +Each element of nvlist describes a requested update of one capability, +identified by the element name. +For simple capabilities, the element must be boolean. +Its +.Dv true +value means that the caller asks to enable the capability, and +.Dv false +value to disable. +Only capabilities listed in the nvlist are affected by the call. +.Pp +.It Dv SIOCSIFFIB +Sets interface FIB. +Caller must have appropriate privilege. +FIB values start at 0 and values greater or equals than +.Va net.fibs +are considered invalid. +.It Dv SIOCSIFFLAGS +Change interface flags. +Caller must have appropriate privilege. +If a change to the +.Dv IFF_UP +flag is requested, +.Fn if_up +or +.Fn if_down +is called as appropriate. +Flags listed in +.Dv IFF_CANTCHANGE +are masked off, and the field +.Va if_flags +in the interface structure is updated. +Finally, the driver +.Fn if_ioctl +routine is called to perform any setup +requested. +.Pp +.It Dv SIOCSIFMETRIC +.It Dv SIOCSIFPHYS +Change interface metric or medium. +Caller must have appropriate privilege. +.Pp +.It Dv SIOCSIFMTU +Change interface MTU. +Caller must have appropriate privilege. +MTU +values less than 72 or greater than 65535 are considered invalid. +The driver +.Fn if_ioctl +routine is called to implement the change; it is responsible for any +additional sanity checking and for actually modifying the MTU in the +interface structure. +.Pp +.It Dv SIOCADDMULTI +.It Dv SIOCDELMULTI +Add or delete permanent multicast group memberships on the interface. +Caller must have appropriate privilege. +The +.Fn if_addmulti +or +.Fn if_delmulti +function is called to perform the operation; qq.v. +.Pp +.It Dv SIOCAIFADDR +.It Dv SIOCDIFADDR +The socket's protocol control routine is called to implement the +requested action. +.El +.El +.Ss "Interface Address Functions" +Several functions exist to look up an interface address structure +given an address. +.Fn ifa_ifwithaddr +returns an interface address with either a local address or a +broadcast address precisely matching the parameter +.Fa addr . +.Fn ifa_ifwithdstaddr +returns an interface address for a point-to-point interface whose +remote +.Pq Dq destination +address is +.Fa addr +and a fib is +.Fa fib . +If +.Fa fib +is +.Dv RT_ALL_FIBS , +then the first interface address matching +.Fa addr +will be returned. +.Pp +.Fn ifa_ifwithnet +returns the most specific interface address which matches the +specified address, +.Fa addr , +subject to its configured netmask, or a point-to-point interface +address whose remote address is +.Fa addr +if one is found. +If +.Fa ignore_ptp +is true, skip point-to-point interface addresses. +The +.Fa fib +parameter is handled the same way as by +.Fn ifa_ifwithdstaddr . +.Pp +.Fn ifaof_ifpforaddr +returns the most specific address configured on interface +.Fa ifp +which matches address +.Fa addr , +subject to its configured netmask. +If the interface is +point-to-point, only an interface address whose remote address is +precisely +.Fa addr +will be returned. +.Pp +All of these functions return a null pointer if no such address can be +found. +.Ss "Interface Multicast Address Functions" +The +.Fn if_addmulti , +.Fn if_delmulti , +and +.Fn if_findmulti +functions provide support for requesting and relinquishing multicast +group memberships, and for querying an interface's membership list, +respectively. +The +.Fn if_addmulti +function takes a pointer to an interface, +.Fa ifp , +and a generic address, +.Fa sa . +It also takes a pointer to a +.Vt "struct ifmultiaddr *" +which is filled in on successful return with the address of the +group membership control block. +The +.Fn if_addmulti +function performs the following four-step process: +.Bl -enum -offset indent +.It +Call the interface's +.Fn if_resolvemulti +entry point to determine the link-layer address, if any, corresponding +to this membership request, and also to give the link layer an +opportunity to veto this membership request should it so desire. +.It +Check the interface's group membership list for a pre-existing +membership for this group. +If one is not found, allocate a new one; +if one is, increment its reference count. +.It +If the +.Fn if_resolvemulti +routine returned a link-layer address corresponding to the group, +repeat the previous step for that address as well. +.It +If the interface's multicast address filter needs to be changed +because a new membership was added, call the interface's +.Fn if_ioctl +routine +(with a +.Fa cmd +argument of +.Dv SIOCADDMULTI ) +to request that it do so. +.El +.Pp +The +.Fn if_delmulti +function, given an interface +.Fa ifp +and an address, +.Fa sa , +reverses this process. +Both functions return zero on success, or a +standard error number on failure. +.Pp +The +.Fn if_findmulti +function examines the membership list of interface +.Fa ifp +for an address matching +.Fa sa , +and returns a pointer to that +.Vt "struct ifmultiaddr" +if one is found, else it returns a null pointer. +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr link_addr 3 , +.Xr queue 3 , +.Xr sysctl 3 , +.Xr bpf 4 , +.Xr ifmib 4 , +.Xr lo 4 , +.Xr netintro 4 , +.Xr polling 4 , +.Xr config 8 , +.Xr ppp 8 , +.Xr mbuf 9 , +.Xr rtentry 9 +.Rs +.%A Gary R. Wright +.%A W. Richard Stevens +.%B TCP/IP Illustrated +.%V Vol. 2 +.%O Addison-Wesley, ISBN 0-201-63354-X +.Re +.Sh AUTHORS +This manual page was written by +.An Garrett A. Wollman . diff --git a/static/freebsd/man9/inittodr.9 b/static/freebsd/man9/inittodr.9 new file mode 100644 index 00000000..9fc697da --- /dev/null +++ b/static/freebsd/man9/inittodr.9 @@ -0,0 +1,121 @@ +.\" $NetBSD: inittodr.9,v 1.2 1996/03/27 21:16:06 jtc Exp $ +.\" +.\" Copyright (c) 1994 Christopher G. Demetriou +.\" 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 Christopher G. Demetriou +.\" for the NetBSD Project. +.\" 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 March 22, 1997 +.Dt INITTODR 9 +.Os +.Sh NAME +.Nm inittodr +.Nd initialize system time +.Sh SYNOPSIS +.In sys/types.h +.In sys/systm.h +.Ft void +.Fn inittodr "time_t base" +.Sh DESCRIPTION +The +.Fn inittodr +function determines the time and sets the system clock. +It tries to pick the correct time using a set of heuristics that examine +the system's battery backed clock and the time obtained from the root +file system, as given in +.Fa base . +How the +.Fa base +value is obtained will vary depending on the +root file system type. +The heuristics used include: +.Bl -bullet +.It +If the battery-backed clock has a valid time, it is used. +.\" .It +.\" If the battery-backed clock does not have a valid time, and +.\" the time provided in +.\" .Fa base +.\" is within reason, +.\" .Fa base +.\" is used as the current time. +.\" .It +.\" If the battery-backed clock appears invalid, and +.\" .Fa base +.\" appears non-sensical or was not provided (was given as zero), +.\" a arbitrary base (typically some time in the late 1970s) +.\" will be used. +.It +If the battery-backed clock does not have a valid time, +the time provided in +.Fa base +will be used. +.El +.Pp +Once a system time has been determined, it is stored in the +.Va time +variable. +.Sh DIAGNOSTICS +The +.Fn inittodr +function prints diagnostic messages if it has trouble figuring +out the system time. +Conditions that can cause diagnostic messages to be printed include: +.Bl -bullet +.It +The battery-backed clock's time appears nonsensical. +.\" .It +.\" The +.\" .Fa base +.\" time appears nonsensical. +.\" .It +.\" The +.\" .Fa base +.\" time and the battery-backed clock's time differ by a large amount. +.El +.Sh SEE ALSO +.Xr resettodr 9 , +.Xr time 9 +.Sh BUGS +On many systems, +.Fn inittodr +has to convert from +a time expressed in terms of year, month, day, hours, minutes, +and seconds to +.Va time , +expressed in seconds. +Many of the implementations could share code, but do not. +.Pp +Each system's heuristics for picking the correct time are slightly +different. +.Pp +The +.Fx +implementation should do a better job of validating the time provided in +.Fa base +when the battery-backed clock is unusable. +Currently it unconditionally sets the system clock to this value. diff --git a/static/freebsd/man9/insmntque.9 b/static/freebsd/man9/insmntque.9 new file mode 100644 index 00000000..33ba697b --- /dev/null +++ b/static/freebsd/man9/insmntque.9 @@ -0,0 +1,97 @@ +.\" Copyright (C) 2008 Chad David . +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 October 24, 2025 +.Dt INSMNTQUE 9 +.Os +.Sh NAME +.Nm insmntque , +.Nm insmntque1 +.Nd "associate a vnode with a mount" +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn insmntque "struct vnode *vp" "struct mount *mp" +.Ft int +.Fn insmntque1 "struct vnode *vp" "struct mount *mp" +.Sh DESCRIPTION +The +.Fn insmntque +function associates a vnode with a mount. +This includes updating +.Va v_mount +for the vnode, and inserting the vnode into the mount's vnode list. +.Pp +The indirect mount reference count, maintained as the count of the +vnodes owned by it, is incremented for each vnode added to the +mount, and that reference is decremented by +.Xr vgone 9 . +.Pp +The mount's interlock is held while the vnode is inserted. +The vnode must be exclusively locked. +.Pp +On failure, +.Fn insmntque +resets vnode's operations vector to the vector of +.Xr deadfs 9 , +clears +.Va v_data , +and then calls +.Xr vgone 9 +and +.Xr vput 9 . +If more elaborated cleanup after +.Fn insmntque +failure is needed, the +.Fn insmntque1 +function may be used instead. +It does not do any cleanup following a failure, leaving all +the work to the caller. +In particular, the operations vector +.Va v_op +and +.Va v_data +fields of the vnode are kept intact. +.Sh RETURN VALUES +The +.Fn insmntque +function will always return 0, unless the file system is currently being unmounted +in which case it may return +.Dv EBUSY . +Also, +.Fn insmntque +may be forced to insert the vnode into the mount's vnode list +by setting the +.Va VV_FORCEINSMQ +flag in the vnode +.Va v_flag , +even if the file system is being unmounted. +.Sh SEE ALSO +.Xr vgone 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/intr_event.9 b/static/freebsd/man9/intr_event.9 new file mode 100644 index 00000000..ba8faf87 --- /dev/null +++ b/static/freebsd/man9/intr_event.9 @@ -0,0 +1,481 @@ +.\" Copyright (c) 2001 John H. Baldwin +.\" Copyright (c) 2006 Tom Rhodes +.\" Copyright (c) 2021 Mitchell Horne +.\" Copyright (c) 2022 The FreeBSD Foundation +.\" +.\" Portions of this documentation were written by Mitchell Horne +.\" under sponsorship from the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 24, 2025 +.Dt INTR_EVENT 9 +.Os +.Sh NAME +.Nm intr_event_add_handler , +.Nm intr_event_create , +.Nm intr_event_destroy , +.Nm intr_event_handle , +.Nm intr_event_remove_handler , +.Nm intr_priority +.Nd "kernel interrupt handler and thread API" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.In sys/interrupt.h +.Ft int +.Fo intr_event_add_handler +.Fa "struct intr_event *ie" +.Fa "const char *name" +.Fa "driver_filter_t filter" +.Fa "driver_intr_t handler" +.Fa "void *arg" +.Fa "u_char pri" +.Fa "enum intr_type flags" +.Fa "void **cookiep" +.Fc +.Ft int +.Fo intr_event_create +.Fa "struct intr_event **event" +.Fa "void *source" +.Fa "int flags" +.Fa "int irq" +.Fa "void (*pre_ithread)(void *)" +.Fa "void (*post_ithread)(void *)" +.Fa "void (*post_filter)(void *)" +.Fa "int (*assign_cpu)(void *, int)" +.Fa "const char *fmt" +.Fa "..." +.Fc +.Ft int +.Fn intr_event_destroy "struct intr_event *ie" +.Ft int +.Fn intr_event_handle "struct intr_event *ie" "struct trapframe *frame" +.Ft int +.Fn intr_event_remove_handler "void *cookie" +.Ft u_char +.Fn intr_priority "enum intr_type flags" +.Sh DESCRIPTION +The interrupt event API provides methods to manage the registration and +execution of interrupt handlers and their associated thread contexts. +.Pp +Each interrupt event in the system corresponds to a single hardware or software +interrupt source. +Each interrupt event maintains a list of interrupt handlers, sorted by +priority, which will be invoked when handling the event. +An interrupt event will typically, but not always, have an associated +.Xr kthread 9 , +known as the interrupt thread. +Finally, each event contains optional callback functions which will be +invoked before and after the handler functions themselves. +.Pp +An interrupt handler contains two distinct handler functions: +the +.Em filter +and the thread +.Em handler . +The +.Em filter +function is run from interrupt context and is intended to perform quick +handling such as acknowledging or masking a hardware interrupt, +and queueing work for the ensuing thread +.Em handler . +Both functions are optional; each interrupt handler may choose to register a +filter, a thread handler, or both. +Each interrupt handler also consists of a name, +a set of flags, +and an opaque argument which will be passed to both the +.Em filter +and +.Em handler +functions. +.Ss Handler Constraints +The +.Em filter +function is executed inside a +.Xr critical 9 +section. +Therefore, filters may not yield the CPU for any reason, and may only use spin +locks to access shared data. +Allocating memory within a filter is not permitted. +.Pp +The +.Em handler +function executes from the context of the associated interrupt kernel thread. +Sleeping is not permitted, but the interrupt thread may be preempted by higher +priority threads. +Thus, threaded handler functions may obtain non-sleepable locks, as described +in +.Xr locking 9 . +Any memory or zone allocations in an interrupt thread must specify the +.Dv M_NOWAIT +flag, and any allocation errors must be handled. +.Pp +The exception to these constraints is software interrupt threads, which are +allowed to sleep but should be allocated and scheduled using the +.Xr swi 9 +interface. +.Ss Function Descriptions +The +.Fn intr_event_create +function creates a new interrupt event. +The +.Fa event +argument points to a +.Vt struct intr_event +pointer that will reference the newly created event upon success. +The +.Fa source +argument is an opaque pointer which will be passed to the +.Fa pre_ithread , +.Fa post_ithread , +and +.Fa post_filter +callbacks. +The +.Fa flags +argument is a mask of properties of this thread. +The only valid flag currently for +.Fn intr_event_create +is +.Dv IE_SOFT +to specify that this interrupt thread is a software interrupt. +The +.Fa enable +and +.Fa disable +arguments specify optional functions used to enable and disable this +interrupt thread's interrupt source. +The +.Fa irq +argument is the unique interrupt vector number corresponding to the event. +The +.Fa pre_ithread , +.Fa post_ithread , +and +.Fa post_filter +arguments are callback functions that are invoked at different +points while handling an interrupt. +This is described in more detail in the +.Sx Handler Callbacks +section, below. +They may be +.Va NULL +to specify no callback. +The +.Fa assign_cpu +argument points to a callback function that will be invoked when binding +an interrupt to a particular CPU. +It may be +.Va NULL +if binding is unsupported. +The +remaining arguments form a +.Xr printf 9 +argument list that is used to build the base name of the new interrupt thread. +The full name of an interrupt thread is formed by concatenating the base +name of the interrupt thread with the names of all of its interrupt handlers. +.Pp +The +.Fn intr_event_destroy +function destroys a previously created interrupt event by releasing its +resources. +.\" The following is not true (yet): +.\"and arranging for the backing kernel thread to terminate. +An interrupt event can only be destroyed if it has no handlers remaining. +.Pp +The +.Fn intr_event_add_handler +function adds a new handler to an existing interrupt event specified by +.Fa ie . +The +.Fa name +argument specifies a name for this handler. +The +.Fa filter +argument provide the filter function to execute. +The +.Fa handler +argument provides the handler function to be executed from the +event's interrupt thread. +The +.Fa arg +argument will be passed to the +.Fa filter +and +.Fa handler +functions when they are invoked. +The +.Fa pri +argument specifies the priority of this handler, +corresponding to the values defined in +.In sys/priority.h . +It determines the order this handler is called relative to the other handlers +for this event, as well as the scheduling priority of the backing kernel +thread. +.Fa flags +argument can be used to specify properties of this handler as defined in +.In sys/bus.h . +If +.Fa cookiep +is not +.Dv NULL , +then it will be assigned a cookie that can be used later to remove this +handler. +.Pp +The +.Fn intr_event_handle +function is the main entry point into the interrupt handling code. +It must be called from an interrupt context. +The function will execute all filter handlers associated with the interrupt +event +.Fa ie , +and schedule the associated interrupt thread to run, if applicable. +The +.Fa frame +argument is used to pass a pointer to the +.Vt struct trapframe +containing the machine state at the time of the interrupt. +The main body of this function runs within a +.Xr critical 9 +section. +.Pp +The +.Fn intr_event_remove_handler +function removes an interrupt handler from the interrupt event specified by +.Fa ie . +The +.Fa cookie +argument, obtained from +.Fn intr_event_add_handler , +identifies the handler to remove. +.Pp +The +.Fn intr_priority +function translates the +.Dv INTR_TYPE_* +interrupt flags into interrupt thread scheduling priorities. +.Pp +The interrupt flags not related to the type of a particular interrupt +.Pq Dv INTR_TYPE_* +can be used to specify additional properties of both hardware and software +interrupt handlers. +The +.Dv INTR_EXCL +flag specifies that this handler cannot share an interrupt thread with +another handler. +The +.Dv INTR_MPSAFE +flag specifies that this handler is MP safe in that it does not need the +Giant mutex to be held while it is executed. +The +.Dv INTR_ENTROPY +flag specifies that the interrupt source this handler is tied to is a good +source of entropy, and thus that entropy should be gathered when an interrupt +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 +is assigned three optional callback functions when it is created: +.Fa pre_ithread , +.Fa post_ithread , +and +.Fa post_filter . +These callbacks are intended to be defined by the interrupt controller driver, +to allow for actions such as masking and unmasking hardware interrupt signals. +.Pp +When an interrupt is triggered, all filters are run to determine if any +threaded interrupt handlers should be scheduled for execution by the associated +interrupt thread. If no threaded handlers are scheduled, the +.Fa post_filter +callback is invoked which should acknowledge the interrupt and permit it to +trigger in the future. +If any threaded handlers are scheduled, the +.Fa pre_ithread +callback is invoked instead. +This handler should acknowledge the interrupt, but it should also ensure that +the interrupt will not fire continuously until after the threaded handlers have +executed. +Typically this callback masks level-triggered interrupts in an interrupt +controller while leaving edge-triggered interrupts alone. +Once all threaded handlers have executed, +the +.Fa post_ithread +callback is invoked from the interrupt thread to enable future interrupts. +Typically this callback unmasks level-triggered interrupts in an interrupt +controller. +.Sh RETURN VALUES +The +.Fn intr_event_add_handler , +.Fn intr_event_create , +.Fn intr_event_destroy , +.Fn intr_event_handle , +and +.Fn intr_event_remove_handler +functions return zero on success and non-zero on failure. +The +.Fn intr_priority +function returns a process priority corresponding to the passed in interrupt +flags. +.Sh EXAMPLES +The +.Xr swi_add 9 +function demonstrates the use of +.Fn intr_event_create +and +.Fn intr_event_add_handler . +.Bd -literal -offset indent +int +swi_add(struct intr_event **eventp, const char *name, driver_intr_t handler, + void *arg, int pri, enum intr_type flags, void **cookiep) +{ + struct intr_event *ie; + int error = 0; + + if (flags & INTR_ENTROPY) + return (EINVAL); + + ie = (eventp != NULL) ? *eventp : NULL; + + if (ie != NULL) { + if (!(ie->ie_flags & IE_SOFT)) + return (EINVAL); + } else { + error = intr_event_create(&ie, NULL, IE_SOFT, 0, + NULL, NULL, NULL, swi_assign_cpu, "swi%d:", pri); + if (error) + return (error); + if (eventp != NULL) + *eventp = ie; + } + if (handler != NULL) { + error = intr_event_add_handler(ie, name, NULL, handler, arg, + PI_SWI(pri), flags, cookiep); + } + return (error); +} +.Ed +.Sh ERRORS +The +.Fn intr_event_add_handler +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa ie +or +.Fa name +arguments are +.Dv NULL . +.It Bq Er EINVAL +The +.Fa handler +and +.Fa filter +arguments are both +.Dv NULL . +.It Bq Er EINVAL +The +.Dv IH_EXCLUSIVE +flag is specified and the interrupt thread +.Fa ie +already has at least one handler, or the interrupt thread +.Fa ie +already has an exclusive handler. +.El +.Pp +The +.Fn intr_event_create +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +A flag other than +.Dv IE_SOFT +was specified in the +.Fa flags +parameter. +.El +.Pp +The +.Fn intr_event_destroy +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa ie +argument is +.Dv NULL . +.It Bq Er EBUSY +The interrupt event pointed to by +.Fa ie +has at least one handler which has not been removed with +.Fn intr_event_remove_handler . +.El +.Pp +The +.Fn intr_event_handle +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa ie +argument is +.Dv NULL . +.It Bq Er EINVAL +There are no interrupt handlers assigned to +.Fa ie . +.It Bq Er EINVAL +The interrupt was not acknowledged by any filter and has no associated thread +handler. +.El +.Pp +The +.Fn intr_event_remove_handler +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa cookie +argument is +.Dv NULL . +.El +.Sh SEE ALSO +.Xr critical 9 , +.Xr kthread 9 , +.Xr locking 9 , +.Xr malloc 9 , +.Xr swi 9 , +.Xr uma 9 +.Sh HISTORY +Interrupt threads and their corresponding API first appeared in +.Fx 5.0 . diff --git a/static/freebsd/man9/intro.9 b/static/freebsd/man9/intro.9 new file mode 100644 index 00000000..0d42efb2 --- /dev/null +++ b/static/freebsd/man9/intro.9 @@ -0,0 +1,517 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2023 The FreeBSD Foundation +.\" +.\" This manual page was written by Mitchell Horne under +.\" sponsorship from the FreeBSD Foundation. +.\" +.Dd January 30, 2024 +.Dt INTRO 9 +.Os +.Sh NAME +.Nm intro +.Nd "introduction to kernel programming interfaces" +.Sh DESCRIPTION +Welcome to the +.Fx +kernel documentation. +Outside the source code itself, this set of +.Xr man 1 +pages is the primary resource for information on usage of the numerous +programming interfaces available within the kernel. +In some cases, it is also a source of truth for the implementation details +and/or design decisions behind a particular subsystem or piece of code. +.Pp +The intended audience of this documentation is developers, and the primary +authors are also developers. +It is written assuming a certain familiarity with common programming or +OS-level concepts and practices. +However, this documentation should also attempt to provide enough background +information that readers approaching a particular subsystem or interface for +the first time will be able to understand. +.Pp +To further set expectations, we acknowledge that kernel documentation, like the +source code itself, is forever a work-in-progress. +There will be large sections of the codebase whose documentation is subtly or +severely outdated, or missing altogether. +This documentation is a supplement to the source code, and cannot always be +taken at face value. +.Pp +At its best, section 9 documentation will provide a description of a particular +piece of code that, paired with its implementation, fully informs the reader of +the intended and realized effects. +.Pp +.Xr man 1 +pages in this section most frequently describe functions, but may also +describe types, global variables, macros, or high-level concepts. +.Sh CODING GUIDELINES +Code written for the +.Fx +kernel is expected to conform to the established style and coding conventions. +Please see +.Xr style 9 +for a detailed set of rules and guidelines. +.Sh OVERVIEW +Below is presented various subsystems. +.Ss Data Structures +There are implementations for many well-known data structures available in the +kernel. +.Bl -tag -width "Xr bitstring 3" +.It Xr bitstring 3 +Simple bitmap implementation. +.It Xr counter 9 +An SMP-safe general-purpose counter implementation. +.It Xr hash 9 +Hash map implementation. +.It Xr nv 9 +Name/value pairs. +.It Xr queue 3 +Singly-linked and doubly-linked lists, and queues. +.It Xr refcount 9 +An SMP-safe implementation of reference counts. +.It Xr sbuf 9 +Dynamic string composition. +.It Xr sglist 9 +A scatter/gather list implementation. +.El +.Ss Utility Functions +Functions or facilities of general usefulness or convenience. +See also the +.Sx Testing and Debugging Tools +or +.Sx Miscellaneous +sub-sections below. +.Pp +Formatted output and logging functions are described by +.Xr printf 9 . +.Pp +Endian-swapping functions: +.Xr byteorder 9 . +.Pp +Data output in hexadecimal format: +.Xr hexdump 9 . +.Pp +A rich set of macros for declaring +.Xr sysctl 8 +variables and functions is described by +.Xr sysctl 9 . +.Pp +Non-recoverable errors in the kernel should trigger a +.Xr panic 9 . +Run-time assertions can be verified using the +.Xr KASSERT 9 +macros. +Compile-time assertions should use +.Fn _Static_assert . +.Pp +The SYSINIT framework provides macros for declaring functions that will be +executed during start-up and shutdown; see +.Xr SYSINIT 9 . +.Pp +Deprecation messages may be emitted with +.Xr gone_in 9 . +.Pp +A unit number facility is provided by +.Xr unr 9 . +.Ss Synchronization Primitives +The +.Xr locking 9 +man page gives an overview of the various types of locks available in the +kernel and advice on their usage. +.Pp +Atomic primitives are described by +.Xr atomic 9 . +.Pp +The +.Xr epoch 9 +and +.Xr smr 9 +facilities are used to create lock-free data structures. +There is also +.Xr seqc 9 . +.Ss Memory Management +Dynamic memory allocations inside the kernel are generally done using +.Xr malloc 9 . +Frequently allocated objects may prefer to use +.Xr uma 9 . +.Pp +.\" MHTODO: It would be useful to have a vm_page(9) or similar +.\" high-level page which points to the following contents instead. +Much of the virtual memory system operates on +.Vt vm_page_t +structures. +The following functions are documented: +.Bd -ragged -offset indent +.Xr vm_page_advise 9 , +.Xr vm_page_aflag 9 , +.Xr vm_page_alloc 9 , +.Xr vm_page_bits 9 , +.Xr vm_page_busy 9 , +.Xr vm_page_deactivate 9 , +.Xr vm_page_free 9 , +.Xr vm_page_grab 9 , +.Xr vm_page_insert 9 , +.Xr vm_page_lookup 9 , +.Xr vm_page_rename 9 , +.Xr vm_page_sbusy 9 , +.Xr vm_page_wire 9 +.Ed +.Pp +Virtual address space maps are managed with the +.Xr vm_map 9 +API. +.Pp +The machine-dependent portion of the virtual memory stack is the +.Xr pmap 9 +module. +.Pp +Allocation policies for NUMA memory domains are managed with the +.Xr domainset 9 +API. +.Ss File Systems +The kernel interface for file systems is +.Xr VFS 9 . +File system implementations register themselves with +.Xr vfsconf 9 . +.Pp +The +.Xr vnode 9 +is the abstract and filesystem-independent representation of a file, +directory, or other file-like entity within the kernel. +.Pp +The implementation of access control lists for filesystems is described by +.Xr acl 9 . +Also +.Xr vaccess 9 . +.Ss I/O and Storage +.\" TODO: This page needs to be rewritten before it can be included here. +.\" The buffer cache is described by: +.\" .Xr buf 9 +.\" .Pp +The GEOM framework represents I/O requests using the +.Xr bio 9 +structure. +.Pp +Disk drivers connect themselves to GEOM using the +.Xr disk 9 +API. +.Pp +The +.Xr devstat 9 +facility provides an interface for recording device statistics in disk drivers. +.Ss Networking +Much of the networking stack uses the +.Xr mbuf 9 , +a flexible memory management unit commonly used to store network packets. +.Pp +Network interfaces are implemented using the +.Xr ifnet 9 +API, which has functions for drivers and consumers. +.Pp +A framework for managing packet output queues is described by +.Xr altq 9 . +.Pp +To receive incoming packets, network protocols register themselves with +.Xr netisr 9 . +.Pp +Virtualization of the network stack is provided by +.Xr VNET 9 . +.Pp +The front-end for interfacing with network sockets from within the kernel is +described by +.Xr socket 9 . +The back-end interface for socket implementations is +.Xr domain 9 . +.Pp +The low-level packet filter interface is described by +.Xr pfil 9 . +.Pp +The +.Xr bpf 9 +interface provides a mechanism to redirect packets to userspace. +.Pp +The subsystem for IEEE 802.11 wireless networking is described by +.Xr ieee80211 9 . +.Pp +A framework for modular TCP implementations is described by +.Xr tcp_functions 9 . +.Pp +A framework for modular congestion control algorithms is described by +.Xr mod_cc 9 . +.Ss Device Drivers +.\" TODO: a bus(9) or newbus(9) page, as well as updates to existing pages +.\" would be helpful in laying out the high-level concepts of FreeBSD's device +.\" structure, and explaining the organization of existing documentation. +Consult the +.Xr device 9 +and +.Xr driver 9 +pages first. +.Pp +Most drivers act as devices, and provide a set of methods implementing the +device interface. +This includes methods such as +.Xr DEVICE_PROBE 9 , +.Xr DEVICE_ATTACH 9 , +and +.Xr DEVICE_DETACH 9 . +.Pp +In addition to devices, there are buses. +Buses may have children, in the form of devices or other buses. +Bus drivers will implement additional methods, such as +.Xr BUS_ADD_CHILD 9 , +.Xr BUS_READ_IVAR 9 , +or +.Xr BUS_RESCAN 9 . +.Pp +Buses often perform resource accounting on behalf of their children. +For this there is the +.Xr rman 9 +API. +.Pp +Drivers can request and manage their resources (e.g. memory-space or IRQ +number) from their parent using the following sets of functions: +.Bd -ragged -offset indent +.Xr bus_alloc_resource 9 , +.Xr bus_adjust_resource 9 , +.Xr bus_get_resource 9 , +.Xr bus_map_resource 9 , +.Xr bus_release_resource 9 , +.Xr bus_set_resource 9 +.Ed +.Pp +Direct Memory Access (DMA) is handled using the +.Xr busdma 9 +framework. +.Pp +Functions for accessing bus space (i.e. read/write) are provided by +.Xr bus_space 9 . +.Ss Clocks and Timekeeping +The kernel clock frequency and overall system time model is described by +.Xr hz 9 . +.Pp +A few global time variables, such as system up-time, are described by +.Xr time 9 . +.Pp +Raw CPU cycles are provided by +.Xr get_cyclecount 9 . +.Ss Userspace Memory Access +Direct read/write access of userspace memory from the kernel is not permitted, +and memory transactions that cross the kernel/user boundary must go through one +of several interfaces built for this task. +.Pp +Most device drivers use the +.Xr uiomove 9 +set of routines. +.Pp +Simpler primitives for reading or writing smaller chunks of memory are +described by +.Xr casuword 9 , +.Xr copy 9 , +.Xr fetch 9 , +and +.Xr store 9 . +.Ss Kernel Threads, Tasks, and Callbacks +Kernel threads and processes are created using the +.Xr kthread 9 +and +.Xr kproc 9 +interfaces, respectively. +.Pp +Where dedicated kernel threads are too heavyweight, there is also the +.Xr taskqueue 9 +interface. +.Pp +For low-latency callback handling, the +.Xr callout 9 +framework should be used. +.Pp +Dynamic handlers for pre-defined event hooks are registered and invoked using +the +.Xr EVENTHANDLER 9 +API. +.Ss Thread Switching and Scheduling +The machine-independent interface to a context switch is +.Xr mi_switch 9 . +.Pp +To prevent preemption, use a +.Xr critical 9 +section. +.Pp +To voluntarily yield the processor, use +.Xr kern_yield 9 . +.Pp +The various functions which will deliberately put a thread to sleep are +described by +.Xr sleep 9 . +Sleeping threads are removed from the scheduler and placed on a +.Xr sleepqueue 9 . +.\" TODO: This page is outdated and can't be included here yet. +.\".Pp +.\"The thread scheduler interface is described by +.\".Xr scheduler 9 . +.Ss Processes and Signals +To locate a process or process group by its identifier, use +.Xr pfind 9 +and +.Xr pgfind 9 . +Alternatively, the +.Xr pget 9 +function provides additional search specificity. +.Pp +The "hold count" of a process can be manipulated with +.Xr PHOLD 9 . +.Pp +The kernel interface for signals is described by +.Xr signal 9 . +.Pp +Signals can be sent to processes or process groups using the functions +described by +.Xr psignal 9 . +.Ss Security +See the overview in +.Xr security 7 . +.Pp +The basic structure for user credentials is +.Vt struct ucred , +managed by the +.Xr ucred 9 +API. +Thread credentials are verified using +.Xr priv 9 +to allow or deny certain privileged actions. +.Pp +Policies influenced by +.Va kern.securelevel +must use the +.Xr securelevel_gt 9 +or +.Xr securelevel_ge 9 +functions. +.Pp +The Mandatory Access Control (MAC) framework provides a wide set of hooks, +supporting dynamically-registered security modules; +see +.Xr mac 9 . +.Pp +Cryptographic services are provided by the OpenCrypto framework. +This API provides an interface for both consumers and crypto drivers; +see +.Xr crypto 9 . +.Pp +For information on random number generation, see +.Xr random 9 +and +.Xr prng 9 . +.Ss Kernel Modules +The interfaces for declaring loadable kernel modules are described by +.Xr module 9 . +.Ss Interrupts +.Xr intr_event 9 +describes the machine-independent portion of the interrupt framework +that supports registration and execution of interrupt handlers. +.Pp +Software interrupts are provided by +.Xr swi 9 . +.Pp +Device drivers register their interrupt handlers using the +.Xr bus_setup_intr 9 +function. +.Ss Testing and Debugging Tools +A kernel test framework: +.Xr kern_testfrwk 9 +.Pp +A facility for defining configurable fail points is described by +.Xr fail 9 . +.Pp +Commands for the +.Xr ddb 4 +kernel debugger are defined with the +.Xr DB_COMMAND 9 +family of macros. +.Pp +The +.Xr ktr 4 +tracing facility adds static tracepoints to many areas of the kernel. +These tracepoints are defined using the macros described by +.Xr ktr 9 . +.Pp +Static probes for DTrace are defined using the +.Xr SDT 9 +macros. +.Pp +Stack traces can be captured and printed with the +.Xr stack 9 +API. +.Pp +Kernel sanitizers can perform additional compiler-assisted checks against +memory use/access. +These runtimes are capable of detecting difficult-to-identify classes of bugs, +at the cost of a large overhead. +The Kernel Address Sanitizer +.Xr KASAN 9 +and Kernel Memory Sanitizer +.Xr KMSAN 9 +are supported. +.Pp +The +.Xr LOCK_PROFILING 9 +kernel config option enables extra code to assist with profiling and/or +debugging lock performance. +.Ss Driver Tools +Defined functions/APIs for specific types of devices. +.Bl -tag -width "Xr usbdi 9" +.It Xr iflib 9 +Programming interface for +.Xr iflib 4 +based network drivers. +.It Xr pci 9 +Peripheral Component Interconnect (PCI) and PCI Express (PCIe) programming API. +.It Xr pwmbus 9 +Pulse-Width Modulation (PWM) bus interface methods. +.It Xr usbdi 9 +Universal Serial Bus programming interface. +.It Xr superio 9 +Functions for Super I/O controller devices. +.El +.Ss Miscellaneous +Dynamic per-CPU variables: +.Xr dpcpu 9 . +.Pp +CPU bitmap management: +.Xr cpuset 9 . +.Pp +Kernel environment management: +.Xr getenv 9 . +.Pp +Contexts for CPU floating-point registers are managed by the +.Xr fpu_kern 9 +facility. +.Pp +For details on the shutdown/reboot procedure and available shutdown hooks, see +.Xr reboot 9 . +.Pp +A facility for asynchronous logging to files from within the kernel is provided +by +.Xr alq 9 . +.Pp +The +.Xr osd 9 +framework provides a mechanism to dynamically extend core structures in a way +that preserves KBI. +See the +.Xr hhook 9 +and +.Xr khelp 9 +APIs for information on how this is used. +.Pp +The kernel object implementation is described by +.Xr kobj 9 . +.Sh SEE ALSO +.Xr man 1 , +.Xr style 9 +.Rs +.%T The FreeBSD Architecture Handbook +.%U https://docs.freebsd.org/en/books/arch-handbook/ +.Re diff --git a/static/freebsd/man9/kasan.9 b/static/freebsd/man9/kasan.9 new file mode 100644 index 00000000..77d7e8f4 --- /dev/null +++ b/static/freebsd/man9/kasan.9 @@ -0,0 +1,185 @@ +.\"- +.\" Copyright (c) 2021 The FreeBSD Foundation +.\" +.\" This documentation was written by Mark Johnston under sponsorship from +.\" the FreeBSD Foundation. +.\" +.\" 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 October 13, 2023 +.Dt KASAN 9 +.Os +.Sh NAME +.Nm KASAN +.Nd Kernel Address SANitizer +.Sh SYNOPSIS +The +.Pa GENERIC-KASAN +kernel configuration can be used to compile a KASAN-enabled kernel using +.Pa GENERIC +as a base configuration. +Alternately, to compile KASAN into the kernel, place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "options KASAN" +.Ed +.Pp +.In sys/asan.h +.Ft void +.Fn kasan_mark "const void *addr" "size_t size" "size_t redzsize" "uint8_t code" +.Sh DESCRIPTION +.Nm +is a subsystem which leverages compiler instrumentation to detect invalid +memory accesses in the kernel. +Currently it is implemented on the amd64 and arm64 platforms. +.Pp +When +.Nm +is compiled into the kernel, the compiler is configured to emit function +calls upon every memory access. +The functions are implemented by +.Nm +and permit run-time detection of several types of bugs including +use-after-frees, double frees and frees of invalid pointers, and out-of-bounds +accesses. +These protections apply to memory allocated by +.Xr uma 9 , +.Xr malloc 9 +and related functions, and +.Fn kmem_malloc +and related functions, +as well as global variables and kernel stacks. +.Nm +is conservative and will not detect all instances of these types of bugs. +Memory accesses through the kernel map are sanitized, but accesses via the +direct map are not. +When +.Nm +is configured, the kernel aims to minimize its use of the direct map. +.Sh IMPLEMENTATION NOTES +.Nm +is implemented using compiler instrumentation and a kernel runtime. +When a +kernel is built with the KASAN option enabled, the compiler inserts function calls +before most memory accesses in the generated code. +The runtime implements the corresponding functions, which decide whether a +given access is valid. +If not, the runtime prints a warning or panics the kernel, depending on the +value of the +.Sy debug.kasan.panic_on_violation +sysctl/tunable. +.Pp +The +.Nm +runtime in a KASAN-configured kernel can be disabled by +setting the loader tunable +.Sy debug.kasan.disable=1 . +.Pp +The +.Nm +runtime works by maintaining a shadow map for the kernel map. +There exists a linear mapping between addresses in the kernel map and addresses +in the shadow map. +The shadow map is used to store information about the current state of +allocations from the kernel map. +For example, when a buffer is returned by +.Xr malloc 9 , +the corresponding region of the shadow map is marked to indicate that the +buffer is valid. +When it is freed, the shadow map is updated to mark the buffer as invalid. +Accesses to the buffer are intercepted by the +.Nm +runtime and validated using the contents of the shadow map. +.Pp +Upon booting, all kernel memory is marked as valid. +Kernel allocators must mark cached but free buffers as invalid, and must mark +them valid before freeing the kernel virtual address range. +This slightly reduces the effectiveness of +.Nm +but simplifies its maintenance and integration into the kernel. +.Pp +Updates to the shadow map are performed by calling +.Fn kasan_mark . +Parameter +.Fa addr +is the address of the buffer whose shadow is to be updated, +.Fa size +is the usable size of the buffer, and +.Fa redzsize +is the full size of the buffer allocated from lower layers of the system. +.Fa redzsize +must be greater than or equal to +.Fa size . +In some cases kernel allocators will return a buffer larger than that requested +by the consumer; the unused space at the end is referred to as a red zone and is +always marked as invalid. +.Fa code +allows the caller to specify an identifier used when marking a buffer as invalid. +The identifier is included in any reports generated by +.Nm +and helps identify the source of the invalid access. +For instance, when an item is freed to a +.Xr uma 9 +zone, the item is marked with +.Dv KASAN_UMA_FREED . +See +.In sys/asan.h +for the available identifiers. +If the entire buffer is to be marked valid, i.e., +.Fa size +and +.Fa redzsize +are equal, +.Fa code +should be 0. +.Sh SEE ALSO +.Xr build 7 , +.Xr KMSAN 9 , +.Xr malloc 9 , +.Xr memguard 9 , +.Xr redzone 9 , +.Xr uma 9 +.Sh HISTORY +.Nm +was ported from +.Nx +and first appeared in +.Fx 13.1 . +.Sh BUGS +Accesses to kernel memory outside of the kernel map are ignored by the +.Nm +runtime. +When +.Nm +is configured, the kernel memory allocators are configured to use the kernel +map, but some uses of the direct map remain. +For example, on amd64 and arm64, accesses to page table pages are not tracked. +.Pp +Some kernel memory allocators explicitly permit accesses after an object has +been freed. +These cannot be sanitized by +.Nm . +For example, memory from all +.Xr uma 9 +zones initialized with the +.Dv UMA_ZONE_NOFREE +flag are not sanitized. diff --git a/static/freebsd/man9/kern_reboot.9 b/static/freebsd/man9/kern_reboot.9 new file mode 100644 index 00000000..5ab17b89 --- /dev/null +++ b/static/freebsd/man9/kern_reboot.9 @@ -0,0 +1,293 @@ +.\" $NetBSD: boot.9,v 1.2 1996/09/24 07:01:26 ghudson Exp $ +.\" +.\" SPDX-License-Identifier: BSD-4-Clause +.\" +.\" Copyright (c) 1997 +.\" Mike Pritchard. All rights reserved. +.\" +.\" Copyright (c) 1994 Christopher G. Demetriou +.\" All rights reserved. +.\" +.\" Copyright (c) 2021,2023 The FreeBSD Foundation +.\" +.\" Portions of this documentation were written by Mitchell Horne +.\" under sponsorship from the FreeBSD Foundation. +.\" +.\" 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 Christopher G. Demetriou +.\" for the NetBSD Project. +.\" 4. 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 November 23, 2023 +.Dt REBOOT 9 +.Os +.Sh NAME +.Nm kern_reboot , +.Nm shutdown_nice +.Nd reboot, halt, or power off the system +.Sh SYNOPSIS +.In sys/types.h +.In sys/systm.h +.In sys/reboot.h +.Vt extern int rebooting; +.Ft void +.Fn kern_reboot "int howto" +.Ft void +.Fn shutdown_nice "int howto" +.In sys/eventhandler.h +.Fn EVENTHANDLER_REGISTER "shutdown_pre_sync" "shutdown_fn" "private" "priority" +.Fn EVENTHANDLER_REGISTER "shutdown_post_sync" "shutdown_fn" "private" "priority" +.Fn EVENTHANDLER_REGISTER "shutdown_final" "shutdown_fn" "private" "priority" +.Sh DESCRIPTION +The +.Fn kern_reboot +function handles final system shutdown, and either halts, reboots, +or powers down the system. +The exact action to be taken is determined by the flags passed in +.Fa howto . +.Pp +The relevant flags are: +.Bl -tag -compact -offset indent -width "RB_POWERCYCLE" +.It Dv RB_HALT +Halt the system in-place rather than restarting. +.It Dv RB_POWEROFF +Power down the system rather than restarting. +.It Dv RB_POWERCYCLE +Request a power-cycle in addition to restarting. +.It Dv RB_NOSYNC +Do not sync filesystems during shutdown. +.It Dv RB_DUMP +Dump kernel memory during shutdown. +.El +.Pp +The +.Fa howto +field, and its full list of flags are described in additional detail by +.Xr reboot 2 . +.Pp +.Fn kern_reboot +performs the following actions: +.Bl -enum -offset indent +.It +Set the +.Va rebooting +variable to +.Dv 1 , +indicating that the reboot process has begun and cannot be stopped. +.It +Unless the +.Dv RB_NOSYNC +flag is set in +.Fa howto , +sync and unmount the system's disks by calling +.Xr vfs_unmountall 9 . +.It +If rebooting after a panic +.Po +.Dv RB_DUMP +is set in +.Fa howto , +but +.Dv RB_HALT +is not set +.Pc , +initiate a system crash dump via +.Fn doadump . +.It +Print a message indicating that the system is about to be halted +or rebooted, and a report of the total system uptime. +.It +Execute all registered shutdown hooks. +See +.Sx SHUTDOWN HOOKS +below. +.It +As a last resort, if none of the shutdown hooks handled the reboot, call the +machine-dependent +.Fn cpu_reset +function. +In the unlikely case that this is not supported, +.Fn kern_reboot +will loop forever at the end of the function. +This requires a manual reset of the system. +.El +.Pp +.Fn kern_reboot +may be called from a typical kernel execution context, when the system is +running normally. +It may also be called as the final step of a kernel panic, or from the kernel +debugger. +Therefore, the code in this function is subject to restrictions described by +the +.Sx EXECUTION CONTEXT +section of the +.Xr panic 9 +man page. +.Pp +The +.Fn shutdown_nice +function is the intended path for performing a clean reboot or shutdown when +the system is operating under normal conditions. +Calling this function will send a signal to the +.Xr init 8 +process, instructing it to perform a shutdown. +When +.Xr init 8 +has cleanly terminated its children, it will perform the +.Xr reboot 2 +system call, which in turn calls +.Fn kern_reboot . +.Pp +If +.Fn shutdown_nice +is called before the +.Xr init 8 +process has been spawned, or if the system has panicked or otherwise halted, +.Fn kern_reboot +will be called directly. +.Sh SHUTDOWN HOOKS +The system defines three separate +.Xr EVENTHANDLER 9 +events, which are invoked successively during the shutdown procedure. +These are +.Va shutdown_pre_sync , +.Va shutdown_post_sync , +and +.Va shutdown_final . +They will be executed unconditionally in the listed order. +Handler functions registered to any of these events will receive the value of +.Fa howto +as their second argument, which may be used to decide what action to take. +.Pp +The +.Va shutdown_pre_sync +event is invoked before syncing filesystems to disk. +It enables any action or state transition that must happen before this point to +take place. +.Pp +The +.Va shutdown_post_sync +event is invoked at the point immediately after the filesystem sync has +finished. +It enables, for example, disk drivers to complete the sync by flushing their +cache to disk. +Note that this event still takes place before the optional kernel core dump. +.Pp +The +.Va shutdown_final +event is invoked as the very last step of +.Fn kern_reboot . +Drivers and subsystems such as +.Xr acpi 4 +can register handlers to this event that will perform the actual reboot, +power-off, or halt. +.Pp +Notably, the +.Va shutdown_final +event is also the point at which all kernel modules will have their shutdown +.Po +.Dv MOD_SHUTDOWN +.Pc +hooks executed, and when the +.Xr DEVICE_SHUTDOWN 9 +method will be executed recursively on all devices. +.Pp +All event handlers, like +.Fn kern_reboot +itself, may be run in either normal shutdown context or a kernel panic or +debugger context. +Handler functions are expected to take care not to trigger recursive panics. +.Sh RETURN VALUES +The +.Fn kern_reboot +function does not return. +.Pp +The +.Fn shutdown_nice +function will usually return to its caller, having initiated the asynchronous +system shutdown. +It will not return when called from a panic or debugger context, or during +early boot. +.Sh EXAMPLES +A hypothetical driver, foo(4), defines a +.Va shutdown_final +event handler that can handle system power-off by writing to a device register, +but it does not handle halt or reset. +.Bd -literal -offset indent +void +foo_poweroff_handler(struct void *arg, int howto) +{ + struct foo_softc *sc = arg; + uint32_t reg; + + if ((howto & RB_POWEROFF) != 0) { + reg = FOO_POWEROFF; + WRITE4(sc, FOO_POWEROFF_REG, reg); + } +} +.Ed +.Pp +The handler is then registered in the device attach routine: +.Bd -literal -offset indent +int +foo_attach(device_t dev) +{ + struct foo_softc *sc; + + ... + + /* Pass the device's software context as the private arg. */ + EVENTHANDLER_REGISTER(shutdown_final, foo_poweroff_handler, sc, + SHUTDOWN_PRI_DEFAULT); + + ... +} +.Ed +.Pp +This +.Va shutdown_final +handler uses the +.Dv RB_NOSYNC +flag to detect that a panic or other unusual condition has occurred, and +returns early: +.Bd -literal -offset indent +void +bar_shutdown_final(struct void *arg, int howto) +{ + + if ((howto & RB_NOSYNC) != 0) + return; + + /* Some code that is not panic-safe. */ + ... +} +.Ed +.Sh SEE ALSO +.Xr reboot 2 , +.Xr init 8 , +.Xr DEVICE_SHUTDOWN 9 , +.Xr EVENTHANDLER 9 , +.Xr module 9 , +.Xr panic 9 , +.Xr vfs_unmountall 9 diff --git a/static/freebsd/man9/kern_testfrwk.9 b/static/freebsd/man9/kern_testfrwk.9 new file mode 100644 index 00000000..0ae694da --- /dev/null +++ b/static/freebsd/man9/kern_testfrwk.9 @@ -0,0 +1,193 @@ +.\" +.\" Copyright (c) 2015 Netflix, Inc. +.\" +.\" 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 November 12, 2015 +.Dt KERN_TESTFRWK 9 +.Os +.Sh NAME +.Nm kern_testfrwk +.Nd A kernel testing framework +.Sh SYNOPSIS +kldload kern_testfrwk +.Sh DESCRIPTION +.\" This whole section is not written in manual page style and should be ripped +.\" out and replaced. -CEM +So what is this sys/tests directory in the kernel all about? +.Pp +Have you ever wanted to test a part of the +.Fx +kernel in some way and you +had no real way from user-land to make what you want to occur happen? +Say an error path or situation where locking occurs in a particular manner that +happens only once in a blue moon? +.Pp +If so, then the kernel test framework is just what you are looking for. +It is designed to help you create the situation you want. +.Pp +There are two components to the system: the test framework and your test. +This document will describe both components and use the test submitted with the +initial commit of this code to discuss the test +.Xr ( callout_test 4 ) . +All of the tests become kernel loadable modules. +The test you write should have a dependency on the test framework. +That way it will be loaded automatically with your test. +For example, you can see how to do this in the bottom of callout_test.c in +.Pa sys/tests/callout_test/callout_test.c . +.Pp +The framework itself is in +.Pa sys/tests/framework/kern_testfrwk.c . +Its job is to manage the tests that are loaded. +(More than one can be loaded.) +The idea is pretty simple; you load the test framework and then load your test. +.Pp +When your test loads, you register your tests with the kernel test framework. +You do that through a call to +.Fn kern_testframework_register . +Usually this is done at the module load event as shown below: +.Bd -literal -offset indent + switch (type) { + case MOD_LOAD: + err = kern_testframework_register("callout_test", + run_callout_test); +.Ed +.Pp +Here the test is "callout_test" and it is registered to run the function +.Fn run_callout_test +passing it a +.Fa struct kern_test *ptr . +The +.Vt kern_test +structure is defined in +.Pa kern_testfrwk.h . +.Bd -literal -offset indent +struct kern_test { + char name[TEST_NAME_LEN]; + int num_threads; /* Fill in how many threads you want */ + int tot_threads_running; /* Private to framework */ + uint8_t test_options[TEST_OPTION_SPACE]; +}; +.Ed +.Pp +The user sends this structure down via a sysctl to start your test. +He or she places the same name you registered ("callout_test" +in our example) in the +.Va name +field. +The user can also set the number of threads to run with +.Va num_threads . +.Pp +The framework will start the requested number of kernel threads, all running +your test at the same time. +The user does not specify anything in +.Va tot_threads_running ; +it is private to the framework. +As the framework calls each of your tests, it will set the +.Va tot_threads_running +to the index of the thread that your call is made from. +For example, if the user sets +.Va num_threads +to 2, then the function +.Fn run_callout_test +will be called once with +.Va tot_threads_running +to 0, and a second time with +.Va tot_threads_running +set to 1. +.Pp +The +.Va test_options +field is a test-specific set of information that is an opaque blob. +It is passed in from user space and has a maximum size of 256 bytes. +You can pass arbitrary test input in the space. +In the case of callout_test we reshape that to: +.Bd -literal -offset indent +struct callout_test { + int number_of_callouts; + int test_number; +}; +.Ed +.Pp +So the first lines of +.Fn run_callout_test +does the following to get at the user specific data: +.\" This is a bad example and violates strict aliasing. It should be replaced. +.Bd -literal -offset indent + struct callout_test *u; + size_t sz; + int i; + struct callout_run *rn; + int index = test->tot_threads_running; + + u = (struct callout_test *)test->test_options; +.Ed +.Pp +That way it can access: +.Va u->test_number +(there are two types of tests provided with this test) +and +.Va u->number_of_callouts +(how many simultaneous callouts to run). +.Pp +Your test can do anything with these bytes. +So the callout_test in question wants to create a situation where multiple +callouts are all run, that is the +.Va number_of_callouts , +and it tries to cancel the callout with the new +.Fn callout_async_drain . +The threads do this by acquiring the lock in question, and then +starting each of the callouts. +It waits for the callouts to all go off (the executor spins waits). +This forces the situation that the callouts have expired and are all waiting on +the lock that the executor holds. +After the callouts are all blocked, the executor calls +.Fn callout_async_drain +on each callout and releases the lock. +.Pp +.\" callout_test(4) specific documentation should probably be moved to its own +.\" page. +After all the callouts are done, a total status is printed +showing the results via +.Xr printf 9 . +The human tester can run +.Xr dmesg 8 +to see the results. +In this case it is expected that if you are running test 0, all the callouts +expire on the same CPU so only one callout_drain function would have been +called. +the number of zero_returns should match the number of callout_drains that were +called, i.e., 1. +The one_returns should be the remainder of the callouts. +If the test number was 1, the callouts were spread across all CPUs. +The number of zero_returns will again match the number of drain calls made +which matches the number of CPUs that were put in use. +.Pp +More than one thread can be used with this test, though in the example case it +is probably not necessary. +.Pp +You should not need to change the framework. +Just add tests and register them after loading. +.Sh AUTHORS +The kernel test framework was written by +.An Randall Stewart Aq Mt rrs@FreeBSD.org +with help from +.An John Mark Gurney Aq Mt jmg@FreeBSD.org . diff --git a/static/freebsd/man9/kern_yield.9 b/static/freebsd/man9/kern_yield.9 new file mode 100644 index 00000000..ba8d64a6 --- /dev/null +++ b/static/freebsd/man9/kern_yield.9 @@ -0,0 +1,134 @@ +.\" +.\" Copyright (c) 2023 The FreeBSD Foundation +.\" +.\" This documentation was written by Mitchell Horne under +.\" sponsorship from the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 30, 2023 +.Dt KERN_YIELD 9 +.Os +.Sh NAME +.Nm kern_yield , +.Nm maybe_yield , +.Nm should_yield +.Nd "functions for yielding execution of the current thread" +.Sh SYNOPSIS +.Ft void +.Fn kern_yield "int prio" +.Ft void +.Fn maybe_yield +.Ft bool +.Fn should_yield +.Sh DESCRIPTION +The +.Fn kern_yield +function causes the currently running thread to voluntarily, but +unconditionally, surrender its execution to the scheduler. +The +.Va prio +argument specifies the scheduling priority to be assigned before the context +switch, which has an influence on when execution will resume. +Note that the requested priority will take effect until the thread returns to +usermode, after which its base user priority will be restored. +Valid values for +.Va prio +are any of the +.Dv PRI_* +values defined in +.In sys/priority.h , +as well as the following special values: +.Bl -tag -width "PRI_UNCHANGED" +.It Dv PRI_USER +Schedule the thread with its base user priority; the value corresponding to +.Xr setpriority 2 / +.Xr nice 3 . +.It Dv PRI_UNCHANGED +Yield the thread without changing its priority. +.El +.Pp +The +.Fn should_yield +function checks if sufficient time has passed since the thread's last voluntary +context switch that yielding would be a useful service to other threads. +It returns +.Va true +when this is the case. +See +.Sx USAGE NOTES +for an elaboration of what this means. +.Pp +The +.Fn maybe_yield +function is a helper function for the common task of optionally yielding the +processor. +Internally, +.Fn kern_yield "PRI_USER" +will be called if +.Fn should_yield +returns +.Va true . +.Sh USAGE NOTES +Although the kernel supports preemption, this is usually reserved for +high-priority realtime or interrupt threads. +Kernel worker threads and timesharing threads are not guaranteed to preempt +each another. +Thus, threads executing in the kernel are expected to behave cooperatively +with respect to other threads in the system. +The yield functions are mostly intended to be used by threads which perform a +lot of work inside the kernel. +For example: +.Fn maybe_yield +is called by the +.Dv vlnru +process each time it reclaims a vnode. +.Pp +The scheduler aims to identify threads which monopolize the CPU, and will +schedule them with decreased priority. +Threads which regularly yield the processor will be given the chance to run +more often. +The possibly surprising effect of this is that, depending on the disposition of +other threads on the CPU's runqueue, a call to +.Fn kern_yield +does not guarantee that the yielding thread will be taken off the CPU. +.Pp +With the above considerations in mind, it is advised that code written using +.Fn kern_yield +be measured to confirm that its use has a positive effect on relevant +performance or responsiveness metrics. +Switching thread contexts has a non-zero cost, and thus yielding the processor +too eagerly could have a negative impact on performance. +.Pp +Additionally, since yielding is a cooperative action, it is advised that the +yielding thread release any locks that it may be holding, when possible. +Otherwise, threads which have been given the chance to run could end up waiting +on the yielding thread to release the lock, largely defeating the purpose of +the yield. +.Sh SEE ALSO +.Xr setpriority 2 , +.Xr nice 3 , +.Xr mi_switch 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Mitchell Horne Aq Mt mhorne@FreeBSD.org . diff --git a/static/freebsd/man9/kernacc.9 b/static/freebsd/man9/kernacc.9 new file mode 100644 index 00000000..9e48b01f --- /dev/null +++ b/static/freebsd/man9/kernacc.9 @@ -0,0 +1,81 @@ +.\" $NetBSD: access.9,v 1.1 1996/06/16 10:38:35 pk Exp $ +.\" +.\" Copyright (c) 1996 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Paul Kranenburg. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 REGENTS 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 June 16, 1996 +.Dt KERNACC 9 +.Os +.Sh NAME +.Nm kernacc , +.Nm useracc +.Nd check memory regions for accessibility +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.In vm/vm.h +.In vm/vm_extern.h +.Ft int +.Fn kernacc "void *addr" "int len" "int rw" +.Ft int +.Fn useracc "void *addr" "int len" "int rw" +.Sh DESCRIPTION +The +.Fn kernacc +and +.Fn useracc +functions check whether operations of the type specified in +.Fa rw +are permitted in the range of virtual addresses given by +.Fa addr +and +.Fa len . +The possible values of +.Fa rw +are any bitwise combination of +.Dv VM_PROT_READ , +.Dv VM_PROT_WRITE +and +.Dv VM_PROT_EXECUTE . +.Fn kernacc +checks addresses in the kernel address space, while +.Fn useracc +considers +.Fa addr +to represent an user space address. +The process context to use for this +operation is taken from the global variable +.Va curproc . +.Sh RETURN VALUES +Both functions return boolean true if the type of access specified +by +.Fa rw +is permitted. +Otherwise boolean false is returned. +.Sh BUGS +The process pointer should be passed in as an argument to +.Fn useracc . diff --git a/static/freebsd/man9/kernel_mount.9 b/static/freebsd/man9/kernel_mount.9 new file mode 100644 index 00000000..1f3ed02e --- /dev/null +++ b/static/freebsd/man9/kernel_mount.9 @@ -0,0 +1,186 @@ +.\" +.\" Copyright (c) 2004 Tom Rhodes +.\" 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 November 20, 2021 +.Dt KERNEL_MOUNT 9 +.Os +.Sh NAME +.Nm free_mntarg , +.Nm kernel_mount , +.Nm mount_arg , +.Nm mount_argb , +.Nm mount_argf , +.Nm mount_argsu +.Nd "functions provided as part of the kernel mount interface" +.Sh SYNOPSIS +.Ft void +.Fn free_mntarg "struct mntarg *ma" +.Ft int +.Fn kernel_mount "struct mntarg *ma" "int flags" +.Ft "struct mntarg *" +.Fo mount_arg +.Fa "struct mntarg *ma" "const char *name" "const void *val" "int len" +.Fc +.Ft "struct mntarg *" +.Fn mount_argb "struct mntarg *ma" "int flag" "const char *name" +.Ft "struct mntarg *" +.Fn mount_argf "struct mntarg *ma" "const char *name" "const char *fmt" ... +.Ft "struct mntarg *" +.Fo mount_argsu +.Fa "struct mntarg *ma" "const char *name" "const void *val" "int len" +.Fc +.Sh DESCRIPTION +The +.Fn kernel_mount +family of functions are provided as an API for building a list +of mount arguments which will be used to mount file systems +from inside the kernel. +By accumulating a list of arguments, the API takes shape and +provides the information necessary for the kernel to control +the +.Xr mount 8 +utility. +When an error occurs, the process will stop. +This will not cause a +.Xr panic 9 . +.Pp +The header of the structure is stored in +.Pa src/sys/kern/vfs_mount.c +which permits automatic structure creation to +ease the mount process. +Memory allocation must always be freed when the entire +process is complete, it is an error otherwise. +.Pp +The +.Fn free_mntarg +function is used to free or clear the +.Vt mntarg +structure. +.Pp +The +.Fn kernel_mount +function pulls information from the structure to perform +the mount request on a given file system. +Additionally, the +.Fn kernel_mount +function always calls the +.Fn free_mntarg +function. +If +.Fa ma +contains any error code generated during the construction, +that code will be called and the file system mount will +not be attempted. +.Pp +The +.Fn mount_arg +function takes a plain argument and crafts parts of +the structure with regards to various mount options. +If the length is a value less than 0, +.Xr strlen 3 +is used. +This argument will be referenced until either +.Fn free_mntarg +or +.Fn kernel_mount +is called. +.Pp +The +.Fn mount_argb +function is used to add boolean arguments to +the structure. +The +.Fa flag +is the boolean value and +.Fa name +must start with +.Qq Li no , +otherwise a panic will occur. +.Pp +The +.Fn mount_argf +function adds +.Xr printf 9 +style arguments to the current structure. +.Pp +The +.Fn mount_argsu +function will add arguments to the structure from a +userland string. +.Sh EXAMPLES +An example of the +.Fn *_cmount +function: +.Bd -literal +static int +msdosfs_cmount(struct mntarg *ma, void *data, int flags, struct thread *td) +{ + struct msdosfs_args args; + int error; + + if (data == NULL) + return (EINVAL); + error = copyin(data, &args, sizeof(args)); + if (error) + return (error); + + ma = mount_argsu(ma, "from", args.fspec, MAXPATHLEN); + ma = mount_arg(ma, "export", &args.export, sizeof(args.export)); + ma = mount_argf(ma, "uid", "%d", args.uid); + ma = mount_argf(ma, "gid", "%d", args.gid); + ma = mount_argf(ma, "mask", "%d", args.mask); + ma = mount_argf(ma, "dirmask", "%d", args.dirmask); + + ma = mount_argb(ma, args.flags & MSDOSFSMNT_SHORTNAME, "noshortname"); + ma = mount_argb(ma, args.flags & MSDOSFSMNT_LONGNAME, "nolongname"); + ma = mount_argb(ma, !(args.flags & MSDOSFSMNT_NOWIN95), "nowin95"); + ma = mount_argb(ma, args.flags & MSDOSFSMNT_KICONV, "nokiconv"); + + ma = mount_argsu(ma, "cs_win", args.cs_win, MAXCSLEN); + ma = mount_argsu(ma, "cs_dos", args.cs_dos, MAXCSLEN); + ma = mount_argsu(ma, "cs_local", args.cs_local, MAXCSLEN); + + error = kernel_mount(ma, flags); + + return (error); +} +.Ed +.Sh SEE ALSO +.Xr VFS 9 , +.Xr VFS_MOUNT 9 +.Sh HISTORY +The +.Fn kernel_mount +family of functions and this manual page first +appeared in +.Fx 6.0 . +.Sh AUTHORS +.An -nosplit +The +.Fn kernel_mount +family of functions and API was developed by +.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org . +This manual page was written by +.An Tom Rhodes Aq Mt trhodes@FreeBSD.org . diff --git a/static/freebsd/man9/khelp.9 b/static/freebsd/man9/khelp.9 new file mode 100644 index 00000000..d619f385 --- /dev/null +++ b/static/freebsd/man9/khelp.9 @@ -0,0 +1,435 @@ +.\" +.\" Copyright (c) 2010-2011 The FreeBSD Foundation +.\" +.\" This documentation was written at the Centre for Advanced Internet +.\" Architectures, Swinburne University of Technology, Melbourne, Australia by +.\" David Hayes and Lawrence Stewart under sponsorship from the FreeBSD +.\" Foundation. +.\" +.\" 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 October 1, 2024 +.Dt KHELP 9 +.Os +.Sh NAME +.Nm khelp , +.Nm khelp_init_osd , +.Nm khelp_destroy_osd , +.Nm khelp_get_id , +.Nm khelp_get_osd , +.Nm khelp_add_hhook , +.Nm khelp_remove_hhook , +.Nm KHELP_DECLARE_MOD , +.Nm KHELP_DECLARE_MOD_UMA +.Nd Kernel Helper Framework +.Sh SYNOPSIS +.In sys/khelp.h +.In sys/module_khelp.h +.Fn "int khelp_init_osd" "uint32_t classes" "struct osd *hosd" +.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" "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 +.Nm +provides a framework for managing +.Nm +modules, which indirectly use the +.Xr hhook 9 +KPI to register their hook functions with hook points of interest within the +kernel. +Khelp modules aim to provide a structured way to dynamically extend the kernel +at runtime in an ABI preserving manner. +Depending on the subsystem providing hook points, a +.Nm +module may be able to associate per-object data for maintaining relevant state +between hook calls. +The +.Xr hhook 9 +and +.Nm +frameworks are tightly integrated and anyone interested in +.Nm +should also read the +.Xr hhook 9 +manual page thoroughly. +.Ss Information for Khelp Module Implementors +.Nm +modules are represented within the +.Nm +framework by a +.Vt struct helper +which has the following members: +.Bd -literal -offset indent +struct helper { + int (*mod_init) (void); + int (*mod_destroy) (void); +#define HELPER_NAME_MAXLEN 16 + char h_name[HELPER_NAME_MAXLEN]; + uma_zone_t h_zone; + struct hookinfo *h_hooks; + uint32_t h_nhooks; + uint32_t h_classes; + int32_t h_id; + volatile uint32_t h_refcount; + uint16_t h_flags; + TAILQ_ENTRY(helper) h_next; +}; +.Ed +.Pp +Modules must instantiate a +.Vt struct helper , +but are only required to set the +.Va h_classes +field, and may optionally set the +.Va h_flags , +.Va mod_init +and +.Va mod_destroy +fields where required. +The framework takes care of all other fields and modules should refrain from +manipulating them. +Using the C99 designated initialiser feature to set fields is encouraged. +.Pp +If specified, the +.Va mod_init +function will be run by the +.Nm +framework prior to completing the registration process. +Returning a non-zero value from the +.Va mod_init +function will abort the registration process and fail to load the module. +If specified, the +.Va mod_destroy +function will be run by the +.Nm +framework during the deregistration process, after the module has been +deregistered by the +.Nm +framework. +The return value is currently ignored. +Valid +.Nm +classes are defined in +.In sys/khelp.h . +Valid flags are defined in +.In sys/module_khelp.h . +The HELPER_NEEDS_OSD flag should be set in the +.Va h_flags +field if the +.Nm +module requires persistent per-object data storage. +There is no programmatic way (yet) to check if a +.Nm +class provides the ability for +.Nm +modules to associate persistent per-object data, so a manual check is required. +.Pp +The +.Fn KHELP_DECLARE_MOD +and +.Fn KHELP_DECLARE_MOD_UMA +macros provide convenient wrappers around the +.Xr DECLARE_MODULE 9 +macro, and are used to register a +.Nm +module with the +.Nm +framework. +.Fn KHELP_DECLARE_MOD_UMA +should only be used by modules which require the use of persistent per-object +storage i.e. modules which set the HELPER_NEEDS_OSD flag in their +.Vt struct helper Ns 's +.Va h_flags +field. +.Pp +The first four arguments common to both macros are as follows. +The +.Fa hname +argument specifies the unique +.Xr ascii 7 +name for the +.Nm +module. +It should be no longer than HELPER_NAME_MAXLEN-1 characters in length. +The +.Fa hdata +argument is a pointer to the module's +.Vt struct helper . +The +.Fa hhooks +argument points to a static array of +.Vt struct hookinfo +structures. +The array should contain a +.Vt struct hookinfo +for each +.Xr hhook 9 +point the module wishes to hook, even when using the same hook function multiple +times for different +.Xr hhook 9 +points. +The +.Fa version +argument specifies a version number for the module which will be passed to +.Xr MODULE_VERSION 9 . +The +.Fn KHELP_DECLARE_MOD_UMA +macro takes the additional +.Fa ctor +and +.Fa dtor +arguments, which specify optional +.Xr uma 9 +constructor and destructor functions. +NULL should be passed where the functionality is not required. +.Pp +The +.Fn khelp_get_id +function returns the numeric identifier for the +.Nm +module with name +.Fa hname . +.Pp +The +.Fn khelp_get_osd +function is used to obtain the per-object data pointer for a specified +.Nm +module. +The +.Fa hosd +argument is a pointer to the underlying subsystem object's +.Vt struct osd . +This is provided by the +.Xr hhook 9 +framework when calling into a +.Nm +module's hook function. +The +.Fa id +argument specifies the numeric identifier for the +.Nm +module to extract the data pointer from +.Fa hosd +for. +The +.Fa id +is obtained using the +.Fn khelp_get_id +function. +.Pp +The +.Fn khelp_add_hhook +and +.Fn khelp_remove_hhook +functions allow a +.Nm +module to dynamically hook/unhook +.Xr hhook 9 +points at run time. +The +.Fa hki +argument specifies a pointer to a +.Vt struct hookinfo +which encapsulates the required information about the +.Xr hhook 9 +point and hook function being manipulated. +The HHOOK_WAITOK flag may be passed in via the +.Fa flags +argument of +.Fn khelp_add_hhook +if +.Xr malloc 9 +is allowed to sleep waiting for memory to become available. +.Ss Integrating Khelp Into a Kernel Subsystem +Most of the work required to allow +.Nm +modules to do useful things relates to defining and instantiating suitable +.Xr hhook 9 +points for +.Nm +modules to hook into. +The only additional decision a subsystem needs to make is whether it wants to +allow +.Nm +modules to associate persistent per-object data. +Providing support for persistent data storage can allow +.Nm +modules to perform more complex functionality which may be desirable. +Subsystems which want to allow Khelp modules to associate +persistent per-object data with one of the subsystem's data structures need to +make the following two key changes: +.Bl -bullet +.It +Embed a +.Vt struct osd +pointer in the structure definition for the object. +.It +Add calls to +.Fn khelp_init_osd +and +.Fn khelp_destroy_osd +to the subsystem code paths which are responsible for respectively initialising +and destroying the object. +.El +.Pp +The +.Fn khelp_init_osd +function initialises the per-object data storage for all currently loaded +.Nm +modules of appropriate classes which have set the HELPER_NEEDS_OSD flag in their +.Va h_flags +field. +The +.Fa classes +argument specifies a bitmask of +.Nm +classes which this subsystem associates with. +If a +.Nm +module matches any of the classes in the bitmask, that module will be associated +with the object. +The +.Fa hosd +argument specifies the pointer to the object's +.Vt struct osd +which will be used to provide the persistent storage for use by +.Nm +modules. +.Pp +The +.Fn khelp_destroy_osd +function frees all memory that was associated with an object's +.Vt struct osd +by a previous call to +.Fn khelp_init_osd . +The +.Fa hosd +argument specifies the pointer to the object's +.Vt struct osd +which will be purged in preparation for destruction. +.Sh IMPLEMENTATION NOTES +.Nm +modules are protected from being prematurely unloaded by a reference count. +The count is incremented each time a subsystem calls +.Fn khelp_init_osd +causing persistent storage to be allocated for the module, and decremented for +each corresponding call to +.Fn khelp_destroy_osd . +Only when a module's reference count has dropped to zero can the module be +unloaded. +.Sh RETURN VALUES +The +.Fn khelp_init_osd +function returns zero if no errors occurred. +It returns ENOMEM if a +.Nm +module which requires per-object storage fails to allocate the necessary memory. +.Pp +The +.Fn khelp_destroy_osd +function only returns zero to indicate that no errors occurred. +.Pp +The +.Fn khelp_get_id +function returns the unique numeric identifier for the registered +.Nm +module with name +.Fa hname . +It return -1 if no module with the specified name is currently registered. +.Pp +The +.Fn khelp_get_osd +function returns the pointer to the +.Nm +module's persistent object storage memory. +If the module identified by +.Fa id +does not have persistent object storage registered with the object's +.Fa hosd +.Vt struct osd , +NULL is returned. +.Pp +The +.Fn khelp_add_hhook +function returns zero if no errors occurred. +It returns ENOENT if it could not find the requested +.Xr hhook 9 +point. +It returns ENOMEM if +.Xr malloc 9 +failed to allocate memory. +It returns EEXIST if attempting to register the same hook function more than +once for the same +.Xr hhook 9 +point. +.Pp +The +.Fn khelp_remove_hhook +function returns zero if no errors occurred. +It returns ENOENT if it could not find the requested +.Xr hhook 9 +point. +.Sh EXAMPLES +A well commented example Khelp module can be found at: +.Pa /usr/share/examples/kld/khelp/h_example.c +.Pp +The Enhanced Round Trip Time (ERTT) +.Xr h_ertt 4 +.Nm +module provides a more complex example of what is possible. +.Sh SEE ALSO +.Xr h_ertt 4 , +.Xr hhook 9 , +.Xr osd 9 +.Sh ACKNOWLEDGEMENTS +Development and testing of this software were made possible in part by grants +from the FreeBSD Foundation and Cisco University Research Program Fund at +Community Foundation Silicon Valley. +.Sh HISTORY +The +.Nm +kernel helper framework first appeared in +.Fx 9.0 . +.Pp +The +.Nm +framework was first released in 2010 by Lawrence Stewart whilst studying at +Swinburne University of Technology's Centre for Advanced Internet Architectures, +Melbourne, Australia. +More details are available at: +.Pp +http://caia.swin.edu.au/urp/newtcp/ +.Sh AUTHORS +.An -nosplit +The +.Nm +framework was written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org . +.Pp +This manual page was written by +.An David Hayes Aq Mt david.hayes@ieee.org +and +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org . diff --git a/static/freebsd/man9/kmsan.9 b/static/freebsd/man9/kmsan.9 new file mode 100644 index 00000000..d9d279e1 --- /dev/null +++ b/static/freebsd/man9/kmsan.9 @@ -0,0 +1,357 @@ +.\"- +.\" Copyright (c) 2021 The FreeBSD Foundation +.\" +.\" This documentation was written by Mark Johnston under sponsorship from +.\" the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 11, 2024 +.Dt KMSAN 9 +.Os +.Sh NAME +.Nm KMSAN +.Nd Kernel Memory SANitizer +.Sh SYNOPSIS +The +.Pa GENERIC-KMSAN +kernel configuration can be used to compile a KMSAN-enabled kernel using +.Pa GENERIC +as a base configuration. +Alternately, to compile KMSAN into the kernel, place the following line in your +kernel configuration file: +.Bd -ragged -offset indent +.Cd "options KMSAN" +.Ed +.Pp +.In sys/msan.h +.Ft void +.Fn kmsan_mark "const void *addr" "size_t size" "uint8_t code" +.Ft void +.Fn kmsan_orig "const void *addr" "size_t size" "int type" "uintptr_t pc" +.Ft void +.Fn kmsan_check "const void *addr" "size_t size" "const char *descr" +.Ft void +.Fn kmsan_check_bio "const struct bio *" "const char *descr" +.Ft void +.Fn kmsan_check_ccb "const union ccb *" "const char *descr" +.Ft void +.Fn kmsan_check_mbuf "const struct mbuf *" "const char *descr" +.Ft void +.Fn kmsan_check_uio "const struct uio *" "const char *descr" +.Sh DESCRIPTION +.Nm +is a subsystem which leverages compiler instrumentation to detect uses of +uninitialized memory in the kernel. +Currently it is implemented only on the amd64 and arm64 platforms. +.Pp +When +.Nm +is compiled into the kernel, the compiler is configured to emit function +calls preceding memory accesses. +The functions are implemented by the +.Nm +runtime component and use hidden, byte-granular shadow state to determine +whether the source operand has been initialized. +When uninitialized memory is used as a source operand in certain operations, +such as control flow expressions or memory accesses, the runtime reports +an error. +Otherwise, the shadow state is propagated to destination operand. +For example, a +variable assignment or a +.Fn memcpy +call which copies uninitialized memory will cause the destination buffer or +variable to be marked uninitialized. +.Pp +To report an error, the +.Nm +runtime will either trigger a kernel panic or print a message to the console, +depending on the value of the +.Sy debug.kmsan.panic_on_violation +sysctl. +In both cases, a stack trace and information about the origin of the +uninitialized memory is included. +.Pp +In addition to compiler-detected uses of uninitialized memory, +various kernel I/O +.Dq exit points , +such as +.Xr copyout 9 , +perform validation of the input's shadow state and will raise an error if +any uninitialized bytes are detected. +.Pp +The +.Nm +option imposes a significant performance penalty. +Kernel code typically runs two or three times slower, and each byte mapped in +the kernel map requires two bytes of shadow state. +As a result, +.Nm +should be used only for kernel testing and development. +It is not recommended to enable +.Nm +in systems with less than 8GB of physical RAM. +.Pp +The sanitizer in a KMSAN-configured kernel can be disabled by setting the loader +tunable +.Sy debug.kmsan.disable=1 . +.Sh FUNCTIONS +The +.Fn kmsan_mark +and +.Fn kmsan_orig +functions update +.Nm +shadow state. +.Fn kmsan_mark +marks an address range as valid or invalid according to the value of the +.Va code +parameter. +The valid values for this parameter are +.Dv KMSAN_STATE_INITED +and +.Dv KMSAN_STATE_UNINIT , +which mark the range as initialized and uninitialized, respectively. +For example, when a piece of memory is freed to a kernel allocator, it will +typically have been marked initialized; before the memory is reused for a new +allocation, the allocator should mark it as uninitialized. +As another example, writes to host memory performed by devices, e.g., via DMA, +are not intercepted by the sanitizer; to avoid false positives, drivers should +mark device-written memory as initialized. +For many drivers this is handled internally by the +.Xr busdma 9 +subsystem. +.Pp +The +.Fn kmsan_orig +function updates +.Dq origin +shadow state. +In particular, it associates a given uninitialized buffer with a memory type +and code address. +This is used by the +.Nm +runtime to track the source of uninitialized memory and is only for debugging +purposes. +See +.Sx IMPLEMENTATION NOTES +for more details. +.Pp +The +.Fn kmsan_check +function and its sub-typed siblings validate the shadow state of the region(s) +of kernel memory passed as input parameters. +If any byte of the input is marked as uninitialized, the runtime will generate +a report. +These functions are useful during debugging, as they can be strategically +inserted into code paths to narrow down the source of uninitialized memory. +They are also used to perform validation in various kernel I/O paths, helping +ensure that, for example, packets transmitted over a network do not contain +uninitialized kernel memory. +.Fn kmsan_check +and related functions also take a +.Fa descr +parameter which is inserted into any reports raised by the check. +.Sh IMPLEMENTATION NOTES +.Ss Shadow Maps +The +.Nm +runtime makes use of two shadows of the kernel map. +Each address in the kernel map has a linear mapping to addresses in the +two shadows. +The first, simply called the shadow map, tracks the state of the corresponding +kernel memory. +A non-zero byte in the shadow map indicates that the corresponding byte of +kernel memory is uninitialized. +The +.Nm +instrumentation automatically propagates shadow state as the contents of kernel +memory are transformed and copied. +.Pp +The second shadow is called the origin map, and exists only to help debug +reports from the sanitizer. +To avoid false positives, +.Nm +does not raise reports for certain operations on uninitialized memory, such +as copying or arithmetic. +Thus, operations on uninitialized state which raise a report may be far removed +from the source of the bug, complicating debugging. +The origin map contains information which can help pinpoint the root cause of +a particular +.Nm +report; when generating a report, the runtime uses state from the origin map +to provide extra details. +.Pp +Unlike the shadow map, the origin map is not byte-granular, but consists of 4-byte +.Dq cells . +Each cell describes the corresponding four bytes of mapped kernel memory and +holds a type and compressed code address. +When kernel memory is allocated for some purpose, its origin is initialized +either by the compiler instrumentation or by runtime hooks in the allocator. +The type indicates the specific allocator, e.g., +.Xr uma 9 , +and the address provides the location in the kernel code where the memory was +allocated. +.Ss Assembly Code +When +.Nm +is configured, the compiler will only emit instrumentation for C code. +Files containing assembly code are left un-instrumented. +In some cases this is handled by the sanitizer runtime, which defines +wrappers for subroutines implemented in assembly. +These wrappers are referred to as interceptors and handle updating +shadow state to reflect the operations performed by the original +subroutines. +In other cases, C code which calls assembly code or is called from +assembly code may need to use +.Fn kmsan_mark +to manually update shadow state. +This is typically only necessary in machine-dependent code. +.Pp +Inline assembly is instrumented by the compiler to update shadow state +based on the output operands of the code, and thus does not usually +require any special handling to avoid false positives. +.Ss Interrupts and Exceptions +In addition to the shadow maps, the sanitizer requires some thread-local +storage (TLS) to track initialization and origin state for function +parameters and return values. +The sanitizer instrumentation will automatically fetch, update and +verify this state. +In particular, this storage block has a layout defined by the sanitizer +ABI. +.Pp +Most kernel code runs in a context where interrupts or exceptions may +redirect the CPU to begin execution of unrelated code. +To ensure that thread-local sanitizer state remains consistent, the +runtime maintains a stack of TLS blocks for each thread. +When machine-dependent interrupt and exception handlers begin execution, +they push a new entry onto the stack before calling into any C code, and +pop the stack before resuming execution of the interrupted code. +These operations are performed by the +.Fn kmsan_intr_enter +and +.Fn kmsan_intr_leave +functions in the sanitizer runtime. +.Sh EXAMPLES +The following contrived example demonstrates some of the types of bugs +that are automatically detected by +.Nm : +.Bd -literal -offset indent +int +f(size_t osz) +{ + struct { + uint32_t bar; + uint16_t baz; + /* A 2-byte hole is here. */ + } foo; + char *buf; + size_t sz; + int error; + + /* + * This will raise a report since "sz" is uninitialized + * here. If it is initialized, and "osz" was left uninitialized + * by the caller, a report would also be raised. + */ + if (sz < osz) + return (1); + + buf = malloc(32, M_TEMP, M_WAITOK); + + /* + * This will raise a report since "buf" has not been + * initialized and contains whatever data is left over from the + * previous use of that memory. + */ + for (i = 0; i < 32; i++) + if (buf[i] != '\0') + foo.bar++; + foo.baz = 0; + + /* + * This will raise a report since the pad bytes in "foo" have + * not been initialized, e.g., by memset(), and this call will + * thus copy uninitialized kernel stack memory into userspace. + */ + copyout(&foo, uaddr, sizeof(foo)); + + /* + * This line itself will not raise a report, but may trigger + * a report in the caller depending on how the return value is + * used. + */ + return (error); +} +.Ed +.Sh SEE ALSO +.Xr build 7 , +.Xr busdma 9 , +.Xr copyout 9 , +.Xr KASAN 9 , +.Xr uio 9 , +.Xr uma 9 +.Rs +.%A Evgeniy Stepanov +.%A Konstantin Serebryany +.%T MemorySanitizer: fast detector of uninitialized memory use in C++ +.%J 2015 IEEE/ACM International Symposium on Code Generation and Optimization (CGO) +.%D 2015 +.Re +.Sh HISTORY +.Nm +was ported from +.Nx +and first appeared in +.Fx 14.0 . +.Sh BUGS +Accesses to kernel memory outside of the kernel map are ignored by the +.Nm +runtime. +In particular, memory accesses via the direct map are not validated. +When memory is copied from outside the kernel map into the kernel map, +that region of the kernel map is marked as initialized. +When +.Nm +is configured, kernel memory allocators are configured to use the kernel map, +and filesystems are configured to always map data buffers into the kernel map, +so usage of the direct map is minimized. +However, some uses of the direct map remain. +This is a conservative policy which aims to avoid false positives, but it will +mask bug in some kernel subsystems. +.Pp +On amd64, global variables and the physical page array +.Va vm_page_array +are not sanitized. +This is intentional, as it reduces memory usage by avoiding creating +shadows of large regions of the kernel map. +However, this can allow bugs to go undetected by +.Nm . +.Pp +Some kernel memory allocators provide type-stable objects, and code which uses +them frequently depends on object data being preserved across allocations. +Such allocations cannot be sanitized by +.Nm . +However, in some cases it may be possible to use +.Fn kmsan_mark +to manually annotate fields which are known to contain invalid data upon +allocation. diff --git a/static/freebsd/man9/kobj.9 b/static/freebsd/man9/kobj.9 new file mode 100644 index 00000000..caa933da --- /dev/null +++ b/static/freebsd/man9/kobj.9 @@ -0,0 +1,154 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2000 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 November 14, 2011 +.Dt KOBJ 9 +.Os +.Sh NAME +.Nm kobj +.Nd a kernel object system for FreeBSD +.Sh SYNOPSIS +.In sys/param.h +.In sys/kobj.h +.Ft void +.Fn kobj_class_compile "kobj_class_t cls" +.Ft void +.Fn kobj_class_compile_static "kobj_class_t cls" "kobj_ops_t ops" +.Ft void +.Fn kobj_class_free "kobj_class_t cls" +.Ft kobj_t +.Fn kobj_create "kobj_class_t cls" "struct malloc_type *mtype" "int mflags" +.Ft void +.Fn kobj_init "kobj_t obj" "kobj_class_t cls" +.Ft void +.Fn kobj_init_static "kobj_t obj" "kobj_class_t cls" +.Ft void +.Fn kobj_delete "kobj_t obj" "struct malloc_type *mtype" +.Fn DEFINE_CLASS name "kobj_method_t *methods" "size_t size" +.Sh DESCRIPTION +The kernel object system implements an object-oriented programming +system in the +.Fx +kernel. +The system is based around the concepts of interfaces, which are +descriptions of sets of methods; classes, which are lists of functions +implementing certain methods from those interfaces; and objects, +which combine a class with a structure in memory. +.Pp +Methods are called using a dynamic method dispatching algorithm which +is designed to allow new interfaces and classes to be introduced into +the system at runtime. +The method dispatch algorithm is designed to be both fast and robust +and is only slightly more expensive than a direct function call, +making kernel objects suitable for performance-critical algorithms. +.Pp +Suitable uses for kernel objects are any algorithms which need some +kind of polymorphism (i.e., many different objects which can be treated +in a uniform way). +The common behaviour of the objects is described by a suitable +interface and each different type of object is implemented by a +suitable class. +.Pp +The simplest way to create a kernel object is to call +.Fn kobj_create +with a suitable class, malloc type and flags (see +.Xr malloc 9 +for a description of the malloc type and flags). +This will allocate memory for the object based on the object size +specified by the class and initialise it by zeroing the memory and +installing a pointer to the class' method dispatch table. +Objects created in this way should be freed by calling +.Fn kobj_delete . +.Pp +Clients which would like to manage the allocation of memory +themselves should call +.Fn kobj_init +or +.Fn kobj_init_static +with a pointer to the memory for the object and the class which +implements it. +It is also possible to use +.Fn kobj_init +and +.Fn kobj_init_static +to change the class for an object. +This should be done with care as the classes must agree on the layout +of the object. +The device framework uses this feature to associate drivers with +devices. +.Pp +The functions +.Fn kobj_class_compile , +.Fn kobj_class_compile_static +and +.Fn kobj_class_free +are used to process a class description to make method dispatching +efficient. +A client should not normally need to call these since a class +will automatically be compiled the first time it is used. +If a class is to be used before +.Xr malloc 9 +and +.Xr mutex 9 +are initialised, +then +.Fn kobj_class_compile_static +should be called with the class and a pointer to a statically +allocated +.Vt kobj_ops +structure before the class is used to initialise any objects. +In that case, also +.Fn kobj_init_static +should be used instead of +.Fn kobj_init . +.Pp +To define a class, first define a simple array of +.Vt kobj_method_t . +Each method which the class implements should be entered into the +table using the macro +.Fn KOBJMETHOD +which takes the name of the method (including its interface) and a +pointer to a function which implements it. +The table should be terminated with two zeros. +The macro +.Fn DEFINE_CLASS +can then be used to initialise a +.Vt kobj_class_t +structure. +The size argument to +.Fn DEFINE_CLASS +specifies how much memory should be allocated for each object. +.Sh HISTORY +Some of the concepts for this interface appeared in the device +framework used for the alpha port of +.Fx 3.0 +and more widely in +.Fx 4.0 . +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/kproc.9 b/static/freebsd/man9/kproc.9 new file mode 100644 index 00000000..14ee056c --- /dev/null +++ b/static/freebsd/man9/kproc.9 @@ -0,0 +1,393 @@ +.\" Copyright (c) 2000-2001 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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 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 October 19, 2007 +.Dt KPROC 9 +.Os +.Sh NAME +.Nm kproc_start , +.Nm kproc_shutdown , +.Nm kproc_create , +.Nm kproc_exit , +.Nm kproc_resume , +.Nm kproc_suspend , +.Nm kproc_suspend_check +.Nd "kernel processes" +.Sh SYNOPSIS +.In sys/kthread.h +.Ft void +.Fn kproc_start "const void *udata" +.Ft void +.Fn kproc_shutdown "void *arg" "int howto" +.Ft int +.Fo kproc_create +.Fa "void (*func)(void *)" "void *arg" "struct proc **newpp" +.Fa "int flags" "int pages" +.Fa "const char *fmt" ... +.Fc +.Ft void +.Fn kproc_exit "int ecode" +.Ft int +.Fn kproc_resume "struct proc *p" +.Ft int +.Fn kproc_suspend "struct proc *p" "int timo" +.Ft void +.Fn kproc_suspend_check "struct proc *p" +.Ft int +.Fo kproc_kthread_add +.Fa "void (*func)(void *)" "void *arg" +.Fa "struct proc **procptr" "struct thread **tdptr" +.Fa "int flags" "int pages" "char * procname" "const char *fmt" "..." +.Fc +.Sh DESCRIPTION +In +.Fx 8.0 , +the +.Fn kthread* 9 +family of functions was renamed to be the +.Fn kproc* 9 +family of functions, as they were misnamed +and actually produced kernel processes. +A new family of +.Em different +.Fn kthread_* 9 +functions was added to produce +.Em real +kernel +.Em threads . +See the +.Xr kthread 9 +man page for more information on those calls. +Also note that the +.Fn kproc_kthread_add 9 +function appears in both pages as its functionality is split. +.Pp +The function +.Fn kproc_start +is used to start +.Dq internal +daemons such as +.Nm bufdaemon , pagedaemon , vmdaemon , +and the +.Nm syncer +and is intended +to be called from +.Xr SYSINIT 9 . +The +.Fa udata +argument is actually a pointer to a +.Vt "struct kproc_desc" +which describes the kernel process that should be created: +.Bd -literal -offset indent +struct kproc_desc { + char *arg0; + void (*func)(void); + struct proc **global_procpp; +}; +.Ed +.Pp +The structure members are used by +.Fn kproc_start +as follows: +.Bl -tag -width ".Va global_procpp" -offset indent +.It Va arg0 +String to be used for the name of the process. +This string will be copied into the +.Va p_comm +member of the new process' +.Vt "struct proc" . +.It Va func +The main function for this kernel process to run. +.It Va global_procpp +A pointer to a +.Vt "struct proc" +pointer that should be updated to point to the newly created process' process +structure. +If this variable is +.Dv NULL , +then it is ignored. +.El +.Pp +The +.Fn kproc_create +function is used to create a kernel process. +The new process shares its address space with process 0, the +.Nm swapper +process, +and runs in kernel mode only. +The +.Fa func +argument specifies the function that the process should execute. +The +.Fa arg +argument is an arbitrary pointer that is passed in as the only argument to +.Fa func +when it is called by the new process. +The +.Fa newpp +pointer points to a +.Vt "struct proc" +pointer that is to be updated to point to the newly created process. +If this argument is +.Dv NULL , +then it is ignored. +The +.Fa flags +argument specifies a set of flags as described in +.Xr rfork 2 . +The +.Fa pages +argument specifies the size of the new kernel process's stack in pages. +If 0 is used, the default kernel stack size is allocated. +The rest of the arguments form a +.Xr printf 9 +argument list that is used to build the name of the new process and is stored +in the +.Va p_comm +member of the new process's +.Vt "struct proc" . +.Pp +The +.Fn kproc_exit +function is used to terminate kernel processes. +It should be called by the main function of the kernel process rather than +letting the main function return to its caller. +The +.Fa ecode +argument specifies the exit status of the process. +While exiting, the function +.Xr exit1 9 +will initiate a call to +.Xr wakeup 9 +on the process handle. +.Pp +The +.Fn kproc_resume , +.Fn kproc_suspend , +and +.Fn kproc_suspend_check +functions are used to suspend and resume a kernel process. +During the main loop of its execution, a kernel process that wishes to allow +itself to be suspended should call +.Fn kproc_suspend_check +passing in +.Va curproc +as the only argument. +This function checks to see if the kernel process has been asked to suspend. +If it has, it will +.Xr tsleep 9 +until it is told to resume. +Once it has been told to resume it will return allowing execution of the +kernel process to continue. +The other two functions are used to notify a kernel process of a suspend or +resume request. +The +.Fa p +argument points to the +.Vt "struct proc" +of the kernel process to suspend or resume. +For +.Fn kproc_suspend , +the +.Fa timo +argument specifies a timeout to wait for the kernel process to acknowledge the +suspend request and suspend itself. +.Pp +The +.Fn kproc_shutdown +function is meant to be registered as a shutdown event for kernel processes that +need to be suspended voluntarily during system shutdown so as not to interfere +with system shutdown activities. +The actual suspension of the kernel process is done with +.Fn kproc_suspend . +.Pp +The +.Fn kproc_kthread_add +function is much like the +.Fn kproc_create +function above except that if the kproc already exists, +then only a new thread (see +.Xr kthread 9 ) +is created on the existing process. +The +.Fa func +argument specifies the function that the process should execute. +The +.Fa arg +argument is an arbitrary pointer that is passed in as the only argument to +.Fa func +when it is called by the new process. +The +.Fa procptr +pointer points to a +.Vt "struct proc" +pointer that is the location to be updated with the new proc pointer +if a new process is created, or if not +.Dv NULL , +must contain the process pointer for the already existing process. +If this argument points to +.Dv NULL , +then a new process is created and the field updated. +If not NULL, the +.Fa tdptr +pointer points to a +.Vt "struct thread" +pointer that is the location to be updated with the new thread pointer. +The +.Fa flags +argument specifies a set of flags as described in +.Xr rfork 2 . +The +.Fa pages +argument specifies the size of the new kernel thread's stack in pages. +If 0 is used, the default kernel stack size is allocated. +The procname argument is the name the new process should be given if it needs to be created. +It is +.Em NOT +a printf style format specifier but a simple string. +The rest of the arguments form a +.Xr printf 9 +argument list that is used to build the name of the new thread and is stored +in the +.Va td_name +member of the new thread's +.Vt "struct thread" . +.Sh RETURN VALUES +The +.Fn kproc_create , +.Fn kproc_resume , +and +.Fn kproc_suspend +functions return zero on success and non-zero on failure. +.Sh EXAMPLES +This example demonstrates the use of a +.Vt "struct kproc_desc" +and the functions +.Fn kproc_start , +.Fn kproc_shutdown , +and +.Fn kproc_suspend_check +to run the +.Nm bufdaemon +process. +.Bd -literal -offset indent +static struct proc *bufdaemonproc; + +static struct kproc_desc buf_kp = { + "bufdaemon", + buf_daemon, + &bufdaemonproc +}; +SYSINIT(bufdaemon, SI_SUB_KTHREAD_BUF, SI_ORDER_FIRST, kproc_start, + &buf_kp) + +static void +buf_daemon() +{ + ... + /* + * This process needs to be suspended prior to shutdown sync. + */ + EVENTHANDLER_REGISTER(shutdown_pre_sync, kproc_shutdown, + bufdaemonproc, SHUTDOWN_PRI_LAST); + ... + for (;;) { + kproc_suspend_check(bufdaemonproc); + ... + } +} +.Ed +.Sh ERRORS +The +.Fn kproc_resume +and +.Fn kproc_suspend +functions will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa p +argument does not reference a kernel process. +.El +.Pp +The +.Fn kproc_create +function will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system-imposed limit on the total +number of processes under execution would be exceeded. +The limit is given by the +.Xr sysctl 3 +MIB variable +.Dv KERN_MAXPROC . +.It Bq Er EINVAL +The +.Dv RFCFDG +flag was specified in the +.Fa flags +parameter. +.El +.Sh SEE ALSO +.Xr rfork 2 , +.Xr exit1 9 , +.Xr kthread 9 , +.Xr SYSINIT 9 , +.Xr wakeup 9 +.Sh HISTORY +The +.Fn kproc_start +function first appeared in +.Fx 2.2 . +The +.Fn kproc_shutdown , +.Fn kproc_create , +.Fn kproc_exit , +.Fn kproc_resume , +.Fn kproc_suspend , +and +.Fn kproc_suspend_check +functions were introduced in +.Fx 4.0 . +Prior to +.Fx 5.0 , +the +.Fn kproc_shutdown , +.Fn kproc_resume , +.Fn kproc_suspend , +and +.Fn kproc_suspend_check +functions were named +.Fn shutdown_kproc , +.Fn resume_kproc , +.Fn shutdown_kproc , +and +.Fn kproc_suspend_loop , +respectively. +Originally they had the names +.Fn kthread_* +but were changed to +.Fn kproc_* +when real kthreads became available. diff --git a/static/freebsd/man9/kqueue.9 b/static/freebsd/man9/kqueue.9 new file mode 100644 index 00000000..bc735302 --- /dev/null +++ b/static/freebsd/man9/kqueue.9 @@ -0,0 +1,438 @@ +.\" Copyright 2006,2011 John-Mark Gurney +.\" 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 December 2, 2025 +.Dt KQUEUE 9 +.Os +.Sh NAME +.Nm kqueue_add_filteropts , kqueue_del_filteropts , +.Nm kqfd_register , +.Nm knote_fdclose , +.Nm knlist_init , knlist_init_mtx , +.Nm knlist_add , knlist_remove , knlist_empty , +.Nm knlist_clear , knlist_delete , knlist_destroy , +.Nm KNOTE_LOCKED , KNOTE_UNLOCKED +.Nd "event delivery subsystem" +.Sh SYNOPSIS +.In sys/event.h +.Ft int +.Fn kqueue_add_filteropts "int filt" "struct filterops *filtops" +.Ft int +.Fn kqueue_del_filteropts "int filt" +.Ft int +.Fn kqfd_register "int fd" "struct kevent *kev" "struct thread *td" "int waitok" +.Ft void +.Fn knote_fdclose "struct thread *td" "int fd" +.Ft void +.Fo knlist_init +.Fa "struct knlist *knl" +.Fa "void *lock" +.Fa "void \*[lp]*kl_lock\*[rp]\*[lp]void *\*[rp]" +.Fa "void \*[lp]*kl_unlock\*[rp]\*[lp]void *\*[rp]" +.Fa "int \*[lp]*kl_locked\*[rp]\*[lp]void *\*[rp]" +.Fc +.Ft void +.Fn knlist_init_mtx "struct knlist *knl" "struct mtx *lock" +.Ft void +.Fn knlist_add "struct knlist *knl" "struct knote *kn" "int islocked" +.Ft void +.Fn knlist_remove "struct knlist *knl" "struct knote *kn" "int islocked" +.Ft int +.Fn knlist_empty "struct knlist *knl" +.Ft void +.Fn knlist_clear "struct knlist *knl" "int islocked" +.Ft void +.Fn knlist_delete "struct knlist *knl" "struct thread *td" "int islocked" +.Ft void +.Fn knlist_destroy "struct knlist *knl" +.Ft void +.Fn KNOTE_LOCKED "struct knlist *knl" "long hint" +.Ft void +.Fn KNOTE_UNLOCKED "struct knlist *knl" "long hint" +.Sh DESCRIPTION +The functions +.Fn kqueue_add_filteropts +and +.Fn kqueue_del_filteropts +allow for the addition and removal of a filter type. +The filter is statically defined by the +.Dv EVFILT_* +macros. +The function +.Fn kqueue_add_filteropts +will make +.Fa filt +available. +The +.Vt "struct filterops" +has the following members: +.Bl -tag -width ".Va f_attach" +.It Va f_isfd +If +.Va f_isfd +is set, +.Va ident +in +.Vt "struct kevent" +is taken to be a file descriptor. +In this case, the +.Vt knote +passed into +.Va f_attach +will have the +.Va kn_fp +member initialized to the +.Vt "struct file *" +that represents the file descriptor. +.It Va f_attach +The +.Va f_attach +function will be called when attaching a +.Vt knote +to the object. +The method should call +.Fn knlist_add +to add the +.Vt knote +to the list that was initialized with +.Fn knlist_init . +The call to +.Fn knlist_add +is only necessary if the object can have multiple +.Vt knotes +associated with it. +If there is no +.Vt knlist +to call +.Fn knlist_add +with, the function +.Va f_attach +must clear the +.Dv KN_DETACHED +bit of +.Va kn_status +in the +.Vt knote . +The function shall return 0 on success, or appropriate error for the failure, +such as when the object is being destroyed, or does not exist. +During +.Va f_attach , +it is valid to change the +.Va kn_fop +pointer to a different pointer. +This will change the +.Va f_event +and +.Va f_detach +functions called when processing the +.Vt knote . +.It Va f_detach +The +.Va f_detach +function will be called to detach the +.Vt knote +if the +.Vt knote +has not already been detached by a call to +.Fn knlist_remove +or +.Fn knlist_delete . +The list +.Fa lock +will not be held when this function is called. +.It Va f_event +The +.Va f_event +function will be called to update the status of the +.Vt knote . +If the function returns 0, it will be assumed that the object is not +ready (or no longer ready) to be woken up. +The +.Fa hint +argument will be 0 when scanning +.Vt knotes +to see which are triggered. +Otherwise, the +.Fa hint +argument will be the value passed to either +.Dv KNOTE_LOCKED +or +.Dv KNOTE_UNLOCKED . +The +.Va kn_data +value should be updated as necessary to reflect the current value, such as +number of bytes available for reading, or buffer space available for writing. +.Pp +Locks +.Em must not +be acquired in +.Va f_event . +If a lock is required in +.Va f_event , +it must be obtained in the +.Fa kl_lock +function of the +.Vt knlist +that the +.Va knote +was added to. +.It Va f_copy +The +.Va f_copy +function is called to copy notes when the process forks. +When +.Dv NULL , +the current node is not duplicated to the child process. +Filter might set +.Dv f_copy +to +.Fn knote_triv_copy +if there is no additional handling required, besides shallow copying of the knote itself. +.El +.Pp +The function +.Fn kqfd_register +will register the +.Vt kevent +on the kqueue file descriptor +.Fa fd . +If it is safe to sleep, +.Fa waitok +should be set. +.Pp +The function +.Fn knote_fdclose +is used to delete all +.Vt knotes +associated with +.Fa fd . +Once returned, there will no longer be any +.Vt knotes +associated with the +.Fa fd . +The +.Vt knotes +removed will never be returned from a +.Xr kevent 2 +call, so if userland uses the +.Vt knote +to track resources, they will be leaked. +The +.Fn FILEDESC_LOCK +lock must be held over the call to +.Fn knote_fdclose +so that file descriptors cannot be added or removed. +.Pp +The +.Fn knlist_* +family of functions are for managing +.Vt knotes +associated with an object. +A +.Vt knlist +is not required, but is commonly used. +If used, the +.Vt knlist +must be initialized with either +.Fn knlist_init +or +.Fn knlist_init_mtx . +The +.Vt knlist +structure may be embedded into the object structure. +The +.Fa lock +will be held over +.Va f_event +calls. +.Pp +For the +.Fn knlist_init +function, if +.Fa lock +is +.Dv NULL , +a shared global lock will be used and the remaining arguments must be +.Dv NULL . +The function pointers +.Fa kl_lock , kl_unlock +and +.Fa kl_locked +will be used to manipulate the argument +.Fa lock . +If any of the function pointers are +.Dv NULL , +a function operating on +.Dv MTX_DEF +style +.Xr mutex 9 +locks will be used instead. +.Pp +The function +.Fn knlist_init_mtx +may be used to initialize a +.Vt knlist +when +.Fa lock +is a +.Dv MTX_DEF +style +.Xr mutex 9 +lock. +.Pp +The function +.Fn knlist_empty +returns true when there are no +.Vt knotes +on the list. +The function requires that the +.Fa lock +be held when called. +.Pp +The function +.Fn knlist_clear +removes all +.Vt knotes +from the list. +The +.Fa islocked +argument declares if the +.Fa lock +has been acquired. +All +.Vt knotes +will have +.Dv EV_ONESHOT +set so that the +.Vt knote +will be returned and removed during the next scan. +The +.Va f_detach +function will be called when the +.Vt knote +is deleted during the next scan. +.Pp +The function +.Fn knlist_delete +removes and deletes all +.Vt knotes +on the list. +The function +.Va f_detach +will not be called, and the +.Vt knote +will not be returned on the next scan. +Using this function could leak userland resources if a process uses the +.Vt knote +to track resources. +.Pp +Both the +.Fn knlist_clear +and +.Fn knlist_delete +functions may sleep. +They also may release the +.Fa lock +to wait for other +.Vt knotes +to drain. +.Pp +The +.Fn knlist_destroy +function is used to destroy a +.Vt knlist . +There must be no +.Vt knotes +associated with the +.Vt knlist +.Po Fn knlist_empty +returns true +.Pc +and no more +.Vt knotes +may be attached to the object. +A +.Vt knlist +may be emptied by calling +.Fn knlist_clear +or +.Fn knlist_delete . +.Pp +The macros +.Fn KNOTE_LOCKED +and +.Fn KNOTE_UNLOCKED +are used to notify +.Vt knotes +about events associated with the object. +It will iterate over all +.Vt knotes +on the list calling the +.Va f_event +function associated with the +.Vt knote . +The macro +.Fn KNOTE_LOCKED +must be used if the lock associated with the +.Fa knl +is held. +The function +.Fn KNOTE_UNLOCKED +will acquire the lock before iterating over the list of +.Vt knotes . +.Sh RETURN VALUES +The function +.Fn kqueue_add_filteropts +will return zero on success, +.Er EINVAL +in the case of an invalid +.Fa filt , +or +.Er EEXIST +if the filter has already been installed. +.Pp +The function +.Fn kqueue_del_filteropts +will return zero on success, +.Er EINVAL +in the case of an invalid +.Fa filt , +or +.Er EBUSY +if the filter is still in use. +.Pp +The function +.Fn kqfd_register +will return zero on success, +.Er EBADF +if the file descriptor is not a kqueue, or any of the possible values returned +by +.Xr kevent 2 . +.Sh SEE ALSO +.Xr kevent 2 , +.Xr kqueue 2 +.Sh AUTHORS +This +manual page was written by +.An John-Mark Gurney Aq Mt jmg@FreeBSD.org . diff --git a/static/freebsd/man9/kstack_contains.9 b/static/freebsd/man9/kstack_contains.9 new file mode 100644 index 00000000..9e0c22bf --- /dev/null +++ b/static/freebsd/man9/kstack_contains.9 @@ -0,0 +1,60 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2023 Joseph Koshy +.\" +.\" 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 May 2, 2023 +.Dt KSTACK_CONTAINS 9 +.Os +.Sh NAME +.Nm kstack_contains +.Nd determine if an address range lies within the kernel stack for a thread +.Sh SYNOPSIS +.In machine/stack.h +.Ft bool +.Fn kstack_contains "struct thread *td" "vm_offset_t va" "size_t len" +.Sh DESCRIPTION +This function can be used to determine whether a given address range +falls within the kernel stack for the thread pointed to by +.Fa td . +.Sh RETURN VALUES +The function +.Fn kstack_contains +returns +.Dv true +if the range of addresses +.Bo +.Fa va Ns .. Ns ( +.Fa va Ns + Ns +.Fa len Ns - Ns 1 ) +.Bc +(both addresses inclusive) lies within the kernel stack for the thread +pointed to by argument +.Fa td , +or returns +.Dv false +otherwise. +.Sh ERRORS +This function does not return an error. +.Sh SEE ALSO +.Xr kproc 9 , +.Xr kthread 9 diff --git a/static/freebsd/man9/kthread.9 b/static/freebsd/man9/kthread.9 new file mode 100644 index 00000000..266faa03 --- /dev/null +++ b/static/freebsd/man9/kthread.9 @@ -0,0 +1,347 @@ +.\" Copyright (c) 2000-2001 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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 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 July 15, 2014 +.Dt KTHREAD 9 +.Os +.Sh NAME +.Nm kthread_start , +.Nm kthread_shutdown , +.Nm kthread_add , +.Nm kthread_exit , +.Nm kthread_resume , +.Nm kthread_suspend , +.Nm kthread_suspend_check +.Nd "kernel threads" +.Sh SYNOPSIS +.In sys/kthread.h +.Ft void +.Fn kthread_start "const void *udata" +.Ft void +.Fn kthread_shutdown "void *arg" "int howto" +.Ft void +.Fn kthread_exit "void" +.Ft int +.Fn kthread_resume "struct thread *td" +.Ft int +.Fn kthread_suspend "struct thread *td" "int timo" +.Ft void +.Fn kthread_suspend_check "void" +.In sys/unistd.h +.Ft int +.Fo kthread_add +.Fa "void (*func)(void *)" "void *arg" "struct proc *procp" +.Fa "struct thread **newtdpp" "int flags" "int pages" +.Fa "const char *fmt" ... +.Fc +.Ft int +.Fo kproc_kthread_add +.Fa "void (*func)(void *)" "void *arg" +.Fa "struct proc **procptr" "struct thread **tdptr" +.Fa "int flags" "int pages" "char * procname" "const char *fmt" "..." +.Fc +.Sh DESCRIPTION +In +.Fx 8.0 , +the older family of +.Fn kthread_* 9 +functions was renamed to be the +.Fn kproc_* 9 +family of functions, +as they were previously misnamed +and actually produced kernel processes. +This new family of +.Fn kthread_* 9 +functions was added to produce +.Em real +kernel threads. +See the +.Xr kproc 9 +man page for more information on the renamed calls. +Also note that the +.Fn kproc_kthread_add 9 +function appears in both pages as its functionality is split. +.Pp +The function +.Fn kthread_start +is used to start +.Dq internal +daemons such as +.Nm bufdaemon , pagedaemon , vmdaemon , +and the +.Nm syncer +and is intended +to be called from +.Xr SYSINIT 9 . +The +.Fa udata +argument is actually a pointer to a +.Vt "struct kthread_desc" +which describes the kernel thread that should be created: +.Bd -literal -offset indent +struct kthread_desc { + char *arg0; + void (*func)(void); + struct thread **global_threadpp; +}; +.Ed +.Pp +The structure members are used by +.Fn kthread_start +as follows: +.Bl -tag -width ".Va global_threadpp" -offset indent +.It Va arg0 +String to be used for the name of the thread. +This string will be copied into the +.Va td_name +member of the new threads' +.Vt "struct thread" . +.It Va func +The main function for this kernel thread to run. +.It Va global_threadpp +A pointer to a +.Vt "struct thread" +pointer that should be updated to point to the newly created thread's +.Vt thread +structure. +If this variable is +.Dv NULL , +then it is ignored. +The thread will be a subthread of +.Va proc0 +(PID 0). +.El +.Pp +The +.Fn kthread_add +function is used to create a kernel thread. +The new thread runs in kernel mode only. +It is added to the process specified by the +.Fa procp +argument, or if that is +.Dv NULL , +to +.Va proc0 . +The +.Fa func +argument specifies the function that the thread should execute. +The +.Fa arg +argument is an arbitrary pointer that is passed in as the only argument to +.Fa func +when it is called by the new thread. +The +.Fa newtdpp +pointer points to a +.Vt "struct thread" +pointer that is to be updated to point to the newly created thread. +If this argument is +.Dv NULL , +then it is ignored. +The +.Fa flags +argument may be set to +.Dv RFSTOPPED +to leave the thread in a stopped state. +The caller must call +.Fn sched_add +to start the thread. +The +.Fa pages +argument specifies the size of the new kernel thread's stack in pages. +If 0 is used, the default kernel stack size is allocated. +The rest of the arguments form a +.Xr printf 9 +argument list that is used to build the name of the new thread and is stored +in the +.Va td_name +member of the new thread's +.Vt "struct thread" . +.Pp +The +.Fn kproc_kthread_add +function is much like the +.Fn kthread_add +function above except that if the kproc does not already +exist, it is created. +This function is better documented in the +.Xr kproc 9 +manual page. +.Pp +The +.Fn kthread_exit +function is used to terminate kernel threads. +It should be called by the main function of the kernel thread rather than +letting the main function return to its caller. +.\" XXX "int ecode" argument isn't documented. +.Pp +The +.Fn kthread_resume , +.Fn kthread_suspend , +and +.Fn kthread_suspend_check +functions are used to suspend and resume a kernel thread. +During the main loop of its execution, a kernel thread that wishes to allow +itself to be suspended should call +.Fn kthread_suspend_check +in order to check if the it has been asked to suspend. +If it has, it will +.Xr msleep 9 +until it is told to resume. +Once it has been told to resume it will return allowing execution of the +kernel thread to continue. +The other two functions are used to notify a kernel thread of a suspend or +resume request. +The +.Fa td +argument points to the +.Vt "struct thread" +of the kernel thread to suspend or resume. +For +.Fn kthread_suspend , +the +.Fa timo +argument specifies a timeout to wait for the kernel thread to acknowledge the +suspend request and suspend itself. +.Pp +The +.Fn kthread_shutdown +function is meant to be registered as a shutdown event for kernel threads that +need to be suspended voluntarily during system shutdown so as not to interfere +with system shutdown activities. +The actual suspension of the kernel thread is done with +.Fn kthread_suspend . +.Sh RETURN VALUES +The +.Fn kthread_add , +.Fn kthread_resume , +and +.Fn kthread_suspend +functions return zero on success and non-zero on failure. +.Sh EXAMPLES +This example demonstrates the use of a +.Vt "struct kthread_desc" +and the functions +.Fn kthread_start , +.Fn kthread_shutdown , +and +.Fn kthread_suspend_check +to run the +.Nm bufdaemon +process. +.Bd -literal -offset indent +static struct thread *bufdaemonthread; + +static struct kthread_desc buf_kp = { + "bufdaemon", + buf_daemon, + &bufdaemonthread +}; +SYSINIT(bufdaemon, SI_SUB_KTHREAD_BUF, SI_ORDER_FIRST, kthread_start, + &buf_kp) + +static void +buf_daemon() +{ + ... + /* + * This process needs to be suspended prior to shutdown sync. + */ + EVENTHANDLER_REGISTER(shutdown_pre_sync, kthread_shutdown, + bufdaemonthread, SHUTDOWN_PRI_LAST); + ... + for (;;) { + kthread_suspend_check(); + ... + } +} +.Ed +.Sh ERRORS +The +.Fn kthread_resume +and +.Fn kthread_suspend +functions will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa td +argument does not reference a kernel thread. +.El +.Pp +The +.Fn kthread_add +function will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Memory for a thread's stack could not be allocated. +.El +.Sh SEE ALSO +.Xr kproc 9 , +.Xr SYSINIT 9 , +.Xr wakeup 9 +.Sh HISTORY +The +.Fn kthread_start +function first appeared in +.Fx 2.2 +where it created a whole process. +It was converted to create threads in +.Fx 8.0 . +The +.Fn kthread_shutdown , +.Fn kthread_exit , +.Fn kthread_resume , +.Fn kthread_suspend , +and +.Fn kthread_suspend_check +functions were introduced in +.Fx 4.0 +and were converted to threads in +.Fx 8.0 . +The +.Fn kthread_create +call was renamed to +.Fn kthread_add +in +.Fx 8.0 . +The old functionality of creating a kernel process was renamed +to +.Xr kproc_create 9 . +Prior to +.Fx 5.0 , +the +.Fn kthread_shutdown , +.Fn kthread_resume , +.Fn kthread_suspend , +and +.Fn kthread_suspend_check +functions were named +.Fn shutdown_kproc , +.Fn resume_kproc , +.Fn shutdown_kproc , +and +.Fn kproc_suspend_loop , +respectively. diff --git a/static/freebsd/man9/ktr.9 b/static/freebsd/man9/ktr.9 new file mode 100644 index 00000000..6910fcd5 --- /dev/null +++ b/static/freebsd/man9/ktr.9 @@ -0,0 +1,170 @@ +.\" Copyright (c) 2001 John H. Baldwin +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 12, 2022 +.Dt KTR 9 +.Os +.Sh NAME +.Nm CTR0 , CTR1 , CTR2 , CTR3 , CTR4 , CTR5 +.Nd kernel tracing facility +.Sh SYNOPSIS +.In sys/param.h +.In sys/ktr.h +.Vt "extern int ktr_cpumask" ; +.Vt "extern int ktr_entries" ; +.Vt "extern int ktr_extend" ; +.Vt "extern int ktr_mask" ; +.Vt "extern int ktr_verbose" ; +.Vt "extern struct ktr_entry ktr_buf[]" ; +.Ft void +.Fn CTR "u_int mask" "char *format" "..." +.Ft void +.Fn CTR0 "u_int mask" "char *format" +.Ft void +.Fn CTR1 "u_int mask" "char *format" "arg1" +.Ft void +.Fn CTR2 "u_int mask" "char *format" "arg1" "arg2" +.Ft void +.Fn CTR3 "u_int mask" "char *format" "arg1" "arg2" "arg3" +.Ft void +.Fn CTR4 "u_int mask" "char *format" "arg1" "arg2" "arg3" "arg4" +.Ft void +.Fn CTR5 "u_int mask" "char *format" "arg1" "arg2" "arg3" "arg4" "arg5" +.Ft void +.Fn CTR6 "u_int mask" "char *format" "arg1" "arg2" "arg3" "arg4" "arg5" "arg6" +.Sh DESCRIPTION +KTR provides a circular buffer of events that can be logged in a +.Xr printf 9 +style +fashion. +These events can then be dumped with +.Xr ddb 4 , +.Xr gdb 1 Pq Pa ports/devel/gdb +or +.Xr ktrdump 8 . +.Pp +Events are created and logged in the kernel via the +.Dv CTR +and +.Dv CTR Ns Ar x +macros. +The first parameter is a mask of event types +.Pq Dv KTR_* +defined in +.In sys/ktr_class.h . +The event will be logged only if any of the event types specified in +.Fa mask +are enabled in the global event mask stored in +.Va ktr_mask . +The +.Fa format +argument is a +.Xr printf 9 +style format string used to build the text of the event log message. +Following the +.Fa format +string are zero to six arguments referenced by +.Fa format . +Each event is logged with a file name and source line number of the +originating CTR call, and a timestamp in addition to the log message. +.Pp +The event is stored in the circular buffer with supplied arguments as is, +and formatting is done at the dump time. +Do not use pointers to the objects with limited lifetime, for instance, +strings, because the pointer may become invalid when buffer is printed. +.Pp +The +.Dv CTR Ns Ar x +macros differ only in the number of arguments each +one takes, as indicated by its name. +.Pp +The +.Va ktr_entries +variable contains the number of entries in the +.Va ktr_buf +array. +These variables are mostly useful for post-mortem crash dump tools to locate +the base of the circular trace buffer and its length. +.Pp +The +.Va ktr_mask +variable contains the run time mask of events to log. +.Pp +The CPU event mask is stored in the +.Va ktr_cpumask +variable. +.Pp +The +.Va ktr_verbose +variable stores the verbose flag that controls whether events are logged to +the console in addition to the event buffer. +.Sh EXAMPLES +This example demonstrates the use of tracepoints at the +.Dv KTR_PROC +logging level. +.Bd -literal +void +mi_switch() +{ + ... + /* + * Pick a new current process and record its start time. + */ + ... + CTR3(KTR_PROC, "mi_switch: old proc %p (pid %d)", p, p->p_pid); + ... + cpu_switch(); + ... + CTR3(KTR_PROC, "mi_switch: new proc %p (pid %d)", p, p->p_pid); + ... +} +.Ed +.Sh SEE ALSO +.Xr ktr 4 , +.Xr ktrdump 8 +.Sh HISTORY +The KTR kernel tracing facility first appeared in +.Bsx 3.0 +and was imported into +.Fx 5.0 . +.Pp +The +.Fn CTR +macro accepting a variable number of arguments first appeared in +.Fx 14.0 . +.Sh BUGS +Currently there is one global buffer shared among all CPUs. +It might be profitable at some point in time to use per-CPU buffers instead +so that if one CPU halts or starts spinning, then the log messages it +emitted just prior to halting or spinning will not be drowned out by events +from the other CPUs. +.Pp +The arguments given in +.Fn CTRx +macros are stored as +.Vt u_long , +so do not pass arguments larger than size of an +.Vt u_long +type. +For example passing 64bit arguments on 32bit architectures will give incorrect +results. diff --git a/static/freebsd/man9/lock.9 b/static/freebsd/man9/lock.9 new file mode 100644 index 00000000..9cff6e3b --- /dev/null +++ b/static/freebsd/man9/lock.9 @@ -0,0 +1,473 @@ +.\" +.\" Copyright (C) 2002 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 June 21, 2024 +.Dt LOCK 9 +.Os +.Sh NAME +.Nm lockinit , +.Nm lockdestroy , +.Nm lockmgr , +.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" +.Sh SYNOPSIS +.In sys/types.h +.In sys/lock.h +.In sys/lockmgr.h +.Ft void +.Fn lockinit "struct lock *lkp" "int prio" "const char *wmesg" "int timo" "int flags" +.Ft void +.Fn lockdestroy "struct lock *lkp" +.Ft int +.Fn lockmgr "struct lock *lkp" "u_int flags" "struct mtx *ilk" +.Ft int +.Fn lockmgr_args "struct lock *lkp" "u_int flags" "struct mtx *ilk" "const char *wmesg" "int prio" "int timo" +.Ft int +.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 +.Fn lockmgr_recursed "const struct lock *lkp" +.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" +.Cd "options INVARIANT_SUPPORT" +.Ft void +.Fn lockmgr_assert "const struct lock *lkp" "int what" +.Sh DESCRIPTION +The +.Fn lockinit +function is used to initialize a lock. +It must be called before any operation can be performed on a lock. +Its arguments are: +.Bl -tag -width ".Fa wmesg" +.It Fa lkp +A pointer to the lock to initialize. +.It Fa prio +The priority passed to +.Xr sleep 9 . +.It Fa wmesg +The lock message. +This is used for both debugging output and +.Xr sleep 9 . +.It Fa timo +The timeout value passed to +.Xr sleep 9 . +.It Fa flags +The flags the lock is to be initialized with: +.Bl -tag -width ".Dv LK_CANRECURSE" +.It Dv LK_CANRECURSE +Allow recursive exclusive locks. +.It Dv LK_NOPROFILE +Disable lock profiling for this lock. +.It Dv LK_NOSHARE +Allow exclusive locks only. +.It Dv LK_NOWITNESS +Instruct +.Xr witness 4 +to ignore this lock. +.It Dv LK_NODUP +.Xr witness 4 +should log messages about duplicate locks being acquired. +.It Dv LK_QUIET +Disable +.Xr ktr 4 +logging for this lock. +.El +.El +.Pp +The +.Fn lockdestroy +function is used to destroy a lock, and while it is called in a number of +places in the kernel, it currently does nothing. +.Pp +The +.Fn lockmgr +and +.Fn lockmgr_rw +functions handle general locking functionality within the kernel, including +support for shared and exclusive locks, and recursion. +.Fn lockmgr +and +.Fn lockmgr_rw +are also able to upgrade and downgrade locks. +.Pp +Their arguments are: +.Bl -tag -width ".Fa flags" +.It Fa lkp +A pointer to the lock to manipulate. +.It Fa flags +Flags indicating what action is to be taken. +.Bl -tag -width ".Dv LK_NODDLKTREAT" +.It Dv LK_SHARED +Acquire a shared lock. +If an exclusive lock is currently held, +.Dv EDEADLK +will be returned. +.It Dv LK_EXCLUSIVE +Acquire an exclusive lock. +If an exclusive lock is already held, and +.Dv LK_CANRECURSE +is not set, the system will +.Xr panic 9 . +.It Dv LK_DOWNGRADE +Downgrade exclusive lock to a shared lock. +Downgrading a shared lock is not permitted. +If an exclusive lock has been recursed, the system will +.Xr panic 9 . +.It Dv LK_UPGRADE +Upgrade a shared lock to an exclusive lock. +If this call fails, the shared lock is lost, even if the +.Dv LK_NOWAIT +flag is specified. +During the upgrade, the shared lock could +be temporarily dropped. +Attempts to upgrade an exclusive lock will cause a +.Xr panic 9 . +.It Dv LK_TRYUPGRADE +Try to upgrade a shared lock to an exclusive lock. +The failure to upgrade does not result in the dropping +of the shared lock ownership. +.It Dv LK_RELEASE +Release the lock. +Releasing a lock that is not held can cause a +.Xr panic 9 . +.It Dv LK_DRAIN +Wait for all activity on the lock to end, then mark it decommissioned. +This is used before freeing a lock that is part of a piece of memory that is +about to be freed. +(As documented in +.In sys/lockmgr.h . ) +.It Dv LK_SLEEPFAIL +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 +checks for this instance. +.It Dv LK_CANRECURSE +Allow recursion on an exclusive lock. +For every lock there must be a release. +.It Dv LK_INTERLOCK +Unlock the interlock (which should be locked already). +.It Dv LK_NODDLKTREAT +Normally, +.Fn lockmgr +postpones serving further shared requests for shared-locked lock if there is +exclusive waiter, to avoid exclusive lock starvation. +But, if the thread requesting the shared lock already owns a shared lockmgr +lock, the request is granted even in presence of the parallel exclusive lock +request, which is done to avoid deadlocks with recursive shared acquisition. +.Pp +The +.Dv LK_NODDLKTREAT +flag can only be used by code which requests shared non-recursive lock. +The flag allows exclusive requests to preempt the current shared request +even if the current thread owns shared locks. +This is safe since shared lock is guaranteed to not recurse, and is used +when thread is known to held unrelated shared locks, to not cause +unnecessary starvation. +An example is +.Dv vp +locking in VFS +.Xr lookup 9 , +when +.Dv dvp +is already locked. +.El +.It Fa ilk +An interlock mutex for controlling group access to the lock. +If +.Dv LK_INTERLOCK +is specified, +.Fn lockmgr +and +.Fn lockmgr_rw +assume +.Fa ilk +is currently owned and not recursed, and will return it unlocked. +See +.Xr mtx_assert 9 . +.El +.Pp +The +.Fn lockmgr_args +and +.Fn lockmgr_args_rw +function work like +.Fn lockmgr +and +.Fn lockmgr_rw +but accepting a +.Fa wmesg , +.Fa timo +and +.Fa prio +on a per-instance basis. +The specified values will override the default +ones, but this can still be used passing, respectively, +.Dv LK_WMESG_DEFAULT , +.Dv LK_PRIO_DEFAULT +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 +.Xr VOP_PRINT 9 +functions. +.Pp +The +.Fn lockmgr_recursed +function returns true if the lock is recursed, 0 +otherwise. +.Pp +The +.Fn lockstatus +function returns the status of the lock in relation to the current thread. +.Pp +When compiled with +.Cd "options INVARIANTS" +and +.Cd "options INVARIANT_SUPPORT" , +the +.Fn lockmgr_assert +function tests +.Fa lkp +for the assertions specified in +.Fa what , +and panics if they are not met. +One of the following assertions must be specified: +.Bl -tag -width ".Dv KA_UNLOCKED" +.It Dv KA_LOCKED +Assert that the current thread has either a shared or an exclusive lock on the +.Vt lkp +lock pointed to by the first argument. +.It Dv KA_SLOCKED +Assert that the current thread has a shared lock on the +.Vt lkp +lock pointed to by the first argument. +.It Dv KA_XLOCKED +Assert that the current thread has an exclusive lock on the +.Vt lkp +lock pointed to by the first argument. +.It Dv KA_UNLOCKED +Assert that the current thread has no lock on the +.Vt lkp +lock pointed to by the first argument. +.El +.Pp +In addition, one of the following optional assertions can be used with +either an +.Dv KA_LOCKED , +.Dv KA_SLOCKED , +or +.Dv KA_XLOCKED +assertion: +.Bl -tag -width ".Dv KA_NOTRECURSED" +.It Dv KA_RECURSED +Assert that the current thread has a recursed lock on +.Fa lkp . +.It Dv KA_NOTRECURSED +Assert that the current thread does not have a recursed lock on +.Fa lkp . +.El +.Sh RETURN VALUES +The +.Fn lockmgr +and +.Fn lockmgr_rw +functions return 0 on success and non-zero on failure. +.Pp +The +.Fn lockstatus +function returns: +.Bl -tag -width ".Dv LK_EXCLUSIVE" +.It Dv LK_EXCLUSIVE +An exclusive lock is held by the current thread. +.It Dv LK_EXCLOTHER +An exclusive lock is held by someone other than the current thread. +.It Dv LK_SHARED +A shared lock is held. +.It Li 0 +The lock is not held by anyone. +.El +.Sh ERRORS +.Fn lockmgr +and +.Fn lockmgr_rw +fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +.Dv LK_FORCEUPGRADE +was requested and another thread had already requested a lock upgrade. +.It Bq Er EBUSY +.Dv LK_NOWAIT +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 +.Fn lockmgr +or +.Fn lockmgr_rw +did sleep. +.It Bq Er EINTR +.Dv PCATCH +was set in the lock priority, and a signal was delivered during a sleep. +Note the +.Er ERESTART +error below. +.It Bq Er ERESTART +.Dv PCATCH +was set in the lock priority, a signal was delivered during a sleep, +and the system call is to be restarted. +.It Bq Er EWOULDBLOCK +a non-zero timeout was given, and the timeout expired. +.El +.Sh LOCKS +If +.Dv LK_INTERLOCK +is passed in the +.Fa flags +argument to +.Fn lockmgr +or +.Fn lockmgr_rw , +the +.Fa ilk +must be held prior to calling +.Fn lockmgr +or +.Fn lockmgr_rw , +and will be returned unlocked. +.Pp +Upgrade attempts that fail result in the loss of the lock that +is currently held. +Also, it is invalid to upgrade an +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 , +.Xr mutex 9 , +.Xr panic 9 , +.Xr rwlock 9 , +.Xr sleep 9 , +.Xr sx 9 , +.Xr VOP_PRINT 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/locking.9 b/static/freebsd/man9/locking.9 new file mode 100644 index 00000000..ad044b6e --- /dev/null +++ b/static/freebsd/man9/locking.9 @@ -0,0 +1,437 @@ +.\" Copyright (c) 2007 Julian Elischer (julian - freebsd 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 December 28, 2025 +.Dt LOCKING 9 +.Os +.Sh NAME +.Nm locking +.Nd kernel synchronization primitives +.Sh DESCRIPTION +The +.Em FreeBSD +kernel is written to run across multiple CPUs and as such provides +several different synchronization primitives to allow developers +to safely access and manipulate many data types. +.Ss Mutexes +Mutexes (also called "blocking mutexes") are the most commonly used +synchronization primitive in the kernel. +A thread acquires (locks) a mutex before accessing data shared with other +threads (including interrupt threads), and releases (unlocks) it afterwards. +If the mutex cannot be acquired, the thread requesting it will wait. +Mutexes are adaptive by default, meaning that +if the owner of a contended mutex is currently running on another CPU, +then a thread attempting to acquire the mutex will spin rather than yielding +the processor. +Mutexes fully support priority propagation. +.Pp +See +.Xr mutex 9 +for details. +.Ss Spin Mutexes +Spin mutexes are a variation of basic mutexes; the main difference between +the two is that spin mutexes never block. +Instead, they spin while waiting for the lock to be released. +To avoid deadlock, a thread that holds a spin mutex must never yield its CPU. +Unlike ordinary mutexes, spin mutexes disable interrupts when acquired. +Since disabling interrupts can be expensive, they are generally slower to +acquire and release. +Spin mutexes should be used only when absolutely necessary, +e.g. to protect data shared +with interrupt filter code (see +.Xr bus_setup_intr 9 +for details), +or for scheduler internals. +.Ss Mutex Pools +With most synchronization primitives, such as mutexes, the programmer must +provide memory to hold the primitive. +For example, a mutex may be embedded inside the structure it protects. +Mutex pools provide a preallocated set of mutexes to avoid this +requirement. +Note that mutexes from a pool may only be used as leaf locks. +.Pp +See +.Xr mtx_pool 9 +for details. +.Ss Reader/Writer Locks +Reader/writer locks allow shared access to protected data by multiple threads +or exclusive access by a single thread. +The threads with shared access are known as +.Em readers +since they should only read the protected data. +A thread with exclusive access is known as a +.Em writer +since it may modify protected data. +.Pp +Reader/writer locks can be treated as mutexes (see above and +.Xr mutex 9 ) +with shared/exclusive semantics. +Reader/writer locks support priority propagation like mutexes, +but priority is propagated only to an exclusive holder. +This limitation comes from the fact that shared owners +are anonymous. +.Pp +See +.Xr rwlock 9 +for details. +.Ss Read-Mostly Locks +Read-mostly locks are similar to +.Em reader/writer +locks but optimized for very infrequent write locking. +.Em Read-mostly +locks implement full priority propagation by tracking shared owners +using a caller-supplied +.Em tracker +data structure. +.Pp +See +.Xr rmlock 9 +for details. +.Ss Sleepable Read-Mostly Locks +Sleepable read-mostly locks are a variation on read-mostly locks. +Threads holding an exclusive lock may sleep, +but threads holding a shared lock may not. +Priority is propagated to shared owners but not to exclusive owners. +.Ss Shared/exclusive locks +Shared/exclusive locks are similar to reader/writer locks; the main difference +between them is that shared/exclusive locks may be held during unbounded sleep. +Acquiring a contested shared/exclusive lock can perform an unbounded sleep. +These locks do not support priority propagation. +.Pp +See +.Xr sx 9 +for details. +.Ss Lockmanager locks +Lockmanager locks are sleepable shared/exclusive locks used mostly in +.Xr VFS 9 +.Po +as a +.Xr vnode 9 +lock +.Pc +and in the buffer cache +.Po +.Xr BUF_LOCK 9 +.Pc . +They have features other lock types do not have such as sleep +timeouts, blocking upgrades, +writer starvation avoidance, draining, and an interlock mutex, +but this makes them complicated both to use and to implement; +for this reason, they should be avoided. +.Pp +See +.Xr lock 9 +for details. +.Ss Non-blocking synchronization +The kernel has two facilities, +.Xr epoch 9 +and +.Xr smr 9 , +which can be used to provide read-only access to a data structure while one or +more writers are concurrently modifying the data structure. +Specifically, readers using +.Xr epoch 9 +and +.Xr smr 9 +to synchronize accesses do not block writers, in contrast with reader/writer +locks, and they help ensure that memory freed by writers is not reused until +all readers which may be accessing it have finished. +Thus, they are a useful building block in the construction of lock-free +data structures. +.Pp +These facilities are difficult to use correctly and should be avoided +in preference to traditional mutual exclusion-based synchronization, +except when performance or non-blocking guarantees are a major concern. +.Pp +See +.Xr epoch 9 +and +.Xr smr 9 +for details. +.Ss Counting semaphores +Counting semaphores provide a mechanism for synchronizing access +to a pool of resources. +Unlike mutexes, semaphores do not have the concept of an owner, +so they can be useful in situations where one thread needs +to acquire a resource, and another thread needs to release it. +They are largely deprecated. +.Pp +See +.Xr sema 9 +for details. +.Ss Condition variables +Condition variables are used in conjunction with locks to wait for +a condition to become true. +A thread must hold the associated lock before calling one of the +.Fn cv_wait , +functions. +When a thread waits on a condition, the lock +is atomically released before the thread yields the processor +and reacquired before the function call returns. +Condition variables may be used with blocking mutexes, +reader/writer locks, read-mostly locks, and shared/exclusive locks. +.Pp +See +.Xr condvar 9 +for details. +.Ss Sleep/Wakeup +The functions +.Fn tsleep , +.Fn msleep , +.Fn msleep_spin , +.Fn pause , +.Fn wakeup , +and +.Fn wakeup_one +also handle event-based thread blocking. +Unlike condition variables, +arbitrary addresses may be used as wait channels and a dedicated +structure does not need to be allocated. +However, care must be taken to ensure that wait channel addresses are +unique to an event. +If a thread must wait for an external event, it is put to sleep by +.Fn tsleep , +.Fn msleep , +.Fn msleep_spin , +or +.Fn pause . +Threads may also wait using one of the locking primitive sleep routines +.Xr mtx_sleep 9 , +.Xr rw_sleep 9 , +or +.Xr sx_sleep 9 . +.Pp +The parameter +.Fa chan +is an arbitrary address that uniquely identifies the event on which +the thread is being put to sleep. +All threads sleeping on a single +.Fa chan +are woken up later by +.Fn wakeup +.Pq often called from inside an interrupt routine +to indicate that the +event the thread was blocking on has occurred. +.Pp +Several of the sleep functions including +.Fn msleep , +.Fn msleep_spin , +and the locking primitive sleep routines specify an additional lock +parameter. +The lock will be released before sleeping and reacquired +before the sleep routine returns. +If +.Fa priority +includes the +.Dv PDROP +flag, then the lock will not be reacquired before returning. +The lock is used to ensure that a condition can be checked atomically, +and that the current thread can be suspended without missing a +change to the condition or an associated wakeup. +In addition, all of the sleep routines will fully drop the +.Va Giant +mutex +.Pq even if recursed +while the thread is suspended and will reacquire the +.Va Giant +mutex +.Pq restoring any recursion +before the function returns. +.Pp +The +.Fn pause +function is a special sleep function that waits for a specified +amount of time to pass before the thread resumes execution. +This sleep cannot be terminated early by either an explicit +.Fn wakeup +or a signal. +.Pp +See +.Xr sleep 9 +for details. +.Ss Giant +Giant is a special mutex used to protect data structures that do not +yet have their own locks. +Since it provides semantics akin to the old +.Xr spl 9 +interface, +Giant has special characteristics: +.Bl -enum +.It +It is recursive. +.It +Drivers can request that Giant be locked around them +by not marking themselves MPSAFE. +Note that infrastructure to do this is slowly going away as non-MPSAFE +drivers either became properly locked or disappear. +.It +Giant must be locked before other non-sleepable locks. +.It +Giant is dropped during unbounded sleeps and reacquired after wakeup. +.It +There are places in the kernel that drop Giant and pick it back up +again. +Sleep locks will do this before sleeping. +Parts of the network or VM code may do this as well. +This means that you cannot count on Giant keeping other code from +running if your code sleeps, even if you want it to. +.El +.Sh INTERACTIONS +The primitives can interact and have a number of rules regarding how +they can and can not be combined. +Many of these rules are checked by +.Xr witness 4 . +.Ss Bounded vs. Unbounded Sleep +In a bounded sleep +.Po also referred to as +.Dq blocking +.Pc +the only resource needed to resume execution of a thread +is CPU time for the owner of a lock that the thread is waiting to acquire. +In an unbounded sleep +.Po +often referred to as simply +.Dq sleeping +.Pc +a thread waits for an external event or for a condition +to become true. +In particular, +a dependency chain of threads in bounded sleeps should always make forward +progress, +since there is always CPU time available. +This requires that no thread in a bounded sleep is waiting for a lock held +by a thread in an unbounded sleep. +To avoid priority inversions, +a thread in a bounded sleep lends its priority to the owner of the lock +that it is waiting for. +.Pp +The following primitives perform bounded sleeps: +mutexes, reader/writer locks and read-mostly locks. +.Pp +The following primitives perform unbounded sleeps: +sleepable read-mostly locks, shared/exclusive locks, lockmanager locks, +counting semaphores, condition variables, and sleep/wakeup. +.Ss General Principles +.Bl -bullet +.It +It is an error to do any operation that could result in yielding the processor +while holding a spin mutex. +.It +It is an error to do any operation that could result in unbounded sleep +while holding any primitive from the 'bounded sleep' group. +For example, it is an error to try to acquire a shared/exclusive lock while +holding a mutex, or to try to allocate memory with M_WAITOK while holding a +reader/writer lock. +.Pp +Note that the lock passed to one of the +.Fn sleep +or +.Fn cv_wait +functions is dropped before the thread enters the unbounded sleep and does +not violate this rule. +.It +It is an error to do any operation that could result in yielding of +the processor when running inside an interrupt filter. +.It +It is an error to do any operation that could result in unbounded sleep when +running inside an interrupt thread. +.El +.Ss Interaction table +The following table shows what you can and can not do while holding +one of the locking primitives discussed. +Note that +.Dq sleep +includes +.Fn sema_wait , +.Fn sema_timedwait , +any of the +.Fn cv_wait +functions, +and any of the +.Fn sleep +functions. +.Bl -column " You want:" "spin mtx " "mutex/rw " "rmlock " "sleep rm " "sx/lk " -offset 3n +.It Em " You want:" Ta spin mtx Ta mutex/rw Ta rmlock Ta sleep rm Ta sx/lk Ta sleep +.It Em "You have:" Ta -------- Ta -------- Ta ------ Ta -------- Ta ----- Ta ------ +.It spin mtx Ta \&ok Ta \&no Ta \&no Ta \&no Ta \&no Ta \&no-1 +.It mutex/rw Ta \&ok Ta \&ok Ta \&ok Ta \&no Ta \&no Ta \&no-1 +.It rmlock Ta \&ok Ta \&ok Ta \&ok Ta \&no Ta \&no Ta \&no-1 +.It sleep rm Ta \&ok Ta \&ok Ta \&ok Ta \&ok-2 Ta \&ok-2 Ta \&ok-2/3 +.It sx Ta \&ok Ta \&ok Ta \&ok Ta \&ok Ta \&ok Ta \&ok-3 +.It lockmgr Ta \&ok Ta \&ok Ta \&ok Ta \&ok Ta \&ok Ta \&ok +.El +.Pp +.Em *1 +There are calls that atomically release this primitive when going to sleep +and reacquire it on wakeup +.Po +.Fn mtx_sleep , +.Fn rw_sleep , +.Fn msleep_spin , +etc. +.Pc . +.Pp +.Em *2 +These cases are only allowed while holding a write lock on a sleepable +read-mostly lock. +.Pp +.Em *3 +Though one can sleep while holding this lock, +one can also use a +.Fn sleep +function to atomically release this primitive when going to sleep and +reacquire it on wakeup. +.Pp +Note that non-blocking try operations on locks are always permitted. +.Ss Context mode table +The next table shows what can be used in different contexts. +At this time this is a rather easy to remember table. +.Bl -column "interrupt filter: " "spin mtx " "mutex/rw " "rmlock " "sleep rm " "sx/lk " -offset 3n +.It Em "Context:" Ta spin mtx Ta mutex/rw Ta rmlock Ta sleep rm Ta sx/lk Ta sleep +.It interrupt filter: Ta \&ok Ta \&no Ta \&no Ta \&no Ta \&no Ta \&no +.It interrupt thread: Ta \&ok Ta \&ok Ta \&ok Ta \&no Ta \&no Ta \&no +.It callout: Ta \&ok Ta \&ok Ta \&ok Ta \&no Ta \&no Ta \&no +.It direct callout: Ta \&ok Ta \&no Ta \&no Ta \&no Ta \&no Ta \&no +.It system call: Ta \&ok Ta \&ok Ta \&ok Ta \&ok Ta \&ok Ta \&ok +.El +.Sh SEE ALSO +.Xr lockstat 1 , +.Xr witness 4 , +.Xr atomic 9 , +.Xr BUS_SETUP_INTR 9 , +.Xr callout 9 , +.Xr condvar 9 , +.Xr epoch 9 , +.Xr lock 9 , +.Xr LOCK_PROFILING 9 , +.Xr mtx_pool 9 , +.Xr mutex 9 , +.Xr rmlock 9 , +.Xr rwlock 9 , +.Xr sema 9 , +.Xr sleep 9 , +.Xr smr 9 , +.Xr sx 9 +.Sh BUGS +There are too many locking primitives to choose from. diff --git a/static/freebsd/man9/mac.9 b/static/freebsd/man9/mac.9 new file mode 100644 index 00000000..98a455e4 --- /dev/null +++ b/static/freebsd/man9/mac.9 @@ -0,0 +1,222 @@ +.\"- +.\" Copyright (c) 1999-2002 Robert N. M. Watson +.\" Copyright (c) 2002-2004 Networks Associates Technology, Inc. +.\" All rights reserved. +.\" +.\" This software was developed by Robert Watson for the TrustedBSD Project. +.\" +.\" This software was developed for the FreeBSD Project in part by Network +.\" Associates Laboratories, the Security Research Division of Network +.\" Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 +.\" ("CBOSS"), as part of the DARPA CHATS research program. +.\" +.\" 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 May 20, 2021 +.Dt MAC 9 +.Os +.Sh NAME +.Nm mac +.Nd TrustedBSD Mandatory Access Control framework +.Sh SYNOPSIS +.In sys/types.h +.In sys/mac.h +.Pp +In the kernel configuration file: +.Cd "options MAC" +.Cd "options MAC_DEBUG" +.Sh DESCRIPTION +.Ss Introduction +The +.Tn TrustedBSD +mandatory access control framework permits dynamically +introduced system security modules to modify system security functionality. +This can be used to support a variety of new security services, including +traditional labeled mandatory access control models. +The framework provides a series of entry points which must be called by +code supporting various kernel services, especially with respects to access +control points and object creation. +The framework then calls out to security modules to offer them the +opportunity to modify security behavior at those MAC API entry points. +Both consumers of the API (normal kernel services) and security modules +must be aware of the semantics of the API calls, particularly with respect +to synchronization primitives (such as locking). +.Ss Kernel Objects Supported by the Framework +The MAC framework manages labels on a variety of types of in-kernel +objects, including process credentials, vnodes, devfs_dirents, mount +points, sockets, mbufs, bpf descriptors, network interfaces, IP fragment +queues, and pipes. +Label data on kernel objects, represented by +.Vt "struct label" , +is policy-unaware, and may be used in the manner seen fit by policy modules. +.Ss API for Consumers +The MAC API provides a large set of entry points, too broad to specifically +document here. +In general, these entry points represent an access control check or other +MAC-relevant operations, accept one or more subjects (credentials) +authorizing the activity, a set of objects on which the operation +is to be performed, and a set of operation arguments providing information +about the type of operation being requested. +.Ss Locking for Consumers +Consumers of the MAC API must be aware of the locking requirements for +each API entry point: generally, appropriate locks must be held over each +subject or object being passed into the call, so that MAC modules may +make use of various aspects of the object for access control purposes. +For example, vnode locks are frequently required in order that the MAC +framework and modules may retrieve security labels and attributes from the +vnodes for the purposes of access control. +Similarly, the caller must be aware of the reference counting semantics +of any subject or object passed into the MAC API: all calls require that +a valid reference to the object be held for the duration of the +(potentially lengthy) MAC API call. +Under some circumstances, objects must be held in either a shared or +exclusive manner. +.Ss API for Module Writers +Each module exports a structure describing the MAC API operations that +the module chooses to implement, including initialization and destruction +API entry points, a variety of object creation and destruction calls, +and a large set of access control check points. +In the future, additional audit entry points will also be present. +Module authors may choose to only implement a subset of the entry points, +setting API function pointers in the description structure to +.Dv NULL , +permitting the framework to avoid calling into the module. +.Ss Locking for Module Writers +Module writers must be aware of the locking semantics of entry points +that they implement: MAC API entry points will have specific locking +or reference counting semantics for each argument, and modules must follow +the locking and reference counting protocol or risk a variety of failure +modes (including race conditions, inappropriate pointer dereferences, +etc). +.Pp +MAC module writers must also be aware that MAC API entry points will +frequently be invoked from deep in a kernel stack, and as such must be +careful to avoid violating more global locking requirements, such as +global lock order requirements. +For example, it may be inappropriate to lock additional objects not +specifically maintained and ordered by the policy module, or the +policy module might violate a global ordering requirement relating +to those additional objects. +.Pp +Finally, MAC API module implementors must be careful to avoid +inappropriately calling back into the MAC framework: the framework +makes use of locking to prevent inconsistencies during policy module +attachment and detachment. +MAC API modules should avoid producing scenarios in which deadlocks +or inconsistencies might occur. +.Ss Adding New MAC Entry Points +The MAC API is intended to be easily expandable as new services are +added to the kernel. +In order that policies may be guaranteed the opportunity to ubiquitously +protect system subjects and objects, it is important that kernel +developers maintain awareness of when security checks or relevant +subject or object operations occur in newly written or modified kernel +code. +New entry points must be carefully documented so as to prevent any +confusion regarding lock orders and semantics. +Introducing new entry points requires four distinct pieces of work: +introducing new MAC API entries reflecting the operation arguments, +scattering these MAC API entry points throughout the new or modified +kernel service, extending the front-end implementation of the MAC API +framework, and modifying appropriate modules to take advantage of +the new entry points so that they may consistently enforce their +policies. +.Sh ENTRY POINTS +System service and module authors should reference the +.%T "FreeBSD Architecture Handbook" +for information on the MAC Framework APIs. +.Sh SEE ALSO +.Xr acl 3 , +.Xr mac 3 , +.Xr posix1e 3 , +.Xr mac 4 , +.Xr ucred 9 , +.Xr vaccess 9 , +.Xr vaccess_acl_posix1e 9 , +.Xr VFS 9 , +.Xr VOP_SETLABEL 9 +.Rs +.%T "The FreeBSD Architecture Handbook" +.%U "https://docs.freebsd.org/en/books/arch-handbook/" +.Re +.Sh HISTORY +The +.Tn TrustedBSD +MAC Framework first appeared in +.Fx 5.0 . +.Sh AUTHORS +This manual page was written by +.An Robert Watson . +This software was contributed to the +.Fx +Project by Network Associates Laboratories, the Security Research +Division of Network Associates Inc.\& under DARPA/SPAWAR contract +N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +.An -nosplit +The +.Tn TrustedBSD +MAC Framework was designed by +.An Robert Watson , +and implemented by the Network Associates Laboratories Network Security +(NETSEC), Secure Execution Environment (SEE), and Adaptive +Network Defense research groups. +Network Associates Laboratory staff contributing to the CBOSS Project +include (in alphabetical order): +.An Lee Badger , +.An Brian Feldman , +.An Hrishikesh Dandekar , +.An Tim Fraser , +.An Doug Kilpatrick , +.An Suresh Krishnaswamy , +.An Adam Migus , +.An Wayne Morrison , +.An Andrew Reisse , +.An Chris Vance , +and +.An Robert Watson . +.Pp +Sub-contracted staff include: +.An Chris Costello , +.An Poul-Henning Kamp , +.An Jonathan Lemon , +.An Kirk McKusick , +.An Dag-Erling Sm\(/orgrav . +.Pp +Additional contributors include: +.An Pawel Dawidek , +.An Chris Faulhaber , +.An Ilmar Habibulin , +.An Mike Halderman , +.An Bosko Milekic , +.An Thomas Moestl , +.An Andrew Reiter , +and +.An Tim Robbins . +.Sh BUGS +While the MAC Framework design is intended to support the containment of +the root user, not all attack channels are currently protected by entry +point checks. +As such, MAC Framework policies should not be relied on, in isolation, +to protect against a malicious privileged user. diff --git a/static/freebsd/man9/make_dev.9 b/static/freebsd/man9/make_dev.9 new file mode 100644 index 00000000..9f2c36fb --- /dev/null +++ b/static/freebsd/man9/make_dev.9 @@ -0,0 +1,499 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 1999 Chris Costello +.\" 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 November 4, 2025 +.Dt MAKE_DEV 9 +.Os +.Sh NAME +.Nm make_dev , +.Nm make_dev_cred , +.Nm make_dev_credf , +.Nm make_dev_p , +.Nm make_dev_s , +.Nm make_dev_alias , +.Nm make_dev_alias_p , +.Nm destroy_dev , +.Nm destroy_dev_sched , +.Nm destroy_dev_sched_cb , +.Nm destroy_dev_drain , +.Nm dev_depends +.Nd create and destroy character devices including devfs registration +.Sh SYNOPSIS +.In sys/param.h +.In sys/conf.h +.Ft void +.Fn make_dev_args_init "struct make_dev_args *args" +.Ft int +.Fn make_dev_s "struct make_dev_args *args" "struct cdev **cdev" "const char *fmt" ... +.Ft int +.Fn make_dev_alias_p "int flags" "struct cdev **cdev" "struct cdev *pdev" "const char *fmt" ... +.Ft void +.Fn destroy_dev "struct cdev *dev" +.Ft void +.Fn destroy_dev_sched "struct cdev *dev" +.Ft void +.Fn destroy_dev_sched_cb "struct cdev *dev" "void (*cb)(void *)" "void *arg" +.Ft void +.Fn destroy_dev_drain "struct cdevsw *csw" +.Ft void +.Fn dev_depends "struct cdev *pdev" "struct cdev *cdev" +.Pp +LEGACY INTERFACES +.Ft struct cdev * +.Fn make_dev "struct cdevsw *cdevsw" "int unit" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" ... +.Ft struct cdev * +.Fn make_dev_cred "struct cdevsw *cdevsw" "int unit" "struct ucred *cr" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" ... +.Ft struct cdev * +.Fn make_dev_credf "int flags" "struct cdevsw *cdevsw" "int unit" "struct ucred *cr" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" ... +.Ft int +.Fn make_dev_p "int flags" "struct cdev **cdev" "struct cdevsw *devsw" "struct ucred *cr" "uid_t uid" "gid_t gid" "int mode" "const char *fmt" ... +.Ft struct cdev * +.Fn make_dev_alias "struct cdev *pdev" "const char *fmt" ... +.Sh DESCRIPTION +The +.Fn make_dev_s +function creates a +.Fa cdev +structure for a new device, which is returned into the +.Fa cdev +argument. +It also notifies +.Xr devfs 4 +of the presence of the new device, that causes corresponding nodes +to be created. +Besides this, a +.Xr devctl 4 +notification is sent. +The function takes the structure +.Va struct make_dev_args args , +which specifies the parameters for the device creation: +.Pp +.Bd -literal -offset indent -compact +struct make_dev_args { + size_t mda_size; + int mda_flags; + struct cdevsw *mda_devsw; + struct ucred *mda_cr; + uid_t mda_uid; + gid_t mda_gid; + int mda_mode; + int mda_unit; + void *mda_si_drv1; + 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 +function, which ensures that future kernel interface expansion does +not affect driver source code or binary interface. +.Pp +The created device will be owned by +.Va args.mda_uid , +with the group ownership as +.Va args.mda_gid . +The name is the expansion of +.Va fmt +and following arguments as +.Xr printf 9 +would print it. +The name determines its path under +.Pa /dev +or other +.Xr devfs 4 +mount point and may contain slash +.Ql / +characters to denote subdirectories. +The permissions of the file specified in +.Va args.mda_mode +are defined in +.In sys/stat.h : +.Pp +.Bd -literal -offset indent -compact +#define S_IRWXU 0000700 /* RWX mask for owner */ +#define S_IRUSR 0000400 /* R for owner */ +#define S_IWUSR 0000200 /* W for owner */ +#define S_IXUSR 0000100 /* X for owner */ + +#define S_IRWXG 0000070 /* RWX mask for group */ +#define S_IRGRP 0000040 /* R for group */ +#define S_IWGRP 0000020 /* W for group */ +#define S_IXGRP 0000010 /* X for group */ + +#define S_IRWXO 0000007 /* RWX mask for other */ +#define S_IROTH 0000004 /* R for other */ +#define S_IWOTH 0000002 /* W for other */ +#define S_IXOTH 0000001 /* X for other */ + +#define S_ISUID 0004000 /* set user id on execution */ +#define S_ISGID 0002000 /* set group id on execution */ +#define S_ISVTX 0001000 /* sticky bit */ +#ifndef _POSIX_SOURCE +#define S_ISTXT 0001000 +#endif +.Ed +.Pp +The +.Va args.mda_cr +argument specifies credentials that will be stored in the +.Fa si_cred +member of the initialized +.Fa struct cdev . +.Pp +The +.Va args.mda_flags +argument alters the operation of +.Fn make_dev_s . +The following values are currently accepted: +.Pp +.Bl -tag -width "MAKEDEV_CHECKNAME" -compact -offset indent +.It Dv MAKEDEV_REF +reference the created device +.It Dv MAKEDEV_NOWAIT +do not sleep, the call may fail +.It Dv MAKEDEV_WAITOK +allow the function to sleep to satisfy malloc +.It Dv MAKEDEV_ETERNAL +created device will be never destroyed +.It Dv MAKEDEV_CHECKNAME +return an error if the device name is invalid or already exists +.El +.Pp +Only +.Dv MAKEDEV_NOWAIT , +.Dv MAKEDEV_WAITOK +and +.Dv MAKEDEV_CHECKNAME +values are accepted for the +.Fn make_dev_alias_p +function. +.Pp +The +.Dv MAKEDEV_WAITOK +flag is assumed if none of +.Dv MAKEDEV_WAITOK , +.Dv MAKEDEV_NOWAIT +is specified. +.Pp +The +.Xr dev_clone 9 +event handler shall specify the +.Dv MAKEDEV_REF +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 +flag allows the kernel to not acquire some locks when translating system +calls into the cdevsw methods calls. +It is responsibility of the driver author to make sure that +.Fn destroy_dev +is never called on the returned cdev. +For the convenience, use the +.Dv MAKEDEV_ETERNAL_KLD +flag for the code that can be compiled into kernel or loaded +(and unloaded) as loadable module. +.Pp +A panic will occur if the +.Dv MAKEDEV_CHECKNAME +flag is not specified +and the device name is invalid or already exists. +.Pp +The +.Fn make_dev_p +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 +.Pp +is equivalent to the code: +.Bd -literal -offset indent +struct cdev *dev; +struct make_dev_args args; +int res; + +make_dev_args_init(&args); +args.mda_flags = flags; +args.mda_devsw = cdevsw; +args.mda_cr = cred; +args.mda_uid = uid; +args.mda_gid = gid; +args.mda_mode = perms; +res = make_dev_s(&args, &dev, name); +.Ed +.Pp +Similarly, the +.Fn make_dev_credf +function call is equivalent to: +.Bd -literal -offset indent +(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 +kernels compiled with the +.Va INVARIANTS +options, the function asserts that the device creation succeeded. +.Pp +The +.Fn make_dev_cred +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: +.Bd -literal -offset indent +make_dev_credf(0, cdevsw, unit, NULL, uid, gid, perms, fmt, ...); +.Ed +.Pp +The +.Fn make_dev_alias_p +function takes the returned +.Ft cdev +from +.Fn make_dev +and makes another (aliased) name for this device. +It is an error to call +.Fn make_dev_alias_p +prior to calling +.Fn make_dev . +.Pp +The +.Fn make_dev_alias +function is similar to +.Fn make_dev_alias_p +but it returns the resulting aliasing +.Ft *cdev +and may not return an error. +.Pp +The +.Fa cdev +returned by +.Fn make_dev_s +and +.Fn make_dev_alias_p +has two fields, +.Fa si_drv1 +and +.Fa si_drv2 , +that are available to store state. +Both fields are of type +.Ft void * , +and can be initialized simultaneously with the +.Va cdev +allocation by filling +.Va args.mda_si_drv1 +and +.Va args.mda_si_drv2 +members of the +.Fn make_dev_s +argument structure, or filled after the +.Va cdev +is allocated, if using legacy interfaces. +In the latter case, the driver should handle the race of +accessing uninitialized +.Va si_drv1 +and +.Va si_drv2 +itself. +These are designed to replace the +.Fa unit +argument to +.Fn make_dev , +which can be obtained with +.Fn dev2unit . +.Pp +The +.Fn destroy_dev +function takes the returned +.Fa cdev +from +.Fn make_dev +and destroys the registration for that device. +The notification is sent to +.Xr devctl 4 +about the destruction event. +Do not call +.Fn destroy_dev +on devices that were created with +.Fn make_dev_alias . +.Pp +The +.Fn dev_depends +function establishes a parent-child relationship between two devices. +The net effect is that a +.Fn destroy_dev +of the parent device will also result in the destruction of the +child device(s), +if any exist. +A device may simultaneously be a parent and a child, +so it is possible to build a complete hierarchy. +.Pp +The +.Fn destroy_dev_sched_cb +function schedules execution of the +.Fn destroy_dev +for the specified +.Fa cdev +in the safe context. +After +.Fn destroy_dev +is finished, and if the supplied +.Fa cb +is not +.Dv NULL , +the callback +.Fa cb +is called, with argument +.Fa arg . +The +.Fn destroy_dev_sched +function is the same as: +.Bd -literal -offset indent +destroy_dev_sched_cb(cdev, NULL, NULL); +.Ed +.Pp +Neither the +.Fn d_close +driver method, nor a +.Xr devfs_cdevpriv 9 +.Fa dtr +method can +.Fn destroy_dev +directly. +Doing so causes deadlock when +.Fn destroy_dev +waits for all threads to leave the driver methods and finish executing any +per-open destructors. +Also, because +.Fn destroy_dev +sleeps, no non-sleepable locks may be held over the call. +The +.Fn destroy_dev_sched +family of functions overcome these issues. +.Pp +The device driver may call the +.Fn destroy_dev_drain +function to wait until all devices that have supplied +.Fa csw +as cdevsw, are destroyed. +This is useful when driver knows that +.Fn destroy_dev_sched +is called for all instantiated devices, but need to postpone module +unload until +.Fn destroy_dev +is actually finished for all of them. +.Sh RETURN VALUES +If successful, +.Fn make_dev_s +and +.Fn make_dev_p +will return 0, otherwise they will return an error. +If successful, +.Fn make_dev_credf +will return a valid +.Fa cdev +pointer, otherwise it will return +.Dv NULL . +.Sh ERRORS +The +.Fn make_dev_s , +.Fn make_dev_p +and +.Fn make_dev_alias_p +calls will fail and the device will be not registered if: +.Bl -tag -width Er +.It Bq Er ENOMEM +The +.Dv MAKEDEV_NOWAIT +flag was specified and a memory allocation request could not be satisfied. +.It Bq Er ENAMETOOLONG +The +.Dv MAKEDEV_CHECKNAME +flag was specified and the provided device name is longer than +.Dv SPECNAMELEN . +.It Bq Er EINVAL +The +.Dv MAKEDEV_CHECKNAME +flag was specified and the provided device name is empty, contains a +.Qq \&. +or +.Qq .. +path component or ends with +.Ql / . +.It Bq Er EINVAL +The +.Dv MAKEDEV_CHECKNAME +flag was specified and the provided device name contains invalid characters. +.It Bq Er EEXIST +The +.Dv MAKEDEV_CHECKNAME +flag was specified and the provided device name already exists. +.El +.Sh SEE ALSO +.Xr devctl 4 , +.Xr devfs 4 , +.Xr dev_clone 9 +.Sh HISTORY +The +.Fn make_dev +and +.Fn destroy_dev +functions first appeared in +.Fx 4.0 . +The function +.Fn make_dev_alias +first appeared in +.Fx 4.1 . +The function +.Fn dev_depends +first appeared in +.Fx 5.0 . +The functions +.Fn make_dev_credf , +.Fn destroy_dev_sched , +.Fn destroy_dev_sched_cb +first appeared in +.Fx 7.0 . +The function +.Fn make_dev_p +first appeared in +.Fx 8.2 . +The function +.Fn make_dev_s +first appeared in +.Fx 11.0 . diff --git a/static/freebsd/man9/malloc.9 b/static/freebsd/man9/malloc.9 new file mode 100644 index 00000000..06f5ed4e --- /dev/null +++ b/static/freebsd/man9/malloc.9 @@ -0,0 +1,406 @@ +.\" +.\" Copyright (c) 1996 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Paul Kranenburg. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 REGENTS 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. +.\" +.\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $ +.\" +.Dd August 4, 2024 +.Dt MALLOC 9 +.Os +.Sh NAME +.Nm malloc , +.Nm mallocarray , +.Nm free , +.Nm zfree , +.Nm realloc , +.Nm reallocf , +.Nm malloc_usable_size , +.Nm malloc_aligned , +.Nm malloc_exec , +.Nm MALLOC_DECLARE , +.Nm MALLOC_DEFINE , +.Nm malloc_domainset , +.Nm malloc_domainset_aligned , +.Nm malloc_domainset_exec , +.Nm mallocarray_domainset +.Nd kernel memory management routines +.Sh SYNOPSIS +.In sys/types.h +.In sys/malloc.h +.Ft void * +.Fn malloc "size_t size" "struct malloc_type *type" "int flags" +.Ft void * +.Fn mallocarray "size_t nmemb" "size_t size" "struct malloc_type *type" "int flags" +.Ft void +.Fn free "void *addr" "struct malloc_type *type" +.Ft void +.Fn zfree "void *addr" "struct malloc_type *type" +.Ft void * +.Fn realloc "void *addr" "size_t size" "struct malloc_type *type" "int flags" +.Ft void * +.Fn reallocf "void *addr" "size_t size" "struct malloc_type *type" "int flags" +.Ft size_t +.Fn malloc_usable_size "const void *addr" +.Ft void * +.Fo malloc_aligned +.Fa "size_t size" +.Fa "size_t align" +.Fa "struct malloc_type *type" +.Fa "int flags" +.Fc +.Ft void * +.Fn malloc_exec "size_t size" "struct malloc_type *type" "int flags" +.Fn MALLOC_DECLARE type +.In sys/param.h +.In sys/malloc.h +.In sys/kernel.h +.Fn MALLOC_DEFINE type shortdesc longdesc +.In sys/param.h +.In sys/domainset.h +.In sys/malloc.h +.Ft void * +.Fn malloc_domainset "size_t size" "struct malloc_type *type" "struct domainset *ds" "int flags" +.Ft void * +.Fo malloc_domainset_aligned +.Fa "size_t size" +.Fa "size_t align" +.Fa "struct malloc_type *type" +.Fa "struct domainset *ds" +.Fa "int flags" +.Fc +.Ft void * +.Fn malloc_domainset_exec "size_t size" "struct malloc_type *type" "struct domainset *ds" "int flags" +.Ft void * +.Fn mallocarray_domainset "size_t nmemb" "size_t size" "struct malloc_type *type" "struct domainset *ds" "int flags" +.Sh DESCRIPTION +The +.Fn malloc +function allocates uninitialized memory in kernel address space for an +object whose size is specified by +.Fa size . +.Pp +The +.Fn malloc_domainset +variant allocates memory from a specific +.Xr numa 4 +domain using the specified domain selection policy. +See +.Xr domainset 9 +for some example policies. +.Pp +The +.Fn malloc_aligned +and +.Fn malloc_domainset_aligned +variants return allocations aligned as specified by +.Fa align , +which must be non-zero, a power of two, and less than or equal to the page size. +.Pp +Both +.Fn malloc_exec +and +.Fn malloc_domainset_exec +can be used to return executable memory. +Not all platforms enforce a distinction between executable and non-executable +memory. +.Pp +The +.Fn mallocarray +function allocates uninitialized memory in kernel address space for an +array of +.Fa nmemb +entries whose size is specified by +.Fa size . +.Pp +The +.Fn mallocarray_domainset +variant allocates memory from a specific +.Xr numa 4 +domain using the specified domain selection policy. +See +.Xr domainset 9 +for some example policies. +.Pp +The +.Fn free +function releases memory at address +.Fa addr +that was previously allocated by +.Fn malloc +for re-use. +The memory is not zeroed. +If +.Fa addr +is +.Dv NULL , +then +.Fn free +does nothing. +.Pp +Like +.Fn free , +the +.Fn zfree +function releases memory at address +.Fa addr +that was previously allocated by +.Fn malloc +for re-use. +However, +.Fn zfree +will zero the memory before it is released. +.Pp +The +.Fn realloc +function changes the size of the previously allocated memory referenced by +.Fa addr +to +.Fa size +bytes. +The contents of the memory are unchanged up to the lesser of the new and +old sizes. +Note that the returned value may differ from +.Fa addr . +If the requested memory cannot be allocated, +.Dv NULL +is returned and the memory referenced by +.Fa addr +is valid and unchanged. +If +.Fa addr +is +.Dv NULL , +the +.Fn realloc +function behaves identically to +.Fn malloc +for the specified size. +.Pp +The +.Fn reallocf +function is identical to +.Fn realloc +except that it +will free the passed pointer when the requested memory cannot be allocated. +.Pp +The +.Fn malloc_usable_size +function returns the usable size of the allocation pointed to by +.Fa addr . +The return value may be larger than the size that was requested during +allocation. +.Pp +Unlike its standard C library counterpart +.Pq Xr malloc 3 , +the kernel version takes two more arguments. +The +.Fa flags +argument further qualifies +.Fn malloc Ns 's +operational characteristics as follows: +.Bl -tag -width "M_USE_RESERVE" +.It Dv M_ZERO +Causes the allocated memory to be set to all zeros. +.It Dv M_NODUMP +For allocations greater than page size, causes the allocated +memory to be excluded from kernel core dumps. +.It Dv M_NOWAIT +Causes +.Fn malloc , +.Fn realloc , +and +.Fn reallocf +to return +.Dv NULL +if the request cannot be immediately fulfilled due to resource shortage. +Note that +.Dv M_NOWAIT +is required when running in an interrupt context. +.It Dv M_WAITOK +Indicates that it is OK to wait for resources. +If the request cannot be immediately fulfilled, the current process is put +to sleep to wait for resources to be released by other processes. +The +.Fn malloc , +.Fn mallocarray , +.Fn realloc , +and +.Fn reallocf +functions cannot return +.Dv NULL +if +.Dv M_WAITOK +is specified. +If the multiplication of +.Fa nmemb +and +.Fa size +would cause an integer overflow, the +.Fn mallocarray +function induces a panic. +.It Dv M_USE_RESERVE +Indicates that the system can use its reserve of memory to satisfy the +request. +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 +.Dv M_WAITOK +or +.Dv M_NOWAIT +must be specified. +.Pp +The +.Fa type +argument is used to perform statistics on memory usage, and for +basic sanity checks. +It can be used to identify multiple allocations. +The statistics can be examined by +.Sq vmstat -m . +.Pp +A +.Fa type +is defined using +.Vt "struct malloc_type" +via the +.Fn MALLOC_DECLARE +and +.Fn MALLOC_DEFINE +macros. +.Bd -literal -offset indent +/* sys/something/foo_extern.h */ + +MALLOC_DECLARE(M_FOOBUF); + +/* sys/something/foo_main.c */ + +MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether"); + +/* sys/something/foo_subr.c */ + +\&... +buf = malloc(sizeof(*buf), M_FOOBUF, M_NOWAIT); + +.Ed +.Pp +In order to use +.Fn MALLOC_DEFINE , +one must include +.In sys/param.h +(instead of +.In sys/types.h ) +and +.In sys/kernel.h . +.Sh CONTEXT +.Fn malloc , +.Fn realloc +and +.Fn reallocf +may not be called from fast interrupts handlers. +When called from threaded interrupts, +.Fa flags +must contain +.Dv M_NOWAIT . +.Pp +.Fn malloc , +.Fn realloc +and +.Fn reallocf +may sleep when called with +.Dv M_WAITOK . +.Fn free +never sleeps. +However, +.Fn malloc , +.Fn realloc , +.Fn reallocf +and +.Fn free +may not be called in a critical section or while holding a spin lock. +.Pp +Any calls to +.Fn malloc +(even with +.Dv M_NOWAIT ) +or +.Fn free +when holding a +.Xr vnode 9 +interlock, will cause a LOR (Lock Order Reversal) due to the +intertwining of VM Objects and Vnodes. +.Sh IMPLEMENTATION NOTES +The memory allocator allocates memory in chunks that have size a power +of two for requests up to the size of a page of memory. +For larger requests, one or more pages is allocated. +While it should not be relied upon, this information may be useful for +optimizing the efficiency of memory use. +.Sh RETURN VALUES +The +.Fn malloc , +.Fn realloc , +and +.Fn reallocf +functions return a kernel virtual address that is suitably aligned for +storage of any type of object, or +.Dv NULL +if the request could not be satisfied (implying that +.Dv M_NOWAIT +was set). +.Sh DIAGNOSTICS +A kernel compiled with the +.Dv INVARIANTS +configuration option attempts to detect memory corruption caused by +such things as writing outside the allocated area and imbalanced calls to the +.Fn malloc +and +.Fn free +functions. +Failing consistency checks will cause a panic or a system console +message. +.Sh SEE ALSO +.Xr numa 4 , +.Xr vmstat 8 , +.Xr contigmalloc 9 , +.Xr domainset 9 , +.Xr memguard 9 , +.Xr vnode 9 +.Sh HISTORY +.Fn zfree +first appeared in +.Fx 13.0 . diff --git a/static/freebsd/man9/mbchain.9 b/static/freebsd/man9/mbchain.9 new file mode 100644 index 00000000..94bad32a --- /dev/null +++ b/static/freebsd/man9/mbchain.9 @@ -0,0 +1,220 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2001 Boris Popov +.\" +.\" 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 February 20, 2001 +.Dt MBCHAIN 9 +.Os +.Sh NAME +.Nm mbchain , +.Nm mb_init , +.Nm mb_initm , +.Nm mb_done , +.Nm mb_detach , +.Nm mb_fixhdr , +.Nm mb_reserve , +.Nm mb_put_uint8 , +.Nm mb_put_uint16be , +.Nm mb_put_uint16le , +.Nm mb_put_uint32be , +.Nm mb_put_uint32le , +.Nm mb_put_int64be , +.Nm mb_put_int64le , +.Nm mb_put_mem , +.Nm mb_put_mbuf , +.Nm mb_put_uio +.Nd "set of functions to build an mbuf chain from various data types" +.Sh SYNOPSIS +.Cd options LIBMCHAIN +.Li kldload libmchain +.Pp +.In sys/param.h +.In sys/uio.h +.In sys/mchain.h +.Ft int +.Fn mb_init "struct mbchain *mbp" +.Ft void +.Fn mb_initm "struct mbchain *mbp" "struct mbuf *m" +.Ft void +.Fn mb_done "struct mbchain *mbp" +.Ft struct mbuf * +.Fn mb_detach "struct mbchain *mbp" +.Ft int +.Fn mb_fixhdr "struct mbchain *mbp" +.Ft caddr_t +.Fn mb_reserve "struct mbchain *mbp" "int size" +.Ft int +.Fn mb_put_uint8 "struct mbchain *mbp" "uint8_t x" +.Ft int +.Fn mb_put_uint16be "struct mbchain *mbp" "uint16_t x" +.Ft int +.Fn mb_put_uint16le "struct mbchain *mbp" "uint16_t x" +.Ft int +.Fn mb_put_uint32be "struct mbchain *mbp" "uint32_t x" +.Ft int +.Fn mb_put_uint32le "struct mbchain *mbp" "uint32_t x" +.Ft int +.Fn mb_put_int64be "struct mbchain *mbp" "int64_t x" +.Ft int +.Fn mb_put_int64le "struct mbchain *mbp" "int64_t x" +.Ft int +.Fn mb_put_mem "struct mbchain *mbp" "c_caddr_t source" "int size" "int type" +.Ft int +.Fn mb_put_mbuf "struct mbchain *mbp" "struct mbuf *m" +.Ft int +.Fn mb_put_uio "struct mbchain *mbp" "struct uio *uiop" "int size" +.Sh DESCRIPTION +These functions are used to compose mbuf chains from various data types. +The +.Vt mbchain +structure is used as a working context and should be initialized with a call +to either +.Fn mb_init +or +.Fn mb_initm . +It has the following fields: +.Bl -tag -width ".Va mb_count" +.It Va "mb_top" +.Pq Vt "struct mbuf *" +A pointer to the top of constructed mbuf chain. +.It Va mb_cur +.Pq Vt "struct mbuf *" +A pointer to the currently filled mbuf. +.It Va mb_mleft +.Pq Vt int +Number of bytes left in the current mbuf. +.It Va mb_count +.Pq Vt int +Total number of bytes placed in the mbuf chain. +.It Va mb_copy +.Pq Vt "mb_copy_t *" +User-defined function to perform a copy into mbuf; +useful if any unusual +data conversion is necessary. +.It Va mb_udata +.Pq Vt "void *" +User-supplied data which can be used in the +.Va mb_copy +function. +.El +.Pp +.Fn mb_done +function disposes an mbuf chain pointed to by +.Fa mbp->mb_top +field and sets +the field to +.Dv NULL . +.Pp +.Fn mb_detach +function returns the value of +.Fa mbp->mb_top +field and sets its value to +.Dv NULL . +.Pp +.Fn mb_fixhdr +recalculates the length of an mbuf chain and updates the +.Va m_pkthdr.len +field of the first mbuf in the chain. +It returns the calculated length. +.Pp +.Fn mb_reserve +ensures that the object of the length specified by the +.Fa size +argument will fit in the current mbuf (mbuf allocation is performed if +necessary), and advances all pointers as if the real data was placed. +Returned +value will point to the beginning of the reserved space. +Note that the size +of the object should not exceed +.Dv MLEN +bytes. +.Pp +All +.Fn mb_put_* +functions perform an actual copy of the data into mbuf chain. +Functions which have +.Cm le +or +.Cm be +suffixes will perform conversion to the little\- or big\-endian data formats. +.Pp +.Fn mb_put_mem +function copies +.Fa size +bytes of data specified by the +.Fa source +argument to an mbuf chain. +The +.Fa type +argument specifies the method used to perform a copy, +and can be one of the following: +.Bl -tag -width ".Dv MB_MINLINE" +.It Dv MB_MSYSTEM +Use +.Fn bcopy +function. +.It Dv MB_MUSER +Use +.Xr copyin 9 +function. +.It Dv MB_MINLINE +Use an +.Dq inline +loop which does not call any function. +.It Dv MB_MZERO +Do not copy any data, but just fill the destination with zero bytes. +.It Dv MB_MCUSTOM +Call function specified by the +.Fa mbp->mb_copy +field. +.El +.Sh RETURN VALUES +All +.Ft int +functions except +.Fn mb_fixhdr +return zero if successful and an error code otherwise. +.Pp +.Em Note : +after failure of any function, an mbuf chain is left in the broken state, +and only +.Fn mb_done +function can safely be called to destroy it. +.Sh EXAMPLES +.Bd -literal +struct mbchain *mbp; +struct mbuf *m; + +mb_init(mbp); +mb_put_uint8(mbp, 33); +mb_put_uint16le(mbp, length); +m = m_copym(mbp->mb_top, 0, M_COPYALL, M_WAIT); +send(m); +mb_done(mbp); +.Ed +.Sh SEE ALSO +.Xr mbuf 9 , +.Xr mdchain 9 +.Sh AUTHORS +This manual page was written by +.An Boris Popov Aq Mt bp@FreeBSD.org . diff --git a/static/freebsd/man9/mbuf.9 b/static/freebsd/man9/mbuf.9 new file mode 100644 index 00000000..265a6ddd --- /dev/null +++ b/static/freebsd/man9/mbuf.9 @@ -0,0 +1,1317 @@ +.\" Copyright (c) 2000 FreeBSD Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY 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 [your name] OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 20, 2026 +.Dt MBUF 9 +.Os +.\" +.Sh NAME +.Nm mbuf +.Nd "memory management in the kernel IPC subsystem" +.\" +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.In sys/mbuf.h +.\" +.Ss Mbuf allocation macros +.Fn MGET "struct mbuf *mbuf" "int how" "short type" +.Fn MGETHDR "struct mbuf *mbuf" "int how" "short type" +.Ft int +.Fn MCLGET "struct mbuf *mbuf" "int how" +.Fo MEXTADD +.Fa "struct mbuf *mbuf" +.Fa "char *buf" +.Fa "u_int size" +.Fa "void (*free)(struct mbuf *)" +.Fa "void *opt_arg1" +.Fa "void *opt_arg2" +.Fa "int flags" +.Fa "int type" +.Fc +.\" +.Ss Mbuf utility macros +.Ft type +.Fn mtod "struct mbuf *mbuf" "type" +.Ft void * +.Fn mtodo "struct mbuf *mbuf" "offset" +.Fn M_ALIGN "struct mbuf *mbuf" "u_int len" +.Fn MH_ALIGN "struct mbuf *mbuf" "u_int len" +.Ft int +.Fn M_LEADINGSPACE "struct mbuf *mbuf" +.Ft int +.Fn M_TRAILINGSPACE "struct mbuf *mbuf" +.Fn M_MOVE_PKTHDR "struct mbuf *to" "struct mbuf *from" +.Fn M_PREPEND "struct mbuf *mbuf" "int len" "int how" +.Fn MCHTYPE "struct mbuf *mbuf" "short type" +.Ft int +.Fn M_WRITABLE "struct mbuf *mbuf" +.\" +.Ss Mbuf allocation functions +.Ft struct mbuf * +.Fn m_get "int how" "short type" +.Ft struct mbuf * +.Fn m_get2 "int size" "int how" "short type" "int flags" +.Ft struct mbuf * +.Fn m_get3 "int size" "int how" "short type" "int flags" +.Ft struct mbuf * +.Fn m_getm "struct mbuf *orig" "int len" "int how" "short type" +.Ft struct mbuf * +.Fn m_getjcl "int how" "short type" "int flags" "int size" +.Ft struct mbuf * +.Fn m_getcl "int how" "short type" "int flags" +.Ft struct mbuf * +.Fn m_gethdr "int how" "short type" +.Ft struct mbuf * +.Fn m_free "struct mbuf *mbuf" +.Ft void +.Fn m_freem "struct mbuf *mbuf" +.\" +.Ss Mbuf utility functions +.Ft void +.Fn m_adj "struct mbuf *mbuf" "int len" +.Ft void +.Fn m_align "struct mbuf *mbuf" "int len" +.Ft int +.Fn m_append "struct mbuf *mbuf" "int len" "c_caddr_t cp" +.Ft struct mbuf * +.Fn m_prepend "struct mbuf *mbuf" "int len" "int how" +.Ft struct mbuf * +.Fn m_copyup "struct mbuf *mbuf" "int len" "int dstoff" +.Ft struct mbuf * +.Fn m_pullup "struct mbuf *mbuf" "int len" +.Ft struct mbuf * +.Fn m_pulldown "struct mbuf *mbuf" "int offset" "int len" "int *offsetp" +.Ft struct mbuf * +.Fn m_copym "struct mbuf *mbuf" "int offset" "int len" "int how" +.Ft struct mbuf * +.Fn m_copypacket "struct mbuf *mbuf" "int how" +.Ft struct mbuf * +.Fn m_dup "const struct mbuf *mbuf" "int how" +.Ft void +.Fn m_copydata "const struct mbuf *mbuf" "int offset" "int len" "caddr_t buf" +.Ft void +.Fn m_copyback "struct mbuf *mbuf" "int offset" "int len" "caddr_t buf" +.Ft struct mbuf * +.Fo m_devget +.Fa "char *buf" +.Fa "int len" +.Fa "int offset" +.Fa "struct ifnet *ifp" +.Fa "void (*copy)(char *from, caddr_t to, u_int len)" +.Fc +.Ft void +.Fn m_cat "struct mbuf *m" "struct mbuf *n" +.Ft void +.Fn m_catpkt "struct mbuf *m" "struct mbuf *n" +.Ft u_int +.Fn m_fixhdr "struct mbuf *mbuf" +.Ft int +.Fn m_dup_pkthdr "struct mbuf *to" "const struct mbuf *from" "int how" +.Ft void +.Fn m_move_pkthdr "struct mbuf *to" "struct mbuf *from" +.Ft u_int +.Fn m_length "struct mbuf *mbuf" "struct mbuf **last" +.Ft struct mbuf * +.Fn m_split "struct mbuf *mbuf" "int len" "int how" +.Ft int +.Fn m_apply "struct mbuf *mbuf" "int off" "int len" "int (*f)(void *arg, void *data, u_int len)" "void *arg" +.Ft struct mbuf * +.Fn m_getptr "struct mbuf *mbuf" "int loc" "int *off" +.Ft struct mbuf * +.Fn m_defrag "struct mbuf *m0" "int how" +.Ft struct mbuf * +.Fn m_collapse "struct mbuf *m0" "int how" "int maxfrags" +.Ft struct mbuf * +.Fn m_unshare "struct mbuf *m0" "int how" +.\" +.Sh DESCRIPTION +An +.Vt mbuf +is a basic unit of memory management in the kernel IPC subsystem. +Network packets and socket buffers are stored in +.Vt mbufs . +A network packet may span multiple +.Vt mbufs +arranged into a +.Vt mbuf chain +(linked list), +which allows adding or trimming +network headers with little overhead. +.Pp +While a developer should not bother with +.Vt mbuf +internals without serious +reason in order to avoid incompatibilities with future changes, it +is useful to understand the general structure of an +.Vt mbuf . +.Pp +An +.Vt mbuf +consists of a variable-sized header and a small internal +buffer for data. +The total size of an +.Vt mbuf , +.Dv MSIZE , +is a constant defined in +.In sys/param.h . +The +.Vt mbuf +header includes: +.Bl -tag -width "m_nextpkt" -offset indent +.It Va m_next +.Pq Vt struct mbuf * +A pointer to the next +.Vt mbuf +in the +.Vt mbuf chain . +.It Va m_nextpkt +.Pq Vt struct mbuf * +A pointer to the next +.Vt mbuf chain +in the queue. +.It Va m_data +.Pq Vt caddr_t +A pointer to data attached to this +.Vt mbuf . +.It Va m_len +.Pq Vt int +The length of the data. +.It Va m_type +.Pq Vt short +The type of the data. +.It Va m_flags +.Pq Vt int +The +.Vt mbuf +flags. +.El +.Pp +The +.Vt mbuf +flag bits are defined as follows: +.Bd -literal +#define M_EXT 0x00000001 /* has associated external storage */ +#define M_PKTHDR 0x00000002 /* start of record */ +#define M_EOR 0x00000004 /* end of record */ +#define M_RDONLY 0x00000008 /* associated data marked read-only */ +#define M_BCAST 0x00000010 /* send/received as link-level broadcast */ +#define M_MCAST 0x00000020 /* send/received as link-level multicast */ +#define M_PROMISC 0x00000040 /* packet was not for us */ +#define M_VLANTAG 0x00000080 /* ether_vtag is valid */ +#define M_EXTPG 0x00000100 /* has array of unmapped pages and TLS */ +#define M_NOFREE 0x00000200 /* do not free mbuf, embedded in cluster */ +#define M_TSTMP 0x00000400 /* rcv_tstmp field is valid */ +#define M_TSTMP_HPREC 0x00000800 /* rcv_tstmp is high-prec, typically + hw-stamped on port (useful for IEEE 1588 + and 802.1AS) */ + +#define M_PROTO1 0x00001000 /* protocol-specific */ +#define M_PROTO2 0x00002000 /* protocol-specific */ +#define M_PROTO3 0x00004000 /* protocol-specific */ +#define M_PROTO4 0x00008000 /* protocol-specific */ +#define M_PROTO5 0x00010000 /* protocol-specific */ +#define M_PROTO6 0x00020000 /* protocol-specific */ +#define M_PROTO7 0x00040000 /* protocol-specific */ +#define M_PROTO8 0x00080000 /* protocol-specific */ +#define M_PROTO9 0x00100000 /* protocol-specific */ +#define M_PROTO10 0x00200000 /* protocol-specific */ +#define M_PROTO11 0x00400000 /* protocol-specific */ +#define M_PROTO12 0x00800000 /* protocol-specific */ +.Ed +.Pp +The available +.Vt mbuf +types are defined as follows: +.Bd -literal +#define MT_DATA 1 /* dynamic (data) allocation */ +#define MT_HEADER MT_DATA /* packet header */ + +#define MT_VENDOR1 4 /* for vendor-internal use */ +#define MT_VENDOR2 5 /* for vendor-internal use */ +#define MT_VENDOR3 6 /* for vendor-internal use */ +#define MT_VENDOR4 7 /* for vendor-internal use */ + +#define MT_SONAME 8 /* socket name */ + +#define MT_EXP1 9 /* for experimental use */ +#define MT_EXP2 10 /* for experimental use */ +#define MT_EXP3 11 /* for experimental use */ +#define MT_EXP4 12 /* for experimental use */ + +#define MT_CONTROL 14 /* extra-data protocol message */ +#define MT_EXTCONTROL 15 /* control message with externalized contents */ +#define MT_OOBDATA 16 /* expedited data */ +.Ed +.Pp +The available external buffer types are defined as follows: +.Bd -literal +#define EXT_CLUSTER 1 /* mbuf cluster */ +#define EXT_SFBUF 2 /* sendfile(2)'s sf_bufs */ +#define EXT_JUMBOP 3 /* jumbo cluster 4096 bytes */ +#define EXT_JUMBO9 4 /* jumbo cluster 9216 bytes */ +#define EXT_JUMBO16 5 /* jumbo cluster 16184 bytes */ +#define EXT_PACKET 6 /* mbuf+cluster from packet zone */ +#define EXT_MBUF 7 /* external mbuf reference */ +#define EXT_RXRING 8 /* data in NIC receive ring */ +#define EXT_PGS 9 /* array of unmapped pages */ + +#define EXT_VENDOR1 224 /* for vendor-internal use */ +#define EXT_VENDOR2 225 /* for vendor-internal use */ +#define EXT_VENDOR3 226 /* for vendor-internal use */ +#define EXT_VENDOR4 227 /* for vendor-internal use */ + +#define EXT_EXP1 244 /* for experimental use */ +#define EXT_EXP2 245 /* for experimental use */ +#define EXT_EXP3 246 /* for experimental use */ +#define EXT_EXP4 247 /* for experimental use */ + +#define EXT_NET_DRV 252 /* custom ext_buf provided by net driver(s) */ +#define EXT_MOD_TYPE 253 /* custom module's ext_buf type */ +#define EXT_DISPOSABLE 254 /* can throw this buffer away w/page flipping */ +#define EXT_EXTREF 255 /* has externally maintained ref_cnt ptr */ +.Ed +.Pp +If the +.Dv M_PKTHDR +flag is set, a +.Vt struct pkthdr Va m_pkthdr +is added to the +.Vt mbuf +header. +It contains a pointer to the interface +the packet has been received from +.Pq Vt struct ifnet Va *rcvif , +and the total packet length +.Pq Vt int Va len . +Optionally, it may also contain an attached list of packet tags +.Pq Vt "struct m_tag" . +See +.Xr mbuf_tags 9 +for details. +Fields used in offloading checksum calculation to the hardware are kept in +.Va m_pkthdr +as well. +See +.Sx HARDWARE-ASSISTED CHECKSUM CALCULATION +for details. +.Pp +If small enough, data is stored in the internal data buffer of an +.Vt mbuf . +If the data is sufficiently large, another +.Vt mbuf +may be added to the +.Vt mbuf chain , +or external storage may be associated with the +.Vt mbuf . +.Dv MHLEN +bytes of data can fit into an +.Vt mbuf +with the +.Dv M_PKTHDR +flag set, +.Dv MLEN +bytes can otherwise. +.Pp +If external storage is being associated with an +.Vt mbuf , +the +.Va m_ext +header is added at the cost of losing the internal data buffer. +It includes a pointer to external storage, the size of the storage, +a pointer to a function used for freeing the storage, +a pointer to an optional argument that can be passed to the function, +and a pointer to a reference counter. +An +.Vt mbuf +using external storage has the +.Dv M_EXT +flag set. +.Pp +The system supplies a macro for allocating the desired external storage +buffer, +.Dv MEXTADD . +.Pp +The allocation and management of the reference counter is handled by the +subsystem. +.Pp +The system also supplies a default type of external storage buffer called an +.Vt mbuf cluster . +.Vt Mbuf clusters +can be allocated and configured with the use of the +.Dv MCLGET +macro. +Each +.Vt mbuf cluster +is +.Dv MCLBYTES +in size, where MCLBYTES is a machine-dependent constant. +The system defines an advisory macro +.Dv MINCLSIZE , +which is the smallest amount of data to put into an +.Vt mbuf cluster . +It is equal to +.Dv MHLEN +plus one. +It is typically preferable to store data into the data region of an +.Vt mbuf , +if size permits, as opposed to allocating a separate +.Vt mbuf cluster +to hold the same data. +.\" +.Ss Macros and Functions +There are numerous predefined macros and functions that provide the +developer with common utilities. +.\" +.Bl -ohang -offset indent +.It Fn mtod mbuf type +Convert an +.Fa mbuf +pointer to a data pointer. +The macro expands to the data pointer cast to the specified +.Fa type . +.Sy Note : +It is advisable to ensure that there is enough contiguous data in +.Fa mbuf . +See +.Fn m_pullup +for details. +.It Fn mtodo mbuf offset +Return a data pointer at an offset (in bytes) into the data attached to +.Fa mbuf . +Returns a +.Ft void * +pointer . +.Sy Note : +The caller must ensure that the offset is in bounds of the attached data. +.It Fn MGET mbuf how type +Allocate an +.Vt mbuf +and initialize it to contain internal data. +.Fa mbuf +will point to the allocated +.Vt mbuf +on success, or be set to +.Dv NULL +on failure. +The +.Fa how +argument is to be set to +.Dv M_WAITOK +or +.Dv M_NOWAIT . +It specifies whether the caller is willing to block if necessary. +A number of other functions and macros related to +.Vt mbufs +have the same argument because they may +at some point need to allocate new +.Vt mbufs . +.It Fn MGETHDR mbuf how type +Allocate an +.Vt mbuf +and initialize it to contain a packet header +and internal data. +See +.Fn MGET +for details. +.It Fn MEXTADD mbuf buf size free opt_arg1 opt_arg2 flags type +Associate externally managed data with +.Fa mbuf . +Any internal data contained in the mbuf will be discarded, and the +.Dv M_EXT +flag will be set. +The +.Fa buf +and +.Fa size +arguments are the address and length, respectively, of the data. +The +.Fa free +argument points to a function which will be called to free the data +when the mbuf is freed; it is only used if +.Fa type +is +.Dv EXT_EXTREF . +The +.Fa opt_arg1 +and +.Fa opt_arg2 +arguments will be saved in +.Va ext_arg1 +and +.Va ext_arg2 +fields of the +.Va struct m_ext +of the mbuf. +The +.Fa flags +argument specifies additional +.Vt mbuf +flags; it is not necessary to specify +.Dv M_EXT . +Finally, the +.Fa type +argument specifies the type of external data, which controls how it +will be disposed of when the +.Vt mbuf +is freed. +In most cases, the correct value is +.Dv EXT_EXTREF . +.It Fn MCLGET mbuf how +Allocate and attach an +.Vt mbuf cluster +to +.Fa mbuf . +On success, a non-zero value returned; otherwise, 0. +Historically, consumers would check for success by testing the +.Dv M_EXT +flag on the mbuf, but this is now discouraged to avoid unnecessary awareness +of the implementation of external storage in protocol stacks and device +drivers. +.It Fn M_ALIGN mbuf len +Set the pointer +.Fa mbuf->m_data +to place an object of the size +.Fa len +at the end of the internal data area of +.Fa mbuf , +long word aligned. +Applicable only if +.Fa mbuf +is newly allocated with +.Fn MGET +or +.Fn m_get . +.It Fn MH_ALIGN mbuf len +Serves the same purpose as +.Fn M_ALIGN +does, but only for +.Fa mbuf +newly allocated with +.Fn MGETHDR +or +.Fn m_gethdr , +or initialized by +.Fn m_dup_pkthdr +or +.Fn m_move_pkthdr . +.It Fn m_align mbuf len +Services the same purpose as +.Fn M_ALIGN +but handles any type of mbuf. +.It Fn M_LEADINGSPACE mbuf +Returns the number of bytes available before the beginning +of data in +.Fa mbuf . +.It Fn M_TRAILINGSPACE mbuf +Returns the number of bytes available after the end of data in +.Fa mbuf . +.It Fn M_PREPEND mbuf len how +This macro operates on an +.Vt mbuf chain . +It is an optimized wrapper for +.Fn m_prepend +that can make use of possible empty space before data +(e.g.\& left after trimming of a link-layer header). +The new +.Vt mbuf chain +pointer or +.Dv NULL +is in +.Fa mbuf +after the call. +.It Fn M_MOVE_PKTHDR to from +Using this macro is equivalent to calling +.Fn m_move_pkthdr to from . +.It Fn M_WRITABLE mbuf +This macro will evaluate true if +.Fa mbuf +is not marked +.Dv M_RDONLY +and if either +.Fa mbuf +does not contain external storage or, +if it does, +then if the reference count of the storage is not greater than 1. +The +.Dv M_RDONLY +flag can be set in +.Fa mbuf->m_flags . +This can be achieved during setup of the external storage, +by passing the +.Dv M_RDONLY +bit as a +.Fa flags +argument to the +.Fn MEXTADD +macro, or can be directly set in individual +.Vt mbufs . +.It Fn MCHTYPE mbuf type +Change the type of +.Fa mbuf +to +.Fa type . +This is a relatively expensive operation and should be avoided. +.El +.Pp +The functions are: +.Bl -ohang -offset indent +.It Fn m_get how type +A function version of +.Fn MGET +for non-critical paths. +.It Fn m_get2 size how type flags +Allocate an +.Vt mbuf +with enough space to hold specified amount of data. +If the size is larger than +.Dv MJUMPAGESIZE , NULL +will be returned. +.It Fn m_get3 size how type flags +Allocate an +.Vt mbuf +with enough space to hold specified amount of data. +If the size is larger than +.Dv MJUM16BYTES, NULL +will be returned. +.It Fn m_getm orig len how type +Allocate +.Fa len +bytes worth of +.Vt mbufs +and +.Vt mbuf clusters +if necessary and append the resulting allocated +.Vt mbuf chain +to the +.Vt mbuf chain +.Fa orig , +if it is +.No non- Ns Dv NULL . +If the allocation fails at any point, +free whatever was allocated and return +.Dv NULL . +If +.Fa orig +is +.No non- Ns Dv NULL , +it will not be freed. +It is possible to use +.Fn m_getm +to either append +.Fa len +bytes to an existing +.Vt mbuf +or +.Vt mbuf chain +(for example, one which may be sitting in a pre-allocated ring) +or to simply perform an all-or-nothing +.Vt mbuf +and +.Vt mbuf cluster +allocation. +.It Fn m_gethdr how type +A function version of +.Fn MGETHDR +for non-critical paths. +.It Fn m_getcl how type flags +Fetch an +.Vt mbuf +with a +.Vt mbuf cluster +attached to it. +If one of the allocations fails, the entire allocation fails. +This routine is the preferred way of fetching both the +.Vt mbuf +and +.Vt mbuf cluster +together, as it avoids having to unlock/relock between allocations. +Returns +.Dv NULL +on failure. +.It Fn m_getjcl how type flags size +This is like +.Fn m_getcl +but the specified +.Fa size +of the cluster to be allocated must be one of +.Dv MCLBYTES , MJUMPAGESIZE , MJUM9BYTES , +or +.Dv MJUM16BYTES . +.It Fn m_free mbuf +Frees +.Vt mbuf . +Returns +.Va m_next +of the freed +.Vt mbuf . +.El +.Pp +The functions below operate on +.Vt mbuf chains . +.Bl -ohang -offset indent +.It Fn m_freem mbuf +Free an entire +.Vt mbuf chain , +including any external storage. +.\" +.It Fn m_adj mbuf len +Trim +.Fa len +bytes from the head of an +.Vt mbuf chain +if +.Fa len +is positive, from the tail otherwise. +.\" +.It Fn m_append mbuf len cp +Append +.Vt len +bytes of data +.Vt cp +to the +.Vt mbuf chain . +Extend the mbuf chain if the new data does not fit in +existing space. +.\" +.It Fn m_prepend mbuf len how +Allocate a new +.Vt mbuf +and prepend it to the +.Vt mbuf chain , +handle +.Dv M_PKTHDR +properly. +.Sy Note : +It does not allocate any +.Vt mbuf clusters , +so +.Fa len +must be less than +.Dv MLEN +or +.Dv MHLEN , +depending on the +.Dv M_PKTHDR +flag setting. +.\" +.It Fn m_copyup mbuf len dstoff +Similar to +.Fn m_pullup +but copies +.Fa len +bytes of data into a new mbuf at +.Fa dstoff +bytes into the mbuf. +The +.Fa dstoff +argument aligns the data and leaves room for a link layer header. +Returns the new +.Vt mbuf chain +on success, +and frees the +.Vt mbuf chain +and returns +.Dv NULL +on failure. +.Sy Note : +The function does not allocate +.Vt mbuf clusters , +so +.Fa len + dstoff +must be less than +.Dv MHLEN . +.\" +.It Fn m_pullup mbuf len +Arrange that the first +.Fa len +bytes of an +.Vt mbuf chain +are contiguous and lay in the data area of +.Fa mbuf , +so they are accessible with +.Fn mtod mbuf type . +It is important to remember that this may involve +reallocating some mbufs and moving data so all pointers +referencing data within the old mbuf chain +must be recalculated or made invalid. +Return the new +.Vt mbuf chain +on success, +.Dv NULL +on failure +(the +.Vt mbuf chain +is freed in this case). +.Sy Note : +It does not allocate any +.Vt mbuf clusters , +so +.Fa len +must be less than or equal to +.Dv MHLEN . +.\" +.It Fn m_pulldown mbuf offset len offsetp +Arrange that +.Fa len +bytes between +.Fa offset +and +.Fa offset + len +in the +.Vt mbuf chain +are contiguous and lay in the data area of +.Fa mbuf , +so they are accessible with +.Fn mtod +or +.Fn mtodo . +.Fa len +must be smaller than, or equal to, the size of an +.Vt mbuf cluster . +Return a pointer to an intermediate +.Vt mbuf +in the chain containing the requested region; +the offset in the data region of the +.Vt mbuf chain +to the data contained in the returned mbuf is stored in +.Fa *offsetp . +If +.Fa offsetp +is NULL, the region may be accessed using +.Fn mtod mbuf type +or +.Fn mtodo mbuf 0 . +If +.Fa offsetp +is non-NULL, the region may be accessed using +.Fn mtodo mbuf *offsetp . +The region of the mbuf chain between its beginning and +.Fa offset +is not modified, therefore it is safe to hold pointers to data within +this region before calling +.Fn m_pulldown . +.\" +.It Fn m_copym mbuf offset len how +Make a copy of an +.Vt mbuf chain +starting +.Fa offset +bytes from the beginning, continuing for +.Fa len +bytes. +If +.Fa len +is +.Dv M_COPYALL , +copy to the end of the +.Vt mbuf chain . +.Sy Note : +The copy is read-only, because the +.Vt mbuf clusters +are not copied, only their reference counts are incremented. +.\" +.It Fn m_copypacket mbuf how +Copy an entire packet including header, which must be present. +This is an optimized version of the common case +.Fn m_copym mbuf 0 M_COPYALL how . +.Sy Note : +the copy is read-only, because the +.Vt mbuf clusters +are not copied, only their reference counts are incremented. +.\" +.It Fn m_dup mbuf how +Copy a packet header +.Vt mbuf chain +into a completely new +.Vt mbuf chain , +including copying any +.Vt mbuf clusters . +Use this instead of +.Fn m_copypacket +when you need a writable copy of an +.Vt mbuf chain . +.\" +.It Fn m_copydata mbuf offset len buf +Copy data from an +.Vt mbuf chain +starting +.Fa off +bytes from the beginning, continuing for +.Fa len +bytes, into the indicated buffer +.Fa buf . +.\" +.It Fn m_copyback mbuf offset len buf +Copy +.Fa len +bytes from the buffer +.Fa buf +back into the indicated +.Vt mbuf chain , +starting at +.Fa offset +bytes from the beginning of the +.Vt mbuf chain , +extending the +.Vt mbuf chain +if necessary. +.Sy Note : +It does not allocate any +.Vt mbuf clusters , +just adds +.Vt mbufs +to the +.Vt mbuf chain . +It is safe to set +.Fa offset +beyond the current +.Vt mbuf chain +end: zeroed +.Vt mbufs +will be allocated to fill the space. +.\" +.It Fn m_length mbuf last +Return the length of the +.Vt mbuf chain , +and optionally a pointer to the last +.Vt mbuf . +.\" +.It Fn m_dup_pkthdr to from how +Upon the function's completion, the +.Vt mbuf +.Fa to +will contain an identical copy of +.Fa from->m_pkthdr +and the per-packet attributes found in the +.Vt mbuf chain +.Fa from . +The +.Vt mbuf +.Fa from +must have the flag +.Dv M_PKTHDR +initially set, and +.Fa to +must be empty on entry. +.\" +.It Fn m_move_pkthdr to from +Move +.Va m_pkthdr +and the per-packet attributes from the +.Vt mbuf chain +.Fa from +to the +.Vt mbuf +.Fa to . +The +.Vt mbuf +.Fa from +must have the flag +.Dv M_PKTHDR +initially set, and +.Fa to +must be empty on entry. +Upon the function's completion, +.Fa from +will have the flag +.Dv M_PKTHDR +and the per-packet attributes cleared. +.\" +.It Fn m_fixhdr mbuf +Set the packet-header length to the length of the +.Vt mbuf chain . +.\" +.It Fn m_devget buf len offset ifp copy +Copy data from a device local memory pointed to by +.Fa buf +to an +.Vt mbuf chain . +The copy is done using a specified copy routine +.Fa copy , +or +.Fn bcopy +if +.Fa copy +is +.Dv NULL . +.\" +.It Fn m_cat m n +Concatenate +.Fa n +to +.Fa m . +Both +.Vt mbuf chains +must be of the same type. +.Fa n +is not guaranteed to be valid after +.Fn m_cat +returns. +.Fn m_cat +does not update any packet header fields or free mbuf tags. +.\" +.It Fn m_catpkt m n +A variant of +.Fn m_cat +that operates on packets. +Both +.Fa m +and +.Fa n +must contain packet headers. +.Fa n +is not guaranteed to be valid after +.Fn m_catpkt +returns. +.\" +.It Fn m_split mbuf len how +Partition an +.Vt mbuf chain +in two pieces, returning the tail: +all but the first +.Fa len +bytes. +In case of failure, it returns +.Dv NULL +and attempts to restore the +.Vt mbuf chain +to its original state. +.\" +.It Fn m_apply mbuf off len f arg +Apply a function to an +.Vt mbuf chain , +at offset +.Fa off , +for length +.Fa len +bytes. +Typically used to avoid calls to +.Fn m_pullup +which would otherwise be unnecessary or undesirable. +.Fa arg +is a convenience argument which is passed to the callback function +.Fa f . +.Pp +Each time +.Fn f +is called, it will be passed +.Fa arg , +a pointer to the +.Fa data +in the current mbuf, and the length +.Fa len +of the data in this mbuf to which the function should be applied. +.Pp +The function should return zero to indicate success; +otherwise, if an error is indicated, then +.Fn m_apply +will return the error and stop iterating through the +.Vt mbuf chain . +.\" +.It Fn m_getptr mbuf loc off +Return a pointer to the mbuf containing the data located at +.Fa loc +bytes from the beginning of the +.Vt mbuf chain . +The corresponding offset into the mbuf will be stored in +.Fa *off . +.It Fn m_defrag m0 how +Defragment an mbuf chain, returning the shortest possible +chain of mbufs and clusters. +If allocation fails and this can not be completed, +.Dv NULL +will be returned and the original chain will be unchanged. +Upon success, the original chain will be freed and the new +chain will be returned. +.Fa how +should be either +.Dv M_WAITOK +or +.Dv M_NOWAIT , +depending on the caller's preference. +.Pp +This function is especially useful in network drivers, where +certain long mbuf chains must be shortened before being added +to TX descriptor lists. +.It Fn m_collapse m0 how maxfrags +Defragment an mbuf chain, returning a chain of at most +.Fa maxfrags +mbufs and clusters. +If allocation fails or the chain cannot be collapsed as requested, +.Dv NULL +will be returned, with the original chain possibly modified. +As with +.Fn m_defrag , +.Fa how +should be one of +.Dv M_WAITOK +or +.Dv M_NOWAIT . +.It Fn m_unshare m0 how +Create a version of the specified mbuf chain whose +contents can be safely modified without affecting other users. +If allocation fails and this operation can not be completed, +.Dv NULL +will be returned. +The original mbuf chain is always reclaimed and the reference +count of any shared mbuf clusters is decremented. +.Fa how +should be either +.Dv M_WAITOK +or +.Dv M_NOWAIT , +depending on the caller's preference. +As a side-effect of this process the returned +mbuf chain may be compacted. +.Pp +This function is especially useful in the transmit path of +network code, when data must be encrypted or otherwise +altered prior to transmission. +.El +.Sh HARDWARE-ASSISTED CHECKSUM CALCULATION +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 +.Va m_pkthdr +member of the leading +.Vt mbuf +of a packet contains two fields used for that purpose, +.Vt int Va csum_flags +and +.Vt int Va csum_data . +The meaning of those fields depends on whether the packet is fragmented. +Henceforth, +.Va csum_flags +or +.Va csum_data +of a packet +will denote the corresponding field of the +.Va m_pkthdr +member of the leading +.Vt mbuf +in the +.Vt mbuf chain +containing the packet. +.Pp +When a packet is sent by SCTP, TCP, or UDP, 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 +(see +.Xr ifnet 9 ) +is consulted by IP for the capabilities of the network interface selected for +output to assist in computing checksums. +The +.Va csum_flags +field of the packet header is set to indicate which actions the interface +is supposed to perform on it. +The actions unsupported by the network interface are done in the +software prior to passing the packet down to the interface driver; +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_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.) +.It Dv CSUM_UDP +The UDP checksum is to be computed. +(See below.) +.El +.Pp +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 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 +When a packet is received by an interface, it indicates the actions it has +performed on a packet by setting one or more of the following flags in +.Va csum_flags +associated with the packet: +.Bl -tag -width ".Dv CSUM_IP_CHECKED" -offset indent +.It Dv CSUM_IP_CHECKED +The IP header checksum has been computed. +.It Dv CSUM_IP_VALID +The IP header has a valid checksum. +This flag can appear only in combination with +.Dv CSUM_IP_CHECKED . +.It Dv CSUM_DATA_VALID +The checksum of the data portion of the IP packet has been computed +and stored in the field +.Va csum_data +in network byte order. +.It Dv CSUM_PSEUDO_HDR +Can be set only along with +.Dv CSUM_DATA_VALID +to indicate that the IP data checksum found in +.Va csum_data +allows for the pseudo header defined by the TCP and UDP specifications. +Otherwise the checksum of the pseudo header must be calculated by +the host CPU and added to +.Va csum_data +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 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 +in +.Va csum_flags +as well as, for TCP and UDP, +.Dv CSUM_PSEUDO_HDR +and set +.Va csum_data +to +.Li 0xFFFF +hexadecimal to indicate a valid checksum. +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. +.Pp +If IP delivers a packet with the flags +.Dv CSUM_IP , +.Dv CSUM_SCTP , +.Dv CSUM_TCP , +or +.Dv CSUM_UDP +set in +.Va csum_flags +to a local IP, SCTP, TCP, or UDP stack, the packet will be processed without +computing or validating the checksum, since the packet has not been on the +wire. +This can happen if the packet was handled by a virtual interface such as +.Xr tap 4 +or +.Xr epair 4 . +.Sh STRESS TESTING +When running a kernel compiled with the option +.Dv MBUF_STRESS_TEST , +the following +.Xr sysctl 8 Ns +-controlled options may be used to create +various failure/extreme cases for testing of network drivers +and other parts of the kernel that rely on +.Vt mbufs . +.Bl -tag -width indent +.It Va net.inet.ip.mbuf_frag_size +Causes +.Fn ip_output +to fragment outgoing +.Vt mbuf chains +into fragments of the specified size. +Setting this variable to 1 is an excellent way to +test the long +.Vt mbuf chain +handling ability of network drivers. +.It Va kern.ipc.m_defragrandomfailures +Causes the function +.Fn m_defrag +to randomly fail, returning +.Dv NULL . +Any piece of code which uses +.Fn m_defrag +should be tested with this feature. +.El +.Sh RETURN VALUES +See above. +.Sh SEE ALSO +.Xr ifnet 9 , +.Xr mbuf_tags 9 +.Rs +.\" 4.4BSD SMM:18 +.%A S. J. Leffler +.%A W. N. Joy +.%A R. S. Fabry +.%A M. J. Karels +.%T Networking Implementation Notes +.%B 4.4BSD System Manager's Manual (SMM) +.Re +.Sh HISTORY +.\" Please correct me if I'm wrong +.Vt Mbufs +appeared in an early version of +.Bx . +Besides being used for network packets, they were used +to store various dynamic structures, such as routing table +entries, interface addresses, protocol control blocks, etc. +In more recent +.Fx +use of +.Vt mbufs +is almost entirely limited to packet storage, with +.Xr uma 9 +zones being used directly to store other network-related memory. +.Pp +Historically, the +.Vt mbuf +allocator has been a special-purpose memory allocator able to run in +interrupt contexts and allocating from a special kernel address space map. +As of +.Fx 5.3 , +the +.Vt mbuf +allocator is a wrapper around +.Xr uma 9 , +allowing caching of +.Vt mbufs , +clusters, and +.Vt mbuf ++ cluster pairs in per-CPU caches, as well as bringing other benefits of +slab allocation. +.Sh AUTHORS +The original +.Nm +manual page was written by +.An Yar Tikhiy . +The +.Xr uma 9 +.Vt mbuf +allocator was written by +.An Bosko Milekic . diff --git a/static/freebsd/man9/mbuf_tags.9 b/static/freebsd/man9/mbuf_tags.9 new file mode 100644 index 00000000..834b1eb0 --- /dev/null +++ b/static/freebsd/man9/mbuf_tags.9 @@ -0,0 +1,284 @@ +.\" $OpenBSD: mbuf_tags.9,v 1.18 2003/12/08 07:07:35 mcbride Exp $ +.\" +.\" The authors of this manual page are Angelos D. Keromytis +.\" (angelos@cis.upenn.edu), Gleb Smirnoff , and +.\" Robert Watson +.\" +.\" Copyright (c) 2004 Robert N. M. Watson +.\" Copyright (c) 2001 Angelos D. Keromytis +.\" +.\" Permission to use, copy, and modify this software with or without +.\" fee is hereby granted, provided that this entire notice is included +.\" in all source code copies of any software which is or includes a copy +.\" or modification of this software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR +.\" IMPLIED WARRANTY. IN PARTICULAR, NONE OF THE AUTHORS MAKES ANY +.\" REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE +.\" MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR +.\" PURPOSE. +.\" +.Dd December 28, 2021 +.Dt MBUF_TAGS 9 +.Os +.Sh NAME +.Nm mbuf_tags +.Nd a framework for generic packet attributes +.Sh SYNOPSIS +.In sys/mbuf.h +.Ft "struct m_tag *" +.Fn m_tag_alloc "uint32_t cookie" "uint16_t type" "int len" "int wait" +.Ft "struct m_tag *" +.Fn m_tag_copy "struct m_tag *t" "int how" +.Ft int +.Fn m_tag_copy_chain "struct mbuf *to" "const struct mbuf *from" "int how" +.Ft void +.Fn m_tag_delete "struct mbuf *m" "struct m_tag *t" +.Ft void +.Fn m_tag_delete_chain "struct mbuf *m" "struct m_tag *t" +.Ft void +.Fn m_tag_delete_nonpersistent "struct mbuf *m" +.Ft "struct m_tag *" +.Fn m_tag_find "struct mbuf *m" "uint16_t type" "struct m_tag *start" +.Ft "struct m_tag *" +.Fn m_tag_first "struct mbuf *m" +.Ft void +.Fn m_tag_free "struct m_tag *t" +.Ft "struct m_tag *" +.Fn m_tag_get "uint16_t type" "int len" "int wait" +.Ft void +.Fn m_tag_init "struct mbuf *m" +.Ft struct m_tag * +.Fn m_tag_locate "struct mbuf *m" "uint32_t cookie" "uint16_t type" "struct m_tag *t" +.Ft "struct m_tag *" +.Fn m_tag_next "struct mbuf *m" "struct m_tag *t" +.Ft void +.Fn m_tag_prepend "struct mbuf *m" "struct m_tag *t" +.Ft void +.Fn m_tag_unlink "struct mbuf *m" "struct m_tag *t" +.Sh DESCRIPTION +Mbuf tags allow additional meta-data to be associated with in-flight packets +by providing a mechanism for the tagging of additional kernel memory onto +packet header mbufs. +Tags are maintained in chains off of the +.Xr mbuf 9 +header, and maintained using a series of API calls to allocate, search, and +delete tags. +Tags are identified using an ID and cookie that uniquely identify a class +of data tagged onto the packet, and may contain an arbitrary amount of +additional storage. +Typical uses of mbuf tags include Mandatory Access Control (MAC) labels as +described in +.Xr mac 9 , +IPsec policy information as described in +.Xr ipsec 4 , +and packet filter tags used by +.Xr pf 4 . +.Pp +Tags will be maintained across a variety of operations, including the copying +of packet headers using facilities such as +.Fn M_COPY_PKTHDR +and +.Fn M_MOVE_PKTHDR . +Any tags associated with an mbuf header will be automatically freed when the +mbuf is freed, although some subsystems will wish to delete the tags prior +to that time. +.Pp +Packet tags are used by different kernel APIs +to keep track of operations done or +scheduled to happen to packets. +Each packet tag can be distinguished by its type and cookie. +The cookie is used to identify a specific module or API. +The packet tags are attached to mbuf packet headers. +.Pp +The first +.Fn sizeof "struct m_tag" +bytes of a tag contain a +.Vt "struct m_tag" : +.Bd -literal +struct m_tag { + SLIST_ENTRY(m_tag) m_tag_link; /* List of packet tags */ + uint16_t m_tag_id; /* Tag ID */ + uint16_t m_tag_len; /* Length of data */ + uint32_t m_tag_cookie; /* ABI/Module ID */ + void (*m_tag_free)(struct m_tag *); +}; +.Ed +.Pp +The +.Va m_tag_link +field is used to link tags together (see +.Xr queue 3 +for more details). +The +.Va m_tag_id , m_tag_len +and +.Va m_tag_cookie +fields are set to type, length, +and +cookie, respectively. +.Va m_tag_free +points to +.Fn m_tag_free_default . +Following this structure are +.Va m_tag_len +bytes of space that can be used to store tag-specific information. +Addressing this data region may be tricky. +A safe way is embedding +.Vt "struct m_tag" +into a private data structure, as follows: +.Bd -literal -offset indent +struct foo { + struct m_tag tag; + ... +}; +struct foo *p = (struct foo *)m_tag_alloc(...); +struct m_tag *mtag = &p->tag; +.Ed +.Pp +Note that +.Ox +does not support cookies, it needs +.Va m_tag_id +to be globally unique. +To keep compatibility with +.Ox , +a cookie +.Dv MTAG_ABI_COMPAT +is provided along with some compatibility functions. +When writing an +.Ox +compatible code, one should be careful not to take already +used tag type. +Tag types are defined in +.In sys/mbuf.h . +.Ss Packet Tag Manipulation Functions +.Bl -ohang -offset indent +.It Fn m_tag_alloc cookie type len wait +Allocate a new tag of type +.Fa type +and cookie +.Fa cookie +with +.Va len +bytes of space following the tag header itself. +The +.Fa wait +argument is passed directly to +.Xr malloc 9 . +If successful, +.Fn m_tag_alloc +returns a memory buffer of +.Pq Va len No + Fn sizeof "struct m_tag" +bytes. +Otherwise, +.Dv NULL +is returned. +A compatibility function +.Fn m_tag_get +is also provided. +.It Fn m_tag_copy tag how +Allocate a copy of +.Fa tag . +The +.Fa how +argument is passed directly to +.Fn m_tag_alloc . +The return values are the same as in +.Fn m_tag_alloc . +.It Fn m_tag_copy_chain tombuf frommbuf how +Allocate and copy all tags from mbuf +.Fa frommbuf +to mbuf +.Fa tombuf . +Returns 1 on success, and 0 on failure. +In the latter case, mbuf +.Fa tombuf +loses all its tags, even previously present. +.It Fn m_tag_delete mbuf tag +Remove +.Fa tag +from +.Fa mbuf Ns 's +list and free it. +.It Fn m_tag_delete_chain mbuf tag +Remove and free a packet tag chain, starting from +.Fa tag . +If +.Fa tag +is +.Dv NULL , +all tags are deleted. +.It Fn m_tag_delete_nonpersistent mbuf +Traverse +.Fa mbuf Ns 's +tags and delete those which do not have the +.Dv MTAG_PERSISTENT +flag set. +.It Fn m_tag_first mbuf +Return the first tag associated with +.Fa mbuf . +.It Fn m_tag_free tag +Free +.Fa tag +using its +.Va m_tag_free +method. +The +.Fn m_tag_free_default +function +is used by default. +.It Fn m_tag_init mbuf +Initialize the tag storage for packet +.Fa mbuf . +.It Fn m_tag_locate mbuf cookie type tag +Search for a tag defined by +.Fa type +and +.Fa cookie +in +.Fa mbuf , +starting from position specified by +.Fa tag . +If the latter is +.Dv NULL , +then search through the whole list. +Upon success, a pointer to the first found tag is returned. +In either case, +.Dv NULL +is returned. +A compatibility function +.Fn m_tag_find +is also provided. +.It Fn m_tag_next mbuf tag +Return tag next to +.Fa tag +in +.Fa mbuf . +If absent, +.Dv NULL +is returned. +.It Fn m_tag_prepend mbuf tag +Add the new tag +.Fa tag +at the head of the tag list for packet +.Fa mbuf . +.It Fn m_tag_unlink mbuf tag +Remove tag +.Fa tag +from the list of tags of packet +.Fa mbuf . +.El +.Sh CODE REFERENCES +The tag-manipulating code is contained in the file +.Pa sys/kern/uipc_mbuf2.c . +Inlined functions are defined in +.In sys/mbuf.h . +.Sh SEE ALSO +.Xr queue 3 , +.Xr mbuf 9 +.Sh HISTORY +The packet tags first appeared in +.Ox 2.9 +and were written by +.An Angelos D. Keromytis Aq Mt angelos@openbsd.org . diff --git a/static/freebsd/man9/mdchain.9 b/static/freebsd/man9/mdchain.9 new file mode 100644 index 00000000..d799775f --- /dev/null +++ b/static/freebsd/man9/mdchain.9 @@ -0,0 +1,209 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2001 Boris Popov +.\" +.\" 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 February 28, 2001 +.Dt MDCHAIN 9 +.Os +.Sh NAME +.Nm mdchain , +.Nm md_initm , +.Nm md_done , +.Nm md_append_record , +.Nm md_next_record , +.Nm md_get_uint8 , +.Nm md_get_uint16 , +.Nm md_get_uint16be , +.Nm md_get_uint16le , +.Nm md_get_uint32 , +.Nm md_get_uint32be , +.Nm md_get_uint32le , +.Nm md_get_int64 , +.Nm md_get_int64be , +.Nm md_get_int64le , +.Nm md_get_mem , +.Nm md_get_mbuf , +.Nm md_get_uio +.Nd "set of functions to dissect an mbuf chain to various data types" +.Sh SYNOPSIS +.Cd options LIBMCHAIN +.Li kldload libmchain +.Pp +.In sys/param.h +.In sys/uio.h +.In sys/mchain.h +.Ft void +.Fn md_initm "struct mdchain *mdp" "struct mbuf *m" +.Ft void +.Fn md_done "struct mdchain *mdp" +.Ft void +.Fn md_append_record "struct mdchain *mdp" "struct mbuf *top" +.Ft int +.Fn md_next_record "struct mdchain *mdp" +.Ft int +.Fn md_get_uint8 "struct mdchain *mdp" "uint8_t *x" +.Ft int +.Fn md_get_uint16 "struct mdchain *mdp" "uint16_t *x" +.Ft int +.Fn md_get_uint16be "struct mdchain *mdp" "uint16_t *x" +.Ft int +.Fn md_get_uint16le "struct mdchain *mdp" "uint16_t *x" +.Ft int +.Fn md_get_uint32 "struct mdchain *mdp" "uint32_t *x" +.Ft int +.Fn md_get_uint32be "struct mdchain *mdp" "uint32_t *x" +.Ft int +.Fn md_get_uint32le "struct mdchain *mdp" "uint32_t *x" +.Ft int +.Fn md_get_int64 "struct mdchain *mdp" "int64_t *x" +.Ft int +.Fn md_get_int64be "struct mdchain *mdp" "int64_t *x" +.Ft int +.Fn md_get_int64le "struct mdchain *mdp" "int64_t *x" +.Ft int +.Fn md_get_mem "struct mdchain *mdp" "caddr_t target" "int size" "int type" +.Ft int +.Fn md_get_mbuf "struct mdchain *mdp" "int size" "struct mbuf **m" +.Ft int +.Fn md_get_uio "struct mdchain *mdp" "struct uio *uiop" "int size" +.Sh DESCRIPTION +These functions are used to decompose mbuf chains to various data types. +The +.Vt mdchain +structure is used as a working context +and should be initialized through a call of the +.Fn mb_initm +function. +It has the following fields: +.Bl -tag -width "md_top" +.It Va "md_top" +.Pq Vt "struct mbuf *" +A pointer to the top of the parsed mbuf chain. +.It Va md_cur +.Pq Vt "struct mbuf *" +A pointer to the currently parsed mbuf. +.It Va md_pas +.Pq Vt int +Offset in the current mbuf. +.El +.Pp +The +.Fn md_done +function disposes of an mbuf chain pointed to by the +.Fa mdp->md_top +field and sets the field to +.Dv NULL . +.Pp +The +.Fn md_append_record +appends a new mbuf chain using +.Va m_nextpkt +field to form a single linked list of mbuf chains. +If the +.Fa mdp->md_top +field is +.Dv NULL , +then this function behaves exactly as the +.Fn md_initm +function. +.Pp +The +.Fn md_next_record +function extracts the next mbuf chain and disposes the current one, if any. +For a new mbuf chain it calls the +.Fn md_initm +function. +If there is no data left the function returns +.Er ENOENT . +.Pp +All +.Fn md_get_* +functions perform an actual copy of the data from an mbuf chain. +Functions which have +.Cm le +or +.Cm be +suffixes will perform conversion to the little\- or big\-endian data formats. +.Pp +.Fn md_get_mem +function copies +.Fa size +bytes of data specified by the +.Fa source +argument from an mbuf chain. +The +.Fa type +argument specifies the method used to perform a copy, +and can be one of the following: +.Bl -tag -width ".Dv MB_MINLINE" +.It Dv MB_MSYSTEM +Use the +.Fn bcopy +function. +.It Dv MB_MUSER +Use the +.Xr copyin 9 +function. +.It Dv MB_MINLINE +Use an +.Dq inline +loop which does not call any function. +.El +.Pp +If +.Fa target +is +.Dv NULL , +an actual copy is not performed +and the function just skips the given number of bytes. +.Sh RETURN VALUES +All +.Ft int +functions return zero if successful, +otherwise an error code is returned. +.Pp +.Em Note : +after failure of any function, +an mbuf chain is left in the broken state and only the +.Fn md_done +function can safely be called to destroy it. +.Sh EXAMPLES +.Bd -literal +struct mdchain *mdp; +struct mbuf *m; +uint16_t length; +uint8_t byte; + +receive(so, &m); +md_initm(mdp, m); +if (md_get_uint8(mdp, &byte) != 0 || + md_get_uint16le(mdp, &length) != 0) + error = EBADRPC; +mb_done(mdp); +.Ed +.Sh SEE ALSO +.Xr mbchain 9 , +.Xr mbuf 9 +.Sh AUTHORS +This manual page was written by +.An Boris Popov Aq Mt bp@FreeBSD.org . diff --git a/static/freebsd/man9/memcchr.9 b/static/freebsd/man9/memcchr.9 new file mode 100644 index 00000000..ce0e9cda --- /dev/null +++ b/static/freebsd/man9/memcchr.9 @@ -0,0 +1,57 @@ +.\" Copyright (c) 2012 Ed Schouten +.\" 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 January 1, 2012 +.Dt MEMCCHR 9 +.Os +.Sh NAME +.Nm memcchr +.Nd locate the complement of a byte in byte string +.Sh SYNOPSIS +.In sys/libkern.h +.Ft void * +.Fn memcchr "const void *b" "int c" "size_t len" +.Sh DESCRIPTION +The +.Fn memcchr +function locates the first occurrence of a byte unequal to +.Fa c +(converted to an +.Vt "unsigned char" ) +in string +.Fa b . +.Sh RETURN VALUES +The +.Fn memcchr +function returns a pointer to the byte located, or NULL if no such byte +exists within +.Fa len +bytes. +.Sh SEE ALSO +.Xr memchr 3 +.Sh HISTORY +The +.Fn memcchr +function first appeared in +.Fx 10.0 . diff --git a/static/freebsd/man9/memguard.9 b/static/freebsd/man9/memguard.9 new file mode 100644 index 00000000..61b04782 --- /dev/null +++ b/static/freebsd/man9/memguard.9 @@ -0,0 +1,204 @@ +.\" Copyright (c) 2005 Christian Brueffer +.\" 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 March 22, 2017 +.Dt MEMGUARD 9 +.Os +.Sh NAME +.Nm MemGuard +.Nd "memory allocator for debugging purposes" +.Sh SYNOPSIS +.Cd "options DEBUG_MEMGUARD" +.Sh DESCRIPTION +.Nm +is a simple and small replacement memory allocator designed +to help detect tamper-after-free scenarios. +These problems are more and more common and likely with +multithreaded kernels where race conditions are more prevalent. +.Pp +.Nm +can take over +.Fn malloc , +.Fn realloc +and +.Fn free +for a single malloc type. +Alternatively +.Nm +can take over +.Fn uma_zalloc , +.Fn uma_zalloc_arg +and +.Fn uma_free +for a single +.Xr uma 9 +zone. +Also +.Nm +can guard all allocations larger than +.Dv PAGE_SIZE , +and can guard a random fraction of all allocations. +There is also a knob to prevent allocations smaller than a specified +size from being guarded, to limit memory waste. +.Sh EXAMPLES +To use +.Nm +for a memory type, either add an entry to +.Pa /boot/loader.conf : +.Bd -literal -offset indent +vm.memguard.desc= +.Ed +.Pp +Or set the +.Va vm.memguard.desc +.Xr sysctl 8 +variable at run-time: +.Bd -literal -offset indent +sysctl vm.memguard.desc= +.Ed +.Pp +Where +.Ar memory_type +can be either a short description of the memory type to monitor, +either name of +.Xr uma 9 +zone. +Only allocations from that +.Ar memory_type +made after +.Va vm.memguard.desc +is set will potentially be guarded. +If +.Va vm.memguard.desc +is modified at run-time then only allocations of the new +.Ar memory_type +will potentially be guarded once the +.Xr sysctl 8 +is set. +Existing guarded allocations will still be properly released by +either +.Xr free 9 +or +.Xr uma_zfree 9 , +depending on what kind of allocation was taken over. +.Pp +To determine short description of a +.Xr malloc 9 +type one can either take it from the first column of +.Xr vmstat 8 Fl m +output, or to find it in the kernel source. +It is the second argument to +.Xr MALLOC_DEFINE 9 +macro. +To determine name of +.Xr uma 9 +zone one can either take it from the first column of +.Xr vmstat 8 Fl z +output, or to find it in the kernel source. +It is the first argument to the +.Xr uma_zcreate 9 +function. +.Pp +The +.Va vm.memguard.divisor +boot-time tunable is used to scale how much of the system's physical +memory +.Nm +is allowed to consume. +The default is 10, so up to +.Va vm_cnt.v_page_count Ns /10 +pages can be used. +.Nm +will reserve +.Va vm_kmem_max +/ +.Va vm.memguard.divisor +bytes of virtual address space, limited by twice the physical memory +size. +The physical limit is reported as +.Va vm.memguard.phys_limit +and the virtual space reserved for +.Nm +is reported as +.Va vm.memguard.mapsize . +.Pp +.Nm +will not do page promotions for any allocation smaller than +.Va vm.memguard.minsize +bytes. +The default is 0, meaning all allocations can potentially be guarded. +.Nm +can guard sufficiently large allocations randomly, with average +frequency of every one in 100000 / +.Va vm.memguard.frequency +allocations. +The default is 0, meaning no allocations are randomly guarded. +.Pp +.Nm +can optionally add unmapped guard pages around each allocation to +detect overflow and underflow, if +.Va vm.memguard.options +has the 1 bit set. +This option is enabled by default. +.Nm +will optionally guard all allocations of +.Dv PAGE_SIZE +or larger if +.Va vm.memguard.options +has the 2 bit set. +This option is off by default. +By default +.Nm +does not guard +.Xr uma 9 +zones that have been initialized with the +.Dv UMA_ZONE_NOFREE +flag set, since it can produce false positives on them. +However, this safety measure can be turned off by setting bit 3 +of the +.Va vm.memguard.options +tunable. +.Sh SEE ALSO +.Xr sysctl 8 , +.Xr vmstat 8 , +.Xr contigmalloc 9 , +.Xr malloc 9 , +.Xr redzone 9 , +.Xr uma 9 +.Sh HISTORY +.Nm +first appeared in +.Fx 6.0 . +.Sh AUTHORS +.An -nosplit +.Nm +was originally written by +.An Bosko Milekic Aq Mt bmilekic@FreeBSD.org . +This manual page was originally written by +.An Christian Brueffer Aq Mt brueffer@FreeBSD.org . +Additions have been made by +.An Matthew Fleming Aq Mt mdf@FreeBSD.org +and +.An Gleb Smirnoff Aq Mt glebius@FreeBSD.org +to both the implementation and the documentation. diff --git a/static/freebsd/man9/mi_switch.9 b/static/freebsd/man9/mi_switch.9 new file mode 100644 index 00000000..e04c2ee3 --- /dev/null +++ b/static/freebsd/man9/mi_switch.9 @@ -0,0 +1,174 @@ +.\" $NetBSD: ctxsw.9,v 1.2 1996/12/02 00:11:31 tls Exp $ +.\" +.\" Copyright (c) 1996 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" Copyright (c) 2023 The FreeBSD Foundation +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Paul Kranenburg. +.\" +.\" Portions of this documentation were written by Mitchell Horne +.\" under sponsorship from the FreeBSD Foundation. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 REGENTS OR CONTRIBUTORS BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 7, 2025 +.Dt MI_SWITCH 9 +.Os +.Sh NAME +.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" +.Sh DESCRIPTION +The +.Fn mi_switch +function implements the machine-independent prelude to a thread context +switch. +It is the single entry point for every context switch and is called from only +a few distinguished places in the kernel. +The context switch is, by necessity, always performed by the switched thread, +even when the switch is initiated from elsewhere; e.g. preemption requested via +Inter-Processor Interrupt (IPI). +.Pp +The various major uses of +.Fn mi_switch +can be enumerated as follows: +.Bl -enum -offset indent +.It +From within a function such as +.Xr sleepq_wait 9 +or +.Fn turnstile_wait +when the current thread +voluntarily relinquishes the CPU to wait for some resource or lock to become +available. +.It +Involuntary preemption due to arrival of a higher-priority thread. +.It +At the tail end of +.Xr critical_exit 9 , +if preemption was deferred due to the critical section. +.It +Within the TDA_SCHED AST handler, when rescheduling before the return to +usermode was requested. +There are several reasons for this, a notable one coming from +.Fn sched_clock +when the running thread has exceeded its time slice. +.It +In the signal handling code +(see +.Xr issignal 9 ) +if a signal is delivered that causes a process to stop. +.It +In +.Fn thread_suspend_check +where a thread needs to stop execution due to the suspension state of +the process as a whole. +.It +In +.Xr kern_yield 9 +when a thread wants to voluntarily relinquish the processor. +.El +.Pp +The +.Va flags +argument to +.Fn mi_switch +indicates the context switch type. +One of the following must be passed: +.Bl -tag -offset indent -width "SWT_REMOTEWAKEIDLE" +.It Dv SWT_OWEPREEMPT +Switch due to delayed preemption after exiting a critical section. +.It Dv SWT_TURNSTILE +Switch after propagating scheduling priority to the owner of a resource. +.It Dv SWT_SLEEPQ +Begin waiting on a +.Xr sleepqueue 9 . +.It Dv SWT_RELINQUISH +Yield call. +.It Dv SWT_NEEDRESCHED +Rescheduling was requested. +.It Dv SWT_IDLE +Switch from the idle thread. +.It Dv SWT_IWAIT +A kernel thread which handles interrupts has finished work and must wait for +interrupts to schedule additional work. +.It Dv SWT_SUSPEND +Thread suspended. +.It Dv SWT_REMOTEPREEMPT +Preemption by a higher-priority thread, initiated by a remote processor. +.It Dv SWT_REMOTEWAKEIDLE +Idle thread preempted, initiated by a remote processor. +.It Dv SWT_BIND +The running thread has been bound to another processor and must be switched +out. +.El +.Pp +In addition to the switch type, callers must specify the nature of the +switch by performing a bitwise OR with one of the +.Dv SW_VOL +or +.Dv SW_INVOL +flags, but not both. +Respectively, these flags denote whether the context switch is voluntary or +involuntary on the part of the current thread. +For an involuntary context switch in which the running thread is +being preempted, the caller should also pass the +.Dv SW_PREEMPT +flag. +.Pp +Upon entry to +.Fn mi_switch , +the current thread must be holding its assigned thread lock. +It may be unlocked as part of the context switch. +After they have been rescheduled and execution resumes, threads will exit +.Fn mi_switch +with their thread lock unlocked. +.Pp +.Fn mi_switch +records the amount of time the current thread has been running before handing +control over to the scheduler, via +.Fn sched_switch . +After selecting a new thread to run, the scheduler will call +.Fn cpu_switch +to perform the low-level context switch. +.Pp +.Fn cpu_switch +is the machine-dependent function that performs the actual switch from the +running thread +.Fa oldtd +to the chosen thread +.Fa newtd . +.Sh SEE ALSO +.Xr cpu_switch 9 , +.Xr cpu_throw 9 , +.Xr critical_exit 9 , +.Xr issignal 9 , +.Xr kern_yield 9 , +.Xr mutex 9 , +.Xr pmap 9 , +.Xr sleepqueue 9 , +.Xr thread_exit 9 diff --git a/static/freebsd/man9/microseq.9 b/static/freebsd/man9/microseq.9 new file mode 100644 index 00000000..06e3ebdd --- /dev/null +++ b/static/freebsd/man9/microseq.9 @@ -0,0 +1,491 @@ +.\" Copyright (c) 1998, 1999, Nicolas Souchu +.\" 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 June 6, 1998 +.Dt MICROSEQ 9 +.Os +.Sh NAME +.Nm microseq +.Nd ppbus microsequencer developer's guide +.Sh SYNOPSIS +.In sys/types.h +.In dev/ppbus/ppbconf.h +.In dev/ppbus/ppb_msq.h +.Sh DESCRIPTION +See +.Xr ppbus 4 +for ppbus description and general info about the microsequencer. +.Pp +The purpose of this document is to encourage developers to use the +microsequencer mechanism in order to have: +.Bl -enum -offset indent +.It +a uniform programming model +.It +efficient code +.El +.Pp +Before using microsequences, you are encouraged to look at +.Xr ppc 4 +microsequencer implementation and an example of how using it in +.Xr ppi 4 . +.Sh PPBUS register model +.Ss Background +The parallel port model chosen for ppbus is the PC parallel port model. +Thus, any register described later has the same semantic than its counterpart +in a PC parallel port. +For more info about ISA/ECP programming, get the +Microsoft standard referenced as "Extended Capabilities Port Protocol and +ISA interface Standard". +Registers described later are standard parallel port +registers. +.Pp +Mask macros are defined in the standard ppbus include files for each valid +bit of parallel port registers. +.Ss Data register +In compatible or nibble mode, writing to this register will drive data to the +parallel port data lines. +In any other mode, drivers may be tri-stated by +setting the direction bit (PCD) in the control register. +Reads to this register +return the value on the data lines. +.Ss Device status register +This read-only register reflects the inputs on the parallel port interface. +.Pp +.Bl -column "Bit" "Name" "Description" -compact +.It Em Bit Ta Em Name Ta Em Description +.It 7 Ta nBUSY Ta "inverted version of parallel port Busy signal" +.It 6 Ta nACK Ta "version of parallel port nAck signal" +.It 5 Ta PERROR Ta "version of parallel port PERROR signal" +.It 4 Ta SELECT Ta "version of parallel port Select signal" +.It 3 Ta nFAULT Ta "version of parallel port nFault signal" +.El +.Pp +Others are reserved and return undefined result when read. +.Ss Device control register +This register directly controls several output signals as well as enabling +some functions. +.Pp +.Bl -column "Bit" "Name " "Description" -compact +.It Em Bit Ta Em Name Ta Em Description +.It 5 Ta PCD Ta "direction bit in extended modes" +.It 4 Ta IRQENABLE Ta "1 enables an interrupt on the rising edge of nAck" +.It 3 Ta SELECTIN Ta "inverted and driven as parallel port nSelectin signal" +.It 2 Ta nINIT Ta "driven as parallel port nInit signal" +.It 1 Ta AUTOFEED Ta "inverted and driven as parallel port nAutoFd signal" +.It 0 Ta STROBE Ta "inverted and driven as parallel port nStrobe signal" +.El +.Sh MICROINSTRUCTIONS +.Ss Description +.Em Microinstructions +are either parallel port accesses, program iterations, submicrosequence or +C calls. +The parallel port must be considered as the logical model described in +.Xr ppbus 4 . +.Pp +Available microinstructions are: +.Bd -literal +#define MS_OP_GET 0 /* get , */ +#define MS_OP_PUT 1 /* put , */ +#define MS_OP_RFETCH 2 /* rfetch , , */ +#define MS_OP_RSET 3 /* rset , , */ +#define MS_OP_RASSERT 4 /* rassert , */ +#define MS_OP_DELAY 5 /* delay */ +#define MS_OP_SET 6 /* set */ +#define MS_OP_DBRA 7 /* dbra */ +#define MS_OP_BRSET 8 /* brset , */ +#define MS_OP_BRCLEAR 9 /* brclear , */ +#define MS_OP_RET 10 /* ret */ +#define MS_OP_C_CALL 11 /* c_call , */ +#define MS_OP_PTR 12 /* ptr */ +#define MS_OP_ADELAY 13 /* adelay */ +#define MS_OP_BRSTAT 14 /* brstat , , */ +#define MS_OP_SUBRET 15 /* subret */ +#define MS_OP_CALL 16 /* call */ +#define MS_OP_RASSERT_P 17 /* rassert_p , */ +#define MS_OP_RFETCH_P 18 /* rfetch_p , , */ +#define MS_OP_TRIG 19 /* trigger , , */ +.Ed +.Ss Execution context +The +.Em execution context +of microinstructions is: +.Bl -bullet -offset indent +.It +the +.Em program counter +which points to the next microinstruction to execute either in the main +microsequence or in a subcall +.It +the current value of +.Em ptr +which points to the next char to send/receive +.It +the current value of the internal +.Em branch register +.El +.Pp +This data is modified by some of the microinstructions, not all. +.Ss MS_OP_GET and MS_OP_PUT +are microinstructions used to do either predefined standard IEEE1284-1994 +transfers or programmed non-standard io. +.Ss MS_OP_RFETCH - Register FETCH +is used to retrieve the current value of a parallel port register, apply a +mask and save it in a buffer. +.Pp +Parameters: +.Bl -enum -offset indent +.It +register +.It +character mask +.It +pointer to the buffer +.El +.Pp +Predefined macro: MS_RFETCH(reg,mask,ptr) +.Ss MS_OP_RSET - Register SET +is used to assert/clear some bits of a particular parallel port register, +two masks are applied. +.Pp +Parameters: +.Bl -enum -offset indent +.It +register +.It +mask of bits to assert +.It +mask of bits to clear +.El +.Pp +Predefined macro: MS_RSET(reg,assert,clear) +.Ss MS_OP_RASSERT - Register ASSERT +is used to assert all bits of a particular parallel port register. +.Pp +Parameters: +.Bl -enum -offset indent +.It +register +.It +byte to assert +.El +.Pp +Predefined macro: MS_RASSERT(reg,byte) +.Ss MS_OP_DELAY - microsecond DELAY +is used to delay the execution of the microsequence. +.Pp +Parameter: +.Bl -enum -offset indent +.It +delay in microseconds +.El +.Pp +Predefined macro: MS_DELAY(delay) +.Ss MS_OP_SET - SET internal branch register +is used to set the value of the internal branch register. +.Pp +Parameter: +.Bl -enum -offset indent +.It +integer value +.El +.Pp +Predefined macro: MS_SET(accum) +.Ss MS_OP_DBRA - \&Do BRAnch +is used to branch if internal branch register decremented by one result value +is positive. +.Pp +Parameter: +.Bl -enum -offset indent +.It +integer offset in the current executed (sub)microsequence. +Offset is added to +the index of the next microinstruction to execute. +.El +.Pp +Predefined macro: MS_DBRA(offset) +.Ss MS_OP_BRSET - BRanch on SET +is used to branch if some of the status register bits of the parallel port +are set. +.Pp +Parameter: +.Bl -enum -offset indent +.It +bits of the status register +.It +integer offset in the current executed (sub)microsequence. +Offset is added to +the index of the next microinstruction to execute. +.El +.Pp +Predefined macro: MS_BRSET(mask,offset) +.Ss MS_OP_BRCLEAR - BRanch on CLEAR +is used to branch if some of the status register bits of the parallel port +are cleared. +.Pp +Parameter: +.Bl -enum -offset indent +.It +bits of the status register +.It +integer offset in the current executed (sub)microsequence. +Offset is added to +the index of the next microinstruction to execute. +.El +.Pp +Predefined macro: MS_BRCLEAR(mask,offset) +.Ss MS_OP_RET - RETurn +is used to return from a microsequence. +This instruction is mandatory. +This +is the only way for the microsequencer to detect the end of the microsequence. +The return code is returned in the integer pointed by the (int *) parameter +of the ppb_MS_microseq(). +.Pp +Parameter: +.Bl -enum -offset indent +.It +integer return code +.El +.Pp +Predefined macro: MS_RET(code) +.Ss MS_OP_C_CALL - C function CALL +is used to call C functions from microsequence execution. +This may be useful +when a non-standard i/o is performed to retrieve a data character from the +parallel port. +.Pp +Parameter: +.Bl -enum -offset indent +.It +the C function to call +.It +the parameter to pass to the function call +.El +.Pp +The C function shall be declared as a +.Ft int(*)(void *p, char *ptr) . +The ptr parameter is the current position in the buffer currently scanned. +.Pp +Predefined macro: MS_C_CALL(func,param) +.Ss MS_OP_PTR - initialize internal PTR +is used to initialize the internal pointer to the currently scanned buffer. +This pointer is passed to any C call (see above). +.Pp +Parameter: +.Bl -enum -offset indent +.It +pointer to the buffer that shall be accessed by xxx_P() microsequence calls. +Note that this pointer is automatically incremented during xxx_P() calls +.El +.Pp +Predefined macro: MS_PTR(ptr) +.Ss MS_OP_ADELAY - do an Asynchronous DELAY +is used to make a tsleep() during microsequence execution. +The tsleep is +executed at PPBPRI level. +.Pp +Parameter: +.Bl -enum -offset indent +.It +delay in ms +.El +.Pp +Predefined macro: MS_ADELAY(delay) +.Ss MS_OP_BRSTAT - BRanch on STATe +is used to branch on status register state condition. +.Pp +Parameter: +.Bl -enum -offset indent +.It +mask of asserted bits. +Bits that shall be asserted in the status register +are set in the mask +.It +mask of cleared bits. +Bits that shall be cleared in the status register +are set in the mask +.It +integer offset in the current executed (sub)microsequence. +Offset is added +to the index of the next microinstruction to execute. +.El +.Pp +Predefined macro: MS_BRSTAT(asserted_bits,clear_bits,offset) +.Ss MS_OP_SUBRET - SUBmicrosequence RETurn +is used to return from the submicrosequence call. +This action is mandatory +before a RET call. +Some microinstructions (PUT, GET) may not be callable +within a submicrosequence. +.Pp +No parameter. +.Pp +Predefined macro: MS_SUBRET() +.Ss MS_OP_CALL - submicrosequence CALL +is used to call a submicrosequence. +A submicrosequence is a microsequence with +a SUBRET call. +Parameter: +.Bl -enum -offset indent +.It +the submicrosequence to execute +.El +.Pp +Predefined macro: MS_CALL(microseq) +.Ss MS_OP_RASSERT_P - Register ASSERT from internal PTR +is used to assert a register with data currently pointed by the internal PTR +pointer. +Parameter: +.Bl -enum -offset indent +.It +amount of data to write to the register +.It +register +.El +.Pp +Predefined macro: MS_RASSERT_P(iter,reg) +.Ss MS_OP_RFETCH_P - Register FETCH to internal PTR +is used to fetch data from a register. +Data is stored in the buffer currently +pointed by the internal PTR pointer. +Parameter: +.Bl -enum -offset indent +.It +amount of data to read from the register +.It +register +.It +mask applied to fetched data +.El +.Pp +Predefined macro: MS_RFETCH_P(iter,reg,mask) +.Ss MS_OP_TRIG - TRIG register +is used to trigger the parallel port. +This microinstruction is intended to +provide a very efficient control of the parallel port. +Triggering a register +is writing data, wait a while, write data, wait a while... +This allows to +write magic sequences to the port. +Parameter: +.Bl -enum -offset indent +.It +amount of data to read from the register +.It +register +.It +size of the array +.It +array of unsigned chars. +Each couple of u_chars define the data to write to +the register and the delay in us to wait. +The delay is limited to 255 us to +simplify and reduce the size of the array. +.El +.Pp +Predefined macro: MS_TRIG(reg,len,array) +.Sh MICROSEQUENCES +.Ss C structures +.Bd -literal +union ppb_insarg { + int i; + char c; + void *p; + int (* f)(void *, char *); +}; + +struct ppb_microseq { + int opcode; /* microins. opcode */ + union ppb_insarg arg[PPB_MS_MAXARGS]; /* arguments */ +}; +.Ed +.Ss Using microsequences +To instantiate a microsequence, just declare an array of ppb_microseq +structures and initialize it as needed. +You may either use predefined macros +or code directly your microinstructions according to the ppb_microseq +definition. +For example, +.Bd -literal + struct ppb_microseq select_microseq[] = { + + /* parameter list + */ + #define SELECT_TARGET MS_PARAM(0, 1, MS_TYP_INT) + #define SELECT_INITIATOR MS_PARAM(3, 1, MS_TYP_INT) + + /* send the select command to the drive */ + MS_DASS(MS_UNKNOWN), + MS_CASS(H_nAUTO | H_nSELIN | H_INIT | H_STROBE), + MS_CASS( H_AUTO | H_nSELIN | H_INIT | H_STROBE), + MS_DASS(MS_UNKNOWN), + MS_CASS( H_AUTO | H_nSELIN | H_nINIT | H_STROBE), + + /* now, wait until the drive is ready */ + MS_SET(VP0_SELTMO), +/* loop: */ MS_BRSET(H_ACK, 2 /* ready */), + MS_DBRA(-2 /* loop */), +/* error: */ MS_RET(1), +/* ready: */ MS_RET(0) + }; +.Ed +.Pp +Here, some parameters are undefined and must be filled before executing +the microsequence. +In order to initialize each microsequence, one +should use the ppb_MS_init_msq() function like this: +.Bd -literal + ppb_MS_init_msq(select_microseq, 2, + SELECT_TARGET, 1 << target, + SELECT_INITIATOR, 1 << initiator); +.Ed +.Pp +and then execute the microsequence. +.Ss The microsequencer +The microsequencer is executed either at ppbus or adapter level (see +.Xr ppbus 4 +for info about ppbus system layers). +Most of the microsequencer is executed +at ppc level to avoid ppbus to adapter function call overhead. +But some +actions like deciding whereas the transfer is IEEE1284-1994 compliant are +executed at ppbus layer. +.Sh SEE ALSO +.Xr ppbus 4 , +.Xr ppc 4 , +.Xr ppi 4 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 3.0 . +.Sh AUTHORS +This +manual page was written by +.An Nicolas Souchu . +.Sh BUGS +Only one level of submicrosequences is allowed. +.Pp +When triggering the port, maximum delay allowed is 255 us. diff --git a/static/freebsd/man9/microtime.9 b/static/freebsd/man9/microtime.9 new file mode 100644 index 00000000..d703d7b5 --- /dev/null +++ b/static/freebsd/man9/microtime.9 @@ -0,0 +1,119 @@ +.\" Copyright (c) 2000 Kelly Yancey +.\" 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 September 16, 2004 +.Dt MICROTIME 9 +.Os +.Sh NAME +.Nm bintime , +.Nm getbintime , +.Nm microtime , +.Nm getmicrotime , +.Nm nanotime , +.Nm getnanotime +.Nd get the current time +.Sh SYNOPSIS +.In sys/time.h +.Ft void +.Fn bintime "struct bintime *bt" +.Ft void +.Fn getbintime "struct bintime *bt" +.Ft void +.Fn microtime "struct timeval *tv" +.Ft void +.Fn getmicrotime "struct timeval *tv" +.Ft void +.Fn nanotime "struct timespec *ts" +.Ft void +.Fn getnanotime "struct timespec *tsp" +.Sh DESCRIPTION +The +.Fn bintime +and +.Fn getbintime +functions store the system time as a +.Vt "struct bintime" +at the addresses specified by +.Fa bt . +The +.Fn microtime +and +.Fn getmicrotime +functions perform the same utility, but record the time as a +.Vt "struct timeval" +instead. +Similarly the +.Fn nanotime +and +.Fn getnanotime +functions store the time as a +.Vt "struct timespec" . +.Pp +The +.Fn bintime , +.Fn microtime , +and +.Fn nanotime +functions +always query the timecounter to return the current time as precisely as +possible. +Whereas +.Fn getbintime , +.Fn getmicrotime , +and +.Fn getnanotime +functions are abstractions which return a less precise, but +faster to obtain, time. +.Pp +The intent of the +.Fn getbintime , +.Fn getmicrotime , +and +.Fn getnanotime +functions is to enforce the user's preference for timer accuracy versus +execution time. +.Sh SEE ALSO +.Xr binuptime 9 , +.Xr getbinuptime 9 , +.Xr getmicrouptime 9 , +.Xr getnanouptime 9 , +.Xr microuptime 9 , +.Xr nanouptime 9 , +.Xr tvtohz 9 +.Sh HISTORY +The +.Nm bintime +functions first appeared in +.Fx 5.0 . +The +.Nm microtime +and +.Nm nanotime +functions first appeared in +.Fx 3.0 +but have existed in other incarnations since +.Bx 4.4 . +.Sh AUTHORS +This manual page was written by +.An Kelly Yancey Aq Mt kbyanc@posi.net . diff --git a/static/freebsd/man9/microuptime.9 b/static/freebsd/man9/microuptime.9 new file mode 100644 index 00000000..e1b9b193 --- /dev/null +++ b/static/freebsd/man9/microuptime.9 @@ -0,0 +1,122 @@ +.\" Copyright (c) 2000 Kelly Yancey +.\" 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 February 21, 2015 +.Dt MICROUPTIME 9 +.Os +.Sh NAME +.Nm binuptime , +.Nm getbinuptime , +.Nm microuptime , +.Nm getmicrouptime , +.Nm nanouptime , +.Nm getnanouptime , +.Nm sbinuptime , +.Nm getsbinuptime +.Nd get the time elapsed since boot +.Sh SYNOPSIS +.In sys/time.h +.Ft void +.Fn binuptime "struct bintime *bt" +.Ft void +.Fn getbinuptime "struct bintime *bt" +.Ft void +.Fn microuptime "struct timeval *tv" +.Ft void +.Fn getmicrouptime "struct timeval *tv" +.Ft void +.Fn nanouptime "struct timespec *ts" +.Ft void +.Fn getnanouptime "struct timespec *tsp" +.Ft sbintime_t +.Fn sbinuptime "void" +.Ft sbintime_t +.Fn getsbinuptime "void" +.Sh DESCRIPTION +The +.Fn binuptime +and +.Fn getbinuptime +functions store the time elapsed since boot as a +.Vt "struct bintime" +at the address specified by +.Fa bt . +The +.Fn microuptime +and +.Fn getmicrouptime +functions perform the same utility, but record the elapsed time as a +.Vt "struct timeval" +instead. +Similarly the +.Fn nanouptime +and +.Fn getnanouptime +functions store the elapsed time as a +.Vt "struct timespec" . +The +.Fn sbinuptime +and +.Fn getsbinuptime +functions return the time elapsed since boot as a +.Vt "sbintime_t" . +.Pp +The +.Fn binuptime , +.Fn microuptime , +.Fn nanouptime , +and +.Fn sbinuptime +functions +always query the timecounter to return the current time as precisely as +possible. +Whereas +.Fn getbinuptime , +.Fn getmicrouptime , +.Fn getnanouptime , +and +.Fn getsbinuptime +functions are abstractions which return a less precise, but +faster to obtain, time. +.Pp +The intent of the +.Fn getbinuptime , +.Fn getmicrouptime , +.Fn getnanouptime , +and +.Fn getsbinuptime +functions is to enforce the user's preference for timer accuracy versus +execution time. +.Sh SEE ALSO +.Xr bintime 9 , +.Xr get_cyclecount 9 , +.Xr getbintime 9 , +.Xr getmicrotime 9 , +.Xr getnanotime 9 , +.Xr microtime 9 , +.Xr nanotime 9 , +.Xr tvtohz 9 +.Sh AUTHORS +This manual page was written by +.An Kelly Yancey Aq Mt kbyanc@posi.net . diff --git a/static/freebsd/man9/mod_cc.9 b/static/freebsd/man9/mod_cc.9 new file mode 100644 index 00000000..09580aa9 --- /dev/null +++ b/static/freebsd/man9/mod_cc.9 @@ -0,0 +1,421 @@ +.\" +.\" Copyright (c) 2008-2009 Lawrence Stewart +.\" Copyright (c) 2010-2011 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" Portions of this documentation were written at the Centre for Advanced +.\" Internet Architectures, Swinburne University of Technology, Melbourne, +.\" Australia by David Hayes and Lawrence Stewart under sponsorship from the +.\" FreeBSD Foundation. +.\" +.\" 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 May 13, 2021 +.Dt MOD_CC 9 +.Os +.Sh NAME +.Nm mod_cc , +.Nm DECLARE_CC_MODULE , +.Nm CCV +.Nd Modular Congestion Control +.Sh SYNOPSIS +.In netinet/tcp.h +.In netinet/cc/cc.h +.In netinet/cc/cc_module.h +.Fn DECLARE_CC_MODULE "ccname" "ccalgo" +.Fn CCV "ccv" "what" +.Sh DESCRIPTION +The +.Nm +framework allows congestion control algorithms to be implemented as dynamically +loadable kernel modules via the +.Xr kld 4 +facility. +Transport protocols can select from the list of available algorithms on a +connection-by-connection basis, or use the system default (see +.Xr mod_cc 4 +for more details). +.Pp +.Nm +modules are identified by an +.Xr ascii 7 +name and set of hook functions encapsulated in a +.Vt "struct cc_algo" , +which has the following members: +.Bd -literal -offset indent +struct cc_algo { + char name[TCP_CA_NAME_MAX]; + int (*mod_init) (void); + int (*mod_destroy) (void); + size_t (*cc_data_sz)(void); + int (*cb_init) (struct cc_var *ccv, void *ptr); + void (*cb_destroy) (struct cc_var *ccv); + void (*conn_init) (struct cc_var *ccv); + void (*ack_received) (struct cc_var *ccv, uint16_t type); + void (*cong_signal) (struct cc_var *ccv, uint32_t type); + void (*post_recovery) (struct cc_var *ccv); + void (*after_idle) (struct cc_var *ccv); + int (*ctl_output)(struct cc_var *, struct sockopt *, void *); + void (*rttsample)(struct cc_var *, uint32_t, uint32_t, uint32_t); + void (*newround)(struct cc_var *, uint32_t); +}; +.Ed +.Pp +The +.Va name +field identifies the unique name of the algorithm, and should be no longer than +TCP_CA_NAME_MAX-1 characters in length (the TCP_CA_NAME_MAX define lives in +.In netinet/tcp.h +for compatibility reasons). +.Pp +The +.Va mod_init +function is called when a new module is loaded into the system but before the +registration process is complete. +It should be implemented if a module needs to set up some global state prior to +being available for use by new connections. +Returning a non-zero value from +.Va mod_init +will cause the loading of the module to fail. +.Pp +The +.Va mod_destroy +function is called prior to unloading an existing module from the kernel. +It should be implemented if a module needs to clean up any global state before +being removed from the kernel. +The return value is currently ignored. +.Pp +The +.Va cc_data_sz +function is called by the socket option code to get the size of +data that the +.Va cb_init +function needs. +The socket option code then preallocates the modules memory so that the +.Va cb_init +function will not fail (the socket option code uses M_WAITOK with +no locks held to do this). +.Pp +The +.Va cb_init +function is called when a TCP control block +.Vt struct tcpcb +is created. +It should be implemented if a module needs to allocate memory for storing +private per-connection state. +Returning a non-zero value from +.Va cb_init +will cause the connection set up to be aborted, terminating the connection as a +result. +Note that the ptr argument passed to the function should be checked to +see if it is non-NULL, if so it is preallocated memory that the cb_init function +must use instead of calling malloc itself. +.Pp +The +.Va cb_destroy +function is called when a TCP control block +.Vt struct tcpcb +is destroyed. +It should be implemented if a module needs to free memory allocated in +.Va cb_init . +.Pp +The +.Va conn_init +function is called when a new connection has been established and variables are +being initialised. +It should be implemented to initialise congestion control algorithm variables +for the newly established connection. +.Pp +The +.Va ack_received +function is called when a TCP acknowledgement (ACK) packet is received. +Modules use the +.Fa type +argument as an input to their congestion management algorithms. +The ACK types currently reported by the stack are CC_ACK and CC_DUPACK. +CC_ACK indicates the received ACK acknowledges previously unacknowledged data. +CC_DUPACK indicates the received ACK acknowledges data we have already received +an ACK for. +.Pp +The +.Va cong_signal +function is called when a congestion event is detected by the TCP stack. +Modules use the +.Fa type +argument as an input to their congestion management algorithms. +The congestion event types currently reported by the stack are CC_ECN, CC_RTO, +CC_RTO_ERR and CC_NDUPACK. +CC_ECN is reported when the TCP stack receives an explicit congestion notification +(RFC3168). +CC_RTO is reported when the retransmission time out timer fires. +CC_RTO_ERR is reported if the retransmission time out timer fired in error. +CC_NDUPACK is reported if N duplicate ACKs have been received back-to-back, +where N is the fast retransmit duplicate ack threshold (N=3 currently as per +RFC5681). +.Pp +The +.Va post_recovery +function is called after the TCP connection has recovered from a congestion event. +It should be implemented to adjust state as required. +.Pp +The +.Va after_idle +function is called when data transfer resumes after an idle period. +It should be implemented to adjust state as required. +.Pp +The +.Va ctl_output +function is called when +.Xr getsockopt 2 +or +.Xr setsockopt 2 +is called on a +.Xr tcp 4 +socket with the +.Va struct sockopt +pointer forwarded unmodified from the TCP control, and a +.Va void * +pointer to algorithm specific argument. +.Pp +The +.Va rttsample +function is called to pass round trip time information to the +congestion controller. +The additional arguments to the function include the microsecond RTT +that is being noted, the number of times that the data being +acknowledged was retransmitted as well as the flightsize at send. +For transports that do not track flightsize at send, this variable +will be the current cwnd at the time of the call. +.Pp +The +.Va newround +function is called each time a new round trip time begins. +The montonically increasing round number is also passed to the +congestion controller as well. +This can be used for various purposes by the congestion controller (e.g Hystart++). +.Pp +Note that currently not all TCP stacks call the +.Va rttsample +and +.Va newround +function so dependency on these functions is also +dependent upon which TCP stack is in use. +.Pp +The +.Fn DECLARE_CC_MODULE +macro provides a convenient wrapper around the +.Xr DECLARE_MODULE 9 +macro, and is used to register a +.Nm +module with the +.Nm +framework. +The +.Fa ccname +argument specifies the module's name. +The +.Fa ccalgo +argument points to the module's +.Vt struct cc_algo . +.Pp +.Nm +modules must instantiate a +.Vt struct cc_algo , +but are only required to set the name field, and optionally any of the function +pointers. +Note that if a module defines the +.Va cb_init +function it also must define a +.Va cc_data_sz +function. +This is because when switching from one congestion control +module to another the socket option code will preallocate memory for the +.Va cb_init +function. +If no memory is allocated by the modules +.Va cb_init +then the +.Va cc_data_sz +function should return 0. +.Pp +The stack will skip calling any function pointer which is NULL, so there is no +requirement to implement any of the function pointers (with the exception of +the cb_init <-> cc_data_sz dependency noted above). +Using the C99 designated initialiser feature to set fields is encouraged. +.Pp +Each function pointer which deals with congestion control state is passed a +pointer to a +.Vt struct cc_var , +which has the following members: +.Bd -literal -offset indent +struct cc_var { + void *cc_data; + int bytes_this_ack; + tcp_seq curack; + uint32_t flags; + int type; + union ccv_container { + struct tcpcb *tcp; + struct sctp_nets *sctp; + } ccvc; + uint16_t nsegs; + uint8_t labc; +}; +.Ed +.Pp +.Vt struct cc_var +groups congestion control related variables into a single, embeddable structure +and adds a layer of indirection to accessing transport protocol control blocks. +The eventual goal is to allow a single set of +.Nm +modules to be shared between all congestion aware transport protocols, though +currently only +.Xr tcp 4 +is supported. +.Pp +To aid the eventual transition towards this goal, direct use of variables from +the transport protocol's data structures is strongly discouraged. +However, it is inevitable at the current time to require access to some of these +variables, and so the +.Fn CCV +macro exists as a convenience accessor. +The +.Fa ccv +argument points to the +.Vt struct cc_var +passed into the function by the +.Nm +framework. +The +.Fa what +argument specifies the name of the variable to access. +.Pp +Apart from the +.Va type +and +.Va ccv_container +fields, the remaining fields in +.Vt struct cc_var +are for use by +.Nm +modules. +.Pp +The +.Va cc_data +field is available for algorithms requiring additional per-connection state to +attach a dynamic memory pointer to. +The memory should be allocated and attached in the module's +.Va cb_init +hook function. +.Pp +The +.Va bytes_this_ack +field specifies the number of new bytes acknowledged by the most recently +received ACK packet. +It is only valid in the +.Va ack_received +hook function. +.Pp +The +.Va curack +field specifies the sequence number of the most recently received ACK packet. +It is only valid in the +.Va ack_received , +.Va cong_signal +and +.Va post_recovery +hook functions. +.Pp +The +.Va flags +field is used to pass useful information from the stack to a +.Nm +module. +The CCF_ABC_SENTAWND flag is relevant in +.Va ack_received +and is set when appropriate byte counting (RFC3465) has counted a window's worth +of bytes has been sent. +It is the module's responsibility to clear the flag after it has processed the +signal. +The CCF_CWND_LIMITED flag is relevant in +.Va ack_received +and is set when the connection's ability to send data is currently constrained +by the value of the congestion window. +Algorithms should use the absence of this flag being set to avoid accumulating +a large difference between the congestion window and send window. +.Pp +The +.Va nsegs +variable is used to pass in how much compression was done by the local +LRO system. +So for example if LRO pushed three in-order acknowledgements into +one acknowledgement the variable would be set to three. +.Pp +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 +for this particular acknowledgement. +.Sh SEE ALSO +.Xr cc_cdg 4 , +.Xr cc_chd 4 , +.Xr cc_cubic 4 , +.Xr cc_dctcp 4 , +.Xr cc_hd 4 , +.Xr cc_htcp 4 , +.Xr cc_newreno 4 , +.Xr cc_vegas 4 , +.Xr mod_cc 4 , +.Xr tcp 4 +.Sh ACKNOWLEDGEMENTS +Development and testing of this software were made possible in part by grants +from the FreeBSD Foundation and Cisco University Research Program Fund at +Community Foundation Silicon Valley. +.Sh FUTURE WORK +Integrate with +.Xr sctp 4 . +.Sh HISTORY +The modular Congestion Control (CC) framework first appeared in +.Fx 9.0 . +.Pp +The framework was first released in 2007 by James Healy and Lawrence Stewart +whilst working on the NewTCP research project at Swinburne University of +Technology's Centre for Advanced Internet Architectures, Melbourne, Australia, +which was made possible in part by a grant from the Cisco University Research +Program Fund at Community Foundation Silicon Valley. +More details are available at: +.Pp +http://caia.swin.edu.au/urp/newtcp/ +.Sh AUTHORS +.An -nosplit +The +.Nm +framework was written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org , +.An James Healy Aq Mt jimmy@deefa.com +and +.An David Hayes Aq Mt david.hayes@ieee.org . +.Pp +This manual page was written by +.An David Hayes Aq Mt david.hayes@ieee.org +and +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org . diff --git a/static/freebsd/man9/module.9 b/static/freebsd/man9/module.9 new file mode 100644 index 00000000..8cb558bc --- /dev/null +++ b/static/freebsd/man9/module.9 @@ -0,0 +1,123 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2000 Alexander Langer +.\" +.\" 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 November 11, 2021 +.Dt MODULE 9 +.Os +.Sh NAME +.Nm module +.Nd structure describing a kernel module +.Sh DESCRIPTION +Each module in the kernel is described by a +.Vt module_t +structure. +The structure contains the name of the device, a unique ID number, +a pointer to an event handler function and to an argument, +which is given to the event handler, +as well as some kernel internal data. +If the event handler function is +.Dv NULL , +the module will use a no-operation function handler instead. +.Pp +The +.Xr DECLARE_MODULE 9 +macro +registers the module with the system. +.Pp +When the module is loaded, the event handler function is called with +the +.Fa what +argument set to +.Dv MOD_LOAD . +.Pp +On unload it is first called with +.Fa what +set to +.Dv MOD_QUIESCE . +If the unload was not forced, a non-zero return will prevent the +unload from happening. +.Pp +If the unload continues +.Fa what +is set to +.Dv MOD_UNLOAD . +If the module returns non-zero to this, the unload will not happen. +.Pp +The difference between +.Dv MOD_QUIESCE +and +.Dv MOD_UNLOAD +is that the module should fail +.Dv MOD_QUIESCE +if it is currently in use, whereas +.Dv MOD_UNLOAD +should only fail if it is impossible to unload the module, for instance +because there are memory references to the module which cannot be revoked. +.Pp +When the system is shutting down, +.Fa what +contains the value of +.Dv MOD_SHUTDOWN . +.Pp +The module should return +.Er EOPNOTSUPP +for unsupported and unrecognized values of +.Fa what . +.Sh EXAMPLES +.Bd -literal +#include +#include +#include + +static int foo_handler(module_t mod, int /*modeventtype_t*/ what, + void *arg); + +static moduledata_t mod_data= { + "foo", + foo_handler, + NULL +}; + +MODULE_VERSION(foo, 1); +MODULE_DEPEND(foo, bar, 1, 3, 4); + +DECLARE_MODULE(foo, mod_data, SI_SUB_EXEC, SI_ORDER_ANY); +.Ed +.Sh SEE ALSO +.Xr DECLARE_MODULE 9 , +.Xr DEV_MODULE 9 , +.Xr DRIVER_MODULE 9 , +.Xr MODULE_DEPEND 9 , +.Xr MODULE_PNP_INFO 9 , +.Xr MODULE_VERSION 9 , +.Xr SYSCALL_MODULE 9 +.Pp +.Pa /usr/share/examples/kld +.Sh AUTHORS +This manual page was written by +.An Alexander Langer Aq Mt alex@FreeBSD.org . diff --git a/static/freebsd/man9/mtx_pool.9 b/static/freebsd/man9/mtx_pool.9 new file mode 100644 index 00000000..32734061 --- /dev/null +++ b/static/freebsd/man9/mtx_pool.9 @@ -0,0 +1,182 @@ +.\" +.\" Copyright (C) 2002 Garrett Rooney . +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 February 6, 2010 +.Dt MTX_POOL 9 +.Os +.Sh NAME +.Nm mtx_pool , +.Nm mtx_pool_alloc , +.Nm mtx_pool_find , +.Nm mtx_pool_lock , +.Nm mtx_pool_lock_spin , +.Nm mtx_pool_unlock , +.Nm mtx_pool_unlock_spin , +.Nm mtx_pool_create , +.Nm mtx_pool_destroy +.Nd "mutex pool routines" +.Sh SYNOPSIS +.In sys/param.h +.In sys/lock.h +.In sys/mutex.h +.Ft "struct mtx *" +.Fn mtx_pool_alloc "struct mtx_pool *pool" +.Ft "struct mtx *" +.Fn mtx_pool_find "struct mtx_pool *pool" "void *ptr" +.Ft void +.Fn mtx_pool_lock "struct mtx_pool *pool" "void *ptr" +.Ft void +.Fn mtx_pool_lock_spin "struct mtx_pool *pool" "void *ptr" +.Ft void +.Fn mtx_pool_unlock "struct mtx_pool *pool" "void *ptr" +.Ft void +.Fn mtx_pool_unlock_spin "struct mtx_pool *pool" "void *ptr" +.Ft "struct mtx_pool *" +.Fn mtx_pool_create "const char *mtx_name" "int pool_size" "int opts" +.Ft "void" +.Fn mtx_pool_destroy "struct mtx_pool **poolp" +.Sh DESCRIPTION +Mutex pools are designed to be used as short term leaf mutexes; +i.e., the last mutex one might acquire before calling +.Xr mtx_sleep 9 . +They operate using a shared pool of mutexes. +A mutex may be chosen from the pool based on a supplied pointer, +which may or may not point to anything valid, +or the caller may allocate an arbitrary shared mutex from the pool +and save the returned mutex pointer for later use. +.Pp +The shared mutexes in the +.Va mtxpool_sleep +mutex pool, +which is created by default, +are standard, non-recursive, +blockable mutexes, and should only be used in appropriate situations. +The mutexes in the +.Va mtxpool_lockbuilder +mutex pool are similar, except that they are initialized with the MTX_NOWITNESS +flag so that they may be used to build higher-level locks. +Other mutex pools may be created that contain mutexes with different +properties, such as spin mutexes. +.Pp +The caller can lock and unlock mutexes returned by the pool routines, but +since the mutexes are shared, the caller should not attempt to destroy them +or modify their characteristics. +While pool mutexes are normally leaf mutexes +(meaning that one cannot depend on any ordering guarantees +after obtaining one), +one can still obtain other mutexes under carefully controlled circumstances. +Specifically, if one has a private mutex +(one that was allocated and initialized by the caller), +one can obtain it after obtaining a pool mutex if ordering issues are +carefully accounted for. +In these cases the private mutex winds up being the true leaf mutex. +.Pp +Pool mutexes have the following advantages: +.Pp +.Bl -enum -offset indent -compact +.It +No structural overhead; +i.e., they can be associated with a structure without adding bloat to it. +.It +Mutexes can be obtained for invalid pointers, which is useful when one uses +mutexes to interlock destructor operations. +.It +No initialization or destruction overhead. +.It +Can be used with +.Xr mtx_sleep 9 . +.El +.Pp +And the following disadvantages: +.Pp +.Bl -enum -offset indent -compact +.It +Should generally only be used as leaf mutexes. +.It +Pool/pool dependency ordering cannot be guaranteed. +.It +Possible L1 cache mastership contention between CPUs. +.El +.Pp +.Fn mtx_pool_alloc +obtains a shared mutex from the specified pool. +This routine uses a simple rover to choose one of the shared mutexes managed +by the +.Nm +subsystem. +.Pp +.Fn mtx_pool_find +returns the shared mutex associated with the specified address. +This routine will create a hash out of the pointer passed into it +and will choose a shared mutex from the specified pool based on that hash. +The pointer does not need to point to anything real. +.Pp +.Fn mtx_pool_lock , +.Fn mtx_pool_lock_spin , +.Fn mtx_pool_unlock , +and +.Fn mtx_pool_unlock_spin +lock and unlock the shared mutex from the specified pool +associated with the specified address; +they are a combination of +.Fn mtx_pool_find +and +.Xr mtx_lock 9 , +.Xr mtx_lock_spin 9 , +.Xr mtx_unlock 9 , +and +.Xr mtx_unlock_spin 9 , +respectively. +Since these routines must first find the mutex to operate on, +they are not as fast as directly using the mutex pointer returned by +a previous invocation of +.Fn mtx_pool_find +or +.Fn mtx_pool_alloc . +.Pp +.Fn mtx_pool_create +allocates and initializes a new mutex pool of the +specified size. +The pool size must be a power of two. +The +.Fa opts +argument is passed to +.Xr mtx_init 9 +to set the options for each mutex in the pool. +.Pp +.Fn mtx_pool_destroy +calls +.Xr mtx_destroy 9 +on each mutex in the specified pool, +deallocates the memory associated with the pool, +and assigns NULL to the pool pointer. +.Sh SEE ALSO +.Xr locking 9 , +.Xr mutex 9 +.Sh HISTORY +These routines first appeared in +.Fx 5.0 . diff --git a/static/freebsd/man9/mutex.9 b/static/freebsd/man9/mutex.9 new file mode 100644 index 00000000..ccba09f3 --- /dev/null +++ b/static/freebsd/man9/mutex.9 @@ -0,0 +1,559 @@ +.\" +.\" Copyright (c) 1998 Berkeley Software Design, Inc. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Berkeley Software Design Inc's name may not be used to endorse or +.\" promote products derived from this software without specific prior +.\" written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY BERKELEY SOFTWARE DESIGN INC ``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 BERKELEY SOFTWARE DESIGN INC 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. +.\" +.\" from BSDI $Id: mutex.4,v 1.1.2.3 1998/04/27 22:53:13 ewv Exp $ +.\" +.Dd February 17, 2023 +.Dt MUTEX 9 +.Os +.Sh NAME +.Nm mutex , +.Nm mtx_init , +.Nm mtx_destroy , +.Nm mtx_lock , +.Nm mtx_lock_spin , +.Nm mtx_lock_flags , +.Nm mtx_lock_spin_flags , +.Nm mtx_trylock , +.Nm mtx_trylock_flags , +.Nm mtx_trylock_spin , +.Nm mtx_trylock_spin_flags , +.Nm mtx_unlock , +.Nm mtx_unlock_spin , +.Nm mtx_unlock_flags , +.Nm mtx_unlock_spin_flags , +.Nm mtx_sleep , +.Nm mtx_initialized , +.Nm mtx_owned , +.Nm mtx_recursed , +.Nm mtx_assert , +.Nm MTX_SYSINIT +.Nd kernel synchronization primitives +.Sh SYNOPSIS +.In sys/param.h +.In sys/lock.h +.In sys/mutex.h +.Ft void +.Fn mtx_init "struct mtx *mutex" "const char *name" "const char *type" "int opts" +.Ft void +.Fn mtx_destroy "struct mtx *mutex" +.Ft void +.Fn mtx_lock "struct mtx *mutex" +.Ft void +.Fn mtx_lock_spin "struct mtx *mutex" +.Ft void +.Fn mtx_lock_flags "struct mtx *mutex" "int flags" +.Ft void +.Fn mtx_lock_spin_flags "struct mtx *mutex" "int flags" +.Ft int +.Fn mtx_trylock "struct mtx *mutex" +.Ft int +.Fn mtx_trylock_flags "struct mtx *mutex" "int flags" +.Ft int +.Fn mtx_trylock_spin "struct mtx *mutex" +.Ft int +.Fn mtx_trylock_spin_flags "struct mtx *mutex" "int flags" +.Ft void +.Fn mtx_unlock "struct mtx *mutex" +.Ft void +.Fn mtx_unlock_spin "struct mtx *mutex" +.Ft void +.Fn mtx_unlock_flags "struct mtx *mutex" "int flags" +.Ft void +.Fn mtx_unlock_spin_flags "struct mtx *mutex" "int flags" +.Ft int +.Fn mtx_sleep "void *chan" "struct mtx *mtx" "int priority" "const char *wmesg" "int timo" +.Ft int +.Fn mtx_initialized "const struct mtx *mutex" +.Ft int +.Fn mtx_owned "const struct mtx *mutex" +.Ft int +.Fn mtx_recursed "const struct mtx *mutex" +.Pp +.Cd "options INVARIANTS" +.Cd "options INVARIANT_SUPPORT" +.Ft void +.Fn mtx_assert "const struct mtx *mutex" "int what" +.In sys/kernel.h +.Fn MTX_SYSINIT "name" "struct mtx *mtx" "const char *description" "int opts" +.Sh DESCRIPTION +Mutexes are the most basic and primary method of thread synchronization. +The major design considerations for mutexes are: +.Bl -enum +.It +Acquiring and releasing uncontested mutexes should be as cheap +as possible. +.It +They must have the information and storage space to support +priority propagation. +.It +A thread must be able to recursively acquire a mutex, +provided that the mutex is initialized to support recursion. +.El +.Pp +There are currently two flavors of mutexes, those that context switch +when they block and those that do not. +.Pp +By default, +.Dv MTX_DEF +mutexes will context switch when they are already held. +As an optimization, +they may spin for some amount +of time before context switching. +It is important to remember that since a thread may be preempted at any time, +the possible context switch introduced by acquiring a mutex is guaranteed +to not break anything that is not already broken. +.Pp +Mutexes which do not context switch are +.Dv MTX_SPIN +mutexes. +These should only be used to protect data shared with primary interrupt +code. +This includes interrupt filters and low level scheduling code. +In all architectures both acquiring and releasing of a +uncontested spin mutex is more expensive than the same operation +on a non-spin mutex. +In order to protect an interrupt service routine from blocking +against itself all interrupts are either blocked or deferred on a processor +while holding a spin lock. +It is permissible to hold multiple spin mutexes. +.Pp +Once a spin mutex has been acquired it is not permissible to acquire a +blocking mutex. +.Pp +The storage needed to implement a mutex is provided by a +.Vt struct mtx . +In general this should be treated as an opaque object and +referenced only with the mutex primitives. +.Pp +The +.Fn mtx_init +function must be used to initialize a mutex +before it can be passed to any of the other mutex functions. +The +.Fa name +option is used to identify the lock in debugging output etc. +The +.Fa type +option is used by the witness code to classify a mutex when doing checks +of lock ordering. +If +.Fa type +is +.Dv NULL , +.Fa name +is used in its place. +The pointer passed in as +.Fa name +and +.Fa type +is saved rather than the data it points to. +The data pointed to must remain stable +until the mutex is destroyed. +The +.Fa opts +argument is used to set the type of mutex. +It may contain either +.Dv MTX_DEF +or +.Dv MTX_SPIN +but not both. +If the kernel has been compiled with +.Cd "option INVARIANTS" , +.Fn mtx_init +will assert that the +.Fa mutex +has not been initialized multiple times without intervening calls to +.Fn mtx_destroy +unless the +.Dv MTX_NEW +option is specified. +See below for additional initialization options. +.Pp +The +.Fn mtx_lock +function acquires a +.Dv MTX_DEF +mutual exclusion lock +on behalf of the currently running kernel thread. +If another kernel thread is holding the mutex, +the caller will be disconnected from the CPU +until the mutex is available +(i.e., it will block). +.Pp +The +.Fn mtx_lock_spin +function acquires a +.Dv MTX_SPIN +mutual exclusion lock +on behalf of the currently running kernel thread. +If another kernel thread is holding the mutex, +the caller will spin until the mutex becomes available. +Interrupts are disabled during the spin and remain disabled +following the acquiring of the lock. +.Pp +It is possible for the same thread to recursively acquire a mutex +with no ill effects, provided that the +.Dv MTX_RECURSE +bit was passed to +.Fn mtx_init +during the initialization of the mutex. +.Pp +The +.Fn mtx_lock_flags +and +.Fn mtx_lock_spin_flags +functions acquire a +.Dv MTX_DEF +or +.Dv MTX_SPIN +lock, respectively, and also accept a +.Fa flags +argument. +In both cases, the only flags presently available for lock acquires are +.Dv MTX_QUIET +and +.Dv MTX_RECURSE . +If the +.Dv MTX_QUIET +bit is turned on in the +.Fa flags +argument, then if +.Dv KTR_LOCK +tracing is being done, +it will be silenced during the lock acquire. +If the +.Dv MTX_RECURSE +bit is turned on in the +.Fa flags +argument, then the mutex can be acquired recursively. +.Pp +The +.Fn mtx_trylock +and +.Fn mtx_trylock_spin +functions attempt to acquire a +.Dv MTX_DEF +or +.Dv MTX_SPIN +mutex, respectively, pointed to by +.Fa mutex . +If the mutex cannot be immediately acquired, the functions will return 0, +otherwise the mutex will be acquired and a non-zero value will be returned. +.Pp +The +.Fn mtx_trylock_flags +and +.Fn mtx_trylock_spin_flags +functions have the same behavior as +.Fn mtx_trylock +and +.Fn mtx_trylock_spin +respectively, but should be used when the caller desires to pass in a +.Fa flags +value. +Presently, the only valid value in the +.Fn mtx_trylock +and +.Fn mtx_trylock_spin +cases is +.Dv MTX_QUIET , +and its effects are identical to those described for +.Fn mtx_lock +above. +.Pp +The +.Fn mtx_unlock +function releases a +.Dv MTX_DEF +mutual exclusion lock. +The current thread may be preempted if a higher priority thread is waiting +for the mutex. +.Pp +The +.Fn mtx_unlock_spin +function releases a +.Dv MTX_SPIN +mutual exclusion lock. +.Pp +The +.Fn mtx_unlock_flags +and +.Fn mtx_unlock_spin_flags +functions behave in exactly the same way as do the standard mutex +unlock routines above, while also allowing a +.Fa flags +argument which may specify +.Dv MTX_QUIET . +The behavior of +.Dv MTX_QUIET +is identical to its behavior in the mutex lock routines. +.Pp +The +.Fn mtx_destroy +function is used to destroy +.Fa mutex +so the data associated with it may be freed +or otherwise overwritten. +Any mutex which is destroyed +must previously have been initialized with +.Fn mtx_init . +It is permissible to have a single hold count +on a mutex when it is destroyed. +It is not permissible to hold the mutex recursively, +or have another thread blocked on the mutex +when it is destroyed. +.Pp +The +.Fn mtx_sleep +function is used to atomically release +.Fa mtx +while waiting for an event. +For more details on the parameters to this function, +see +.Xr sleep 9 . +.Pp +The +.Fn mtx_initialized +function returns non-zero if +.Fa mutex +has been initialized and zero otherwise. +.Pp +The +.Fn mtx_owned +function returns non-zero +if the current thread holds +.Fa mutex . +If the current thread does not hold +.Fa mutex +zero is returned. +.Pp +The +.Fn mtx_recursed +function returns non-zero if the +.Fa mutex +is recursed. +This check should only be made if the running thread already owns +.Fa mutex . +.Pp +The +.Fn mtx_assert +function allows assertions specified in +.Fa what +to be made about +.Fa mutex . +If the assertions are not true and the kernel is compiled with +.Cd "options INVARIANTS" +and +.Cd "options INVARIANT_SUPPORT" , +the kernel will panic. +Currently the following assertions are supported: +.Bl -tag -width MA_NOTRECURSED +.It Dv MA_OWNED +Assert that the current thread +holds the mutex +pointed to by the first argument. +.It Dv MA_NOTOWNED +Assert that the current thread +does not hold the mutex +pointed to by the first argument. +.It Dv MA_RECURSED +Assert that the current thread has recursed on the mutex +pointed to by the first argument. +This assertion is only valid in conjunction with +.Dv MA_OWNED . +.It Dv MA_NOTRECURSED +Assert that the current thread has not recursed on the mutex +pointed to by the first argument. +This assertion is only valid in conjunction with +.Dv MA_OWNED . +.El +.Pp +The +.Fn MTX_SYSINIT +macro is used to generate a call to the +.Fn mtx_sysinit +routine at system startup in order to initialize a given mutex lock. +The parameters are the same as +.Fn mtx_init +but with an additional argument, +.Fa name , +that is used in generating unique variable names for the related structures associated with the lock and the sysinit routine. +.Ss The Default Mutex Type +Most kernel code should use the default lock type, +.Dv MTX_DEF . +The default lock type will allow the thread +to be disconnected from the CPU +if the lock is already held by another thread. +The implementation +may treat the lock as a short term spin lock +under some circumstances. +However, it is always safe to use these forms of locks +in an interrupt thread +without fear of deadlock +against an interrupted thread on the same CPU. +.Ss The Spin Mutex Type +A +.Dv MTX_SPIN +mutex will not relinquish the CPU +when it cannot immediately get the requested lock, +but will loop, waiting for the mutex to be released by another CPU. +This could result in deadlock +if another thread interrupted the thread which held a mutex +and then tried to acquire the mutex. +For this reason spin locks disable all interrupts on the local CPU. +.Pp +Spin locks are fairly specialized locks +that are intended to be held for very short periods of time. +Their primary purpose is to protect portions of the code +that implement other synchronization primitives such as default mutexes, +thread scheduling, and interrupt threads. +.Ss Initialization Options +The options passed in the +.Fa opts +argument of +.Fn mtx_init +specify the mutex type. +One of the +.Dv MTX_DEF +or +.Dv MTX_SPIN +options is required and only one of those two options may be specified. +The possibilities are: +.Bl -tag -width MTX_NOWITNESS +.It Dv MTX_DEF +Default mutexes +will always allow the current thread to be suspended +to avoid deadlock conditions against interrupt threads. +The implementation of this lock type +may spin for a while before suspending the current thread. +.It Dv MTX_SPIN +Spin mutexes +will never relinquish the CPU. +All interrupts are disabled on the local CPU +while any spin lock is held. +.It Dv MTX_RECURSE +Specifies that the initialized mutex is allowed to recurse. +This bit must be present if the mutex is permitted to recurse. +.Pp +Note that neither +.Fn mtx_trylock +nor +.Fn mtx_trylock_spin +support recursion; +that is, attempting to acquire an already-owned mutex fails. +.It Dv MTX_QUIET +Do not log any mutex operations for this lock. +.It Dv MTX_NOWITNESS +Instruct +.Xr witness 4 +to ignore this lock. +.It Dv MTX_DUPOK +Witness should not log messages about duplicate locks being acquired. +.It Dv MTX_NOPROFILE +Do not profile this lock. +.It Dv MTX_NEW +Do not check for double-init. +.El +.Ss Lock and Unlock Flags +The flags passed to the +.Fn mtx_lock_flags , +.Fn mtx_lock_spin_flags , +.Fn mtx_unlock_flags , +and +.Fn mtx_unlock_spin_flags +functions provide some basic options to the caller, +and are often used only under special circumstances to modify lock or +unlock behavior. +Standard locking and unlocking should be performed with the +.Fn mtx_lock , +.Fn mtx_lock_spin , +.Fn mtx_unlock , +and +.Fn mtx_unlock_spin +functions. +Only if a flag is required should the corresponding +flags-accepting routines be used. +.Pp +Options that modify mutex behavior: +.Bl -tag -width MTX_QUIET +.It Dv MTX_QUIET +This option is used to quiet logging messages during individual mutex +operations. +This can be used to trim superfluous logging messages for debugging purposes. +.El +.Ss Giant +If +.Va Giant +must be acquired, it must be acquired prior to acquiring +other mutexes. +Put another way: it is impossible to acquire +.Va Giant +non-recursively while +holding another mutex. +It is possible to acquire other mutexes while holding +.Va Giant , +and it is possible to acquire +.Va Giant +recursively while holding other mutexes. +.Ss Sleeping +Sleeping while holding a mutex (except for +.Va Giant ) +is never safe +and should be avoided. +There are numerous assertions which will fail if this is attempted. +.Ss Functions Which Access Memory in Userspace +No mutexes should be held (except for +.Va Giant ) +across functions which +access memory in userspace, such as +.Xr copyin 9 , +.Xr copyout 9 , +.Xr uiomove 9 , +.Xr fuword 9 , +etc. +No locks are needed when calling these functions. +.Sh SEE ALSO +.Xr condvar 9 , +.Xr LOCK_PROFILING 9 , +.Xr locking 9 , +.Xr mtx_pool 9 , +.Xr panic 9 , +.Xr rwlock 9 , +.Xr sema 9 , +.Xr sleep 9 , +.Xr sx 9 +.Sh HISTORY +These +functions appeared in +.Bsx 4.1 +and +.Fx 5.0 . +The +.Fn mtx_trylock_spin +function was added in +.Fx 11.1 . diff --git a/static/freebsd/man9/namei.9 b/static/freebsd/man9/namei.9 new file mode 100644 index 00000000..d920f4e9 --- /dev/null +++ b/static/freebsd/man9/namei.9 @@ -0,0 +1,551 @@ +.\" +.\" Copyright (c) 1998, 1999 Eivind Eklund +.\" Copyright (c) 2003 Hiten M. Pandya +.\" Copyright (c) 2005 Robert N. M. Watson +.\" +.\" 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. +.\" +.\" +.\" If you integrate this manpage in another OS, I'd appreciate a note +.\" - eivind@FreeBSD.org +.\" +.Dd September 30, 2025 +.Dt NAMEI 9 +.Os +.Sh NAME +.Nm namei , +.Nm NDINIT , +.Nm NDINIT_AT , +.Nm NDFREE_PNBUF +.Nd pathname translation and lookup operations +.Sh SYNOPSIS +.In sys/param.h +.In sys/fcntl.h +.In sys/namei.h +.Ft int +.Fn namei "struct nameidata *ndp" +.Ft void +.Fo NDINIT +.Fa "struct nameidata *ndp" "enum nameiop op" "u_int64_t flags" +.Fa "enum uio_seg segflg" "const char *namep" +.Fc +.Ft void +.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 +facility allows the client to perform pathname translation and lookup +operations. +The +.Nm +functions will increment the reference count for the vnode in question. +The reference count has to be decremented after use of the vnode, by +using either +.Xr vrele 9 +or +.Xr vput 9 , +depending on whether the +.Dv LOCKLEAF +flag was specified or not. +.Pp +The +.Fn NDINIT +macro is used to initialize +.Nm +components. +It takes the following arguments: +.Bl -tag -width ".Fa segflg" +.It Fa ndp +A pointer to the +.Vt "struct nameidata" +to initialize. +.It Fa op +The operation which +.Fn namei +will perform. +The following operations are valid: +.Dv LOOKUP , CREATE , DELETE , +and +.Dv RENAME . +The latter three are just setup for those +effects; just calling +.Fn namei +will not result in +.Fn VOP_RENAME +being called. +.It Fa flags +Operation flags, described in the next section. +Several of these can be effective at the same time. +.It Fa segflg +UIO segment indicator. +This indicates if the name of the object is in userspace +.Pq Dv UIO_USERSPACE +or in the kernel address space +.Pq Dv UIO_SYSSPACE . +.It Fa namep +Pointer to the component's pathname buffer +(the file or directory name that will be looked up). +.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 +.Fn namei +function takes the following set of +.Dq "operation flags" +that influence its operation: +.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. +.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 LOCKPARENT +This flag lets the +.Fn namei +function return the parent (directory) vnode, +.Va ni_dvp +in locked state, unless it is identical to +.Va ni_vp , +in which case +.Va ni_dvp +is not locked per se (but may be locked due to +.Dv LOCKLEAF ) . +If a lock is enforced, it should be released using +.Xr vput 9 +or +.Xr VOP_UNLOCK 9 +and +.Xr vrele 9 . +.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 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 +.Dv FOLLOW . +.Dv NOFOLLOW +is used to indicate to the source code reader that symlinks +are intentionally not followed. +.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 +.Vt nameidata +structure is composed of the following fields: +.Bl -tag -width ".Va ni_cnd.cn_pnbuf" +.It Va ni_startdir +In the normal case, this is either the current directory or the root. +It is the current directory if the name passed in does not start with +.Ql / +and we have not gone through any symlinks with an absolute path, and +the root otherwise. +.Pp +In this case, it is only used by +.Fn vfs_lookup , +and should not be +considered valid after a call to +.Fn namei . +.It Va ni_dvp +Vnode pointer to directory of the object on which lookup is performed. +This is available on successful return if +.Dv LOCKPARENT +or +.Dv WANTPARENT +is set. +It is locked if +.Dv LOCKPARENT +is set. +.It Va ni_vp +Vnode pointer to the resulting object, +.Dv NULL +otherwise. +The +.Va v_usecount +field of this vnode is incremented. +If +.Dv LOCKLEAF +is set, it is also locked. +.Pp +.It Va ni_cnd.cn_pnbuf +The pathname buffer contains the location of the file or directory +that will be used by the +.Nm +operations. +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 successful 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 +will return 0, otherwise it will return an error. +.Sh FILES +.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 +may return: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the specified pathname is not a directory when a directory is +expected. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire pathname exceeded 1023 characters. +.It Bq Er ENOENT +A component of the specified pathname does not exist, +or the pathname is an empty string. +.It Bq Er EACCES +An attempt is made to access a file in a way forbidden by its file access +permissions. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EISDIR +An attempt is made to open a directory with write mode specified. +.It Bq Er EINVAL +The last component of the pathname specified for a +.Dv DELETE +or +.Dv RENAME +operation is +.Ql \&. . +.It Bq Er EROFS +An attempt is made to modify a file or directory on a read-only file system. +.El +.Sh SEE ALSO +.Xr uio 9 , +.Xr uma 9 , +.Xr VFS 9 , +.Xr vnode 9 , +.Xr vput 9 , +.Xr vref 9 , +.Xr vrele 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Eivind Eklund Aq Mt eivind@FreeBSD.org +and later significantly revised by +.An Hiten M. Pandya Aq Mt hmp@FreeBSD.org . +.Sh BUGS +The +.Dv LOCKPARENT +flag does not always result in the parent vnode being locked. +This results in complications when the +.Dv LOCKPARENT +is used. +In order to solve this for the cases where both +.Dv LOCKPARENT +and +.Dv LOCKLEAF +are used, it is necessary to resort to recursive locking. diff --git a/static/freebsd/man9/netisr.9 b/static/freebsd/man9/netisr.9 new file mode 100644 index 00000000..6bb59b45 --- /dev/null +++ b/static/freebsd/man9/netisr.9 @@ -0,0 +1,226 @@ +.\" +.\" Copyright (c) 2009 Robert N. M. Watson +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 12, 2023 +.Dt NETISR 9 +.Os +.Sh NAME +.Nm netisr +.Nd Kernel network dispatch service +.Sh SYNOPSIS +.In net/netisr.h +.Ft void +.Fn netisr_register "const struct netisr_handler *nhp" +.Ft void +.Fn netisr_unregister "const struct netisr_handler *nhp" +.Ft int +.Fn netisr_dispatch "u_int proto" "struct mbuf *m" +.Ft int +.Fn netisr_dispatch_src "u_int proto" "uintptr_t source" "struct mbuf *m" +.Ft int +.Fn netisr_queue "u_int proto" "struct mbuf *m" +.Ft int +.Fn netisr_queue_src "u_int proto" "uintptr_t source" "struct mbuf *m" +.Ft void +.Fn netisr_clearqdrops "const struct netisr_handler *nhp" +.Ft void +.Fn netisr_getqdrops "const struct netisr_handler *nhp" "uint64_t *qdropsp" +.Ft void +.Fn netisr_getqlimit "const struct netisr_handler *nhp" "u_int *qlimitp" +.Ft int +.Fn netisr_setqlimit "const struct netisr_handler *nhp" "u_int qlimit" +.Ft u_int +.Fn netisr_default_flow2cpu "u_int flowid" +.Ft u_int +.Fn netisr_get_cpucount "void" +.Ft u_int +.Fn netisr_get_cpuid "u_int cpunumber" +.Pp +With optional virtual network stack support enabled via the following kernel +compile option: +.Bd -ragged -offset indent +.Cd "options VIMAGE" +.Ed +.Ft void +.Fn netisr_register_vnet "const struct netisr_handler *nhp" +.Ft void +.Fn netisr_unregister_vnet "const struct netisr_handler *nhp" +.Sh DESCRIPTION +The +.Nm +kernel interface suite allows device drivers (and other packet sources) to +direct packets to protocols for directly dispatched or deferred processing. +Protocol registration and work stream statistics may be monitored using +.Xr netstat 1 . +.Ss Protocol registration +Protocols register and unregister handlers using +.Fn netisr_register +and +.Fn netisr_unregister , +and may also manage queue limits and statistics using the +.Fn netisr_clearqdrops , +.Fn netisr_getqdrops , +.Fn netisr_getqlimit , +and +.Fn netisr_setqlimit . +.Pp +In case of VIMAGE kernels each virtual network stack (vnet), that is not the +default base system network stack, calls +.Fn netisr_register_vnet +and +.Fn netisr_unregister_vnet +to enable or disable packet processing by the +.Nm +for each protocol. +Disabling will also purge any outstanding packet from the protocol queue. +.Pp +.Nm +supports multi-processor execution of handlers, and relies on a combination +of source ordering and protocol-specific ordering and work-placement +policies to decide how to distribute work across one or more worker +threads. +Registering protocols will declare one of three policies: +.Bl -tag -width NETISR_POLICY_SOURCE +.It Dv NETISR_POLICY_SOURCE +.Nm +should maintain source ordering without advice from the protocol. +.Nm +will ignore any flow IDs present on +.Vt mbuf +headers for the purposes of work placement. +.It Dv NETISR_POLICY_FLOW +.Nm +should maintain flow ordering as defined by the +.Vt mbuf +header flow ID field. +If the protocol implements +.Va nh_m2flow , +then +.Nm +will query the protocol in the event that the +.Vt mbuf +doesn't have a flow ID, falling back on source ordering. +.It NETISR_POLICY_CPU +.Nm +will entirely delegate all work placement decisions to the protocol, +querying +.Va nh_m2cpuid +for each packet. +.El +.Pp +Registration is declared using +.Vt "struct netisr_handler" , +whose fields are defined as follows: +.Bl -tag -width "netisr_handler_t nh_handler" +.It Vt "const char *" Va nh_name +Unique character string name of the protocol, which may be included in +.Xr sysctl 3 +MIB names, so should not contain whitespace. +.It Vt netisr_handler_t Va nh_handler +Protocol handler function that will be invoked on each packet received for +the protocol. +.It Vt netisr_m2flow_t Va nh_m2flow +Optional protocol function to generate a flow ID and set a valid +hashtype for packets that enter the +.Nm +with +.Dv M_HASHTYPE_GET(m) +equal to +.Dv M_HASHTYPE_NONE . +Will be used only with +.Dv NETISR_POLICY_FLOW . +.It Vt netisr_m2cpuid_t Va nh_m2cpuid +Protocol function to determine what CPU a packet should be processed on. +Will be used only with +.Dv NETISR_POLICY_CPU . +.It Vt netisr_drainedcpu_t Va nh_drainedcpu +Optional callback function that will be invoked when a per-CPU queue +was drained. +It will never fire for directly dispatched packets. +Unless fully understood, this special-purpose function should not be used. +.\" In case you intend to use this please send 50 chocolate bars to each +.\" of rwatson and bz and wait for an answer. +.It Vt u_int Va nh_proto +Protocol number used by both protocols to identify themselves to +.Nm , +and by packet sources to select what handler will be used to process +packets. +A table of supported protocol numbers appears below. +For implementation reasons, protocol numbers great than 15 are currently +unsupported. +.It Vt u_int Va nh_qlimit +The maximum per-CPU queue depth for the protocol; due to internal +implementation details, the effective queue depth may be as much as twice +this number. +.It Vt u_int Va nh_policy +The ordering and work placement policy for the protocol, as described +earlier. +.El +.Ss Packet source interface +Packet sources, such as network interfaces, may request protocol processing +using the +.Fn netisr_dispatch +and +.Fn netisr_queue +interfaces. +Both accept a protocol number and +.Vt mbuf +argument, but while +.Fn netisr_queue +will always execute the protocol handler asynchronously in a deferred +context, +.Fn netisr_dispatch +will optionally direct dispatch if permitted by global and per-protocol +policy. +.Pp +In order to provide additional load balancing and flow information, +packet sources may also specify an opaque source identifier, which in +practice might be a network interface number or socket pointer, using +the +.Fn netisr_dispatch_src +and +.Fn netisr_queue_src +variants. +.Ss Protocol number constants +The follow protocol numbers are currently defined: +.Bl -tag -width NETISR_ROUTE +.It Dv NETISR_IP +IPv4 +.It Dv NETISR_IGMP +IGMPv3 loopback +.It Dv NETISR_ROUTE +Routing socket loopback +.It Dv NETISR_ARP +ARP +.It Dv NETISR_IPV6 +IPv6 +.El +.Sh AUTHORS +This manual page and the +.Nm +implementation were written by +.An Robert N. M. Watson . diff --git a/static/freebsd/man9/nv.9 b/static/freebsd/man9/nv.9 new file mode 100644 index 00000000..8c99f1d1 --- /dev/null +++ b/static/freebsd/man9/nv.9 @@ -0,0 +1,1099 @@ +.\" +.\" Copyright (c) 2013 The FreeBSD Foundation +.\" Copyright (c) 2013-2015 Mariusz Zaborski +.\" All rights reserved. +.\" +.\" This documentation was written by Pawel Jakub Dawidek under sponsorship +.\" the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 3, 2025 +.Dt NV 9 +.Os +.Sh NAME +.Nm nvlist_create , +.Nm nvlist_destroy , +.Nm nvlist_error , +.Nm nvlist_set_error , +.Nm nvlist_empty , +.Nm nvlist_flags , +.Nm nvlist_exists , +.Nm nvlist_free , +.Nm nvlist_clone , +.Nm nvlist_dump , +.Nm nvlist_fdump , +.Nm nvlist_size , +.Nm nvlist_pack , +.Nm nvlist_unpack , +.Nm nvlist_send , +.Nm nvlist_recv , +.Nm nvlist_xfer , +.Nm nvlist_in_array , +.Nm nvlist_next , +.Nm nvlist_add , +.Nm nvlist_move , +.Nm nvlist_get , +.Nm nvlist_take , +.Nm nvlist_append +.Nd "library for name/value pairs" +.Sh LIBRARY +.Lb libnv +.Sh SYNOPSIS +.In sys/nv.h +.Ft "nvlist_t *" +.Fn nvlist_create "int flags" +.Ft void +.Fn nvlist_destroy "nvlist_t *nvl" +.Ft int +.Fn nvlist_error "const nvlist_t *nvl" +.Ft void +.Fn nvlist_set_error "nvlist_t *nvl" "int error" +.Ft bool +.Fn nvlist_empty "const nvlist_t *nvl" +.Ft int +.Fn nvlist_flags "const nvlist_t *nvl" +.Ft bool +.Fn nvlist_in_array "const nvlist_t *nvl" +.\" +.Ft "nvlist_t *" +.Fn nvlist_clone "const nvlist_t *nvl" +.\" +.Ft void +.Fn nvlist_dump "const nvlist_t *nvl" "int fd" +.Ft void +.Fn nvlist_fdump "const nvlist_t *nvl" "FILE *fp" +.\" +.Ft size_t +.Fn nvlist_size "const nvlist_t *nvl" +.Ft "void *" +.Fn nvlist_pack "const nvlist_t *nvl" "size_t *sizep" +.Ft "nvlist_t *" +.Fn nvlist_unpack "const void *buf" "size_t size" "int flags" +.\" +.Ft int +.Fn nvlist_send "int sock" "const nvlist_t *nvl" +.Ft "nvlist_t *" +.Fn nvlist_recv "int sock" "int flags" +.Ft "nvlist_t *" +.Fn nvlist_xfer "int sock" "nvlist_t *nvl" "int flags" +.\" +.Ft "const char *" +.Fn nvlist_next "const nvlist_t *nvl" "int *typep" "void **cookiep" +.\" +.Ft bool +.Fn nvlist_exists "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_type "const nvlist_t *nvl" "const char *name" "int type" +.Ft bool +.Fn nvlist_exists_null "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_bool "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_number "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_string "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_nvlist "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_descriptor "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_binary "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_bool_array "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_number_array "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_string_array "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_nvlist_array "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_descriptor_array "const nvlist_t *nvl" "const char *name" +.\" +.Ft void +.Fn nvlist_add_null "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_add_bool "nvlist_t *nvl" "const char *name" "bool value" +.Ft void +.Fn nvlist_add_number "nvlist_t *nvl" "const char *name" "uint64_t value" +.Ft void +.Fn nvlist_add_string "nvlist_t *nvl" "const char *name" "const char *value" +.Ft void +.Fn nvlist_add_stringf "nvlist_t *nvl" "const char *name" "const char *valuefmt" "..." +.Ft void +.Fn nvlist_add_stringv "nvlist_t *nvl" "const char *name" "const char *valuefmt" "va_list valueap" +.Ft void +.Fn nvlist_add_nvlist "nvlist_t *nvl" "const char *name" "const nvlist_t *value" +.Ft void +.Fn nvlist_add_descriptor "nvlist_t *nvl" "const char *name" "int value" +.Ft void +.Fn nvlist_add_binary "nvlist_t *nvl" "const char *name" "const void *value" "size_t size" +.Ft void +.Fn nvlist_add_bool_array "nvlist_t *nvl" "const char *name" "const bool *value" "size_t nitems" +. +.Ft void +.Fn nvlist_add_number_array "nvlist_t *nvl" "const char *name" "const uint64_t *value" "size_t nitems" +. +.Ft void +.Fn nvlist_add_string_array "nvlist_t *nvl" "const char *name" "const char * const * value" "size_t nitems" +. +.Ft void +.Fn nvlist_add_nvlist_array "nvlist_t *nvl" "const char *name" "const nvlist_t * const * value" "size_t nitems" +. +.Ft void +.Fn nvlist_add_descriptor_array "nvlist_t *nvl" "const char *name" "const int *value" "size_t nitems" +.\" +.Ft void +.Fn nvlist_move_string "nvlist_t *nvl" "const char *name" "char *value" +.Ft void +.Fn nvlist_move_nvlist "nvlist_t *nvl" "const char *name" "nvlist_t *value" +.Ft void +.Fn nvlist_move_descriptor "nvlist_t *nvl" "const char *name" "int value" +.Ft void +.Fn nvlist_move_binary "nvlist_t *nvl" "const char *name" "void *value" "size_t size" +.Ft void +.Fn nvlist_move_bool_array "nvlist_t *nvl" "const char *name" "bool *value" "size_t nitems" +. +.Ft void +.Fn nvlist_move_number_array "nvlist_t *nvl" "const char *name" "uint64_t *value" "size_t nitems" +. +.Ft void +.Fn nvlist_move_string_array "nvlist_t *nvl" "const char *name" "char **value" "size_t nitems" +. +.Ft void +.Fn nvlist_move_nvlist_array "nvlist_t *nvl" "const char *name" "nvlist_t **value" "size_t nitems" +. +.Ft void +.Fn nvlist_move_descriptor_array "nvlist_t *nvl" "const char *name" "int *value" "size_t nitems" +.\" +.Ft bool +.Fn nvlist_get_bool "const nvlist_t *nvl" "const char *name" +.Ft uint64_t +.Fn nvlist_get_number "const nvlist_t *nvl" "const char *name" +.Ft "const char *" +.Fn nvlist_get_string "const nvlist_t *nvl" "const char *name" +.Ft "const nvlist_t *" +.Fn nvlist_get_nvlist "const nvlist_t *nvl" "const char *name" +.Ft int +.Fn nvlist_get_descriptor "const nvlist_t *nvl" "const char *name" +.Ft "const void *" +.Fn nvlist_get_binary "const nvlist_t *nvl" "const char *name" "size_t *sizep" +.Ft "const bool *" +.Fn nvlist_get_bool_array "const nvlist_t *nvl" "const char *name" "size_t *nitems" +.Ft "const uint64_t *" +.Fn nvlist_get_number_array "const nvlist_t *nvl" "const char *name" "size_t *nitems" +.Ft "const char * const *" +.Fn nvlist_get_string_array "const nvlist_t *nvl" "const char *name" "size_t *nitems" +.Ft "const nvlist_t * const *" +.Fn nvlist_get_nvlist_array "const nvlist_t *nvl" "const char *name" "size_t *nitems" +.Ft "const int *" +.Fn nvlist_get_descriptor_array "const nvlist_t *nvl" "const char *name" "size_t *nitems" +.Ft "const nvlist_t *" +.Fn nvlist_get_parent "const nvlist_t *nvl" "void **cookiep" +.Ft "const nvlist_t *" +.Fn nvlist_get_array_next "const nvlist_t *nvl" +.Ft "const nvlist_t *" +.Fn nvlist_get_pararr "const nvlist_t *nvl" "void **cookiep" +.\" +.Ft bool +.Fn nvlist_take_bool "nvlist_t *nvl" "const char *name" +.Ft uint64_t +.Fn nvlist_take_number "nvlist_t *nvl" "const char *name" +.Ft "char *" +.Fn nvlist_take_string "nvlist_t *nvl" "const char *name" +.Ft "nvlist_t *" +.Fn nvlist_take_nvlist "nvlist_t *nvl" "const char *name" +.Ft int +.Fn nvlist_take_descriptor "nvlist_t *nvl" "const char *name" +.Ft "void *" +.Fn nvlist_take_binary "nvlist_t *nvl" "const char *name" "size_t *sizep" +.Ft "bool *" +.Fn nvlist_take_bool_array "nvlist_t *nvl" "const char *name" "size_t *nitems" +.Ft "uint64_t **" +.Fn nvlist_take_number_array "nvlist_t *nvl" "const char *name" "size_t *nitems" +.Ft "char **" +.Fn nvlist_take_string_array "nvlist_t *nvl" "const char *name" "size_t *nitems" +.Ft "nvlist_t **" +.Fn nvlist_take_nvlist_array "nvlist_t *nvl" "const char *name" "size_t *nitems" +.Ft "int *" +.Fn nvlist_take_descriptor_array "nvlist_t *nvl" "const char *name" "size_t *nitems" +.\" +.Ft void +.Fn nvlist_append_bool_array "nvlist_t *nvl" "const char *name" "const bool value" +.Ft void +.Fn nvlist_append_number_array "nvlist_t *nvl" "const char *name" "const uint64_t value" +.Ft void +.Fn nvlist_append_string_array "nvlist_t *nvl" "const char *name" "const char * const value" +.Ft void +.Fn nvlist_append_nvlist_array "nvlist_t *nvl" "const char *name" "const nvlist_t * const value" +.Ft void +.Fn nvlist_append_descriptor_array "nvlist_t *nvl" "const char *name" "int value" +.\" +.Ft void +.Fn nvlist_free "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_type "nvlist_t *nvl" "const char *name" "int type" +.\" +.Ft void +.Fn nvlist_free_null "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_bool "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_number "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_string "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_nvlist "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_descriptor "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_binary "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_bool_array "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_number_array "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_string_array "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_nvlist_array "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_descriptor_array "nvlist_t *nvl" "const char *name" +.Sh DESCRIPTION +The +.Nm libnv +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 for values: +.Bl -ohang -offset indent +.It Sy null ( NV_TYPE_NULL ) +There is no data associated with the name. +.It Sy bool ( NV_TYPE_BOOL ) +The value can be either +.Dv true +or +.Dv false . +.It Sy number ( NV_TYPE_NUMBER ) +The value is a number stored as +.Vt uint64_t . +.It Sy string ( NV_TYPE_STRING ) +The value is a C string. +.It Sy nvlist ( NV_TYPE_NVLIST ) +The value is a nested nvlist. +.It Sy descriptor ( NV_TYPE_DESCRIPTOR ) +The value is a file descriptor. +Note that file descriptors can be sent only over +.Xr unix 4 +domain sockets. +.It Sy binary ( NV_TYPE_BINARY ) +The value is a binary buffer. +.It Sy bool array ( NV_TYPE_BOOL_ARRAY ) +The value is an array of boolean values. +.It Sy number array ( NV_TYPE_NUMBER_ARRAY ) +The value is an array of numbers, each stored as +.Vt uint64_t . +.It Sy string array ( NV_TYPE_STRING_ARRAY ) +The value is an array of C strings. +.It Sy nvlist array ( NV_TYPE_NVLIST_ARRAY ) +The value is an array of nvlists. +When an nvlist is added to an array, it becomes part of the primary nvlist. +Traversing these arrays can be done using the +.Fn nvlist_get_array_next +and +.Fn nvlist_get_pararr +functions. +.It Sy descriptor array ( NV_TYPE_DESCRIPTOR_ARRAY ) +The value is an array of files descriptors. +.El +.Pp +The +.Fn nvlist_create +function allocates memory and initializes an nvlist. +.Pp +The following flags can be provided: +.Pp +.Bl -tag -width "NV_FLAG_IGNORE_CASE" -compact -offset indent +.It Dv NV_FLAG_IGNORE_CASE +Perform case-insensitive lookups of provided names. +.It Dv NV_FLAG_NO_UNIQUE +Names in the nvlist do not have to be unique. +.El +.Pp +The +.Fn nvlist_destroy +function destroys the given nvlist. +This function does nothing if +.Fa nvl +is +.Dv NULL . +This function never modifies +.Va errno . +.Pp +The +.Fn nvlist_error +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 +is returned. +.Pp +The +.Fn nvlist_set_error +function sets an the error value for +.Fa nvl . +Subsequent calls to +.Fn nvlist_error +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 +The +.Fn nvlist_empty +function returns +.Dv true +if +.Fa nvl +is empty and +.Dv false +otherwise. +The nvlist must not be in the error state. +.Pp +The +.Fn nvlist_flags +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 +function returns +.Dv true +if +.Fa nvl +is part of an array that is a member of another nvlist. +.Pp +The +.Fn nvlist_clone +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 +.Xr dup 2 +system call before placing them in the clone. +.Pp +The +.Fn nvlist_dump +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 file stream +.Fa fp . +.Pp +The +.Fn nvlist_size +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 +.Xr free 3 +function. +If the +.Fa sizep +argument is not +.Dv NULL , +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 the error state. +.Pp +The +.Fn nvlist_unpack +function converts a binary buffer to a new nvlist. +The +.Fa flags +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 +.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 an nvlist over the socket +.Fa sock . +As with +.Fn nvlist_unpack , +the +.Fa flags +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 +.Fa nvl +over the socket +.Fa sock +argument and then receives a new nvlist over the same socket. +The +.Fa flags +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 +.Fa nvl +returning the names and types of subsequent +elements. +The +.Fa cookiep +argument determines which element is returned. +If +.Va *cookiep +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 +when there are no more elements on +.Fa nvl . +The +.Fa typep +argument can be +.Dv NULL . +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 an element named +.Fa name +exists in +.Fa nvl +(regardless of type) or +.Dv false +otherwise. +The nvlist must not be in the error state. +.Pp +The +.Fn nvlist_exists_type +function returns +.Dv true +if an element named +.Fa name +of type +.Fa type +exists or +.Dv false +otherwise. +The nvlist must not be in the error state. +.Pp +The +.Fn nvlist_exists_null , +.Fn nvlist_exists_bool , +.Fn nvlist_exists_number , +.Fn nvlist_exists_string , +.Fn nvlist_exists_nvlist , +.Fn nvlist_exists_descriptor , +.Fn nvlist_exists_binary , +.Fn nvlist_exists_bool_array , +.Fn nvlist_exists_number_array , +.Fn nvlist_exists_string_array , +.Fn nvlist_exists_nvlist_array , +.Fn nvlist_exists_descriptor_array +functions return +.Dv true +if element named +.Fa name +with the type determined by the function name +exists or +.Dv false +otherwise. +The nvlist must not be in the error state. +.Pp +The +.Fn nvlist_add_null , +.Fn nvlist_add_bool , +.Fn nvlist_add_number , +.Fn nvlist_add_string , +.Fn nvlist_add_stringf , +.Fn nvlist_add_stringv , +.Fn nvlist_add_nvlist , +.Fn nvlist_add_descriptor , +.Fn nvlist_add_binary , +.Fn nvlist_add_bool_array , +.Fn nvlist_add_number_array , +.Fn nvlist_add_string_array , +.Fn nvlist_add_nvlist_array , +.Fn nvlist_add_descriptor_array +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 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 a new element, +an internal error is set which can be +examined using the +.Fn nvlist_error +function. +.Pp +The +.Fn nvlist_move_string , +.Fn nvlist_move_nvlist , +.Fn nvlist_move_descriptor , +.Fn nvlist_move_binary , +.Fn nvlist_move_bool_array , +.Fn nvlist_move_number_array , +.Fn nvlist_move_string_array , +.Fn nvlist_move_nvlist_array , +.Fn nvlist_move_descriptor_array +functions add an element to +.Fa nvl , +but unlike the +.Fn nvlist_add_ +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 +an internal error is set which can be examined using the +.Fn nvlist_error +function. +.Pp +The +.Fn nvlist_get_bool , +.Fn nvlist_get_number , +.Fn nvlist_get_string , +.Fn nvlist_get_nvlist , +.Fn nvlist_get_descriptor , +.Fn nvlist_get_binary , +.Fn nvlist_get_bool_array , +.Fn nvlist_get_number_array , +.Fn nvlist_get_string_array , +.Fn nvlist_get_nvlist_array , +.Fn nvlist_get_descriptor_array +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 +.Fa nvl . +.Pp +The +.Fn nvlist_get_array_next +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_move_nvlist_array . +.Pp +The +.Fn nvlist_get_pararr +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 , +.Fn nvlist_take_number , +.Fn nvlist_take_string , +.Fn nvlist_take_nvlist , +.Fn nvlist_take_descriptor , +.Fn nvlist_take_binary , +.Fn nvlist_take_bool_array , +.Fn nvlist_take_number_array , +.Fn nvlist_take_string_array , +.Fn nvlist_take_nvlist_array , +.Fn nvlist_take_descriptor_array +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. +For nvlist values, the caller is responsible for destroying the returned nvlist +using the +.Fn nvlist_destroy +function. +For file descriptor values, the caller is responsible for closing the +returned descriptor +using the +.Fn close 2 +system call. +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. +.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 , +.Fn nvlist_append_number_array , +.Fn nvlist_append_string_array , +.Fn nvlist_append_nvlist_array , +.Fn nvlist_append_descriptor_array +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__array +function. +If an error occurs while appending a new element, +an internal error is set on +.Fa nvl . +.Pp +The +.Fn nvlist_free +function removes the first element named +.Fa name +from +.Fa nvl +(regardless of type) +and frees all resources associated with it. +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 the first element named +.Fa name +of type +.Fa type +from +.Fa nvl +and frees all resources associated with it. +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 , +.Fn nvlist_free_bool , +.Fn nvlist_free_number , +.Fn nvlist_free_string , +.Fn nvlist_free_nvlist , +.Fn nvlist_free_descriptor , +.Fn nvlist_free_binary , +.Fn nvlist_free_bool_array , +.Fn nvlist_free_number_array , +.Fn nvlist_free_string_array , +.Fn nvlist_free_nvlist_array , +.Fn nvlist_free_descriptor_array +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 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 a +.Xr unix 4 +domain socket. +.Bd -literal +nvlist_t *nvl; +int fd; + +fd = open("/tmp/foo", O_RDONLY); +if (fd < 0) + err(1, "open(\\"/tmp/foo\\") failed"); + +nvl = nvlist_create(0); + +/* + * There is no need to check if nvlist_create() succeeded + * as the nvlist_add_() 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 is why we use nvlist_move + * not nvlist_add). + */ +nvlist_move_descriptor(nvl, "fd", fd); +if (nvlist_send(sock, nvl) < 0) { + nvlist_destroy(nvl); + err(1, "nvlist_send() failed"); +} +nvlist_destroy(nvl); +.Ed +.Pp +Receiving an nvlist and retrieving element values: +.Bd -literal +nvlist_t *nvl; +const char *command; +char *filename; +int fd; + +nvl = nvlist_recv(sock, 0); +if (nvl == NULL) + err(1, "nvlist_recv() failed"); + +/* 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 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); +.Ed +.Pp +Iterating over an nvlist: +.Bd -literal +nvlist_t *nvl; +const char *name; +void *cookie; +int type; + +nvl = nvlist_recv(sock, 0); +if (nvl == NULL) + err(1, "nvlist_recv() failed"); + +cookie = NULL; +while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) { + printf("%s=", name); + switch (type) { + case NV_TYPE_NUMBER: + printf("%ju", (uintmax_t)nvlist_get_number(nvl, name)); + break; + case NV_TYPE_STRING: + printf("%s", nvlist_get_string(nvl, name)); + break; + default: + printf("N/A"); + break; + } + printf("\\n"); +} +.Ed +.Pp +Iterating over every nested nvlist: +.Bd -literal +nvlist_t *nvl; +const char *name; +void *cookie; +int type; + +nvl = nvlist_recv(sock, 0); +if (nvl == NULL) + err(1, "nvlist_recv() failed"); + +cookie = NULL; +do { + while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) { + if (type == NV_TYPE_NVLIST) { + nvl = nvlist_get_nvlist(nvl, name); + cookie = NULL; + } + } +} while ((nvl = nvlist_get_parent(nvl, &cookie)) != NULL); +.Ed +.Pp +Iterating over every nested nvlist and every nvlist element: +.Bd -literal +nvlist_t *nvl; +const nvlist_t * const *array; +const char *name; +void *cookie; +int type; + +nvl = nvlist_recv(sock, 0); +if (nvl == null) + err(1, "nvlist_recv() failed"); + +cookie = NULL; +do { + while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) { + if (type == NV_TYPE_NVLIST) { + nvl = nvlist_get_nvlist(nvl, name); + cookie = NULL; + } else if (type == NV_TYPE_NVLIST_ARRAY) { + nvl = nvlist_get_nvlist_array(nvl, name, NULL)[0]; + cookie = NULL; + } + } +} while ((nvl = nvlist_get_pararr(nvl, &cookie)) != NULL); +.Ed +.Pp +Or alternatively: +.Bd -literal +nvlist_t *nvl, *tmp; +const nvlist_t * const *array; +const char *name; +void *cookie; +int type; + +nvl = nvlist_recv(sock, 0); +if (nvl == null) + err(1, "nvlist_recv() failed"); + +cooke = NULL; +tmp = nvl; +do { + do { + nvl = tmp; + while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) { + if (type == NV_TYPE_NVLIST) { + nvl = nvlist_get_nvlist(nvl, name); + cookie = NULL; + } else if (type == NV_TYPE_NVLIST_ARRAY) { + nvl = nvlist_get_nvlist_array(nvl, name, + NULL)[0]; + cookie = NULL; + } + } + cookie = NULL; + } while ((tmp = nvlist_get_array_next(nvl)) != NULL); +} while ((tmp = nvlist_get_parent(nvl, &cookie)) != NULL); +.Ed +.Sh SEE ALSO +.Xr close 2 , +.Xr dup 2 , +.Xr open 2 , +.Xr err 3 , +.Xr free 3 , +.Xr printf 3 , +.Xr unix 4 +.Sh HISTORY +The +.Nm libnv +library appeared in +.Fx 11.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm libnv +library was implemented by +.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net +under sponsorship from the FreeBSD Foundation. diff --git a/static/freebsd/man9/nvmem.9 b/static/freebsd/man9/nvmem.9 new file mode 100644 index 00000000..fa88cbb9 --- /dev/null +++ b/static/freebsd/man9/nvmem.9 @@ -0,0 +1,154 @@ +.\" Copyright (c) 2018 Emmanuel Vadot +.\" +.\" 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 July 24, 2018 +.Dt nvmem 9 +.Os +.Sh NAME +.Nm nvmem , +.Nm nvmem_get_cell_len , +.Nm nvmem_read_cell_by_name , +.Nm nvmem_read_cell_by_idx , +.Nm nvmem_write_cell_by_name , +.Nm nvmem_write_cell_by_idx +.Sh SYNOPSIS +.Cd "options FDT" +.Cd "device nvmem" +.In sys/extres/nvmem/nvmem.h +.Ft int +.Fn nvmem_get_cell_len "phandle_t node" "const char *name" +.Ft int +.Fn nvmem_read_cell_by_name "phandle_t node" "const char *name" "void *cell" "size_t buflen" +.Ft int +.Fn nvmem_read_cell_by_idx "phandle_t node" "int idx" "void *cell" "size_t buflen" +.Ft int +.Fn nvmem_write_cell_by_name "phandle_t node" "const char *name" "void *cell" "size_t buflen" +.Ft int +.Fn nvmem_write_cell_by_idx "phandle_t node" "int idx" "void *cell" "size_t buflen" +.Sh DESCRIPTION +On some embedded boards, the manufacturer stored some data on a NVMEM +(Non-Volatile Memory), this is generally stored in some eeprom or fuses. +.Pp +The +.Nm +API consist of helpers functions for consumer and device methods for +providers. +.Sh FUNCTIONS +.Bl -tag -width indent +.It Fn nvmem_get_cell_len "phandle_t node" "const char *name" +Get the size of the cell base on the reg property on the node. +Return the size or ENOENT if the cell name wasn't found +.It Fn nvmem_read_cell_by_name "phandle_t node" "const char *name" "void *cell" "size_t buflen" +Get the cell content based on the name. +Return 0 on success or ENOENT if the cell doesn't exists, ENXIO if no provider device was found, +EINVAL if the size isn't correct. +.It Fn nvmem_read_cell_by_idx "phandle_t node" "int idx" "void *cell" "size_t buflen" +Get the cell content based on the id. +Return 0 on success or ENOENT if the cell doesn't exists, ENXIO if no provider device was found, +EINVAL if the size isn't correct. +.It Fn nvmem_write_cell_by_name "phandle_t node" "const char *name" "void *cell" "size_t buflen" +Write the cell content based on the name. +Return 0 on success or ENOENT if the cell doesn't exists, ENXIO if no provider device was found, +EINVAL if the size isn't correct. +.It Fn nvmem_write_cell_by_idx "phandle_t node" "int idx" "void *cell" "size_t buflen" +Write the cell content based on the id. +Return 0 on success or ENOENT if the cell doesn't exists, ENXIO if no provider device was found, +EINVAL if the size isn't correct. +.El +.Sh DEVICE METHODS +.Bl -tag -width indent +.It Fn nvmem_read "device_t dev" "uint32_t offset" "uint32_t size" "uint8_t *buffer" +Provider device method to read a cell content. +.It Fn nvmem_write "device_t dev" "uint32_t offset" "uint32_t size" "uint8_t *buffer" +Provider device method to write a cell content. +.El +.Sh EXAMPLES +Consider this DTS +.Bd -literal +/* Provider */ +eeprom: eeprom@20000 { + board_id: id@0 { + reg = <0x0 0x4>; + }; +}; +/* Consumer */ +device@30000 { + ... + + nvmem-cells = <&board_id> + nvmem-cell-names = "boardid"; +}; +.Ed +.Pp +The device driver for eeprom@20000 needs to expose itself as a provider +.Bd -literal +#include "nvmem_if.h" + +int +foo_nvmem_read(device_t dev, uint32_t offset, uint32_t size, uint8_t *buffer) +{ + /* Read the data */ +} + +int +foo_attach(device_t dev) +{ + phandle_t node; + + node = ofw_bus_get_node(dev); + ... + /* Registering the device so the consumers can find us */ + OF_device_register_xref(OF_xref_from_node(node), dev); + + ... +} + +static device_method_t foo_methods[] = { + ... + + /* nvmem interface */ + DEVMETHOD(nvmem_read, foo_nvmem_read), + + /* Terminate method list */ + DEVMETHOD_END +}; +.Ed +.Pp +The consumer device driver for device@30000 can now read the nvmem data +.Bd -literal +int +bar_attach(device_t dev) +{ + phandle_t node; + uint32_t boardid; + + ... + node = ofw_bus_get_node(dev); + nvmem_read_cell_by_name(node, "boardid", (void *)&boardid, sizeof(boardid)); + ... +} +.Ed +.Sh HISTORY +The nvmem related function first appear in +.Fx 12.0 . +The nvmem interface and manual page was written by +.An Emmanuel Vadot Aq Mt manu@FreeBSD.org . diff --git a/static/freebsd/man9/ofw_bus_is_compatible.9 b/static/freebsd/man9/ofw_bus_is_compatible.9 new file mode 100644 index 00000000..fcfe8755 --- /dev/null +++ b/static/freebsd/man9/ofw_bus_is_compatible.9 @@ -0,0 +1,144 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2018 Oleksandr Tymoshenko +.\" +.\" 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 April 8, 2018 +.Dt ofw_bus_is_compatible 9 +.Os +.Sh NAME +.Nm ofw_bus_is_compatible , +.Nm ofw_bus_is_compatible_strict , +.Nm ofw_bus_node_is_compatible , +.Nm ofw_bus_search_compatible +.Nd check device tree nodes for compatibility with drivers +.Sh SYNOPSIS +.In dev/ofw/openfirm.h +.In dev/ofw/ofw_bus.h +.In dev/ofw/ofw_bus_subr.h +.Ft int +.Fn ofw_bus_is_compatible "device_t dev" "const char *compatstr" +.Ft int +.Fn ofw_bus_is_compatible_strict "device_t dev" "const char *compatstr" +.Ft int +.Fn ofw_bus_node_is_compatible "phandle_t node" "const char *compatstr" +.Ft const struct ofw_compat_data * +.Fn ofw_bus_search_compatible "device_t dev" "const struct ofw_compat_data *compat" +.Sh DESCRIPTION +The "compatible" property of the device tree node is used to +identify the type of the device the node represents. +The property is a list of one or more strings that represent +hardware types the device is compatible with. +The common format for such strings is "vendor,hardware" +where "vendor" is an abbreviated name of the manufacturer +and "hardware" is a device identifier, for instance, "fsl" +for "Freescale" and "imx6ul-i2c" for the I2C controller. +More than one string is required for compatibility with +older revisions of the driver. +If hardware revision B is backward compatible with revision +A device tree node can signal this compatibility by +providing both "vndr,hrdwrA" and "vndr,hrdwrB" strings in +the "compatible" property value. +This way older driver can use features available only in +revision A, and the new version of the driver can take +advantage of revision B feature set. +.Pp +.Fn ofw_bus_is_compatible +returns 1 if the +.Fa compatstr +value occurs in the "compatible" property list of the device +tree node associated with the device +.Fa dev , +and 0 otherwise. +.Pp +.Fn ofw_bus_is_compatible_strict +return 1 if the "compatible" +property of the device tree node associated with the device +.Fa dev +consists of only one string and this string is equal to +.Fa compatstr , +and 0 otherwise. +.Pp +.Fn ofw_bus_node_is_compatible +returns 1 if the +.Fa compatstr +value occurs in the "compatible" property list of the device +tree node +.Fa node , +and 0 otherwise. +.Pp +.Fn ofw_bus_search_compatible +returns pointer to the first entry of the +.Fa compat +table whose ocd_str field occurs in "compatible" property of +the device tree node associated with the device +.Fa dev . +The +.Fa compat +table is an array of struct ofw_compat_data elements defined as follows: +.Bd -literal -offset indent +struct ofw_compat_data { + const char *ocd_str; + uintptr_t ocd_data; +}; +.Ed +The +.Fa compat +table must be terminated by the entry with ocd_str set to NULL. +If the device tree node is not compatible with any of +the entries, the function returns the pointer to the +terminating entry. +.Sh EXAMPLES +.Bd -literal -offset indent +static struct ofw_compat_data compat_data[] = { + {"arm,hrdwrA", FEATURE_A}, + {"arm,hrdwrB", FEATURE_A | FEATURE_B}, + {NULL, 0} +}; + +static int +hrdwr_probe(device_t dev) +{ + ... + if (!ofw_bus_search_compatible(dev, compat_data)->ocd_data) + return (ENXIO); + ... +} + +static int +hrdwr_attach(device_t dev) +{ + ... + sc = device_get_softc(dev); + sc->sc_features = ofw_bus_search_compatible(dev, compat_data)->ocd_data; + ... +} +.Ed +.Sh SEE ALSO +.Xr ofw_bus_find_compatible 9 +.Sh AUTHORS +This manual page was written by +.An Oleksandr Tymoshenko . diff --git a/static/freebsd/man9/ofw_bus_status_okay.9 b/static/freebsd/man9/ofw_bus_status_okay.9 new file mode 100644 index 00000000..8c77e777 --- /dev/null +++ b/static/freebsd/man9/ofw_bus_status_okay.9 @@ -0,0 +1,74 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2018 Oleksandr Tymoshenko +.\" +.\" 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 April 8, 2018 +.Dt ofw_bus_status_okay 9 +.Os +.Sh NAME +.Nm ofw_bus_get_status , +.Nm ofw_bus_status_okay , +.Nm ofw_bus_node_status_okay +.Nd check status of the device tree node +.Sh SYNOPSIS +.In dev/ofw/openfirm.h +.In dev/ofw/ofw_bus.h +.In dev/ofw/ofw_bus_subr.h +.Ft const char * +.Fn ofw_bus_get_status "device_t dev" +.Ft int +.Fn ofw_bus_status_okay "device_t dev" +.Ft int +.Fn ofw_bus_node_status_okay "phandle_t node" +.Sh DESCRIPTION +The "status" property of the device tree node indicates whether the device is +enabled or not. +Multiple hardware versions might be built using the same base System-on-Chip +but with a different set of blocks enabled. +It is common to use SoC device tree and only enable/disable device nodes for +the derivative boards. +The device tree node is considered enabled only if it has "status" property +with the value set to either "ok" or "okay". +.Pp +.Fn ofw_bus_get_status +returns the value of the "status" property of the device tree node associated with the device +.Fa dev . +If the node does not have "status" property or there is no node associated with +the device the function returns NULL. +.Pp +.Fn ofw_bus_status_okay +returns 1 if the device tree node associated with the device +.Fa dev +has "status" property and its value is either "ok" or "okay". +.Pp +.Fn ofw_bus_node_status_okay +returns 1 if the device tree node +.Fa node +has "status" property and its value is either "ok" or "okay". +.Sh AUTHORS +This manual page was written by +.An Oleksandr Tymoshenko . diff --git a/static/freebsd/man9/ofw_graph.9 b/static/freebsd/man9/ofw_graph.9 new file mode 100644 index 00000000..fe4b7a6b --- /dev/null +++ b/static/freebsd/man9/ofw_graph.9 @@ -0,0 +1,104 @@ +.\" Copyright (c) 2019 Emmanuel Vadot +.\" +.\" 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 April 10, 2019 +.Dt ofw_graph 9 +.Os +.Sh NAME +.Nm ofw_graph , +.Nm ofw_graph_get_port_by_idx , +.Nm ofw_graph_port_get_num_endpoints , +.Nm ofw_graph_get_endpoint_by_idx , +.Nm ofw_graph_get_remote_endpoint , +.Nm ofw_graph_get_remote_parent , +.Nm ofw_graph_get_device_by_port_ep +.Nd Helpers for the graph bindings +.Sh SYNOPSIS +.In dev/ofw/openfirm.h +.In dev/ofw/ofw_graph.h +.Ft phandle_t +.Fn ofw_graph_get_port_by_idx "phandle_t node" "uint32_t idx" +.Ft size_t +.Fn ofw_graph_port_get_num_endpoints "phandle_t port" +.Ft phandle_t +.Fn ofw_graph_get_endpoint_by_idx "phandle_t port" "uint32_t idx" +.Ft phandle_t +.Fn ofw_graph_get_remote_endpoint "phandle_t endpoint" +.Ft phandle_t +.Fn ofw_graph_get_remote_parent "phandle_t remote" +.Ft device_t +.Fn ofw_graph_get_device_by_port_ep "phandle_t node" "uint32_t port_id" "uin32_t ep_id" +.Sh DESCRIPTION +The ofw_graph functions are helpers to parse the DTS graph bindings +.Pp +.Fn ofw_graph_get_port_by_idx +return the port with id +.Fa idx . +It will first check node named +.Fa port@idx +and then fallback on checking the +.Fa ports +child for a child node matching the id. +If no ports matching +.Fa idx +is found the function return 0. +.Pp +.Fn ofw_graph_port_get_num_endpoints +returns the number of endpoints a port node have. +.Pp +.Fn ofw_graph_get_endpoint_by_idx +return the endpoint with id +.Fa idx . +It will first check if there is a single child named +.Fa endpoint +and returns it if there is. +If there is multiple endpoints it will check the +.Fa reg +property and returns the correct +.Fa phandle_t +or 0 if none match. +.Pp +.Fn ofw_graph_get_remote_endpoint +returns the +.Fa remote-endpoint +property if it exists or 0. +.Pp +.Fn ofw_graph_get_remote_parent +returns the device node corresponding to the +.Fa remote-endpoint +phandle or 0 if none. +.Fn ofw_graph_get_device_by_port_ep +returns the device associated with the port and endpoint or +.Fa NULL +if none. +The device driver should have called +.Fn OF_device_register_xref +before. +.Sh HISTORY +The +.Nm ofw_graph +functions first appeared in +.Fx 13.0 . +The +.Nm ofw_graph +functions and manual page were written by +.An Emmanuel Vadot Aq Mt manu@FreeBSD.org . diff --git a/static/freebsd/man9/osd.9 b/static/freebsd/man9/osd.9 new file mode 100644 index 00000000..5e0e4829 --- /dev/null +++ b/static/freebsd/man9/osd.9 @@ -0,0 +1,448 @@ +.\" +.\" Copyright (c) 2010 Lawrence Stewart +.\" 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, +.\" without modification, immediately at the beginning of the file. +.\" 2. 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 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 October 07, 2024 +.Dt OSD 9 +.Os +.Sh NAME +.Nm osd , +.Nm osd_register , +.Nm osd_deregister , +.Nm osd_set , +.Nm osd_reserve , +.Nm osd_set_reserved , +.Nm osd_free_reserved , +.Nm osd_get , +.Nm osd_del , +.Nm osd_call , +.Nm osd_exit +.Nd Object Specific Data +.Sh SYNOPSIS +.In sys/osd.h +.Ft typedef void +.Fn "\*(lp*osd_destructor_t\*(rp" "void *value" +.Ft typedef int +.Fn "\*(lp*osd_method_t\*(rp" "void *obj" "void *data" +.Ft int +.Fo osd_register +.Fa "u_int type" +.Fa "osd_destructor_t destructor" +.Fa "const osd_method_t *methods" +.Fc +.Ft void +.Fo osd_deregister +.Fa "u_int type" +.Fa "u_int slot" +.Fc +.Ft int +.Fo osd_set +.Fa "u_int type" +.Fa "struct osd *osd" +.Fa "u_int slot" +.Fa "void *value" +.Fc +.Ft void ** +.Fo osd_reserve +.Fa "u_int slot" +.Fc +.Ft int +.Fo osd_set_reserved +.Fa "u_int type" +.Fa "struct osd *osd" +.Fa "u_int slot" +.Fa "void **rsv" +.Fa "void *value" +.Fc +.Ft void +.Fo osd_free_reserved +.Fa "void **rsv" +.Fc +.Ft void * +.Fo osd_get +.Fa "u_int type" +.Fa "struct osd *osd" +.Fa "u_int slot" +.Fc +.Ft void +.Fo osd_del +.Fa "u_int type" +.Fa "struct osd *osd" +.Fa "u_int slot" +.Fc +.Ft int +.Fo osd_call +.Fa "u_int type" +.Fa "u_int method" +.Fa "void *obj" +.Fa "void *data" +.Fc +.Ft void +.Fo osd_exit +.Fa "u_int type" +.Fa "struct osd *osd" +.Fc +.Sh DESCRIPTION +The +.Nm +framework provides a mechanism to dynamically associate arbitrary data at +run-time with any kernel data structure which has been suitably modified for use +with +.Nm . +The one-off modification required involves embedding a +.Vt "struct osd" +inside the kernel data structure. +.Pp +An additional benefit is that after the initial change to a structure is made, +all subsequent use of +.Nm +with the structure involves no changes to the structure's layout. +By extension, if the data structure is part of the ABI, +.Nm +provides a way of extending the structure in an ABI preserving manner. +.Pp +The details of the embedded +.Vt "struct osd" +are not relevant to consumers of the +.Nm +framework and should not be manipulated directly. +.Pp +Data associated with a structure is referenced by the +.Nm +framework using a type/slot identifier pair. +Types are statically defined in +.In sys/osd.h +and provide a high-level grouping for slots to be registered under. +Slot identifiers are dynamically assigned by the framework when a data type is +registered using +.Fn osd_register +and remains valid until a corresponding call to +.Fn osd_deregister . +.Ss Functions +The +.Fn osd_register +function registers a type/slot identifier pair with the +.Nm +framework for use with a new data type. +The function may sleep and therefore cannot be called from a non-sleepable +context. +The +.Fa type +argument specifies which high-level type grouping from +.In sys/osd.h +the slot identifier should be allocated under. +The +.Fa destructor +argument specifies an optional osd_destructor_t function pointer that will be +called for objects of the type being registered which are later destroyed by the +.Fn osd_del +function. +NULL may be passed if no destructor is required. +The +.Fa methods +argument specifies an optional array of osd_method_t function pointers which +can be later invoked by the +.Fn osd_call +function. +NULL may be passed if no methods are required. +The +.Fa methods +argument is currently only useful with the OSD_JAIL type identifier. +.Pp +The +.Fn osd_deregister +function deregisters a previously registered type/slot identifier pair. +The function may sleep and therefore cannot be called from a non-sleepable +context. +The +.Fa type +argument specifies which high-level type grouping from +.In sys/osd.h +the slot identifier is allocated under. +The +.Fa slot +argument specifies the slot identifier which is being deregistered and should be +the value that was returned by +.Fn osd_register +when the data type was registered. +.Pp +The +.Fn osd_set +function associates a data object pointer with a kernel data structure's +.Vt struct osd +member. +The +.Fa type +argument specifies which high-level type grouping from +.In sys/osd.h +the slot identifier is allocated under. +The +.Fa osd +argument is a pointer to the kernel data structure's +.Vt struct osd +which will have the +.Fa value +pointer associated with it. +The +.Fa slot +argument specifies the slot identifier to assign the +.Fa value +pointer to. +The +.Fa value +argument points to a data object to associate with +.Fa osd . +.Pp +The +.Fn osd_set_reserved +function does the same as +.Fn osd_set , +but with an extra argument +.Fa rsv +that is internal-use memory previously allocated via +.Fn osd_reserve . +.Pp +The +.Fn osd_get +function returns the data pointer associated with a kernel data structure's +.Vt struct osd +member from the specified type/slot identifier pair. +The +.Fa type +argument specifies which high-level type grouping from +.In sys/osd.h +the slot identifier is allocated under. +The +.Fa osd +argument is a pointer to the kernel data structure's +.Vt struct osd +to retrieve the data pointer from. +The +.Fa slot +argument specifies the slot identifier to retrieve the data pointer from. +.Pp +The +.Fn osd_del +function removes the data pointer associated with a kernel data structure's +.Vt struct osd +member from the specified type/slot identifier pair. +The +.Fa type +argument specifies which high-level type grouping from +.In sys/osd.h +the slot identifier is allocated under. +The +.Fa osd +argument is a pointer to the kernel data structure's +.Vt struct osd +to remove the data pointer from. +The +.Fa slot +argument specifies the slot identifier to remove the data pointer from. +If an osd_destructor_t function pointer was specified at registration time, the +destructor function will be called and passed the data pointer for the type/slot +identifier pair which is being deleted. +.Pp +The +.Fn osd_call +function calls the specified osd_method_t function pointer for all +currently registered slots of a given type on the specified +.Fa obj +and +.Fa data +pointers. +The function may sleep and therefore cannot be called from a non-sleepable +context. +The +.Fa type +argument specifies which high-level type grouping from +.In sys/osd.h +to call the method for. +The +.Fa method +argument specifies the index into the osd_method_t array that was passed to +.Fn osd_register . +The +.Fa obj +and +.Fa data +arguments are passed to the method function pointer of each slot. +.Pp +The +.Fn osd_exit +function removes all data object pointers from all currently registered slots +for a given type for the specified kernel data structure's +.Vt struct osd +member. +The +.Fa type +argument specifies which high-level type grouping from +.In sys/osd.h +to remove data pointers from. +The +.Fa osd +argument is a pointer to the kernel data structure's +.Vt struct osd +to remove all data object pointers for all currently registered slots from. +.Sh IMPLEMENTATION NOTES +.Nm +uses a two dimensional matrix (array of arrays) as the data structure to manage +the external data associated with a kernel data structure's +.Vt struct osd +member. +The type identifier is used as the index into the outer array, and the slot +identifier is used as the index into the inner array. +To set or retrieve a data pointer for a given type/slot identifier pair, +.Fn osd_set +and +.Fn osd_get +perform the equivalent of array[type][slot], which is both constant time and +fast. +.Pp +If +.Fn osd_set +is called on a +.Vt struct osd +for the first time, the array for storing data pointers is dynamically allocated +using +.Xr malloc 9 +with M_NOWAIT to a size appropriate for the slot identifier being set. +If a subsequent call to +.Fn osd_set +attempts to set a slot identifier which is numerically larger than the slot used +in the previous +.Fn osd_set +call, +.Xr realloc 9 +is used to grow the array to the appropriate size such that the slot identifier +can be used. +To maximise the efficiency of any code which calls +.Fn osd_set +sequentially on a number of different slot identifiers (e.g., during an +initialisation phase) one should loop through the slot identifiers in descending +order from highest to lowest. +This will result in only a single +.Xr malloc 9 +call to create an array of the largest slot size and all subsequent calls to +.Fn osd_set +will proceed without any +.Xr realloc 9 +calls. +.Pp +It is possible for +.Fn osd_set +to fail to allocate this array. +To ensure that such allocation succeeds, +.Fn osd_reserve +may be called (in a non-blocking context), and it will pre-allocate the +memory via +.Xr malloc 9 +with M_WAITOK. +Then this pre-allocated memory is passed to +.Fn osd_set_reserved , +which will use it if necessary or otherwise discard it. +The memory may also be explicitly discarded by calling +.Fn osd_free_reserved . +As this method always allocates memory whether or not it is ultimately needed, +it should be used only rarely, such as in the unlikely event that +.Fn osd_set +fails. +.Pp +The +.Nm +API is geared towards slot identifiers storing pointers to the same underlying +data structure type for a given +.Nm +type identifier. +This is not a requirement, and +.Xr khelp 9 +for example stores completely different data types in slots under the OSD_KHELP +type identifier. +.Ss Locking +.Nm +internally uses a mix of +.Xr mutex 9 , +.Xr rmlock 9 +and +.Xr sx 9 +locks to protect its internal data structures and state. +.Pp +Responsibility for synchronising access to a kernel data structure's +.Vt struct osd +member is left to the subsystem that uses the data structure and calls the +.Nm +API. +.Pp +.Fn osd_get +only acquires an +.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 +.Fn osd_register +returns the slot identifier for the newly registered data type. +.Pp +.Fn osd_set +and +.Fn osd_set_reserved +return zero on success or ENOMEM if the specified type/slot identifier pair +triggered an internal +.Xr realloc 9 +which failed +.Ns ( +.Fn osd_set_reserved +will always succeed when +.Fa rsv +is non-NULL). +.Pp +.Fn osd_get +returns the data pointer for the specified type/slot identifier pair, or NULL if +the slot has not been initialised yet. +.Pp +.Fn osd_reserve +returns a pointer suitable for passing to +.Fn osd_set_reserved +or +.Fn osd_free_reserved . +.Pp +.Fn osd_call +returns zero if no method is run or the method for each slot runs successfully. +If a method for a slot returns non-zero, +.Fn osd_call +terminates prematurely and returns the method's error to the caller. +.Sh SEE ALSO +.Xr khelp 9 +.Sh HISTORY +The +Object Specific Data (OSD) facility first appeared in +.Fx 8.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +facility was written by +.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . +.Pp +This manual page was written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org . diff --git a/static/freebsd/man9/owll.9 b/static/freebsd/man9/owll.9 new file mode 100644 index 00000000..6df01ea2 --- /dev/null +++ b/static/freebsd/man9/owll.9 @@ -0,0 +1,90 @@ +.\" +.\" Copyright (c) 2015 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. 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 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 September 22, 2016 +.Dt OWLL 9 +.Os +.Sh NAME +.Nm owll , +.Nm OWLL_WRITE_ONE , +.Nm OWLL_WRITE_ZERO , +.Nm OWLL_READ_DATA , +.Nm OWLL_REASET_AND_PRESENCE +.Nd Dallas Semiconductor 1-Wire Link Layer Interface +.Sh SYNOPSIS +.Ft int +.Fn OWLL_WRITE_ONE "device_t lldev" "struct ow_timing *timing" +.Ft int +.Fn OWLL_WRITE_ZERO "device_t lldev" "struct ow_timing *timing" +.Ft int +.Fn OWLL_READ_DATA "device_t lldev" "struct ow_timing *timing" "int *bit" +.Ft int +.Fn OWLL_RESET_AND_PRESENCE "device_t lldev" "struct ow_timing *timing" "int *bit" +.Sh DESCRIPTION +The +.Nm +interface provides access to the link layer of the Dallas +Semiconductor 1-Wire from upper layers of the protocol. +.Pp +.Fn OWLL_WRITE_ONE +and +.Fn OWLL_WRITE_ZERO +writes a one bit or a zero bit respectively on the 1-Wire bus. +.Pp +.Fn OWLL_READ_DATA +reads one bit from the 1-Wire bus. +This is often referred to as a +.Dq Read Time Slot +in the 1-Wire device data sheets. +.Pp +The +.Fn OWLL_RESET_AND_PRESENCE +function starts a reset sequence and detects if any device(s) are +present on the bus. +This is the beginning of all 1-Wire transactions. +.Sh NOTES +This interface is intended to be used only by the +.Xr ow 4 +device to talk to the low-level bus. +By convention, the device that implements this interface is called +.Xr owc 4 . +Only devices that implement +.Xr own 9 +should call these interfaces. +.Sh SEE ALSO +.Xr ow 4 , +.Xr owc 4 , +.Xr own 9 +.Sh LEGAL +.Tn 1-Wire +is a registered trademark of Maxim Integrated Products, Inc. +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 11.0 . +.Sh AUTHORS +The +.Nm +device driver and this manual page were written by +.An Warner Losh . diff --git a/static/freebsd/man9/own.9 b/static/freebsd/man9/own.9 new file mode 100644 index 00000000..b27ef82a --- /dev/null +++ b/static/freebsd/man9/own.9 @@ -0,0 +1,227 @@ +.\" +.\" Copyright (c) 2015 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. 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 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 20, 2015 +.Dt OWN 9 +.Os +.Sh NAME +.Nm own , +.Nm own_send_command , +.Nm own_command_wait , +.Nm own_self_command , +.Nm own_acquire_bus , +.Nm own crc , +.Nm own_release_bus , +.Nm OWN_ACQUIRE_BUS , +.Nm OWN_CRC , +.Nm OWN_RELEASE_BUS , +.Nm OWN_SEND_COMMAND +.Nd Dallas Semiconductor 1-Wire Network and Transport Interface +.Sh SYNOPSIS +.In sys/bus.h +.In dev/ow/own.h +.Ft int +.Fn own_send_command "device_t pdev" "struct ow_cmd *cmd" +.Ft int +.Fn own_command_wait "device_t pdev" "struct ow_cmd *cmd" +.Ft int +.Fn own_self_command "device_t pdev" "struct ow_cmd *cmd" "uint8_t xpt_cmd" +.Ft int +.Fn own_acquire_bus "device_t pdev" "int how" +.Ft int +.Fn own_release_bus "device_t pdev" +.Ft int +.Fn own_crc "device_t pdev" "uint8_t *buffer" "size_t len" +.Ft int +.Fn OWN_SEND_COMMAND "device_t ndev" "device_t pdev" "struct ow_cmd *cmd" +.Ft int +.Fn OWN_ACQUIRE_BUS "device_t ndev" "device_t pdev" "int how" +.Ft void +.Fn OWN_RELEASE_BUS "device_t ndev" "device_t pdev" +.Ft uint8_t +.Fn OWN_CRC "device_t ndev" "device_t pdev" "uint8_t *buffer" "size_t len" +.Sh DESCRIPTION +The +.Nm +interface defines three sets of functions for interacting with 1-Wire +devices: +sending commands, +reserving the bus, +and +ensuring data integrity. +Wrappers are provided for the raw +.Nm OWN +.Xr kobj 9 +interfaces and should be used for improved safety over the +.Xr kobj 9 +ones. +.Ss Bus Commands +The 1-Wire bus defines different layers of access to the devices on +the bus. +The +.Nm +functions provide access to the network and transport layers. +The network layer designates the next command as being either for all +devices on the bus, or for a specific device. +The network layer also specifies the speed used by the link layer. +.Pp +.Vt "struct ow_cmd" +encapsulates network access, speed, and timing information. +It specifies the commands to send and whether or not to read data. +Its members are: +.Bl -tag -width ".Va xxxx" +.It Va flags +Flags controlling the interpretation of the structure. +These flags are defined in +.In dev/ow/ow.h : +.Bl -tag -width indent +.It OW_FLAG_OVERDRIVE +Send +.Va xpt_cmd +bytes and read +.Va xpt_read +bytes at overdrive speed. +.It OW_FLAG_READ_BIT +Interpret +.Va xpt_read_len +to be in bits to be read after +.Va xpt_cmd +rather than bytes. +.El +.It Va rom_cmd +ROM command bytes to send. +.It Va rom_len +Number of ROM command bytes to send. +.It Va rom_read_len +Number of bytes to read after sending the ROM command. +.It Va rom_read +Buffer for bytes read after the ROM command. +.It Va xpt_cmd +Transport command to send. +.It Va xpt_len +Length of the transport command bytes to send. +Specify 0 for no transport command. +.It Va xpt_read_len +Number of bytes to read after +.Va xpt_cmd +bytes are sent. +If the +.Dv OW_FLAG_READ_BIT +bit is set in +.Va flags , +then it is the number of bits to read. +Bits read are packed into bytes. +.It Va xpt_read +Buffer for data read. +.El +.Pp +.Fn own_command_wait +acquires the 1-Wire bus, waiting if necessary, +sends the command, +and +then releases the bus. +.Fn own_send_command +sends the command without bus reservation. +.Fa pdev +is the client device (the presentation layer device) sending the command. +The +.Fa cmd +argument describes the transaction to send to the 1-Wire bus. +.Pp +.Fn own_self_command +fills in +.Fa cmd +with a MATCH_ROM ROM command, the ROM address of +.Fa pdev +and the +.Fa xpt_cmd +as a convenient way to create directed commands. +.Ss Bus Reservation +The 1-Wire system includes an advisory lock for the bus that +presentation layer devices can use to coordinate access. +Locking is purely advisory at this time. +.Pp +.Fn own_acquire_bus +reserves the bus. +It waits indefinitely if the +.Fa how +argument is +.Dv OWN_WAIT +and returns the error +.Dv EWOULDBLOCK +if passed +.Dv OWN_DONTWAIT +when the bus is owned by another client. +.Pp +.Fn own_release_bus +releases the bus. +.Ss Data Integrity +.Fn own_crc +computes the 1-Wire standard CRC function over the data +passed in +.Fa buffer +and +.Fa len +and returns the result. +.Ss Notes +The 1-Wire standard (Maxim AN937) defines layers that are akin to ISO +networking layers. +The lowest relevant layer, the link layer, defines the polling windows +and the timing of the signaling of different modes. +The network layer is built on top of the link layer +and is used to address devices in a unicast or multicast manner. +The transport layer defines commands and responses from the devices. +The presentation layer is composed of the device specific commands and +actions used to control the specific 1-Wire devices on bus. +.Pp +These interfaces are implemented by the +.Xr ow 4 +device. +Presentation layer devices (children of the newbus +.Xr ow 4 +device) should only call the functions described here. +The functionality provided by the +.Xr owc 4 +device (specifically the +.Xr owll 9 +interface) should only be called by the +.Xr ow 4 +driver. +.Sh SEE ALSO +.Xr ow 4 , +.Xr owc 4 , +.Xr owll 9 +.Pa https://pdfserv.maximintegrated.com/en/an/AN937.pdf +.Sh LEGAL +.Tn 1-Wire +is a registered trademark of Maxim Integrated Products, Inc. +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 11.0 . +.Sh AUTHORS +The +.Nm +device driver and this manual page were written by +.An Warner Losh . diff --git a/static/freebsd/man9/p_candebug.9 b/static/freebsd/man9/p_candebug.9 new file mode 100644 index 00000000..be4710f0 --- /dev/null +++ b/static/freebsd/man9/p_candebug.9 @@ -0,0 +1,145 @@ +.\" +.\" Copyright (c) 2003 Joseph Koshy +.\" Copyright (c) 2023 Olivier Certner +.\" +.\" 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 August 18, 2023 +.Dt P_CANDEBUG 9 +.Os +.Sh NAME +.Nm p_candebug +.Nd determine debuggability of a process +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.Ft int +.Fn p_candebug "struct thread *td" "struct proc *p" +.Sh DESCRIPTION +This function determines if a given process +.Fa p +is debuggable by some thread +.Fa td . +.Pp +The following +.Xr sysctl 8 +variables directly influence the behaviour of +.Fn p_candebug : +.Bl -tag -width indent +.It Va security.bsd.unprivileged_proc_debug +Must be set to a non-zero value to allow unprivileged processes +access to the kernel's debug facilities. +.It Va kern.securelevel +Debugging of the init process is not allowed if this variable is +.Li 1 +or greater. +.El +.Pp +Other such variables indirectly influence it; see +.Xr cr_bsd_visible 9 . +.Sh RETURN VALUES +The +.Fn p_candebug +function +returns +.Li 0 +if the process denoted by +.Fa p +is debuggable by thread +.Fa td , +or a non-zero error return value otherwise. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EPERM +An unprivileged process attempted to debug another process but the system is +configured to deny it +.Po +see +.Xr sysctl 8 +variable +.Va security.bsd.unprivileged_proc_debug +above +.Pc . +.It Bq Er ESRCH +Thread +.Fa td +has been jailed and the process to debug does not belong to the same jail or one +of its sub-jails, as determined by +.Xr prison_check 9 . +.It Bq Er ESRCH +.Xr cr_bsd_visible 9 +denied visibility according to the BSD security policies in force. +.It Bq Er EPERM +Thread +.Fa td +lacks superuser credentials and its (effective) group set is not a superset of +process +.Fa p Ns 's +whole group set +.Pq "including real, effective and saved group IDs" . +.It Bq Er EPERM +Thread +.Fa td +lacks superuser credentials and its (effective) user ID does not match all user +IDs of process +.Fa p . +.It Bq Er EPERM +Thread +.Fa td +lacks superuser credentials and process +.Fa p +is executing a set-user-ID or set-group-ID executable. +.It Bq Er EPERM +Process +.Fa p +denotes the initial process +.Fn initproc +and the +.Xr sysctl 8 +variable +.Va kern.securelevel +is greater than zero. +.It Bq Er EBUSY +Process +.Fa p +is in the process of being +.Fn exec Ns 'ed. +.It Bq Er EPERM +Process +.Fa p +denied debuggability +.Po +see +.Xr procctl 2 , +command +.Dv PROC_TRACE_CTL +.Pc . +.El +.Sh SEE ALSO +.Xr procctl 2 , +.Xr cr_bsd_visible 9 , +.Xr mac 9 , +.Xr p_cansee 9 , +.Xr prison_check 9 diff --git a/static/freebsd/man9/p_cansee.9 b/static/freebsd/man9/p_cansee.9 new file mode 100644 index 00000000..7de0c965 --- /dev/null +++ b/static/freebsd/man9/p_cansee.9 @@ -0,0 +1,79 @@ +.\" +.\" Copyright (c) 2003 Joseph Koshy +.\" Copyright (c) 2006 Ceri Davies +.\" +.\" 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 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 August 18, 2023 +.Dt P_CANSEE 9 +.Os +.Sh NAME +.Nm p_cansee +.Nd determine visibility of a process +.Sh SYNOPSIS +.In sys/proc.h +.Ft int +.Fn p_cansee "struct thread *td" "struct proc *p" +.Sh DESCRIPTION +This function determines if a given process +.Fa p +is visible to the thread +.Fa td , +where the notion of +.Dq visibility +may be read as +.Dq "awareness of existence" . +.Pp +This function explicitly allows a thread to always see its own process, +even with pending credentials changes +.Po +see +.Xr ucred 9 +.Pc . +Otherwise, it simply defers to +.Xr cr_cansee 9 . +.Sh RETURN VALUES +The +.Fn p_cansee +function +returns +.Li 0 +if the process denoted by +.Fa p +is visible by thread +.Fa td , +or ESRCH otherwise. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ESRCH +Thread +.Fa td +is not part of process +.Fa p +and cannot see it as determined by +.Xr cr_cansee 9 . +.El +.Sh SEE ALSO +.Xr cr_cansee 9 , +.Xr p_candebug 9 , +.Xr ucred 9 diff --git a/static/freebsd/man9/panic.9 b/static/freebsd/man9/panic.9 new file mode 100644 index 00000000..ee422e45 --- /dev/null +++ b/static/freebsd/man9/panic.9 @@ -0,0 +1,157 @@ +.\" $NetBSD: panic.9,v 1.2 1996/10/09 17:20:04 explorer Exp $ +.\" +.\" SPDX-License-Identifier: BSD-4-Clause +.\" +.\" Copyright (c) 1996 Michael Graff. +.\" All rights reserved. +.\" Copyright (c) 2023 The FreeBSD Foundation +.\" +.\" Portions of this documentation were written by Mitchell Horne +.\" under sponsorship from the FreeBSD Foundation. +.\" +.\" 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 Graff +.\" for the NetBSD Project. +.\" 4. 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 March 17, 2023 +.Dt PANIC 9 +.Os +.Sh NAME +.Nm panic +.Nd bring down system on fatal error +.Sh SYNOPSIS +.In sys/types.h +.In sys/systm.h +.Vt extern char *panicstr; +.Ft void +.Fn panic "const char *fmt" ... +.Ft void +.Fn vpanic "const char *fmt" "va_list ap" +.Fn KERNEL_PANICKED +.Sh DESCRIPTION +The +.Fn panic +and +.Fn vpanic +functions terminate the running system. +The message +.Fa fmt +is a +.Xr printf 3 +style format string. +The message is printed to the console and +.Va panicstr +is set pointing to the address of the message text. +This can be retrieved from a core dump at a later time. +.Pp +Upon entering the +.Fn panic +function the panicking thread disables interrupts and calls +.Xr critical_enter 9 . +This prevents the thread from being preempted or interrupted while the system +is still in a running state. +Next, it will instruct the other CPUs in the system to stop. +This synchronizes with other threads to prevent concurrent panic conditions +from interfering with one another. +In the unlikely event of concurrent panics, only one panicking thread will proceed. +.Pp +Control will be passed to the kernel debugger via +.Fn kdb_enter . +This is conditional on a debugger being installed and enabled by the +.Va debugger_on_panic +variable; see +.Xr ddb 4 +and +.Xr gdb 4 . +The debugger may initiate a system reset, or it may eventually return. +.Pp +Finally, +.Xr kern_reboot 9 +is called to restart the system, and a kernel dump will be requested. +If +.Fn panic +is called recursively (from the disk sync routines, for example), +.Fn kern_reboot +will be instructed not to sync the disks. +.Pp +The +.Fn vpanic +function implements the main body of +.Fn panic . +It is suitable to be called by functions which perform their own +variable-length argument processing. +In all other cases, +.Fn panic +is preferred. +.Pp +The +.Fn KERNEL_PANICKED +macro is the preferred way to determine if the system has panicked. +It returns a boolean value. +Most often this is used to avoid taking an action that cannot possibly succeed +in a panic context. +.Sh EXECUTION CONTEXT +.\" TODO: This text describes the kernel debugger / kernel dump execution +.\" context as well. It could be moved to a future kdb(9) page, and this +.\" section would become a pointer. +Once the panic has been initiated, code executing in a panic context is subject +to the following restrictions: +.Bl -bullet +.It +Single-threaded execution. +The scheduler is disabled, and other CPUs are stopped/forced idle. +Functions that manipulate the scheduler state must be avoided. +This includes, but is not limited to, +.Xr wakeup 9 +and +.Xr sleepqueue 9 +functions. +.It +Interrupts are disabled. +Device I/O (e.g. to the console) must be achieved with polling. +.It +Dynamic memory allocation cannot be relied on, and must be avoided. +.It +Lock acquisition/release will be ignored, meaning these operations will appear +to succeed. +.It +Sleeping on a resource is not strictly prohibited, but will result in an +immediate return from the sleep function. +Time-based sleeps such as +.Xr pause 9 +may be performed as a busy-wait. +.El +.Sh RETURN VALUES +The +.Fn panic +and +.Fn vpanic +functions do not return. +.Sh SEE ALSO +.Xr printf 3 , +.Xr ddb 4 , +.Xr gdb 4 , +.Xr KASSERT 9 , +.Xr kern_reboot 9 diff --git a/static/freebsd/man9/pci.9 b/static/freebsd/man9/pci.9 new file mode 100644 index 00000000..871f69f8 --- /dev/null +++ b/static/freebsd/man9/pci.9 @@ -0,0 +1,1159 @@ +.\" +.\" Copyright (c) 2005 Bruce M Simpson +.\" 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 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 , +.Nm pci_find_device , +.Nm pci_find_extcap , +.Nm pci_find_htcap , +.Nm pci_find_next_cap , +.Nm pci_find_next_extcap , +.Nm pci_find_next_htcap , +.Nm pci_find_pcie_root_port , +.Nm pci_get_id , +.Nm pci_get_max_payload , +.Nm pci_get_max_read_req , +.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 , +.Nm pci_msi_count , +.Nm pci_msix_count , +.Nm pci_msix_pba_bar , +.Nm pci_msix_table_bar , +.Nm pci_pending_msix , +.Nm pci_read_config , +.Nm pci_release_msi , +.Nm pci_remap_msix , +.Nm pci_restore_state , +.Nm pci_save_state , +.Nm pci_set_max_read_req , +.Nm pci_set_powerstate , +.Nm pci_write_config , +.Nm pcie_adjust_config , +.Nm pcie_flr , +.Nm pcie_get_max_completion_timeout , +.Nm pcie_read_config , +.Nm pcie_wait_for_pending_transactions , +.Nm pcie_write_config +.Nd PCI bus interface +.Sh SYNOPSIS +.In sys/bus.h +.In dev/pci/pcireg.h +.In dev/pci/pcivar.h +.Ft int +.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 +.Fn pci_disable_io "device_t dev" "int space" +.Ft int +.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 +.Fn pci_find_cap "device_t dev" "int capability" "int *capreg" +.Ft device_t +.Fn pci_find_dbsf "uint32_t domain" "uint8_t bus" "uint8_t slot" "uint8_t func" +.Ft device_t +.Fn pci_find_device "uint16_t vendor" "uint16_t device" +.Ft int +.Fn pci_find_extcap "device_t dev" "int capability" "int *capreg" +.Ft int +.Fn pci_find_htcap "device_t dev" "int capability" "int *capreg" +.Ft int +.Fn pci_find_next_cap "device_t dev" "int capability" "int start" "int *capreg" +.Ft int +.Fn pci_find_next_extcap "device_t dev" "int capability" "int start" "int *capreg" +.Ft int +.Fn pci_find_next_htcap "device_t dev" "int capability" "int start" "int *capreg" +.Ft device_t +.Fn pci_find_pcie_root_port "device_t dev" +.Ft int +.Fn pci_get_id "device_t dev" "enum pci_id_type type" "uintptr_t *id" +.Ft int +.Fn pci_get_max_payload "device_t dev" +.Ft int +.Fn pci_get_max_read_req "device_t dev" +.Ft int +.Fn pci_get_powerstate "device_t dev" +.Ft int +.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 +.Fn pci_msix_count "device_t dev" +.Ft int +.Fn pci_msix_pba_bar "device_t dev" +.Ft int +.Fn pci_msix_table_bar "device_t dev" +.Ft int +.Fn pci_pending_msix "device_t dev" "u_int index" +.Ft uint32_t +.Fn pci_read_config "device_t dev" "int reg" "int width" +.Ft int +.Fn pci_release_msi "device_t dev" +.Ft int +.Fn pci_remap_msix "device_t dev" "int count" "const u_int *vectors" +.Ft void +.Fn pci_restore_state "device_t dev" +.Ft void +.Fn pci_save_state "device_t dev" +.Ft int +.Fn pci_set_max_read_req "device_t dev" "int size" +.Ft int +.Fn pci_set_powerstate "device_t dev" "int state" +.Ft void +.Fn pci_write_config "device_t dev" "int reg" "uint32_t val" "int width" +.Ft uint32_t +.Fo pcie_adjust_config +.Fa "device_t dev" +.Fa "int reg" +.Fa "uint32_t mask" +.Fa "uint32_t val" +.Fa "int width" +.Fc +.Ft bool +.Fn pcie_flr "device_t dev" "u_int max_delay" "bool force" +.Ft int +.Fn pcie_get_max_completion_timeout "device_t dev" +.Ft uint32_t +.Fn pcie_read_config "device_t dev" "int reg" "int width" +.Ft bool +.Fn pcie_wait_for_pending_transactions "device_t dev" "u_int max_delay" +.Ft void +.Fn pcie_write_config "device_t dev" "int reg" "uint32_t val" "int width" +.Ft void +.Fn pci_event_fn "void *arg" "device_t dev" +.Fn EVENTHANDLER_REGISTER "pci_add_device" "pci_event_fn" +.Fn EVENTHANDLER_DEREGISTER "pci_delete_resource" "pci_event_fn" +.In dev/pci/pci_iov.h +.Ft int +.Fn pci_iov_attach "device_t dev" "nvlist_t *pf_schema" "nvlist_t *vf_schema" +.Ft int +.Fo pci_iov_attach_name +.Fa "device_t dev" +.Fa "nvlist_t *pf_schema" +.Fa "nvlist_t *vf_schema" +.Fa "const char *fmt" +.Fa "..." +.Fc +.Ft int +.Fn pci_iov_detach "device_t dev" +.Sh DESCRIPTION +The +.Nm +set of functions are used for managing PCI devices. +The functions are split into several groups: +raw configuration access, +locating devices, +device information, +device configuration, +and +message signaled interrupts. +.Ss Raw Configuration Access +The +.Fn pci_read_config +function is used to read data from the PCI configuration +space of the device +.Fa dev , +at offset +.Fa reg , +with +.Fa width +specifying the size of the access. +.Pp +The +.Fn pci_write_config +function is used to write the value +.Fa val +to the PCI configuration +space of the device +.Fa dev , +at offset +.Fa reg , +with +.Fa width +specifying the size of the access. +.Pp +The +.Fn pcie_adjust_config +function is used to modify the value of a register in the PCI-express +capability register set of device +.Fa dev . +The offset +.Fa reg +specifies a relative offset in the register set with +.Fa width +specifying the size of the access. +The new value of the register is computed by modifying bits set in +.Fa mask +to the value in +.Fa val . +Any bits not specified in +.Fa mask +are preserved. +The previous value of the register is returned. +.Pp +The +.Fn pcie_read_config +function is used to read the value of a register in the PCI-express +capability register set of device +.Fa dev . +The offset +.Fa reg +specifies a relative offset in the register set with +.Fa width +specifying the size of the access. +.Pp +The +.Fn pcie_write_config +function is used to write the value +.Fa val +to a register in the PCI-express capability register set of device +.Fa dev . +The offset +.Fa reg +specifies a relative offset in the register set with +.Fa width +specifying the size of the access. +.Pp +.Em NOTE : +Device drivers should only use these functions for functionality that +is not available via another +.Fn pci +function. +.Ss Locating Devices +The +.Fn pci_find_bsf +function looks up the +.Vt device_t +of a PCI device, given its +.Fa bus , +.Fa slot , +and +.Fa func . +The +.Fa slot +number actually refers to the number of the device on the bus, +which does not necessarily indicate its geographic location +in terms of a physical slot. +Note that in case the system has multiple PCI domains, +the +.Fn pci_find_bsf +function only searches the first one. +Actually, it is equivalent to: +.Bd -literal -offset indent +pci_find_dbsf(0, bus, slot, func); +.Ed +.Pp +The +.Fn pci_find_dbsf +function looks up the +.Vt device_t +of a PCI device, given its +.Fa domain , +.Fa bus , +.Fa slot , +and +.Fa func . +The +.Fa slot +number actually refers to the number of the device on the bus, +which does not necessarily indicate its geographic location +in terms of a physical slot. +.Pp +The +.Fn pci_find_device +function looks up the +.Vt device_t +of a PCI device, given its +.Fa vendor +and +.Fa device +IDs. +Note that there can be multiple matches for this search; this function +only returns the first matching device. +.Ss Device Information +The +.Fn pci_find_cap +function is used to locate the first instance of a PCI capability +register set for the device +.Fa dev . +The capability to locate is specified by ID via +.Fa capability . +Constant macros of the form +.Dv PCIY_xxx +for standard capability IDs are defined in +.In dev/pci/pcireg.h . +If the capability is found, then +.Fa *capreg +is set to the offset in configuration space of the capability register set, +and +.Fn pci_find_cap +returns zero. +If the capability is not found or the device does not support capabilities, +.Fn pci_find_cap +returns an error. +The +.Fn pci_find_next_cap +function is used to locate the next instance of a PCI capability +register set for the device +.Fa dev . +The +.Fa start +should be the +.Fa *capreg +returned by a prior +.Fn pci_find_cap +or +.Fn pci_find_next_cap . +When no more instances are located +.Fn pci_find_next_cap +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 +.Fa dev . +The extended capability to locate is specified by ID via +.Fa capability . +Constant macros of the form +.Dv PCIZ_xxx +for standard extended capability IDs are defined in +.In dev/pci/pcireg.h . +If the extended capability is found, then +.Fa *capreg +is set to the offset in configuration space of the extended capability +register set, and +.Fn pci_find_extcap +returns zero. +If the extended capability is not found or the device is not a +PCI-express device, +.Fn pci_find_extcap +returns an error. +The +.Fn pci_find_next_extcap +function is used to locate the next instance of a PCI-express +extended capability register set for the device +.Fa dev . +The +.Fa start +should be the +.Fa *capreg +returned by a prior +.Fn pci_find_extcap +or +.Fn pci_find_next_extcap . +When no more instances are located +.Fn pci_find_next_extcap +returns an error. +.Pp +The +.Fn pci_find_htcap +function is used to locate the first instance of a HyperTransport capability +register set for the device +.Fa dev . +The capability to locate is specified by type via +.Fa capability . +Constant macros of the form +.Dv PCIM_HTCAP_xxx +for standard HyperTransport capability types are defined in +.In dev/pci/pcireg.h . +If the capability is found, then +.Fa *capreg +is set to the offset in configuration space of the capability register set, +and +.Fn pci_find_htcap +returns zero. +If the capability is not found or the device is not a HyperTransport device, +.Fn pci_find_htcap +returns an error. +The +.Fn pci_find_next_htcap +function is used to locate the next instance of a HyperTransport capability +register set for the device +.Fa dev . +The +.Fa start +should be the +.Fa *capreg +returned by a prior +.Fn pci_find_htcap +or +.Fn pci_find_next_htcap . +When no more instances are located +.Fn pci_find_next_htcap +returns an error. +.Pp +The +.Fn pci_find_pcie_root_port +function walks up the PCI device hierarchy to locate the PCI-express root +port upstream of +.Fa dev . +If a root port is not found, +.Fn pci_find_pcie_root_port +returns +.Dv NULL . +.Pp +The +.Fn pci_get_id +function is used to read an identifier from a device. +The +.Fa type +flag is used to specify which identifier to read. +The following flags are supported: +.Bl -hang -width ".Dv PCI_ID_RID" +.It Dv PCI_ID_RID +Read the routing identifier for the device. +.It Dv PCI_ID_MSI +Read the MSI routing ID. +This is needed by some interrupt controllers to route MSI and MSI-X interrupts. +.El +.Pp +The +.Fn pci_get_vpd_ident +function is used to fetch a device's Vital Product Data +.Pq VPD +identifier string. +If the device +.Fa dev +supports VPD and provides an identifier string, +then +.Fa *identptr +is set to point at a read-only, null-terminated copy of the identifier +string, +and +.Fn pci_get_vpd_ident +returns zero. +If the device does not support VPD or does not provide an identifier +string, +then +.Fn pci_get_vpd_ident +returns an error. +.Pp +The +.Fn pci_get_vpd_readonly +function is used to fetch the value of a single VPD read-only keyword +for the device +.Fa dev . +The keyword to fetch is identified by the two character string +.Fa kw . +If the device supports VPD and provides a read-only value for the +requested keyword, +then +.Fa *vptr +is set to point at a read-only, null-terminated copy of the value, +and +.Fn pci_get_vpd_readonly +returns zero. +If the device does not support VPD or does not provide the requested +keyword, +then +.Fn pci_get_vpd_readonly +returns an error. +.Pp +The +.Fn pcie_get_max_completion_timeout +function returns the maximum completion timeout configured for the device +.Fa dev +in microseconds. +If the +.Fa dev +device is not a PCI-express device, +.Fn pcie_get_max_completion_timeout +returns zero. +When completion timeouts are disabled for +.Fa dev , +this function returns the maximum timeout that would be used if timeouts +were enabled. +.Pp +The +.Fn pcie_wait_for_pending_transactions +function waits for any pending transactions initiated by the +.Fa dev +device to complete. +The function checks for pending transactions by polling the transactions +pending flag in the PCI-express device status register. +It returns +.Dv true +once the transaction pending flag is clear. +If transactions are still pending after +.Fa max_delay +milliseconds, +.Fn pcie_wait_for_pending_transactions +returns +.Dv false . +If +.Fa max_delay +is set to zero, +.Fn pcie_wait_for_pending_transactions +performs a single check; +otherwise, +this function may sleep while polling the transactions pending flag. +.Nm pcie_wait_for_pending_transactions +returns +.Dv true +if +.Fa dev +is not a PCI-express device. +.Ss Device Configuration +The +.Fn pci_enable_busmaster +function enables PCI bus mastering for the device +.Fa dev , +by setting the +.Dv PCIM_CMD_BUSMASTEREN +bit in the +.Dv PCIR_COMMAND +register. +The +.Fn pci_disable_busmaster +function clears this bit. +.Pp +The +.Fn pci_enable_io +function enables memory or I/O port address decoding for the device +.Fa dev , +by setting the +.Dv PCIM_CMD_MEMEN +or +.Dv PCIM_CMD_PORTEN +bit in the +.Dv PCIR_COMMAND +register appropriately. +The +.Fn pci_disable_io +function clears the appropriate bit. +The +.Fa space +argument specifies which resource is affected; this can be either +.Dv SYS_RES_MEMORY +or +.Dv SYS_RES_IOPORT +as appropriate. +Device drivers should generally not use these routines directly. +The PCI bus will enable decoding automatically when a +.Dv SYS_RES_MEMORY +or +.Dv SYS_RES_IOPORT +resource is activated via +.Xr bus_alloc_resource 9 +or +.Xr bus_activate_resource 9 . +.Pp +The +.Fn pci_get_max_payload +function returns the current maximum TLP payload size in bytes for a +PCI-express device. +If the +.Fa dev +device is not a PCI-express device, +.Fn pci_get_max_payload +returns zero. +.Pp +The +.Fn pci_get_max_read_req +function returns the current maximum read request size in bytes for a +PCI-express device. +If the +.Fa dev +device is not a PCI-express device, +.Fn pci_get_max_read_req +returns zero. +.Pp +The +.Fn pci_set_max_read_req +sets the PCI-express maximum read request size for +.Fa dev . +The requested +.Fa size +may be adjusted, +and +.Fn pci_set_max_read_req +returns the actual size set in bytes. +If the +.Fa dev +device is not a PCI-express device, +.Fn pci_set_max_read_req +returns zero. +.Pp +The +.Fn pci_get_powerstate +function returns the current power state of the device +.Fa dev . +If the device does not support power management capabilities, then the default +state of +.Dv PCI_POWERSTATE_D0 +is returned. +The following power states are defined by PCI: +.Bl -hang -width ".Dv PCI_POWERSTATE_UNKNOWN" +.It Dv PCI_POWERSTATE_D0 +State in which device is on and running. +It is receiving full power from the system and delivering +full functionality to the user. +.It Dv PCI_POWERSTATE_D1 +Class-specific low-power state in which device context may or +may not be lost. +Buses in this state cannot do anything to the bus, to +force devices to lose context. +.It Dv PCI_POWERSTATE_D2 +Class-specific low-power state in which device context may or +may not be lost. +Attains greater power savings than +.Dv PCI_POWERSTATE_D1 . +Buses in this state can cause devices to lose some context. +Devices +.Em must +be prepared for the bus to be in this state or higher. +.It Dv PCI_POWERSTATE_D3_HOT +State in which the device is off and not running. +Device context is lost, and power from the device can +be (but is not necessarily) removed. +.It Dv PCI_POWERSTATE_D3_COLD +Same as +.Dv PCI_POWERSTATE_D3_HOT , +except power has been removed from the device. +.It Dv PCI_POWERSTATE_UNKNOWN +State of the device is unknown. +.El +.Pp +The +.Fn pci_set_powerstate +function is used to transition the device +.Fa dev +to the PCI power state +.Fa state . +If the device does not support power management capabilities or +it does not support the specific power state +.Fa state , +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 +supports PCI Single-Root I/O Virtualization +.Pq SR-IOV . +A driver that supports SR-IOV must implement the +.Xr PCI_IOV_INIT 9 , +.Xr PCI_IOV_ADD_VF 9 +and +.Xr PCI_IOV_UNINIT 9 +methods. +This function should be called during the +.Xr DEVICE_ATTACH 9 +method. +If this function returns an error, it is recommended that the device driver +still successfully attaches, but runs with SR-IOV disabled. +The +.Fa pf_schema +and +.Fa vf_schema +parameters are used to define what device-specific configuration parameters the +device driver accepts when SR-IOV is enabled for the Physical Function +.Pq PF +and for individual Virtual Functions +.Pq VFs +respectively. +See +.Xr pci_iov_schema 9 +for details on how to construct the schema. +If either the +.Pa pf_schema +or +.Pa vf_schema +is invalid or specifies parameter names that conflict with parameter names that +are already in use, +.Fn pci_iov_attach +will return an error and SR-IOV will not be available on the PF device. +If a driver does not accept configuration parameters for either the PF device +or the VF devices, the driver must pass an empty schema for that device. +The SR-IOV infrastructure takes ownership of the +.Fa pf_schema +and +.Fa vf_schema +and is responsible for freeing them. +The driver must never free the schemas itself. +.Pp +The +.Fn pci_iov_attach_name +function is a variant of +.Fn pci_iov_attach +that allows the name of the associated character device in +.Pa /dev/iov +to be specified by +.Fa fmt . +The +.Fn pci_iov_attach +function uses the name of +.Fa dev +as the device name. +.Pp +The +.Fn pci_iov_detach +function is used to advise the SR-IOV infrastructure that the driver for the +given device is attempting to detach and that all SR-IOV resources for the +device must be released. +This function must be called during the +.Xr DEVICE_DETACH 9 +method if +.Fn pci_iov_attach +was successfully called on the device and +.Fn pci_iov_detach +has not subsequently been called on the device and returned no error. +If this function returns an error, the +.Xr DEVICE_DETACH 9 +method must fail and return an error, as detaching the PF driver while VF +devices are active would cause system instability. +This function is safe to call and will always succeed if +.Fn pci_iov_attach +previously failed with an error on the given device, or if +.Fn pci_iov_attach +was never called on the device. +.Pp +The +.Fn pci_save_state +and +.Fn pci_restore_state +functions can be used by a device driver to save and restore standard PCI +config registers. +The +.Fn pci_save_state +function must be invoked while the device has valid state before +.Fn pci_restore_state +can be used. +If the device is not in the fully-powered state +.Pq Dv PCI_POWERSTATE_D0 +when +.Fn pci_restore_state +is invoked, +then the device will be transitioned to +.Dv PCI_POWERSTATE_D0 +before any config registers are restored. +.Pp +The +.Fn pcie_flr +function requests a Function Level Reset +.Pq FLR +of +.Fa dev . +If +.Fa dev +is not a PCI-express device or does not support Function Level Resets via +the PCI-express device control register, +.Dv false +is returned. +Pending transactions are drained by disabling busmastering and calling +.Fn pcie_wait_for_pending_transactions +before resetting the device. +The +.Fa max_delay +argument specifies the maximum timeout to wait for pending transactions as +described for +.Fn pcie_wait_for_pending_transactions . +If +.Fn pcie_wait_for_pending_transactions +fails with a timeout and +.Fa force +is +.Dv false , +busmastering is re-enabled and +.Dv false +is returned. +If +.Fn pcie_wait_for_pending_transactions +fails with a timeout and +.Fa force +is +.Dv true , +the device is reset despite the timeout. +After the reset has been requested, +.Nm pcie_flr +sleeps for at least 100 milliseconds before returning +.Dv true . +Note that +.Nm pcie_flr +does not save and restore any state around the reset. +The caller should save and restore state as needed. +.Ss Message Signaled Interrupts +Message Signaled Interrupts +.Pq MSI +and +Enhanced Message Signaled Interrupts +.Pq MSI-X +are PCI capabilities that provide an alternate method for PCI +devices to signal interrupts. +The legacy INTx interrupt is available to PCI devices as a +.Dv SYS_RES_IRQ +resource with a resource ID of zero. +MSI and MSI-X interrupts are available to PCI devices as one or more +.Dv SYS_RES_IRQ +resources with resource IDs greater than zero. +A driver must ask the PCI bus to allocate MSI or MSI-X interrupts +using +.Fn pci_alloc_msi +or +.Fn pci_alloc_msix +before it can use MSI or MSI-X +.Dv SYS_RES_IRQ +resources. +A driver is not allowed to use the legacy INTx +.Dv SYS_RES_IRQ +resource if MSI or MSI-X interrupts have been allocated, +and attempts to allocate MSI or MSI-X interrupts will fail if the +driver is currently using the legacy INTx +.Dv SYS_RES_IRQ +resource. +A driver is only allowed to use either MSI or MSI-X, +but not both. +.Pp +The +.Fn pci_msi_count +function returns the maximum number of MSI messages supported by the +device +.Fa dev . +If the device does not support MSI, +then +.Fn pci_msi_count +returns zero. +.Pp +The +.Fn pci_alloc_msi +function attempts to allocate +.Fa *count +MSI messages for the device +.Fa dev . +The +.Fn pci_alloc_msi +function may allocate fewer messages than requested for various +reasons including requests for more messages than the device +.Fa dev +supports, +or if the system has a shortage of available MSI messages. +On success, +.Fa *count +is set to the number of messages allocated and +.Fn pci_alloc_msi +returns zero. +The +.Dv SYS_RES_IRQ +resources for the allocated messages will be available at consecutive +resource IDs beginning with one. +If +.Fn pci_alloc_msi +is not able to allocate any messages, +it returns an error. +Note that MSI only supports message counts that are powers of two; +requests to allocate a non-power of two count of messages will fail. +.Pp +The +.Fn pci_release_msi +function is used to release any allocated MSI or MSI-X messages back +to the system. +If any MSI or MSI-X +.Dv SYS_RES_IRQ +resources are allocated by the driver or have a configured interrupt +handler, +this function will fail with +.Er EBUSY . +The +.Fn pci_release_msi +function returns zero on success and an error on failure. +.Pp +The +.Fn pci_msix_count +function returns the maximum number of MSI-X messages supported by the +device +.Fa dev . +If the device does not support MSI-X, +then +.Fn pci_msix_count +returns zero. +.Pp +The +.Fn pci_msix_pba_bar +function returns the offset in configuration space of the Base Address Register +.Pq BAR +containing the MSI-X Pending Bit Array (PBA) for device +.Fa dev . +The returned value can be used as the resource ID with +.Xr bus_alloc_resource 9 +and +.Xr bus_release_resource 9 +to allocate the BAR. +If the device does not support MSI-X, +then +.Fn pci_msix_pba_bar +returns -1. +.Pp +The +.Fn pci_msix_table_bar +function returns the offset in configuration space of the BAR +containing the MSI-X vector table for device +.Fa dev . +The returned value can be used as the resource ID with +.Xr bus_alloc_resource 9 +and +.Xr bus_release_resource 9 +to allocate the BAR. +If the device does not support MSI-X, +then +.Fn pci_msix_table_bar +returns -1. +.Pp +The +.Fn pci_alloc_msix +function attempts to allocate +.Fa *count +MSI-X messages for the device +.Fa dev . +The +.Fn pci_alloc_msix +function may allocate fewer messages than requested for various +reasons including requests for more messages than the device +.Fa dev +supports, +or if the system has a shortage of available MSI-X messages. +On success, +.Fa *count +is set to the number of messages allocated and +.Fn pci_alloc_msix +returns zero. +For MSI-X messages, +the resource ID for each +.Dv SYS_RES_IRQ +resource identifies the index in the MSI-X table of the +corresponding message. +A resource ID of one maps to the first index of the MSI-X table; +a resource ID two identifies the second index in the table, etc. +The +.Fn pci_alloc_msix +function assigns the +.Fa *count +messages allocated to the first +.Fa *count +table indices. +If +.Fn pci_alloc_msix +is not able to allocate any messages, +it returns an error. +Unlike MSI, +MSI-X does not require message counts that are powers of two. +.Pp +The BARs containing the MSI-X vector table and PBA must be +allocated via +.Xr bus_alloc_resource 9 +before calling +.Fn pci_alloc_msix +and must not be released until after calling +.Fn pci_release_msi . +Note that the vector table and PBA may be stored in the same BAR or in +different BARs. +.Pp +The +.Fn pci_pending_msix +function examines the +.Fa dev +device's PBA +to determine the pending status of the MSI-X message at table index +.Fa index . +If the indicated message is pending, +this function returns a non-zero value; +otherwise, +it returns zero. +Passing an invalid +.Fa index +to this function will result in undefined behavior. +.Pp +As mentioned in the description of +.Fn pci_alloc_msix , +MSI-X messages are initially assigned to the first N table entries. +A driver may use a different distribution of available messages to +table entries via the +.Fn pci_remap_msix +function. +Note that this function must be called after a successful call to +.Fn pci_alloc_msix +but before any of the +.Dv SYS_RES_IRQ +resources are allocated. +The +.Fn pci_remap_msix +function returns zero on success, +or an error on failure. +.Pp +The +.Fa vectors +array should contain +.Fa count +message vectors. +The array maps directly to the MSI-X table in that the first entry in +the array specifies the message used for the first entry in the MSI-X +table, +the second entry in the array corresponds to the second entry in the +MSI-X table, +etc. +The vector value in each array index can either be zero to indicate +that no message should be assigned to the corresponding MSI-X table entry, +or it can be a number from one to N +.Po +where N is the count returned from the previous call to +.Fn pci_alloc_msix +.Pc +to indicate which of the allocated messages should be assigned to the +corresponding MSI-X table entry. +.Pp +If +.Fn pci_remap_msix +succeeds, +each MSI-X table entry with a non-zero vector will have an associated +.Dv SYS_RES_IRQ +resource whose resource ID corresponds to the table index as described +above for +.Fn pci_alloc_msix . +MSI-X table entries that with a vector of zero will not have an +associated +.Dv SYS_RES_IRQ +resource. +Additionally, +if any of the original messages allocated by +.Fn pci_alloc_msix +are not used in the new distribution of messages in the MSI-X table, +they will be released automatically. +Note that if a driver wishes to use fewer messages than were allocated by +.Fn pci_alloc_msix , +the driver must use a single, contiguous range of messages beginning +with one in the new distribution. +The +.Fn pci_remap_msix +function will fail if this condition is not met. +.Ss Device Events +The +.Va pci_add_device +event handler is invoked every time a new PCI device is added to the system. +This includes the creation of Virtual Functions via SR-IOV. +.Pp +The +.Va pci_delete_device +event handler is invoked every time a PCI device is removed from the system. +.Pp +Both event handlers pass the +.Vt device_t +object of the relevant PCI device as +.Fa dev +to each callback function. +Both event handlers are invoked while +.Fa dev +is unattached but with valid instance variables. +.Sh SEE ALSO +.Xr pci 4 , +.Xr pciconf 8 , +.Xr bus_alloc_resource 9 , +.Xr bus_dma 9 , +.Xr bus_release_resource 9 , +.Xr bus_setup_intr 9 , +.Xr bus_teardown_intr 9 , +.Xr devclass 9 , +.Xr device 9 , +.Xr driver 9 , +.Xr eventhandler 9 , +.Xr rman 9 +.Rs +.%B FreeBSD Developers' Handbook +.%T NewBus +.%U https://docs.freebsd.org/en/books/developers-handbook/ +.Re +.Rs +.%A Shanley +.%A Anderson +.%B PCI System Architecture +.%N 2nd Edition +.%I Addison-Wesley +.%O ISBN 0-201-30974-2 +.Re +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Bruce M Simpson Aq Mt bms@FreeBSD.org +and +.An John Baldwin Aq Mt jhb@FreeBSD.org . +.Sh BUGS +The kernel PCI code has a number of references to +.Dq "slot numbers" . +These do not refer to the geographic location of PCI devices, +but to the device number assigned by the combination of the PCI IDSEL +mechanism and the platform firmware. +This should be taken note of when working with the kernel PCI code. +.Pp +The PCI bus driver should allocate the MSI-X vector table and PBA internally +as necessary rather than requiring the caller to do so. diff --git a/static/freebsd/man9/pci_iov_schema.9 b/static/freebsd/man9/pci_iov_schema.9 new file mode 100644 index 00000000..99589b59 --- /dev/null +++ b/static/freebsd/man9/pci_iov_schema.9 @@ -0,0 +1,263 @@ +.\" +.\" Copyright (c) 2014 Sandvine Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY 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 8, 2015 +.Dt PCI_IOV_SCHEMA 9 +.Os +.Sh NAME +.Nm pci_iov_schema , +.Nm pci_iov_schema_alloc_node , +.Nm pci_iov_schema_add_bool , +.Nm pci_iov_schema_add_string , +.Nm pci_iov_schema_add_uint8 , +.Nm pci_iov_schema_add_uint16 , +.Nm pci_iov_schema_add_uint32 , +.Nm pci_iov_schema_add_uint64 , +.Nm pci_iov_schema_add_unicast_mac +.Nd PCI SR-IOV config schema interface +.Sh SYNOPSIS +.In sys/stdarg.h +.In sys/nv.h +.In sys/iov_schema.h +.Ft nvlist_t * +.Fn pci_iov_schema_alloc_node "void" +.Ft void +.Fn pci_iov_schema_add_bool "nvlist_t *schema" "const char *name" \ +"uint32_t flags" "int defaultVal" +.Ft void +.Fn pci_iov_schema_add_string "nvlist_t *schema" "const char *name" \ +"uint32_t flags" "const char *defaultVal" +.Ft void +.Fn pci_iov_schema_add_uint8 "nvlist_t *schema" "const char *name" \ +"uint32_t flags" "uint8_t defaultVal" +.Ft void +.Fn pci_iov_schema_add_uint16 "nvlist_t *schema" "const char *name" \ +"uint32_t flags" "uint16_t defaultVal" +.Ft void +.Fn pci_iov_schema_add_uint32 "nvlist_t *schema" "const char *name" \ +"uint32_t flags" "uint32_t defaultVal" +.Ft void +.Fn pci_iov_schema_add_uint64 "nvlist_t *schema" "const char *name" \ +"uint32_t flags" "uint64_t defaultVal" +.Ft void +.Fn pci_iov_schema_add_unicast_mac "nvlist_t *schema" "const char *name" \ +"uint32_t flags" "const uint8_t *defaultVal" +.Sh DESCRIPTION +The PCI Single-Root I/O Virtualization +.Pq SR-IOV +configuration schema is a data +structure that describes the device-specific configuration parameters that a PF +driver will accept when SR-IOV is enabled on the PF device. +Each PF driver defines two schema instances: the PF schema and the VF schema. +The PF schema describes configuration that applies to the PF device as a whole. +The VF schema describes configuration that applies to an individual VF device. +Different VF devices may have different configuration applied to them, as long +as the configuration for each VF conforms to the VF schema. +.Pp +A PF driver builds a configuration schema by first allocating a schema node and +then adding configuration parameter specifications to the schema. +The configuration parameter specification consists of a name and a value type. +.Pp +Configuration parameter names are case-insensitive. +It is an error to specify two or more configuration parameters with the same +name. +It is also an error to specific a configuration parameter that uses the same +name as a configuration parameter used by the SR-IOV infrastructure. +See +.Xr iovctl.conf 5 +for documentation of all configuration parameters used by the SR-IOV +infrastructure. +.Pp +The parameter type constrains the possible values that the configuration +parameter may take. +.Pp +A configuration parameter may be specified as a required parameter by setting +the +.Dv IOV_SCHEMA_REQUIRED +flag in the +.Pa flags +argument. +Required parameters must be specified by the user when SR-IOV is enabled. +If the user does not specify a required parameter, the SR-IOV infrastructure +will abort the request to enable SR-IOV and return an error to the user. +.Pp +Alternatively, a configuration parameter may be given a default value by +setting the +.Dv IOV_SCHEMA_HASDEFAULT +flag in the +.Pa flags +argument. +If a configuration parameter has a default value but the user has not specified +a value for that parameter, then the SR-IOV infrastructure will apply +.Pa defaultVal +for that parameter in the configuration before passing it to the PF driver. +It is an error for the value of the +.Pa defaultVal +parameter to not conform to the restrictions of the specified type. +If this flag is not specified then the +.Pa defaultVal +argument is ignored. +This flag is not compatible with the +.Dv IOV_SCHEMA_REQUIRED +flag; it is an error to specify both on the same parameter. +.Pp +The SR-IOV infrastructure guarantees that all configuration parameters that are +either specified as required or given a default value will be present in the +configuration passed to the PF driver. +Configuration parameters that are neither specified as required nor given a +default value are optional and may or may not be present in the configuration +passed to the PF driver. +.Pp +It is highly recommended that a PF driver reserve the use of optional parameters +for configuration that is truly optional. +For example, a Network Interface PF device might have the option to encapsulate +all traffic to and from a VF device in a vlan tag. +The PF driver could expose that option as a "vlan" parameter accepting an +integer argument specifying the vlan tag. +In this case, it would be appropriate to set the "vlan" parameter as an optional +parameter as it would be legitimate for a VF to be configured to have no vlan +tagging enabled at all. +.Pp +Alternatively, if the PF device had an boolean option that controlled whether +the VF was allowed to change its MAC address, it would not be appropriate to +set this parameter as optional. +The PF driver must either allow the MAC to change or not, so it would be more +appropriate for the PF driver to document the default behaviour by specifying +a default value in the schema +.Po or potentially force the user to make the choice by setting the parameter +to be required +.Pc . +.Pp +Configuration parameters that have security implications must default to the +most secure configuration possible. +.Pp +All device-specific configuration parameters must be documented in the manual +page for the PF driver, or in a separate manual page that is cross-referenced +from the main driver manual page. +.Pp +It is not necessary for a PF driver to check for failure from any of these +functions. +If an error occurs, it is flagged in the schema. +The +.Xr pci_iov_attach 9 +function checks for this error and will fail to initialize SR-IOV on the PF +device if an error is set in the schema. +If this occurs, it is recommended that the PF driver still succeed in attaching +and run with SR-IOV disabled on the device. +.Pp +The +.Fn pci_iov_schema_alloc_node +function is used to allocate an empty configuration schema. +It is not necessary to check for failure from this function. +The SR-IOV infrastructure will gracefully handle failure to allocate a schema +and will simply not enable SR-IOV on the PF device. +.Pp +The +.Fn pci_iov_schema_add_bool +function is used to specify a configuration parameter in the given schema with +the name +.Pa name +and having a boolean type. +Boolean values can only take the value true or false (1 or 0, respectively). +.Pp +The +.Fn pci_iov_schema_add_string +function is used to specify a configuration parameter in the given schema with +the name +.Pa name +and having a string type. +String values are standard C strings. +.Pp +The +.Fn pci_iov_schema_add_uint8 +function is used to specify a configuration parameter in the given schema with +the name +.Pa name +and having a +.Vt uint8_t +type. +Values of type +.Vt uint8_t +are unsigned integers in the range 0 to 255, inclusive. +.Pp +The +.Fn pci_iov_schema_add_uint16 +function is used to specify a configuration parameter in the given schema with +the name +.Pa name +and having a +.Vt uint16_t +type. +Values of type +.Vt uint16_t +are unsigned integers in the range 0 to 65535, inclusive. +.Pp +The +.Fn pci_iov_schema_add_uint32 +function is used to specify a configuration parameter in the given schema with +the name +.Pa name +and having a +.Vt uint32_t +type. +Values of type +.Vt uint32_t +are unsigned integers in the range 0 to +.Pq 2**32 - 1 , +inclusive. +.Pp +The +.Fn pci_iov_schema_add_uint64 +function is used to specify a configuration parameter in the given schema with +the name +.Pa name +and having a +.Vt uint64_t +type. +Values of type +.Vt uint64_t +are unsigned integers in the range 0 to +.Pq 2**64 - 1 , +inclusive. +.Pp +The +.Fn pci_iov_schema_add_unicast_mac +function is used to specify a configuration parameter in the given schema with +the name +.Pa name +and having a unicast-mac type. +Values of type unicast-mac are binary values exactly 6 bytes long. +The MAC address is guaranteed to not be a multicast or broadcast address. +.Sh RETURN VALUES +The +.Fn pci_iov_schema_alloc_node +function returns a pointer to the allocated schema, or NULL if a failure occurs. +.Sh SEE ALSO +.Xr pci 9 , +.Xr PCI_IOV_ADD_VF 9 , +.Xr PCI_IOV_INIT 9 +.Sh AUTHORS +This manual page was written by +.An Ryan Stone Aq rstone@FreeBSD.org . diff --git a/static/freebsd/man9/pfil.9 b/static/freebsd/man9/pfil.9 new file mode 100644 index 00000000..63eb3da8 --- /dev/null +++ b/static/freebsd/man9/pfil.9 @@ -0,0 +1,162 @@ +.\" $NetBSD: pfil.9,v 1.22 2003/07/01 13:04:06 wiz Exp $ +.\" +.\" Copyright (c) 2019 Gleb Smirnoff +.\" Copyright (c) 1996 Matthew R. Green +.\" 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. 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 January 28, 2019 +.Dt PFIL 9 +.Os +.Sh NAME +.Nm pfil , +.Nm pfil_head_register , +.Nm pfil_head_unregister , +.Nm pfil_link , +.Nm pfil_run_hooks +.Nd packet filter interface +.Sh SYNOPSIS +.In sys/param.h +.In sys/mbuf.h +.In net/pfil.h +.Ft pfil_head_t +.Fn pfil_head_register "struct pfil_head_args *args" +.Ft void +.Fn pfil_head_unregister "struct pfil_head_t *head" +.Ft pfil_hook_t +.Fn pfil_add_hook "struct pfil_hook_args *" +.Ft void +.Fn pfil_remove_hook "pfil_hook_t" +.Ft int +.Fn pfil_link "struct pfil_link_args *args" +.Ft int +.Fn pfil_run_hooks "phil_head_t *" "pfil_packet_t" "struct ifnet *" "int" "struct inpcb *" +.Sh DESCRIPTION +The +.Nm +framework allows for a specified function or a list of functions +to be invoked for every incoming or outgoing packet for a particular +network I/O stream. +These hooks may be used to implement a firewall or perform packet +transformations. +.Pp +Packet filtering points, for historical reasons named +.Em heads , +are registered with +.Fn pfil_head_register . +The function is supplied with special versioned +.Vt struct pfil_head_args +structure that specifies type and features of the head as well as +human readable name. +If the filtering point to be ever destroyed, the subsystem that +created it must unregister it with call to +.Fn pfil_head_unregister . +.Pp +Packet filtering systems may register arbitrary number of filters, +for historical reasons named +.Em hooks . +To register a new hook +.Fn pfil_add_hook +with special versioned +.Vt struct pfil_hook_args +structure is called. +The structure specifies type and features of the hook, pointer to +the actual filtering function and user readable name of the filtering +module and ruleset name. +Later hooks can be removed with +.Fn pfil_remove_hook +functions. +.Pp +To connect existing +.Em hook +to an existing +.Em head +function +.Fn pfil_link +shall be used. +The function is supplied with versioned +.Vt struct pfil_link_args +structure that specifies either literal names of hook and head or +pointers to them. +Typically +.Fn pfil_link +is called by filtering modules to autoregister their default ruleset +and default filtering points. +It also serves on the kernel side of +.Xr ioctl 2 +when user changes +.Nm +configuration with help of +.Xr pfilctl 8 +utility. +.Pp +For every packet traveling through a +.Em head +the latter shall invoke +.Fn pfil_run_hooks . +The function can accept either +.Vt struct mbuf * +pointer or a +.Vt void * +pointer and length. +In case if a hooked filtering module cannot understand +.Vt void * +pointer +.Nm +will provide it with a fake one. +All calls to +.Fn pfil_run_hooks +are performed in network +.Xr epoch 9 . +.Sh HEADS (filtering points) +By default kernel creates the following heads: +.Bl -tag -width "ethernet" +.It inet +IPv4 packets. +.It inet6 +IPv6 packets. +.It ethernet +Link-layer packets. +.El +.Pp +Default rulesets are automatically linked to these heads to preserve +historical behaviour. +.Sh SEE ALSO +.Xr ipfilter 4 , +.Xr ipfw 4 , +.Xr pf 4 , +.Xr pfilctl 8 +.Sh HISTORY +The +.Nm +interface first appeared in +.Nx 1.3 . +The +.Nm +interface was imported into +.Fx 5.2 . +In +.Fx 13.0 +the interface was significantly rewritten. diff --git a/static/freebsd/man9/pfind.9 b/static/freebsd/man9/pfind.9 new file mode 100644 index 00000000..298b6b3e --- /dev/null +++ b/static/freebsd/man9/pfind.9 @@ -0,0 +1,91 @@ +.\" Copyright (c) 2001 Evan Sarmiento. +.\" 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 November 3, 2025 +.Dt PFIND 9 +.Os +.Sh NAME +.Nm pfind , +.Nm pfind_any , +.Nm pfind_any_locked +.Nd locate a process by number +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.Ft "struct proc *" +.Fn pfind "pid_t pid" +.Ft "struct proc *" +.Fn pfind_any "pid_t pid" +.Ft "struct proc *" +.Fn pfind_any_locked "pid_t pid" +.Sh DESCRIPTION +The +.Fn pfind +function walks the list of processes in the system, looking for the one with a +process ID of +.Fa pid . +If the process exists, and is not in the zombie state, a pointer to the process +structure will be returned. +.Pp +.Fn pfind_any +takes a +.Fa pid +as its argument. +.Fn pfind_any +searches the +.Va allproc +list and returns the first process with a matching PID, whose state may be +.Dv PRS_ZOMBIE . +.Pp +.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. +.Pp +All three functions +.Fn pfind , +.Fn pfind_any , +and +.Fn pfind_any_locked +lock the +.Vt proc +structure before returning. +.Sh RETURN VALUES +.Fn pfind , +.Fn pfind_any , +and +.Fn pfind_any_locked +return pointer to a +.Vt proc +structure on success or +.Dv NULL +on failure. +.Sh SEE ALSO +.Xr pget 9 , +.Xr pgfind 9 +.Sh AUTHORS +This manual page was written by +.An Evan Sarmiento Aq Mt kaworu@sektor7.ath.cx . diff --git a/static/freebsd/man9/pget.9 b/static/freebsd/man9/pget.9 new file mode 100644 index 00000000..af292d21 --- /dev/null +++ b/static/freebsd/man9/pget.9 @@ -0,0 +1,105 @@ +.\" Copyright (c) 2011 Sergey Kandaurov +.\" 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 May 3, 2014 +.Dt PGET 9 +.Os +.Sh NAME +.Nm pget +.Nd locate a process by number +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.Ft int +.Fn pget "pid_t pid" "int flags" "struct proc **pp" +.Sh DESCRIPTION +This function +takes a +.Fa pid +as its argument, +which can be either a process or thread id, +and fills a pointer to the +.Vt proc +structure in +.Fa *pp . +In the latter case, a process owning the specified thread is looked for. +The operation is performed by invoking the +.Xr pfind 9 +function. +The found process is returned locked. +For the +.Dv PGET_HOLD +case, it is returned unlocked (but held). +The +.Fn pget +function can +perform additional manipulations, depending on a +.Fa flags +argument. +.Pp +The +.Fa flags +argument is the logical OR of some subset of: +.Bl -tag -width ".Dv PGET_NOTINEXEC" +.It Dv PGET_HOLD +If set, the found process will be held and unlocked. +.It Dv PGET_CANSEE +If set, the found process will be checked for its visibility. +See +.Xr p_cansee 9 . +.It Dv PGET_CANDEBUG +If set, the found process will be checked for its debuggability. +See +.Xr p_candebug 9 . +.It Dv PGET_ISCURRENT +If set, the found process will be checked that it matches the current +process context. +.It Dv PGET_NOTWEXIT +If set, the found process will be checked that it does not have the process +flag +.Dv P_WEXIT +set. +.It Dv PGET_NOTINEXEC +If set, the found process will be checked that it does not have the process +flag +.Dv P_INEXEC +set. +.It Dv PGET_NOTID +If set, +.Fa pid +is not assumed as a thread id for values larger than +.Dv PID_MAX . +.It Dv PGET_WANTREAD +If set, the found process will be checked that the caller may get +a read access to its structure. +A shorthand for +.Pq Dv PGET_HOLD | PGET_CANDEBUG | PGET_NOTWEXIT . +.El +.Sh RETURN VALUES +If the process is found in the specified way, then zero is returned, +otherwise an appropriate error code is returned. +.Sh SEE ALSO +.Xr p_candebug 9 , +.Xr p_cansee 9 , +.Xr pfind 9 diff --git a/static/freebsd/man9/pgfind.9 b/static/freebsd/man9/pgfind.9 new file mode 100644 index 00000000..58e2e290 --- /dev/null +++ b/static/freebsd/man9/pgfind.9 @@ -0,0 +1,63 @@ +.\" Copyright (c) 2001 Evan Sarmiento. +.\" 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 August 8, 2001 +.Dt PGFIND 9 +.Os +.Sh NAME +.Nm pgfind +.Nd "locate a process group by number" +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.Ft "struct pgrp *" +.Fn pgfind "pid_t pgid" +.Sh DESCRIPTION +The +.Fn pgfind +function takes a +.Fa pgid +as its argument and returns a pointer to the +.Vt pgrp +structure whose +.Va pg_id +is specified in the argument. +.Pp +.Fn pgfind +locks the +.Vt pgrp +structure that is returned. +.Sh RETURN VALUES +The +.Fn pgfind +function returns +.Dv NULL +on failure or a pointer to a +.Vt pgrp +structure on successful completion. +.Sh SEE ALSO +.Xr pfind 9 +.Sh AUTHORS +This manual page was written by +.An Evan Sarmiento Aq Mt kaworu@sektor7.ath.cx . diff --git a/static/freebsd/man9/physio.9 b/static/freebsd/man9/physio.9 new file mode 100644 index 00000000..09f2886c --- /dev/null +++ b/static/freebsd/man9/physio.9 @@ -0,0 +1,129 @@ +.\" $NetBSD: physio.9,v 1.2 1996/11/11 00:05:12 lukem Exp $ +.\" +.\" Copyright (c) 1996 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Paul Kranenburg. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 REGENTS OR CONTRIBUTORS BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 19, 2012 +.Dt PHYSIO 9 +.Os +.Sh NAME +.Nm physio +.Nd initiate I/O on raw devices +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.In sys/bio.h +.In sys/buf.h +.Ft int +.Fn physio "struct cdev *dev" "struct uio *uio" "int ioflag" +.Sh DESCRIPTION +The +.Fn physio +is a helper function typically called from character device +.Fn read +and +.Fn write +routines to start I/O on a user process buffer. +The maximum amount of data to transfer with each call +is determined by +.Fa dev->si_iosize_max . +The +.Fn physio +call converts the I/O request into a +.Fn strategy +request and passes the new request to the driver's +.Fn strategy +routine for processing. +.Pp +Since +.Fa uio +normally describes user space addresses, +.Fn physio +needs to lock those pages into memory. +This is done by calling +.Fn vmapbuf +for the appropriate pages. +.Fn physio +always awaits the completion of the entire requested transfer before +returning, unless an error condition is detected earlier. +.Pp +A break-down of the arguments follows: +.Bl -tag -width indent +.It Fa dev +The device number identifying the device to interact with. +.It Fa uio +The description of the entire transfer as requested by the user process. +Currently, the results of passing a +.Fa uio +structure with the +.Va uio_segflg +set to anything other than +.Dv UIO_USERSPACE +are undefined. +.It Fa ioflag +The ioflag argument from the +.Fn read +or +.Fn write +function calling +.Fn physio . +.El +.Sh RETURN VALUES +If successful +.Fn physio +returns 0. +.Er EFAULT +is returned if the address range described by +.Fa uio +is not accessible by the requesting process. +.Fn physio +will return any error resulting from calls to the device strategy routine, +by examining the +.Dv B_ERROR +buffer flag and the +.Va b_error +field. +Note that the actual transfer size may be less than requested by +.Fa uio +if the device signals an +.Dq "end of file" +condition. +.Sh SEE ALSO +.Xr read 2 , +.Xr write 2 +.Sh HISTORY +The +.Nm +manual page is originally from +.Nx +with minor changes for applicability with +.Fx . +.Pp +The +.Nm +call has been completely re-written for providing higher +I/O and paging performance. diff --git a/static/freebsd/man9/pmap.9 b/static/freebsd/man9/pmap.9 new file mode 100644 index 00000000..8c86f44d --- /dev/null +++ b/static/freebsd/man9/pmap.9 @@ -0,0 +1,125 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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 January 12, 2024 +.Dt PMAP 9 +.Os +.Sh NAME +.Nm pmap +.Nd machine-dependent portion of virtual memory subsystem +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Sh DESCRIPTION +The +.Nm +module is the machine-dependent portion of the +.Fx +VM (Virtual Memory) sub-system. +Each function documented herein must have its own +architecture-dependent implementation. +.Pp +The +.Nm +module +is responsible for managing hardware-dependent objects such as page tables, +address maps, TLBs, etc. +.Pp +Machine-dependent code must provide the header file +.In machine/pmap.h . +This file contains the definition of the +.Vt pmap +structure: +.Bd -literal -offset indent +struct pmap { + /* Contents defined by pmap implementation. */ +}; +typedef struct pmap *pmap_t; +.Ed +.Pp +This header file may also define other data structures used by the +.Nm +implementation. +.Pp +The header file +.In vm/pmap.h +defines a structure for tracking +.Nm +statistics (see below). +This structure is defined as: +.Bd -literal -offset indent +struct pmap_statistics { + long resident_count; /* number of mapped pages */ + long wired_count; /* number of wired pages */ +}; +.Ed +.Pp +The implementation's +.Vt "struct pmap" +must contain an instance of this structure having the name +.Va pm_stats , +and it must be updated by the implementation after each relevant +.Nm +operation. +.Sh SEE ALSO +.Xr pmap_activate 9 , +.Xr pmap_clear_modify 9 , +.Xr pmap_copy 9 , +.Xr pmap_copy_page 9 , +.Xr pmap_enter 9 , +.Xr pmap_extract 9 , +.Xr pmap_extract_and_hold 9 , +.Xr pmap_growkernel 9 , +.Xr pmap_init 9 , +.Xr pmap_is_modified 9 , +.Xr pmap_is_prefaultable 9 , +.Xr pmap_kextract 9 , +.Xr pmap_map 9 , +.Xr pmap_mincore 9 , +.Xr pmap_object_init_pt 9 , +.Xr pmap_page_exists_quick 9 , +.Xr pmap_page_init 9 , +.Xr pmap_pinit 9 , +.Xr pmap_pinit0 9 , +.Xr pmap_protect 9 , +.Xr pmap_qenter 9 , +.Xr pmap_qremove 9 , +.Xr pmap_quick_enter_page 9 , +.Xr pmap_quick_remove_page 9 , +.Xr pmap_release 9 , +.Xr pmap_remove 9 , +.Xr pmap_remove_all 9 , +.Xr pmap_remove_pages 9 , +.Xr pmap_resident_count 9 , +.Xr pmap_ts_referenced 9 , +.Xr pmap_unwire 9 , +.Xr pmap_wired_count 9 , +.Xr pmap_zero_area 9 , +.Xr pmap_zero_page 9 , +.Xr vm_map 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/pmap_activate.9 b/static/freebsd/man9/pmap_activate.9 new file mode 100644 index 00000000..9a398983 --- /dev/null +++ b/static/freebsd/man9/pmap_activate.9 @@ -0,0 +1,49 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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 21, 2003 +.Dt PMAP_ACTIVATE 9 +.Os +.Sh NAME +.Nm pmap_activate +.Nd activate a physical map +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft void +.Fn pmap_activate "struct thread *td" +.Sh DESCRIPTION +The +.Fn pmap_activate +function activates the physical map for a user thread +.Fa td . +This function must be called before the thread's address space may be +accessed. +.Sh SEE ALSO +.Xr pmap 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/pmap_clear_modify.9 b/static/freebsd/man9/pmap_clear_modify.9 new file mode 100644 index 00000000..708ea1aa --- /dev/null +++ b/static/freebsd/man9/pmap_clear_modify.9 @@ -0,0 +1,50 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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 17, 2014 +.Dt PMAP_CLEAR_MODIFY 9 +.Os +.Sh NAME +.Nm pmap_clear_modify +.Nd set information about physical pages +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft void +.Fn pmap_clear_modify "vm_page_t m" +.Sh DESCRIPTION +The +.Fn pmap_clear_modify +function clears the +.Dq modified +bit on the physical page +.Fa m . +.Sh SEE ALSO +.Xr pmap 9 , +.Xr pmap_is_modified 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/pmap_copy.9 b/static/freebsd/man9/pmap_copy.9 new file mode 100644 index 00000000..cfc24282 --- /dev/null +++ b/static/freebsd/man9/pmap_copy.9 @@ -0,0 +1,82 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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 21, 2003 +.Dt PMAP_COPY 9 +.Os +.Sh NAME +.Nm pmap_copy , +.Nm pmap_copy_page +.Nd copy physical memory pages +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft void +.Fo pmap_copy +.Fa "pmap_t dst_pmap" "pmap_t src_pmap" "vm_offset_t dst_addr" +.Fa "vm_size_t len" "vm_offset_t src_addr" +.Fc +.Ft void +.Fn pmap_copy_page "vm_page_t src" "vm_page_t dst" +.Sh DESCRIPTION +The +.Fn pmap_copy +function copies the range specified by +.Fa src_addr +and +.Fa len +from the source physical map +.Fa src_pmap +to the destination physical map +.Fa dst_pmap +at the address +.Fa dst_addr . +.Pp +The +.Fn pmap_copy_page +function +copies the physical page +.Fa src +to the physical page +.Fa dst , +by mapping the page into kernel virtual address space (KVA), and using +.Fn bcopy +to copy the page. +.Sh IMPLEMENTATION NOTES +The +.Fn pmap_copy +routine is only advisory and need not do anything. +Actually implementing it may seriously reduce system performance. +.Pp +The +.Fn pmap_copy_page +routine only operates upon a single page. +.Sh SEE ALSO +.Xr bcopy 3 , +.Xr pmap 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/pmap_enter.9 b/static/freebsd/man9/pmap_enter.9 new file mode 100644 index 00000000..d4b8dd7e --- /dev/null +++ b/static/freebsd/man9/pmap_enter.9 @@ -0,0 +1,170 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" Copyright (c) 2014 The FreeBSD Foundation +.\" 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 December 16, 2018 +.Dt PMAP_ENTER 9 +.Os +.Sh NAME +.Nm pmap_enter +.Nd insert a virtual page into a physical map +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft int +.Fo pmap_enter +.Fa "pmap_t pmap" "vm_offset_t va" "vm_page_t m" "vm_prot_t prot" +.Fa "u_int flags" "int8_t psind" +.Fc +.Sh DESCRIPTION +The +.Fn pmap_enter +function creates a mapping in the physical map +.Fa pmap +from the virtual address +.Fa va +to the physical page +.Fa m +with the protection +.Fa prot . +Any previous mapping at the virtual address +.Fa va +is destroyed. +.Pp +The +.Fa flags +argument may have the following values: +.Bl -tag -width ".Dv PMAP_ENTER_NOSLEEP" +.It Dv VM_PROT_READ +A read access to the given virtual address triggered the call. +.It Dv VM_PROT_WRITE +A write access to the given virtual address triggered the call. +.It Dv VM_PROT_EXECUTE +An execute access to the given virtual address triggered the call. +.It Dv PMAP_ENTER_WIRED +The mapping should be marked as wired. +.It Dv PMAP_ENTER_NOSLEEP +This function may not sleep during creation of the mapping. +If the mapping cannot be created without sleeping, an appropriate +Mach VM error is returned. +.El +If the +.Dv PMAP_ENTER_NOSLEEP +flag is not specified, this function must create the requested mapping +before returning. +It may not fail. +In order to create the requested mapping, this function may destroy +any non-wired mapping in any pmap. +.Pp +The +.Fa psind +parameter specifies the page size that should be used by the mapping. +The supported page sizes are described by the global array +.Dv pagesizes[] . +The desired page size is specified by passing the index of the array +element that equals the desired page size. +.Pp +When the +.Fn pmap_enter +function destroys or updates a managed mapping, including an existing +mapping at virtual address +.Fa va , +it updates the +.Ft vm_page +structure corresponding to the previously mapped physical page. +If the physical page was accessed through the managed mapping, +then the +.Ft vm_page +structure's +.Dv PGA_REFERENCED +aflag is set. +If the physical page was modified through the managed mapping, then the +.Fn vm_page_dirty +function is called on the +.Ft vm_page +structure. +.Pp +The +.Dv PGA_WRITEABLE +aflag must be set for the page +.Fa m +if the new mapping is managed and writeable. +It is advised to clear +.Dv PGA_WRITEABLE +for destroyed mappings if the implementation can ensure +that no other writeable managed mappings for the previously +mapped pages exist. +.Pp +If the request modifies an existing mapping to use a different physical +page, an implementation of +.Nm +must invalidate the previous mapping before installing the new one. +This ensures that all threads sharing the pmap keep a consistent +view of the mapping, which is necessary for the correct handling +of CoW (copy on write) faults. +.Pp +If the page +.Fa m +is managed, the page must be busied by the caller +or the owning object must be locked. +In the later case, the +.Dv PMAP_ENTER_NOSLEEP +must be specified by the caller. +.Pp +The +.Fn pmap_enter +function must handle the multiprocessor TLB consistency for the +given address. +.Sh NOTES +On arm and i386 architectures the existing implementation +of the +.Nm +function is incomplete, only value 0 for +.Fa psind +is supported. +Other supported architectures, except amd64, have +.Dv pagesizes[] +array of size 1. +.Sh RETURN VALUES +If successful, the +.Fn pmap_enter +function returns +.Er KERN_SUCCESS . +If the +.Dv PMAP_ENTER_NOSLEEP +flag was specified and the resources required for the mapping cannot +be acquired without sleeping, +.Dv KERN_RESOURCE_SHORTAGE +is returned. +.Sh SEE ALSO +.Xr pmap 9 +.Sh AUTHORS +This manual page was first written by +.An Bruce M Simpson Aq Mt bms@spc.org +and then rewritten by +.An Alan Cox Aq Mt alc@FreeBSD.org +and +.An Konstantin Belousov Aq Mt kib@FreeBSD.org . diff --git a/static/freebsd/man9/pmap_extract.9 b/static/freebsd/man9/pmap_extract.9 new file mode 100644 index 00000000..89655879 --- /dev/null +++ b/static/freebsd/man9/pmap_extract.9 @@ -0,0 +1,95 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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 21, 2003 +.Dt PMAP_EXTRACT 9 +.Os +.Sh NAME +.Nm pmap_extract , +.Nm pmap_extract_and_hold +.Nd map a virtual address to a physical page +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft vm_paddr_t +.Fn pmap_extract "pmap_t pmap" "vm_offset_t va" +.Ft vm_page_t +.Fn pmap_extract_and_hold "pmap_t pmap" "vm_offset_t va" "vm_prot_t prot" +.Sh DESCRIPTION +The +.Fn pmap_extract +function maps a virtual address to a physical page. +In certain situations, callers may use +.Fn pmap_extract_and_hold +instead, to ensure that the returned page is held. +.Pp +The +.Fn pmap_extract_and_hold +function maps a virtual address to a physical page, and atomically holds +the returned page for use by the caller, only if the mapping permits +the given page protection. +.Sh IMPLEMENTATION NOTES +Currently, the page protection requested by the caller is not verified. +.Sh RETURN VALUES +The +.Fn pmap_extract +function will return the physical page address associated with the +virtual address +.Fa va +inside the physical map +.Fa pmap . +If the mapping does not exist, or if the +.Fa pmap +parameter is +.Dv NULL , +then +.Dv NULL +will be returned. +.Pp +The +.Fn pmap_extract_and_hold +function will return the +.Ft vm_page_t +associated with the +virtual address +.Fa va +inside the physical map +.Fa pmap . +If the mapping does not exist, the result is a no-op, and +.Dv NULL +will +be returned. +.Sh SEE ALSO +.Xr mutex 9 , +.Xr pmap 9 +.Sh AUTHORS +.An -nosplit +The +.Fn pmap_extract_and_hold +function was implemented by +.An Alan L. Cox Aq Mt alc@imimic.com . +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/pmap_growkernel.9 b/static/freebsd/man9/pmap_growkernel.9 new file mode 100644 index 00000000..4a39ed27 --- /dev/null +++ b/static/freebsd/man9/pmap_growkernel.9 @@ -0,0 +1,49 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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 21, 2003 +.Dt PMAP_GROWKERNEL 9 +.Os +.Sh NAME +.Nm pmap_growkernel +.Nd grow the kernel virtual address (KVA) space +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft void +.Fn pmap_growkernel "vm_offset_t addr" +.Sh DESCRIPTION +The +.Fn pmap_growkernel +function grows the kernel virtual address space to the virtual address +.Fa addr . +.Pp +It will allocate more page entries if required. +.Sh SEE ALSO +.Xr pmap 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/pmap_init.9 b/static/freebsd/man9/pmap_init.9 new file mode 100644 index 00000000..3ca609d0 --- /dev/null +++ b/static/freebsd/man9/pmap_init.9 @@ -0,0 +1,53 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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 January 12, 2024 +.Dt PMAP_INIT 9 +.Os +.Sh NAME +.Nm pmap_init +.Nd initialize the pmap subsystem +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft void +.Fn pmap_init "void" +.Sh DESCRIPTION +The +.Fn pmap_init +function initializes the +.Xr pmap 9 +sub-system. +It is called during system initialization by +.Fn vm_mem_init , +to initialize any structures that the +.Nm +system needs in order to map between physical and virtual memory. +.Sh SEE ALSO +.Xr pmap 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/pmap_is_modified.9 b/static/freebsd/man9/pmap_is_modified.9 new file mode 100644 index 00000000..4f6a15b8 --- /dev/null +++ b/static/freebsd/man9/pmap_is_modified.9 @@ -0,0 +1,68 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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 17, 2014 +.Dt PMAP_IS_MODIFIED 9 +.Os +.Sh NAME +.Nm pmap_is_modified , +.Nm pmap_ts_modified +.Nd return information about physical pages +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft bool +.Fn pmap_is_modified "vm_page_t m" +.Ft int +.Fn pmap_ts_referenced "vm_page_t m" +.Sh DESCRIPTION +The +.Fn pmap_is_modified +and +.Fn pmap_ts_referenced +functions return information about physical pages. +.Sh RETURN VALUES +The +.Fn pmap_is_modified +function returns the status of the +.Dq "page modified" +bit for the physical page +.Fa m . +.Pp +The +.Fn pmap_ts_referenced +function returns a count of reference bits for a page +.Fa m , +clearing those bits. +It is not necessary for every reference bit to be cleared, but it is +necessary that 0 only be returned when there are no remaining reference +bits set on the page. +.Sh SEE ALSO +.Xr pmap 9 , +.Xr pmap_clear_modify 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/pmap_is_prefaultable.9 b/static/freebsd/man9/pmap_is_prefaultable.9 new file mode 100644 index 00000000..eb8bd54c --- /dev/null +++ b/static/freebsd/man9/pmap_is_prefaultable.9 @@ -0,0 +1,55 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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 21, 2003 +.Dt PMAP_IS_PREFAULTABLE 9 +.Os +.Sh NAME +.Nm pmap_is_prefaultable +.Nd determine if a page may be prefaulted +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft bool +.Fn pmap_is_prefaultable "pmap_t pmap" "vm_offset_t va" +.Sh DESCRIPTION +The +.Fn pmap_is_prefaultable +function provides a means of determining if the page residing at +virtual address +.Fa va +in the physical map +.Fa pmap +may be pre-faulted into main memory. +.Pp +This is a helper function which is called by +.Xr vm_fault_prefault 9 . +.Sh SEE ALSO +.Xr pmap 9 , +.Xr vm_fault_prefault 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/pmap_kextract.9 b/static/freebsd/man9/pmap_kextract.9 new file mode 100644 index 00000000..a93bbc70 --- /dev/null +++ b/static/freebsd/man9/pmap_kextract.9 @@ -0,0 +1,77 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2023 The FreeBSD Foundation +.\" +.\" This manual page was written by Mina Galić under +.\" sponsorship from the FreeBSD Foundation. +.\" +.Dd October 16, 2023 +.Dt PMAP_KEXTRACT 9 +.Os +.Sh NAME +.Nm pmap_kextract , +.Nm vtophys +.Nd extract a physical address from the kernel page table +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft vm_paddr_t +.Fo pmap_kextract +.Fa "vm_offset_t va" +.Fc +.Ft vm_paddr_t +.Fo vtophys +.Fa "vm_offset_t va" +.Fc +.Sh DESCRIPTION +The +.Fn pmap_kextract +function retrieves the underlying physical memory address corresponding to the +given kernel virtual address +.Fa va . +The caller is responsible for ensuring that +.Fa va +belongs to a valid mapping in the kernel address space. +The returned physical address is only meaningful as long as the mapping remains +stable, so the caller must also have some knowledge or guarantee of the +mapping's lifetime. +For example, it is invalid to call +.Fn pmap_kextract +with the address of a malloc'd object while there is a possibility for that +object to be freed concurrently. +.Pp +Unlike +.Xr pmap_extract 9 , +.Fn pmap_kextract +is safe to be called from any context; it has no internal locking or sleep. +.Pp +.Fn vtophys +is an alias for +.Fn pmap_kextract +and behaves identically. +.Sh RETURN VALUES +The +.Fn pmap_kextract +function returns the physical address of memory mapped at the kernel +virtual address +.Fa va . +.Pp +.Fn pmap_kextract +generally does not fail. +However, if supplied with an illegitimate value for +.Fa va , +the function may return zero, an invalid non-zero value, or call +.Xr panic 9 . +.Sh SEE ALSO +.Xr pmap 9 , +.Xr pmap_extract 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Mina Galić Aq Mt FreeBSD@igalic.co , +based on the +.Xr pmap_extract 9 +page written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/pmap_map.9 b/static/freebsd/man9/pmap_map.9 new file mode 100644 index 00000000..9af18286 --- /dev/null +++ b/static/freebsd/man9/pmap_map.9 @@ -0,0 +1,78 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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 21, 2003 +.Dt PMAP_MAP 9 +.Os +.Sh NAME +.Nm pmap_map +.Nd map a physical memory range into kernel virtual address (KVA) space +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft vm_offset_t +.Fo pmap_map +.Fa "vm_offset_t *virt" "vm_paddr_t start" "vm_paddr_t end" "int prot" +.Fc +.Sh DESCRIPTION +The +.Fn pmap_map +function maps a range of physical addresses into kernel virtual address (KVA) +space, from +.Fa start +to +.Fa end , +with protection bits +.Fa prot . +.Pp +The value passed in +.Fa *virt +is treated as a hint for the virtual address of the beginning of the mapping. +.Sh IMPLEMENTATION NOTES +The +.Fa prot +argument is currently ignored by machine-dependent implementations. +.Pp +Architectures which can support a direct mapped physical to virtual +region can return the appropriate address within that region, leaving +.Fa *virt +unchanged. +.Sh RETURN VALUES +The +.Fn pmap_map +function returns the virtual address of the beginning of the mapping, if +the mapping was successfully made; +.Fa *virt +will also be updated with the first usable address after the mapped region. +.Pp +If the function is unsuccessful, +.Dv NULL +is returned. +.Sh SEE ALSO +.Xr pmap 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/pmap_mincore.9 b/static/freebsd/man9/pmap_mincore.9 new file mode 100644 index 00000000..38c3f9ac --- /dev/null +++ b/static/freebsd/man9/pmap_mincore.9 @@ -0,0 +1,72 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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 21, 2003 +.Dt PMAP_MINCORE 9 +.Os +.Sh NAME +.Nm pmap_mincore +.Nd determine if a virtual address is resident in physical memory +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft int +.Fn pmap_mincore "pmap_t pmap" "vm_offset_t addr" +.Sh DESCRIPTION +The +.Fn pmap_mincore +function determines if the page at the virtual address +.Fa addr +in the physical map +.Fa pmap +is resident in physical memory. +It is the machine-dependent interface used by the +.Xr mincore 2 +system call. +.Sh RETURN VALUES +If the page is resident in physical memory, +a mask of flags is returned, +whose meaning is documented in +.Xr mincore 2 ; +otherwise, +0 +is returned. +.Pp +The +.Fa pmap +must exist and +.Fa addr +must be mapped into the +.Fa pmap . +If any error occurs, the machine-dependent implementation should +return +0. +.Sh SEE ALSO +.Xr mincore 2 , +.Xr pmap 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/pmap_object_init_pt.9 b/static/freebsd/man9/pmap_object_init_pt.9 new file mode 100644 index 00000000..a4c6f804 --- /dev/null +++ b/static/freebsd/man9/pmap_object_init_pt.9 @@ -0,0 +1,71 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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 21, 2003 +.Dt PMAP_OBJECT_INIT_PT 9 +.Os +.Sh NAME +.Nm pmap_object_init_pt +.Nd initialize page tables for a VM object +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft void +.Fo pmap_object_init_pt +.Fa "pmap_t pmap" "vm_offset_t addr" "vm_object_t object" +.Fa "vm_pindex_t pindex" "vm_size_t size" "int limit" +.Fc +.Sh DESCRIPTION +The +.Fn pmap_object_init_pt +function preloads the page table entries into the specified physical map +.Fa pmap , +for the given +.Fa object +at the virtual address +.Fa addr , +for +.Fa size +bytes, beginning at the page index +.Fa pindex +within the object. +The map bits +.Fa limit +are heeded when creating the mapping. +.Sh IMPLEMENTATION NOTES +This function is not strictly required by an architecture's +.Xr pmap 9 +implementation, but it does provide performance benefits if implemented. +.Pp +It is intended to eliminate the blast of soft faults on process +startup, and immediately following a call to +.Xr mmap 2 . +.Sh SEE ALSO +.Xr pmap 9 , +.Xr vm_map 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/pmap_page_exists_quick.9 b/static/freebsd/man9/pmap_page_exists_quick.9 new file mode 100644 index 00000000..030d0e1f --- /dev/null +++ b/static/freebsd/man9/pmap_page_exists_quick.9 @@ -0,0 +1,64 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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 21, 2003 +.Dt PMAP_PAGE_EXISTS_QUICK 9 +.Os +.Sh NAME +.Nm pmap_page_exists_quick +.Nd determine if a page exists in a physical map +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft bool +.Fn pmap_page_exists_quick "pmap_t pmap" "vm_page_t m" +.Sh DESCRIPTION +The +.Fn pmap_page_exists_quick +function is used to quickly determine if the page +.Fa m +exists in the physical map +.Fa pmap . +It is typically called from the VM paging code. +.Sh IMPLEMENTATION NOTES +The PV count used above may be changed upwards or downwards in future; +it is only necessary that +.Dv true +be returned for a small subset of pmaps for proper page aging. +.Sh RETURN VALUES +The +.Fn pmap_page_exists_quick +returns +.Dv true +only if the PV entry for the physical map +.Fa pmap +is one of the first 16 PVs linked from the page +.Fa m . +.Sh SEE ALSO +.Xr pmap 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/pmap_page_init.9 b/static/freebsd/man9/pmap_page_init.9 new file mode 100644 index 00000000..4e39f855 --- /dev/null +++ b/static/freebsd/man9/pmap_page_init.9 @@ -0,0 +1,49 @@ +.\" +.\" Copyright (c) 2005 Hiten Pandya +.\" 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 June 10, 2005 +.Dt PMAP_PAGE_INIT 9 +.Os +.Sh NAME +.Nm pmap_page_init +.Nd initialize machine-dependent fields of a VM page +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft void +.Fn pmap_page_init "vm_page_t m" +.Sh DESCRIPTION +The +.Fn pmap_page_init +function initializes the machine-dependent fields of a VM page structure. +This procedure is normally used when adding new pages to the VM page +queue management lists. +.Sh SEE ALSO +.Xr pmap 9 , +.Xr pmap_pinit 9 +.Sh AUTHORS +This manual page was written by +.An Hiten Pandya Aq Mt hmp@FreeBSD.org . diff --git a/static/freebsd/man9/pmap_pinit.9 b/static/freebsd/man9/pmap_pinit.9 new file mode 100644 index 00000000..8ef16a69 --- /dev/null +++ b/static/freebsd/man9/pmap_pinit.9 @@ -0,0 +1,60 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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 January 12, 2024 +.Dt PMAP_PINIT 9 +.Os +.Sh NAME +.Nm pmap_pinit , +.Nm pmap_pinit0 +.Nd initialize pmap structures +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft void +.Fn pmap_pinit "pmap_t pmap" +.Ft void +.Fn pmap_pinit0 "pmap_t pm" +.Sh DESCRIPTION +The +.Fn pmap_pinit +function initializes the preallocated and zeroed structure +.Fa pmap , +such as one in a +.Vt vmspace +structure. +.Pp +The +.Fn pmap_pinit0 +function initializes the physical map +.Fa pm , +associated with process 0, the first process created in the system. +.Sh SEE ALSO +.Xr pmap 9 , +.Xr pmap_growkernel 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/pmap_protect.9 b/static/freebsd/man9/pmap_protect.9 new file mode 100644 index 00000000..80959ced --- /dev/null +++ b/static/freebsd/man9/pmap_protect.9 @@ -0,0 +1,55 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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 18, 2014 +.Dt PMAP_PROTECT 9 +.Os +.Sh NAME +.Nm pmap_protect +.Nd set physical page protection +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft void +.Fo pmap_protect +.Fa "pmap_t pmap" "vm_offset_t sva" "vm_offset_t eva" "vm_prot_t prot" +.Fc +.Sh DESCRIPTION +The +.Fn pmap_protect +function sets the physical page permissions to +.Fa prot +for all physical pages in the physical map +.Fa pmap +in the virtual address range between +.Fa sva +and +.Fa eva . +.Sh SEE ALSO +.Xr pmap 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/pmap_qenter.9 b/static/freebsd/man9/pmap_qenter.9 new file mode 100644 index 00000000..bf7b79f2 --- /dev/null +++ b/static/freebsd/man9/pmap_qenter.9 @@ -0,0 +1,79 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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 February 15, 2018 +.Dt PMAP_QENTER 9 +.Os +.Sh NAME +.Nm pmap_qenter , +.Nm pmap_qremove +.Nd manage temporary kernel space mappings +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft void +.Fn pmap_qenter "vm_offset_t sva" "vm_page_t *m" "int count" +.Ft void +.Fn pmap_qremove "vm_offset_t sva" "int count" +.Sh DESCRIPTION +The +.Fn pmap_qenter +function accepts a linear array of +.Fa count +pointers to wired pages +.Fa *m , +and enters each of these pages into the kernel virtual address (KVA) space, +beginning at the address +.Fa sva . +The pages are mapped non-executable, if possible. +(For example, non-PAE i386 has no capability to map pages non-executable.) +.Pp +The +.Fn pmap_qremove +function tears out a mapping from the kernel virtual address space, +beginning at +.Fa sva +and for +.Fa count +pages. +.Sh IMPLEMENTATION NOTES +The +.Fn pmap_qenter +function is intended for temporary mappings that do not require page +modification or reference counting. +Old mappings are simply overwritten. +The pages +.Em must +be wired into physical memory. +.Pp +The corresponding +.Fn pmap_qremove +function is intended to remove such temporary mappings. +.Sh SEE ALSO +.Xr pmap 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/pmap_quick_enter_page.9 b/static/freebsd/man9/pmap_quick_enter_page.9 new file mode 100644 index 00000000..418b657d --- /dev/null +++ b/static/freebsd/man9/pmap_quick_enter_page.9 @@ -0,0 +1,101 @@ +.\" +.\" Copyright (c) 2015 Jason A. Harmening +.\" 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 August 6, 2015 +.Dt PMAP_QUICK_ENTER_PAGE 9 +.Os +.Sh NAME +.Nm pmap_quick_enter_page , +.Nm pmap_quick_remove_page +.Nd manage fast, single-page kernel address space mappings +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft vm_offset_t +.Fn pmap_quick_enter_page "vm_page_t m" +.Ft void +.Fn pmap_quick_remove_page "vm_offset_t kva" +.Sh DESCRIPTION +The +.Fn pmap_quick_enter_page +function accepts a single page +.Fa m , +and enters this page into a preallocated address in kernel virtual +address (KVA) space. +This function is intended for temporary mappings that will only +be used for a very short period, for example a copy operation on +the page contents. +.Pp +The +.Fn pmap_quick_remove_page +function removes a mapping previously created by +.Fn pmap_quick_enter_page +at +.Fa kva , +making the KVA frame used by +.Fn pmap_quick_enter_page +available for reuse. +.Pp +On many architectures, +.Fn pmap_quick_enter_page +uses a per-CPU pageframe. +In those cases, it must disable preemption on the local CPU. +The corresponding call to +.Fn pmap_quick_remove_page +then re-enables preemption. +It is therefore not safe for machine-independent code to sleep +or perform locking operations while holding these mappings. +Current implementations only guarantee the availability of a single +page for the calling thread, so calls to +.Fn pmap_quick_enter_page +must not be nested. +.Pp +.Fn pmap_quick_enter_page +and +.Fn pmap_quick_remove_page +do not sleep, and +.Fn pmap_quick_enter_page +always returns a valid address. +It is safe to use these functions under all types of locks except spin mutexes. +It is also safe to use them in all thread contexts except primary interrupt +context. +.Pp +The page +.Em must +not be swapped or otherwise reused while the mapping is active. +It must be either wired or held, or it must belong to an unmanaged +region such as I/O device memory. +.Sh RETURN VALUES +The +.Fn pmap_quick_enter_page +function returns the kernel virtual address +that is mapped to the page +.Fa m . +.Sh SEE ALSO +.Xr pmap 9 +.Sh AUTHORS +This manual page was written by +.An Jason A Harmening Aq Mt jah@FreeBSD.org . diff --git a/static/freebsd/man9/pmap_release.9 b/static/freebsd/man9/pmap_release.9 new file mode 100644 index 00000000..b343c4c6 --- /dev/null +++ b/static/freebsd/man9/pmap_release.9 @@ -0,0 +1,56 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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 21, 2003 +.Dt PMAP_RELEASE 9 +.Os +.Sh NAME +.Nm pmap_release +.Nd release resources held by a physical map +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft void +.Fn pmap_release "pmap_t pmap" +.Sh DESCRIPTION +The +.Fn pmap_release +function releases any resources held by the physical map +.Fa pmap . +This function is +called when a pmap initialized by the corresponding function, +.Fn pmap_pinit +is being released. +.Sh IMPLEMENTATION NOTES +This function should only be called if +.Fa pmap +no longer contains any valid mappings. +.Sh SEE ALSO +.Xr pmap 9 , +.Xr pmap_pinit 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/pmap_remove.9 b/static/freebsd/man9/pmap_remove.9 new file mode 100644 index 00000000..0b48b92b --- /dev/null +++ b/static/freebsd/man9/pmap_remove.9 @@ -0,0 +1,82 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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 21, 2003 +.Dt PMAP_REMOVE 9 +.Os +.Sh NAME +.Nm pmap_remove , +.Nm pmap_remove_all , +.Nm pmap_remove_pages +.Nd remove pages from a physical map +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft void +.Fn pmap_remove "pmap_t pmap" "vm_offset_t sva" "vm_offset_t eva" +.Ft void +.Fn pmap_remove_all "vm_page_t m" +.Ft void +.Fn pmap_remove_pages "pmap_t pmap" +.Sh DESCRIPTION +The +.Fn pmap_remove +function removes the range of addresses between +.Fa sva +and +.Fa eva +from the physical map +.Fa pmap . +If +.Fa eva +is less than +.Fa sva , +then the result is undefined. +It is assumed that both +.Fa sva +and +.Fa eva +are page-aligned addresses. +.Pp +The +.Fn pmap_remove_all +removes the physical page +.Fa m +from all physical maps in which it resides, and reflects back the modify +bits to the appropriate pager. +.Pp +The +.Fn pmap_remove_pages +function removes all user pages from the physical map +.Fa pmap . +This function is called when a process exits to run down its address space +more quickly than would be the case for calling +.Fn pmap_remove . +.Sh SEE ALSO +.Fn pmap 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/pmap_resident_count.9 b/static/freebsd/man9/pmap_resident_count.9 new file mode 100644 index 00000000..fae1f759 --- /dev/null +++ b/static/freebsd/man9/pmap_resident_count.9 @@ -0,0 +1,72 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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 21, 2003 +.Dt PMAP_RESIDENT_COUNT 9 +.Os +.Sh NAME +.Nm pmap_resident_count , +.Nm pmap_wired_count +.Nd return page resident and wiring statistics +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft long +.Fn pmap_resident_count "pmap_t pmap" +.Ft long +.Fn pmap_wired_count "pmap_t pmap" +.Sh DESCRIPTION +The +.Fn pmap_resident_count +and +.Fn pmap_wired_count +macros allow +.Nm pmap +consumers to retrieve statistics from the +.Va pm_stats +member of the machine-dependent structure +.Vt struct pmap . +.Sh IMPLEMENTATION NOTES +Both functions are defined as in-line macros. +The members which they access have type +.Vt long . +.Sh RETURN VALUES +The +.Fn pmap_resident_count +returns the number of pages in the physical map +.Va pmap +which are currently resident in main memory. +.Pp +The +.Fn pmap_wired_count +returns the number of pages in the physical map +.Va pmap +which are currently wired into in main memory. +.Sh SEE ALSO +.Xr pmap 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/pmap_unwire.9 b/static/freebsd/man9/pmap_unwire.9 new file mode 100644 index 00000000..ca36d4e0 --- /dev/null +++ b/static/freebsd/man9/pmap_unwire.9 @@ -0,0 +1,63 @@ +.\" +.\" Copyright (c) 2014 Alan L. Cox +.\" 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 17, 2014 +.Dt PMAP_UNWIRE 9 +.Os +.Sh NAME +.Nm pmap_unwire +.Nd unwire a range of virtual pages +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft void +.Fo pmap_unwire +.Fa "pmap_t pmap" "vm_offset_t start" "vm_offset_t end" +.Fc +.Sh DESCRIPTION +The function +.Fn pmap_unwire +removes the wired attribute from each of the virtual-to-physical page mappings +within the virtual address range from +.Fa start +to +.Fa end +of the physical map +.Fa pmap . +Every valid mapping within that range is required to have the wired attribute +set. +Invalid mappings are ignored, since they cannot have the wired attribute set. +.Sh NOTES +Only the function +.Xr pmap_enter 9 +can be used to set the wired attribute of a virtual-to-physical page mapping. +.Sh SEE ALSO +.Xr pmap 9 , +.Xr pmap_enter 9 , +.Xr pmap_wired_count 9 +.Sh AUTHORS +This manual page was written by +.An Alan L. Cox Aq alc@rice.edu . diff --git a/static/freebsd/man9/pmap_zero_page.9 b/static/freebsd/man9/pmap_zero_page.9 new file mode 100644 index 00000000..82cf9ccf --- /dev/null +++ b/static/freebsd/man9/pmap_zero_page.9 @@ -0,0 +1,58 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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 August 30, 2016 +.Dt PMAP_ZERO 9 +.Os +.Sh NAME +.Nm pmap_zero_page , +.Nm pmap_zero_area +.Nd zero-fill a page using machine-dependent optimizations +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft void +.Fn pmap_zero_page "vm_page_t m" +.Ft void +.Fn pmap_zero_page_area "vm_page_t m" "int off" "int size" +.Sh DESCRIPTION +The +.Fn pmap_zero_page +function zero-fills an entire page using machine-dependent optimizations. +The +.Fn pmap_zero_page_area +function is used to zero-fill an area of a page. +The range specified must not cross a page boundary; it must be contained +entirely within a single page. +.Sh IMPLEMENTATION NOTES +This function is required to be implemented for each architecture supported by +.Fx . +.Sh SEE ALSO +.Xr bzero 3 , +.Xr pmap 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/printf.9 b/static/freebsd/man9/printf.9 new file mode 100644 index 00000000..5c819acb --- /dev/null +++ b/static/freebsd/man9/printf.9 @@ -0,0 +1,197 @@ +.\" +.\" Copyright (c) 2001 Andrew R. Reiter +.\" Copyright (c) 2004 Joerg Wunsch +.\" 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 ``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 December 19, 2025 +.Dt PRINTF 9 +.Os +.Sh NAME +.Nm printf , +.Nm uprintf , +.Nm tprintf , +.Nm log +.Nd formatted output conversion +.Sh SYNOPSIS +.In sys/types.h +.In sys/systm.h +.Ft int +.Fn printf "const char *fmt" ... +.Ft void +.Fn tprintf "struct proc *p" "int pri" "const char *fmt" ... +.Ft int +.Fn uprintf "const char *fmt" ... +.Ft int +.Fn vprintf "const char *fmt" "va_list ap" +.In sys/syslog.h +.Ft void +.Fn log "int pri" "const char *fmt" ... +.Ft void +.Fn vlog "int pri" "const char *fmt" "va_list ap" +.Sh DESCRIPTION +The +.Nm +family of functions are similar to the +.Xr printf 3 +family of functions. +The different functions each use a different output stream. +The +.Fn uprintf +function outputs to the current process' controlling tty, while +.Fn printf +writes to the console as well as to the logging facility. +The +.Fn tprintf +function outputs to the tty associated with the process +.Fa p +and the logging facility if +.Fa pri +is not \-1. +The +.Fn log +function sends the message to the kernel logging facility, using +the log level as indicated by +.Fa pri , +and to the console if no process is yet reading the log. +.Pp +Each of these related functions use the +.Fa fmt +parameter in the same manner as +.Xr printf 3 . +However, +.Nm +adds two other conversion specifiers and omits one. +.Pp +The +.Cm \&%b +identifier expects two arguments: an +.Vt int +and a +.Vt "char *" . +These are used as a register value and a print mask for decoding bitmasks. +The print mask is made up of two parts: the base and the +arguments. +The base value is the output base (radix) expressed as an octal value; +for example, \e10 gives octal and \e20 gives hexadecimal. +The arguments are made up of a sequence of bit identifiers. +Each bit identifier begins with a character specifying the number of the bit +(starting from 1) this identifier describes. +The characters from \e01 to \e40 can be used to specify bit numbers in the +range from 1 to 32 and characters from \e200 to \e377 to specify bit numbers +in the range from 1 to 128. +The rest of the identifier is a string of characters containing the name of +the bit. +The identifier is terminated by either the bit number at the start of the next +bit identifier or by +.Dv NUL +for the last bit identifier. +.Pp +The +.Cm \&%D +identifier is meant to assist in hexdumps. +It requires two arguments: a +.Vt "u_char *" +pointer and a +.Vt "char *" +string. +The memory pointed to by the pointer is output in hexadecimal one byte at +a time. +The string is used as a delimiter between individual bytes. +If present, a width directive will specify the number of bytes to display. +By default, 16 bytes of data are output. +.Pp +The +.Cm \&%n +conversion specifier is not supported. +.Pp +The +.Fn log +function uses +.Xr syslog 3 +level values +.Dv LOG_DEBUG +through +.Dv LOG_EMERG +for its +.Fa pri +parameter (mistakenly called +.Sq priority +here). +Alternatively, if a +.Fa pri +of \-1 is given, the message will be appended to the last log message +started by a previous call to +.Fn log . +As these messages are generated by the kernel itself, the facility will +always be +.Dv LOG_KERN . +.Sh RETURN VALUES +The +.Fn printf +and the +.Fn uprintf +functions return the number of characters displayed. +.Sh EXAMPLES +This example demonstrates the use of the +.Cm \&%b +and +.Cm \&%D +conversion specifiers. +The function +.Bd -literal -offset indent +void +printf_test(void) +{ + printf("reg=%b\en", 3, "\e10\e2BITTWO\e1BITONE"); + printf("out: %4D\en", "AAZZ", ":"); +} +.Ed +.Pp +will produce the following output: +.Bd -literal -offset indent +reg=3 +out: 41:41:5a:5a +.Ed +.Pp +The same output will be generated by the following function: +.Bd -literal -offset indent +void +printf_test(void) +{ + printf("reg=%b\en", 3, "\e10\e201BITTWO\e200BITONE"); + printf("out: %4D\en", "AAZZ", ":"); +} +.Ed +.Pp +The call +.Bd -literal -offset indent +log(LOG_DEBUG, "%s%d: been there.\en", sc->sc_name, sc->sc_unit); +.Ed +.Pp +will add the appropriate debug message at priority +.Dq Li kern.debug +to the system log. +.Sh SEE ALSO +.Xr printf 3 , +.Xr syslog 3 diff --git a/static/freebsd/man9/prison_check.9 b/static/freebsd/man9/prison_check.9 new file mode 100644 index 00000000..7f174e3c --- /dev/null +++ b/static/freebsd/man9/prison_check.9 @@ -0,0 +1,59 @@ +.\" +.\" Copyright (c) 2003 Joseph Koshy +.\" +.\" 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 August 18, 2023 +.Dt PRISON_CHECK 9 +.Os +.Sh NAME +.Nm prison_check +.Nd determine if subjects may see entities according to jail restrictions +.Sh SYNOPSIS +.In sys/jail.h +.Ft int +.Fn prison_check "struct ucred *cred1" "struct ucred *cred2" +.Sh DESCRIPTION +This function determines if a subject with credentials +.Fa cred1 +is denied access to subjects or objects with credentials +.Fa cred2 +according to the policy that a subject can see subjects or objects in its own +jail or any sub-jail of it. +.Sh RETURN VALUES +The +.Fn prison_check +function +returns +.Er ESRCH +if +.Fa cred2 +is not in the same jail or a sub-jail of that of +.Fa cred1 . +In all other cases, +.Fn prison_check +returns zero. +.Sh SEE ALSO +.Xr jail 2 diff --git a/static/freebsd/man9/priv.9 b/static/freebsd/man9/priv.9 new file mode 100644 index 00000000..6343940c --- /dev/null +++ b/static/freebsd/man9/priv.9 @@ -0,0 +1,118 @@ +.\"- +.\" Copyright (c) 2006 nCircle Network Security, Inc. +.\" All rights reserved. +.\" +.\" This software was developed by Robert N. M. Watson for the TrustedBSD +.\" Project under contract to nCircle Network Security, Inc. +.\" +.\" 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, NCIRCLE NETWORK SECURITY, +.\" INC., 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 November 12, 2025 +.Dt PRIV 9 +.Os +.Sh NAME +.Nm priv +.Nd kernel privilege checking API +.Sh SYNOPSIS +.In sys/priv.h +.Ft int +.Fn priv_check "struct thread *td" "int priv" +.Ft int +.Fn priv_check_cred "struct ucred *cred" "int priv" +.Sh DESCRIPTION +The +.Nm +interfaces check to see if specific system privileges are granted to the +passed thread, +.Fa td , +or credential, +.Fa cred . +This interface replaces the now removed +.Xr suser 9 +privilege checking interface. +Privileges typically represent rights in one of two categories: the right to +manage a particular component of the system, or an exemption to a specific +policy or access control list. +The caller identifies the desired privilege via the +.Fa priv +argument. +.Ss Privilege Policies +Privileges are typically granted based on one of two base system policies: +the superuser policy, which grants privilege based on the effective (or +sometimes real) UID having a value of 0, and the +.Xr jail 2 +policy, which permits only certain privileges to be granted to processes in a +jail. +The set of available privileges may also be influenced by the TrustedBSD MAC +Framework, described in +.Xr mac 9 . +.Sh IMPLEMENTATION NOTES +When adding a new privilege check to a code path, first check the complete +list of current privileges in +.Pa sys/priv.h +to see if one already exists for the class of privilege required. +Only if there is not an exact match should a new privilege be added to the +privilege list. +As privilege numbers becomes encoded in the kernel module ABI, privilege +constants must not be changed as any kernel modules depending on privileges +will then need to be recompiled. +When adding a new privilege, be certain to also determine whether it should +be listed in +.Fn prison_priv_check , +which includes a complete list of privileges granted to the root user in +.Xr jail 2 . +.Pp +Certain catch-all privileges exist, such as +.Dv PRIV_DRIVER , +intended to be used by device drivers, rather than adding a new +driver-specific privilege. +.Sh RETURN VALUES +Typically, 0 will be returned for success, and +.Er EPERM +will be returned on failure. +Most consumers of +.Nm +will wish to directly return the error code from a failed privilege check to +user space; a small number will wish to translate it to another error code +appropriate to a specific context. +.Pp +When designing new APIs, it is preferable to return explicit errors from a +call if privilege is not granted rather than changing the semantics of the +call but returning success. +For example, the behavior exhibited by +.Xr stat 2 , +in which the generation field is optionally zero'd out when there is +insufficient privilege is highly undesirable, as it results in frequent +privilege checks, and the caller is unable to tell if an access control +failure occurred. +.Sh SEE ALSO +.Xr jail 2 , +.Xr dtrace_priv 4 , +.Xr mac 9 , +.Xr ucred 9 +.Sh AUTHORS +The +.Nm +API and implementation were created by +.An Robert Watson +under contract to +nCircle Network Security, Inc. diff --git a/static/freebsd/man9/prng.9 b/static/freebsd/man9/prng.9 new file mode 100644 index 00000000..9fcc6f1e --- /dev/null +++ b/static/freebsd/man9/prng.9 @@ -0,0 +1,96 @@ +.\"- +.\" Copyright 2020 Conrad Meyer . 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 August 5, 2020 +.Dt PRNG 9 +.Os +.Sh NAME +.Nm prng +.Nd "Kernel pseudo-random number generators" +.Sh SYNOPSIS +.In sys/prng.h +.Ft uint32_t +.Fn prng32 void +.Ft uint32_t +.Fn prng32_bounded "uint32_t bound" +.Ft uint64_t +.Fn prng64 void +.Ft uint64_t +.Fn prng64_bounded "uint64_t bound" +.Sh DESCRIPTION +.Ss GENERIC PRNG ROUTINES +.Nm +is a family of fast, +.Em non-cryptographic +pseudo-random number generators. +Unlike +.Xr random 9 , +.Fn prng32 , +.Fn prng32_bounded , +.Fn prng64 , +and +.Fn prng64_bounded +avoid shared global state, removing unnecessary contention on SMP +systems. +The routines are not explicitly tied to any specific implementation, and +may produce different specific sequences on different hosts, reboots, or +versions of +.Fx . +Different CPUs in SMP systems are guaranteed to produce different sequences of +integers. +.Pp +For +.Em cryptographically secure +random numbers generated by the +.Xr random 4 +kernel cryptographically secure random number generator subsystem, see +.Xr arc4random 9 . +.Bl -tag -width indent +.It Fn prng32 +Generate a 32-bit integer uniformly distributed in [0, 2^32-1]. +.It Fn prng32_bounded bound +Generate an integer uniformly in the range [0, bound-1]. +.It Fn prng64 +Generate a 64-bit integer uniformly distributed in [0, 2^64-1]. +.It Fn prng64_bounded bound +Generate an integer uniformly in the range [0, bound-1]. +.El +.Pp +These routines are not reentrant; they are not safe to use in interrupt +handlers ("interrupt filters" in +.Xr bus_setup_intr 9 +terminology). +They are safe to use in all other kernel contexts, including interrupt threads +("ithreads"). +.Ss REPRODUCIBLE PRNG APIS +In addition to these per-CPU helpers, the +.In sys/prng.h +header also exposes the entire API of the PCG family of PRNGs as inline +functions. +The PCG-C API is described in full at +.Lk https://www.pcg-random.org/using-pcg-c.html . +.Sh HISTORY +.Nm +was introduced in +.Fx 13 . diff --git a/static/freebsd/man9/proc_rwmem.9 b/static/freebsd/man9/proc_rwmem.9 new file mode 100644 index 00000000..fb595026 --- /dev/null +++ b/static/freebsd/man9/proc_rwmem.9 @@ -0,0 +1,102 @@ +.\" +.\" Copyright (c) 2015 Mark Johnston +.\" +.\" 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 7, 2015 +.Dt PROC_RWMEM 9 +.Os +.Sh NAME +.Nm proc_rwmem , +.Nm proc_readmem , +.Nm proc_writemem +.Nd read from or write to a process address space +.Sh SYNOPSIS +.In sys/types.h +.In sys/ptrace.h +.Ft int +.Fn proc_rwmem "struct proc *p" "struct uio *uio" +.Ft ssize_t +.Fn proc_readmem "struct thread *td" "struct proc *p" "vm_offset_t va" "void *buf" "size_t len" +.Ft ssize_t +.Fn proc_writemem "struct thread *td" "struct proc *p" "vm_offset_t va" "void *buf" "size_t len" +.Sh DESCRIPTION +These functions are used to read to or write from the address space of the +process +.Fa p . +The +.Fn proc_rwmem +function requires the caller to specify the I/O parameters using a +.Vt "struct uio" , +described in +.Xr uio 9 . +The +.Fn proc_readmem +and +.Fn proc_writemem +functions provide a simpler, less general interface which allows the caller to +read into or write the kernel buffer +.Fa buf +of size +.Fa len +from or to the memory at offset +.Fa va +in the address space of +.Fa p . +The operation is performed on behalf of thread +.Fa td , +which will most often be the current thread. +.Pp +These functions may sleep and thus may not be called with any non-sleepable +locks held. +The process +.Fa p +must be held by the caller using +.Xr PHOLD 9 . +.Sh RETURN VALUES +The +.Fn proc_rwmem +function returns +.Dv 0 +on success. +.Dv EFAULT +is returned if the specified user address is invalid, and +.Dv ENOMEM +is returned if the target pages could not be faulted in due to a resource +shortage. +.Pp +The +.Fn proc_readmem +and +.Fn proc_writemem +functions return the number of bytes read or written, respectively. +This may be smaller than the number of bytes requested, for example if the +request spans multiple pages in the process address space and one of them after +the first is not mapped. +Otherwise, -1 is returned. +.Sh SEE ALSO +.Xr copyin 9 , +.Xr locking 9 , +.Xr PHOLD 9 , +.Xr uio 9 +.Sh AUTHORS +This manual page was written by +.An Mark Johnston Aq Mt markj@FreeBSD.org . diff --git a/static/freebsd/man9/pseudofs.9 b/static/freebsd/man9/pseudofs.9 new file mode 100644 index 00000000..d87bbb00 --- /dev/null +++ b/static/freebsd/man9/pseudofs.9 @@ -0,0 +1,68 @@ +.\"- +.\" Copyright (c) 2001 Dag-Erling Smørgrav +.\" 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 April 20, 2007 +.Dt PSEUDOFS 9 +.Os +.Sh NAME +.Nm pseudofs +.Nd pseudo file system construction kit +.Sh SYNOPSIS +.In fs/pseudofs/pseudofs.h +.\" Insert usage example here +.Sh DESCRIPTION +The +.Nm +module offers an abstract API for pseudo-file systems such as +.Xr procfs 4 +and +.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. +The consumer module, i.e., the module that implements the actual guts +of the file system, needs only provide the directory structure +(represented by a collection of structures declared and initialized by +macros provided by +.Nm ) +and callbacks that report file attributes or write the actual file +contents into sbufs. +.\" Insert more info here +.Sh SEE ALSO +.Xr linprocfs 4 , +.Xr linsysfs 4 , +.Xr procfs 4 , +.Xr sbuf 9 , +.Xr vnode 9 +.Sh HISTORY +The +.Nm +module appeared in +.Fx 5.0 . +.Sh AUTHORS +The +.Nm +module and this manual page were written by +.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . diff --git a/static/freebsd/man9/psignal.9 b/static/freebsd/man9/psignal.9 new file mode 100644 index 00000000..2d57673d --- /dev/null +++ b/static/freebsd/man9/psignal.9 @@ -0,0 +1,143 @@ +.\" Copyright (c) 1996 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Paul Kranenburg. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 REGENTS 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. +.\" +.\" $NetBSD: psignal.9,v 1.1 1996/06/22 22:57:35 pk Exp $ +.\" +.Dd July 14, 2023 +.Dt PSIGNAL 9 +.Os +.Sh NAME +.Nm psignal , +.Nm kern_psignal , +.Nm pgsignal , +.Nm tdsignal +.Nd post signal to a thread, process, or process group +.Sh SYNOPSIS +.In sys/types.h +.In sys/signalvar.h +.Ft void +.Fn kern_psignal "struct proc *p" "int signum" +.Ft void +.Fn pgsignal "struct pgrp *pgrp" "int signum" "int checkctty" +.Ft void +.Fn tdsignal "struct thread *td" "int signum" +.Sh DESCRIPTION +These functions post a signal to a thread or one or more processes. +The argument +.Fa signum +common to all three functions should be in the range +.Bq 1- Ns Dv NSIG . +.Pp +The +.Fn kern_psignal +function posts signal number +.Fa signum +to the process represented by the process structure +.Fa p . +The +.Fn kern_psignal +function used to be called +.Fn psignal +but was renamed in order to eliminate a name collision with the libc +function of that name and facilitate code reuse. +With a few exceptions noted below, the target process signal disposition is +updated and is marked as runnable, so further handling of the signal is done +in the context of the target process after a context switch. +Note that +.Fn kern_psignal +does not by itself cause a context switch to happen. +.Pp +The target process is not marked as runnable in the following cases: +.Bl -bullet -offset indent +.It +The target process is sleeping uninterruptibly. +The signal will be +noticed when the process returns from the system call or trap. +.It +The target process is currently ignoring the signal. +.It +If a stop signal is sent to a sleeping process that takes the +default action +(see +.Xr sigaction 2 ) , +the process is stopped without awakening it. +.It +.Dv SIGCONT +restarts a stopped process +(or puts them back to sleep) +regardless of the signal action +(e.g., blocked or ignored). +.El +.Pp +If the target process is being traced +.Fn kern_psignal +behaves as if the target process were taking the default action for +.Fa signum . +This allows the tracing process to be notified of the signal. +.Pp +The +.Fn pgsignal +function posts signal number +.Fa signum +to each member of the process group described by +.Fa pgrp . +If +.Fa checkctty +is non-zero, the signal will be posted only to processes that have +a controlling terminal. +.Fn pgsignal +is implemented by walking along the process list headed by the field +.Li pg_members +of the process group structure +pointed at by +.Fa pgrp +and calling +.Fn kern_psignal +as appropriate. +If +.Fa pgrp +is +.Dv NULL +no action is taken. +.Pp +The +.Fn tdsignal +function posts signal number +.Fa signum +to the thread represented by the thread structure +.Fa td . +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr signal 9 , +.Xr tsleep 9 +.Sh HISTORY +The +.Fn psignal +function was renamed to +.Fn kern_psignal +in +.Fx 9.0 . diff --git a/static/freebsd/man9/pwmbus.9 b/static/freebsd/man9/pwmbus.9 new file mode 100644 index 00000000..1cd10d6f --- /dev/null +++ b/static/freebsd/man9/pwmbus.9 @@ -0,0 +1,111 @@ +.\" Copyright (c) 2018 Emmanuel Vadot +.\" +.\" 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 March 9, 2021 +.Dt PWMBUS 9 +.Os +.Sh NAME +.Nm pwmbus , +.Nm PWMBUS_CHANNEL_CONFIG , +.Nm PWMBUS_CHANNEL_COUNT , +.Nm PWMBUS_CHANNEL_ENABLE , +.Nm PWMBUS_CHANNEL_GET_CONFIG , +.Nm PWMBUS_CHANNEL_GET_FLAGS , +.Nm PWMBUS_CHANNEL_IS_ENABLED , +.Nm PWMBUS_CHANNEL_SET_FLAGS , +.Nm PWMBUS_GET_BUS +.Nd PWMBUS methods +.Sh SYNOPSIS +.Cd "device pwm" +.In "pwmbus_if.h" +.Ft int +.Fn PWMBUS_CHANNEL_CONFIG "device_t bus" "u_int channel" "u_int period" "u_int duty" +.Ft int +.Fn PWMBUS_CHANNEL_COUNT "device_t bus" "u_int *nchannel" +.Ft int +.Fn PWMBUS_CHANNEL_ENABLE "device_t bus" "u_int channel" "bool enable" +.Ft int +.Fn PWMBUS_CHANNEL_GET_CONFIG "device_t bus" "u_int channel" "u_int *period" "u_int *duty" +.Ft int +.Fn PWMBUS_CHANNEL_GET_FLAGS "device_t bus" "u_int channel" "uint32_t *flags" +.Ft int +.Fn PWMBUS_CHANNEL_IS_ENABLED "device_t bus" "u_int channel" "bool *enabled" +.Ft int +.Fn PWMBUS_CHANNEL_SET_FLAGS "device_t bus" "u_int channel" "uint32_t flags" +.Sh DESCRIPTION +The PWMBUS (Pulse-Width Modulation) interface allows a device driver to +register to a global bus so other devices in the kernel can use them in a +generic way. +.Pp +For all +.Nm +methods, the +.Va period +argument is the duration in nanoseconds of one complete on-off cycle, and the +.Va duty +argument is the duration in nanoseconds of the on portion of that cycle. +.Pp +Some PWM hardware is organized as a single controller with multiple channels. +Channel numbers count up from zero. +When multiple channels are present, they sometimes share a common clock or +other resources. +In such cases, changing the period or duty cycle of any one channel may affect +other channels within the hardware which share the same resources. +Consult the documentation for the underlying PWM hardware device driver for +details on channels that share resources. +.Sh INTERFACE +.Bl -tag -width indent +.It Fn PWMBUS_CHANNEL_CONFIG "device_t bus" "u_int channel" "u_int period" "u_int duty" +Configure the period and duty (in nanoseconds) in the PWM controller on the bus +for the specified channel. +Returns 0 on success or +.Er EINVAL +if the values are not supported by the controller or +.Er EBUSY +if the PWMBUS controller is in use and does not support changing the value on +the fly. +.It Fn PWMBUS_CHANNEL_COUNT "device_t bus" "u_int *nchannel" +Get the number of channels supported by the controller. +.It Fn PWMBUS_CHANNEL_ENABLE "device_t bus" "u_int channel" "bool enable" +Enable the PWM channel. +.It Fn PWMBUS_CHANNEL_GET_CONFIG "device_t bus" "u_int channel" "u_int *period" "u_int *duty" +Get the current configuration of the period and duty for the specified channel. +.It Fn PWMBUS_CHANNEL_GET_FLAGS "device_t bus" "u_int channel" "uint32_t *flags" +Get the current flags for the channel. +If the driver or controller +does not support this, a default method returns a flags value of zero. +.It Fn PWMBUS_CHANNEL_IS_ENABLED "device_t bus" "u_int channel" "bool *enable" +Test whether the PWM channel is enabled. +.It Fn PWMBUS_CHANNEL_SET_FLAGS "device_t bus" "u_int channel" "uint32_t flags" +Set the flags of the channel (such as inverted polarity). +If the driver or controller does not support this a do-nothing default method +is used. +.El +.Sh HISTORY +The +.Nm pwmbus +interface first appear in +.Fx 13.0 . +The +.Nm pwmbus +interface and manual page was written by +.An Emmanuel Vadot Aq Mt manu@FreeBSD.org . diff --git a/static/freebsd/man9/random.9 b/static/freebsd/man9/random.9 new file mode 100644 index 00000000..f1833c63 --- /dev/null +++ b/static/freebsd/man9/random.9 @@ -0,0 +1,203 @@ +.\" +.\" Copyright (c) 2015 +.\" Mark R V Murray +.\" Copyright (c) 2000 +.\" The Regents of the University of California. 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 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 May 11, 2025 +.Dt RANDOM 9 +.Os +.Sh NAME +.Nm arc4rand , +.Nm arc4random , +.Nm arc4random_buf , +.Nm is_random_seeded , +.Nm random , +.Nm read_random , +.Nm read_random_uio +.Nd supply pseudo-random numbers +.Sh SYNOPSIS +.In sys/libkern.h +.Ft uint32_t +.Fn arc4random "void" +.Ft void +.Fn arc4random_buf "void *ptr" "size_t len" +.Ft void +.Fn arc4rand "void *ptr" "u_int length" "int reseed" +.Pp +.In sys/random.h +.Ft bool +.Fn is_random_seeded "void" +.Ft void +.Fn read_random "void *buffer" "int count" +.Ft int +.Fn read_random_uio "struct uio *uio" "bool nonblock" +.Ss LEGACY ROUTINES +.In sys/libkern.h +.Ft u_long +.Fn random "void" +.Sh DESCRIPTION +The +.Fn arc4random +and +.Fn arc4random_buf +functions will return very good quality random numbers, suited for +security-related purposes. +Both are wrappers around the underlying +.Fn arc4rand +interface. +.Fn arc4random +returns a 32-bit random value, while +.Fn arc4random_buf +fills +.Fa ptr +with +.Fa len +bytes of random data. +.Pp +The +.Fn arc4rand +CSPRNG +is seeded from the +.Xr random 4 +kernel abstract entropy device. +Automatic reseeding happens at unspecified time and bytes (of output) +intervals. +A reseed can be forced by passing a non-zero +.Fa reseed +value. +.Pp +The +.Fn read_random +function is used to read entropy directly from the kernel abstract entropy +device. +.Fn read_random +blocks if and until the entropy device is seeded. +The provided +.Fa buffer +is filled with no more than +.Fa count +bytes. +It is strongly advised that +.Fn read_random +is not used directly; +instead, use the +.Fn arc4rand +family of functions. +.Pp +The +.Fn is_random_seeded +function can be used to check in advance if +.Fn read_random +will block. +(If random is seeded, it will not block.) +.Pp +The +.Fn read_random_uio +function behaves identically to +.Xr read 2 +on +.Pa /dev/random . +The +.Fa uio +argument points to a buffer where random data should be stored. +If +.Fa nonblock +is true and the random device is not seeded, this function does not return any +data. +Otherwise, this function may block interruptibly until the random device is seeded. +If the function is interrupted before the random device is seeded, no data is +returned. +.Pp +The deprecated +.Fn random +function will return a 31-bit value. +It is obsolete and scheduled to be removed in +.Fx 16.0 . +Consider +.Xr prng 9 +instead and see +.Sx SECURITY CONSIDERATIONS . +.Sh RETURN VALUES +The +.Fn arc4rand +function uses the Chacha20 algorithm to generate a pseudo-random sequence of +bytes. +The +.Fn arc4random +function uses +.Fn arc4rand +to generate pseudo-random numbers +in the range from 0 to +.if t 2\u\s732\s10\d\(mi1. +.if n (2**32)\(mi1. +.Pp +The +.Fn read_random +function returns +the number of bytes placed in +.Fa buffer . +.Pp +.Fn read_random_uio +returns zero when successful, +otherwise an error code is returned. +.Pp +.Fn random +returns numbers +in the range from 0 to +.if t 2\u\s731\s10\d\(mi1. +.if n (2**31)\(mi1. + +.Sh ERRORS +.Fn read_random_uio +may fail if: +.Bl -tag -width Er +.It Bq Er EFAULT +.Fa uio +points to an invalid memory region. +.It Bq Er EWOULDBLOCK +The random device is unseeded and +.Fa nonblock +is true. +.El +.Sh AUTHORS +.An Dan Moschuk +wrote +.Fn arc4random . +.An Mark R V Murray +wrote +.Fn read_random . +.Sh SECURITY CONSIDERATIONS +Do not use +.Fn random +in new code. +.Pp +It is important to remember that the +.Fn random +function is entirely predictable. +It is easy for attackers to predict future output of +.Fn random +by recording some generated values. +We cannot emphasize strongly enough that +.Fn random +must not be used to generate values that are intended to be unpredictable. diff --git a/static/freebsd/man9/random_harvest.9 b/static/freebsd/man9/random_harvest.9 new file mode 100644 index 00000000..0f98d77b --- /dev/null +++ b/static/freebsd/man9/random_harvest.9 @@ -0,0 +1,130 @@ +.\" +.\" Copyright (c) 2002-2015 Mark R V Murray +.\" 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 ``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 August 26, 2018 +.Dt RANDOM_HARVEST 9 +.Os +.Sh NAME +.Nm random_harvest +.Nd gather entropy from the kernel for the entropy device +.Sh SYNOPSIS +.In sys/types.h +.In sys/random.h +.Ft void +.Fo random_harvest_direct +.Fa "void *entropy" +.Fa "u_int size" +.Fa "enum esource source" +.Fc +.Ft void +.Fo random_harvest_fast +.Fa "void *entropy" +.Fa "u_int size" +.Fa "enum esource source" +.Fc +.Ft void +.Fo random_harvest_queue +.Fa "void *entropy" +.Fa "u_int size" +.Fa "enum esource source" +.Fc +.Sh DESCRIPTION +The +.Fn random_harvest_* +functions are used by device drivers +and other kernel processes to pass data +that is considered (at least partially) stochastic +to the entropy device. +.Pp +The caller should pass +a pointer pointing to the +.Dq random +data in +.Fa entropy . +The argument +.Fa size +contains the number of bytes pointed to. +The +.Fa source +is chosen from one of +the values enumerated in +.Pa sys/dev/random.h . +and is used to indicate the source of the entropy. +.Pp +The +.Fo random_harvest_direct +.Fc +variant is used +for early harvesting +before any multitasking +is enabled. +.Pp +The +.Fn random_harvest_fast +variant is used +by sources that +should not take +a performance hit +from harvesting, +as they are high-rate +sources. +Some entropy is sacrificed, +but the high rate of supply +will compensate for this. +.Pp +The +.Fn random_harvest_queue +variant is used +for general harvesting +and is the default +choice for most entropy sources +such as interrupts +or console events. +.Pp +Interrupt harvesting has been +in part simplified +for the kernel programmer. +If a device driver registers an interrupt handler +with +.Xr BUS_SETUP_INTR 9 +or +.Xr bus_setup_intr 9 , +then it is only necessary to +include the +.Dv INTR_ENTROPY +bit in the +.Fa flags +argument to have that interrupt source +be used for entropy harvesting. +This should be done wherever practicable. +.Sh SEE ALSO +.Xr random 4 , +.Xr BUS_SETUP_INTR 9 +.Sh AUTHORS +The +.Fx +.Xr random 4 +entropy device and supporting documentation was written by +.An Mark R V Murray . diff --git a/static/freebsd/man9/ratecheck.9 b/static/freebsd/man9/ratecheck.9 new file mode 100644 index 00000000..71f19839 --- /dev/null +++ b/static/freebsd/man9/ratecheck.9 @@ -0,0 +1,91 @@ +.\"- +.\" Copyright (c) 2017 Dag-Erling Smørgrav +.\" 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 March 11, 2022 +.Dt RATECHECK 9 +.Os +.Sh NAME +.Nm ratecheck , +.Nm ppsratecheck +.Nd "event rate limiting" +.Sh SYNOPSIS +.In sys/time.h +.Ft int +.Fn ratecheck "struct timeval *lasttime" "const struct timeval *mininterval" +.Ft int +.Fn ppsratecheck "struct timeval *lasttime" "int *curpps" "int maxpps" +.Sh DESCRIPTION +The +.Nm ratecheck +and +.Nm ppsratecheck +functions facilitate rate-limiting of arbitrary events. +The former enforces a minimum interval between events while the latter +enforces a maximum number of events per second. +.Pp +The +.Nm ratecheck +function compares the current time to the value pointed to by +.Fa lasttime . +If the difference is equal to or greater than +.Fa mininterval , +it returns a non-zero value and updates +.Fa lasttime +to the current time. +Otherwise, it returns zero. +.Pp +The +.Nm ppsratecheck +function first compares the current time +to +.Fa lasttime . +If at least a full second has passed, the value pointed to by the +.Fa curpps +argument is reset to 1 and +.Fa lasttime +is updated to the current time. +Otherwise, +.Fa curpps +is incremented and +.Fa lasttime +is left untouched. +In either case, +.Nm ppsratecheck +returns a non-zero value if and only if the updated +.Fa curpps +is less than or equal to +.Fa maxpps +or +.Fa maxpps +is negative. +.Sh SEE ALSO +.Xr counter 9 +.Sh HISTORY +The +.Nm ratecheck +and +.Nm ppsratecheck +functions first appeared in +.Fx 5.1 . diff --git a/static/freebsd/man9/redzone.9 b/static/freebsd/man9/redzone.9 new file mode 100644 index 00000000..f9a5cef6 --- /dev/null +++ b/static/freebsd/man9/redzone.9 @@ -0,0 +1,123 @@ +.\" Copyright (c) 2006 Pawel Jakub Dawidek +.\" 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 AUTHORS 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 AUTHORS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 9, 2009 +.Dt REDZONE 9 +.Os +.Sh NAME +.Nm RedZone +.Nd "buffer corruptions detector" +.Sh SYNOPSIS +.Cd "options KDB" +.Cd "options DDB" +.Cd "options DEBUG_REDZONE" +.Sh DESCRIPTION +.Nm +detects buffer underflow and buffer overflow bugs at runtime. +Currently +.Nm +only detects buffer corruptions for memory allocated with +.Xr malloc 9 . +When such corruption is detected two backtraces are printed on the console. +The first one shows from where memory was allocated, the second one shows from +where memory was freed. +By default the system will not panic when buffer corruption is detected. +This can be changed by setting the +.Va vm.redzone.panic +.Xr sysctl 8 +variable to 1. +The amount of extra memory allocated for +.Nm Ns 's +needs is stored in the +.Va vm.redzone.extra_mem +.Xr sysctl 8 +variable. +.Sh EXAMPLE +The example below shows the logs from the detection of a buffer underflow and a +buffer overflow. +.Bd -literal -offset indent +REDZONE: Buffer underflow detected. 2 bytes corrupted before 0xc8688580 (16 bytes allocated). +Allocation backtrace: +#0 0xc0583e4e at redzone_setup+0x3c +#1 0xc04a23fa at malloc+0x19e +#2 0xcdeb69ca at redzone_modevent+0x60 +#3 0xc04a3f3c at module_register_init+0x82 +#4 0xc049d96a at linker_file_sysinit+0x8e +#5 0xc049dc7c at linker_load_file+0xed +#6 0xc04a041f at linker_load_module+0xc4 +#7 0xc049e883 at kldload+0x116 +#8 0xc05d9b3d at syscall+0x325 +#9 0xc05c944f at Xint0x80_syscall+0x1f +Free backtrace: +#0 0xc0583f92 at redzone_check+0xd4 +#1 0xc04a2422 at free+0x1c +#2 0xcdeb69a6 at redzone_modevent+0x3c +#3 0xc04a438d at module_unload+0x61 +#4 0xc049e0b3 at linker_file_unload+0x89 +#5 0xc049e979 at kern_kldunload+0x96 +#6 0xc049ea00 at kldunloadf+0x2c +#7 0xc05d9b3d at syscall+0x325 +#8 0xc05c944f at Xint0x80_syscall+0x1f + +REDZONE: Buffer overflow detected. 4 bytes corrupted after 0xc8688590 (16 bytes allocated). +Allocation backtrace: +#0 0xc0583e4e at redzone_setup+0x3c +#1 0xc04a23fa at malloc+0x19e +#2 0xcdeb69ca at redzone_modevent+0x60 +#3 0xc04a3f3c at module_register_init+0x82 +#4 0xc049d96a at linker_file_sysinit+0x8e +#5 0xc049dc7c at linker_load_file+0xed +#6 0xc04a041f at linker_load_module+0xc4 +#7 0xc049e883 at kldload+0x116 +#8 0xc05d9b3d at syscall+0x325 +#9 0xc05c944f at Xint0x80_syscall+0x1f +Free backtrace: +#0 0xc0584020 at redzone_check+0x162 +#1 0xc04a2422 at free+0x1c +#2 0xcdeb69a6 at redzone_modevent+0x3c +#3 0xc04a438d at module_unload+0x61 +#4 0xc049e0b3 at linker_file_unload+0x89 +#5 0xc049e979 at kern_kldunload+0x96 +#6 0xc049ea00 at kldunloadf+0x2c +#7 0xc05d9b3d at syscall+0x325 +#8 0xc05c944f at Xint0x80_syscall+0x1f +.Ed +.Sh SEE ALSO +.Xr sysctl 8 , +.Xr malloc 9 , +.Xr memguard 9 +.Sh HISTORY +.Nm +first appeared in +.Fx 7.0 . +.Sh AUTHORS +.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org +.Sh BUGS +Currently, +.Nm +does not cooperate with +.Xr memguard 9 . +Allocations from a memory type controlled by +.Xr memguard 9 +are simply skipped, so buffer corruptions will not be detected there. diff --git a/static/freebsd/man9/refcount.9 b/static/freebsd/man9/refcount.9 new file mode 100644 index 00000000..7375f429 --- /dev/null +++ b/static/freebsd/man9/refcount.9 @@ -0,0 +1,194 @@ +.\" +.\" Copyright (c) 2009 Hudson River Trading LLC +.\" Written by: John H. Baldwin +.\" All rights reserved. +.\" +.\" Copyright (c) 2019 The FreeBSD Foundation +.\" +.\" Parts of this documentation was written by +.\" Konstantin Belousov under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" 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 October 12, 2022 +.Dt REFCOUNT 9 +.Os +.Sh NAME +.Nm refcount , +.Nm refcount_init , +.Nm refcount_acquire , +.Nm refcount_release +.Nd manage a simple reference counter +.Sh SYNOPSIS +.In sys/param.h +.In sys/refcount.h +.Ft void +.Fn refcount_init "volatile u_int *count" "u_int value" +.Ft u_int +.Fn refcount_load "volatile u_int *count" +.Ft u_int +.Fn refcount_acquire "volatile u_int *count" +.Ft bool +.Fn refcount_acquire_checked "volatile u_int *count" +.Ft bool +.Fn refcount_acquire_if_not_zero "volatile u_int *count" +.Ft bool +.Fn refcount_release "volatile u_int *count" +.Ft bool +.Fn refcount_release_if_last "volatile u_int *count" +.Ft bool +.Fn refcount_release_if_not_last "volatile u_int *count" +.Sh DESCRIPTION +The +.Nm +functions provide an API to manage a simple reference counter. +The caller provides the storage for the counter in an unsigned integer. +A pointer to this integer is passed via +.Fa count . +Usually the counter is used to manage the lifetime of an object and is +stored as a member of the object. +.Pp +Currently all functions are implemented as static inline. +.Pp +The +.Fn refcount_init +function is used to set the initial value of the counter to +.Fa value . +It is normally used when creating a reference-counted object. +.Pp +The +.Fn refcount_load +function returns a snapshot of the counter value. +This value may immediately become out-of-date in the absence of external +synchronization. +.Fn refcount_load +should be used instead of relying on the properties of the +.Vt volatile +qualifier. +.Pp +The +.Fn refcount_acquire +function is used to acquire a new reference. +It returns the counter value before the new reference was acquired. +The caller is responsible for ensuring that it holds a valid reference +while obtaining a new reference. +For example, +if an object is stored on a list and the list holds a reference on the +object, then holding a lock that protects the list provides sufficient +protection for acquiring a new reference. +.Pp +The +.Fn refcount_acquire_checked +variant performs the same operation as +.Fn refcount_acquire , +but additionally checks that the +.Fa count +value does not overflow as result of the operation. +It returns +.Dv true +if the reference was successfully obtained, and +.Dv false +if it was not, due to the overflow. +.Pp +The +.Fn refcount_acquire_if_not_zero +function is yet another variant of +.Fn refcount_acquire , +which only obtains the reference when some reference already exists. +In other words, +.Fa *count +must be already greater than zero for the function to succeed, in which +case the return value is +.Dv true , +otherwise +.Dv false +is returned. +.Pp +The +.Fn refcount_release +function is used to release an existing reference. +The function returns true if the reference being released was +the last reference; +otherwise, it returns false. +.Pp +The +.Fn refcount_release_if_last +and +.Fn refcount_release_if_not_last +functions are variants of +.Fn refcount_release +which only drop the reference when it is or is not the last reference, +respectively. +In other words, +.Fn refcount_release_if_last +returns +.Dv true +when +.Fa *count +is equal to one, in which case it is decremented to zero. +Otherwise, +.Fa *count +is not modified and the function returns +.Dv false . +Similarly, +.Fn refcount_release_if_not_last +returns +.Dv true +when +.Fa *count +is greater than one, in which case +.Fa *count +is decremented. +Otherwise, if +.Fa *count +is equal to one, the reference is not released and the function returns +.Dv false . +.Pp +Note that these routines do not provide any inter-CPU synchronization or +data protection for managing the counter. +The caller is responsible for any additional synchronization needed by +consumers of any containing objects. +In addition, +the caller is also responsible for managing the life cycle of any containing +objects including explicitly releasing any resources when the last reference +is released. +.Pp +The +.Fn refcount_release +unconditionally executes a release fence (see +.Xr atomic 9 ) before releasing the reference, which +synchronizes with an acquire fence executed right before +returning the +.Dv true +value. +This ensures that the destructor, supposedly executed by the caller after +the last reference was dropped, sees all updates done during the lifetime +of the object. +.Sh RETURN VALUES +The +.Nm refcount_release +function returns true when releasing the last reference and false when +releasing any other reference. +.Sh HISTORY +These functions were introduced in +.Fx 6.0 . diff --git a/static/freebsd/man9/regulator.9 b/static/freebsd/man9/regulator.9 new file mode 100644 index 00000000..52e24c18 --- /dev/null +++ b/static/freebsd/man9/regulator.9 @@ -0,0 +1,147 @@ +.\" Copyright (c) 2021 Emmanuel Vadot +.\" +.\" 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 June 14, 2021 +.Dt REGULATOR 9 +.Os +.Sh NAME +.Nm regulator , +.Nm regulator_get_by_name , +.Nm regulator_get_by_id , +.Nm regulator_release , +.Nm regulator_get_name , +.Nm regulator_enable , +.Nm regulator_disable , +.Nm regulator_stop , +.Nm regulator_status , +.Nm regulator_get_voltage , +.Nm regulator_set_voltage , +.Nm regulator_check_voltage , +.Nm regulator_get_by_ofw_property +.Nd regulator methods +.Sh SYNOPSIS +.Cd "device regulator" +.In "dev/extres/regulator/regulator.h" +.Ft int +.Fn regulator_get_by_name "device_t cdev" "const char *name" "regulator_t *regulator" +.Ft int +.Fn regulator_get_by_id "device_t cdev" "device_t pdev" "intptr_t id" "regulator_t *regulator" +.Ft int +.Fn regulator_release "regulator_t regulator" +.Ft int +.Fn regulator_get_name "regulator_t regulator" +.Ft int +.Fn regulator_enable "regulator_t reg" +.Ft int +.Fn regulator_disable "regulator_t reg" +.Ft int +.Fn regulator_stop "regulator_t reg" +.Ft int +.Fn regulator_status "regulator_t reg" "int *status" +.Ft int +.Fn regulator_get_voltage "regulator_t reg" "int *uvolt" +.Ft int +.Fn regulator_set_voltage "regulator_t reg" "int min_uvolt" "int max_uvolt" +.Ft int +.Fn regulator_check_voltage "regulator_t reg" "int uvolt" +.Ft int +.Fn regulator_get_by_ofw_property "device_t dev" "phandle_t node" "char *name" "regulator_t *reg" +.Sh DESCRIPTION +The regulator framework allow drivers to enable, disable and change regulator voltage. +.Sh RETURN VALUES +All functions returns 0 on success or +.Er ENODEV +if the regulator or one of its parent was not found. +.Sh INTERFACE +.Bl -tag -width indent +.It Fn regulator_get_by_name "device_t cdev" "const char *name" "regulator_t *regulator" +Resolve a regulator based on its name. +All regulators names are unique. +This will also increment the refcount on the regulator. +.It Fn regulator_get_by_id "device_t cdev" "device_t pdev" "intptr_t id" "regulator_t *regulator" +Resolve a regulator based on its id. +All regulators ids are unique. +This will also increment the refcount on the regulator. +.It Fn regulator_get_by_ofw_property "device_t dev" "phandle_t node" "char *name" "regulator_t *reg" +Resolve a regulator based on the fdt property named name. +If node is 0 then the function will get the ofw node itself. +This will also increment the refcount on the regulator. +Returns 0 on success or +.Er ENOENT +if the ofw property does not exists. +.It Fn regulator_release "regulator_t regulator" +This disables the regulator, decrements the refcount on it and frees the regulator variable passed. +.It Fn regulator_get_name "regulator_t regulator" +Returns the name of the regulator. +All regulator names are unique. +.It Fn regulator_enable "regulator_t reg" +Enable the regulator. +If the regulator supports a voltage range, the one configured in the hardware will be the output voltage. +If the regulator was already enabled by another driver this simply increments the enable counter. +.It Fn regulator_disable "regulator_t reg" +Disable the regulator. +If the regulator was also enabled by another driver this simply decrements the enable counter. +If the regulator was not previously enabled we will kassert. +.It Fn regulator_stop "regulator_t reg" +Disable the regulator in hardware. +This ensures the regulator is disabled even if it was enabled by bootloader. +This should not be called on regulator that has previously been enabled by a driver. +Returns 0 on success or +.Er EBUSY +if another consumer enabled it. +.It Fn regulator_status "regulator_t reg" "int *status" +Get the hardware status of the regulator. +status will contain a bit mask with +thoses possible value : +.Bl -tag -width indent +.It REGULATOR_STATUS_ENABLED +The regulator is enabled. +.It REGULATOR_STATUS_OVERCURRENT +The hardware reports that too much current is being drawn. +.El +.It Fn regulator_get_voltage "regulator_t reg" "int *uvolt" +Get the current voltage set for the regulator in microvolts. +.It Fn regulator_set_voltage "regulator_t reg" "int min_uvolt" "int max_uvolt" +Change the voltage for the regulator. +If a range is acceptable by the hardware or driver different values can be provided as min and max. +Returns 0 on success or +.Er ERANGE +if the regulator doesn't support this voltage range. +.It Fn regulator_check_voltage "regulator_t reg" "int uvolt" +Checks if the regulator support the given voltage. +Returns 0 on success or +.Er ERANGE +if the regulator doesn't support this voltage range. +.El +.Sh HISTORY +The +.Nm regulator +framework first appear in +.Fx 12.0 . +The +.Nm regulator +framework was written by +.An Michal Meloun Aq Mt mmel@FreeBSD.org . +The +.Nm regulator +manual page was written by +.An Emmanuel Vadot Aq Mt manu@FreeBSD.org . diff --git a/static/freebsd/man9/resettodr.9 b/static/freebsd/man9/resettodr.9 new file mode 100644 index 00000000..a697500b --- /dev/null +++ b/static/freebsd/man9/resettodr.9 @@ -0,0 +1,60 @@ +.\" $NetBSD: resettodr.9,v 1.1 1995/11/25 21:24:51 perry Exp $ +.\" +.\" Copyright (c) 1994 Christopher G. Demetriou +.\" 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 Christopher G. Demetriou +.\" for the NetBSD Project. +.\" 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 November 13, 1995 +.Dt RESETTODR 9 +.Os +.Sh NAME +.Nm resettodr +.Nd set battery-backed clock from system time +.Sh SYNOPSIS +.In sys/types.h +.In sys/systm.h +.Ft void +.Fn resettodr "void" +.Sh DESCRIPTION +The +.Fn resettodr +function sets the system's battery-backed clock based on the contents +of the system +.Va time +variable. +.Sh SEE ALSO +.Xr inittodr 9 , +.Xr time 9 +.Sh BUGS +On many systems, +.Fn resettodr +has to convert from +.Va time +to a time expressed in terms of year, month, day, hours, minutes, +and seconds. +Many of the implementations could share code, but do not. diff --git a/static/freebsd/man9/resource_int_value.9 b/static/freebsd/man9/resource_int_value.9 new file mode 100644 index 00000000..08efe41a --- /dev/null +++ b/static/freebsd/man9/resource_int_value.9 @@ -0,0 +1,73 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2001 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 March 1, 2001 +.Dt RESOURCE_INT_VALUE 9 +.Os +.Sh NAME +.Nm resource_int_value , resource_long_value , resource_string_value +.Nd get a value from the hints mechanism +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn resource_int_value "const char *name" "int unit" "const char *resname" "int *result" +.Ft int +.Fn resource_long_value "const char *name" "int unit" "const char *resname" "long *result" +.Ft int +.Fn resource_string_value "const char *name" "int unit" "const char *resname" "const char **result" +.Sh DESCRIPTION +These functions fetch a value from the +.Dq hints +mechanism. +.Pp +The functions take the following arguments: +.Bl -tag -width "resname" +.It Fa name +The name of the device to get the resource value from. +.It Fa unit +The unit number of the device. +\-1 is special and is used for wildcard entries. +.It Fa resname +The resource name. +.It Fa result +A pointer to memory in which to store the resource value. +.El +.Sh RETURN VALUES +If successful, the functions return 0. +Otherwise, a non\-zero error code is returned. +.Sh ERRORS +The functions will fail if: +.Bl -tag -width Er +.It Bq Er ENOENT +The resource could not be found. +.It Bq Er EFTYPE +Inappropriate resource type. +.El +.Sh SEE ALSO +.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/static/freebsd/man9/rijndael.9 b/static/freebsd/man9/rijndael.9 new file mode 100644 index 00000000..0084b3ad --- /dev/null +++ b/static/freebsd/man9/rijndael.9 @@ -0,0 +1,133 @@ +.\" +.\" Copyright (c) 2002 +.\" Mark R V Murray. All rights reserved. +.\" +.\" 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 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 February 6, 2002 +.Dt RIJNDAEL 9 +.Os +.Sh NAME +.Nm rijndael_makeKey , +.Nm rijndael_cipherInit , +.Nm rijndael_blockEncrypt , +.Nm rijndael_padEncrypt , +.Nm rijndael_blockDecrypt , +.Nm rijndael_padDecrypt +.Nd AES encryption +.Sh SYNOPSIS +.In sys/types.h +.In crypto/rijndael.h +.Ft int +.Fo rijndael_makeKey +.Fa "keyInstance *key" +.Fa "uint8_t direction" +.Fa "int keyLen" +.Fa "char *keyMaterial" +.Fc +.Ft int +.Fo rijndael_cipherInit +.Fa "cipherInstance *cipher" +.Fa "uint8_t mode" +.Fa "char *IV" +.Fc +.Ft int +.Fo rijndael_blockEncrypt +.Fa "cipherInstance *cipher" +.Fa "keyInstance *key" +.Fa "uint8_t *input" +.Fa "int inputLen" +.Fa "uint8_t *outBuffer" +.Fc +.Ft int +.Fo rijndael_padEncrypt +.Fa "cipherInstance *cipher" +.Fa "keyInstance *key" +.Fa "uint8_t *input" +.Fa "int inputOctets" +.Fa "uint8_t *outBuffer" +.Fc +.Ft int +.Fo rijndael_blockDecrypt +.Fa "cipherInstance *cipher" +.Fa "keyInstance *key" +.Fa "uint8_t *input" +.Fa "int inputLen" +.Fa "uint8_t *outBuffer" +.Fc +.Ft int +.Fo rijndael_padDecrypt +.Fa "cipherInstance *cipher" +.Fa "keyInstance *key" +.Fa "uint8_t *input" +.Fa "int inputOctets" +.Fa "uint8_t *outBuffer" +.Fc +.Sh DESCRIPTION +The +.Fn rijndael_makeKey +function is used to set up the key schedule in +.Fa key . +The +.Fa direction +(which may be +.Dv DIR_ENCRYPT +or +.Dv DIR_DECRYPT ) +specifies the intended use of the key. +The length of the key (in bits) is given in +.Fa keyLen , +and must be 128, 192 or 256. +The actual key is supplied in the buffer pointed to by +.Fa keyMaterial . +This material may be raw binary data, +or an ASCII string containing a hexadecimal rendition +of the raw binary data, +dependent on a compile-time option in the +.Nm +sources, +.Dv BINARY_KEY_MATERIAL . +.Sh RETURN VALUES +The +.Fn rijndael_makeKey +function will return +.Dv BAD_KEY_INSTANCE +if a +.Dv NULL +.Fa key +is passed, +.Dv BAD_KEY_DIR +if +.Fa direction +is not +.Dv DIR_ENCRYPT +or +.Dv DIR_DECRYPT , +.Dv BAD_KEY_MAT +if the key materials are not a hexadecimal string +(and binary keys are not set), +and +.Dv TRUE +otherwise. +.Sh AUTHORS +.An Mark R V Murray diff --git a/static/freebsd/man9/rman.9 b/static/freebsd/man9/rman.9 new file mode 100644 index 00000000..d175b60b --- /dev/null +++ b/static/freebsd/man9/rman.9 @@ -0,0 +1,471 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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 March 13, 2024 +.Dt RMAN 9 +.Os +.Sh NAME +.Nm rman , +.Nm rman_activate_resource , +.Nm rman_adjust_resource , +.Nm rman_deactivate_resource , +.Nm rman_fini , +.Nm rman_init , +.Nm rman_init_from_resource , +.Nm rman_is_region_manager , +.Nm rman_manage_region , +.Nm rman_first_free_region , +.Nm rman_last_free_region , +.Nm rman_release_resource , +.Nm rman_reserve_resource , +.Nm rman_make_alignment_flags , +.Nm rman_get_start , +.Nm rman_get_end , +.Nm rman_get_device , +.Nm rman_get_size , +.Nm rman_get_flags , +.Nm rman_set_mapping , +.Nm rman_get_mapping , +.Nm rman_set_virtual , +.Nm rman_get_virtual , +.Nm rman_set_bustag , +.Nm rman_get_bustag , +.Nm rman_set_bushandle , +.Nm rman_get_bushandle , +.Nm rman_set_rid , +.Nm rman_get_rid , +.Nm rman_set_type , +.Nm rman_get_type +.Nd resource management functions +.Sh SYNOPSIS +.In sys/types.h +.In sys/rman.h +.Ft int +.Fn rman_activate_resource "struct resource *r" +.Ft int +.Fn rman_adjust_resource "struct resource *r" "rman_res_t start" "rman_res_t end" +.Ft int +.Fn rman_deactivate_resource "struct resource *r" +.Ft int +.Fn rman_fini "struct rman *rm" +.Ft int +.Fn rman_init "struct rman *rm" +.Ft int +.Fn rman_init_from_resource "struct rman *rm" "struct resource *r" +.Ft int +.Fn rman_is_region_manager "struct resource *r" "struct rman *rm" +.Ft int +.Fn rman_manage_region "struct rman *rm" "rman_res_t start" "rman_res_t end" +.Ft int +.Fn rman_first_free_region "struct rman *rm" "rman_res_t *start" "rman_res_t *end" +.Ft int +.Fn rman_last_free_region "struct rman *rm" "rman_res_t *start" "rman_res_t *end" +.Ft int +.Fn rman_release_resource "struct resource *r" +.Ft "struct resource *" +.Fo rman_reserve_resource +.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 uint32_t +.Fn rman_make_alignment_flags "uint32_t size" +.Ft rman_res_t +.Fn rman_get_start "struct resource *r" +.Ft rman_res_t +.Fn rman_get_end "struct resource *r" +.Ft "device_t" +.Fn rman_get_device "struct resource *r" +.Ft rman_res_t +.Fn rman_get_size "struct resource *r" +.Ft u_int +.Fn rman_get_flags "struct resource *r" +.Ft void +.Fn rman_set_mapping "struct resource *r" "struct resource_map *map" +.Ft void +.Fn rman_get_mapping "struct resource *r" "struct resource_map *map" +.Ft void +.Fn rman_set_virtual "struct resource *r" "void *v" +.Ft "void *" +.Fn rman_get_virtual "struct resource *r" +.Ft void +.Fn rman_set_bustag "struct resource *r" "bus_space_tag_t t" +.Ft bus_space_tag_t +.Fn rman_get_bustag "struct resource *r" +.Ft void +.Fn rman_set_bushandle "struct resource *r" "bus_space_handle_t h" +.Ft bus_space_handle_t +.Fn rman_get_bushandle "struct resource *r" +.Ft void +.Fn rman_set_rid "struct resource *r" "int rid" +.Ft int +.Fn rman_get_rid "struct resource *r" +.Ft void +.Fn rman_set_type "struct resource *r" "int type" +.Ft int +.Fn rman_get_type "struct resource *r" +.Sh DESCRIPTION +The +.Nm +set of functions provides a flexible resource management abstraction. +It is used extensively by the bus management code. +It implements the abstractions of region and resource. +A region descriptor is used to manage a region; this could be memory or +some other form of bus space. +.Pp +Each region has a set of bounds. +Within these bounds, allocated segments may reside. +Each segment, termed a resource, has several properties which are +represented by a 16-bit flag register, as follows. +.Bd -literal +#define RF_ALLOCATED 0x0001 /* resource has been reserved */ +#define RF_ACTIVE 0x0002 /* resource allocation has been activated */ +#define RF_SHAREABLE 0x0004 /* resource permits contemporaneous sharing */ +#define RF_FIRSTSHARE 0x0020 /* first in sharing list */ +#define RF_PREFETCHABLE 0x0040 /* resource is prefetchable */ +#define RF_UNMAPPED 0x0100 /* don't map resource when activating */ +.Ed +.Pp +Bits 15:10 of the flag register are used to represent the desired alignment +of the resource within the region. +.Pp +The +.Fn rman_init +function initializes the region descriptor, pointed to by the +.Fa rm +argument, for use with the resource management functions. +It is required that the fields +.Va rm_type +and +.Va rm_descr +of +.Vt "struct rman" +be set before calling +.Fn rman_init . +The field +.Va rm_type +shall be set to +.Dv RMAN_ARRAY . +The field +.Va rm_descr +shall be set to a string that describes the resource to be managed. +The +.Va rm_start +and +.Va rm_end +fields may be set to limit the range of acceptable resource addresses. +If these fields are not set, +.Fn rman_init +will initialize them to allow the entire range of resource addresses. +It also initializes any mutexes associated with the structure. +If +.Fn rman_init +fails to initialize the mutex, it will return +.Er ENOMEM ; otherwise it will return 0 and +.Fa rm +will be initialized. +.Pp +The +.Fn rman_fini +function frees any structures associated with the structure +pointed to by the +.Fa rm +argument. +If any of the resources within the managed region have the +.Dv RF_ALLOCATED +flag set, it will return +.Er EBUSY ; +otherwise, any mutexes associated with the structure will be released +and destroyed, and the function will return 0. +.Pp +The +.Fn rman_manage_region +function establishes the concept of a region which is under +.Nm +control. +The +.Fa rman +argument points to the region descriptor. +The +.Fa start +and +.Fa end +arguments specify the bounds of the region. +If successful, +.Fn rman_manage_region +will return 0. +If the region overlaps with an existing region, it will return +.Er EBUSY . +If any part of the region falls outside of the valid address range for +.Fa rm , +it will return +.Er EINVAL . +.Er ENOMEM +will be returned when +.Fn rman_manage_region +failed to allocate memory for the region. +.Pp +The +.Fn rman_init_from_resource +function is a wrapper routine to create a resource manager backed by an +existing resource. +It initializes +.Fa rm +using +.Fn rman_init +and then adds a region to +.Fa rm +corresponding to the address range allocated to +.Fa r +via +.Fn rman_manage_region . +.Pp +The +.Fn rman_first_free_region +and +.Fn rman_last_free_region +functions can be used to query a resource manager for its first +.Pq or last +unallocated region. +If +.Fa rm +contains no free region, +these functions will return +.Er ENOENT . +Otherwise, +.Fa *start +and +.Fa *end +are set to the bounds of the free region and zero is returned. +.Pp +The +.Fn rman_reserve_resource +function is where the bulk of the +.Nm +logic is located. +It attempts to reserve a contiguous range in the specified region +.Fa rm +for the use of the device +.Fa dev . +The caller can specify the +.Fa start +and +.Fa end +of an acceptable range, +required alignment, +and the code will attempt to find a free segment which fits. +The +.Fa start +argument is the lowest acceptable starting value of the resource. +The +.Fa end +argument is the highest acceptable ending value of the resource. +Therefore, +.Fa start No + Fa count No \- 1 +must be \[<=] +.Fa end +for any allocation to happen. +The alignment requirement +.Pq if any +is specified in +.Fa flags . +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. +If this shared segment already exists, the caller has its device +added to the list of consumers. +.Pp +The +.Fn rman_make_alignment_flags +function returns the flag mask corresponding to the desired alignment +.Fa size . +This should be used when calling +.Fn rman_reserve_resource_bound . +.Pp +The +.Fn rman_is_region_manager +function returns true if the allocated resource +.Fa r +was allocated from +.Fa rm . +Otherwise, +it returns false. +.Pp +The +.Fn rman_adjust_resource +function is used to adjust the reserved address range of an allocated resource +to reserve +.Fa start +through +.Fa end . +It can be used to grow or shrink one or both ends of the resource range. +The current implementation does not support entirely relocating the resource +and will fail with +.Er EINVAL +if the new resource range does not overlap the old resource range. +If either end of the resource range grows and the new resource range would +conflict with another allocated resource, +the function will fail with +.Er EBUSY . +The +.Fn rman_adjust_resource +function does not support adjusting the resource range for shared resources +and will fail such attempts with +.Er EINVAL . +Upon success, +the resource +.Fa r +will have a start address of +.Fa start +and an end address of +.Fa end +and the function will return zero. +Note that none of the constraints of the original allocation request such +as alignment or boundary restrictions are checked by +.Fn rman_adjust_resource . +It is the caller's responsibility to enforce any such requirements. +.Pp +The +.Fn rman_release_resource +function releases the reserved resource +.Fa r . +It may attempt to merge adjacent free resources. +.Pp +The +.Fn rman_activate_resource +function marks a resource as active, by setting the +.Dv RF_ACTIVE +flag. +If this is a time shared resource, and the caller has not yet acquired +the resource, the function returns +.Er EBUSY . +.Pp +The +.Fn rman_deactivate_resource +function marks a resource +.Fa r +as inactive, by clearing the +.Dv RF_ACTIVE +flag. +If other consumers are waiting for this range, it will wakeup their threads. +.Pp +The +.Fn rman_get_start , +.Fn rman_get_end , +.Fn rman_get_size , +and +.Fn rman_get_flags +functions return the bounds, size and flags of the previously reserved +resource +.Fa r . +.Pp +The +.Fn rman_set_bustag +function associates a +.Vt bus_space_tag_t +.Fa t +with the resource +.Fa r . +The +.Fn rman_get_bustag +function is used to retrieve this tag once set. +.Pp +The +.Fn rman_set_bushandle +function associates a +.Vt bus_space_handle_t +.Fa h +with the resource +.Fa r . +The +.Fn rman_get_bushandle +function is used to retrieve this handle once set. +.Pp +The +.Fn rman_set_virtual +function is used to associate a kernel virtual address with a resource +.Fa r . +The +.Fn rman_get_virtual +function can be used to retrieve the KVA once set. +.Pp +The +.Fn rman_set_mapping +function is used to associate a resource mapping with a resource +.Fa r . +The mapping must cover the entire resource. +Setting a mapping sets the associated +.Xr bus_space 9 +handle and tag for +.Fa r +as well as the kernel virtual address if the mapping contains one. +These individual values can be retrieved via +.Fn rman_get_bushandle , +.Fn rman_get_bustag , +and +.Fn rman_get_virtual . +.Pp +The +.Fn rman_get_mapping +function can be used to retrieve the associated resource mapping once set. +.Pp +The +.Fn rman_set_rid +function associates a resource identifier with a resource +.Fa r . +The +.Fn rman_get_rid +function retrieves this RID. +.Pp +The +.Fn rman_set_type +function associates a resource type with a resource +.Fa r . +The +.Fn rman_get_type +function retrieves this type. +.Pp +The +.Fn rman_get_device +function returns a pointer to the device which reserved the resource +.Fa r . +.Sh SEE ALSO +.Xr bus_activate_resource 9 , +.Xr bus_adjust_resource 9 , +.Xr bus_alloc_resource 9 , +.Xr bus_map_resource 9 , +.Xr bus_release_resource 9 , +.Xr bus_set_resource 9 , +.Xr bus_space 9 , +.Xr mutex 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/rmlock.9 b/static/freebsd/man9/rmlock.9 new file mode 100644 index 00000000..777492f8 --- /dev/null +++ b/static/freebsd/man9/rmlock.9 @@ -0,0 +1,382 @@ +.\" Copyright (c) 2007 Stephan Uphoff +.\" Copyright (c) 2006 Gleb Smirnoff +.\" 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. +.\" +.\" Based on rwlock.9 man page +.Dd April 12, 2021 +.Dt RMLOCK 9 +.Os +.Sh NAME +.Nm rmlock , +.Nm rm_init , +.Nm rm_init_flags , +.Nm rm_destroy , +.Nm rm_rlock , +.Nm rm_try_rlock , +.Nm rm_wlock , +.Nm rm_runlock , +.Nm rm_wunlock , +.Nm rm_wowned , +.Nm rm_sleep , +.Nm rm_assert , +.Nm RM_SYSINIT , +.Nm RM_SYSINIT_FLAGS , +.Nm rms_init , +.Nm rms_destroy , +.Nm rms_rlock , +.Nm rms_wlock , +.Nm rms_runlock , +.Nm rms_wunlock +.Nd kernel reader/writer lock optimized for read-mostly access patterns +.Sh SYNOPSIS +.In sys/param.h +.In sys/lock.h +.In sys/rmlock.h +.Ft void +.Fn rm_init "struct rmlock *rm" "const char *name" +.Ft void +.Fn rm_init_flags "struct rmlock *rm" "const char *name" "int opts" +.Ft void +.Fn rm_destroy "struct rmlock *rm" +.Ft void +.Fn rm_rlock "struct rmlock *rm" "struct rm_priotracker* tracker" +.Ft int +.Fn rm_try_rlock "struct rmlock *rm" "struct rm_priotracker* tracker" +.Ft void +.Fn rm_wlock "struct rmlock *rm" +.Ft void +.Fn rm_runlock "struct rmlock *rm" "struct rm_priotracker* tracker" +.Ft void +.Fn rm_wunlock "struct rmlock *rm" +.Ft int +.Fn rm_wowned "const struct rmlock *rm" +.Ft int +.Fn rm_sleep "void *wchan" "struct rmlock *rm" "int priority" "const char *wmesg" "int timo" +.Pp +.Cd "options INVARIANTS" +.Cd "options INVARIANT_SUPPORT" +.Ft void +.Fn rm_assert "struct rmlock *rm" "int what" +.In sys/kernel.h +.Fn RM_SYSINIT "name" "struct rmlock *rm" "const char *desc" +.Fn RM_SYSINIT_FLAGS "name" "struct rmlock *rm" "const char *desc" "int flags" +.Ft void +.Fn rms_init "struct rmslock *rms" "const char *name" +.Ft void +.Fn rms_destroy "struct rmslock *rms" +.Ft void +.Fn rms_rlock "struct rmslock *rms" +.Ft void +.Fn rms_wlock "struct rmslock *rms" +.Ft void +.Fn rms_runlock "struct rmslock *rms" +.Ft void +.Fn rms_wunlock "struct rmslock *rms" +.Sh DESCRIPTION +Read-mostly locks allow shared access to protected data by multiple threads, +or exclusive access by a single thread. +The threads with shared access are known as +.Em readers +since they only read the protected data. +A thread with exclusive access is known as a +.Em writer +since it can modify protected data. +.Pp +Read-mostly locks are designed to be efficient for locks almost exclusively +used as reader locks and as such should be used for protecting data that +rarely changes. +Acquiring an exclusive lock after the lock has been locked for shared access +is an expensive operation. +.Pp +Normal read-mostly locks are similar to +.Xr rwlock 9 +locks and follow the same lock ordering rules as +.Xr rwlock 9 +locks. +Read-mostly locks have full priority propagation like mutexes. +Unlike +.Xr rwlock 9 , +read-mostly locks propagate priority to both readers and writers. +This is implemented via the +.Va rm_priotracker +structure argument supplied to +.Fn rm_rlock +and +.Fn rm_runlock . +Readers can recurse if the lock is initialized with the +.Dv RM_RECURSE +option; +however, writers are never allowed to recurse. +.Pp +Sleeping for writers can be allowed by passing +.Dv RM_SLEEPABLE +to +.Fn rm_init_flags . +It changes lock ordering rules to the same as for +.Xr sx 9 +locks. +They do not propagate priority to writers, but they do propagate priority to readers. +Note that readers are not permitted to sleep regardless of the flag. +.Pp +Sleepable read-mostly locks (created with +.Fn rms_init ) +allow sleeping for both readers and writers, but don't do priority propagation +for either. +They follow +.Xr sx 9 +lock ordering. +.Ss Macros and Functions +.Bl -tag -width indent +.It Fn rm_init "struct rmlock *rm" "const char *name" +Initialize the read-mostly lock +.Fa rm . +The +.Fa name +description is used solely for debugging purposes. +This function must be called before any other operations +on the lock. +.It Fn rm_init_flags "struct rmlock *rm" "const char *name" "int opts" +Similar to +.Fn rm_init , +initialize the read-mostly lock +.Fa rm +with a set of optional flags. +The +.Fa opts +arguments contains one or more of the following flags: +.Bl -tag -width ".Dv RM_NOWITNESS" +.It Dv RM_NOWITNESS +Instruct +.Xr witness 4 +to ignore this lock. +.It Dv RM_RECURSE +Allow threads to recursively acquire shared locks for +.Fa rm . +.It Dv RM_SLEEPABLE +Create a sleepable read-mostly lock. +.It Dv RM_NEW +If the kernel has been compiled with +.Cd "option INVARIANTS" , +.Fn rm_init_flags +will assert that the +.Fa rm +has not been initialized multiple times without intervening calls to +.Fn rm_destroy +unless this option is specified. +.It Dv RM_DUPOK +.Xr witness 4 +should not log messages about duplicate locks being acquired. +.El +.It Fn rm_rlock "struct rmlock *rm" "struct rm_priotracker* tracker" +Lock +.Fa rm +as a reader using +.Fa tracker +to track read owners of a lock for priority propagation. +This data structure is only used internally by +.Nm +and must persist until +.Fn rm_runlock +has been called. +This data structure can be allocated on the stack since +readers cannot sleep. +If any thread holds this lock exclusively, the current thread blocks, +and its priority is propagated to the exclusive holder. +If the lock was initialized with the +.Dv RM_RECURSE +option the +.Fn rm_rlock +function can be called when the current thread has already acquired reader +access on +.Fa rm . +.It Fn rm_try_rlock "struct rmlock *rm" "struct rm_priotracker* tracker" +Try to lock +.Fa rm +as a reader. +.Fn rm_try_rlock +will return 0 if the lock cannot be acquired immediately; +otherwise, +the lock will be acquired and a non-zero value will be returned. +Note that +.Fn rm_try_rlock +may fail even while the lock is not currently held by a writer. +If the lock was initialized with the +.Dv RM_RECURSE +option, +.Fn rm_try_rlock +will succeed if the current thread has already acquired reader access. +.It Fn rm_wlock "struct rmlock *rm" +Lock +.Fa rm +as a writer. +If there are any shared owners of the lock, the current thread blocks. +The +.Fn rm_wlock +function cannot be called recursively. +.It Fn rm_runlock "struct rmlock *rm" "struct rm_priotracker* tracker" +This function releases a shared lock previously acquired by +.Fn rm_rlock . +The +.Fa tracker +argument must match the +.Fa tracker +argument used for acquiring the shared lock +.It Fn rm_wunlock "struct rmlock *rm" +This function releases an exclusive lock previously acquired by +.Fn rm_wlock . +.It Fn rm_destroy "struct rmlock *rm" +This functions destroys a lock previously initialized with +.Fn rm_init . +The +.Fa rm +lock must be unlocked. +.It Fn rm_wowned "const struct rmlock *rm" +This function returns a non-zero value if the current thread owns an +exclusive lock on +.Fa rm . +.It Fn rm_sleep "void *wchan" "struct rmlock *rm" "int priority" "const char *wmesg" "int timo" +This function atomically releases +.Fa rm +while waiting for an event. +The +.Fa rm +lock must be exclusively locked. +For more details on the parameters to this function, +see +.Xr sleep 9 . +.It Fn rm_assert "struct rmlock *rm" "int what" +This function asserts that the +.Fa rm +lock is in the state specified by +.Fa what . +If the assertions are not true and the kernel is compiled with +.Cd "options INVARIANTS" +and +.Cd "options INVARIANT_SUPPORT" , +the kernel will panic. +Currently the following base assertions are supported: +.Bl -tag -width ".Dv RA_UNLOCKED" +.It Dv RA_LOCKED +Assert that current thread holds either a shared or exclusive lock +of +.Fa rm . +.It Dv RA_RLOCKED +Assert that current thread holds a shared lock of +.Fa rm . +.It Dv RA_WLOCKED +Assert that current thread holds an exclusive lock of +.Fa rm . +.It Dv RA_UNLOCKED +Assert that current thread holds neither a shared nor exclusive lock of +.Fa rm . +.El +.Pp +In addition, one of the following optional flags may be specified with +.Dv RA_LOCKED , +.Dv RA_RLOCKED , +or +.Dv RA_WLOCKED : +.Bl -tag -width ".Dv RA_NOTRECURSED" +.It Dv RA_RECURSED +Assert that the current thread holds a recursive lock of +.Fa rm . +.It Dv RA_NOTRECURSED +Assert that the current thread does not hold a recursive lock of +.Fa rm . +.El +.El +.Bl -tag -width indent +.It Fn rms_init "struct rmslock *rms" "const char *name" +Initialize the sleepable read-mostly lock +.Fa rms . +The +.Fa name +description is used as +.Fa wmesg +parameter to the +.Xr msleep 9 +routine. +This function must be called before any other operations on the lock. +.It Fn rms_rlock "struct rmlock *rm" +Lock +.Fa rms +as a reader. +If any thread holds this lock exclusively, the current thread blocks. +.It Fn rms_wlock "struct rmslock *rms" +Lock +.Fa rms +as a writer. +If the lock is already taken, the current thread blocks. +The +.Fn rms_wlock +function cannot be called recursively. +.It Fn rms_runlock "struct rmslock *rms" +This function releases a shared lock previously acquired by +.Fn rms_rlock . +.It Fn rms_wunlock "struct rmslock *rms" +This function releases an exclusive lock previously acquired by +.Fn rms_wlock . +.It Fn rms_destroy "struct rmslock *rms" +This functions destroys a lock previously initialized with +.Fn rms_init . +The +.Fa rms +lock must be unlocked. +.El +.Sh SEE ALSO +.Xr locking 9 , +.Xr mutex 9 , +.Xr panic 9 , +.Xr rwlock 9 , +.Xr sema 9 , +.Xr sleep 9 , +.Xr sx 9 +.Sh HISTORY +These functions appeared in +.Fx 7.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +facility was written by +.An "Stephan Uphoff" . +This manual page was written by +.An "Gleb Smirnoff" +for rwlock and modified to reflect rmlock by +.An "Stephan Uphoff" . +.Sh BUGS +The +.Nm +implementation is currently not optimized for single processor systems. +.Pp +.Fn rm_try_rlock +can fail transiently even when there is no writer, while another reader +updates the state on the local CPU. +.Pp +The +.Nm +implementation uses a single per CPU list shared by all +rmlocks in the system. +If rmlocks become popular, hashing to multiple per CPU queues may +be needed to speed up the writer lock process. diff --git a/static/freebsd/man9/rtentry.9 b/static/freebsd/man9/rtentry.9 new file mode 100644 index 00000000..3f2e6c9e --- /dev/null +++ b/static/freebsd/man9/rtentry.9 @@ -0,0 +1,249 @@ +.\" +.\" Copyright 1996 Massachusetts Institute of Technology +.\" +.\" Permission to use, copy, modify, and distribute this software and +.\" its documentation for any purpose and without fee is hereby +.\" granted, provided that both the above copyright notice and this +.\" permission notice appear in all copies, that both the above +.\" copyright notice and this permission notice appear in all +.\" supporting documentation, and that the name of M.I.T. not be used +.\" in advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. M.I.T. makes +.\" no representations about the suitability of this software for any +.\" purpose. It is provided "as is" without express or implied +.\" warranty. +.\" +.\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS +.\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE, +.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT +.\" SHALL M.I.T. 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 March 5, 2014 +.Dt RTENTRY 9 +.Os +.Sh NAME +.Nm rtentry +.Nd structure of an entry in the kernel routing table +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In net/route.h +.Sh DESCRIPTION +The kernel provides a common mechanism by which all protocols can store +and retrieve entries from a central table of routes. +Parts of this +mechanism are also used to interact with user-level processes by means +of a socket in the +.Xr route 4 +pseudo-protocol family. +The +.In net/route.h +header file defines the structures and manifest constants used in this +facility. +.Pp +The basic structure of a route is defined by +.Vt "struct rtentry" , +which includes the following fields: +.Bl -tag -offset indent -width 6n +.It Vt "struct radix_node rt_nodes[2]" ; +Glue used by the radix-tree routines. +These members also include in +their substructure the key (i.e., destination address) and mask used +when the route was created. +The +.Fn rt_key rt +and +.Fn rt_mask rt +macros can be used to extract this information (in the form of a +.Vt "struct sockaddr *" ) +given a +.Vt "struct rtentry *" . +.It Vt "struct sockaddr *rt_gateway" ; +The +.Dq target +of the route, which can either represent a destination in its own +right (some protocols will put a link-layer address here), or some +intermediate stop on the way to that destination (if the +.Dv RTF_GATEWAY +flag is set). +.It Vt "int rt_flags" ; +See below. +If the +.Dv RTF_UP +flag is not present, the +.Fn rtfree +function will delete the route from the radix tree when the last +reference drops. +.It Vt "int rt_refcnt" ; +Route entries are reference-counted; this field indicates the number +of external (to the radix tree) references. +.It Vt "struct ifnet *rt_ifp" ; +.It Vt "struct ifaddr *rt_ifa" ; +These two fields represent the +.Dq answer , +as it were, to the question posed by a route lookup; that is, they +name the interface and interface address to be used in sending a +packet to the destination or set of destinations which this route +represents. +.It Vt "u_long rt_mtu"; +See description of rmx_mtu below. +.It Vt "u_long rt_weight"; +See description of rmx_weight below. +.It Vt "u_long rt_expire"; +See description of rmx_expire below. +.It Vt "counter64_t rt_pksent"; +See description of rmx_pksent below. +.It Vt "struct rtentry *rt_gwroute" ; +This member is a reference to a route whose destination is +.Va rt_gateway . +It is only used for +.Dv RTF_GATEWAY +routes. +.It Vt "struct mtx rt_mtx" ; +Mutex to lock this routing entry. +.El +.Pp +The following flag bits are defined: +.Bl -tag -offset indent -width ".Dv RTF_BLACKHOLE" -compact +.It Dv RTF_UP +The route is not deleted. +.It Dv RTF_GATEWAY +The route points to an intermediate destination and not the ultimate +recipient; the +.Va rt_gateway +and +.Va rt_gwroute +fields name that destination. +.It Dv RTF_HOST +This is a host route. +.It Dv RTF_REJECT +The destination is presently unreachable. +This should result in an +.Er EHOSTUNREACH +error from output routines. +.It Dv RTF_DYNAMIC +This route was created dynamically by +.Fn rtredirect . +.It Dv RTF_MODIFIED +This route was modified by +.Fn rtredirect . +.It Dv RTF_DONE +Used only in the +.Xr route 4 +protocol, indicating that the request was executed. +.It Dv RTF_XRESOLVE +When this route is returned as a result of a lookup, send a report on +the +.Xr route 4 +interface requesting that an external process perform resolution for +this route. +.It Dv RTF_STATIC +Indicates that this route was manually added by means of the +.Xr route 8 +command. +.It Dv RTF_BLACKHOLE +Requests that output sent via this route be discarded. +.It Dv RTF_PROTO1 +.It Dv RTF_PROTO2 +.It Dv RTF_PROTO3 +Protocol-specific. +.It Dv RTF_PINNED +Indicates that this route is immutable to a routing protocol. +.It Dv RTF_LOCAL +Indicates that the destination of this route is an address configured +as belonging to this system. +.It Dv RTF_BROADCAST +Indicates that the destination is a broadcast address. +.It Dv RTF_MULTICAST +Indicates that the destination is a multicast address. +.El +.Pp +Several metrics are supplied in +.Vt "struct rt_metrics" +passed with routing control messages via +.Xr route 4 +API. +Currently only +.Vt rmx_mtu , rmx_expire , +and +.Vt rmx_pksent +metrics are supplied. +All others are ignored. +.Pp +The following metrics are defined by +.Vt "struct rt_metrics" : +.Bl -tag -offset indent -width 6n +.It Vt "u_long rmx_locks" ; +Flag bits indicating which metrics the kernel is not permitted to +dynamically modify. +.It Vt "u_long rmx_mtu" ; +MTU for this path. +.It Vt "u_long rmx_hopcount" ; +Number of intermediate systems on the path to this destination. +.It Vt "u_long rmx_expire" ; +The time +(a la +.Xr time 3 ) +at which this route should expire, or zero if it should never expire. +It is the responsibility of individual protocol suites to ensure that routes +are actually deleted once they expire. +.It Vt "u_long rmx_recvpipe" ; +Nominally, the bandwidth-delay product for the path +.Em from +the destination +.Em to +this system. +In practice, this value is used to set the size of the +receive buffer (and thus the window in sliding-window protocols like +.Tn TCP ) . +.It Vt "u_long rmx_sendpipe" ; +As before, but in the opposite direction. +.It Vt "u_long rmx_ssthresh" ; +The slow-start threshold used in +.Tn TCP +congestion-avoidance. +.It Vt "u_long rmx_rtt" ; +The round-trip time to this destination, in units of +.Dv RMX_RTTUNIT +per second. +.It Vt "u_long rmx_rttvar" ; +The average deviation of the round-trip time to this destination, in +units of +.Dv RMX_RTTUNIT +per second. +.It Vt "u_long rmx_pksent" ; +A count of packets successfully sent via this route. +.It Vt "u_long rmx_filler[4]" ; +.\" XXX badly named +Empty space available for protocol-specific information. +.El +.Sh SEE ALSO +.Xr route 4 , +.Xr route 8 +.Sh HISTORY +The +.Vt rtentry +structure first appeared in +.Bx 4.2 . +The radix-tree representation of the routing table and the +.Vt rt_metrics +structure first appeared in +.Bx 4.3 reno . +.Sh AUTHORS +This manual page was written by +.An Garrett Wollman . +.Sh BUGS +There are a number of historical relics remaining in this interface. +The +.Va rt_gateway +and +.Va rmx_filler +fields could be named better. diff --git a/static/freebsd/man9/runqueue.9 b/static/freebsd/man9/runqueue.9 new file mode 100644 index 00000000..9938af8e --- /dev/null +++ b/static/freebsd/man9/runqueue.9 @@ -0,0 +1,134 @@ +.\" Copyright (c) 2000-2001 John H. Baldwin +.\" +.\" 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 August 15, 2010 +.Dt RUNQUEUE 9 +.Os +.Sh NAME +.Nm choosethread , +.Nm procrunnable , +.Nm remrunqueue , +.Nm setrunqueue +.Nd manage the queue of runnable processes +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.Vt "extern struct rq itqueues[]" ; +.Vt "extern struct rq rtqueues[]" ; +.Vt "extern struct rq queues[]" ; +.Vt "extern struct rq idqueues[]" ; +.Ft struct thread * +.Fn choosethread "void" +.Ft int +.Fn procrunnable "void" +.Ft void +.Fn remrunqueue "struct thread *td" +.Ft void +.Fn setrunqueue "struct thread *td" +.Sh DESCRIPTION +The run queue consists of four priority queues: +.Va itqueues +for interrupt threads, +.Va rtqueues +for realtime priority processes, +.Va queues +for time sharing processes, and +.Va idqueues +for idle priority processes. +Each priority queue consists of an array of +.Dv NQS +queue header structures. +Each queue header identifies a list of runnable processes of equal priority. +Each queue also has a single word that contains a bit mask identifying +non-empty queues to assist in selecting a process quickly. +These are named +.Va itqueuebits , +.Va rtqueuebits , +.Va queuebits , +and +.Va idqueuebits . +The run queues are protected by the +.Va sched_lock +mutex. +.Pp +.Fn procrunnable +returns zero if there are no runnable processes other than the idle process. +If there is at least one runnable process other than the idle process, it +will return a non-zero value. +Note that the +.Va sched_lock +mutex does +.Em not +need to be held when this function is called. +There is a small race window where one CPU may place a process on the run queue +when there are currently no other runnable processes while another CPU is +calling this function. +In that case the second CPU will simply travel through the idle loop one +additional time before noticing that there is a runnable process. +This works because idle CPUs are not halted in SMP systems. +If idle CPUs are halted in SMP systems, then this race condition might have +more serious repercussions in the losing case, and +.Fn procrunnable +may have to require that the +.Va sched_lock +mutex be acquired. +.Pp +.Fn choosethread +returns the highest priority runnable thread. +If there are no runnable threads, then the idle thread is returned. +This function is called by +.Fn cpu_switch +and +.Fn cpu_throw +to determine which thread to switch to. +.Fn choosethread +must be called with the +.Va sched_lock +mutex held. +.Pp +.Fn setrunqueue +adds the thread +.Fa td +to the tail of the appropriate queue in the proper priority queue. +The thread must be runnable, i.e.\& +.Va p_stat +must be set to +.Dv SRUN . +This function must be called with the +.Va sched_lock +mutex held. +.Pp +.Fn remrunqueue +removes thread +.Fa td +from its run queue. +If +.Fa td +is not on a run queue, then the kernel will +.Xr panic 9 . +This function must be called with the +.Va sched_lock +mutex held. +.Sh SEE ALSO +.Xr cpu_switch 9 , +.Xr scheduler 9 , +.Xr sleepqueue 9 diff --git a/static/freebsd/man9/rwlock.9 b/static/freebsd/man9/rwlock.9 new file mode 100644 index 00000000..63266387 --- /dev/null +++ b/static/freebsd/man9/rwlock.9 @@ -0,0 +1,335 @@ +.\" Copyright (c) 2006 Gleb Smirnoff +.\" 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 November 11, 2017 +.Dt RWLOCK 9 +.Os +.Sh NAME +.Nm rwlock , +.Nm rw_init , +.Nm rw_init_flags , +.Nm rw_destroy , +.Nm rw_rlock , +.Nm rw_wlock , +.Nm rw_runlock , +.Nm rw_wunlock , +.Nm rw_unlock , +.Nm rw_try_rlock , +.Nm rw_try_upgrade , +.Nm rw_try_wlock , +.Nm rw_downgrade , +.Nm rw_sleep , +.Nm rw_initialized , +.Nm rw_wowned , +.Nm rw_assert , +.Nm RW_SYSINIT , +.Nm RW_SYSINIT_FLAGS +.Nd kernel reader/writer lock +.Sh SYNOPSIS +.In sys/param.h +.In sys/lock.h +.In sys/rwlock.h +.Ft void +.Fn rw_init "struct rwlock *rw" "const char *name" +.Ft void +.Fn rw_init_flags "struct rwlock *rw" "const char *name" "int opts" +.Ft void +.Fn rw_destroy "struct rwlock *rw" +.Ft void +.Fn rw_rlock "struct rwlock *rw" +.Ft void +.Fn rw_wlock "struct rwlock *rw" +.Ft int +.Fn rw_try_rlock "struct rwlock *rw" +.Ft int +.Fn rw_try_wlock "struct rwlock *rw" +.Ft void +.Fn rw_runlock "struct rwlock *rw" +.Ft void +.Fn rw_wunlock "struct rwlock *rw" +.Ft void +.Fn rw_unlock "struct rwlock *rw" +.Ft int +.Fn rw_try_upgrade "struct rwlock *rw" +.Ft void +.Fn rw_downgrade "struct rwlock *rw" +.Ft int +.Fn rw_sleep "void *chan" "struct rwlock *rw" "int priority" "const char *wmesg" "int timo" +.Ft int +.Fn rw_initialized "const struct rwlock *rw" +.Ft int +.Fn rw_wowned "const struct rwlock *rw" +.Pp +.Cd "options INVARIANTS" +.Cd "options INVARIANT_SUPPORT" +.Ft void +.Fn rw_assert "const struct rwlock *rw" "int what" +.In sys/kernel.h +.Fn RW_SYSINIT "name" "struct rwlock *rw" "const char *desc" +.Fn RW_SYSINIT_FLAGS "name" "struct rwlock *rw" "const char *desc" "int flags" +.Sh DESCRIPTION +Reader/writer locks allow shared access to protected data by multiple threads, +or exclusive access by a single thread. +The threads with shared access are known as +.Em readers +since they only read the protected data. +A thread with exclusive access is known as a +.Em writer +since it can modify protected data. +.Pp +Although reader/writer locks look very similar to +.Xr sx 9 +locks, their usage pattern is different. +Reader/writer locks can be treated as mutexes (see +.Xr mutex 9 ) +with shared/exclusive semantics. +Unlike +.Xr sx 9 , +an +.Nm +can be locked while holding a non-spin mutex, and an +.Nm +cannot be held while sleeping. +The +.Nm +locks have priority propagation like mutexes, but priority +can be propagated only to writers. +This limitation comes from the fact that readers +are anonymous. +Another important property is that readers can always recurse, +and exclusive locks can be made recursive selectively. +.Ss Macros and Functions +.Bl -tag -width indent +.It Fn rw_init "struct rwlock *rw" "const char *name" +Initialize structure located at +.Fa rw +as reader/writer lock, described by name +.Fa name . +The description is used solely for debugging purposes. +This function must be called before any other operations +on the lock. +.It Fn rw_init_flags "struct rwlock *rw" "const char *name" "int opts" +Initialize the rw lock just like the +.Fn rw_init +function, but specifying a set of optional flags to alter the +behaviour of +.Fa rw , +through the +.Fa opts +argument. +It contains one or more of the following flags: +.Bl -tag -width ".Dv RW_NOPROFILE" +.It Dv RW_DUPOK +Witness should not log messages about duplicate locks being acquired. +.It Dv RW_NOPROFILE +Do not profile this lock. +.It Dv RW_NOWITNESS +Instruct +.Xr witness 4 +to ignore this lock. +.It Dv RW_QUIET +Do not log any operations for this lock via +.Xr ktr 4 . +.It Dv RW_RECURSE +Allow threads to recursively acquire exclusive locks for +.Fa rw . +.It Dv RW_NEW +If the kernel has been compiled with +.Cd "option INVARIANTS" , +.Fn rw_init_flags +will assert that the +.Fa rw +has not been initialized multiple times without intervening calls to +.Fn rw_destroy +unless this option is specified. +.El +.It Fn rw_rlock "struct rwlock *rw" +Lock +.Fa rw +as a reader. +If any thread holds this lock exclusively, the current thread blocks, +and its priority is propagated to the exclusive holder. +The +.Fn rw_rlock +function can be called when the thread has already acquired reader +access on +.Fa rw . +This is called +.Dq "recursing on a lock" . +.It Fn rw_wlock "struct rwlock *rw" +Lock +.Fa rw +as a writer. +If there are any shared owners of the lock, the current thread blocks. +The +.Fn rw_wlock +function can be called recursively only if +.Fa rw +has been initialized with the +.Dv RW_RECURSE +option enabled. +.It Fn rw_try_rlock "struct rwlock *rw" +Try to lock +.Fa rw +as a reader. +This function will return true if the operation succeeds, otherwise 0 +will be returned. +.It Fn rw_try_wlock "struct rwlock *rw" +Try to lock +.Fa rw +as a writer. +This function will return true if the operation succeeds, otherwise 0 +will be returned. +.It Fn rw_runlock "struct rwlock *rw" +This function releases a shared lock previously acquired by +.Fn rw_rlock . +.It Fn rw_wunlock "struct rwlock *rw" +This function releases an exclusive lock previously acquired by +.Fn rw_wlock . +.It Fn rw_unlock "struct rwlock *rw" +This function releases a shared lock previously acquired by +.Fn rw_rlock +or an exclusive lock previously acquired by +.Fn rw_wlock . +.It Fn rw_try_upgrade "struct rwlock *rw" +Attempt to upgrade a single shared lock to an exclusive lock. +The current thread must hold a shared lock of +.Fa rw . +This will only succeed if the current thread holds the only shared lock on +.Fa rw , +and it only holds a single shared lock. +If the attempt succeeds +.Fn rw_try_upgrade +will return a non-zero value, +and the current thread will hold an exclusive lock. +If the attempt fails +.Fn rw_try_upgrade +will return zero, +and the current thread will still hold a shared lock. +.It Fn rw_downgrade "struct rwlock *rw" +Convert an exclusive lock into a single shared lock. +The current thread must hold an exclusive lock of +.Fa rw . +.It Fn rw_sleep "void *chan" "struct rwlock *rw" "int priority" "const char *wmesg" "int timo" +Atomically release +.Fa rw +while waiting for an event. +For more details on the parameters to this function, +see +.Xr sleep 9 . +.It Fn rw_initialized "const struct rwlock *rw" +This function returns non-zero if +.Fa rw +has been initialized, and zero otherwise. +.It Fn rw_destroy "struct rwlock *rw" +This functions destroys a lock previously initialized with +.Fn rw_init . +The +.Fa rw +lock must be unlocked. +.It Fn rw_wowned "const struct rwlock *rw" +This function returns a non-zero value if the current thread owns an +exclusive lock on +.Fa rw . +.It Fn rw_assert "const struct rwlock *rw" "int what" +This function allows assertions specified in +.Fa what +to be made about +.Fa rw . +If the assertions are not true and the kernel is compiled +with +.Cd "options INVARIANTS" +and +.Cd "options INVARIANT_SUPPORT" , +the kernel will panic. +Currently the following base assertions are supported: +.Bl -tag -width ".Dv RA_UNLOCKED" +.It Dv RA_LOCKED +Assert that current thread holds either a shared or exclusive lock +of +.Fa rw . +.It Dv RA_RLOCKED +Assert that current thread holds a shared lock of +.Fa rw . +.It Dv RA_WLOCKED +Assert that current thread holds an exclusive lock of +.Fa rw . +.It Dv RA_UNLOCKED +Assert that current thread holds neither a shared nor exclusive lock of +.Fa rw . +.El +.Pp +In addition, one of the following optional flags may be specified with +.Dv RA_LOCKED , +.Dv RA_RLOCKED , +or +.Dv RA_WLOCKED : +.Bl -tag -width ".Dv RA_NOTRECURSED" +.It Dv RA_RECURSED +Assert that the current thread holds a recursive lock of +.Fa rw . +.It Dv RA_NOTRECURSED +Assert that the current thread does not hold a recursive lock of +.Fa rw . +.El +.El +.Sh SEE ALSO +.Xr locking 9 , +.Xr mutex 9 , +.Xr panic 9 , +.Xr sema 9 , +.Xr sx 9 +.Sh HISTORY +These +functions appeared in +.Fx 7.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +facility was written by +.An "John Baldwin" . +This manual page was written by +.An "Gleb Smirnoff" . +.Sh BUGS +A kernel without +.Dv WITNESS +cannot assert whether the current thread does or does not hold a read lock. +.Dv RA_LOCKED +and +.Dv RA_RLOCKED +can only assert that +.Em any +thread holds a read lock. +They cannot ensure that the current thread holds a read lock. +Further, +.Dv RA_UNLOCKED +can only assert that the current thread does not hold a write lock. +.Pp +Reader/writer is a bit of an awkward name. +An +.Nm +can also be called a +.Dq Robert Watson +lock if desired. diff --git a/static/freebsd/man9/sbuf.9 b/static/freebsd/man9/sbuf.9 new file mode 100644 index 00000000..d4ffa050 --- /dev/null +++ b/static/freebsd/man9/sbuf.9 @@ -0,0 +1,769 @@ +.\"- +.\" Copyright (c) 2000 Poul-Henning Kamp and Dag-Erling Smørgrav +.\" 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 October 3, 2023 +.Dt SBUF 9 +.Os +.Sh NAME +.Nm sbuf , +.Nm sbuf_new , +.Nm sbuf_new_auto , +.Nm sbuf_new_for_sysctl , +.Nm sbuf_clear , +.Nm sbuf_get_flags , +.Nm sbuf_set_flags , +.Nm sbuf_clear_flags , +.Nm sbuf_setpos , +.Nm sbuf_bcat , +.Nm sbuf_bcopyin , +.Nm sbuf_bcpy , +.Nm sbuf_cat , +.Nm sbuf_copyin , +.Nm sbuf_cpy , +.Nm sbuf_nl_terminate , +.Nm sbuf_printf , +.Nm sbuf_vprintf , +.Nm sbuf_putc , +.Nm sbuf_set_drain , +.Nm sbuf_trim , +.Nm sbuf_error , +.Nm sbuf_finish , +.Nm sbuf_data , +.Nm sbuf_len , +.Nm sbuf_done , +.Nm sbuf_delete , +.Nm sbuf_start_section , +.Nm sbuf_end_section , +.Nm sbuf_hexdump , +.Nm sbuf_printf_drain , +.Nm sbuf_putbuf +.Nd safe string composition +.Sh LIBRARY +.Lb libsbuf +.Sh SYNOPSIS +.In sys/types.h +.In sys/sbuf.h +.Ft typedef int +.Fo (sbuf_drain_func) +.Fa "void *arg" +.Fa "const char *data" +.Fa "int len" +.Fc +.Pp +.Ft struct sbuf * +.Fo sbuf_new +.Fa "struct sbuf *s" +.Fa "char *buf" +.Fa "int length" +.Fa "int flags" +.Fc +.Ft struct sbuf * +.Fo sbuf_new_auto +.Fa "void" +.Fc +.Ft void +.Fo sbuf_clear +.Fa "struct sbuf *s" +.Fc +.Ft int +.Fo sbuf_get_flags +.Fa "struct sbuf *s" +.Fc +.Ft void +.Fo sbuf_set_flags +.Fa "struct sbuf *s" +.Fa "int flags" +.Fc +.Ft void +.Fo sbuf_clear_flags +.Fa "struct sbuf *s" +.Fa "int flags" +.Fc +.Ft int +.Fo sbuf_setpos +.Fa "struct sbuf *s" +.Fa "int pos" +.Fc +.Ft int +.Fo sbuf_bcat +.Fa "struct sbuf *s" +.Fa "const void *buf" +.Fa "size_t len" +.Fc +.Ft int +.Fo sbuf_bcpy +.Fa "struct sbuf *s" +.Fa "const void *buf" +.Fa "size_t len" +.Fc +.Ft int +.Fo sbuf_cat +.Fa "struct sbuf *s" +.Fa "const char *str" +.Fc +.Ft int +.Fo sbuf_cpy +.Fa "struct sbuf *s" +.Fa "const char *str" +.Fc +.Ft int +.Fn sbuf_nl_terminate "struct sbuf *" +.Ft int +.Fo sbuf_printf +.Fa "struct sbuf *s" +.Fa "const char *fmt" "..." +.Fc +.Ft int +.Fo sbuf_vprintf +.Fa "struct sbuf *s" +.Fa "const char *fmt" +.Fa "va_list ap" +.Fc +.Ft int +.Fo sbuf_putc +.Fa "struct sbuf *s" +.Fa "int c" +.Fc +.Ft void +.Fo sbuf_set_drain +.Fa "struct sbuf *s" +.Fa "sbuf_drain_func *func" +.Fa "void *arg" +.Fc +.Ft int +.Fo sbuf_trim +.Fa "struct sbuf *s" +.Fc +.Ft int +.Fo sbuf_error +.Fa "struct sbuf *s" +.Fc +.Ft int +.Fo sbuf_finish +.Fa "struct sbuf *s" +.Fc +.Ft char * +.Fo sbuf_data +.Fa "struct sbuf *s" +.Fc +.Ft ssize_t +.Fo sbuf_len +.Fa "struct sbuf *s" +.Fc +.Ft int +.Fo sbuf_done +.Fa "struct sbuf *s" +.Fc +.Ft void +.Fo sbuf_delete +.Fa "struct sbuf *s" +.Fc +.Ft void +.Fo sbuf_start_section +.Fa "struct sbuf *s" +.Fa "ssize_t *old_lenp" +.Fc +.Ft ssize_t +.Fo sbuf_end_section +.Fa "struct sbuf *s" +.Fa "ssize_t old_len" +.Fa "size_t pad" +.Fa "int c" +.Fc +.Ft void +.Fo sbuf_hexdump +.Fa "struct sbuf *sb" +.Fa "void *ptr" +.Fa "int length" +.Fa "const char *hdr" +.Fa "int flags" +.Fc +.Ft int +.Fo sbuf_printf_drain +.Fa "void *arg" +.Fa "const char *data" +.Fa "int len" +.Fc +.Ft void +.Fo sbuf_putbuf +.Fa "struct sbuf *s" +.Fc +.Fd #ifdef _KERNEL +.In sys/types.h +.In sys/sbuf.h +.Ft int +.Fo sbuf_bcopyin +.Fa "struct sbuf *s" +.Fa "const void *uaddr" +.Fa "size_t len" +.Fc +.Ft int +.Fo sbuf_copyin +.Fa "struct sbuf *s" +.Fa "const void *uaddr" +.Fa "size_t len" +.Fc +.In sys/sysctl.h +.Ft struct sbuf * +.Fo sbuf_new_for_sysctl +.Fa "struct sbuf *s" +.Fa "char *buf" +.Fa "int length" +.Fa "struct sysctl_req *req" +.Fc +.Fd #endif /* _KERNEL */ +.Sh DESCRIPTION +The +.Nm +family of functions allows one to safely allocate, compose and +release strings in kernel or user space. +.Pp +Instead of arrays of characters, these functions operate on structures +called +.Fa sbufs , +defined in +.In sys/sbuf.h . +.Pp +Any errors encountered during the allocation or composition of the +string will be latched in the data structure, +making a single error test at the end of the composition +sufficient to determine success or failure of the entire process. +.Pp +The +.Fn sbuf_new +function initializes the +.Fa sbuf +pointed to by its first argument. +If that pointer is +.Dv NULL , +.Fn sbuf_new +allocates a +.Vt struct sbuf +using +.Xr malloc 9 . +The +.Fa buf +argument is a pointer to a buffer in which to store the actual string; +if it is +.Dv NULL , +.Fn sbuf_new +will allocate one using +.Xr malloc 9 . +The +.Fa length +is the initial size of the storage buffer. +The fourth argument, +.Fa flags , +may be comprised of the following flags: +.Bl -tag -width ".Dv SBUF_AUTOEXTEND" +.It Dv SBUF_FIXEDLEN +The storage buffer is fixed at its initial size. +Attempting to extend the sbuf beyond this size results in an overflow condition. +.It Dv SBUF_AUTOEXTEND +This indicates that the storage buffer may be extended as necessary, so long +as resources allow, to hold additional data. +.It Dv SBUF_INCLUDENUL +This causes the final nulterm byte to be counted in the length of the data. +.It Dv SBUF_DRAINTOEOR +Treat top-level sections started with +.Fn sbuf_start_section +as a record boundary marker that will be used during drain operations to avoid +records being split. +If a record grows sufficiently large such that it fills the +.Fa sbuf +and therefore cannot be drained without being split, an error of +.Er EDEADLK +is set. +.It Dv SBUF_NOWAIT +Indicates that attempts to extend the storage buffer should fail in low memory +conditions, like +.Xr malloc 9 +.Dv M_NOWAIT . +.El +.Pp +Note that if +.Fa buf +is not +.Dv NULL , +it must point to an array of at least +.Fa length +characters. +The result of accessing that array directly while it is in use by the +sbuf is undefined. +.Pp +The +.Fn sbuf_new_auto +function is a shortcut for creating a completely dynamic +.Nm . +It is the equivalent of calling +.Fn sbuf_new +with values +.Dv NULL , +.Dv NULL , +.Dv 0 , +and +.Dv SBUF_AUTOEXTEND . +.Pp +The +.Fn sbuf_new_for_sysctl +function will set up an sbuf with a drain function to use +.Fn SYSCTL_OUT +when the internal buffer fills. +Note that if the various functions which append to an sbuf are used while +a non-sleepable lock is held, the user buffer should be wired using +.Fn sysctl_wire_old_buffer . +.Pp +The +.Fn sbuf_delete +function clears the +.Fa sbuf +and frees any memory allocated for it. +There must be a call to +.Fn sbuf_delete +for every call to +.Fn sbuf_new . +Any attempt to access the sbuf after it has been deleted will fail. +.Pp +The +.Fn sbuf_clear +function invalidates the contents of the +.Fa sbuf +and resets its position to zero. +.Pp +The +.Fn sbuf_get_flags +function returns the current user flags. +The +.Fn sbuf_set_flags +and +.Fn sbuf_clear_flags +functions set or clear one or more user flags, respectively. +The user flags are described under the +.Fn sbuf_new +function. +.Pp +The +.Fn sbuf_setpos +function sets the +.Fa sbuf Ns 's +end position to +.Fa pos , +which is a value between zero and the current position in the buffer. +It can only truncate the sbuf to the new position. +.Pp +The +.Fn sbuf_bcat +function appends the first +.Fa len +bytes from the buffer +.Fa buf +to the +.Fa sbuf . +.Pp +The +.Fn sbuf_bcopyin +function copies +.Fa len +bytes from the specified userland address into the +.Fa sbuf . +.Pp +The +.Fn sbuf_bcpy +function replaces the contents of the +.Fa sbuf +with the first +.Fa len +bytes from the buffer +.Fa buf . +.Pp +The +.Fn sbuf_cat +function appends the NUL-terminated string +.Fa str +to the +.Fa sbuf +at the current position. +.Pp +The +.Fn sbuf_set_drain +function sets a drain function +.Fa func +for the +.Fa sbuf , +and records a pointer +.Fa arg +to be passed to the drain on callback. +The drain function cannot be changed while +.Fa sbuf_len +is non-zero. +.Pp +The registered drain function +.Vt sbuf_drain_func +will be called with the argument +.Fa arg +provided to +.Fn sbuf_set_drain , +a pointer +.Fa data +to a byte string that is the contents of the sbuf, and the length +.Fa len +of the data. +If the drain function exists, it will be called when the sbuf internal +buffer is full, or on behalf of +.Fn sbuf_finish . +The drain function may drain some or all of the data, but must drain +at least 1 byte. +The return value from the drain function, if positive, indicates how +many bytes were drained. +If negative, the return value indicates the negative error code which +will be returned from this or a later call to +.Fn sbuf_finish . +If the returned drained length is 0, an error of +.Er EDEADLK +is set. +To do unbuffered draining, initialize the sbuf with a two-byte buffer. +The drain will be called for every byte added to the sbuf. +The +.Fn sbuf_bcopyin , +.Fn sbuf_bcpy , +.Fn sbuf_clear , +.Fn sbuf_copyin , +.Fn sbuf_cpy , +.Fn sbuf_trim , +.Fn sbuf_data , +and +.Fn sbuf_len +functions cannot be used on an sbuf with a drain. +.Pp +The +.Fn sbuf_copyin +function copies a NUL-terminated string from the specified userland +address into the +.Fa sbuf . +If the +.Fa len +argument is non-zero, no more than +.Fa len +characters (not counting the terminating NUL) are copied; otherwise +the entire string, or as much of it as can fit in the +.Fa sbuf , +is copied. +.Pp +The +.Fn sbuf_cpy +function replaces the contents of the +.Fa sbuf +with those of the NUL-terminated string +.Fa str . +This is equivalent to calling +.Fn sbuf_cat +with a fresh +.Fa sbuf +or one which position has been reset to zero with +.Fn sbuf_clear +or +.Fn sbuf_setpos . +.Pp +The +.Fn sbuf_nl_terminate +function appends a trailing newline character, if the current line is non-empty +and not already terminated by a newline character. +.Pp +The +.Fn sbuf_printf +function formats its arguments according to the format string pointed +to by +.Fa fmt +and appends the resulting string to the +.Fa sbuf +at the current position. +.Pp +The +.Fn sbuf_vprintf +function behaves the same as +.Fn sbuf_printf +except that the arguments are obtained from the variable-length argument list +.Fa ap . +.Pp +The +.Fn sbuf_putc +function appends the character +.Fa c +to the +.Fa sbuf +at the current position. +.Pp +The +.Fn sbuf_trim +function removes trailing whitespace from the +.Fa sbuf . +.Pp +The +.Fn sbuf_error +function returns any error value that the +.Fa sbuf +may have accumulated, either from the drain function, or +.Er ENOMEM +if the +.Fa sbuf +overflowed. +This function is generally not needed and instead the error code from +.Fn sbuf_finish +is the preferred way to discover whether an sbuf had an error. +.Pp +The +.Fn sbuf_finish +function will call the attached drain function if one exists until all +the data in the +.Fa sbuf +is flushed. +If there is no attached drain, +.Fn sbuf_finish +NUL-terminates the +.Fa sbuf . +In either case it marks the +.Fa sbuf +as finished, which means that it may no longer be modified using +.Fn sbuf_setpos , +.Fn sbuf_cat , +.Fn sbuf_cpy , +.Fn sbuf_printf +or +.Fn sbuf_putc , +until +.Fn sbuf_clear +is used to reset the sbuf. +.Pp +The +.Fn sbuf_data +function returns the actual string; +.Fn sbuf_data +only works on a finished +.Fa sbuf . +The +.Fn sbuf_len +function returns the length of the string. +For an +.Fa sbuf +with an attached drain, +.Fn sbuf_len +returns the length of the un-drained data. +.Fn sbuf_done +returns non-zero if the +.Fa sbuf +is finished. +.Pp +The +.Fn sbuf_start_section +and +.Fn sbuf_end_section +functions may be used for automatic section alignment. +The arguments +.Fa pad +and +.Fa c +specify the padding size and a character used for padding. +The arguments +.Fa old_lenp +and +.Fa old_len +are to save and restore the current section length when nested sections +are used. +For the top level section +.Dv NULL +and \-1 can be specified for +.Fa old_lenp +and +.Fa old_len +respectively. +.Pp +The +.Fn sbuf_hexdump +function prints an array of bytes to the supplied sbuf, along with an ASCII +representation of the bytes if possible. +See the +.Xr hexdump 3 +man page for more details on the interface. +.Pp +The +.Fn sbuf_printf_drain +function is a drain function that will call printf, or log to the console. +The argument +.Fa arg +must be either +.Dv NULL , +or a valid pointer to a +.Vt size_t . +If +.Fa arg +is not +.Dv NULL , +the total bytes drained will be added to the value pointed to by +.Fa arg . +.Pp +The +.Fn sbuf_putbuf +function printfs the sbuf to stdout if in userland, and to the console +and log if in the kernel. +The +.Fa sbuf +must be finished before calling +.Fn sbuf_putbuf . +It does not drain the buffer or update any pointers. +.Sh NOTES +If an operation caused an +.Fa sbuf +to overflow, most subsequent operations on it will fail until the +.Fa sbuf +is finished using +.Fn sbuf_finish +or reset using +.Fn sbuf_clear , +or its position is reset to a value between 0 and one less than the +size of its storage buffer using +.Fn sbuf_setpos , +or it is reinitialized to a sufficiently short string using +.Fn sbuf_cpy . +.Pp +Drains in user-space will not always function as indicated. +While the drain function will be called immediately on overflow from +the +.Fa sbuf_putc , +.Fa sbuf_bcat , +.Fa sbuf_cat +functions, +.Fa sbuf_printf +and +.Fa sbuf_vprintf +currently have no way to determine whether there will be an overflow +until after it occurs, and cannot do a partial expansion of the format +string. +Thus when using libsbuf the buffer may be extended to allow completion +of a single printf call, even though a drain is attached. +.Sh RETURN VALUES +The +.Fn sbuf_new +function returns +.Dv NULL +if it failed to allocate a storage buffer, and a pointer to the new +.Fa sbuf +otherwise. +.Pp +The +.Fn sbuf_setpos +function returns \-1 if +.Fa pos +was invalid, and zero otherwise. +.Pp +The +.Fn sbuf_bcat , +.Fn sbuf_cat , +.Fn sbuf_cpy , +.Fn sbuf_printf , +.Fn sbuf_putc , +and +.Fn sbuf_trim +functions +all return \-1 if the buffer overflowed, and zero otherwise. +.Pp +The +.Fn sbuf_error +function returns a non-zero value if the buffer has an overflow or +drain error, and zero otherwise. +.Pp +The +.Fn sbuf_len +function returns \-1 if the buffer overflowed. +.Pp +The +.Fn sbuf_copyin +function +returns \-1 if copying string from userland failed, and number of bytes +copied otherwise. +.Pp +The +.Fn sbuf_end_section +function returns the section length or \-1 if the buffer has an error. +.Pp +The +.Fn sbuf_finish 9 +function (the kernel version) returns +.Er ENOMEM +if the sbuf overflowed before being finished, +or returns the error code from the drain if one is attached. +.Pp +The +.Fn sbuf_finish 3 +function (the userland version) +will return zero for success and \-1 and set errno on error. +.Sh EXAMPLES +.Bd -literal -compact +#include +#include + +struct sbuf *sb; + +sb = sbuf_new_auto(); +sbuf_cat(sb, "Customers found:\en"); +TAILQ_FOREACH(foo, &foolist, list) { + sbuf_printf(sb, " %4d %s\en", foo->index, foo->name); + sbuf_printf(sb, " Address: %s\en", foo->address); + sbuf_printf(sb, " Zip: %s\en", foo->zipcode); +} +if (sbuf_finish(sb) != 0) /* Check for any and all errors */ + err(1, "Could not generate message"); +transmit_msg(sbuf_data(sb), sbuf_len(sb)); +sbuf_delete(sb); +.Ed +.Sh SEE ALSO +.Xr hexdump 3 , +.Xr printf 3 , +.Xr strcat 3 , +.Xr strcpy 3 , +.Xr copyin 9 , +.Xr copyinstr 9 , +.Xr printf 9 +.Sh HISTORY +The +.Nm +family of functions first appeared in +.Fx 4.4 . +.Sh AUTHORS +.An -nosplit +The +.Nm +family of functions was designed by +.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org +and implemented by +.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . +Additional improvements were suggested by +.An Justin T. Gibbs Aq Mt gibbs@FreeBSD.org . +Auto-extend support added by +.An Kelly Yancey Aq Mt kbyanc@FreeBSD.org . +Drain functionality added by +.An Matthew Fleming Aq Mt mdf@FreeBSD.org . +.Pp +This manual page was written by +.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . diff --git a/static/freebsd/man9/scheduler.9 b/static/freebsd/man9/scheduler.9 new file mode 100644 index 00000000..31f0309a --- /dev/null +++ b/static/freebsd/man9/scheduler.9 @@ -0,0 +1,273 @@ +.\" Copyright (c) 2000-2001 John H. Baldwin +.\" +.\" 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 November 3, 2000 +.Dt SCHEDULER 9 +.Os +.Sh NAME +.Nm curpriority_cmp , +.Nm maybe_resched , +.Nm resetpriority , +.Nm roundrobin , +.Nm roundrobin_interval , +.Nm sched_setup , +.Nm schedclock , +.Nm schedcpu , +.Nm setrunnable , +.Nm updatepri +.Nd perform round-robin scheduling of runnable processes +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.Ft int +.Fn curpriority_cmp "struct proc *p" +.Ft void +.Fn maybe_resched "struct thread *td" +.Ft void +.Fn propagate_priority "struct proc *p" +.Ft void +.Fn resetpriority "struct ksegrp *kg" +.Ft void +.Fn roundrobin "void *arg" +.Ft int +.Fn roundrobin_interval "void" +.Ft void +.Fn sched_setup "void *dummy" +.Ft void +.Fn schedclock "struct thread *td" +.Ft void +.Fn schedcpu "void *arg" +.Ft void +.Fn setrunnable "struct thread *td" +.Ft void +.Fn updatepri "struct thread *td" +.Sh DESCRIPTION +Each process has three different priorities stored in +.Vt "struct proc" : +.Va p_usrpri , +.Va p_nativepri , +and +.Va p_priority . +.Pp +The +.Va p_usrpri +member is the user priority of the process calculated from a process' +estimated CPU time and nice level. +.Pp +The +.Va p_nativepri +member is the saved priority used by +.Fn propagate_priority . +When a process obtains a mutex, its priority is saved in +.Va p_nativepri . +While it holds the mutex, the process's priority may be bumped by another +process that blocks on the mutex. +When the process releases the mutex, then its priority is restored to the +priority saved in +.Va p_nativepri . +.Pp +The +.Va p_priority +member is the actual priority of the process and is used to determine what +.Xr runqueue 9 +it runs on, for example. +.Pp +The +.Fn curpriority_cmp +function compares the cached priority of the currently running process with +process +.Fa p . +If the currently running process has a higher priority, then it will return +a value less than zero. +If the current process has a lower priority, then it will return a value +greater than zero. +If the current process has the same priority as +.Fa p , +then +.Fn curpriority_cmp +will return zero. +The cached priority of the currently running process is updated when a process +resumes from +.Xr tsleep 9 +or returns to userland in +.Fn userret +and is stored in the private variable +.Va curpriority . +.Pp +The +.Fn maybe_resched +function compares the priorities of the current thread and +.Fa td . +If +.Fa td +has a higher priority than the current thread, then a context switch is +needed, and +.Dv KEF_NEEDRESCHED +is set. +.Pp +The +.Fn propagate_priority +looks at the process that owns the mutex +.Fa p +is blocked on. +That process's priority is bumped to the priority of +.Fa p +if needed. +If the process is currently running, then the function returns. +If the process is on a +.Xr runqueue 9 , +then the process is moved to the appropriate +.Xr runqueue 9 +for its new priority. +If the process is blocked on a mutex, its position in the list of +processes blocked on the mutex in question is updated to reflect its new +priority. +Then, the function repeats the procedure using the process that owns the +mutex just encountered. +Note that a process's priorities are only bumped to the priority of the +original process +.Fa p , +not to the priority of the previously encountered process. +.Pp +The +.Fn resetpriority +function recomputes the user priority of the ksegrp +.Fa kg +(stored in +.Va kg_user_pri ) +and calls +.Fn maybe_resched +to force a reschedule of each thread in the group if needed. +.Pp +The +.Fn roundrobin +function is used as a +.Xr timeout 9 +function to force a reschedule every +.Va sched_quantum +ticks. +.Pp +The +.Fn roundrobin_interval +function simply returns the number of clock ticks in between reschedules +triggered by +.Fn roundrobin . +Thus, all it does is return the current value of +.Va sched_quantum . +.Pp +The +.Fn sched_setup +function is a +.Xr SYSINIT 9 +that is called to start the callout driven scheduler functions. +It just calls the +.Fn roundrobin +and +.Fn schedcpu +functions for the first time. +After the initial call, the two functions will propagate themselves by +registering their callout event again at the completion of the respective +function. +.Pp +The +.Fn schedclock +function is called by +.Fn statclock +to adjust the priority of the currently running thread's ksegrp. +It updates the group's estimated CPU time and then adjusts the priority via +.Fn resetpriority . +.Pp +The +.Fn schedcpu +function updates all process priorities. +First, it updates statistics that track how long processes have been in various +process states. +Secondly, it updates the estimated CPU time for the current process such +that about 90% of the CPU usage is forgotten in 5 * load average seconds. +For example, if the load average is 2.00, +then at least 90% of the estimated CPU time for the process should be based +on the amount of CPU time the process has had in the last 10 seconds. +It then recomputes the priority of the process and moves it to the +appropriate +.Xr runqueue 9 +if necessary. +Thirdly, it updates the %CPU estimate used by utilities such as +.Xr ps 1 +and +.Xr top 1 +so that 95% of the CPU usage is forgotten in 60 seconds. +Once all process priorities have been updated, +.Fn schedcpu +calls +.Fn vmmeter +to update various other statistics including the load average. +Finally, it schedules itself to run again in +.Va hz +clock ticks. +.Pp +The +.Fn setrunnable +function is used to change a process's state to be runnable. +The process is placed on a +.Xr runqueue 9 +if needed, and the swapper process is woken up and told to swap the process in +if the process is swapped out. +If the process has been asleep for at least one run of +.Fn schedcpu , +then +.Fn updatepri +is used to adjust the priority of the process. +.Pp +The +.Fn updatepri +function is used to adjust the priority of a process that has been asleep. +It retroactively decays the estimated CPU time of the process for each +.Fn schedcpu +event that the process was asleep. +Finally, it calls +.Fn resetpriority +to adjust the priority of the process. +.Sh SEE ALSO +.Xr mi_switch 9 , +.Xr runqueue 9 , +.Xr sleepqueue 9 , +.Xr tsleep 9 +.Sh BUGS +The +.Va curpriority +variable really should be per-CPU. +In addition, +.Fn maybe_resched +should compare the priority of +.Fa chk +with that of each CPU, and then send an IPI to the processor with the lowest +priority to trigger a reschedule if needed. +.Pp +Priority propagation is broken and is thus disabled by default. +The +.Va p_nativepri +variable is only updated if a process does not obtain a sleep mutex on the +first try. +Also, if a process obtains more than one sleep mutex in this manner, and +had its priority bumped in between, then +.Va p_nativepri +will be clobbered. diff --git a/static/freebsd/man9/securelevel_gt.9 b/static/freebsd/man9/securelevel_gt.9 new file mode 100644 index 00000000..4ba7dfe9 --- /dev/null +++ b/static/freebsd/man9/securelevel_gt.9 @@ -0,0 +1,70 @@ +.\" +.\" Copyright (c) 2000 Christian S.J. Peron +.\" 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. 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 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 June 2, 2007 +.Dt SECURELEVEL_GT 9 +.Os +.Sh NAME +.Nm securelevel_gt , securelevel_ge +.Nd test active securelevel +.Sh SYNOPSIS +.In sys/types.h +.In sys/proc.h +.Ft int +.Fn securelevel_gt "struct ucred *cr" "int level" +.Ft int +.Fn securelevel_ge "struct ucred *cr" "int level" +.Sh DESCRIPTION +These functions test the active security level against the given +.Fa level . +If the calling credential +.Fa cr +was imprisoned by the +.Xr jail 2 +system call, and has a +different security level set than the host environment, +the security level with the highest value is used. +.Pp +The +.Fn securelevel_gt +function +will evaluate whether or not the active security +level is greater than the supplied +.Fa level . +.Pp +The +.Fn securelevel_ge +function +will evaluate whether or not the active security +level is greater than or equal to the supplied +.Fa level . +.Sh RETURN VALUES +These functions return +.Er EPERM +if condition evaluated to true, and 0 otherwise. +.Sh SEE ALSO +.Xr securelevel 7 diff --git a/static/freebsd/man9/selrecord.9 b/static/freebsd/man9/selrecord.9 new file mode 100644 index 00000000..685079da --- /dev/null +++ b/static/freebsd/man9/selrecord.9 @@ -0,0 +1,124 @@ +.\" +.\" Copyright (C) 2002 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 August 25, 2011 +.Dt SELRECORD 9 +.Os +.Sh NAME +.Nm seldrain , +.Nm selrecord , +.Nm selwakeup +.Nd "record and wakeup select requests" +.Sh SYNOPSIS +.In sys/param.h +.In sys/selinfo.h +.Ft void +.Fn seldrain "struct selinfo *sip" +.Ft void +.Fn selrecord "struct thread *td" "struct selinfo *sip" +.Ft void +.Fn selwakeup "struct selinfo *sip" +.Sh DESCRIPTION +.Fn seldrain , +.Fn selrecord +and +.Fn selwakeup +are the three central functions used by +.Xr select 2 , +.Xr poll 2 +and the objects that are being selected on. +They handle the task of recording which threads are waiting on which objects +and the waking of the proper threads when an event of interest occurs on an +object. +.Pp +.Fn selrecord +records that the calling thread is interested in events related to a given +object. +If another thread is already waiting on the object a collision will be flagged +in +.Fa sip +which will be later dealt with by +.Fn selwakeup . +.Pp +.Fn selrecord +acquires and releases +.Va sellock . +.Pp +.Fn selwakeup +is called by the underlying object handling code in order to notify any waiting +threads that an event of interest has occurred. +If a collision has occurred, +.Fn selwakeup +will increment +.Va nselcoll , +and broadcast on the global cv in order to wake all waiting threads so that +they can handle it. +If the thread waiting on the object is not currently sleeping or the wait +channel is not +.Va selwait , +.Fn selwakeup +will clear the +.Dv TDF_SELECT +flag which should be noted by +.Xr select 2 +and +.Xr poll 2 +when they wake up. +.Pp +.Fn seldrain +will flush the waiters queue on a specified object before its +destruction. +The object handling code must ensure that +.Fa *sip +cannot be used once +.Fn seldrain +has been called. +.Pp +The contents of +.Fa *sip +must be zeroed, such as by softc initialization, before any call to +.Fn selrecord +or +.Fn selwakeup , +otherwise a panic may occur. +.Fn selwakeup +acquires and releases +.Va sellock +and may acquire and release +.Va sched_lock . +.Fn seldrain +could usually be just a wrapper for +.Fn selwakeup , +but consumers should not generally rely on this feature. +.Sh SEE ALSO +.Xr poll 2 , +.Xr select 2 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Chad David Aq Mt davidc@FreeBSD.org +and +.An Alfred Perlstein Aq Mt alfred@FreeBSD.org . diff --git a/static/freebsd/man9/sema.9 b/static/freebsd/man9/sema.9 new file mode 100644 index 00000000..5c1b9e0e --- /dev/null +++ b/static/freebsd/man9/sema.9 @@ -0,0 +1,130 @@ +.\" +.\" Copyright (C) 2001 Jason Evans . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 February 1, 2006 +.Dt SEMA 9 +.Os +.Sh NAME +.Nm sema , +.Nm sema_init , +.Nm sema_destroy , +.Nm sema_post , +.Nm sema_wait , +.Nm sema_timedwait , +.Nm sema_trywait , +.Nm sema_value +.Nd kernel counting semaphore +.Sh SYNOPSIS +.In sys/types.h +.In sys/lock.h +.In sys/sema.h +.Ft void +.Fn sema_init "struct sema *sema" "int value" "const char *description" +.Ft void +.Fn sema_destroy "struct sema *sema" +.Ft void +.Fn sema_post "struct sema *sema" +.Ft void +.Fn sema_wait "struct sema *sema" +.Ft int +.Fn sema_timedwait "struct sema *sema" "int timo" +.Ft int +.Fn sema_trywait "struct sema *sema" +.Ft int +.Fn sema_value "struct sema *sema" +.Sh DESCRIPTION +Counting semaphores provide a mechanism for synchronizing access to a pool of +resources. +Unlike mutexes, semaphores do not have the concept of an owner, so they can also +be useful in situations where one thread needs to acquire a resource, and +another thread needs to release it. +Each semaphore has an integer value associated with it. +Posting (incrementing) always succeeds, but waiting (decrementing) can only +successfully complete if the resulting value of the semaphore is greater than or +equal to zero. +.Pp +Semaphores should not be used where mutexes and condition variables +will suffice. +Semaphores are a more complex synchronization mechanism than mutexes and +condition variables, and are not as efficient. +.Pp +Semaphores are created with +.Fn sema_init , +where +.Fa sema +is a pointer to space for a +.Vt "struct sema" , +.Fa value +is the initial value of the semaphore, and +.Fa description +is a pointer to a null-terminated character string that describes the semaphore. +Semaphores are destroyed with +.Fn sema_destroy . +A semaphore is posted (incremented) with +.Fn sema_post . +A semaphore is waited on (decremented) with +.Fn sema_wait , +.Fn sema_timedwait , +or +.Fn sema_trywait . +The +.Fa timo +argument to +.Fn sema_timedwait +specifies the minimum time in ticks to wait before returning with failure. +.Fn sema_value +is used to read the current value of the semaphore. +.Sh RETURN VALUES +The +.Fn sema_value +function +returns the current value of the semaphore. +.Pp +If decrementing the semaphore would result in its value being negative, +.Fn sema_trywait +returns 0 to indicate failure. +Otherwise, a non-zero value is returned to indicate success. +.Pp +The +.Fn sema_timedwait +function +returns 0 if waiting on the semaphore succeeded; otherwise a +non-zero error code is returned. +.Sh ERRORS +The +.Fn sema_timedwait +function will fail if: +.Bl -tag -width Er +.It Bq Er EWOULDBLOCK +Timeout expired. +.El +.Sh SEE ALSO +.Xr condvar 9 , +.Xr locking 9 , +.Xr mtx_pool 9 , +.Xr mutex 9 , +.Xr rwlock 9 , +.Xr sx 9 diff --git a/static/freebsd/man9/seqc.9 b/static/freebsd/man9/seqc.9 new file mode 100644 index 00000000..b1e59b6b --- /dev/null +++ b/static/freebsd/man9/seqc.9 @@ -0,0 +1,137 @@ +.\" +.\" Copyright (C) 2019 Mariusz Zaborski +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 29, 2019 +.Dt SEQC 9 +.Os +.Sh NAME +.Nm seqc_consistent , +.Nm seqc_read , +.Nm seqc_write_begin , +.Nm seqc_write_end +.Nd "lockless read algorithm" +.Sh SYNOPSIS +.In sys/seqc.h +.Ft void +.Fn seqc_write_begin "seqc_t *seqcp" +.Ft void +.Fn seqc_write_end "seqc_t *seqcp" +.Ft seqc_t +.Fn seqc_read "seqc_t *seqcp" +.Ft seqc_t +.Fn seqc_consistent "const seqc_t *seqcp" "seqc_t oldseqc" +.Sh DESCRIPTION +The +.Nm seqc +allows zero or more readers and zero or one writer to concurrently access +an object, providing a consistent snapshot of the object for readers. +No mutual exclusion between readers and writers is required, +but readers may be starved indefinitely by writers. +.Pp +The functions +.Fn seqc_write_begin +and +.Fn seqc_write_end +are used to create a transaction for writer, and notify the readers that the +object will be modified. +.Pp +The +.Fn seqc_read +function returns the current sequence number. +If a writer has started a transaction, this function will spin until the +transaction has ended. +.Pp +The +.Fn seqc_consistent +function compares the sequence number with a previously fetched value. +The +.Fa oldseqc +variable should contain a sequence number from the beginning of read +transaction. +.Pp +The reader at the end of a transaction checks if the sequence number has +changed. +If the sequence number didn't change the object wasn't modified, and fetched +variables are valid. +If the sequence number changed the object was modified and the fetch should be +repeated. +In case when sequence number is odd the object change is in progress and the +reader will wait until the write will the sequence number will become even. +.Sh EXAMPLES +The following example for a writer changes the +.Va var1 +and +.Va var2 +variables in the +.Va obj +structure: +.Bd -literal +lock_exclusive(&obj->lock); +seqc_write_begin(&obj->seqc); +obj->var1 = 1; +obj->var2 = 2; +seqc_write_end(&obj->seqc); +unlock_exclusive(&obj->lock); +.Ed +.Pp +The following example for a reader reads the +.Va var1 +and +.Va var2 +variables from the +.Va obj +structure. +In the case where the sequence number was changed it restarts the whole process. +.Bd -literal +int var1, var2; +seqc_t seqc; + +for (;;) { + seqc = seqc_read(&obj->seqc); + var1 = obj->var1; + var2 = obj->var2; + if (seqc_consistent(&obj->seqc, seqc)) + break; +} +.Ed +.Sh AUTHORS +The +.Nm seqc +functions was implemented by +.An Mateusz Guzik Aq Mt mjg@FreeBSD.org . +This manual page was written by +.An Mariusz Zaborski Aq Mt oshogbo@FreeBSD.org . +.Sh CAVEATS +There is no guarantee of progress for readers. +In case when there are a lot of writers the reader can be starved. +This concern may be solved by returning error after a few attempts. +.Pp +Theoretically if reading takes a very long time, and when there are many writers +the counter may overflow and wrap around to the same value. +In that case the reader will not notice that the object was changed. +Given that this needs 4 billion transactional writes across a single contended +reader, it is unlikely to ever happen. +This could be avoided by extending the interface to allow 64-bit counters. diff --git a/static/freebsd/man9/sf_buf.9 b/static/freebsd/man9/sf_buf.9 new file mode 100644 index 00000000..e99e4841 --- /dev/null +++ b/static/freebsd/man9/sf_buf.9 @@ -0,0 +1,140 @@ +.\" +.\" Copyright (c) 2007 Seccuris Inc. +.\" All rights reserved. +.\" +.\" This documentation was written by Robert N. M. Watson under contract to +.\" Seccuris Inc. +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 28, 2007 +.Dt SF_BUF 9 +.Os +.Sh NAME +.Nm sf_buf +.Nd manage temporary kernel address space mapping for memory pages +.Sh SYNOPSIS +.In sys/sf_buf.h +.Ft struct sf_buf * +.Fn sf_buf_alloc "struct vm_page *m" "int flags" +.Ft void +.Fn sf_buf_free "struct sf_buf *sf" +.Ft vm_offset_t +.Fn sf_buf_kva "struct sf_buf *sf" +.Ft struct vm_page * +.Fn sf_buf_page "struct sf_buf *sf" +.Sh DESCRIPTION +The +.Nm +interface, historically the +.Xr sendfile 2 +buffer interface, allows kernel subsystems to manage temporary kernel address +space mappings for physical memory pages. +On systems with a direct memory map region (allowing all physical pages to be +visible in the kernel address space at all times), the +.Vt "struct sf_buf" +will point to an address in the direct map region; on systems without a +direct memory map region, the +.Vt "struct sf_buf" +will manage a temporary kernel address space mapping valid for the lifetime +of the +.Vt "struct sf_buf". +.Pp +Call +.Fn sf_buf_alloc +to allocate a +.Vt "struct sf_buf" +for a physical memory page. +.Fn sf_buf_alloc +is not responsible for arranging for the page to be present in physical +memory; the caller should already have arranged for the page to be wired, +i.e., by calling +.Xr vm_page_wire 9 . +Several flags may be passed to +.Fn sf_buf_alloc : +.Bl -tag -width SFB_CPUPRIVATE +.It Dv SFB_CATCH +Cause +.Fn sf_buf_alloc +to abort and return +.Dv NULL +if a signal is received waiting for a +.Vt "struct sf_buf" +to become available. +.It Dv SFB_NOWAIT +Cause +.Fn sf_buf_alloc +to return +.Dv NULL +rather than sleeping if a +.Vt "struct sf_buf" +is not immediately available. +.It Dv SFB_CPUPRIVATE +Cause +.Fn sf_buf_alloc +to only arrange that the temporary mapping be valid on the current CPU, +avoiding unnecessary TLB shootdowns for mappings that will only be accessed +on a single CPU at a time. +The caller must ensure that accesses to the virtual address occur only on the +CPU from which +.Fn sf_buf_alloc +was invoked, perhaps by using +.Fn sched_pin . +.El +.Pp +Call +.Fn sf_buf_kva +to return a kernel mapped address for the page. +.Pp +Call +.Fn sf_buf_page +to return a pointer to the page originally passed into +.Fn sf_buf_alloc . +.Pp +Call +.Fn sf_buf_free +to release the +.Vt "struct sf_buf" +reference. +The caller is responsible for releasing any wiring they have previously +acquired on the physical page; +.Fn sf_buf_free +releases only the temporary kernel address space mapping, not the page +itself. +.Pp +Uses of this interface include managing mappings of borrowed pages from user +memory, such as in zero-copy socket I/O, or pages of memory from the buffer +cache referenced by mbuf external storage for +.Xr sendfile 2 . +.Sh SEE ALSO +.Xr sendfile 2 , +.Xr vm_page_wire 9 +.Sh AUTHORS +.An -nosplit +The +.Vt "struct sf_buf" +API was designed and implemented by +.An Alan L. Cox . +This manual page was written by +.An Robert N. M. Watson . diff --git a/static/freebsd/man9/sglist.9 b/static/freebsd/man9/sglist.9 new file mode 100644 index 00000000..f4930134 --- /dev/null +++ b/static/freebsd/man9/sglist.9 @@ -0,0 +1,612 @@ +.\" +.\" Copyright (c) 2009 Hudson River Trading LLC +.\" Written by: John H. Baldwin +.\" 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 May 25, 2021 +.Dt SGLIST 9 +.Os +.Sh NAME +.Nm sglist , +.Nm sglist_alloc , +.Nm sglist_append , +.Nm sglist_append_bio , +.Nm sglist_append_mbuf , +.Nm sglist_append_mbuf_epg , +.Nm sglist_append_phys , +.Nm sglist_append_sglist , +.Nm sglist_append_single_mbuf , +.Nm sglist_append_uio , +.Nm sglist_append_user , +.Nm sglist_append_vmpages , +.Nm sglist_build , +.Nm sglist_clone , +.Nm sglist_consume_uio , +.Nm sglist_count , +.Nm sglist_count_mbuf_epg , +.Nm sglist_count_vmpages , +.Nm sglist_free , +.Nm sglist_hold , +.Nm sglist_init , +.Nm sglist_join , +.Nm sglist_length , +.Nm sglist_reset , +.Nm sglist_slice , +.Nm sglist_split +.Nd manage a scatter/gather list of physical memory addresses +.Sh SYNOPSIS +.In sys/types.h +.In sys/sglist.h +.Ft struct sglist * +.Fn sglist_alloc "int nsegs" "int mflags" +.Ft int +.Fn sglist_append "struct sglist *sg" "void *buf" "size_t len" +.Ft int +.Fn sglist_append_bio "struct sglist *sg" "struct bio *bp" +.Ft int +.Fn sglist_append_mbuf_epg "struct sglist *sg" "struct mbuf *m" "size_t offset" "size_t len" +.Ft int +.Fn sglist_append_mbuf "struct sglist *sg" "struct mbuf *m" +.Ft int +.Fn sglist_append_phys "struct sglist *sg" "vm_paddr_t paddr" "size_t len" +.Ft int +.Fn sglist_append_sglist "struct sglist *sg" "struct sglist *source" "size_t offset" "size_t len" +.Ft int +.Fn sglist_append_single_mbuf "struct sglist *sg" "struct mbuf *m" +.Ft int +.Fn sglist_append_uio "struct sglist *sg" "struct uio *uio" +.Ft int +.Fn sglist_append_user "struct sglist *sg" "void *buf" "size_t len" "struct thread *td" +.Ft int +.Fn sglist_append_vmpages "struct sglist *sg" "vm_page_t *m" "size_t pgoff" "size_t len" +.Ft struct sglist * +.Fn sglist_build "void *buf" "size_t len" "int mflags" +.Ft struct sglist * +.Fn sglist_clone "struct sglist *sg" "int mflags" +.Ft int +.Fn sglist_consume_uio "struct sglist *sg" "struct uio *uio" "size_t resid" +.Ft int +.Fn sglist_count "void *buf" "size_t len" +.Ft int +.Fn sglist_count_mbuf_epg "struct mbuf *m" "size_t offset" "size_t len" +.Ft int +.Fn sglist_count_vmpages "vm_page_t *m" "size_t pgoff" "size_t len" +.Ft void +.Fn sglist_free "struct sglist *sg" +.Ft struct sglist * +.Fn sglist_hold "struct sglist *sg" +.Ft void +.Fn sglist_init "struct sglist *sg" "int maxsegs" "struct sglist_seg *segs" +.Ft int +.Fn sglist_join "struct sglist *first" "struct sglist *second" +.Ft size_t +.Fn sglist_length "struct sglist *sg" +.Ft void +.Fn sglist_reset "struct sglist *sg" +.Ft int +.Fn sglist_slice "struct sglist *original" "struct sglist **slice" "size_t offset" "size_t length" "int mflags" +.Ft int +.Fn sglist_split "struct sglist *original" "struct sglist **head" "size_t length" "int mflags" +.Sh DESCRIPTION +The +.Nm +API manages physical address ranges. +Each list contains one or more elements. +Each element contains a starting physical address and a length. +Scatter/gather lists are read-only while they are shared. +If one wishes to alter an existing scatter/gather list and does not hold the +sole reference to the list, +then one should create a new list instead of modifying the existing list. +.Pp +Each scatter/gather list object contains a reference count. +New lists are created with a single reference. +New references are obtained by calling +.Nm sglist_hold +and are released by calling +.Nm sglist_free . +.Ss Allocating and Initializing Lists +Each +.Nm +object consists of a header structure and a variable-length array of +scatter/gather list elements. +The +.Nm sglist_alloc +function allocates a new list that contains a header and +.Fa nsegs +scatter/gather list elements. +The +.Fa mflags +argument can be set to either +.Dv M_NOWAIT +or +.Dv M_WAITOK . +.Pp +The +.Nm sglist_count +function returns the number of scatter/gather list elements needed to describe +the physical address ranges mapped by a single kernel virtual address range. +The kernel virtual address range starts at +.Fa buf +and is +.Fa len +bytes long. +.Pp +The +.Nm sglist_count_mbuf_epg +function returns the number of scatter/gather list elements needed to describe +the external multipage mbuf buffer +.Fa m . +The ranges start at an offset of +.Fa offset +relative to the start of the buffer and is +.Fa len +bytes long. +.Pp +The +.Nm sglist_count_vmpages +function returns the number of scatter/gather list elements needed to describe +the physical address ranges of a buffer backed by an array of virtual memory +pages +.Fa m . +The buffer starts at an offset of +.Fa pgoff +bytes relative to the first page and is +.Fa len +bytes long. +.Pp +The +.Nm sglist_build +function allocates a new scatter/gather list object that describes the physical +address ranges mapped by a single kernel virtual address range. +The kernel virtual address range starts at +.Fa buf +and is +.Fa len +bytes long. +The +.Fa mflags +argument can be set to either +.Dv M_NOWAIT +or +.Dv M_WAITOK . +.Pp +The +.Nm sglist_clone +function returns a copy of an existing scatter/gather list object +.Fa sg . +The +.Fa mflags +argument can be set to either +.Dv M_NOWAIT +or +.Dv M_WAITOK . +This can be used to obtain a private copy of a scatter/gather list before +modifying it. +.Pp +The +.Nm sglist_init +function initializes a scatter/gather list header. +The header is pointed to by +.Fa sg +and is initialized to manage an array of +.Fa maxsegs +scatter/gather list elements pointed to by +.Fa segs . +This can be used to initialize a scatter/gather list header whose storage +is not provided by +.Nm sglist_alloc . +In that case, the caller should not call +.Nm sglist_free +to release its own reference and is responsible for ensuring all other +references to the list are dropped before it releases the storage for +.Fa sg +and +.Fa segs . +.Ss Constructing Scatter/Gather Lists +The +.Nm +API provides several routines for building a scatter/gather list to describe +one or more objects. +Specifically, the +.Nm sglist_append +family of routines can be used to append the physical address ranges described +by an object to the end of a scatter/gather list. +All of these routines return 0 on success or an error on failure. +If a request to append an address range to a scatter/gather list fails, +the scatter/gather list will remain unchanged. +.Pp +The +.Nm sglist_append +function appends the physical address ranges described by a single kernel +virtual address range to the scatter/gather list +.Fa sg . +The kernel virtual address range starts at +.Fa buf +and is +.Fa len +bytes long. +.Pp +The +.Nm sglist_append_bio +function appends the physical address ranges described by a single bio +.Fa bp +to the scatter/gather list +.Fa sg . +.Pp +The +.Nm sglist_append_mbuf_epg +function appends the physical address ranges described by the +external multipage +.Xr mbuf 9 +buffer +.Fa ext_pgs +to the scatter/gather list +.Fa sg . +The physical address ranges start at offset +.Fa offset +within +.Fa ext_pgs +and continue for +.Fa len +bytes. +Note that unlike +.Nm sglist_append_mbuf , +.Nm sglist_append_mbuf_epg +only adds ranges for a single mbuf, +not an entire mbuf chain. +.Pp +The +.Nm sglist_append_mbuf +function appends the physical address ranges described by an entire mbuf +chain +.Fa m +to the scatter/gather list +.Fa sg . +.Pp +The +.Nm sglist_append_single_mbuf +function appends the physical address ranges described by a single mbuf +.Fa m +to the scatter/gather list +.Fa sg . +.Pp +The +.Nm sglist_append_phys +function appends a single physical address range to the scatter/gather list +.Fa sg . +The physical address range starts at +.Fa paddr +and is +.Fa len +bytes long. +.Pp +The +.Nm sglist_append_sglist +function appends physical address ranges described by the scatter/gather list +.Fa source +to the scatter/gather list +.Fa sg . +The physical address ranges start at offset +.Fa offset +within +.Fa source +and continue for +.Fa len +bytes. +.Pp +The +.Nm sglist_append_uio +function appends the physical address ranges described by a +.Xr uio 9 +object to the scatter/gather list +.Fa sg . +Note that it is the caller's responsibility to ensure that the pages backing +the I/O request are wired for the lifetime of +.Fa sg . +Note also that this routine does not modify +.Fa uio . +.Pp +The +.Nm sglist_append_user +function appends the physical address ranges described by a single user +virtual address range to the scatter/gather list +.Fa sg . +The user virtual address range is relative to the address space of the thread +.Fa td . +It starts at +.Fa buf +and is +.Fa len +bytes long. +Note that it is the caller's responsibility to ensure that the pages backing +the user buffer are wired for the lifetime of +.Fa sg . +.Pp +The +.Nm sglist_append_vmpages +function appends the physical address ranges of a buffer backed by an array +of virtual memory pages +.Fa m . +The buffer starts at an offset of +.Fa pgoff +bytes relative to the first page and is +.Fa len +bytes long. +.Pp +The +.Nm sglist_consume_uio +function is a variation of +.Nm sglist_append_uio . +As with +.Nm sglist_append_uio , +it appends the physical address ranges described by +.Fa uio +to the scatter/gather list +.Fa sg . +Unlike +.Nm sglist_append_uio , +however, +.Nm sglist_consume_uio +modifies the I/O request to indicate that the appended address ranges have +been processed similar to calling +.Xr uiomove 9 . +This routine will only append ranges that describe up to +.Fa resid +total bytes in length. +If the available segments in the scatter/gather list are exhausted before +.Fa resid +bytes are processed, +then the +.Fa uio +structure will be updated to reflect the actual number of bytes processed, +and +.Nm sglist_consume_io +will return zero to indicate success. +In effect, this function will perform partial reads or writes. +The caller can compare the +.Fa uio_resid +member of +.Fa uio +before and after calling +.Nm sglist_consume_uio +to determine the actual number of bytes processed. +.Ss Manipulating Scatter/Gather Lists +The +.Nm sglist_join +function appends physical address ranges from the scatter/gather list +.Fa second +onto +.Fa first +and then resets +.Fa second +to an empty list. +It returns zero on success or an error on failure. +.Pp +The +.Nm sglist_split +function splits an existing scatter/gather list into two lists. +The first +.Fa length +bytes described by the list +.Fa original +are moved to a new list +.Fa *head . +If +.Fa original +describes a total address range that is smaller than +.Fa length +bytes, +then all of the address ranges will be moved to the new list at +.Fa *head +and +.Fa original +will be an empty list. +The caller may supply an existing scatter/gather list in +.Fa *head . +If so, the list must be empty. +Otherwise, the caller may set +.Fa *head +to +.Dv NULL +in which case a new scatter/gather list will be allocated. +In that case, +.Fa mflags +may be set to either +.Dv M_NOWAIT +or +.Dv M_WAITOK . +Note that since the +.Fa original +list is modified by this call, it must be a private list with no other +references. +The +.Nm sglist_split +function returns zero on success or an error on failure. +.Pp +The +.Nm sglist_slice +function generates a new scatter/gather list from a sub-range of an existing +scatter/gather list +.Fa original . +The sub-range to extract is specified by the +.Fa offset +and +.Fa length +parameters. +The new scatter/gather list is stored in +.Fa *slice . +As with +.Fa head +for +.Nm sglist_join , +the caller may either provide an empty scatter/gather list, +or it may set +.Fa *slice +to +.Dv NULL +in which case +.Nm sglist_slice +will allocate a new list subject to +.Fa mflags . +Unlike +.Nm sglist_split , +.Nm sglist_slice +does not modify +.Fa original +and does not require it to be a private list. +The +.Nm sglist_split +function returns zero on success or an error on failure. +.Ss Miscellaneous Routines +The +.Nm sglist_reset +function clears the scatter/gather list +.Fa sg +so that it no longer maps any address ranges. +This can allow reuse of a single scatter/gather list object for multiple +requests. +.Pp +The +.Nm sglist_length +function returns the total length of the physical address ranges described +by the scatter/gather list +.Fa sg . +.Sh RETURN VALUES +The +.Nm sglist_alloc , +.Nm sglist_build , +and +.Nm sglist_clone +functions return a new scatter/gather list on success or +.Dv NULL +on failure. +.Pp +The +.Nm sglist_append +family of functions and the +.Nm sglist_consume_uio , +.Nm sglist_join , +.Nm sglist_slice , +and +.Nm sglist_split +functions return zero on success or an error on failure. +.Pp +The +.Nm sglist_count +family of +functions return a count of scatter/gather list elements. +.Pp +The +.Nm sglist_length +function returns a count of address space described by a scatter/gather list +in bytes. +.Sh ERRORS +The +.Nm sglist_append +functions return the following errors on failure: +.Bl -tag -width Er +.It Bq Er EINVAL +The scatter/gather list has zero segments. +.It Bq Er EFBIG +There are not enough available segments in the scatter/gather list to append +the specified physical address ranges. +.El +.Pp +The +.Nm sglist_consume_uio +function returns the following error on failure: +.Bl -tag -width Er +.It Bq Er EINVAL +The scatter/gather list has zero segments. +.El +.Pp +The +.Nm sglist_join +function returns the following error on failure: +.Bl -tag -width Er +.It Bq Er EFBIG +There are not enough available segments in the scatter/gather list +.Fa first +to append the physical address ranges from +.Fa second . +.El +.Pp +The +.Nm sglist_slice +function returns the following errors on failure: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa original +scatter/gather list does not describe enough address space to cover the +requested sub-range. +.It Bq Er EINVAL +The caller-supplied scatter/gather list in +.Fa *slice +is not empty. +.It Bq Er ENOMEM +An attempt to allocate a new scatter/gather list with +.Dv M_NOWAIT +set in +.Fa mflags +failed. +.It Bq Er EFBIG +There are not enough available segments in the caller-supplied scatter/gather +list in +.Fa *slice +to describe the requested physical address ranges. +.El +.Pp +The +.Nm sglist_split +function returns the following errors on failure: +.Bl -tag -width Er +.It Bq Er EDOOFUS +The +.Fa original +scatter/gather list has more than one reference. +.It Bq Er EINVAL +The caller-supplied scatter/gather list in +.Fa *head +is not empty. +.It Bq Er ENOMEM +An attempt to allocate a new scatter/gather list with +.Dv M_NOWAIT +set in +.Fa mflags +failed. +.It Bq Er EFBIG +There are not enough available segments in the caller-supplied scatter/gather +list in +.Fa *head +to describe the requested physical address ranges. +.El +.Sh SEE ALSO +.Xr g_bio 9 , +.Xr malloc 9 , +.Xr mbuf 9 , +.Xr uio 9 +.Sh HISTORY +This API was first introduced in +.Fx 8.0 . diff --git a/static/freebsd/man9/shm_map.9 b/static/freebsd/man9/shm_map.9 new file mode 100644 index 00000000..d5d8cc03 --- /dev/null +++ b/static/freebsd/man9/shm_map.9 @@ -0,0 +1,184 @@ +.\" +.\" Copyright (c) 2011 Hudson River Trading LLC +.\" Written by: John H. Baldwin +.\" 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 December 14, 2011 +.Dt SHM_MAP 9 +.Os +.Sh NAME +.Nm shm_map , shm_unmap +.Nd "map shared memory objects into the kernel's address space" +.Sh SYNOPSIS +.In sys/types.h +.In sys/mman.h +.Ft int +.Fn shm_map "struct file *fp" "size_t size" "off_t offset" "void **memp" +.Ft int +.Fn shm_unmap "struct file *fp" "void *mem" "size_t size" +.Sh DESCRIPTION +The +.Fn shm_map +and +.Fn shm_unmap +functions provide an API for mapping shared memory objects into the kernel. +Shared memory objects are created by +.Xr shm_open 2 . +These objects can then be passed into the kernel via file descriptors. +.Pp +A shared memory object cannot be shrunk while it is mapped into the kernel. +This is to avoid invalidating any pages that may be wired into the kernel's +address space. +Shared memory objects can still be grown while mapped into the kernel. +.Pp +To simplify the accounting needed to enforce the above requirement, +callers of this API are required to unmap the entire region mapped by +.Fn shm_map +when calling +.Fn shm_unmap . +Unmapping only a portion of the region is not permitted. +.Pp +The +.Fn shm_map +function locates the shared memory object associated with the open file +.Fa fp . +It maps the region of that object described by +.Fa offset +and +.Fa size +into the kernel's address space. +If it succeeds, +.Fa *memp +will be set to the start of the mapping. +All pages for the range will be wired into memory upon successful return. +.Pp +The +.Fn shm_unmap +function unmaps a region previously mapped by +.Fn shm_map . +The +.Fa mem +argument should match the value previously returned in +.Fa *memp , +and the +.Fa size +argument should match the value passed to +.Fn shm_map . +.Pp +Note that +.Fn shm_map +will not hold an extra reference on the open file +.Fa fp +for the lifetime of the mapping. +Instead, +the calling code is required to do this if it wishes to use +.Fn shm_unmap +on the region in the future. +.Sh RETURN VALUES +The +.Fn shm_map +and +.Fn shm_unmap +functions return zero on success or an error on failure. +.Sh EXAMPLES +The following function accepts a file descriptor for a shared memory +object. +It maps the first sixteen kilobytes of the object into the kernel, +performs some work on that address, +and then unmaps the address before returning. +.Bd -literal -offset indent +int +shm_example(int fd) +{ + struct file *fp; + void *mem; + int error; + + error = fget(curthread, fd, CAP_MMAP, &fp); + if (error) + return (error); + error = shm_map(fp, 16384, 0, &mem); + if (error) { + fdrop(fp, curthread); + return (error); + } + + /* Do something with 'mem'. */ + + error = shm_unmap(fp, mem, 16384); + fdrop(fp, curthread); + return (error); +} +.Ed +.Sh ERRORS +The +.Fn shm_map +function returns the following errors on failure: +.Bl -tag -width Er +.It Bq Er EINVAL +The open file +.Fa fp +is not a shared memory object. +.It Bq Er EINVAL +The requested region described by +.Fa offset +and +.Fa size +extends beyond the end of the shared memory object. +.It Bq Er ENOMEM +Insufficient address space was available. +.It Bq Er EACCES +The shared memory object could not be mapped due to a protection error. +.It Bq Er EINVAL +The shared memory object could not be mapped due to some other VM error. +.El +.Pp +The +.Fn shm_unmap +function returns the following errors on failure: +.Bl -tag -width Er +.It Bq Er EINVAL +The open file +.Fa fp +is not a shared memory object. +.It Bq Er EINVAL +The address range described by +.Fa mem +and +.Fa size +is not a valid address range. +.It Bq Er EINVAL +The address range described by +.Fa mem +and +.Fa size +is not backed by the shared memory object associated with the open file +.Fa fp , +or the address range does not cover the entire mapping of the object. +.El +.Sh SEE ALSO +.Xr shm_open 2 +.Sh HISTORY +This API was first introduced in +.Fx 10.0 . diff --git a/static/freebsd/man9/signal.9 b/static/freebsd/man9/signal.9 new file mode 100644 index 00000000..a41ceea4 --- /dev/null +++ b/static/freebsd/man9/signal.9 @@ -0,0 +1,435 @@ +.\" +.\" Copyright (C) 2002 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 14, 2023 +.Dt SIGNAL 9 +.Os +.Sh NAME +.Nm signal , +.Nm SIGADDSET , +.Nm SIGDELSET , +.Nm SETEMPTYSET , +.Nm SIGFILLSET , +.Nm SIGISMEMBER , +.Nm SIGISEMPTY , +.Nm SIGNOTEMPTY , +.Nm SIGSETEQ , +.Nm SIGSETNEQ , +.Nm SIGSETOR , +.Nm SIGSETAND , +.Nm SIGSETNAND , +.Nm SIGSETCANTMASK , +.Nm SIG_STOPSIGMASK , +.Nm SIG_CONTSIGMASK , +.Nm SIGPENDING , +.Nm cursig , +.Nm execsigs , +.Nm issignal , +.Nm killproc , +.Nm pgsigio , +.Nm postsig , +.Nm sigexit , +.Nm siginit , +.Nm signotify , +.Nm trapsignal +.Nd "kernel signal functions" +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.In sys/signalvar.h +.Ft void +.Fn SIGADDSET "sigset_t set" "int signo" +.Ft void +.Fn SIGDELSET "sigset_t set" "int signo" +.Ft void +.Fn SIGEMPTYSET "sigset_t set" +.Ft void +.Fn SIGFILLSET "sigset_t set" +.Ft int +.Fn SIGISMEMBER "sigset_t set" "int signo" +.Ft int +.Fn SIGISEMPTY "sigset_t set" +.Ft int +.Fn SIGNOTEMPTY "sigset_t set" +.Ft int +.Fn SIGSETEQ "sigset_t set1" "sigset_t set2" +.Ft int +.Fn SIGSETNEQ "sigset_t set1" "sigset_t set2" +.Ft void +.Fn SIGSETOR "sigset_t set1" "sigset_t set2" +.Ft void +.Fn SIGSETAND "sigset_t set1" "sigset_t set2" +.Ft void +.Fn SIGSETNAND "sigset_t set1" "sigset_t set2" +.Ft void +.Fn SIG_CANTMASK "sigset_t set" +.Ft void +.Fn SIG_STOPSIGMASK "sigset_t set" +.Ft void +.Fn SIG_CONTSIGMASK "sigset_t set" +.Ft int +.Fn SIGPENDING "struct proc *p" +.Ft int +.Fn cursig "struct thread *td" +.Ft void +.Fn execsigs "struct proc *p" +.Ft int +.Fn issignal "struct thread *td" +.Ft void +.Fn killproc "struct proc *p" "char *why" +.Ft void +.Fn pgsigio "struct sigio **sigiop" "int sig" "int checkctty" +.Ft void +.Fn postsig "int sig" +.Ft void +.Fn sigexit "struct thread *td" "int signum" +.Ft void +.Fn siginit "struct proc *p" +.Ft void +.Fn signotify "struct thread *td" +.Ft void +.Fn trapsignal "struct thread *td" "int sig" "u_long code" +.Sh DESCRIPTION +The +.Fn SIGADDSET +macro adds +.Fa signo +to +.Fa set . +No effort is made to ensure that +.Fa signo +is a valid signal number. +.Pp +The +.Fn SIGDELSET +macro removes +.Fa signo +from +.Fa set . +No effort is made to ensure that +.Fa signo +is a valid signal number. +.Pp +The +.Fn SIGEMPTYSET +macro clears all signals in +.Fa set . +.Pp +The +.Fn SIGFILLSET +macro sets all signals in +.Fa set . +.Pp +The +.Fn SIGISMEMBER +macro determines if +.Fa signo +is set in +.Fa set . +.Pp +The +.Fn SIGISEMPTY +macro determines if +.Fa set +does not have any signals set. +.Pp +The +.Fn SIGNOTEMPTY +macro determines if +.Fa set +has any signals set. +.Pp +The +.Fn SIGSETEQ +macro determines if two signal sets are equal; that is, the same signals +are set in both. +.Pp +The +.Fn SIGSETNEQ +macro determines if two signal sets differ; that is, if any signal set in +one is not set in the other. +.Pp +The +.Fn SIGSETOR +macro ORs the signals set in +.Fa set2 +into +.Fa set1 . +.Pp +The +.Fn SIGSETAND +macro ANDs the signals set in +.Fa set2 +into +.Fa set1 . +.Pp +The +.Fn SIGSETNAND +macro NANDs the signals set in +.Fa set2 +into +.Fa set1 . +.Pp +The +.Fn SIG_CANTMASK +macro clears the +.Dv SIGKILL +and +.Dv SIGSTOP +signals from +.Fa set . +These two signals cannot be blocked or caught and +.Fn SIG_CANTMASK +is used in code where signals are manipulated to ensure this policy +is enforced. +.Pp +The +.Fn SIG_STOPSIGMASK +macro clears the +.Dv SIGSTOP , +.Dv SIGTSTP , +.Dv SIGTTIN , +and +.Dv SIGTTOU +signals from +.Fa set . +.Fn SIG_STOPSIGMASK +is used to clear stop signals when a process is waiting for a child to +exit or exec, and when a process is continuing after having been +suspended. +.Pp +The +.Fn SIG_CONTSIGMASK +macro clears the +.Dv SIGCONT +signal from +.Fa set . +.Fn SIG_CONTSIGMASK +is called when a process is stopped. +.Pp +The +.Fn SIGPENDING +macro determines if the given process has any pending signals that are +not masked. +If the process has a pending signal and the process is currently being +traced, +.Fn SIGPENDING +will return true even if the signal is masked. +.Pp +The +.Fn cursig +function returns the signal number that should be delivered to process +.Fa td->td_proc . +If there are no signals pending, zero is returned. +.Pp +The +.Fn execsigs +function resets the signal set and signal stack of a process in preparation +for an +.Xr execve 2 . +The process lock for +.Fa p +must be held before +.Fn execsigs +is called. +.Pp +The +.Fn issignal +function determines if there are any pending signals for process +.Fa td->td_proc +that should be caught, or cause this process to terminate or interrupt its +current system call. +If process +.Fa td->td_proc +is currently being traced, ignored signals will be handled and the process +is always stopped. +Stop signals are handled and cleared right away by +.Fn issignal +unless the process is a member of an orphaned process group and the stop +signal originated from a TTY. +The process spin lock for +.Fa td->td_proc +may be acquired and released. +The +.Vt sigacts +structure +.Fa td->td_proc->p_sigacts +must be locked before calling +.Fn issignal +and may be released and reacquired during the call. +The process lock for +.Fa td->td_proc +must be acquired before calling +.Fn issignal +and may be released and reacquired during the call. +Default signal actions are not taken for system processes and init. +.Pp +The +.Fn killproc +function delivers +.Dv SIGKILL +to +.Fa p . +.Fa why +is logged as the reason +.Em why +the process was killed. +.Pp +The +.Fn pgsigio +function sends the signal +.Fa sig +to the process or process group +.Fa sigiop->sio_pgid . +If +.Fa checkctty +is non-zero, the signal is only delivered to processes in the process group +that have a controlling terminal. +If +.Fa sigiop->sio_pgid +is for a process (> 0), the lock for +.Fa sigiop->sio_proc +is acquired and released. +If +.Fa sigiop->sio_pgid +is for a process group (< 0), the process group lock for +.Fa sigiop->sio_pgrp +is acquired and released. +The lock +.Va sigio_lock +is acquired and released. +.Pp +The +.Fn postsig +function handles the actual delivery of the signal +.Fa sig . +.Fn postsig +is called from +.Fn ast +after the kernel has been notified that a signal should be delivered +(via a call to +.Fn signotify , +which causes the flag +.Dv PS_NEEDSIGCHK +to be set). +The process lock for process that owns +.Va curthread +must be held before +.Fn postsig +is called, and the current process cannot be 0. +The lock for the +.Va p_sigacts +field of the current process must be held before +.Fn postsig +is called, and may be released and reacquired. +.Pp +The +.Fn sigexit +function causes the process that owns +.Fa td +to exit with a return value of signal number +.Fa sig . +If required, the process will dump core. +The process lock for the process that owns +.Fa td +must be held before +.Fn sigexit +is called. +.Pp +The +.Fn siginit +function is called during system initialization to cause every signal with +a default property of +.Dv SA_IGNORE +(except +.Dv SIGCONT ) +to be ignored by +.Fa p . +The process lock for +.Fa p +is acquired and released, as is the lock for sigacts structure +.Fa p->p_sigacts . +The only process that +.Fn siginit +is ever called for +is +.Va proc0 . +.Pp +The +.Fn signotify +function flags that there are unmasked signals pending that +.Fn ast +should handle. +The process lock for process +.Fa td->td_proc +must be held before +.Fn signotify +is called, and the thread lock is acquired and released. +.Pp +The +.Fn trapsignal +function sends a signal that is the result of a trap to process +.Fa td->td_proc . +If the process is not being traced and the signal can be delivered +immediately, +.Fn trapsignal +will deliver it directly; otherwise, +.Fn trapsignal +will call +.Xr psignal 9 +to cause the signal to be delivered. +The process lock for +.Fa td->td_proc +is acquired and released. +The lock for the +.Va p_sigacts +field of +.Fa td->td_proc +is acquired and released. +.Sh RETURN VALUES +The +.Fn SIGISMEMBER , +.Fn SIGISEMPTY , +.Fn SIGNOTEMPTY , +.Fn SIGSETEQ , +.Fn SIGSETNEQ , +and +.Fn SIGPENDING +macros all return non-zero (true) if the condition they are checking +is found to be true; otherwise, zero (false) is returned. +.Pp +The +.Fn cursig +function returns either a valid signal number or zero. +.Pp +.Fn issignal +returns either a valid signal number or zero. +.Sh SEE ALSO +.Xr pgsignal 9 , +.Xr psignal 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@FreeBSD.org . diff --git a/static/freebsd/man9/sleep.9 b/static/freebsd/man9/sleep.9 new file mode 100644 index 00000000..10ad743c --- /dev/null +++ b/static/freebsd/man9/sleep.9 @@ -0,0 +1,421 @@ +.\" +.\" Copyright (c) 1996 Joerg Wunsch +.\" +.\" 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 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 June 19, 2019 +.Dt SLEEP 9 +.Os +.Sh NAME +.Nm msleep , +.Nm msleep_sbt , +.Nm msleep_spin , +.Nm msleep_spin_sbt , +.Nm pause , +.Nm pause_sig , +.Nm pause_sbt , +.Nm tsleep , +.Nm tsleep_sbt , +.Nm wakeup , +.Nm wakeup_one , +.Nm wakeup_any +.Nd wait for events +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.In sys/proc.h +.Ft int +.Fn msleep "const void *chan" "struct mtx *mtx" "int priority" "const char *wmesg" "int timo" +.Ft int +.Fn msleep_sbt "const void *chan" "struct mtx *mtx" "int priority" \ +"const char *wmesg" "sbintime_t sbt" "sbintime_t pr" "int flags" +.Ft int +.Fn msleep_spin "const void *chan" "struct mtx *mtx" "const char *wmesg" "int timo" +.Ft int +.Fn msleep_spin_sbt "const void *chan" "struct mtx *mtx" "const char *wmesg" \ +"sbintime_t sbt" "sbintime_t pr" "int flags" +.Ft int +.Fn pause "const char *wmesg" "int timo" +.Ft int +.Fn pause_sig "const char *wmesg" "int timo" +.Ft int +.Fn pause_sbt "const char *wmesg" "sbintime_t sbt" "sbintime_t pr" \ + "int flags" +.Ft int +.Fn tsleep "const void *chan" "int priority" "const char *wmesg" "int timo" +.Ft int +.Fn tsleep_sbt "const void *chan" "int priority" "const char *wmesg" \ +"sbintime_t sbt" "sbintime_t pr" "int flags" +.Ft void +.Fn wakeup "const void *chan" +.Ft void +.Fn wakeup_one "const void *chan" +.Ft void +.Fn wakeup_any "const void *chan" +.Sh DESCRIPTION +The functions +.Fn tsleep , +.Fn msleep , +.Fn msleep_spin , +.Fn pause , +.Fn pause_sig , +.Fn pause_sbt , +.Fn wakeup , +.Fn wakeup_one , +and +.Fn wakeup_any +handle event-based thread blocking. +If a thread must wait for an +external event, it is put to sleep by +.Fn tsleep , +.Fn msleep , +.Fn msleep_spin , +.Fn pause , +.Fn pause_sig , +or +.Fn pause_sbt . +Threads may also wait using one of the locking primitive sleep routines +.Xr mtx_sleep 9 , +.Xr rw_sleep 9 , +or +.Xr sx_sleep 9 . +.Pp +The parameter +.Fa chan +is an arbitrary address that uniquely identifies the event on which +the thread is being put to sleep. +All threads sleeping on a single +.Fa chan +are woken up later by +.Fn wakeup , +often called from inside an interrupt routine, to indicate that the +resource the thread was blocking on is available now. +.Pp +The parameter +.Fa priority +specifies a new priority for the thread as well as some optional flags. +If the new priority is not 0, +then the thread will be made +runnable with the specified +.Fa priority +when it resumes. +.Dv PZERO +should never be used, as it is for compatibility only. +A new priority of 0 means to use the thread's current priority when +it is made runnable again. +.Pp +If +.Fa priority +includes the +.Dv PCATCH +flag, pending signals are allowed to interrupt the sleep, otherwise +pending signals are ignored during the sleep. +If +.Dv PCATCH +is set and a signal becomes pending, +.Er ERESTART +is returned if the current system call should be restarted if +possible, and +.Er EINTR +is returned if the system call should be interrupted by the signal +(return +.Er EINTR ) . +.Pp +The parameter +.Fa wmesg +is a string describing the sleep condition for tools like +.Xr ps 1 . +Due to the limited space of those programs to display arbitrary strings, +this message should not be longer than 6 characters. +.Pp +The parameter +.Fa timo +specifies a timeout for the sleep. +If +.Fa timo +is not 0, +then the thread will sleep for at most +.Fa timo No / Va hz +seconds. +If the timeout expires, +then the sleep function will return +.Er EWOULDBLOCK . +.Pp +.Fn msleep_sbt , +.Fn msleep_spin_sbt , +.Fn pause_sbt +and +.Fn tsleep_sbt +functions take +.Fa sbt +parameter instead of +.Fa timo . +It allows the caller to specify relative or absolute wakeup time with higher resolution +in form of +.Vt sbintime_t . +The parameter +.Fa pr +allows the caller to specify wanted absolute event precision. +The parameter +.Fa flags +allows the caller to pass additional +.Fn callout_reset_sbt +flags. +.Pp +Several of the sleep functions including +.Fn msleep , +.Fn msleep_spin , +and the locking primitive sleep routines specify an additional lock +parameter. +The lock will be released before sleeping and reacquired +before the sleep routine returns. +If +.Fa priority +includes the +.Dv PDROP +flag, then +the lock will not be reacquired before returning. +The lock is used to ensure that a condition can be checked atomically, +and that the current thread can be suspended without missing a +change to the condition, or an associated wakeup. +In addition, all of the sleep routines will fully drop the +.Va Giant +mutex +(even if recursed) +while the thread is suspended and will reacquire the +.Va Giant +mutex before the function returns. +Note that the +.Va Giant +mutex may be specified as the lock to drop. +In that case, however, the +.Dv PDROP +flag is not allowed. +.Pp +To avoid lost wakeups, +either a lock should be used to protect against races, +or a timeout should be specified to place an upper bound on the delay due +to a lost wakeup. +As a result, +the +.Fn tsleep +function should only be invoked with a timeout of 0 when the +.Va Giant +mutex is held. +.Pp +The +.Fn msleep +function requires that +.Fa mtx +reference a default, i.e. non-spin, mutex. +Its use is deprecated in favor of +.Xr mtx_sleep 9 +which provides identical behavior. +.Pp +The +.Fn msleep_spin +function requires that +.Fa mtx +reference a spin mutex. +The +.Fn msleep_spin +function does not accept a +.Fa priority +parameter and thus does not support changing the current thread's priority, +the +.Dv PDROP +flag, +or catching signals via the +.Dv PCATCH +flag. +.Pp +The +.Fn pause +function is a wrapper around +.Fn tsleep +that suspends execution of the current thread for the indicated timeout. +The thread can not be awakened early by signals or calls to +.Fn wakeup , +.Fn wakeup_one +or +.Fn wakeup_any . +The +.Fn pause_sig +function is a variant of +.Fn pause +which can be awakened early by signals. +.Pp +The +.Fn wakeup_one +function makes the first highest priority thread in the queue that is +sleeping on the parameter +.Fa chan +runnable. +This reduces the load when a large number of threads are sleeping on +the same address, but only one of them can actually do any useful work +when made runnable. +.Pp +Due to the way it works, the +.Fn wakeup_one +function requires that only related threads sleep on a specific +.Fa chan +address. +It is the programmer's responsibility to choose a unique +.Fa chan +value. +The older +.Fn wakeup +function did not require this, though it was never good practice +for threads to share a +.Fa chan +value. +When converting from +.Fn wakeup +to +.Fn wakeup_one , +pay particular attention to ensure that no other threads wait on the +same +.Fa chan . +.Pp +The +.Fn wakeup_any +function is similar to +.Fn wakeup_one , +except that it makes runnable last thread on the queue (sleeping less), +ignoring fairness. +It can be used when threads sleeping on the +.Fa chan +are known to be identical and there is no reason to be fair. +.Pp +If the timeout given by +.Fa timo +or +.Fa sbt +is based on an absolute real-time clock value, +then the thread should copy the global +.Va rtc_generation +into its +.Va td_rtcgen +member before reading the RTC. +If the real-time clock is adjusted, these functions will set +.Va td_rtcgen +to zero and return zero. +The caller should reconsider its orientation with the new RTC value. +.Sh RETURN VALUES +When awakened by a call to +.Fn wakeup +or +.Fn wakeup_one , +if a signal is pending and +.Dv PCATCH +is specified, +a non-zero error code is returned. +If the thread is awakened by a call to +.Fn wakeup +or +.Fn wakeup_one , +the +.Fn msleep , +.Fn msleep_spin , +.Fn tsleep , +and locking primitive sleep functions return 0. +Zero can also be returned when the real-time clock is adjusted; +see above regarding +.Va td_rtcgen . +Otherwise, a non-zero error code is returned. +.Sh ERRORS +.Fn msleep , +.Fn msleep_spin , +.Fn tsleep , +and the locking primitive sleep functions will fail if: +.Bl -tag -width Er +.It Bq Er EINTR +The +.Dv PCATCH +flag was specified, a signal was caught, and the system call should be +interrupted. +.It Bq Er ERESTART +The +.Dv PCATCH +flag was specified, a signal was caught, and the system call should be +restarted. +.It Bq Er EWOULDBLOCK +A non-zero timeout was specified and the timeout expired. +.El +.Sh SEE ALSO +.Xr ps 1 , +.Xr callout 9 , +.Xr locking 9 , +.Xr malloc 9 , +.Xr mi_switch 9 , +.Xr mtx_sleep 9 , +.Xr rw_sleep 9 , +.Xr sx_sleep 9 +.Sh HISTORY +The functions +.Fn sleep +and +.Fn wakeup +were present in +.At v1 . +They were probably also present in the preceding +PDP-7 version of +.Ux . +They were the basic process synchronization model. +.Pp +The +.Fn tsleep +function appeared in +.Bx 4.4 +and added the parameters +.Fa wmesg +and +.Fa timo . +The +.Fn sleep +function was removed in +.Fx 2.2 . +The +.Fn wakeup_one +function appeared in +.Fx 2.2 . +The +.Fn msleep +function appeared in +.Fx 5.0 , +and the +.Fn msleep_spin +function appeared in +.Fx 6.2 . +The +.Fn pause +function appeared in +.Fx 7.0 . +The +.Fn pause_sig +function appeared in +.Fx 12.0 . +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An J\(:org Wunsch Aq Mt joerg@FreeBSD.org . diff --git a/static/freebsd/man9/sleepqueue.9 b/static/freebsd/man9/sleepqueue.9 new file mode 100644 index 00000000..6502ce37 --- /dev/null +++ b/static/freebsd/man9/sleepqueue.9 @@ -0,0 +1,388 @@ +.\" Copyright (c) 2000-2004 John H. Baldwin +.\" +.\" 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 June 19, 2019 +.Dt SLEEPQUEUE 9 +.Os +.Sh NAME +.Nm init_sleepqueues , +.Nm sleepq_abort , +.Nm sleepq_add , +.Nm sleepq_alloc , +.Nm sleepq_broadcast , +.Nm sleepq_free , +.Nm sleepq_lock , +.Nm sleepq_lookup , +.Nm sleepq_release , +.Nm sleepq_remove , +.Nm sleepq_signal , +.Nm sleepq_set_timeout , +.Nm sleepq_set_timeout_sbt , +.Nm sleepq_sleepcnt , +.Nm sleepq_timedwait , +.Nm sleepq_timedwait_sig , +.Nm sleepq_type , +.Nm sleepq_wait , +.Nm sleepq_wait_sig +.Nd manage the queues of sleeping threads +.Sh SYNOPSIS +.In sys/param.h +.In sys/sleepqueue.h +.Ft void +.Fn init_sleepqueues "void" +.Ft int +.Fn sleepq_abort "struct thread *td" +.Ft void +.Fn sleepq_add "const void *wchan" "struct lock_object *lock" "const char *wmesg" "int flags" "int queue" +.Ft struct sleepqueue * +.Fn sleepq_alloc "void" +.Ft int +.Fn sleepq_broadcast "const void *wchan" "int flags" "int pri" "int queue" +.Ft void +.Fn sleepq_free "struct sleepqueue *sq" +.Ft struct sleepqueue * +.Fn sleepq_lookup "const void *wchan" +.Ft void +.Fn sleepq_lock "const void *wchan" +.Ft void +.Fn sleepq_release "const void *wchan" +.Ft void +.Fn sleepq_remove "struct thread *td" "const void *wchan" +.Ft int +.Fn sleepq_signal "const void *wchan" "int flags" "int pri" "int queue" +.Ft void +.Fn sleepq_set_timeout "const void *wchan" "int timo" +.Ft void +.Fn sleepq_set_timeout_sbt "const void *wchan" "sbintime_t sbt" \ +"sbintime_t pr" "int flags" +.Ft u_int +.Fn sleepq_sleepcnt "const void *wchan" "int queue" +.Ft int +.Fn sleepq_timedwait "const void *wchan" "int pri" +.Ft int +.Fn sleepq_timedwait_sig "const void *wchan" "int pri" +.Ft int +.Fn sleepq_type "const void *wchan" +.Ft void +.Fn sleepq_wait "const void *wchan" "int pri" +.Ft int +.Fn sleepq_wait_sig "const void *wchan" "int pri" +.Sh DESCRIPTION +Sleep queues provide a mechanism for suspending execution of a thread until +some condition is met. +Each queue is associated with a specific wait channel when it is active, +and only one queue may be associated with a wait channel at any given point +in time. +The implementation of each wait channel splits its sleepqueue into 2 sub-queues +in order to enable some optimizations on threads' wakeups. +An active queue holds a list of threads that are blocked on the associated +wait channel. +Threads that are not blocked on a wait channel have an associated inactive +sleep queue. +When a thread blocks on a wait channel it donates its inactive sleep queue +to the wait channel. +When a thread is resumed, +the wait channel that it was blocked on gives it an inactive sleep queue for +later use. +.Pp +The +.Fn sleepq_alloc +function allocates an inactive sleep queue and is used to assign a +sleep queue to a thread during thread creation. +The +.Fn sleepq_free +function frees the resources associated with an inactive sleep queue and is +used to free a queue during thread destruction. +.Pp +Active sleep queues are stored in a hash table hashed on the addresses pointed +to by wait channels. +Each bucket in the hash table contains a sleep queue chain. +A sleep queue chain contains a spin mutex and a list of sleep queues that hash +to that specific chain. +Active sleep queues are protected by their chain's spin mutex. +The +.Fn init_sleepqueues +function initializes the hash table of sleep queue chains. +.Pp +The +.Fn sleepq_lock +function locks the sleep queue chain associated with wait channel +.Fa wchan . +.Pp +The +.Fn sleepq_lookup +returns a pointer to the currently active sleep queue for that wait +channel associated with +.Fa wchan +or +.Dv NULL +if there is no active sleep queue associated with +argument +.Fa wchan . +It requires the sleep queue chain associated with +.Fa wchan +to have been locked by a prior call to +.Fn sleepq_lock . +.Pp +The +.Fn sleepq_release +function unlocks the sleep queue chain associated with +.Fn wchan +and is primarily useful when aborting a pending sleep request before one of +the wait functions is called. +.Pp +The +.Fn sleepq_add +function places the current thread on the sleep queue associated with the +wait channel +.Fa wchan . +The sleep queue chain associated with argument +.Fa wchan +must be locked by a prior call to +.Fn sleepq_lock +when this function is called. +If a lock is specified via the +.Fa lock +argument, and if the kernel was compiled with +.Cd "options INVARIANTS" , +then the sleep queue code will perform extra checks to ensure that +the lock is used by all threads sleeping on +.Fa wchan . +The +.Fa wmesg +parameter should be a short description of +.Fa wchan . +The +.Fa flags +parameter is a bitmask consisting of the type of sleep queue being slept on +and zero or more optional flags. +The +.Fa queue +parameter specifies the sub-queue, in which the contending thread will be +inserted. +.Pp +There are currently three types of sleep queues: +.Pp +.Bl -tag -width ".Dv SLEEPQ_CONDVAR" -compact +.It Dv SLEEPQ_CONDVAR +A sleep queue used to implement condition variables. +.It Dv SLEEPQ_SLEEP +A sleep queue used to implement +.Xr sleep 9 , +.Xr wakeup 9 +and +.Xr wakeup_one 9 . +.It Dv SLEEPQ_PAUSE +A sleep queue used to implement +.Xr pause 9 . +.El +.Pp +There are currently two optional flag: +.Pp +.Bl -tag -width ".Dv SLEEPQ_INTERRUPTIBLE" -compact +.It Dv SLEEPQ_INTERRUPTIBLE +The current thread is entering an interruptible sleep. +.El +.Bl -tag -width ".Dv SLEEPQ_STOP_ON_BDRY" -compact +.It Dv SLEEPQ_STOP_ON_BDRY +When thread is entering an interruptible sleep, do not stop it upon +arrival of stop action, like +.Dv SIGSTOP . +Wake it up instead. +.El +.Pp +A timeout on the sleep may be specified by calling +.Fn sleepq_set_timeout +after +.Fn sleepq_add . +The +.Fa wchan +parameter should be the same value from the preceding call to +.Fn sleepq_add , +and the sleep queue chain associated with +.Fa wchan +must have been locked by a prior call to +.Fn sleepq_lock . +The +.Fa timo +parameter should specify the timeout value in ticks. +.Pp +.Fn sleepq_set_timeout_sbt +function takes +.Fa sbt +argument instead of +.Fa timo . +It allows to specify relative or absolute wakeup time with higher resolution +in form of +.Vt sbintime_t . +The parameter +.Fa pr +allows to specify wanted absolute event precision. +The parameter +.Fa flags +allows to pass additional +.Fn callout_reset_sbt +flags. +.Pp +Once the thread is ready to suspend, +one of the wait functions is called to put the current thread to sleep +until it is awakened and to context switch to another thread. +The +.Fn sleepq_wait +function is used for non-interruptible sleeps that do not have a timeout. +The +.Fn sleepq_timedwait +function is used for non-interruptible sleeps that have had a timeout set via +.Fn sleepq_set_timeout . +The +.Fn sleepq_wait_sig +function is used for interruptible sleeps that do not have a timeout. +The +.Fn sleepq_timedwait_sig +function is used for interruptible sleeps that do have a timeout set. +The +.Fa wchan +argument to all of the wait functions is the wait channel being slept +on. +The sleep queue chain associated with argument +.Fa wchan +needs to have been locked with a prior call to +.Fn sleepq_lock . +The +.Fa pri +argument is used to set the priority of the thread when it is awakened. +If it is set to zero, the thread's priority is left alone. +.Pp +When the thread is resumed, +the wait functions return a non-zero value if the thread was awakened due to +an interrupt other than a signal or a timeout. +If the sleep timed out, then +.Er EWOULDBLOCK +is returned. +If the sleep was interrupted by something other than a signal, +then some other return value will be returned. +.Pp +A sleeping thread is normally resumed by the +.Fn sleepq_broadcast +and +.Fn sleepq_signal +functions. +The +.Fn sleepq_signal +function awakens the highest priority thread sleeping on a wait channel +(if SLEEPQ_UNFAIR flag is set, thread that went to sleep recently) while +.Fn sleepq_broadcast +awakens all of the threads sleeping on a wait channel. +The +.Fa wchan +argument specifics which wait channel to awaken. +The +.Fa flags +argument must match the sleep queue type contained in the +.Fa flags +argument passed to +.Fn sleepq_add +by the threads sleeping on the wait channel. +If the +.Fa pri +argument does not equal \-1, +then each thread that is awakened will have its priority raised to +.Fa pri +if it has a lower priority. +The sleep queue chain associated with argument +.Fa wchan +must be locked by a prior call to +.Fn sleepq_lock +before calling any of these functions. +The +.Fa queue +argument specifies the sub-queue, from which threads need to be woken up. +.Pp +A thread in an interruptible sleep can be interrupted by another thread via +the +.Fn sleepq_abort +function. +The +.Fa td +argument specifies the thread to interrupt. +An individual thread can also be awakened from sleeping on a specific wait +channel via the +.Fn sleepq_remove +function. +The +.Fa td +argument specifies the thread to awaken and the +.Fa wchan +argument specifies the wait channel to awaken it from. +If the thread +.Fa td +is not blocked on the wait channel +.Fa wchan +then this function will not do anything, +even if the thread is asleep on a different wait channel. +This function should only be used if one of the other functions above is not +sufficient. +One possible use is waking up a specific thread from a widely shared sleep +channel. +.Pp +The +.Fn sleepq_sleepcnt +function offer a simple way to retrieve the number of threads sleeping for +the specified +.Fa queue , +given a +.Fa wchan . +.Pp +The +.Fn sleepq_type +function returns the type of +.Fa wchan +associated to a sleepqueue. +.Pp +The +.Fn sleepq_abort , +.Fn sleepq_broadcast , +and +.Fn sleepq_signal +functions all return a boolean value. +If the return value is true, +then at least one thread was resumed that is currently swapped out. +The caller is responsible for awakening the scheduler process so that the +resumed thread will be swapped back in. +This is done by calling the +.Fn kick_proc0 +function after releasing the sleep queue chain lock via a call to +.Fn sleepq_release . +.Pp +The sleep queue interface is currently used to implement the +.Xr sleep 9 +and +.Xr condvar 9 +interfaces. +Almost all other code in the kernel should use one of those interfaces rather +than manipulating sleep queues directly. +.Sh SEE ALSO +.Xr callout 9 , +.Xr condvar 9 , +.Xr runqueue 9 , +.Xr scheduler 9 , +.Xr sleep 9 diff --git a/static/freebsd/man9/smr.9 b/static/freebsd/man9/smr.9 new file mode 100644 index 00000000..32ef313c --- /dev/null +++ b/static/freebsd/man9/smr.9 @@ -0,0 +1,294 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2023 The FreeBSD Foundation +.\" +.\" This documentation was written by Mark Johnston +.\" under sponsorship from the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 17, 2023 +.Dt SMR 9 +.Os +.Sh NAME +.Nm smr +.Nd safe memory reclamation for lock-free data structures +.Sh SYNOPSIS +.In sys/smr.h +.Ft smr_seq_t +.Fo smr_advance +.Fa "smr_t smr" +.Fc +.Ft smr_t +.Fo smr_create +.Fa "const char *name" +.Fc +.Ft void +.Fo smr_destroy +.Fa "smr_t smr" +.Fc +.Ft void +.Fo smr_enter +.Fa "smr_t smr" +.Fc +.Ft void +.Fo smr_exit +.Fa "smr_t smr" +.Fc +.Ft bool +.Fo smr_poll +.Fa "smr_t smr" +.Fa "smr_seq_t goal" +.Fa "bool wait" +.Fc +.Ft void +.Fo smr_synchronize +.Fa "smr_t smr" +.Fc +.Ft void +.Fo smr_wait +.Fa "smr_t smr" +.Fa "smr_seq_t goal" +.Fc +.Sh DESCRIPTION +Safe Memory Reclamation (SMR) is a facility which enables the implementation of +memory-safe lock-free data structures. +In typical usage, read accesses to an SMR-protected data structure, such as a +hash table or tree, are performed in a +.Dq read section +consisting of code bracketed by +.Fn smr_enter +and +.Fn smr_exit +calls, while mutations of the data structure are serialized by a traditional +mutex such as +.Xr mutex 9 . +In contrast with reader-writer locks such as +.Xr rwlock 9 , +.Xr rmlock 9 , +and +.Xr sx 9 , +SMR allows readers and writers to access the data structure concurrently. +Readers can always enter a read section immediately +.Po +.Fn smr_enter +never blocks +.Pc , +so mutations do not introduce read latency. +Furthermore, +.Fn smr_enter +and +.Fn smr_exit +operate only on per-CPU data and thus avoid some of the performance problems +inherent in the implementation of traditional reader-writer mutexes. +SMR can therefore be a useful building block for data structures which are +accessed frequently but are only rarely modified. +.Pp +Note that any SMR-protected data structure must be implemented carefully such +that operations behave correctly in the absence of mutual exclusion between +readers and writers. +The data structure must be designed to be lock-free; SMR merely facilitates +the implementation, for example by making it safe to follow dangling pointers +and by helping avoid the ABA problem. +.Pp +When shared accesses to and mutations of a data structure can proceed +concurrently, writers must take care to ensure that any items removed from the +structure are not freed and recycled while readers are accessing them in +parallel. +This requirement results in a two-phase approach to the removal of items: +first, the item is unlinked such that all pointers to the item are removed from +the structure, preventing any new readers from observing the item. +Then, the writer waits until some mechanism guarantees that no existing readers +are still accessing the item. +At that point the memory for that item can be freed and reused safely. +SMR provides this mechanism: readers may access a lock-free data structure in +between calls to the +.Fn smr_enter +and +.Fn smr_exit +functions, which together create a read section, and the +.Fn smr_advance , +.Fn smr_poll , +.Fn smr_wait , +and +.Fn smr_synchronize +functions can be used to wait for threads in read sections to finish. +All of these functions operate on a +.Ft smr_t +state block which holds both per-CPU and global state. +Readers load global state and modify per-CPU state, while writers must scan all +per-CPU states to detect active readers. +SMR is designed to amortize this cost by batching to give acceptable +performance in write-heavy workloads. +.Ss Readers +Threads enter a read section by calling +.Fn smr_enter . +Read sections should be short, and many operations are not permitted while in +a read section. +Specifically, context switching is disabled, and thus readers may not acquire +blocking mutexes such as +.Xr mutex 9 . +Another consequence of this is that the thread is pinned to the current CPU for +the duration of the read section. +Furthermore, read sections may not be nested: it is incorrect to call +.Fn smr_enter +with a given +.Ft smr_t +state block when already in a read section for that state block. +.Ss UMA Integration +To simplify the integration of SMR into consumers, the +.Xr uma 9 +kernel memory allocator provides some SMR-specified facilities. +This eliminates a good deal of complexity from the implementation of consumers +and automatically batches write operations. +.Pp +In typical usage, a UMA zone (created with the +.Dv UMA_ZONE_SMR +flag or initialized with the +.Fn uma_zone_set_smr +function) is coupled with a +.Ft smr_t +state block. +To insert an item into an SMR-protected data structure, memory is allocated +from the zone using the +.Fn uma_zalloc_smr +function. +Insertions and removals are serialized using traditional mutual exclusion +and items are freed using the +.Fn uma_zfree_smr +function. +Read-only lookup operations are performed in SMR read sections. +.Fn uma_zfree_smr +waits for all active readers which may be accessing the freed item to finish +their read sections before recycling that item's memory. +.Pp +If the zone has an associated per-item destructor, it will be invoked at some +point when no readers can be accessing a given item. +The destructor can be used to release additional resources associated with the +item. +Note however that there is no guarantee that the destructor will be invoked in +a bounded time period. +.Ss Writers +Consumers are expected to use SMR in conjunction with UMA and thus need only +make use of the +.Fn smr_enter +and +.Fn smr_exit +functions, and the SMR helper macros defined in +.Pa sys/smr_types.h . +However, an introduction to the write-side interface of SMR can be useful. +.Pp +Internally, SMR maintains a global +.Ql write sequence +number. +When entering a read section, +.Fn smr_enter +loads a copy of the write sequence and stores it in per-CPU memory, hence +.Ql observing +that value. +To exit a read section, this per-CPU memory is overwritten with an invalid +value, making the CPU inactive. +Writers perform two operations: advancing the write sequence number, and +polling all CPUs to see whether active readers have observed a given sequence +number. +These operations are performed by +.Fn smr_advance +and +.Fn smr_poll , +respectively, which do not require serialization between multiple writers. +.Pp +After a writer unlinks an item from a data structure, it increments the write +sequence number and tags the item with the new value returned by +.Fn smr_advance . +Once all CPUs have observed the new value, the writer can use +.Fn smr_poll +to deduce that no active readers have access to the unlinked item, and thus the +item is safe to recycle. +Because this pair of operations is relatively expensive, it is generally a good +idea to amortize this cost by accumulating a collection of multiple unlinked +items and tagging the entire batch with a target write sequence number. +.Pp +.Fn smr_poll +is a non-blocking operation and returns true only if all active readers are +guaranteed to have observed the target sequence number value. +.Fn smr_wait +is a variant of +.Fn smr_poll +which waits until all CPUs have observed the target sequence number value. +.Fn smr_synchronize +combines +.Fn smr_advance +with +.Fn smr_wait +to wait for all CPUs to observe a new write sequence number. +This is an expensive operation and should only be used if polling cannot be +deferred in some way. +.Ss Memory Ordering +The +.Fn smr_enter +function has acquire semantics, and the +.Fn smr_exit +function has release semantics. +The +.Fn smr_advance , +.Fn smr_poll , +.Fn smr_wait , +and +.Fn smr_synchronize +functions should not be assumed to have any guarantees with respect to memory +ordering. +In practice, some of these functions have stronger ordering semantics than +is stated here, but this is specific to the implementation and should not be +relied upon. +See +.Xr atomic 9 +for more details. +.Sh NOTES +Outside of +.Fx +the acronym SMR typically refers to a family of algorithms which enable +memory-safe read-only access to a data structure concurrent with modifications +to that data structure. +Here, SMR refers to a particular algorithm belonging to this family, as well as +its implementation in +.Fx . +See +.Pa sys/sys/smr.h +and +.Pa sys/kern/subr_smr.c +in the +.Fx +source tree for further details on the algorithm and the context. +.Pp +The acronym SMR is also used to mean "shingled magnetic recording", a +technology used to store data on hard disk drives which requires operating +system support. +These two uses of the acronym are unrelated. +.Sh SEE ALSO +.Xr atomic 9 , +.Xr locking 9 , +.Xr uma 9 +.Sh AUTHORS +The SMR algorithm and its implementation were provided by +.An Jeff Roberson Aq Mt jeff@FreeBSD.org . +This manual page was written by +.An Mark Johnston Aq Mt markj@FreeBSD.org . diff --git a/static/freebsd/man9/socket.9 b/static/freebsd/man9/socket.9 new file mode 100644 index 00000000..fb0ead0e --- /dev/null +++ b/static/freebsd/man9/socket.9 @@ -0,0 +1,643 @@ +.\"- +.\" Copyright (c) 2006 Robert N. M. Watson +.\" Copyright (c) 2014 Benjamin J. Kaduk +.\" 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 September 6, 2022 +.Dt SOCKET 9 +.Os +.Sh NAME +.Nm socket +.Nd "kernel socket interface" +.Sh SYNOPSIS +.In sys/socket.h +.In sys/socketvar.h +.Ft void +.Fn soabort "struct socket *so" +.Ft int +.Fn soaccept "struct socket *so" "struct sockaddr *nam" +.Ft int +.Fn socheckuid "struct socket *so" "uid_t uid" +.Ft int +.Fn sobind "struct socket *so" "struct sockaddr *nam" "struct thread *td" +.Ft void +.Fn soclose "struct socket *so" +.Ft int +.Fn soconnect "struct socket *so" "struct sockaddr *nam" "struct thread *td" +.Ft int +.Fo socreate +.Fa "int dom" "struct socket **aso" "int type" "int proto" +.Fa "struct ucred *cred" "struct thread *td" +.Fc +.Ft int +.Fn sodisconnect "struct socket *so" +.Ft void +.Fo sodtor_set +.Fa "struct socket *so" +.Fa "void (*func)(struct socket *)" +.Fc +.Ft struct sockaddr * +.Fn sodupsockaddr "const struct sockaddr *sa" "int mflags" +.Ft void +.Fn sofree "struct socket *so" +.Ft void +.Fn sohasoutofband "struct socket *so" +.Ft int +.Fn solisten "struct socket *so" "int backlog" "struct thread *td" +.Ft void +.Fn solisten_proto "struct socket *so" "int backlog" +.Ft int +.Fn solisten_proto_check "struct socket *so" +.Ft struct socket * +.Fn sonewconn "struct socket *head" "int connstatus" +.Ft int +.Fo sopoll +.Fa "struct socket *so" "int events" "struct ucred *active_cred" +.Fa "struct thread *td" +.Fc +.Ft int +.Fo sopoll_generic +.Fa "struct socket *so" "int events" "struct ucred *active_cred" +.Fa "struct thread *td" +.Fc +.Ft int +.Fo soreceive +.Fa "struct socket *so" "struct sockaddr **psa" "struct uio *uio" +.Fa "struct mbuf **mp0" "struct mbuf **controlp" "int *flagsp" +.Fc +.Ft int +.Fo soreceive_stream +.Fa "struct socket *so" "struct sockaddr **paddr" +.Fa "struct uio *uio" "struct mbuf **mp0" "struct mbuf **controlp" +.Fa "int *flagsp" +.Fc +.Ft int +.Fo soreceive_dgram +.Fa "struct socket *so" "struct sockaddr **paddr" +.Fa "struct uio *uio" "struct mbuf **mp0" "struct mbuf **controlp" +.Fa "int *flagsp" +.Fc +.Ft int +.Fo soreceive_generic +.Fa "struct socket *so" "struct sockaddr **paddr" +.Fa "struct uio *uio" "struct mbuf **mp0" "struct mbuf **controlp" +.Fa "int *flagsp" +.Fc +.Ft int +.Fn soreserve "struct socket *so" "u_long sndcc" "u_long rcvcc" +.Ft void +.Fn sorflush "struct socket *so" +.Ft int +.Fo sosend +.Fa "struct socket *so" "struct sockaddr *addr" "struct uio *uio" +.Fa "struct mbuf *top" "struct mbuf *control" "int flags" "struct thread *td" +.Fc +.Ft int +.Fo sosend_dgram +.Fa "struct socket *so" "struct sockaddr *addr" +.Fa "struct uio *uio" "struct mbuf *top" "struct mbuf *control" +.Fa "int flags" "struct thread *td" +.Fc +.Ft int +.Fo sosend_generic +.Fa "struct socket *so" "struct sockaddr *addr" +.Fa "struct uio *uio" "struct mbuf *top" "struct mbuf *control" +.Fa "int flags" "struct thread *td" +.Fc +.Ft int +.Fn soshutdown "struct socket *so" "int how" +.Ft void +.Fn sotoxsocket "struct socket *so" "struct xsocket *xso" +.Ft void +.Fn soupcall_clear "struct socket *so" "int which" +.Ft void +.Fo soupcall_set +.Fa "struct socket *so" "int which" +.Fa "int (*func)(struct socket *, void *, int)" "void *arg" +.Fc +.Ft void +.Fn sowakeup "struct socket *so" "struct sockbuf *sb" +.In sys/sockopt.h +.Ft int +.Fn sosetopt "struct socket *so" "struct sockopt *sopt" +.Ft int +.Fn sogetopt "struct socket *so" "struct sockopt *sopt" +.Ft int +.Fn sooptcopyin "struct sockopt *sopt" "void *buf" "size_t len" "size_t minlen" +.Ft int +.Fn sooptcopyout "struct sockopt *sopt" "const void *buf" "size_t len" +.Sh DESCRIPTION +The kernel +.Nm +programming interface permits in-kernel consumers to interact with +local and network socket objects in a manner similar to that permitted using +the +.Xr socket 2 +user API. +These interfaces are appropriate for use by distributed file systems and +other network-aware kernel services. +While the user API operates on file descriptors, the kernel interfaces +operate directly on +.Vt "struct socket" +pointers. +Some portions of the kernel API exist only to implement the user API, +and are not expected to be used by kernel code. +The portions of the socket API used by socket consumers and +implementations of network protocols will differ; some routines +are only useful for protocol implementors. +.Pp +Except where otherwise indicated, +.Nm +functions may sleep, and are not appropriate for use in an interrupt thread +context or while holding non-sleepable kernel locks. +.Ss Creating and Destroying Sockets +A new socket may be created using +.Fn socreate . +As with +.Xr socket 2 , +arguments specify the requested domain, type, and protocol via +.Fa dom , type , +and +.Fa proto . +The socket is returned via +.Fa aso +on success. +In addition, the credential used to authorize operations associated with the +socket will be passed via +.Fa cred +(and will be cached for the lifetime of the socket), and the thread +performing the operation via +.Fa td . +.Em Warning : +authorization of the socket creation operation will be performed +using the thread credential for some protocols (such as raw sockets). +.Pp +Sockets may be closed and freed using +.Fn soclose , +which has similar semantics to +.Xr close 2 . +.Pp +In certain circumstances, it is appropriate to destroy a socket without +waiting for it to disconnect, for which +.Fn soabort +is used. +This is only appropriate for incoming connections which are in a +partially connected state. +It must be called on an unreferenced socket, by the thread which +removed the socket from its listen queue, to prevent races. +It will call into protocol code, so no socket locks may be held +over the call. +The caller of +.Fn soabort +is responsible for setting the VNET context. +The normal path to freeing a socket is +.Fn sofree , +which handles reference counting on the socket. +It should be called whenever a reference is released, and also whenever +reference flags are cleared in socket or protocol code. +Calls to +.Fn sofree +should not be made from outside the socket layer; outside callers +should use +.Fn soclose +instead. +.Ss Connections and Addresses +The +.Fn sobind +function is equivalent to the +.Xr bind 2 +system call, and binds the socket +.Fa so +to the address +.Fa nam . +The operation would be authorized using the credential on thread +.Fa td . +.Pp +The +.Fn soconnect +function is equivalent to the +.Xr connect 2 +system call, and initiates a connection on the socket +.Fa so +to the address +.Fa nam . +The operation will be authorized using the credential on thread +.Fa td . +Unlike the user system call, +.Fn soconnect +returns immediately; the caller may +.Xr msleep 9 +on +.Fa so->so_timeo +while holding the socket mutex and waiting for the +.Dv SS_ISCONNECTING +flag to clear or +.Fa so->so_error +to become non-zero. +If +.Fn soconnect +fails, the caller must manually clear the +.Dv SS_ISCONNECTING +flag. +.Pp +A call to +.Fn sodisconnect +disconnects the socket without closing it. +.Pp +The +.Fn soshutdown +function is equivalent to the +.Xr shutdown 2 +system call, and causes part or all of a connection on a socket to be closed +down. +.Pp +Sockets are transitioned from non-listening status to listening with +.Fn solisten . +.Ss Socket Options +The +.Fn sogetopt +function is equivalent to the +.Xr getsockopt 2 +system call, and retrieves a socket option on socket +.Fa so . +The +.Fn sosetopt +function is equivalent to the +.Xr setsockopt 2 +system call, and sets a socket option on socket +.Fa so . +.Pp +The second argument in both +.Fn sogetopt +and +.Fn sosetopt +is the +.Fa sopt +pointer to a +.Vt "struct sopt" +describing the socket option operation. +The caller-allocated structure must be zeroed, and then have its fields +initialized to specify socket option operation arguments: +.Bl -tag -width ".Va sopt_valsize" +.It Va sopt_dir +Set to +.Dv SOPT_SET +or +.Dv SOPT_GET +depending on whether this is a get or set operation. +.It Va sopt_level +Specify the level in the network stack the operation is targeted at; for +example, +.Dv SOL_SOCKET . +.It Va sopt_name +Specify the name of the socket option to set. +.It Va sopt_val +Kernel space pointer to the argument value for the socket option. +.It Va sopt_valsize +Size of the argument value in bytes. +.El +.Ss Socket Upcalls +In order for the owner of a socket to be notified when the socket +is ready to send or receive data, an upcall may be registered on +the socket. +The upcall is a function that will be called by the socket framework +when a socket buffer associated with the given socket is ready for +reading or writing. +.Fn soupcall_set +is used to register a socket upcall. +The function +.Va func +is registered, and the pointer +.Va arg +will be passed as its second argument when it is called by the framework. +The possible values for +.Va which +are +.Dv SO_RCV +and +.Dv SO_SND , +which register upcalls for receive and send events, respectively. +The upcall function +.Fn func +must return either +.Dv SU_OK +or +.Dv SU_ISCONNECTED , +depending on whether or not a call to +.Xr soisconnected +should be made by the socket framework after the upcall returns. +The upcall +.Va func +cannot call +.Xr soisconnected +itself due to lock ordering with the socket buffer lock. +Only +.Dv SO_RCV +upcalls should return +.Dv SU_ISCONNECTED . +When a +.Dv SO_RCV +upcall returns +.Dv SU_ISCONNECTED , +the upcall will be removed from the socket. +.Pp +Upcalls are removed from their socket by +.Fn soupcall_clear . +The +.Va which +argument again specifies whether the sending or receiving upcall is to +be cleared, with +.Dv SO_RCV +or +.Dv SO_SND . +.Ss Socket Destructor Callback +A kernel system can use the +.Fn sodtor_set +function to set a destructor for a socket. +The destructor is called when the socket is about to be freed. +The destructor is called before the protocol detach routine. +The destructor can serve as a callback to initiate additional cleanup actions. +.Ss Socket I/O +The +.Fn soreceive +function is equivalent to the +.Xr recvmsg 2 +system call, and attempts to receive bytes of data from the socket +.Fa so , +optionally blocking awaiting for data if none is ready to read. +Data may be retrieved directly to kernel or user memory via the +.Fa uio +argument, or as an mbuf chain returned to the caller via +.Fa mp0 , +avoiding a data copy. +The +.Fa uio +must always be +.Pf non- Dv NULL . +If +.Fa mp0 +is +.Pf non- Dv NULL , +only the +.Fa uio_resid +of +.Fa uio +is used. +The caller may optionally retrieve a socket address on a protocol with the +.Dv PR_ADDR +capability by providing storage via +.Pf non- Dv NULL +.Fa psa +argument. +The caller may optionally retrieve control data mbufs via a +.Pf non- Dv NULL +.Fa controlp +argument. +Optional flags may be passed to +.Fn soreceive +via a +.Pf non- Dv NULL +.Fa flagsp +argument, and use the same flag name space as the +.Xr recvmsg 2 +system call. +.Pp +The +.Fn sosend +function is equivalent to the +.Xr sendmsg 2 +system call, and attempts to send bytes of data via the socket +.Fa so , +optionally blocking if data cannot be immediately sent. +Data may be sent directly from kernel or user memory via the +.Fa uio +argument, or as an mbuf chain via +.Fa top , +avoiding a data copy. +Only one of the +.Fa uio +or +.Fa top +pointers may be +.Pf non- Dv NULL . +An optional destination address may be specified via a +.Pf non- Dv NULL +.Fa addr +argument, which may result in an implicit connect if supported by the +protocol. +The caller may optionally send control data mbufs via a +.Pf non- Dv NULL +.Fa control +argument. +Flags may be passed to +.Fn sosend +using the +.Fa flags +argument, and use the same flag name space as the +.Xr sendmsg 2 +system call. +.Pp +Kernel callers running in an interrupt thread context, or with a mutex held, +will wish to use non-blocking sockets and pass the +.Dv MSG_DONTWAIT +flag in order to prevent these functions from sleeping. +.Pp +A socket can be queried for readability, writability, out-of-band data, +or end-of-file using +.Fn sopoll . +The possible values for +.Va events +are as for +.Xr poll 2 , +with symbolic values +.Dv POLLIN , +.Dv POLLPRI , +.Dv POLLOUT , +.Dv POLLRDNORM , +.Dv POLLWRNORM , +.Dv POLLRDBAND , +and +.Dv POLLINGEOF +taken from +.In sys/poll.h . +.Pp +Calls to +.Fn soaccept +pass through to the protocol's accept routine to accept an incoming connection. +.Ss Socket Utility Functions +The uid of a socket's credential may be compared against a +.Va uid +with +.Fn socheckuid . +.Pp +A copy of an existing +.Vt struct sockaddr +may be made using +.Fn sodupsockaddr . +.Pp +Protocol implementations notify the socket layer of the arrival of +out-of-band data using +.Fn sohasoutofband , +so that the socket layer can notify socket consumers of the available data. +.Pp +An +.Dq external-format +version of a +.Vt struct socket +can be created using +.Fn sotoxsocket , +suitable for isolating user code from changes in the kernel structure. +.Ss Protocol Implementations +Protocols must supply an implementation for +.Fn solisten ; +such protocol implementations can call back into the socket layer using +.Fn solisten_proto_check +and +.Fn solisten_proto +to check and set the socket-layer listen state. +These callbacks are provided so that the protocol implementation +can order the socket layer and protocol locks as necessary. +Protocols must supply an implementation of +.Fn soreceive ; +the functions +.Fn soreceive_stream , +.Fn soreceive_dgram , +and +.Fn soreceive_generic +are supplied for use by such implementations. +.Pp +Protocol implementations can use +.Fn sonewconn +to create a socket and attach protocol state to that socket. +This can be used to create new sockets available for +.Fn soaccept +on a listen socket. +The returned socket has a reference count of zero. +.Pp +Protocols must supply an implementation for +.Fn sopoll ; +.Fn sopoll_generic +is provided for the use by protocol implementations. +.Pp +The functions +.Fn sosend_dgram +and +.Fn sosend_generic +are supplied to assist in protocol implementations of +.Fn sosend . +.Pp +When a protocol creates a new socket structure, it is necessary to +reserve socket buffer space for that socket, by calling +.Fn soreserve . +The rough inverse of this reservation is performed by +.Fn sorflush , +which is called automatically by the socket framework. +.Pp +When a protocol needs to wake up threads waiting for the socket to +become ready to read or write, variants of +.Fn sowakeup +are used. +The +.Fn sowakeup +function should not be called directly by protocol code, instead use the +wrappers +.Fn sorwakeup , +.Fn sorwakeup_locked , +.Fn sowwakeup , +and +.Fn sowwakeup_locked +for readers and writers, with the corresponding socket buffer lock +not already locked, or already held, respectively. +.Pp +The functions +.Fn sooptcopyin +and +.Fn sooptcopyout +are useful for transferring +.Vt struct sockopt +data between user and kernel code. +.Sh SEE ALSO +.Xr bind 2 , +.Xr close 2 , +.Xr connect 2 , +.Xr getsockopt 2 , +.Xr recv 2 , +.Xr send 2 , +.Xr setsockopt 2 , +.Xr shutdown 2 , +.Xr socket 2 , +.Xr ng_ksocket 4 , +.Xr intr_event 9 , +.Xr msleep 9 , +.Xr ucred 9 +.Sh HISTORY +The +.Xr socket 2 +system call appeared in +.Bx 4.2 . +This manual page was introduced in +.Fx 7.0 . +.Sh AUTHORS +This manual page was written by +.An Robert Watson +and +.An Benjamin Kaduk . +.Sh BUGS +The use of explicitly passed credentials, credentials hung from explicitly +passed threads, the credential on +.Dv curthread , +and the cached credential from +socket creation time is inconsistent, and may lead to unexpected behaviour. +It is possible that several of the +.Fa td +arguments should be +.Fa cred +arguments, or simply not be present at all. +.Pp +The caller may need to manually clear +.Dv SS_ISCONNECTING +if +.Fn soconnect +returns an error. +.Pp +The +.Dv MSG_DONTWAIT +flag is not implemented for +.Fn sosend , +and may not always work with +.Fn soreceive +when zero copy sockets are enabled. +.Pp +This manual page does not describe how to register socket upcalls or monitor +a socket for readability/writability without using blocking I/O. +.Pp +The +.Fn soref +and +.Fn sorele +functions are not described, and in most cases should not be used, due to +confusing and potentially incorrect interactions when +.Fn sorele +is last called after +.Fn soclose . diff --git a/static/freebsd/man9/stack.9 b/static/freebsd/man9/stack.9 new file mode 100644 index 00000000..c912cd30 --- /dev/null +++ b/static/freebsd/man9/stack.9 @@ -0,0 +1,184 @@ +.\" +.\" Copyright (c) 2007-2009 Robert N. M. Watson +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 March 6, 2022 +.Dt STACK 9 +.Os +.Sh NAME +.Nm stack +.Nd kernel thread stack tracing routines +.Sh SYNOPSIS +.In sys/param.h +.In sys/stack.h +.Pp +In the kernel configuration file: +.Cd "options DDB" +.Cd "options STACK" +.Pp +.Ft struct stack * +.Fn stack_create "int flags" +.Ft void +.Fn stack_destroy "struct stack *st" +.Ft int +.Fn stack_put "struct stack *st" "vm_offset_t pc" +.Ft void +.Fn stack_copy "const struct stack *src" "struct stack *dst" +.Ft void +.Fn stack_zero "struct stack *st" +.Ft void +.Fn stack_print "const struct stack *st" +.Ft void +.Fn stack_print_ddb "const struct stack *st" +.Ft void +.Fn stack_print_short "const struct stack *st" +.Ft void +.Fn stack_print_short_ddb "const struct stack *st" +.Ft void +.Fn stack_sbuf_print "struct sbuf *sb" "const struct stack *st" +.Ft void +.Fn stack_sbuf_print_ddb "struct sbuf *sb" "const struct stack *st" +.Ft void +.Fn stack_save "struct stack *st" +.Ft int +.Fn stack_save_td "struct stack *st" "struct thread *td" +.Sh DESCRIPTION +The +.Nm +KPI allows querying of kernel stack trace information and the automated +generation of kernel stack trace strings for the purposes of debugging and +tracing. +To use the KPI, at least one of +.Cd "options DDB" +and +.Cd "options STACK" +must be compiled into the kernel. +.Pp +Each stack trace is described by a +.Vt "struct stack" . +It can be declared in the usual ways, including on the stack, and optionally +initialized with +.Fn stack_zero , +though this is not necessary before saving a trace. +It can also be dynamically allocated with +.Fn stack_create . +The +.Ar flags +argument is passed to +.Xr malloc 9 . +This dynamic allocation must be freed with +.Fn stack_destroy . +.Pp +A trace of the current thread's kernel call stack may be captured using +.Fn stack_save . +.Fn stack_save_td +can be used to capture the kernel stack of a caller-specified thread. +Callers of +.Fn stack_save_td +must own the thread lock of the specified thread, +and the thread's stack must not be swapped out. +.Fn stack_save_td +can capture the kernel stack of a running thread, though note that this is +not implemented on all platforms. +If the thread is running, the caller must also hold the process lock for the +target thread. +.Pp +.Fn stack_print +and +.Fn stack_print_short +may be used to print a stack trace using the kernel +.Xr printf 9 , +and may sleep as a result of acquiring +.Xr sx 9 +locks in the kernel linker while looking up symbol names. +In locking-sensitive environments, the unsynchronized +.Fn stack_print_ddb +and +.Fn stack_print_short_ddb +variants may be invoked. +This function bypasses kernel linker locking, making it usable in +.Xr ddb 4 , +but not in a live system where linker data structures may change. +.Pp +.Fn stack_sbuf_print +may be used to construct a human-readable string, including conversion (where +possible) from a simple kernel instruction pointer to a named symbol and +offset. +The argument +.Ar sb +must be an initialized +.Dv struct sbuf +as described in +.Xr sbuf 9 . +This function may sleep if an auto-extending +.Dv struct sbuf +is used, or due to kernel linker locking. +In locking-sensitive environments, such as +.Xr ddb 4 , +the unsynchronized +.Fn stack_sbuf_print_ddb +variant may be invoked to avoid kernel linker locking; it should be used with +a fixed-length sbuf. +.Pp +The utility functions +.Nm stack_zero , +.Nm stack_copy , +and +.Nm stack_put +may be used to manipulate stack data structures directly. +.Sh RETURN VALUES +.Fn stack_put +returns 0 on success. +Otherwise the +.Dv struct stack +does not contain space to record additional frames, and a non-zero value is +returned. +.Pp +.Fn stack_save_td +returns 0 when the stack capture was successful and a non-zero error number +otherwise. +In particular, +.Er EBUSY +is returned if the thread was running in user mode at the time that the +capture was attempted, and +.Er EOPNOTSUPP +is returned if the operation is not implemented. +.Sh SEE ALSO +.Xr ddb 4 , +.Xr printf 9 , +.Xr sbuf 9 , +.Xr sx 9 +.Sh AUTHORS +.An -nosplit +The +.Nm +function suite was created by +.An Antoine Brodin . +.Nm +was extended by +.An Robert Watson +for general-purpose use outside of +.Xr ddb 4 . diff --git a/static/freebsd/man9/store.9 b/static/freebsd/man9/store.9 new file mode 100644 index 00000000..18fd646d --- /dev/null +++ b/static/freebsd/man9/store.9 @@ -0,0 +1,92 @@ +.\" $NetBSD: store.9,v 1.2 1996/01/09 21:59:27 perry Exp $ +.\" +.\" Copyright (c) 1996 Jason R. Thorpe. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed by Kenneth Stailey. +.\" +.\" 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 for the NetBSD Project +.\" by Jason R. Thorpe. +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd July 22, 2021 +.Dt STORE 9 +.Os +.Sh NAME +.Nm store , +.Nm subyte , +.Nm suword +.Nd store data to user-space +.Sh SYNOPSIS +.In sys/types.h +.In sys/time.h +.In sys/systm.h +.Ft int +.Fn subyte "volatile void *base" "int byte" +.Ft int +.Fn suword "volatile void *base" "long word" +.Ft int +.Fn suword16 "volatile void *base" "int word" +.Ft int +.Fn suword32 "volatile void *base" "int32_t word" +.Ft int +.Fn suword64 "volatile void *base" "int64_t word" +.Sh DESCRIPTION +The +.Nm +functions are designed to copy small amounts of data to user-space. +If the user address is naturally aligned, then the operation will be +performed atomically. +Otherwise it may fail or be performed non-atomically, depending on +the platform. +.Pp +The +.Nm +routines provide the following functionality: +.Bl -tag -width "suword64()" +.It Fn subyte +Stores a byte of data to the user-space address +.Pa base . +.It Fn suword +Stores a word of data to the user-space address +.Pa base . +.It Fn suword16 +Stores 16 bits of data to the user-space address +.Pa base . +.It Fn suword32 +Stores 32 bits of data to the user-space address +.Pa base . +.It Fn suword64 +Stores 64 bits of data to the user-space address +.Pa base . +.El +.Sh RETURN VALUES +The +.Nm +functions return 0 on success or -1 on failure. +.Sh SEE ALSO +.Xr copy 9 , +.Xr fetch 9 diff --git a/static/freebsd/man9/style.9 b/static/freebsd/man9/style.9 new file mode 100644 index 00000000..65636a8a --- /dev/null +++ b/static/freebsd/man9/style.9 @@ -0,0 +1,1119 @@ +.\" +.\" 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 +.\" 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 [your name] 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 28, 2025 +.Dt STYLE 9 +.Os +.Sh NAME +.Nm style +.Nd kernel source file style guide +.Sh DESCRIPTION +This file specifies the preferred style for kernel source files in the +.Fx +source tree. +It is also a guide for the preferred userland code style. +The preferred line width is 80 characters, but some exceptions are +made when a slightly longer line is clearer or easier to read. +Anything that is frequently grepped for, such as diagnostic, error, or panic +messages, should not be broken up over multiple lines despite this rule. +Many of the style rules are implicit in the examples. +Be careful to check the examples before assuming that +.Nm +is silent on an issue. +.Bd -literal +/* + * Style guide for FreeBSD. Based on the CSRG's KNF (Kernel Normal Form). + */ + +/* + * VERY important single-line comments look like this. + */ + +/* 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 +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 +/* + * Copyright (c) 1984-2025 John Q. Public + * + * SPDX-License-Identifier: BSD-2-Clause + */ +.Ed +.Pp +Comments starting in columns other than the first are never +considered license statements. +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 +.Dq Li "Copyright" . +You should not insert a new copyright line between an old +copyright line and this phrase. +Instead, you should insert a new copyright phrase after +a pre-existing +.Dq Li "All Rights Reserved" +line. +When making changes, it is acceptable to fold an +.Dq Li "All Rights Reserved" +line with each of the +.Dq Li "Copyright" +lines. +For files that have the +.Dq Li "All Rights Reserved" +line on the same line(s) as the word +.Dq Li "Copyright" , +new copyright assertions should be added last. +New +.Dq Li "Copyright" +lines should only be added when making substantial changes to the file, +not for trivial changes. +.Pp +After any copyright and license comment, there is a blank line. +Non-C/C++ source files follow the example above, while C/C++ source files +follow the one below. +Version control system ID tags should only exist once in a file +(unlike in this one). +All VCS (version control system) revision identification in files obtained +from elsewhere should be maintained, including, where applicable, multiple IDs +showing a file's history. +In general, do not edit foreign IDs or their infrastructure. +Unless otherwise wrapped (such as +.Dq Li "#if defined(LIBC_SCCS)" ) , +enclose both in +.Dq Li "#if 0 ... #endif" +to hide any uncompilable bits +and to keep the IDs out of object files. +Only add +.Dq Li "From: " +in front of foreign VCS IDs if the file is renamed. +Add +.Dq Li "From: " +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 either +.In sys/types.h +or +.In sys/param.h +is needed, include it before other include files. +.Po +.In sys/param.h +includes +.In sys/types.h ; +do not include both. +.Pc +Next, include +.In sys/systm.h , +if needed. +The remaining kernel headers should be sorted alphabetically. +.Bd -literal +#include /* Non-local includes in angle brackets. */ +#include +#include +#include +#include +.Ed +.Pp +For a network program, put the network include files next. +.Bd -literal +#include +#include +#include +#include +#include +.Ed +.Pp +Do not include files from +.Pa /usr/include +in the kernel. +.Pp +Leave a blank line before the next group, the +.Pa /usr/include +files, +which should be sorted alphabetically by name. +.Bd -literal +#include +.Ed +.Pp +Global pathnames are defined in +.In paths.h . +Pathnames local +to the program go in +.Qq Pa pathnames.h +in the local directory. +.Bd -literal +#include +.Ed +.Pp +Leave another blank line before the local include files. +.Bd -literal +#include "pathnames.h" /* Local includes in double quotes. */ +.Ed +.Pp +Do not +.Ic #define +or declare names in the implementation namespace except +for implementing application interfaces. +.Pp +The names of +.Dq unsafe +macros (ones that have side effects), and the names of macros for +manifest constants, are all in uppercase. +The expansions of expression-like macros are either a single token +or have outer parentheses. +Put a single space or tab character between the +.Ic #define +and the macro name, but be consistent within a file. +If a macro is an inline expansion of a function, the function name is +all in lowercase and the macro has the same name all in uppercase. +.\" XXX the above conflicts with ANSI style where the names are the +.\" same and you #undef the macro (if any) to get the function. +.\" It is not followed for MALLOC(), and not very common if inline +.\" functions are used. +Right-justify the +backslashes; it makes it easier to read. +If the macro encapsulates a compound statement, enclose it in a +.Ic do +loop, +so that it can safely be used in +.Ic if +statements. +Any final statement-terminating semicolon should be +supplied by the macro invocation rather than the macro, to make parsing easier +for pretty-printers and editors. +.Bd -literal +#define MACRO(x, y) do { \e + variable = (x) + (y); \e + (y) += 2; \e +} while (0) +.Ed +.Pp +When code is conditionally compiled using +.Ic #ifdef +or +.Ic #if , +a comment may be added following the matching +.Ic #endif +or +.Ic #else +to permit the reader to easily discern where conditionally compiled code +regions end. +This comment should be used only for (subjectively) long regions, regions +greater than 20 lines, or where a series of nested +.Ic #ifdef 's +may be confusing to the reader. +The comment should be separated from the +.Ic #endif +or +.Ic #else +by a single space. +For short conditionally compiled regions, a closing comment should not be +used. +.Pp +The comment for +.Ic #endif +should match the expression used in the corresponding +.Ic #if +or +.Ic #ifdef . +The comment for +.Ic #else +and +.Ic #elif +should match the inverse of the expression(s) used in the preceding +.Ic #if +and/or +.Ic #elif +statements. +In the comments, the subexpression +.Dq Li defined(FOO) +is abbreviated as +.Dq Li FOO . +For the purposes of comments, +.Dq Ic #ifndef Li FOO +is treated as +.Dq Ic #if Li !defined(FOO) . +.Bd -literal +#ifdef KTRACE +#include +#endif + +#ifdef COMPAT_43 +/* A large region here, or other conditional code. */ +#else /* !COMPAT_43 */ +/* Or here. */ +#endif /* COMPAT_43 */ + +#ifndef COMPAT_43 +/* Yet another large region here, or other conditional code. */ +#else /* COMPAT_43 */ +/* Or here. */ +#endif /* !COMPAT_43 */ +.Ed +.Pp +The project prefers the use of +.St -isoC-99 +unsigned integer identifiers of the form +.Vt uintXX_t +rather than the older +.Bx Ns -style +integer identifiers of the form +.Vt u_intXX_t . +New code should use the former, and old code should be converted to +the new form if other major work is being done in that area and +there is no overriding reason to prefer the older +.Bx Ns -style . +Like white-space commits, care should be taken in making +.Vt uintXX_t +only commits. +.Pp +Similarly, the project prefers the use of +ISO C99 +.Vt bool +rather than the older +.Vt int +or +.Vt boolean_t . +New code should use +.Vt bool , +and old code may be converted if it is +reasonable to do so. +Literal values are named +.Dv true +and +.Dv false . +These are preferred to the old spellings +.Dv TRUE +and +.Dv FALSE . +Userspace code should include +.In stdbool.h , +while kernel code should include +.In sys/types.h . +.Pp +Likewise, the project prefers +ISO C99 +designated initializers when it makes sense to do so. +.Pp +Enumeration values are all uppercase. +.Bd -literal +enum enumtype { ONE, TWO } et; +.Ed +.Pp +The use of internal_underscores in identifiers is preferred over +camelCase or TitleCase. +.Pp +In declarations, do not put any whitespace between asterisks and +adjacent tokens, except for tokens that are identifiers related to +types. +(These identifiers are the names of basic types, type +qualifiers, and +.Ic typedef Ns -names +other than the one being declared.) +Separate these identifiers from asterisks using a single space. +.Pp +When declaring variables in structures, declare them sorted by use, then +by size (largest to smallest), and then in alphabetical order. +The first category normally does not apply, but there are exceptions. +Each one gets its own line. +Try to make the structure +readable by aligning the member names using either one or two tabs +depending upon your judgment. +You should use one tab only if it suffices to align at least 90% of +the member names. +Names following extremely long types +should be separated by a single space. +.Pp +Major structures should be declared at the top of the file in which they +are used, or in separate header files if they are used in multiple +source files. +Use of the structures should be by separate declarations +and should be +.Ic extern +if they are declared in a header file. +.Bd -literal +struct foo { + struct foo *next; /* List of active foo. */ + struct mumble amumble; /* Comment for mumble. */ + int bar; /* Try to align the comments. */ + struct verylongtypename *baz; /* Does not fit in 2 tabs. */ +}; +struct foo *foohead; /* Head of global foo list. */ +.Ed +.Pp +Use +.Xr queue 3 +macros rather than rolling your own lists, whenever possible. +Thus, +the previous example would be better written: +.Bd -literal +#include + +struct foo { + LIST_ENTRY(foo) link; /* Use queue macros for foo lists. */ + struct mumble amumble; /* Comment for mumble. */ + int bar; /* Try to align the comments. */ + struct verylongtypename *baz; /* Does not fit in 2 tabs. */ +}; +LIST_HEAD(, foo) foohead; /* Head of global foo list. */ +.Ed +.Pp +Avoid using typedefs for structure types. +Typedefs are problematic because they do not properly hide their +underlying type; for example you need to know if the typedef is +the structure itself or a pointer to the structure. +In addition they must be declared exactly once, whereas an +incomplete structure type can be mentioned as many times as +necessary. +Typedefs are difficult to use in stand-alone header files: +the header that defines the typedef must be included +before the header that uses it, or by the header that uses +it (which causes namespace pollution), or there must be a +back-door mechanism for obtaining the typedef. +.Pp +When convention requires a +.Ic typedef , +make its name match the struct tag. +Avoid typedefs ending in +.Dq Li _t , +except as specified in Standard C or by POSIX. +.Bd -literal +/* Make the structure name match the typedef. */ +typedef struct bar { + int level; +} BAR; +typedef int foo; /* This is foo. */ +typedef const long baz; /* This is baz. */ +.Ed +.Pp +All functions are prototyped somewhere. +.Pp +Function prototypes for private functions (i.e., functions not used +elsewhere) go at the top of the first source module. +Functions +local to one source module should be declared +.Ic static . +.Pp +Functions used from other parts of the kernel are prototyped in the +relevant include file. +Function prototypes should be listed in a logical order, preferably +alphabetical unless there is a compelling reason to use a different +ordering. +.Pp +Functions that are used locally in more than one module go into a +separate header file, e.g., +.Qq Pa extern.h . +.Pp +The kernel has a name associated with parameter types, e.g., in the kernel +use: +.Bd -literal +void function(int fd); +.Ed +.Pp +In header files visible to userland applications, prototypes that are +visible must use either +.Dq protected +names (ones beginning with an underscore) +or no names with the types. +It is preferable to use protected names. +E.g., use: +.Bd -literal +void function(int); +.Ed +.Pp +or: +.Bd -literal +void function(int _fd); +.Ed +.Pp +Prototypes may have an extra space after a tab to enable function names +to line up: +.Bd -literal +static char *function(int _arg, const char *_arg2, struct foo *_arg3, + struct bar *_arg4); +static void usage(void); + +/* + * All major routines should have a comment briefly describing what + * they do. The comment before the "main" routine should describe + * what the program does. + */ +int +main(int argc, char *argv[]) +{ + char *ep; + long num; + int ch; +.Ed +.Pp +For consistency, +.Xr getopt 3 +should be used to parse options. +Options +should be sorted in the +.Xr getopt 3 +call and the +.Ic switch +statement, unless +parts of the +.Ic switch +cascade. +Elements in a +.Ic switch +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. +Code which is unreachable for non-obvious reasons may be marked /* +.Li NOTREACHED +*/. +.Bd -literal + while ((ch = getopt(argc, argv, "abNn:")) != -1) + switch (ch) { /* Indent the switch. */ + case 'a': /* Do not indent the case. */ + aflag = 1; /* Indent case body one tab. */ + /* FALLTHROUGH */ + case 'b': + bflag = 1; + break; + case 'N': + Nflag = 1; + break; + case 'n': + num = strtol(optarg, &ep, 10); + if (num <= 0 || *ep != '\e0') { + warnx("illegal number, -n argument -- %s", + optarg); + usage(); + } + break; + case '?': + default: + usage(); + } + argc -= optind; + argv += optind; +.Ed +.Pp +Space after keywords +.Pq Ic if , while , for , return , switch . +Two styles of braces +.Ql ( \&{ +and +.Ql \&} ) +are allowed for single line statements. +Either they are used for all single statements, or +they are used only where needed for clarity. +Usage within a function should be consistent. +Forever loops are done with +.Ic for Ns 's , +not +.Ic while Ns 's . +.Bd -literal + for (p = buf; *p != '\e0'; ++p) + ; /* nothing */ + for (;;) + stmt; + for (;;) { + z = a + really + long + statement + that + needs + + two + lines + gets + indented + four + spaces + + on + the + second + and + subsequent + lines; + } + for (;;) { + if (cond) + stmt; + } + if (val != NULL) + val = realloc(val, newsize); +.Ed +.Pp +Parts of a +.Ic for +loop may be left empty. +.Bd -literal + for (; cnt < 15; cnt++) { + stmt1; + stmt2; + } +.Ed +.Pp +A +.Ic for +loop may declare and initialize its counting variable. +.Bd -literal + for (int i = 0; i < 15; i++) { + stmt1; + } +.Ed +.Pp +Indentation is an 8 character tab. +Second level indents are four spaces. +If you have to wrap a long statement, put the operator at the end of the +line. +.Bd -literal + while (cnt < 20 && this_variable_name_is_too_long && + ep != NULL) + z = a + really + long + statement + that + needs + + two + lines + gets + indented + four + spaces + + on + the + second + and + subsequent + lines; +.Ed +.Pp +Do not add whitespace at the end of a line, and only use tabs +followed by spaces +to form the indentation. +Do not use more spaces than a tab will produce +and do not use spaces in front of tabs. +.Pp +Closing and opening braces go on the same line as the +.Ic else . +Braces that are not necessary may be left out. +.Bd -literal + if (test) + stmt; + else if (bar) { + stmt; + stmt; + } else + stmt; +.Ed +.Pp +No spaces after function names. +Commas have a space after them. +No spaces +after +.Ql \&( +or +.Ql \&[ +or preceding +.Ql \&] +or +.Ql \&) +characters. +.Bd -literal + error = function(a1, a2); + if (error != 0) + exit(error); +.Ed +.Pp +Unary operators do not require spaces, binary operators do. +Do not use parentheses unless they are required for precedence or unless the +statement is confusing without them. +Remember that other people may +confuse easier than you. +Do YOU understand the following? +.Bd -literal + a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1; + k = !(l & FLAGS); +.Ed +.Pp +Exits should be 0 on success, or 1 on failure. +.Bd -literal + exit(0); /* + * Avoid obvious comments such as + * "Exit 0 on success." + */ +} +.Ed +.Pp +The function type should be on a line by itself +preceding the function. +The opening brace of the function body should be +on a line by itself. +.Bd -literal +static char * +function(int a1, int a2, float fl, int a4, struct bar *bar) +{ +.Ed +.Pp +When declaring variables in functions declare them sorted by size, +then in alphabetical order; multiple ones per line are okay. +If a line overflows reuse the type keyword. +Variables may be initialized where declared especially when they +are constant for the rest of the scope. +Declarations may be in any block, but must be placed before statements. +Calls to complicated functions should be avoided when initializing variables. +.Bd -literal + struct foo one, *two; + struct baz *three = bar_get_baz(bar); + double four; + int *five, six; + char *seven, eight, nine, ten, eleven, twelve; + + four = my_complicated_function(a1, f1, a4); +.Ed +.Pp +Do not declare functions inside other functions; ANSI C says that +such declarations have file scope regardless of the nesting of the +declaration. +Hiding file declarations in what appears to be a local +scope is undesirable and will elicit complaints from a good compiler. +.Pp +Casts and +.Ic sizeof Ns 's +are not followed by a space. +.Ic sizeof Ns 's +are written with parenthesis always. +The redundant parenthesis rules do not apply to +.Fn sizeof var +instances. +.Pp +.Dv NULL +is the preferred null pointer constant. +Use +.Dv NULL +instead of +.Vt ( "type *" ) Ns 0 +or +.Vt ( "type *" ) Ns Dv NULL +in contexts where the compiler knows the +type, e.g., in assignments. +Use +.Vt ( "type *" ) Ns Dv NULL +in other contexts, +in particular for all function args. +(Casting is essential for +variadic args and is necessary for other args if the function prototype +might not be in scope.) +Test pointers against +.Dv NULL , +e.g., use: +.Bd -literal +(p = f()) == NULL +.Ed +.Pp +not: +.Bd -literal +!(p = f()) +.Ed +.Pp +Do not test without a comparison, or with unary +.Ic \&! +(except for booleans). +For example, use: +.Bd -literal +if (*p == '\e0') +.Ed +.Pp +not: +.Bd -literal +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 +to any pointer type. +.Pp +Values in +.Ic return +statements should be enclosed in parentheses. +.Pp +Use +.Xr err 3 +or +.Xr warn 3 , +do not roll your own. +.Bd -literal + if ((four = malloc(sizeof(struct foo))) == NULL) + err(1, (char *)NULL); + if ((six = (int *)overflow()) == NULL) + errx(1, "number overflowed"); + return (eight); +} +.Ed +.Pp +Do not use K&R style declarations or definitions, they are obsolete +and are forbidden in C23. +Compilers warn of their use and some treat them as an error by default. +When converting K&R style definitions to ANSI style, preserve +any comments about parameters. +.Pp +Long parameter lists are wrapped with a normal four space indent. +.Pp +Variable numbers of arguments should look like this: +.Bd -literal +#include + +void +vaf(const char *fmt, ...) +{ + va_list ap; + + va_start(ap, fmt); + STUFF; + va_end(ap); + /* No return needed for void functions. */ +} + +static void +usage(void) +{ +.Ed +.Pp +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 a blank line before code. +Such lines should be removed when significant changes are made to the code. +.Pp +Use +.Xr printf 3 , +not +.Xr fputs 3 , +.Xr puts 3 , +.Xr putchar 3 , +whatever; it is faster and usually cleaner, not +to mention avoiding stupid bugs. +.Pp +Usage statements should look like the manual pages +.Sx SYNOPSIS . +The usage statement should be structured in the following order: +.Bl -enum +.It +Options without operands come first, +in alphabetical order, +inside a single set of brackets +.Ql ( \&[ +and +.Ql \&] ) . +.It +Options with operands come next, +also in alphabetical order, +with each option and its argument inside its own pair of brackets. +.It +Required arguments +(if any) +are next, +listed in the order they should be specified on the command line. +.It +Finally, +any optional arguments should be listed, +listed in the order they should be specified, +and all inside brackets. +.El +.Pp +A bar +.Pq Ql \&| +separates +.Dq either-or +options/arguments, +and multiple options/arguments which are specified together are +placed in a single set of brackets. +.Bd -literal -offset 4n +"usage: f [-aDde] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\en" +"usage: f [-a | -b] [-c [-dEe] [-n number]]\en" +.Ed +.Bd -literal + (void)fprintf(stderr, "usage: f [-ab]\en"); + exit(1); +} +.Ed +.Pp +Note that the manual page options description should list the options in +pure alphabetical order. +That is, without regard to whether an option takes arguments or not. +The alphabetical ordering should take into account the case ordering +shown above. +.Pp +Whenever possible, code should be run through a code checker +(e.g., various static analyzers or +.Nm cc Fl Wall ) +and produce minimal warnings. +.Pp +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. +.Pp +New core kernel code should be compliant with the +.Nm +guides. +The guidelines for third-party maintained modules and device drivers are more +relaxed. +Their code is expected to at least be internally consistent with their style. +.Pp +Stylistic changes, including whitespace ones, complicate the work of downstream +consumers and may impair developers' ability to trace the history of some +changes. +Such standalone must be avoided, and should not span unrelated directories as +this increases the chances of conflicts when merging to stable and release +branches (MFCs). +On the other hand, when a significant portion, usually about a half, of some +logical unit of code, be it a function, group of functions, file or group of +files, is going to be modified, developers are encouraged to amend the style of +the whole unit as described in this document. +In this case, style changes to otherwise unmodified code should be committed +separately. +Style-only commits should be added to the file +.Pa .git-blame-ignore-revs +at the top of the source repository to hide them from +.Ql git blame . +Comments in this file indicate how to use it. +Code that is approximately +.Fx +KNF +.Nm +compliant in the repository must not diverge from compliance. +.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 parentheses. +When converting existing C code to C++, +existing return values may remain in parentheses. +.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 prototypes 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 +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 +A script to check for violations of +.Nm +in a source file. +.It Pa /usr/src/tools/tools/editing/freebsd.el +An Emacs plugin to follow the +.Fx +.Nm +indentation rules. +.It Pa /usr/src/tools/tools/editing/freebsd.vim +A Vim plugin to follow the +.Fx +.Nm +indentation rules. +.El +.Sh SEE ALSO +.Xr indent 1 , +.Xr err 3 , +.Xr warn 3 , +.Xr style.Makefile 5 , +.Xr style.mdoc 5 , +.Xr style.lua 9 +.Sh HISTORY +This manual page was originally based on the +.Pa src/admin/style/style +file from the +.Bx 4.4 Lite2 +release, with frequent updates to reflect the current practice and +desire of the +.Fx +project. +.Pa src/admin/style/style +is a codification by the CSRG of the programming style of Ken Thompson and +Dennis Ritchie in +.At v6 . diff --git a/static/freebsd/man9/style.lua.9 b/static/freebsd/man9/style.lua.9 new file mode 100644 index 00000000..991a6f96 --- /dev/null +++ b/static/freebsd/man9/style.lua.9 @@ -0,0 +1,124 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2018 Kyle Evans +.\" +.\" 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 [your name] 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 February 25, 2018 +.Dt STYLE.LUA 9 +.Os +.Sh NAME +.Nm style.lua +.Nd +.Fx +lua file style guide +.Sh DESCRIPTION +This file specifies the preferred style for lua source files in the +.Fx +source tree. +Many of the style rules are implicit in the examples. +Be careful to check the examples before assuming that +.Nm +is silent on an issue. +.Pp +The copyright header should be a series of single-line comments. +Use the single-line comment style for every line in a multi-line comment. +.Pp +After any copyright header there is a blank line. +.Pp +The preferred method of including other files and modules is with +.Fn require name , +such as: +.Bd -literal +-- License block + +config = require("config"); +menu = require("menu"); +password = require("password"); +-- One blank line following the module require block +.Ed +.Pp +.Fn include +is generally avoided. +.Pp +Indentation and wrapping should match the guidelines provided by +.Xr style 9 . +Do note that it is ok to wrap much earlier than 80 columns if readability would +otherwise suffer. +.Pp +Where possible, +.Fn s:method ... +is preferred to +.Fn method s ... . +This is applicable to objects with methods. +String are a commonly-used example of objects with methods. +.Pp +Testing for +.Va nil +should be done explicitly, rather than as a boolean expression. +Single-line conditional statements and loops should be avoided. +.Pp +.Ic local +variables should be preferred to global variables in module scope. +internal_underscores tend to be preferred for variable identifiers, while +camelCase tends to be preferred for function identifiers. +.Pp +If a table definition spans multiple lines, then the final value in the table +should include the optional terminating comma. +For example: +.Bd -literal +-- No terminating comma needed for trivial table definitions +local trivial_table = {1, 2, 3, 4} + +local complex_table = { + { + id = "foo", + func = foo_function, -- Trailing comma preferred + }, + { + id = "bar", + func = bar_function, + }, -- Trailing comma preferred +} +.Ed +.Pp +This reduces the chance for errors to be introduced when modifying more complex +tables. +.Pp +Multiple local variables should not be declared +.Sy and +initialized on a single line. +Lines containing multiple variable declarations without initialization are ok. +Lines containing multiple variable declarations initialized to a single function +call returning a tuple with the same number of values is also ok. +.Pp +Initialization +.Sy should +be done at declaration time as appropriate. +.Sh SEE ALSO +.Xr style 9 +.Sh HISTORY +This manual page is inspired from the same source as +.Xr style 9 +manual page in +.Fx . diff --git a/static/freebsd/man9/superio.9 b/static/freebsd/man9/superio.9 new file mode 100644 index 00000000..6318b5a4 --- /dev/null +++ b/static/freebsd/man9/superio.9 @@ -0,0 +1,187 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2019 Andriy Gapon +.\" +.\" 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 October 11, 2019 +.Dt SUPERIO 9 +.Os +.Sh NAME +.Nm superio , +.Nm superio_devid , +.Nm superio_dev_disable , +.Nm superio_dev_enable , +.Nm superio_dev_enabled , +.Nm superio_find_dev , +.Nm superio_get_dma , +.Nm superio_get_iobase , +.Nm superio_get_irq , +.Nm superio_get_ldn , +.Nm superio_get_type , +.Nm superio_read , +.Nm superio_revid , +.Nm superio_vendor , +.Nm superio_write +.Nd Super I/O bus interface +.Sh SYNOPSIS +.In sys/bus.h +.In dev/superio/superio.h +.Ft uint16_t +.Fn superio_devid "device_t dev" +.Ft void +.Fn superio_dev_disable "device_t dev" "uint8_t mask" +.Ft void +.Fn superio_dev_enable "device_t dev" "uint8_t mask" +.Ft bool +.Fn superio_dev_enabled "device_t dev" "uint8_t mask" +.Ft device_t +.Fn superio_find_dev "device_t dev" "superio_dev_type_t type" "int ldn" +.Ft uint8_t +.Fn superio_get_dma "device_t dev" +.Ft uint16_t +.Fn superio_get_iobase "device_t dev" +.Ft uint8_t +.Fn superio_get_irq "device_t dev" +.Ft uint8_t +.Fn superio_get_ldn "device_t dev" +.Ft superio_dev_type_t +.Fn superio_get_type "device_t dev" +.Ft uint8_t +.Fn superio_read "device_t dev" "uint8_t reg" +.Ft uint8_t +.Fn superio_revid "device_t dev" +.Ft superio_vendor_t +.Fn superio_vendor "device_t dev" +.Ft void +.Fn superio_write "device_t dev" "uint8_t reg" "uint8_t val" +.Sh DESCRIPTION +The +.Nm +set of functions are used for managing Super I/O devices. +The functions provide support for +raw configuration access, +locating devices, +device information, +and +device configuration. +.Ss The controller interface +The +.Fn superio_vendor +function is used to get a vendor of the Super I/O controller +.Fa dev . +Possible return values are +.Dv SUPERIO_VENDOR_ITE +and +.Dv SUPERIO_VENDOR_NUVOTON . +.Pp +The +.Fn superio_devid +function is used to get a device ID of the Super I/O controller +.Fa dev . +.Pp +The +.Fn superio_revid +function is used to get a revision ID of the Super I/O controller +.Fa dev . +.Pp +The +.Fn superio_find_dev +function is used to find a device on the +.Xr superio 4 +bus, specified by +.Fa dev , +that has the requested type and logical device number. +Either of those, but not both, can be a wildcard. +Supported types are +.Dv SUPERIO_DEV_GPIO , +.Dv SUPERIO_DEV_HWM , +and +.Dv SUPERIO_DEV_WDT . +The wildcard value for +.Fa type +is +.Dv SUPERIO_DEV_NONE . +The wildcard value for +.Fa ldn +is -1. +.Ss The device interface +The +.Fn superio_read +function is used to read data from the Super I/O configuration register +of the device +.Fa dev . +.Pp +The +.Fn superio_write +function is used to write data to the Super I/O configuration register +of the device +.Fa dev . +.Pp +The +.Fn superio_dev_enable , +.Fn superio_dev_disable , +and +.Fn superio_dev_enabled +functions are used to enable, disable, or check status of the device +.Fa dev . +The +.Fa mask +parameter selects sub-functions of a device that supports them. +For devices that do not have sub-functions, +.Fa mask +should be set to 1. +.Ss The accessor interface +The +.Fn superio_get_dma +is used to get a DMA channel number configured for the device +.Fa dev . +.Pp +The +.Fn superio_get_iobase +is used to get a base I/O port configured for the device +.Fa dev . +The device may expose additional or alternative configuration access via +the I/O ports. +.Pp +The +.Fn superio_get_irq +is used to get an interrupt number configured for the device +.Fa dev . +.Pp +The +.Fn superio_get_ldn +is used to get a Logical Device Number of the device +.Fa dev . +.Pp +The +.Fn superio_get_type +is used to get a type of the device +.Fa dev . +.Sh SEE ALSO +.Xr superio 4 , +.Xr device 9 , +.Xr driver 9 +.Sh AUTHORS +This manual page was written by +.An Andriy Gapon Mt avg@FreeBSD.org diff --git a/static/freebsd/man9/swi.9 b/static/freebsd/man9/swi.9 new file mode 100644 index 00000000..ea6285b5 --- /dev/null +++ b/static/freebsd/man9/swi.9 @@ -0,0 +1,231 @@ +.\" Copyright (c) 2000-2001 John H. Baldwin +.\" +.\" 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 October 12, 2022 +.Dt SWI 9 +.Os +.Sh NAME +.Nm swi_add , +.Nm swi_remove , +.Nm swi_sched +.Nd register and schedule software interrupt handlers +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.In sys/interrupt.h +.Vt "extern struct intr_event *clk_intr_event" ; +.Ft int +.Fo swi_add +.Fa "struct intr_event **eventp" +.Fa "const char *name" +.Fa "driver_intr_t handler" +.Fa "void *arg" +.Fa "int pri" +.Fa "enum intr_type flags" +.Fa "void **cookiep" +.Fc +.Ft int +.Fn swi_remove "void *cookie" +.Ft void +.Fn swi_sched "void *cookie" "int flags" +.Sh DESCRIPTION +These functions are used to register and schedule software interrupt handlers. +Software interrupt handlers are attached to a software interrupt thread, just +as hardware interrupt handlers are attached to a hardware interrupt thread. +Multiple handlers can be attached to the same thread. +Software interrupt handlers can be used to queue up less critical processing +inside of hardware interrupt handlers so that the work can be done at a later +time. +Software interrupt threads are different from other kernel threads in that they +are treated as an interrupt thread. +This means that time spent executing these threads is counted as interrupt +time, and that they can be run via a lightweight context switch. +.Pp +The +.Fn swi_add +function is used to add a new software interrupt handler to a specified +interrupt event. +The +.Fa eventp +argument is an optional pointer to a +.Vt struct intr_event +pointer. +If this argument points to an existing event that holds a list of +interrupt handlers, then this handler will be attached to that event. +Otherwise a new event will be created, and if +.Fa eventp +is not +.Dv NULL , +then the pointer at that address to will be modified to point to the +newly created event. +The +.Fa name +argument is used to associate a name with a specific handler. +This name is appended to the name of the software interrupt thread that this +handler is attached to. +The +.Fa handler +argument is the function that will be executed when the handler is scheduled +to run. +The +.Fa arg +parameter will be passed in as the only parameter to +.Fa handler +when the function is executed. +The +.Fa pri +value specifies the priority of this interrupt handler relative to other +software interrupt handlers. +If an interrupt event is created, then this value is used as the vector, +and the +.Fa flags +argument is used to specify the attributes of a handler such as +.Dv INTR_MPSAFE . +The +.Fa cookiep +argument points to a +.Vt void * +cookie. +This cookie will be set to a value that uniquely identifies this handler, +and is used to schedule the handler for execution later on. +.Pp +The +.Fn swi_remove +function is used to teardown an interrupt handler pointed to by the +.Fa cookie +argument. +It detaches the interrupt handler from the associated interrupt event +and frees its memory. +.Pp +The +.Fn swi_sched +function is used to schedule an interrupt handler and its associated thread to +run. +The +.Fa cookie +argument specifies which software interrupt handler should be scheduled to run. +The +.Fa flags +argument specifies how and when the handler should be run and is a mask of one +or more of the following flags: +.Bl -tag -width SWI_FROMNMI +.It Dv SWI_DELAY +Specifies that the kernel should mark the specified handler as needing to run, +but the kernel should not schedule the software interrupt thread to run. +Instead, +.Fa handler +will be executed the next time that the software interrupt thread runs after +being scheduled by another event. +.It Dv SWI_FROMNMI +Specifies that +.Fn swi_sched +is called from NMI context and should be careful about used KPIs. +On platforms allowing IPI sending from NMI context it immediately wakes +.Va clk_intr_event +via the IPI, otherwise it works just like SWI_DELAY. +.El +.Pp +.Va clk_intr_event +is a pointer to the +.Vt struct intr_event +used to hang delayed handlers off of the clock interrupt, and is invoked +directly by +.Xr hardclock 9 . +.Sh RETURN VALUES +The +.Fn swi_add +and +.Fn swi_remove +functions return zero on success and non-zero on failure. +.Sh ERRORS +The +.Fn swi_add +function will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system-imposed limit on the total +number of processes under execution would be exceeded. +The limit is given by the +.Xr sysctl 3 +MIB variable +.Dv KERN_MAXPROC . +.It Bq Er EINVAL +The +.Fa flags +argument specifies +.Dv INTR_ENTROPY . +.It Bq Er EINVAL +The +.Fa eventp +argument points to a hardware interrupt thread. +.It Bq Er EINVAL +Either of the +.Fa name +or +.Fa handler +arguments are +.Dv NULL . +.It Bq Er EINVAL +The +.Dv INTR_EXCL +flag is specified and the interrupt event pointed to by +.Fa eventp +already has at least one handler, or the interrupt event already has an +exclusive handler. +.El +.Pp +The +.Fn swi_remove +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +A software interrupt handler pointed to by +.Fa cookie +is +.Dv NULL . +.El +.Sh SEE ALSO +.Xr hardclock 9 , +.Xr intr_event 9 , +.Xr taskqueue 9 +.Sh HISTORY +The +.Fn swi_add +and +.Fn swi_sched +functions first appeared in +.Fx 5.0 . +They replaced the +.Fn register_swi +function which appeared in +.Fx 3.0 +and the +.Fn setsoft* , +and +.Fn schedsoft* +functions which date back to at least +.Bx 4.4 . +The +.Fn swi_remove +function first appeared in +.Fx 6.1 . diff --git a/static/freebsd/man9/sx.9 b/static/freebsd/man9/sx.9 new file mode 100644 index 00000000..473a47c2 --- /dev/null +++ b/static/freebsd/man9/sx.9 @@ -0,0 +1,336 @@ +.\" +.\" Copyright (C) 2001 Jason Evans . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 November 11, 2017 +.Dt SX 9 +.Os +.Sh NAME +.Nm sx , +.Nm sx_init , +.Nm sx_init_flags , +.Nm sx_destroy , +.Nm sx_slock , +.Nm sx_xlock , +.Nm sx_slock_sig , +.Nm sx_xlock_sig , +.Nm sx_try_slock , +.Nm sx_try_xlock , +.Nm sx_sunlock , +.Nm sx_xunlock , +.Nm sx_unlock , +.Nm sx_try_upgrade , +.Nm sx_downgrade , +.Nm sx_sleep , +.Nm sx_xholder , +.Nm sx_xlocked , +.Nm sx_assert , +.Nm SX_SYSINIT , +.Nm SX_SYSINIT_FLAGS +.Nd kernel shared/exclusive lock +.Sh SYNOPSIS +.In sys/param.h +.In sys/lock.h +.In sys/sx.h +.Ft void +.Fn sx_init "struct sx *sx" "const char *description" +.Ft void +.Fn sx_init_flags "struct sx *sx" "const char *description" "int opts" +.Ft void +.Fn sx_destroy "struct sx *sx" +.Ft void +.Fn sx_slock "struct sx *sx" +.Ft void +.Fn sx_xlock "struct sx *sx" +.Ft int +.Fn sx_slock_sig "struct sx *sx" +.Ft int +.Fn sx_xlock_sig "struct sx *sx" +.Ft int +.Fn sx_try_slock "struct sx *sx" +.Ft int +.Fn sx_try_xlock "struct sx *sx" +.Ft void +.Fn sx_sunlock "struct sx *sx" +.Ft void +.Fn sx_xunlock "struct sx *sx" +.Ft void +.Fn sx_unlock "struct sx *sx" +.Ft int +.Fn sx_try_upgrade "struct sx *sx" +.Ft void +.Fn sx_downgrade "struct sx *sx" +.Ft int +.Fn sx_sleep "void *chan" "struct sx *sx" "int priority" "const char *wmesg" "int timo" +.Ft "struct thread *" +.Fn sx_xholder "struct sx *sx" +.Ft int +.Fn sx_xlocked "const struct sx *sx" +.Pp +.Cd "options INVARIANTS" +.Cd "options INVARIANT_SUPPORT" +.Ft void +.Fn sx_assert "const struct sx *sx" "int what" +.In sys/kernel.h +.Fn SX_SYSINIT "name" "struct sx *sx" "const char *desc" +.Fn SX_SYSINIT_FLAGS "name" "struct sx *sx" "const char *desc" "int flags" +.Sh DESCRIPTION +Shared/exclusive locks are used to protect data that are read far more often +than they are written. +Shared/exclusive locks do not implement priority propagation like mutexes and +reader/writer locks to prevent priority inversions, so +shared/exclusive locks should be used prudently. +.Pp +Shared/exclusive locks are created with either +.Fn sx_init +or +.Fn sx_init_flags +where +.Fa sx +is a pointer to space for a +.Vt struct sx , +and +.Fa description +is a pointer to a null-terminated character string that describes the +shared/exclusive lock. +The +.Fa opts +argument to +.Fn sx_init_flags +specifies a set of optional flags to alter the behavior of +.Fa sx . +It contains one or more of the following flags: +.Bl -tag -width SX_NOWITNESS +.It Dv SX_DUPOK +Witness should not log messages about duplicate locks being acquired. +.It Dv SX_NOWITNESS +Instruct +.Xr witness 4 +to ignore this lock. +.It Dv SX_NOPROFILE +Do not profile this lock. +.It Dv SX_RECURSE +Allow threads to recursively acquire exclusive locks for +.Fa sx . +.It Dv SX_QUIET +Do not log any operations for this lock via +.Xr ktr 4 . +.It Dv SX_NEW +If the kernel has been compiled with +.Cd "options INVARIANTS" , +.Fn sx_init +will assert that the +.Fa sx +has not been initialized multiple times without intervening calls to +.Fn sx_destroy +unless this option is specified. +.El +.Pp +Shared/exclusive locks are destroyed with +.Fn sx_destroy . +The lock +.Fa sx +must not be locked by any thread when it is destroyed. +.Pp +Threads acquire and release a shared lock by calling +.Fn sx_slock , +.Fn sx_slock_sig +or +.Fn sx_try_slock +and +.Fn sx_sunlock +or +.Fn sx_unlock . +Threads acquire and release an exclusive lock by calling +.Fn sx_xlock , +.Fn sx_xlock_sig +or +.Fn sx_try_xlock +and +.Fn sx_xunlock +or +.Fn sx_unlock . +A thread can attempt to upgrade a currently held shared lock to an exclusive +lock by calling +.Fn sx_try_upgrade . +A thread that has an exclusive lock can downgrade it to a shared lock by +calling +.Fn sx_downgrade . +.Pp +.Fn sx_try_slock +and +.Fn sx_try_xlock +will return 0 if the shared/exclusive lock cannot be acquired immediately; +otherwise the shared/exclusive lock will be acquired and a non-zero value will +be returned. +.Pp +.Fn sx_try_upgrade +will return 0 if the shared lock cannot be upgraded to an exclusive lock +immediately; otherwise the exclusive lock will be acquired and a non-zero value +will be returned. +.Pp +.Fn sx_slock_sig +and +.Fn sx_xlock_sig +do the same as their normal versions but performing an interruptible sleep. +They return a non-zero value if the sleep has been interrupted by a signal +or an interrupt, otherwise 0. +.Pp +A thread can atomically release a shared/exclusive lock while waiting for an +event by calling +.Fn sx_sleep . +For more details on the parameters to this function, +see +.Xr sleep 9 . +.Pp +When compiled with +.Cd "options INVARIANTS" +and +.Cd "options INVARIANT_SUPPORT" , +the +.Fn sx_assert +function tests +.Fa sx +for the assertions specified in +.Fa what , +and panics if they are not met. +One of the following assertions must be specified: +.Bl -tag -width ".Dv SA_UNLOCKED" +.It Dv SA_LOCKED +Assert that the current thread has either a shared or an exclusive lock on the +.Vt sx +lock pointed to by the first argument. +.It Dv SA_SLOCKED +Assert that the current thread has a shared lock on the +.Vt sx +lock pointed to by +the first argument. +.It Dv SA_XLOCKED +Assert that the current thread has an exclusive lock on the +.Vt sx +lock pointed to +by the first argument. +.It Dv SA_UNLOCKED +Assert that the current thread has no lock on the +.Vt sx +lock pointed to +by the first argument. +.El +.Pp +In addition, one of the following optional assertions may be included with +either an +.Dv SA_LOCKED , +.Dv SA_SLOCKED , +or +.Dv SA_XLOCKED +assertion: +.Bl -tag -width ".Dv SA_NOTRECURSED" +.It Dv SA_RECURSED +Assert that the current thread has a recursed lock on +.Fa sx . +.It Dv SA_NOTRECURSED +Assert that the current thread does not have a recursed lock on +.Fa sx . +.El +.Pp +.Fn sx_xholder +will return a pointer to the thread which currently holds an exclusive lock on +.Fa sx . +If no thread holds an exclusive lock on +.Fa sx , +then +.Dv NULL +is returned instead. +.Pp +.Fn sx_xlocked +will return non-zero if the current thread holds the exclusive lock; +otherwise, it will return zero. +.Pp +For ease of programming, +.Fn sx_unlock +is provided as a macro frontend to the respective functions, +.Fn sx_sunlock +and +.Fn sx_xunlock . +Algorithms that are aware of what state the lock is in should use either +of the two specific functions for a minor performance benefit. +.Pp +The +.Fn SX_SYSINIT +macro is used to generate a call to the +.Fn sx_sysinit +routine at system startup in order to initialize a given +.Fa sx +lock. +The parameters are the same as +.Fn sx_init +but with an additional argument, +.Fa name , +that is used in generating unique variable names for the related +structures associated with the lock and the sysinit routine. +The +.Fn SX_SYSINIT_FLAGS +macro can similarly be used to initialize a given +.Fa sx +lock using +.Fn sx_init_flags . +.Pp +A thread may not hold both a shared lock and an exclusive lock on the same +lock simultaneously; +attempting to do so will result in deadlock. +.Sh CONTEXT +A thread may hold a shared or exclusive lock on an +.Nm +lock while sleeping. +As a result, an +.Nm +lock may not be acquired while holding a mutex. +Otherwise, if one thread slept while holding an +.Nm +lock while another thread blocked on the same +.Nm +lock after acquiring a mutex, then the second thread would effectively +end up sleeping while holding a mutex, which is not allowed. +.Sh SEE ALSO +.Xr lock 9 , +.Xr locking 9 , +.Xr mutex 9 , +.Xr panic 9 , +.Xr rwlock 9 , +.Xr sema 9 +.Sh BUGS +A kernel without +.Dv WITNESS +cannot assert whether the current thread does or does not hold a shared lock. +.Dv SA_LOCKED +and +.Dv SA_SLOCKED +can only assert that +.Em any +thread holds a shared lock. +They cannot ensure that the current thread holds a shared lock. +Further, +.Dv SA_UNLOCKED +can only assert that the current thread does not hold an exclusive lock. diff --git a/static/freebsd/man9/syscall_helper_register.9 b/static/freebsd/man9/syscall_helper_register.9 new file mode 100644 index 00000000..bad8eee3 --- /dev/null +++ b/static/freebsd/man9/syscall_helper_register.9 @@ -0,0 +1,137 @@ +.\" Copyright (c) 2018 Conrad Meyer +.\" 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 February 10, 2018 +.Dt SYSCALL_HELPER_REGISTER 9 +.Os +.Sh NAME +.Nm syscall_helper_register , +.Nm syscall_helper_unregister +.Nd kernel syscall registration routines +.\" +.Sh SYNOPSIS +.In sys/sysent.h +.Ft int +.Fn syscall_helper_register "struct syscall_helper_data *sd" "int flags" +.Ft int +.Fn syscall_helper_unregister "struct syscall_helper_data *sd" +.\" +.Ss INITIALIZER MACROS +.Ft struct syscall_helper_data +.Fn SYSCALL_INIT_HELPER "syscallname" +.Ft struct syscall_helper_data +.Fn SYSCALL_INIT_HELPER_F "syscallname" "int flags" +.\" +.Ss COMPATIBILITY INITIALIZER MACROS +.Ft struct syscall_helper_data +.Fn SYSCALL_INIT_HELPER_COMPAT "syscallname" +.Ft struct syscall_helper_data +.Fn SYSCALL_INIT_HELPER_COMPAT_F "syscallname" "int flags" +.\" +.Sh DESCRIPTION +The +.Fn syscall_helper_register +registers a system call. +This function takes the structure +.Va struct syscall_helper_data sd , +which specifies the parameters for syscall registration: +.Pp +.Bd -literal -offset indent -compact +struct syscall_helper_data { + struct sysent new_sysent; + struct sysent old_sysent; + int syscall_no; + int registered; +}; +.Ed +.Pp +The only valid flag for the +.Fa flags +argument to +.Fn syscall_helper_register +is +.Dv SY_THR_STATIC . +This flag prevents the syscall from being unregistered. +.\" +.Pp +Before use, the structure must be initialized with one of the +.Fn SYSCALL_INIT_HELPER* +macros. +In new code, syscall implementation functions shall be named +.Fn sys_syscallname +and the regular macros shall be used. +.Pp +For legacy syscall functions named without "sys_" prefixes, the "COMPAT" +versions of the macros may be used. +.Pp +The only valid flag for the +.Fa flags +argument to the "F" variants of the initializer macros is +.Dv SYF_CAPENABLED . +This flag indicates that the syscall is allowed in capability mode. +.Pp +The +.Fn syscall_helper_unregister +unregisters a system call. +This function takes the same structure +.Va struct syscall_helper_data sd +that was previously initialized in the manner described above and used in a +successful invocation of +.Fn syscall_helper_register . +.\" +.Sh RETURN VALUES +If successful, +.Fn syscall_helper_register +and +.Fn syscall_helper_unregister +will return 0. +Otherwise, they will return an error. +.\" +.Sh ERRORS +The +.Fn syscall_helper_register +call will fail and the syscall will not be registered if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa flags +argument contained a value other than +.Dv SY_THR_STATIC . +.It Bq Er EINVAL +The specified syscall number, +.Dv sd.syscall_no +.Dv ( SYS_syscallname ) , +was outside of the valid range of system call numbers (zero through +.Dv SYS_MAXSYSCALL ) . +.It Bq Er ENFILE +The system call table does not have any available slots. +.It Bq Er EEXIST +The specified syscall number, +.Dv sd.syscall_no +.Dv ( SYS_syscallname ) , +was already in use. +.El +.\" +.Sh SEE ALSO +.Xr SYSCALL_MODULE 9 diff --git a/static/freebsd/man9/sysctl.9 b/static/freebsd/man9/sysctl.9 new file mode 100644 index 00000000..31031e64 --- /dev/null +++ b/static/freebsd/man9/sysctl.9 @@ -0,0 +1,1119 @@ +.\" +.\" Copyright (c) 2006 Robert N. M. Watson +.\" 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 September 28, 2025 +.Dt SYSCTL 9 +.Os +.Sh NAME +.Nm SYSCTL_DECL , +.Nm SYSCTL_ADD_BOOL , +.Nm SYSCTL_ADD_COUNTER_U64 , +.Nm SYSCTL_ADD_COUNTER_U64_ARRAY , +.Nm SYSCTL_ADD_INT , +.Nm SYSCTL_ADD_LONG , +.Nm SYSCTL_ADD_NODE , +.Nm SYSCTL_ADD_NODE_WITH_LABEL , +.Nm SYSCTL_ADD_OPAQUE , +.Nm SYSCTL_ADD_PROC , +.Nm SYSCTL_ADD_QUAD , +.Nm SYSCTL_ADD_ROOT_NODE , +.Nm SYSCTL_ADD_S8 , +.Nm SYSCTL_ADD_S16 , +.Nm SYSCTL_ADD_S32 , +.Nm SYSCTL_ADD_S64 , +.Nm SYSCTL_ADD_SBINTIME_MSEC , +.Nm SYSCTL_ADD_SBINTIME_USEC , +.Nm SYSCTL_ADD_STRING , +.Nm SYSCTL_ADD_CONST_STRING , +.Nm SYSCTL_ADD_STRUCT , +.Nm SYSCTL_ADD_TIMEVAL_SEC , +.Nm SYSCTL_ADD_U8 , +.Nm SYSCTL_ADD_U16 , +.Nm SYSCTL_ADD_U32 , +.Nm SYSCTL_ADD_U64 , +.Nm SYSCTL_ADD_UAUTO , +.Nm SYSCTL_ADD_UINT , +.Nm SYSCTL_ADD_ULONG , +.Nm SYSCTL_ADD_UMA_CUR , +.Nm SYSCTL_ADD_UMA_MAX , +.Nm SYSCTL_ADD_UQUAD , +.Nm SYSCTL_CHILDREN , +.Nm SYSCTL_STATIC_CHILDREN , +.Nm SYSCTL_NODE_CHILDREN , +.Nm SYSCTL_PARENT , +.Nm SYSCTL_BOOL , +.Nm SYSCTL_COUNTER_U64 , +.Nm SYSCTL_COUNTER_U64_ARRAY , +.Nm SYSCTL_INT , +.Nm SYSCTL_INT_WITH_LABEL , +.Nm SYSCTL_LONG , +.Nm sysctl_msec_to_ticks , +.Nm SYSCTL_NODE , +.Nm SYSCTL_NODE_WITH_LABEL , +.Nm SYSCTL_OPAQUE , +.Nm SYSCTL_PROC , +.Nm SYSCTL_QUAD , +.Nm SYSCTL_ROOT_NODE , +.Nm SYSCTL_S8 , +.Nm SYSCTL_S16 , +.Nm SYSCTL_S32 , +.Nm SYSCTL_S64 , +.Nm SYSCTL_SBINTIME_MSEC , +.Nm SYSCTL_SBINTIME_USEC , +.Nm SYSCTL_STRING , +.Nm SYSCTL_CONST_STRING , +.Nm SYSCTL_STRUCT , +.Nm SYSCTL_TIMEVAL_SEC , +.Nm SYSCTL_U8 , +.Nm SYSCTL_U16 , +.Nm SYSCTL_U32 , +.Nm SYSCTL_U64 , +.Nm SYSCTL_UINT , +.Nm SYSCTL_ULONG , +.Nm SYSCTL_UMA_CUR , +.Nm SYSCTL_UMA_MAX , +.Nm SYSCTL_UQUAD +.Nd Dynamic and static sysctl MIB creation functions +.Sh SYNOPSIS +.In sys/param.h +.In sys/sysctl.h +.Fn SYSCTL_DECL name +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_BOOL +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "bool *ptr" +.Fa "uint8_t val" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_COUNTER_U64 +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "counter_u64_t *ptr" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_COUNTER_U64_ARRAY +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "counter_u64_t *ptr" +.Fa "intmax_t len" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_INT +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "int *ptr" +.Fa "int val" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_LONG +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "long *ptr" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_NODE +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "int (*handler)(SYSCTL_HANDLER_ARGS)" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_NODE_WITH_LABEL +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "int (*handler)(SYSCTL_HANDLER_ARGS)" +.Fa "const char *descr" +.Fa "const char *label" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_OPAQUE +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "void *ptr" +.Fa "intptr_t len" +.Fa "const char *format" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_PROC +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "void *arg1" +.Fa "intptr_t arg2" +.Fa "int (*handler) (SYSCTL_HANDLER_ARGS)" +.Fa "const char *format" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_QUAD +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "int64_t *ptr" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_ROOT_NODE +.Fa "struct sysctl_ctx_list *ctx" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "int (*handler)(SYSCTL_HANDLER_ARGS)" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_S8 +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "int8_t *ptr" +.Fa "int8_t val" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_S16 +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "int16_t *ptr" +.Fa "int16_t val" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_S32 +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "int32_t *ptr" +.Fa "int32_t val" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_S64 +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "int64_t *ptr" +.Fa "int64_t val" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_SBINTIME_MSEC +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "sbintime_t *ptr" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_SBINTIME_USEC +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "sbintime_t *ptr" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_STRING +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "char *ptr" +.Fa "intptr_t len" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_CONST_STRING +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "const char *ptr" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_STRUCT +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "void *ptr" +.Fa struct_type +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_TIMEVAL_SEC +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "struct timeval *ptr" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_U8 +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "uint8_t *ptr" +.Fa "uint8_t val" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_U16 +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "uint16_t *ptr" +.Fa "uint16_t val" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_U32 +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "uint32_t *ptr" +.Fa "uint32_t val" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_U64 +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "uint64_t *ptr" +.Fa "uint64_t val" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_UINT +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "unsigned int *ptr" +.Fa "unsigned int val" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_ULONG +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "unsigned long *ptr" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_UQUAD +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "uint64_t *ptr" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_UMA_CUR +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "uma_zone_t ptr" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_UMA_MAX +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "uma_zone_t ptr" +.Fa "const char *descr" +.Fc +.Fa "const char *descr" +.Ft struct sysctl_oid * +.Fo SYSCTL_ADD_UAUTO +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int ctlflags" +.Fa "void *ptr" +.Fa "const char *descr" +.Fc +.Ft struct sysctl_oid_list * +.Fo SYSCTL_CHILDREN +.Fa "struct sysctl_oid *oidp" +.Fc +.Ft struct sysctl_oid_list * +.Fo SYSCTL_STATIC_CHILDREN +.Fa "struct sysctl_oid_list OID_NAME" +.Fc +.Ft struct sysctl_oid_list * +.Fo SYSCTL_NODE_CHILDREN +.Fa "parent" +.Fa "name" +.Fc +.Ft struct sysctl_oid * +.Fo SYSCTL_PARENT +.Fa "struct sysctl_oid *oid" +.Fc +.Fn SYSCTL_BOOL parent number name ctlflags ptr val descr +.Fn SYSCTL_COUNTER_U64 parent number name ctlflags ptr descr +.Fn SYSCTL_COUNTER_U64_ARRAY parent number name ctlflags ptr len descr +.Fn SYSCTL_INT parent number name ctlflags ptr val descr +.Fn SYSCTL_INT_WITH_LABEL parent number name ctlflags ptr val descr label +.Fn SYSCTL_LONG parent number name ctlflags ptr val descr +.Ft int +.Fn sysctl_msec_to_ticks SYSCTL_HANDLER_ARGS +.Fn SYSCTL_NODE parent number name ctlflags handler descr +.Fn SYSCTL_NODE_WITH_LABEL parent number name ctlflags handler descr label +.Fn SYSCTL_OPAQUE parent number name ctlflags ptr len format descr +.Fn SYSCTL_PROC parent number name ctlflags arg1 arg2 handler format descr +.Fn SYSCTL_QUAD parent number name ctlflags ptr val descr +.Fn SYSCTL_ROOT_NODE number name ctlflags handler descr +.Fn SYSCTL_S8 parent number name ctlflags ptr val descr +.Fn SYSCTL_S16 parent number name ctlflags ptr val descr +.Fn SYSCTL_S32 parent number name ctlflags ptr val descr +.Fn SYSCTL_S64 parent number name ctlflags ptr val descr +.Fn SYSCTL_SBINTIME_MSEC parent number name ctlflags ptr descr +.Fn SYSCTL_SBINTIME_USEC parent number name ctlflags ptr descr +.Fn SYSCTL_STRING parent number name ctlflags arg len descr +.Fn SYSCTL_CONST_STRING parent number name ctlflags arg descr +.Fn SYSCTL_STRUCT parent number name ctlflags ptr struct_type descr +.Fn SYSCTL_TIMEVAL_SEC parent number name ctlflags ptr descr +.Fn SYSCTL_U8 parent number name ctlflags ptr val descr +.Fn SYSCTL_U16 parent number name ctlflags ptr val descr +.Fn SYSCTL_U32 parent number name ctlflags ptr val descr +.Fn SYSCTL_U64 parent number name ctlflags ptr val descr +.Fn SYSCTL_UINT parent number name ctlflags ptr val descr +.Fn SYSCTL_ULONG parent number name ctlflags ptr val descr +.Fn SYSCTL_UQUAD parent number name ctlflags ptr val descr +.Fn SYSCTL_UMA_MAX parent number name ctlflags ptr descr +.Fn SYSCTL_UMA_CUR parent number name ctlflags ptr descr +.Sh DESCRIPTION +The +.Nm SYSCTL +kernel interface allows dynamic or static creation of +.Xr sysctl 8 +MIB entries. +All static sysctls are automatically destroyed when the module which +they are part of is unloaded. +Most top level categories are created statically and are available to +all kernel code and its modules. +.Sh DESCRIPTION OF ARGUMENTS +.Bl -tag -width ctlflags +.It Fa ctx +Pointer to sysctl context or NULL, if no context. +See +.Xr sysctl_ctx_init 9 +for how to create a new sysctl context. +Programmers are strongly advised to use contexts to organize the +dynamic OIDs which they create because when a context is destroyed all +belonging sysctls are destroyed as well. +This makes the sysctl cleanup code much simpler. +Else deletion of all created OIDs is required at module unload. +.It Fa parent +A pointer to a +.Li struct sysctl_oid_list , +which is the head of the parent's list of children. +This pointer is retrieved using the +.Fn SYSCTL_STATIC_CHILDREN +macro for static sysctls and the +.Fn SYSCTL_CHILDREN +macro for dynamic sysctls. +The +.Fn SYSCTL_PARENT +macro can be used to get the parent of an OID. +The macro returns NULL if there is no parent. +.It Fa number +The OID number that will be assigned to this OID. +In almost all cases this should be set to +.Dv OID_AUTO , +which will result in the assignment of the next available OID number. +.It Fa name +The name of the OID. +The newly created OID will contain a copy of the name. +.It Fa ctlflags +A bit mask of sysctl control flags. +See the section below describing all the control flags. +.It Fa arg1 +First callback argument for procedure sysctls. +.It Fa arg2 +Second callback argument for procedure sysctls. +.It Fa len +The length of the data pointed to by the +.Fa ptr +argument. +For string type OIDs a length of zero means that +.Xr strlen 3 +will be used to get the length of the string at each access to the OID. +For array type OIDs the length must be greater than zero. +.It Fa ptr +Pointer to sysctl variable or string data. +For sysctl values the pointer can be SYSCTL_NULL_XXX_PTR which means the OID is read-only and the returned value should be taken from the +.Fa val +argument. +.It Fa val +If the +.Fa ptr +argument is SYSCTL_NULL_XXX_PTR, gives the constant value returned by this OID. +Else this argument is not used. +.It Fa struct_type +Name of structure type. +.It Fa handler +A pointer to the function +that is responsible for handling read and write requests +to this OID. +There are several standard handlers +that support operations on nodes, +integers, strings and opaque objects. +It is possible to define custom handlers using the +.Fn SYSCTL_PROC +macro or the +.Fn SYSCTL_ADD_PROC +function. +.It Fa format +A pointer to a string +which specifies the format of the OID in a symbolic way. +This format is used as a hint by +.Xr sysctl 8 +to apply proper data formatting for display purposes. +.Pp +Current formats: +.Bl -tag -width "S,TYPE" -compact -offset indent +.It Cm N +node +.It Cm A +.Li "char *" +.It Cm C +.Li "int8_t" +.It Cm CU +.Li "uint8_t" +.It Cm I +.Li "int" +.It Cm IK Ns Op Ar n +temperature in Kelvin, multiplied by an optional single digit +power of ten scaling factor: 1 (default) gives deciKelvin, 0 gives Kelvin, 3 +gives milliKelvin +.It Cm IU +.Li "unsigned int" +.It Cm L +.Li "long" +.It Cm LU +.Li "unsigned long" +.It Cm Q +.Li "quad_t" +.It Cm QU +.Li "u_quad_t" +.It Cm S +.Li "int16_t" +.It Cm SU +.Li "uint16_t" +.It Cm "S,TYPE" +.Li "struct TYPE" +structures +.El +.It Fa descr +A pointer to a textual description of the OID. +.It Fa label +A pointer to an aggregation label for this component of the OID. +To make it easier to export sysctl data to monitoring systems that +support aggregations through labels (e.g., Prometheus), +this argument can be used to attach a label name to an OID. +The label acts as a hint that this component's name should not be part +of the metric's name, +but attached to the metric as a label instead. +.Pp +Labels should only be applied to siblings that are structurally similar +and encode the same type of value, +as aggregation is of no use otherwise. +.El +.Sh NODE VALUE TYPES +Most of the macros and functions used to create sysctl nodes export a +read-only constant or in-kernel variable whose type matches the type +of the node's value. +For example, +.Fn SYSCTL_INT +reports the raw value of an associated variable of type +.Vt int . +However, nodes may also export a value that is a translation of an internal +representation. +.Pp +The +.Fn sysctl_msec_to_ticks +handler can be used with +.Fn SYSCTL_PROC +or +.Fn SYSCTL_ADD_PROC +to export a millisecond time interval. +When using this handler, +the +.Fa arg2 +parameter points to an in-kernel variable of type +.Vt int +which stores a tick count suitable for use with functions like +.Xr tsleep 9 . +The +.Fn sysctl_msec_to_ticks +function converts this value to milliseconds when reporting the node's value. +Similarly, +.Fn sysctl_msec_to_ticks +accepts new values in milliseconds and stores an equivalent value in ticks to +.Fa *arg2 . +Note that new code should use kernel variables of type +.Vt sbintime_t +instead of tick counts. +.Pp +The +.Fn SYSCTL_ADD_SBINTIME_MSEC +and +.Fn SYSCTL_ADD_SBINTIME_USEC +functions and +.Fn SYSCTL_SBINTIME_MSEC +and +.Fn SYSCTL_SBINTIME_USEC +macros all create nodes which export an in-kernel variable of type +.Vt sbintime_t . +These nodes do not export the raw value of the associated variable. +Instead, they export a 64-bit integer containing a count of either +milliseconds (the MSEC variants) or microseconds (the USEC variants). +.Pp +The +.Fn SYSCTL_ADD_TIMEVAL_SEC +function and +.Fn SYSCTL_TIMEVAL_SEC +macro create nodes which export an in-kernel variable of type +.Vt struct timeval . +These nodes do not export full value of the associated structure. +Instead, they export a count in seconds as a simple integer which is +stored in the +.Fa tv_sec +field of the associated variable. +This function and macro are intended to be used with variables which +store a non-negative interval rather than an absolute time. +As a result, they reject attempts to store negative values. +.Sh CREATING ROOT NODES +Sysctl MIBs or OIDs are created in a hierarchical tree. +The nodes at the bottom of the tree are called root nodes, and have no +parent OID. +To create bottom tree nodes the +.Fn SYSCTL_ROOT_NODE +macro or the +.Fn SYSCTL_ADD_ROOT_NODE +function needs to be used. +By default all static sysctl node OIDs are global and need a +.Fn SYSCTL_DECL +statement prior to their +.Fn SYSCTL_NODE +definition statement, typically in a so-called header file. +.Sh CREATING SYSCTL STRINGS +Zero terminated character strings sysctls are created either using the +.Fn SYSCTL_STRING +macro or the +.Fn SYSCTL_ADD_STRING +function. +If the +.Fa len +argument is zero, the string length is computed at every access to the OID using +.Xr strlen 3 . +Use the +.Fn SYSCTL_CONST_STRING +macro or the +.Fn SYSCTL_ADD_CONST_STRING +function to add a sysctl for a constant string. +.Sh CREATING OPAQUE SYSCTLS +The +.Fn SYSCTL_OPAQUE +or +.Fn SYSCTL_STRUCT +macros or the +.Fn SYSCTL_ADD_OPAQUE +or +.Fn SYSCTL_ADD_STRUCT +functions create an OID that handle any chunk of data +of the size specified by the +.Fa len +argument and data pointed to by the +.Fa ptr +argument. +When using the structure version the type is encoded as part of the +created sysctl. +.Sh CREATING CUSTOM SYSCTLS +The +.Fn SYSCTL_PROC +macro and the +.Fn SYSCTL_ADD_PROC +function +create OIDs with the specified +.Pa handler +function. +The handler is responsible for handling all read and write requests to +the OID. +This OID type is especially useful if the kernel data is not easily +accessible, or needs to be processed before exporting. +.Sh CREATING A STATIC SYSCTL +Static sysctls are declared using one of the +.Fn SYSCTL_BOOL , +.Fn SYSCTL_COUNTER_U64 , +.Fn SYSCTL_COUNTER_U64_ARRAY , +.Fn SYSCTL_INT , +.Fn SYSCTL_INT_WITH_LABEL , +.Fn SYSCTL_LONG , +.Fn SYSCTL_NODE , +.Fn SYSCTL_NODE_WITH_LABEL , +.Fn SYSCTL_OPAQUE , +.Fn SYSCTL_PROC , +.Fn SYSCTL_QUAD , +.Fn SYSCTL_ROOT_NODE , +.Fn SYSCTL_S8 , +.Fn SYSCTL_S16 , +.Fn SYSCTL_S32 , +.Fn SYSCTL_S64 , +.Fn SYSCTL_SBINTIME_MSEC , +.Fn SYSCTL_SBINTIME_USEC , +.Fn SYSCTL_STRING , +.Fn SYSCTL_CONST_STRING , +.Fn SYSCTL_STRUCT , +.Fn SYSCTL_TIMEVAL_SEC , +.Fn SYSCTL_U8 , +.Fn SYSCTL_U16 , +.Fn SYSCTL_U32 , +.Fn SYSCTL_U64 , +.Fn SYSCTL_UINT , +.Fn SYSCTL_ULONG , +.Fn SYSCTL_UQUAD , +.Fn SYSCTL_UMA_CUR +or +.Fn SYSCTL_UMA_MAX +macros. +.Sh CREATING A DYNAMIC SYSCTL +Dynamic nodes are created using one of the +.Fn SYSCTL_ADD_BOOL , +.Fn SYSCTL_ADD_COUNTER_U64 , +.Fn SYSCTL_ADD_COUNTER_U64_ARRAY , +.Fn SYSCTL_ADD_INT , +.Fn SYSCTL_ADD_LONG , +.Fn SYSCTL_ADD_NODE , +.Fn SYSCTL_ADD_NODE_WITH_LABEL , +.Fn SYSCTL_ADD_OPAQUE , +.Fn SYSCTL_ADD_PROC , +.Fn SYSCTL_ADD_QUAD , +.Fn SYSCTL_ADD_ROOT_NODE , +.Fn SYSCTL_ADD_S8 , +.Fn SYSCTL_ADD_S16 , +.Fn SYSCTL_ADD_S32 , +.Fn SYSCTL_ADD_S64 , +.Fn SYSCTL_ADD_SBINTIME_MSEC , +.Fn SYSCTL_ADD_SBINTIME_USEC , +.Fn SYSCTL_ADD_STRING , +.Fn SYSCTL_ADD_CONST_STRING , +.Fn SYSCTL_ADD_STRUCT , +.Fn SYSCTL_ADD_TIMEVAL_SEC , +.Fn SYSCTL_ADD_U8 , +.Fn SYSCTL_ADD_U16 , +.Fn SYSCTL_ADD_U32 , +.Fn SYSCTL_ADD_U64 , +.Fn SYSCTL_ADD_UAUTO , +.Fn SYSCTL_ADD_UINT , +.Fn SYSCTL_ADD_ULONG , +.Fn SYSCTL_ADD_UQUAD , +.Fn SYSCTL_ADD_UMA_CUR +or +.Fn SYSCTL_ADD_UMA_MAX +functions. +See +.Xr sysctl_remove_oid 9 +or +.Xr sysctl_ctx_free 9 +for more information on how to destroy a dynamically created OID. +.Sh CONTROL FLAGS +For most of the above functions and macros, declaring a type as part +of the access flags is not necessary \[em] however, when declaring a +sysctl implemented by a function, including a type in the access mask +is required: +.Bl -tag -width ".Dv CTLTYPE_NOFETCH" +.It Dv CTLTYPE_NODE +This is a node intended to be a parent for other nodes. +.It Dv CTLTYPE_INT +This is a signed integer. +.It Dv CTLTYPE_STRING +This is a nul-terminated string stored in a character array. +.It Dv CTLTYPE_S8 +This is an 8-bit signed integer. +.It Dv CTLTYPE_S16 +This is a 16-bit signed integer. +.It Dv CTLTYPE_S32 +This is a 32-bit signed integer. +.It Dv CTLTYPE_S64 +This is a 64-bit signed integer. +.It Dv CTLTYPE_OPAQUE +This is an opaque data structure. +.It Dv CTLTYPE_STRUCT +Alias for +.Dv CTLTYPE_OPAQUE . +.It Dv CTLTYPE_U8 +This is an 8-bit unsigned integer. +.It Dv CTLTYPE_U16 +This is a 16-bit unsigned integer. +.It Dv CTLTYPE_U32 +This is a 32-bit unsigned integer. +.It Dv CTLTYPE_U64 +This is a 64-bit unsigned integer. +.It Dv CTLTYPE_UINT +This is an unsigned integer. +.It Dv CTLTYPE_LONG +This is a signed long. +.It Dv CTLTYPE_ULONG +This is an unsigned long. +.El +.Pp +All sysctl types except for new node declarations require one of the following +flags to be set indicating the read and write disposition of the sysctl: +.Bl -tag -width ".Dv CTLFLAG_ANYBODY" +.It Dv CTLFLAG_RD +This is a read-only sysctl. +.It Dv CTLFLAG_RDTUN +This is a read-only sysctl and tunable which is fetched once +from the system environment early during module load or system boot. +.It Dv CTLFLAG_WR +This is a writable sysctl. +.It Dv CTLFLAG_RW +This sysctl is readable and writable. +.It Dv CTLFLAG_RWTUN +This is a readable and writeable sysctl and tunable which is +fetched once from the system environment early during module load or +system boot. +.It Dv CTLFLAG_NOFETCH +In case the node is marked as a tunable using the CTLFLAG_[XX]TUN, +this flag will prevent fetching the initial value from the system +environment. +Typically this flag should only be used for very early +low level system setup code, and not by common drivers and modules. +.It Dv CTLFLAG_MPSAFE +This +.Xr sysctl 9 +handler is MP safe. +Do not grab Giant around calls to this handler. +This should only be used for +.Fn SYSCTL_PROC +entries. +.El +.Pp +Additionally, any of the following optional flags may also be specified: +.Bl -tag -width ".Dv CTLFLAG_ANYBODY" +.It Dv CTLFLAG_ANYBODY +Any user or process can write to this sysctl. +.It Dv CTLFLAG_CAPRD +A process in capability mode can read from this sysctl. +.It Dv CTLFLAG_CAPWR +A process in capability mode can write to this sysctl. +.It Dv CTLFLAG_SECURE +This sysctl can be written to only if the effective securelevel of the +process is \[<=] 0. +.It Dv CTLFLAG_PRISON +This sysctl can be written to by processes in +.Xr jail 2 . +.It Dv CTLFLAG_SKIP +When iterating the sysctl name space, do not list this sysctl. +.It Dv CTLFLAG_TUN +Advisory flag that a system tunable also exists for this variable. +The initial sysctl value is fetched once from the system +environment early during module load or system boot. +.It Dv CTLFLAG_DYN +Dynamically created OIDs automatically get this flag set. +.It Dv CTLFLAG_VNET +OID references a VIMAGE-enabled variable. +.El +.Sh EXAMPLES +Sample use of +.Fn SYSCTL_DECL +to declare the +.Va security +sysctl tree for use by new nodes: +.Bd -literal -offset indent +SYSCTL_DECL(_security); +.Ed +.Pp +Examples of integer, opaque, string, and procedure sysctls follow: +.Bd -literal -offset indent +/* + * Example of a constant integer value. Notice that the control + * flags are CTLFLAG_RD, the variable pointer is SYSCTL_NULL_INT_PTR, + * and the value is declared. + */ +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 + * flags are CTLFLAG_RW, the variable pointer is set, and the + * value is 0. + */ +static int doingcache = 1; /* 1 => enable the cache */ +SYSCTL_INT(_debug, OID_AUTO, vfscache, CTLFLAG_RW, &doingcache, 0, + "Enable name cache"); + +/* + * Example of a variable string value. Notice that the control + * flags are CTLFLAG_RW, that the variable pointer and string + * size are set. Unlike newer sysctls, this older sysctl uses a + * static oid number. + */ +char kernelname[MAXPATHLEN] = "/kernel"; /* XXX bloat */ +SYSCTL_STRING(_kern, KERN_BOOTFILE, bootfile, CTLFLAG_RW, + kernelname, sizeof(kernelname), "Name of kernel file booted"); + +/* + * Example of an opaque data type exported by sysctl. Notice that + * the variable pointer and size are provided, as well as a format + * string for sysctl(8). + */ +static l_fp pps_freq; /* scaled frequency offset (ns/s) */ +SYSCTL_OPAQUE(_kern_ntp_pll, OID_AUTO, pps_freq, CTLFLAG_RD, + &pps_freq, sizeof(pps_freq), "I", ""); + +/* + * Example of a procedure based sysctl exporting string + * information. Notice that the data type is declared, the NULL + * variable pointer and 0 size, the function pointer, and the + * format string for sysctl(8). + */ +SYSCTL_PROC(_kern_timecounter, OID_AUTO, hardware, CTLTYPE_STRING | + CTLFLAG_RW, NULL, 0, sysctl_kern_timecounter_hardware, "A", + ""); +.Ed +.Pp +The following is an example of +how to create a new top-level category +and how to hook up another subtree to an existing static node. +This example does not use contexts, +which results in tedious management of all intermediate oids, +as they need to be freed later on: +.Bd -literal -offset indent +#include + ... +/* + * Need to preserve pointers to newly created subtrees, + * to be able to free them later: + */ +static struct sysctl_oid *root1; +static struct sysctl_oid *root2; +static struct sysctl_oid *oidp; +static int a_int; +static char *string = "dynamic sysctl"; + ... + +root1 = SYSCTL_ADD_ROOT_NODE(NULL, + OID_AUTO, "newtree", CTLFLAG_RW, 0, "new top level tree"); +oidp = SYSCTL_ADD_INT(NULL, SYSCTL_CHILDREN(root1), + OID_AUTO, "newint", CTLFLAG_RW, &a_int, 0, "new int leaf"); + ... +root2 = SYSCTL_ADD_NODE(NULL, SYSCTL_STATIC_CHILDREN(_debug), + OID_AUTO, "newtree", CTLFLAG_RW, 0, "new tree under debug"); +oidp = SYSCTL_ADD_STRING(NULL, SYSCTL_CHILDREN(root2), + OID_AUTO, "newstring", CTLFLAG_RD, string, 0, "new string leaf"); +.Ed +.Pp +This example creates the following subtrees: +.Bd -literal -offset indent +debug.newtree.newstring +newtree.newint +.Ed +.Pp +.Em "Care should be taken to free all OIDs once they are no longer needed!" +.Sh SYSCTL NAMING +When adding, modifying, or removing sysctl names, it is important to be +aware that these interfaces may be used by users, libraries, applications, +or documentation (such as published books), and are implicitly published application interfaces. +As with other application interfaces, caution must be taken not to break +existing applications, and to think about future use of new name spaces so as +to avoid the need to rename or remove interfaces that might be depended on in +the future. +.Pp +The semantics chosen for a new sysctl should be as clear as possible, +and the name of the sysctl must closely reflect its semantics. +Therefore the sysctl name deserves a fair amount of consideration. +It should be short but yet representative of the sysctl meaning. +If the name consists of several words, they should be separated by +underscore characters, as in +.Va compute_summary_at_mount . +Underscore characters may be omitted only if the name consists of not more +than two words, each being not longer than four characters, as in +.Va bootfile . +.Pp +For boolean sysctls, negative logic should be totally avoided. +That is, do not use names like +.Va no_foobar +or +.Va foobar_disable . +They are confusing and lead to configuration errors. +Use positive logic instead: +.Va foobar , +.Va foobar_enable . +.Pp +A temporary sysctl node OID that should not be relied upon must be designated +as such by a leading underscore character in its name. +For example: +.Va _dirty_hack . +.Sh SEE ALSO +.Xr sysctl 3 , +.Xr sysctl 8 , +.Xr device_get_sysctl 9 , +.Xr sysctl_add_oid 9 , +.Xr sysctl_ctx_free 9 , +.Xr sysctl_ctx_init 9 , +.Xr sysctl_remove_oid 9 +.Sh HISTORY +The +.Xr sysctl 8 +utility first appeared in +.Bx 4.4 . +.Nm SYSCTL_ADD_CONST_STRING +first appeared in +.Fx 12.1 . +.Sh AUTHORS +.An -nosplit +The +.Nm sysctl +implementation originally found in +.Bx +has been extensively rewritten by +.An Poul-Henning Kamp +in order to add support for name lookups, name space iteration, and dynamic +addition of MIB nodes. +.Pp +This man page was written by +.An Robert N. M. Watson . +.Sh SECURITY CONSIDERATIONS +When creating new sysctls, careful attention should be paid to the security +implications of the monitoring or management interface being created. +Most sysctls present in the kernel are read-only or writable only by the +superuser. +Sysctls exporting extensive information on system data structures and +operation, especially those implemented using procedures, will wish to +implement access control to limit the undesired exposure of information about +other processes, network connections, etc. +.Pp +The following top level sysctl name spaces are commonly used: +.Bl -tag -width ".Va regression" +.It Va compat +Compatibility layer information. +.It Va debug +Debugging information. +Various name spaces exist under +.Va debug . +.It Va hw +Hardware and device driver information. +.It Va kern +Kernel behavior tuning; generally deprecated in favor of more specific +name spaces. +.It Va machdep +Machine-dependent configuration parameters. +.It Va net +Network subsystem. +Various protocols have name spaces under +.Va net . +.It Va regression +Regression test configuration and information. +.It Va security +Security and security-policy configuration and information. +.It Va sysctl +Reserved name space for the implementation of sysctl. +.It Va user +Configuration settings relating to user application behavior. +Generally, configuring applications using kernel sysctls is discouraged. +.It Va vfs +Virtual file system configuration and information. +.It Va vm +Virtual memory subsystem configuration and information. +.El diff --git a/static/freebsd/man9/sysctl_add_oid.9 b/static/freebsd/man9/sysctl_add_oid.9 new file mode 100644 index 00000000..c6c41582 --- /dev/null +++ b/static/freebsd/man9/sysctl_add_oid.9 @@ -0,0 +1,201 @@ +.\" +.\" Copyright (c) 2000, Andrzej Bialecki +.\" 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. 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 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 December 13, 2016 +.Dt SYSCTL_ADD_OID 9 +.Os +.Sh NAME +.Nm sysctl_add_oid , +.Nm sysctl_move_oid , +.Nm sysctl_remove_oid , +.Nm sysctl_remove_name +.Nd runtime sysctl tree manipulation +.Sh SYNOPSIS +.In sys/types.h +.In sys/sysctl.h +.Ft struct sysctl_oid * +.Fo sysctl_add_oid +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int kind" +.Fa "void *arg1" +.Fa "intmax_t arg2" +.Fa "int (*handler) (SYSCTL_HANDLER_ARGS)" +.Fa "const char *format" +.Fa "const char *descr" +.Fa "const char *label" +.Fc +.Ft int +.Fo sysctl_move_oid +.Fa "struct sysctl_oid *oidp" +.Fa "struct sysctl_oid_list *parent" +.Fc +.Ft int +.Fo sysctl_remove_oid +.Fa "struct sysctl_oid *oidp" +.Fa "int del" +.Fa "int recurse" +.Fc +.Ft int +.Fo sysctl_remove_name +.Fa "struct sysctl_oid *oidp" +.Fa "const char *name" +.Fa "int del" +.Fa "int recurse" +.Fc +.Sh DESCRIPTION +These functions provide the interface for creating and deleting sysctl +OIDs at runtime for example during the lifetime of a module. +The wrapper macros defined by +.Xr sysctl 9 +are recommended when creating new OIDs. +.Fn sysctl_add_oid +should not be called directly from the code. +.Pp +Dynamic OIDs of type +.Dv CTLTYPE_NODE +are reusable +so that several code sections can create and delete them, +but in reality they are allocated and freed +based on their reference count. +As a consequence, +it is possible for two or more code sections +to create partially overlapping trees that they both can use. +It is not possible to create overlapping leaves, +nor to create different child types with the same name and parent. +.Pp +The +.Fn sysctl_add_oid +function creates a raw OID of any type and connects it to its parent node, if any. +If the OID is successfully created, +the function returns a pointer to it else +it returns +.Dv NULL . +Many of the arguments for +.Fn sysctl_add_oid +are common to the wrapper macros defined by +.Xr sysctl 9 . +.Pp +The +.Fn sysctl_move_oid +function reparents an existing OID. +The OID is assigned a new number as if it had been created with +.Fa number +set to +.Dv OID_AUTO . +.Pp +The +.Fn sysctl_remove_oid +function removes a dynamically created OID from the tree and +optionally freeing its resources. +It takes the following arguments: +.Bl -tag -width recurse +.It Fa oidp +A pointer to the dynamic OID to be removed. +If the OID is not dynamic, or the pointer is +.Dv NULL , +the function returns +.Er EINVAL . +.It Fa del +If non-zero, +.Fn sysctl_remove_oid +will try to free the OID's resources +when the reference count of the OID becomes zero. +However, if +.Fa del +is set to 0, +the routine will only deregister the OID from the tree, +without freeing its resources. +This behaviour is useful when the caller expects to rollback +(possibly partially failed) +deletion of many OIDs later. +.It Fa recurse +If non-zero, attempt to remove the node and all its children. +If +.Pa recurse +is set to 0, +any attempt to remove a node that contains any children +will result in a +.Er ENOTEMPTY +error. +.Em WARNING : "use recursive deletion with extreme caution" ! +Normally it should not be needed if contexts are used. +Contexts take care of tracking inter-dependencies +between users of the tree. +However, in some extreme cases it might be necessary +to remove part of the subtree no matter how it was created, +in order to free some other resources. +Be aware, though, that this may result in a system +.Xr panic 9 +if other code sections continue to use removed subtrees. +.El +.Pp +The +.Fn sysctl_remove_name +function looks up the child node matching the +.Fa name +argument and then invokes the +.Fn sysctl_remove_oid +function on that node, passing along the +.Fa del +and +.Fa recurse +arguments. +If a node having the specified name does not exist an error code of +.Er ENOENT +is returned. +Else the error code from +.Fn sysctl_remove_oid +is returned. +.Pp +In most cases the programmer should use contexts, +as described in +.Xr sysctl_ctx_init 9 , +to keep track of created OIDs, +and to delete them later in orderly fashion. +.Sh SEE ALSO +.Xr sysctl 8 , +.Xr sysctl 9 , +.Xr sysctl_ctx_free 9 , +.Xr sysctl_ctx_init 9 +.Sh HISTORY +These functions first appeared in +.Fx 4.2 . +.Sh AUTHORS +.An Andrzej Bialecki Aq Mt abial@FreeBSD.org +.Sh BUGS +Sharing nodes between many code sections +causes interdependencies that sometimes may lock the resources. +For example, +if module A hooks up a subtree to an OID created by module B, +module B will be unable to delete that OID. +These issues are handled properly by sysctl contexts. +.Pp +Many operations on the tree involve traversing linked lists. +For this reason, OID creation and removal is relatively costly. diff --git a/static/freebsd/man9/sysctl_ctx_init.9 b/static/freebsd/man9/sysctl_ctx_init.9 new file mode 100644 index 00000000..92ba3e1a --- /dev/null +++ b/static/freebsd/man9/sysctl_ctx_init.9 @@ -0,0 +1,245 @@ +.\" +.\" Copyright (c) 2000, Andrzej Bialecki +.\" 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. 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 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 31, 2014 +.Dt SYSCTL_CTX_INIT 9 +.Os +.Sh NAME +.Nm sysctl_ctx_init , +.Nm sysctl_ctx_free , +.Nm sysctl_ctx_entry_add , +.Nm sysctl_ctx_entry_find , +.Nm sysctl_ctx_entry_del +.Nd "sysctl context for managing dynamically created sysctl OIDs" +.Sh SYNOPSIS +.In sys/types.h +.In sys/sysctl.h +.Ft int +.Fo sysctl_ctx_init +.Fa "struct sysctl_ctx_list *clist" +.Fc +.Ft int +.Fo sysctl_ctx_free +.Fa "struct sysctl_ctx_list *clist" +.Fc +.Ft struct sysctl_ctx_entry * +.Fo sysctl_ctx_entry_add +.Fa "struct sysctl_ctx_list *clist" +.Fa "struct sysctl_oid *oidp" +.Fc +.Ft struct sysctl_ctx_entry * +.Fo sysctl_ctx_entry_find +.Fa "struct sysctl_ctx_list *clist" +.Fa "struct sysctl_oid *oidp" +.Fc +.Ft int +.Fo sysctl_ctx_entry_del +.Fa "struct sysctl_ctx_list *clist" +.Fa "struct sysctl_oid *oidp" +.Fc +.Sh DESCRIPTION +These functions provide an interface +for managing dynamically created OIDs. +The sysctl context is responsible for keeping track of created OIDs, +as well as their proper removal when needed. +It adds a simple transactional aspect to OID removal operations; +i.e., if a removal operation fails part way, +it is possible to roll back the sysctl tree +to its previous state. +.Pp +The +.Fn sysctl_ctx_init +function initializes a sysctl context. +The +.Fa clist +argument must point to an already allocated variable. +A context +.Em must +be initialized before use. +Once it is initialized, +a pointer to the context can be passed as an argument to all the +.Fa SYSCTL_ADD_* +macros (see +.Xr sysctl_add_oid 9 ) , +and it will be updated with entries pointing to newly created OIDS. +.Pp +Internally, the context is represented as a +.Xr queue 3 +TAILQ linked list. +The list consists of +.Li struct sysctl_ctx_entry +entries: +.Bd -literal -offset indent +struct sysctl_ctx_entry { + struct sysctl_oid *entry; + TAILQ_ENTRY(sysctl_ctx_entry) link; +}; + +TAILQ_HEAD(sysctl_ctx_list, sysctl_ctx_entry); +.Ed +.Pp +Each context entry points to one dynamic OID that it manages. +Newly created OIDs are always inserted in the front of the list. +.Pp +The +.Fn sysctl_ctx_free +function removes the context and associated OIDs it manages. +If the function completes successfully, +all managed OIDs have been unregistered +(removed from the tree) +and freed, +together with all their allocated memory, +and the entries of the context have been freed as well. +.Pp +The removal operation is performed in two steps. +First, for each context entry, the function +.Xr sysctl_remove_oid 9 +is executed, with parameter +.Fa del +set to 0, which inhibits the freeing of resources. +If there are no errors during this step, +.Fn sysctl_ctx_free +proceeds to the next step. +If the first step fails, +all unregistered OIDs associated with the context are registered again. +.Pp +.Em Note : +in most cases, the programmer specifies +.Dv OID_AUTO +as the OID number when creating an OID. +However, during registration of the OID in the tree, +this number is changed to the first available number +greater than or equal to +.Dv CTL_AUTO_START . +If the first step of context deletion fails, +re-registration of the OID does not change the already assigned OID number +(which is different from OID_AUTO). +This ensures that re-registered entries +maintain their original positions in the tree. +.Pp +The second step actually performs the deletion of the dynamic OIDs. +.Xr sysctl_remove_oid 9 +iterates through the context list, +starting from beginning (i.e., the newest entries). +.Em Important : +this time, the function not only deletes the OIDs from the tree, +but also frees their memory (provided that oid_refcnt == 0), +as well as the memory of all context entries. +.Pp +The +.Fn sysctl_ctx_entry_add +function allows the addition of an existing dynamic OID to a context. +.Pp +The +.Fn sysctl_ctx_entry_del +function removes an entry from the context. +.Em Important : +in this case, only the corresponding +.Li struct sysctl_ctx_entry +is freed, but the +.Fa oidp +pointer remains intact. +Thereafter, the programmer is responsible for managing the resources +allocated to this OID. +.Pp +The +.Fn sysctl_ctx_entry_find +function searches for a given +.Fa oidp +within a context list, +either returning a pointer to the +.Fa struct sysctl_ctx_entry +found, +or +.Dv NULL . +.Sh EXAMPLES +The following is an example of how to create a new top-level category +and how to hook up another subtree to an existing static node. +This example uses contexts to keep track of the OIDs. +.Bd -literal +#include + ... +static struct sysctl_ctx_list clist; +static struct sysctl_oid *oidp; +static int a_int; +static const char *string = "dynamic sysctl"; + ... + +sysctl_ctx_init(&clist); +oidp = SYSCTL_ADD_ROOT_NODE(&clist, + OID_AUTO, "newtree", CTLFLAG_RW, 0, "new top level tree"); +oidp = SYSCTL_ADD_INT(&clist, SYSCTL_CHILDREN(oidp), + OID_AUTO, "newint", CTLFLAG_RW, &a_int, 0, "new int leaf"); + ... +oidp = SYSCTL_ADD_NODE(&clist, SYSCTL_STATIC_CHILDREN(_debug), + OID_AUTO, "newtree", CTLFLAG_RW, 0, "new tree under debug"); +oidp = SYSCTL_ADD_STRING(&clist, SYSCTL_CHILDREN(oidp), + OID_AUTO, "newstring", CTLFLAG_RD, string, 0, "new string leaf"); + ... +/* Now we can free up the OIDs */ +if (sysctl_ctx_free(&clist)) { + printf("can't free this context - other OIDs depend on it"); + return (ENOTEMPTY); +} else { + printf("Success!\\n"); + return (0); +} +.Ed +.Pp +This example creates the following subtrees: +.Bd -literal -offset indent +debug.newtree.newstring +newtree.newint +.Ed +.Pp +Note that both trees are removed, and their resources freed, +through one +.Fn sysctl_ctx_free +call, which starts by freeing the newest entries (leaves) +and then proceeds to free the older entries (in this case the nodes). +.Sh SEE ALSO +.Xr queue 3 , +.Xr sysctl 8 , +.Xr sysctl 9 , +.Xr sysctl_add_oid 9 , +.Xr sysctl_remove_oid 9 +.Sh HISTORY +These functions first appeared in +.Fx 4.2 . +.Sh AUTHORS +.An Andrzej Bialecki Aq Mt abial@FreeBSD.org +.Sh BUGS +The current removal algorithm is somewhat heavy. +In the worst case, +all OIDs need to be unregistered, registered again, +and then unregistered and deleted. +However, the algorithm does guarantee transactional properties +for removal operations. +.Pp +All operations on contexts involve linked list traversal. +For this reason, +creation and removal of entries is relatively costly. diff --git a/static/freebsd/man9/taskqueue.9 b/static/freebsd/man9/taskqueue.9 new file mode 100644 index 00000000..8ffa9a96 --- /dev/null +++ b/static/freebsd/man9/taskqueue.9 @@ -0,0 +1,542 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2000 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 April 25, 2022 +.Dt TASKQUEUE 9 +.Os +.Sh NAME +.Nm taskqueue +.Nd asynchronous task execution +.Sh SYNOPSIS +.In sys/param.h +.In sys/kernel.h +.In sys/malloc.h +.In sys/queue.h +.In sys/taskqueue.h +.Bd -literal +typedef void (*task_fn_t)(void *context, int pending); + +typedef void (*taskqueue_enqueue_fn)(void *context); + +struct task { + STAILQ_ENTRY(task) ta_link; /* link for queue */ + u_short ta_pending; /* count times queued */ + u_short ta_priority; /* priority of task in queue */ + task_fn_t ta_func; /* task handler */ + void *ta_context; /* argument for handler */ +}; + +enum taskqueue_callback_type { + TASKQUEUE_CALLBACK_TYPE_INIT, + TASKQUEUE_CALLBACK_TYPE_SHUTDOWN, +}; + +typedef void (*taskqueue_callback_fn)(void *context); + +struct timeout_task; +.Ed +.Ft struct taskqueue * +.Fn taskqueue_create "const char *name" "int mflags" "taskqueue_enqueue_fn enqueue" "void *context" +.Ft struct taskqueue * +.Fn taskqueue_create_fast "const char *name" "int mflags" "taskqueue_enqueue_fn enqueue" "void *context" +.Ft int +.Fn taskqueue_start_threads "struct taskqueue **tqp" "int count" "int pri" "const char *name" "..." +.Ft int +.Fo taskqueue_start_threads_cpuset +.Fa "struct taskqueue **tqp" "int count" "int pri" "cpuset_t *mask" +.Fa "const char *name" "..." +.Fc +.Ft int +.Fo taskqueue_start_threads_in_proc +.Fa "struct taskqueue **tqp" "int count" "int pri" "struct proc *proc" +.Fa "const char *name" "..." +.Fc +.Ft void +.Fn taskqueue_set_callback "struct taskqueue *queue" "enum taskqueue_callback_type cb_type" "taskqueue_callback_fn callback" "void *context" +.Ft void +.Fn taskqueue_free "struct taskqueue *queue" +.Ft int +.Fn taskqueue_enqueue "struct taskqueue *queue" "struct task *task" +.Ft int +.Fn taskqueue_enqueue_flags "struct taskqueue *queue" "struct task *task" "int flags" +.Ft int +.Fn taskqueue_enqueue_timeout "struct taskqueue *queue" "struct timeout_task *timeout_task" "int ticks" +.Ft int +.Fn taskqueue_enqueue_timeout_sbt "struct taskqueue *queue" "struct timeout_task *timeout_task" "sbintime_t sbt" "sbintime_t pr" "int flags" +.Ft int +.Fn taskqueue_cancel "struct taskqueue *queue" "struct task *task" "u_int *pendp" +.Ft int +.Fn taskqueue_cancel_timeout "struct taskqueue *queue" "struct timeout_task *timeout_task" "u_int *pendp" +.Ft void +.Fn taskqueue_drain "struct taskqueue *queue" "struct task *task" +.Ft void +.Fn taskqueue_drain_timeout "struct taskqueue *queue" "struct timeout_task *timeout_task" +.Ft void +.Fn taskqueue_drain_all "struct taskqueue *queue" +.Ft void +.Fn taskqueue_quiesce "struct taskqueue *queue" +.Ft void +.Fn taskqueue_block "struct taskqueue *queue" +.Ft void +.Fn taskqueue_unblock "struct taskqueue *queue" +.Ft int +.Fn taskqueue_member "struct taskqueue *queue" "struct thread *td" +.Ft void +.Fn taskqueue_run "struct taskqueue *queue" +.Fn TASK_INIT "struct task *task" "int priority" "task_fn_t func" "void *context" +.Fn TASK_INITIALIZER "int priority" "task_fn_t func" "void *context" +.Fn TASKQUEUE_DECLARE "name" +.Fn TASKQUEUE_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init" +.Fn TASKQUEUE_FAST_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init" +.Fn TASKQUEUE_DEFINE_THREAD "name" +.Fn TASKQUEUE_FAST_DEFINE_THREAD "name" +.Fn TIMEOUT_TASK_INIT "struct taskqueue *queue" "struct timeout_task *timeout_task" "int priority" "task_fn_t func" "void *context" +.Sh DESCRIPTION +These functions provide a simple interface for asynchronous execution +of code. +.Pp +The function +.Fn taskqueue_create +is used to create new queues. +The arguments to +.Fn taskqueue_create +include a name that should be unique, +a set of +.Xr malloc 9 +flags that specify whether the call to +.Fn malloc +is allowed to sleep, +a function that is called from +.Fn taskqueue_enqueue +when a task is added to the queue, +and a pointer to the memory location where the identity of the +thread that services the queue is recorded. +.\" XXX The rest of the sentence gets lots in relation to the first part. +The function called from +.Fn taskqueue_enqueue +must arrange for the queue to be processed +(for instance by scheduling a software interrupt or waking a kernel +thread). +The memory location where the thread identity is recorded is used +to signal the service thread(s) to terminate--when this value is set to +zero and the thread is signaled it will terminate. +If the queue is intended for use in fast interrupt handlers +.Fn taskqueue_create_fast +should be used in place of +.Fn taskqueue_create . +.Pp +The function +.Fn taskqueue_free +should be used to free the memory used by the queue. +Any tasks that are on the queue will be executed at this time after +which the thread servicing the queue will be signaled that it should exit. +.Pp +Once a taskqueue has been created, its threads should be started using +.Fn taskqueue_start_threads , +.Fn taskqueue_start_threads_cpuset +or +.Fn taskqueue_start_threads_in_proc . +.Fn taskqueue_start_threads_cpuset +takes a +.Va cpuset +argument which will cause the threads which are started for the taskqueue +to be restricted to run on the given CPUs. +.Fn taskqueue_start_threads_in_proc +takes a +.Va proc +argument which will cause the threads which are started for the taskqueue +to be assigned to the given kernel process. +Callbacks may optionally be registered using +.Fn taskqueue_set_callback . +Currently, callbacks may be registered for the following purposes: +.Bl -tag -width TASKQUEUE_CALLBACK_TYPE_SHUTDOWN +.It Dv TASKQUEUE_CALLBACK_TYPE_INIT +This callback is called by every thread in the taskqueue, before it executes +any tasks. +This callback must be set before the taskqueue's threads are started. +.It Dv TASKQUEUE_CALLBACK_TYPE_SHUTDOWN +This callback is called by every thread in the taskqueue, after it executes +its last task. +This callback will always be called before the taskqueue structure is +reclaimed. +.El +.Pp +To add a task to the list of tasks queued on a taskqueue, call +.Fn taskqueue_enqueue +with pointers to the queue and task. +If the task's +.Va ta_pending +field is non-zero, +then it is simply incremented to reflect the number of times the task +was enqueued, up to a cap of USHRT_MAX. +Otherwise, +the task is added to the list before the first task which has a lower +.Va ta_priority +value or at the end of the list if no tasks have a lower priority. +Enqueueing a task does not perform any memory allocation which makes +it suitable for calling from an interrupt handler. +This function will return +.Er EPIPE +if the queue is being freed. +.Pp +When a task is executed, +first it is removed from the queue, +the value of +.Va ta_pending +is recorded and then the field is zeroed. +The function +.Va ta_func +from the task structure is called with the value of the field +.Va ta_context +as its first argument +and the value of +.Va ta_pending +as its second argument. +After the function +.Va ta_func +returns, +.Xr wakeup 9 +is called on the task pointer passed to +.Fn taskqueue_enqueue . +.Pp +The +.Fn taskqueue_enqueue_flags +accepts an extra +.Va flags +parameter which specifies a set of optional flags to alter the behavior of +.Fn taskqueue_enqueue . +It contains one or more of the following flags: +.Bl -tag -width TASKQUEUE_FAIL_IF_CANCELING +.It Dv TASKQUEUE_FAIL_IF_PENDING +.Fn taskqueue_enqueue_flags +fails if the task is already scheduled for execution. +.Er EEXIST +is returned and the +.Va ta_pending +counter value remains unchanged. +.It Dv TASKQUEUE_FAIL_IF_CANCELING +.Fn taskqueue_enqueue_flags +fails if the task is in the canceling state and +.Er ECANCELED +is returned. +.El +.Pp +The +.Fn taskqueue_enqueue_timeout +function is used to schedule the enqueue after the specified number of +.Va ticks . +The +.Fn taskqueue_enqueue_timeout_sbt +function provides finer control over the scheduling based on +.Va sbt , +.Va pr , +and +.Va flags , +as detailed in +.Xr callout 9 . +If the +.Va ticks +argument is negative, the already scheduled enqueueing is not re-scheduled. +Otherwise, the task is scheduled for enqueueing in the future, +after the absolute value of +.Va ticks +is passed. +This function returns -1 if the task is being drained. +Otherwise, the number of pending calls is returned. +.Pp +The +.Fn taskqueue_cancel +function is used to cancel a task. +The +.Va ta_pending +count is cleared, and the old value returned in the reference +parameter +.Fa pendp , +if it is +.Pf non- Dv NULL . +If the task is currently running, +.Dv EBUSY +is returned, otherwise 0. +To implement a blocking +.Fn taskqueue_cancel +that waits for a running task to finish, it could look like: +.Bd -literal -offset indent +while (taskqueue_cancel(tq, task, NULL) != 0) + taskqueue_drain(tq, task); +.Ed +.Pp +Note that, as with +.Fn taskqueue_drain , +the caller is responsible for ensuring that the task is not re-enqueued +after being canceled. +.Pp +Similarly, the +.Fn taskqueue_cancel_timeout +function is used to cancel the scheduled task execution. +.Pp +The +.Fn taskqueue_drain +function is used to wait for the task to finish, and +the +.Fn taskqueue_drain_timeout +function is used to wait for the scheduled task to finish. +There is no guarantee that the task will not be +enqueued after call to +.Fn taskqueue_drain . +If the caller wants to put the task into a known state, +then before calling +.Fn taskqueue_drain +the caller should use out-of-band means to ensure that the task +would not be enqueued. +For example, if the task is enqueued by an interrupt filter, then +the interrupt could be disabled. +.Pp +The +.Fn taskqueue_drain_all +function is used to wait for all pending and running tasks that +are enqueued on the taskqueue to finish. +Tasks posted to the taskqueue after +.Fn taskqueue_drain_all +begins processing, +including pending enqueues scheduled by a previous call to +.Fn taskqueue_enqueue_timeout , +do not extend the wait time of +.Fn taskqueue_drain_all +and may complete after +.Fn taskqueue_drain_all +returns. +The +.Fn taskqueue_quiesce +function is used to wait for the queue to become empty and for all +running tasks to finish. +To avoid blocking indefinitely, the caller must ensure by some mechanism +that tasks will eventually stop being posted to the queue. +.Pp +The +.Fn taskqueue_block +function blocks the taskqueue. +It prevents any enqueued but not running tasks from being executed. +Future calls to +.Fn taskqueue_enqueue +will enqueue tasks, but the tasks will not be run until +.Fn taskqueue_unblock +is called. +Please note that +.Fn taskqueue_block +does not wait for any currently running tasks to finish. +Thus, the +.Fn taskqueue_block +does not provide a guarantee that +.Fn taskqueue_run +is not running after +.Fn taskqueue_block +returns, but it does provide a guarantee that +.Fn taskqueue_run +will not be called again +until +.Fn taskqueue_unblock +is called. +If the caller requires a guarantee that +.Fn taskqueue_run +is not running, then this must be arranged by the caller. +Note that if +.Fn taskqueue_drain +is called on a task that is enqueued on a taskqueue that is blocked by +.Fn taskqueue_block , +then +.Fn taskqueue_drain +can not return until the taskqueue is unblocked. +This can result in a deadlock if the thread blocked in +.Fn taskqueue_drain +is the thread that is supposed to call +.Fn taskqueue_unblock . +Thus, use of +.Fn taskqueue_drain +after +.Fn taskqueue_block +is discouraged, because the state of the task can not be known in advance. +The same caveat applies to +.Fn taskqueue_drain_all . +.Pp +The +.Fn taskqueue_unblock +function unblocks the previously blocked taskqueue. +All enqueued tasks can be run after this call. +.Pp +The +.Fn taskqueue_member +function returns +.No 1 +if the given thread +.Fa td +is part of the given taskqueue +.Fa queue +and +.No 0 +otherwise. +.Pp +The +.Fn taskqueue_run +function will run all pending tasks in the specified +.Fa queue . +Normally this function is only used internally. +.Pp +A convenience macro, +.Fn TASK_INIT "task" "priority" "func" "context" +is provided to initialise a +.Va task +structure. +The +.Fn TASK_INITIALIZER +macro generates an initializer for a task structure. +A macro +.Fn TIMEOUT_TASK_INIT "queue" "timeout_task" "priority" "func" "context" +initializes the +.Va timeout_task +structure. +The values of +.Va priority , +.Va func , +and +.Va context +are simply copied into the task structure fields and the +.Va ta_pending +field is cleared. +.Pp +Five macros +.Fn TASKQUEUE_DECLARE "name" , +.Fn TASKQUEUE_DEFINE "name" "enqueue" "context" "init" , +.Fn TASKQUEUE_FAST_DEFINE "name" "enqueue" "context" "init" , +and +.Fn TASKQUEUE_DEFINE_THREAD "name" +.Fn TASKQUEUE_FAST_DEFINE_THREAD "name" +are used to declare a reference to a global queue, to define the +implementation of the queue, and declare a queue that uses its own thread. +The +.Fn TASKQUEUE_DEFINE +macro arranges to call +.Fn taskqueue_create +with the values of its +.Va name , +.Va enqueue +and +.Va context +arguments during system initialisation. +After calling +.Fn taskqueue_create , +the +.Va init +argument to the macro is executed as a C statement, +allowing any further initialisation to be performed +(such as registering an interrupt handler, etc.). +.Pp +The +.Fn TASKQUEUE_DEFINE_THREAD +macro defines a new taskqueue with its own kernel thread to serve tasks. +The variable +.Vt struct taskqueue *taskqueue_name +is used to enqueue tasks onto the queue. +.Pp +.Fn TASKQUEUE_FAST_DEFINE +and +.Fn TASKQUEUE_FAST_DEFINE_THREAD +act just like +.Fn TASKQUEUE_DEFINE +and +.Fn TASKQUEUE_DEFINE_THREAD +respectively but taskqueue is created with +.Fn taskqueue_create_fast . +.Ss Predefined Task Queues +The system provides four global taskqueues, +.Va taskqueue_fast , +.Va taskqueue_swi , +.Va taskqueue_swi_giant , +and +.Va taskqueue_thread . +The +.Va taskqueue_fast +queue is for swi handlers dispatched from fast interrupt handlers, +where sleep mutexes cannot be used. +The swi taskqueues are run via a software interrupt mechanism. +The +.Va taskqueue_swi +queue runs without the protection of the +.Va Giant +kernel lock, and the +.Va taskqueue_swi_giant +queue runs with the protection of the +.Va Giant +kernel lock. +The thread taskqueue +.Va taskqueue_thread +runs in a kernel thread context, and tasks run from this thread do +not run under the +.Va Giant +kernel lock. +If the caller wants to run under +.Va Giant , +he should explicitly acquire and release +.Va Giant +in his taskqueue handler routine. +.Pp +To use these queues, +call +.Fn taskqueue_enqueue +with the value of the global taskqueue variable for the queue you wish to +use. +.Pp +The software interrupt queues can be used, +for instance, for implementing interrupt handlers which must perform a +significant amount of processing in the handler. +The hardware interrupt handler would perform minimal processing of the +interrupt and then enqueue a task to finish the work. +This reduces to a minimum +the amount of time spent with interrupts disabled. +.Pp +The thread queue can be used, for instance, by interrupt level routines +that need to call kernel functions that do things that can only be done +from a thread context. +(e.g., call malloc with the M_WAITOK flag.) +.Pp +Note that tasks queued on shared taskqueues such as +.Va taskqueue_swi +may be delayed an indeterminate amount of time before execution. +If queueing delays cannot be tolerated then a private taskqueue should +be created with a dedicated processing thread. +.Sh SEE ALSO +.Xr callout 9 , +.Xr intr_event 9 , +.Xr kthread 9 , +.Xr swi 9 +.Sh HISTORY +This interface first appeared in +.Fx 5.0 . +There is a similar facility called work_queue in the Linux kernel. +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/tcp_functions.9 b/static/freebsd/man9/tcp_functions.9 new file mode 100644 index 00000000..8ba7f21c --- /dev/null +++ b/static/freebsd/man9/tcp_functions.9 @@ -0,0 +1,392 @@ +.\" +.\" Copyright (c) 2016 Jonathan Looney +.\" 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 13, 2024 +.Dt TCP_FUNCTIONS 9 +.Os +.Sh NAME +.Nm tcp_functions +.Nd Alternate TCP Stack Framework +.Sh SYNOPSIS +.In netinet/tcp.h +.In netinet/tcp_var.h +.Ft int +.Fn register_tcp_functions "struct tcp_function_block *blk" "int wait" +.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 +.Fn deregister_tcp_functions "struct tcp_function_block *blk" +.Sh DESCRIPTION +The +.Nm +framework allows a kernel developer to implement alternate TCP stacks. +The alternate stacks can be compiled in the kernel or can be implemented in +loadable kernel modules. +This functionality is intended to encourage experimentation with the TCP stack +and to allow alternate behaviors to be deployed for different TCP connections +on a single system. +.Pp +A system administrator can set a system default stack. +By default, all TCP connections will use the system default stack. +Additionally, users can specify a particular stack to use on a per-connection +basis. +(See +.Xr tcp 4 +for details on setting the system default stack, or selecting a specific stack +for a given connection.) +.Pp +This man page treats "TCP stacks" as synonymous with "function blocks". +This is intentional. +A "TCP stack" is a collection of functions that implement a set of behavior. +Therefore, an alternate "function block" defines an alternate "TCP stack". +.Pp +The +.Fn register_tcp_functions , +.Fn register_tcp_functions_as_name , +and +.Fn register_tcp_functions_as_names +functions request that the system add a specified function block +and register it for use with a given name. +Modules may register the same function block multiple times with different +names. +However, names must be globally unique among all registered function blocks. +Also, modules may not ever modify the contents of the function block (including +the name) after it has been registered, unless the module first successfully +de-registers the function block. +.Pp +The +.Fn register_tcp_functions +function requests that the system register the function block with the name +defined in the function block's +.Va tfb_tcp_block_name +field. +Note that this is the only one of the three registration functions that +automatically registers the function block using the name defined in the +function block's +.Va tfb_tcp_block_name +field. +If a module uses one of the other registration functions, it may request that +the system register the function block using the name defined in the +function block's +.Va tfb_tcp_block_name +field by explicitly providing that name. +.Pp +The +.Fn register_tcp_functions_as_name +function requests that the system register the function block with the name +provided in the +.Fa name +argument. +.Pp +The +.Fn register_tcp_functions_as_names +function requests that the system register the function block with all the +names provided in the +.Fa names +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 +.Fa num_names +argument is updated with the index number of the entry in the +.Fa names +array which the system was processing when it encountered the error. +.Pp +The +.Fn deregister_tcp_functions +function requests that the system remove a specified function block from the +system. +If this call succeeds, it will completely deregister the function block, +regardless of the number of names used to register the function block. +If the call fails because sockets are still using the specified function block, +the system will mark the function block as being in the process of being +removed. +This will prevent additional sockets from using the specified function block. +However, it will not impact sockets that are already using the function block. +.Pp +.Nm +modules must call one or more of the registration functions during +initialization and successfully call the +.Fn deregister_tcp_functions +function prior to allowing the module to be unloaded. +.Pp +The +.Fa blk +argument is a pointer to a +.Vt "struct tcp_function_block" , +which is explained below (see +.Sx Function Block Structure ) . +The +.Fa wait +argument is used as the +.Fa flags +argument to +.Xr malloc 9 , +and must be set to one of the valid values defined in that man page. +.Ss Function Block Structure +The +.Fa blk argument is a pointer to a +.Vt "struct tcp_function_block" , +which has the following members: +.Bd -literal -offset indent +struct tcp_function_block { + char tfb_tcp_block_name[TCP_FUNCTION_NAME_LEN_MAX]; + int (*tfb_tcp_output)(struct tcpcb *); + void (*tfb_tcp_do_segment)(struct mbuf *, struct tcphdr *, + struct socket *, struct tcpcb *, + int, int, uint8_t, + int); + int (*tfb_tcp_ctloutput)(struct socket *so, + struct sockopt *sopt, + struct inpcb *inp, struct tcpcb *tp); + /* Optional memory allocation/free routine */ + void (*tfb_tcp_fb_init)(struct tcpcb *); + void (*tfb_tcp_fb_fini)(struct tcpcb *, int); + /* Optional timers, must define all if you define one */ + int (*tfb_tcp_timer_stop_all)(struct tcpcb *); + void (*tfb_tcp_timer_activate)(struct tcpcb *, + uint32_t, u_int); + int (*tfb_tcp_timer_active)(struct tcpcb *, uint32_t); + void (*tfb_tcp_timer_stop)(struct tcpcb *, uint32_t); + /* Optional function */ + void (*tfb_tcp_rexmit_tmr)(struct tcpcb *); + /* Mandatory function */ + int (*tfb_tcp_handoff_ok)(struct tcpcb *); + /* System use */ + volatile uint32_t tfb_refcnt; + uint32_t tfb_flags; +}; +.Ed +.Pp +The +.Va tfb_tcp_block_name +field identifies the unique name of the TCP stack, and should be no longer than +TCP_FUNCTION_NAME_LEN_MAX-1 characters in length. +.Pp +The +.Va tfb_tcp_output , +.Va tfb_tcp_do_segment , +and +.Va tfb_tcp_ctloutput +fields are pointers to functions that perform the equivalent actions +as the default +.Fn tcp_output , +.Fn tcp_do_segment , +and +.Fn tcp_default_ctloutput +functions, respectively. +Each of these function pointers must be non-NULL. +.Pp +If a TCP stack needs to initialize data when a socket first selects the TCP +stack (or, when the socket is first opened), it should set a non-NULL +pointer in the +.Va tfb_tcp_fb_init +field. +Likewise, if a TCP stack needs to cleanup data when a socket stops using the +TCP stack (or, when the socket is closed), it should set a non-NULL pointer +in the +.Va tfb_tcp_fb_fini +field. +.Pp +If the +.Va tfb_tcp_fb_fini +argument is non-NULL, the function to which it points is called when the +kernel is destroying the TCP control block or when the socket is transitioning +to use a different TCP stack. +The function is called with arguments of the TCP control block and an integer +flag. +The flag will be zero if the socket is transitioning to use another TCP stack +or one if the TCP control block is being destroyed. +.Pp +If the TCP stack implements additional timers, the TCP stack should set a +non-NULL pointer in the +.Va tfb_tcp_timer_stop_all , +.Va tfb_tcp_timer_activate , +.Va tfb_tcp_timer_active , +and +.Va tfb_tcp_timer_stop +fields. +These fields should all be +.Dv NULL +or should all contain pointers to functions. +The +.Va tfb_tcp_timer_activate , +.Va tfb_tcp_timer_active , +and +.Va tfb_tcp_timer_stop +functions will be called when the +.Fn tcp_timer_activate , +.Fn tcp_timer_active , +and +.Fn tcp_timer_stop +functions, respectively, are called with a timer type other than the standard +types. +The functions defined by the TCP stack have the same semantics (both for +arguments and return values) as the normal timer functions they supplement. +.Pp +Additionally, a stack may define its own actions to take when the retransmit +timer fires by setting a non-NULL function pointer in the +.Va tfb_tcp_rexmit_tmr +field. +This function is called very early in the process of handling a retransmit +timer. +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 at any time. +Therefore, the function pointer +.Va tfb_tcp_handoff_ok +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. 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 +and +.Va tfb_flags +fields are used by the kernel's TCP code and will be initialized when the +TCP stack is registered. +.Ss Requirements for Alternate TCP Stacks +If the TCP stack needs to store data beyond what is stored in the default +TCP control block, the TCP stack can initialize its own per-connection storage. +The +.Va t_fb_ptr +field in the +.Vt "struct tcpcb" +control block structure has been reserved to hold a pointer to this +per-connection storage. +If the TCP stack uses this alternate storage, it should understand that the +value of the +.Va t_fb_ptr +pointer may not be initialized to +.Dv NULL . +Therefore, it should use a +.Va tfb_tcp_fb_init +function to initialize this field. +Additionally, it should use a +.Va tfb_tcp_fb_fini +function to deallocate storage when the socket is closed. +.Pp +It is understood that alternate TCP stacks may keep different sets of data. +However, in order to ensure that data is available to both the user and the +rest of the system in a standardized format, alternate TCP stacks must +update all fields in the TCP control block to the greatest extent practical. +.Sh RETURN VALUES +The +.Fn register_tcp_functions , +.Fn register_tcp_functions_as_name , +.Fn register_tcp_functions_as_names , +and +.Fn deregister_tcp_functions +functions return zero on success and non-zero on failure. +In particular, the +.Fn deregister_tcp_functions +will return +.Er EBUSY +until no more connections are using the specified TCP stack. +A module calling +.Fn deregister_tcp_functions +must be prepared to wait until all connections have stopped using the +specified TCP stack. +.Sh ERRORS +The +.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 +.Fa blk +argument are set incorrectly. +.It Bq Er ENOMEM +The function could not allocate memory for its internal data. +.It Bq Er EALREADY +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 +function will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +The +.Fa blk +argument references the kernel's compiled-in default function block. +.It Bq Er EBUSY +The function block is still in use by one or more sockets, or is defined as +the current default function block. +.It Bq Er ENOENT +The +.Fa blk +argument references a function block that is not currently registered. +.El +.Sh SEE ALSO +.Xr connect 2 , +.Xr listen 2 , +.Xr tcp 4 , +.Xr malloc 9 +.Sh HISTORY +This framework first appeared in +.Fx 11.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +framework was written by +.An Randall Stewart Aq Mt rrs@FreeBSD.org . +.Pp +This manual page was written by +.An Jonathan Looney Aq Mt jtl@FreeBSD.org . diff --git a/static/freebsd/man9/thread_exit.9 b/static/freebsd/man9/thread_exit.9 new file mode 100644 index 00000000..a5822d6e --- /dev/null +++ b/static/freebsd/man9/thread_exit.9 @@ -0,0 +1,61 @@ +.\" +.\" Copyright (c) 2002 Julian Elischer +.\" 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 5, 2002 +.Dt THREAD_EXIT 9 +.Os +.Sh NAME +.Nm thread_exit +.Nd abandon current thread context +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.Ft void +.Fn thread_exit "void" +.Sh DESCRIPTION +The +.Fn thread_exit +function implements the machine independent prelude to a thread +shutdown. +It will not return, and will result in a call to +.Xr mi_switch 9 +to schedule some other thread. +.Pp +.Fn thread_exit +arranges to free all the resources of the thread, specifically the kernel +stack. +.Pp +To protect the +.Xr runqueue 9 , +.Fn thread_exit +must be called with the +.Va sched_lock +mutex held. +.Sh SEE ALSO +.Xr mi_switch 9 , +.Xr mutex 9 , +.Xr runqueue 9 , +.Xr sleep 9 diff --git a/static/freebsd/man9/time.9 b/static/freebsd/man9/time.9 new file mode 100644 index 00000000..8a3f9eec --- /dev/null +++ b/static/freebsd/man9/time.9 @@ -0,0 +1,125 @@ +.\" $NetBSD: time.9,v 1.1 1995/11/25 21:24:53 perry Exp $ +.\" +.\" Copyright (c) 1994 Christopher G. Demetriou +.\" 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 Christopher G. Demetriou +.\" for the NetBSD Project. +.\" 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 May 4, 2021 +.Dt TIME 9 +.Os +.Sh NAME +.Nm boottime , +.Nm time_second , +.Nm time_uptime +.Nd system time variables +.Sh SYNOPSIS +.In sys/time.h +.Pp +.Vt extern struct timeval boottime ; +.Vt extern time_t time_second ; +.Vt extern time_t time_uptime ; +.Sh DESCRIPTION +The +.Va boottime +variable holds the estimated system boot time. +This time is initially set when the system boots, either from the RTC, or from a +time estimated from the system's root filesystem. +When the current system time is set, stepped by +.Xr ntpd 8 , +or a new time is read from the RTC as the system resumes, +.Va boottime +is recomputed as new_time - uptime. +The +.Xr sysctl 8 +.Va kern.boottime +returns this value. +.Pp +The +.Va time_second +variable is the system's +.Dq wall time +clock to the second. +.Pp +The +.Va time_uptime +variable is the number of seconds since boot. +.Pp +The +.Xr bintime 9 , +.Xr getbintime 9 , +.Xr microtime 9 , +.Xr getmicrotime 9 , +.Xr nanotime 9 , +and +.Xr getnanotime 9 +functions can be used to get the current time more accurately and in an +atomic manner. +Similarly, the +.Xr binuptime 9 , +.Xr getbinuptime 9 , +.Xr microuptime 9 , +.Xr getmicrouptime 9 , +.Xr nanouptime 9 , +and +.Xr getnanouptime 9 +functions can be used to get the time elapse since boot more accurately +and in an atomic manner. +The +.Va boottime +variable may be read and written without special precautions. +It is adjusted when the phase of the system time changes. +.Sh SEE ALSO +.Xr clock_settime 2 , +.Xr ntp_adjtime 2 , +.Xr settimeofday 2 , +.Xr bintime 9 , +.Xr binuptime 9 , +.Xr getbintime 9 , +.Xr getbinuptime 9 , +.Xr getmicrotime 9 , +.Xr getmicrouptime 9 , +.Xr getnanotime 9 , +.Xr getnanouptime 9 , +.Xr microtime 9 , +.Xr microuptime 9 , +.Xr nanotime 9 , +.Xr nanouptime 9 +.Rs +.%A "Poul-Henning Kamp" +.%T "Timecounters: Efficient and precise timekeeping in SMP kernels" +.%J "Proceedings of EuroBSDCon 2002, Amsterdam" +.%O /usr/share/doc/papers/timecounter.ascii.gz +.Re +.Rs +.%A "Marshall Kirk McKusick" +.%A "George V. Neville-Neil" +.%B "The Design and Implementation of the FreeBSD Operating System" +.%D "July 2004" +.%I "Addison-Wesley" +.%P "57-61,65-66" +.Re diff --git a/static/freebsd/man9/tvtohz.9 b/static/freebsd/man9/tvtohz.9 new file mode 100644 index 00000000..947ab5b0 --- /dev/null +++ b/static/freebsd/man9/tvtohz.9 @@ -0,0 +1,56 @@ +.\" Copyright (c) 2000 Kelly Yancey +.\" 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 January 3, 2000 +.Dt TVTOHZ 9 +.Os +.Sh NAME +.Nm tvtohz +.Nd convert time interval to tick count +.Sh SYNOPSIS +.In sys/time.h +.Ft int +.Fn tvtohz "struct timeval *tv" +.Sh DESCRIPTION +The +.Fn tvtohz +function accepts a single argument +.Fa tv +which specifies the time interval over which to calculate the number +of system ticks that would elapse. +.Sh RETURN VALUES +Returns the integral number of system ticks expected to elapse in the given +interval, including the current tick. +.Sh SEE ALSO +.Xr callout 9 , +.Xr microtime 9 , +.Xr microuptime 9 +.Sh HISTORY +The +.Nm +function first appeared in +.Fx 3.0 +.Sh AUTHORS +This manual page was written by +.An Kelly Yancey Aq Mt kbyanc@posi.net . diff --git a/static/freebsd/man9/ucred.9 b/static/freebsd/man9/ucred.9 new file mode 100644 index 00000000..453df386 --- /dev/null +++ b/static/freebsd/man9/ucred.9 @@ -0,0 +1,224 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 August 29, 2025 +.Dt UCRED 9 +.Os +.Sh NAME +.Nm ucred , +.Nm crget , +.Nm crhold , +.Nm crfree , +.Nm crcopy , +.Nm crdup , +.Nm cru2x +.Nd "functions related to user credentials" +.Sh SYNOPSIS +.In sys/param.h +.In sys/ucred.h +.Ft "struct ucred *" +.Fn crget void +.Ft "struct ucred *" +.Fn crhold "struct ucred *cr" +.Ft void +.Fn crfree "struct ucred *cr" +.Ft void +.Fn crcopy "struct ucred *dest" "struct ucred *src" +.Ft "struct ucred *" +.Fn crcopysafe "struct proc *p" "struct ucred *cr" +.Ft "struct ucred *" +.Fn crdup "struct ucred *cr" +.Ft void +.Fn crsetgroups "struct ucred *cr" "int ngrp" "gid_t *groups" +.Ft void +.Fn crsetgroups_and_egid "struct ucred *cr" "int ngrp" "gid_t *groups" \ + "gid_t default_egid" +.Ft void +.Fn cru2x "struct ucred *cr" "struct xucred *xcr" +.Sh DESCRIPTION +The +.Nm +family of functions is used to manage user credential structures +.Pq Vt "struct ucred" +within the kernel. +.Pp +The +.Fn crget +function allocates memory +for a new structure, sets its reference count to 1, and +initializes its lock. +.Pp +The +.Fn crhold +function increases the reference count on the credential. +.Pp +The +.Fn crfree +function decreases the reference count on the credential. +If the count drops to 0, the storage for the structure is freed. +.Pp +The +.Fn crcopy +function copies the contents of the source (template) +credential into the destination template. +The +.Vt uidinfo +structure within the destination is referenced +by calling +.Xr uihold 9 . +.Pp +The +.Fn crcopysafe +function copies the current credential associated with the process +.Fa p +into the newly allocated credential +.Fa cr . +The process lock on +.Fa p +must be held and will be dropped and reacquired as needed to allocate +group storage space in +.Fa cr . +.Pp +The +.Fn crdup +function allocates memory for a new structure and copies the +contents of +.Fa cr +into it. +The actual copying is performed by +.Fn crcopy . +.Pp +The +.Fn crsetgroups +function sets the +.Va cr_groups +and +.Va cr_ngroups +variables representing the supplementary groups, allocating space as needed. +It also truncates the group list to the current maximum number of groups. +The +.Fn crsetgroups_and_egid +function is similar, but interprets separately the first group of +.Va groups +as the effective GID to set, only setting the subsequent groups as supplementary +ones. +It will use +.Va default_egid +as the new effective GID if +.Va groups +is empty. +No other mechanism should be used to modify the +.Va cr_groups +array. +.Pp +The +.Fn cru2x +function converts a +.Vt ucred +structure to an +.Vt xucred +structure. +That is, +it copies data from +.Fa cr +to +.Fa xcr ; +it ignores fields in the former that are not present in the latter +(e.g., +.Va cr_uidinfo ) , +and appropriately sets fields in the latter that are not present in +the former +(e.g., +.Va cr_version ) . +.Sh RETURN VALUES +.Fn crget , +.Fn crhold , +.Fn crdup , +and +.Fn crcopysafe +all return a pointer to a +.Vt ucred +structure. +.Sh USAGE NOTES +As of +.Fx 5.0 , +the +.Vt ucred +structure contains extensible fields. +This means that the correct protocol must always be followed to create +a fresh and writable credential structure: new credentials must always +be derived from existing credentials using +.Fn crget , +.Fn crcopy , +and +.Fn crcopysafe . +.Pp +In the common case, credentials required for access control decisions are +used in a read-only manner. +In these circumstances, the thread credential +.Va td_ucred +should be used, as it requires no locking to access safely, and remains stable +for the duration of the call even in the face of a multi-threaded +application changing the process credentials from another thread. +.Pp +During a process credential update, the process lock must be held across +check and update, to prevent race conditions. +The process credential, +.Va td->td_proc->p_ucred , +must be used both for check and update. +If a process credential is updated during a system call and checks against +the thread credential are to be made later during the same system call, +the thread credential must also be refreshed from the process credential +so as to prevent use of a stale value. +To avoid this scenario, it is recommended that system calls updating the +process credential be designed to avoid other authorization functions. +.Pp +If temporarily elevated privileges are required for a thread, the thread +credential can be replaced for the duration of an activity, or for +the remainder of the system call. +However, as a thread credential is often shared, appropriate care should be +taken to make sure modifications are made to a writable credential +through the use of +.Fn crget +and +.Fn crcopy . +.Pp +Caution should be exercised when checking authorization for a thread or +process perform an operation on another thread or process. +As a result of temporary elevation, the target thread credential should +.Em never +be used as the target credential in an access control decision: the process +credential associated with the thread, +.Va td->td_proc->p_ucred , +should be used instead. +For example, +.Xr p_candebug 9 +accepts a target process, not a target thread, for access control purposes. +.Sh SEE ALSO +.Xr uihold 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/uidinfo.9 b/static/freebsd/man9/uidinfo.9 new file mode 100644 index 00000000..99d96ee9 --- /dev/null +++ b/static/freebsd/man9/uidinfo.9 @@ -0,0 +1,107 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 10, 2001 +.Dt UIDINFO 9 +.Os +.Sh NAME +.Nm uidinfo , +.Nm uihashinit , +.Nm uifind , +.Nm uihold , +.Nm uifree +.Nd "functions for managing UID information" +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.In sys/resourcevar.h +.Ft void +.Fn uihashinit void +.Ft "struct uidinfo *" +.Fn uifind "uid_t uid" +.Ft void +.Fn uihold "struct uidinfo *uip" +.Ft void +.Fn uifree "struct uidinfo *uip" +.Sh DESCRIPTION +The +.Nm +family of functions +is used to manage +.Vt uidinfo +structures. +Each +.Vt uidinfo +structure maintains per uid resource consumption counts, including the +process count and socket buffer space usage. +.Pp +The +.Fn uihashinit +function initializes the +.Vt uidinfo +hash table and its mutex. +This function should only be called during system initialization. +.Pp +The +.Fn uifind +function looks up and returns the +.Vt uidinfo +structure for +.Fa uid . +If no +.Vt uidinfo +structure exists for +.Fa uid , +a new structure will be allocated and initialized. +The +.Nm +hash mutex is acquired and released. +.Pp +The +.Fn uihold +function increases the reference count on +.Fa uip . +.Fa uip Ns 's +lock is acquired and released. +.Pp +The +.Fn uifree +function decreases the reference count on +.Fa uip , +and if the count reaches 0 +.Fa uip +is freed. +.Fa uip Ns 's +lock is acquired and release and the uidinfo hash mutex may be +acquired and released. +.Sh RETURN VALUES +.Fn uifind +returns a pointer to an initialized +.Vt uidinfo +structure, and should not fail. +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/uio.9 b/static/freebsd/man9/uio.9 new file mode 100644 index 00000000..b143eb6e --- /dev/null +++ b/static/freebsd/man9/uio.9 @@ -0,0 +1,239 @@ +.\" +.\" Copyright (c) 1997 Joerg Wunsch +.\" +.\" 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 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 October 22, 2025 +.Dt UIO 9 +.Os +.Sh NAME +.Nm uio , +.Nm uiomove , +.Nm uiomove_frombuf , +.Nm uiomove_nofault +.Nd device driver I/O routines +.Sh SYNOPSIS +.In sys/types.h +.In sys/uio.h +.Bd -literal +struct uio { + struct iovec *uio_iov; /* scatter/gather list */ + int uio_iovcnt; /* length of scatter/gather list */ + off_t uio_offset; /* offset in target object */ + ssize_t uio_resid; /* remaining bytes to copy */ + enum uio_seg uio_segflg; /* address space */ + enum uio_rw uio_rw; /* operation */ + struct thread *uio_td; /* owner */ +}; +.Ed +.Ft int +.Fn uiomove "void *buf" "int howmuch" "struct uio *uiop" +.Ft int +.Fn uiomove_frombuf "void *buf" "int howmuch" "struct uio *uiop" +.Ft int +.Fn uiomove_nofault "void *buf" "int howmuch" "struct uio *uiop" +.Sh DESCRIPTION +The functions +.Fn uiomove , +.Fn uiomove_frombuf , +and +.Fn uiomove_nofault +are used to transfer data between buffers and I/O vectors that might +possibly cross the user/kernel space boundary. +.Pp +As a result of any +.Xr read 2 , +.Xr write 2 , +.Xr readv 2 , +or +.Xr writev 2 +system call that is being passed to a character-device driver, the +appropriate driver +.Va d_read +or +.Va d_write +entry will be called with a pointer to a +.Vt "struct uio" +being passed. +The transfer request is encoded in this structure. +The driver itself should use +.Fn uiomove +or +.Fn uiomove_nofault +to get at the data in this structure. +.Pp +The fields in the +.Vt uio +structure are: +.Bl -tag -width ".Va uio_iovcnt" +.It Va uio_iov +The array of I/O vectors to be processed. +In the case of scatter/gather +I/O, this will be more than one vector. +.It Va uio_iovcnt +The number of I/O vectors present. +.It Va uio_offset +The offset into the device. +.It Va uio_resid +The remaining number of bytes to process, updated after transfer. +.It Va uio_segflg +One of the following flags: +.Bl -tag -width ".Dv UIO_USERSPACE" +.It Dv UIO_USERSPACE +The I/O vector points into a process's address space. +.It Dv UIO_SYSSPACE +The I/O vector points into the kernel address space. +.It Dv UIO_NOCOPY +Do not copy, already in object. +.El +.It Va uio_rw +The direction of the desired transfer. +The supported flags are: +.Bl -tag -width "UIO_WRITE" +.It Dv UIO_READ +Transfer data from the buffers into the I/O vectors. +.It Dv UIO_WRITE +Transfer data from the I/O vectors into the buffers. +.El +.It Va uio_td +The pointer to a +.Vt "struct thread" +for the associated thread; used if +.Va uio_segflg +indicates that the transfer is to be made from/to a process's address +space. +.El +.Pp +The function +.Fn uiomove_nofault +requires that the buffer and I/O vectors be accessible without +incurring a page fault. +The source and destination addresses must be physically mapped for +read and write access, respectively, and neither the source nor +destination addresses may be pageable. +Thus, the function +.Fn uiomove_nofault +can be called from contexts where acquiring virtual memory system +locks or sleeping are prohibited. +.Pp +The +.Fn uiomove_frombuf +function is a convenience wrapper around +.Fn uiomove +for drivers that serve data which is wholly contained within an +existing buffer in memory. +It validates the +.Va uio_offset +and +.Va uio_resid +values against the size of the existing buffer, handling short +transfers when the request partially overlaps the buffer. +When +.Va uio_offset +is greater than or equal to the buffer size, the result is success +with no bytes transferred, effectively signaling EOF. +.Sh RETURN VALUES +On success +.Fn uiomove , +.Fn uiomove_frombuf , +and +.Fn uiomove_nofault +will return 0; on error they will return an appropriate error code. +.Sh EXAMPLES +The idea is that the driver maintains a private buffer for its data, +and processes the request in chunks of maximal the size of this +buffer. +Note that the buffer handling below is very simplified and +will not work (the buffer pointer is not being advanced in case of a +partial read), it is just here to demonstrate the +.Nm +handling. +.Bd -literal +/* MIN() can be found there: */ +#include + +#define BUFSIZE 512 +static char buffer[BUFSIZE]; + +static int data_available; /* amount of data that can be read */ + +static int +fooread(struct cdev *dev, struct uio *uio, int flag) +{ + int rv, amnt; + + rv = 0; + while (uio->uio_resid > 0) { + if (data_available > 0) { + amnt = MIN(uio->uio_resid, data_available); + rv = uiomove(buffer, amnt, uio); + if (rv != 0) + break; + data_available -= amnt; + } else + tsleep(...); /* wait for a better time */ + } + if (rv != 0) { + /* do error cleanup here */ + } + return (rv); +} +.Ed +.Sh ERRORS +.Fn uiomove +and +.Fn uiomove_nofault +will fail and return the following error code if: +.Bl -tag -width Er +.It Bq Er EFAULT +The invoked +.Xr copyin 9 +or +.Xr copyout 9 +returned +.Er EFAULT +.El +.Pp +In addition, +.Fn uiomove_nofault +will fail and return the following error code if: +.Bl -tag -width Er +.It Bq Er EFAULT +A page fault occurs. +.El +.Sh SEE ALSO +.Xr read 2 , +.Xr readv 2 , +.Xr write 2 , +.Xr writev 2 , +.Xr copyin 9 , +.Xr copyout 9 , +.Xr sleep 9 +.Sh HISTORY +The +.Nm +mechanism appeared in some early version of +.Ux . +.Sh AUTHORS +This manual page was written by +.An J\(:org Wunsch . diff --git a/static/freebsd/man9/unr.9 b/static/freebsd/man9/unr.9 new file mode 100644 index 00000000..73717dd9 --- /dev/null +++ b/static/freebsd/man9/unr.9 @@ -0,0 +1,191 @@ +.\" Copyright (c) 2005 Gleb Smirnoff +.\" 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 April 21, 2022 +.Dt UNR 9 +.Os +.Sh NAME +.Nm new_unrhdr , +.Nm clean_unrhdr , +.Nm clear_unrhdr , +.Nm delete_unrhdr , +.Nm alloc_unr , +.Nm alloc_unr_specific , +.Nm free_unr , +.Nm create_iter_unr , +.Nm next_iter_unr , +.Nm free_iter_unr +.Nd "kernel unit number allocator" +.Sh SYNOPSIS +.In sys/systm.h +.Ft "struct unrhdr *" +.Fn new_unrhdr "int low" "int high" "struct mtx *mutex" +.Ft void +.Fn clean_unrhdr "struct unrhdr *uh" +.Ft void +.Fn clean_unrhdrl "struct unrhdr *uh" +.Ft void +.Fn clear_unrhdr "struct unrhdr *uh" +.Ft void +.Fn delete_unrhdr "struct unrhdr *uh" +.Ft int +.Fn alloc_unr "struct unrhdr *uh" +.Ft int +.Fn alloc_unrl "struct unrhdr *uh" +.Ft int +.Fn alloc_unr_specific "struct unrhdr *uh" "u_int item" +.Ft void +.Fn free_unr "struct unrhdr *uh" "u_int item" +.Ft void * +.Fn create_iter_unr "struct unrhdr *uh" +.Ft int +.Fn next_iter_unr "void *handle" +.Ft void +.Fn free_iter_unr "void *handle" +.Sh DESCRIPTION +The kernel unit number allocator is a generic facility, which allows to allocate +unit numbers within a specified range. +.Bl -tag -width indent +.It Fn new_unrhdr low high mutex +Initialize a new unit number allocator entity. +The +.Fa low +and +.Fa high +arguments +specify minimum and maximum number of unit numbers. +There is no cost associated with the range of unit numbers, so unless the resource +really is finite, +.Dv INT_MAX +can be used. +If +.Fa mutex +is not +.Dv NULL , +it is used for locking when allocating and freeing units. +If the passed value is the token +.Va UNR_NO_MTX , +then no locking is applied internally. +Otherwise, internal mutex is used. +.It Fn clear_unrhdr uh +Clear all units from the specified unit number allocator entity. +This function resets the entity as if it were just initialized with +.Fn new_unrhdr . +.It Fn delete_unrhdr uh +Delete specified unit number allocator entity. +This function frees the memory associated with the entity, it does not free +any units. +To free all units use +.Fn clear_unrhdr . +.It Fn clean_unrhdr uh +Freeing unit numbers might result in some internal memory becoming unused. +There are +.Nm unit +allocator consumers that cannot tolerate taking +.Xr malloc 9 +locks to free the memory, while having their unit mutex locked. +For this reason, free of the unused memory after delete is postponed +until the consumer can afford calling into the +.Xr malloc 9 +subsystem. +Call +.Fn clean_unrhdr uh +to do the cleanup. +In particular, this needs to be done before freeing a unr, if +a deletion of units could have been performed. +.It Fn clean_unrhdrl +Same as +.Fn clean_unrhdr , +but assumes that the unr mutex is already owned, if any. +.It Fn alloc_unr uh +Return a new unit number. +The lowest free number is always allocated. +This function does not allocate memory and never sleeps, however it may +block on a mutex. +If no free unit numbers are left, +.Li \-1 +is returned. +.It Fn alloc_unrl uh +Same as +.Fn alloc_unr +except that mutex is assumed to be already locked and thus is not used. +.It Fn alloc_unr_specific uh item +Allocate a specific unit number. +This function allocates memory and thus may sleep. +The allocated unit number is returned on success. +If the specified number is already allocated or out of the range, +.Li \-1 +is returned. +.It Fn free_unr uh item +Free a previously allocated unit number. +This function may require allocating memory, and thus it can sleep. +There is no pre-locked variant. +.El +.Sh ITERATOR INTERFACE +The +.Nm unr +facility provides an interface to iterate over all allocated units +for the given +.Dv unrhdr . +Iterators are identified by an opaque handle. +More than one iterators can operate simultaneously; the iterator position +data is recorded only in the iterator handle. +.Pp +Consumers must ensure that the unit allocator is not modified between +calls to the iterator functions. +In particular, the internal allocator mutex cannot provide consistency, +because it is acquired and dropped inside the +.Fn next_iter_unr +function. +If the allocator was modified, it is safe to free the iterator with +.Fn free_iter_unr +method nevertheless. +.Bl -tag -width indent +.It Fn create_iter_unr uh +Create an iterator. +Return the handle that should be passed to other iterator functions. +.It Fn next_iter_unr handle +Return the value of the next unit. +Units are returned in ascending order. +A return value of +.Li \-1 +indicates the end of iteration, in which +case +.Li \-1 +is returned for all future calls. +.It Fn free_iter_unr handle +Free the iterator, handle is no longer valid. +.El +.Sh CODE REFERENCES +The above functions are implemented in +.Pa sys/kern/subr_unit.c . +.Sh HISTORY +Kernel unit number allocator first appeared in +.Fx 6.0 . +.Sh AUTHORS +.An -nosplit +Kernel unit number allocator was written by +.An Poul-Henning Kamp . +This manpage was written by +.An Gleb Smirnoff . diff --git a/static/freebsd/man9/usbdi.9 b/static/freebsd/man9/usbdi.9 new file mode 100644 index 00000000..47034b87 --- /dev/null +++ b/static/freebsd/man9/usbdi.9 @@ -0,0 +1,630 @@ +.\" +.\" Copyright (c) 2005 Ian Dowse +.\" 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 November 14, 2016 +.Dt USBDI 9 +.Os +.Sh NAME +.Nm usb_fifo_alloc_buffer , +.Nm usb_fifo_attach , +.Nm usb_fifo_detach , +.Nm usb_fifo_free_buffer , +.Nm usb_fifo_get_data , +.Nm usb_fifo_get_data_buffer , +.Nm usb_fifo_get_data_error , +.Nm usb_fifo_get_data_linear , +.Nm usb_fifo_put_bytes_max , +.Nm usb_fifo_put_data , +.Nm usb_fifo_put_data_buffer , +.Nm usb_fifo_put_data_error , +.Nm usb_fifo_put_data_linear , +.Nm usb_fifo_reset , +.Nm usb_fifo_softc , +.Nm usb_fifo_wakeup , +.Nm usbd_do_request , +.Nm usbd_do_request_flags , +.Nm usbd_errstr , +.Nm usbd_lookup_id_by_info , +.Nm usbd_lookup_id_by_uaa , +.Nm usbd_transfer_clear_stall , +.Nm usbd_transfer_drain , +.Nm usbd_transfer_pending , +.Nm usbd_transfer_poll , +.Nm usbd_transfer_setup , +.Nm usbd_transfer_start , +.Nm usbd_transfer_stop , +.Nm usbd_transfer_submit , +.Nm usbd_transfer_unsetup , +.Nm usbd_xfer_clr_flag , +.Nm usbd_xfer_frame_data , +.Nm usbd_xfer_frame_len , +.Nm usbd_xfer_get_frame , +.Nm usbd_xfer_get_priv , +.Nm usbd_xfer_is_stalled , +.Nm usbd_xfer_max_framelen , +.Nm usbd_xfer_max_frames , +.Nm usbd_xfer_max_len , +.Nm usbd_xfer_set_flag , +.Nm usbd_xfer_set_frame_data , +.Nm usbd_xfer_set_frame_len , +.Nm usbd_xfer_set_frame_offset , +.Nm usbd_xfer_set_frames , +.Nm usbd_xfer_set_interval , +.Nm usbd_xfer_set_priv , +.Nm usbd_xfer_set_stall , +.Nm usbd_xfer_set_timeout , +.Nm usbd_xfer_softc , +.Nm usbd_xfer_state , +.Nm usbd_xfer_status +.Nd Universal Serial Bus driver programming interface +.Sh SYNOPSIS +.In dev/usb/usb.h +.In dev/usb/usbdi.h +.In dev/usb/usbdi_util.h +.Ft "usb_error_t" +.Fo "usbd_transfer_setup" +.Fa "struct usb_device *udev" +.Fa "const uint8_t *ifaces" +.Fa "struct usb_xfer **pxfer" +.Fa "const struct usb_config *setup_start" +.Fa "uint16_t n_setup" +.Fa "void *priv_sc" +.Fa "struct mtx *priv_mtx" +.Fc +.Ft "void" +.Fo "usbd_transfer_unsetup" +.Fa "struct usb_xfer **pxfer" +.Fa "uint16_t n_setup" +.Fc +.Ft "void" +.Fo "usbd_transfer_start" +.Fa "struct usb_xfer *xfer" +.Fc +.Ft "void" +.Fo "usbd_transfer_stop" +.Fa "struct usb_xfer *xfer" +.Fc +.Ft "void" +.Fo "usbd_transfer_drain" +.Fa "struct usb_xfer *xfer" +.Fc +.Sh DESCRIPTION +The Universal Serial Bus (USB) driver programming interface provides +USB peripheral drivers with a host controller independent API for +controlling and communicating with USB peripherals. +The +.Nm usb +module supports both USB Host and USB Device side mode. +.Sh USB TRANSFER MANAGEMENT FUNCTIONS +The USB standard defines four types of USB transfers. +. +Control transfers, Bulk transfers, Interrupt transfers and Isochronous +transfers. +. +All the transfer types are managed using the following five functions: +. +.Pp +. +.Fn usbd_transfer_setup +This function will allocate memory for and initialise an array of USB +transfers and all required DMA memory. +. +This function can sleep or block waiting for resources to become +available. +.Fa udev +is a pointer to "struct usb_device". +.Fa ifaces +is an array of interface index numbers to use. +See "if_index". +.Fa pxfer +is a pointer to an array of USB transfer pointers that are initialized +to NULL, and then pointed to allocated USB transfers. +.Fa setup_start +is a pointer to an array of USB config structures. +.Fa n_setup +is a number telling the USB system how many USB transfers should be +setup. +.Fa priv_sc +is the private softc pointer, which will be used to initialize +"xfer->priv_sc". +.Fa priv_mtx +is the private mutex protecting the transfer structure and the +softc. +This pointer is used to initialize "xfer->priv_mtx". +This function returns zero upon success. +A non-zero return value indicates failure. +. +.Pp +. +.Fn usbd_transfer_unsetup +This function will release the given USB transfers and all allocated +resources associated with these USB transfers. +.Fa pxfer +is a pointer to an array of USB transfer pointers, that may be NULL, +that should be freed by the USB system. +.Fa n_setup +is a number telling the USB system how many USB transfers should be +unsetup. +. +This function can sleep waiting for USB transfers to complete. +. +This function is NULL safe with regard to the USB transfer structure +pointer. +. +It is not allowed to call this function from the USB transfer +callback. +. +.Pp +. +.Fn usbd_transfer_start +This function will start the USB transfer pointed to by +.Fa xfer , +if not already started. +. +This function is always non-blocking and must be called with the +so-called private USB mutex locked. +. +This function is NULL safe with regard to the USB transfer structure +pointer. +. +.Pp +. +.Fn usbd_transfer_stop +This function will stop the USB transfer pointed to by +.Fa xfer , +if not already stopped. +. +This function is always non-blocking and must be called with the +so-called private USB mutex locked. +. +This function can return before the USB callback has been called. +. +This function is NULL safe with regard to the USB transfer structure +pointer. +. +If the transfer was in progress, the callback will called with +"USB_ST_ERROR" and "error = USB_ERR_CANCELLED". +. +.Pp +. +.Fn usbd_transfer_drain +This function will stop an USB transfer, if not already stopped and +wait for any additional USB hardware operations to complete. +. +Buffers that are loaded into DMA using "usbd_xfer_set_frame_data()" can +safely be freed after that this function has returned. +. +This function can block the caller and will not return before the USB +callback has been called. +. +This function is NULL safe with regard to the USB transfer structure +pointer. +. +.Sh USB TRANSFER CALLBACK +. +The USB callback has three states. +. +USB_ST_SETUP, USB_ST_TRANSFERRED and USB_ST_ERROR. +USB_ST_SETUP is the initial state. +. +After the callback has been called with this state it will always be +called back at a later stage in one of the other two states. +. +The USB callback should not restart the USB transfer in case the error +cause is USB_ERR_CANCELLED. +. +The USB callback is protected from recursion. +. +That means one can start and stop whatever transfer from the callback +of another transfer one desires. +. +Also the transfer that is currently called back. +. +Recursion is handled like this that when the callback that wants to +recurse returns it is called one more time. +. +. +.Pp +. +.Fn usbd_transfer_submit +This function should only be called from within the USB callback and +is used to start the USB hardware. +. +An USB transfer can have multiple frames consisting of one or more USB +packets making up an I/O vector for all USB transfer types. +. +.Bd -literal -offset indent +void +usb_default_callback(struct usb_xfer *xfer, usb_error_t error) +{ + int actlen; + + usbd_xfer_status(xfer, &actlen, NULL, NULL, NULL); + + switch (USB_GET_STATE(xfer)) { + case USB_ST_SETUP: + /* + * Setup xfer frame lengths/count and data + */ + usbd_transfer_submit(xfer); + break; + + case USB_ST_TRANSFERRED: + /* + * Read usb frame data, if any. + * "actlen" has the total length for all frames + * transferred. + */ + break; + + default: /* Error */ + /* + * Print error message and clear stall + * for example. + */ + break; + } + /* + * Here it is safe to do something without the private + * USB mutex locked. + */ + return; +} +.Ed +. +.Sh USB CONTROL TRANSFERS +An USB control transfer has three parts. +. +First the SETUP packet, then DATA packet(s) and then a STATUS +packet. +. +The SETUP packet is always pointed to by frame 0 and the +length is set by +.Fn usbd_xfer_frame_len +also if there should not be +sent any SETUP packet! +If an USB control transfer has no DATA stage, +then the number of frames should be set to 1. +. +Else the default number of frames is 2. +. +.Bd -literal -offset indent + +Example1: SETUP + STATUS + usbd_xfer_set_frames(xfer, 1); + usbd_xfer_set_frame_len(xfer, 0, 8); + usbd_transfer_submit(xfer); + +Example2: SETUP + DATA + STATUS + usbd_xfer_set_frames(xfer, 2); + usbd_xfer_set_frame_len(xfer, 0, 8); + usbd_xfer_set_frame_len(xfer, 1, 1); + usbd_transfer_submit(xfer); + +Example3: SETUP + DATA + STATUS - split +1st callback: + usbd_xfer_set_frames(xfer, 1); + usbd_xfer_set_frame_len(xfer, 0, 8); + usbd_transfer_submit(xfer); + +2nd callback: + /* IMPORTANT: frbuffers[0] must still point at the setup packet! */ + usbd_xfer_set_frames(xfer, 2); + usbd_xfer_set_frame_len(xfer, 0, 0); + usbd_xfer_set_frame_len(xfer, 1, 1); + usbd_transfer_submit(xfer); + +Example4: SETUP + STATUS - split +1st callback: + usbd_xfer_set_frames(xfer, 1); + usbd_xfer_set_frame_len(xfer, 0, 8); + usbd_xfer_set_flag(xfer, USB_MANUAL_STATUS); + usbd_transfer_submit(xfer); + +2nd callback: + usbd_xfer_set_frames(xfer, 1); + usbd_xfer_set_frame_len(xfer, 0, 0); + usbd_xfer_clr_flag(xfer, USB_MANUAL_STATUS); + usbd_transfer_submit(xfer); + +.Ed +.Sh USB TRANSFER CONFIG +To simplify the search for endpoints the +.Nm usb +module defines a USB config structure where it is possible to specify +the characteristics of the wanted endpoint. +.Bd -literal -offset indent + +struct usb_config { + bufsize, + callback + direction, + endpoint, + frames, + index flags, + interval, + timeout, + type, +}; + +.Ed +. +.Pp +.Fa type +field selects the USB pipe type. +. +Valid values are: UE_INTERRUPT, UE_CONTROL, UE_BULK, +UE_ISOCHRONOUS. +. +The special value UE_BULK_INTR will select BULK and INTERRUPT pipes. +. +This field is mandatory. +. +.Pp +.Fa endpoint +field selects the USB endpoint number. +. +A value of 0xFF, "-1" or "UE_ADDR_ANY" will select the first matching +endpoint. +. +This field is mandatory. +. +.Pp +.Fa direction +field selects the USB endpoint direction. +. +A value of "UE_DIR_ANY" will select the first matching endpoint. +. +Else valid values are: "UE_DIR_IN" and "UE_DIR_OUT". +. +"UE_DIR_IN" and "UE_DIR_OUT" can be binary OR'ed by "UE_DIR_SID" which +means that the direction will be swapped in case of +USB_MODE_DEVICE. +. +Note that "UE_DIR_IN" refers to the data transfer direction of the +"IN" tokens and "UE_DIR_OUT" refers to the data transfer direction of +the "OUT" tokens. +. +This field is mandatory. +. +.Pp +.Fa interval +field selects the interrupt interval. +. +The value of this field is given in milliseconds and is independent of +device speed. +. +Depending on the endpoint type, this field has different meaning: +.Bl -tag -width "UE_ISOCHRONOUS" +.It UE_INTERRUPT +"0" use the default interrupt interval based on endpoint descriptor. +"Else" use the given value for polling rate. +.It UE_ISOCHRONOUS +"0" use default. +"Else" the value is ignored. +.It UE_BULK +.It UE_CONTROL +"0" no transfer pre-delay. +"Else" a delay as given by this field in +milliseconds is inserted before the hardware is started when +"usbd_transfer_submit()" is called. +.Pp +NOTE: The transfer timeout, if any, is started after that the +pre-delay has elapsed! +.El +. +.Pp +.Fa timeout +field, if non-zero, will set the transfer timeout in milliseconds. +If the "timeout" field is zero and the transfer type is ISOCHRONOUS a +timeout of 250ms will be used. +. +.Pp +.Fa frames +field sets the maximum number of frames. +If zero is specified it will yield the following results: +.Bl -tag -width "UE_INTERRUPT" +.It UE_BULK +xfer->nframes = 1; +.It UE_INTERRUPT +xfer->nframes = 1; +.It UE_CONTROL +xfer->nframes = 2; +.It UE_ISOCHRONOUS +Not allowed. +Will cause an error. +.El +. +.Pp +.Fa ep_index +field allows you to give a number, in case more endpoints match the +description, that selects which matching "ep_index" should be used. +. +.Pp +.Fa if_index +field allows you to select which of the interface numbers in the +"ifaces" array parameter passed to "usbd_transfer_setup" that should +be used when setting up the given USB transfer. +. +.Pp +.Fa flags +field has type "struct usb_xfer_flags" and allows one to set initial +flags an USB transfer. +Valid flags are: +.Bl -tag -width "force_short_xfer" +.It force_short_xfer +This flag forces the last transmitted USB packet to be short. +A short packet has a length of less than "xfer->max_packet_size", which +derives from "wMaxPacketSize". +This flag can be changed during operation. +.It short_xfer_ok +This flag allows the received transfer length, "xfer->actlen" to be +less than "xfer->sumlen" upon completion of a transfer. +This flag can be changed during operation. +.It short_frames_ok +This flag allows the reception of multiple short USB frames. +This flag +only has effect for BULK and INTERRUPT endpoints and if the number of +frames received is greater than 1. +This flag can be changed during operation. +.It pipe_bof +This flag causes a failing USB transfer to remain first in the PIPE +queue except in the case of "xfer->error" equal to +"USB_ERR_CANCELLED". +No other USB transfers in the affected PIPE queue +will be started until either: +.Bl -tag -width "X" +.It 1 +The failing USB transfer is stopped using "usbd_transfer_stop()". +.It 2 +The failing USB transfer performs a successful transfer. +.El +The purpose of this flag is to avoid races when multiple transfers are +queued for execution on an USB endpoint, and the first executing +transfer fails leading to the need for clearing of stall for +example. +. +In this case this flag is used to prevent the following USB transfers +from being executed at the same time the clear-stall command is +executed on the USB control endpoint. +. +This flag can be changed during operation. +.Pp +"BOF" is short for "Block On Failure". +.Pp +NOTE: This flag should be set on all BULK and INTERRUPT USB transfers +which use an endpoint that can be shared between userland and kernel. +. +. +.It proxy_buffer +Setting this flag will cause that the total buffer size will be +rounded up to the nearest atomic hardware transfer size. +. +The maximum data length of any USB transfer is always stored in the +"xfer->max_data_length". +. +For control transfers the USB kernel will allocate additional space +for the 8-bytes of SETUP header. +. +These 8-bytes are not counted by the "xfer->max_data_length" +variable. +. +This flag cannot be changed during operation. +. +. +.It ext_buffer +Setting this flag will cause that no data buffer will be +allocated. +. +Instead the USB client must supply a data buffer. +. +This flag cannot be changed during operation. +. +. +.It manual_status +Setting this flag prevents an USB STATUS stage to be appended to the +end of the USB control transfer. +. +If no control data is transferred this flag must be cleared. +. +Else an error will be returned to the USB callback. +. +This flag is mostly useful for the USB device side. +. +This flag can be changed during operation. +. +. +.It no_pipe_ok +Setting this flag causes the USB_ERR_NO_PIPE error to be ignored. +This flag cannot be changed during operation. +. +. +.It stall_pipe +.Bl -tag -width "Device Side Mode" +.It Device Side Mode +Setting this flag will cause STALL pids to be sent to the endpoint +belonging to this transfer before the transfer is started. +. +The transfer is started at the moment the host issues a clear-stall +command on the STALL'ed endpoint. +. +This flag can be changed during operation. +.It Host Side Mode +Setting this flag will cause a clear-stall control request to be +executed on the endpoint before the USB transfer is started. +.El +.Pp +If this flag is changed outside the USB callback function you have to +use the "usbd_xfer_set_stall()" and "usbd_transfer_clear_stall()" +functions! This flag is automatically cleared after that the stall or +clear stall has been executed. +. +.It pre_scale_frames +If this flag is set the number of frames specified is assumed to give the buffering time in milliseconds instead of frames. +During transfer setup the frames field is pre scaled with the corresponding value for the endpoint and rounded to the nearest number of frames greater than zero. +This option only has effect for ISOCHRONOUS transfers. +.El +.Pp +.Fa bufsize +field sets the total buffer size in bytes. +. +If this field is zero, "wMaxPacketSize" will be used, multiplied by +the "frames" field if the transfer type is ISOCHRONOUS. +. +This is useful for setting up interrupt pipes. +. +This field is mandatory. +.Pp +NOTE: For control transfers "bufsize" includes the length of the +request structure. +. +.Pp +.Fa callback +pointer sets the USB callback. +This field is mandatory. +. +. +.Sh USB LINUX COMPAT LAYER +The +.Nm usb +module supports the Linux USB API. +. +. +.Sh SEE ALSO +.Xr libusb 3 , +.Xr usb 4 , +.Xr usbconfig 8 +.Sh STANDARDS +The +.Nm usb +module complies with the USB 2.0 standard. +.Sh HISTORY +The +.Nm usb +module has been inspired by the NetBSD USB stack initially written by +Lennart Augustsson. +The +.Nm usb +module was written by +.An Hans Petter Selasky Aq Mt hselasky@FreeBSD.org . diff --git a/static/freebsd/man9/vaccess.9 b/static/freebsd/man9/vaccess.9 new file mode 100644 index 00000000..fe9a37d1 --- /dev/null +++ b/static/freebsd/man9/vaccess.9 @@ -0,0 +1,115 @@ +.\"- +.\" Copyright (c) 2001 Robert N. M. Watson +.\" 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 August 23, 2022 +.Dt VACCESS 9 +.Os +.Sh NAME +.Nm vaccess +.Nd generate an access control decision using vnode parameters +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fo vaccess +.Fa "enum vtype type" +.Fa "mode_t file_mode" +.Fa "uid_t file_uid" +.Fa "gid_t file_gid" +.Fa "accmode_t accmode" +.Fa "struct ucred *cred" +.Fc +.Sh DESCRIPTION +This call implements the logic for the +.Ux +discretionary file security model +common to many file systems in +.Fx . +It accepts the vnodes type +.Fa type , +permissions via +.Fa file_mode , +owning UID +.Fa file_uid , +owning GID +.Fa file_gid , +desired access mode +.Fa accmode +and requesting credential +.Fa cred . +.Pp +This call is intended to support implementations of +.Xr VOP_ACCESS 9 , +which will use their own access methods to retrieve the vnode properties, +and then invoke +.Fn vaccess +in order to perform the actual check. +Implementations of +.Xr VOP_ACCESS 9 +may choose to implement additional security mechanisms whose results will +be composed with the return value. +.Pp +The algorithm used by +.Fn vaccess +selects a component of the file permission bits based on comparing the +passed credential, file owner, and file group. +If the credential's effective UID matches the file owner, then the +owner component of the permission bits is selected. +If the UID does not match, then the credential's effective GID, followed +by additional groups, are compared with the file group\[em]if there is +a match, then the group component of the permission bits is selected. +If neither the credential UID or GIDs match the passed file owner and +group, then the other component of the permission bits is selected. +.Pp +Once appropriate protections are selected for the current credential, +the requested access mode, in combination with the vnode type, will be +compared with the discretionary rights available for the credential. +If the rights granted by discretionary protections are insufficient, +then super-user privilege, if available for the credential, will also be +considered. +.Sh RETURN VALUES +.Fn vaccess +will return 0 on success, or a non-zero error value on failure. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EACCES +Permission denied. +An attempt was made to access a file in a way forbidden by its file access +permissions. +.It Bq Er EPERM +Operation not permitted. +An attempt was made to perform an operation limited to processes with +appropriate privileges or to the owner of a file or other resource. +.El +.Sh SEE ALSO +.Xr vaccess_acl_nfs4 9 , +.Xr vaccess_acl_posix1e 9 , +.Xr vnode 9 , +.Xr VOP_ACCESS 9 +.Sh AUTHORS +This manual page and the current implementation of +.Fn vaccess +were written by +.An Robert Watson . diff --git a/static/freebsd/man9/vaccess_acl_nfs4.9 b/static/freebsd/man9/vaccess_acl_nfs4.9 new file mode 100644 index 00000000..76cedc34 --- /dev/null +++ b/static/freebsd/man9/vaccess_acl_nfs4.9 @@ -0,0 +1,127 @@ +.\"- +.\" Copyright (c) 2001 Robert N. M. Watson +.\" 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 September 18, 2009 +.Dt VACCESS_ACL_NFS4 9 +.Os +.Sh NAME +.Nm vaccess_acl_nfs4 +.Nd generate a NFSv4 ACL access control decision using vnode parameters +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/acl.h +.Ft int +.Fo vaccess_acl_nfs4 +.Fa "enum vtype type" +.Fa "uid_t file_uid" +.Fa "gid_t file_gid" +.Fa "struct acl *acl" +.Fa "accmode_t accmode" +.Fa "struct ucred *cred" +.Fa "int *privused" +.Fc +.Sh DESCRIPTION +This call implements the logic for the +.Ux +discretionary file security model +with NFSv4 ACL extensions. +It accepts the vnodes type +.Fa type , +owning UID +.Fa file_uid , +owning GID +.Fa file_gid , +access ACL for the file +.Fa acl , +desired access mode +.Fa accmode , +requesting credential +.Fa cred , +and an optional call-by-reference +.Vt int +pointer returning whether or not +privilege was required for successful evaluation of the call; the +.Fa privused +pointer may be set to +.Dv NULL +by the caller in order not to be informed of +privilege information, or it may point to an integer that will be set to +1 if privilege is used, and 0 otherwise. +.Pp +This call is intended to support implementations of +.Xr VOP_ACCESS 9 , +which will use their own access methods to retrieve the vnode properties, +and then invoke +.Fn vaccess_acl_nfs4 +in order to perform the actual check. +Implementations of +.Xr VOP_ACCESS 9 +may choose to implement additional security mechanisms whose results will +be composed with the return value. +.Pp +The algorithm used by +.Fn vaccess_acl_nfs4 +is based on the NFSv4 ACL evaluation algorithm, as described in +NFSv4 Minor Version 1, draft-ietf-nfsv4-minorversion1-21.txt. +The algorithm selects a +.Em matching +entry from the access ACL, which may +then be composed with an available ACL mask entry, providing +.Ux +security compatibility. +.Pp +Once appropriate protections are selected for the current credential, +the requested access mode, in combination with the vnode type, will be +compared with the discretionary rights available for the credential. +If the rights granted by discretionary protections are insufficient, +then super-user privilege, if available for the credential, will also be +considered. +.Sh RETURN VALUES +.Fn vaccess_acl_nfs4 +will return 0 on success, or a non-zero error value on failure. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EACCES +Permission denied. +An attempt was made to access a file in a way forbidden by its file access +permissions. +.It Bq Er EPERM +Operation not permitted. +An attempt was made to perform an operation limited to processes with +appropriate privileges or to the owner of a file or other resource. +.El +.Sh SEE ALSO +.Xr vaccess 9 , +.Xr vnode 9 , +.Xr VOP_ACCESS 9 +.Sh AUTHORS +Current implementation of +.Fn vaccess_acl_nfs4 +was written by +.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org . +.Sh BUGS +This manual page should include a full description of the NFSv4 ACL +evaluation algorithm, or cross reference another page that does. diff --git a/static/freebsd/man9/vaccess_acl_posix1e.9 b/static/freebsd/man9/vaccess_acl_posix1e.9 new file mode 100644 index 00000000..5b61a00e --- /dev/null +++ b/static/freebsd/man9/vaccess_acl_posix1e.9 @@ -0,0 +1,126 @@ +.\"- +.\" Copyright (c) 2001 Robert N. M. Watson +.\" 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 August 22, 2001 +.Dt VACCESS_ACL_POSIX1E 9 +.Os +.Sh NAME +.Nm vaccess_acl_posix1e +.Nd generate a POSIX.1e ACL access control decision using vnode parameters +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/acl.h +.Ft int +.Fo vaccess_acl_posix1e +.Fa "enum vtype type" +.Fa "uid_t file_uid" +.Fa "gid_t file_gid" +.Fa "struct acl *acl" +.Fa "accmode_t accmode" +.Fa "struct ucred *cred" +.Fa "int *privused" +.Fc +.Sh DESCRIPTION +This call implements the logic for the +.Ux +discretionary file security model +with POSIX.1e ACL extensions. +It accepts the vnodes type +.Fa type , +owning UID +.Fa file_uid , +owning GID +.Fa file_gid , +access ACL for the file +.Fa acl , +desired access mode +.Fa accmode , +requesting credential +.Fa cred , +and an optional call-by-reference +.Vt int +pointer returning whether or not +privilege was required for successful evaluation of the call; the +.Fa privused +pointer may be set to +.Dv NULL +by the caller in order not to be informed of +privilege information, or it may point to an integer that will be set to +1 if privilege is used, and 0 otherwise. +.Pp +This call is intended to support implementations of +.Xr VOP_ACCESS 9 , +which will use their own access methods to retrieve the vnode properties, +and then invoke +.Fn vaccess_acl_posix1e +in order to perform the actual check. +Implementations of +.Xr VOP_ACCESS 9 +may choose to implement additional security mechanisms whose results will +be composed with the return value. +.Pp +The algorithm used by +.Fn vaccess_acl_posix1e +is based on the POSIX.1e ACL evaluation algorithm. +The algorithm selects a +.Em matching +entry from the access ACL, which may +then be composed with an available ACL mask entry, providing +.Ux +security compatibility. +.Pp +Once appropriate protections are selected for the current credential, +the requested access mode, in combination with the vnode type, will be +compared with the discretionary rights available for the credential. +If the rights granted by discretionary protections are insufficient, +then super-user privilege, if available for the credential, will also be +considered. +.Sh RETURN VALUES +.Fn vaccess_acl_posix1e +will return 0 on success, or a non-zero error value on failure. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EACCES +Permission denied. +An attempt was made to access a file in a way forbidden by its file access +permissions. +.It Bq Er EPERM +Operation not permitted. +An attempt was made to perform an operation limited to processes with +appropriate privileges or to the owner of a file or other resource. +.El +.Sh SEE ALSO +.Xr vaccess 9 , +.Xr vnode 9 , +.Xr VOP_ACCESS 9 +.Sh AUTHORS +This manual page and the current implementation of +.Fn vaccess_acl_posix1e +were written by +.An Robert Watson . +.Sh BUGS +This manual page should include a full description of the POSIX.1e ACL +evaluation algorithm, or cross reference another page that does. diff --git a/static/freebsd/man9/vflush.9 b/static/freebsd/man9/vflush.9 new file mode 100644 index 00000000..b5d3cacf --- /dev/null +++ b/static/freebsd/man9/vflush.9 @@ -0,0 +1,79 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 November 21, 2001 +.Dt VFLUSH 9 +.Os +.Sh NAME +.Nm vflush +.Nd "flush vnodes for a mount point" +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn vflush "struct mount *mp" "int rootrefs" "int flags" "struct thread *td" +.Sh DESCRIPTION +The +.Fn vflush +function removes any vnodes in the vnode table that belong to the given +.Vt mount +structure. +.Pp +Its arguments are: +.Bl -tag -width ".Fa rootrefs" +.It Fa mp +The mount point whose vnodes should be removed. +.It Fa rootrefs +The number of references expected on the root vnode. +.Xr vrele 9 +will be invoked on the root vnode +.Fa rootrefs +times. +.It Fa flags +The flags indicating how vnodes should be handled. +.Bl -tag -width ".Dv WRITECLOSE" +.It Dv FORCECLOSE +If set, busy vnodes will be forcibly closed. +.It Dv SKIPSYSTEM +If set, vnodes with the +.Dv VV_SYSTEM +flag set will be skipped. +.It Dv WRITECLOSE +If set, only regular files currently opened for writing will be removed. +.El +.It Fa td +The calling thread. +.El +.Sh RETURN VALUES +A value of 0 is returned if the flush is successful; otherwise, +.Er EBUSY +will be returned. +.Sh SEE ALSO +.Xr vgone 9 , +.Xr vrele 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/vfs_busy.9 b/static/freebsd/man9/vfs_busy.9 new file mode 100644 index 00000000..5cbd1d6f --- /dev/null +++ b/static/freebsd/man9/vfs_busy.9 @@ -0,0 +1,89 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 February 11, 2013 +.Dt VFS_BUSY 9 +.Os +.Sh NAME +.Nm vfs_busy +.Nd "marks a mount point as busy" +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.Ft int +.Fn vfs_busy "struct mount *mp" "int flags" +.Sh DESCRIPTION +The +.Fn vfs_busy +function marks a mount point as busy by incrementing +the reference count of a mount point. +It also delays unmounting by sleeping on +.Fa mp +if the +.Dv MNTK_UNMOUNT +flag is set in +.Fa mp->mnt_kern_flag +and the +.Dv MBF_NOWAIT +flag is +.Em not +set. +.Pp +Its arguments are: +.Bl -tag -width ".Fa flags" +.It Fa mp +The mount point to busy. +.It Fa flags +Flags controlling how +.Fn vfs_busy +should act. +.Bl -tag -width ".Dv MBF_MNTLSTLOCK" +.It Dv MBF_NOWAIT +do not sleep if +.Dv MNTK_UNMOUNT +is set. +.It Dv MBF_MNTLSTLOCK +drop the mountlist_mtx in the critical path. +.El +.El +.Sh RETURN VALUES +A 0 value is returned on success. +If the mount point is being +unmounted and MBF_NOWAIT flag is specified +.Er ENOENT +will be returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ENOENT +The mount point is being unmounted +.Dv ( MNTK_UNMOUNT +is set). +.El +.Sh SEE ALSO +.Xr vfs_unbusy 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/vfs_getnewfsid.9 b/static/freebsd/man9/vfs_getnewfsid.9 new file mode 100644 index 00000000..8eb95805 --- /dev/null +++ b/static/freebsd/man9/vfs_getnewfsid.9 @@ -0,0 +1,75 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 November 21, 2001 +.Dt VFS_GETNEWFSID 9 +.Os +.Sh NAME +.Nm vfs_getnewfsid +.Nd "allocate a new file system identifier" +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.Ft void +.Fn vfs_getnewfsid "struct mount *mp" +.Sh DESCRIPTION +The +.Fn vfs_getnewfsid +function allocates a new file system identifier for the mount point given. +File systems typically call +.Fn vfs_getnewfsid +in their mount routine in order to acquire a unique ID within the system +which can later be used to uniquely identify the file system via calls such as +.Xr vfs_getvfs 9 . +.Pp +The actual +.Vt fsid +is made up of two 32 bit integers, that are stored in the +.Vt statfs +structure of +.Fa mp . +The first integer is unique in the set of mounted file systems, +while the second holds the file system type. +.Bd -literal +typedef struct fsid { + int32_t val[2]; +} fsid_t; +.Ed +.Sh PSEUDOCODE +.Bd -literal +xxx_mount(struct mount *mp, char *path, caddr_t data, + struct nameidata *ndp, struct thread *td) +{ + ... + vfs_getnewfsid(mp); + ... +} +.Ed +.Sh SEE ALSO +.Xr vfs_getvfs 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/vfs_getopt.9 b/static/freebsd/man9/vfs_getopt.9 new file mode 100644 index 00000000..ff0f0273 --- /dev/null +++ b/static/freebsd/man9/vfs_getopt.9 @@ -0,0 +1,243 @@ +.\" +.\" Copyright (C) 2007 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 May 19, 2024 +.Dt VFS_GETOPT 9 +.Os +.Sh NAME +.Nm vfs_getopt , +.Nm vfs_getopts , +.Nm vfs_flagopt , +.Nm vfs_scanopt , +.Nm vfs_copyopt , +.Nm vfs_filteropt , +.Nm vfs_setopt , +.Nm vfs_setopt_part , +.Nm vfs_setopts +.Nd "manipulate mount options and their values" +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.Ft int +.Fo vfs_getopt +.Fa "struct vfsoptlist *opts" "const char *name" "void **buf" "int *len" +.Fc +.Ft "char *" +.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" +.Fc +.Ft int +.Fo vfs_scanopt +.Fa "struct vfsoptlist *opts" "const char *name" "const char *fmt" ... +.Fc +.Ft int +.Fo vfs_copyopt +.Fa "struct vfsoptlist *opts" "const char *name" "void *dest" "int len" +.Fc +.Ft int +.Fo vfs_filteropt +.Fa "struct vfsoptlist *opts" "const char **legal" +.Fc +.Ft int +.Fo vfs_setopt +.Fa "struct vfsoptlist *opts" "const char *name" "void *value" "int len" +.Fc +.Ft int +.Fo vfs_setopt_part +.Fa "struct vfsoptlist *opts" "const char *name" "void *value" "int len" +.Fc +.Ft int +.Fo vfs_setopts +.Fa "struct vfsoptlist *opts" "const char *name" "const char *value" +.Fc +.Sh DESCRIPTION +The +.Fn vfs_getopt +function sets +.Fa buf +to point to the value of the named mount option, and sets +.Fa len +to the length of the value if it is not +.Dv NULL . +The +.Fa buf +argument +will point to the actual value, and does not need to be freed or released +(and probably should not be modified). +.Pp +The +.Fn vfs_getopts +function +returns the value of the specified option if it is a string (i.e., +.Dv NUL +terminated). +.Pp +The +.Fn vfs_flagopt +function determines if an option exists. +If the option does exist, and +.Fa flags +is not +.Dv NULL , +.Fa flag +is added to those already set in +.Fa flags . +If the option does not exist, and +.Fa flags +is not +.Dv NULL , +.Fa flag +is removed from those already set in +.Fa flags . +An example of typical usage is: +.Bd -literal +if (vfs_flagopt(mp->mnt_optnew, "wormlike", NULL, 0)) + vfs_flagopt(mp->mnt_optnew, "appendok", &(mp->flags), F_APPENDOK); +.Ed +.Pp +The +.Fn vfs_scanopt +function performs a +.Xr vsscanf 3 +with the option's value, using the given format, +into the specified variable arguments. +The value must be a string (i.e., +.Dv NUL +terminated). +.Pp +The +.Fn vfs_copyopt +function creates a copy of the option's value. +The +.Fa len +argument must match the length of the option's value exactly +(i.e., a larger buffer will still cause +.Fn vfs_copyout +to fail with +.Er EINVAL ) . +.Pp +The +.Fn vfs_filteropt +function ensures that no unknown options were specified. +A option is valid if its name matches one of the names in the +list of legal names. +An option may be prefixed with 'no', and still be considered valid. +.Pp +The +.Fn vfs_setopt +and +.Fn vfs_setopt_part +functions copy new data into the option's value. +In +.Fn vfs_setopt , +the +.Fa len +argument must match the length of the option's value exactly +(i.e., a larger buffer will still cause +.Fn vfs_copyout +to fail with +.Er EINVAL ) . +.Pp +The +.Fn vfs_setopts +function copies a new string into the option's value. +The string, including +.Dv NUL +byte, must be no longer than the option's length. +.Sh RETURN VALUES +The +.Fn vfs_getopt +function returns 0 if the option was found; otherwise, +.Er ENOENT +is returned. +.Pp +The +.Fn vfs_getopts +function returns the specified option if it is found, and is +.Dv NUL +terminated. +If the option was found, but is not +.Dv NUL +terminated, +.Fa error +is set to +.Er EINVAL +and +.Dv NULL +is returned. +If the option was not found, +.Fa error +is set to 0, and +.Dv NULL +is returned. +.Pp +The +.Fn vfs_flagopt +function returns 1 if the option was found, and 0 if it was not. +.Pp +The +.Fn vfs_scanopt +function returns 0 if the option was not found, or was not +.Dv NUL +terminated; otherwise, the return value of +.Xr vsscanf 3 +is returned. +If +.Xr vsscanf 3 +returns 0, it will be returned unchanged; therefore, a return value of 0 does +not always mean the option does not exist, or is not a valid string. +.Pp +The +.Fn vfs_copyopt +and +.Fn vfs_setopt +functions return 0 if the copy was successful, +.Er EINVAL +if the option was found but the lengths did not match, and +.Er ENOENT +if the option was not found. +.Pp +The +.Fn vfs_filteropt +function returns 0 if all of the options are legal; otherwise, +.Er EINVAL +is returned. +.Pp +The +.Fn vfs_setopts +function returns 0 if the copy was successful, +.Er EINVAL +if the option was found but the string was too long, and +.Er ENOENT +if the option was not found. +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Chad David Aq Mt davidc@FreeBSD.org +and +.An Ruslan Ermilov Aq Mt ru@FreeBSD.org . diff --git a/static/freebsd/man9/vfs_getvfs.9 b/static/freebsd/man9/vfs_getvfs.9 new file mode 100644 index 00000000..639eccb7 --- /dev/null +++ b/static/freebsd/man9/vfs_getvfs.9 @@ -0,0 +1,75 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 November 21, 2001 +.Dt VFS_GETVFS 9 +.Os +.Sh NAME +.Nm vfs_getvfs +.Nd "returns a mount point given its file system identifier" +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.Ft "struct mount *" +.Fn vfs_getvfs "fsid_t *fsid" +.Sh DESCRIPTION +The +.Fn vfs_getvfs +function returns the mount point structure for a file system given its file system +identifier. +The file system ID should have been allocated by calling +.Xr vfs_getnewfsid 9 ; +otherwise, it will not be found. +.Pp +A major user of +.Fn vfs_getvfs +is NFS, which uses the +.Vt fsid +as part of file handles in order to determine the +file system a given RPC is for. +If +.Fn vfs_getvfs +fails to find the mount point related to +.Fa fsid , +the file system is considered stale. +.Sh RETURN VALUES +If +.Fa fsid +is found, the mount point for the ID is returned; otherwise, +.Dv NULL +is returned. +.Sh PSEUDOCODE +.Bd -literal +if ((mp = vfs_getvfs(&fhp->fh_fsid)) == NULL) { + error = ESTALE; + goto out; +} +.Ed +.Sh SEE ALSO +.Xr vfs_getnewfsid 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/vfs_mountedfrom.9 b/static/freebsd/man9/vfs_mountedfrom.9 new file mode 100644 index 00000000..bd1b1919 --- /dev/null +++ b/static/freebsd/man9/vfs_mountedfrom.9 @@ -0,0 +1,53 @@ +.\" Copyright (C) 2008 Chad David . +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 February 25, 2008 +.Dt VFS_MOUNTEDFROM 9 +.Os +.Sh NAME +.Nm vfs_mountedfrom +.Nd "sets the mounted from name for a mount" +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.Ft void +.Fn vfs_mountedfrom "struct mount *mp" "const char *from" +.Sh DESCRIPTION +The +.Fn vfs_mountedfrom +function sets the mounted from name for a mount. +This value is used by +.Fn statfs 2 +to fill in +.Va f_mntfromname . +.Pp +In most cases +.Va from +is the device that contains the file system, but in the case of a pseudo +file system it could be a descriptive name like "devfs" or "procfs". +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/vfs_rootmountalloc.9 b/static/freebsd/man9/vfs_rootmountalloc.9 new file mode 100644 index 00000000..eee413a3 --- /dev/null +++ b/static/freebsd/man9/vfs_rootmountalloc.9 @@ -0,0 +1,64 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 November 21, 2001 +.Dt VFS_ROOTMOUNTALLOC 9 +.Os +.Sh NAME +.Nm vfs_rootmountalloc +.Nd "allocate a root" +.Vt mount +structure +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.Ft int +.Fn vfs_rootmountalloc "char *fstypename" "char *devname" "struct mount **mpp" +.Sh DESCRIPTION +.Fn vfs_rootmountalloc +allocates a +.Vt mount +structure initialized from the +.Vt vfsconf +type that matches +.Fa fstypename . +.Sh RETURN VALUES +If successful, 0 is returned and +.Fa mpp +points to the newly allocated +.Vt mount +structure. +.Er ENODEV +is returned if +.Fa fstypename +is +.Dv NULL +or invalid. +.Sh SEE ALSO +.Xr vfsconf 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/vfs_suser.9 b/static/freebsd/man9/vfs_suser.9 new file mode 100644 index 00000000..aff6410b --- /dev/null +++ b/static/freebsd/man9/vfs_suser.9 @@ -0,0 +1,70 @@ +.\" +.\" Copyright (c) 2004 Alfred Perlstein +.\" 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 ``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 2, 2004 +.Dt VFS_SUSER 9 +.Os +.Sh NAME +.Nm vfs_suser +.Nd check if credentials have superuser privileges for a mount point +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.In sys/mount.h +.Ft int +.Fn vfs_suser "struct mount *mp" "struct thread *td" +.Sh DESCRIPTION +The +.Fn vfs_suser +function checks if the credentials given include superuser powers +for the given mount point. +It will check to see if the thread +passed in has the same credentials as the user that mounted the +file system. +If so, it returns 0, otherwise it returns what +.Xr priv_check 9 +would have returned. +.Sh RETURN VALUES +The +.Fn vfs_suser +function returns 0 if the user has superuser powers and +.Er EPERM +otherwise. +This is the +.Em reverse logic +of some other implementations of +.Fn suser +in which a TRUE response indicates superuser powers. +.Sh SEE ALSO +.Xr chroot 2 , +.Xr jail 2 +.Sh HISTORY +The +.Fn vfs_suser +function was introduced in +.Fx 5.2 . +.Sh AUTHORS +This manual page was written by +.An Alfred Perlstein . diff --git a/static/freebsd/man9/vfs_timestamp.9 b/static/freebsd/man9/vfs_timestamp.9 new file mode 100644 index 00000000..19baff12 --- /dev/null +++ b/static/freebsd/man9/vfs_timestamp.9 @@ -0,0 +1,61 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 November 21, 2001 +.Dt VFS_TIMESTAMP 9 +.Os +.Sh NAME +.Nm vfs_timestamp +.Nd "generate current timestamp" +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft void +.Fn vfs_timestamp "struct timespec *tsp" +.Sh DESCRIPTION +The +.Fn vfs_timestamp +function fills in +.Fa tsp +with the current time. +.Pp +The precision is based on the value of the +.Va vfs.timestamp_precision +sysctl variable: +.Pp +.Bl -tag -width ".No \(>=3" -compact +.It 0 +seconds only; nanoseconds are zeroed. +.It 1 +seconds and nanoseconds, accurate within 1/HZ. +.It 2 +seconds and nanoseconds, truncated to microseconds. +.It \(>=3 +seconds and nanoseconds, maximum precision. +.El +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/vfs_unbusy.9 b/static/freebsd/man9/vfs_unbusy.9 new file mode 100644 index 00000000..8e3b8f1e --- /dev/null +++ b/static/freebsd/man9/vfs_unbusy.9 @@ -0,0 +1,56 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 June 14, 2010 +.Dt VFS_UNBUSY 9 +.Os +.Sh NAME +.Nm vfs_unbusy +.Nd "unbusy a mount point" +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.Ft void +.Fn vfs_unbusy "struct mount *mp" +.Sh DESCRIPTION +The +.Fn vfs_unbusy +function un-busies a mount point by decrementing +the reference count of a mount point. +The reference count is typically incremented by calling +.Xr vfs_busy 9 +prior to this call. +.Pp +Its arguments are: +.Bl -tag -width ".Fa mp" +.It Fa mp +The mount point to unbusy. +.El +.Sh SEE ALSO +.Xr vfs_busy 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/vfs_unmountall.9 b/static/freebsd/man9/vfs_unmountall.9 new file mode 100644 index 00000000..a637a6b0 --- /dev/null +++ b/static/freebsd/man9/vfs_unmountall.9 @@ -0,0 +1,45 @@ +.\" Copyright (c) 2001 Chris Costello +.\" 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 26, 2001 +.Dt VFS_UNMOUNTALL 9 +.Os +.Sh NAME +.Nm vfs_unmountall +.Nd unmount all file systems +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.Ft void +.Fn vfs_unmountall "void" +.Sh DESCRIPTION +The +.Nm +function, +run only at system shutdown, +unmounts all mounted file systems +from most recent to oldest +in order to avoid handling dependencies. +.Sh SEE ALSO +.Xr boot 9 diff --git a/static/freebsd/man9/vfsconf.9 b/static/freebsd/man9/vfsconf.9 new file mode 100644 index 00000000..ff299e3d --- /dev/null +++ b/static/freebsd/man9/vfsconf.9 @@ -0,0 +1,149 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 June 16, 2013 +.Dt VFSCONF 9 +.Os +.Sh NAME +.Nm vfsconf +.Nd "vfs configuration information" +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.Ft int +.Fn vfs_register "struct vfsconf *vfc" +.Ft int +.Fn vfs_unregister "struct vfsconf *vfc" +.Ft int +.Fn vfs_modevent "module_t mod" "int type" "void *data" +.Sh DESCRIPTION +Each file system type known to the kernel has a +.Vt vfsconf +structure that contains the +information required to create a new mount of that file systems type. +.Bd -literal +struct vfsconf { + struct vfsops *vfc_vfsops; /* file system operations vector */ + char vfc_name[MFSNAMELEN]; /* file system type name */ + int vfc_typenum; /* historic file system type number */ + int vfc_refcount; /* number mounted of this type */ + int vfc_flags; /* permanent flags */ + struct vfsconf *vfc_next; /* next in list */ +}; +.Ed +.Pp +When a new file system is mounted, +.Xr mount 2 +does a lookup of the +.Vt vfsconf +structure by its name, and if it is not already registered, +attempts to load a kernel module for it. +The file system operations for the new mount point are taken from +.Va vfc_vfsops , +and +.Va mnt_vfc +in the +.Vt mount +structure is made to point directly at the +.Vt vfsconf +structure for the +file system type. +The file system type number is taken from +.Va vfc_typenum +which was assigned in +.Fn vfs_register , +and the mount flags are taken from a mask of +.Va vfc_flags . +Each time a file system of a given type is mounted, +.Va vfc_refcount +is incremented. +.Pp +.Fn vfs_register +takes a new +.Vt vfsconf +structure and adds it to the list of existing file systems. +If the type has not already been registered, it is initialized by calling the +.Fn vfs_init +function in the file system operations vector. +.Fn vfs_register +also updates the oid's of any sysctl nodes for this file system type +to be the same as the newly assigned type number. +.Pp +.Fn vfs_unregister +unlinks +.Fa vfc +from the list of registered file system types if there are currently no mounted instances. +If the +.Fn vfs_uninit +function in the file systems initialization vector is defined, it is called. +.Pp +.Fn vfs_modevent +is registered by +.Fn VFS_SET +to handle the loading and unloading of file system kernel modules. +In the case of +.Dv MOD_LOAD , +.Fn vfs_register +is called. +In the case of +.Dv MOD_UNLOAD , +.Fn vfs_unregister +is called. +.Sh RETURN VALUES +.Fn vfs_register +returns 0 if successful; otherwise, +.Er EEXIST +is returned indicating that the file system type has already been registered. +.Pp +.Fn vfs_unregister +returns 0 if successful. +If no +.Vt vfsconf +entry can be found matching the name in +.Fa vfc , +.Er EINVAL +is returned. +If the reference count of mounted instances of the file system type is not zero, +.Er EBUSY +is returned. +If +.Fn vfs_uninit +is called, any errors it returns will be returned by +.Fn vfs_unregister . +.Pp +.Fn vfs_modevent +returns the result of the call to +.Fn vfs_register +or +.Fn vfs_unregister , +whatever the case. +.Sh SEE ALSO +.Xr mount 2 , +.Xr vfs_rootmountalloc 9 , +.Xr VFS_SET 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/vget.9 b/static/freebsd/man9/vget.9 new file mode 100644 index 00000000..8bfc5068 --- /dev/null +++ b/static/freebsd/man9/vget.9 @@ -0,0 +1,69 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 July 24, 1996 +.Dt VGET 9 +.Os +.Sh NAME +.Nm vget +.Nd get a vnode from the free list +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn vget "struct vnode *vp" "int lockflag" "struct thread *td" +.Sh DESCRIPTION +Get a vnode from the free list and increment its reference count. +.Bl -tag -width lockflag +.It Fa vp +The vnode to remove from the free list. +.It Fa lockflag +If non-zero, the vnode will also be locked. +.El +.Pp +When not in use, vnodes are kept on a free list. +The vnodes still +reference valid files but may be reused to refer to a new file at any +time. +Often, these vnodes are also held in caches in the system, such +as the name cache. +.Pp +When a vnode which is on the free list is used again, for instance if +the vnode was found in the name cache as a result of a call to +.Xr VOP_LOOKUP 9 +then the new user must call +.Fn vget +to increment the reference count and remove it from the free list. +.Sh SEE ALSO +.Xr vnode 9 , +.Xr vput 9 , +.Xr vref 9 , +.Xr vrele 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/vgone.9 b/static/freebsd/man9/vgone.9 new file mode 100644 index 00000000..319b5407 --- /dev/null +++ b/static/freebsd/man9/vgone.9 @@ -0,0 +1,61 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 8, 2019 +.Dt VGONE 9 +.Os +.Sh NAME +.Nm vgone +.Nd "prepare a vnode for reuse" +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft void +.Fn vgone "struct vnode *vp" +.Sh DESCRIPTION +The +.Fn vgone +function prepares the vnode to be destroyed. +The preparation includes the cleaning of all file system specific data and +the removal from its mount point vnode list. +.Pp +If the vnode has a +.Va v_usecount +of zero, and its +.Dv VIRF_DOOMED +flag is not set, it is moved to the head of the free list +as in most cases the vnode +is about to be reused, or its file system is being unmounted. +.Pp +The +.Fn vgone +function takes an exclusively locked vnode, and returns with the vnode +exclusively locked. +.Sh SEE ALSO +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/vhold.9 b/static/freebsd/man9/vhold.9 new file mode 100644 index 00000000..d8e9e56e --- /dev/null +++ b/static/freebsd/man9/vhold.9 @@ -0,0 +1,81 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 1, 2007 +.Dt VHOLD 9 +.Os +.Sh NAME +.Nm vhold , vdrop , vdropl +.Nd "acquire/release a hold on a vnode" +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft void +.Fn vhold "struct vnode *vp" +.Ft void +.Fn vholdl "struct vnode *vp" +.Ft void +.Fn vdrop "struct vnode *vp" +.Ft void +.Fn vdropl "struct vnode *vp" +.Sh DESCRIPTION +The +.Fn vhold +and +.Fn vholdl +functions increment the +.Va v_holdcnt +of the given vnode. +If the vnode has already been added to the free list and is still referenced, +it will be removed. +.Pp +The +.Fn vdrop +and +.Fn vdropl +functions decrement the +.Va v_holdcnt +of the vnode. +If the holdcount is less than or equal to zero prior to calling +.Fn vdrop +or +.Fn vdropl , +the system will panic. +If the vnode is no longer referenced, it will be freed. +.Pp +.Fn vhold +and +.Fn vdrop +lock the vnode interlock while +.Fn vholdl +and +.Fn vdropl +expect the interlock to already be held. +.Sh SEE ALSO +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/vinvalbuf.9 b/static/freebsd/man9/vinvalbuf.9 new file mode 100644 index 00000000..5660eb35 --- /dev/null +++ b/static/freebsd/man9/vinvalbuf.9 @@ -0,0 +1,115 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 October 20, 2008 +.Dt VINVALBUF 9 +.Os +.Sh NAME +.Nm vinvalbuf +.Nd "flushes and invalidates all buffers associated with a vnode" +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn vinvalbuf "struct vnode *vp" "int flags" "struct ucred *cred" "int slpflag" "int slptimeo" +.Sh DESCRIPTION +The +.Fn vinvalbuf +function invalidates all of the buffers associated with the given vnode. +This includes buffers on the clean list and the dirty list. +If the +.Dv V_SAVE +flag is specified then the buffers on the dirty list are synced prior to being +released. +If there is a VM Object associated with the vnode, it is removed. +.Pp +Its arguments are: +.Bl -tag -width ".Fa spltimeo" +.It Fa vp +A pointer to the vnode whose buffers will be invalidated. +.It Fa flags +The only supported flag is +.Dv V_SAVE +and it indicates that dirty buffers should be synced with the disk. +.It Fa cred +The user credentials that are used to +.Xr VOP_FSYNC 9 +buffers if +.Dv V_SAVE +is set. +.It Fa slpflag +The slp flag that will be used in the priority of any sleeps in the function. +.It Fa slptimeo +The timeout for any sleeps in the function. +.El +.Sh LOCKS +The vnode is assumed to be locked prior to the call and remains locked upon return. +.Pp +.Va Giant +must be held by prior to the call and remains locked upon return. +.Sh RETURN VALUES +A 0 value is returned on success. +.Sh PSEUDOCODE +.Bd -literal -offset indent +vn_lock(devvp, LK_EXCLUSIVE | LK_RETRY); +error = vinvalbuf(devvp, V_SAVE, cred, 0, 0); +VOP_UNLOCK(devvp, 0); +if (error) + return (error); +.Ed +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ENOSPC +The file system is full. +(With +.Dv V_SAVE ) +.It Bq Er EDQUOT +Disc quota exceeded. +(With +.Dv V_SAVE ) +.It Bq Er EWOULDBLOCK +Sleep operation timed out. +(See +.Fa slptimeo ) +.It Bq Er ERESTART +A signal needs to be delivered and the system call should be restarted. +(With +.Dv PCATCH +set in +.Fa slpflag ) +.It Bq Er EINTR +The system has been interrupted by a signal. +(With +.Dv PCATCH +set in +.Fa slpflag ) +.El +.Sh SEE ALSO +.Xr tsleep 9 , +.Xr VOP_FSYNC 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/vm_fault_prefault.9 b/static/freebsd/man9/vm_fault_prefault.9 new file mode 100644 index 00000000..a61b453b --- /dev/null +++ b/static/freebsd/man9/vm_fault_prefault.9 @@ -0,0 +1,70 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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 21, 2003 +.Dt VM_FAULT_PREFAULT 9 +.Os +.Sh NAME +.Nm vm_fault_prefault +.Nd cluster page faults into a process's address space +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft void +.Fn vm_fault_prefault "pmap_t pmap" "vm_offset_t addra" "vm_map_entry_t entry" +.Sh DESCRIPTION +The +.Fn vm_fault_prefault +function provides a means of clustering pagefaults into a process's +address space. +It operates upon the physical map +.Fa pmap . +The +.Fa entry +argument specifies the entry to be prefaulted; the +.Fa addra +argument specifies the beginning of the mapping in the process's virtual +address space. +.Pp +It is typically called by +.Fn vm_fault +after the first page fault. +It benefits the +.Xr execve 2 +system call by eliminating repetitive calls to +.Fn vm_fault , +which would otherwise be made to bring the process's executable pages +into physical memory. +.Sh IMPLEMENTATION NOTES +This is a machine-independent function which calls the machine-dependent +.Xr pmap_is_prefaultable 9 +helper function to determine if a page may be prefaulted into physical memory. +.Sh SEE ALSO +.Xr execve 2 , +.Xr pmap_is_prefaultable 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/vm_map.9 b/static/freebsd/man9/vm_map.9 new file mode 100644 index 00000000..d08d54bd --- /dev/null +++ b/static/freebsd/man9/vm_map.9 @@ -0,0 +1,332 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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 3, 2018 +.Dt VM_MAP 9 +.Os +.Sh NAME +.Nm vm_map +.Nd virtual address space portion of virtual memory subsystem +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Sh DESCRIPTION +The +.Nm +subsystem is used to manage virtual address spaces. +This section describes the main data structures used within the code. +.Pp +The +.Vt "struct vm_map" +is a generic representation of an address space. +This address space may belong to a user process or the kernel. +The kernel actually uses several maps, which are maintained as +subordinate maps, created using the +.Xr vm_map_submap 9 +function. +.Bd -literal -offset indent +struct vm_map { + struct vm_map_entry header; + union { + struct sx lock; + struct mtx system_mtx; + }; + int nentries; + vm_size_t size; + u_int timestamp; + u_int flags; + vm_map_entry_t root; + pmap_t pmap; + int busy; +}; +.Ed +.Pp +The fields of +.Vt struct vm_map +are as follows: +.Bl -tag -width ".Va needs_wakeup" +.It Va header +Head node of a circular, doubly linked list of +.Vt struct vm_map_entry +objects. +Each object defines a particular region within this map's address space. +.It Va lock +Used to serialize access to the structure. +.It Va system_mtx +A mutex which is used if the map is a system map. +.It Va nentries +A count of the members in use within the circular map entry list. +.It Va size +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 flags +Map flags, described below. +.It Va root +Root node of a binary search tree used for fast lookup of map entries. +.It Va pmap +Pointer to the underlying physical map with which this virtual map +is associated. +.It Va busy +Map busy counter, prevents forks. +.El +.Pp +Possible map flags: +.Bl -tag -width ".Dv MAP_PREFAULT_MADVISE" +.It Dv MAP_WIREFUTURE +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 +.Xr vm_map_find 9 +and +.Xr vm_map_insert 9 +to specify the copy-on-write properties of regions within the map: +.Bl -tag -width ".Dv MAP_PREFAULT_MADVISE" +.It Dv MAP_COPY_ON_WRITE +The mapping is copy-on-write. +.It Dv MAP_NOFAULT +The mapping should not generate page faults. +.It Dv MAP_PREFAULT +The mapping should be prefaulted into physical memory. +.It Dv MAP_PREFAULT_PARTIAL +The mapping should be partially prefaulted into physical memory. +.It Dv MAP_DISABLE_SYNCER +Do not periodically flush dirty pages; only flush them when absolutely +necessary. +.It Dv MAP_DISABLE_COREDUMP +Do not include the mapping in a core dump. +.It Dv MAP_PREFAULT_MADVISE +Specify that the request is from a user process calling +.Xr madvise 2 . +.It Dv MAP_ACC_CHARGED +Region is already charged to the requestor by some means. +.It Dv MAP_ACC_NO_CHARGE +Do not charge for allocated region. +.El +.Pp +The +.Vt struct vm_map_entry +is a generic representation of a region. +The region managed by each entry is associated with a +.Vt union vm_map_object , +described below. +.Bd -literal -offset indent +struct vm_map_entry { + struct vm_map_entry *prev; + struct vm_map_entry *next; + struct vm_map_entry *left; + struct vm_map_entry *right; + vm_offset_t start; + vm_offset_t end; + vm_offset_t avail_ssize; + vm_size_t adj_free; + vm_size_t max_free; + union vm_map_object object; + vm_ooffset_t offset; + vm_eflags_t eflags; + /* Only in task maps: */ + vm_prot_t protection; + vm_prot_t max_protection; + vm_inherit_t inheritance; + int wired_count; + vm_pindex_t lastr; +}; +.Ed +.Pp +The fields of +.Vt struct vm_map_entry +are as follows: +.Bl -tag -width ".Va avail_ssize" +.It Va prev +Pointer to the previous node in a doubly-linked, circular list. +.It Va next +Pointer to the next node in a doubly-linked, circular list. +.It Va left +Pointer to the left node in a binary search tree. +.It Va right +Pointer to the right node in a binary search tree. +.It Va start +Lower address bound of this entry's region. +.It Va end +Upper address bound of this entry's region. +.It Va avail_ssize +If the entry is for a process stack, specifies how much the entry can grow. +.It Va adj_free +The amount of free, unmapped address space adjacent to and immediately +following this map entry. +.It Va max_free +The maximum amount of contiguous free space in this map entry's subtree. +.It Va object +Pointer to the +.Vt struct vm_map_object +with which this entry is associated. +.It Va offset +Offset within the +.Va object +which is mapped from +.Va start +onwards. +.It Va eflags +Flags applied to this entry, described below. +.El +.Pp +The following five members are only valid for entries forming part of +a user process's address space: +.Bl -tag -width ".Va max_protection" +.It Va protection +Memory protection bits applied to this region. +.It Va max_protection +Mask for the memory protection bits which may be actually be applied to +this region. +.It Va inheritance +Contains flags which specify how this entry should be treated +during fork processing. +.It Va wired_count +Count of how many times this entry has been wired into physical memory. +.It Va lastr +Contains the address of the last read which caused a page fault. +.El +.Pp +The following flags may be applied to each entry, by specifying them +as a mask within the +.Va eflags +member: +.Bl -tag -width ".Dv MAP_ENTRY_BEHAV_SEQUENTIAL" +.It Dv MAP_ENTRY_NOSYNC +The system should not flush the data associated with this map +periodically, but only when it needs to. +.It Dv MAP_ENTRY_IS_SUB_MAP +If set, then the +.Va object +member specifies a subordinate map. +.It Dv MAP_ENTRY_COW +Indicate that this is a copy-on-write region. +.It Dv MAP_ENTRY_NEEDS_COPY +Indicate that a copy-on-write region needs to be copied. +.It Dv MAP_ENTRY_NOFAULT +Specifies that accesses within this region should never cause a page fault. +If a page fault occurs within this region, the system will panic. +.It Dv MAP_ENTRY_USER_WIRED +Indicate that this region was wired on behalf of a user process. +.It Dv MAP_ENTRY_BEHAV_NORMAL +The system should use the default paging behaviour for this region. +.It Dv MAP_ENTRY_BEHAV_SEQUENTIAL +The system should depress the priority of pages immediately preceding +each page within this region when faulted in. +.It Dv MAP_ENTRY_BEHAV_RANDOM +Is a hint that pages within this region will be accessed randomly, +and that prefetching is likely not advantageous. +.It Dv MAP_ENTRY_IN_TRANSITION +Indicate that wiring or unwiring of an entry is in progress, and that +other kernel threads should not attempt to modify fields in the structure. +.It Dv MAP_ENTRY_NEEDS_WAKEUP +Indicate that there are kernel threads waiting for this region to become +available. +.It Dv MAP_ENTRY_NOCOREDUMP +The region should not be included in a core dump. +.El +.Pp +The +.Va inheritance +member has type +.Vt vm_inherit_t . +This governs the inheritance behaviour for a map entry during fork processing. +The following values are defined for +.Vt vm_inherit_t : +.Bl -tag -width ".Dv VM_INHERIT_DEFAULT" +.It Dv VM_INHERIT_SHARE +The object associated with the entry should be cloned and shared +with the new map. +A new +.Vt struct vm_object +will be created if necessary. +.It Dv VM_INHERIT_COPY +The object associated with the entry should be copied to the new map. +.It Dv VM_INHERIT_NONE +The entry should not be copied to the new map. +.It Dv VM_INHERIT_DEFAULT +Specifies the default behaviour, +.Dv VM_INHERIT_COPY . +.El +.Pp +The +.Vt union vm_map_object +is used to specify the structure which a +.Vt struct vm_map_entry +is associated with. +.Pp +The fields of +.Vt union vm_map_object +are as follows: +.Bd -literal -offset indent +union vm_map_object { + struct vm_object *vm_object; + struct vm_map *sub_map; +}; +.Ed +.Pp +Normally, the +.Va sub_map +member is only used by system maps to indicate that a memory range +is managed by a subordinate system map. +Within a user process map, each +.Vt struct vm_map_entry +is backed by a +.Vt struct vm_object . +.Sh SEE ALSO +.Xr pmap 9 , +.Xr vm_map_check_protection 9 , +.Xr vm_map_delete 9 , +.Xr vm_map_entry_resize_free 9 , +.Xr vm_map_find 9 , +.Xr vm_map_findspace 9 , +.Xr vm_map_inherit 9 , +.Xr vm_map_init 9 , +.Xr vm_map_insert 9 , +.Xr vm_map_lock 9 , +.Xr vm_map_lookup 9 , +.Xr vm_map_madvise 9 , +.Xr vm_map_max 9 , +.Xr vm_map_min 9 , +.Xr vm_map_pmap 9 , +.Xr vm_map_protect 9 , +.Xr vm_map_remove 9 , +.Xr vm_map_stack 9 , +.Xr vm_map_submap 9 , +.Xr vm_map_sync 9 , +.Xr vm_map_wire 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/vm_map_check_protection.9 b/static/freebsd/man9/vm_map_check_protection.9 new file mode 100644 index 00000000..2e1bdc8d --- /dev/null +++ b/static/freebsd/man9/vm_map_check_protection.9 @@ -0,0 +1,68 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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_CHECK_PROTECTION 9 +.Os +.Sh NAME +.Nm vm_map_check_protection +.Nd check memory protection for a vm_map +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft boolean_t +.Fo vm_map_check_protection +.Fa "vm_map_t map" "vm_offset_t start" "vm_offset_t end" "vm_prot_t protection" +.Fc +.Sh DESCRIPTION +The +.Fn vm_map_check_protection +function asserts that the target +.Fa map +allows the specified privilege +.Fa protection +over the entire address range from +.Fa start +to +.Fa end . +The region MUST be contiguous; no holes are allowed. +.Sh IMPLEMENTATION NOTES +This code does not and SHOULD not check whether the contents of +the region are accessible. +For example, a small file may be mapped into an address space which +is significantly larger in size. +.Sh RETURN VALUES +The +.Fn vm_map_check_protection +function returns TRUE if the privilege is allowed; if it is not allowed, +or if any other error occurred, the value FALSE is returned. +.Sh SEE ALSO +.Xr munmap 2 , +.Xr vm_map 9 , +.Xr vm_map_protect 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/vm_map_delete.9 b/static/freebsd/man9/vm_map_delete.9 new file mode 100644 index 00000000..c8e1cd2d --- /dev/null +++ b/static/freebsd/man9/vm_map_delete.9 @@ -0,0 +1,66 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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_DELETE 9 +.Os +.Sh NAME +.Nm vm_map_delete +.Nd deallocate an address range from a map +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft int +.Fn vm_map_delete "vm_map_t map" "vm_offset_t start" "vm_offset_t end" +.Sh DESCRIPTION +The +.Fn vm_map_delete +function deallocates the address range bounded by +.Fa start +and +.Fa end +from the +.Fa map . +.Sh IMPLEMENTATION NOTES +This function is for +.Fx +VM internal use only. +The +.Xr vm_map_remove 9 +function should be called by +.Fx +VM consumers instead. +.Sh RETURN VALUES +The +.Fn vm_map_delete +function always returns +.Dv KERN_SUCCESS . +.Sh SEE ALSO +.Xr vm_map 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/static/freebsd/man9/vm_map_entry_resize_free.9 b/static/freebsd/man9/vm_map_entry_resize_free.9 new file mode 100644 index 00000000..07f80db5 --- /dev/null +++ b/static/freebsd/man9/vm_map_entry_resize_free.9 @@ -0,0 +1,241 @@ +.\" +.\" Copyright (c) 2004 Mark W. Krentel +.\" 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 August 17, 2004 +.Dt VM_MAP_ENTRY_RESIZE_FREE 9 +.Os +.Sh NAME +.Nm vm_map_entry_resize_free +.Nd "vm map free space algorithm" +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft void +.Fn vm_map_entry_resize_free "vm_map_t map" "vm_map_entry_t entry" +.Sh DESCRIPTION +This manual page describes the +.Vt vm_map_entry +fields used in the VM map free space algorithm, how to maintain +consistency of these variables, and the +.Fn vm_map_entry_resize_free +function. +.Pp +VM map entries are organized as both a doubly-linked list +.Va ( prev +and +.Va next +pointers) and as a binary search tree +.Va ( left +and +.Va right +pointers). +The search tree is organized as a Sleator and Tarjan splay tree, +also known as a +.Dq "self-adjusting tree" . +.Bd -literal -offset indent +struct vm_map_entry { + struct vm_map_entry *prev; + struct vm_map_entry *next; + struct vm_map_entry *left; + struct vm_map_entry *right; + vm_offset_t start; + vm_offset_t end; + vm_offset_t avail_ssize; + vm_size_t adj_free; + vm_size_t max_free; + ... +}; +.Ed +.Pp +The free space algorithm adds two fields to +.Vt "struct vm_map_entry" : +.Va adj_free +and +.Va max_free . +The +.Va adj_free +field +is the amount of free address space adjacent to and immediately +following (higher address) the map entry. +This field is unused in the map header. +Note that +.Va adj_free +depends on the linked list, not the splay tree and that +.Va adj_free +can be computed as: +.Bd -literal -offset indent +entry->adj_free = (entry->next == &map->header ? + map->max_offset : entry->next->start) - entry->end; +.Ed +.Pp +The +.Va max_free +field +is the maximum amount of contiguous free space in the entry's subtree. +Note that +.Va max_free +depends on the splay tree, not the linked list and that +.Va max_free +is computed by taking the maximum of its own +.Va adj_free +and the +.Va max_free +of its left and right subtrees. +Again, +.Va max_free +is unused in the map header. +.Pp +These fields allow for an +.Fn O "log n" +implementation of +.Fn vm_map_findspace . +Using +.Va max_free , +we can immediately test for a sufficiently large free region +in an entire subtree. +This makes it possible to find a first-fit free region of a given size +in one pass down the tree, so +.Fn O "log n" +amortized using splay trees. +.Pp +When a free region changes size, we must update +.Va adj_free +and +.Va max_free +in the preceding map entry and propagate +.Va max_free +up the tree. +This is handled in +.Fn vm_map_entry_link +and +.Fn vm_map_entry_unlink +for the cases of inserting and deleting an entry. +Note that +.Fn vm_map_entry_link +updates both the new entry and the previous entry, and that +.Fn vm_map_entry_unlink +updates the previous entry. +Also note that +.Va max_free +is not actually propagated up the tree. +Instead, that entry is first splayed to the root and +then the change is made there. +This is a common technique in splay trees and is also +how map entries are linked and unlinked into the tree. +.Pp +The +.Fn vm_map_entry_resize_free +function updates the free space variables in the given +.Fa entry +and propagates those values up the tree. +This function should be called whenever a map entry is resized +in-place, that is, by modifying its +.Va start +or +.Va end +values. +Note that if you change +.Va end , +then you should resize that entry, but if you change +.Va start , +then you should resize the previous entry. +The map must be locked before calling this function, +and again, propagating +.Va max_free +is performed by splaying that entry to the root. +.Sh EXAMPLES +Consider adding a map entry with +.Fn vm_map_insert . +.Bd -literal -offset indent +ret = vm_map_insert(map, object, offset, start, end, prot, + max_prot, cow); +.Ed +.Pp +In this case, no further action is required to maintain +consistency of the free space variables. +The +.Fn vm_map_insert +function calls +.Fn vm_map_entry_link +which updates both the new entry and the previous entry. +The same would be true for +.Fn vm_map_delete +and for calling +.Fn vm_map_entry_link +or +.Fn vm_map_entry_unlink +directly. +.Pp +Now consider resizing an entry in-place without a call to +.Fn vm_map_entry_link +or +.Fn vm_map_entry_unlink . +.Bd -literal -offset indent +entry->start = new_start; +if (entry->prev != &map->header) + vm_map_entry_resize_free(map, entry->prev); +.Ed +.Pp +In this case, resetting +.Va start +changes the amount of free space following the previous entry, +so we use +.Fn vm_map_entry_resize_free +to update the previous entry. +.Pp +Finally, suppose we change an entry's +.Va end +address. +.Bd -literal -offset indent +entry->end = new_end; +vm_map_entry_resize_free(map, entry); +.Ed +.Pp +Here, we call +.Fn vm_map_entry_resize_free +on the entry itself. +.Sh SEE ALSO +.Xr vm_map 9 , +.Xr vm_map_findspace 9 +.Rs +.%A Daniel D. Sleator +.%A Robert E. Tarjan +.%T Self-Adjusting Binary Search Trees +.%J JACM +.%V vol. 32(3) +.%P pp. 652-686 +.%D July 1985 +.Re +.Sh HISTORY +Splay trees were added to the VM map in +.Fx 5.0 , +and the +.Fn O "log n" +tree-based free space algorithm was added in +.Fx 5.3 . +.Sh AUTHORS +The tree-based free space algorithm and this manual page were written by +.An Mark W. Krentel Aq Mt krentel@dreamscape.com . diff --git a/static/freebsd/man9/vm_map_find.9 b/static/freebsd/man9/vm_map_find.9 new file mode 100644 index 00000000..0a961dfa --- /dev/null +++ b/static/freebsd/man9/vm_map_find.9 @@ -0,0 +1,159 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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 September 12, 2013 +.Dt VM_MAP_FIND 9 +.Os +.Sh NAME +.Nm vm_map_find +.Nd find a free region within a map, and optionally map a vm_object +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft int +.Fo vm_map_find +.Fa "vm_map_t map" "vm_object_t object" "vm_ooffset_t offset" +.Fa "vm_offset_t *addr" "vm_size_t length" "vm_offset_t max_addr" +.Fa "int find_space" "vm_prot_t prot" "vm_prot_t max" "int cow" +.Fc +.Sh DESCRIPTION +The +.Fn vm_map_find +function attempts to find a free region in the target +.Fa map , +with the given +.Fa length. +If a free region is found, +.Fn vm_map_find +creates a mapping of +.Fa object +via a call to +.Xr vm_map_insert 9 . +.Pp +The arguments +.Fa offset , +.Fa prot , +.Fa max , +and +.Fa cow +are passed unchanged to +.Xr vm_map_insert 9 +when creating the mapping, if and only if a free region is found. +.Pp +If +.Fa object +is +.Pf non- Dv NULL , +the reference count on the object must be incremented +by the caller before calling this function to account for the new entry. +.Pp +If +.Fa max_addr +is non-zero, +it specifies an upper bound on the mapping. +The mapping will only succeed if a free region can be found that resides +entirely below +.Fa max_addr . +.Pp +The +.Fa find_space +argument specifies the strategy to use when searching for a free region of +the requested length. +For all values other than +.Dv VMFS_NO_SPACE , +.Xr vm_map_findspace 9 +is called to locate a free region of the requested length with a starting +address at or above +.Fa *addr . +The following strategies are supported: +.Bl -tag -width "Dv VMFS_ALIGNED_SPACE Ns" +.It Dv VMFS_NO_SPACE +The mapping will only succeed if there is a free region of the requested +length at the given address +.Fa *addr . +.It Dv VMFS_ANY_SPACE +The mapping will succeed as long as there is a free region. +.It Dv VMFS_SUPER_SPACE +The mapping will succeed as long as there is a free region that begins on +a superpage boundary. +If +.Fa object +is +.Pf non- Dv NULL +and is already backed by superpages, +then the mapping will require a free region that aligns relative to the +existing superpages rather than one beginning on a superpage boundary. +.It Dv VMFS_OPTIMAL_SPACE +The mapping will succeed as long as there is a free region. +However, if +.Fa object +is +.Pf non- Dv NULL +and is already backed by superpages, +this strategy will attempt to find a free region aligned relative to +the existing superpages. +.It Dv VMFS_ALIGNED_SPACE Ns Pq Fa n +The mapping will succeed as long as there is a free region that aligns on +a +.Pf 2^ Fa n +boundary. +.El +.Sh IMPLEMENTATION NOTES +This function acquires a lock on +.Fa map +by calling +.Xr vm_map_lock 9 , +and holds it until the function returns. +.Pp +The search for a free region is defined to be first-fit, from the address +.Fa addr +onwards. +.Sh RETURN VALUES +The +.Fn vm_map_find +function returns +.Dv KERN_SUCCESS +if the mapping was successfully created. +If space could not be found or +.Fa find_space +was +.Dv VMFS_NO_SPACE +and the given address, +.Fa addr , +was already mapped, +.Dv KERN_NO_SPACE +will be returned. +If the discovered range turned out to be bogus, +.Dv KERN_INVALID_ADDRESS +will be returned. +.Sh SEE ALSO +.Xr vm_map 9 , +.Xr vm_map_findspace 9 , +.Xr vm_map_insert 9 , +.Xr vm_map_lock 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/vm_map_findspace.9 b/static/freebsd/man9/vm_map_findspace.9 new file mode 100644 index 00000000..5e5ebcba --- /dev/null +++ b/static/freebsd/man9/vm_map_findspace.9 @@ -0,0 +1,76 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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_FINDSPACE 9 +.Os +.Sh NAME +.Nm vm_map_findspace +.Nd find a free region within a map +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft int +.Fo vm_map_findspace +.Fa "vm_map_t map" "vm_offset_t start" "vm_size_t length" "vm_offset_t *addr" +.Fc +.Sh DESCRIPTION +The +.Fn vm_map_findspace +function attempts to find a region with sufficient space in the +.Fa map +for an object of size +.Fa length +at the address +.Fa addr . +.Sh IMPLEMENTATION NOTES +It is the caller's responsibility to obtain a lock on the +.Fa map +using +.Xr vm_map_lock 9 +before calling this function. +.Pp +This routine may call +.Xr pmap_growkernel 9 +to grow the kernel's address space, if and only if the mapping is being +made within the kernel address space, and if insufficient space remains +in the +.Va kernel_map . +.Sh RETURN VALUES +The +.Fn vm_map_findspace +function returns the value 0 if successful, and +.Fa *addr +will contain the first virtual address in the found region; +otherwise, the value 1 is returned. +.Sh SEE ALSO +.Xr pmap_growkernel 9 , +.Xr vm_map 9 , +.Xr vm_map_entry_resize_free 9 , +.Xr vm_map_lock 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/vm_map_inherit.9 b/static/freebsd/man9/vm_map_inherit.9 new file mode 100644 index 00000000..511403d8 --- /dev/null +++ b/static/freebsd/man9/vm_map_inherit.9 @@ -0,0 +1,83 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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_INHERIT 9 +.Os +.Sh NAME +.Nm vm_map_inherit +.Nd set fork inheritance flags for a range within a map +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft int +.Fo vm_map_inherit +.Fa "vm_map_t map" "vm_offset_t start" "vm_offset_t end" +.Fa "vm_inherit_t new_inheritance" +.Fc +.Sh DESCRIPTION +The +.Fn vm_map_inherit +function sets the inheritance flags for the range +.Fa start +to +.Fa end +within the target +.Fa map +to the value +.Fa new_inheritance . +.Pp +The +.Fa new_inheritance +flag must have one of the values +.Dv VM_INHERIT_NONE , +.Dv VM_INHERIT_COPY , +or +.Dv VM_INHERIT_SHARE . +This affects how the map will be shared with child maps when the +associated process forks. +.Sh IMPLEMENTATION NOTES +The +.Fn vm_map_inherit +function obtains a lock on the +.Fa map +using +.Xr vm_map_lock 9 +for the duration of the function. +.Sh RETURN VALUES +The +.Fn vm_map_inherit +function returns +.Dv KERN_SUCCESS +if the inheritance flags could be set. +Otherwise, if the provided flags were invalid, +.Dv KERN_INVALID_ARGUMENT +will be returned. +.Sh SEE ALSO +.Xr fork 2 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/vm_map_init.9 b/static/freebsd/man9/vm_map_init.9 new file mode 100644 index 00000000..f2e01bed --- /dev/null +++ b/static/freebsd/man9/vm_map_init.9 @@ -0,0 +1,57 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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_INIT 9 +.Os +.Sh NAME +.Nm vm_map_init +.Nd initialize a vm_map structure for process zero +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft void +.Fn vm_map_init "vm_map_t map" "vm_offset_t min" "vm_offset_t max" +.Sh DESCRIPTION +The +.Fn vm_map_init +function initializes the system map +.Fa map +by setting its upper and lower address bounds to +.Fa max +and +.Fa min +respectively. +.Pp +It also initializes the system map mutex. +.Sh IMPLEMENTATION NOTES +This routine is for internal use only. +It is called during early system initialization. +.Sh SEE ALSO +.Xr vm_map 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/vm_map_insert.9 b/static/freebsd/man9/vm_map_insert.9 new file mode 100644 index 00000000..2cd33e45 --- /dev/null +++ b/static/freebsd/man9/vm_map_insert.9 @@ -0,0 +1,91 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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 January 11, 2013 +.Dt VM_MAP_INSERT 9 +.Os +.Sh NAME +.Nm vm_map_insert +.Nd insert an object into a map +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft int +.Fo vm_map_insert +.Fa "vm_map_t map" "vm_object_t object" "vm_ooffset_t offset" +.Fa "vm_offset_t start" "vm_offset_t end" "vm_prot_t prot" +.Fa "vm_prot_t max" "int cow" +.Fc +.Sh DESCRIPTION +The +.Fn vm_map_insert +function inserts a mapping for the entire vm_object +.Fa object +into the target map +.Fa map . +.Pp +The +.Fa offset +argument specifies the offset into the +.Fa object +at which to begin mapping. +The object's size should match that of the specified address range. +.Pp +The +.Fa start +and +.Fa end +arguments specify the bounds of the mapped object's window in the +address space of +.Fa map . +.Pp +The +.Fa cow +argument specifies the flags which should be propagated to the new entry, +for example, to indicate that this is a copy-on-write mapping. +.Sh IMPLEMENTATION NOTES +This function implicitly creates a new +.Vt vm_map_entry +by calling the internal function +.Fn vm_map_entry_create . +.Sh RETURN VALUES +The +.Fn vm_map_insert +function returns +.Dv KERN_SUCCESS +if the mapping could be made successfully. +.Pp +Otherwise, +.Dv KERN_INVALID_ADDRESS +will be returned if the start of the range could not be found, or +.Dv KERN_NO_SPACE +if the range was found to be part of an existing entry or if it +overlaps the end of the map. +.Sh SEE ALSO +.Xr vm_map 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/vm_map_lock.9 b/static/freebsd/man9/vm_map_lock.9 new file mode 100644 index 00000000..5b0afa1b --- /dev/null +++ b/static/freebsd/man9/vm_map_lock.9 @@ -0,0 +1,111 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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_LOCK 9 +.Os +.Sh NAME +.Nm vm_map_lock , +.Nm vm_map_unlock , +.Nm vm_map_lock_read , +.Nm vm_map_unlock_read , +.Nm vm_map_trylock , +.Nm vm_map_trylock_read , +.Nm vm_map_lock_upgrade , +.Nm vm_map_lock_downgrade +.Nd vm_map locking macros +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft void +.Fn vm_map_lock "vm_map_t map" +.Ft void +.Fn vm_map_unlock "vm_map_t map" +.Ft void +.Fn vm_map_lock_read "vm_map_t map" +.Ft void +.Fn vm_map_unlock_read "vm_map_t map" +.Ft int +.Fn vm_map_trylock "vm_map_t map" +.Ft int +.Fn vm_map_trylock_read "vm_map_t map" +.Ft int +.Fn vm_map_lock_upgrade "vm_map_t map" +.Ft int +.Fn vm_map_lock_downgrade "vm_map_t map" +.Sh DESCRIPTION +The +.Fn vm_map_lock +macro obtains an exclusive lock on +.Fa map . +.Pp +The +.Fn vm_map_unlock +macro releases an exclusive lock on +.Fa map . +.Pp +The +.Fn vm_map_lock_read +macro obtains a read-lock on +.Fa map . +.Pp +The +.Fn vm_map_unlock_read +macro releases a read-lock on +.Fa map . +.Pp +The +.Fn vm_map_trylock +macro attempts to obtain an exclusive lock on +.Fa map . +It returns FALSE if the lock cannot be immediately acquired; +otherwise return TRUE with the lock acquired. +.Pp +The +.Fn vm_map_trylock_read +macro attempts to obtain a read-lock on +.Fa map . +It returns FALSE if the lock cannot be immediately acquired; +otherwise return TRUE with the lock acquired. +.Pp +The +.Fn vm_map_lock_upgrade +macro attempts to atomically upgrade a read-lock on +.Fa map +to an exclusive lock. +.Pp +The +.Fn vm_map_lock_downgrade +macro attempts to downgrade an exclusive lock on +.Fa map +to a read-lock. +.Sh IMPLEMENTATION NOTES +Currently, all of the locking macros implement their locks as sleep locks. +.Sh SEE ALSO +.Xr vm_map 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/vm_map_lookup.9 b/static/freebsd/man9/vm_map_lookup.9 new file mode 100644 index 00000000..fe19d09e --- /dev/null +++ b/static/freebsd/man9/vm_map_lookup.9 @@ -0,0 +1,86 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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_LOOKUP 9 +.Os +.Sh NAME +.Nm vm_map_lookup , +.Nm vm_map_lookup_done +.Nd lookup the vm_object backing a given virtual region +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft int +.Fo vm_map_lookup +.Fa "vm_map_t *var_map" "vm_offset_t vaddr" "vm_prot_t fault_type" +.Fa "vm_map_entry_t *out_entry" "vm_object_t *object" "vm_pindex_t *pindex" +.Fa "vm_prot_t *out_prot" "boolean_t *wired" +.Fc +.Ft void +.Fn vm_map_lookup_done "vm_map_t map" "vm_map_entry_t entry" +.Sh DESCRIPTION +The +.Fn vm_map_lookup +function attempts to find the +.Vt vm_object , +page index and protection, for the given virtual address +.Fa vaddr , +in the map +.Fa var_map , +assuming a page fault of the type +.Fa fault_type +had occurred. +.Pp +Return values are guaranteed until +.Fn vm_map_lookup_done +is called to release the lock. +.Sh IMPLEMENTATION NOTES +The function +.Fn vm_map_lookup +acquires a read-lock on the map +.Fa *var_map , +but does not release it. +The caller should invoke +.Fn vm_map_lookup_done +in order to release this lock. +.Sh RETURN VALUES +The +.Fn vm_map_lookup +function returns +.Dv KERN_SUCCESS , +and sets the +.Fa *object , +.Fa *pindex , +.Fa *out_prot , +and +.Fa *out_entry +arguments appropriately for the hypothetical page fault. +.Sh SEE ALSO +.Xr vm_map 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/vm_map_madvise.9 b/static/freebsd/man9/vm_map_madvise.9 new file mode 100644 index 00000000..9163ca9d --- /dev/null +++ b/static/freebsd/man9/vm_map_madvise.9 @@ -0,0 +1,75 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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_MADVISE 9 +.Os +.Sh NAME +.Nm vm_map_madvise +.Nd apply advice about use of memory to map entries +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft int +.Fo vm_map_madvise +.Fa "vm_map_t map" "vm_offset_t start" "vm_offset_t end" "int behav" +.Fc +.Sh DESCRIPTION +The +.Fn vm_map_madvise +function applies the flags +.Fa behav +to the entries within +.Fa map +between +.Fa start +and +.Fa end . +.Pp +Advisories are classified as either those affecting the +.Vt vm_map_entry +structure, or those affecting the underlying objects. +.Pp +The +.Fn vm_map_madvise +function is used by the +.Xr madvise 2 +system call. +.Sh RETURN VALUES +The +.Fn vm_map_madvise +function returns 0 if successful. +If the +.Fa behav +argument was not recognised, +.Dv KERN_INVALID_ARGUMENT +is returned. +.Sh SEE ALSO +.Xr madvise 2 , +.Xr vm_map 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/vm_map_max.9 b/static/freebsd/man9/vm_map_max.9 new file mode 100644 index 00000000..0f531785 --- /dev/null +++ b/static/freebsd/man9/vm_map_max.9 @@ -0,0 +1,64 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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_MAX 9 +.Os +.Sh NAME +.Nm vm_map_max , +.Nm vm_map_min , +.Nm vm_map_pmap +.Nd return map properties +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft vm_offset_t +.Fn vm_map_max "vm_map_t map" +.Ft vm_offset_t +.Fn vm_map_min "vm_map_t map" +.Ft pmap_t +.Fn vm_map_pmap "vm_map_t map" +.Sh DESCRIPTION +The function +.Fn vm_map_max +returns the upper address bound of the map +.Fa map . +.Pp +The function +.Fn vm_map_min +returns the lower address bound of the map +.Fa map . +.Pp +The function +.Fn vm_map_pmap +returns a pointer to the physical map associated with the virtual map +.Fa map . +.Sh SEE ALSO +.Xr pmap 9 , +.Xr vm_map 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/vm_map_protect.9 b/static/freebsd/man9/vm_map_protect.9 new file mode 100644 index 00000000..5ece889a --- /dev/null +++ b/static/freebsd/man9/vm_map_protect.9 @@ -0,0 +1,137 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" Copyright (c) 2021 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" Parts of this documentation were written by +.\" Konstantin Belousov under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 23, 2021 +.Dt VM_MAP_PROTECT 9 +.Os +.Sh NAME +.Nm vm_map_protect +.Nd apply protection bits to a virtual memory region +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft int +.Fo vm_map_protect +.Fa "vm_map_t map" +.Fa "vm_offset_t start" +.Fa "vm_offset_t end" +.Fa "vm_prot_t new_prot" +.Fa "vm_prot_t new_maxprot" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +The +.Fn vm_map_protect +function sets the protection bits and maximum protection bits of the address +region bounded by +.Fa start +and +.Fa end +within the map +.Fa map . +.Pp +If the +.Fa flags +argument has the +.Dv VM_MAP_PROTECT_SET_PROT +bit set, then the effective protection is set to +.Fa new_prot . +.Pp +If the +.Fa flags +argument has the +.Dv VM_MAP_PROTECT_SET_MAXPROT +bit set, then the maximum protection is set to +.Fa new_maxprot . +Protection bits not included into +.Fa new_maxprot +will be cleared from existing entries. +.Pp +The values specified by +.Fa new_prot +and +.Fa new_maxprot +are not allowed to include any protection bits that are not set in existing +.Va max_protection +on every entry within the range. +The operation will fail if this condition is violated. +For instance, this prevents upgrading a shared mapping of a read-only file +from read-only to read-write. +.Pp +The specified range must not contain sub-maps. +.Sh IMPLEMENTATION NOTES +The function acquires a lock on the +.Fa map +for the duration, by calling +.Xr vm_map_lock 9 . +Also, any in-progress wiring operation on the map affecting the specified +range will cause +.Nm +to sleep, waiting for completion. +.Sh RETURN VALUES +.Bl -tag -width "Dv KERN_PROTECTION_FAILURE" +.It Dv KERN_SUCCESS +The specified protection bits were set successfully. +.It Dv KERN_INVALID_ARGUMENT +A sub-map entry was encountered in the range, +.It Dv KERN_PROTECTION_FAILURE +The value of +.Fa new_prot +or +.Fa new_maxprot +exceed +.Va max_protection +for an entry within the range. +.It Dv KERN_PROTECTION_FAILURE +The map does not allow simultaneous setting of write and execute permissions, +but +.Fa new_prot +has both +.Dv VM_PROT_WRITE +and +.Dv VM_PROT_EXECUTE +set. +.It Dv KERN_RESOURCE_SHORTAGE +A copy-on-write mapping is transitioned from read-only to +read-write, and not enough swap space is available to back the +copied pages. +.It Dv KERN_OUT_OF_BOUNDS +Both new protection and new maximum protection updates were requested, +but the specified +.Fa new_prot +is not a subset of +.Fa new_maxprot . +.El +.Sh SEE ALSO +.Xr vm_map 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/vm_map_remove.9 b/static/freebsd/man9/vm_map_remove.9 new file mode 100644 index 00000000..c72abe74 --- /dev/null +++ b/static/freebsd/man9/vm_map_remove.9 @@ -0,0 +1,67 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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_REMOVE 9 +.Os +.Sh NAME +.Nm vm_map_remove +.Nd remove a virtual address range from a map +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft int +.Fn vm_map_remove "vm_map_t map" "vm_offset_t start" "vm_offset_t end" +.Sh DESCRIPTION +The +.Fn vm_map_remove +function removes the given address range bounded by +.Fa start +and +.Fa end +from the target +.Fa map . +.Sh IMPLEMENTATION NOTES +This is the exported form of +.Xr vm_map_delete 9 +which may be called by consumers of the VM subsystem. +.Pp +The function calls +.Xr vm_map_lock 9 +to hold a lock on +.Fa map +for the duration of the function call. +.Sh RETURN VALUES +The +.Fn vm_map_remove +always returns +.Dv KERN_SUCCESS . +.Sh SEE ALSO +.Xr vm_map 9 , +.Xr vm_map_delete 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/vm_map_stack.9 b/static/freebsd/man9/vm_map_stack.9 new file mode 100644 index 00000000..533a9a49 --- /dev/null +++ b/static/freebsd/man9/vm_map_stack.9 @@ -0,0 +1,130 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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 January 11, 2013 +.Dt VM_MAP_STACK 9 +.Os +.Sh NAME +.Nm vm_map_stack , +.Nm vm_map_growstack +.Nd manage process stacks +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft int +.Fo vm_map_stack +.Fa "vm_map_t map" "vm_offset_t addrbos" "vm_size_t max_ssize" "vm_prot_t prot" +.Fa "vm_prot_t max" "int cow" +.Fc +.Ft int +.Fn vm_map_growstack "struct proc *p" "vm_offset_t addr" +.Sh DESCRIPTION +The +.Fn vm_map_stack +function maps a process stack for a new process image. +The stack is mapped +.Fa addrbos +in +.Fa map , +with a maximum size of +.Fa max_ssize . +Copy-on-write flags passed in +.Fa cow +are also applied to the new mapping. +Protection bits are supplied by +.Fa prot +and +.Fa max . +.Pp +It is typically called by +.Xr execve 2 . +.Pp +The +.Fn vm_map_growstack +function is responsible for growing a stack for the process +.Fa p +to the desired address +.Fa addr , +similar to the legacy +.Xr sbrk 2 +call. +.Sh IMPLEMENTATION NOTES +The +.Fn vm_map_stack +function calls +.Xr vm_map_insert 9 +to create its mappings. +.Pp +The +.Fn vm_map_stack +and +.Fn vm_map_growstack +functions acquire the process lock on +.Fa p +for the duration of the call. +.Sh RETURN VALUES +The +.Fn vm_map_stack +function returns +.Dv KERN_SUCCESS +if the mapping was allocated successfully. +.Pp +Otherwise, +if mapping the stack would exceed the process's VMEM resource limit, +or if the specified bottom-of-stack address is out of range for the map, +or if there is already a mapping at the address which would result, +or if +.Fa max_ssize +could not be accommodated within the current mapping, +.Dv KERN_NO_SPACE +is returned. +.Pp +Other possible return values for this function are documented in +.Xr vm_map_insert 9 . +.Pp +The +.Fn vm_map_growstack +function returns +.Dv KERN_SUCCESS +if +.Fa addr +is already mapped, or if the stack was grown successfully. +.Pp +It also returns +.Dv KERN_SUCCESS +if +.Fa addr +is outside the stack range; this is done in order to preserve +compatibility with the deprecated +.Fn grow +function previously located in the file +.Pa vm_machdep.c . +.Sh SEE ALSO +.Xr vm_map 9 , +.Xr vm_map_insert 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/vm_map_submap.9 b/static/freebsd/man9/vm_map_submap.9 new file mode 100644 index 00000000..9d96f9bd --- /dev/null +++ b/static/freebsd/man9/vm_map_submap.9 @@ -0,0 +1,93 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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_SUBMAP 9 +.Os +.Sh NAME +.Nm vm_map_submap +.Nd create a subordinate map +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft int +.Fo vm_map_submap +.Fa "vm_map_t map" "vm_offset_t start" "vm_offset_t end" "vm_map_t submap" +.Fc +.Sh DESCRIPTION +The +.Fn vm_map_submap +function marks the range bounded by +.Fa start +and +.Fa end +within the map +.Fa map +as being handled by a subordinate map +.Fa sub_map . +.Pp +It is generally called by the kernel memory allocator. +.Sh IMPLEMENTATION NOTES +This function is for internal use only. +.Pp +Both maps must exist. +The range must have been created with +.Xr vm_map_find 9 +previously. +.Pp +No other operations may have been performed on this range +before calling this function. +Only the +.Fn vm_fault +operation may be performed within this range after calling +this function. +.Pp +To remove a submapping, one must first remove the range from +the parent +.Fa map , +and then destroy the +.Fa sub_map . +This procedure is not recommended. +.Sh RETURN VALUES +The +.Fn vm_map_submap +function returns +.Dv KERN_SUCCESS +if successful. +.Pp +Otherwise, it returns +.Dv KERN_INVALID_ARGUMENT +if the caller requested copy-on-write flags, +or if the range specified for the sub-map was out of range for the parent map, +or if a +.Dv NULL +backing object was specified. +.Sh SEE ALSO +.Xr vm_map 9 , +.Xr vm_map_find 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/vm_map_sync.9 b/static/freebsd/man9/vm_map_sync.9 new file mode 100644 index 00000000..028ef20b --- /dev/null +++ b/static/freebsd/man9/vm_map_sync.9 @@ -0,0 +1,79 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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 9, 2011 +.Dt VM_MAP_SYNC 9 +.Os +.Sh NAME +.Nm vm_map_sync +.Nd push dirty pages to their pager +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft int +.Fo vm_map_sync +.Fa "vm_map_t map" "vm_offset_t start" "vm_offset_t end" "boolean_t syncio" +.Fa "boolean_t invalidate" +.Fc +.Sh DESCRIPTION +The +.Fn vm_map_sync +function forces any dirty cached pages in the range +.Fa start +to +.Fa end +within the +.Fa map +to be pushed to their underlying pager. +.Pp +If +.Fa syncio +is TRUE, dirty pages are written synchronously. +.Pp +If +.Fa invalidate +is TRUE, any cached pages are also freed. +.Pp +The range provided must be contiguous, it MUST NOT contain holes. +The range provided MUST NOT contain any sub-map entries. +.Sh RETURN VALUES +The +.Fn vm_map_sync +function returns +.Dv KERN_SUCCESS +if successful. +.Pp +Otherwise, +.Dv KERN_INVALID_ADDRESS +will be returned if the function encountered a sub-map entry; +.Dv KERN_INVALID_ARGUMENT +will be returned if the function encountered a hole in the region provided, +or if an entry could not be found for the given start address. +.Sh SEE ALSO +.Xr vm_map 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/vm_map_wire.9 b/static/freebsd/man9/vm_map_wire.9 new file mode 100644 index 00000000..2bea01c7 --- /dev/null +++ b/static/freebsd/man9/vm_map_wire.9 @@ -0,0 +1,112 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" 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_WIRE 9 +.Os +.Sh NAME +.Nm vm_map_wire , +.Nm vm_map_unwire +.Nd manage page wiring within a virtual memory map +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft int +.Fn vm_map_wire "vm_map_t map" "vm_offset_t start" "vm_offset_t end" "int flags" +.Ft int +.Fo vm_map_unwire +.Fa "vm_map_t map" "vm_offset_t start" "vm_offset_t end" "int flags" +.Fc +.Sh DESCRIPTION +The +.Fn vm_map_wire +function is responsible for wiring pages in the range between +.Fa start +and +.Fa end +within the map +.Fa map . +Wired pages are locked into physical memory, and may not be paged out +as long as their wire count remains above zero. +.Pp +The +.Fn vm_map_unwire +function performs the corresponding unwire operation. +.Pp +The +.Fa flags +argument is a bit mask, consisting of the following flags: +.Pp +If the +.Dv VM_MAP_WIRE_USER +flag is set, the function operates within user address space. +.Pp +If the +.Dv VM_MAP_WIRE_HOLESOK +flag is set, it may operate upon an arbitrary range within the +address space of +.Fa map . +.Pp +If a contiguous range is desired, callers should explicitly express +their intent by specifying the +.Dv VM_MAP_WIRE_NOHOLES +flag. +.Sh IMPLEMENTATION NOTES +Both functions will attempt to acquire a lock on the map using +.Xr vm_map_lock 9 +and hold it for the duration of the call. +If they detect +.Dv MAP_ENTRY_IN_TRANSITION , +they will call +.Xr vm_map_unlock_and_wait 9 +until the map becomes available again. +.Pp +The map could have changed during this window as it was held by another +consumer, therefore consumers of this interface should check for this +condition using the return values below. +.Sh RETURN VALUES +The +.Fn vm_map_wire +and +.Fn vm_map_unwire +functions have identical return values. +The functions return +.Dv KERN_SUCCESS +if all pages within the range were [un]wired successfully. +.Pp +Otherwise, if the specified range was not valid, +or if the map changed while the +.Dv MAP_ENTRY_IN_TRANSITION +flag was set, +.Dv KERN_INVALID_ADDRESS +is returned. +.Sh SEE ALSO +.Xr mlockall 2 , +.Xr munlockall 2 , +.Xr vm_map 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/static/freebsd/man9/vm_page_aflag.9 b/static/freebsd/man9/vm_page_aflag.9 new file mode 100644 index 00000000..4f45d7b7 --- /dev/null +++ b/static/freebsd/man9/vm_page_aflag.9 @@ -0,0 +1,98 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 August 31, 2011 +.Dt VM_PAGE_AFLAG 9 +.Os +.Sh NAME +.Nm vm_page_aflag_clear , vm_page_aflag_set , vm_page_reference +.Nd "change page atomic flags" +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_page.h +.Ft void +.Fn vm_page_aflag_clear "vm_page_t m" "uint8_t bits" +.Ft void +.Fn vm_page_aflag_set "vm_page_t m" "uint8_t bits" +.Ft void +.Fn vm_page_reference "vm_page_t m" +.Sh DESCRIPTION +The +.Fn vm_page_aflag_clear +atomically clears the specified bits on the page's +.Va aflags . +.Pp +The +.Fn vm_page_aflag_set +atomically sets the specified bits on the page's +.Va aflags . +.Pp +The +.Fn vm_page_reference m +call is the same as +.Bd -literal -offset indent +vm_page_aflag_set(m, PGA_REFERENCED); +.Ed +.Lp +and is the recommended way to mark the page as referenced from +third-party kernel modules. +.Pp +These functions neither block nor require any locks to be held +around the calls for correctness. +.Pp +The functions arguments are: +.Bl -tag -width ".Fa bits" +.It Fa m +The page whose +.Va aflags +are updated. +.It Fa bits +The bits that are set or cleared on the page's flags. +.El +.Pp +The following +.Va aflags +can be set or cleared: +.Bl -tag -width ".Fa PGA_REFERENCED" +.It Fa PGA_REFERENCED +The bit may be set to indicate that the page has been recently accessed. +For instance, +.Xr pmap 9 +sets this bit to reflect the accessed attribute of the page mapping +typically updated by processor's memory management unit on the page access. +.It Fa PGA_WRITEABLE +A writeable mapping for the page may exist. +.El +.Pp +Both +.Dv PGA_REFERENCED +and +.Dv PGA_WRITEABLE +bits are only valid for the managed pages. +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/vm_page_alloc.9 b/static/freebsd/man9/vm_page_alloc.9 new file mode 100644 index 00000000..4bf8db33 --- /dev/null +++ b/static/freebsd/man9/vm_page_alloc.9 @@ -0,0 +1,338 @@ +.\" +.\" Copyright (C) 2001 Chad David . All rights reserved. +.\" Copyright (c) 2021 The FreeBSD Foundation +.\" +.\" Portions of this documentation were written by Mark Johnston under +.\" sponsorship from the FreeBSD Foundation. +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 August 4, 2024 +.Dt VM_PAGE_ALLOC 9 +.Os +.Sh NAME +.Nm vm_page_alloc +.Nd "allocate a page of memory" +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_page.h +.Ft vm_page_t +.Fn vm_page_alloc "vm_object_t object" "vm_pindex_t pindex" "int req" +.Ft vm_page_t +.Fo vm_page_alloc_after +.Fa "vm_object_t object" +.Fa "vm_pindex_t pindex" +.Fa "int req" +.Fa "vm_page_t mpred" +.Fc +.Ft vm_page_t +.Fo vm_page_alloc_contig +.Fa "vm_object_t object" +.Fa "vm_pindex_t pindex" +.Fa "int req" +.Fa "u_long npages" +.Fa "vm_paddr_t low" +.Fa "vm_paddr_t high" +.Fa "u_long alignment" +.Fa "vm_paddr_t boundary" +.Fa "vm_memattr_t memattr" +.Fc +.Ft vm_page_t +.Fo vm_page_alloc_contig_domain +.Fa "vm_object_t object" +.Fa "vm_pindex_t pindex" +.Fa "int req" +.Fa "u_long npages" +.Fa "vm_paddr_t low" +.Fa "vm_paddr_t high" +.Fa "u_long alignment" +.Fa "vm_paddr_t boundary" +.Fa "vm_memattr_t memattr" +.Fc +.Ft vm_page_t +.Fo vm_page_alloc_domain +.Fa "vm_object_t object" +.Fa "vm_pindex_t pindex" +.Fa "int domain" +.Fa "int req" +.Fc +.Ft vm_page_t +.Fo vm_page_alloc_domain_after +.Fa "vm_object_t object" +.Fa "vm_pindex_t pindex" +.Fa "int domain" +.Fa "int req" +.Fa "vm_page_t mpred" +.Fc +.Ft vm_page_t +.Fo vm_page_alloc_noobj +.Fa "int req" +.Fc +.Ft vm_page_t +.Fo vm_page_alloc_noobj_contig +.Fa "int req" +.Fa "u_long npages" +.Fa "vm_paddr_t low" +.Fa "vm_paddr_t high" +.Fa "u_long alignment" +.Fa "vm_paddr_t boundary" +.Fa "vm_memattr_t memattr" +.Fc +.Ft vm_page_t +.Fo vm_page_alloc_noobj_contig_domain +.Fa "int domain" +.Fa "int req" +.Fa "u_long npages" +.Fa "vm_paddr_t low" +.Fa "vm_paddr_t high" +.Fa "u_long alignment" +.Fa "vm_paddr_t boundary" +.Fa "vm_memattr_t memattr" +.Fc +.Ft vm_page_t +.Fo vm_page_alloc_noobj_domain +.Fa "int domain" +.Fa "int req" +.Fc +.Sh DESCRIPTION +The +.Fn vm_page_alloc +family of functions allocate one or more pages of physical memory. +Most kernel code should not call these functions directly but should instead +use a kernel memory allocator such as +.Xr malloc 9 +or +.Xr uma 9 , +or should use a higher-level interface to the page cache, such as +.Xr vm_page_grab 9 . +.Pp +All of the functions take a +.Fa req +parameter which encodes the allocation priority and optional modifier flags, +described below. +The functions whose names do not include +.Dq noobj +additionally insert the pages starting at index +.Fa pindex +in the +VM object +.Fa object . +The object must be write-locked and not have a page already resident at the +specified index. +The functions whose names include +.Dq domain +support NUMA-aware allocation by returning pages from the +.Xr numa 4 +domain specified by +.Fa domain . +.Pp +The +.Fn vm_page_alloc_after +and +.Fn vm_page_alloc_domain_after +functions behave identically to +.Fn vm_page_alloc +and +.Fn vm_page_alloc_domain , +respectively, except that they take an additional parameter +.Fa mpred +which must be the page resident in +.Fa object +with largest index smaller than +.Fa pindex , +or +.Dv NULL +if no such page exists. +These functions exist to optimize the common case of loops that allocate +multiple pages at successive indices within an object. +.Pp +The +.Fn vm_page_alloc_contig +and +.Fn vm_page_alloc_noobj_contig +functions and their NUMA-aware variants allocate a physically contiguous run of +.Fa npages +pages which satisfies the specified constraints. +The +.Fa low +and +.Fa high +parameters specify a physical address range from which the run is to +be allocated. +The +.Fa alignment +parameter specifies the requested alignment of the first page in the run +and must be a power of two. +If the +.Fa boundary +parameter is non-zero, the pages constituting the run will not cross a +physical address that is a multiple of the parameter value, which must be a +power of two. +If +.Fa memattr +is not equal to +.Dv VM_MEMATTR_DEFAULT , +then mappings of the returned pages created by, e.g., +.Xr pmap_enter 9 +or +.Xr pmap_qenter 9 , +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. +.Sh REQUEST FLAGS +All page allocator functions accept a +.Fa req +parameter that governs certain aspects of the function's behavior. +.Pp +The +.Dv VM_ALLOC_WAITOK , +.Dv VM_ALLOC_WAITFAIL , +and +.Dv VM_ALLOC_NOWAIT +flags specify the behavior of the allocator if free pages could not be +immediately allocated. +The +.Dv VM_ALLOC_WAITOK +flag can only be used with the +.Dq noobj +variants. +If +.Dv VM_ALLOC_NOWAIT +is specified, then the allocator gives up and returns +.Dv NULL . +.Dv VM_ALLOC_NOWAIT +is specified implicitly if none of the flags are present in the request. +If either +.Dv VM_ALLOC_WAITOK +or +.Dv VM_ALLOC_WAITFAIL +is specified, the allocator will put the calling thread to sleep until +sufficient free pages become available. +At this point, if +.Dv VM_ALLOC_WAITFAIL +is specified the allocator will return +.Dv NULL , +and if +.Dv VM_ALLOC_WAITOK +is specified the allocator will retry the allocation. +After a failed +.Dv VM_ALLOC_WAITFAIL +allocation returns, the VM object, if any, will have been unlocked while the +thread was sleeping. +In this case the VM object write lock will be re-acquired before the function +call returns. +.Pp +.Fa req +also encodes the allocation request priority. +By default the page(s) are allocated with no special treatment. +If the number of available free pages is below a certain watermark, the +allocation will fail or the allocating thread will sleep, depending on +the specified wait flag. +The watermark is computed at boot time and corresponds to a small (less than +one percent) fraction of the system's total physical memory. +To allocate memory more aggressively, one of following flags may be specified. +.Bl -tag -width ".Dv VM_ALLOC_INTERRUPT" +.It Dv VM_ALLOC_SYSTEM +The page can be allocated if the free page count is above the interrupt +reserved water mark. +This flag should be used only when the system really needs the page. +.It Dv VM_ALLOC_INTERRUPT +The allocation will fail only if zero free pages are available. +This flag should be used only if the consequences of an allocation failure +are worse than leaving the system without free memory. +For example, this flag is used when allocating kernel page table pages, where +allocation failures trigger a kernel panic. +.El +.Pp +The following optional flags can further modify allocator behavior: +.Bl -tag -width ".Dv VM_ALLOC_NOBUSY" +.It Dv VM_ALLOC_SBUSY +The returned page will be shared-busy. +This flag may only be specified when allocating pages in a VM object. +.It Dv VM_ALLOC_NOBUSY +The returned page will not be busy. +This flag is implicit when allocating pages without a VM object. +When allocating pages in a VM object, and neither +.Dv VM_ALLOC_SBUSY +nor +.Dv VM_ALLOC_NOBUSY +are specified, the returned pages will be exclusively busied. +.It Dv VM_ALLOC_NODUMP +The returned page will not be included in any kernel core dumps +regardless of whether or not it is mapped in to KVA. +.It Dv VM_ALLOC_WIRED +The returned page will be wired. +.It Dv VM_ALLOC_ZERO +If this flag is specified, the +.Dq noobj +variants will return zeroed pages. +The other allocator interfaces ignore this flag. +.It Dv VM_ALLOC_NORECLAIM +If this flag is specified and the request can not be immediately satisfied, +the allocator will not attempt to break superpage reservations to satisfy the +allocation. +This may be useful when the overhead of scanning the reservation queue +outweighs the cost of a failed allocation. +This flag may be used only with the +.Dq contig +variants, and must not be specified in combination with +.Dv VM_ALLOC_WAITOK . +.It Dv VM_ALLOC_COUNT(n) +Hint that at least +.Fa n +pages will be allocated by the caller in the near future. +.Fa n +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 +.Vt struct vm_page +corresponding to the allocated page is returned. +If the allocation request specified multiple pages, the returned +pointer points to an array of +.Vt struct vm_page +constituting the run. +Upon failure, +.Dv NULL +is returned. +Regardless of whether the allocation succeeds or fails, the VM +object +.Fa object +will be write-locked upon return. +.Sh SEE ALSO +.Xr numa 4 , +.Xr malloc 9 , +.Xr uma 9 , +.Xr vm_page_grab 9 , +.Xr vm_page_sbusy 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/vm_page_bits.9 b/static/freebsd/man9/vm_page_bits.9 new file mode 100644 index 00000000..c8900f4a --- /dev/null +++ b/static/freebsd/man9/vm_page_bits.9 @@ -0,0 +1,165 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 1, 2001 +.Dt VM_PAGE_BITS 9 +.Os +.Sh NAME +.Nm vm_page_bits , +.Nm vm_page_set_validclean , +.Nm vm_page_clear_dirty , +.Nm vm_page_set_invalid , +.Nm vm_page_zero_invalid , +.Nm vm_page_is_valid , +.Nm vm_page_test_dirty , +.Nm vm_page_dirty , +.Nm vm_page_undirty +.Nd "manage page clean and dirty bits" +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_page.h +.Ft int +.Fn vm_page_bits "int base" "int size" +.Ft void +.Fn vm_page_set_validclean "vm_page_t m" "int base" "int size" +.Ft void +.Fn vm_page_clear_dirty "vm_page_t m" "int base" "int size" +.Ft void +.Fn vm_page_set_invalid "vm_page_t m" "int base" "int size" +.Ft void +.Fn vm_page_zero_invalid "vm_page_t m" "boolean_t setvalid" +.Ft int +.Fn vm_page_is_valid "vm_page_t m" "int base" "int size" +.Ft void +.Fn vm_page_test_dirty "vm_page_t m" +.Ft void +.Fn vm_page_dirty "vm_page_t m" +.Ft void +.Fn vm_page_undirty "vm_page_t m" +.Sh DESCRIPTION +.Fn vm_page_bits +calculates the bits representing the +.Dv DEV_BSIZE +range of bytes between +.Fa base +and +.Fa size . +The byte range is expected to be within a single page, and if +.Fa size +is zero, no bits will be set. +.Pp +.Fn vm_page_set_validclean +flags the byte range between +.Fa base +and +.Fa size +as valid and clean. +The range is expected to be +.Dv DEV_BSIZE +aligned and no larger than +.Dv PAGE_SIZE . +If it is not properly aligned, any unaligned chunks of the +.Dv DEV_BSIZE +blocks at the beginning and end of the range will be zeroed. +.Pp +If +.Fa base +is zero and +.Fa size +is one page, the modified bit in the page map is cleared; as well, +the +.Dv VPO_NOSYNC +flag is cleared. +.Pp +.Fn vm_page_clear_dirty +clears the dirty bits within a page in the range between +.Fa base +and +.Fa size . +The bits representing the range are calculated by calling +.Fn vm_page_bits . +.Pp +.Fn vm_page_set_invalid +clears the bits in both the valid and dirty flags representing +the +.Dv DEV_BSIZE +blocks between +.Fa base +and +.Fa size +in the page. +The bits are calculated by calling +.Fn vm_page_bits . +As well as clearing the bits within the page, the generation +number within the object holding the page is incremented. +.Pp +.Fn vm_page_zero_invalid +zeroes all of the blocks within the page that are currently +flagged as invalid. +If +.Fa setvalid +is +.Dv TRUE , +all of the valid bits within the page are set. +.Pp +In some cases, such as NFS, the valid bits cannot be set +in order to maintain cache consistency. +.Pp +.Fn vm_page_is_valid +checks to determine if the all of the +.Dv DEV_BSIZE +blocks between +.Fa base +and +.Fa size +of the page are valid. +If +.Fa size +is zero and the page is entirely invalid +.Fn vm_page_is_valid +will return +.Dv TRUE , +in all other cases a size of zero will return +.Dv FALSE . +.Pp +.Fn vm_page_test_dirty +checks if a page has been modified via any of its physical maps, +and if so, flags the entire page as dirty. +.Fn vm_page_dirty +is called to modify the dirty bits. +.Pp +.Fn vm_page_dirty +flags the entire page as dirty. +It is expected that the page is not currently on the cache queue. +.Pp +.Fn vm_page_undirty +clears all of the dirty bits in a page. +.Sh NOTES +None of these functions are allowed to block. +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/vm_page_busy.9 b/static/freebsd/man9/vm_page_busy.9 new file mode 100644 index 00000000..ee8ca7e1 --- /dev/null +++ b/static/freebsd/man9/vm_page_busy.9 @@ -0,0 +1,198 @@ +.\" +.\" Copyright (c) 2013 EMC Corp. +.\" 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 November 11, 2021 +.Dt VM_PAGE_BUSY 9 +.Os +.Sh NAME +.Nm vm_page_busied , +.Nm vm_page_busy_downgrade , +.Nm vm_page_busy_sleep , +.Nm vm_page_sbusied , +.Nm vm_page_sunbusy , +.Nm vm_page_trysbusy , +.Nm vm_page_tryxbusy , +.Nm vm_page_xbusied , +.Nm vm_page_xunbusy , +.Nm vm_page_assert_sbusied , +.Nm vm_page_assert_unbusied , +.Nm vm_page_assert_xbusied +.Nd protect page identity changes and page content references +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_page.h +.Ft int +.Fn vm_page_busied "vm_page_t m" +.Ft void +.Fn vm_page_busy_downgrade "vm_page_t m" +.Ft bool +.Fn vm_page_busy_sleep "vm_page_t m" "const char *msg" "int allocflags" +.Ft int +.Fn vm_page_sbusied "vm_page_t m" +.Ft void +.Fn vm_page_sunbusy "vm_page_t m" +.Ft int +.Fn vm_page_trysbusy "vm_page_t m" +.Ft int +.Fn vm_page_tryxbusy "vm_page_t m" +.Ft int +.Fn vm_page_xbusied "vm_page_t m" +.Ft void +.Fn vm_page_xunbusy "vm_page_t m" +.Pp +.Cd "options INVARIANTS" +.Cd "options INVARIANT_SUPPORT" +.Ft void +.Fn vm_page_assert_sbusied "vm_page_t m" +.Ft void +.Fn vm_page_assert_unbusied "vm_page_t m" +.Ft void +.Fn vm_page_assert_xbusied "vm_page_t m" +.Sh DESCRIPTION +Page identity is usually protected by higher level locks like vm_object +locks and vm page locks. +However, sometimes it is not possible to hold such locks for the time +necessary to complete the identity change. +In such case the page can be exclusively busied by a thread which needs +to own the identity for a certain amount of time. +.Pp +In other situations, threads do not need to change the identity of the +page but they want to prevent other threads from changing the identity +themselves. +For example, when a thread wants to access or update page contents +without a lock held the page is shared busied. +.Pp +Before busying a page the vm_object lock must be held. +The same rule applies when a page is unbusied. +This makes the vm_object lock a real busy interlock. +.Pp +The +.Fn vm_page_busied +function returns non-zero if the current thread busied +.Fa m +in either exclusive or shared mode. +Returns zero otherwise. +.Pp +The +.Fn vm_page_busy_downgrade +function must be used to downgrade +.Fa m +from an exclusive busy state to a shared busy state. +.Pp +The +.Fn vm_page_busy_sleep +checks the busy state of the page +.Fa m +and puts the invoking thread to sleep if the page is busy. +The VM object for the page must be locked. +The +.Fa allocflags +parameter must be either +.Dv 0 , +in which case the function will sleep if the page is busied, +or +.Dv VM_ALLOC_IGN_SBUSY , +in which case the function will sleep only if the page is exclusively +busied. +A return value of true indicates that the invoking thread was put to +sleep and that the object was unlocked. +A return value of false indicates that the invoking thread did not sleep +and the object remains locked. +The parameter +.Fa msg +is a string describing the sleep condition for userland tools. +.Pp +The +.Fn vm_page_busied +function returns non-zero if the current thread busied +.Fa m +in shared mode. +Returns zero otherwise. +.Pp +The +.Fn vm_page_sunbusy +function shared unbusies +.Fa m . +.Pp +The +.Fn vm_page_trysbusy +attempts to shared busy +.Fa m . +If the operation cannot immediately succeed +.Fn vm_page_trysbusy +returns 0, otherwise a non-zero value is returned. +.Pp +The +.Fn vm_page_tryxbusy +attempts to exclusive busy +.Fa m . +If the operation cannot immediately succeed +.Fn vm_page_tryxbusy +returns 0, otherwise a non-zero value is returned. +.Pp +The +.Fn vm_page_xbusied +function returns non-zero if the current thread busied +.Fa m +in exclusive mode. +Returns zero otherwise. +.Pp +The +.Fn vm_page_xunbusy +function exclusive unbusies +.Fa m . +Assertions on the busy state allow kernels compiled with +.Cd "options INVARIANTS" +and +.Cd "options INVARIANT_SUPPORT" +to panic if they are not respected. +.Pp +The +.Fn vm_page_assert_sbusied +function panics if +.Fa m +is not shared busied. +.Pp +The +.Fn vm_page_assert_unbusied +function panics if +.Fa m +is not unbusied. +.Pp +The +.Fn vm_page_assert_xbusied +function panics if +.Fa m +is not exclusive busied. +.Sh SEE ALSO +.Xr vm_page_aflag 9 , +.Xr vm_page_alloc 9 , +.Xr vm_page_deactivate 9 , +.Xr vm_page_free 9 , +.Xr vm_page_grab 9 , +.Xr vm_page_insert 9 , +.Xr vm_page_lookup 9 , +.Xr vm_page_rename 9 , +.Xr VOP_GETPAGES 9 diff --git a/static/freebsd/man9/vm_page_deactivate.9 b/static/freebsd/man9/vm_page_deactivate.9 new file mode 100644 index 00000000..ca6c0595 --- /dev/null +++ b/static/freebsd/man9/vm_page_deactivate.9 @@ -0,0 +1,48 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH +.\" DAMAGE. +.\" +.Dd July 24, 2001 +.Dt VM_PAGE_DEACTIVATE 9 +.Os +.Sh NAME +.Nm vm_page_deactivate +.Nd "deactivate a page" +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_page.h +.Ft void +.Fn vm_page_deactivate "vm_page_t m" +.Sh DESCRIPTION +The +.Fn vm_page_deactivate +function moves the given page to the inactive queue as long as it is +unmanaged and is not wired. +.Sh SEE ALSO +.Xr vm_page_wire 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/vm_page_dontneed.9 b/static/freebsd/man9/vm_page_dontneed.9 new file mode 100644 index 00000000..6f6628f7 --- /dev/null +++ b/static/freebsd/man9/vm_page_dontneed.9 @@ -0,0 +1,57 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 30, 2001 +.Dt VM_PAGE_DONTNEED 9 +.Os +.Sh NAME +.Nm vm_page_dontneed +.Nd "indicate that a page is not needed anymore" +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_page.h +.Ft void +.Fn vm_page_dontneed "vm_page_t m" +.Sh DESCRIPTION +The +.Fn vm_page_dontneed +function advises the VM system that the given page is no longer +required. +If the page is already in the inactive queue or in the cache queue, this +function does nothing; otherwise the page is deactivated. +.Pp +Note that +.Fn vm_page_dontneed +does not necessarily deactivate a page, but instead implements an +algorithm that attempts to prevent small objects from having their +pages reused too quickly, and large objects from flushing smaller +ones from the queues as their pages are released. +.Sh SEE ALSO +.Xr vm_page_deactivate 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/vm_page_free.9 b/static/freebsd/man9/vm_page_free.9 new file mode 100644 index 00000000..0a71076d --- /dev/null +++ b/static/freebsd/man9/vm_page_free.9 @@ -0,0 +1,96 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH +.\" DAMAGE. +.\" +.Dd July 24, 2001 +.Dt VM_PAGE_FREE 9 +.Os +.Sh NAME +.Nm vm_page_free , +.Nm vm_page_free_toq , +.Nm vm_page_free_zero , +.Nm vm_page_try_to_free +.Nd "free a page" +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_page.h +.Ft void +.Fn vm_page_free "vm_page_t m" +.Ft void +.Fn vm_page_free_toq "vm_page_t m" +.Ft void +.Fn vm_page_free_zero "vm_page_t m" +.Ft int +.Fn vm_page_try_to_free "vm_page_t m" +.Sh DESCRIPTION +The +.Fn vm_page_free_toq +function moves a page into the free queue, and disassociates it from +its object. +If the page is held, wired, already free, or its busy count is not +zero, the system will panic. +If the +.Dv PG_ZERO +flag is set on the page, it is placed at the end of the free queue; +otherwise, it is placed at the front. +.Pp +If the page's object is of type +.Dv OBJT_VNODE +and it is the last page associated with the object, the underlying +vnode may be freed. +.Pp +The +.Fn vm_page_free +and +.Fn vm_page_free_zero +functions both call +.Fn vm_page_free_toq +to actually free the page, but +.Fn vm_page_free_zero +sets the +.Dv PG_ZERO +flag and +.Fn vm_page_free +clears the +.Dv PG_ZERO +flag prior to the call to +.Fn vm_page_free_toq . +.Pp +The +.Fn vm_page_try_to_free +function verifies that the page is not held, wired, busy or dirty, and +if so, marks the page as busy, drops any protection that may be set on +the page, and frees it. +.Sh RETURN VALUES +.Fn vm_page_try_to_free +returns 1 if it is able to free the page; otherwise, 0 is returned. +.Sh SEE ALSO +.Xr vm_page_busy 9 , +.Xr vm_page_hold 9 , +.Xr vm_page_wire 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/vm_page_grab.9 b/static/freebsd/man9/vm_page_grab.9 new file mode 100644 index 00000000..28a24e8b --- /dev/null +++ b/static/freebsd/man9/vm_page_grab.9 @@ -0,0 +1,82 @@ +.\" +.\" Copyright (C) 2001 Chad David . All rights reserved. +.\" Copyright (c) 2013 The FreeBSD Foundation +.\" +.\" Portions of this documentation were written by Konstantin Belousov +.\" under sponsorship from the FreeBSD Foundation. +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 August 23, 2013 +.Dt VM_PAGE_GRAB 9 +.Os +.Sh NAME +.Nm vm_page_grab +.Nd "returns a page from an object" +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_page.h +.Ft vm_page_t +.Fn vm_page_grab "vm_object_t object" "vm_pindex_t pindex" "int allocflags" +.Sh DESCRIPTION +The +.Fn vm_page_grab +function returns the page at +.Fa pindex +from the given object. +If the page exists and is busy, +.Fn vm_page_grab +will sleep while waiting for it. +If the page does not exist, it is allocated. +The function sleeps until the allocation request can be satisfied. +.Pp +The function requires the +.Fa object +to be locked on entry, and returns with the object locked. +If the +.Fn vm_page_grab +function sleeps for any reason, the object lock is temporary dropped. +.Pp +The +.Fn vm_page_grab +supports all of the flags supported by +.Xr vm_page_alloc 9 . +In addition, +.Fn vm_page_grab +supports the following flags: +.Bl -tag -width ".Dv VM_ALLOC_IGN_SBUSY" +.It Dv VM_ALLOC_IGN_SBUSY +When waiting for the busy state of the existing page to drain, +only test for exclusive busy; ignore the shared busy counter. +.El +.Sh RETURN VALUES +The +.Fn vm_page_grab +always returns the page. +.Sh SEE ALSO +.Xr vm_page_alloc 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/vm_page_insert.9 b/static/freebsd/man9/vm_page_insert.9 new file mode 100644 index 00000000..7f872c47 --- /dev/null +++ b/static/freebsd/man9/vm_page_insert.9 @@ -0,0 +1,94 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 17, 2001 +.Dt VM_PAGE_INSERT 9 +.Os +.Sh NAME +.Nm vm_page_insert , +.Nm vm_page_remove +.Nd "add/remove page from an object" +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_page.h +.Ft void +.Fn vm_page_insert "vm_page_t m" "vm_object_t object" "vm_pindex_t pindex" +.Ft void +.Fn vm_page_remove "vm_page_t m" +.Sh DESCRIPTION +The +.Fn vm_page_insert +function adds a page to the given object at the given index. +The page is added to both the VM page hash table and to the +object's list of pages, but the hardware page tables are not updated. +In the case of a user page, it will be faulted in when it is +accessed. +If the page is a kernel page, the caller is expected to +handle adding the page to the kernel's pmap. +.Pp +If +.Dv PG_WRITEABLE +is set in the page's flags, +.Dv OBJ_WRITEABLE +and +.Dv OBJ_MIGHTBEDIRTY +are set in the object's flags. +.Pp +The +.Fn vm_page_remove +function removes the given page from its object, and from the +VM page hash table. +The page must be busy prior to this call, or the system will panic. +The pmap entry for the page is not removed by this function. +.Pp +The arguments to +.Fn vm_page_insert +are: +.Bl -tag -width ".Fa object" +.It Fa m +The page to add to the object. +.It Fa object +The object the page should be added to. +.It Fa pindex +The index into the object the page should be at. +.El +.Pp +The arguments to +.Fn vm_page_remove +are: +.Bl -tag -width ".Fa m" +.It Fa m +The page to remove. +.El +.Sh IMPLEMENTATION NOTES +The index of a page in a VM object is the byte index into the +same object truncated to a page boundary. +For example, if the page size is 4096 bytes, and the address +in the object is 81944, the page index is 20. +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/vm_page_lookup.9 b/static/freebsd/man9/vm_page_lookup.9 new file mode 100644 index 00000000..74318fd6 --- /dev/null +++ b/static/freebsd/man9/vm_page_lookup.9 @@ -0,0 +1,61 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 13, 2001 +.Dt VM_PAGE_LOOKUP 9 +.Os +.Sh NAME +.Nm vm_page_lookup +.Nd "lookup a vm page" +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_page.h +.Ft vm_page_t +.Fn vm_page_lookup "vm_object_t object" "vm_pindex_t pindex" +.Sh DESCRIPTION +The +.Fn vm_page_lookup +function searches for a VM page given its VM object and index. +If the page is not found, +.Dv NULL +is returned. +Its arguments are: +.Bl -tag -width ".Fa object" +.It Fa object +The VM object to search on. +.It Fa pindex +The page index to search on. +.El +.Sh RETURN VALUES +A +.Vt vm_page_t +is returned if successful; otherwise, +.Dv NULL +is returned. +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/vm_page_rename.9 b/static/freebsd/man9/vm_page_rename.9 new file mode 100644 index 00000000..359d3341 --- /dev/null +++ b/static/freebsd/man9/vm_page_rename.9 @@ -0,0 +1,70 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 17, 2001 +.Dt VM_PAGE_RENAME 9 +.Os +.Sh NAME +.Nm vm_page_rename +.Nd "move a page" +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_page.h +.Ft void +.Fo vm_page_rename +.Fa "vm_page_t m" +.Fa "vm_object_t new_object" +.Fa "vm_pindex_t new_pindex" +.Fc +.Sh DESCRIPTION +The +.Fn vm_page_rename +function removes a page from one object, and adds it to another +at the given page index. +The page is added to the given object, and is removed from the +object that is currently associated with. +If the page is currently on the cache queue it will be deactivated +unless it is wired or unmanaged, in which case the deactivation will +fail. +The entire page is marked as dirty after the move. +.Pp +The arguments to +.Fn vm_page_rename +are: +.Bl -tag -width ".Fa new_object" +.It Fa m +The page to move. +.It Fa new_object +The object the page should be inserted into. +.It Fa new_pindex +The page index into +.Fa new_object +at which the new page should be inserted. +.El +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/vm_page_wire.9 b/static/freebsd/man9/vm_page_wire.9 new file mode 100644 index 00000000..1f23bd5a --- /dev/null +++ b/static/freebsd/man9/vm_page_wire.9 @@ -0,0 +1,81 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 September 9, 2019 +.Dt VM_PAGE_WIRE 9 +.Os +.Sh NAME +.Nm vm_page_wire , +.Nm vm_page_unwire , +.Nm vm_page_unwire_noq +.Nd "wire and unwire pages" +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_page.h +.Ft void +.Fn vm_page_wire "vm_page_t m" +.Ft bool +.Fn vm_page_wire_mapped "vm_page_t m" +.Ft void +.Fn vm_page_unwire "vm_page_t m" "int queue" +.Ft bool +.Fn vm_page_unwire_noq "vm_page_t m" +.Sh DESCRIPTION +The +.Fn vm_page_wire +and +.Fn vm_page_wire_mapped +functions wire the page, which prevents it from being reclaimed by the page +daemon or when its containing object is destroyed. +Both functions require that the page belong to an object. +The +.Fn vm_page_wire_mapped +function is for use by the +.Xr pmap 9 +layer following a lookup. +This function may fail if mappings of the page are concurrently +being destroyed, in which case it will return false. +.Pp +The +.Fn vm_page_unwire +and +.Fn vm_page_unwire_noq +functions release a wiring of a page. +The +.Fn vm_page_unwire +function takes a queue index and will insert the page into the +corresponding page queue upon releasing its last wiring. +If the page does not belong to an object and no other references +to the page exist, +.Fn vm_page_unwire +will free the page. +.Fn vm_page_unwire_noq +releases the wiring and returns true if it was the last wiring +of the page. +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/vm_set_page_size.9 b/static/freebsd/man9/vm_set_page_size.9 new file mode 100644 index 00000000..e0fda4f5 --- /dev/null +++ b/static/freebsd/man9/vm_set_page_size.9 @@ -0,0 +1,60 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 March 21, 2014 +.Dt VM_SET_PAGE_SIZE 9 +.Os +.Sh NAME +.Nm vm_set_page_size +.Nd "initialize the system page size" +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_page.h +.Ft void +.Fn vm_set_page_size void +.Sh DESCRIPTION +The +.Fn vm_set_page_size +function initializes the system page size. +If +.Va vm_cnt.v_page_size +(see +.In sys/vmmeter.h ) +equals 0, +.Dv PAGE_SIZE +is used; otherwise, the value stored in +.Va vm_cnt.v_page_size +is used. +If +.Va vm_cnt.v_page_size +is not a power of two, the system will panic. +.Pp +.Fn vm_set_page_size +must be called prior to any page size dependent functions. +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/vmem.9 b/static/freebsd/man9/vmem.9 new file mode 100644 index 00000000..119815e8 --- /dev/null +++ b/static/freebsd/man9/vmem.9 @@ -0,0 +1,316 @@ +.\"- +.\" 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, +.\" 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 May 17, 2019 +.Dt VMEM 9 +.Os +.\" ------------------------------------------------------------ +.Sh NAME +.Nm vmem +.Nd general purpose resource allocator +.\" ------------------------------------------------------------ +.Sh SYNOPSIS +.In sys/vmem.h +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft vmem_t * +.Fn vmem_create \ +"const char *name" "vmem_addr_t base" "vmem_size_t size" "vmem_size_t quantum" \ +"vmem_size_t qcache_max" "int flags" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft int +.Fn vmem_add \ +"vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size" "int flags" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft int +.Fn vmem_xalloc \ +"vmem_t *vm" "const vmem_size_t size" "vmem_size_t align" \ +"const vmem_size_t phase" "const vmem_size_t nocross" \ +"const vmem_addr_t minaddr" "const vmem_addr_t maxaddr" "int flags" \ +"vmem_addr_t *addrp" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn vmem_xfree "vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft int +.Fn vmem_alloc "vmem_t *vm" "vmem_size_t size" "int flags" "vmem_addr_t *addrp" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn vmem_free "vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn vmem_destroy "vmem_t *vm" +.\" ------------------------------------------------------------ +.Sh DESCRIPTION +The +.Nm +is a general purpose resource allocator. +Despite its name, it can be used for arbitrary resources +other than virtual memory. +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn vmem_create +creates a new vmem arena. +.Bl -tag -offset indent -width "qcache_max" +.It Fa name +The string to describe the vmem. +.It Fa base +The start address of the initial span. +Pass +.Dv 0 +if no initial span is required. +.It Fa size +The size of the initial span. +Pass +.Dv 0 +if no initial span is required. +.It Fa quantum +The smallest unit of allocation. +.It Fa qcache_max +The largest size of allocations which can be served by quantum cache. +It is merely a hint and can be ignored. +.It Fa flags +.Xr malloc 9 +wait flag. +.El +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn vmem_add +adds a span of size +.Fa size +starting at +.Fa addr +to the arena. +Returns +0 +on success, +.Dv ENOMEM +on failure. +.Fa flags +is +.Xr malloc 9 +wait flag. +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn vmem_xalloc +allocates a resource from the arena. +.Bl -tag -offset indent -width "qcache_max" +.It Fa vm +The arena which we allocate from. +.It Fa size +Specify the size of the allocation. +.It Fa align +If zero, don't care about the alignment of the allocation. +Otherwise, request a resource segment starting at +offset +.Fa phase +from an +.Fa align +aligned boundary. +.It Fa phase +See the above description of +.Fa align . +If +.Fa align +is zero, +.Fa phase +should be zero. +Otherwise, +.Fa phase +should be smaller than +.Fa align . +.It Fa nocross +Request a resource which doesn't cross +.Fa nocross +aligned boundary. +.It Fa minaddr +Specify the minimum address which can be allocated, or +.Dv VMEM_ADDR_MIN +if the caller does not care. +.It Fa maxaddr +Specify the maximum address which can be allocated, or +.Dv VMEM_ADDR_MAX +if the caller does not care. +.It Fa flags +A bitwise OR of an allocation strategy and a +.Xr malloc 9 +wait flag. +The allocation strategy is one of: +.Bl -tag -width "M_FIRSTFIT" +.It Dv M_FIRSTFIT +Prefer allocation performance. +.It Dv M_BESTFIT +Prefer space efficiency. +.It Dv M_NEXTFIT +Perform an address-ordered search for free addresses, beginning where +the previous search ended. +.El +.It Fa addrp +On success, if +.Fa addrp +is not +.Dv NULL , +.Fn vmem_xalloc +overwrites it with the start address of the allocated span. +.El +.Pp +.\" ------------------------------------------------------------ +.Fn vmem_xfree +frees resource allocated by +.Fn vmem_xalloc +to the arena. +.Bl -tag -offset indent -width "qcache_max" +.It Fa vm +The arena which we free to. +.It Fa addr +The resource being freed. +It must be the one returned by +.Fn vmem_xalloc . +Notably, it must not be the one from +.Fn vmem_alloc . +Otherwise, the behaviour is undefined. +.It Fa size +The size of the resource being freed. +It must be the same as the +.Fa size +argument used for +.Fn vmem_xalloc . +.El +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn vmem_alloc +allocates a resource from the arena. +.Bl -tag -offset indent -width "qcache_max" +.It Fa vm +The arena which we allocate from. +.It Fa size +Specify the size of the allocation. +.It Fa flags +A bitwise OR of an +.Nm +allocation strategy flag (see above) and a +.Xr malloc 9 +sleep flag. +.It Fa addrp +On success, if +.Fa addrp +is not +.Dv NULL , +.Fn vmem_alloc +overwrites it with the start address of the allocated span. +.El +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn vmem_free +frees resource allocated by +.Fn vmem_alloc +to the arena. +.Bl -tag -offset indent -width "qcache_max" +.It Fa vm +The arena which we free to. +.It Fa addr +The resource being freed. +It must be the one returned by +.Fn vmem_alloc . +Notably, it must not be the one from +.Fn vmem_xalloc . +Otherwise, the behaviour is undefined. +.It Fa size +The size of the resource being freed. +It must be the same as the +.Fa size +argument used for +.Fn vmem_alloc . +.El +.Pp +.\" ------------------------------------------------------------ +.Fn vmem_destroy +destroys a vmem arena. +.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. +.El +.\" ------------------------------------------------------------ +.Sh RETURN VALUES +.Fn vmem_create +returns a pointer to the newly allocated vmem_t. +Otherwise, it returns +.Dv NULL . +.Pp +On success, +.Fn vmem_xalloc +and +.Fn vmem_alloc +return 0. +Otherwise, +.Dv ENOMEM +is returned. +.\" ------------------------------------------------------------ +.Sh CODE REFERENCES +The +.Nm +subsystem is implemented within the file +.Pa sys/kern/subr_vmem.c . +.\" ------------------------------------------------------------ +.Sh SEE ALSO +.Xr malloc 9 +.Pp +.Xr libuvmem 3 +for the userspace port of the allocator. +.Rs +.%A Jeff Bonwick +.%A Jonathan Adams +.%T "Magazines and Vmem: Extending the Slab Allocator to Many CPUs and Arbitrary Resources" +.%J "2001 USENIX Annual Technical Conference" +.%D 2001 +.Re +.\" ------------------------------------------------------------ +.Sh HISTORY +The +.Nm +allocator was originally implemented in +.Nx . +It was introduced in +.Fx 10.0 . +.Sh AUTHORS +.An -nosplit +Original implementation of +.Nm +was written by +.An "YAMAMOTO Takashi" . +The +.Fx +port was made by +.An "Jeff Roberson" . +.Sh BUGS +.Nm +relies on +.Xr malloc 9 , +so it cannot be used as early during system bootstrap. diff --git a/static/freebsd/man9/vn_deallocate.9 b/static/freebsd/man9/vn_deallocate.9 new file mode 100644 index 00000000..6ce64dc6 --- /dev/null +++ b/static/freebsd/man9/vn_deallocate.9 @@ -0,0 +1,113 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2021 The FreeBSD Foundation +.\" +.\" This manual page was written by Ka Ho Ng under sponsorship from +.\" the FreeBSD Foundation. +.\" +.\" 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 August 25, 2021 +.Dt VN_DEALLOCATE 9 +.Os +.Sh NAME +.Nm vn_deallocate +.Nd zero and/or deallocate storage from a file +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fo vn_deallocate +.Fa "struct vnode *vp" +.Fa "off_t *offset" +.Fa "off_t *length" +.Fa "int flags" +.Fa "int ioflag" +.Fa "struct ucred *active_cred" +.Fa "struct ucred *file_cred" +.Fc +.Sh DESCRIPTION +The +.Fn vn_deallocate +function zeros and/or deallocates backing storage space from a file. +This function only works on vnodes with +.Dv VREG +type. +.Pp +The arguments are: +.Bl -tag -width active_cred +.It Fa vp +The vnode of the file. +.It Fa offset +The starting offset of the operation range. +.It Fa length +The length of the operation range. +This must be greater than 0. +.It Fa flags +The control flags of the operation. +This should be set to 0 for now. +.It Fa ioflag +Directives and hints to be given to the file system. +.It Fa active_cred +The user credentials of the calling thread. +.It Fa file_cred +The credentials installed on the file description pointing to the vnode or NOCRED. +.El +.Pp +The +.Fn ioflag +argument gives directives and hints to the file system. +It may include one or more of the following flags: +.Bl -tag -width IO_RANGELOCKED +.It Dv IO_NODELOCKED +The vnode was locked before the call. +.It Dv IO_RANGELOCKED +Rangelock was owned around the call. +.It Dv IO_NOMACCHECK +Skip MAC checking in the call. +.It Dv IO_SYNC +Do I/O synchronously. +.It Dv IO_DIRECT +Attempt to bypass buffer cache. +.El +.Pp +.Fa *offset +and +.Fa *length +are updated to reflect the unprocessed operation range of the call. +For a successful completion, +.Fa *length +is updated to be the value 0, and +.Fa *offset +is incremented by the number of bytes zeroed before the end-of-file. +.Sh RETURN VALUES +Upon successful completion, the value 0 is returned; otherwise the +appropriate error is returned. +.Sh SEE ALSO +.Xr vnode 9 , +.Xr VOP_DEALLOCATE 9 +.Sh AUTHORS +.Nm +and this manual page was written by +.An Ka Ho Ng Aq Mt khng@FreeBSD.org +under sponsorship from the FreeBSD Foundation. diff --git a/static/freebsd/man9/vn_fullpath.9 b/static/freebsd/man9/vn_fullpath.9 new file mode 100644 index 00000000..af459ed2 --- /dev/null +++ b/static/freebsd/man9/vn_fullpath.9 @@ -0,0 +1,196 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2003 Robert N. M. Watson. +.\" All rights reserved. +.\" Copyright (c) 2025 The FreeBSD Foundation +.\" +.\" Portions of this documentation were written by Olivier Certner +.\" at Kumacom SARL under sponsorship from the FreeBSD +.\" Foundation. +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 September 29, 2025 +.Dt VN_FULLPATH 9 +.Os +.Sh NAME +.Nm vn_fullpath +.Nd "convert a vnode reference to a full pathname, given a process context" +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn vn_fullpath "struct vnode *vp" "char **retbuf" "char **freebuf" +.Ft int +.Fn vn_fullpath_jail "struct vnode *vp" "char **retbuf" "char **freebuf" +.Ft int +.Fn vn_fullpath_global "struct vnode *vp" "char **retbuf" "char **freebuf" +.Ft int +.Fo vn_fullpath_hardlink +.Fa "struct vnode *vp" "struct vnode *dvp" +.Fa "const char *hrdl_name" "size_t hrdl_name_length" +.Fa "char **retbuf" "char **freebuf" "size_t *buflen" +.Fc +.Sh DESCRIPTION +The +.Fn vn_fullpath , +.Fn vn_fullpath_jail , +.Fn vn_fullpath_global +and +.Fn vn_fullpath_hardlink +functions make a +.Dq best effort +attempt at generating a string pathname for the passed vnode. +They differ in which directory the returned path is relative to, except for +.Fn vn_fullpath_hardlink +which behaves like +.Fn vn_fullpath +in this respect and is described at the end. +.Pp +The +.Fn vn_fullpath +function returns a path relative to the root directory of the process associated +with the passed thread pointer. +That root directory is either the system's or the thread's process' containing +jail's root directory, or some descendant directory of such established by some +.Xr chroot 2 +call. +The +.Fn vn_fullpath_jail +function returns a path relative to the passed thread's process' current jail's +root, ignoring intervening +.Xr chroot 2 +calls possibly made inside that jail. +The +.Fn vn_fullpath_global +function returns the full path from the system root, ignoring all jail roots and +.Xr chroot 2 +calls. +.Pp +Paths that the kernel intends to communicate to the passed user thread should +exclusively be obtained via +.Fn vn_fullpath . +Paths obtained via +.Fn vn_fullpath_jail +or +.Fn vn_fullpath_global +are only useful for specific kernel checks or auditing purposes. +.Pp +All these functions are implemented by inspecting the VFS name cache, and +attempting to reconstruct a path from the process root to the object. +This process is necessarily unreliable for several reasons: intermediate +entries in the path may not be found in the cache; files may have more +than one name (hard links), not all file systems use the name cache +(specifically, most synthetic file systems do not); a single name may +be used for more than one file (in the context of file systems covering +other file systems); a file may have no name (if deleted but still +open or referenced). +However, the resulting string may still be more usable to a user than +a vnode pointer value, or a device number and inode number. +Code consuming the results of this function should anticipate (and +properly handle) failure. +.Pp +These functions take the following arguments: +.Bl -tag -width ".Fa freebuf" +.It Fa vp +The vnode to search for. +No need to be locked by the caller. +.It Fa retbuf +Pointer to a +.Vt "char *" +that may be set (on success) to point at a newly allocated buffer containing the +resulting pathname. +.It Fa freebuf +Pointer to a +.Vt "char *" +that may be set (on success) to point at a buffer to be freed, when the caller +is done with +.Fa retbuf . +.El +.Pp +Typical consumers will declare two character pointers: +.Va fullpath +and +.Va freepath ; +they will set +.Va freepath +to +.Dv NULL , +and +.Va fullpath +to a name to use +in the event that the call to +.Fn vn_fullpath +fails. +After done with the value of +.Va fullpath , +the caller will check if +.Va freepath +is +.Pf non- Dv NULL , +and if so, invoke +.Xr free 9 +with a pool type of +.Dv M_TEMP . +.Pp +The +.Fn vn_fullpath_hardlink +function is a convenience wrapper which automatically appends the hardlink name +passed via arguments +.Fa hrdl_name +and +.Fa hrdl_name_length +to the result of calling +.Fn vn_fullpath +on the vnode's parent directory. +It requires the results of a prior call to +.Xr namei 9 +with flag +.Dv WANTPARENT +to be passed in the +.Fa vp +and +.Fa dvp +arguments. +Argument +.Fa buflen +must point to a valid storage containing the size of the desired buffer, which +will be reduced to +.Dv MAXPATHLEN +if in excess of it. +.Sh RETURN VALUES +If the vnode is successfully converted to a pathname, 0 is returned; +otherwise, an error number is returned. +.Sh SEE ALSO +.Xr free 9 +.Sh AUTHORS +.An -nosplit +This manual page was initially written by +.An Robert Watson Aq Mt rwatson@FreeBSD.org +to describe the +.Fn vn_fullpath +function. +The descriptions of the other related functions were added by +.An Olivier Certner Aq Mt olce@FreeBSD.org . diff --git a/static/freebsd/man9/vn_isdisk.9 b/static/freebsd/man9/vn_isdisk.9 new file mode 100644 index 00000000..1c218b4a --- /dev/null +++ b/static/freebsd/man9/vn_isdisk.9 @@ -0,0 +1,75 @@ +.\" +.\" Copyright (C) 2001 Chad David . 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 June 28, 2021 +.Dt VN_ISDISK 9 +.Os +.Sh NAME +.Nm vn_isdisk +.Nd "checks if a vnode represents a disk" +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft bool +.Fn vn_isdisk "struct vnode *vp" +.Ft bool +.Fn vn_isdisk_error "struct vnode *vp" "int *errp" +.Sh DESCRIPTION +The +.Fn vn_isdisk +and +.Fn vn_isdisk_error +functions check to see if +.Fa vp +represents a disk. +In order for +.Fa vp +to be a disk, +it must be a character device, +.Va v_rdev +must be valid, and the +.Vt cdevsw +entry's +.Va flags +must have +.Dv D_DISK +set. +.Pp +The arguments are: +.Bl -tag -width ".Fa errp" +.It Fa vp +The vnode to check. +.It Fa errp +An integer pointer to store the error number in if the call fails. +.El +.Sh RETURN VALUES +If the vnode represents a disk, true is returned; otherwise, false +is returned and +.Fa errp +will contain the error number. +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/static/freebsd/man9/vnode.9 b/static/freebsd/man9/vnode.9 new file mode 100644 index 00000000..d1749266 --- /dev/null +++ b/static/freebsd/man9/vnode.9 @@ -0,0 +1,219 @@ +.\" Copyright (c) 1996 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 July 15, 2025 +.Dt VNODE 9 +.Os +.Sh NAME +.Nm vnode +.Nd internal representation of a file or directory +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Sh DESCRIPTION +The vnode is the focus of all file activity in +.Ux . +A vnode is described by +.Vt "struct vnode" . +There is a +unique vnode allocated for each active file, each current directory, +each mounted-on file, text file, and the root. +.Pp +Each vnode has three reference counts, +.Va v_usecount , +.Va v_holdcnt +and +.Va v_writecount . +The first is the number of clients within the kernel which are +using this vnode. +This count is maintained by +.Xr vref 9 , +.Xr vrele 9 +and +.Xr vput 9 . +The second is the number of clients within the kernel who veto +the recycling of this vnode. +This count is +maintained by +.Xr vhold 9 +and +.Xr vdrop 9 . +When both the +.Va v_usecount +and the +.Va v_holdcnt +of a vnode reaches zero then the vnode will be put on the freelist +and may be reused for another file, possibly in another file system. +The transition from the freelist is handled by +.Xr getnewvnode 9 . +The third is a count of the number of clients which are writing into +the file. +It is maintained by the +.Xr open 2 +and +.Xr close 2 +system calls. +.Pp +Any call which returns a vnode (e.g.,\& +.Xr vget 9 , +.Xr VOP_LOOKUP 9 , +etc.\&) +will increase the +.Va v_usecount +of the vnode by one. +When the caller is finished with the vnode, it +should release this reference by calling +.Xr vrele 9 +(or +.Xr vput 9 +if the vnode is locked). +.Pp +Other commonly used members of the vnode structure are +.Va v_id +which is used to maintain consistency in the name cache, +.Va v_mount +which points at the file system which owns the vnode, +.Va v_type +which contains the type of object the vnode represents and +.Va v_data +which is used by file systems to store file system specific data with +the vnode. +The +.Va v_op +field is used by the +.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 +No type. +.It Dv VREG +A regular file; may be with or without VM object backing. +If you want to make sure this get a backing object, call +.Fn vnode_create_vobject . +.It Dv VDIR +A directory. +.It Dv VBLK +A block device; may be with or without VM object backing. +If you want to make sure this get a backing object, call +.Fn vnode_create_vobject . +.It Dv VCHR +A character device. +.It Dv VLNK +A symbolic link. +.It Dv VSOCK +A socket. +Advisory locking will not work on this. +.It Dv VFIFO +A FIFO (named pipe). +Advisory locking will not work on this. +.It Dv VBAD +Indicates that the vnode has been reclaimed. +.El +.Sh IMPLEMENTATION NOTES +VFIFO uses the "struct fileops" from +.Pa /sys/kern/sys_pipe.c . +VSOCK uses the "struct fileops" from +.Pa /sys/kern/sys_socket.c . +Everything else uses the one from +.Pa /sys/kern/vfs_vnops.c . +.Pp +The VFIFO/VSOCK code, which is why "struct fileops" is used at all, is +an artifact of an incomplete integration of the VFS code into the +kernel. +.Pp +Calls to +.Xr malloc 9 +or +.Xr free 9 +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 , +.Xr VOP_ACCESS 9 , +.Xr VOP_ACLCHECK 9 , +.Xr VOP_ADVISE 9 , +.Xr VOP_ADVLOCK 9 , +.Xr VOP_ALLOCATE 9 , +.Xr VOP_ATTRIB 9 , +.Xr VOP_BWRITE 9 , +.Xr VOP_CREATE 9 , +.Xr VOP_FSYNC 9 , +.Xr VOP_GETACL 9 , +.Xr VOP_GETEXTATTR 9 , +.Xr VOP_GETPAGES 9 , +.Xr VOP_INACTIVE 9 , +.Xr VOP_IOCTL 9 , +.Xr VOP_LINK 9 , +.Xr VOP_LISTEXTATTR 9 , +.Xr VOP_LOCK 9 , +.Xr VOP_LOOKUP 9 , +.Xr VOP_OPENCLOSE 9 , +.Xr VOP_PATHCONF 9 , +.Xr VOP_PRINT 9 , +.Xr VOP_RDWR 9 , +.Xr VOP_READ_PGCACHE 9 , +.Xr VOP_READDIR 9 , +.Xr VOP_READLINK 9 , +.Xr VOP_REALLOCBLKS 9 , +.Xr VOP_REMOVE 9 , +.Xr VOP_RENAME 9 , +.Xr VOP_REVOKE 9 , +.Xr VOP_SETACL 9 , +.Xr VOP_SETEXTATTR 9 , +.Xr VOP_SETLABEL 9 , +.Xr VOP_STRATEGY 9 , +.Xr VOP_VPTOCNP 9 , +.Xr VOP_VPTOFH 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/vnode_pager_purge_range.9 b/static/freebsd/man9/vnode_pager_purge_range.9 new file mode 100644 index 00000000..8bd54de9 --- /dev/null +++ b/static/freebsd/man9/vnode_pager_purge_range.9 @@ -0,0 +1,85 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2021 The FreeBSD Foundation +.\" +.\" This manual page was written by Ka Ho Ng under sponsorship from +.\" the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 24, 2022 +.Dt VNODE_PAGER_PURGE_RANGE 9 +.Os +.Sh NAME +.Nm vnode_pager_purge_range +.Nd "invalidate the cached content within the given byte range" +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_extern.h +.Ft void +.Fo vnode_pager_purge_range +.Fa "struct vnode *vp" +.Fa "vm_ooffset_t start" +.Fa "vm_ooffset_t end" +.Fc +.Sh DESCRIPTION +.Nm +invalidates the cached content within the given byte range from the +specified vnode +.Fa vp . +The range to be purged is +.Eo [ +.Fa start , end +.Ec ) . +If the +.Fa end +parameter is the value zero, the affected range starts from +.Fa start +continues to the end of the object. +Pages within the specified range will be removed from the object's queue. +If +.Fa start +or +.Fa end +is not aligned to a page boundary, the invalidated part of the page is zeroed. +This function only cleans the resident pages in the affected region, it is up to +the callers to ensure reading the backing store gets back zeroes. +.Pp +In case the vnode +.Fa vp +does not have a VM object allocated, the effect of calling this function is a +no-op. +.Sh LOCKS +The vnode must be locked on entry and will still be locked on exit. +.Sh SEE ALSO +.Xr vnode 9 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 14 . +.Sh AUTHORS +This +manual page was written by +.An Ka Ho Ng Aq Mt khng@FreeBSD.org . diff --git a/static/freebsd/man9/vnode_pager_setsize.9 b/static/freebsd/man9/vnode_pager_setsize.9 new file mode 100644 index 00000000..8de33541 --- /dev/null +++ b/static/freebsd/man9/vnode_pager_setsize.9 @@ -0,0 +1,79 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2021 The FreeBSD Foundation +.\" +.\" Portions of this software were developed by Ka Ho Ng +.\" under sponsorship from the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd April 8, 2021 +.Dt VNODE_PAGER_SETSIZE 9 +.Os +.Sh NAME +.Nm vnode_pager_setsize +.Nd "notify the VM system about updates in the file size" +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_extern.h +.Ft void +.Fn vnode_pager_setsize "struct vnode *vp" "vm_ooffset_t nsize" +.Sh DESCRIPTION +.Nm +lets the VM system know about a change in size for a file, +and updates the object size and vnode pager size of the vm object in +.Fa vp +with +.Fa nsize . +Page faults on the object mapping with offset beyond the new object +size results in +.Va SIGBUS . +.Pp +Pages between the old EOF and the new EOF are removed from the object queue +if the file size shrinks. +In case the new EOF specified by the +.Fa nsize +argument is not aligned to page boundary, +partial-page area starting beyond the EOF is zeroed and marked invalid. +if the page exists resident. +.Pp +In case the vnode +.Fa vp +does not have a VM object allocated, the effect of calling this function is no-op. +.Pp +This function must be used within file system code to implement truncation +if the file system allocates vm objects for vnodes. +.Sh LOCKS +The vnode should be exclusively locked on entry and will still be locked on exit. +.Sh SEE ALSO +.Xr vnode 9 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 14 . +.Sh AUTHORS +This +manual page was written by +.An Ka Ho Ng Aq Mt khng@FreeBSD.org . diff --git a/static/freebsd/man9/vref.9 b/static/freebsd/man9/vref.9 new file mode 100644 index 00000000..56afe7a0 --- /dev/null +++ b/static/freebsd/man9/vref.9 @@ -0,0 +1,75 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 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 18, 2016 +.Dt VREF 9 +.Os +.Sh NAME +.Nm vref , vrefl +.Nd increment the use count for a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft void +.Fn vref "struct vnode *vp" +.Ft void +.Fn vrefl "struct vnode *vp" +.Sh DESCRIPTION +Increment the +.Va v_usecount +field of a vnode. +.Bl -tag -width 2n +.It Fa vp +the vnode to increment +.El +.Pp +Each vnode maintains a reference count of how many parts of the system +are using the vnode. +This allows the system to detect when a vnode is +no longer being used and can be safely recycled for a different file. +.Pp +Any code in the system which is using a vnode (e.g.\& during the +operation of some algorithm or to store in a data structure) should +call +.Fn vref +or +.Fn vrefl . +.Pp +.Fn vref +locks the vnode interlock while +.Fn vrefl +expects the interlock to already be held. +.Sh SEE ALSO +.Xr vget 9 , +.Xr vnode 9 , +.Xr vput 9 , +.Xr vrefcnt 9 , +.Xr vrele 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . diff --git a/static/freebsd/man9/vrefcnt.9 b/static/freebsd/man9/vrefcnt.9 new file mode 100644 index 00000000..d6f73f15 --- /dev/null +++ b/static/freebsd/man9/vrefcnt.9 @@ -0,0 +1,51 @@ +.\" Copyright (C) 2007 Chad David . +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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 February 10, 2008 +.Dt VREFCNT 9 +.Os +.Sh NAME +.Nm vrefcnt +.Nd returns the use count of a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn vrefcnt "struct vnode *vp" +.Sh DESCRIPTION +Returns the use count of a vnode. +.Pp +See +.Xr vnode 9 +for a detailed description of the vnode reference counts. +.Sh SEE ALSO +.Xr vget 9 , +.Xr vnode 9 , +.Xr vput 9 , +.Xr vrele 9 +.Sh AUTHORS +This manual page was written by +.An Chad David . diff --git a/static/freebsd/man9/vrele.9 b/static/freebsd/man9/vrele.9 new file mode 100644 index 00000000..01a6a895 --- /dev/null +++ b/static/freebsd/man9/vrele.9 @@ -0,0 +1,101 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" Copyright (c) 2010 Konstantin Belousov +.\" +.\" 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 February 24, 2016 +.Dt VRELE 9 +.Os +.Sh NAME +.Nm vput , +.Nm vrele , +.Nm vunref +.Nd decrement the use count for a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft void +.Fn vput "struct vnode *vp" +.Ft void +.Fn vrele "struct vnode *vp" +.Ft void +.Fn vunref "struct vnode *vp" +.Sh DESCRIPTION +Decrement the +.Va v_usecount +field of a vnode. +.Bl -tag -width 2n +.It Fa vp +the vnode to decrement +.El +.Pp +The +.Fn vrele +function takes an unlocked vnode and returns with the vnode unlocked. +.Pp +The +.Fn vput +function should be given a locked vnode as argument, the vnode is unlocked +after the function returned. +The +.Fn vput +is operationally equivalent to calling +.Xr VOP_UNLOCK 9 +followed by +.Fn vrele , +with less overhead. +.Pp +The +.Fn vunref +function takes a locked vnode as argument, and returns with the vnode locked. +.Pp +Any code in the system which signified its use of a vnode by usecount +should call one of the listed function to decrement use counter. +If the +.Va v_usecount +field of the non-doomed vnode reaches zero, then it will be inactivated +and placed on the free list. +.Pp +The +.Fn vrele +function may lock the vnode. +All three functions may sleep. +.Pp +The hold count for the vnode is always greater or equal to the usecount. +Non-forced unmount fails when mount point owns a vnode that has non-zero +usecount, see +.Xr vflush 9 . +.Sh SEE ALSO +.Xr vget 9 , +.Xr vnode 9 , +.Xr vref 9 , +.Xr vrefcnt 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson +and +.An Konstantin Belousov . diff --git a/static/freebsd/man9/vslock.9 b/static/freebsd/man9/vslock.9 new file mode 100644 index 00000000..4522822d --- /dev/null +++ b/static/freebsd/man9/vslock.9 @@ -0,0 +1,86 @@ +.\" $NetBSD: vslock.9,v 1.1 1996/06/15 20:47:29 pk Exp $ +.\" +.\" Copyright (c) 1996 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Paul Kranenburg. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 REGENTS 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 August 29, 2012 +.Dt VSLOCK 9 +.Os +.Sh NAME +.Nm vslock , +.Nm vsunlock +.Nd lock/unlock user space addresses in memory +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.In vm/vm.h +.In vm/vm_extern.h +.Ft int +.Fn vslock "void *addr" "size_t len" +.Ft void +.Fn vsunlock "void *addr" "size_t len" +.Sh DESCRIPTION +The +.Fn vslock +and +.Fn vsunlock +functions respectively lock and unlock a range of +addresses belonging to the currently running process into memory. +The actual amount of memory locked is a multiple of the machine's page size. +The starting page number is computed by truncating +.Fa addr +to the nearest preceding page boundary, and by rounding up +.Fa addr + +.Fa len +to the next page boundary. +The process context to use for this operation is taken from the +global variable +.Va curproc . +.Sh RETURN VALUES +The +.Fn vslock +function will return 0 on success, otherwise it will return +one of the errors listed below. +.Sh ERRORS +The +.Fn vslock +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa addr +and +.Fa len +parameters specify a memory range that wraps around the end of the +machine address space. +.It Bq Er ENOMEM +The size of the specified address range exceeds the system +limit on locked memory. +.It Bq Er EFAULT +Some portion of the indicated address range is not allocated. +There was an error faulting/mapping a page. +.El diff --git a/static/freebsd/man9/watchdog.9 b/static/freebsd/man9/watchdog.9 new file mode 100644 index 00000000..5a0cf55b --- /dev/null +++ b/static/freebsd/man9/watchdog.9 @@ -0,0 +1,79 @@ +.\" +.\" Copyright (c) 2004 Poul-Henning Kamp +.\" 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 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 February 28, 2004 +.Dt WATCHDOG 9 +.Os +.Sh NAME +.Nm watchdog +.Nd "software and hardware watchdog facility" +.Sh SYNOPSIS +.In sys/watchdog.h +.Ft void +.Fn watchdog_fn "void *private" "u_int cmd" "int *error" +.Fn EVENTHANDLER_REGISTER watchdog_list watchdog_fn private 0 +.Fn EVENTHANDLER_DEREGISTER watchdog_list eventhandler_tag +.Sh DESCRIPTION +To implement a watchdog in software or hardware, only a single +function needs to be written and registered on the global +.Va watchdog_list . +.Pp +The function must examine the +.Fa cmd +argument and act on it as +follows: +.Pp +If +.Fa cmd +is zero, the watchdog must be disabled and the +.Fa error +argument left untouched. +If the watchdog cannot be disabled, the +.Fa error +argument must be set to +.Dv EOPNOTSUPP . +.Pp +Else the watchdog should be reset and configured to a timeout of +.Pq 1 << Pq Fa cmd No & Dv WD_INTERVAL +nanoseconds or larger and the +.Fa error +argument be set to zero to signal arming of a watchdog. +.Pp +If the watchdog cannot be configured to the proposed timeout, it +must be disabled and the +.Fa error +argument left as is (to avoid hiding the arming of another watchdog). +.Pp +There is no specification of what the watchdog should do when it +times out, but a hardware reset or similar +.Dq "drastic but certain" +behaviour is recommended. +.Sh SEE ALSO +.Xr watchdog 4 +.Sh AUTHORS +.An -nosplit +The +.Nm +facility and this manual page was written +.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org . diff --git a/static/freebsd/man9/zero_region.9 b/static/freebsd/man9/zero_region.9 new file mode 100644 index 00000000..1ad21661 --- /dev/null +++ b/static/freebsd/man9/zero_region.9 @@ -0,0 +1,84 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2021 The FreeBSD Foundation +.\" +.\" 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 March 2, 2021 +.Dt ZERO_REGION 9 +.Os +.Sh NAME +.Nm zero_region +.Nd Read-only region prefilled with zeroes +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.In vm/vm_param.h +.Vt extern const void *zero_region ; +.Sh DESCRIPTION +The global variable +.Va zero_region +points to a read-only region prefilled with zeroes. +The size of the region is specified by the +.Dv ZERO_REGION_SIZE +macro. +.Sh IMPLEMENTATION NOTES +The region +.Va zero_region +points to is mapped to the same page multiple times. +.Sh EXAMPLES +.Bd -literal +/* + * This function writes zeroes to the vnode at offset 0 + * with ZERO_REGION_SIZE length. + */ +static int +write_example(struct vnode *vp) +{ + struct thread *td; + struct iovec aiov; + struct uio auio; + int error; + + td = curthread; + + aiov.iov_base = __DECONST(void *, zero_region); + aiov.iov_len = ZERO_REGION_SIZE; + auio.uio_iov = &aiov; + auio.uio_iovcnt = 1; + auio.uio_offset = 0; + auio.uio_resid = ZERO_REGION_SIZE; + auio.uio_segflg = UIO_SYSSPACE; + auio.uio_rw = UIO_WRITE; + auio.uio_td = td; + + error = VOP_WRITE(vp, &auio, 0, td->td_ucred); + return (error); +} +.Ed +.Sh SEE ALSO +.Xr pmap 9 , +.Xr vm_map 9 +.Sh AUTHORS +This manual page was written by +.An Ka Ho Ng Aq Mt khng@FreeBSDFoundation.org +under sponsorship from the FreeBSD Foundation. diff --git a/static/freebsd/man9/zone.9 b/static/freebsd/man9/zone.9 new file mode 100644 index 00000000..9f13cf0e --- /dev/null +++ b/static/freebsd/man9/zone.9 @@ -0,0 +1,639 @@ +.\"- +.\" Copyright (c) 2001 Dag-Erling Smørgrav +.\" 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 January 16, 2023 +.Dt UMA 9 +.Os +.Sh NAME +.Nm UMA +.Nd general-purpose kernel object allocator +.Sh SYNOPSIS +.In sys/param.h +.In sys/queue.h +.In vm/uma.h +.Bd -literal +typedef int (*uma_ctor)(void *mem, int size, void *arg, int flags); +typedef void (*uma_dtor)(void *mem, int size, void *arg); +typedef int (*uma_init)(void *mem, int size, int flags); +typedef void (*uma_fini)(void *mem, int size); +typedef int (*uma_import)(void *arg, void **store, int count, int domain, + int flags); +typedef void (*uma_release)(void *arg, void **store, int count); +typedef void *(*uma_alloc)(uma_zone_t zone, vm_size_t size, int domain, + uint8_t *pflag, int wait); +typedef void (*uma_free)(void *item, vm_size_t size, uint8_t pflag); + +.Ed +.Ft uma_zone_t +.Fo uma_zcreate +.Fa "char *name" "size_t size" +.Fa "uma_ctor ctor" "uma_dtor dtor" "uma_init zinit" "uma_fini zfini" +.Fa "int align" "uint16_t flags" +.Fc +.Ft uma_zone_t +.Fo uma_zcache_create +.Fa "char *name" "int size" +.Fa "uma_ctor ctor" "uma_dtor dtor" "uma_init zinit" "uma_fini zfini" +.Fa "uma_import zimport" "uma_release zrelease" +.Fa "void *arg" "int flags" +.Fc +.Ft uma_zone_t +.Fo uma_zsecond_create +.Fa "char *name" +.Fa "uma_ctor ctor" "uma_dtor dtor" "uma_init zinit" "uma_fini zfini" +.Fa "uma_zone_t master" +.Fc +.Ft void +.Fn uma_zdestroy "uma_zone_t zone" +.Ft "void *" +.Fn uma_zalloc "uma_zone_t zone" "int flags" +.Ft "void *" +.Fn uma_zalloc_arg "uma_zone_t zone" "void *arg" "int flags" +.Ft "void *" +.Fn uma_zalloc_domain "uma_zone_t zone" "void *arg" "int domain" "int flags" +.Ft "void *" +.Fn uma_zalloc_pcpu "uma_zone_t zone" "int flags" +.Ft "void *" +.Fn uma_zalloc_pcpu_arg "uma_zone_t zone" "void *arg" "int flags" +.Ft "void *" +.Fn uma_zalloc_smr "uma_zone_t zone" "int flags" +.Ft void +.Fn uma_zfree "uma_zone_t zone" "void *item" +.Ft void +.Fn uma_zfree_arg "uma_zone_t zone" "void *item" "void *arg" +.Ft void +.Fn uma_zfree_pcpu "uma_zone_t zone" "void *item" +.Ft void +.Fn uma_zfree_pcpu_arg "uma_zone_t zone" "void *item" "void *arg" +.Ft void +.Fn uma_zfree_smr "uma_zone_t zone" "void *item" +.Ft void +.Fn uma_prealloc "uma_zone_t zone" "int nitems" +.Ft void +.Fn uma_zone_reserve "uma_zone_t zone" "int nitems" +.Ft void +.Fn uma_zone_reserve_kva "uma_zone_t zone" "int nitems" +.Ft void +.Fn uma_reclaim "int req" +.Ft void +.Fn uma_reclaim_domain "int req" "int domain" +.Ft void +.Fn uma_zone_reclaim "uma_zone_t zone" "int req" +.Ft void +.Fn uma_zone_reclaim_domain "uma_zone_t zone" "int req" "int domain" +.Ft void +.Fn uma_zone_set_allocf "uma_zone_t zone" "uma_alloc allocf" +.Ft void +.Fn uma_zone_set_freef "uma_zone_t zone" "uma_free freef" +.Ft int +.Fn uma_zone_set_max "uma_zone_t zone" "int nitems" +.Ft void +.Fn uma_zone_set_maxcache "uma_zone_t zone" "int nitems" +.Ft int +.Fn uma_zone_get_max "uma_zone_t zone" +.Ft int +.Fn uma_zone_get_cur "uma_zone_t zone" +.Ft void +.Fn uma_zone_set_warning "uma_zone_t zone" "const char *warning" +.Ft void +.Fn uma_zone_set_maxaction "uma_zone_t zone" "void (*maxaction)(uma_zone_t)" +.Ft smr_t +.Fn uma_zone_get_smr "uma_zone_t zone" +.Ft void +.Fn uma_zone_set_smr "uma_zone_t zone" "smr_t smr" +.In sys/sysctl.h +.Fn SYSCTL_UMA_MAX parent nbr name access zone descr +.Fn SYSCTL_ADD_UMA_MAX ctx parent nbr name access zone descr +.Fn SYSCTL_UMA_CUR parent nbr name access zone descr +.Fn SYSCTL_ADD_UMA_CUR ctx parent nbr name access zone descr +.Sh DESCRIPTION +UMA (Universal Memory Allocator) provides an efficient interface for managing +dynamically-sized collections of items of identical size, referred to as zones. +Zones keep track of which items are in use and which +are not, and UMA provides functions for allocating items from a zone and +for releasing them back, making them available for subsequent allocation requests. +Zones maintain per-CPU caches with linear scalability on SMP +systems as well as round-robin and first-touch policies for NUMA +systems. +The number of items cached per CPU is bounded, and each zone additionally +maintains an unbounded cache of items that is used to quickly satisfy +per-CPU cache allocation misses. +.Pp +Two types of zones exist: regular zones and cache zones. +In a regular zone, items are allocated from a slab, which is one or more +virtually contiguous memory pages that have been allocated from the kernel's +page allocator. +Internally, slabs are managed by a UMA keg, which is responsible for allocating +slabs and keeping track of their usage by one or more zones. +In typical usage, there is one keg per zone, so slabs are not shared among +multiple zones. +.Pp +Normal zones import items from a keg, and release items back to that keg if +requested. +Cache zones do not have a keg, and instead use custom import and release +methods. +For example, some collections of kernel objects are statically allocated +at boot-time, and the size of the collection does not change. +A cache zone can be used to implement an efficient allocator for the objects in +such a collection. +.Pp +The +.Fn uma_zcreate +and +.Fn uma_zcache_create +functions create a new regular zone and cache zone, respectively. +The +.Fn uma_zsecond_create +function creates a regular zone which shares the keg of the zone +specified by the +.Fa master +argument. +The +.Fa name +argument is a text name of the zone for debugging and stats; this memory +should not be freed until the zone has been deallocated. +.Pp +The +.Fa ctor +and +.Fa dtor +arguments are callback functions that are called by +the UMA subsystem at the time of the call to +.Fn uma_zalloc +and +.Fn uma_zfree +respectively. +Their purpose is to provide hooks for initializing or +destroying things that need to be done at the time of the allocation +or release of a resource. +A good usage for the +.Fa ctor +and +.Fa dtor +callbacks might be to initialize a data structure embedded in the item, +such as a +.Xr queue 3 +head. +.Pp +The +.Fa zinit +and +.Fa zfini +arguments are used to optimize the allocation of items from the zone. +They are called by the UMA subsystem whenever +it needs to allocate or free items to satisfy requests or memory pressure. +A good use for the +.Fa zinit +and +.Fa zfini +callbacks might be to +initialize and destroy a mutex contained within an item. +This would allow one to avoid destroying and re-initializing the mutex +each time the item is freed and re-allocated. +They are not called on each call to +.Fn uma_zalloc +and +.Fn uma_zfree +but rather when an item is imported into a zone's cache, and when a zone +releases an item to the slab allocator, typically as a response to memory +pressure. +.Pp +For +.Fn uma_zcache_create , +the +.Fa zimport +and +.Fa zrelease +functions are called to import items into the zone and to release items +from the zone, respectively. +The +.Fa zimport +function should store pointers to items in the +.Fa store +array, which contains a maximum of +.Fa count +entries. +The function must return the number of imported items, which may be less than +the maximum. +Similarly, the +.Fa store +parameter to the +.Fa zrelease +function contains an array of +.Fa count +pointers to items. +The +.Fa arg +parameter passed to +.Fn uma_zcache_create +is provided to the import and release functions. +The +.Fa domain +parameter to +.Fa zimport +specifies the requested +.Xr numa 4 +domain for the allocation. +It is either a NUMA domain number or the special value +.Dv UMA_ANYDOMAIN . +.Pp +The +.Fa flags +argument of +.Fn uma_zcreate +and +.Fn uma_zcache_create +is a subset of the following flags: +.Bl -tag -width "foo" +.It Dv UMA_ZONE_NOFREE +Slabs allocated to the zone's keg are never freed. +.It Dv UMA_ZONE_NODUMP +Pages belonging to the zone will not be included in minidumps. +.It Dv UMA_ZONE_PCPU +An allocation from zone would have +.Va mp_ncpu +shadow copies, that are privately assigned to CPUs. +A CPU can address its private copy using base the allocation address plus +a multiple of the current CPU ID and +.Fn sizeof "struct pcpu" : +.Bd -literal -offset indent +foo_zone = uma_zcreate(..., UMA_ZONE_PCPU); + ... +foo_base = uma_zalloc(foo_zone, ...); + ... +critical_enter(); +foo_pcpu = (foo_t *)zpcpu_get(foo_base); +/* do something with foo_pcpu */ +critical_exit(); + +.Ed +Note that +.Dv M_ZERO +cannot be used when allocating items from a PCPU zone. +To obtain zeroed memory from a PCPU zone, use the +.Fn uma_zalloc_pcpu +function and its variants instead, and pass +.Dv M_ZERO . +.It Dv UMA_ZONE_NOTOUCH +The UMA subsystem may not directly touch (i.e. read or write) the slab memory. +Otherwise, by default, book-keeping of items within a slab may be done in the +slab page itself, and +.Dv INVARIANTS +kernels may also do use-after-free checking by accessing the slab memory. +.It Dv UMA_ZONE_ZINIT +The zone will have its +.Ft uma_init +method set to internal method that initializes a new allocated slab +to all zeros. +Do not mistake +.Ft uma_init +method with +.Ft uma_ctor . +A zone with +.Dv UMA_ZONE_ZINIT +flag would not return zeroed memory on every +.Fn uma_zalloc . +.It Dv UMA_ZONE_NOTPAGE +An allocator function will be supplied with +.Fn uma_zone_set_allocf +and the memory that it returns may not be kernel virtual memory backed by VM +pages in the page array. +.It Dv UMA_ZONE_MALLOC +The zone is for the +.Xr malloc 9 +subsystem. +.It Dv UMA_ZONE_VM +The zone is for the VM subsystem. +.It Dv UMA_ZONE_CONTIG +Items in this zone must be contiguous in physical address space. +Items will follow normal alignment constraints and may span page boundaries +between pages with contiguous physical addresses. +.It Dv UMA_ZONE_UNMANAGED +By default, UMA zone caches are shrunk to help resolve free page shortages. +Cached items that have not been used for a long period may also be freed from +zone. +When this flag is set, the system will not reclaim memory from the zone's +caches. +.It Dv UMA_ZONE_SMR +Create a zone whose items will be synchronized using the +.Xr smr 9 +mechanism. +Upon creation the zone will have an associated +.Ft smr_t +structure which can be fetched using +.Fn uma_zone_get_smr . +.El +.Pp +Zones can be destroyed using +.Fn uma_zdestroy , +freeing all memory that is cached in the zone. +All items allocated from the zone must be freed to the zone before the zone +may be safely destroyed. +.Pp +To allocate an item from a zone, simply call +.Fn uma_zalloc +with a pointer to that zone and set the +.Fa flags +argument to selected flags as documented in +.Xr malloc 9 . +It will return a pointer to an item if successful, or +.Dv NULL +in the rare case where all items in the zone are in use and the +allocator is unable to grow the zone and +.Dv M_NOWAIT +is specified. +.Pp +Items are released back to the zone from which they were allocated by +calling +.Fn uma_zfree +with a pointer to the zone and a pointer to the item. +If +.Fa item +is +.Dv NULL , +then +.Fn uma_zfree +does nothing. +.Pp +The variants +.Fn uma_zalloc_arg +and +.Fn uma_zfree_arg +allow callers to +specify an argument for the +.Dv ctor +and +.Dv dtor +functions of the zone, respectively. +The variants +.Fn uma_zalloc_pcpu +and +.Fn uma_zfree_pcpu +allocate and free +.Va mp_ncpu +shadow copies as described for +.Dv UMA_ZONE_PCPU . +If +.Fa item +is +.Dv NULL , +then +.Fn uma_zfree_pcpu +does nothing. +.Pp +The +.Fn uma_zalloc_smr +and +.Fn uma_zfree_smr +functions allocate and free items from an SMR-enabled zone, that is, +a zone created with +.Dv UMA_ZONE_SMR +or a zone that has had +.Fn uma_zone_set_smr +called. +.Pp +The +.Fn uma_zalloc_domain +function allows callers to specify a fixed +.Xr numa 4 +domain to allocate from. +This uses a guaranteed but slow path in the allocator which reduces +concurrency. +.Pp +The +.Fn uma_prealloc +function allocates slabs for the requested number of items, typically following +the initial creation of a zone. +Subsequent allocations from the zone will be satisfied using the pre-allocated +slabs. +Note that slab allocation is performed with the +.Dv M_WAITOK +flag, so +.Fn uma_prealloc +may sleep. +.Pp +The +.Fn uma_zone_reserve +function sets the number of reserved items for the zone. +.Fn uma_zalloc +and variants will ensure that the zone contains at least the reserved number +of free items. +Reserved items may be allocated by specifying +.Dv M_USE_RESERVE +in the allocation request flags. +.Fn uma_zone_reserve +does not perform any pre-allocation by itself. +.Pp +The +.Fn uma_zone_reserve_kva +function pre-allocates kernel virtual address space for the requested +number of items. +Subsequent allocations from the zone will be satisfied using the pre-allocated +address space. +Note that unlike +.Fn uma_zone_reserve , +.Fn uma_zone_reserve_kva +does not restrict the use of the pre-allocation to +.Dv M_USE_RESERVE +requests. +.Pp +The +.Fn uma_reclaim +and +.Fn uma_zone_reclaim +functions reclaim cached items from UMA zones, releasing unused memory. +The +.Fn uma_reclaim +function reclaims items from all regular zones, while +.Fn uma_zone_reclaim +reclaims items only from the specified zone. +The +.Fa req +parameter must be one of three values which specify how aggressively +items are to be reclaimed: +.Bl -tag -width indent +.It Dv UMA_RECLAIM_TRIM +Reclaim items only in excess of the zone's estimated working set size. +The working set size is periodically updated and tracks the recent history +of the zone's usage. +.It Dv UMA_RECLAIM_DRAIN +Reclaim all items from the unbounded cache. +Free items in the per-CPU caches are left alone. +.It Dv UMA_RECLAIM_DRAIN_CPU +Reclaim all cached items. +.El +The +.Fn uma_reclaim_domain +and +.Fn uma_zone_reclaim_domain +functions apply only to items allocated from the specified domain. +In the case of domains using a round-robin NUMA policy, cached items from all +domains are freed to the keg, but only slabs from the specific domain will +be freed. +.Pp +The +.Fn uma_zone_set_allocf +and +.Fn uma_zone_set_freef +functions allow a zone's default slab allocation and free functions to be +overridden. +This is useful if memory with special constraints such as attributes, +alignment, or address ranges must be used. +.Pp +The +.Fn uma_zone_set_max +function limits the number of items +.Pq and therefore memory +that can be allocated to +.Fa zone . +The +.Fa nitems +argument specifies the requested upper limit number of items. +The effective limit is returned to the caller, as it may end up being higher +than requested due to the implementation rounding up to ensure all memory pages +allocated to the zone are utilised to capacity. +The limit applies to the total number of items in the zone, which includes +allocated items, free items and free items in the per-cpu caches. +On systems with more than one CPU it may not be possible to allocate +the specified number of items even when there is no shortage of memory, +because all of the remaining free items may be in the caches of the +other CPUs when the limit is hit. +.Pp +The +.Fn uma_zone_set_maxcache +function limits the number of free items which may be cached in the zone. +This limit applies to both the per-CPU caches and the cache of free buckets. +.Pp +The +.Fn uma_zone_get_max +function returns the effective upper limit number of items for a zone. +.Pp +The +.Fn uma_zone_get_cur +function returns an approximation of the number of items currently allocated +from the zone. +The returned value is approximate because appropriate synchronisation to +determine an exact value is not performed by the implementation. +This ensures low overhead at the expense of potentially stale data being used +in the calculation. +.Pp +The +.Fn uma_zone_set_warning +function sets a warning that will be printed on the system console when the +given zone becomes full and fails to allocate an item. +The warning will be printed no more often than every five minutes. +Warnings can be turned off globally by setting the +.Va vm.zone_warnings +sysctl tunable to +.Va 0 . +.Pp +The +.Fn uma_zone_set_maxaction +function sets a function that will be called when the given zone becomes full +and fails to allocate an item. +The function will be called with the zone locked. +Also, the function +that called the allocation function may have held additional locks. +Therefore, +this function should do very little work (similar to a signal handler). +.Pp +The +.Fn uma_zone_set_smr +function associates an existing +.Xr smr 9 +structure with a UMA zone. +The effect is similar to creating a zone with the +.Dv UMA_ZONE_SMR +flag, except that a new SMR structure is not created. +This function must be called before any allocations from the zone are performed. +.Pp +The +.Fn SYSCTL_UMA_MAX parent nbr name access zone descr +macro declares a static +.Xr sysctl 9 +oid that exports the effective upper limit number of items for a zone. +The +.Fa zone +argument should be a pointer to +.Vt uma_zone_t . +A read of the oid returns value obtained through +.Fn uma_zone_get_max . +A write to the oid sets new value via +.Fn uma_zone_set_max . +The +.Fn SYSCTL_ADD_UMA_MAX ctx parent nbr name access zone descr +macro is provided to create this type of oid dynamically. +.Pp +The +.Fn SYSCTL_UMA_CUR parent nbr name access zone descr +macro declares a static read-only +.Xr sysctl 9 +oid that exports the approximate current occupancy of the zone. +The +.Fa zone +argument should be a pointer to +.Vt uma_zone_t . +A read of the oid returns value obtained through +.Fn uma_zone_get_cur . +The +.Fn SYSCTL_ADD_UMA_CUR ctx parent nbr name zone descr +macro is provided to create this type of oid dynamically. +.Sh IMPLEMENTATION NOTES +The memory that these allocation calls return is not executable. +The +.Fn uma_zalloc +function does not support the +.Dv M_EXEC +flag to allocate executable memory. +Not all platforms enforce a distinction between executable and +non-executable memory. +.Sh SEE ALSO +.Xr numa 4 , +.Xr vmstat 8 , +.Xr malloc 9 , +.Xr smr 9 +.Rs +.%A Jeff Bonwick +.%T "The Slab Allocator: An Object-Caching Kernel Memory Allocator" +.%D 1994 +.Re +.Sh HISTORY +The zone allocator first appeared in +.Fx 3.0 . +It was radically changed in +.Fx 5.0 +to function as a slab allocator. +.Sh AUTHORS +.An -nosplit +The zone allocator was written by +.An John S. Dyson . +The zone allocator was rewritten in large parts by +.An Jeff Roberson Aq Mt jeff@FreeBSD.org +to function as a slab allocator. +.Pp +This manual page was written by +.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . +Changes for UMA by +.An Jeroen Ruigrok van der Werven Aq Mt asmodai@FreeBSD.org . -- cgit v1.2.3